<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook V3.1//EN"[]><article class="whitepaper" id="LinuxSecurityModule" lang="en"> <artheader> <title>Linux Security Modules:  General Security Hooks for Linux</title> <authorgroup> <author> <firstname>Stephen</firstname>  <surname>Smalley</surname> <affiliation> <orgname>NAI Labs</orgname> <address><email>ssmalley@nai.com</email></address> </affiliation> </author> <author> <firstname>Timothy</firstname>  <surname>Fraser</surname> <affiliation> <orgname>NAI Labs</orgname> <address><email>tfraser@nai.com</email></address> </affiliation> </author> <author> <firstname>Chris</firstname>  <surname>Vance</surname> <affiliation> <orgname>NAI Labs</orgname> <address><email>cvance@nai.com</email></address> </affiliation> </author> </authorgroup> </artheader><sect1><title>Introduction</title><para>In March 2001, the National Security Agency (NSA) gave a presentationabout Security-Enhanced Linux (SELinux) at the 2.5 Linux KernelSummit.  SELinux is an implementation of flexible and fine-grainednondiscretionary access controls in the Linux kernel, originallyimplemented as its own particular kernel patch.  Several othersecurity projects (e.g. RSBAC, Medusa) have also developed flexibleaccess control architectures for the Linux kernel, and variousprojects have developed particular access control models for Linux(e.g. LIDS, DTE, SubDomain).  Each project has developed andmaintained its own kernel patch to support its security needs.</para><para>In response to the NSA presentation, Linus Torvalds made a set ofremarks that described a security framework he would be willing toconsider for inclusion in the mainstream Linux kernel.  He described ageneral framework that would provide a set of security hooks tocontrol operations on kernel objects and a set of opaque securityfields in kernel data structures for maintaining security attributes.This framework could then be used by loadable kernel modules toimplement any desired model of security.  Linus also suggested thepossibility of migrating the Linux capabilities code into such amodule.</para><para>The Linux Security Modules (LSM) project was started by WireX todevelop such a framework.  LSM is a joint development effort byseveral security projects, including Immunix, SELinux, SGI and Janus,and several individuals, including Greg Kroah-Hartman and JamesMorris, to develop a Linux kernel patch that implements thisframework.  The patch is currently tracking the 2.4 series and istargeted for integration into the 2.5 development series.  Thistechnical report provides an overview of the framework and the examplecapabilities security module provided by the LSM kernel patch.</para></sect1><sect1 id="framework"><title>LSM Framework</title><para>The LSM kernel patch provides a general kernel framework to supportsecurity modules.  In particular, the LSM framework is primarilyfocused on supporting access control modules, although futuredevelopment is likely to address other security needs such asauditing.  By itself, the framework does not provide any additionalsecurity; it merely provides the infrastructure to support securitymodules.  The LSM kernel patch also moves most of the capabilitieslogic into an optional security module, with the system defaultingto the traditional superuser logic.  This capabilities moduleis discussed further in <XRef LinkEnd="cap">.</para><para>The LSM kernel patch adds security fields to kernel data structuresand inserts calls to hook functions at critical points in the kernelcode to manage the security fields and to perform access control.  Italso adds functions for registering and unregistering securitymodules, and adds a general <function>security</function> system callto support new system calls for security-aware applications.</para><para>The LSM security fields are simply <type>void*</type> pointers.  Forprocess and program execution security information, security fieldswere added to <structname>struct task_struct</structname> and <structname>struct linux_binprm</structname>.  For filesystem securityinformation, a security field was added to <structname>struct super_block</structname>.  For pipe, file, and socketsecurity information, security fields were added to <structname>struct inode</structname> and <structname>struct file</structname>.  For packet and network device securityinformation, security fields were added to<structname>struct sk_buff</structname> and<structname>struct net_device</structname>.  For System V IPC securityinformation, security fields were added to<structname>struct kern_ipc_perm</structname> and<structname>struct msg_msg</structname>; additionally, the definitionsfor <structname>struct msg_msg</structname>, <structname>struct msg_queue</structname>, and <structname>struct shmid_kernel</structname> were moved to header files(<filename>include/linux/msg.h</filename> and<filename>include/linux/shm.h</filename> as appropriate) to allowthe security modules to use these definitions.</para><para>Each LSM hook is a function pointer in a global table,security_ops. This table is a<structname>security_operations</structname> structure as defined by<filename>include/linux/security.h</filename>.  Detailed documentationfor each hook is included in this header file.  At present, thisstructure consists of a collection of substructures that group relatedhooks based on the kernel object (e.g. task, inode, file, sk_buff,etc) as well as some top-level hook function pointers for systemoperations.  This structure is likely to be flattened in the futurefor performance.  The placement of the hook calls in the kernel codeis described by the "called:" lines in the per-hook documentation inthe header file.  The hook calls can also be easily found in thekernel code by looking for the string "security_ops->".</para><para>Linus mentioned per-process security hooks in his original remarks as apossible alternative to global security hooks.  However, if LSM wereto start from the perspective of per-process hooks, then the baseframework would have to deal with how to handle operations thatinvolve multiple processes (e.g. kill), since each process might haveits own hook for controlling the operation.  This would require ageneral mechanism for composing hooks in the base framework.Additionally, LSM would still need global hooks for operations thathave no process context (e.g. network input operations).Consequently, LSM provides global security hooks, but a securitymodule is free to implement per-process hooks (where that makes sense)by storing a security_ops table in each process' security field andthen invoking these per-process hooks from the global hooks.The problem of composition is thus deferred to the module.</para><para>The global security_ops table is initialized to a set of hookfunctions provided by a dummy security module that providestraditional superuser logic.  A <function>register_security</function>function (in <filename>security/security.c</filename>) is provided toallow a security module to set security_ops to refer to its own hookfunctions, and an <function>unregister_security</function> function isprovided to revert security_ops to the dummy module hooks.  Thismechanism is used to set the primary security module, which isresponsible for making the final decision for each hook.</para><para>LSM also provides a simple mechanism for stacking additional securitymodules with the primary security module.  It defines<function>register_security</function> and<function>unregister_security</function> hooks in the<structname>security_operations</structname> structure and provides<function>mod_reg_security</function> and<function>mod_unreg_security</function> functions that invoke thesehooks after performing some sanity checking.  A security module cancall these functions in order to stack with other modules.  However,the actual details of how this stacking is handled are deferred to themodule, which can implement these hooks in any way it wishes(including always returning an error if it does not wish to supportstacking).  In this manner, LSM again defers the problem ofcomposition to the module.</para><para>Although the LSM hooks are organized into substructures based onkernel object, all of the hooks can be viewed as falling into twomajor categories: hooks that are used to manage the security fieldsand hooks that are used to perform access control.  Examples of thefirst category of hooks include the<function>alloc_security</function> and<function>free_security</function> hooks defined for each kernel datastructure that has a security field.  These hooks are used to allocateand free security structures for kernel objects.  The first categoryof hooks also includes hooks that set information in the securityfield after allocation, such as the <function>post_lookup</function>hook in <structname>struct inode_security_ops</structname>.  This hookis used to set security information for inodes after successful lookupoperations.  An example of the second category of hooks is the<function>permission</function> hook in <structname>struct inode_security_ops</structname>.  This hook checkspermission when accessing an inode.</para></sect1><sect1 id="cap"><title>LSM Capabilities Module</title><para>The LSM kernel patch moves most of the existing POSIX.1e capabilitieslogic into an optional security module stored in the file<filename>security/capability.c</filename>.  This change allowsusers who do not want to use capabilities to omit this code entirelyfrom their kernel, instead using the dummy module for traditionalsuperuser logic or any other module that they desire.  This changealso allows the developers of the capabilities logic to maintain andenhance their code more freely, without needing to integrate patchesback into the base kernel.</para><para>In addition to moving the capabilities logic, the LSM kernel patchcould move the capability-related fields from the kernel datastructures into the new security fields managed by the securitymodules.  However, at present, the LSM kernel patch leaves thecapability fields in the kernel data structures.  In his originalremarks, Linus suggested that this might be preferable so that othersecurity modules can be easily stacked with the capabilities modulewithout needing to chain multiple security structures on the security field.It also avoids imposing extra overhead on the capabilities moduleto manage the security fields.  However, the LSM framework couldcertainly support such a move if it is determined to be desirable,with only a few additional changes described below.</para><para>At present, the capabilities logic for computing process capabilitieson <function>execve</function> and <function>set*uid</function>,checking capabilities for a particular process, saving and checkingcapabilities for netlink messages, and handling the<function>capget</function> and <function>capset</function> systemcalls have been moved into the capabilities module.  There are still afew locations in the base kernel where capability-related fields aredirectly examined or modified, but the current version of the LSMpatch does allow a security module to completely replace theassignment and testing of capabilities.  These few locations wouldneed to be changed if the capability-related fields were moved intothe security field.  The following is a list of known locations thatstill perform such direct examination or modification ofcapability-related fields:<itemizedlist><listitem><para><filename>fs/open.c</filename>:<function>sys_access</function></para></listitem><listitem><para><filename>fs/lockd/host.c</filename>:<function>nlm_bind_host</function></para></listitem><listitem><para><filename>fs/nfsd/auth.c</filename>:<function>nfsd_setuser</function></para></listitem><listitem><para><filename>fs/proc/array.c</filename>:<function>task_cap</function></para></listitem></itemizedlist></para></sect1></article>