Re: [PATCH 09/17] doc: ReSTify apparmor.txt
On 05/13/2017 04:51 AM, Kees Cook wrote:
> Adjusts for ReST markup and moves under LSM admin guide.
>
> Cc: John Johansen
> Signed-off-by: Kees Cook
Acked-by: John Johansen
> ---
> .../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= (where XXX is valid security module), on the
> -kernel's command line
> +``apparmor=0, security=`` (where ```` 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 - appar...@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
> 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 Docume
[PATCH] doc-rst: fixed kernel-doc directives in usb/typec.rst
Even if this file is not yet included in any toctree, it is parsed by Sphinx since it is named '.rst'. This patch fixes the following two ERRORs from Sphinx build: Documentation/usb/typec.rst:116: ERROR: Error in "kernel-doc" directive: invalid option block. .. kernel-doc:: drivers/usb/typec/typec.c :functions: typec_register_cable typec_unregister_cable typec_register_plug typec_unregister_plug Documentation/usb/typec.rst:139: ERROR: Error in "kernel-doc" directive: invalid option block. .. kernel-doc:: drivers/usb/typec/typec.c :functions: typec_set_data_role typec_set_pwr_role typec_set_vconn_role typec_set_pwr_opmode Signed-off-by: Markus Heiser --- Documentation/usb/typec.rst | 6 ++ 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/Documentation/usb/typec.rst b/Documentation/usb/typec.rst index b67a467..8a7249f 100644 --- a/Documentation/usb/typec.rst +++ b/Documentation/usb/typec.rst @@ -114,8 +114,7 @@ the details during registration. The class offers the following API for registering/unregistering cables and their plugs: .. kernel-doc:: drivers/usb/typec/typec.c - :functions: typec_register_cable typec_unregister_cable typec_register_plug - typec_unregister_plug + :functions: typec_register_cable typec_unregister_cable typec_register_plug typec_unregister_plug The class will provide a handle to struct typec_cable and struct typec_plug if the registration is successful, or NULL if it isn't. @@ -137,8 +136,7 @@ during connection of a partner or cable, the port driver must use the following APIs to report it to the class: .. kernel-doc:: drivers/usb/typec/typec.c - :functions: typec_set_data_role typec_set_pwr_role typec_set_vconn_role - typec_set_pwr_opmode + :functions: typec_set_data_role typec_set_pwr_role typec_set_vconn_role typec_set_pwr_opmode Alternate Modes ~~~ -- 2.7.4 -- To unsubscribe from this list: send the line "unsubscribe linux-doc" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
[PATCH] doc-rst: fix inline emphasis in unshare.rst
The asterisk of the pointer is interpreted as a start tag for inline emphasis. Asterisks which are not Sphinx markup need to be quoted in rst-files. This fixes the Sphinx warning: Documentation/userspace-api/unshare.rst:108: WARNING: Inline emphasis start-string without end-string. Signed-off-by: Markus Heiser --- Documentation/userspace-api/unshare.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation/userspace-api/unshare.rst b/Documentation/userspace-api/unshare.rst index 737c192..877e90a 100644 --- a/Documentation/userspace-api/unshare.rst +++ b/Documentation/userspace-api/unshare.rst @@ -107,7 +107,7 @@ the benefits of this new feature can exceed its cost. unshare() reverses sharing that was done using clone(2) system call, so unshare() should have a similar interface as clone(2). That is, -since flags in clone(int flags, void *stack) specifies what should +since flags in clone(int flags, void \*stack) specifies what should be shared, similar flags in unshare(int flags) should specify what should be unshared. Unfortunately, this may appear to invert the meaning of the flags from the way they are used in clone(2). -- 2.7.4 -- To unsubscribe from this list: send the line "unsubscribe linux-doc" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
[PATCH] core-api: remove an unexpected unident
As complained by Sphinx: Documentation/core-api/assoc_array.rst:13: WARNING: Enumerated list ends without a blank line; unexpected unindent. This was already addressed, but not really fixed in 2ba90ccca7. Signed-off-by: Markus Heiser --- Documentation/core-api/assoc_array.rst | 5 - 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/Documentation/core-api/assoc_array.rst b/Documentation/core-api/assoc_array.rst index d83cfff..8231b91 100644 --- a/Documentation/core-api/assoc_array.rst +++ b/Documentation/core-api/assoc_array.rst @@ -10,7 +10,10 @@ properties: 1. Objects are opaque pointers. The implementation does not care where they point (if anywhere) or what they point to (if anything). -.. note:: Pointers to objects _must_ be zero in the least significant bit. + + .. note:: + + Pointers to objects _must_ be zero in the least significant bit. 2. Objects do not need to contain linkage blocks for use by the array. This permits an object to be located in multiple arrays simultaneously. -- 2.7.4 -- To unsubscribe from this list: send the line "unsubscribe linux-doc" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
[PATCH V4] cfg80211: add request id to cfg80211_sched_scan_*() api
Hi Arend,
I guess there is a typo in your kernel-doc comment [1]:
modified include/net/cfg80211.h
@@ -1666,6 +1666,7 @@ struct cfg80211_bss_select_adjust {
* (others are filtered out).
* If ommited, all results are passed.
* @n_match_sets: number of match sets
+ * @results_wk: worker for processing results notification.
-
I'am not familiar with the implementation, but as far as I can see, there
is no results_wk in the struct ... and you added report_results (see below)
which needs a documentation.
* @wiphy: the wiphy this was for
* @dev: the interface
* @scan_start: start time of the scheduled scan
@@ -1726,6 +1727,7 @@ struct cfg80211_sched_scan_request {
struct wiphy *wiphy;
struct net_device *dev;
unsigned long scan_start;
+ bool report_results;
struct rcu_head rcu_head;
u32 owner_nlportid;
bool nl_owner_dead;
@@ -4564,31 +4566,34 @@ void cfg80211_scan_done(struct cfg80211_scan_request
*request,
Here is what I get, when compiling the documentation:
make DOCBOOKS= cleandocs htmldocs
./include/net/cfg80211.h:1738: warning: No description found for parameter
'report_results'
./include/net/cfg80211.h:1738: warning: Excess struct/union/enum/typedef member
'results_wk' description in 'cfg80211_sched_scan_request'
Can you please look at this / Thanks a lot!
-- Markus --
[1] https://www.spinics.net/lists/linux-wireless/msg161889.html--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
[PATCH 03/17] doc: ReSTify IMA-templates.txt
Adjust IMA-templates.txt for ReST markup and add to the index for
security/, under the Kernel API Documentation.
Cc: Mimi Zohar
Signed-off-by: Kees Cook
---
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
-('': description), that can be used to define new template
+``('': 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: [:]digest, where the digest
- prefix is shown only if the hash algorithm is not SHA1 or MD5);
+ algorithm (field format: [:]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 li
[PATCH 04/17] doc: ReSTify credentials.txt
This updates the credentials API documentation to ReST markup and moves
it under the security subsection of kernel API documentation.
Cc: David Howells
Signed-off-by: Kees Cook
---
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
-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 ano
[PATCH 02/17] doc: ReSTify no_new_privs.txt
This updates no_new_privs documentation to ReST markup and adds it to
the user-space API documentation.
Signed-off-by: Kees Cook
---
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 princip
[PATCH 05/17] doc: ReSTify self-protection.txt
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
---
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 trivi
[PATCH 06/17] doc: security: minor cleanups to build kernel-doc
These fixes were needed to parse lsm_hooks.h kernel-doc. More work is
needed, but this is the first step.
Cc: Casey Schaufler
Signed-off-by: Kees Cook
---
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
/**
+ * 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 .
- * @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
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
[PATCH 10/17] doc: ReSTify tomoyo.txt
Adjusts for ReST markup and moves under LSM admin guide.
Cc: Tetsuo Handa
Signed-off-by: Kees Cook
---
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
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
[PATCH 08/17] doc: ReSTify SELinux.txt
Adjusts for ReST markup and moves under LSM admin guide.
Cc: Paul Moore
Signed-off-by: Kees Cook
---
.../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
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
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
[PATCH 07/17] doc: ReSTify and split LSM.txt
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
Signed-off-by: Kees Cook
---
.../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 ..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 4212d
[PATCH 09/17] doc: ReSTify apparmor.txt
Adjusts for ReST markup and moves under LSM admin guide.
Cc: John Johansen
Signed-off-by: Kees Cook
---
.../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= (where XXX is valid security module), on the
-kernel's command line
+``apparmor=0, security=`` (where ```` 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 - appar...@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
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
[PATCH 17/17] doc: ReSTify keys-trusted-encrypted.txt
Adjusts for ReST markup and moves under keys security devel index.
Cc: David Howells
Cc: Mimi Zohar
Signed-off-by: Kees Cook
---
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..
--- 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..
--- 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 def
[PATCH 11/17] doc: ReSTify Yama.txt
Adjusts for ReST markup and moves under LSM admin guide.
Signed-off-by: Kees Cook
---
.../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
[PATCH 16/17] doc: ReSTify keys-request-key.txt
Adjusts for ReST markup and moves under keys security devel index.
Cc: David Howells
Signed-off-by: Kees Cook
---
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 for more information
+See 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 for further
+See 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
[PATCH 12/17] doc: ReSTify LoadPin.txt
Adjusts for ReST markup and moves under LSM admin guide.
Signed-off-by: Kees Cook
---
.../{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
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
--
2.7.4
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
[PATCH 13/17] doc: ReSTify Smack.txt
Adjusts for ReST markup and moves under LSM admin guide.
Cc: Casey Schaufler
Signed-off-by: Kees Cook
---
.../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 filesyst
[PATCH 14/17] doc: ReSTify keys.txt
This creates a new section in the security development index for kernel
keys, and adjusts for ReST markup.
Cc: David Howells
Signed-off-by: Kees Cook
---
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
actua
[PATCH 15/17] doc: ReSTify keys-ecryptfs.txt
Adjusts for ReST markup and moves under keys security devel index.
Cc: David Howells
Cc: Tyler Hicks
Signed-off-by: Kees Cook
---
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
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
[PATCH 01/17] doc: ReSTify seccomp_filter.txt
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
---
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
[PATCH 00/17] convert/reorganize Documentation/security/
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 -- To unsubscribe from this list: send the line "unsubscribe linux-doc" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
[PATCH 0/5] Convert more books to ReST
This patch series convert the following books to ReST: - librs - mtdnand - sh And it is based on my previous series of conversion patches. After this series, there will be just one DocBook pending conversion: - lsm (Linux Security Modules) This book is very outdated: no changes since the Kernel moved to git, in 2005 (except for a minor editorial fix in 2008). I took a look on the described API: it doesn't seem to be describing the current security implementation. The best here is if someone that works with LSM to convert it to ReST with: $ Documentation/sphinx/tmplcvt Documentation/DocBook/lsm.tmpl lsm.rst And fix the document to produce something that reflects the current implementation. If nobody is interested, then maybe we could just drop it. - This patch series is based on my past 00/36 patch series, applied on the top of docs tree (next branch). The full patch series is on this tree is at: https://git.linuxtv.org//mchehab/experimental.git/log/?h=docbook And the HTML output at: http://www.infradead.org/~mchehab/kernel_docs/ https://mchehab.fedorapeople.org/kernel_docs/ Mauro Carvalho Chehab (5): docs-rst: convert librs book to ReST docs-rst: convert mtdnand book to ReST mtdnand.rst: Fix some typos and group the "::" with previous line mtd: adjust kernel-docs to avoid Sphinx/kerneldoc warnings docs-rst: convert sh book to ReST Documentation/DocBook/Makefile |5 +- Documentation/DocBook/librs.tmpl | 289 Documentation/DocBook/mtdnand.tmpl | 1291 -- Documentation/DocBook/sh.tmpl| 105 --- Documentation/conf.py|2 + Documentation/core-api/index.rst |1 + Documentation/core-api/librs.rst | 212 ++ Documentation/driver-api/index.rst |1 + Documentation/driver-api/mtdnand.rst | 1007 ++ Documentation/index.rst | 11 + Documentation/sh/index.rst | 59 ++ drivers/mtd/nand/nand_base.c |7 +- include/linux/mtd/nand.h |2 +- 13 files changed, 1300 insertions(+), 1692 deletions(-) delete mode 100644 Documentation/DocBook/librs.tmpl delete mode 100644 Documentation/DocBook/mtdnand.tmpl delete mode 100644 Documentation/DocBook/sh.tmpl create mode 100644 Documentation/core-api/librs.rst create mode 100644 Documentation/driver-api/mtdnand.rst create mode 100644 Documentation/sh/index.rst -- 2.9.3 -- To unsubscribe from this list: send the line "unsubscribe linux-doc" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
[PATCH 1/5] docs-rst: convert librs book to ReST
Use pandoc to convert documentation to ReST by calling Documentation/sphinx/tmplcvt script. Signed-off-by: Mauro Carvalho Chehab --- Documentation/DocBook/Makefile | 2 +- Documentation/DocBook/librs.tmpl | 289 --- Documentation/core-api/index.rst | 1 + Documentation/core-api/librs.rst | 212 4 files changed, 214 insertions(+), 290 deletions(-) delete mode 100644 Documentation/DocBook/librs.tmpl create mode 100644 Documentation/core-api/librs.rst diff --git a/Documentation/DocBook/Makefile b/Documentation/DocBook/Makefile index baedb14f3b40..0a82f6253682 100644 --- a/Documentation/DocBook/Makefile +++ b/Documentation/DocBook/Makefile @@ -8,7 +8,7 @@ DOCBOOKS := \ lsm.xml \ - mtdnand.xml librs.xml \ + mtdnand.xml \ sh.xml ifeq ($(DOCBOOKS),) diff --git a/Documentation/DocBook/librs.tmpl b/Documentation/DocBook/librs.tmpl deleted file mode 100644 index 94f21361e0ed.. --- a/Documentation/DocBook/librs.tmpl +++ /dev/null @@ -1,289 +0,0 @@ - -http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd"; []> - - - - Reed-Solomon Library Programming Interface - - - -Thomas -Gleixner - - - t...@linutronix.de - - - - - - - 2004 - Thomas Gleixner - - - - - This documentation is free software; you can redistribute - it and/or modify it under the terms of the GNU General Public - License version 2 as published by the Free Software Foundation. - - - - This program is distributed in the hope that it will be - useful, but WITHOUT ANY WARRANTY; without even the implied - warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. - See the GNU General Public License for more details. - - - - You should have received a copy of the GNU General Public - License along with this program; if not, write to the Free - Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, - MA 02111-1307 USA - - - - For more details see the file COPYING in the source - distribution of Linux. - - - - - - - - Introduction - - The generic Reed-Solomon Library provides encoding, decoding - and error correction functions. - - - Reed-Solomon codes are used in communication and storage - applications to ensure data integrity. - - - This documentation is provided for developers who want to utilize - the functions provided by the library. - - - - - Known Bugs And Assumptions - - None. - - - - - Usage - - This chapter provides examples of how to use the library. - - - Initializing - - The init function init_rs returns a pointer to an - rs decoder structure, which holds the necessary - information for encoding, decoding and error correction - with the given polynomial. It either uses an existing - matching decoder or creates a new one. On creation all - the lookup tables for fast en/decoding are created. - The function may take a while, so make sure not to - call it in critical code paths. - - -/* the Reed Solomon control structure */ -static struct rs_control *rs_decoder; - -/* Symbolsize is 10 (bits) - * Primitive polynomial is x^10+x^3+1 - * first consecutive root is 0 - * primitive element to generate roots = 1 - * generator polynomial degree (number of roots) = 6 - */ -rs_decoder = init_rs (10, 0x409, 0, 1, 6); - - - - Encoding - - The encoder calculates the Reed-Solomon code over - the given data length and stores the result in - the parity buffer. Note that the parity buffer must - be initialized before calling the encoder. - - - The expanded data can be inverted on the fly by - providing a non-zero inversion mask. The expanded data is - XOR'ed with the mask. This is used e.g. for FLASH - ECC, where the all 0xFF is inverted to an all 0x00. - The Reed-Solomon code for all 0x00 is all 0x00. The - code is inverted before storing to FLASH so it is 0xFF - too. This prevents that reading from an erased FLASH - results in ECC errors. - - - The databytes are expanded to the given symbol size - on the fly. There is no support for encoding continuous - bitstreams with
[PATCH 4/5] mtd: adjust kernel-docs to avoid Sphinx/kerneldoc warnings
./drivers/mtd/nand/nand_bbt.c:1: warning: no structured comments found ./include/linux/mtd/nand.h:785: ERROR: Unexpected indentation. ./drivers/mtd/nand/nand_base.c:449: WARNING: Definition list ends without a blank line; unexpected unindent. ./drivers/mtd/nand/nand_base.c:1161: ERROR: Unexpected indentation. ./drivers/mtd/nand/nand_base.c:1162: WARNING: Block quote ends without a blank line; unexpected unindent. Signed-off-by: Mauro Carvalho Chehab --- Documentation/driver-api/mtdnand.rst | 3 --- drivers/mtd/nand/nand_base.c | 7 +-- include/linux/mtd/nand.h | 2 +- 3 files changed, 6 insertions(+), 6 deletions(-) diff --git a/Documentation/driver-api/mtdnand.rst b/Documentation/driver-api/mtdnand.rst index e670f8b15a79..4fe3bf00299b 100644 --- a/Documentation/driver-api/mtdnand.rst +++ b/Documentation/driver-api/mtdnand.rst @@ -970,9 +970,6 @@ hints" for an explanation. .. kernel-doc:: drivers/mtd/nand/nand_base.c :export: -.. kernel-doc:: drivers/mtd/nand/nand_bbt.c - :export: - .. kernel-doc:: drivers/mtd/nand/nand_ecc.c :export: diff --git a/drivers/mtd/nand/nand_base.c b/drivers/mtd/nand/nand_base.c index b0524f8accb6..c8988c01e0d7 100644 --- a/drivers/mtd/nand/nand_base.c +++ b/drivers/mtd/nand/nand_base.c @@ -442,10 +442,12 @@ static int nand_default_block_markbad(struct mtd_info *mtd, loff_t ofs) * specify how to write bad block markers to OOB (chip->block_markbad). * * We try operations in the following order: + * * (1) erase the affected block, to allow OOB marker to be written cleanly * (2) write bad block marker to OOB area of affected block (unless flag * NAND_BBT_NO_OOB_BBM is present) * (3) update the BBT + * * Note that we retain the first error encountered in (2) or (3), finish the * procedures, and dump the error in the end. */ @@ -1155,9 +1157,10 @@ int nand_reset(struct nand_chip *chip, int chipnr) * @mtd: mtd info * @ofs: offset to start unlock from * @len: length to unlock - * @invert: when = 0, unlock the range of blocks within the lower and + * @invert: + *- when = 0, unlock the range of blocks within the lower and *upper boundary address - * when = 1, unlock the range of blocks outside the boundaries + *- when = 1, unlock the range of blocks outside the boundaries *of the lower and upper boundary address * * Returs unlock status. diff --git a/include/linux/mtd/nand.h b/include/linux/mtd/nand.h index 9591e0fbe5bd..3d5b20379ba3 100644 --- a/include/linux/mtd/nand.h +++ b/include/linux/mtd/nand.h @@ -779,7 +779,7 @@ nand_get_sdr_timings(const struct nand_data_interface *conf) * Minimum amount of bit errors per @ecc_step_ds guaranteed * to be correctable. If unknown, set to zero. * @ecc_step_ds: [INTERN] ECC step required by the @ecc_strength_ds, - * also from the datasheet. It is the recommended ECC step + * also from the datasheet. It is the recommended ECC step * size, if known; if unknown, set to zero. * @onfi_timing_mode_default: [INTERN] default ONFI timing mode. This field is * set to the actually used ONFI mode if the chip is -- 2.9.3 -- To unsubscribe from this list: send the line "unsubscribe linux-doc" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
[PATCH 3/5] mtdnand.rst: Fix some typos and group the "::" with previous line
Typo: ored -> ordered While here, group the :: with the previous paragraph, in order to make it visually better when reading as a text file. Signed-off-by: Mauro Carvalho Chehab --- Documentation/driver-api/mtdnand.rst | 24 +++- 1 file changed, 7 insertions(+), 17 deletions(-) diff --git a/Documentation/driver-api/mtdnand.rst b/Documentation/driver-api/mtdnand.rst index 8723175f955e..e670f8b15a79 100644 --- a/Documentation/driver-api/mtdnand.rst +++ b/Documentation/driver-api/mtdnand.rst @@ -843,10 +843,8 @@ Chip option constants Constants for chip id table ~~~ -These constants are defined in nand.h. They are ored together to -describe the chip functionality. - -:: +These constants are defined in nand.h. They are ordered together to +describe the chip functionality:: /* Buswitdh is 16 bit */ #define NAND_BUSWIDTH_160x0002 @@ -867,10 +865,8 @@ describe the chip functionality. Constants for runtime options ~ -These constants are defined in nand.h. They are ored together to -describe the functionality. - -:: +These constants are defined in nand.h. They are ordered together to +describe the functionality:: /* The hw ecc generator provides a syndrome instead a ecc value on read * This can only work if we have the ecc bytes directly behind the @@ -881,9 +877,7 @@ describe the functionality. ECC selection constants --- -Use these constants to select the ECC algorithm. - -:: +Use these constants to select the ECC algorithm:: /* No ECC. Usage is not recommended ! */ #define NAND_ECC_NONE 0 @@ -903,9 +897,7 @@ Hardware control related constants -- These constants describe the requested hardware access function when the -boardspecific hardware control function is called - -:: +boardspecific hardware control function is called:: /* Select the chip by setting nCE to low */ #define NAND_CTL_SETNCE 1 @@ -929,9 +921,7 @@ Bad block table related constants - These constants describe the options used for bad block table -descriptors. - -:: +descriptors:: /* Options for the bad block table descriptors */ -- 2.9.3 -- To unsubscribe from this list: send the line "unsubscribe linux-doc" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
[PATCH 5/5] docs-rst: convert sh book to ReST
Use pandoc to convert documentation to ReST by calling
Documentation/sphinx/tmplcvt script.
Signed-off-by: Mauro Carvalho Chehab
---
Documentation/DocBook/Makefile | 4 +-
Documentation/DocBook/sh.tmpl | 105 -
Documentation/conf.py | 2 +
Documentation/index.rst| 11 +
Documentation/sh/index.rst | 59 +++
5 files changed, 73 insertions(+), 108 deletions(-)
delete mode 100644 Documentation/DocBook/sh.tmpl
create mode 100644 Documentation/sh/index.rst
diff --git a/Documentation/DocBook/Makefile b/Documentation/DocBook/Makefile
index 226e5e9fc801..efba7f980895 100644
--- a/Documentation/DocBook/Makefile
+++ b/Documentation/DocBook/Makefile
@@ -6,9 +6,7 @@
# To add a new book the only step required is to add the book to the
# list of DOCBOOKS.
-DOCBOOKS := \
- lsm.xml \
- sh.xml
+DOCBOOKS := lsm.xml
ifeq ($(DOCBOOKS),)
diff --git a/Documentation/DocBook/sh.tmpl b/Documentation/DocBook/sh.tmpl
deleted file mode 100644
index 4a38f604fa66..
--- a/Documentation/DocBook/sh.tmpl
+++ /dev/null
@@ -1,105 +0,0 @@
-
-http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd"; []>
-
-
-
- SuperH Interfaces Guide
-
-
-
-Paul
-Mundt
-
-
- let...@linux-sh.org
-
-
-
-
-
-
- 2008-2010
- Paul Mundt
-
-
- 2008-2010
- Renesas Technology Corp.
-
-
- 2010
- Renesas Electronics Corp.
-
-
-
-
- This documentation is free software; you can redistribute
- it and/or modify it under the terms of the GNU General Public
- License version 2 as published by the Free Software Foundation.
-
-
-
- This program is distributed in the hope that it will be
- useful, but WITHOUT ANY WARRANTY; without even the implied
- warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
- See the GNU General Public License for more details.
-
-
-
- You should have received a copy of the GNU General Public
- License along with this program; if not, write to the Free
- Software Foundation, Inc., 59 Temple Place, Suite 330, Boston,
- MA 02111-1307 USA
-
-
-
- For more details see the file COPYING in the source
- distribution of Linux.
-
-
-
-
-
-
-
-Memory Management
-
-SH-4
-
-Store Queue API
-!Earch/sh/kernel/cpu/sh4/sq.c
-
-
-
- SH-5
-
- TLB Interfaces
-!Iarch/sh/mm/tlb-sh5.c
-!Iarch/sh/include/asm/tlb_64.h
-
-
-
-
-Machine Specific Interfaces
-
- mach-dreamcast
-!Iarch/sh/boards/mach-dreamcast/rtc.c
-
-
- mach-x3proto
-!Earch/sh/boards/mach-x3proto/ilsel.c
-
-
-
-Busses
-
- SuperHyway
-!Edrivers/sh/superhyway/superhyway.c
-
-
-
- Maple
-!Edrivers/sh/maple/maple.c
-
-
-
diff --git a/Documentation/conf.py b/Documentation/conf.py
index dfe14f7525d0..77d47bb1df1d 100644
--- a/Documentation/conf.py
+++ b/Documentation/conf.py
@@ -375,6 +375,8 @@ latex_documents = [
'The kernel development community', 'manual'),
('security/index', 'security.tex', 'The kernel security subsystem manual',
'The kernel development community', 'manual'),
+('sh/index', 'sh.tex', 'SuperH architecture implementation manual',
+ 'The kernel development community', 'manual'),
('sound/index', 'sound.tex', 'Linux Sound Subsystem Documentation',
'The kernel development community', 'manual'),
('userspace-api/index', 'userspace-api.tex', 'The Linux kernel user-space
API guide',
diff --git a/Documentation/index.rst b/Documentation/index.rst
index 25c4da41da6b..e9017bb3a6ce 100644
--- a/Documentation/index.rst
+++ b/Documentation/index.rst
@@ -76,6 +76,17 @@ needed).
crypto/index
filesystems/index
+Architecture-specific documentation
+---
+
+These books provide programming details about architecture-specific
+implementation.
+
+.. toctree::
+ :maxdepth: 2
+
+ sh/index
+
Korean translations
---
diff --git a/Documentation/sh/index.rst b/Documentation/sh/index.rst
new file mode 100644
index ..bc8db7ba894a
--- /dev/null
+++ b/Documentation/sh/index.rst
@@ -0,0 +1,59 @@
+===
+SuperH Interfaces Guide
+===
+
+:Author: Paul Mundt
+
+Memory Management
+=
+
+SH-4
+
+
+Store Queue API
+~~~
+
+.. kernel-doc:: arch/sh/kernel/cpu/sh4/sq.c
+ :export:
+
+SH-5
+
+
+TLB Interfaces
+~~
+
+.. kernel-doc:: arch/sh/mm/tlb-sh5.c
+ :internal:
+
+.. kernel-doc:: arch/sh/include/asm/tlb_64.h
+ :internal:
+
+Machine Specific Interfaces
+===
+
+mach-dreamcast
+--
+
+.. kernel-doc:: arch/sh/boards/mach-dreamcast/rtc.c
+ :internal:
+
+mach-x3proto
+
+
+.. kernel-doc:: arch/sh/boards/mach-x3proto/ilsel.c
+ :export:
+
+Busses
[PATCH 2/5] docs-rst: convert mtdnand book to ReST
Use pandoc to convert documentation to ReST by calling Documentation/sphinx/tmplcvt script. The tables were manually adjusted to fit into 80 columns. Signed-off-by: Mauro Carvalho Chehab --- Documentation/DocBook/Makefile |1 - Documentation/DocBook/mtdnand.tmpl | 1291 -- Documentation/driver-api/index.rst |1 + Documentation/driver-api/mtdnand.rst | 1020 +++ 4 files changed, 1021 insertions(+), 1292 deletions(-) delete mode 100644 Documentation/DocBook/mtdnand.tmpl create mode 100644 Documentation/driver-api/mtdnand.rst diff --git a/Documentation/DocBook/Makefile b/Documentation/DocBook/Makefile index 0a82f6253682..226e5e9fc801 100644 --- a/Documentation/DocBook/Makefile +++ b/Documentation/DocBook/Makefile @@ -8,7 +8,6 @@ DOCBOOKS := \ lsm.xml \ - mtdnand.xml \ sh.xml ifeq ($(DOCBOOKS),) diff --git a/Documentation/DocBook/mtdnand.tmpl b/Documentation/DocBook/mtdnand.tmpl deleted file mode 100644 index b442921bca54.. --- a/Documentation/DocBook/mtdnand.tmpl +++ /dev/null @@ -1,1291 +0,0 @@ - -http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd"; []> - - - - MTD NAND Driver Programming Interface - - - -Thomas -Gleixner - - - t...@linutronix.de - - - - - - - 2004 - Thomas Gleixner - - - - - This documentation is free software; you can redistribute - it and/or modify it under the terms of the GNU General Public - License version 2 as published by the Free Software Foundation. - - - - This program is distributed in the hope that it will be - useful, but WITHOUT ANY WARRANTY; without even the implied - warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. - See the GNU General Public License for more details. - - - - You should have received a copy of the GNU General Public - License along with this program; if not, write to the Free - Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, - MA 02111-1307 USA - - - - For more details see the file COPYING in the source - distribution of Linux. - - - - - - - - Introduction - - The generic NAND driver supports almost all NAND and AG-AND based - chips and connects them to the Memory Technology Devices (MTD) - subsystem of the Linux Kernel. - - - This documentation is provided for developers who want to implement - board drivers or filesystem drivers suitable for NAND devices. - - - - - Known Bugs And Assumptions - - None. - - - - - Documentation hints - - The function and structure docs are autogenerated. Each function and - struct member has a short description which is marked with an [XXX] identifier. - The following chapters explain the meaning of those identifiers. - - - Function identifiers [XXX] - - The functions are marked with [XXX] identifiers in the short - comment. The identifiers explain the usage and scope of the - functions. Following identifiers are used: - - - - [MTD Interface] - These functions provide the interface to the MTD kernel API. - They are not replaceable and provide functionality - which is complete hardware independent. - - - [NAND Interface] - These functions are exported and provide the interface to the NAND kernel API. - - - [GENERIC] - Generic functions are not replaceable and provide functionality - which is complete hardware independent. - - - [DEFAULT] - Default functions provide hardware related functionality which is suitable - for most of the implementations. These functions can be replaced by the - board driver if necessary. Those functions are called via pointers in the - NAND chip description structure. The board driver can set the functions which - should be replaced by board dependent functions before calling nand_scan(). - If the function pointer is NULL on entry to nand_scan() then the pointer - is set to the default function which is suitable for the detected chip type. - - - - - Struct member identifiers [XXX] - - The struct members are marked with [XXX] identifiers in the - comment. The identifiers explain the usage and scope of the - members. Following identifiers are used: - - - - [INTERN] - These members are for NAND driver internal use only and must not be - modified. Most of the
Re: [PATCH 01/36] docs-rst: convert kernel-hacking to ReST
Em Fri, 12 May 2017 18:35:29 +0200 Markus Heiser escreveu: > Am 12.05.2017 um 15:59 schrieb Mauro Carvalho Chehab > : > > > Use pandoc to convert documentation to ReST by calling > > Documentation/sphinx/tmplcvt script. > > > > - Manually adjusted to use ..note and ..warning > > - Minor fixes for it to be parsed without errors > > - Use **bold** for emphasis. > > > > Signed-off-by: Mauro Carvalho Chehab > > --- > > Documentation/DocBook/Makefile|2 +- > > Documentation/DocBook/kernel-hacking.tmpl | 1312 > > - > > Documentation/conf.py |2 + > > Documentation/index.rst |1 + > > Documentation/kernel-hacking/conf.py | 10 + > > Documentation/kernel-hacking/index.rst| 794 + > > 6 files changed, 808 insertions(+), 1313 deletions(-) > > delete mode 100644 Documentation/DocBook/kernel-hacking.tmpl > > create mode 100644 Documentation/kernel-hacking/conf.py > > create mode 100644 Documentation/kernel-hacking/index.rst > > > > > > > > +:c:func:`cpu_to_be32()`/:c:func:`be32_to_cpu()`/:c:func:`cpu_to_le32()`/:c:func:`le32_to_cpu()` > > ``include/asm/byteorder.h`` > > +--- > > + > > Hi Mauro, just my bikeshedding: > > what do you think, do we really need to refer functions in titles? > As far as I know, there is no use-case where we can get any benefit > from. So I recommend to write titles more simple, e.g.: > > cpu_to_be32()/be32_to_cpu()/cpu_to_le32()/le32_to_cpu() > include/asm/byteorder.h > > .. which is long enough ;) There are some functions there that are only mentioned at the title, like: local_bh_disable(). IMHO, it is a good idea to add a cross-reference to those, as it helps the reader to get further information if needed. So, except if this would cause Sphinx to crash, I prefer to keep the references. What I did, instead, on patch 02/36 is to move all header references to be outside the title: +:c:func:`cpu_to_be32()`/:c:func:`be32_to_cpu()`/:c:func:`cpu_to_le32()`/:c:func:`le32_to_cpu()` +--- + +Defined in ``include/asm/byteorder.h`` With reduces the displayed title to something reasonable. Thanks, Mauro -- To unsubscribe from this list: send the line "unsubscribe linux-doc" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH 04/36] mutex, futex: adjust kernel-doc markups to generate ReST
Em Fri, 12 May 2017 15:19:17 -0700 Darren Hart escreveu: > On Sat, May 13, 2017 at 12:11:09AM +0200, Peter Zijlstra wrote: > > On Fri, May 12, 2017 at 06:51:50PM -0300, Mauro Carvalho Chehab wrote: > > > > * Return: > > > > * * 0 - ready to wait > > > > * * 1 - acquired the lock > > > > * * <0 - error > > > > > > > > I'm fine with either though, just curious if this would be an > > > > improvement, or if > > > > we have an established policy (which I didn't find in the docs on > > > > docs...). > > > > > > I prefer myself to use "-". IMHO, a dash is visually less polluted > > > than an asterisk, when reading text files, but I guess this is a > > > matter of taste. > > > > Not to mention it just reads very awkward in a comment. I don't much > > care about it in any other context. > > Agreed, the - is better (and equally functional - so yay). > > > > > And I really _really_ hate to see that rest crap spread here. Can't we > > just delete all that nonsense and go back to 80 column 7bit ASCII ? > > > > Depending on the source this could be a genuine appeal or satire :-D > > In this case, I don't think the ReST changes (with -) make the comment block > any > less readable in the C files. > > > It is an incentive not to use kerneldoc.. Very few kerneldoc markups need changes due to ReST introduction, and usually is just whitespace/blank lines adjustment. Ok, someone could try to improve the script to make it smarter[1], but, on my experiences addressing it, usually doing the required changes make it visually better on both C file and on PDF/LaTeX/HTML outputs. [1] probably rewriting the entire script to work more like a lexical interpreter than a bunch of rejex expressions. > I like the kerneldoc if for no other reason that it helps keeps formatting > consistent. I would object if I started seeing XML or some other horrible > formatting style showing up in the code, but this honestly seems like a fairly > minimal imposition... but that's me. IMHO, the best thing with kerneldoc is that it helps to keep the documentation updated, as it warns when someone change the function arguments without updating the comments. Thanks, Mauro -- To unsubscribe from this list: send the line "unsubscribe linux-doc" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH 03/36] docs-rst: convert kernel-locking to ReST
Em Fri, 12 May 2017 18:57:13 +0200
Markus Heiser escreveu:
> Am 12.05.2017 um 15:59 schrieb Mauro Carvalho Chehab
> :
>
> > Use pandoc to convert documentation to ReST by calling
> > Documentation/sphinx/tmplcvt script.
> >
> > - Manually adjust tables with got broken by conversion
> >
> > Signed-off-by: Mauro Carvalho Chehab
> > ---
> > Documentation/DocBook/Makefile|1 -
> > Documentation/DocBook/kernel-locking.tmpl | 2151
> > -
> > Documentation/kernel-hacking/hacking.rst | 811 +++
> > Documentation/kernel-hacking/index.rst| 814 +--
> > Documentation/kernel-hacking/locking.rst | 1453 +++
> > 5 files changed, 2268 insertions(+), 2962 deletions(-)
> > delete mode 100644 Documentation/DocBook/kernel-locking.tmpl
> > create mode 100644 Documentation/kernel-hacking/hacking.rst
> > create mode 100644 Documentation/kernel-hacking/locking.rst
> >
> > ...
>
> > diff --git a/Documentation/kernel-hacking/index.rst
> > b/Documentation/kernel-hacking/index.rst
> > index 1a456b60a7cf..b3d8fe56d310 100644
> > --- a/Documentation/kernel-hacking/index.rst
> > +++ b/Documentation/kernel-hacking/index.rst
> > @@ -1,811 +1,5 @@
> > -
> > -Unreliable Guide To Hacking The Linux Kernel
> > -
> > +.. toctree::
> > + :maxdepth: 2
>
> Every .rst file needs a title, otherwise is inserted,
> see breadcrumb at the top :
>
> https://mchehab.fedorapeople.org/kernel_docs/kernel-hacking/index.html
Thanks for review!
I'll fold it with the enclosed path.
diff --git a/Documentation/conf.py b/Documentation/conf.py
index bfa95c881956..0ce8001a50b6 100644
--- a/Documentation/conf.py
+++ b/Documentation/conf.py
@@ -352,7 +352,7 @@ latex_documents = [
'The kernel development community', 'manual'),
('kernel-documentation', 'kernel-documentation.tex', 'The Linux Kernel
Documentation',
'The kernel development community', 'manual'),
-('kernel-hacking/index', 'kernel-hacking.tex', 'Unreliable Guide To
Hacking The Linux Kernel',
+('kernel-hacking/index', 'kernel-hacking.tex', 'Kernel Hacking Guides',
'The kernel development community', 'manual'),
('process/index', 'development-process.tex', 'Linux Kernel Development
Documentation',
'The kernel development community', 'manual'),
diff --git a/Documentation/kernel-hacking/conf.py
b/Documentation/kernel-hacking/conf.py
index 4facca74a6f0..3d8acf0f33ad 100644
--- a/Documentation/kernel-hacking/conf.py
+++ b/Documentation/kernel-hacking/conf.py
@@ -1,6 +1,6 @@
# -*- coding: utf-8; mode: python -*-
-project = "Unreliable Guide To Hacking The Linux Kernel"
+project = "Kernel Hacking Guides"
tags.add("subproject")
diff --git a/Documentation/kernel-hacking/index.rst
b/Documentation/kernel-hacking/index.rst
index b3d8fe56d310..fcb0eda3cca3 100644
--- a/Documentation/kernel-hacking/index.rst
+++ b/Documentation/kernel-hacking/index.rst
@@ -1,3 +1,7 @@
+=
+Kernel Hacking Guides
+=
+
.. toctree::
:maxdepth: 2
diff --git a/Documentation/kernel-hacking/hacking.rst
b/Documentation/kernel-hacking/hacking.rst
index 1a456b60a7cf..58831decd5ae 100644
--- a/Documentation/kernel-hacking/hacking.rst
+++ b/Documentation/kernel-hacking/hacking.rst
@@ -764,7 +764,7 @@ Some favorites from browsing the source. Feel free to add
to this list.
#define PTR_ERR(ptr)((long)(ptr))
#define IS_ERR(ptr) ((unsigned long)(ptr) > (unsigned long)(-1000))
-``arch/x86/include/asm/uaccess_32.h:``::
+``arch/x86/include/asm/uaccess_32.h``::
#define copy_to_user(to,from,n) \
(__builtin_constant_p(n) ? \
@@ -772,7 +772,7 @@ Some favorites from browsing the source. Feel free to add
to this list.
__generic_copy_to_user((to),(from),(n)))
-``arch/sparc/kernel/head.S:``::
+``arch/sparc/kernel/head.S``::
/*
* Sun people can't spell worth damn. "compatability" indeed.
@@ -791,7 +791,7 @@ Some favorites from browsing the source. Feel free to add
to this list.
.asciz "compatible"
-``arch/sparc/lib/checksum.S:``::
+``arch/sparc/lib/checksum.S``::
/* Sun, you just can't beat me, you just can't. Stop trying,
* give up. I'm serious, I am going to kick the living shit
Thanks,
Mauro
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH 21/36] fs: locks: Fix some troubles at kernel-doc comments
Hi Jeff, Em Fri, 12 May 2017 10:02:56 -0400 Jeff Layton escreveu: > On Fri, 2017-05-12 at 11:00 -0300, Mauro Carvalho Chehab wrote: > > There are a few syntax violations that cause outputs of > > a few comments to not be properly parsed in ReST format. > > > > No functional changes. > > > > Signed-off-by: Mauro Carvalho Chehab > > --- > > fs/locks.c | 18 -- > > 1 file changed, 8 insertions(+), 10 deletions(-) > > > > diff --git a/fs/locks.c b/fs/locks.c > > index 26811321d39b..bdce708e4251 100644 > > --- a/fs/locks.c > > +++ b/fs/locks.c > > @@ -1858,8 +1858,8 @@ EXPORT_SYMBOL(generic_setlease); > > * > > * Call this to establish a lease on the file. The "lease" argument is not > > * used for F_UNLCK requests and may be NULL. For commands that set or > > alter > > - * an existing lease, the (*lease)->fl_lmops->lm_break operation must be > > set; > > - * if not, this function will return -ENOLCK (and generate a scary-looking > > + * an existing lease, the ``(*lease)->fl_lmops->lm_break`` operation must > > be > > + * set; if not, this function will return -ENOLCK (and generate a > > scary-looking > > * stack trace). > > * > > * The "priv" pointer is passed directly to the lm_setup function as-is. It > > @@ -1972,15 +1972,13 @@ EXPORT_SYMBOL(locks_lock_inode_wait); > > * @cmd: the type of lock to apply. > > * > > * Apply a %FL_FLOCK style lock to an open file descriptor. > > - * The @cmd can be one of > > + * The @cmd can be one of: > > * > > - * %LOCK_SH -- a shared lock. > > - * > > - * %LOCK_EX -- an exclusive lock. > > - * > > - * %LOCK_UN -- remove an existing lock. > > - * > > - * %LOCK_MAND -- a `mandatory' flock. This exists to emulate Windows > > Share Modes. > > + * - %LOCK_SH -- a shared lock. > > + * - %LOCK_EX -- an exclusive lock. > > + * - %LOCK_UN -- remove an existing lock. > > + * - %LOCK_MAND -- a 'mandatory' flock. > > + * This exists to emulate Windows Share Modes. > > * > > * %LOCK_MAND can be combined with %LOCK_READ or %LOCK_WRITE to allow other > > * processes read and write access respectively. > > LGTM. Do you need me or Bruce to pick this one up? Feel free to pick it, if it works best for you. > Reviewed-by: Jeff Layton Thanks, Mauro -- To unsubscribe from this list: send the line "unsubscribe linux-doc" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
