From SELinux Wiki
 Linux Security Module and SELinux
This section gives a high level overview of the LSM and SELinux internal structure and workings. A more detailed view can be found in the "Implementing SELinux as a Linux Security Module" that was used extensively to develop this section (with the SELinux kernel source code). The major areas covered are:
- How the LSM and SELinux modules work together.
- The major SELinux internal services.
- The fork system call and exec are followed through as an example to tie in with the transition process covered in the Domain and Object Transitions section.
- The SELinux filesystem /selinux.
- The boot sequences that are relevant to SELinux.
 The LSM Module
The LSM is the Linux security framework that allows 3rd party access control mechanisms to be linked into the GNU / Linux kernel. Currently there are two 3rd party services that utilise the LSM: SELinux and SMACK (Simplified Mandatory Access Control Kernel) that both provide mandatory access control services. Details regarding SMACK can be found at: http://www.schaufler-ca.com/.
The basic idea behind the LSM is to:
- Insert security function calls (or hooks) and security data structures in the various kernel services to allow access control to be applied over and above that already implemented via DAC. The type of service that have hooks inserted are shown in Table 1 with an example task and program execution shown in the Fork Walk-thorough and Process Transition Walk-thorough sections below.
- Allow registration and initialisation services for the 3rd party security modules.
- Allow process security attributes to be available to userspace services by extending the /proc filesystem with a security namespace.
- Support filesystems that use extended attributes (SELinux uses security.selinux.
- Consolidate the Linux capabilities into an optional module.
It should be noted that the LSM does not provide any security services itself, only the hooks and structures for supporting 3rd party modules. If no 3rd party module is loaded, the capabilities module becomes the default module thus allowing standard DAC access control.
|Program execution||Filesystem operations||Inode operations|
|File operations||Task operations||Netlink messaging|
|Unix domain networking||Socket operations||XFRM operations|
|Key Management operations||IPC operations||Memory Segments|
Table 1: LSM Hooks - These are the kernel services that LSM has inserted security hooks and structures to allow access control to be managed by 3rd party modules (see ./kernel-2.6.27/include/linux/security.h).
The major kernel source files (relative to ./kernel-2.6.27/security) that form the LSM are shown in Table 2. However there is one major header file (include/linux/security.h) that describes all the security hooks and structures defined by the LSM.
|capability.c||Some capability functions were in various kernel modules have been consolidated into these source files. These are now (from Kernel 2.6.27) always linked into the kernel. This means the dummy.c security module (mentioned in the "Implementing SELinux as a Linux Security Module" document) is no longer required.|
|inode.c||This allows the 3rd party security module to initialise a security filesystem. In the case of SELinux this would be /selinux that is defined in the selinux/selinuxfs.c source file.|
|root_plug.c||This is a sample 3rd party module and therefore not used.|
|security.c||Contains the LSM framework initialisation services that will set up the hooks described in security.h and those in the capability source files. It also provides functions to initialise 3rd party modules.|
Table 2: The core LSM source modules.
 The SELinux Module
This section does not go into detail of all the SELinux module functionality as the "Implementing SELinux as a Linux Security Module" document does this, however it attempts to highlight the way some areas work by using the Fork and Domain Transition Walk-thorough and transition process examples and also by describing the SELinux Boot Process.
The major kernel SELinux source files (relative to ./kernel-2.6.27/security/selinux) that form the SELinux security module are shown in Table 3. The diagrams High Level SELinux Architecture and The Main LSM / SELinux Modules can be used to see how some of these kernel source modules fit together.
|avc.c||Access Vector Cache functions and structures. The function calls are for the kernel services, however they have been ported to form the libselinux userspace library detailed in the API Summary for libselinux section.|
|exports.c||Exported SELinux services for SECMARK (as there is SELinux specific code in the netfilter source tree).|
|hooks.c||Contains all the SELinux functions that are called by the kernel resources via the security_ops function table (they form the kernel resource object managers). There are also support functions for managing process exec's, managing SID allocation and removal, interfacing into the AVC and Security Server.|
|netif.c||These manage the mapping between labels and SIDs for the net* language statements when they are declared in the active policy.|
|netlabel.c||The interface between NetLabel services and SELinux.|
|netlink.c||Manages the notification of policy updates to resources including userspace applications via libselinux.|
|selinuxfs.c||The selinuxfs pseudo filesystem (/selinux) that exports the security policy to userspace services via libselinux. The services exported are shown in the SELinux Filesystem section below.|
|xfrm.c||Contains the IPSec XFRM hooks for SELinux.|
|include/flask.h||This contains all the kernel security classes and initial SIDs. Note that the Reference Policy source (policy/flask directory) contains a list of all the kernel and userspace security classes and permissions.|
|ss/avtab.c||AVC table functions for inserting / deleting entries.|
|ss/conditional.c||Support boolean statement functions and implements a conditional AV table to hold entries.|
|ss/avtab.c||AVC table functions for inserting / deleting entries.|
|ss/ebitmap.c||Bitmaps to represent sets of values, such as types, roles, categories, and classes.|
|ss/mls.c||Functions to support MLS.|
|ss/policydb.c||Defines the structure of the policy database. See the "SELinux Policy Module Primer" article for details on the structure.|
|ss/services.c|| This contains the supporting services for kernel hooks defined in hooks.c, the AVC and the Security Server.
For example the security_transition_sid that computes the SID for a new subject / object shown in the The Main LSM / SELinux Modules diagram.
|ss/sidtab.c||The SID table contains the security context indexed by its SID value.|
|ss/symtab.c||Maintains associations between symbol strings and their values.|
Table 3: The core SELinux source modules - The .h files and those in the include directory have a number of useful comments.
 Fork System Call Walk-thorough
This section walks through the the fork system call shown in the Domain Transition diagram starting at the kernel hooks that link to the SELinux services. The way the SELinux hooks are initialised into the LSM security_ops and secondary_ops function tables are also described.
Using the Hooks for the fork system call diagram, the major steps to check whether the unconfined_t process has permission to use the fork permission are:
- The kernel/fork.c has a hook that links it to the LSM function security_task_create() that is called to check access permissions.
- Because the SELinux module has been initialised as the security module, the security_ops table has been set to point to the SELinux selinux_task_create() function in hooks.c.
- The selinux_task_create() function will first call the capabilities code in capability.c via the secondary_ops function table to check the DAC permission.
- This is simply a return 0;, therefore no error would be generated.
- The selinux_task_create() function will then check whether the task has permission via the task_has_perm(current_process, current_process, PROCESS__FORK) function.
- This will result in a call to the AVC via the avc_has_perm() function in avc.c that checks whether the permission has been granted or not. First (via avc_has_perm_noaudit()) the cache is checked to for an entry. Assuming that there is no entry in the AVC, then the security_compute_av() function in services.c is called.
- The security_compute_av() function will search the SID table for source and target entries, and if found will then call the context_struct_compute_av() function.
- The context_struct_compute_av() function carries out many check to validate whether access is allowed. The steps are (assuming the access is valid):
- a) Initialise the AV structure so that it is clear.
- b) Check the object class and permissions are correct. It also checks the status of the allow_unknown flag (see the SELinux Filesystem section below, /etc/selinux/semanage.conf file and Reference Policy Build Options - build.conf sections).
- c) Checks if there are any type enforcement rules (ALLOW, AUDIT_ALLOW, AUDIT_DENY).
- d) Check whether any conditional statements are involved via the cond_compute_av() function in conditional.c.
- e) Remove permissions that are defined in any constraint via the constraint_expr_eval() function call (in services.c). This function will also check any MLS constraints.
- f) Finally context_struct_compute_av() checks if a process transition is being requested (it is not). If it were, then the TRANSITION and DYNTRANSITION permissions are checked and whether the role is changing.
- 8. Once the result has been computed it is returned to the kernel/fork.c system call via the initial selinux_task_create() function. In this case the fork call is allowed.
- 9. The End.
 Process Transition Walk-thorough
