lsm.tmpl 12 KB

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