[PATCH 00/17] convert/reorganize Documentation/security/

[PATCH 00/17] convert/reorganize Documentation/security/

[Kees Cook]

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

[PATCH 01/17] doc: ReSTify seccomp_filter.txt

[Kees Cook]

This updates seccomp_filter.txt for ReST markup, and moves it under the
user-space API index, since it describes how application author can use
seccomp.

Signed-off-by: Kees Cook <keescook@chromium.org>
---
 Documentation/userspace-api/index.rst              |   1 +
 .../seccomp_filter.rst}                            | 116 +++++++++++----------
 MAINTAINERS                                        |   1 +
 3 files changed, 62 insertions(+), 56 deletions(-)
 rename Documentation/{prctl/seccomp_filter.txt => userspace-api/seccomp_filter.rst} (71%)

diff --git a/Documentation/userspace-api/index.rst b/Documentation/userspace-api/index.rst
index a9d01b44a659..15ff12342db8 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
 
+   seccomp_filter
    unshare
 
 .. only::  subproject and html
diff --git a/Documentation/prctl/seccomp_filter.txt b/Documentation/userspace-api/seccomp_filter.rst
similarity index 71%
rename from Documentation/prctl/seccomp_filter.txt
rename to Documentation/userspace-api/seccomp_filter.rst
index 1e469ef75778..f71eb5ef1f2d 100644
--- a/Documentation/prctl/seccomp_filter.txt
+++ b/Documentation/userspace-api/seccomp_filter.rst
@@ -1,8 +1,9 @@
-		SECure COMPuting with filters
-		=============================
+===========================================
+Seccomp BPF (SECure COMPuting with filters)
+===========================================
 
 Introduction
-------------
+============
 
 A large number of system calls are exposed to every userland process
 with many of them going unused for the entire lifetime of the process.
@@ -27,7 +28,7 @@ pointers which constrains all filters to solely evaluating the system
 call arguments directly.
 
 What it isn't
--------------
+=============
 
 System call filtering isn't a sandbox.  It provides a clearly defined
 mechanism for minimizing the exposed kernel surface.  It is meant to be
@@ -40,13 +41,13 @@ system calls in socketcall() is allowed, for instance) which could be
 construed, incorrectly, as a more complete sandboxing solution.
 
 Usage
------
+=====
 
 An additional seccomp mode is added and is enabled using the same
 prctl(2) call as the strict seccomp.  If the architecture has
-CONFIG_HAVE_ARCH_SECCOMP_FILTER, then filters may be added as below:
+``CONFIG_HAVE_ARCH_SECCOMP_FILTER``, then filters may be added as below:
 
-PR_SET_SECCOMP:
+``PR_SET_SECCOMP``:
 	Now takes an additional argument which specifies a new filter
 	using a BPF program.
 	The BPF program will be executed over struct seccomp_data
@@ -55,24 +56,25 @@ PR_SET_SECCOMP:
 	acceptable values to inform the kernel which action should be
 	taken.
 
-	Usage:
+	Usage::
+
 		prctl(PR_SET_SECCOMP, SECCOMP_MODE_FILTER, prog);
 
 	The 'prog' argument is a pointer to a struct sock_fprog which
 	will contain the filter program.  If the program is invalid, the
-	call will return -1 and set errno to EINVAL.
+	call will return -1 and set errno to ``EINVAL``.
 
-	If fork/clone and execve are allowed by @prog, any child
+	If ``fork``/``clone`` and ``execve`` are allowed by @prog, any child
 	processes will be constrained to the same filters and system
 	call ABI as the parent.
 
-	Prior to use, the task must call prctl(PR_SET_NO_NEW_PRIVS, 1) or
-	run with CAP_SYS_ADMIN privileges in its namespace.  If these are not
-	true, -EACCES will be returned.  This requirement ensures that filter
+	Prior to use, the task must call ``prctl(PR_SET_NO_NEW_PRIVS, 1)`` or
+	run with ``CAP_SYS_ADMIN`` privileges in its namespace.  If these are not
+	true, ``-EACCES`` will be returned.  This requirement ensures that filter
 	programs cannot be applied to child processes with greater privileges
 	than the task that installed them.
 
-	Additionally, if prctl(2) is allowed by the attached filter,
+	Additionally, if ``prctl(2)`` is allowed by the attached filter,
 	additional filters may be layered on which will increase evaluation
 	time, but allow for further decreasing the attack surface during
 	execution of a process.
@@ -80,51 +82,52 @@ PR_SET_SECCOMP:
 The above call returns 0 on success and non-zero on error.
 
 Return values
--------------
+=============
+
 A seccomp filter may return any of the following values. If multiple
 filters exist, the return value for the evaluation of a given system
 call will always use the highest precedent value. (For example,
-SECCOMP_RET_KILL will always take precedence.)
+``SECCOMP_RET_KILL`` will always take precedence.)
 
 In precedence order, they are:
 
-SECCOMP_RET_KILL:
+``SECCOMP_RET_KILL``:
 	Results in the task exiting immediately without executing the
-	system call.  The exit status of the task (status & 0x7f) will
-	be SIGSYS, not SIGKILL.
+	system call.  The exit status of the task (``status & 0x7f``) will
+	be ``SIGSYS``, not ``SIGKILL``.
 
-SECCOMP_RET_TRAP:
-	Results in the kernel sending a SIGSYS signal to the triggering
-	task without executing the system call.  siginfo->si_call_addr
+``SECCOMP_RET_TRAP``:
+	Results in the kernel sending a ``SIGSYS`` signal to the triggering
+	task without executing the system call. ``siginfo->si_call_addr``
 	will show the address of the system call instruction, and
-	siginfo->si_syscall and siginfo->si_arch will indicate which
+	``siginfo->si_syscall`` and ``siginfo->si_arch`` will indicate which
 	syscall was attempted.  The program counter will be as though
 	the syscall happened (i.e. it will not point to the syscall
 	instruction).  The return value register will contain an arch-
 	dependent value -- if resuming execution, set it to something
 	sensible.  (The architecture dependency is because replacing
-	it with -ENOSYS could overwrite some useful information.)
+	it with ``-ENOSYS`` could overwrite some useful information.)
 
-	The SECCOMP_RET_DATA portion of the return value will be passed
-	as si_errno.
+	The ``SECCOMP_RET_DATA`` portion of the return value will be passed
+	as ``si_errno``.
 
-	SIGSYS triggered by seccomp will have a si_code of SYS_SECCOMP.
+	``SIGSYS`` triggered by seccomp will have a si_code of ``SYS_SECCOMP``.
 
-SECCOMP_RET_ERRNO:
+``SECCOMP_RET_ERRNO``:
 	Results in the lower 16-bits of the return value being passed
 	to userland as the errno without executing the system call.
 
-SECCOMP_RET_TRACE:
+``SECCOMP_RET_TRACE``:
 	When returned, this value will cause the kernel to attempt to
-	notify a ptrace()-based tracer prior to executing the system
-	call.  If there is no tracer present, -ENOSYS is returned to
+	notify a ``ptrace()``-based tracer prior to executing the system
+	call.  If there is no tracer present, ``-ENOSYS`` is returned to
 	userland and the system call is not executed.
 
-	A tracer will be notified if it requests PTRACE_O_TRACESECCOMP
-	using ptrace(PTRACE_SETOPTIONS).  The tracer will be notified
-	of a PTRACE_EVENT_SECCOMP and the SECCOMP_RET_DATA portion of
+	A tracer will be notified if it requests ``PTRACE_O_TRACESECCOM``P
+	using ``ptrace(PTRACE_SETOPTIONS)``.  The tracer will be notified
+	of a ``PTRACE_EVENT_SECCOMP`` and the ``SECCOMP_RET_DATA`` portion of
 	the BPF program return value will be available to the tracer
-	via PTRACE_GETEVENTMSG.
+	via ``PTRACE_GETEVENTMSG``.
 
 	The tracer can skip the system call by changing the syscall number
 	to -1.  Alternatively, the tracer can change the system call
@@ -138,19 +141,19 @@ SECCOMP_RET_TRACE:
 	allow use of ptrace, even of other sandboxed processes, without
 	extreme care; ptracers can use this mechanism to escape.)
 
-SECCOMP_RET_ALLOW:
+``SECCOMP_RET_ALLOW``:
 	Results in the system call being executed.
 
 If multiple filters exist, the return value for the evaluation of a
 given system call will always use the highest precedent value.
 
-Precedence is only determined using the SECCOMP_RET_ACTION mask.  When
+Precedence is only determined using the ``SECCOMP_RET_ACTION`` mask.  When
 multiple filters return values of the same precedence, only the
-SECCOMP_RET_DATA from the most recently installed filter will be
+``SECCOMP_RET_DATA`` from the most recently installed filter will be
 returned.
 
 Pitfalls
---------
+========
 
 The biggest pitfall to avoid during use is filtering on system call
 number without checking the architecture value.  Why?  On any
@@ -160,39 +163,40 @@ the numbers in the different calling conventions overlap, then checks in
 the filters may be abused.  Always check the arch value!
 
 Example
--------
+=======
 
-The samples/seccomp/ directory contains both an x86-specific example
+The ``samples/seccomp/`` directory contains both an x86-specific example
 and a more generic example of a higher level macro interface for BPF
 program generation.
 
 
 
 Adding architecture support
------------------------
+===========================
 
-See arch/Kconfig for the authoritative requirements.  In general, if an
+See ``arch/Kconfig`` for the authoritative requirements.  In general, if an
 architecture supports both ptrace_event and seccomp, it will be able to
-support seccomp filter with minor fixup: SIGSYS support and seccomp return
-value checking.  Then it must just add CONFIG_HAVE_ARCH_SECCOMP_FILTER
+support seccomp filter with minor fixup: ``SIGSYS`` support and seccomp return
+value checking.  Then it must just add ``CONFIG_HAVE_ARCH_SECCOMP_FILTER``
 to its arch-specific Kconfig.
 
 
 
 Caveats
--------
+=======
 
 The vDSO can cause some system calls to run entirely in userspace,
 leading to surprises when you run programs on different machines that
 fall back to real syscalls.  To minimize these surprises on x86, make
 sure you test with
-/sys/devices/system/clocksource/clocksource0/current_clocksource set to
-something like acpi_pm.
+``/sys/devices/system/clocksource/clocksource0/current_clocksource`` set to
+something like ``acpi_pm``.
 
 On x86-64, vsyscall emulation is enabled by default.  (vsyscalls are
-legacy variants on vDSO calls.)  Currently, emulated vsyscalls will honor seccomp, with a few oddities:
+legacy variants on vDSO calls.)  Currently, emulated vsyscalls will
+honor seccomp, with a few oddities:
 
