Implementing SELinux as a Linux Security Module

Initial: December 2001, Last revised: March 2004


Table of Contents
1. Introduction
2. Acknowledgements
3. LSM Overview
4. SELinux Basic Concepts
5. Changes from the Original SELinux Kernel Patch
5.1. General Changes
5.1.1. Adding a New Level of Indirection
5.1.2. Dynamically Allocating Security Fields
5.1.3. Stacking with the Capabilities Module
5.1.4. Redesigning the SELinux API
5.1.5. Leveraging Linux Permission Functions
5.2. Program Execution Changes
5.2.1. File execute_no_trans Permission
5.2.2. Inheritance of State
5.3. Filesystem Changes
5.3.1. Labeling of Persistent Files
5.3.2. Pseudo Filesystem Labeling
5.3.3. Leveraging permission
5.3.4. File Descriptor Permissions
5.3.5. Pipe Security Class
5.4. Socket IPC and Networking Changes
5.4.1. Redesigning Network Access Controls
5.4.2. Storing Socket Security Data
5.4.3. Minimally Invasive Hooks
5.4.4. File Descriptor Transfer
5.4.5. Omitting Low-Level ioctl Controls
5.4.6. Extended Socket Calls
5.5. System V IPC Changes
5.5.1. Storing IPC Security Data
5.5.2. Leveraging ipcperms
5.6. Miscellaneous Changes
6. Internal Architecture
7. Initialization and Exit
7.1. selinux_plug_init
7.2. selinux_plug_exit
8. Stacking with Other Modules
9. New System Calls
10. Helper Functions for Hook Functions
10.1. Primitive Allocation Helper Functions
10.2. Precondition Helper Functions
10.3. Permission Checking Helper Functions
11. Task Hook Functions
11.1. Managing Task Security Fields
11.1.1. Task Security Structure
11.1.2. task_alloc_security and task_free_security
11.1.3. task_precondition
11.1.4. selinux_task_kmod_set_label
11.1.5. selinux_task_post_setuid
11.2. Controlling Task Operations
11.2.1. Helper Functions for Checking Task Permissions
11.2.2. Hook Functions for Controlling Task Operations
12. Program Loading Hook Functions
12.1. Managing Binprm Security Fields
12.1.1. selinux_bprm_alloc_security and selinux_bprm_free_security
12.1.2. selinux_bprm_set_security
12.1.3. selinux_bprm_compute_creds
13. Superblock Hook Functions
13.1. Managing Superblock Security Fields
13.1.1. Superblock Security Structure
13.1.2. superblock_alloc_security and superblock_free_security
13.1.3. superblock_precondition
13.1.4. selinux_post_mountroot
13.1.5. selinux_post_pivotroot
13.1.6. selinux_post_addmount
13.1.7. selinux_post_remount
13.1.8. selinux_umount_close
13.1.9. selinux_umount_busy
13.2. Controlling Filesystem Operations
13.2.1. superblock_has_perm
13.2.2. selinux_sb_statfs
13.2.3. selinux_mount
13.2.4. selinux_check_sb
13.2.5. selinux_umount
13.2.6. selinux_pivotroot
13.2.7. Summary of Filesystem Permission Checks
14. Inode Hook Functions
14.1. Managing Inode Security Fields
14.1.1. Inode Security Structure
14.1.2. inode_alloc_security and inode_free_security
14.1.3. inode_precondition
14.1.4. selinux_inode_post_lookup
14.1.5. post_create
14.1.6. selinux_inode_post_link/rename
14.1.7. selinux_inode_delete
14.1.8. selinux_inode_revalidate
14.2. Controlling Inode Operations
14.2.1. inode_has_perm
14.2.2. dentry_has_perm
14.2.3. may_create
14.2.4. may_link
14.2.5. may_rename
14.2.6. selinux_inode_permission
14.2.7. Other inode access control hook functions
15. File Hook Functions
15.1. Managing File Security Fields
15.1.1. File Security Structure
15.1.2. file_alloc_security and file_free_security
15.1.3. file_precondition
15.1.4. selinux_file_set_fowner
15.2. Controlling File Operations
15.2.1. file_has_perm
15.2.2. selinux_file_permission
15.2.3. selinux_file_llseek
15.2.4. selinux_file_ioctl
15.2.5. selinux_file_mmap
15.2.6. selinux_file_mprotect
15.2.7. selinux_file_lock
15.2.8. selinux_file_fcntl
15.2.9. selinux_file_send_sigiotask
15.2.10. selinux_file_receive
16. System V IPC Hook Functions
16.1. Managing System V IPC Security Fields
16.1.1. IPC Security Structure
16.1.2. ipc_alloc_security and ipc_free_security
16.1.3. msg_msg_alloc_security and msg_msg_free_security
16.1.4. ipc_precondition
16.1.5. msg_precondition
16.1.6. ipc_savesid
16.2. Controlling General IPC Operations
16.2.1. ipc_has_perm
16.2.2. selinux_ipc_permission
16.2.3. selinux_ipc_getinfo
16.2.4. selinux_*_associate
16.3. Controlling Semaphore Operations
16.3.1. selinux_semctl
16.3.2. selinux_semop
16.4. Controlling Shared Memory Operations
16.4.1. selinux_shm_shmctl
16.4.2. selinux_shm_shmat
16.5. Controlling Message Queue Operations
16.5.1. selinux_msg_queue_msgctl
16.5.2. selinux_msg_queue_msgsnd
16.5.3. selinux_msg_queue_msgrcv
17. Socket Hook Functions
17.1. Socket Related Security Structures
17.2. Managing Socket Related Security Fields
17.2.1. selinux_socket_post_create
17.2.2. selinux_socket_accept
17.2.3. selinux_socket_post_accept
17.2.4. selinux_tcp_connection_request
17.2.5. selinux_tcp_synack
17.2.6. selinux_tcp_create_openreq_child
17.3. Controlling Socket Operations
17.3.1. socket_has_perm
17.3.2. Socket Layer Hooks
17.3.3. selinux_socket_sock_rcv_skb (Transport Layer Hook)
17.3.4. Hooks for Unix Domain Socket IPC
17.4. Extended Socket Call Processing
17.4.1. Extended Inode Security Structure
17.4.2. Open Request Security Structure
17.4.3. Extended Socket Functions
18. Network Buffer Hook Functions
18.1. Network Buffer Security Structure
18.2. selinux_skb_set_owner_w
18.3. selinux_skb_recv_datagram
19. IPv4 Networking Hook Functions
19.1. Netfilter-based Hook Functions
19.1.1. selinux_ip_input_helper
19.1.2. selinux_ip_preroute_last
19.1.3. selinux_ip_input_first
19.1.4. selinux_ip_input_last
19.1.5. selinux_ip_output_first
19.1.6. selinux_ip_postroute_last
19.1.7. Unused NetFilter-based Hooks
19.2. IP Packet Lifecycle Hooks
19.2.1. selinux_ip_fragment
19.2.2. selinux_ip_defragment
19.2.3. selinux_ip_decode_options
19.2.4. Unused IP Packet Lifecycle Hooks
20. Network Packet Labeling
20.1. NSID API
20.2. Selopt
20.2.1. selopt_ip_label_output
20.2.2. selopt_ip_map_input
20.2.3. selopt_ip_decode_options
20.2.4. selopt_ip_defragment
20.2.5. selopt_sock_sendmsg
21. Network Device Hook Functions
21.1. Managing Network Device Security Fields
21.1.1. Network Device Security Structure
21.1.2. netdev_alloc_security and netdev_free_security
21.1.3. netdev_precondition
21.1.4. selinux_netdev_unregister
22. Module Hook Functions
23. System Hook Functions
23.1. Capability-Related System Hook Functions
23.1.1. selinux_capable
23.1.2. selinux_capget
23.1.3. selinux_capset_check
23.1.4. selinux_capset_set
23.1.5. selinux_netlink_send
23.1.6. selinux_netlink_recv
23.1.7. Summary of Capability-Related Permission Checks
23.2. System Hook Functions that Defer to Capable
23.3. System Hook Function for sysctl
23.3.1. Shadow Sysctl Table
23.3.2. search_ctl_sid
23.3.3. selinux_sysctl
23.3.4. Comparison with /proc/sys
23.4. System Hook Function for quotactl
23.5. System Hook Function for syslog
23.6. System Hook Function for New System Calls
23.7. Remaining System Hook Functions
References

