14d3beaa0SMauro Carvalho Chehab======================================================== 24d3beaa0SMauro Carvalho ChehabLinux Security Modules: General Security Hooks for Linux 34d3beaa0SMauro Carvalho Chehab======================================================== 44d3beaa0SMauro Carvalho Chehab 54d3beaa0SMauro Carvalho Chehab:Author: Stephen Smalley 64d3beaa0SMauro Carvalho Chehab:Author: Timothy Fraser 74d3beaa0SMauro Carvalho Chehab:Author: Chris Vance 84d3beaa0SMauro Carvalho Chehab 94d3beaa0SMauro Carvalho Chehab.. note:: 104d3beaa0SMauro Carvalho Chehab 114d3beaa0SMauro Carvalho Chehab The APIs described in this book are outdated. 124d3beaa0SMauro Carvalho Chehab 134d3beaa0SMauro Carvalho ChehabIntroduction 144d3beaa0SMauro Carvalho Chehab============ 154d3beaa0SMauro Carvalho Chehab 164d3beaa0SMauro Carvalho ChehabIn March 2001, the National Security Agency (NSA) gave a presentation 174d3beaa0SMauro Carvalho Chehababout Security-Enhanced Linux (SELinux) at the 2.5 Linux Kernel Summit. 184d3beaa0SMauro Carvalho ChehabSELinux is an implementation of flexible and fine-grained 194d3beaa0SMauro Carvalho Chehabnondiscretionary access controls in the Linux kernel, originally 204d3beaa0SMauro Carvalho Chehabimplemented as its own particular kernel patch. Several other security 214d3beaa0SMauro Carvalho Chehabprojects (e.g. RSBAC, Medusa) have also developed flexible access 224d3beaa0SMauro Carvalho Chehabcontrol architectures for the Linux kernel, and various projects have 234d3beaa0SMauro Carvalho Chehabdeveloped particular access control models for Linux (e.g. LIDS, DTE, 244d3beaa0SMauro Carvalho ChehabSubDomain). Each project has developed and maintained its own kernel 254d3beaa0SMauro Carvalho Chehabpatch to support its security needs. 264d3beaa0SMauro Carvalho Chehab 274d3beaa0SMauro Carvalho ChehabIn response to the NSA presentation, Linus Torvalds made a set of 284d3beaa0SMauro Carvalho Chehabremarks that described a security framework he would be willing to 294d3beaa0SMauro Carvalho Chehabconsider for inclusion in the mainstream Linux kernel. He described a 304d3beaa0SMauro Carvalho Chehabgeneral framework that would provide a set of security hooks to control 314d3beaa0SMauro Carvalho Chehaboperations on kernel objects and a set of opaque security fields in 324d3beaa0SMauro Carvalho Chehabkernel data structures for maintaining security attributes. This 334d3beaa0SMauro Carvalho Chehabframework could then be used by loadable kernel modules to implement any 344d3beaa0SMauro Carvalho Chehabdesired model of security. Linus also suggested the possibility of 354d3beaa0SMauro Carvalho Chehabmigrating the Linux capabilities code into such a module. 364d3beaa0SMauro Carvalho Chehab 374d3beaa0SMauro Carvalho ChehabThe Linux Security Modules (LSM) project was started by WireX to develop 38e2d467deSCasey Schauflersuch a framework. LSM was a joint development effort by several security 394d3beaa0SMauro Carvalho Chehabprojects, including Immunix, SELinux, SGI and Janus, and several 404d3beaa0SMauro Carvalho Chehabindividuals, including Greg Kroah-Hartman and James Morris, to develop a 41e2d467deSCasey SchauflerLinux kernel patch that implements this framework. The work was 42e2d467deSCasey Schauflerincorporated in the mainstream in December of 2003. This technical 43e2d467deSCasey Schauflerreport provides an overview of the framework and the capabilities 44e2d467deSCasey Schauflersecurity module. 454d3beaa0SMauro Carvalho Chehab 464d3beaa0SMauro Carvalho ChehabLSM Framework 474d3beaa0SMauro Carvalho Chehab============= 484d3beaa0SMauro Carvalho Chehab 49e2d467deSCasey SchauflerThe LSM framework provides a general kernel framework to support 504d3beaa0SMauro Carvalho Chehabsecurity modules. In particular, the LSM framework is primarily focused 514d3beaa0SMauro Carvalho Chehabon supporting access control modules, although future development is 52e2d467deSCasey Schauflerlikely to address other security needs such as sandboxing. By itself, the 534d3beaa0SMauro Carvalho Chehabframework does not provide any additional security; it merely provides 54e2d467deSCasey Schauflerthe infrastructure to support security modules. The LSM framework is 55e2d467deSCasey Schaufleroptional, requiring `CONFIG_SECURITY` to be enabled. The capabilities 56e2d467deSCasey Schauflerlogic is implemented as a security module. 574d3beaa0SMauro Carvalho ChehabThis capabilities module is discussed further in 586795b29cSBrendan Jackman`LSM Capabilities Module`_. 594d3beaa0SMauro Carvalho Chehab 60e2d467deSCasey SchauflerThe LSM framework includes security fields in kernel data structures and 61e2d467deSCasey Schauflercalls to hook functions at critical points in the kernel code to 62e2d467deSCasey Schauflermanage the security fields and to perform access control. 63e2d467deSCasey SchauflerIt also adds functions for registering security modules. 64e2d467deSCasey SchauflerAn interface `/sys/kernel/security/lsm` reports a comma separated list 65e2d467deSCasey Schauflerof security modules that are active on the system. 664d3beaa0SMauro Carvalho Chehab 67e2d467deSCasey SchauflerThe LSM security fields are simply ``void*`` pointers. 68e2d467deSCasey SchauflerThe data is referred to as a blob, which may be managed by 69e2d467deSCasey Schauflerthe framework or by the individual security modules that use it. 70e2d467deSCasey SchauflerSecurity blobs that are used by more than one security module are 71e2d467deSCasey Schauflertypically managed by the framework. 72e2d467deSCasey SchauflerFor process and 73e2d467deSCasey Schauflerprogram execution security information, security fields are included in 744d3beaa0SMauro Carvalho Chehab:c:type:`struct task_struct <task_struct>` and 75e2d467deSCasey Schaufler:c:type:`struct cred <cred>`. 76e2d467deSCasey SchauflerFor filesystem 77e2d467deSCasey Schauflersecurity information, a security field is included in :c:type:`struct 784d3beaa0SMauro Carvalho Chehabsuper_block <super_block>`. For pipe, file, and socket security 79e2d467deSCasey Schauflerinformation, security fields are included in :c:type:`struct inode 80e2d467deSCasey Schaufler<inode>` and :c:type:`struct file <file>`. 81e2d467deSCasey SchauflerFor System V IPC security information, 824d3beaa0SMauro Carvalho Chehabsecurity fields were added to :c:type:`struct kern_ipc_perm 834d3beaa0SMauro Carvalho Chehab<kern_ipc_perm>` and :c:type:`struct msg_msg 844d3beaa0SMauro Carvalho Chehab<msg_msg>`; additionally, the definitions for :c:type:`struct 854d3beaa0SMauro Carvalho Chehabmsg_msg <msg_msg>`, struct msg_queue, and struct shmid_kernel 864d3beaa0SMauro Carvalho Chehabwere moved to header files (``include/linux/msg.h`` and 874d3beaa0SMauro Carvalho Chehab``include/linux/shm.h`` as appropriate) to allow the security modules to 884d3beaa0SMauro Carvalho Chehabuse these definitions. 894d3beaa0SMauro Carvalho Chehab 90e2d467deSCasey SchauflerFor packet and 91e2d467deSCasey Schauflernetwork device security information, security fields were added to 92e2d467deSCasey Schaufler:c:type:`struct sk_buff <sk_buff>` and 93e2d467deSCasey Schaufler:c:type:`struct scm_cookie <scm_cookie>`. 94e2d467deSCasey SchauflerUnlike the other security module data, the data used here is a 95e2d467deSCasey Schaufler32-bit integer. The security modules are required to map or otherwise 96e2d467deSCasey Schauflerassociate these values with real security attributes. 974d3beaa0SMauro Carvalho Chehab 98e2d467deSCasey SchauflerLSM hooks are maintained in lists. A list is maintained for each 99e2d467deSCasey Schauflerhook, and the hooks are called in the order specified by CONFIG_LSM. 100e2d467deSCasey SchauflerDetailed documentation for each hook is 101*6d2ed653SRandy Dunlapincluded in the `security/security.c` source file. 1024d3beaa0SMauro Carvalho Chehab 103e2d467deSCasey SchauflerThe LSM framework provides for a close approximation of 104e2d467deSCasey Schauflergeneral security module stacking. It defines 105e2d467deSCasey Schauflersecurity_add_hooks() to which each security module passes a 106e2d467deSCasey Schaufler:c:type:`struct security_hooks_list <security_hooks_list>`, 107e2d467deSCasey Schauflerwhich are added to the lists. 108e2d467deSCasey SchauflerThe LSM framework does not provide a mechanism for removing hooks that 109e2d467deSCasey Schauflerhave been registered. The SELinux security module has implemented 110e2d467deSCasey Schauflera way to remove itself, however the feature has been deprecated. 1114d3beaa0SMauro Carvalho Chehab 112e2d467deSCasey SchauflerThe hooks can be viewed as falling into two major 1134d3beaa0SMauro Carvalho Chehabcategories: hooks that are used to manage the security fields and hooks 1144d3beaa0SMauro Carvalho Chehabthat are used to perform access control. Examples of the first category 115e2d467deSCasey Schauflerof hooks include the security_inode_alloc() and security_inode_free() 116e2d467deSCasey SchauflerThese hooks are used to allocate 117e2d467deSCasey Schauflerand free security structures for inode objects. 118e2d467deSCasey SchauflerAn example of the second category of hooks 119e2d467deSCasey Schaufleris the security_inode_permission() hook. 120e2d467deSCasey SchauflerThis hook checks permission when accessing an inode. 1214d3beaa0SMauro Carvalho Chehab 1224d3beaa0SMauro Carvalho ChehabLSM Capabilities Module 1234d3beaa0SMauro Carvalho Chehab======================= 1244d3beaa0SMauro Carvalho Chehab 125e2d467deSCasey SchauflerThe POSIX.1e capabilities logic is maintained as a security module 126e2d467deSCasey Schauflerstored in the file ``security/commoncap.c``. The capabilities 127e2d467deSCasey Schauflermodule uses the order field of the :c:type:`lsm_info` description 128e2d467deSCasey Schauflerto identify it as the first security module to be registered. 129e2d467deSCasey SchauflerThe capabilities security module does not use the general security 130e2d467deSCasey Schauflerblobs, unlike other modules. The reasons are historical and are 131e2d467deSCasey Schauflerbased on overhead, complexity and performance concerns. 132