Mauro Carvalho Chehab | 415008a | 2017-05-14 11:41:53 -0300 | [diff] [blame] | 1 | ======================================================== |
| 2 | Linux Security Modules: General Security Hooks for Linux |
| 3 | ======================================================== |
| 4 | |
| 5 | :Author: Stephen Smalley |
| 6 | :Author: Timothy Fraser |
| 7 | :Author: Chris Vance |
| 8 | |
| 9 | .. note:: |
| 10 | |
| 11 | The APIs described in this book are outdated. |
| 12 | |
| 13 | Introduction |
| 14 | ============ |
| 15 | |
| 16 | In March 2001, the National Security Agency (NSA) gave a presentation |
| 17 | about Security-Enhanced Linux (SELinux) at the 2.5 Linux Kernel Summit. |
| 18 | SELinux is an implementation of flexible and fine-grained |
| 19 | nondiscretionary access controls in the Linux kernel, originally |
| 20 | implemented as its own particular kernel patch. Several other security |
| 21 | projects (e.g. RSBAC, Medusa) have also developed flexible access |
| 22 | control architectures for the Linux kernel, and various projects have |
| 23 | developed particular access control models for Linux (e.g. LIDS, DTE, |
| 24 | SubDomain). Each project has developed and maintained its own kernel |
| 25 | patch to support its security needs. |
| 26 | |
| 27 | In response to the NSA presentation, Linus Torvalds made a set of |
| 28 | remarks that described a security framework he would be willing to |
| 29 | consider for inclusion in the mainstream Linux kernel. He described a |
| 30 | general framework that would provide a set of security hooks to control |
| 31 | operations on kernel objects and a set of opaque security fields in |
| 32 | kernel data structures for maintaining security attributes. This |
| 33 | framework could then be used by loadable kernel modules to implement any |
| 34 | desired model of security. Linus also suggested the possibility of |
| 35 | migrating the Linux capabilities code into such a module. |
| 36 | |
| 37 | The Linux Security Modules (LSM) project was started by WireX to develop |
Casey Schaufler | e2d467d | 2020-04-21 14:48:34 -0700 | [diff] [blame] | 38 | such a framework. LSM was a joint development effort by several security |
Mauro Carvalho Chehab | 415008a | 2017-05-14 11:41:53 -0300 | [diff] [blame] | 39 | projects, including Immunix, SELinux, SGI and Janus, and several |
| 40 | individuals, including Greg Kroah-Hartman and James Morris, to develop a |
Casey Schaufler | e2d467d | 2020-04-21 14:48:34 -0700 | [diff] [blame] | 41 | Linux kernel patch that implements this framework. The work was |
| 42 | incorporated in the mainstream in December of 2003. This technical |
| 43 | report provides an overview of the framework and the capabilities |
| 44 | security module. |
Mauro Carvalho Chehab | 415008a | 2017-05-14 11:41:53 -0300 | [diff] [blame] | 45 | |
| 46 | LSM Framework |
| 47 | ============= |
| 48 | |
Casey Schaufler | e2d467d | 2020-04-21 14:48:34 -0700 | [diff] [blame] | 49 | The LSM framework provides a general kernel framework to support |
Mauro Carvalho Chehab | 415008a | 2017-05-14 11:41:53 -0300 | [diff] [blame] | 50 | security modules. In particular, the LSM framework is primarily focused |
| 51 | on supporting access control modules, although future development is |
Casey Schaufler | e2d467d | 2020-04-21 14:48:34 -0700 | [diff] [blame] | 52 | likely to address other security needs such as sandboxing. By itself, the |
Mauro Carvalho Chehab | 415008a | 2017-05-14 11:41:53 -0300 | [diff] [blame] | 53 | framework does not provide any additional security; it merely provides |
Casey Schaufler | e2d467d | 2020-04-21 14:48:34 -0700 | [diff] [blame] | 54 | the infrastructure to support security modules. The LSM framework is |
| 55 | optional, requiring `CONFIG_SECURITY` to be enabled. The capabilities |
| 56 | logic is implemented as a security module. |
Mauro Carvalho Chehab | 415008a | 2017-05-14 11:41:53 -0300 | [diff] [blame] | 57 | This capabilities module is discussed further in |
Brendan Jackman | 6795b29 | 2019-09-25 17:17:44 +0700 | [diff] [blame] | 58 | `LSM Capabilities Module`_. |
Mauro Carvalho Chehab | 415008a | 2017-05-14 11:41:53 -0300 | [diff] [blame] | 59 | |
Casey Schaufler | e2d467d | 2020-04-21 14:48:34 -0700 | [diff] [blame] | 60 | The LSM framework includes security fields in kernel data structures and |
| 61 | calls to hook functions at critical points in the kernel code to |
| 62 | manage the security fields and to perform access control. |
| 63 | It also adds functions for registering security modules. |
| 64 | An interface `/sys/kernel/security/lsm` reports a comma separated list |
| 65 | of security modules that are active on the system. |
Mauro Carvalho Chehab | 415008a | 2017-05-14 11:41:53 -0300 | [diff] [blame] | 66 | |
Casey Schaufler | e2d467d | 2020-04-21 14:48:34 -0700 | [diff] [blame] | 67 | The LSM security fields are simply ``void*`` pointers. |
| 68 | The data is referred to as a blob, which may be managed by |
| 69 | the framework or by the individual security modules that use it. |
| 70 | Security blobs that are used by more than one security module are |
| 71 | typically managed by the framework. |
| 72 | For process and |
| 73 | program execution security information, security fields are included in |
Mauro Carvalho Chehab | 415008a | 2017-05-14 11:41:53 -0300 | [diff] [blame] | 74 | :c:type:`struct task_struct <task_struct>` and |
Casey Schaufler | e2d467d | 2020-04-21 14:48:34 -0700 | [diff] [blame] | 75 | :c:type:`struct cred <cred>`. |
| 76 | For filesystem |
| 77 | security information, a security field is included in :c:type:`struct |
Mauro Carvalho Chehab | 415008a | 2017-05-14 11:41:53 -0300 | [diff] [blame] | 78 | super_block <super_block>`. For pipe, file, and socket security |
Casey Schaufler | e2d467d | 2020-04-21 14:48:34 -0700 | [diff] [blame] | 79 | information, security fields are included in :c:type:`struct inode |
| 80 | <inode>` and :c:type:`struct file <file>`. |
| 81 | For System V IPC security information, |
Mauro Carvalho Chehab | 415008a | 2017-05-14 11:41:53 -0300 | [diff] [blame] | 82 | security fields were added to :c:type:`struct kern_ipc_perm |
| 83 | <kern_ipc_perm>` and :c:type:`struct msg_msg |
| 84 | <msg_msg>`; additionally, the definitions for :c:type:`struct |
| 85 | msg_msg <msg_msg>`, struct msg_queue, and struct shmid_kernel |
| 86 | were moved to header files (``include/linux/msg.h`` and |
| 87 | ``include/linux/shm.h`` as appropriate) to allow the security modules to |
| 88 | use these definitions. |
| 89 | |
Casey Schaufler | e2d467d | 2020-04-21 14:48:34 -0700 | [diff] [blame] | 90 | For packet and |
| 91 | network device security information, security fields were added to |
| 92 | :c:type:`struct sk_buff <sk_buff>` and |
| 93 | :c:type:`struct scm_cookie <scm_cookie>`. |
| 94 | Unlike the other security module data, the data used here is a |
| 95 | 32-bit integer. The security modules are required to map or otherwise |
| 96 | associate these values with real security attributes. |
Mauro Carvalho Chehab | 415008a | 2017-05-14 11:41:53 -0300 | [diff] [blame] | 97 | |
Casey Schaufler | e2d467d | 2020-04-21 14:48:34 -0700 | [diff] [blame] | 98 | LSM hooks are maintained in lists. A list is maintained for each |
| 99 | hook, and the hooks are called in the order specified by CONFIG_LSM. |
| 100 | Detailed documentation for each hook is |
Randy Dunlap | 6d2ed65 | 2023-04-27 20:09:16 -0700 | [diff] [blame] | 101 | included in the `security/security.c` source file. |
Mauro Carvalho Chehab | 415008a | 2017-05-14 11:41:53 -0300 | [diff] [blame] | 102 | |
Casey Schaufler | e2d467d | 2020-04-21 14:48:34 -0700 | [diff] [blame] | 103 | The LSM framework provides for a close approximation of |
| 104 | general security module stacking. It defines |
| 105 | security_add_hooks() to which each security module passes a |
| 106 | :c:type:`struct security_hooks_list <security_hooks_list>`, |
| 107 | which are added to the lists. |
| 108 | The LSM framework does not provide a mechanism for removing hooks that |
| 109 | have been registered. The SELinux security module has implemented |
| 110 | a way to remove itself, however the feature has been deprecated. |
Mauro Carvalho Chehab | 415008a | 2017-05-14 11:41:53 -0300 | [diff] [blame] | 111 | |
Casey Schaufler | e2d467d | 2020-04-21 14:48:34 -0700 | [diff] [blame] | 112 | The hooks can be viewed as falling into two major |
Mauro Carvalho Chehab | 415008a | 2017-05-14 11:41:53 -0300 | [diff] [blame] | 113 | categories: hooks that are used to manage the security fields and hooks |
| 114 | that are used to perform access control. Examples of the first category |
Casey Schaufler | e2d467d | 2020-04-21 14:48:34 -0700 | [diff] [blame] | 115 | of hooks include the security_inode_alloc() and security_inode_free() |
| 116 | These hooks are used to allocate |
| 117 | and free security structures for inode objects. |
| 118 | An example of the second category of hooks |
| 119 | is the security_inode_permission() hook. |
| 120 | This hook checks permission when accessing an inode. |
Mauro Carvalho Chehab | 415008a | 2017-05-14 11:41:53 -0300 | [diff] [blame] | 121 | |
| 122 | LSM Capabilities Module |
| 123 | ======================= |
| 124 | |
Casey Schaufler | e2d467d | 2020-04-21 14:48:34 -0700 | [diff] [blame] | 125 | The POSIX.1e capabilities logic is maintained as a security module |
| 126 | stored in the file ``security/commoncap.c``. The capabilities |
| 127 | module uses the order field of the :c:type:`lsm_info` description |
| 128 | to identify it as the first security module to be registered. |
| 129 | The capabilities security module does not use the general security |
| 130 | blobs, unlike other modules. The reasons are historical and are |
| 131 | based on overhead, complexity and performance concerns. |