Skip to content

Commit e2d467d

Browse files
cschauflerJonathan Corbet
authored andcommitted
Documentation: LSM: Correct the basic LSM description
This is a first pass at updating the basic documentation on Linux Security Modules (LSM), which is frighteningly out of date. Remove untrue statements about the LSM framework. Replace them with true statements where it is convenient to do so. This is the beginnig of a larger effort to bring the LSM documentation up to date. Signed-off-by: Casey Schaufler <[email protected]> Link: https://lore.kernel.org/r/[email protected] Signed-off-by: Jonathan Corbet <[email protected]>
1 parent cea0fad commit e2d467d

File tree

1 file changed

+66
-136
lines changed

1 file changed

+66
-136
lines changed

Documentation/security/lsm.rst

Lines changed: 66 additions & 136 deletions
Original file line numberDiff line numberDiff line change
@@ -35,47 +35,50 @@ desired model of security. Linus also suggested the possibility of
3535
migrating the Linux capabilities code into such a module.
3636

3737
The Linux Security Modules (LSM) project was started by WireX to develop
38-
such a framework. LSM is a joint development effort by several security
38+
such a framework. LSM was a joint development effort by several security
3939
projects, including Immunix, SELinux, SGI and Janus, and several
4040
individuals, including Greg Kroah-Hartman and James Morris, to develop a
41-
Linux kernel patch that implements this framework. The patch is
42-
currently tracking the 2.4 series and is targeted for integration into
43-
the 2.5 development series. This technical report provides an overview
44-
of the framework and the example capabilities security module provided
45-
by the LSM kernel patch.
41+
Linux kernel patch that implements this framework. The work was
42+
incorporated in the mainstream in December of 2003. This technical
43+
report provides an overview of the framework and the capabilities
44+
security module.
4645

4746
LSM Framework
4847
=============
4948

50-
The LSM kernel patch provides a general kernel framework to support
49+
The LSM framework provides a general kernel framework to support
5150
security modules. In particular, the LSM framework is primarily focused
5251
on supporting access control modules, although future development is
53-
likely to address other security needs such as auditing. By itself, the
52+
likely to address other security needs such as sandboxing. By itself, the
5453
framework does not provide any additional security; it merely provides
55-
the infrastructure to support security modules. The LSM kernel patch
56-
also moves most of the capabilities logic into an optional security
57-
module, with the system defaulting to the traditional superuser logic.
54+
the infrastructure to support security modules. The LSM framework is
55+
optional, requiring `CONFIG_SECURITY` to be enabled. The capabilities
56+
logic is implemented as a security module.
5857
This capabilities module is discussed further in
5958
`LSM Capabilities Module`_.
6059

61-
The LSM kernel patch adds security fields to kernel data structures and
62-
inserts calls to hook functions at critical points in the kernel code to
63-
manage the security fields and to perform access control. It also adds
64-
functions for registering and unregistering security modules, and adds a
65-
general :c:func:`security()` system call to support new system calls
66-
for security-aware applications.
67-
68-
The LSM security fields are simply ``void*`` pointers. For process and
69-
program execution security information, security fields were added to
60+
The LSM framework includes security fields in kernel data structures and
61+
calls to hook functions at critical points in the kernel code to
62+
manage the security fields and to perform access control.
63+
It also adds functions for registering security modules.
64+
An interface `/sys/kernel/security/lsm` reports a comma separated list
65+
of security modules that are active on the system.
66+
67+
The LSM security fields are simply ``void*`` pointers.
68+
The data is referred to as a blob, which may be managed by
69+
the framework or by the individual security modules that use it.
70+
Security blobs that are used by more than one security module are
71+
typically managed by the framework.
72+
For process and
73+
program execution security information, security fields are included in
7074
:c:type:`struct task_struct <task_struct>` and
71-
:c:type:`struct linux_binprm <linux_binprm>`. For filesystem
72-
security information, a security field was added to :c:type:`struct
75+
:c:type:`struct cred <cred>`.
76+
For filesystem
77+
security information, a security field is included in :c:type:`struct
7378
super_block <super_block>`. For pipe, file, and socket security
74-
information, security fields were added to :c:type:`struct inode
75-
<inode>` and :c:type:`struct file <file>`. For packet and
76-
network device security information, security fields were added to
77-
:c:type:`struct sk_buff <sk_buff>` and :c:type:`struct
78-
net_device <net_device>`. For System V IPC security information,
79+
information, security fields are included in :c:type:`struct inode
80+
<inode>` and :c:type:`struct file <file>`.
81+
For System V IPC security information,
7982
security fields were added to :c:type:`struct kern_ipc_perm
8083
<kern_ipc_perm>` and :c:type:`struct msg_msg
8184
<msg_msg>`; additionally, the definitions for :c:type:`struct
@@ -84,118 +87,45 @@ were moved to header files (``include/linux/msg.h`` and
8487
``include/linux/shm.h`` as appropriate) to allow the security modules to
8588
use these definitions.
8689