-- A return value of SECCOMP_RET_TRAP will set a si_call_addr pointing to
+- A return value of ``SECCOMP_RET_TRAP`` will set a ``si_call_addr`` pointing to
   the vsyscall entry for the given call and not the address after the
   'syscall' instruction.  Any code which wants to restart the call
   should be aware that (a) a ret instruction has been emulated and (b)
@@ -200,7 +204,7 @@ legacy variants on vDSO calls.)  Currently, emulated vsyscalls will honor seccom
   emulation security checks, making resuming the syscall mostly
   pointless.
 
-- A return value of SECCOMP_RET_TRACE will signal the tracer as usual,
+- A return value of ``SECCOMP_RET_TRACE`` will signal the tracer as usual,
   but the syscall may not be changed to another system call using the
   orig_rax register. It may only be changed to -1 order to skip the
   currently emulated call. Any other change MAY terminate the process.
@@ -209,14 +213,14 @@ legacy variants on vDSO calls.)  Currently, emulated vsyscalls will honor seccom
   rip or rsp.  (Do not rely on other changes terminating the process.
   They might work.  For example, on some kernels, choosing a syscall
   that only exists in future kernels will be correctly emulated (by
-  returning -ENOSYS).
+  returning ``-ENOSYS``).
 
-To detect this quirky behavior, check for addr & ~0x0C00 ==
-0xFFFFFFFFFF600000.  (For SECCOMP_RET_TRACE, use rip.  For
-SECCOMP_RET_TRAP, use siginfo->si_call_addr.)  Do not check any other
+To detect this quirky behavior, check for ``addr & ~0x0C00 ==
+0xFFFFFFFFFF600000``.  (For ``SECCOMP_RET_TRACE``, use rip.  For
+``SECCOMP_RET_TRAP``, use ``siginfo->si_call_addr``.)  Do not check any other
 condition: future kernels may improve vsyscall emulation and current
 kernels in vsyscall=native mode will behave differently, but the
-instructions at 0xF...F600{0,4,8,C}00 will not be system calls in these
+instructions at ``0xF...F600{0,4,8,C}00`` will not be system calls in these
 cases.
 
 Note that modern systems are unlikely to use vsyscalls at all -- they
diff --git a/MAINTAINERS b/MAINTAINERS
index 6b36037cbe8f..f2261713043c 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -11492,6 +11492,7 @@ F:	kernel/seccomp.c
 F:	include/uapi/linux/seccomp.h
 F:	include/linux/seccomp.h
 F:	tools/testing/selftests/seccomp/*
+F:	Documentation/userspace-api/seccomp_filter.rst
 K:	\bsecure_computing
 K:	\bTIF_SECCOMP\b
 
-- 
2.7.4

[PATCH 02/17] doc: ReSTify no_new_privs.txt

[Kees Cook]

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

[PATCH 03/17] doc: ReSTify IMA-templates.txt

[Kees Cook]

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

[PATCH 04/17] doc: ReSTify credentials.txt

[Kees Cook]

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

[PATCH 05/17] doc: ReSTify self-protection.txt

[Kees Cook]

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

[PATCH 06/17] doc: security: minor cleanups to build kernel-doc

[Kees Cook]

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

Re: [PATCH 06/17] doc: security: minor cleanups to build kernel-doc

[James Morris]

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>

Re: [PATCH 06/17] doc: security: minor cleanups to build kernel-doc

[Jonathan Corbet]

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

Re: [PATCH 06/17] doc: security: minor cleanups to build kernel-doc

[Casey Schaufler]

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,

Re: [PATCH 06/17] doc: security: minor cleanups to build kernel-doc

[Kees Cook]

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

[PATCH 07/17] doc: ReSTify and split LSM.txt

[Kees Cook]

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

[PATCH 08/17] doc: ReSTify SELinux.txt

[Kees Cook]

Adjusts for ReST markup and moves under LSM admin guide.

Cc: Paul Moore <paul@paul-moore.com>
Signed-off-by: Kees Cook <keescook@chromium.org>
---
 .../SELinux.txt => admin-guide/LSM/SELinux.rst}        | 18 ++++++++++++------
 Documentation/admin-guide/LSM/index.rst                |  5 +++++
 Documentation/security/00-INDEX                        |  2 --
 MAINTAINERS                                            |  1 +
 scripts/selinux/README                                 |  2 +-
 5 files changed, 19 insertions(+), 9 deletions(-)
 rename Documentation/{security/SELinux.txt => admin-guide/LSM/SELinux.rst} (71%)

diff --git a/Documentation/security/SELinux.txt b/Documentation/admin-guide/LSM/SELinux.rst
similarity index 71%
rename from Documentation/security/SELinux.txt
rename to Documentation/admin-guide/LSM/SELinux.rst
index 07eae00f3314..f722c9b4173a 100644
--- a/Documentation/security/SELinux.txt
+++ b/Documentation/admin-guide/LSM/SELinux.rst
@@ -1,27 +1,33 @@
+=======
+SELinux
+=======
+
 If you want to use SELinux, chances are you will want
 to use the distro-provided policies, or install the
 latest reference policy release from
+
 	http://oss.tresys.com/projects/refpolicy
 
 However, if you want to install a dummy policy for
-testing, you can do using 'mdp' provided under
+testing, you can do using ``mdp`` provided under
 scripts/selinux.  Note that this requires the selinux
 userspace to be installed - in particular you will
 need checkpolicy to compile a kernel, and setfiles and
 fixfiles to label the filesystem.
 
 	1. Compile the kernel with selinux enabled.
-	2. Type 'make' to compile mdp.
+	2. Type ``make`` to compile ``mdp``.
 	3. Make sure that you are not running with
 	   SELinux enabled and a real policy.  If
 	   you are, reboot with selinux disabled
 	   before continuing.
-	4. Run install_policy.sh:
+	4. Run install_policy.sh::
+
 		cd scripts/selinux
 		sh install_policy.sh
 
 Step 4 will create a new dummy policy valid for your
 kernel, with a single selinux user, role, and type.
-It will compile the policy, will set your SELINUXTYPE to
-dummy in /etc/selinux/config, install the compiled policy
-as 'dummy', and relabel your filesystem.
+It will compile the policy, will set your ``SELINUXTYPE`` to
+``dummy`` in ``/etc/selinux/config``, install the compiled policy
+as ``dummy``, and relabel your filesystem.
diff --git a/Documentation/admin-guide/LSM/index.rst b/Documentation/admin-guide/LSM/index.rst
index 7e892b9b58aa..cc0e04d63bf9 100644
--- a/Documentation/admin-guide/LSM/index.rst
+++ b/Documentation/admin-guide/LSM/index.rst
@@ -29,3 +29,8 @@ 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.
+
+.. toctree::
+   :maxdepth: 1
+
+   SELinux
diff --git a/Documentation/security/00-INDEX b/Documentation/security/00-INDEX
index 190a023a7e72..aaa0195418b3 100644
--- a/Documentation/security/00-INDEX
+++ b/Documentation/security/00-INDEX
@@ -1,7 +1,5 @@
 00-INDEX
 	- this file.
-SELinux.txt
-	- how to get started with the SELinux security enhancement.
 Smack.txt
 	- documentation on the Smack Linux Security Module.
 Yama.txt
diff --git a/MAINTAINERS b/MAINTAINERS
index f2261713043c..c85108b4f6c7 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -11551,6 +11551,7 @@ S:	Supported
 F:	include/linux/selinux*
 F:	security/selinux/
 F:	scripts/selinux/
+F:	Documentation/admin-guide/LSM/SELinux.rst
 
 APPARMOR SECURITY MODULE
 M:	John Johansen <john.johansen@canonical.com>
diff --git a/scripts/selinux/README b/scripts/selinux/README
index 4d020ecb7524..5ba679c5be18 100644
--- a/scripts/selinux/README
+++ b/scripts/selinux/README
@@ -1,2 +1,2 @@
-Please see Documentation/security/SELinux.txt for information on
+Please see Documentation/admin-guide/LSM/SELinux.rst for information on
 installing a dummy SELinux policy.
-- 
2.7.4

Re: [PATCH 08/17] doc: ReSTify SELinux.txt

[Paul Moore]

On Sat, May 13, 2017 at 7:51 AM, Kees Cook <keescook@chromium.org> wrote:
> Adjusts for ReST markup and moves under LSM admin guide.
>
> Cc: Paul Moore <paul@paul-moore.com>
> Signed-off-by: Kees Cook <keescook@chromium.org>
> ---
>  .../SELinux.txt => admin-guide/LSM/SELinux.rst}        | 18 ++++++++++++------
>  Documentation/admin-guide/LSM/index.rst                |  5 +++++
>  Documentation/security/00-INDEX                        |  2 --
>  MAINTAINERS                                            |  1 +
>  scripts/selinux/README                                 |  2 +-
>  5 files changed, 19 insertions(+), 9 deletions(-)
>  rename Documentation/{security/SELinux.txt => admin-guide/LSM/SELinux.rst} (71%)

I'm not sure if this has already been merged, but in case it hasn't
feel free to add my sign-off.  Thanks Kees.

Signed-off-by: Paul Moore <paul@paul-moore.com>

> diff --git a/Documentation/security/SELinux.txt b/Documentation/admin-guide/LSM/SELinux.rst
> similarity index 71%
> rename from Documentation/security/SELinux.txt
> rename to Documentation/admin-guide/LSM/SELinux.rst
> index 07eae00f3314..f722c9b4173a 100644
> --- a/Documentation/security/SELinux.txt
> +++ b/Documentation/admin-guide/LSM/SELinux.rst
> @@ -1,27 +1,33 @@
> +=======
> +SELinux
> +=======
> +
>  If you want to use SELinux, chances are you will want
>  to use the distro-provided policies, or install the
>  latest reference policy release from
> +
>         http://oss.tresys.com/projects/refpolicy
>
>  However, if you want to install a dummy policy for
> -testing, you can do using 'mdp' provided under
> +testing, you can do using ``mdp`` provided under
>  scripts/selinux.  Note that this requires the selinux
>  userspace to be installed - in particular you will
>  need checkpolicy to compile a kernel, and setfiles and
>  fixfiles to label the filesystem.
>
>         1. Compile the kernel with selinux enabled.
> -       2. Type 'make' to compile mdp.
> +       2. Type ``make`` to compile ``mdp``.
>         3. Make sure that you are not running with
>            SELinux enabled and a real policy.  If
>            you are, reboot with selinux disabled
>            before continuing.
> -       4. Run install_policy.sh:
> +       4. Run install_policy.sh::
> +
>                 cd scripts/selinux
>                 sh install_policy.sh
>
>  Step 4 will create a new dummy policy valid for your
>  kernel, with a single selinux user, role, and type.
> -It will compile the policy, will set your SELINUXTYPE to
> -dummy in /etc/selinux/config, install the compiled policy
> -as 'dummy', and relabel your filesystem.
> +It will compile the policy, will set your ``SELINUXTYPE`` to
> +``dummy`` in ``/etc/selinux/config``, install the compiled policy
> +as ``dummy``, and relabel your filesystem.
> diff --git a/Documentation/admin-guide/LSM/index.rst b/Documentation/admin-guide/LSM/index.rst
> index 7e892b9b58aa..cc0e04d63bf9 100644
> --- a/Documentation/admin-guide/LSM/index.rst
> +++ b/Documentation/admin-guide/LSM/index.rst
> @@ -29,3 +29,8 @@ 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.
> +
> +.. toctree::
> +   :maxdepth: 1
> +
> +   SELinux
> diff --git a/Documentation/security/00-INDEX b/Documentation/security/00-INDEX
> index 190a023a7e72..aaa0195418b3 100644
> --- a/Documentation/security/00-INDEX
> +++ b/Documentation/security/00-INDEX
> @@ -1,7 +1,5 @@
>  00-INDEX
>         - this file.
> -SELinux.txt
> -       - how to get started with the SELinux security enhancement.
>  Smack.txt
>         - documentation on the Smack Linux Security Module.
>  Yama.txt
> diff --git a/MAINTAINERS b/MAINTAINERS
> index f2261713043c..c85108b4f6c7 100644
> --- a/MAINTAINERS
> +++ b/MAINTAINERS
> @@ -11551,6 +11551,7 @@ S:      Supported
>  F:     include/linux/selinux*
>  F:     security/selinux/
>  F:     scripts/selinux/
> +F:     Documentation/admin-guide/LSM/SELinux.rst
>
>  APPARMOR SECURITY MODULE
>  M:     John Johansen <john.johansen@canonical.com>
> diff --git a/scripts/selinux/README b/scripts/selinux/README
> index 4d020ecb7524..5ba679c5be18 100644
> --- a/scripts/selinux/README
> +++ b/scripts/selinux/README
> @@ -1,2 +1,2 @@
> -Please see Documentation/security/SELinux.txt for information on
> +Please see Documentation/admin-guide/LSM/SELinux.rst for information on
>  installing a dummy SELinux policy.
> --
> 2.7.4
>



-- 
paul moore
www.paul-moore.com

[PATCH 09/17] doc: ReSTify apparmor.txt

[Kees Cook]

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

Re: [PATCH 09/17] doc: ReSTify apparmor.txt

[John Johansen]

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.
>   */
>  
> 

