Groups | Search | Server Info | Keyboard shortcuts | Login | Register [http] [https] [nntp] [nntps]
Groups > linux.kernel > #1640893 > unrolled thread
| Started by | Kees Cook <keescook@chromium.org> |
|---|---|
| First post | 2017-05-13 14:00 +0200 |
| Last post | 2017-05-18 19:10 +0200 |
| Articles | 20 on this page of 22 — 5 participants |
Back to article view | Back to linux.kernel
[PATCH 00/17] convert/reorganize Documentation/security/ Kees Cook <keescook@chromium.org> - 2017-05-13 14:00 +0200
[PATCH 16/17] doc: ReSTify keys-request-key.txt Kees Cook <keescook@chromium.org> - 2017-05-13 14:00 +0200
[PATCH 04/17] doc: ReSTify credentials.txt Kees Cook <keescook@chromium.org> - 2017-05-13 14:00 +0200
[PATCH 06/17] doc: security: minor cleanups to build kernel-doc Kees Cook <keescook@chromium.org> - 2017-05-13 14:00 +0200
Re: [PATCH 06/17] doc: security: minor cleanups to build kernel-doc James Morris <jmorris@namei.org> - 2017-05-15 01:20 +0200
Re: [PATCH 06/17] doc: security: minor cleanups to build kernel-doc Jonathan Corbet <corbet@lwn.net> - 2017-05-15 19:30 +0200
Re: [PATCH 06/17] doc: security: minor cleanups to build kernel-doc Casey Schaufler <casey@schaufler-ca.com> - 2017-05-15 02:10 +0200
Re: [PATCH 06/17] doc: security: minor cleanups to build kernel-doc Kees Cook <keescook@chromium.org> - 2017-05-15 16:50 +0200
[PATCH 12/17] doc: ReSTify LoadPin.txt Kees Cook <keescook@chromium.org> - 2017-05-13 14:00 +0200
[PATCH 17/17] doc: ReSTify keys-trusted-encrypted.txt Kees Cook <keescook@chromium.org> - 2017-05-13 14:00 +0200
[PATCH 05/17] doc: ReSTify self-protection.txt Kees Cook <keescook@chromium.org> - 2017-05-13 14:00 +0200
[PATCH 03/17] doc: ReSTify IMA-templates.txt Kees Cook <keescook@chromium.org> - 2017-05-13 14:00 +0200
[PATCH 02/17] doc: ReSTify no_new_privs.txt Kees Cook <keescook@chromium.org> - 2017-05-13 14:00 +0200
[PATCH 13/17] doc: ReSTify Smack.txt Kees Cook <keescook@chromium.org> - 2017-05-13 14:00 +0200
Re: [PATCH 13/17] doc: ReSTify Smack.txt Casey Schaufler <casey@schaufler-ca.com> - 2017-05-15 16:20 +0200
[PATCH 07/17] doc: ReSTify and split LSM.txt Kees Cook <keescook@chromium.org> - 2017-05-13 14:00 +0200
[PATCH 09/17] doc: ReSTify apparmor.txt Kees Cook <keescook@chromium.org> - 2017-05-13 14:00 +0200
Re: [PATCH 09/17] doc: ReSTify apparmor.txt John Johansen <john.johansen@canonical.com> - 2017-05-13 21:50 +0200
Re: [PATCH 00/17] convert/reorganize Documentation/security/ Jonathan Corbet <corbet@lwn.net> - 2017-05-15 19:30 +0200
Re: [PATCH 00/17] convert/reorganize Documentation/security/ Kees Cook <keescook@chromium.org> - 2017-05-15 19:40 +0200
Re: [PATCH 00/17] convert/reorganize Documentation/security/ Jonathan Corbet <corbet@lwn.net> - 2017-05-18 19:00 +0200
Re: [PATCH 00/17] convert/reorganize Documentation/security/ Kees Cook <keescook@chromium.org> - 2017-05-18 19:10 +0200
Page 1 of 2 [1] 2 Next page →
| From | Kees Cook <keescook@chromium.org> |
|---|---|
| Date | 2017-05-13 14:00 +0200 |
| Subject | [PATCH 00/17] convert/reorganize Documentation/security/ |
| Message-ID | <tGDSi-39c-3@gated-at.bofh.it> |
Hi, This ReSTifies everything under Documentation/security/, and reorganizes some of it (mainly the LSMs) under /admin-guide/ per Jon's request. Since /security/ is already being indexed under the kernel development portion of the sphinx index, I didn't move it, keeping only things that were directly related to internal kernel development (keys, creds, etc). I also updated some path references, and MAINTAINERS lines. Some of the conversion could probably do with some tweaks, but I think this is a good first step in the right direction. -Kees
[toc] | [next] | [standalone]
| From | Kees Cook <keescook@chromium.org> |
|---|---|
| Date | 2017-05-13 14:00 +0200 |
| Subject | [PATCH 16/17] doc: ReSTify keys-request-key.txt |
| Message-ID | <tGDSj-39c-31@gated-at.bofh.it> |
| In reply to | #1640893 |
Adjusts for ReST markup and moves under keys security devel index.
Cc: David Howells <dhowells@redhat.com>
Signed-off-by: Kees Cook <keescook@chromium.org>
---
Documentation/filesystems/nfs/idmapper.txt | 2 +-
Documentation/networking/dns_resolver.txt | 2 +-
Documentation/security/00-INDEX | 2 -
Documentation/security/keys/index.rst | 1 +
.../{keys-request-key.txt => keys/request-key.rst} | 69 +++++++++++-----------
security/keys/request_key.c | 2 +-
security/keys/request_key_auth.c | 2 +-
7 files changed, 38 insertions(+), 42 deletions(-)
rename Documentation/security/{keys-request-key.txt => keys/request-key.rst} (78%)
diff --git a/Documentation/filesystems/nfs/idmapper.txt b/Documentation/filesystems/nfs/idmapper.txt
index fe03d10bb79a..b86831acd583 100644
--- a/Documentation/filesystems/nfs/idmapper.txt
+++ b/Documentation/filesystems/nfs/idmapper.txt
@@ -55,7 +55,7 @@ request-key will find the first matching line and corresponding program. In
this case, /some/other/program will handle all uid lookups and
/usr/sbin/nfs.idmap will handle gid, user, and group lookups.
-See <file:Documentation/security/keys-request-key.txt> for more information
+See <file:Documentation/security/keys/request-key.rst> for more information
about the request-key function.
diff --git a/Documentation/networking/dns_resolver.txt b/Documentation/networking/dns_resolver.txt
index d86adcdae420..eaa8f9a6fd5d 100644
--- a/Documentation/networking/dns_resolver.txt
+++ b/Documentation/networking/dns_resolver.txt
@@ -143,7 +143,7 @@ the key will be discarded and recreated when the data it holds has expired.
dns_query() returns a copy of the value attached to the key, or an error if
that is indicated instead.
-See <file:Documentation/security/keys-request-key.txt> for further
+See <file:Documentation/security/keys/request-key.rst> for further
information about request-key function.
diff --git a/Documentation/security/00-INDEX b/Documentation/security/00-INDEX
index 08a6e7a195ef..c8dbbc227326 100644
--- a/Documentation/security/00-INDEX
+++ b/Documentation/security/00-INDEX
@@ -1,6 +1,4 @@
00-INDEX
- this file.
-keys-request-key.txt
- - description of the kernel key request service.
keys-trusted-encrypted.txt
- info on the Trusted and Encrypted keys in the kernel key ring service.
diff --git a/Documentation/security/keys/index.rst b/Documentation/security/keys/index.rst
index d34f663354bb..d7ddbc1c2502 100644
--- a/Documentation/security/keys/index.rst
+++ b/Documentation/security/keys/index.rst
@@ -7,3 +7,4 @@ Kernel Keys
core
ecryptfs
+ request-key
diff --git a/Documentation/security/keys-request-key.txt b/Documentation/security/keys/request-key.rst
similarity index 78%
rename from Documentation/security/keys-request-key.txt
rename to Documentation/security/keys/request-key.rst
index 51987bfecfed..5cdcee28479e 100644
--- a/Documentation/security/keys-request-key.txt
+++ b/Documentation/security/keys/request-key.rst
@@ -1,19 +1,19 @@
- ===================
- KEY REQUEST SERVICE
- ===================
+===================
+Key Request Service
+===================
The key request service is part of the key retention service (refer to
Documentation/security/keys.txt). This document explains more fully how
the requesting algorithm works.
The process starts by either the kernel requesting a service by calling
-request_key*():
+``request_key*()``::
struct key *request_key(const struct key_type *type,
const char *description,
const char *callout_info);
-or:
+or::
struct key *request_key_with_auxdata(const struct key_type *type,
const char *description,
@@ -21,14 +21,14 @@ or:
size_t callout_len,
void *aux);
-or:
+or::
struct key *request_key_async(const struct key_type *type,
const char *description,
const char *callout_info,
size_t callout_len);
-or:
+or::
struct key *request_key_async_with_auxdata(const struct key_type *type,
const char *description,
@@ -36,7 +36,7 @@ or:
size_t callout_len,
void *aux);
-Or by userspace invoking the request_key system call:
+Or by userspace invoking the request_key system call::
key_serial_t request_key(const char *type,
const char *description,
@@ -67,38 +67,37 @@ own upcall mechanisms. If they do, then those should be substituted for the
forking and execution of /sbin/request-key.
-===========
-THE PROCESS
+The Process
===========
A request proceeds in the following manner:
- (1) Process A calls request_key() [the userspace syscall calls the kernel
+ 1) Process A calls request_key() [the userspace syscall calls the kernel
interface].
- (2) request_key() searches the process's subscribed keyrings to see if there's
+ 2) request_key() searches the process's subscribed keyrings to see if there's
a suitable key there. If there is, it returns the key. If there isn't,
and callout_info is not set, an error is returned. Otherwise the process
proceeds to the next step.
- (3) request_key() sees that A doesn't have the desired key yet, so it creates
+ 3) request_key() sees that A doesn't have the desired key yet, so it creates
two things:
- (a) An uninstantiated key U of requested type and description.
+ a) An uninstantiated key U of requested type and description.
- (b) An authorisation key V that refers to key U and notes that process A
+ b) An authorisation key V that refers to key U and notes that process A
is the context in which key U should be instantiated and secured, and
from which associated key requests may be satisfied.
- (4) request_key() then forks and executes /sbin/request-key with a new session
+ 4) request_key() then forks and executes /sbin/request-key with a new session
keyring that contains a link to auth key V.
- (5) /sbin/request-key assumes the authority associated with key U.
+ 5) /sbin/request-key assumes the authority associated with key U.
- (6) /sbin/request-key execs an appropriate program to perform the actual
+ 6) /sbin/request-key execs an appropriate program to perform the actual
instantiation.
- (7) The program may want to access another key from A's context (say a
+ 7) The program may want to access another key from A's context (say a
Kerberos TGT key). It just requests the appropriate key, and the keyring
search notes that the session keyring has auth key V in its bottom level.
@@ -110,10 +109,10 @@ A request proceeds in the following manner:
instantiate key U, using key W as a reference (perhaps it contacts a
Kerberos server using the TGT) and then instantiates key U.
- (9) Upon instantiating key U, auth key V is automatically revoked so that it
+ 9) Upon instantiating key U, auth key V is automatically revoked so that it
may not be used again.
-(10) The program then exits 0 and request_key() deletes key V and returns key
+ 10) The program then exits 0 and request_key() deletes key V and returns key
U to the caller.
This also extends further. If key W (step 7 above) didn't exist, key W would
@@ -127,8 +126,7 @@ This is because process A's keyrings can't simply be attached to
of them, and (b) it requires the same UID/GID/Groups all the way through.
-====================================
-NEGATIVE INSTANTIATION AND REJECTION
+Negative Instantiation And Rejection
====================================
Rather than instantiating a key, it is possible for the possessor of an
@@ -145,23 +143,22 @@ signal, the key under construction will be automatically negatively
instantiated for a short amount of time.
-====================
-THE SEARCH ALGORITHM
+The Search Algorithm
====================
A search of any particular keyring proceeds in the following fashion:
- (1) When the key management code searches for a key (keyring_search_aux) it
+ 1) When the key management code searches for a key (keyring_search_aux) it
firstly calls key_permission(SEARCH) on the keyring it's starting with,
if this denies permission, it doesn't search further.
- (2) It considers all the non-keyring keys within that keyring and, if any key
+ 2) It considers all the non-keyring keys within that keyring and, if any key
matches the criteria specified, calls key_permission(SEARCH) on it to see
if the key is allowed to be found. If it is, that key is returned; if
not, the search continues, and the error code is retained if of higher
priority than the one currently set.
- (3) It then considers all the keyring-type keys in the keyring it's currently
+ 3) It then considers all the keyring-type keys in the keyring it's currently
searching. It calls key_permission(SEARCH) on each keyring, and if this
grants permission, it recurses, executing steps (2) and (3) on that
keyring.
@@ -173,20 +170,20 @@ returned.
When search_process_keyrings() is invoked, it performs the following searches
until one succeeds:
- (1) If extant, the process's thread keyring is searched.
+ 1) If extant, the process's thread keyring is searched.
- (2) If extant, the process's process keyring is searched.
+ 2) If extant, the process's process keyring is searched.
- (3) The process's session keyring is searched.
+ 3) The process's session keyring is searched.
- (4) If the process has assumed the authority associated with a request_key()
+ 4) If the process has assumed the authority associated with a request_key()
authorisation key then:
- (a) If extant, the calling process's thread keyring is searched.
+ a) If extant, the calling process's thread keyring is searched.
- (b) If extant, the calling process's process keyring is searched.
+ b) If extant, the calling process's process keyring is searched.
- (c) The calling process's session keyring is searched.
+ c) The calling process's session keyring is searched.
The moment one succeeds, all pending errors are discarded and the found key is
returned.
@@ -194,7 +191,7 @@ returned.
Only if all these fail does the whole thing fail with the highest priority
error. Note that several errors may have come from LSM.
-The error priority is:
+The error priority is::
EKEYREVOKED > EKEYEXPIRED > ENOKEY
diff --git a/security/keys/request_key.c b/security/keys/request_key.c
index 9822e500d50d..63e63a42db3c 100644
--- a/security/keys/request_key.c
+++ b/security/keys/request_key.c
@@ -8,7 +8,7 @@
* as published by the Free Software Foundation; either version
* 2 of the License, or (at your option) any later version.
*
- * See Documentation/security/keys-request-key.txt
+ * See Documentation/security/keys/request-key.rst
*/
#include <linux/module.h>
diff --git a/security/keys/request_key_auth.c b/security/keys/request_key_auth.c
index 0f062156dfb2..afe9d22ab361 100644
--- a/security/keys/request_key_auth.c
+++ b/security/keys/request_key_auth.c
@@ -8,7 +8,7 @@
* as published by the Free Software Foundation; either version
* 2 of the License, or (at your option) any later version.
*
- * See Documentation/security/keys-request-key.txt
+ * See Documentation/security/keys/request-key.rst
*/
#include <linux/module.h>
--
2.7.4
[toc] | [prev] | [next] | [standalone]
| From | Kees Cook <keescook@chromium.org> |
|---|---|
| Date | 2017-05-13 14:00 +0200 |
| Subject | [PATCH 04/17] doc: ReSTify credentials.txt |
| Message-ID | <tGDSj-39c-33@gated-at.bofh.it> |
| In reply to | #1640893 |
This updates the credentials API documentation to ReST markup and moves
it under the security subsection of kernel API documentation.
Cc: David Howells <dhowells@redhat.com>
Signed-off-by: Kees Cook <keescook@chromium.org>
---
Documentation/security/00-INDEX | 2 -
.../security/{credentials.txt => credentials.rst} | 275 ++++++++++-----------
Documentation/security/index.rst | 1 +
include/linux/cred.h | 2 +-
kernel/cred.c | 2 +-
5 files changed, 127 insertions(+), 155 deletions(-)
rename Documentation/security/{credentials.txt => credentials.rst} (72%)
diff --git a/Documentation/security/00-INDEX b/Documentation/security/00-INDEX
index 414235c1fcfc..c4df62a9ae5b 100644
--- a/Documentation/security/00-INDEX
+++ b/Documentation/security/00-INDEX
@@ -10,8 +10,6 @@ Yama.txt
- documentation on the Yama Linux Security Module.
apparmor.txt
- documentation on the AppArmor security extension.
-credentials.txt
- - documentation about credentials in Linux.
keys-ecryptfs.txt
- description of the encryption keys for the ecryptfs filesystem.
keys-request-key.txt
diff --git a/Documentation/security/credentials.txt b/Documentation/security/credentials.rst
similarity index 72%
rename from Documentation/security/credentials.txt
rename to Documentation/security/credentials.rst
index 86257052e31a..038a7e19eff9 100644
--- a/Documentation/security/credentials.txt
+++ b/Documentation/security/credentials.rst
@@ -1,38 +1,18 @@
- ====================
- CREDENTIALS IN LINUX
- ====================
+====================
+Credentials in Linux
+====================
By: David Howells <dhowells@redhat.com>
-Contents:
-
- (*) Overview.
-
- (*) Types of credentials.
-
- (*) File markings.
-
- (*) Task credentials.
+.. contents:: :local:
- - Immutable credentials.
- - Accessing task credentials.
- - Accessing another task's credentials.
- - Altering credentials.
- - Managing credentials.
-
- (*) Open file credentials.
-
- (*) Overriding the VFS's use of credentials.
-
-
-========
-OVERVIEW
+Overview
========
There are several parts to the security check performed by Linux when one
object acts upon another:
- (1) Objects.
+ 1. Objects.
Objects are things in the system that may be acted upon directly by
userspace programs. Linux has a variety of actionable objects, including:
@@ -48,7 +28,7 @@ object acts upon another:
As a part of the description of all these objects there is a set of
credentials. What's in the set depends on the type of object.
- (2) Object ownership.
+ 2. Object ownership.
Amongst the credentials of most objects, there will be a subset that
indicates the ownership of that object. This is used for resource
@@ -57,7 +37,7 @@ object acts upon another:
In a standard UNIX filesystem, for instance, this will be defined by the
UID marked on the inode.
- (3) The objective context.
+ 3. The objective context.
Also amongst the credentials of those objects, there will be a subset that
indicates the 'objective context' of that object. This may or may not be
@@ -67,7 +47,7 @@ object acts upon another:
The objective context is used as part of the security calculation that is
carried out when an object is acted upon.
- (4) Subjects.
+ 4. Subjects.
A subject is an object that is acting upon another object.
@@ -77,10 +57,10 @@ object acts upon another:
Objects other than tasks may under some circumstances also be subjects.
For instance an open file may send SIGIO to a task using the UID and EUID
- given to it by a task that called fcntl(F_SETOWN) upon it. In this case,
+ given to it by a task that called ``fcntl(F_SETOWN)`` upon it. In this case,
the file struct will have a subjective context too.
- (5) The subjective context.
+ 5. The subjective context.
A subject has an additional interpretation of its credentials. A subset
of its credentials forms the 'subjective context'. The subjective context
@@ -92,7 +72,7 @@ object acts upon another:
from the real UID and GID that normally form the objective context of the
task.
- (6) Actions.
+ 6. Actions.
Linux has a number of actions available that a subject may perform upon an
object. The set of actions available depends on the nature of the subject
@@ -101,7 +81,7 @@ object acts upon another:
Actions include reading, writing, creating and deleting files; forking or
signalling and tracing tasks.
- (7) Rules, access control lists and security calculations.
+ 7. Rules, access control lists and security calculations.
When a subject acts upon an object, a security calculation is made. This
involves taking the subjective context, the objective context and the
@@ -111,7 +91,7 @@ object acts upon another:
There are two main sources of rules:
- (a) Discretionary access control (DAC):
+ a. Discretionary access control (DAC):
Sometimes the object will include sets of rules as part of its
description. This is an 'Access Control List' or 'ACL'. A Linux
@@ -127,7 +107,7 @@ object acts upon another:
A Linux file might also sport a POSIX ACL. This is a list of rules
that grants various permissions to arbitrary subjects.
- (b) Mandatory access control (MAC):
+ b. Mandatory access control (MAC):
The system as a whole may have one or more sets of rules that get
applied to all subjects and objects, regardless of their source.
@@ -139,65 +119,65 @@ object acts upon another:
that says that this action is either granted or denied.
-====================
-TYPES OF CREDENTIALS
+Types of Credentials
====================
The Linux kernel supports the following types of credentials:
- (1) Traditional UNIX credentials.
+ 1. Traditional UNIX credentials.
- Real User ID
- Real Group ID
+ - Real User ID
+ - Real Group ID
The UID and GID are carried by most, if not all, Linux objects, even if in
some cases it has to be invented (FAT or CIFS files for example, which are
derived from Windows). These (mostly) define the objective context of
that object, with tasks being slightly different in some cases.
- Effective, Saved and FS User ID
- Effective, Saved and FS Group ID
- Supplementary groups
+ - Effective, Saved and FS User ID
+ - Effective, Saved and FS Group ID
+ - Supplementary groups
These are additional credentials used by tasks only. Usually, an
EUID/EGID/GROUPS will be used as the subjective context, and real UID/GID
will be used as the objective. For tasks, it should be noted that this is
not always true.
- (2) Capabilities.
+ 2. Capabilities.
- Set of permitted capabilities
- Set of inheritable capabilities
- Set of effective capabilities
- Capability bounding set
+ - Set of permitted capabilities
+ - Set of inheritable capabilities
+ - Set of effective capabilities
+ - Capability bounding set
These are only carried by tasks. They indicate superior capabilities
granted piecemeal to a task that an ordinary task wouldn't otherwise have.
These are manipulated implicitly by changes to the traditional UNIX
- credentials, but can also be manipulated directly by the capset() system
- call.
+ credentials, but can also be manipulated directly by the ``capset()``
+ system call.
The permitted capabilities are those caps that the process might grant
- itself to its effective or permitted sets through capset(). This
+ itself to its effective or permitted sets through ``capset()``. This
inheritable set might also be so constrained.
The effective capabilities are the ones that a task is actually allowed to
make use of itself.
The inheritable capabilities are the ones that may get passed across
- execve().
+ ``execve()``.
The bounding set limits the capabilities that may be inherited across
- execve(), especially when a binary is executed that will execute as UID 0.
+ ``execve()``, especially when a binary is executed that will execute as
+ UID 0.
- (3) Secure management flags (securebits).
+ 3. Secure management flags (securebits).
These are only carried by tasks. These govern the way the above
credentials are manipulated and inherited over certain operations such as
execve(). They aren't used directly as objective or subjective
credentials.
- (4) Keys and keyrings.
+ 4. Keys and keyrings.
These are only carried by tasks. They carry and cache security tokens
that don't fit into the other standard UNIX credentials. They are for
@@ -218,7 +198,7 @@ The Linux kernel supports the following types of credentials:
For more information on using keys, see Documentation/security/keys.txt.
- (5) LSM
+ 5. LSM
The Linux Security Module allows extra controls to be placed over the
operations that a task may do. Currently Linux supports several LSM
@@ -228,7 +208,7 @@ The Linux kernel supports the following types of credentials:
rules (policies) that say what operations a task with one label may do to
an object with another label.
- (6) AF_KEY
+ 6. AF_KEY
This is a socket-based approach to credential management for networking
stacks [RFC 2367]. It isn't discussed by this document as it doesn't
@@ -244,25 +224,19 @@ network filesystem where the credentials of the opened file should be presented
to the server, regardless of who is actually doing a read or a write upon it.
-=============
-FILE MARKINGS
+File Markings
=============
Files on disk or obtained over the network may have annotations that form the
objective security context of that file. Depending on the type of filesystem,
this may include one or more of the following:
- (*) UNIX UID, GID, mode;
-
- (*) Windows user ID;
-
- (*) Access control list;
-
- (*) LSM security label;
-
- (*) UNIX exec privilege escalation bits (SUID/SGID);
-
- (*) File capabilities exec privilege escalation bits.
+ * UNIX UID, GID, mode;
+ * Windows user ID;
+ * Access control list;
+ * LSM security label;
+ * UNIX exec privilege escalation bits (SUID/SGID);
+ * File capabilities exec privilege escalation bits.
These are compared to the task's subjective security context, and certain
operations allowed or disallowed as a result. In the case of execve(), the
@@ -270,8 +244,7 @@ privilege escalation bits come into play, and may allow the resulting process
extra privileges, based on the annotations on the executable file.
-================
-TASK CREDENTIALS
+Task Credentials
================
In Linux, all of a task's credentials are held in (uid, gid) or through
@@ -282,20 +255,20 @@ task_struct.
Once a set of credentials has been prepared and committed, it may not be
changed, barring the following exceptions:
- (1) its reference count may be changed;
+ 1. its reference count may be changed;
- (2) the reference count on the group_info struct it points to may be changed;
+ 2. the reference count on the group_info struct it points to may be changed;
- (3) the reference count on the security data it points to may be changed;
+ 3. the reference count on the security data it points to may be changed;
- (4) the reference count on any keyrings it points to may be changed;
+ 4. the reference count on any keyrings it points to may be changed;
- (5) any keyrings it points to may be revoked, expired or have their security
- attributes changed; and
+ 5. any keyrings it points to may be revoked, expired or have their security
+ attributes changed; and
- (6) the contents of any keyrings to which it points may be changed (the whole
- point of keyrings being a shared set of credentials, modifiable by anyone
- with appropriate access).
+ 6. the contents of any keyrings to which it points may be changed (the whole
+ point of keyrings being a shared set of credentials, modifiable by anyone
+ with appropriate access).
To alter anything in the cred struct, the copy-and-replace principle must be
adhered to. First take a copy, then alter the copy and then use RCU to change
@@ -303,37 +276,37 @@ the task pointer to make it point to the new copy. There are wrappers to aid
with this (see below).
A task may only alter its _own_ credentials; it is no longer permitted for a
-task to alter another's credentials. This means the capset() system call is no
-longer permitted to take any PID other than the one of the current process.
-Also keyctl_instantiate() and keyctl_negate() functions no longer permit
-attachment to process-specific keyrings in the requesting process as the
-instantiating process may need to create them.
+task to alter another's credentials. This means the ``capset()`` system call
+is no longer permitted to take any PID other than the one of the current
+process. Also ``keyctl_instantiate()`` and ``keyctl_negate()`` functions no
+longer permit attachment to process-specific keyrings in the requesting
+process as the instantiating process may need to create them.
-IMMUTABLE CREDENTIALS
+Immutable Credentials
---------------------
-Once a set of credentials has been made public (by calling commit_creds() for
-example), it must be considered immutable, barring two exceptions:
+Once a set of credentials has been made public (by calling ``commit_creds()``
+for example), it must be considered immutable, barring two exceptions:
- (1) The reference count may be altered.
+ 1. The reference count may be altered.
- (2) Whilst the keyring subscriptions of a set of credentials may not be
- changed, the keyrings subscribed to may have their contents altered.
+ 2. Whilst the keyring subscriptions of a set of credentials may not be
+ changed, the keyrings subscribed to may have their contents altered.
To catch accidental credential alteration at compile time, struct task_struct
has _const_ pointers to its credential sets, as does struct file. Furthermore,
-certain functions such as get_cred() and put_cred() operate on const pointers,
-thus rendering casts unnecessary, but require to temporarily ditch the const
-qualification to be able to alter the reference count.
+certain functions such as ``get_cred()`` and ``put_cred()`` operate on const
+pointers, thus rendering casts unnecessary, but require to temporarily ditch
+the const qualification to be able to alter the reference count.
-ACCESSING TASK CREDENTIALS
+Accessing Task Credentials
--------------------------
A task being able to alter only its own credentials permits the current process
to read or replace its own credentials without the need for any form of locking
-- which simplifies things greatly. It can just call:
+-- which simplifies things greatly. It can just call::
const struct cred *current_cred()
@@ -341,7 +314,7 @@ to get a pointer to its credentials structure, and it doesn't have to release
it afterwards.
There are convenience wrappers for retrieving specific aspects of a task's
-credentials (the value is simply returned in each case):
+credentials (the value is simply returned in each case)::
uid_t current_uid(void) Current's real UID
gid_t current_gid(void) Current's real GID
@@ -354,7 +327,7 @@ credentials (the value is simply returned in each case):
struct user_struct *current_user(void) Current's user account
There are also convenience wrappers for retrieving specific associated pairs of
-a task's credentials:
+a task's credentials::
void current_uid_gid(uid_t *, gid_t *);
void current_euid_egid(uid_t *, gid_t *);
@@ -365,12 +338,12 @@ them from the current task's credentials.
In addition, there is a function for obtaining a reference on the current
-process's current set of credentials:
+process's current set of credentials::
const struct cred *get_current_cred(void);
and functions for getting references to one of the credentials that don't
-actually live in struct cred:
+actually live in struct cred::
struct user_struct *get_current_user(void);
struct group_info *get_current_groups(void);
@@ -378,22 +351,22 @@ actually live in struct cred:
which get references to the current process's user accounting structure and
supplementary groups list respectively.
-Once a reference has been obtained, it must be released with put_cred(),
-free_uid() or put_group_info() as appropriate.
+Once a reference has been obtained, it must be released with ``put_cred()``,
+``free_uid()`` or ``put_group_info()`` as appropriate.
-ACCESSING ANOTHER TASK'S CREDENTIALS
+Accessing Another Task's Credentials
------------------------------------
Whilst a task may access its own credentials without the need for locking, the
same is not true of a task wanting to access another task's credentials. It
-must use the RCU read lock and rcu_dereference().
+must use the RCU read lock and ``rcu_dereference()``.
-The rcu_dereference() is wrapped by:
+The ``rcu_dereference()`` is wrapped by::
const struct cred *__task_cred(struct task_struct *task);
-This should be used inside the RCU read lock, as in the following example:
+This should be used inside the RCU read lock, as in the following example::
void foo(struct task_struct *t, struct foo_data *f)
{
@@ -410,39 +383,40 @@ This should be used inside the RCU read lock, as in the following example:
Should it be necessary to hold another task's credentials for a long period of
time, and possibly to sleep whilst doing so, then the caller should get a
-reference on them using:
+reference on them using::
const struct cred *get_task_cred(struct task_struct *task);
This does all the RCU magic inside of it. The caller must call put_cred() on
the credentials so obtained when they're finished with.
- [*] Note: The result of __task_cred() should not be passed directly to
- get_cred() as this may race with commit_cred().
+.. note::
+ The result of ``__task_cred()`` should not be passed directly to
+ ``get_cred()`` as this may race with ``commit_cred()``.
There are a couple of convenience functions to access bits of another task's
-credentials, hiding the RCU magic from the caller:
+credentials, hiding the RCU magic from the caller::
uid_t task_uid(task) Task's real UID
uid_t task_euid(task) Task's effective UID
-If the caller is holding the RCU read lock at the time anyway, then:
+If the caller is holding the RCU read lock at the time anyway, then::
__task_cred(task)->uid
__task_cred(task)->euid
should be used instead. Similarly, if multiple aspects of a task's credentials
-need to be accessed, RCU read lock should be used, __task_cred() called, the
-result stored in a temporary pointer and then the credential aspects called
+need to be accessed, RCU read lock should be used, ``__task_cred()`` called,
+the result stored in a temporary pointer and then the credential aspects called
from that before dropping the lock. This prevents the potentially expensive
RCU magic from being invoked multiple times.
Should some other single aspect of another task's credentials need to be
-accessed, then this can be used:
+accessed, then this can be used::
task_cred_xxx(task, member)
-where 'member' is a non-pointer member of the cred struct. For instance:
+where 'member' is a non-pointer member of the cred struct. For instance::
uid_t task_cred_xxx(task, suid);
@@ -451,7 +425,7 @@ magic. This may not be used for pointer members as what they point to may
disappear the moment the RCU read lock is dropped.
-ALTERING CREDENTIALS
+Altering Credentials
--------------------
As previously mentioned, a task may only alter its own credentials, and may not
@@ -459,7 +433,7 @@ alter those of another task. This means that it doesn't need to use any
locking to alter its own credentials.
To alter the current process's credentials, a function should first prepare a
-new set of credentials by calling:
+new set of credentials by calling::
struct cred *prepare_creds(void);
@@ -467,9 +441,10 @@ this locks current->cred_replace_mutex and then allocates and constructs a
duplicate of the current process's credentials, returning with the mutex still
held if successful. It returns NULL if not successful (out of memory).
-The mutex prevents ptrace() from altering the ptrace state of a process whilst
-security checks on credentials construction and changing is taking place as
-the ptrace state may alter the outcome, particularly in the case of execve().
+The mutex prevents ``ptrace()`` from altering the ptrace state of a process
+whilst security checks on credentials construction and changing is taking place
+as the ptrace state may alter the outcome, particularly in the case of
+``execve()``.
The new credentials set should be altered appropriately, and any security
checks and hooks done. Both the current and the proposed sets of credentials
@@ -478,36 +453,37 @@ still at this point.
When the credential set is ready, it should be committed to the current process
-by calling:
+by calling::
int commit_creds(struct cred *new);
This will alter various aspects of the credentials and the process, giving the
-LSM a chance to do likewise, then it will use rcu_assign_pointer() to actually
-commit the new credentials to current->cred, it will release
-current->cred_replace_mutex to allow ptrace() to take place, and it will notify
-the scheduler and others of the changes.
+LSM a chance to do likewise, then it will use ``rcu_assign_pointer()`` to
+actually commit the new credentials to ``current->cred``, it will release
+``current->cred_replace_mutex`` to allow ``ptrace()`` to take place, and it
+will notify the scheduler and others of the changes.
This function is guaranteed to return 0, so that it can be tail-called at the
-end of such functions as sys_setresuid().
+end of such functions as ``sys_setresuid()``.
Note that this function consumes the caller's reference to the new credentials.
-The caller should _not_ call put_cred() on the new credentials afterwards.
+The caller should _not_ call ``put_cred()`` on the new credentials afterwards.
Furthermore, once this function has been called on a new set of credentials,
those credentials may _not_ be changed further.
-Should the security checks fail or some other error occur after prepare_creds()
-has been called, then the following function should be invoked:
+Should the security checks fail or some other error occur after
+``prepare_creds()`` has been called, then the following function should be
+invoked::
void abort_creds(struct cred *new);
-This releases the lock on current->cred_replace_mutex that prepare_creds() got
-and then releases the new credentials.
+This releases the lock on ``current->cred_replace_mutex`` that
+``prepare_creds()`` got and then releases the new credentials.
-A typical credentials alteration function would look something like this:
+A typical credentials alteration function would look something like this::
int alter_suid(uid_t suid)
{
@@ -529,53 +505,50 @@ A typical credentials alteration function would look something like this:
}
-MANAGING CREDENTIALS
+Managing Credentials
--------------------
There are some functions to help manage credentials:
- (*) void put_cred(const struct cred *cred);
+ - ``void put_cred(const struct cred *cred);``
This releases a reference to the given set of credentials. If the
reference count reaches zero, the credentials will be scheduled for
destruction by the RCU system.
- (*) const struct cred *get_cred(const struct cred *cred);
+ - ``const struct cred *get_cred(const struct cred *cred);``
This gets a reference on a live set of credentials, returning a pointer to
that set of credentials.
- (*) struct cred *get_new_cred(struct cred *cred);
+ - ``struct cred *get_new_cred(struct cred *cred);``
This gets a reference on a set of credentials that is under construction
and is thus still mutable, returning a pointer to that set of credentials.
-=====================
-OPEN FILE CREDENTIALS
+Open File Credentials
=====================
When a new file is opened, a reference is obtained on the opening task's
-credentials and this is attached to the file struct as 'f_cred' in place of
-'f_uid' and 'f_gid'. Code that used to access file->f_uid and file->f_gid
-should now access file->f_cred->fsuid and file->f_cred->fsgid.
+credentials and this is attached to the file struct as ``f_cred`` in place of
+``f_uid`` and ``f_gid``. Code that used to access ``file->f_uid`` and
+``file->f_gid`` should now access ``file->f_cred->fsuid`` and
+``file->f_cred->fsgid``.
-It is safe to access f_cred without the use of RCU or locking because the
+It is safe to access ``f_cred`` without the use of RCU or locking because the
pointer will not change over the lifetime of the file struct, and nor will the
contents of the cred struct pointed to, barring the exceptions listed above
(see the Task Credentials section).
-=======================================
-OVERRIDING THE VFS'S USE OF CREDENTIALS
+Overriding the VFS's Use of Credentials
=======================================
Under some circumstances it is desirable to override the credentials used by
-the VFS, and that can be done by calling into such as vfs_mkdir() with a
+the VFS, and that can be done by calling into such as ``vfs_mkdir()`` with a
different set of credentials. This is done in the following places:
- (*) sys_faccessat().
-
- (*) do_coredump().
-
- (*) nfs4recover.c.
+ * ``sys_faccessat()``.
+ * ``do_coredump()``.
+ * nfs4recover.c.
diff --git a/Documentation/security/index.rst b/Documentation/security/index.rst
index 07335659ce8d..415be8e0b013 100644
--- a/Documentation/security/index.rst
+++ b/Documentation/security/index.rst
@@ -5,5 +5,6 @@ Security Documentation
.. toctree::
:maxdepth: 1
+ credentials
IMA-templates
tpm/index
diff --git a/include/linux/cred.h b/include/linux/cred.h
index b03e7d049a64..c728d515e5e2 100644
--- a/include/linux/cred.h
+++ b/include/linux/cred.h
@@ -1,4 +1,4 @@
-/* Credentials management - see Documentation/security/credentials.txt
+/* Credentials management - see Documentation/security/credentials.rst
*
* Copyright (C) 2008 Red Hat, Inc. All Rights Reserved.
* Written by David Howells (dhowells@redhat.com)
diff --git a/kernel/cred.c b/kernel/cred.c
index 2bc66075740f..ecf03657e71c 100644
--- a/kernel/cred.c
+++ b/kernel/cred.c
@@ -1,4 +1,4 @@
-/* Task credentials management - see Documentation/security/credentials.txt
+/* Task credentials management - see Documentation/security/credentials.rst
*
* Copyright (C) 2008 Red Hat, Inc. All Rights Reserved.
* Written by David Howells (dhowells@redhat.com)
--
2.7.4
[toc] | [prev] | [next] | [standalone]
| From | Kees Cook <keescook@chromium.org> |
|---|---|
| Date | 2017-05-13 14:00 +0200 |
| Subject | [PATCH 06/17] doc: security: minor cleanups to build kernel-doc |
| Message-ID | <tGDSj-39c-37@gated-at.bofh.it> |
| In reply to | #1640893 |
These fixes were needed to parse lsm_hooks.h kernel-doc. More work is
needed, but this is the first step.
Cc: Casey Schaufler <casey@schaufler-ca.com>
Signed-off-by: Kees Cook <keescook@chromium.org>
---
include/linux/lsm_hooks.h | 25 ++++++++++++-------------
1 file changed, 12 insertions(+), 13 deletions(-)
diff --git a/include/linux/lsm_hooks.h b/include/linux/lsm_hooks.h
index 080f34e66017..a1eeaf603d2f 100644
--- a/include/linux/lsm_hooks.h
+++ b/include/linux/lsm_hooks.h
@@ -29,6 +29,8 @@
#include <linux/rculist.h>
/**
+ * union security_list_options - Linux Security Module hook function list
+ *
* Security hooks for program execution operations.
*
* @bprm_set_creds:
@@ -193,8 +195,8 @@
* @value will be set to the allocated attribute value.
* @len will be set to the length of the value.
* Returns 0 if @name and @value have been successfully set,
- * -EOPNOTSUPP if no security attribute is needed, or
- * -ENOMEM on memory allocation failure.
+ * -EOPNOTSUPP if no security attribute is needed, or
+ * -ENOMEM on memory allocation failure.
* @inode_create:
* Check permission to create a regular file.
* @dir contains inode structure of the parent of the new file.
@@ -510,8 +512,7 @@
* process @tsk. Note that this hook is sometimes called from interrupt.
* Note that the fown_struct, @fown, is never outside the context of a
* struct file, so the file structure (and associated security information)
- * can always be obtained:
- * container_of(fown, struct file, f_owner)
+ * can always be obtained: container_of(fown, struct file, f_owner)
* @tsk contains the structure of task receiving signal.
* @fown contains the file owner information.
* @sig is the signal that will be sent. When 0, kernel sends SIGIO.
@@ -521,7 +522,7 @@
* to receive an open file descriptor via socket IPC.
* @file contains the file structure being received.
* Return 0 if permission is granted.
- * @file_open
+ * @file_open:
* Save open-time permission checking state for later use upon
* file_permission, and recheck access if anything has changed
* since inode_permission.
@@ -1143,7 +1144,7 @@
* @sma contains the semaphore structure. May be NULL.
* @cmd contains the operation to be performed.
* Return 0 if permission is granted.
- * @sem_semop
+ * @sem_semop:
* Check permissions before performing operations on members of the
* semaphore set @sma. If the @alter flag is nonzero, the semaphore set
* may be modified.
@@ -1153,20 +1154,20 @@
* @alter contains the flag indicating whether changes are to be made.
* Return 0 if permission is granted.
*
- * @binder_set_context_mgr
+ * @binder_set_context_mgr:
* Check whether @mgr is allowed to be the binder context manager.
* @mgr contains the task_struct for the task being registered.
* Return 0 if permission is granted.
- * @binder_transaction
+ * @binder_transaction:
* Check whether @from is allowed to invoke a binder transaction call
* to @to.
* @from contains the task_struct for the sending task.
* @to contains the task_struct for the receiving task.
- * @binder_transfer_binder
+ * @binder_transfer_binder:
* Check whether @from is allowed to transfer a binder reference to @to.
* @from contains the task_struct for the sending task.
* @to contains the task_struct for the receiving task.
- * @binder_transfer_file
+ * @binder_transfer_file:
* Check whether @from is allowed to transfer @file to @to.
* @from contains the task_struct for the sending task.
* @file contains the struct file being transferred.
@@ -1214,7 +1215,7 @@
* @cred contains the credentials to use.
* @ns contains the user namespace we want the capability in
* @cap contains the capability <include/linux/capability.h>.
- * @audit: Whether to write an audit message or not
+ * @audit contains whether to write an audit message or not
* Return 0 if the capability is granted for @tsk.
* @syslog:
* Check permission before accessing the kernel message ring or changing
@@ -1336,9 +1337,7 @@
* @inode we wish to get the security context of.
* @ctx is a pointer in which to place the allocated security context.
* @ctxlen points to the place to put the length of @ctx.
- * This is the main security structure.
*/
-
union security_list_options {
int (*binder_set_context_mgr)(struct task_struct *mgr);
int (*binder_transaction)(struct task_struct *from,
--
2.7.4
[toc] | [prev] | [next] | [standalone]
| From | James Morris <jmorris@namei.org> |
|---|---|
| Date | 2017-05-15 01:20 +0200 |
| Subject | Re: [PATCH 06/17] doc: security: minor cleanups to build kernel-doc |
| Message-ID | <tHaXU-8mK-13@gated-at.bofh.it> |
| In reply to | #1640896 |
On Sat, 13 May 2017, Kees Cook wrote: > These fixes were needed to parse lsm_hooks.h kernel-doc. More work is > needed, but this is the first step. > > Cc: Casey Schaufler <casey@schaufler-ca.com> > Signed-off-by: Kees Cook <keescook@chromium.org> Should these changes go in via the docs tree or mine? In any case: Acked-by: James Morris <james.l.morris@oracle.com> -- James Morris <jmorris@namei.org>
[toc] | [prev] | [next] | [standalone]
| From | Jonathan Corbet <corbet@lwn.net> |
|---|---|
| Date | 2017-05-15 19:30 +0200 |
| Subject | Re: [PATCH 06/17] doc: security: minor cleanups to build kernel-doc |
| Message-ID | <tHrYL-2FM-31@gated-at.bofh.it> |
| In reply to | #1641226 |
On Mon, 15 May 2017 09:17:25 +1000 (AEST) James Morris <jmorris@namei.org> wrote: > On Sat, 13 May 2017, Kees Cook wrote: > > > These fixes were needed to parse lsm_hooks.h kernel-doc. More work is > > needed, but this is the first step. > > > > Cc: Casey Schaufler <casey@schaufler-ca.com> > > Signed-off-by: Kees Cook <keescook@chromium.org> > > Should these changes go in via the docs tree or mine? > > In any case: > Acked-by: James Morris <james.l.morris@oracle.com> These changes are entirely independent from the documentation stuff, so it could really go either way. I'm happy to carry them with the set, if that works for you. Thanks, jon
[toc] | [prev] | [next] | [standalone]
| From | Casey Schaufler <casey@schaufler-ca.com> |
|---|---|
| Date | 2017-05-15 02:10 +0200 |
| Subject | Re: [PATCH 06/17] doc: security: minor cleanups to build kernel-doc |
| Message-ID | <tHbKh-qx-1@gated-at.bofh.it> |
| In reply to | #1640896 |
On 5/13/2017 4:51 AM, Kees Cook wrote:
> These fixes were needed to parse lsm_hooks.h kernel-doc. More work is
> needed, but this is the first step.
>
> Cc: Casey Schaufler <casey@schaufler-ca.com>
> Signed-off-by: Kees Cook <keescook@chromium.org>
Acked_by: Casey Schaufler <casey@schaufler-ca.com>
Tell me more about the additional work that's needed.
> ---
> include/linux/lsm_hooks.h | 25 ++++++++++++-------------
> 1 file changed, 12 insertions(+), 13 deletions(-)
>
> diff --git a/include/linux/lsm_hooks.h b/include/linux/lsm_hooks.h
> index 080f34e66017..a1eeaf603d2f 100644
> --- a/include/linux/lsm_hooks.h
> +++ b/include/linux/lsm_hooks.h
> @@ -29,6 +29,8 @@
> #include <linux/rculist.h>
>
> /**
> + * union security_list_options - Linux Security Module hook function list
> + *
> * Security hooks for program execution operations.
> *
> * @bprm_set_creds:
> @@ -193,8 +195,8 @@
> * @value will be set to the allocated attribute value.
> * @len will be set to the length of the value.
> * Returns 0 if @name and @value have been successfully set,
> - * -EOPNOTSUPP if no security attribute is needed, or
> - * -ENOMEM on memory allocation failure.
> + * -EOPNOTSUPP if no security attribute is needed, or
> + * -ENOMEM on memory allocation failure.
> * @inode_create:
> * Check permission to create a regular file.
> * @dir contains inode structure of the parent of the new file.
> @@ -510,8 +512,7 @@
> * process @tsk. Note that this hook is sometimes called from interrupt.
> * Note that the fown_struct, @fown, is never outside the context of a
> * struct file, so the file structure (and associated security information)
> - * can always be obtained:
> - * container_of(fown, struct file, f_owner)
> + * can always be obtained: container_of(fown, struct file, f_owner)
> * @tsk contains the structure of task receiving signal.
> * @fown contains the file owner information.
> * @sig is the signal that will be sent. When 0, kernel sends SIGIO.
> @@ -521,7 +522,7 @@
> * to receive an open file descriptor via socket IPC.
> * @file contains the file structure being received.
> * Return 0 if permission is granted.
> - * @file_open
> + * @file_open:
> * Save open-time permission checking state for later use upon
> * file_permission, and recheck access if anything has changed
> * since inode_permission.
> @@ -1143,7 +1144,7 @@
> * @sma contains the semaphore structure. May be NULL.
> * @cmd contains the operation to be performed.
> * Return 0 if permission is granted.
> - * @sem_semop
> + * @sem_semop:
> * Check permissions before performing operations on members of the
> * semaphore set @sma. If the @alter flag is nonzero, the semaphore set
> * may be modified.
> @@ -1153,20 +1154,20 @@
> * @alter contains the flag indicating whether changes are to be made.
> * Return 0 if permission is granted.
> *
> - * @binder_set_context_mgr
> + * @binder_set_context_mgr:
> * Check whether @mgr is allowed to be the binder context manager.
> * @mgr contains the task_struct for the task being registered.
> * Return 0 if permission is granted.
> - * @binder_transaction
> + * @binder_transaction:
> * Check whether @from is allowed to invoke a binder transaction call
> * to @to.
> * @from contains the task_struct for the sending task.
> * @to contains the task_struct for the receiving task.
> - * @binder_transfer_binder
> + * @binder_transfer_binder:
> * Check whether @from is allowed to transfer a binder reference to @to.
> * @from contains the task_struct for the sending task.
> * @to contains the task_struct for the receiving task.
> - * @binder_transfer_file
> + * @binder_transfer_file:
> * Check whether @from is allowed to transfer @file to @to.
> * @from contains the task_struct for the sending task.
> * @file contains the struct file being transferred.
> @@ -1214,7 +1215,7 @@
> * @cred contains the credentials to use.
> * @ns contains the user namespace we want the capability in
> * @cap contains the capability <include/linux/capability.h>.
> - * @audit: Whether to write an audit message or not
> + * @audit contains whether to write an audit message or not
> * Return 0 if the capability is granted for @tsk.
> * @syslog:
> * Check permission before accessing the kernel message ring or changing
> @@ -1336,9 +1337,7 @@
> * @inode we wish to get the security context of.
> * @ctx is a pointer in which to place the allocated security context.
> * @ctxlen points to the place to put the length of @ctx.
> - * This is the main security structure.
> */
> -
> union security_list_options {
> int (*binder_set_context_mgr)(struct task_struct *mgr);
> int (*binder_transaction)(struct task_struct *from,
[toc] | [prev] | [next] | [standalone]
| From | Kees Cook <keescook@chromium.org> |
|---|---|
| Date | 2017-05-15 16:50 +0200 |
| Subject | Re: [PATCH 06/17] doc: security: minor cleanups to build kernel-doc |
| Message-ID | <tHptV-XY-29@gated-at.bofh.it> |
| In reply to | #1641229 |
On Sun, May 14, 2017 at 5:00 PM, Casey Schaufler <casey@schaufler-ca.com> wrote:
> On 5/13/2017 4:51 AM, Kees Cook wrote:
>> These fixes were needed to parse lsm_hooks.h kernel-doc. More work is
>> needed, but this is the first step.
>>
>> Cc: Casey Schaufler <casey@schaufler-ca.com>
>> Signed-off-by: Kees Cook <keescook@chromium.org>
>
> Acked_by: Casey Schaufler <casey@schaufler-ca.com>
>
> Tell me more about the additional work that's needed.
What I wanted to do was insert the kernel-doc from lsm_hooks.h into
the LSM kernel API documentation .rst file (via the special ReST
markup that includes structure documentation). There is, however,
free-form text in the existing union security_list_options kernel-doc
to announce related function groups which ReST just kind of skips over
and the collects all at the end in the HTML output. It also orders the
HTML doc output by the struct ordering, which makes things even
stranger to parse. And additionally, kernel-doc for fields that are
function pointers is especially hard to read.
So, while this patch fixes the kernel-doc to at least be parsed
without errors, it doesn't really fix the overall appearance, which
I'm not sure how to fix yet. It might be possible to do per-struct
"/** DOC:" markup, but I decided to leave that for another pass in the
future.
If there is a v2 of this series, I'll update the changelog to include
these details. :)
-Kees
>> ---
>> include/linux/lsm_hooks.h | 25 ++++++++++++-------------
>> 1 file changed, 12 insertions(+), 13 deletions(-)
>>
>> diff --git a/include/linux/lsm_hooks.h b/include/linux/lsm_hooks.h
>> index 080f34e66017..a1eeaf603d2f 100644
>> --- a/include/linux/lsm_hooks.h
>> +++ b/include/linux/lsm_hooks.h
>> @@ -29,6 +29,8 @@
>> #include <linux/rculist.h>
>>
>> /**
>> + * union security_list_options - Linux Security Module hook function list
>> + *
>> * Security hooks for program execution operations.
>> *
>> * @bprm_set_creds:
>> @@ -193,8 +195,8 @@
>> * @value will be set to the allocated attribute value.
>> * @len will be set to the length of the value.
>> * Returns 0 if @name and @value have been successfully set,
>> - * -EOPNOTSUPP if no security attribute is needed, or
>> - * -ENOMEM on memory allocation failure.
>> + * -EOPNOTSUPP if no security attribute is needed, or
>> + * -ENOMEM on memory allocation failure.
>> * @inode_create:
>> * Check permission to create a regular file.
>> * @dir contains inode structure of the parent of the new file.
>> @@ -510,8 +512,7 @@
>> * process @tsk. Note that this hook is sometimes called from interrupt.
>> * Note that the fown_struct, @fown, is never outside the context of a
>> * struct file, so the file structure (and associated security information)
>> - * can always be obtained:
>> - * container_of(fown, struct file, f_owner)
>> + * can always be obtained: container_of(fown, struct file, f_owner)
>> * @tsk contains the structure of task receiving signal.
>> * @fown contains the file owner information.
>> * @sig is the signal that will be sent. When 0, kernel sends SIGIO.
>> @@ -521,7 +522,7 @@
>> * to receive an open file descriptor via socket IPC.
>> * @file contains the file structure being received.
>> * Return 0 if permission is granted.
>> - * @file_open
>> + * @file_open:
>> * Save open-time permission checking state for later use upon
>> * file_permission, and recheck access if anything has changed
>> * since inode_permission.
>> @@ -1143,7 +1144,7 @@
>> * @sma contains the semaphore structure. May be NULL.
>> * @cmd contains the operation to be performed.
>> * Return 0 if permission is granted.
>> - * @sem_semop
>> + * @sem_semop:
>> * Check permissions before performing operations on members of the
>> * semaphore set @sma. If the @alter flag is nonzero, the semaphore set
>> * may be modified.
>> @@ -1153,20 +1154,20 @@
>> * @alter contains the flag indicating whether changes are to be made.
>> * Return 0 if permission is granted.
>> *
>> - * @binder_set_context_mgr
>> + * @binder_set_context_mgr:
>> * Check whether @mgr is allowed to be the binder context manager.
>> * @mgr contains the task_struct for the task being registered.
>> * Return 0 if permission is granted.
>> - * @binder_transaction
>> + * @binder_transaction:
>> * Check whether @from is allowed to invoke a binder transaction call
>> * to @to.
>> * @from contains the task_struct for the sending task.
>> * @to contains the task_struct for the receiving task.
>> - * @binder_transfer_binder
>> + * @binder_transfer_binder:
>> * Check whether @from is allowed to transfer a binder reference to @to.
>> * @from contains the task_struct for the sending task.
>> * @to contains the task_struct for the receiving task.
>> - * @binder_transfer_file
>> + * @binder_transfer_file:
>> * Check whether @from is allowed to transfer @file to @to.
>> * @from contains the task_struct for the sending task.
>> * @file contains the struct file being transferred.
>> @@ -1214,7 +1215,7 @@
>> * @cred contains the credentials to use.
>> * @ns contains the user namespace we want the capability in
>> * @cap contains the capability <include/linux/capability.h>.
>> - * @audit: Whether to write an audit message or not
>> + * @audit contains whether to write an audit message or not
>> * Return 0 if the capability is granted for @tsk.
>> * @syslog:
>> * Check permission before accessing the kernel message ring or changing
>> @@ -1336,9 +1337,7 @@
>> * @inode we wish to get the security context of.
>> * @ctx is a pointer in which to place the allocated security context.
>> * @ctxlen points to the place to put the length of @ctx.
>> - * This is the main security structure.
>> */
>> -
>> union security_list_options {
>> int (*binder_set_context_mgr)(struct task_struct *mgr);
>> int (*binder_transaction)(struct task_struct *from,
>
--
Kees Cook
Pixel Security
[toc] | [prev] | [next] | [standalone]
| From | Kees Cook <keescook@chromium.org> |
|---|---|
| Date | 2017-05-13 14:00 +0200 |
| Subject | [PATCH 12/17] doc: ReSTify LoadPin.txt |
| Message-ID | <tGDSj-39c-29@gated-at.bofh.it> |
| In reply to | #1640893 |
Adjusts for ReST markup and moves under LSM admin guide.
Signed-off-by: Kees Cook <keescook@chromium.org>
---
.../{security/LoadPin.txt => admin-guide/LSM/LoadPin.rst} | 12 ++++++++----
Documentation/admin-guide/LSM/index.rst | 1 +
MAINTAINERS | 1 +
3 files changed, 10 insertions(+), 4 deletions(-)
rename Documentation/{security/LoadPin.txt => admin-guide/LSM/LoadPin.rst} (73%)
diff --git a/Documentation/security/LoadPin.txt b/Documentation/admin-guide/LSM/LoadPin.rst
similarity index 73%
rename from Documentation/security/LoadPin.txt
rename to Documentation/admin-guide/LSM/LoadPin.rst
index e11877f5d3d4..32070762d24c 100644
--- a/Documentation/security/LoadPin.txt
+++ b/Documentation/admin-guide/LSM/LoadPin.rst
@@ -1,3 +1,7 @@
+=======
+LoadPin
+=======
+
LoadPin is a Linux Security Module that ensures all kernel-loaded files
(modules, firmware, etc) all originate from the same filesystem, with
the expectation that such a filesystem is backed by a read-only device
@@ -5,13 +9,13 @@ such as dm-verity or CDROM. This allows systems that have a verified
and/or unchangeable filesystem to enforce module and firmware loading
restrictions without needing to sign the files individually.
-The LSM is selectable at build-time with CONFIG_SECURITY_LOADPIN, and
+The LSM is selectable at build-time with ``CONFIG_SECURITY_LOADPIN``, and
can be controlled at boot-time with the kernel command line option
-"loadpin.enabled". By default, it is enabled, but can be disabled at
-boot ("loadpin.enabled=0").
+"``loadpin.enabled``". By default, it is enabled, but can be disabled at
+boot ("``loadpin.enabled=0``").
LoadPin starts pinning when it sees the first file loaded. If the
block device backing the filesystem is not read-only, a sysctl is
-created to toggle pinning: /proc/sys/kernel/loadpin/enabled. (Having
+created to toggle pinning: ``/proc/sys/kernel/loadpin/enabled``. (Having
a mutable filesystem means pinning is mutable too, but having the
sysctl allows for easy testing on systems with a mutable filesystem.)
diff --git a/Documentation/admin-guide/LSM/index.rst b/Documentation/admin-guide/LSM/index.rst
index e5ba2c69b8ef..41f5262359f9 100644
--- a/Documentation/admin-guide/LSM/index.rst
+++ b/Documentation/admin-guide/LSM/index.rst
@@ -34,6 +34,7 @@ the one "major" module (e.g. SELinux) if there is one configured.
:maxdepth: 1
apparmor
+ LoadPin
SELinux
tomoyo
Yama
diff --git a/MAINTAINERS b/MAINTAINERS
index c72830e888f1..3c1560c75aa6 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -11567,6 +11567,7 @@ M: Kees Cook <keescook@chromium.org>
T: git git://git.kernel.org/pub/scm/linux/kernel/git/kees/linux.git lsm/loadpin
S: Supported
F: security/loadpin/
+F: Documentation/admin-guide/LSM/LoadPin.rst
YAMA SECURITY MODULE
M: Kees Cook <keescook@chromium.org>
--
2.7.4
[toc] | [prev] | [next] | [standalone]
| From | Kees Cook <keescook@chromium.org> |
|---|---|
| Date | 2017-05-13 14:00 +0200 |
| Subject | [PATCH 17/17] doc: ReSTify keys-trusted-encrypted.txt |
| Message-ID | <tGDSj-39c-35@gated-at.bofh.it> |
| In reply to | #1640893 |
Adjusts for ReST markup and moves under keys security devel index.
Cc: David Howells <dhowells@redhat.com>
Cc: Mimi Zohar <zohar@linux.vnet.ibm.com>
Signed-off-by: Kees Cook <keescook@chromium.org>
---
Documentation/security/00-INDEX | 4 ---
Documentation/security/conf.py | 8 ------
Documentation/security/keys/index.rst | 1 +
.../trusted-encrypted.rst} | 32 ++++++++++++++--------
MAINTAINERS | 4 +--
security/keys/encrypted-keys/encrypted.c | 2 +-
security/keys/encrypted-keys/masterkey_trusted.c | 2 +-
security/keys/trusted.c | 2 +-
8 files changed, 26 insertions(+), 29 deletions(-)
delete mode 100644 Documentation/security/00-INDEX
delete mode 100644 Documentation/security/conf.py
rename Documentation/security/{keys-trusted-encrypted.txt => keys/trusted-encrypted.rst} (93%)
diff --git a/Documentation/security/00-INDEX b/Documentation/security/00-INDEX
deleted file mode 100644
index c8dbbc227326..000000000000
--- a/Documentation/security/00-INDEX
+++ /dev/null
@@ -1,4 +0,0 @@
-00-INDEX
- - this file.
-keys-trusted-encrypted.txt
- - info on the Trusted and Encrypted keys in the kernel key ring service.
diff --git a/Documentation/security/conf.py b/Documentation/security/conf.py
deleted file mode 100644
index 472fc9a8eb67..000000000000
--- a/Documentation/security/conf.py
+++ /dev/null
@@ -1,8 +0,0 @@
-project = "The kernel security subsystem manual"
-
-tags.add("subproject")
-
-latex_documents = [
- ('index', 'security.tex', project,
- 'The kernel development community', 'manual'),
-]
diff --git a/Documentation/security/keys/index.rst b/Documentation/security/keys/index.rst
index d7ddbc1c2502..647d58f2588e 100644
--- a/Documentation/security/keys/index.rst
+++ b/Documentation/security/keys/index.rst
@@ -8,3 +8,4 @@ Kernel Keys
core
ecryptfs
request-key
+ trusted-encrypted
diff --git a/Documentation/security/keys-trusted-encrypted.txt b/Documentation/security/keys/trusted-encrypted.rst
similarity index 93%
rename from Documentation/security/keys-trusted-encrypted.txt
rename to Documentation/security/keys/trusted-encrypted.rst
index b20a993a32af..7b503831bdea 100644
--- a/Documentation/security/keys-trusted-encrypted.txt
+++ b/Documentation/security/keys/trusted-encrypted.rst
@@ -1,4 +1,6 @@
- Trusted and Encrypted Keys
+==========================
+Trusted and Encrypted Keys
+==========================
Trusted and Encrypted Keys are two new key types added to the existing kernel
key ring service. Both of these new types are variable length symmetric keys,
@@ -20,7 +22,8 @@ By default, trusted keys are sealed under the SRK, which has the default
authorization value (20 zeros). This can be set at takeownership time with the
trouser's utility: "tpm_takeownership -u -z".
-Usage:
+Usage::
+
keyctl add trusted name "new keylen [options]" ring
keyctl add trusted name "load hex_blob [pcrlock=pcrnum]" ring
keyctl update key "update [options]"
@@ -64,19 +67,22 @@ The decrypted portion of encrypted keys can contain either a simple symmetric
key or a more complex structure. The format of the more complex structure is
application specific, which is identified by 'format'.
-Usage:
+Usage::
+
keyctl add encrypted name "new [format] key-type:master-key-name keylen"
ring
keyctl add encrypted name "load hex_blob" ring
keyctl update keyid "update key-type:master-key-name"
-format:= 'default | ecryptfs'
-key-type:= 'trusted' | 'user'
+Where::
+
+ format:= 'default | ecryptfs'
+ key-type:= 'trusted' | 'user'
Examples of trusted and encrypted key usage:
-Create and save a trusted key named "kmk" of length 32 bytes:
+Create and save a trusted key named "kmk" of length 32 bytes::
$ keyctl add trusted kmk "new 32" @u
440502848
@@ -99,7 +105,7 @@ Create and save a trusted key named "kmk" of length 32 bytes:
$ keyctl pipe 440502848 > kmk.blob
-Load a trusted key from the saved blob:
+Load a trusted key from the saved blob::
$ keyctl add trusted kmk "load `cat kmk.blob`" @u
268728824
@@ -114,7 +120,7 @@ Load a trusted key from the saved blob:
f1f8fff03ad0acb083725535636addb08d73dedb9832da198081e5deae84bfaf0409c22b
e4a8aea2b607ec96931e6f4d4fe563ba
-Reseal a trusted key under new pcr values:
+Reseal a trusted key under new pcr values::
$ keyctl update 268728824 "update pcrinfo=`cat pcr.blob`"
$ keyctl print 268728824
@@ -135,11 +141,13 @@ compromised by a user level problem, and when sealed to specific boot PCR
values, protects against boot and offline attacks. Create and save an
encrypted key "evm" using the above trusted key "kmk":
-option 1: omitting 'format'
+option 1: omitting 'format'::
+
$ keyctl add encrypted evm "new trusted:kmk 32" @u
159771175
-option 2: explicitly defining 'format' as 'default'
+option 2: explicitly defining 'format' as 'default'::
+
$ keyctl add encrypted evm "new default trusted:kmk 32" @u
159771175
@@ -150,7 +158,7 @@ option 2: explicitly defining 'format' as 'default'
$ keyctl pipe 159771175 > evm.blob
-Load an encrypted key "evm" from saved blob:
+Load an encrypted key "evm" from saved blob::
$ keyctl add encrypted evm "load `cat evm.blob`" @u
831684262
@@ -164,4 +172,4 @@ Other uses for trusted and encrypted keys, such as for disk and file encryption
are anticipated. In particular the new format 'ecryptfs' has been defined in
in order to use encrypted keys to mount an eCryptfs filesystem. More details
about the usage can be found in the file
-'Documentation/security/keys-ecryptfs.txt'.
+``Documentation/security/keys-ecryptfs.txt``.
diff --git a/MAINTAINERS b/MAINTAINERS
index 3973e25e5aca..c7674bda49ba 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -7356,7 +7356,7 @@ M: Mimi Zohar <zohar@linux.vnet.ibm.com>
L: linux-security-module@vger.kernel.org
L: keyrings@vger.kernel.org
S: Supported
-F: Documentation/security/keys-trusted-encrypted.txt
+F: Documentation/security/keys/trusted-encrypted.rst
F: include/keys/trusted-type.h
F: security/keys/trusted.c
F: security/keys/trusted.h
@@ -7367,7 +7367,7 @@ M: David Safford <safford@us.ibm.com>
L: linux-security-module@vger.kernel.org
L: keyrings@vger.kernel.org
S: Supported
-F: Documentation/security/keys-trusted-encrypted.txt
+F: Documentation/security/keys/trusted-encrypted.rst
F: include/keys/encrypted-type.h
F: security/keys/encrypted-keys/
diff --git a/security/keys/encrypted-keys/encrypted.c b/security/keys/encrypted-keys/encrypted.c
index 0010955d7876..72ecbd0d1e37 100644
--- a/security/keys/encrypted-keys/encrypted.c
+++ b/security/keys/encrypted-keys/encrypted.c
@@ -11,7 +11,7 @@
* it under the terms of the GNU General Public License as published by
* the Free Software Foundation, version 2 of the License.
*
- * See Documentation/security/keys-trusted-encrypted.txt
+ * See Documentation/security/keys/trusted-encrypted.rst
*/
#include <linux/uaccess.h>
diff --git a/security/keys/encrypted-keys/masterkey_trusted.c b/security/keys/encrypted-keys/masterkey_trusted.c
index b5b4812dbc87..cbf0bc127a73 100644
--- a/security/keys/encrypted-keys/masterkey_trusted.c
+++ b/security/keys/encrypted-keys/masterkey_trusted.c
@@ -11,7 +11,7 @@
* it under the terms of the GNU General Public License as published by
* the Free Software Foundation, version 2 of the License.
*
- * See Documentation/security/keys-trusted-encrypted.txt
+ * See Documentation/security/keys/trusted-encrypted.rst
*/
#include <linux/uaccess.h>
diff --git a/security/keys/trusted.c b/security/keys/trusted.c
index 2ae31c5a87de..3811e75d280f 100644
--- a/security/keys/trusted.c
+++ b/security/keys/trusted.c
@@ -8,7 +8,7 @@
* it under the terms of the GNU General Public License as published by
* the Free Software Foundation, version 2 of the License.
*
- * See Documentation/security/keys-trusted-encrypted.txt
+ * See Documentation/security/keys/trusted-encrypted.rst
*/
#include <crypto/hash_info.h>
--
2.7.4
[toc] | [prev] | [next] | [standalone]
| From | Kees Cook <keescook@chromium.org> |
|---|---|
| Date | 2017-05-13 14:00 +0200 |
| Subject | [PATCH 05/17] doc: ReSTify self-protection.txt |
| Message-ID | <tGDSj-39c-41@gated-at.bofh.it> |
| In reply to | #1640893 |
This updates the credentials API documentation to ReST markup and moves
it under the security subsection of kernel API documentation.
Signed-off-by: Kees Cook <keescook@chromium.org>
---
Documentation/security/index.rst | 1 +
.../{self-protection.txt => self-protection.rst} | 99 ++++++++++++++--------
2 files changed, 64 insertions(+), 36 deletions(-)
rename Documentation/security/{self-protection.txt => self-protection.rst} (83%)
diff --git a/Documentation/security/index.rst b/Documentation/security/index.rst
index 415be8e0b013..4212d7ac58b6 100644
--- a/Documentation/security/index.rst
+++ b/Documentation/security/index.rst
@@ -7,4 +7,5 @@ Security Documentation
credentials
IMA-templates
+ self-protection
tpm/index
diff --git a/Documentation/security/self-protection.txt b/Documentation/security/self-protection.rst
similarity index 83%
rename from Documentation/security/self-protection.txt
rename to Documentation/security/self-protection.rst
index 141acfebe6ef..60c8bd8b77bf 100644
--- a/Documentation/security/self-protection.txt
+++ b/Documentation/security/self-protection.rst
@@ -1,4 +1,6 @@
-# Kernel Self-Protection
+======================
+Kernel Self-Protection
+======================
Kernel self-protection is the design and implementation of systems and
structures within the Linux kernel to protect against security flaws in
@@ -26,7 +28,8 @@ mentioning them, since these aspects need to be explored, dealt with,
and/or accepted.
-## Attack Surface Reduction
+Attack Surface Reduction
+========================
The most fundamental defense against security exploits is to reduce the
areas of the kernel that can be used to redirect execution. This ranges
@@ -34,13 +37,15 @@ from limiting the exposed APIs available to userspace, making in-kernel
APIs hard to use incorrectly, minimizing the areas of writable kernel
memory, etc.
-### Strict kernel memory permissions
+Strict kernel memory permissions
+--------------------------------
When all of kernel memory is writable, it becomes trivial for attacks
to redirect execution flow. To reduce the availability of these targets
the kernel needs to protect its memory with a tight set of permissions.
-#### Executable code and read-only data must not be writable
+Executable code and read-only data must not be writable
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Any areas of the kernel with executable memory must not be writable.
While this obviously includes the kernel text itself, we must consider
@@ -51,18 +56,19 @@ kernel, they are implemented in a way where the memory is temporarily
made writable during the update, and then returned to the original
permissions.)
-In support of this are CONFIG_STRICT_KERNEL_RWX and
-CONFIG_STRICT_MODULE_RWX, which seek to make sure that code is not
+In support of this are ``CONFIG_STRICT_KERNEL_RWX`` and
+``CONFIG_STRICT_MODULE_RWX``, which seek to make sure that code is not
writable, data is not executable, and read-only data is neither writable
nor executable.
Most architectures have these options on by default and not user selectable.
For some architectures like arm that wish to have these be selectable,
the architecture Kconfig can select ARCH_OPTIONAL_KERNEL_RWX to enable
-a Kconfig prompt. CONFIG_ARCH_OPTIONAL_KERNEL_RWX_DEFAULT determines
+a Kconfig prompt. ``CONFIG_ARCH_OPTIONAL_KERNEL_RWX_DEFAULT`` determines
the default setting when ARCH_OPTIONAL_KERNEL_RWX is enabled.
-#### Function pointers and sensitive variables must not be writable
+Function pointers and sensitive variables must not be writable
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Vast areas of kernel memory contain function pointers that are looked
up by the kernel and used to continue execution (e.g. descriptor/vector
@@ -74,8 +80,8 @@ so that they live in the .rodata section instead of the .data section
of the kernel, gaining the protection of the kernel's strict memory
permissions as described above.
-For variables that are initialized once at __init time, these can
-be marked with the (new and under development) __ro_after_init
+For variables that are initialized once at ``__init`` time, these can
+be marked with the (new and under development) ``__ro_after_init``
attribute.
What remains are variables that are updated rarely (e.g. GDT). These
@@ -85,7 +91,8 @@ of their lifetime read-only. (For example, when being updated, only the
CPU thread performing the update would be given uninterruptible write
access to the memory.)
-#### Segregation of kernel memory from userspace memory
+Segregation of kernel memory from userspace memory
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The kernel must never execute userspace memory. The kernel must also never
access userspace memory without explicit expectation to do so. These
@@ -95,10 +102,11 @@ By blocking userspace memory in this way, execution and data parsing
cannot be passed to trivially-controlled userspace memory, forcing
attacks to operate entirely in kernel memory.
-### Reduced access to syscalls
+Reduced access to syscalls
+--------------------------
One trivial way to eliminate many syscalls for 64-bit systems is building
-without CONFIG_COMPAT. However, this is rarely a feasible scenario.
+without ``CONFIG_COMPAT``. However, this is rarely a feasible scenario.
The "seccomp" system provides an opt-in feature made available to
userspace, which provides a way to reduce the number of kernel entry
@@ -112,7 +120,8 @@ to trusted processes. This would keep the scope of kernel entry points
restricted to the more regular set of normally available to unprivileged
userspace.
-### Restricting access to kernel modules
+Restricting access to kernel modules
+------------------------------------
The kernel should never allow an unprivileged user the ability to
load specific kernel modules, since that would provide a facility to
@@ -127,11 +136,12 @@ for debate in some scenarios.)
To protect against even privileged users, systems may need to either
disable module loading entirely (e.g. monolithic kernel builds or
modules_disabled sysctl), or provide signed modules (e.g.
-CONFIG_MODULE_SIG_FORCE, or dm-crypt with LoadPin), to keep from having
+``CONFIG_MODULE_SIG_FORCE``, or dm-crypt with LoadPin), to keep from having
root load arbitrary kernel code via the module loader interface.
-## Memory integrity
+Memory integrity
+================
There are many memory structures in the kernel that are regularly abused
to gain execution control during an attack, By far the most commonly
@@ -139,16 +149,18 @@ understood is that of the stack buffer overflow in which the return
address stored on the stack is overwritten. Many other examples of this
kind of attack exist, and protections exist to defend against them.
-### Stack buffer overflow
+Stack buffer overflow
+---------------------
The classic stack buffer overflow involves writing past the expected end
of a variable stored on the stack, ultimately writing a controlled value
to the stack frame's stored return address. The most widely used defense
is the presence of a stack canary between the stack variables and the
-return address (CONFIG_CC_STACKPROTECTOR), which is verified just before
+return address (``CONFIG_CC_STACKPROTECTOR``), which is verified just before
the function returns. Other defenses include things like shadow stacks.
-### Stack depth overflow
+Stack depth overflow
+--------------------
A less well understood attack is using a bug that triggers the
kernel to consume stack memory with deep function calls or large stack
@@ -158,27 +170,31 @@ important changes need to be made for better protections: moving the
sensitive thread_info structure elsewhere, and adding a faulting memory
hole at the bottom of the stack to catch these overflows.
-### Heap memory integrity
+Heap memory integrity
+---------------------
The structures used to track heap free lists can be sanity-checked during
allocation and freeing to make sure they aren't being used to manipulate
other memory areas.
-### Counter integrity
+Counter integrity
+-----------------
Many places in the kernel use atomic counters to track object references
or perform similar lifetime management. When these counters can be made
to wrap (over or under) this traditionally exposes a use-after-free
flaw. By trapping atomic wrapping, this class of bug vanishes.
-### Size calculation overflow detection
+Size calculation overflow detection
+-----------------------------------
Similar to counter overflow, integer overflows (usually size calculations)
need to be detected at runtime to kill this class of bug, which
traditionally leads to being able to write past the end of kernel buffers.
-## Statistical defenses
+Probabilistic defenses
+======================
While many protections can be considered deterministic (e.g. read-only
memory cannot be written to), some protections provide only statistical
@@ -186,7 +202,8 @@ defense, in that an attack must gather enough information about a
running system to overcome the defense. While not perfect, these do
provide meaningful defenses.
-### Canaries, blinding, and other secrets
+Canaries, blinding, and other secrets
+-------------------------------------
It should be noted that things like the stack canary discussed earlier
are technically statistical defenses, since they rely on a secret value,
@@ -201,7 +218,8 @@ It is critical that the secret values used must be separate (e.g.
different canary per stack) and high entropy (e.g. is the RNG actually
working?) in order to maximize their success.
-### Kernel Address Space Layout Randomization (KASLR)
+Kernel Address Space Layout Randomization (KASLR)
+-------------------------------------------------
Since the location of kernel memory is almost always instrumental in
mounting a successful attack, making the location non-deterministic
@@ -209,22 +227,25 @@ raises the difficulty of an exploit. (Note that this in turn makes
the value of information exposures higher, since they may be used to
discover desired memory locations.)
-#### Text and module base
+Text and module base
+~~~~~~~~~~~~~~~~~~~~
By relocating the physical and virtual base address of the kernel at
-boot-time (CONFIG_RANDOMIZE_BASE), attacks needing kernel code will be
+boot-time (``CONFIG_RANDOMIZE_BASE``), attacks needing kernel code will be
frustrated. Additionally, offsetting the module loading base address
means that even systems that load the same set of modules in the same
order every boot will not share a common base address with the rest of
the kernel text.
-#### Stack base
+Stack base
+~~~~~~~~~~
If the base address of the kernel stack is not the same between processes,
or even not the same between syscalls, targets on or beyond the stack
become more difficult to locate.
-#### Dynamic memory base
+Dynamic memory base
+~~~~~~~~~~~~~~~~~~~
Much of the kernel's dynamic memory (e.g. kmalloc, vmalloc, etc) ends up
being relatively deterministic in layout due to the order of early-boot
@@ -232,7 +253,8 @@ initializations. If the base address of these areas is not the same
between boots, targeting them is frustrated, requiring an information
exposure specific to the region.
-#### Structure layout
+Structure layout
+~~~~~~~~~~~~~~~~
By performing a per-build randomization of the layout of sensitive
structures, attacks must either be tuned to known kernel builds or expose
@@ -240,26 +262,30 @@ enough kernel memory to determine structure layouts before manipulating
them.
-## Preventing Information Exposures
+Preventing Information Exposures
+================================
Since the locations of sensitive structures are the primary target for
attacks, it is important to defend against exposure of both kernel memory
addresses and kernel memory contents (since they may contain kernel
addresses or other sensitive things like canary values).
-### Unique identifiers
+Unique identifiers
+------------------
Kernel memory addresses must never be used as identifiers exposed to
userspace. Instead, use an atomic counter, an idr, or similar unique
identifier.
-### Memory initialization
+Memory initialization
+---------------------
Memory copied to userspace must always be fully initialized. If not
explicitly memset(), this will require changes to the compiler to make
sure structure holes are cleared.
-### Memory poisoning
+Memory poisoning
+----------------
When releasing memory, it is best to poison the contents (clear stack on
syscall return, wipe heap memory on a free), to avoid reuse attacks that
@@ -267,9 +293,10 @@ rely on the old contents of memory. This frustrates many uninitialized
variable attacks, stack content exposures, heap content exposures, and
use-after-free attacks.
-### Destination tracking
+Destination tracking
+--------------------
To help kill classes of bugs that result in kernel addresses being
written to userspace, the destination of writes needs to be tracked. If
-the buffer is destined for userspace (e.g. seq_file backed /proc files),
+the buffer is destined for userspace (e.g. seq_file backed ``/proc`` files),
it should automatically censor sensitive values.
--
2.7.4
[toc] | [prev] | [next] | [standalone]
| From | Kees Cook <keescook@chromium.org> |
|---|---|
| Date | 2017-05-13 14:00 +0200 |
| Subject | [PATCH 03/17] doc: ReSTify IMA-templates.txt |
| Message-ID | <tGDSj-39c-45@gated-at.bofh.it> |
| In reply to | #1640893 |
Adjust IMA-templates.txt for ReST markup and add to the index for
security/, under the Kernel API Documentation.
Cc: Mimi Zohar <zohar@linux.vnet.ibm.com>
Signed-off-by: Kees Cook <keescook@chromium.org>
---
Documentation/security/00-INDEX | 2 -
.../{IMA-templates.txt => IMA-templates.rst} | 46 ++++++++++++----------
Documentation/security/index.rst | 4 +-
3 files changed, 29 insertions(+), 23 deletions(-)
rename Documentation/security/{IMA-templates.txt => IMA-templates.rst} (72%)
diff --git a/Documentation/security/00-INDEX b/Documentation/security/00-INDEX
index 45c82fd3e9d3..414235c1fcfc 100644
--- a/Documentation/security/00-INDEX
+++ b/Documentation/security/00-INDEX
@@ -22,5 +22,3 @@ keys.txt
- description of the kernel key retention service.
tomoyo.txt
- documentation on the TOMOYO Linux Security Module.
-IMA-templates.txt
- - documentation on the template management mechanism for IMA.
diff --git a/Documentation/security/IMA-templates.txt b/Documentation/security/IMA-templates.rst
similarity index 72%
rename from Documentation/security/IMA-templates.txt
rename to Documentation/security/IMA-templates.rst
index 839b5dad9226..2cd0e273cc9a 100644
--- a/Documentation/security/IMA-templates.txt
+++ b/Documentation/security/IMA-templates.rst
@@ -1,9 +1,12 @@
- IMA Template Management Mechanism
+=================================
+IMA Template Management Mechanism
+=================================
-==== INTRODUCTION ====
+Introduction
+============
-The original 'ima' template is fixed length, containing the filedata hash
+The original ``ima`` template is fixed length, containing the filedata hash
and pathname. The filedata hash is limited to 20 bytes (md5/sha1).
The pathname is a null terminated string, limited to 255 characters.
To overcome these limitations and to add additional file metadata, it is
@@ -28,61 +31,64 @@ a new data type, developers define the field identifier and implement
two functions, init() and show(), respectively to generate and display
measurement entries. Defining a new template descriptor requires
specifying the template format (a string of field identifiers separated
-by the '|' character) through the 'ima_template_fmt' kernel command line
+by the ``|`` character) through the ``ima_template_fmt`` kernel command line
parameter. At boot time, IMA initializes the chosen template descriptor
by translating the format into an array of template fields structures taken
from the set of the supported ones.
-After the initialization step, IMA will call ima_alloc_init_template()
+After the initialization step, IMA will call ``ima_alloc_init_template()``
(new function defined within the patches for the new template management
mechanism) to generate a new measurement entry by using the template
descriptor chosen through the kernel configuration or through the newly
-introduced 'ima_template' and 'ima_template_fmt' kernel command line parameters.
+introduced ``ima_template`` and ``ima_template_fmt`` kernel command line parameters.
It is during this phase that the advantages of the new architecture are
clearly shown: the latter function will not contain specific code to handle
-a given template but, instead, it simply calls the init() method of the template
+a given template but, instead, it simply calls the ``init()`` method of the template
fields associated to the chosen template descriptor and store the result
(pointer to allocated data and data length) in the measurement entry structure.
The same mechanism is employed to display measurements entries.
-The functions ima[_ascii]_measurements_show() retrieve, for each entry,
+The functions ``ima[_ascii]_measurements_show()`` retrieve, for each entry,
the template descriptor used to produce that entry and call the show()
method for each item of the array of template fields structures.
-==== SUPPORTED TEMPLATE FIELDS AND DESCRIPTORS ====
+Supported Template Fields and Descriptors
+=========================================
In the following, there is the list of supported template fields
-('<identifier>': description), that can be used to define new template
+``('<identifier>': description)``, that can be used to define new template
descriptors by adding their identifier to the format string
(support for more data types will be added later):
- 'd': the digest of the event (i.e. the digest of a measured file),
- calculated with the SHA1 or MD5 hash algorithm;
+ calculated with the SHA1 or MD5 hash algorithm;
- 'n': the name of the event (i.e. the file name), with size up to 255 bytes;
- 'd-ng': the digest of the event, calculated with an arbitrary hash
- algorithm (field format: [<hash algo>:]digest, where the digest
- prefix is shown only if the hash algorithm is not SHA1 or MD5);
+ algorithm (field format: [<hash algo>:]digest, where the digest
+ prefix is shown only if the hash algorithm is not SHA1 or MD5);
- 'n-ng': the name of the event, without size limitations;
- 'sig': the file signature.
Below, there is the list of defined template descriptors:
- - "ima": its format is 'd|n';
- - "ima-ng" (default): its format is 'd-ng|n-ng';
- - "ima-sig": its format is 'd-ng|n-ng|sig'.
+ - "ima": its format is ``d|n``;
+ - "ima-ng" (default): its format is ``d-ng|n-ng``;
+ - "ima-sig": its format is ``d-ng|n-ng|sig``.
-==== USE ====
+
+Use
+===
To specify the template descriptor to be used to generate measurement entries,
currently the following methods are supported:
- select a template descriptor among those supported in the kernel
- configuration ('ima-ng' is the default choice);
+ configuration (``ima-ng`` is the default choice);
- specify a template descriptor name from the kernel command line through
- the 'ima_template=' parameter;
+ the ``ima_template=`` parameter;
- register a new template descriptor with custom format through the kernel
- command line parameter 'ima_template_fmt='.
+ command line parameter ``ima_template_fmt=``.
diff --git a/Documentation/security/index.rst b/Documentation/security/index.rst
index 9bae6bb20e7f..07335659ce8d 100644
--- a/Documentation/security/index.rst
+++ b/Documentation/security/index.rst
@@ -1,7 +1,9 @@
======================
-Security documentation
+Security Documentation
======================
.. toctree::
+ :maxdepth: 1
+ IMA-templates
tpm/index
--
2.7.4
[toc] | [prev] | [next] | [standalone]
| From | Kees Cook <keescook@chromium.org> |
|---|---|
| Date | 2017-05-13 14:00 +0200 |
| Subject | [PATCH 02/17] doc: ReSTify no_new_privs.txt |
| Message-ID | <tGDSj-39c-47@gated-at.bofh.it> |
| In reply to | #1640893 |
This updates no_new_privs documentation to ReST markup and adds it to
the user-space API documentation.
Signed-off-by: Kees Cook <keescook@chromium.org>
---
Documentation/userspace-api/index.rst | 1 +
.../no_new_privs.rst} | 44 ++++++++++++----------
2 files changed, 26 insertions(+), 19 deletions(-)
rename Documentation/{prctl/no_new_privs.txt => userspace-api/no_new_privs.rst} (54%)
diff --git a/Documentation/userspace-api/index.rst b/Documentation/userspace-api/index.rst
index 15ff12342db8..7b2eb1b7d4ca 100644
--- a/Documentation/userspace-api/index.rst
+++ b/Documentation/userspace-api/index.rst
@@ -16,6 +16,7 @@ place where this information is gathered.
.. toctree::
:maxdepth: 2
+ no_new_privs
seccomp_filter
unshare
diff --git a/Documentation/prctl/no_new_privs.txt b/Documentation/userspace-api/no_new_privs.rst
similarity index 54%
rename from Documentation/prctl/no_new_privs.txt
rename to Documentation/userspace-api/no_new_privs.rst
index f7be84fba910..d060ea217ea1 100644
--- a/Documentation/prctl/no_new_privs.txt
+++ b/Documentation/userspace-api/no_new_privs.rst
@@ -1,3 +1,7 @@
+======================
+No New Privileges Flag
+======================
+
The execve system call can grant a newly-started program privileges that
its parent did not have. The most obvious examples are setuid/setgid
programs and file capabilities. To prevent the parent program from
@@ -5,53 +9,55 @@ gaining these privileges as well, the kernel and user code must be
careful to prevent the parent from doing anything that could subvert the
child. For example:
- - The dynamic loader handles LD_* environment variables differently if
+ - The dynamic loader handles ``LD_*`` environment variables differently if
a program is setuid.
- chroot is disallowed to unprivileged processes, since it would allow
- /etc/passwd to be replaced from the point of view of a process that
+ ``/etc/passwd`` to be replaced from the point of view of a process that
inherited chroot.
- The exec code has special handling for ptrace.
-These are all ad-hoc fixes. The no_new_privs bit (since Linux 3.5) is a
+These are all ad-hoc fixes. The ``no_new_privs`` bit (since Linux 3.5) is a
new, generic mechanism to make it safe for a process to modify its
execution environment in a manner that persists across execve. Any task
-can set no_new_privs. Once the bit is set, it is inherited across fork,
-clone, and execve and cannot be unset. With no_new_privs set, execve
+can set ``no_new_privs``. Once the bit is set, it is inherited across fork,
+clone, and execve and cannot be unset. With ``no_new_privs`` set, ``execve()``
promises not to grant the privilege to do anything that could not have
been done without the execve call. For example, the setuid and setgid
bits will no longer change the uid or gid; file capabilities will not
add to the permitted set, and LSMs will not relax constraints after
execve.
-To set no_new_privs, use prctl(PR_SET_NO_NEW_PRIVS, 1, 0, 0, 0).
+To set ``no_new_privs``, use::
+
+ prctl(PR_SET_NO_NEW_PRIVS, 1, 0, 0, 0);
Be careful, though: LSMs might also not tighten constraints on exec
-in no_new_privs mode. (This means that setting up a general-purpose
-service launcher to set no_new_privs before execing daemons may
+in ``no_new_privs`` mode. (This means that setting up a general-purpose
+service launcher to set ``no_new_privs`` before execing daemons may
interfere with LSM-based sandboxing.)
-Note that no_new_privs does not prevent privilege changes that do not
-involve execve. An appropriately privileged task can still call
-setuid(2) and receive SCM_RIGHTS datagrams.
+Note that ``no_new_privs`` does not prevent privilege changes that do not
+involve ``execve()``. An appropriately privileged task can still call
+``setuid(2)`` and receive SCM_RIGHTS datagrams.
-There are two main use cases for no_new_privs so far:
+There are two main use cases for ``no_new_privs`` so far:
- Filters installed for the seccomp mode 2 sandbox persist across
execve and can change the behavior of newly-executed programs.
Unprivileged users are therefore only allowed to install such filters
- if no_new_privs is set.
+ if ``no_new_privs`` is set.
- - By itself, no_new_privs can be used to reduce the attack surface
+ - By itself, ``no_new_privs`` can be used to reduce the attack surface
available to an unprivileged user. If everything running with a
- given uid has no_new_privs set, then that uid will be unable to
+ given uid has ``no_new_privs`` set, then that uid will be unable to
escalate its privileges by directly attacking setuid, setgid, and
fcap-using binaries; it will need to compromise something without the
- no_new_privs bit set first.
+ ``no_new_privs`` bit set first.
In the future, other potentially dangerous kernel features could become
-available to unprivileged tasks if no_new_privs is set. In principle,
-several options to unshare(2) and clone(2) would be safe when
-no_new_privs is set, and no_new_privs + chroot is considerable less
+available to unprivileged tasks if ``no_new_privs`` is set. In principle,
+several options to ``unshare(2)`` and ``clone(2)`` would be safe when
+``no_new_privs`` is set, and ``no_new_privs`` + ``chroot`` is considerable less
dangerous than chroot by itself.
--
2.7.4
[toc] | [prev] | [next] | [standalone]
| From | Kees Cook <keescook@chromium.org> |
|---|---|
| Date | 2017-05-13 14:00 +0200 |
| Subject | [PATCH 13/17] doc: ReSTify Smack.txt |
| Message-ID | <tGDSj-39c-43@gated-at.bofh.it> |
| In reply to | #1640893 |
Adjusts for ReST markup and moves under LSM admin guide.
Cc: Casey Schaufler <casey@schaufler-ca.com>
Signed-off-by: Kees Cook <keescook@chromium.org>
---
.../Smack.txt => admin-guide/LSM/Smack.rst} | 273 ++++++++++++++-------
Documentation/admin-guide/LSM/index.rst | 1 +
Documentation/security/00-INDEX | 2 -
MAINTAINERS | 2 +-
4 files changed, 191 insertions(+), 87 deletions(-)
rename Documentation/{security/Smack.txt => admin-guide/LSM/Smack.rst} (85%)
diff --git a/Documentation/security/Smack.txt b/Documentation/admin-guide/LSM/Smack.rst
similarity index 85%
rename from Documentation/security/Smack.txt
rename to Documentation/admin-guide/LSM/Smack.rst
index 945cc633d883..6a5826a13aea 100644
--- a/Documentation/security/Smack.txt
+++ b/Documentation/admin-guide/LSM/Smack.rst
@@ -1,3 +1,6 @@
+=====
+Smack
+=====
"Good for you, you've decided to clean the elevator!"
@@ -14,6 +17,7 @@ available to determine which is best suited to the problem
at hand.
Smack consists of three major components:
+
- The kernel
- Basic utilities, which are helpful but not required
- Configuration data
@@ -39,16 +43,24 @@ The current git repository for Smack user space is:
This should make and install on most modern distributions.
There are five commands included in smackutil:
-chsmack - display or set Smack extended attribute values
-smackctl - load the Smack access rules
-smackaccess - report if a process with one label has access
- to an object with another
+chsmack:
+ display or set Smack extended attribute values
+
+smackctl:
+ load the Smack access rules
+
+smackaccess:
+ report if a process with one label has access
+ to an object with another
These two commands are obsolete with the introduction of
the smackfs/load2 and smackfs/cipso2 interfaces.
-smackload - properly formats data for writing to smackfs/load
-smackcipso - properly formats data for writing to smackfs/cipso
+smackload:
+ properly formats data for writing to smackfs/load
+
+smackcipso:
+ properly formats data for writing to smackfs/cipso
In keeping with the intent of Smack, configuration data is
minimal and not strictly required. The most important
@@ -56,15 +68,15 @@ configuration step is mounting the smackfs pseudo filesystem.
If smackutil is installed the startup script will take care
of this, but it can be manually as well.
-Add this line to /etc/fstab:
+Add this line to ``/etc/fstab``::
smackfs /sys/fs/smackfs smackfs defaults 0 0
-The /sys/fs/smackfs directory is created by the kernel.
+The ``/sys/fs/smackfs`` directory is created by the kernel.
Smack uses extended attributes (xattrs) to store labels on filesystem
objects. The attributes are stored in the extended attribute security
-name space. A process must have CAP_MAC_ADMIN to change any of these
+name space. A process must have ``CAP_MAC_ADMIN`` to change any of these
attributes.
The extended attributes that Smack uses are:
@@ -73,14 +85,17 @@ SMACK64
Used to make access control decisions. In almost all cases
the label given to a new filesystem object will be the label
of the process that created it.
+
SMACK64EXEC
The Smack label of a process that execs a program file with
this attribute set will run with this attribute's value.
+
SMACK64MMAP
Don't allow the file to be mmapped by a process whose Smack
label does not allow all of the access permitted to a process
with the label contained in this attribute. This is a very
specific use case for shared libraries.
+
SMACK64TRANSMUTE
Can only have the value "TRUE". If this attribute is present
on a directory when an object is created in the directory and
@@ -89,27 +104,29 @@ SMACK64TRANSMUTE
gets the label of the directory instead of the label of the
creating process. If the object being created is a directory
the SMACK64TRANSMUTE attribute is set as well.
+
SMACK64IPIN
This attribute is only available on file descriptors for sockets.
Use the Smack label in this attribute for access control
decisions on packets being delivered to this socket.
+
SMACK64IPOUT
This attribute is only available on file descriptors for sockets.
Use the Smack label in this attribute for access control
decisions on packets coming from this socket.
-There are multiple ways to set a Smack label on a file:
+There are multiple ways to set a Smack label on a file::
# attr -S -s SMACK64 -V "value" path
# chsmack -a value path
A process can see the Smack label it is running with by
-reading /proc/self/attr/current. A process with CAP_MAC_ADMIN
+reading ``/proc/self/attr/current``. A process with ``CAP_MAC_ADMIN``
can set the process Smack by writing there.
Most Smack configuration is accomplished by writing to files
in the smackfs filesystem. This pseudo-filesystem is mounted
-on /sys/fs/smackfs.
+on ``/sys/fs/smackfs``.
access
Provided for backward compatibility. The access2 interface
@@ -120,6 +137,7 @@ access
this file. The next read will indicate whether the access
would be permitted. The text will be either "1" indicating
access, or "0" indicating denial.
+
access2
This interface reports whether a subject with the specified
Smack label has a particular access to an object with a
@@ -127,13 +145,17 @@ access2
this file. The next read will indicate whether the access
would be permitted. The text will be either "1" indicating
access, or "0" indicating denial.
+
ambient
This contains the Smack label applied to unlabeled network
packets.
+
change-rule
This interface allows modification of existing access control rules.
- The format accepted on write is:
+ The format accepted on write is::
+
"%s %s %s %s"
+
where the first string is the subject label, the second the
object label, the third the access to allow and the fourth the
access to deny. The access strings may contain only the characters
@@ -141,47 +163,63 @@ change-rule
modified by enabling the permissions in the third string and disabling
those in the fourth string. If there is no such rule it will be
created using the access specified in the third and the fourth strings.
+
cipso
Provided for backward compatibility. The cipso2 interface
is preferred and should be used instead.
This interface allows a specific CIPSO header to be assigned
- to a Smack label. The format accepted on write is:
+ to a Smack label. The format accepted on write is::
+
"%24s%4d%4d"["%4d"]...
+
The first string is a fixed Smack label. The first number is
the level to use. The second number is the number of categories.
- The following numbers are the categories.
- "level-3-cats-5-19 3 2 5 19"
+ The following numbers are the categories::
+
+ "level-3-cats-5-19 3 2 5 19"
+
cipso2
This interface allows a specific CIPSO header to be assigned
- to a Smack label. The format accepted on write is:
- "%s%4d%4d"["%4d"]...
+ to a Smack label. The format accepted on write is::
+
+ "%s%4d%4d"["%4d"]...
+
The first string is a long Smack label. The first number is
the level to use. The second number is the number of categories.
- The following numbers are the categories.
- "level-3-cats-5-19 3 2 5 19"
+ The following numbers are the categories::
+
+ "level-3-cats-5-19 3 2 5 19"
+
direct
This contains the CIPSO level used for Smack direct label
representation in network packets.
+
doi
This contains the CIPSO domain of interpretation used in
network packets.
+
ipv6host
This interface allows specific IPv6 internet addresses to be
treated as single label hosts. Packets are sent to single
label hosts only from processes that have Smack write access
to the host label. All packets received from single label hosts
- are given the specified label. The format accepted on write is:
+ are given the specified label. The format accepted on write is::
+
"%h:%h:%h:%h:%h:%h:%h:%h label" or
"%h:%h:%h:%h:%h:%h:%h:%h/%d label".
+
The "::" address shortcut is not supported.
If label is "-DELETE" a matched entry will be deleted.
+
load
Provided for backward compatibility. The load2 interface
is preferred and should be used instead.
This interface allows access control rules in addition to
the system defined rules to be specified. The format accepted
- on write is:
+ on write is::
+
"%24s%24s%5s"
+
where the first string is the subject label, the second the
object label, and the third the requested access. The access
string may contain only the characters "rwxat-", and specifies
@@ -189,17 +227,21 @@ load
permissions that are not allowed. The string "r-x--" would
specify read and execute access. Labels are limited to 23
characters in length.
+
load2
This interface allows access control rules in addition to
the system defined rules to be specified. The format accepted
- on write is:
+ on write is::
+
"%s %s %s"
+
where the first string is the subject label, the second the
object label, and the third the requested access. The access
string may contain only the characters "rwxat-", and specifies
which sort of access is allowed. The "-" is a placeholder for
permissions that are not allowed. The string "r-x--" would
specify read and execute access.
+
load-self
Provided for backward compatibility. The load-self2 interface
is preferred and should be used instead.
@@ -208,66 +250,83 @@ load-self
otherwise be permitted, and are intended to provide additional
restrictions on the process. The format is the same as for
the load interface.
+
load-self2
This interface allows process specific access rules to be
defined. These rules are only consulted if access would
otherwise be permitted, and are intended to provide additional
restrictions on the process. The format is the same as for
the load2 interface.
+
logging
This contains the Smack logging state.
+
mapped
This contains the CIPSO level used for Smack mapped label
representation in network packets.
+
netlabel
This interface allows specific internet addresses to be
treated as single label hosts. Packets are sent to single
label hosts without CIPSO headers, but only from processes
that have Smack write access to the host label. All packets
received from single label hosts are given the specified
- label. The format accepted on write is:
+ label. The format accepted on write is::
+
"%d.%d.%d.%d label" or "%d.%d.%d.%d/%d label".
+
If the label specified is "-CIPSO" the address is treated
as a host that supports CIPSO headers.
+
onlycap
This contains labels processes must have for CAP_MAC_ADMIN
- and CAP_MAC_OVERRIDE to be effective. If this file is empty
+ and ``CAP_MAC_OVERRIDE`` to be effective. If this file is empty
these capabilities are effective at for processes with any
label. The values are set by writing the desired labels, separated
by spaces, to the file or cleared by writing "-" to the file.
+
ptrace
This is used to define the current ptrace policy
- 0 - default: this is the policy that relies on Smack access rules.
- For the PTRACE_READ a subject needs to have a read access on
- object. For the PTRACE_ATTACH a read-write access is required.
- 1 - exact: this is the policy that limits PTRACE_ATTACH. Attach is
+
+ 0 - default:
+ this is the policy that relies on Smack access rules.
+ For the ``PTRACE_READ`` a subject needs to have a read access on
+ object. For the ``PTRACE_ATTACH`` a read-write access is required.
+
+ 1 - exact:
+ this is the policy that limits ``PTRACE_ATTACH``. Attach is
only allowed when subject's and object's labels are equal.
- PTRACE_READ is not affected. Can be overridden with CAP_SYS_PTRACE.
- 2 - draconian: this policy behaves like the 'exact' above with an
- exception that it can't be overridden with CAP_SYS_PTRACE.
+ ``PTRACE_READ`` is not affected. Can be overridden with ``CAP_SYS_PTRACE``.
+
+ 2 - draconian:
+ this policy behaves like the 'exact' above with an
+ exception that it can't be overridden with ``CAP_SYS_PTRACE``.
+
revoke-subject
Writing a Smack label here sets the access to '-' for all access
rules with that subject label.
+
unconfined
- If the kernel is configured with CONFIG_SECURITY_SMACK_BRINGUP
- a process with CAP_MAC_ADMIN can write a label into this interface.
+ If the kernel is configured with ``CONFIG_SECURITY_SMACK_BRINGUP``
+ a process with ``CAP_MAC_ADMIN`` can write a label into this interface.
Thereafter, accesses that involve that label will be logged and
the access permitted if it wouldn't be otherwise. Note that this
is dangerous and can ruin the proper labeling of your system.
It should never be used in production.
+
relabel-self
This interface contains a list of labels to which the process can
- transition to, by writing to /proc/self/attr/current.
+ transition to, by writing to ``/proc/self/attr/current``.
Normally a process can change its own label to any legal value, but only
- if it has CAP_MAC_ADMIN. This interface allows a process without
- CAP_MAC_ADMIN to relabel itself to one of labels from predefined list.
- A process without CAP_MAC_ADMIN can change its label only once. When it
+ if it has ``CAP_MAC_ADMIN``. This interface allows a process without
+ ``CAP_MAC_ADMIN`` to relabel itself to one of labels from predefined list.
+ A process without ``CAP_MAC_ADMIN`` can change its label only once. When it
does, this list will be cleared.
The values are set by writing the desired labels, separated
by spaces, to the file or cleared by writing "-" to the file.
If you are using the smackload utility
-you can add access rules in /etc/smack/accesses. They take the form:
+you can add access rules in ``/etc/smack/accesses``. They take the form::
subjectlabel objectlabel access
@@ -277,14 +336,14 @@ object with objectlabel. If there is no rule no access is allowed.
Look for additional programs on http://schaufler-ca.com
-From the Smack Whitepaper:
-
-The Simplified Mandatory Access Control Kernel
+The Simplified Mandatory Access Control Kernel (Whitepaper)
+===========================================================
Casey Schaufler
casey@schaufler-ca.com
Mandatory Access Control
+------------------------
Computer systems employ a variety of schemes to constrain how information is
shared among the people and services using the machine. Some of these schemes
@@ -297,6 +356,7 @@ access control mechanisms because you don't have a choice regarding the users
or programs that have access to pieces of data.
Bell & LaPadula
+---------------
From the middle of the 1980's until the turn of the century Mandatory Access
Control (MAC) was very closely associated with the Bell & LaPadula security
@@ -306,6 +366,7 @@ within the Capital Beltway and Scandinavian supercomputer centers but was
often sited as failing to address general needs.
Domain Type Enforcement
+-----------------------
Around the turn of the century Domain Type Enforcement (DTE) became popular.
This scheme organizes users, programs, and data into domains that are
@@ -316,6 +377,7 @@ necessary to provide a secure domain mapping leads to the scheme being
disabled or used in limited ways in the majority of cases.
Smack
+-----
Smack is a Mandatory Access Control mechanism designed to provide useful MAC
while avoiding the pitfalls of its predecessors. The limitations of Bell &
@@ -326,46 +388,55 @@ Enforcement and avoided by defining access controls in terms of the access
modes already in use.
Smack Terminology
+-----------------
The jargon used to talk about Smack will be familiar to those who have dealt
with other MAC systems and shouldn't be too difficult for the uninitiated to
pick up. There are four terms that are used in a specific way and that are
especially important:
- Subject: A subject is an active entity on the computer system.
+ Subject:
+ A subject is an active entity on the computer system.
On Smack a subject is a task, which is in turn the basic unit
of execution.
- Object: An object is a passive entity on the computer system.
+ Object:
+ An object is a passive entity on the computer system.
On Smack files of all types, IPC, and tasks can be objects.
- Access: Any attempt by a subject to put information into or get
+ Access:
+ Any attempt by a subject to put information into or get
information from an object is an access.
- Label: Data that identifies the Mandatory Access Control
+ Label:
+ Data that identifies the Mandatory Access Control
characteristics of a subject or an object.
These definitions are consistent with the traditional use in the security
community. There are also some terms from Linux that are likely to crop up:
- Capability: A task that possesses a capability has permission to
+ Capability:
+ A task that possesses a capability has permission to
violate an aspect of the system security policy, as identified by
the specific capability. A task that possesses one or more
capabilities is a privileged task, whereas a task with no
capabilities is an unprivileged task.
- Privilege: A task that is allowed to violate the system security
+ Privilege:
+ A task that is allowed to violate the system security
policy is said to have privilege. As of this writing a task can
have privilege either by possessing capabilities or by having an
effective user of root.
Smack Basics
+------------
Smack is an extension to a Linux system. It enforces additional restrictions
on what subjects can access which objects, based on the labels attached to
each of the subject and the object.
Labels
+~~~~~~
Smack labels are ASCII character strings. They can be up to 255 characters
long, but keeping them to twenty-three characters is recommended.
@@ -377,7 +448,7 @@ contain unprintable characters, the "/" (slash), the "\" (backslash), the "'"
(quote) and '"' (double-quote) characters.
Smack labels cannot begin with a '-'. This is reserved for special options.
-There are some predefined labels:
+There are some predefined labels::
_ Pronounced "floor", a single underscore character.
^ Pronounced "hat", a single circumflex character.
@@ -390,14 +461,18 @@ of a process will usually be assigned by the system initialization
mechanism.
Access Rules
+~~~~~~~~~~~~
Smack uses the traditional access modes of Linux. These modes are read,
execute, write, and occasionally append. There are a few cases where the
access mode may not be obvious. These include:
- Signals: A signal is a write operation from the subject task to
+ Signals:
+ A signal is a write operation from the subject task to
the object task.
- Internet Domain IPC: Transmission of a packet is considered a
+
+ Internet Domain IPC:
+ Transmission of a packet is considered a
write operation from the source task to the destination task.
Smack restricts access based on the label attached to a subject and the label
@@ -417,6 +492,7 @@ order:
7. Any other access is denied.
Smack Access Rules
+~~~~~~~~~~~~~~~~~~
With the isolation provided by Smack access separation is simple. There are
many interesting cases where limited access by subjects to objects with
@@ -427,8 +503,9 @@ be "born" highly classified. To accommodate such schemes Smack includes a
mechanism for specifying rules allowing access between labels.
Access Rule Format
+~~~~~~~~~~~~~~~~~~
-The format of an access rule is:
+The format of an access rule is::
subject-label object-label access
@@ -446,7 +523,7 @@ describe access modes:
Uppercase values for the specification letters are allowed as well.
Access mode specifications can be in any order. Examples of acceptable rules
-are:
+are::
TopSecret Secret rx
Secret Unclass R
@@ -456,7 +533,7 @@ are:
New Old rRrRr
Closed Off -
-Examples of unacceptable rules are:
+Examples of unacceptable rules are::
Top Secret Secret rx
Ace Ace r
@@ -469,6 +546,7 @@ access specifications. The dash is a placeholder, so "a-r" is the same
as "ar". A lone dash is used to specify that no access should be allowed.
Applying Access Rules
+~~~~~~~~~~~~~~~~~~~~~
The developers of Linux rarely define new sorts of things, usually importing
schemes and concepts from other systems. Most often, the other systems are
@@ -511,6 +589,7 @@ one process to another requires that the sender have write access to the
receiver. The receiver is not required to have read access to the sender.
Setting Access Rules
+~~~~~~~~~~~~~~~~~~~~
The configuration file /etc/smack/accesses contains the rules to be set at
system startup. The contents are written to the special file
@@ -520,6 +599,7 @@ one rule, with the most recently specified overriding any earlier
specification.
Task Attribute
+~~~~~~~~~~~~~~
The Smack label of a process can be read from /proc/<pid>/attr/current. A
process can read its own Smack label from /proc/self/attr/current. A
@@ -527,12 +607,14 @@ privileged process can change its own Smack label by writing to
/proc/self/attr/current but not the label of another process.
File Attribute
+~~~~~~~~~~~~~~
The Smack label of a filesystem object is stored as an extended attribute
named SMACK64 on the file. This attribute is in the security namespace. It can
only be changed by a process with privilege.
Privilege
+~~~~~~~~~
A process with CAP_MAC_OVERRIDE or CAP_MAC_ADMIN is privileged.
CAP_MAC_OVERRIDE allows the process access to objects it would
@@ -540,6 +622,7 @@ be denied otherwise. CAP_MAC_ADMIN allows a process to change
Smack data, including rules and attributes.
Smack Networking
+~~~~~~~~~~~~~~~~
As mentioned before, Smack enforces access control on network protocol
transmissions. Every packet sent by a Smack process is tagged with its Smack
@@ -551,6 +634,7 @@ packet has write access to the receiving process and if that is not the case
the packet is dropped.
CIPSO Configuration
+~~~~~~~~~~~~~~~~~~~
It is normally unnecessary to specify the CIPSO configuration. The default
values used by the system handle all internal cases. Smack will compose CIPSO
@@ -571,13 +655,13 @@ discarded. The DOI is 3 by default. The value can be read from
The label and category set are mapped to a Smack label as defined in
/etc/smack/cipso.
-A Smack/CIPSO mapping has the form:
+A Smack/CIPSO mapping has the form::
smack level [category [category]*]
Smack does not expect the level or category sets to be related in any
particular way and does not assume or assign accesses based on them. Some
-examples of mappings:
+examples of mappings::
TopSecret 7
TS:A,B 7 1 2
@@ -597,25 +681,30 @@ value can be read from /sys/fs/smackfs/direct and changed by writing to
/sys/fs/smackfs/direct.
Socket Attributes
+~~~~~~~~~~~~~~~~~
There are two attributes that are associated with sockets. These attributes
can only be set by privileged tasks, but any task can read them for their own
sockets.
- SMACK64IPIN: The Smack label of the task object. A privileged
+ SMACK64IPIN:
+ The Smack label of the task object. A privileged
program that will enforce policy may set this to the star label.
- SMACK64IPOUT: The Smack label transmitted with outgoing packets.
+ SMACK64IPOUT:
+ The Smack label transmitted with outgoing packets.
A privileged program may set this to match the label of another
task with which it hopes to communicate.
Smack Netlabel Exceptions
+~~~~~~~~~~~~~~~~~~~~~~~~~
You will often find that your labeled application has to talk to the outside,
unlabeled world. To do this there's a special file /sys/fs/smackfs/netlabel
-where you can add some exceptions in the form of :
-@IP1 LABEL1 or
-@IP2/MASK LABEL2
+where you can add some exceptions in the form of::
+
+ @IP1 LABEL1 or
+ @IP2/MASK LABEL2
It means that your application will have unlabeled access to @IP1 if it has
write access on LABEL1, and access to the subnet @IP2/MASK if it has write
@@ -624,28 +713,32 @@ access on LABEL2.
Entries in the /sys/fs/smackfs/netlabel file are matched by longest mask
first, like in classless IPv4 routing.
-A special label '@' and an option '-CIPSO' can be used there :
-@ means Internet, any application with any label has access to it
--CIPSO means standard CIPSO networking
+A special label '@' and an option '-CIPSO' can be used there::
-If you don't know what CIPSO is and don't plan to use it, you can just do :
-echo 127.0.0.1 -CIPSO > /sys/fs/smackfs/netlabel
-echo 0.0.0.0/0 @ > /sys/fs/smackfs/netlabel
+ @ means Internet, any application with any label has access to it
+ -CIPSO means standard CIPSO networking
+
+If you don't know what CIPSO is and don't plan to use it, you can just do::
+
+ echo 127.0.0.1 -CIPSO > /sys/fs/smackfs/netlabel
+ echo 0.0.0.0/0 @ > /sys/fs/smackfs/netlabel
If you use CIPSO on your 192.168.0.0/16 local network and need also unlabeled
-Internet access, you can have :
-echo 127.0.0.1 -CIPSO > /sys/fs/smackfs/netlabel
-echo 192.168.0.0/16 -CIPSO > /sys/fs/smackfs/netlabel
-echo 0.0.0.0/0 @ > /sys/fs/smackfs/netlabel
+Internet access, you can have::
+ echo 127.0.0.1 -CIPSO > /sys/fs/smackfs/netlabel
+ echo 192.168.0.0/16 -CIPSO > /sys/fs/smackfs/netlabel
+ echo 0.0.0.0/0 @ > /sys/fs/smackfs/netlabel
Writing Applications for Smack
+------------------------------
There are three sorts of applications that will run on a Smack system. How an
application interacts with Smack will determine what it will have to do to
work properly under Smack.
Smack Ignorant Applications
+---------------------------
By far the majority of applications have no reason whatever to care about the
unique properties of Smack. Since invoking a program has no impact on the
@@ -653,12 +746,14 @@ Smack label associated with the process the only concern likely to arise is
whether the process has execute access to the program.
Smack Relevant Applications
+---------------------------
Some programs can be improved by teaching them about Smack, but do not make
any security decisions themselves. The utility ls(1) is one example of such a
program.
Smack Enforcing Applications
+----------------------------
These are special programs that not only know about Smack, but participate in
the enforcement of system policy. In most cases these are the programs that
@@ -666,15 +761,16 @@ set up user sessions. There are also network services that provide information
to processes running with various labels.
File System Interfaces
+----------------------
Smack maintains labels on file system objects using extended attributes. The
Smack label of a file, directory, or other file system object can be obtained
-using getxattr(2).
+using getxattr(2)::
len = getxattr("/", "security.SMACK64", value, sizeof (value));
will put the Smack label of the root directory into value. A privileged
-process can set the Smack label of a file system object with setxattr(2).
+process can set the Smack label of a file system object with setxattr(2)::
len = strlen("Rubble");
rc = setxattr("/foo", "security.SMACK64", "Rubble", len, 0);
@@ -683,17 +779,18 @@ will set the Smack label of /foo to "Rubble" if the program has appropriate
privilege.
Socket Interfaces
+-----------------
The socket attributes can be read using fgetxattr(2).
A privileged process can set the Smack label of outgoing packets with
-fsetxattr(2).
+fsetxattr(2)::
len = strlen("Rubble");
rc = fsetxattr(fd, "security.SMACK64IPOUT", "Rubble", len, 0);
will set the Smack label "Rubble" on packets going out from the socket if the
-program has appropriate privilege.
+program has appropriate privilege::
rc = fsetxattr(fd, "security.SMACK64IPIN, "*", strlen("*"), 0);
@@ -701,33 +798,40 @@ will set the Smack label "*" as the object label against which incoming
packets will be checked if the program has appropriate privilege.
Administration
+--------------
Smack supports some mount options:
- smackfsdef=label: specifies the label to give files that lack
+ smackfsdef=label:
+ specifies the label to give files that lack
the Smack label extended attribute.
- smackfsroot=label: specifies the label to assign the root of the
+ smackfsroot=label:
+ specifies the label to assign the root of the
file system if it lacks the Smack extended attribute.
- smackfshat=label: specifies a label that must have read access to
+ smackfshat=label:
+ specifies a label that must have read access to
all labels set on the filesystem. Not yet enforced.
- smackfsfloor=label: specifies a label to which all labels set on the
+ smackfsfloor=label:
+ specifies a label to which all labels set on the
filesystem must have read access. Not yet enforced.
These mount options apply to all file system types.
Smack auditing
+--------------
If you want Smack auditing of security events, you need to set CONFIG_AUDIT
in your kernel configuration.
By default, all denied events will be audited. You can change this behavior by
-writing a single character to the /sys/fs/smackfs/logging file :
-0 : no logging
-1 : log denied (default)
-2 : log accepted
-3 : log denied & accepted
+writing a single character to the /sys/fs/smackfs/logging file::
+
+ 0 : no logging
+ 1 : log denied (default)
+ 2 : log accepted
+ 3 : log denied & accepted
Events are logged as 'key=value' pairs, for each event you at least will get
the subject, the object, the rights requested, the action, the kernel function
@@ -735,6 +839,7 @@ that triggered the event, plus other pairs depending on the type of event
audited.
Bringup Mode
+------------
Bringup mode provides logging features that can make application
configuration and system bringup easier. Configure the kernel with
diff --git a/Documentation/admin-guide/LSM/index.rst b/Documentation/admin-guide/LSM/index.rst
index 41f5262359f9..c980dfe9abf1 100644
--- a/Documentation/admin-guide/LSM/index.rst
+++ b/Documentation/admin-guide/LSM/index.rst
@@ -36,5 +36,6 @@ the one "major" module (e.g. SELinux) if there is one configured.
apparmor
LoadPin
SELinux
+ Smack
tomoyo
Yama
diff --git a/Documentation/security/00-INDEX b/Documentation/security/00-INDEX
index a55f781be0dd..cdb2294ec047 100644
--- a/Documentation/security/00-INDEX
+++ b/Documentation/security/00-INDEX
@@ -1,7 +1,5 @@
00-INDEX
- this file.
-Smack.txt
- - documentation on the Smack Linux Security Module.
keys-ecryptfs.txt
- description of the encryption keys for the ecryptfs filesystem.
keys-request-key.txt
diff --git a/MAINTAINERS b/MAINTAINERS
index 3c1560c75aa6..3e78b5c9b3f9 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -11876,7 +11876,7 @@ L: linux-security-module@vger.kernel.org
W: http://schaufler-ca.com
T: git git://github.com/cschaufler/smack-next
S: Maintained
-F: Documentation/security/Smack.txt
+F: Documentation/admin-guide/LSM/Smack.rst
F: security/smack/
DRIVERS FOR ADAPTIVE VOLTAGE SCALING (AVS)
--
2.7.4
[toc] | [prev] | [next] | [standalone]
| From | Casey Schaufler <casey@schaufler-ca.com> |
|---|---|
| Date | 2017-05-15 16:20 +0200 |
| Subject | Re: [PATCH 13/17] doc: ReSTify Smack.txt |
| Message-ID | <tHp0R-O3-15@gated-at.bofh.it> |
| In reply to | #1640902 |
On 5/13/2017 4:51 AM, Kees Cook wrote:
> Adjusts for ReST markup and moves under LSM admin guide.
>
> Cc: Casey Schaufler <casey@schaufler-ca.com>
> Signed-off-by: Kees Cook <keescook@chromium.org>
Acked-by: Casey Schaufler <casey@schaufler-ca.com>
Thank you.
> ---
> .../Smack.txt => admin-guide/LSM/Smack.rst} | 273 ++++++++++++++-------
> Documentation/admin-guide/LSM/index.rst | 1 +
> Documentation/security/00-INDEX | 2 -
> MAINTAINERS | 2 +-
> 4 files changed, 191 insertions(+), 87 deletions(-)
> rename Documentation/{security/Smack.txt => admin-guide/LSM/Smack.rst} (85%)
>
> diff --git a/Documentation/security/Smack.txt b/Documentation/admin-guide/LSM/Smack.rst
> similarity index 85%
> rename from Documentation/security/Smack.txt
> rename to Documentation/admin-guide/LSM/Smack.rst
> index 945cc633d883..6a5826a13aea 100644
> --- a/Documentation/security/Smack.txt
> +++ b/Documentation/admin-guide/LSM/Smack.rst
> @@ -1,3 +1,6 @@
> +=====
> +Smack
> +=====
>
>
> "Good for you, you've decided to clean the elevator!"
> @@ -14,6 +17,7 @@ available to determine which is best suited to the problem
> at hand.
>
> Smack consists of three major components:
> +
> - The kernel
> - Basic utilities, which are helpful but not required
> - Configuration data
> @@ -39,16 +43,24 @@ The current git repository for Smack user space is:
> This should make and install on most modern distributions.
> There are five commands included in smackutil:
>
> -chsmack - display or set Smack extended attribute values
> -smackctl - load the Smack access rules
> -smackaccess - report if a process with one label has access
> - to an object with another
> +chsmack:
> + display or set Smack extended attribute values
> +
> +smackctl:
> + load the Smack access rules
> +
> +smackaccess:
> + report if a process with one label has access
> + to an object with another
>
> These two commands are obsolete with the introduction of
> the smackfs/load2 and smackfs/cipso2 interfaces.
>
> -smackload - properly formats data for writing to smackfs/load
> -smackcipso - properly formats data for writing to smackfs/cipso
> +smackload:
> + properly formats data for writing to smackfs/load
> +
> +smackcipso:
> + properly formats data for writing to smackfs/cipso
>
> In keeping with the intent of Smack, configuration data is
> minimal and not strictly required. The most important
> @@ -56,15 +68,15 @@ configuration step is mounting the smackfs pseudo filesystem.
> If smackutil is installed the startup script will take care
> of this, but it can be manually as well.
>
> -Add this line to /etc/fstab:
> +Add this line to ``/etc/fstab``::
>
> smackfs /sys/fs/smackfs smackfs defaults 0 0
>
> -The /sys/fs/smackfs directory is created by the kernel.
> +The ``/sys/fs/smackfs`` directory is created by the kernel.
>
> Smack uses extended attributes (xattrs) to store labels on filesystem
> objects. The attributes are stored in the extended attribute security
> -name space. A process must have CAP_MAC_ADMIN to change any of these
> +name space. A process must have ``CAP_MAC_ADMIN`` to change any of these
> attributes.
>
> The extended attributes that Smack uses are:
> @@ -73,14 +85,17 @@ SMACK64
> Used to make access control decisions. In almost all cases
> the label given to a new filesystem object will be the label
> of the process that created it.
> +
> SMACK64EXEC
> The Smack label of a process that execs a program file with
> this attribute set will run with this attribute's value.
> +
> SMACK64MMAP
> Don't allow the file to be mmapped by a process whose Smack
> label does not allow all of the access permitted to a process
> with the label contained in this attribute. This is a very
> specific use case for shared libraries.
> +
> SMACK64TRANSMUTE
> Can only have the value "TRUE". If this attribute is present
> on a directory when an object is created in the directory and
> @@ -89,27 +104,29 @@ SMACK64TRANSMUTE
> gets the label of the directory instead of the label of the
> creating process. If the object being created is a directory
> the SMACK64TRANSMUTE attribute is set as well.
> +
> SMACK64IPIN
> This attribute is only available on file descriptors for sockets.
> Use the Smack label in this attribute for access control
> decisions on packets being delivered to this socket.
> +
> SMACK64IPOUT
> This attribute is only available on file descriptors for sockets.
> Use the Smack label in this attribute for access control
> decisions on packets coming from this socket.
>
> -There are multiple ways to set a Smack label on a file:
> +There are multiple ways to set a Smack label on a file::
>
> # attr -S -s SMACK64 -V "value" path
> # chsmack -a value path
>
> A process can see the Smack label it is running with by
> -reading /proc/self/attr/current. A process with CAP_MAC_ADMIN
> +reading ``/proc/self/attr/current``. A process with ``CAP_MAC_ADMIN``
> can set the process Smack by writing there.
>
> Most Smack configuration is accomplished by writing to files
> in the smackfs filesystem. This pseudo-filesystem is mounted
> -on /sys/fs/smackfs.
> +on ``/sys/fs/smackfs``.
>
> access
> Provided for backward compatibility. The access2 interface
> @@ -120,6 +137,7 @@ access
> this file. The next read will indicate whether the access
> would be permitted. The text will be either "1" indicating
> access, or "0" indicating denial.
> +
> access2
> This interface reports whether a subject with the specified
> Smack label has a particular access to an object with a
> @@ -127,13 +145,17 @@ access2
> this file. The next read will indicate whether the access
> would be permitted. The text will be either "1" indicating
> access, or "0" indicating denial.
> +
> ambient
> This contains the Smack label applied to unlabeled network
> packets.
> +
> change-rule
> This interface allows modification of existing access control rules.
> - The format accepted on write is:
> + The format accepted on write is::
> +
> "%s %s %s %s"
> +
> where the first string is the subject label, the second the
> object label, the third the access to allow and the fourth the
> access to deny. The access strings may contain only the characters
> @@ -141,47 +163,63 @@ change-rule
> modified by enabling the permissions in the third string and disabling
> those in the fourth string. If there is no such rule it will be
> created using the access specified in the third and the fourth strings.
> +
> cipso
> Provided for backward compatibility. The cipso2 interface
> is preferred and should be used instead.
> This interface allows a specific CIPSO header to be assigned
> - to a Smack label. The format accepted on write is:
> + to a Smack label. The format accepted on write is::
> +
> "%24s%4d%4d"["%4d"]...
> +
> The first string is a fixed Smack label. The first number is
> the level to use. The second number is the number of categories.
> - The following numbers are the categories.
> - "level-3-cats-5-19 3 2 5 19"
> + The following numbers are the categories::
> +
> + "level-3-cats-5-19 3 2 5 19"
> +
> cipso2
> This interface allows a specific CIPSO header to be assigned
> - to a Smack label. The format accepted on write is:
> - "%s%4d%4d"["%4d"]...
> + to a Smack label. The format accepted on write is::
> +
> + "%s%4d%4d"["%4d"]...
> +
> The first string is a long Smack label. The first number is
> the level to use. The second number is the number of categories.
> - The following numbers are the categories.
> - "level-3-cats-5-19 3 2 5 19"
> + The following numbers are the categories::
> +
> + "level-3-cats-5-19 3 2 5 19"
> +
> direct
> This contains the CIPSO level used for Smack direct label
> representation in network packets.
> +
> doi
> This contains the CIPSO domain of interpretation used in
> network packets.
> +
> ipv6host
> This interface allows specific IPv6 internet addresses to be
> treated as single label hosts. Packets are sent to single
> label hosts only from processes that have Smack write access
> to the host label. All packets received from single label hosts
> - are given the specified label. The format accepted on write is:
> + are given the specified label. The format accepted on write is::
> +
> "%h:%h:%h:%h:%h:%h:%h:%h label" or
> "%h:%h:%h:%h:%h:%h:%h:%h/%d label".
> +
> The "::" address shortcut is not supported.
> If label is "-DELETE" a matched entry will be deleted.
> +
> load
> Provided for backward compatibility. The load2 interface
> is preferred and should be used instead.
> This interface allows access control rules in addition to
> the system defined rules to be specified. The format accepted
> - on write is:
> + on write is::
> +
> "%24s%24s%5s"
> +
> where the first string is the subject label, the second the
> object label, and the third the requested access. The access
> string may contain only the characters "rwxat-", and specifies
> @@ -189,17 +227,21 @@ load
> permissions that are not allowed. The string "r-x--" would
> specify read and execute access. Labels are limited to 23
> characters in length.
> +
> load2
> This interface allows access control rules in addition to
> the system defined rules to be specified. The format accepted
> - on write is:
> + on write is::
> +
> "%s %s %s"
> +
> where the first string is the subject label, the second the
> object label, and the third the requested access. The access
> string may contain only the characters "rwxat-", and specifies
> which sort of access is allowed. The "-" is a placeholder for
> permissions that are not allowed. The string "r-x--" would
> specify read and execute access.
> +
> load-self
> Provided for backward compatibility. The load-self2 interface
> is preferred and should be used instead.
> @@ -208,66 +250,83 @@ load-self
> otherwise be permitted, and are intended to provide additional
> restrictions on the process. The format is the same as for
> the load interface.
> +
> load-self2
> This interface allows process specific access rules to be
> defined. These rules are only consulted if access would
> otherwise be permitted, and are intended to provide additional
> restrictions on the process. The format is the same as for
> the load2 interface.
> +
> logging
> This contains the Smack logging state.
> +
> mapped
> This contains the CIPSO level used for Smack mapped label
> representation in network packets.
> +
> netlabel
> This interface allows specific internet addresses to be
> treated as single label hosts. Packets are sent to single
> label hosts without CIPSO headers, but only from processes
> that have Smack write access to the host label. All packets
> received from single label hosts are given the specified
> - label. The format accepted on write is:
> + label. The format accepted on write is::
> +
> "%d.%d.%d.%d label" or "%d.%d.%d.%d/%d label".
> +
> If the label specified is "-CIPSO" the address is treated
> as a host that supports CIPSO headers.
> +
> onlycap
> This contains labels processes must have for CAP_MAC_ADMIN
> - and CAP_MAC_OVERRIDE to be effective. If this file is empty
> + and ``CAP_MAC_OVERRIDE`` to be effective. If this file is empty
> these capabilities are effective at for processes with any
> label. The values are set by writing the desired labels, separated
> by spaces, to the file or cleared by writing "-" to the file.
> +
> ptrace
> This is used to define the current ptrace policy
> - 0 - default: this is the policy that relies on Smack access rules.
> - For the PTRACE_READ a subject needs to have a read access on
> - object. For the PTRACE_ATTACH a read-write access is required.
> - 1 - exact: this is the policy that limits PTRACE_ATTACH. Attach is
> +
> + 0 - default:
> + this is the policy that relies on Smack access rules.
> + For the ``PTRACE_READ`` a subject needs to have a read access on
> + object. For the ``PTRACE_ATTACH`` a read-write access is required.
> +
> + 1 - exact:
> + this is the policy that limits ``PTRACE_ATTACH``. Attach is
> only allowed when subject's and object's labels are equal.
> - PTRACE_READ is not affected. Can be overridden with CAP_SYS_PTRACE.
> - 2 - draconian: this policy behaves like the 'exact' above with an
> - exception that it can't be overridden with CAP_SYS_PTRACE.
> + ``PTRACE_READ`` is not affected. Can be overridden with ``CAP_SYS_PTRACE``.
> +
> + 2 - draconian:
> + this policy behaves like the 'exact' above with an
> + exception that it can't be overridden with ``CAP_SYS_PTRACE``.
> +
> revoke-subject
> Writing a Smack label here sets the access to '-' for all access
> rules with that subject label.
> +
> unconfined
> - If the kernel is configured with CONFIG_SECURITY_SMACK_BRINGUP
> - a process with CAP_MAC_ADMIN can write a label into this interface.
> + If the kernel is configured with ``CONFIG_SECURITY_SMACK_BRINGUP``
> + a process with ``CAP_MAC_ADMIN`` can write a label into this interface.
> Thereafter, accesses that involve that label will be logged and
> the access permitted if it wouldn't be otherwise. Note that this
> is dangerous and can ruin the proper labeling of your system.
> It should never be used in production.
> +
> relabel-self
> This interface contains a list of labels to which the process can
> - transition to, by writing to /proc/self/attr/current.
> + transition to, by writing to ``/proc/self/attr/current``.
> Normally a process can change its own label to any legal value, but only
> - if it has CAP_MAC_ADMIN. This interface allows a process without
> - CAP_MAC_ADMIN to relabel itself to one of labels from predefined list.
> - A process without CAP_MAC_ADMIN can change its label only once. When it
> + if it has ``CAP_MAC_ADMIN``. This interface allows a process without
> + ``CAP_MAC_ADMIN`` to relabel itself to one of labels from predefined list.
> + A process without ``CAP_MAC_ADMIN`` can change its label only once. When it
> does, this list will be cleared.
> The values are set by writing the desired labels, separated
> by spaces, to the file or cleared by writing "-" to the file.
>
> If you are using the smackload utility
> -you can add access rules in /etc/smack/accesses. They take the form:
> +you can add access rules in ``/etc/smack/accesses``. They take the form::
>
> subjectlabel objectlabel access
>
> @@ -277,14 +336,14 @@ object with objectlabel. If there is no rule no access is allowed.
>
> Look for additional programs on http://schaufler-ca.com
>
> -From the Smack Whitepaper:
> -
> -The Simplified Mandatory Access Control Kernel
> +The Simplified Mandatory Access Control Kernel (Whitepaper)
> +===========================================================
>
> Casey Schaufler
> casey@schaufler-ca.com
>
> Mandatory Access Control
> +------------------------
>
> Computer systems employ a variety of schemes to constrain how information is
> shared among the people and services using the machine. Some of these schemes
> @@ -297,6 +356,7 @@ access control mechanisms because you don't have a choice regarding the users
> or programs that have access to pieces of data.
>
> Bell & LaPadula
> +---------------
>
> From the middle of the 1980's until the turn of the century Mandatory Access
> Control (MAC) was very closely associated with the Bell & LaPadula security
> @@ -306,6 +366,7 @@ within the Capital Beltway and Scandinavian supercomputer centers but was
> often sited as failing to address general needs.
>
> Domain Type Enforcement
> +-----------------------
>
> Around the turn of the century Domain Type Enforcement (DTE) became popular.
> This scheme organizes users, programs, and data into domains that are
> @@ -316,6 +377,7 @@ necessary to provide a secure domain mapping leads to the scheme being
> disabled or used in limited ways in the majority of cases.
>
> Smack
> +-----
>
> Smack is a Mandatory Access Control mechanism designed to provide useful MAC
> while avoiding the pitfalls of its predecessors. The limitations of Bell &
> @@ -326,46 +388,55 @@ Enforcement and avoided by defining access controls in terms of the access
> modes already in use.
>
> Smack Terminology
> +-----------------
>
> The jargon used to talk about Smack will be familiar to those who have dealt
> with other MAC systems and shouldn't be too difficult for the uninitiated to
> pick up. There are four terms that are used in a specific way and that are
> especially important:
>
> - Subject: A subject is an active entity on the computer system.
> + Subject:
> + A subject is an active entity on the computer system.
> On Smack a subject is a task, which is in turn the basic unit
> of execution.
>
> - Object: An object is a passive entity on the computer system.
> + Object:
> + An object is a passive entity on the computer system.
> On Smack files of all types, IPC, and tasks can be objects.
>
> - Access: Any attempt by a subject to put information into or get
> + Access:
> + Any attempt by a subject to put information into or get
> information from an object is an access.
>
> - Label: Data that identifies the Mandatory Access Control
> + Label:
> + Data that identifies the Mandatory Access Control
> characteristics of a subject or an object.
>
> These definitions are consistent with the traditional use in the security
> community. There are also some terms from Linux that are likely to crop up:
>
> - Capability: A task that possesses a capability has permission to
> + Capability:
> + A task that possesses a capability has permission to
> violate an aspect of the system security policy, as identified by
> the specific capability. A task that possesses one or more
> capabilities is a privileged task, whereas a task with no
> capabilities is an unprivileged task.
>
> - Privilege: A task that is allowed to violate the system security
> + Privilege:
> + A task that is allowed to violate the system security
> policy is said to have privilege. As of this writing a task can
> have privilege either by possessing capabilities or by having an
> effective user of root.
>
> Smack Basics
> +------------
>
> Smack is an extension to a Linux system. It enforces additional restrictions
> on what subjects can access which objects, based on the labels attached to
> each of the subject and the object.
>
> Labels
> +~~~~~~
>
> Smack labels are ASCII character strings. They can be up to 255 characters
> long, but keeping them to twenty-three characters is recommended.
> @@ -377,7 +448,7 @@ contain unprintable characters, the "/" (slash), the "\" (backslash), the "'"
> (quote) and '"' (double-quote) characters.
> Smack labels cannot begin with a '-'. This is reserved for special options.
>
> -There are some predefined labels:
> +There are some predefined labels::
>
> _ Pronounced "floor", a single underscore character.
> ^ Pronounced "hat", a single circumflex character.
> @@ -390,14 +461,18 @@ of a process will usually be assigned by the system initialization
> mechanism.
>
> Access Rules
> +~~~~~~~~~~~~
>
> Smack uses the traditional access modes of Linux. These modes are read,
> execute, write, and occasionally append. There are a few cases where the
> access mode may not be obvious. These include:
>
> - Signals: A signal is a write operation from the subject task to
> + Signals:
> + A signal is a write operation from the subject task to
> the object task.
> - Internet Domain IPC: Transmission of a packet is considered a
> +
> + Internet Domain IPC:
> + Transmission of a packet is considered a
> write operation from the source task to the destination task.
>
> Smack restricts access based on the label attached to a subject and the label
> @@ -417,6 +492,7 @@ order:
> 7. Any other access is denied.
>
> Smack Access Rules
> +~~~~~~~~~~~~~~~~~~
>
> With the isolation provided by Smack access separation is simple. There are
> many interesting cases where limited access by subjects to objects with
> @@ -427,8 +503,9 @@ be "born" highly classified. To accommodate such schemes Smack includes a
> mechanism for specifying rules allowing access between labels.
>
> Access Rule Format
> +~~~~~~~~~~~~~~~~~~
>
> -The format of an access rule is:
> +The format of an access rule is::
>
> subject-label object-label access
>
> @@ -446,7 +523,7 @@ describe access modes:
>
> Uppercase values for the specification letters are allowed as well.
> Access mode specifications can be in any order. Examples of acceptable rules
> -are:
> +are::
>
> TopSecret Secret rx
> Secret Unclass R
> @@ -456,7 +533,7 @@ are:
> New Old rRrRr
> Closed Off -
>
> -Examples of unacceptable rules are:
> +Examples of unacceptable rules are::
>
> Top Secret Secret rx
> Ace Ace r
> @@ -469,6 +546,7 @@ access specifications. The dash is a placeholder, so "a-r" is the same
> as "ar". A lone dash is used to specify that no access should be allowed.
>
> Applying Access Rules
> +~~~~~~~~~~~~~~~~~~~~~
>
> The developers of Linux rarely define new sorts of things, usually importing
> schemes and concepts from other systems. Most often, the other systems are
> @@ -511,6 +589,7 @@ one process to another requires that the sender have write access to the
> receiver. The receiver is not required to have read access to the sender.
>
> Setting Access Rules
> +~~~~~~~~~~~~~~~~~~~~
>
> The configuration file /etc/smack/accesses contains the rules to be set at
> system startup. The contents are written to the special file
> @@ -520,6 +599,7 @@ one rule, with the most recently specified overriding any earlier
> specification.
>
> Task Attribute
> +~~~~~~~~~~~~~~
>
> The Smack label of a process can be read from /proc/<pid>/attr/current. A
> process can read its own Smack label from /proc/self/attr/current. A
> @@ -527,12 +607,14 @@ privileged process can change its own Smack label by writing to
> /proc/self/attr/current but not the label of another process.
>
> File Attribute
> +~~~~~~~~~~~~~~
>
> The Smack label of a filesystem object is stored as an extended attribute
> named SMACK64 on the file. This attribute is in the security namespace. It can
> only be changed by a process with privilege.
>
> Privilege
> +~~~~~~~~~
>
> A process with CAP_MAC_OVERRIDE or CAP_MAC_ADMIN is privileged.
> CAP_MAC_OVERRIDE allows the process access to objects it would
> @@ -540,6 +622,7 @@ be denied otherwise. CAP_MAC_ADMIN allows a process to change
> Smack data, including rules and attributes.
>
> Smack Networking
> +~~~~~~~~~~~~~~~~
>
> As mentioned before, Smack enforces access control on network protocol
> transmissions. Every packet sent by a Smack process is tagged with its Smack
> @@ -551,6 +634,7 @@ packet has write access to the receiving process and if that is not the case
> the packet is dropped.
>
> CIPSO Configuration
> +~~~~~~~~~~~~~~~~~~~
>
> It is normally unnecessary to specify the CIPSO configuration. The default
> values used by the system handle all internal cases. Smack will compose CIPSO
> @@ -571,13 +655,13 @@ discarded. The DOI is 3 by default. The value can be read from
> The label and category set are mapped to a Smack label as defined in
> /etc/smack/cipso.
>
> -A Smack/CIPSO mapping has the form:
> +A Smack/CIPSO mapping has the form::
>
> smack level [category [category]*]
>
> Smack does not expect the level or category sets to be related in any
> particular way and does not assume or assign accesses based on them. Some
> -examples of mappings:
> +examples of mappings::
>
> TopSecret 7
> TS:A,B 7 1 2
> @@ -597,25 +681,30 @@ value can be read from /sys/fs/smackfs/direct and changed by writing to
> /sys/fs/smackfs/direct.
>
> Socket Attributes
> +~~~~~~~~~~~~~~~~~
>
> There are two attributes that are associated with sockets. These attributes
> can only be set by privileged tasks, but any task can read them for their own
> sockets.
>
> - SMACK64IPIN: The Smack label of the task object. A privileged
> + SMACK64IPIN:
> + The Smack label of the task object. A privileged
> program that will enforce policy may set this to the star label.
>
> - SMACK64IPOUT: The Smack label transmitted with outgoing packets.
> + SMACK64IPOUT:
> + The Smack label transmitted with outgoing packets.
> A privileged program may set this to match the label of another
> task with which it hopes to communicate.
>
> Smack Netlabel Exceptions
> +~~~~~~~~~~~~~~~~~~~~~~~~~
>
> You will often find that your labeled application has to talk to the outside,
> unlabeled world. To do this there's a special file /sys/fs/smackfs/netlabel
> -where you can add some exceptions in the form of :
> -@IP1 LABEL1 or
> -@IP2/MASK LABEL2
> +where you can add some exceptions in the form of::
> +
> + @IP1 LABEL1 or
> + @IP2/MASK LABEL2
>
> It means that your application will have unlabeled access to @IP1 if it has
> write access on LABEL1, and access to the subnet @IP2/MASK if it has write
> @@ -624,28 +713,32 @@ access on LABEL2.
> Entries in the /sys/fs/smackfs/netlabel file are matched by longest mask
> first, like in classless IPv4 routing.
>
> -A special label '@' and an option '-CIPSO' can be used there :
> -@ means Internet, any application with any label has access to it
> --CIPSO means standard CIPSO networking
> +A special label '@' and an option '-CIPSO' can be used there::
>
> -If you don't know what CIPSO is and don't plan to use it, you can just do :
> -echo 127.0.0.1 -CIPSO > /sys/fs/smackfs/netlabel
> -echo 0.0.0.0/0 @ > /sys/fs/smackfs/netlabel
> + @ means Internet, any application with any label has access to it
> + -CIPSO means standard CIPSO networking
> +
> +If you don't know what CIPSO is and don't plan to use it, you can just do::
> +
> + echo 127.0.0.1 -CIPSO > /sys/fs/smackfs/netlabel
> + echo 0.0.0.0/0 @ > /sys/fs/smackfs/netlabel
>
> If you use CIPSO on your 192.168.0.0/16 local network and need also unlabeled
> -Internet access, you can have :
> -echo 127.0.0.1 -CIPSO > /sys/fs/smackfs/netlabel
> -echo 192.168.0.0/16 -CIPSO > /sys/fs/smackfs/netlabel
> -echo 0.0.0.0/0 @ > /sys/fs/smackfs/netlabel
> +Internet access, you can have::
>
> + echo 127.0.0.1 -CIPSO > /sys/fs/smackfs/netlabel
> + echo 192.168.0.0/16 -CIPSO > /sys/fs/smackfs/netlabel
> + echo 0.0.0.0/0 @ > /sys/fs/smackfs/netlabel
>
> Writing Applications for Smack
> +------------------------------
>
> There are three sorts of applications that will run on a Smack system. How an
> application interacts with Smack will determine what it will have to do to
> work properly under Smack.
>
> Smack Ignorant Applications
> +---------------------------
>
> By far the majority of applications have no reason whatever to care about the
> unique properties of Smack. Since invoking a program has no impact on the
> @@ -653,12 +746,14 @@ Smack label associated with the process the only concern likely to arise is
> whether the process has execute access to the program.
>
> Smack Relevant Applications
> +---------------------------
>
> Some programs can be improved by teaching them about Smack, but do not make
> any security decisions themselves. The utility ls(1) is one example of such a
> program.
>
> Smack Enforcing Applications
> +----------------------------
>
> These are special programs that not only know about Smack, but participate in
> the enforcement of system policy. In most cases these are the programs that
> @@ -666,15 +761,16 @@ set up user sessions. There are also network services that provide information
> to processes running with various labels.
>
> File System Interfaces
> +----------------------
>
> Smack maintains labels on file system objects using extended attributes. The
> Smack label of a file, directory, or other file system object can be obtained
> -using getxattr(2).
> +using getxattr(2)::
>
> len = getxattr("/", "security.SMACK64", value, sizeof (value));
>
> will put the Smack label of the root directory into value. A privileged
> -process can set the Smack label of a file system object with setxattr(2).
> +process can set the Smack label of a file system object with setxattr(2)::
>
> len = strlen("Rubble");
> rc = setxattr("/foo", "security.SMACK64", "Rubble", len, 0);
> @@ -683,17 +779,18 @@ will set the Smack label of /foo to "Rubble" if the program has appropriate
> privilege.
>
> Socket Interfaces
> +-----------------
>
> The socket attributes can be read using fgetxattr(2).
>
> A privileged process can set the Smack label of outgoing packets with
> -fsetxattr(2).
> +fsetxattr(2)::
>
> len = strlen("Rubble");
> rc = fsetxattr(fd, "security.SMACK64IPOUT", "Rubble", len, 0);
>
> will set the Smack label "Rubble" on packets going out from the socket if the
> -program has appropriate privilege.
> +program has appropriate privilege::
>
> rc = fsetxattr(fd, "security.SMACK64IPIN, "*", strlen("*"), 0);
>
> @@ -701,33 +798,40 @@ will set the Smack label "*" as the object label against which incoming
> packets will be checked if the program has appropriate privilege.
>
> Administration
> +--------------
>
> Smack supports some mount options:
>
> - smackfsdef=label: specifies the label to give files that lack
> + smackfsdef=label:
> + specifies the label to give files that lack
> the Smack label extended attribute.
>
> - smackfsroot=label: specifies the label to assign the root of the
> + smackfsroot=label:
> + specifies the label to assign the root of the
> file system if it lacks the Smack extended attribute.
>
> - smackfshat=label: specifies a label that must have read access to
> + smackfshat=label:
> + specifies a label that must have read access to
> all labels set on the filesystem. Not yet enforced.
>
> - smackfsfloor=label: specifies a label to which all labels set on the
> + smackfsfloor=label:
> + specifies a label to which all labels set on the
> filesystem must have read access. Not yet enforced.
>
> These mount options apply to all file system types.
>
> Smack auditing
> +--------------
>
> If you want Smack auditing of security events, you need to set CONFIG_AUDIT
> in your kernel configuration.
> By default, all denied events will be audited. You can change this behavior by
> -writing a single character to the /sys/fs/smackfs/logging file :
> -0 : no logging
> -1 : log denied (default)
> -2 : log accepted
> -3 : log denied & accepted
> +writing a single character to the /sys/fs/smackfs/logging file::
> +
> + 0 : no logging
> + 1 : log denied (default)
> + 2 : log accepted
> + 3 : log denied & accepted
>
> Events are logged as 'key=value' pairs, for each event you at least will get
> the subject, the object, the rights requested, the action, the kernel function
> @@ -735,6 +839,7 @@ that triggered the event, plus other pairs depending on the type of event
> audited.
>
> Bringup Mode
> +------------
>
> Bringup mode provides logging features that can make application
> configuration and system bringup easier. Configure the kernel with
> diff --git a/Documentation/admin-guide/LSM/index.rst b/Documentation/admin-guide/LSM/index.rst
> index 41f5262359f9..c980dfe9abf1 100644
> --- a/Documentation/admin-guide/LSM/index.rst
> +++ b/Documentation/admin-guide/LSM/index.rst
> @@ -36,5 +36,6 @@ the one "major" module (e.g. SELinux) if there is one configured.
> apparmor
> LoadPin
> SELinux
> + Smack
> tomoyo
> Yama
> diff --git a/Documentation/security/00-INDEX b/Documentation/security/00-INDEX
> index a55f781be0dd..cdb2294ec047 100644
> --- a/Documentation/security/00-INDEX
> +++ b/Documentation/security/00-INDEX
> @@ -1,7 +1,5 @@
> 00-INDEX
> - this file.
> -Smack.txt
> - - documentation on the Smack Linux Security Module.
> keys-ecryptfs.txt
> - description of the encryption keys for the ecryptfs filesystem.
> keys-request-key.txt
> diff --git a/MAINTAINERS b/MAINTAINERS
> index 3c1560c75aa6..3e78b5c9b3f9 100644
> --- a/MAINTAINERS
> +++ b/MAINTAINERS
> @@ -11876,7 +11876,7 @@ L: linux-security-module@vger.kernel.org
> W: http://schaufler-ca.com
> T: git git://github.com/cschaufler/smack-next
> S: Maintained
> -F: Documentation/security/Smack.txt
> +F: Documentation/admin-guide/LSM/Smack.rst
> F: security/smack/
>
> DRIVERS FOR ADAPTIVE VOLTAGE SCALING (AVS)
[toc] | [prev] | [next] | [standalone]
| From | Kees Cook <keescook@chromium.org> |
|---|---|
| Date | 2017-05-13 14:00 +0200 |
| Subject | [PATCH 07/17] doc: ReSTify and split LSM.txt |
| Message-ID | <tGDSj-39c-49@gated-at.bofh.it> |
| In reply to | #1640893 |
The existing LSM.txt file covered both usage and development, so split
this into two files, one under admin-guide and one under kernel
development.
Cc: James Morris <james.l.morris@oracle.com>
Signed-off-by: Kees Cook <keescook@chromium.org>
---
.../LSM.txt => admin-guide/LSM/index.rst} | 22 ++++++----------------
Documentation/admin-guide/index.rst | 1 +
Documentation/security/00-INDEX | 2 --
Documentation/security/LSM.rst | 14 ++++++++++++++
Documentation/security/index.rst | 1 +
5 files changed, 22 insertions(+), 18 deletions(-)
rename Documentation/{security/LSM.txt => admin-guide/LSM/index.rst} (62%)
create mode 100644 Documentation/security/LSM.rst
diff --git a/Documentation/security/LSM.txt b/Documentation/admin-guide/LSM/index.rst
similarity index 62%
rename from Documentation/security/LSM.txt
rename to Documentation/admin-guide/LSM/index.rst
index c2683f28ed36..7e892b9b58aa 100644
--- a/Documentation/security/LSM.txt
+++ b/Documentation/admin-guide/LSM/index.rst
@@ -1,12 +1,13 @@
-Linux Security Module framework
--------------------------------
+===========================
+Linux Security Module Usage
+===========================
The Linux Security Module (LSM) framework provides a mechanism for
various security checks to be hooked by new kernel extensions. The name
"module" is a bit of a misnomer since these extensions are not actually
loadable kernel modules. Instead, they are selectable at build-time via
CONFIG_DEFAULT_SECURITY and can be overridden at boot-time via the
-"security=..." kernel command line argument, in the case where multiple
+``"security=..."`` kernel command line argument, in the case where multiple
LSMs were built into a given kernel.
The primary users of the LSM interface are Mandatory Access Control
@@ -19,23 +20,12 @@ in the core functionality of Linux itself.
Without a specific LSM built into the kernel, the default LSM will be the
Linux capabilities system. Most LSMs choose to extend the capabilities
system, building their checks on top of the defined capability hooks.
-For more details on capabilities, see capabilities(7) in the Linux
+For more details on capabilities, see ``capabilities(7)`` in the Linux
man-pages project.
A list of the active security modules can be found by reading
-/sys/kernel/security/lsm. This is a comma separated list, and
+``/sys/kernel/security/lsm``. This is a comma separated list, and
will always include the capability module. The list reflects the
order in which checks are made. The capability module will always
be first, followed by any "minor" modules (e.g. Yama) and then
the one "major" module (e.g. SELinux) if there is one configured.
-
-Based on https://lkml.org/lkml/2007/10/26/215,
-a new LSM is accepted into the kernel when its intent (a description of
-what it tries to protect against and in what cases one would expect to
-use it) has been appropriately documented in Documentation/security/.
-This allows an LSM's code to be easily compared to its goals, and so
-that end users and distros can make a more informed decision about which
-LSMs suit their requirements.
-
-For extensive documentation on the available LSM hook interfaces, please
-see include/linux/security.h.
diff --git a/Documentation/admin-guide/index.rst b/Documentation/admin-guide/index.rst
index 8c60a8a32a1a..e14c374aaf60 100644
--- a/Documentation/admin-guide/index.rst
+++ b/Documentation/admin-guide/index.rst
@@ -61,6 +61,7 @@ configure specific aspects of kernel behavior to your liking.
java
ras
pm/index
+ LSM/index
.. only:: subproject and html
diff --git a/Documentation/security/00-INDEX b/Documentation/security/00-INDEX
index c4df62a9ae5b..190a023a7e72 100644
--- a/Documentation/security/00-INDEX
+++ b/Documentation/security/00-INDEX
@@ -1,7 +1,5 @@
00-INDEX
- this file.
-LSM.txt
- - description of the Linux Security Module framework.
SELinux.txt
- how to get started with the SELinux security enhancement.
Smack.txt
diff --git a/Documentation/security/LSM.rst b/Documentation/security/LSM.rst
new file mode 100644
index 000000000000..d75778b0fa10
--- /dev/null
+++ b/Documentation/security/LSM.rst
@@ -0,0 +1,14 @@
+=================================
+Linux Security Module Development
+=================================
+
+Based on https://lkml.org/lkml/2007/10/26/215,
+a new LSM is accepted into the kernel when its intent (a description of
+what it tries to protect against and in what cases one would expect to
+use it) has been appropriately documented in ``Documentation/security/LSM``.
+This allows an LSM's code to be easily compared to its goals, and so
+that end users and distros can make a more informed decision about which
+LSMs suit their requirements.
+
+For extensive documentation on the available LSM hook interfaces, please
+see ``include/linux/lsm_hooks.h``.
diff --git a/Documentation/security/index.rst b/Documentation/security/index.rst
index 4212d7ac58b6..94ba1cfc01c5 100644
--- a/Documentation/security/index.rst
+++ b/Documentation/security/index.rst
@@ -7,5 +7,6 @@ Security Documentation
credentials
IMA-templates
+ LSM
self-protection
tpm/index
--
2.7.4
[toc] | [prev] | [next] | [standalone]
| From | Kees Cook <keescook@chromium.org> |
|---|---|
| Date | 2017-05-13 14:00 +0200 |
| Subject | [PATCH 09/17] doc: ReSTify apparmor.txt |
| Message-ID | <tGDSj-39c-53@gated-at.bofh.it> |
| In reply to | #1640893 |
Adjusts for ReST markup and moves under LSM admin guide.
Cc: John Johansen <john.johansen@canonical.com>
Signed-off-by: Kees Cook <keescook@chromium.org>
---
.../apparmor.txt => admin-guide/LSM/apparmor.rst} | 36 ++++++++++++++--------
Documentation/admin-guide/LSM/index.rst | 1 +
Documentation/security/00-INDEX | 2 --
MAINTAINERS | 1 +
security/apparmor/match.c | 2 +-
security/apparmor/policy_unpack.c | 2 +-
6 files changed, 28 insertions(+), 16 deletions(-)
rename Documentation/{security/apparmor.txt => admin-guide/LSM/apparmor.rst} (65%)
diff --git a/Documentation/security/apparmor.txt b/Documentation/admin-guide/LSM/apparmor.rst
similarity index 65%
rename from Documentation/security/apparmor.txt
rename to Documentation/admin-guide/LSM/apparmor.rst
index 93c1fd7d0635..3e9734bd0e05 100644
--- a/Documentation/security/apparmor.txt
+++ b/Documentation/admin-guide/LSM/apparmor.rst
@@ -1,4 +1,9 @@
---- What is AppArmor? ---
+========
+AppArmor
+========
+
+What is AppArmor?
+=================
AppArmor is MAC style security extension for the Linux kernel. It implements
a task centered policy, with task "profiles" being created and loaded
@@ -6,34 +11,41 @@ from user space. Tasks on the system that do not have a profile defined for
them run in an unconfined state which is equivalent to standard Linux DAC
permissions.
---- How to enable/disable ---
+How to enable/disable
+=====================
+
+set ``CONFIG_SECURITY_APPARMOR=y``
-set CONFIG_SECURITY_APPARMOR=y
+If AppArmor should be selected as the default security module then set::
-If AppArmor should be selected as the default security module then
- set CONFIG_DEFAULT_SECURITY="apparmor"
- and CONFIG_SECURITY_APPARMOR_BOOTPARAM_VALUE=1
+ CONFIG_DEFAULT_SECURITY="apparmor"
+ CONFIG_SECURITY_APPARMOR_BOOTPARAM_VALUE=1
Build the kernel
If AppArmor is not the default security module it can be enabled by passing
-security=apparmor on the kernel's command line.
+``security=apparmor`` on the kernel's command line.
If AppArmor is the default security module it can be disabled by passing
-apparmor=0, security=XXXX (where XXX is valid security module), on the
-kernel's command line
+``apparmor=0, security=XXXX`` (where ``XXXX`` is valid security module), on the
+kernel's command line.
For AppArmor to enforce any restrictions beyond standard Linux DAC permissions
policy must be loaded into the kernel from user space (see the Documentation
and tools links).
---- Documentation ---
+Documentation
+=============
-Documentation can be found on the wiki.
+Documentation can be found on the wiki, linked below.
---- Links ---
+Links
+=====
Mailing List - apparmor@lists.ubuntu.com
+
Wiki - http://apparmor.wiki.kernel.org/
+
User space tools - https://launchpad.net/apparmor
+
Kernel module - git://git.kernel.org/pub/scm/linux/kernel/git/jj/apparmor-dev.git
diff --git a/Documentation/admin-guide/LSM/index.rst b/Documentation/admin-guide/LSM/index.rst
index cc0e04d63bf9..a4db29410ea0 100644
--- a/Documentation/admin-guide/LSM/index.rst
+++ b/Documentation/admin-guide/LSM/index.rst
@@ -33,4 +33,5 @@ the one "major" module (e.g. SELinux) if there is one configured.
.. toctree::
:maxdepth: 1
+ apparmor
SELinux
diff --git a/Documentation/security/00-INDEX b/Documentation/security/00-INDEX
index aaa0195418b3..22ebdc02f0dc 100644
--- a/Documentation/security/00-INDEX
+++ b/Documentation/security/00-INDEX
@@ -4,8 +4,6 @@ Smack.txt
- documentation on the Smack Linux Security Module.
Yama.txt
- documentation on the Yama Linux Security Module.
-apparmor.txt
- - documentation on the AppArmor security extension.
keys-ecryptfs.txt
- description of the encryption keys for the ecryptfs filesystem.
keys-request-key.txt
diff --git a/MAINTAINERS b/MAINTAINERS
index c85108b4f6c7..184cdd32a67e 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -11560,6 +11560,7 @@ W: apparmor.wiki.kernel.org
T: git git://git.kernel.org/pub/scm/linux/kernel/git/jj/apparmor-dev.git
S: Supported
F: security/apparmor/
+F: Documentation/admin-guide/LSM/apparmor.rst
LOADPIN SECURITY MODULE
M: Kees Cook <keescook@chromium.org>
diff --git a/security/apparmor/match.c b/security/apparmor/match.c
index 960c913381e2..72c604350e80 100644
--- a/security/apparmor/match.c
+++ b/security/apparmor/match.c
@@ -226,7 +226,7 @@ void aa_dfa_free_kref(struct kref *kref)
* @flags: flags controlling what type of accept tables are acceptable
*
* Unpack a dfa that has been serialized. To find information on the dfa
- * format look in Documentation/security/apparmor.txt
+ * format look in Documentation/admin-guide/LSM/apparmor.rst
* Assumes the dfa @blob stream has been aligned on a 8 byte boundary
*
* Returns: an unpacked dfa ready for matching or ERR_PTR on failure
diff --git a/security/apparmor/policy_unpack.c b/security/apparmor/policy_unpack.c
index f3422a91353c..981d570eebba 100644
--- a/security/apparmor/policy_unpack.c
+++ b/security/apparmor/policy_unpack.c
@@ -13,7 +13,7 @@
* License.
*
* AppArmor uses a serialized binary format for loading policy. To find
- * policy format documentation look in Documentation/security/apparmor.txt
+ * policy format documentation see Documentation/admin-guide/LSM/apparmor.rst
* All policy is validated before it is used.
*/
--
2.7.4
[toc] | [prev] | [next] | [standalone]
| From | John Johansen <john.johansen@canonical.com> |
|---|---|
| Date | 2017-05-13 21:50 +0200 |
| Subject | Re: [PATCH 09/17] doc: ReSTify apparmor.txt |
| Message-ID | <tGLd7-82A-1@gated-at.bofh.it> |
| In reply to | #1640904 |
On 05/13/2017 04:51 AM, Kees Cook wrote:
> Adjusts for ReST markup and moves under LSM admin guide.
>
> Cc: John Johansen <john.johansen@canonical.com>
> Signed-off-by: Kees Cook <keescook@chromium.org>
Acked-by: John Johansen <john.johansen@canonical.com>
> ---
> .../apparmor.txt => admin-guide/LSM/apparmor.rst} | 36 ++++++++++++++--------
> Documentation/admin-guide/LSM/index.rst | 1 +
> Documentation/security/00-INDEX | 2 --
> MAINTAINERS | 1 +
> security/apparmor/match.c | 2 +-
> security/apparmor/policy_unpack.c | 2 +-
> 6 files changed, 28 insertions(+), 16 deletions(-)
> rename Documentation/{security/apparmor.txt => admin-guide/LSM/apparmor.rst} (65%)
>
> diff --git a/Documentation/security/apparmor.txt b/Documentation/admin-guide/LSM/apparmor.rst
> similarity index 65%
> rename from Documentation/security/apparmor.txt
> rename to Documentation/admin-guide/LSM/apparmor.rst
> index 93c1fd7d0635..3e9734bd0e05 100644
> --- a/Documentation/security/apparmor.txt
> +++ b/Documentation/admin-guide/LSM/apparmor.rst
> @@ -1,4 +1,9 @@
> ---- What is AppArmor? ---
> +========
> +AppArmor
> +========
> +
> +What is AppArmor?
> +=================
>
> AppArmor is MAC style security extension for the Linux kernel. It implements
> a task centered policy, with task "profiles" being created and loaded
> @@ -6,34 +11,41 @@ from user space. Tasks on the system that do not have a profile defined for
> them run in an unconfined state which is equivalent to standard Linux DAC
> permissions.
>
> ---- How to enable/disable ---
> +How to enable/disable
> +=====================
> +
> +set ``CONFIG_SECURITY_APPARMOR=y``
>
> -set CONFIG_SECURITY_APPARMOR=y
> +If AppArmor should be selected as the default security module then set::
>
> -If AppArmor should be selected as the default security module then
> - set CONFIG_DEFAULT_SECURITY="apparmor"
> - and CONFIG_SECURITY_APPARMOR_BOOTPARAM_VALUE=1
> + CONFIG_DEFAULT_SECURITY="apparmor"
> + CONFIG_SECURITY_APPARMOR_BOOTPARAM_VALUE=1
>
> Build the kernel
>
> If AppArmor is not the default security module it can be enabled by passing
> -security=apparmor on the kernel's command line.
> +``security=apparmor`` on the kernel's command line.
>
> If AppArmor is the default security module it can be disabled by passing
> -apparmor=0, security=XXXX (where XXX is valid security module), on the
> -kernel's command line
> +``apparmor=0, security=XXXX`` (where ``XXXX`` is valid security module), on the
> +kernel's command line.
>
> For AppArmor to enforce any restrictions beyond standard Linux DAC permissions
> policy must be loaded into the kernel from user space (see the Documentation
> and tools links).
>
> ---- Documentation ---
> +Documentation
> +=============
>
> -Documentation can be found on the wiki.
> +Documentation can be found on the wiki, linked below.
>
> ---- Links ---
> +Links
> +=====
>
> Mailing List - apparmor@lists.ubuntu.com
> +
> Wiki - http://apparmor.wiki.kernel.org/
> +
> User space tools - https://launchpad.net/apparmor
> +
> Kernel module - git://git.kernel.org/pub/scm/linux/kernel/git/jj/apparmor-dev.git
> diff --git a/Documentation/admin-guide/LSM/index.rst b/Documentation/admin-guide/LSM/index.rst
> index cc0e04d63bf9..a4db29410ea0 100644
> --- a/Documentation/admin-guide/LSM/index.rst
> +++ b/Documentation/admin-guide/LSM/index.rst
> @@ -33,4 +33,5 @@ the one "major" module (e.g. SELinux) if there is one configured.
> .. toctree::
> :maxdepth: 1
>
> + apparmor
> SELinux
> diff --git a/Documentation/security/00-INDEX b/Documentation/security/00-INDEX
> index aaa0195418b3..22ebdc02f0dc 100644
> --- a/Documentation/security/00-INDEX
> +++ b/Documentation/security/00-INDEX
> @@ -4,8 +4,6 @@ Smack.txt
> - documentation on the Smack Linux Security Module.
> Yama.txt
> - documentation on the Yama Linux Security Module.
> -apparmor.txt
> - - documentation on the AppArmor security extension.
> keys-ecryptfs.txt
> - description of the encryption keys for the ecryptfs filesystem.
> keys-request-key.txt
> diff --git a/MAINTAINERS b/MAINTAINERS
> index c85108b4f6c7..184cdd32a67e 100644
> --- a/MAINTAINERS
> +++ b/MAINTAINERS
> @@ -11560,6 +11560,7 @@ W: apparmor.wiki.kernel.org
> T: git git://git.kernel.org/pub/scm/linux/kernel/git/jj/apparmor-dev.git
> S: Supported
> F: security/apparmor/
> +F: Documentation/admin-guide/LSM/apparmor.rst
>
> LOADPIN SECURITY MODULE
> M: Kees Cook <keescook@chromium.org>
> diff --git a/security/apparmor/match.c b/security/apparmor/match.c
> index 960c913381e2..72c604350e80 100644
> --- a/security/apparmor/match.c
> +++ b/security/apparmor/match.c
> @@ -226,7 +226,7 @@ void aa_dfa_free_kref(struct kref *kref)
> * @flags: flags controlling what type of accept tables are acceptable
> *
> * Unpack a dfa that has been serialized. To find information on the dfa
> - * format look in Documentation/security/apparmor.txt
> + * format look in Documentation/admin-guide/LSM/apparmor.rst
> * Assumes the dfa @blob stream has been aligned on a 8 byte boundary
> *
> * Returns: an unpacked dfa ready for matching or ERR_PTR on failure
> diff --git a/security/apparmor/policy_unpack.c b/security/apparmor/policy_unpack.c
> index f3422a91353c..981d570eebba 100644
> --- a/security/apparmor/policy_unpack.c
> +++ b/security/apparmor/policy_unpack.c
> @@ -13,7 +13,7 @@
> * License.
> *
> * AppArmor uses a serialized binary format for loading policy. To find
> - * policy format documentation look in Documentation/security/apparmor.txt
> + * policy format documentation see Documentation/admin-guide/LSM/apparmor.rst
> * All policy is validated before it is used.
> */
>
>
[toc] | [prev] | [next] | [standalone]
| From | Jonathan Corbet <corbet@lwn.net> |
|---|---|
| Date | 2017-05-15 19:30 +0200 |
| Message-ID | <tHrYK-2FM-19@gated-at.bofh.it> |
| In reply to | #1640893 |
On Sat, 13 May 2017 04:51:36 -0700 Kees Cook <keescook@chromium.org> wrote: > This ReSTifies everything under Documentation/security/, and reorganizes > some of it (mainly the LSMs) under /admin-guide/ per Jon's request. Since > /security/ is already being indexed under the kernel development portion > of the sphinx index, I didn't move it, keeping only things that were > directly related to internal kernel development (keys, creds, etc). > > I also updated some path references, and MAINTAINERS lines. Some of the > conversion could probably do with some tweaks, but I think this is a > good first step in the right direction. This all looks pretty good to me, though I'll confess I haven't actually built the resulting docs yet. Assuming no issues turn up there, I'd be happy to just apply these and let any follow-on tweaks go from there. Thanks for doing this, and for humoring me on the organizational issues :) jon
[toc] | [prev] | [next] | [standalone]
| From | Kees Cook <keescook@chromium.org> |
|---|---|
| Date | 2017-05-15 19:40 +0200 |
| Message-ID | <tHs8p-2IK-5@gated-at.bofh.it> |
| In reply to | #1641907 |
On Mon, May 15, 2017 at 10:26 AM, Jonathan Corbet <corbet@lwn.net> wrote: > On Sat, 13 May 2017 04:51:36 -0700 > Kees Cook <keescook@chromium.org> wrote: > >> This ReSTifies everything under Documentation/security/, and reorganizes >> some of it (mainly the LSMs) under /admin-guide/ per Jon's request. Since >> /security/ is already being indexed under the kernel development portion >> of the sphinx index, I didn't move it, keeping only things that were >> directly related to internal kernel development (keys, creds, etc). >> >> I also updated some path references, and MAINTAINERS lines. Some of the >> conversion could probably do with some tweaks, but I think this is a >> good first step in the right direction. > > This all looks pretty good to me, though I'll confess I haven't actually > built the resulting docs yet. Assuming no issues turn up there, I'd be > happy to just apply these and let any follow-on tweaks go from there. > Thanks for doing this, and for humoring me on the organizational issues :) My local tree builds the docs sanely from what I can see, so if it looks good to you too, yeah, please take these as they are. I'm sure we'll need tweaks going forward, but this seems like the bulk of the organizational and basic ReST work. BTW, something I noticed in while doing this conversion is the difference between the section headings and the left-side nav bar at the top level: https://www.kernel.org/doc/html/latest/index.html The section names don't match, and each of the Kernel API Documentation sections is at the top level in the nav bar. I think this would be cleaner if everything matched up, but I didn't yet dig into figuring out why they were different. -Kees -- Kees Cook Pixel Security
[toc] | [prev] | [next] | [standalone]
Page 1 of 2 [1] 2 Next page →
Back to top | Article view | linux.kernel
csiph-web