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