kernel/linux/Documentation/DocBook/lsm.tmpl

   1 <!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook V3.1//EN"[]>
   2 <article class="whitepaper" id="LinuxSecurityModule" lang="en">
   3  <artheader>
   4  <title>Linux Security Modules:  General Security Hooks for Linux</title>
   5  <authorgroup>
   6  <author>
   7  <firstname>Stephen</firstname>
   8  <surname>Smalley</surname>
   9  <affiliation>
  10  <orgname>NAI Labs</orgname>
  11  <address><email>ssmalley@nai.com</email></address>
  12  </affiliation>
  13  </author>
  14  <author>
  15  <firstname>Timothy</firstname>
  16  <surname>Fraser</surname>
  17  <affiliation>
  18  <orgname>NAI Labs</orgname>
  19  <address><email>tfraser@nai.com</email></address>
  20  </affiliation>
  21  </author>
  22  <author>
  23  <firstname>Chris</firstname>
  24  <surname>Vance</surname>
  25  <affiliation>
  26  <orgname>NAI Labs</orgname>
  27  <address><email>cvance@nai.com</email></address>
  28  </affiliation>
  29  </author>
  30  </authorgroup>
  31  </artheader>
  32
  33 <sect1><title>Introduction</title>
  34
  35 <para>
  36 In March 2001, the National Security Agency (NSA) gave a presentation
  37 about Security-Enhanced Linux (SELinux) at the 2.5 Linux Kernel
  38 Summit.  SELinux is an implementation of flexible and fine-grained
  39 nondiscretionary access controls in the Linux kernel, originally
  40 implemented as its own particular kernel patch.  Several other
  41 security projects (e.g. RSBAC, Medusa) have also developed flexible
  42 access control architectures for the Linux kernel, and various
  43 projects have developed particular access control models for Linux
  44 (e.g. LIDS, DTE, SubDomain).  Each project has developed and
  45 maintained its own kernel patch to support its security needs.
  46 </para>
  47
  48 <para>
  49 In response to the NSA presentation, Linus Torvalds made a set of
  50 remarks that described a security framework he would be willing to
  51 consider for inclusion in the mainstream Linux kernel.  He described a
  52 general framework that would provide a set of security hooks to
  53 control operations on kernel objects and a set of opaque security
  54 fields in kernel data structures for maintaining security attributes.
  55 This framework could then be used by loadable kernel modules to
  56 implement any desired model of security.  Linus also suggested the
  57 possibility of migrating the Linux capabilities code into such a
  58 module.
  59 </para>
  60
  61 <para>
  62 The Linux Security Modules (LSM) project was started by WireX to
  63 develop such a framework.  LSM is a joint development effort by
  64 several security projects, including Immunix, SELinux, SGI and Janus,
  65 and several individuals, including Greg Kroah-Hartman and James
  66 Morris, to develop a Linux kernel patch that implements this
  67 framework.  The patch is currently tracking the 2.4 series and is
  68 targeted for integration into the 2.5 development series.  This
  69 technical report provides an overview of the framework and the example
  70 capabilities security module provided by the LSM kernel patch.
  71 </para>
  72
  73 </sect1>
  74
  75 <sect1 id="framework"><title>LSM Framework</title>
  76
  77 <para>
  78 The LSM kernel patch provides a general kernel framework to support
  79 security modules.  In particular, the LSM framework is primarily
  80 focused on supporting access control modules, although future
  81 development is likely to address other security needs such as
  82 auditing.  By itself, the framework does not provide any additional
  83 security; it merely provides the infrastructure to support security
  84 modules.  The LSM kernel patch also moves most of the capabilities
  85 logic into an optional security module, with the system defaulting
  86 to the traditional superuser logic.  This capabilities module
  87 is discussed further in <XRef LinkEnd="cap">.
  88 </para>
  89
  90 <para>
  91 The LSM kernel patch adds security fields to kernel data structures
  92 and inserts calls to hook functions at critical points in the kernel
  93 code to manage the security fields and to perform access control.  It
  94 also adds functions for registering and unregistering security
  95 modules, and adds a general <function>security</function> system call
  96 to support new system calls for security-aware applications.
  97 </para>
  98
  99 <para>
 100 The LSM security fields are simply <type>void*</type> pointers.  For
 101 process and program execution security information, security fields
 102 were added to <structname>struct task_struct</structname> and
 103 <structname>struct linux_binprm</structname>.  For filesystem security
 104 information, a security field was added to
 105 <structname>struct super_block</structname>.  For pipe, file, and socket
 106 security information, security fields were added to
 107 <structname>struct inode</structname> and
 108 <structname>struct file</structname>.  For packet and network device security
 109 information, security fields were added to
 110 <structname>struct sk_buff</structname> and
 111 <structname>struct net_device</structname>.  For System V IPC security
 112 information, security fields were added to
 113 <structname>struct kern_ipc_perm</structname> and
 114 <structname>struct msg_msg</structname>; additionally, the definitions
 115 for <structname>struct msg_msg</structname>, <structname>struct
 116 msg_queue</structname>, and <structname>struct
 117 shmid_kernel</structname> were moved to header files
 118 (<filename>include/linux/msg.h</filename> and
 119 <filename>include/linux/shm.h</filename> as appropriate) to allow
 120 the security modules to use these definitions.
 121 </para>
 122
 123 <para>
 124 Each LSM hook is a function pointer in a global table,
 125 security_ops. This table is a
 126 <structname>security_operations</structname> structure as defined by
 127 <filename>include/linux/security.h</filename>.  Detailed documentation
 128 for each hook is included in this header file.  At present, this
 129 structure consists of a collection of substructures that group related
 130 hooks based on the kernel object (e.g. task, inode, file, sk_buff,
 131 etc) as well as some top-level hook function pointers for system
 132 operations.  This structure is likely to be flattened in the future
 133 for performance.  The placement of the hook calls in the kernel code
 134 is described by the "called:" lines in the per-hook documentation in
 135 the header file.  The hook calls can also be easily found in the
 136 kernel code by looking for the string "security_ops->".
 137
 138 </para>
 139
 140 <para>
 141 Linus mentioned per-process security hooks in his original remarks as a
 142 possible alternative to global security hooks.  However, if LSM were
 143 to start from the perspective of per-process hooks, then the base
 144 framework would have to deal with how to handle operations that
 145 involve multiple processes (e.g. kill), since each process might have
 146 its own hook for controlling the operation.  This would require a
 147 general mechanism for composing hooks in the base framework.
 148 Additionally, LSM would still need global hooks for operations that
 149 have no process context (e.g. network input operations).
 150 Consequently, LSM provides global security hooks, but a security
 151 module is free to implement per-process hooks (where that makes sense)
 152 by storing a security_ops table in each process' security field and
 153 then invoking these per-process hooks from the global hooks.
 154 The problem of composition is thus deferred to the module.
 155 </para>
 156
 157 <para>
 158 The global security_ops table is initialized to a set of hook
 159 functions provided by a dummy security module that provides
 160 traditional superuser logic.  A <function>register_security</function>
 161 function (in <filename>security/security.c</filename>) is provided to
 162 allow a security module to set security_ops to refer to its own hook
 163 functions, and an <function>unregister_security</function> function is
 164 provided to revert security_ops to the dummy module hooks.  This
 165 mechanism is used to set the primary security module, which is
 166 responsible for making the final decision for each hook.
 167 </para>
 168
 169 <para>
 170 LSM also provides a simple mechanism for stacking additional security
 171 modules with the primary security module.  It defines
 172 <function>register_security</function> and
 173 <function>unregister_security</function> hooks in the
 174 <structname>security_operations</structname> structure and provides
 175 <function>mod_reg_security</function> and
 176 <function>mod_unreg_security</function> functions that invoke these
 177 hooks after performing some sanity checking.  A security module can
 178 call these functions in order to stack with other modules.  However,
 179 the actual details of how this stacking is handled are deferred to the
 180 module, which can implement these hooks in any way it wishes
 181 (including always returning an error if it does not wish to support
 182 stacking).  In this manner, LSM again defers the problem of
 183 composition to the module.
 184 </para>
 185
 186 <para>
 187 Although the LSM hooks are organized into substructures based on
 188 kernel object, all of the hooks can be viewed as falling into two
 189 major categories: hooks that are used to manage the security fields
 190 and hooks that are used to perform access control.  Examples of the
 191 first category of hooks include the
 192 <function>alloc_security</function> and
 193 <function>free_security</function> hooks defined for each kernel data
 194 structure that has a security field.  These hooks are used to allocate
 195 and free security structures for kernel objects.  The first category
 196 of hooks also includes hooks that set information in the security
 197 field after allocation, such as the <function>post_lookup</function>
 198 hook in <structname>struct inode_security_ops</structname>.  This hook
 199 is used to set security information for inodes after successful lookup
 200 operations.  An example of the second category of hooks is the
 201 <function>permission</function> hook in
 202 <structname>struct inode_security_ops</structname>.  This hook checks
 203 permission when accessing an inode.
 204 </para>
 205
 206 </sect1>
 207
 208 <sect1 id="cap"><title>LSM Capabilities Module</title>
 209
 210 <para>
 211 The LSM kernel patch moves most of the existing POSIX.1e capabilities
 212 logic into an optional security module stored in the file
 213 <filename>security/capability.c</filename>.  This change allows
 214 users who do not want to use capabilities to omit this code entirely
 215 from their kernel, instead using the dummy module for traditional
 216 superuser logic or any other module that they desire.  This change
 217 also allows the developers of the capabilities logic to maintain and
 218 enhance their code more freely, without needing to integrate patches
 219 back into the base kernel.
 220 </para>
 221
 222 <para>
 223 In addition to moving the capabilities logic, the LSM kernel patch
 224 could move the capability-related fields from the kernel data
 225 structures into the new security fields managed by the security
 226 modules.  However, at present, the LSM kernel patch leaves the
 227 capability fields in the kernel data structures.  In his original
 228 remarks, Linus suggested that this might be preferable so that other
 229 security modules can be easily stacked with the capabilities module
 230 without needing to chain multiple security structures on the security field.
 231 It also avoids imposing extra overhead on the capabilities module
 232 to manage the security fields.  However, the LSM framework could
 233 certainly support such a move if it is determined to be desirable,
 234 with only a few additional changes described below.
 235 </para>
 236
 237 <para>
 238 At present, the capabilities logic for computing process capabilities
 239 on <function>execve</function> and <function>set*uid</function>,
 240 checking capabilities for a particular process, saving and checking
 241 capabilities for netlink messages, and handling the
 242 <function>capget</function> and <function>capset</function> system
 243 calls have been moved into the capabilities module.  There are still a
 244 few locations in the base kernel where capability-related fields are
 245 directly examined or modified, but the current version of the LSM
 246 patch does allow a security module to completely replace the
 247 assignment and testing of capabilities.  These few locations would
 248 need to be changed if the capability-related fields were moved into
 249 the security field.  The following is a list of known locations that
 250 still perform such direct examination or modification of
 251 capability-related fields:
 252 <itemizedlist>
 253 <listitem><para><filename>fs/open.c</filename>:<function>sys_access</function></para></listitem>
 254 <listitem><para><filename>fs/lockd/host.c</filename>:<function>nlm_bind_host</function></para></listitem>
 255 <listitem><para><filename>fs/nfsd/auth.c</filename>:<function>nfsd_setuser</function></para></listitem>
 256 <listitem><para><filename>fs/proc/array.c</filename>:<function>task_cap</function></para></listitem>
 257 </itemizedlist>
 258 </para>
 259
 260 </sect1>
 261
 262 </article>