On 5/13/2017 4:51 AM, Kees Cook wrote:
> Adjusts for ReST markup and moves under LSM admin guide.
>
> Cc: Casey Schaufler <casey@xxxxxxxxxxxxxxxx>
> Signed-off-by: Kees Cook <keescook@xxxxxxxxxxxx>
Acked-by: Casey Schaufler <casey@xxxxxxxxxxxxxxxx>
Thank you.
> ---
> .../Smack.txt => admin-guide/LSM/Smack.rst} | 273 ++++++++++++++-------
> Documentation/admin-guide/LSM/index.rst | 1 +
> Documentation/security/00-INDEX | 2 -
> MAINTAINERS | 2 +-
> 4 files changed, 191 insertions(+), 87 deletions(-)
> rename Documentation/{security/Smack.txt => admin-guide/LSM/Smack.rst} (85%)
>
> diff --git a/Documentation/security/Smack.txt b/Documentation/admin-guide/LSM/Smack.rst
> similarity index 85%
> rename from Documentation/security/Smack.txt
> rename to Documentation/admin-guide/LSM/Smack.rst
> index 945cc633d883..6a5826a13aea 100644
> --- a/Documentation/security/Smack.txt
> +++ b/Documentation/admin-guide/LSM/Smack.rst
> @@ -1,3 +1,6 @@
> +=====
> +Smack
> +=====
>
>
> "Good for you, you've decided to clean the elevator!"
> @@ -14,6 +17,7 @@ available to determine which is best suited to the problem
> at hand.
>
> Smack consists of three major components:
> +
> - The kernel
> - Basic utilities, which are helpful but not required
> - Configuration data
> @@ -39,16 +43,24 @@ The current git repository for Smack user space is:
> This should make and install on most modern distributions.
> There are five commands included in smackutil:
>
> -chsmack - display or set Smack extended attribute values
> -smackctl - load the Smack access rules
> -smackaccess - report if a process with one label has access
> - to an object with another
> +chsmack:
> + display or set Smack extended attribute values
> +
> +smackctl:
> + load the Smack access rules
> +
> +smackaccess:
> + report if a process with one label has access
> + to an object with another
>
> These two commands are obsolete with the introduction of
> the smackfs/load2 and smackfs/cipso2 interfaces.
>
> -smackload - properly formats data for writing to smackfs/load
> -smackcipso - properly formats data for writing to smackfs/cipso
> +smackload:
> + properly formats data for writing to smackfs/load
> +
> +smackcipso:
> + properly formats data for writing to smackfs/cipso
>
> In keeping with the intent of Smack, configuration data is
> minimal and not strictly required. The most important
> @@ -56,15 +68,15 @@ configuration step is mounting the smackfs pseudo filesystem.
> If smackutil is installed the startup script will take care
> of this, but it can be manually as well.
>
> -Add this line to /etc/fstab:
> +Add this line to ``/etc/fstab``::
>
> smackfs /sys/fs/smackfs smackfs defaults 0 0
>
> -The /sys/fs/smackfs directory is created by the kernel.
> +The ``/sys/fs/smackfs`` directory is created by the kernel.
>
> Smack uses extended attributes (xattrs) to store labels on filesystem
> objects. The attributes are stored in the extended attribute security
> -name space. A process must have CAP_MAC_ADMIN to change any of these
> +name space. A process must have ``CAP_MAC_ADMIN`` to change any of these
> attributes.
>
> The extended attributes that Smack uses are:
> @@ -73,14 +85,17 @@ SMACK64
> Used to make access control decisions. In almost all cases
> the label given to a new filesystem object will be the label
> of the process that created it.
> +
> SMACK64EXEC
> The Smack label of a process that execs a program file with
> this attribute set will run with this attribute's value.
> +
> SMACK64MMAP
> Don't allow the file to be mmapped by a process whose Smack
> label does not allow all of the access permitted to a process
> with the label contained in this attribute. This is a very
> specific use case for shared libraries.
> +
> SMACK64TRANSMUTE
> Can only have the value "TRUE". If this attribute is present
> on a directory when an object is created in the directory and
> @@ -89,27 +104,29 @@ SMACK64TRANSMUTE
> gets the label of the directory instead of the label of the
> creating process. If the object being created is a directory
> the SMACK64TRANSMUTE attribute is set as well.
> +
> SMACK64IPIN
> This attribute is only available on file descriptors for sockets.
> Use the Smack label in this attribute for access control
> decisions on packets being delivered to this socket.
> +
> SMACK64IPOUT
> This attribute is only available on file descriptors for sockets.
> Use the Smack label in this attribute for access control
> decisions on packets coming from this socket.
>
> -There are multiple ways to set a Smack label on a file:
> +There are multiple ways to set a Smack label on a file::
>
> # attr -S -s SMACK64 -V "value" path
> # chsmack -a value path
>
> A process can see the Smack label it is running with by
> -reading /proc/self/attr/current. A process with CAP_MAC_ADMIN
> +reading ``/proc/self/attr/current``. A process with ``CAP_MAC_ADMIN``
> can set the process Smack by writing there.
>
> Most Smack configuration is accomplished by writing to files
> in the smackfs filesystem. This pseudo-filesystem is mounted
> -on /sys/fs/smackfs.
> +on ``/sys/fs/smackfs``.
>
> access
> Provided for backward compatibility. The access2 interface
> @@ -120,6 +137,7 @@ access
> this file. The next read will indicate whether the access
> would be permitted. The text will be either "1" indicating
> access, or "0" indicating denial.
> +
> access2
> This interface reports whether a subject with the specified
> Smack label has a particular access to an object with a
> @@ -127,13 +145,17 @@ access2
> this file. The next read will indicate whether the access
> would be permitted. The text will be either "1" indicating
> access, or "0" indicating denial.
> +
> ambient
> This contains the Smack label applied to unlabeled network
> packets.
> +
> change-rule
> This interface allows modification of existing access control rules.
> - The format accepted on write is:
> + The format accepted on write is::
> +
> "%s %s %s %s"
> +
> where the first string is the subject label, the second the
> object label, the third the access to allow and the fourth the
> access to deny. The access strings may contain only the characters
> @@ -141,47 +163,63 @@ change-rule
> modified by enabling the permissions in the third string and disabling
> those in the fourth string. If there is no such rule it will be
> created using the access specified in the third and the fourth strings.
> +
> cipso
> Provided for backward compatibility. The cipso2 interface
> is preferred and should be used instead.
> This interface allows a specific CIPSO header to be assigned
> - to a Smack label. The format accepted on write is:
> + to a Smack label. The format accepted on write is::
> +
> "%24s%4d%4d"["%4d"]...
> +
> The first string is a fixed Smack label. The first number is
> the level to use. The second number is the number of categories.
> - The following numbers are the categories.
> - "level-3-cats-5-19 3 2 5 19"
> + The following numbers are the categories::
> +
> + "level-3-cats-5-19 3 2 5 19"
> +
> cipso2
> This interface allows a specific CIPSO header to be assigned
> - to a Smack label. The format accepted on write is:
> - "%s%4d%4d"["%4d"]...
> + to a Smack label. The format accepted on write is::
> +
> + "%s%4d%4d"["%4d"]...
> +
> The first string is a long Smack label. The first number is
> the level to use. The second number is the number of categories.
> - The following numbers are the categories.
> - "level-3-cats-5-19 3 2 5 19"
> + The following numbers are the categories::
> +
> + "level-3-cats-5-19 3 2 5 19"
> +
> direct
> This contains the CIPSO level used for Smack direct label
> representation in network packets.
> +
> doi
> This contains the CIPSO domain of interpretation used in
> network packets.
> +
> ipv6host
> This interface allows specific IPv6 internet addresses to be
> treated as single label hosts. Packets are sent to single
> label hosts only from processes that have Smack write access
> to the host label. All packets received from single label hosts
> - are given the specified label. The format accepted on write is:
> + are given the specified label. The format accepted on write is::
> +
> "%h:%h:%h:%h:%h:%h:%h:%h label" or
> "%h:%h:%h:%h:%h:%h:%h:%h/%d label".
> +
> The "::" address shortcut is not supported.
> If label is "-DELETE" a matched entry will be deleted.
> +
> load
> Provided for backward compatibility. The load2 interface
> is preferred and should be used instead.
> This interface allows access control rules in addition to
> the system defined rules to be specified. The format accepted
> - on write is:
> + on write is::
> +
> "%24s%24s%5s"
> +
> where the first string is the subject label, the second the
> object label, and the third the requested access. The access
> string may contain only the characters "rwxat-", and specifies
> @@ -189,17 +227,21 @@ load
> permissions that are not allowed. The string "r-x--" would
> specify read and execute access. Labels are limited to 23
> characters in length.
> +
> load2
> This interface allows access control rules in addition to
> the system defined rules to be specified. The format accepted
> - on write is:
> + on write is::
> +
> "%s %s %s"
> +
> where the first string is the subject label, the second the
> object label, and the third the requested access. The access
> string may contain only the characters "rwxat-", and specifies
> which sort of access is allowed. The "-" is a placeholder for
> permissions that are not allowed. The string "r-x--" would
> specify read and execute access.
> +
> load-self
> Provided for backward compatibility. The load-self2 interface
> is preferred and should be used instead.
> @@ -208,66 +250,83 @@ load-self
> otherwise be permitted, and are intended to provide additional
> restrictions on the process. The format is the same as for
> the load interface.
> +
> load-self2
> This interface allows process specific access rules to be
> defined. These rules are only consulted if access would
> otherwise be permitted, and are intended to provide additional
> restrictions on the process. The format is the same as for
> the load2 interface.
> +
> logging
> This contains the Smack logging state.
> +
> mapped
> This contains the CIPSO level used for Smack mapped label
> representation in network packets.
> +
> netlabel
> This interface allows specific internet addresses to be
> treated as single label hosts. Packets are sent to single
> label hosts without CIPSO headers, but only from processes
> that have Smack write access to the host label. All packets
> received from single label hosts are given the specified
> - label. The format accepted on write is:
> + label. The format accepted on write is::
> +
> "%d.%d.%d.%d label" or "%d.%d.%d.%d/%d label".
> +
> If the label specified is "-CIPSO" the address is treated
> as a host that supports CIPSO headers.
> +
> onlycap
> This contains labels processes must have for CAP_MAC_ADMIN
> - and CAP_MAC_OVERRIDE to be effective. If this file is empty
> + and ``CAP_MAC_OVERRIDE`` to be effective. If this file is empty
> these capabilities are effective at for processes with any
> label. The values are set by writing the desired labels, separated
> by spaces, to the file or cleared by writing "-" to the file.
> +
> ptrace
> This is used to define the current ptrace policy
> - 0 - default: this is the policy that relies on Smack access rules.
> - For the PTRACE_READ a subject needs to have a read access on
> - object. For the PTRACE_ATTACH a read-write access is required.
> - 1 - exact: this is the policy that limits PTRACE_ATTACH. Attach is
> +
> + 0 - default:
> + this is the policy that relies on Smack access rules.
> + For the ``PTRACE_READ`` a subject needs to have a read access on
> + object. For the ``PTRACE_ATTACH`` a read-write access is required.
> +
> + 1 - exact:
> + this is the policy that limits ``PTRACE_ATTACH``. Attach is
> only allowed when subject's and object's labels are equal.
> - PTRACE_READ is not affected. Can be overridden with CAP_SYS_PTRACE.
> - 2 - draconian: this policy behaves like the 'exact' above with an
> - exception that it can't be overridden with CAP_SYS_PTRACE.
> + ``PTRACE_READ`` is not affected. Can be overridden with ``CAP_SYS_PTRACE``.
> +
> + 2 - draconian:
> + this policy behaves like the 'exact' above with an
> + exception that it can't be overridden with ``CAP_SYS_PTRACE``.
> +
> revoke-subject
> Writing a Smack label here sets the access to '-' for all access
> rules with that subject label.
> +
> unconfined
> - If the kernel is configured with CONFIG_SECURITY_SMACK_BRINGUP
> - a process with CAP_MAC_ADMIN can write a label into this interface.
> + If the kernel is configured with ``CONFIG_SECURITY_SMACK_BRINGUP``
> + a process with ``CAP_MAC_ADMIN`` can write a label into this interface.
> Thereafter, accesses that involve that label will be logged and
> the access permitted if it wouldn't be otherwise. Note that this
> is dangerous and can ruin the proper labeling of your system.
> It should never be used in production.
> +
> relabel-self
> This interface contains a list of labels to which the process can
> - transition to, by writing to /proc/self/attr/current.
> + transition to, by writing to ``/proc/self/attr/current``.
> Normally a process can change its own label to any legal value, but only
> - if it has CAP_MAC_ADMIN. This interface allows a process without
> - CAP_MAC_ADMIN to relabel itself to one of labels from predefined list.
> - A process without CAP_MAC_ADMIN can change its label only once. When it
> + if it has ``CAP_MAC_ADMIN``. This interface allows a process without
> + ``CAP_MAC_ADMIN`` to relabel itself to one of labels from predefined list.
> + A process without ``CAP_MAC_ADMIN`` can change its label only once. When it
> does, this list will be cleared.
> The values are set by writing the desired labels, separated
> by spaces, to the file or cleared by writing "-" to the file.
>
> If you are using the smackload utility
> -you can add access rules in /etc/smack/accesses. They take the form:
> +you can add access rules in ``/etc/smack/accesses``. They take the form::
>
> subjectlabel objectlabel access
>
> @@ -277,14 +336,14 @@ object with objectlabel. If there is no rule no access is allowed.
>
> Look for additional programs on http://schaufler-ca.com
>
> -From the Smack Whitepaper:
> -
> -The Simplified Mandatory Access Control Kernel
> +The Simplified Mandatory Access Control Kernel (Whitepaper)
> +===========================================================
>
> Casey Schaufler
> casey@xxxxxxxxxxxxxxxx
>
> Mandatory Access Control
> +------------------------
>
> Computer systems employ a variety of schemes to constrain how information is
> shared among the people and services using the machine. Some of these schemes
> @@ -297,6 +356,7 @@ access control mechanisms because you don't have a choice regarding the users
> or programs that have access to pieces of data.
>
> Bell & LaPadula
> +---------------
>
> From the middle of the 1980's until the turn of the century Mandatory Access
> Control (MAC) was very closely associated with the Bell & LaPadula security
> @@ -306,6 +366,7 @@ within the Capital Beltway and Scandinavian supercomputer centers but was
> often sited as failing to address general needs.
>
> Domain Type Enforcement
> +-----------------------
>
> Around the turn of the century Domain Type Enforcement (DTE) became popular.
> This scheme organizes users, programs, and data into domains that are
> @@ -316,6 +377,7 @@ necessary to provide a secure domain mapping leads to the scheme being
> disabled or used in limited ways in the majority of cases.
>
> Smack
> +-----
>
> Smack is a Mandatory Access Control mechanism designed to provide useful MAC
> while avoiding the pitfalls of its predecessors. The limitations of Bell &
> @@ -326,46 +388,55 @@ Enforcement and avoided by defining access controls in terms of the access
> modes already in use.
>
> Smack Terminology
> +-----------------
>
> The jargon used to talk about Smack will be familiar to those who have dealt
> with other MAC systems and shouldn't be too difficult for the uninitiated to
> pick up. There are four terms that are used in a specific way and that are
> especially important:
>
> - Subject: A subject is an active entity on the computer system.
> + Subject:
> + A subject is an active entity on the computer system.
> On Smack a subject is a task, which is in turn the basic unit
> of execution.
>
> - Object: An object is a passive entity on the computer system.
> + Object:
> + An object is a passive entity on the computer system.
> On Smack files of all types, IPC, and tasks can be objects.
>
> - Access: Any attempt by a subject to put information into or get
> + Access:
> + Any attempt by a subject to put information into or get
> information from an object is an access.
>
> - Label: Data that identifies the Mandatory Access Control
> + Label:
> + Data that identifies the Mandatory Access Control
> characteristics of a subject or an object.
>
> These definitions are consistent with the traditional use in the security
> community. There are also some terms from Linux that are likely to crop up:
>
> - Capability: A task that possesses a capability has permission to
> + Capability:
> + A task that possesses a capability has permission to
> violate an aspect of the system security policy, as identified by
> the specific capability. A task that possesses one or more
> capabilities is a privileged task, whereas a task with no
> capabilities is an unprivileged task.
>
> - Privilege: A task that is allowed to violate the system security
> + Privilege:
> + A task that is allowed to violate the system security
> policy is said to have privilege. As of this writing a task can
> have privilege either by possessing capabilities or by having an
> effective user of root.
>
> Smack Basics
> +------------
>
> Smack is an extension to a Linux system. It enforces additional restrictions
> on what subjects can access which objects, based on the labels attached to
> each of the subject and the object.
>
> Labels
> +~~~~~~
>
> Smack labels are ASCII character strings. They can be up to 255 characters
> long, but keeping them to twenty-three characters is recommended.
> @@ -377,7 +448,7 @@ contain unprintable characters, the "/" (slash), the "\" (backslash), the "'"
> (quote) and '"' (double-quote) characters.
> Smack labels cannot begin with a '-'. This is reserved for special options.
>
> -There are some predefined labels:
> +There are some predefined labels::
>
> _ Pronounced "floor", a single underscore character.
> ^ Pronounced "hat", a single circumflex character.
> @@ -390,14 +461,18 @@ of a process will usually be assigned by the system initialization
> mechanism.
>
> Access Rules
> +~~~~~~~~~~~~
>
> Smack uses the traditional access modes of Linux. These modes are read,
> execute, write, and occasionally append. There are a few cases where the
> access mode may not be obvious. These include:
>
> - Signals: A signal is a write operation from the subject task to
> + Signals:
> + A signal is a write operation from the subject task to
> the object task.
> - Internet Domain IPC: Transmission of a packet is considered a
> +
> + Internet Domain IPC:
> + Transmission of a packet is considered a
> write operation from the source task to the destination task.
>
> Smack restricts access based on the label attached to a subject and the label
> @@ -417,6 +492,7 @@ order:
> 7. Any other access is denied.
>
> Smack Access Rules
> +~~~~~~~~~~~~~~~~~~
>
> With the isolation provided by Smack access separation is simple. There are
> many interesting cases where limited access by subjects to objects with
> @@ -427,8 +503,9 @@ be "born" highly classified. To accommodate such schemes Smack includes a
> mechanism for specifying rules allowing access between labels.
>
> Access Rule Format
> +~~~~~~~~~~~~~~~~~~
>
> -The format of an access rule is:
> +The format of an access rule is::
>
> subject-label object-label access
>
> @@ -446,7 +523,7 @@ describe access modes:
>
> Uppercase values for the specification letters are allowed as well.
> Access mode specifications can be in any order. Examples of acceptable rules
> -are:
> +are::
>
> TopSecret Secret rx
> Secret Unclass R
> @@ -456,7 +533,7 @@ are:
> New Old rRrRr
> Closed Off -
>
> -Examples of unacceptable rules are:
> +Examples of unacceptable rules are::
>
> Top Secret Secret rx
> Ace Ace r
> @@ -469,6 +546,7 @@ access specifications. The dash is a placeholder, so "a-r" is the same
> as "ar". A lone dash is used to specify that no access should be allowed.
>
> Applying Access Rules
> +~~~~~~~~~~~~~~~~~~~~~
>
> The developers of Linux rarely define new sorts of things, usually importing
> schemes and concepts from other systems. Most often, the other systems are
> @@ -511,6 +589,7 @@ one process to another requires that the sender have write access to the
> receiver. The receiver is not required to have read access to the sender.
>
> Setting Access Rules
> +~~~~~~~~~~~~~~~~~~~~
>
> The configuration file /etc/smack/accesses contains the rules to be set at
> system startup. The contents are written to the special file
> @@ -520,6 +599,7 @@ one rule, with the most recently specified overriding any earlier
> specification.
>
> Task Attribute
> +~~~~~~~~~~~~~~
>
> The Smack label of a process can be read from /proc/<pid>/attr/current. A
> process can read its own Smack label from /proc/self/attr/current. A
> @@ -527,12 +607,14 @@ privileged process can change its own Smack label by writing to
> /proc/self/attr/current but not the label of another process.
>
> File Attribute
> +~~~~~~~~~~~~~~
>
> The Smack label of a filesystem object is stored as an extended attribute
> named SMACK64 on the file. This attribute is in the security namespace. It can
> only be changed by a process with privilege.
>
> Privilege
> +~~~~~~~~~
>
> A process with CAP_MAC_OVERRIDE or CAP_MAC_ADMIN is privileged.
> CAP_MAC_OVERRIDE allows the process access to objects it would
> @@ -540,6 +622,7 @@ be denied otherwise. CAP_MAC_ADMIN allows a process to change
> Smack data, including rules and attributes.
>
> Smack Networking
> +~~~~~~~~~~~~~~~~
>
> As mentioned before, Smack enforces access control on network protocol
> transmissions. Every packet sent by a Smack process is tagged with its Smack
> @@ -551,6 +634,7 @@ packet has write access to the receiving process and if that is not the case
> the packet is dropped.
>
> CIPSO Configuration
> +~~~~~~~~~~~~~~~~~~~
>
> It is normally unnecessary to specify the CIPSO configuration. The default
> values used by the system handle all internal cases. Smack will compose CIPSO
> @@ -571,13 +655,13 @@ discarded. The DOI is 3 by default. The value can be read from
> The label and category set are mapped to a Smack label as defined in
> /etc/smack/cipso.
>
> -A Smack/CIPSO mapping has the form:
> +A Smack/CIPSO mapping has the form::
>
> smack level [category [category]*]
>
> Smack does not expect the level or category sets to be related in any
> particular way and does not assume or assign accesses based on them. Some
> -examples of mappings:
> +examples of mappings::
>
> TopSecret 7
> TS:A,B 7 1 2
> @@ -597,25 +681,30 @@ value can be read from /sys/fs/smackfs/direct and changed by writing to
> /sys/fs/smackfs/direct.
>
> Socket Attributes
> +~~~~~~~~~~~~~~~~~
>
> There are two attributes that are associated with sockets. These attributes
> can only be set by privileged tasks, but any task can read them for their own
> sockets.
>
> - SMACK64IPIN: The Smack label of the task object. A privileged
> + SMACK64IPIN:
> + The Smack label of the task object. A privileged
> program that will enforce policy may set this to the star label.
>
> - SMACK64IPOUT: The Smack label transmitted with outgoing packets.
> + SMACK64IPOUT:
> + The Smack label transmitted with outgoing packets.
> A privileged program may set this to match the label of another
> task with which it hopes to communicate.
>
> Smack Netlabel Exceptions
> +~~~~~~~~~~~~~~~~~~~~~~~~~
>
> You will often find that your labeled application has to talk to the outside,
> unlabeled world. To do this there's a special file /sys/fs/smackfs/netlabel
> -where you can add some exceptions in the form of :
> -@IP1 LABEL1 or
> -@IP2/MASK LABEL2
> +where you can add some exceptions in the form of::
> +
> + @IP1 LABEL1 or
> + @IP2/MASK LABEL2
>
> It means that your application will have unlabeled access to @IP1 if it has
> write access on LABEL1, and access to the subnet @IP2/MASK if it has write
> @@ -624,28 +713,32 @@ access on LABEL2.
> Entries in the /sys/fs/smackfs/netlabel file are matched by longest mask
> first, like in classless IPv4 routing.
>
> -A special label '@' and an option '-CIPSO' can be used there :
> -@ means Internet, any application with any label has access to it
> --CIPSO means standard CIPSO networking
> +A special label '@' and an option '-CIPSO' can be used there::
>
> -If you don't know what CIPSO is and don't plan to use it, you can just do :
> -echo 127.0.0.1 -CIPSO > /sys/fs/smackfs/netlabel
> -echo 0.0.0.0/0 @ > /sys/fs/smackfs/netlabel
> + @ means Internet, any application with any label has access to it
> + -CIPSO means standard CIPSO networking
> +
> +If you don't know what CIPSO is and don't plan to use it, you can just do::
> +
> + echo 127.0.0.1 -CIPSO > /sys/fs/smackfs/netlabel
> + echo 0.0.0.0/0 @ > /sys/fs/smackfs/netlabel
>
> If you use CIPSO on your 192.168.0.0/16 local network and need also unlabeled
> -Internet access, you can have :
> -echo 127.0.0.1 -CIPSO > /sys/fs/smackfs/netlabel
> -echo 192.168.0.0/16 -CIPSO > /sys/fs/smackfs/netlabel
> -echo 0.0.0.0/0 @ > /sys/fs/smackfs/netlabel
> +Internet access, you can have::
>
> + echo 127.0.0.1 -CIPSO > /sys/fs/smackfs/netlabel
> + echo 192.168.0.0/16 -CIPSO > /sys/fs/smackfs/netlabel
> + echo 0.0.0.0/0 @ > /sys/fs/smackfs/netlabel
>
> Writing Applications for Smack
> +------------------------------
>
> There are three sorts of applications that will run on a Smack system. How an
> application interacts with Smack will determine what it will have to do to
> work properly under Smack.
>
> Smack Ignorant Applications
> +---------------------------
>
> By far the majority of applications have no reason whatever to care about the
> unique properties of Smack. Since invoking a program has no impact on the
> @@ -653,12 +746,14 @@ Smack label associated with the process the only concern likely to arise is
> whether the process has execute access to the program.
>
> Smack Relevant Applications
> +---------------------------
>
> Some programs can be improved by teaching them about Smack, but do not make
> any security decisions themselves. The utility ls(1) is one example of such a
> program.
>
> Smack Enforcing Applications
> +----------------------------
>
> These are special programs that not only know about Smack, but participate in
> the enforcement of system policy. In most cases these are the programs that
> @@ -666,15 +761,16 @@ set up user sessions. There are also network services that provide information
> to processes running with various labels.
>
> File System Interfaces
> +----------------------
>
> Smack maintains labels on file system objects using extended attributes. The
> Smack label of a file, directory, or other file system object can be obtained
> -using getxattr(2).
> +using getxattr(2)::
>
> len = getxattr("/", "security.SMACK64", value, sizeof (value));
>
> will put the Smack label of the root directory into value. A privileged
> -process can set the Smack label of a file system object with setxattr(2).
> +process can set the Smack label of a file system object with setxattr(2)::
>
> len = strlen("Rubble");
> rc = setxattr("/foo", "security.SMACK64", "Rubble", len, 0);
> @@ -683,17 +779,18 @@ will set the Smack label of /foo to "Rubble" if the program has appropriate
> privilege.
>
> Socket Interfaces
> +-----------------
>
> The socket attributes can be read using fgetxattr(2).
>
> A privileged process can set the Smack label of outgoing packets with
> -fsetxattr(2).
> +fsetxattr(2)::
>
> len = strlen("Rubble");
> rc = fsetxattr(fd, "security.SMACK64IPOUT", "Rubble", len, 0);
>
> will set the Smack label "Rubble" on packets going out from the socket if the
> -program has appropriate privilege.
> +program has appropriate privilege::
>
> rc = fsetxattr(fd, "security.SMACK64IPIN, "*", strlen("*"), 0);
>
> @@ -701,33 +798,40 @@ will set the Smack label "*" as the object label against which incoming
> packets will be checked if the program has appropriate privilege.
>
> Administration
> +--------------
>
> Smack supports some mount options:
>
> - smackfsdef=label: specifies the label to give files that lack
> + smackfsdef=label:
> + specifies the label to give files that lack
> the Smack label extended attribute.
>
> - smackfsroot=label: specifies the label to assign the root of the
> + smackfsroot=label:
> + specifies the label to assign the root of the
> file system if it lacks the Smack extended attribute.
>
> - smackfshat=label: specifies a label that must have read access to
> + smackfshat=label:
> + specifies a label that must have read access to
> all labels set on the filesystem. Not yet enforced.
>
> - smackfsfloor=label: specifies a label to which all labels set on the
> + smackfsfloor=label:
> + specifies a label to which all labels set on the
> filesystem must have read access. Not yet enforced.
>
> These mount options apply to all file system types.
>
> Smack auditing
> +--------------
>
> If you want Smack auditing of security events, you need to set CONFIG_AUDIT
> in your kernel configuration.
> By default, all denied events will be audited. You can change this behavior by
> -writing a single character to the /sys/fs/smackfs/logging file :
> -0 : no logging
> -1 : log denied (default)
> -2 : log accepted
> -3 : log denied & accepted
> +writing a single character to the /sys/fs/smackfs/logging file::
> +
> + 0 : no logging
> + 1 : log denied (default)
> + 2 : log accepted
> + 3 : log denied & accepted
>
> Events are logged as 'key=value' pairs, for each event you at least will get
> the subject, the object, the rights requested, the action, the kernel function
> @@ -735,6 +839,7 @@ that triggered the event, plus other pairs depending on the type of event
> audited.
>
> Bringup Mode
> +------------
>
> Bringup mode provides logging features that can make application
> configuration and system bringup easier. Configure the kernel with
> diff --git a/Documentation/admin-guide/LSM/index.rst b/Documentation/admin-guide/LSM/index.rst
> index 41f5262359f9..c980dfe9abf1 100644
> --- a/Documentation/admin-guide/LSM/index.rst
> +++ b/Documentation/admin-guide/LSM/index.rst
> @@ -36,5 +36,6 @@ the one "major" module (e.g. SELinux) if there is one configured.
> apparmor
> LoadPin
> SELinux
> + Smack
> tomoyo
> Yama
> diff --git a/Documentation/security/00-INDEX b/Documentation/security/00-INDEX
> index a55f781be0dd..cdb2294ec047 100644
> --- a/Documentation/security/00-INDEX
> +++ b/Documentation/security/00-INDEX
> @@ -1,7 +1,5 @@
> 00-INDEX
> - this file.
> -Smack.txt
> - - documentation on the Smack Linux Security Module.
> keys-ecryptfs.txt
> - description of the encryption keys for the ecryptfs filesystem.
> keys-request-key.txt
> diff --git a/MAINTAINERS b/MAINTAINERS
> index 3c1560c75aa6..3e78b5c9b3f9 100644
> --- a/MAINTAINERS
> +++ b/MAINTAINERS
> @@ -11876,7 +11876,7 @@ L: linux-security-module@xxxxxxxxxxxxxxx
> W: http://schaufler-ca.com
> T: git git://github.com/cschaufler/smack-next
> S: Maintained
> -F: Documentation/security/Smack.txt
> +F: Documentation/admin-guide/LSM/Smack.rst
> F: security/smack/
>
> DRIVERS FOR ADAPTIVE VOLTAGE SCALING (AVS)
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html