87-
Each LSM hook is a function pointer in a global table, security_ops.
88-
This 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
91-
included in this header file. At present, this structure consists of a
92-
collection of substructures that group related hooks based on the kernel
93-
object (e.g. task, inode, file, sk_buff, etc) as well as some top-level
94-
hook function pointers for system operations. This structure is likely
95-
to be flattened in the future for performance. The placement of the hook
96-
calls in the kernel code is described by the "called:" lines in the
97-
per-hook documentation in the header file. The hook calls can also be
98-
easily found in the kernel code by looking for the string
99-
"security_ops->".
100-
101-
Linus mentioned per-process security hooks in his original remarks as a
102-
possible alternative to global security hooks. However, if LSM were to
103-
start from the perspective of per-process hooks, then the base framework
104-
would have to deal with how to handle operations that involve multiple
105-
processes (e.g. kill), since each process might have its own hook for
106-
controlling the operation. This would require a general mechanism for
107-
composing hooks in the base framework. Additionally, LSM would still
108-
need global hooks for operations that have no process context (e.g.
109-
network input operations). Consequently, LSM provides global security
110-
hooks, but a security module is free to implement per-process hooks
111-
(where that makes sense) by storing a security_ops table in each
112-
process' security field and then invoking these per-process hooks from
113-
the global hooks. The problem of composition is thus deferred to the
114-
module.
115-
116-
The global security_ops table is initialized to a set of hook functions
117-
provided by a dummy security module that provides traditional superuser
118-
logic. A :c:func:`register_security()` function (in
119-
``security/security.c``) is provided to allow a security module to set
120-
security_ops to refer to its own hook functions, and an
121-
:c:func:`unregister_security()` function is provided to revert
122-
security_ops to the dummy module hooks. This mechanism is used to set
123-
the primary security module, which is responsible for making the final
124-
decision for each hook.
125-
126-
LSM also provides a simple mechanism for stacking additional security
127-
modules with the primary security module. It defines
128-
:c:func:`register_security()` and
129-
:c:func:`unregister_security()` hooks in the :c:type:`struct
130-
security_operations <security_operations>` structure and
131-
provides :c:func:`mod_reg_security()` and
132-
:c:func:`mod_unreg_security()` functions that invoke these hooks
133-
after performing some sanity checking. A security module can call these
134-
functions in order to stack with other modules. However, the actual
135-
details of how this stacking is handled are deferred to the module,
136-
which can implement these hooks in any way it wishes (including always
137-
returning an error if it does not wish to support stacking). In this
138-
manner, LSM again defers the problem of composition to the module.
139-
140-
Although the LSM hooks are organized into substructures based on kernel
141-
object, all of the hooks can be viewed as falling into two major
90+
For packet and
91+
network device security information, security fields were added to
92+
:c:type:`struct sk_buff <sk_buff>` and
93+
:c:type:`struct scm_cookie <scm_cookie>`.
94+
Unlike the other security module data, the data used here is a
95+
32-bit integer. The security modules are required to map or otherwise
96+
associate these values with real security attributes.
97+
98+
LSM hooks are maintained in lists. A list is maintained for each
99+
hook, and the hooks are called in the order specified by CONFIG_LSM.
100+
Detailed documentation for each hook is
101+
included in the `include/linux/lsm_hooks.h` header file.
102+
103+
The LSM framework provides for a close approximation of
104+
general security module stacking. It defines
105+
security_add_hooks() to which each security module passes a
106+
:c:type:`struct security_hooks_list <security_hooks_list>`,
107+
which are added to the lists.
108+
The LSM framework does not provide a mechanism for removing hooks that
109+
have been registered. The SELinux security module has implemented
110+
a way to remove itself, however the feature has been deprecated.
111+
112+
The hooks can be viewed as falling into two major
142113
categories: hooks that are used to manage the security fields and hooks
143114
that are used to perform access control. Examples of the first category
144-
of hooks include the :c:func:`alloc_security()` and
145-
:c:func:`free_security()` hooks defined for each kernel data
146-
structure that has a security field. These hooks are used to allocate
147-
and free security structures for kernel objects. The first category of
148-
hooks also includes hooks that set information in the security field
149-
after allocation, such as the :c:func:`post_lookup()` hook in
150-
:c:type:`struct inode_security_ops <inode_security_ops>`.
151-
This hook is used to set security information for inodes after
152-
successful lookup operations. An example of the second category of hooks
153-
is the :c:func:`permission()` hook in :c:type:`struct
154-
inode_security_ops <inode_security_ops>`. This hook checks
155-
permission when accessing an inode.
115+
of hooks include the security_inode_alloc() and security_inode_free()
116+
These hooks are used to allocate
117+
and free security structures for inode objects.
118+
An example of the second category of hooks
119+
is the security_inode_permission() hook.
120+
This hook checks permission when accessing an inode.
156121