This section walks through the execve() and checking whether a process transition to the ext_gateway_t domain is allowed, and if so obtain a new SID for the context (user_u:message_filter_r:ext_gateway_t) as shown in the Domain Transition diagram.
The process starts with the Linux operating system issuing a do_execve() call from the CPU specific architecture code to execute a new program (for example, from arch/ia64/kernel/process.c). The do_execve() function is located in the fs/exec.c source code module and does the loading and final exec as described below.
do_execve() has a number of calls to security_bprm_* functions that are a part of the LSM (see security.h), and are hooked by SELinux during the initialisation process (in hooks.c). Table 4 briefly describes these security_bprm functions that are hooks for validating program loading and execution (although see security.h for greater detail).
|LSM / SElinux Function Name||Description|
|security_bprm_alloc-> selinux_bprm_alloc_security||Allocates memory for the bprm structure.|
|security_bprm_free-> selinux_bprm_free_security||Frees memory from the bprm structure.|
|security_bprm_apply_creds-> selinux_bprm_apply_creds||Sets task lock and new security attributes for a transformed process on execve. Seems to be used for libraries, scripts etc. Called from various Linux OS areas via compute_creds() located in fs/exec.c.|
|security_bprm_post_apply_creds-> selinux_bprm_post_apply_creds||Supports the security_bprm_apply_creds function for areas that must not be locked.|
|security_bprm_secureexec-> selinux_bprm_secureexec||Called after the selinux_bprm_post_apply_creds function to check AT_SECURE flag for glibc secure mode support.|
|security_bprm_set-> selinux_bprm_set_security||Carries out the major checks to validate whether the process can transition to the target context, and obtain a new SID if required.|
|security_bprm_check-> selinux_bprm_check_security||This hook is not used by SELinux.|
Table 4: The LSM / SELinux Program Loading Hooks
Therefore starting at the do_execve() function and using the Process Transition diagram, the following major steps will be carried out to check whether the unconfined_t process has permission to transition the secure_server executable to the ext_gateway_t domain:
- 1. The executable file is opened, a call issued to the sched_exec() function and the bprm structure is initialised with the file parameters (name, environment and arguments).
- The security_bprm_alloc()->selinux_bprm_alloc_security() function is then called (in hooks.c) where SELinux will allocate memory for the bprm security structure and set the bsec->set flag to 0 indicating this is the first time through this process for this exec request.
- 2. Via the prepare_binprm() function call the UID and GIDs are checked and a call issued to security_bprm_set() that will carry out the following:
- a) The selinux_bprm_set_security() function will call the secondary_ops->bprm_set_security function in capability.c, that is effectively a no-op.
- b) The bsec->set flag will be checked and if 1 will return as this function can be called multiple times during the exec process.
- c) The target SID is checked to see whether a transition is required (in this case it is), therefore a call will be made to the security_transition_sid() function in services.c. This function will compute the SID for a new subject or object (subject in this case) via the security_compute_sid() function that will (assuming there are no errors):
- .i. Search the SID table for the source and target SIDs.
- .ii. Sets the SELinux user identity.
- .iii. Set the source role and type.
- .iv. Checks that a type_transition rule exists in the AV table and / or the conditional AV table (see the The Main LSM / SELinux Modules diagram).
- .v. If a type_transition, then also check for a role_transition (there is a role change in the ext_gateway.conf policy module), set the role.
- .vi. Check if any MLS attributes by calling mls_compute_sid() in mls.c. It also checks whether MLS is enabled or not, if so sets up MLS contexts.
- .vii. Check whether the contexts are valid by calling compute_sid_handle_invalid_context() that will also log an audit message if the context is invalid.
- .viii. Finally obtains a SID for the new context by calling sidtab_context_to_sid() in sidtab.c that will search the SID table (see the The Main LSM / SELinux Modules diagram) and insert a new entry if okay or log a kernel event if invalid.
- d) The selinux_bprm_set_security() function will then continue by checking via the avc_has_perm() function (in avc.c) whether the file_execute_no_trans is set (in this case it is not), therefore the process_transition and file_entrypoint permissions are checked (in this case they are), therefore the new SID is set, the bsec->set flag is set to 1 so that this part of the function is not executed again for this exec, finally control is passed back to the do_execve function:
- 3. Various strings are copied (args etc.) and a check is made to see if the exec succeeded or not (in this case it did), therefore the security_bprm_free() function is called to free the bprm security structure.
- 4. The End.
 SELinux Filesystem
