This file is outdated. Still, as it is the only one left at DocBook dir, convert it, and store it, with a .txt extension, under Documentation/lsm.txt. This way, we can get rid of DocBook from the building system, without needing to wait for someone to take care of it. Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>tirimbino
Mauro Carvalho Chehab
8 years ago
parent
bffac837f3
commit
415008af32
@ -1,265 +0,0 @@ |
||||
<?xml version="1.0" encoding="UTF-8"?> |
||||
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" |
||||
"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []> |
||||
|
||||
<article class="whitepaper" id="LinuxSecurityModule" lang="en"> |
||||
<articleinfo> |
||||
<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> |
||||
</articleinfo> |
||||
|
||||
<sect1 id="Introduction"><title>Introduction</title> |
||||
|
||||
<para> |
||||
In March 2001, the National Security Agency (NSA) gave a presentation |
||||
about Security-Enhanced Linux (SELinux) at the 2.5 Linux Kernel |
||||
Summit. SELinux is an implementation of flexible and fine-grained |
||||
nondiscretionary access controls in the Linux kernel, originally |
||||
implemented as its own particular kernel patch. Several other |
||||
security projects (e.g. RSBAC, Medusa) have also developed flexible |
||||
access control architectures for the Linux kernel, and various |
||||
projects have developed particular access control models for Linux |
||||
(e.g. LIDS, DTE, SubDomain). Each project has developed and |
||||
maintained its own kernel patch to support its security needs. |
||||
</para> |
||||
|
||||
<para> |
||||
In response to the NSA presentation, Linus Torvalds made a set of |
||||
remarks that described a security framework he would be willing to |
||||
consider for inclusion in the mainstream Linux kernel. He described a |
||||
general framework that would provide a set of security hooks to |
||||
control operations on kernel objects and a set of opaque security |
||||
fields in kernel data structures for maintaining security attributes. |
||||
This framework could then be used by loadable kernel modules to |
||||
implement any desired model of security. Linus also suggested the |
||||
possibility of migrating the Linux capabilities code into such a |
||||
module. |
||||
</para> |
||||
|
||||
<para> |
||||
The Linux Security Modules (LSM) project was started by WireX to |
||||
develop such a framework. LSM is a joint development effort by |
||||
several security projects, including Immunix, SELinux, SGI and Janus, |
||||
and several individuals, including Greg Kroah-Hartman and James |
||||
Morris, to develop a Linux kernel patch that implements this |
||||
framework. The patch is currently tracking the 2.4 series and is |
||||
targeted for integration into the 2.5 development series. This |
||||
technical report provides an overview of the framework and the example |
||||
capabilities 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 support |
||||
security modules. In particular, the LSM framework is primarily |
||||
focused on supporting access control modules, although future |
||||
development is likely to address other security needs such as |
||||
auditing. By itself, the framework does not provide any additional |
||||
security; it merely provides the infrastructure to support security |
||||
modules. The LSM kernel patch also moves most of the capabilities |
||||
logic into an optional security module, with the system defaulting |
||||
to the traditional superuser logic. This capabilities module |
||||
is discussed further in <xref linkend="cap"/>. |
||||
</para> |
||||
|
||||
<para> |
||||
The LSM kernel patch adds security fields to kernel data structures |
||||
and inserts calls to hook functions at critical points in the kernel |
||||
code to manage the security fields and to perform access control. It |
||||
also adds functions for registering and unregistering security |
||||
modules, and adds a general <function>security</function> system call |
||||
to support new system calls for security-aware applications. |
||||
</para> |
||||
|
||||
<para> |
||||
The LSM security fields are simply <type>void*</type> pointers. For |
||||
process and program execution security information, security fields |
||||
were added to <structname>struct task_struct</structname> and |
||||
<structname>struct linux_binprm</structname>. For filesystem security |
||||
information, a security field was added to |
||||
<structname>struct super_block</structname>. For pipe, file, and socket |
||||
security information, security fields were added to |
||||
<structname>struct inode</structname> and |
||||
<structname>struct file</structname>. For packet and network device security |
||||
information, security fields were added to |
||||
<structname>struct sk_buff</structname> and |
||||
<structname>struct net_device</structname>. For System V IPC security |
||||
information, security fields were added to |
||||
<structname>struct kern_ipc_perm</structname> and |
||||
<structname>struct msg_msg</structname>; additionally, the definitions |
||||
for <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 allow |
||||
the 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 documentation |
||||
for each hook is included in this header file. At present, this |
||||
structure consists of a collection of substructures that group related |
||||
hooks based on the kernel object (e.g. task, inode, file, sk_buff, |
||||
etc) as well as some top-level hook function pointers for system |
||||
operations. This structure is likely to be flattened in the future |
||||
for performance. The placement of the hook calls in the kernel code |
||||
is described by the "called:" lines in the per-hook documentation in |
||||
the header file. The hook calls can also be easily found in the |
||||
kernel code by looking for the string "security_ops->". |
||||
|
||||
</para> |
||||
|
||||
<para> |
||||
Linus mentioned per-process security hooks in his original remarks as a |
||||
possible alternative to global security hooks. However, if LSM were |
||||
to start from the perspective of per-process hooks, then the base |
||||
framework would have to deal with how to handle operations that |
||||
involve multiple processes (e.g. kill), since each process might have |
||||
its own hook for controlling the operation. This would require a |
||||
general mechanism for composing hooks in the base framework. |
||||
Additionally, LSM would still need global hooks for operations that |
||||
have no process context (e.g. network input operations). |
||||
Consequently, LSM provides global security hooks, but a security |
||||
module is free to implement per-process hooks (where that makes sense) |
||||
by storing a security_ops table in each process' security field and |
||||
then 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 hook |
||||
functions provided by a dummy security module that provides |
||||
traditional superuser logic. A <function>register_security</function> |
||||
function (in <filename>security/security.c</filename>) is provided to |
||||
allow a security module to set security_ops to refer to its own hook |
||||
functions, and an <function>unregister_security</function> function is |
||||
provided to revert security_ops to the dummy module hooks. This |
||||
mechanism is used to set the primary security module, which is |
||||
responsible for making the final decision for each hook. |
||||
</para> |
||||
|
||||
<para> |
||||
LSM also provides a simple mechanism for stacking additional security |
||||
modules 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 these |
||||
hooks after performing some sanity checking. A security module can |
||||
call these functions in order to stack with other modules. However, |
||||
the actual details of how this stacking is handled are deferred to the |
||||
module, which can implement these hooks in any way it wishes |
||||
(including always returning an error if it does not wish to support |
||||
stacking). In this manner, LSM again defers the problem of |
||||
composition to the module. |
||||
</para> |
||||
|
||||
<para> |
||||
Although the LSM hooks are organized into substructures based on |
||||
kernel object, all of the hooks can be viewed as falling into two |
||||
major categories: hooks that are used to manage the security fields |
||||
and hooks that are used to perform access control. Examples of the |
||||
first category of hooks include the |
||||
<function>alloc_security</function> and |
||||
<function>free_security</function> hooks defined for each kernel data |
||||
structure that has a security field. These hooks are used to allocate |
||||
and free security structures for kernel objects. The first category |
||||
of hooks also includes hooks that set information in the security |
||||
field after allocation, such as the <function>post_lookup</function> |
||||
hook in <structname>struct inode_security_ops</structname>. This hook |
||||
is used to set security information for inodes after successful lookup |
||||
operations. An example of the second category of hooks is the |
||||
<function>permission</function> hook in |
||||
<structname>struct inode_security_ops</structname>. This hook checks |
||||
permission 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 capabilities |
||||
logic into an optional security module stored in the file |
||||
<filename>security/capability.c</filename>. This change allows |
||||
users who do not want to use capabilities to omit this code entirely |
||||
from their kernel, instead using the dummy module for traditional |
||||
superuser logic or any other module that they desire. This change |
||||
also allows the developers of the capabilities logic to maintain and |
||||
enhance their code more freely, without needing to integrate patches |
||||
back into the base kernel. |
||||
</para> |
||||
|
||||
<para> |
||||
In addition to moving the capabilities logic, the LSM kernel patch |
||||
could move the capability-related fields from the kernel data |
||||
structures into the new security fields managed by the security |
||||
modules. However, at present, the LSM kernel patch leaves the |
||||
capability fields in the kernel data structures. In his original |
||||
remarks, Linus suggested that this might be preferable so that other |
||||
security modules can be easily stacked with the capabilities module |
||||
without needing to chain multiple security structures on the security field. |
||||
It also avoids imposing extra overhead on the capabilities module |
||||
to manage the security fields. However, the LSM framework could |
||||
certainly 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 capabilities |
||||
on <function>execve</function> and <function>set*uid</function>, |
||||
checking capabilities for a particular process, saving and checking |
||||
capabilities for netlink messages, and handling the |
||||
<function>capget</function> and <function>capset</function> system |
||||
calls have been moved into the capabilities module. There are still a |
||||
few locations in the base kernel where capability-related fields are |
||||
directly examined or modified, but the current version of the LSM |
||||
patch does allow a security module to completely replace the |
||||
assignment and testing of capabilities. These few locations would |
||||
need to be changed if the capability-related fields were moved into |
||||
the security field. The following is a list of known locations that |
||||
still perform such direct examination or modification of |
||||
capability-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> |
||||
@ -0,0 +1,201 @@ |
||||
======================================================== |
||||
Linux Security Modules: General Security Hooks for Linux |
||||
======================================================== |
||||
|
||||
:Author: Stephen Smalley |
||||
:Author: Timothy Fraser |
||||
:Author: Chris Vance |
||||
|
||||
.. note:: |
||||
|
||||
The APIs described in this book are outdated. |
||||
|
||||
Introduction |
||||
============ |
||||
|
||||
In March 2001, the National Security Agency (NSA) gave a presentation |
||||
about Security-Enhanced Linux (SELinux) at the 2.5 Linux Kernel Summit. |
||||
SELinux is an implementation of flexible and fine-grained |
||||
nondiscretionary access controls in the Linux kernel, originally |
||||
implemented as its own particular kernel patch. Several other security |
||||
projects (e.g. RSBAC, Medusa) have also developed flexible access |
||||
control architectures for the Linux kernel, and various projects have |
||||
developed particular access control models for Linux (e.g. LIDS, DTE, |
||||
SubDomain). Each project has developed and maintained its own kernel |
||||
patch to support its security needs. |
||||
|
||||
In response to the NSA presentation, Linus Torvalds made a set of |
||||
remarks that described a security framework he would be willing to |
||||
consider for inclusion in the mainstream Linux kernel. He described a |
||||
general framework that would provide a set of security hooks to control |
||||
operations on kernel objects and a set of opaque security fields in |
||||
kernel data structures for maintaining security attributes. This |
||||
framework could then be used by loadable kernel modules to implement any |
||||
desired model of security. Linus also suggested the possibility of |
||||
migrating the Linux capabilities code into such a module. |
||||
|
||||
The Linux Security Modules (LSM) project was started by WireX to develop |
||||
such a framework. LSM is a joint development effort by several security |
||||
projects, including Immunix, SELinux, SGI and Janus, and several |
||||
individuals, including Greg Kroah-Hartman and James Morris, to develop a |
||||
Linux kernel patch that implements this framework. The patch is |
||||
currently tracking the 2.4 series and is targeted for integration into |
||||
the 2.5 development series. This technical report provides an overview |
||||
of the framework and the example capabilities security module provided |
||||
by the LSM kernel patch. |
||||
|
||||
LSM Framework |
||||
============= |
||||
|
||||
The LSM kernel patch provides a general kernel framework to support |
||||
security modules. In particular, the LSM framework is primarily focused |
||||
on supporting access control modules, although future development is |
||||
likely to address other security needs such as auditing. By itself, the |
||||
framework does not provide any additional security; it merely provides |
||||
the infrastructure to support security modules. The LSM kernel patch |
||||
also moves most of the capabilities logic into an optional security |
||||
module, with the system defaulting to the traditional superuser logic. |
||||
This capabilities module is discussed further in |
||||
`LSM Capabilities Module <#cap>`__. |
||||
|
||||
The LSM kernel patch adds security fields to kernel data structures and |
||||
inserts calls to hook functions at critical points in the kernel code to |
||||
manage the security fields and to perform access control. It also adds |
||||
functions for registering and unregistering security modules, and adds a |
||||
general :c:func:`security()` system call to support new system calls |
||||
for security-aware applications. |
||||
|
||||
The LSM security fields are simply ``void*`` pointers. For process and |
||||
program execution security information, security fields were added to |
||||
:c:type:`struct task_struct <task_struct>` and |
||||
:c:type:`struct linux_binprm <linux_binprm>`. For filesystem |
||||
security information, a security field was added to :c:type:`struct |
||||
super_block <super_block>`. For pipe, file, and socket security |
||||
information, security fields were added to :c:type:`struct inode |
||||
<inode>` and :c:type:`struct file <file>`. For packet and |
||||
network device security information, security fields were added to |
||||
:c:type:`struct sk_buff <sk_buff>` and :c:type:`struct |
||||
net_device <net_device>`. For System V IPC security information, |
||||
security fields were added to :c:type:`struct kern_ipc_perm |
||||
<kern_ipc_perm>` and :c:type:`struct msg_msg |
||||
<msg_msg>`; additionally, the definitions for :c:type:`struct |
||||
msg_msg <msg_msg>`, struct msg_queue, and struct shmid_kernel |
||||
were moved to header files (``include/linux/msg.h`` and |
||||
``include/linux/shm.h`` as appropriate) to allow the security modules to |
||||
use these definitions. |
||||
|
||||
Each LSM hook is a function pointer in a global table, security_ops. |
||||
This table is a :c:type:`struct security_operations |
||||
<security_operations>` structure as defined by |
||||
``include/linux/security.h``. Detailed documentation for each hook is |
||||
included in this header file. At present, this structure consists of a |
||||
collection of substructures that group related hooks based on the kernel |
||||
object (e.g. task, inode, file, sk_buff, etc) as well as some top-level |
||||
hook function pointers for system operations. This structure is likely |
||||
to be flattened in the future for performance. The placement of the hook |
||||
calls in the kernel code is described by the "called:" lines in the |
||||
per-hook documentation in the header file. The hook calls can also be |
||||
easily found in the kernel code by looking for the string |
||||
"security_ops->". |
||||
|
||||
Linus mentioned per-process security hooks in his original remarks as a |
||||
possible alternative to global security hooks. However, if LSM were to |
||||
start from the perspective of per-process hooks, then the base framework |
||||
would have to deal with how to handle operations that involve multiple |
||||
processes (e.g. kill), since each process might have its own hook for |
||||
controlling the operation. This would require a general mechanism for |
||||
composing hooks in the base framework. Additionally, LSM would still |
||||
need global hooks for operations that have no process context (e.g. |
||||
network input operations). Consequently, LSM provides global security |
||||
hooks, but a security module is free to implement per-process hooks |
||||
(where that makes sense) by storing a security_ops table in each |
||||
process' security field and then invoking these per-process hooks from |
||||
the global hooks. The problem of composition is thus deferred to the |
||||
module. |
||||
|
||||
The global security_ops table is initialized to a set of hook functions |
||||
provided by a dummy security module that provides traditional superuser |
||||
logic. A :c:func:`register_security()` function (in |
||||
``security/security.c``) is provided to allow a security module to set |
||||
security_ops to refer to its own hook functions, and an |
||||
:c:func:`unregister_security()` function is provided to revert |
||||
security_ops to the dummy module hooks. This mechanism is used to set |
||||
the primary security module, which is responsible for making the final |
||||
decision for each hook. |
||||
|
||||
LSM also provides a simple mechanism for stacking additional security |
||||
modules with the primary security module. It defines |
||||
:c:func:`register_security()` and |
||||
:c:func:`unregister_security()` hooks in the :c:type:`struct |
||||
security_operations <security_operations>` structure and |
||||
provides :c:func:`mod_reg_security()` and |
||||
:c:func:`mod_unreg_security()` functions that invoke these hooks |
||||
after performing some sanity checking. A security module can call these |
||||
functions in order to stack with other modules. However, the actual |
||||
details of how this stacking is handled are deferred to the module, |
||||
which can implement these hooks in any way it wishes (including always |
||||
returning an error if it does not wish to support stacking). In this |
||||
manner, LSM again defers the problem of composition to the module. |
||||
|
||||
Although the LSM hooks are organized into substructures based on kernel |
||||
object, all of the hooks can be viewed as falling into two major |
||||
categories: hooks that are used to manage the security fields and hooks |
||||
that are used to perform access control. Examples of the first category |
||||
of hooks include the :c:func:`alloc_security()` and |
||||
:c:func:`free_security()` hooks defined for each kernel data |
||||
structure that has a security field. These hooks are used to allocate |
||||
and free security structures for kernel objects. The first category of |
||||
hooks also includes hooks that set information in the security field |
||||
after allocation, such as the :c:func:`post_lookup()` hook in |
||||
:c:type:`struct inode_security_ops <inode_security_ops>`. |
||||
This hook is used to set security information for inodes after |
||||
successful lookup operations. An example of the second category of hooks |
||||
is the :c:func:`permission()` hook in :c:type:`struct |
||||
inode_security_ops <inode_security_ops>`. This hook checks |
||||
permission when accessing an inode. |
||||
|
||||
LSM Capabilities Module |
||||
======================= |
||||
|
||||
The LSM kernel patch moves most of the existing POSIX.1e capabilities |
||||
logic into an optional security module stored in the file |
||||
``security/capability.c``. This change allows users who do not want to |
||||
use capabilities to omit this code entirely from their kernel, instead |
||||
using the dummy module for traditional superuser logic or any other |
||||
module that they desire. This change also allows the developers of the |
||||
capabilities logic to maintain and enhance their code more freely, |
||||
without needing to integrate patches back into the base kernel. |
||||
|
||||
In addition to moving the capabilities logic, the LSM kernel patch could |
||||
move the capability-related fields from the kernel data structures into |
||||
the new security fields managed by the security modules. However, at |
||||
present, the LSM kernel patch leaves the capability fields in the kernel |
||||
data structures. In his original remarks, Linus suggested that this |
||||
might be preferable so that other security modules can be easily stacked |
||||
with the capabilities module without needing to chain multiple security |
||||
structures on the security field. It also avoids imposing extra overhead |
||||
on the capabilities module to manage the security fields. However, the |
||||
LSM framework could certainly support such a move if it is determined to |
||||
be desirable, with only a few additional changes described below. |
||||
|
||||
At present, the capabilities logic for computing process capabilities on |
||||
:c:func:`execve()` and :c:func:`set\*uid()`, checking |
||||
capabilities for a particular process, saving and checking capabilities |
||||
for netlink messages, and handling the :c:func:`capget()` and |
||||
:c:func:`capset()` system calls have been moved into the |
||||
capabilities module. There are still a few locations in the base kernel |
||||
where capability-related fields are directly examined or modified, but |
||||
the current version of the LSM patch does allow a security module to |
||||
completely replace the assignment and testing of capabilities. These few |
||||
locations would need to be changed if the capability-related fields were |
||||
moved into the security field. The following is a list of known |
||||
locations that still perform such direct examination or modification of |
||||
capability-related fields: |
||||
|
||||
- ``fs/open.c``::c:func:`sys_access()` |
||||
|
||||
- ``fs/lockd/host.c``::c:func:`nlm_bind_host()` |
||||
|
||||
- ``fs/nfsd/auth.c``::c:func:`nfsd_setuser()` |
||||
|
||||
- ``fs/proc/array.c``::c:func:`task_cap()` |
||||
Loading…
Reference in new issue