157122
LSM Capabilities Module
158123
=======================
159124

160-
The LSM kernel patch moves most of the existing POSIX.1e capabilities
161-
logic into an optional security module stored in the file
162-
``security/capability.c``. This change allows users who do not want to
163-
use capabilities to omit this code entirely from their kernel, instead
164-
using the dummy module for traditional superuser logic or any other
165-
module that they desire. This change also allows the developers of the
166-
capabilities logic to maintain and enhance their code more freely,
167-
without needing to integrate patches back into the base kernel.
168-
169-
In addition to moving the capabilities logic, the LSM kernel patch could
170-
move the capability-related fields from the kernel data structures into
171-
the new security fields managed by the security modules. However, at
172-
present, the LSM kernel patch leaves the capability fields in the kernel
173-
data structures. In his original remarks, Linus suggested that this
174-
might be preferable so that other security modules can be easily stacked
175-
with the capabilities module without needing to chain multiple security
176-
structures on the security field. It also avoids imposing extra overhead
177-
on the capabilities module to manage the security fields. However, the
178-
LSM framework could certainly support such a move if it is determined to
179-
be desirable, with only a few additional changes described below.
180-
181-
At present, the capabilities logic for computing process capabilities on
182-
:c:func:`execve()` and :c:func:`set\*uid()`, checking
183-
capabilities for a particular process, saving and checking capabilities
184-
for netlink messages, and handling the :c:func:`capget()` and
185-
:c:func:`capset()` system calls have been moved into the
186-
capabilities module. There are still a few locations in the base kernel
187-
where capability-related fields are directly examined or modified, but
188-
the current version of the LSM patch does allow a security module to
189-
completely replace the assignment and testing of capabilities. These few
190-
locations would need to be changed if the capability-related fields were
191-
moved into the security field. The following is a list of known
192-
locations that still perform such direct examination or modification of
193-
capability-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()`
125+
The POSIX.1e capabilities logic is maintained as a security module
126+
stored in the file ``security/commoncap.c``. The capabilities
127+
module uses the order field of the :c:type:`lsm_info` description
128+
to identify it as the first security module to be registered.
129+
The capabilities security module does not use the general security
130+
blobs, unlike other modules. The reasons are historical and are
131+
based on overhead, complexity and performance concerns.

0 commit comments

Comments
 (0)