[PATCH 10/17] doc: ReSTify tomoyo.txt

[Kees Cook]

Adjusts for ReST markup and moves under LSM admin guide.

Cc: Tetsuo Handa <penguin-kernel@I-love.SAKURA.ne.jp>
Signed-off-by: Kees Cook <keescook@chromium.org>
---
 Documentation/admin-guide/LSM/index.rst            |  1 +
 .../tomoyo.txt => admin-guide/LSM/tomoyo.rst}      | 22 ++++++++++++++++------
 Documentation/security/00-INDEX                    |  2 --
 3 files changed, 17 insertions(+), 8 deletions(-)
 rename Documentation/{security/tomoyo.txt => admin-guide/LSM/tomoyo.rst} (85%)

diff --git a/Documentation/admin-guide/LSM/index.rst b/Documentation/admin-guide/LSM/index.rst
index a4db29410ea0..6aa4e0dc588b 100644
--- a/Documentation/admin-guide/LSM/index.rst
+++ b/Documentation/admin-guide/LSM/index.rst
@@ -35,3 +35,4 @@ the one "major" module (e.g. SELinux) if there is one configured.
 
    apparmor
    SELinux
+   tomoyo
diff --git a/Documentation/security/tomoyo.txt b/Documentation/admin-guide/LSM/tomoyo.rst
similarity index 85%
rename from Documentation/security/tomoyo.txt
rename to Documentation/admin-guide/LSM/tomoyo.rst
index 200a2d37cbc8..a5947218fa64 100644
--- a/Documentation/security/tomoyo.txt
+++ b/Documentation/admin-guide/LSM/tomoyo.rst
@@ -1,21 +1,30 @@
---- What is TOMOYO? ---
+======
+TOMOYO
+======
+
+What is TOMOYO?
+===============
 
 TOMOYO is a name-based MAC extension (LSM module) for the Linux kernel.
 
 LiveCD-based tutorials are available at
+
 http://tomoyo.sourceforge.jp/1.7/1st-step/ubuntu10.04-live/
-http://tomoyo.sourceforge.jp/1.7/1st-step/centos5-live/ .
+http://tomoyo.sourceforge.jp/1.7/1st-step/centos5-live/
+
 Though these tutorials use non-LSM version of TOMOYO, they are useful for you
 to know what TOMOYO is.
 
---- How to enable TOMOYO? ---
+How to enable TOMOYO?
+=====================
 
-Build the kernel with CONFIG_SECURITY_TOMOYO=y and pass "security=tomoyo" on
+Build the kernel with ``CONFIG_SECURITY_TOMOYO=y`` and pass ``security=tomoyo`` on
 kernel's command line.
 
 Please see http://tomoyo.sourceforge.jp/2.3/ for details.
 
---- Where is documentation? ---
+Where is documentation?
+=======================
 
 User <-> Kernel interface documentation is available at
 http://tomoyo.sourceforge.jp/2.3/policy-reference.html .
@@ -42,7 +51,8 @@ History of TOMOYO?
   Realities of Mainlining
     http://sourceforge.jp/projects/tomoyo/docs/lfj2008.pdf
 
---- What is future plan? ---
+What is future plan?
+====================
 
 We believe that inode based security and name based security are complementary
 and both should be used together. But unfortunately, so far, we cannot enable
diff --git a/Documentation/security/00-INDEX b/Documentation/security/00-INDEX
index 22ebdc02f0dc..04ef62511ea1 100644
--- a/Documentation/security/00-INDEX
+++ b/Documentation/security/00-INDEX
@@ -12,5 +12,3 @@ keys-trusted-encrypted.txt
 	- info on the Trusted and Encrypted keys in the kernel key ring service.
 keys.txt
 	- description of the kernel key retention service.
-tomoyo.txt
-	- documentation on the TOMOYO Linux Security Module.
-- 
2.7.4

[PATCH 11/17] doc: ReSTify Yama.txt

[Kees Cook]

Adjusts for ReST markup and moves under LSM admin guide.

Signed-off-by: Kees Cook <keescook@chromium.org>
---
 .../Yama.txt => admin-guide/LSM/Yama.rst}          | 55 ++++++++++++----------
 Documentation/admin-guide/LSM/index.rst            |  1 +
 Documentation/security/00-INDEX                    |  2 -
 MAINTAINERS                                        |  1 +
 security/yama/Kconfig                              |  3 +-
 5 files changed, 33 insertions(+), 29 deletions(-)
 rename Documentation/{security/Yama.txt => admin-guide/LSM/Yama.rst} (60%)

diff --git a/Documentation/security/Yama.txt b/Documentation/admin-guide/LSM/Yama.rst
similarity index 60%
rename from Documentation/security/Yama.txt
rename to Documentation/admin-guide/LSM/Yama.rst
index d9ee7d7a6c7f..13468ea696b7 100644
--- a/Documentation/security/Yama.txt
+++ b/Documentation/admin-guide/LSM/Yama.rst
@@ -1,13 +1,14 @@
+====
+Yama
+====
+
 Yama is a Linux Security Module that collects system-wide DAC security
 protections that are not handled by the core kernel itself. This is
-selectable at build-time with CONFIG_SECURITY_YAMA, and can be controlled
-at run-time through sysctls in /proc/sys/kernel/yama:
-
-- ptrace_scope
+selectable at build-time with ``CONFIG_SECURITY_YAMA``, and can be controlled
+at run-time through sysctls in ``/proc/sys/kernel/yama``:
 
-==============================================================
-
-ptrace_scope:
+ptrace_scope
+============
 
 As Linux grows in popularity, it will become a larger target for
 malware. One particularly troubling weakness of the Linux process
@@ -25,47 +26,49 @@ exist and remain possible if ptrace is allowed to operate as before.
 Since ptrace is not commonly used by non-developers and non-admins, system
 builders should be allowed the option to disable this debugging system.
 
-For a solution, some applications use prctl(PR_SET_DUMPABLE, ...) to
+For a solution, some applications use ``prctl(PR_SET_DUMPABLE, ...)`` to
 specifically disallow such ptrace attachment (e.g. ssh-agent), but many
 do not. A more general solution is to only allow ptrace directly from a
 parent to a child process (i.e. direct "gdb EXE" and "strace EXE" still
-work), or with CAP_SYS_PTRACE (i.e. "gdb --pid=PID", and "strace -p PID"
+work), or with ``CAP_SYS_PTRACE`` (i.e. "gdb --pid=PID", and "strace -p PID"
 still work as root).
 
 In mode 1, software that has defined application-specific relationships
 between a debugging process and its inferior (crash handlers, etc),
-prctl(PR_SET_PTRACER, pid, ...) can be used. An inferior can declare which
-other process (and its descendants) are allowed to call PTRACE_ATTACH
+``prctl(PR_SET_PTRACER, pid, ...)`` can be used. An inferior can declare which
+other process (and its descendants) are allowed to call ``PTRACE_ATTACH``
 against it. Only one such declared debugging process can exists for
 each inferior at a time. For example, this is used by KDE, Chromium, and
 Firefox's crash handlers, and by Wine for allowing only Wine processes
 to ptrace each other. If a process wishes to entirely disable these ptrace
-restrictions, it can call prctl(PR_SET_PTRACER, PR_SET_PTRACER_ANY, ...)
+restrictions, it can call ``prctl(PR_SET_PTRACER, PR_SET_PTRACER_ANY, ...)``
 so that any otherwise allowed process (even those in external pid namespaces)
 may attach.
 
-The sysctl settings (writable only with CAP_SYS_PTRACE) are:
+The sysctl settings (writable only with ``CAP_SYS_PTRACE``) are:
 