1. Introduction

In March 2001, the National Security Agency (NSA) gave a presentation about Security-Enhanced Linux (SELinux) at the 2.5 Linux Kernel Summit. SELinux is an implementation of flexible and fine-grained nondiscretionary access controls in the Linux kernel, originally implemented as its own particular kernel patch. The design and implementation of the original SELinux prototype is described in [LoscoccoFreenix2001] and [LoscoccoNSATR2001], both of which can be found at the NSA SELinux web site.

In response to the NSA presentation, Linus Torvalds made a set of remarks that described a security framework he would be willing to consider for inclusion in the mainstream Linux kernel. He described a general framework that would provide a set of security hooks to control operations on kernel objects and a set of opaque security fields in kernel data structures for maintaining security attributes. This framework could then be used by loadable kernel modules to implement any desired model of security.

The Linux Security Modules (LSM) project was started by Immunix to develop such a framework. LSM was a joint development effort by several security projects, including Immunix, SELinux, SGI and Janus, and several individuals, including Greg Kroah-Hartman and James Morris, to develop a Linux kernel patch that implements this framework. The LSM framework is included as part of the Linux 2.6 series. Documentation and papers about LSM are available from the LSM web site.

The SELinux implementation was adapted to use the LSM framework rather than its own particular kernel patch. This technical report documents the LSM-based SELinux security module. The report begins by providing an overview of LSM and a review of the SELinux basic concepts. It then provides an overview of how the LSM-based SELinux security module differs from the original SELinux kernel patch. Several aspects of the SELinux security module are then described, including its internal architecture, its initialization and exit code, its support for stacking with other security modules, and its approach for implementing the new SELinux system calls. The remainder of the report is then spent documenting the SELinux hook function implementations, organized into sections for each grouping of LSM hooks. Typically, these hooks are grouped based on the relevant kernel object or kernel subsystem.

This report has not been updated yet to reflect the reworking of the SELinux module by NSA for inclusion in mainline Linux 2.6 or other recent changes to SELinux. Stay tuned for further updates.