Table 5 shows the information contained in the pseudo file system /selinux where the SELinux kernel exports relevant information regarding its configuration and active policy for use by the libselinux API library (that is used by user-space object managers and SELinux-aware applications).
| || || |
|/selinux|| ||This is the root directory where the SELinux kernel exports relevant information regarding its configuration and active policy for use by the libselinux library (that is used by user space object managers and SELinux-aware applications).|
| ||Compute access decision interface.|
| ||Check requested protection, not kernel-applied one.|
| ||Commit new boolean values to the kernel policy.|
| || Whether SECMARK is enabled or not:
0 = SECMARK enabled (F-12 default).
1 = SECMARK disabled
| ||Validate context interface.|
| ||Compute create labeling decision interface.|
| || These two files export unknown deny and reject handling status to user space. This is taken from the handle-unknown parameter set in the /etc/selinux/semanage.conf file and are set as follows:
0:0 = allow, 1:0 = deny and 1:1 = reject.
| ||Disable SELinux until next reboot.|
| ||Get or set enforcing status. Used by the setenforce(8) command.|
| ||Load policy interface.|
| ||Compute polyinstantiation membership decision interface.|
| ||Returns 1 if MLS policy is enabled or 0 if not.|
| ||Returns policy version for this kernel (F-12 = 24).|
| ||Compute relabeling decision interface.|
| ||Compute reachable user contexts interface.|
|/selinux/avc|| ||This directory contains information regarding the kernel AVC that can be displayed by the avcstat command.|
| ||Shows the AVC lookups, hits, misses etc.|
| || The default value is 512, however caching can be turned off (but performance suffers) by:
echo 0 > /selinux/avc/cache_threshold
| ||Shows the number of AVC entries, longest chain etc.|
|/selinux/booleans|| ||This directory contains one file for each boolean defined in the active policy.|
| ||Each file contains the current status of the boolean (0 = false or 1 = true). The getsebool(8), setsebool(8) and sestatus -b commands use this information.|
|/selinux/initial_contexts|| ||This directory contains one file for each initial SID defined in the active policy.|
| ||Each file contains the initial context of the initial SID as defined in the active policy (e.g. any_socket was assigned system_u:object_r:unconfined_t).|
|/selinux/policy_capabilities|| ||This directory contains the policy capabilities that have been configured by default in the kernel. They are generally new features that can be enabled for testing by using the policycap statement in a monolithic or base policy.|
| || For the F-12 kernel, this file contains "0" (false) which means that the following network_peer_controls are not enabled by default:
node: sendto recvfrom
netif: ingress egress
| ||For the F-12 kernel, this file contains "0" (false) which means that open permissions are not enabled by default on the following objects: dir, file, fifo_file, chr_file, blk_file.|
|/selinux/class|| ||This directory contains a list of classes and their permissions as defined within the policy.|
|/selinux/class/appletalk_socket|| ||Each class has its own directory that contains the following:|
| ||This file contains the allocated class number (e.g. appletalk_socket is "56" in flask.h (linux-2.6.27/security/selinux/include/flask.h)).|
| ||This directory contains one file for each permission defined in the policy.|
| ||Each file contains a number but not sure what it represents.|
Table 5: /selinux File and Directory Information
- SIDs are not passed to userspace, only the security context string. The context can be read via the libselinux API where a userspace object manager normally manages the relationship (see "SELinux Support for Userspace Object Managers" [Ref. 17]).
- The /proc filesystem exports the process security context string to userspace via /proc/<pid>/attr interface (where <pid> is the process ID). These can also be managed via the the libselinux API.
 SELinux Boot Process
Figure 1 shows the boot process that has been limited to what is considered relevant for initialising SELinux, loading the policy and checking whether re-labeling is required. The SELinux kernel initialisation areas are in red. The kernel, mkinitrd and upstart source code rpms were used to find the sequence of events (all corrections welcome).
Figure 1: The Boot Sequence - This shows how SELinux is initialised and the policy loaded during the boot process.
- ↑ This function call will pass over the file name to be run and its environment + arguments. Note that for loading shared libraries the exec_mmap function is used.
- ↑ That is taken from the UNK_PERMS entry in the Reference Policy build.conf file.
- ↑ There is a Linux overview at: http://en.wikipedia.org/wiki/Linux_startup_process.