-0 - classic ptrace permissions: a process can PTRACE_ATTACH to any other
+0 - classic ptrace permissions:
+    a process can ``PTRACE_ATTACH`` to any other
     process running under the same uid, as long as it is dumpable (i.e.
     did not transition uids, start privileged, or have called
-    prctl(PR_SET_DUMPABLE...) already). Similarly, PTRACE_TRACEME is
+    ``prctl(PR_SET_DUMPABLE...)`` already). Similarly, ``PTRACE_TRACEME`` is
     unchanged.
 
-1 - restricted ptrace: a process must have a predefined relationship
-    with the inferior it wants to call PTRACE_ATTACH on. By default,
+1 - restricted ptrace:
+    a process must have a predefined relationship
+    with the inferior it wants to call ``PTRACE_ATTACH`` on. By default,
     this relationship is that of only its descendants when the above
     classic criteria is also met. To change the relationship, an
-    inferior can call prctl(PR_SET_PTRACER, debugger, ...) to declare
-    an allowed debugger PID to call PTRACE_ATTACH on the inferior.
-    Using PTRACE_TRACEME is unchanged.
+    inferior can call ``prctl(PR_SET_PTRACER, debugger, ...)`` to declare
+    an allowed debugger PID to call ``PTRACE_ATTACH`` on the inferior.
+    Using ``PTRACE_TRACEME`` is unchanged.
 
-2 - admin-only attach: only processes with CAP_SYS_PTRACE may use ptrace
-    with PTRACE_ATTACH, or through children calling PTRACE_TRACEME.
+2 - admin-only attach:
+    only processes with ``CAP_SYS_PTRACE`` may use ptrace
+    with ``PTRACE_ATTACH``, or through children calling ``PTRACE_TRACEME``.
 
-3 - no attach: no processes may use ptrace with PTRACE_ATTACH nor via
-    PTRACE_TRACEME. Once set, this sysctl value cannot be changed.
+3 - no attach:
+    no processes may use ptrace with ``PTRACE_ATTACH`` nor via
+    ``PTRACE_TRACEME``. Once set, this sysctl value cannot be changed.
 
 The original children-only logic was based on the restrictions in grsecurity.
-
-==============================================================
diff --git a/Documentation/admin-guide/LSM/index.rst b/Documentation/admin-guide/LSM/index.rst
index 6aa4e0dc588b..e5ba2c69b8ef 100644
--- a/Documentation/admin-guide/LSM/index.rst
+++ b/Documentation/admin-guide/LSM/index.rst
@@ -36,3 +36,4 @@ the one "major" module (e.g. SELinux) if there is one configured.
    apparmor
    SELinux
    tomoyo
+   Yama
diff --git a/Documentation/security/00-INDEX b/Documentation/security/00-INDEX
index 04ef62511ea1..a55f781be0dd 100644
--- a/Documentation/security/00-INDEX
+++ b/Documentation/security/00-INDEX
@@ -2,8 +2,6 @@
 	- this file.
 Smack.txt
 	- documentation on the Smack Linux Security Module.
-Yama.txt
-	- documentation on the Yama 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 184cdd32a67e..c72830e888f1 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -11573,6 +11573,7 @@ M:	Kees Cook <keescook@chromium.org>
 T:	git git://git.kernel.org/pub/scm/linux/kernel/git/kees/linux.git yama/tip
 S:	Supported
 F:	security/yama/
+F:	Documentation/admin-guide/LSM/Yama.rst
 
 SENSABLE PHANTOM
 M:	Jiri Slaby <jirislaby@gmail.com>
diff --git a/security/yama/Kconfig b/security/yama/Kconfig
index 90c605eea892..96b27405558a 100644
--- a/security/yama/Kconfig
+++ b/security/yama/Kconfig
@@ -7,6 +7,7 @@ config SECURITY_YAMA
 	  system-wide security settings beyond regular Linux discretionary
 	  access controls. Currently available is ptrace scope restriction.
 	  Like capabilities, this security module stacks with other LSMs.
-	  Further information can be found in Documentation/security/Yama.txt.
+	  Further information can be found in
+	  Documentation/admin-guide/LSM/Yama.rst.
 
 	  If you are unsure how to answer this question, answer N.
-- 
2.7.4

[PATCH 12/17] doc: ReSTify LoadPin.txt

[Kees Cook]

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

[PATCH 13/17] doc: ReSTify Smack.txt

[Kees Cook]

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

Re: [PATCH 13/17] doc: ReSTify Smack.txt

[Casey Schaufler]

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)

[PATCH 14/17] doc: ReSTify keys.txt

[Kees Cook]

This creates a new section in the security development index for kernel
keys, and adjusts for ReST markup.

Cc: David Howells <dhowells@redhat.com>
Signed-off-by: Kees Cook <keescook@chromium.org>
---
 Documentation/crypto/asymmetric-keys.txt           |   2 +-
 Documentation/security/00-INDEX                    |   2 -
 Documentation/security/index.rst                   |   1 +
 Documentation/security/{keys.txt => keys/core.rst} | 314 ++++++++++-----------
 Documentation/security/keys/index.rst              |   8 +
 MAINTAINERS                                        |   2 +-
 include/linux/key.h                                |   2 +-
 7 files changed, 163 insertions(+), 168 deletions(-)
 rename Documentation/security/{keys.txt => keys/core.rst} (89%)
 create mode 100644 Documentation/security/keys/index.rst

diff --git a/Documentation/crypto/asymmetric-keys.txt b/Documentation/crypto/asymmetric-keys.txt
index 5ad6480e3fb9..b82b6ad48488 100644
--- a/Documentation/crypto/asymmetric-keys.txt
+++ b/Documentation/crypto/asymmetric-keys.txt
@@ -265,7 +265,7 @@ mandatory:
 
      The caller passes a pointer to the following struct with all of the fields
      cleared, except for data, datalen and quotalen [see
-     Documentation/security/keys.txt].
+     Documentation/security/keys/core.rst].
 
 	struct key_preparsed_payload {
 		char		*description;
diff --git a/Documentation/security/00-INDEX b/Documentation/security/00-INDEX
index cdb2294ec047..a840095bb11c 100644
--- a/Documentation/security/00-INDEX
+++ b/Documentation/security/00-INDEX
@@ -6,5 +6,3 @@ 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.
-keys.txt
-	- description of the kernel key retention service.
diff --git a/Documentation/security/index.rst b/Documentation/security/index.rst
index 94ba1cfc01c5..298a94a33f05 100644
--- a/Documentation/security/index.rst
+++ b/Documentation/security/index.rst
@@ -7,6 +7,7 @@ Security Documentation
 
    credentials
    IMA-templates
+   keys/index
    LSM
    self-protection
    tpm/index
diff --git a/Documentation/security/keys.txt b/Documentation/security/keys/core.rst
similarity index 89%
rename from Documentation/security/keys.txt
rename to Documentation/security/keys/core.rst
index cd5019934d7f..0d831a7afe4f 100644
--- a/Documentation/security/keys.txt
+++ b/Documentation/security/keys/core.rst
@@ -1,6 +1,6 @@
-			 ============================
-			 KERNEL KEY RETENTION SERVICE
-			 ============================
+============================
+Kernel Key Retention Service
+============================
 
 This service allows cryptographic keys, authentication tokens, cross-domain
 user mappings, and similar to be cached in the kernel for the use of
@@ -29,8 +29,7 @@ This document has the following sections:
 	- Garbage collection
 
 
-============
-KEY OVERVIEW
+Key Overview
 ============
 
 In this context, keys represent units of cryptographic data, authentication
@@ -47,14 +46,14 @@ Each key has a number of attributes:
 	- State.
 
 
- (*) Each key is issued a serial number of type key_serial_t that is unique for
+  *  Each key is issued a serial number of type key_serial_t that is unique for
      the lifetime of that key. All serial numbers are positive non-zero 32-bit
      integers.
 
      Userspace programs can use a key's serial numbers as a way to gain access
      to it, subject to permission checking.
 
- (*) Each key is of a defined "type". Types must be registered inside the
+  *  Each key is of a defined "type". Types must be registered inside the
      kernel by a kernel service (such as a filesystem) before keys of that type
      can be added or used. Userspace programs cannot define new types directly.
 
@@ -64,18 +63,18 @@ Each key has a number of attributes:
      Should a type be removed from the system, all the keys of that type will
      be invalidated.
 
- (*) Each key has a description. This should be a printable string. The key
+  *  Each key has a description. This should be a printable string. The key
      type provides an operation to perform a match between the description on a
      key and a criterion string.
 
- (*) Each key has an owner user ID, a group ID and a permissions mask. These
+  *  Each key has an owner user ID, a group ID and a permissions mask. These
      are used to control what a process may do to a key from userspace, and
      whether a kernel service will be able to find the key.
 
- (*) Each key can be set to expire at a specific time by the key type's
+  *  Each key can be set to expire at a specific time by the key type's
      instantiation function. Keys can also be immortal.
 
- (*) Each key can have a payload. This is a quantity of data that represent the
+  *  Each key can have a payload. This is a quantity of data that represent the
      actual "key". In the case of a keyring, this is a list of keys to which
      the keyring links; in the case of a user-defined key, it's an arbitrary
      blob of data.
@@ -91,39 +90,38 @@ Each key has a number of attributes:
      permitted, another key type operation will be called to convert the key's
      attached payload back into a blob of data.
 
- (*) Each key can be in one of a number of basic states:
+  *  Each key can be in one of a number of basic states:
 
-     (*) Uninstantiated. The key exists, but does not have any data attached.
+      *  Uninstantiated. The key exists, but does not have any data attached.
      	 Keys being requested from userspace will be in this state.
 
-     (*) Instantiated. This is the normal state. The key is fully formed, and
+      *  Instantiated. This is the normal state. The key is fully formed, and
 	 has data attached.
 
-     (*) Negative. This is a relatively short-lived state. The key acts as a
+      *  Negative. This is a relatively short-lived state. The key acts as a
 	 note saying that a previous call out to userspace failed, and acts as
 	 a throttle on key lookups. A negative key can be updated to a normal
 	 state.
 
-     (*) Expired. Keys can have lifetimes set. If their lifetime is exceeded,
+      *  Expired. Keys can have lifetimes set. If their lifetime is exceeded,
 	 they traverse to this state. An expired key can be updated back to a
 	 normal state.
 
-     (*) Revoked. A key is put in this state by userspace action. It can't be
+      *  Revoked. A key is put in this state by userspace action. It can't be
 	 found or operated upon (apart from by unlinking it).
 
-     (*) Dead. The key's type was unregistered, and so the key is now useless.
+      *  Dead. The key's type was unregistered, and so the key is now useless.
 
 Keys in the last three states are subject to garbage collection.  See the
 section on "Garbage collection".
 
 
-====================
-KEY SERVICE OVERVIEW
+Key Service Overview
 ====================
 
 The key service provides a number of features besides keys:
 
- (*) The key service defines three special key types:
+  *  The key service defines three special key types:
 
      (+) "keyring"
 
@@ -149,7 +147,7 @@ The key service provides a number of features besides keys:
 	 be created and updated from userspace, but the payload is only
 	 readable from kernel space.
 
- (*) Each process subscribes to three keyrings: a thread-specific keyring, a
+  *  Each process subscribes to three keyrings: a thread-specific keyring, a
      process-specific keyring, and a session-specific keyring.
 
      The thread-specific keyring is discarded from the child when any sort of
@@ -170,7 +168,7 @@ The key service provides a number of features besides keys:
      The ownership of the thread keyring changes when the real UID and GID of
      the thread changes.
 
- (*) Each user ID resident in the system holds two special keyrings: a user
+  *  Each user ID resident in the system holds two special keyrings: a user
      specific keyring and a default user session keyring. The default session
      keyring is initialised with a link to the user-specific keyring.
 
@@ -180,7 +178,7 @@ The key service provides a number of features besides keys:
      If a process attempts to access its session key when it doesn't have one,
      it will be subscribed to the default for its current UID.
 
- (*) Each user has two quotas against which the keys they own are tracked. One
+  *  Each user has two quotas against which the keys they own are tracked. One
      limits the total number of keys and keyrings, the other limits the total
      amount of description and payload space that can be consumed.
 
@@ -194,54 +192,53 @@ The key service provides a number of features besides keys:
      If a system call that modifies a key or keyring in some way would put the
      user over quota, the operation is refused and error EDQUOT is returned.
 
- (*) There's a system call interface by which userspace programs can create and
+  *  There's a system call interface by which userspace programs can create and
      manipulate keys and keyrings.
 
- (*) There's a kernel interface by which services can register types and search
+  *  There's a kernel interface by which services can register types and search
      for keys.
 
- (*) There's a way for the a search done from the kernel to call back to
+  *  There's a way for the a search done from the kernel to call back to
      userspace to request a key that can't be found in a process's keyrings.
 
- (*) An optional filesystem is available through which the key database can be
+  *  An optional filesystem is available through which the key database can be
      viewed and manipulated.
 
 
-======================
-KEY ACCESS PERMISSIONS
+Key Access Permissions
 ======================
 
 Keys have an owner user ID, a group access ID, and a permissions mask. The mask
 has up to eight bits each for possessor, user, group and other access. Only
 six of each set of eight bits are defined. These permissions granted are:
 
- (*) View
+  *  View
 
      This permits a key or keyring's attributes to be viewed - including key
      type and description.
 
- (*) Read
+  *  Read
 
      This permits a key's payload to be viewed or a keyring's list of linked
      keys.
 
- (*) Write
+  *  Write
 
      This permits a key's payload to be instantiated or updated, or it allows a
      link to be added to or removed from a keyring.
 
- (*) Search
+  *  Search
 
      This permits keyrings to be searched and keys to be found. Searches can
      only recurse into nested keyrings that have search permission set.
 
- (*) Link
+  *  Link
 
      This permits a key or keyring to be linked to. To create a link from a
      keyring to a key, a process must have Write permission on the keyring and
      Link permission on the key.
 
- (*) Set Attribute
+  *  Set Attribute
 
      This permits a key's UID, GID and permissions mask to be changed.
 
@@ -249,8 +246,7 @@ For changing the ownership, group ID or permissions mask, being the owner of
 the key or having the sysadmin capability is sufficient.
 
 
-===============
-SELINUX SUPPORT
+SELinux Support
 ===============
 
 The security class "key" has been added to SELinux so that mandatory access
@@ -282,14 +278,13 @@ their associated thread, and both session and process keyrings are handled
 similarly.
 
 
-================
-NEW PROCFS FILES
+New ProcFS Files
 ================
 
 Two files have been added to procfs by which an administrator can find out
 about the status of the key service:
 
- (*) /proc/keys
+  *  /proc/keys
 
      This lists the keys that are currently viewable by the task reading the
      file, giving information about their type, description and permissions.
@@ -301,7 +296,7 @@ about the status of the key service:
      security checks are still performed, and may further filter out keys that
      the current process is not authorised to view.
 
-     The contents of the file look like this:
+     The contents of the file look like this::
 
 	SERIAL   FLAGS  USAGE EXPY PERM     UID   GID   TYPE      DESCRIPTION: SUMMARY
 	00000001 I-----    39 perm 1f3f0000     0     0 keyring   _uid_ses.0: 1/4
@@ -314,7 +309,7 @@ about the status of the key service:
 	00000893 I--Q-N     1  35s 1f3f0000     0     0 user      metal:silver: 0
 	00000894 I--Q--     1  10h 003f0000     0     0 user      metal:gold: 0
 
-     The flags are:
+     The flags are::
 
 	I	Instantiated
 	R	Revoked
@@ -324,10 +319,10 @@ about the status of the key service:
 	N	Negative key
 
 
- (*) /proc/key-users
+  *  /proc/key-users
 
      This file lists the tracking data for each user that has at least one key
-     on the system.  Such data includes quota information and statistics:
+     on the system.  Such data includes quota information and statistics::
 
 	[root@andromeda root]# cat /proc/key-users
 	0:     46 45/45 1/100 13/10000
@@ -335,7 +330,8 @@ about the status of the key service:
 	32:     2 2/2 2/100 40/10000
 	38:     2 2/2 2/100 40/10000
 
-     The format of each line is
+     The format of each line is::
+
 	<UID>:			User ID to which this applies
 	<usage>			Structure refcount
 	<inst>/<keys>		Total number of keys and number instantiated
@@ -346,14 +342,14 @@ about the status of the key service:
 Four new sysctl files have been added also for the purpose of controlling the
 quota limits on keys:
 
- (*) /proc/sys/kernel/keys/root_maxkeys
+  *  /proc/sys/kernel/keys/root_maxkeys
      /proc/sys/kernel/keys/root_maxbytes
 
      These files hold the maximum number of keys that root may have and the
      maximum total number of bytes of data that root may have stored in those
      keys.
 
- (*) /proc/sys/kernel/keys/maxkeys
+  *  /proc/sys/kernel/keys/maxkeys
      /proc/sys/kernel/keys/maxbytes
 
      These files hold the maximum number of keys that each non-root user may
@@ -364,8 +360,7 @@ Root may alter these by writing each new limit as a decimal number string to
 the appropriate file.
 
 
-===============================
-USERSPACE SYSTEM CALL INTERFACE
+Userspace System Call Interface
 ===============================
 
 Userspace can manipulate keys directly through three new syscalls: add_key,
@@ -375,7 +370,7 @@ manipulating keys.
 When referring to a key directly, userspace programs should use the key's
 serial number (a positive 32-bit integer). However, there are some special
 values available for referring to special keys and keyrings that relate to the
-process making the call:
+process making the call::
 
 	CONSTANT			VALUE	KEY REFERENCED
 	==============================	======	===========================
@@ -391,8 +386,8 @@ process making the call:
 
 The main syscalls are:
 
- (*) Create a new key of given type, description and payload and add it to the
-     nominated keyring:
+  *  Create a new key of given type, description and payload and add it to the
+     nominated keyring::
 
 	key_serial_t add_key(const char *type, const char *desc,
 			     const void *payload, size_t plen,
@@ -432,8 +427,8 @@ The main syscalls are:
      The ID of the new or updated key is returned if successful.
 
 
- (*) Search the process's keyrings for a key, potentially calling out to
-     userspace to create it.
+  *  Search the process's keyrings for a key, potentially calling out to
+     userspace to create it::
 
 	key_serial_t request_key(const char *type, const char *description,
 				 const char *callout_info,
@@ -453,7 +448,7 @@ The main syscalls are:
 
 The keyctl syscall functions are:
 
- (*) Map a special key ID to a real key ID for this process:
+  *  Map a special key ID to a real key ID for this process::
 
 	key_serial_t keyctl(KEYCTL_GET_KEYRING_ID, key_serial_t id,
 			    int create);
@@ -466,7 +461,7 @@ The keyctl syscall functions are:
      non-zero; and the error ENOKEY will be returned if "create" is zero.
 
 
- (*) Replace the session keyring this process subscribes to with a new one:
+  *  Replace the session keyring this process subscribes to with a new one::
 
 	key_serial_t keyctl(KEYCTL_JOIN_SESSION_KEYRING, const char *name);
 
@@ -484,7 +479,7 @@ The keyctl syscall functions are:
      The ID of the new session keyring is returned if successful.
 
 
- (*) Update the specified key:
+  *  Update the specified key::
 
 	long keyctl(KEYCTL_UPDATE, key_serial_t key, const void *payload,
 		    size_t plen);
@@ -498,7 +493,7 @@ The keyctl syscall functions are:
      add_key().
 
 
- (*) Revoke a key:
+  *  Revoke a key::
 
 	long keyctl(KEYCTL_REVOKE, key_serial_t key);
 
@@ -507,7 +502,7 @@ The keyctl syscall functions are:
      be findable.
 
 
- (*) Change the ownership of a key:
+  *  Change the ownership of a key::
 
 	long keyctl(KEYCTL_CHOWN, key_serial_t key, uid_t uid, gid_t gid);
 
@@ -520,7 +515,7 @@ The keyctl syscall functions are:
      its group list members.
 
 
- (*) Change the permissions mask on a key:
+  *  Change the permissions mask on a key::
 
 	long keyctl(KEYCTL_SETPERM, key_serial_t key, key_perm_t perm);
 
@@ -531,7 +526,7 @@ The keyctl syscall functions are:
      error EINVAL will be returned.
 
 
- (*) Describe a key:
+  *  Describe a key::
 
 	long keyctl(KEYCTL_DESCRIBE, key_serial_t key, char *buffer,
 		    size_t buflen);
@@ -547,7 +542,7 @@ The keyctl syscall functions are:
      A process must have view permission on the key for this function to be
      successful.
 
-     If successful, a string is placed in the buffer in the following format:
+     If successful, a string is placed in the buffer in the following format::
 
 	<type>;<uid>;<gid>;<perm>;<description>
 
@@ -555,12 +550,12 @@ The keyctl syscall functions are:
      is hexadecimal. A NUL character is included at the end of the string if
      the buffer is sufficiently big.
 
-     This can be parsed with
+     This can be parsed with::
 
 	sscanf(buffer, "%[^;];%d;%d;%o;%s", type, &uid, &gid, &mode, desc);
 
 
- (*) Clear out a keyring:
+  *  Clear out a keyring::
 
 	long keyctl(KEYCTL_CLEAR, key_serial_t keyring);
 
@@ -573,7 +568,7 @@ The keyctl syscall functions are:
      DNS resolver cache keyring is an example of this.
 
 
- (*) Link a key into a keyring:
+  *  Link a key into a keyring::
 
 	long keyctl(KEYCTL_LINK, key_serial_t keyring, key_serial_t key);
 
@@ -592,7 +587,7 @@ The keyctl syscall functions are:
      added.
 
 
- (*) Unlink a key or keyring from another keyring:
+  *  Unlink a key or keyring from another keyring::
 
 	long keyctl(KEYCTL_UNLINK, key_serial_t keyring, key_serial_t key);
 
@@ -604,7 +599,7 @@ The keyctl syscall functions are:
      is not present, error ENOENT will be the result.
 
 
- (*) Search a keyring tree for a key:
+  *  Search a keyring tree for a key::
 
 	key_serial_t keyctl(KEYCTL_SEARCH, key_serial_t keyring,
 			    const char *type, const char *description,
@@ -628,7 +623,7 @@ The keyctl syscall functions are:
      fails. On success, the resulting key ID will be returned.
 
 
- (*) Read the payload data from a key:
+  *  Read the payload data from a key::
 
 	long keyctl(KEYCTL_READ, key_serial_t keyring, char *buffer,
 		    size_t buflen);
@@ -650,7 +645,7 @@ The keyctl syscall functions are:
      available rather than the amount copied.
 
 
- (*) Instantiate a partially constructed key.
+  *  Instantiate a partially constructed key::
 
 	long keyctl(KEYCTL_INSTANTIATE, key_serial_t key,
 		    const void *payload, size_t plen,
@@ -677,7 +672,7 @@ The keyctl syscall functions are:
      array instead of a single buffer.
 
 
- (*) Negatively instantiate a partially constructed key.
+  *  Negatively instantiate a partially constructed key::
 
 	long keyctl(KEYCTL_NEGATE, key_serial_t key,
 		    unsigned timeout, key_serial_t keyring);
@@ -700,12 +695,12 @@ The keyctl syscall functions are:
      as rejecting the key with ENOKEY as the error code.
 
 
- (*) Set the default request-key destination keyring.
+  *  Set the default request-key destination keyring::
 
 	long keyctl(KEYCTL_SET_REQKEY_KEYRING, int reqkey_defl);
 
      This sets the default keyring to which implicitly requested keys will be
-     attached for this thread. reqkey_defl should be one of these constants:
+     attached for this thread. reqkey_defl should be one of these constants::
 
 	CONSTANT				VALUE	NEW DEFAULT KEYRING
 	======================================	======	=======================
@@ -731,7 +726,7 @@ The keyctl syscall functions are:
      there is one, otherwise the user default session keyring.
 
 
- (*) Set the timeout on a key.
+  *  Set the timeout on a key::
 
 	long keyctl(KEYCTL_SET_TIMEOUT, key_serial_t key, unsigned timeout);
 
@@ -744,7 +739,7 @@ The keyctl syscall functions are:
      or expired keys.
 
 
- (*) Assume the authority granted to instantiate a key
+  *  Assume the authority granted to instantiate a key::
 
 	long keyctl(KEYCTL_ASSUME_AUTHORITY, key_serial_t key);
 
@@ -766,7 +761,7 @@ The keyctl syscall functions are:
      The assumed authoritative key is inherited across fork and exec.
 
 
- (*) Get the LSM security context attached to a key.
+  *  Get the LSM security context attached to a key::
 
 	long keyctl(KEYCTL_GET_SECURITY, key_serial_t key, char *buffer,
 		    size_t buflen)
@@ -787,7 +782,7 @@ The keyctl syscall functions are:
      successful.
 
 
- (*) Install the calling process's session keyring on its parent.
+  *  Install the calling process's session keyring on its parent::
 
 	long keyctl(KEYCTL_SESSION_TO_PARENT);
 
@@ -807,7 +802,7 @@ The keyctl syscall functions are:
      kernel and resumes executing userspace.
 
 
- (*) Invalidate a key.
+  *  Invalidate a key::
 
 	long keyctl(KEYCTL_INVALIDATE, key_serial_t key);
 
@@ -823,20 +818,19 @@ The keyctl syscall functions are:
      A process must have search permission on the key for this function to be
      successful.
 
- (*) Compute a Diffie-Hellman shared secret or public key
+  *  Compute a Diffie-Hellman shared secret or public key::
 
-       long keyctl(KEYCTL_DH_COMPUTE, struct keyctl_dh_params *params,
-		   char *buffer, size_t buflen,
-		   struct keyctl_kdf_params *kdf);
+	long keyctl(KEYCTL_DH_COMPUTE, struct keyctl_dh_params *params,
+		    char *buffer, size_t buflen, struct keyctl_kdf_params *kdf);
 
-     The params struct contains serial numbers for three keys:
+     The params struct contains serial numbers for three keys::
 
 	 - The prime, p, known to both parties
 	 - The local private key
 	 - The base integer, which is either a shared generator or the
 	   remote public key
 
-     The value computed is:
+     The value computed is::
 
 	result = base ^ private (mod prime)
 
@@ -858,12 +852,12 @@ The keyctl syscall functions are:
      of the KDF is returned to the caller. The KDF is characterized with
      struct keyctl_kdf_params as follows:
 
-	 - char *hashname specifies the NUL terminated string identifying
+	 - ``char *hashname`` specifies the NUL terminated string identifying
 	   the hash used from the kernel crypto API and applied for the KDF
 	   operation. The KDF implemenation complies with SP800-56A as well
 	   as with SP800-108 (the counter KDF).
 
-	 - char *otherinfo specifies the OtherInfo data as documented in
+	 - ``char *otherinfo`` specifies the OtherInfo data as documented in
 	   SP800-56A section 5.8.1.2. The length of the buffer is given with
 	   otherinfolen. The format of OtherInfo is defined by the caller.
 	   The otherinfo pointer may be NULL if no OtherInfo shall be used.
@@ -875,10 +869,10 @@ The keyctl syscall functions are:
      and either the buffer length or the OtherInfo length exceeds the
      allowed length.
 
- (*) Restrict keyring linkage
+  *  Restrict keyring linkage::
 
-       long keyctl(KEYCTL_RESTRICT_KEYRING, key_serial_t keyring,
-		   const char *type, const char *restriction);
+	long keyctl(KEYCTL_RESTRICT_KEYRING, key_serial_t keyring,
+		    const char *type, const char *restriction);
 
      An existing keyring can restrict linkage of additional keys by evaluating
      the contents of the key according to a restriction scheme.
@@ -900,8 +894,7 @@ The keyctl syscall functions are:
      To apply a keyring restriction the process must have Set Attribute
      permission and the keyring must not be previously restricted.
 
-===============
-KERNEL SERVICES
+Kernel Services
 ===============
 
 The kernel services for key management are fairly simple to deal with. They can
@@ -915,29 +908,29 @@ call, and the key released upon close. How to deal with conflicting keys due to
 two different users opening the same file is left to the filesystem author to
 solve.
 
-To access the key manager, the following header must be #included:
+To access the key manager, the following header must be #included::
 
 	<linux/key.h>
 
 Specific key types should have a header file under include/keys/ that should be
-used to access that type.  For keys of type "user", for example, that would be:
+used to access that type.  For keys of type "user", for example, that would be::
 
 	<keys/user-type.h>
 
 Note that there are two different types of pointers to keys that may be
 encountered:
 
- (*) struct key *
+  *  struct key *
 
      This simply points to the key structure itself. Key structures will be at
      least four-byte aligned.
 
- (*) key_ref_t
+  *  key_ref_t
 
-     This is equivalent to a struct key *, but the least significant bit is set
+     This is equivalent to a ``struct key *``, but the least significant bit is set
      if the caller "possesses" the key. By "possession" it is meant that the
      calling processes has a searchable link to the key from one of its
-     keyrings. There are three functions for dealing with these:
+     keyrings. There are three functions for dealing with these::
 
 	key_ref_t make_key_ref(const struct key *key, bool possession);
 
@@ -955,7 +948,7 @@ When accessing a key's payload contents, certain precautions must be taken to
 prevent access vs modification races. See the section "Notes on accessing
 payload contents" for more information.
 
-(*) To search for a key, call:
+ *  To search for a key, call::
 
 	struct key *request_key(const struct key_type *type,
 				const char *description,
@@ -977,7 +970,7 @@ payload contents" for more information.
     See also Documentation/security/keys-request-key.txt.
 
 
-(*) To search for a key, passing auxiliary data to the upcaller, call:
+ *  To search for a key, passing auxiliary data to the upcaller, call::
 
 	struct key *request_key_with_auxdata(const struct key_type *type,
 					     const char *description,
@@ -990,14 +983,14 @@ payload contents" for more information.
     is a blob of length callout_len, if given (the length may be 0).
 
 
-(*) A key can be requested asynchronously by calling one of:
+ *  A key can be requested asynchronously by calling one of::
 
 	struct key *request_key_async(const struct key_type *type,
 				      const char *description,
 				      const void *callout_info,
 				      size_t callout_len);
 
-    or:
+    or::
 
 	struct key *request_key_async_with_auxdata(const struct key_type *type,
 						   const char *description,
@@ -1010,7 +1003,7 @@ payload contents" for more information.
 
     These two functions return with the key potentially still under
     construction.  To wait for construction completion, the following should be
-    called:
+    called::
 
 	int wait_for_key_construction(struct key *key, bool intr);
 
@@ -1022,11 +1015,11 @@ payload contents" for more information.
     case error ERESTARTSYS will be returned.
 
 
-(*) When it is no longer required, the key should be released using:
+ *  When it is no longer required, the key should be released using::
 
 	void key_put(struct key *key);
 
-    Or:
+    Or::
 
 	void key_ref_put(key_ref_t key_ref);
 
@@ -1034,8 +1027,8 @@ payload contents" for more information.
     the argument will not be parsed.
 
 
-(*) Extra references can be made to a key by calling one of the following
-    functions:
+ *  Extra references can be made to a key by calling one of the following
+    functions::
 
 	struct key *__key_get(struct key *key);
 	struct key *key_get(struct key *key);
@@ -1047,7 +1040,7 @@ payload contents" for more information.
     then the key will not be dereferenced and no increment will take place.
 
 
-(*) A key's serial number can be obtained by calling:
+ *  A key's serial number can be obtained by calling::
 
 	key_serial_t key_serial(struct key *key);
 
@@ -1055,7 +1048,7 @@ payload contents" for more information.
     latter case without parsing the argument).
 
 
-(*) If a keyring was found in the search, this can be further searched by:
+ *  If a keyring was found in the search, this can be further searched by::
 
 	key_ref_t keyring_search(key_ref_t keyring_ref,
 				 const struct key_type *type,
@@ -1070,7 +1063,7 @@ payload contents" for more information.
     reference pointer if successful.
 
 
-(*) A keyring can be created by:
+ *  A keyring can be created by::
 
 	struct key *keyring_alloc(const char *description, uid_t uid, gid_t gid,
 				  const struct cred *cred,
@@ -1109,7 +1102,7 @@ payload contents" for more information.
     -EPERM to in this case.
 
 
-(*) To check the validity of a key, this function can be called:
+ *  To check the validity of a key, this function can be called::
 
 	int validate_key(struct key *key);
 
@@ -1119,7 +1112,7 @@ payload contents" for more information.
     returned (in the latter case without parsing the argument).
 
 
-(*) To register a key type, the following function should be called:
+ *  To register a key type, the following function should be called::
 
 	int register_key_type(struct key_type *type);
 
@@ -1127,13 +1120,13 @@ payload contents" for more information.
     present.
 
 
-(*) To unregister a key type, call:
+ *  To unregister a key type, call::
 
 	void unregister_key_type(struct key_type *type);
 
 
 Under some circumstances, it may be desirable to deal with a bundle of keys.
-The facility provides access to the keyring type for managing such a bundle:
+The facility provides access to the keyring type for managing such a bundle::
 
 	struct key_type key_type_keyring;
 
@@ -1143,8 +1136,7 @@ with keyring_search().  Note that it is not possible to use request_key() to
 search a specific keyring, so using keyrings in this way is of limited utility.
 
 
-===================================
-NOTES ON ACCESSING PAYLOAD CONTENTS
+Notes On Accessing Payload Contents
 ===================================
 
 The simplest payload is just data stored in key->payload directly.  In this
@@ -1154,31 +1146,31 @@ More complex payload contents must be allocated and pointers to them set in the
 key->payload.data[] array.  One of the following ways must be selected to
 access the data:
 
- (1) Unmodifiable key type.
+  1) Unmodifiable key type.
 
      If the key type does not have a modify method, then the key's payload can
      be accessed without any form of locking, provided that it's known to be
      instantiated (uninstantiated keys cannot be "found").
 
- (2) The key's semaphore.
+  2) The key's semaphore.
 
      The semaphore could be used to govern access to the payload and to control
      the payload pointer. It must be write-locked for modifications and would
      have to be read-locked for general access. The disadvantage of doing this
      is that the accessor may be required to sleep.
 
- (3) RCU.
+  3) RCU.
 
      RCU must be used when the semaphore isn't already held; if the semaphore
      is held then the contents can't change under you unexpectedly as the
      semaphore must still be used to serialise modifications to the key. The
      key management code takes care of this for the key type.
 
-     However, this means using:
+     However, this means using::
 
 	rcu_read_lock() ... rcu_dereference() ... rcu_read_unlock()
 
-     to read the pointer, and:
+     to read the pointer, and::
 
 	rcu_dereference() ... rcu_assign_pointer() ... call_rcu()
 
@@ -1194,11 +1186,11 @@ access the data:
      usage.  This is called key->payload.rcu_data0.  The following accessors
      wrap the RCU calls to this element:
 
-     (a) Set or change the first payload pointer:
+     a) Set or change the first payload pointer::
 
 		rcu_assign_keypointer(struct key *key, void *data);
 
-     (b) Read the first payload pointer with the key semaphore held:
+     b) Read the first payload pointer with the key semaphore held::
 
 		[const] void *dereference_key_locked([const] struct key *key);
 
@@ -1206,39 +1198,38 @@ access the data:
 	 parameter.  Static analysis will give an error if it things the lock
 	 isn't held.
 
-     (c) Read the first payload pointer with the RCU read lock held:
+     c) Read the first payload pointer with the RCU read lock held::
 
 		const void *dereference_key_rcu(const struct key *key);
 
 
-===================
-DEFINING A KEY TYPE
+Defining a Key Type
 ===================
 
 A kernel service may want to define its own key type. For instance, an AFS
 filesystem might want to define a Kerberos 5 ticket key type. To do this, it
 author fills in a key_type struct and registers it with the system.
 
-Source files that implement key types should include the following header file:
+Source files that implement key types should include the following header file::
 
 	<linux/key-type.h>
 
 The structure has a number of fields, some of which are mandatory:
 
- (*) const char *name
+  *  ``const char *name``
 
      The name of the key type. This is used to translate a key type name
      supplied by userspace into a pointer to the structure.
 
 
- (*) size_t def_datalen
+  *  ``size_t def_datalen``
 
      This is optional - it supplies the default payload data length as
      contributed to the quota. If the key type's payload is always or almost
      always the same size, then this is a more efficient way to do things.
 
      The data length (and quota) on a particular key can always be changed
-     during instantiation or update by calling:
+     during instantiation or update by calling::
 
 	int key_payload_reserve(struct key *key, size_t datalen);
 
@@ -1246,18 +1237,18 @@ The structure has a number of fields, some of which are mandatory:
      viable.
 
 
- (*) int (*vet_description)(const char *description);
+  *  ``int (*vet_description)(const char *description);``
 
      This optional method is called to vet a key description.  If the key type
      doesn't approve of the key description, it may return an error, otherwise
      it should return 0.
 
 
- (*) int (*preparse)(struct key_preparsed_payload *prep);
+  *  ``int (*preparse)(struct key_preparsed_payload *prep);``
 
      This optional method permits the key type to attempt to parse payload
      before a key is created (add key) or the key semaphore is taken (update or
-     instantiate key).  The structure pointed to by prep looks like:
+     instantiate key).  The structure pointed to by prep looks like::
 
 	struct key_preparsed_payload {
 		char		*description;
@@ -1285,7 +1276,7 @@ The structure has a number of fields, some of which are mandatory:
      otherwise.
 
 
- (*) void (*free_preparse)(struct key_preparsed_payload *prep);
+  *  ``void (*free_preparse)(struct key_preparsed_payload *prep);``
 
      This method is only required if the preparse() method is provided,
      otherwise it is unused.  It cleans up anything attached to the description
@@ -1294,7 +1285,7 @@ The structure has a number of fields, some of which are mandatory:
      successfully, even if instantiate() or update() succeed.
 
 
- (*) int (*instantiate)(struct key *key, struct key_preparsed_payload *prep);
+  *  ``int (*instantiate)(struct key *key, struct key_preparsed_payload *prep);``
 
      This method is called to attach a payload to a key during construction.
      The payload attached need not bear any relation to the data passed to this
@@ -1318,7 +1309,7 @@ The structure has a number of fields, some of which are mandatory:
      free_preparse method doesn't release the data.
 
 
- (*) int (*update)(struct key *key, const void *data, size_t datalen);
+  *  ``int (*update)(struct key *key, const void *data, size_t datalen);``
 
      If this type of key can be updated, then this method should be provided.
      It is called to update a key's payload from the blob of data provided.
@@ -1343,10 +1334,10 @@ The structure has a number of fields, some of which are mandatory:
      It is safe to sleep in this method.
 
 
- (*) int (*match_preparse)(struct key_match_data *match_data);
+  *  ``int (*match_preparse)(struct key_match_data *match_data);``
 
      This method is optional.  It is called when a key search is about to be
-     performed.  It is given the following structure:
+     performed.  It is given the following structure::
 
 	struct key_match_data {
 		bool (*cmp)(const struct key *key,
@@ -1357,23 +1348,23 @@ The structure has a number of fields, some of which are mandatory:
 	};
 
      On entry, raw_data will be pointing to the criteria to be used in matching
-     a key by the caller and should not be modified.  (*cmp)() will be pointing
+     a key by the caller and should not be modified.  ``(*cmp)()`` will be pointing
      to the default matcher function (which does an exact description match
      against raw_data) and lookup_type will be set to indicate a direct lookup.
 
      The following lookup_type values are available:
 
-      [*] KEYRING_SEARCH_LOOKUP_DIRECT - A direct lookup hashes the type and
+       *  KEYRING_SEARCH_LOOKUP_DIRECT - A direct lookup hashes the type and
       	  description to narrow down the search to a small number of keys.
 
-      [*] KEYRING_SEARCH_LOOKUP_ITERATE - An iterative lookup walks all the
+       *  KEYRING_SEARCH_LOOKUP_ITERATE - An iterative lookup walks all the
       	  keys in the keyring until one is matched.  This must be used for any
       	  search that's not doing a simple direct match on the key description.
 
      The method may set cmp to point to a function of its choice that does some
      other form of match, may set lookup_type to KEYRING_SEARCH_LOOKUP_ITERATE
-     and may attach something to the preparsed pointer for use by (*cmp)().
-     (*cmp)() should return true if a key matches and false otherwise.
+     and may attach something to the preparsed pointer for use by ``(*cmp)()``.
+     ``(*cmp)()`` should return true if a key matches and false otherwise.
 
      If preparsed is set, it may be necessary to use the match_free() method to
      clean it up.
@@ -1381,20 +1372,20 @@ The structure has a number of fields, some of which are mandatory:
      The method should return 0 if successful or a negative error code
      otherwise.
 
-     It is permitted to sleep in this method, but (*cmp)() may not sleep as
+     It is permitted to sleep in this method, but ``(*cmp)()`` may not sleep as
      locks will be held over it.
 
      If match_preparse() is not provided, keys of this type will be matched
      exactly by their description.
 
 
- (*) void (*match_free)(struct key_match_data *match_data);
+  *  ``void (*match_free)(struct key_match_data *match_data);``
 
      This method is optional.  If given, it called to clean up
      match_data->preparsed after a successful call to match_preparse().
 
 
- (*) void (*revoke)(struct key *key);
+  *  ``void (*revoke)(struct key *key);``
 
      This method is optional.  It is called to discard part of the payload
      data upon a key being revoked.  The caller will have the key semaphore
@@ -1404,7 +1395,7 @@ The structure has a number of fields, some of which are mandatory:
      a deadlock against the key semaphore.
 
 
- (*) void (*destroy)(struct key *key);
+  *  ``void (*destroy)(struct key *key);``
 
      This method is optional. It is called to discard the payload data on a key
      when it is being destroyed.
@@ -1416,7 +1407,7 @@ The structure has a number of fields, some of which are mandatory:
      It is not safe to sleep in this method; the caller may hold spinlocks.
 
 
- (*) void (*describe)(const struct key *key, struct seq_file *p);
+  *  ``void (*describe)(const struct key *key, struct seq_file *p);``
 
      This method is optional. It is called during /proc/keys reading to
      summarise a key's description and payload in text form.
@@ -1432,7 +1423,7 @@ The structure has a number of fields, some of which are mandatory:
      caller.
 
 
- (*) long (*read)(const struct key *key, char __user *buffer, size_t buflen);
+  *  ``long (*read)(const struct key *key, char __user *buffer, size_t buflen);``
 
      This method is optional. It is called by KEYCTL_READ to translate the
      key's payload into something a blob of data for userspace to deal with.
@@ -1448,8 +1439,7 @@ The structure has a number of fields, some of which are mandatory:
      as might happen when the userspace buffer is accessed.
 
 
- (*) int (*request_key)(struct key_construction *cons, const char *op,
-			void *aux);
+  *  ``int (*request_key)(struct key_construction *cons, const char *op, void *aux);``
 
      This method is optional.  If provided, request_key() and friends will
      invoke this function rather than upcalling to /sbin/request-key to operate
@@ -1463,7 +1453,7 @@ The structure has a number of fields, some of which are mandatory:
      This method is permitted to return before the upcall is complete, but the
      following function must be called under all circumstances to complete the
      instantiation process, whether or not it succeeds, whether or not there's
-     an error:
+     an error::
 
 	void complete_request_key(struct key_construction *cons, int error);
 
@@ -1479,16 +1469,16 @@ The structure has a number of fields, some of which are mandatory:
      The key under construction and the authorisation key can be found in the
      key_construction struct pointed to by cons:
 
-     (*) struct key *key;
+      *  ``struct key *key;``
 
      	 The key under construction.
 
-     (*) struct key *authkey;
+      *  ``struct key *authkey;``
 
      	 The authorisation key.
 
 
- (*) struct key_restriction *(*lookup_restriction)(const char *params);
+  *  ``struct key_restriction *(*lookup_restriction)(const char *params);``
 
      This optional method is used to enable userspace configuration of keyring
      restrictions. The restriction parameter string (not including the key type
@@ -1497,12 +1487,11 @@ The structure has a number of fields, some of which are mandatory:
      attempted key link operation. If there is no match, -EINVAL is returned.
 
 
-============================
-REQUEST-KEY CALLBACK SERVICE
+Request-Key Callback Service
 ============================
 
 To create a new key, the kernel will attempt to execute the following command
-line:
+line::
 
 	/sbin/request-key create <key> <uid> <gid> \
 		<threadring> <processring> <sessionring> <callout_info>
@@ -1511,10 +1500,10 @@ line:
 keyrings from the process that caused the search to be issued. These are
 included for two reasons:
 
-  (1) There may be an authentication token in one of the keyrings that is
+   1  There may be an authentication token in one of the keyrings that is
       required to obtain the key, eg: a Kerberos Ticket-Granting Ticket.
 
-  (2) The new key should probably be cached in one of these rings.
+   2  The new key should probably be cached in one of these rings.
 
 This program should set it UID and GID to those specified before attempting to
 access any more keys. It may then look around for a user specific process to
@@ -1539,7 +1528,7 @@ instead.
 
 
 Similarly, the kernel may attempt to update an expired or a soon to expire key
-by executing:
+by executing::
 
 	/sbin/request-key update <key> <uid> <gid> \
 		<threadring> <processring> <sessionring>
@@ -1548,8 +1537,7 @@ In this case, the program isn't required to actually attach the key to a ring;
 the rings are provided for reference.
 
 
-==================
-GARBAGE COLLECTION
+Garbage Collection
 ==================
 
 Dead keys (for which the type has been removed) will be automatically unlinked
@@ -1557,6 +1545,6 @@ from those keyrings that point to them and deleted as soon as possible by a
 background garbage collector.
 
 Similarly, revoked and expired keys will be garbage collected, but only after a
-certain amount of time has passed.  This time is set as a number of seconds in:
+certain amount of time has passed.  This time is set as a number of seconds in::
 
 	/proc/sys/kernel/keys/gc_delay
diff --git a/Documentation/security/keys/index.rst b/Documentation/security/keys/index.rst
new file mode 100644
index 000000000000..ddfe7e4726e6
--- /dev/null
+++ b/Documentation/security/keys/index.rst
@@ -0,0 +1,8 @@
+===========
+Kernel Keys
+===========
+
+.. toctree::
+   :maxdepth: 1
+
+   core
diff --git a/MAINTAINERS b/MAINTAINERS
index 3e78b5c9b3f9..3973e25e5aca 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -7342,7 +7342,7 @@ KEYS/KEYRINGS:
 M:	David Howells <dhowells@redhat.com>
 L:	keyrings@vger.kernel.org
 S:	Maintained
-F:	Documentation/security/keys.txt
+F:	Documentation/security/keys/core.rst
 F:	include/linux/key.h
 F:	include/linux/key-type.h
 F:	include/linux/keyctl.h
diff --git a/include/linux/key.h b/include/linux/key.h
index 0c9b93b0d1f7..24dfe6c1f8cb 100644
--- a/include/linux/key.h
+++ b/include/linux/key.h
@@ -9,7 +9,7 @@
  * 2 of the License, or (at your option) any later version.
  *
  *
- * See Documentation/security/keys.txt for information on keys/keyrings.
+ * See Documentation/security/keys/core.rst for information on keys/keyrings.
  */
 
 #ifndef _LINUX_KEY_H
-- 
2.7.4

[PATCH 15/17] doc: ReSTify keys-ecryptfs.txt

[Kees Cook]

Adjusts for ReST markup and moves under keys security devel index.

Cc: David Howells <dhowells@redhat.com>
Cc: Tyler Hicks <tyhicks@canonical.com>
Signed-off-by: Kees Cook <keescook@chromium.org>
---
 Documentation/security/00-INDEX                       |  2 --
 .../security/{keys-ecryptfs.txt => keys/ecryptfs.rst} | 19 ++++++++++++-------
 Documentation/security/keys/index.rst                 |  1 +
 3 files changed, 13 insertions(+), 9 deletions(-)
 rename Documentation/security/{keys-ecryptfs.txt => keys/ecryptfs.rst} (91%)

diff --git a/Documentation/security/00-INDEX b/Documentation/security/00-INDEX
index a840095bb11c..08a6e7a195ef 100644
--- a/Documentation/security/00-INDEX
+++ b/Documentation/security/00-INDEX
@@ -1,7 +1,5 @@
 00-INDEX
 	- this file.
-keys-ecryptfs.txt
-	- description of the encryption keys for the ecryptfs filesystem.
 keys-request-key.txt
 	- description of the kernel key request service.
 keys-trusted-encrypted.txt
diff --git a/Documentation/security/keys-ecryptfs.txt b/Documentation/security/keys/ecryptfs.rst
similarity index 91%
rename from Documentation/security/keys-ecryptfs.txt
rename to Documentation/security/keys/ecryptfs.rst
index c3bbeba63562..4920f3a8ea75 100644
--- a/Documentation/security/keys-ecryptfs.txt
+++ b/Documentation/security/keys/ecryptfs.rst
@@ -1,4 +1,6 @@
-		Encrypted keys for the eCryptfs filesystem
+==========================================
+Encrypted keys for the eCryptfs filesystem
+==========================================
 
 ECryptfs is a stacked filesystem which transparently encrypts and decrypts each
 file using a randomly generated File Encryption Key (FEK).
@@ -35,20 +37,23 @@ controlled environment.  Another advantage is that the key is not exposed to
 threats of malicious software, because it is available in clear form only at
 kernel level.
 
-Usage:
+Usage::
+
    keyctl add encrypted name "new ecryptfs key-type:master-key-name keylen" ring
    keyctl add encrypted name "load hex_blob" ring
    keyctl update keyid "update key-type:master-key-name"
 
-name:= '<16 hexadecimal characters>'
-key-type:= 'trusted' | 'user'
-keylen:= 64
+Where::
+
+	name:= '<16 hexadecimal characters>'
+	key-type:= 'trusted' | 'user'
+	keylen:= 64
 
 
 Example of encrypted key usage with the eCryptfs filesystem:
 
 Create an encrypted key "1000100010001000" of length 64 bytes with format
-'ecryptfs' and save it using a previously loaded user key "test":
+'ecryptfs' and save it using a previously loaded user key "test"::
 
     $ keyctl add encrypted 1000100010001000 "new ecryptfs user:test 64" @u
     19184530
@@ -62,7 +67,7 @@ Create an encrypted key "1000100010001000" of length 64 bytes with format
     $ keyctl pipe 19184530 > ecryptfs.blob
 
 Mount an eCryptfs filesystem using the created encrypted key "1000100010001000"
-into the '/secret' directory:
+into the '/secret' directory::
 
     $ mount -i -t ecryptfs -oecryptfs_sig=1000100010001000,\
       ecryptfs_cipher=aes,ecryptfs_key_bytes=32 /secret /secret
diff --git a/Documentation/security/keys/index.rst b/Documentation/security/keys/index.rst
index ddfe7e4726e6..d34f663354bb 100644
--- a/Documentation/security/keys/index.rst
+++ b/Documentation/security/keys/index.rst
@@ -6,3 +6,4 @@ Kernel Keys
    :maxdepth: 1
 
    core
+   ecryptfs
-- 
2.7.4

[PATCH 16/17] doc: ReSTify keys-request-key.txt

[Kees Cook]

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

[PATCH 17/17] doc: ReSTify keys-trusted-encrypted.txt

[Kees Cook]

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

Re: [PATCH 00/17] convert/reorganize Documentation/security/

[Jonathan Corbet]

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

Re: [PATCH 00/17] convert/reorganize Documentation/security/

[Kees Cook]

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

Re: [PATCH 00/17] convert/reorganize Documentation/security/

[Jonathan Corbet]

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.

I agree with the need for tweaks :)  I fixed up key-request.rst a bit
since I just couldn't stand it.

Anyway, the set is applied, many thanks for doing this!

jon

Re: [PATCH 00/17] convert/reorganize Documentation/security/

[Kees Cook]

On Thu, May 18, 2017 at 9:49 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.
>
> I agree with the need for tweaks :)  I fixed up key-request.rst a bit
> since I just couldn't stand it.
>
> Anyway, the set is applied, many thanks for doing this!

Awesome, thanks for the fixes!

-Kees

-- 
Kees Cook
Pixel Security