summaryrefslogtreecommitdiffstats
path: root/Documentation/security
diff options
context:
space:
mode:
Diffstat (limited to 'Documentation/security')
-rw-r--r--Documentation/security/00-INDEX22
-rw-r--r--Documentation/security/LSM.txt34
-rw-r--r--Documentation/security/SELinux.txt27
-rw-r--r--Documentation/security/Smack.txt665
-rw-r--r--Documentation/security/Yama.txt73
-rw-r--r--Documentation/security/apparmor.txt39
-rw-r--r--Documentation/security/credentials.txt581
-rw-r--r--Documentation/security/keys-ecryptfs.txt68
-rw-r--r--Documentation/security/keys-request-key.txt202
-rw-r--r--Documentation/security/keys-trusted-encrypted.txt160
-rw-r--r--Documentation/security/keys.txt1323
-rw-r--r--Documentation/security/tomoyo.txt55
12 files changed, 0 insertions, 3249 deletions
diff --git a/Documentation/security/00-INDEX b/Documentation/security/00-INDEX
deleted file mode 100644
index eeed1de546d..00000000000
--- a/Documentation/security/00-INDEX
+++ /dev/null
@@ -1,22 +0,0 @@
-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
- - documentation on the Smack Linux Security Module.
-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-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.
-tomoyo.txt
- - documentation on the TOMOYO Linux Security Module.
diff --git a/Documentation/security/LSM.txt b/Documentation/security/LSM.txt
deleted file mode 100644
index c335a763a2e..00000000000
--- a/Documentation/security/LSM.txt
+++ /dev/null
@@ -1,34 +0,0 @@
-Linux Security Module framework
--------------------------------
-
-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
-LSMs were built into a given kernel.
-
-The primary users of the LSM interface are Mandatory Access Control
-(MAC) extensions which provide a comprehensive security policy. Examples
-include SELinux, Smack, Tomoyo, and AppArmor. In addition to the larger
-MAC extensions, other extensions can be built using the LSM to provide
-specific changes to system operation when these tweaks are not available
-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
-man-pages project.
-
-Based on http://kerneltrap.org/Linux/Documenting_Security_Module_Intent,
-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/security/SELinux.txt b/Documentation/security/SELinux.txt
deleted file mode 100644
index 07eae00f331..00000000000
--- a/Documentation/security/SELinux.txt
+++ /dev/null
@@ -1,27 +0,0 @@
-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
-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.
- 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:
- 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.
diff --git a/Documentation/security/Smack.txt b/Documentation/security/Smack.txt
deleted file mode 100644
index a416479b8a1..00000000000
--- a/Documentation/security/Smack.txt
+++ /dev/null
@@ -1,665 +0,0 @@
-
-
- "Good for you, you've decided to clean the elevator!"
- - The Elevator, from Dark Star
-
-Smack is the the Simplified Mandatory Access Control Kernel.
-Smack is a kernel based implementation of mandatory access
-control that includes simplicity in its primary design goals.
-
-Smack is not the only Mandatory Access Control scheme
-available for Linux. Those new to Mandatory Access Control
-are encouraged to compare Smack with the other mechanisms
-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
-
-The kernel component of Smack is implemented as a Linux
-Security Modules (LSM) module. It requires netlabel and
-works best with file systems that support extended attributes,
-although xattr support is not strictly required.
-It is safe to run a Smack kernel under a "vanilla" distribution.
-
-Smack kernels use the CIPSO IP option. Some network
-configurations are intolerant of IP options and can impede
-access to systems that use them as Smack does.
-
-The current git repositories for Smack user space are:
-
- git@gitorious.org:meego-platform-security/smackutil.git
- git@gitorious.org:meego-platform-security/libsmack.git
-
-These should make and install on most modern distributions.
-There are three commands included in smackutil:
-
-smackload - properly formats data for writing to /smack/load
-smackcipso - properly formats data for writing to /smack/cipso
-chsmack - display or set Smack extended attribute values
-
-In keeping with the intent of Smack, configuration data is
-minimal and not strictly required. The most important
-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:
-
- smackfs /smack smackfs smackfsdef=* 0 0
-
-and create the /smack directory for mounting.
-
-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
-attributes.
-
-The extended attributes that Smack uses are:
-
-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
- the Smack rule (more below) that permitted the write access
- to the directory includes the transmute ("t") mode the object
- 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:
-
- # 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
-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 usually
-mounted on /smack.
-
-access
- This interface reports whether a subject with the specified
- Smack label has a particular access to an object with a
- specified Smack label. Write a fixed format access rule to
- 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
- specified Smack label. Write a long format access rule to
- 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.
-cipso
- This interface allows a specific CIPSO header to be assigned
- 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"
-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"]...
- 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"
-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.
-load
- This interface allows access control rules in addition to
- the system defined rules to be specified. The format accepted
- 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
- 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. 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:
- "%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
- 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 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:
- "%d.%d.%d.%d label" or "%d.%d.%d.%d/%d label".
-onlycap
- This contains the label processes must have for CAP_MAC_ADMIN
- and CAP_MAC_OVERRIDE to be effective. If this file is empty
- these capabilities are effective at for processes with any
- label. The value is set by writing the desired label to the
- file or cleared by writing "-" to the file.
-
-You can add access rules in /etc/smack/accesses. They take the form:
-
- subjectlabel objectlabel access
-
-access is a combination of the letters rwxa which specify the
-kind of access permitted a subject with subjectlabel on an
-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
-
-Casey Schaufler
-casey@schaufler-ca.com
-
-Mandatory Access Control
-
-Computer systems employ a variety of schemes to constrain how information is
-shared among the people and services using the machine. Some of these schemes
-allow the program or user to decide what other programs or users are allowed
-access to pieces of data. These schemes are called discretionary access
-control mechanisms because the access control is specified at the discretion
-of the user. Other schemes do not leave the decision regarding what a user or
-program can access up to users or programs. These schemes are called mandatory
-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
-model, a mathematical description of the United States Department of Defense
-policy for marking paper documents. MAC in this form enjoyed a following
-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
-protected from each other. This scheme has been widely deployed as a component
-of popular Linux distributions. The administrative overhead required to
-maintain this scheme and the detailed understanding of the whole system
-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 &
-LaPadula are addressed by providing a scheme whereby access can be controlled
-according to the requirements of the system and its purpose rather than those
-imposed by an arcane government policy. The complexity of Domain Type
-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.
- 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.
- On Smack files of all types, IPC, and tasks can be objects.
-
- 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
- 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
- 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
- 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, one to twenty-three characters in
-length. Single character labels using special characters, that being anything
-other than a letter or digit, are reserved for use by the Smack development
-team. Smack labels are unstructured, case sensitive, and the only operation
-ever performed on them is comparison for equality. Smack labels cannot
-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:
-
- _ Pronounced "floor", a single underscore character.
- ^ Pronounced "hat", a single circumflex character.
- * Pronounced "star", a single asterisk character.
- ? Pronounced "huh", a single question mark character.
- @ Pronounced "web", a single at sign character.
-
-Every task on a Smack system is assigned a label. System tasks, such as
-init(8) and systems daemons, are run with the floor ("_") label. User tasks
-are assigned labels according to the specification found in the
-/etc/smack/user configuration file.
-
-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
- the object task.
- 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
-attached to the object it is trying to access. The rules enforced are, in
-order:
-
- 1. Any access requested by a task labeled "*" is denied.
- 2. A read or execute access requested by a task labeled "^"
- is permitted.
- 3. A read or execute access requested on an object labeled "_"
- is permitted.
- 4. Any access requested on an object labeled "*" is permitted.
- 5. Any access requested by a task on an object with the same
- label is permitted.
- 6. Any access requested that is explicitly defined in the loaded
- rule set is permitted.
- 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
-different labels is desired. One example is the familiar spy model of
-sensitivity, where a scientist working on a highly classified project would be
-able to read documents of lower classifications and anything she writes will
-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:
-
- subject-label object-label access
-
-Where subject-label is the Smack label of the task, object-label is the Smack
-label of the thing being accessed, and access is a string specifying the sort
-of access allowed. The access specification is searched for letters that
-describe access modes:
-
- a: indicates that append access should be granted.
- r: indicates that read access should be granted.
- w: indicates that write access should be granted.
- x: indicates that execute access should be granted.
- t: indicates that the rule requests transmutation.
-
-Uppercase values for the specification letters are allowed as well.
-Access mode specifications can be in any order. Examples of acceptable rules
-are:
-
- TopSecret Secret rx
- Secret Unclass R
- Manager Game x
- User HR w
- New Old rRrRr
- Closed Off -
-
-Examples of unacceptable rules are:
-
- Top Secret Secret rx
- Ace Ace r
- Odd spells waxbeans
-
-Spaces are not allowed in labels. Since a subject always has access to files
-with the same label specifying a rule for that case is pointless. Only
-valid letters (rwxatRWXAT) and the dash ('-') character are allowed in
-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
-variants of Unix. Unix has many endearing properties, but consistency of
-access control models is not one of them. Smack strives to treat accesses as
-uniformly as is sensible while keeping with the spirit of the underlying
-mechanism.
-
-File system objects including files, directories, named pipes, symbolic links,
-and devices require access permissions that closely match those used by mode
-bit access. To open a file for reading read access is required on the file. To
-search a directory requires execute access. Creating a file with write access
-requires both read and write access on the containing directory. Deleting a
-file requires read and write access to the file and to the containing
-directory. It is possible that a user may be able to see that a file exists
-but not any of its attributes by the circumstance of having read access to the
-containing directory but not to the differently labeled file. This is an
-artifact of the file name being data in the directory, not a part of the file.
-
-If a directory is marked as transmuting (SMACK64TRANSMUTE=TRUE) and the
-access rule that allows a process to create an object in that directory
-includes 't' access the label assigned to the new object will be that
-of the directory, not the creating process. This makes it much easier
-for two processes with different labels to share data without granting
-access to all of their files.
-
-IPC objects, message queues, semaphore sets, and memory segments exist in flat
-namespaces and access requests are only required to match the object in
-question.
-
-Process objects reflect tasks on the system and the Smack label used to access
-them is the same Smack label that the task would use for its own access
-attempts. Sending a signal via the kill() system call is a write operation
-from the signaler to the recipient. Debugging a process requires both reading
-and writing. Creating a new task is an internal operation that results in two
-tasks with identical Smack labels and requires no access checks.
-
-Sockets are data structures attached to processes and sending a packet from
-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 /smack/load.
-Rules can be written to /smack/load at any time and take effect immediately.
-For any pair of subject and object labels there can be only one rule, with the
-most recently specified overriding any earlier specification.
-
-The program smackload is provided to ensure data is formatted
-properly when written to /smack/load. This program reads lines
-of the form
-
- subjectlabel objectlabel mode.
-
-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
-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 is privileged.
-
-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
-label. This is done by adding a CIPSO tag to the header of the IP packet. Each
-packet received is expected to have a CIPSO tag that identifies the label and
-if it lacks such a tag the network ambient label is assumed. Before the packet
-is delivered a check is made to determine that a subject with the label on the
-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
-label values to match the Smack labels being used without administrative
-intervention. Unlabeled packets that come into the system will be given the
-ambient label.
-
-Smack requires configuration in the case where packets from a system that is
-not smack that speaks CIPSO may be encountered. Usually this will be a Trusted
-Solaris system, but there are other, less widely deployed systems out there.
-CIPSO provides 3 important values, a Domain Of Interpretation (DOI), a level,
-and a category set with each packet. The DOI is intended to identify a group
-of systems that use compatible labeling schemes, and the DOI specified on the
-smack system must match that of the remote system or packets will be
-discarded. The DOI is 3 by default. The value can be read from /smack/doi and
-can be changed by writing to /smack/doi.
-
-The label and category set are mapped to a Smack label as defined in
-/etc/smack/cipso.
-
-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:
-
- TopSecret 7
- TS:A,B 7 1 2
- SecBDE 5 2 4 6
- RAFTERS 7 12 26
-
-The ":" and "," characters are permitted in a Smack label but have no special
-meaning.
-
-The mapping of Smack labels to CIPSO values is defined by writing to
-/smack/cipso. Again, the format of data written to this special file
-is highly restrictive, so the program smackcipso is provided to
-ensure the writes are done properly. This program takes mappings
-on the standard input and sends them to /smack/cipso properly.
-
-In addition to explicit mappings Smack supports direct CIPSO mappings. One
-CIPSO level is used to indicate that the category set passed in the packet is
-in fact an encoding of the Smack label. The level used is 250 by default. The
-value can be read from /smack/direct and changed by writing to /smack/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
- program that will enforce policy may set this to the star label.
-
- 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 /smack/netlabel 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
-access on LABEL2.
-
-Entries in the /smack/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
-
-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 > /smack/netlabel
-echo 0.0.0.0/0 @ > /smack/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 > /smack/netlabel
-echo 192.168.0.0/16 -CIPSO > /smack/netlabel
-echo 0.0.0.0/0 @ > /smack/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
-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
-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).
-
- 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).
-
- len = strlen("Rubble");
- rc = setxattr("/foo", "security.SMACK64", "Rubble", len, 0);
-
-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).
-
- 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.
-
- rc = fsetxattr(fd, "security.SMACK64IPIN, "*", strlen("*"), 0);
-
-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
- the Smack label extended attribute.
-
- 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
- all labels set on the filesystem. Not yet enforced.
-
- 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 /smack/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
-that triggered the event, plus other pairs depending on the type of event
-audited.
diff --git a/Documentation/security/Yama.txt b/Documentation/security/Yama.txt
deleted file mode 100644
index e369de2d48c..00000000000
--- a/Documentation/security/Yama.txt
+++ /dev/null
@@ -1,73 +0,0 @@
-Yama is a Linux Security Module that collects a number of system-wide DAC
-security protections that are not handled by the core kernel itself. To
-select it at boot time, specify "security=yama" (though this will disable
-any other LSM).
-
-Yama is controlled through sysctl 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
-interfaces is that a single user is able to examine the memory and
-running state of any of their processes. For example, if one application
-(e.g. Pidgin) was compromised, it would be possible for an attacker to
-attach to other running processes (e.g. Firefox, SSH sessions, GPG agent,
-etc) to extract additional credentials and continue to expand the scope
-of their attack without resorting to user-assisted phishing.
-
-This is not a theoretical problem. SSH session hijacking
-(http://www.storm.net.nz/projects/7) and arbitrary code injection
-(http://c-skills.blogspot.com/2007/05/injectso.html) attacks already
-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
-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"
-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 descendents) 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, ...)
-so that any otherwise allowed process (even those in external pid namespaces)
-may attach.
-
-These restrictions do not change how ptrace via PTRACE_TRACEME operates.
-
-The sysctl settings are:
-
-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).
-
-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.
-
-2 - admin-only attach: only processes with CAP_SYS_PTRACE may use ptrace
- with PTRACE_ATTACH.
-
-3 - no attach: no processes may use ptrace with PTRACE_ATTACH. Once set,
- this sysctl cannot be changed to a lower value.
-
-The original children-only logic was based on the restrictions in grsecurity.
-
-==============================================================
diff --git a/Documentation/security/apparmor.txt b/Documentation/security/apparmor.txt
deleted file mode 100644
index 93c1fd7d063..00000000000
--- a/Documentation/security/apparmor.txt
+++ /dev/null
@@ -1,39 +0,0 @@
---- 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
-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 ---
-
-set CONFIG_SECURITY_APPARMOR=y
-
-If AppArmor should be selected as the default security module then
- set CONFIG_DEFAULT_SECURITY="apparmor"
- and 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.
-
-If AppArmor is the default security module it can be disabled by passing
-apparmor=0, security=XXXX (where XXX is valid security module), on the
-kernel's command line
-
-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 can be found on the wiki.
-
---- Links ---
-
-Mailing List - apparmor@lists.ubuntu.com
-Wiki - http://apparmor.wiki.kernel.org/
-User space tools - https://launchpad.net/apparmor
-Kernel module - git://git.kernel.org/pub/scm/linux/kernel/git/jj/apparmor-dev.git
diff --git a/Documentation/security/credentials.txt b/Documentation/security/credentials.txt
deleted file mode 100644
index 86257052e31..00000000000
--- a/Documentation/security/credentials.txt
+++ /dev/null
@@ -1,581 +0,0 @@
- ====================
- CREDENTIALS IN LINUX
- ====================
-
-By: David Howells <dhowells@redhat.com>
-
-Contents:
-
- (*) Overview.
-
- (*) Types of credentials.
-
- (*) File markings.
-
- (*) Task credentials.
-
- - 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
-========
-
-There are several parts to the security check performed by Linux when one
-object acts upon another:
-
- (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:
-
- - Tasks
- - Files/inodes
- - Sockets
- - Message queues
- - Shared memory segments
- - Semaphores
- - Keys
-
- 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.
-
- Amongst the credentials of most objects, there will be a subset that
- indicates the ownership of that object. This is used for resource
- accounting and limitation (disk quotas and task rlimits for example).
-
- In a standard UNIX filesystem, for instance, this will be defined by the
- UID marked on the inode.
-
- (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
- the same set as in (2) - in standard UNIX files, for instance, this is the
- defined by the UID and the GID marked on the inode.
-
- The objective context is used as part of the security calculation that is
- carried out when an object is acted upon.
-
- (4) Subjects.
-
- A subject is an object that is acting upon another object.
-
- Most of the objects in the system are inactive: they don't act on other
- objects within the system. Processes/tasks are the obvious exception:
- they do stuff; they access and manipulate things.
-
- 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,
- the file struct will have a subjective context too.
-
- (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
- is used as part of the security calculation that is carried out when a
- subject acts.
-
- A Linux task, for example, has the FSUID, FSGID and the supplementary
- group list for when it is acting upon a file - which are quite separate
- from the real UID and GID that normally form the objective context of the
- task.
-
- (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
- and the object.
-
- Actions include reading, writing, creating and deleting files; forking or
- signalling and tracing tasks.
-
- (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
- action, and searching one or more sets of rules to see whether the subject
- is granted or denied permission to act in the desired manner on the
- object, given those contexts.
-
- There are two main sources of rules:
-
- (a) Discretionary access control (DAC):
-
- Sometimes the object will include sets of rules as part of its
- description. This is an 'Access Control List' or 'ACL'. A Linux
- file may supply more than one ACL.
-
- A traditional UNIX file, for example, includes a permissions mask that
- is an abbreviated ACL with three fixed classes of subject ('user',
- 'group' and 'other'), each of which may be granted certain privileges
- ('read', 'write' and 'execute' - whatever those map to for the object
- in question). UNIX file permissions do not allow the arbitrary
- specification of subjects, however, and so are of limited use.
-
- A Linux file might also sport a POSIX ACL. This is a list of rules
- that grants various permissions to arbitrary subjects.
-
- (b) Mandatory access control (MAC):
-
- The system as a whole may have one or more sets of rules that get
- applied to all subjects and objects, regardless of their source.
- SELinux and Smack are examples of this.
-
- In the case of SELinux and Smack, each object is given a label as part
- of its credentials. When an action is requested, they take the
- subject label, the object label and the action and look for a rule
- that says that this action is either granted or denied.
-
-
-====================
-TYPES OF CREDENTIALS
-====================
-
-The Linux kernel supports the following types of credentials:
-
- (1) Traditional UNIX credentials.
-
- Real User ID
- Real Group ID
-
- The UID and GID are carried by most, if not all, Linux objects, even if in
- some cases it has to be invented (FAT or CIFS files for example, which are
- derived from Windows). These (mostly) define the objective context of
- that object, with tasks being slightly different in some cases.
-
- Effective, Saved and FS User ID
- Effective, Saved and FS Group ID
- Supplementary groups
-
- These are additional credentials used by tasks only. Usually, an
- EUID/EGID/GROUPS will be used as the subjective context, and real UID/GID
- will be used as the objective. For tasks, it should be noted that this is
- not always true.
-
- (2) Capabilities.
-
- Set of permitted capabilities
- Set of inheritable capabilities
- Set of effective capabilities
- Capability bounding set
-
- These are only carried by tasks. They indicate superior capabilities
- granted piecemeal to a task that an ordinary task wouldn't otherwise have.
- These are manipulated implicitly by changes to the traditional UNIX
- credentials, but can also be manipulated directly by the capset() system
- call.
-
- The permitted capabilities are those caps that the process might grant
- itself to its effective or permitted sets through capset(). This
- inheritable set might also be so constrained.
-
- The effective capabilities are the ones that a task is actually allowed to
- make use of itself.
-
- The inheritable capabilities are the ones that may get passed across
- execve().
-
- The bounding set limits the capabilities that may be inherited across
- execve(), especially when a binary is executed that will execute as UID 0.
-
- (3) Secure management flags (securebits).
-
- These are only carried by tasks. These govern the way the above
- credentials are manipulated and inherited over certain operations such as
- execve(). They aren't used directly as objective or subjective
- credentials.
-
- (4) Keys and keyrings.
-
- These are only carried by tasks. They carry and cache security tokens
- that don't fit into the other standard UNIX credentials. They are for
- making such things as network filesystem keys available to the file
- accesses performed by processes, without the necessity of ordinary
- programs having to know about security details involved.
-
- Keyrings are a special type of key. They carry sets of other keys and can
- be searched for the desired key. Each process may subscribe to a number
- of keyrings:
-
- Per-thread keying
- Per-process keyring
- Per-session keyring
-
- When a process accesses a key, if not already present, it will normally be
- cached on one of these keyrings for future accesses to find.
-
- For more information on using keys, see Documentation/security/keys.txt.
-
- (5) LSM
-
- The Linux Security Module allows extra controls to be placed over the
- operations that a task may do. Currently Linux supports several LSM
- options.
-
- Some work by labelling the objects in a system and then applying sets of
- rules (policies) that say what operations a task with one label may do to
- an object with another label.
-
- (6) AF_KEY
-
- This is a socket-based approach to credential management for networking
- stacks [RFC 2367]. It isn't discussed by this document as it doesn't
- interact directly with task and file credentials; rather it keeps system
- level credentials.
-
-
-When a file is opened, part of the opening task's subjective context is
-recorded in the file struct created. This allows operations using that file
-struct to use those credentials instead of the subjective context of the task
-that issued the operation. An example of this would be a file opened on a
-network filesystem where the credentials of the opened file should be presented
-to the server, regardless of who is actually doing a read or a write upon it.
-
-
-=============
-FILE MARKINGS
-=============
-
-Files on disk or obtained over the network may have annotations that form the
-objective security context of that file. Depending on the type of filesystem,
-this may include one or more of the following:
-
- (*) UNIX UID, GID, mode;
-
- (*) Windows user ID;
-
- (*) Access control list;
-
- (*) LSM security label;
-
- (*) UNIX exec privilege escalation bits (SUID/SGID);
-
- (*) File capabilities exec privilege escalation bits.
-
-These are compared to the task's subjective security context, and certain
-operations allowed or disallowed as a result. In the case of execve(), the
-privilege escalation bits come into play, and may allow the resulting process
-extra privileges, based on the annotations on the executable file.
-
-
-================
-TASK CREDENTIALS
-================
-
-In Linux, all of a task's credentials are held in (uid, gid) or through
-(groups, keys, LSM security) a refcounted structure of type 'struct cred'.
-Each task points to its credentials by a pointer called 'cred' in its
-task_struct.
-
-Once a set of credentials has been prepared and committed, it may not be
-changed, barring the following exceptions:
-
- (1) its reference count may be changed;
-
- (2) the reference count on the group_info struct it points to may be changed;
-
- (3) the reference count on the security data it points to may be changed;
-
- (4) the reference count on any keyrings it points to may be changed;
-
- (5) any keyrings it points to may be revoked, expired or have their security
- attributes changed; and
-
- (6) the contents of any keyrings to which it points may be changed (the whole
- point of keyrings being a shared set of credentials, modifiable by anyone
- with appropriate access).
-
-To alter anything in the cred struct, the copy-and-replace principle must be
-adhered to. First take a copy, then alter the copy and then use RCU to change
-the task pointer to make it point to the new copy. There are wrappers to aid
-with this (see below).
-
-A task may only alter its _own_ credentials; it is no longer permitted for a
-task to alter another's credentials. This means the capset() system call is no
-longer permitted to take any PID other than the one of the current process.
-Also keyctl_instantiate() and keyctl_negate() functions no longer permit
-attachment to process-specific keyrings in the requesting process as the
-instantiating process may need to create them.
-
-
-IMMUTABLE CREDENTIALS
----------------------
-
-Once a set of credentials has been made public (by calling commit_creds() for
-example), it must be considered immutable, barring two exceptions:
-
- (1) The reference count may be altered.
-
- (2) Whilst the keyring subscriptions of a set of credentials may not be
- changed, the keyrings subscribed to may have their contents altered.
-
-To catch accidental credential alteration at compile time, struct task_struct
-has _const_ pointers to its credential sets, as does struct file. Furthermore,
-certain functions such as get_cred() and put_cred() operate on const pointers,
-thus rendering casts unnecessary, but require to temporarily ditch the const
-qualification to be able to alter the reference count.
-
-
-ACCESSING TASK CREDENTIALS
---------------------------
-
-A task being able to alter only its own credentials permits the current process
-to read or replace its own credentials without the need for any form of locking
-- which simplifies things greatly. It can just call:
-
- const struct cred *current_cred()
-
-to get a pointer to its credentials structure, and it doesn't have to release
-it afterwards.
-
-There are convenience wrappers for retrieving specific aspects of a task's
-credentials (the value is simply returned in each case):
-
- uid_t current_uid(void) Current's real UID
- gid_t current_gid(void) Current's real GID
- uid_t current_euid(void) Current's effective UID
- gid_t current_egid(void) Current's effective GID
- uid_t current_fsuid(void) Current's file access UID
- gid_t current_fsgid(void) Current's file access GID
- kernel_cap_t current_cap(void) Current's effective capabilities
- void *current_security(void) Current's LSM security pointer
- struct user_struct *current_user(void) Current's user account
-
-There are also convenience wrappers for retrieving specific associated pairs of
-a task's credentials:
-
- void current_uid_gid(uid_t *, gid_t *);
- void current_euid_egid(uid_t *, gid_t *);
- void current_fsuid_fsgid(uid_t *, gid_t *);
-
-which return these pairs of values through their arguments after retrieving
-them from the current task's credentials.
-
-
-In addition, there is a function for obtaining a reference on the current
-process's current set of credentials:
-
- const struct cred *get_current_cred(void);
-
-and functions for getting references to one of the credentials that don't
-actually live in struct cred:
-
- struct user_struct *get_current_user(void);
- struct group_info *get_current_groups(void);
-
-which get references to the current process's user accounting structure and
-supplementary groups list respectively.
-
-Once a reference has been obtained, it must be released with put_cred(),
-free_uid() or put_group_info() as appropriate.
-
-
-ACCESSING ANOTHER TASK'S CREDENTIALS
-------------------------------------
-
-Whilst a task may access its own credentials without the need for locking, the
-same is not true of a task wanting to access another task's credentials. It
-must use the RCU read lock and rcu_dereference().
-
-The rcu_dereference() is wrapped by:
-
- const struct cred *__task_cred(struct task_struct *task);
-
-This should be used inside the RCU read lock, as in the following example:
-
- void foo(struct task_struct *t, struct foo_data *f)
- {
- const struct cred *tcred;
- ...
- rcu_read_lock();
- tcred = __task_cred(t);
- f->uid = tcred->uid;
- f->gid = tcred->gid;
- f->groups = get_group_info(tcred->groups);
- rcu_read_unlock();
- ...
- }
-
-Should it be necessary to hold another task's credentials for a long period of
-time, and possibly to sleep whilst doing so, then the caller should get a
-reference on them using:
-
- const struct cred *get_task_cred(struct task_struct *task);
-
-This does all the RCU magic inside of it. The caller must call put_cred() on
-the credentials so obtained when they're finished with.
-
- [*] Note: The result of __task_cred() should not be passed directly to
- get_cred() as this may race with commit_cred().
-
-There are a couple of convenience functions to access bits of another task's
-credentials, hiding the RCU magic from the caller:
-
- uid_t task_uid(task) Task's real UID
- uid_t task_euid(task) Task's effective UID
-
-If the caller is holding the RCU read lock at the time anyway, then:
-
- __task_cred(task)->uid
- __task_cred(task)->euid
-
-should be used instead. Similarly, if multiple aspects of a task's credentials
-need to be accessed, RCU read lock should be used, __task_cred() called, the
-result stored in a temporary pointer and then the credential aspects called
-from that before dropping the lock. This prevents the potentially expensive
-RCU magic from being invoked multiple times.
-
-Should some other single aspect of another task's credentials need to be
-accessed, then this can be used:
-
- task_cred_xxx(task, member)
-
-where 'member' is a non-pointer member of the cred struct. For instance:
-
- uid_t task_cred_xxx(task, suid);
-
-will retrieve 'struct cred::suid' from the task, doing the appropriate RCU
-magic. This may not be used for pointer members as what they point to may
-disappear the moment the RCU read lock is dropped.
-
-
-ALTERING CREDENTIALS
---------------------
-
-As previously mentioned, a task may only alter its own credentials, and may not
-alter those of another task. This means that it doesn't need to use any
-locking to alter its own credentials.
-
-To alter the current process's credentials, a function should first prepare a
-new set of credentials by calling:
-
- struct cred *prepare_creds(void);
-
-this locks current->cred_replace_mutex and then allocates and constructs a
-duplicate of the current process's credentials, returning with the mutex still
-held if successful. It returns NULL if not successful (out of memory).
-
-The mutex prevents ptrace() from altering the ptrace state of a process whilst
-security checks on credentials construction and changing is taking place as
-the ptrace state may alter the outcome, particularly in the case of execve().
-
-The new credentials set should be altered appropriately, and any security
-checks and hooks done. Both the current and the proposed sets of credentials
-are available for this purpose as current_cred() will return the current set
-still at this point.
-
-
-When the credential set is ready, it should be committed to the current process
-by calling:
-
- int commit_creds(struct cred *new);
-
-This will alter various aspects of the credentials and the process, giving the
-LSM a chance to do likewise, then it will use rcu_assign_pointer() to actually
-commit the new credentials to current->cred, it will release
-current->cred_replace_mutex to allow ptrace() to take place, and it will notify
-the scheduler and others of the changes.
-
-This function is guaranteed to return 0, so that it can be tail-called at the
-end of such functions as sys_setresuid().
-
-Note that this function consumes the caller's reference to the new credentials.
-The caller should _not_ call put_cred() on the new credentials afterwards.
-
-Furthermore, once this function has been called on a new set of credentials,
-those credentials may _not_ be changed further.
-
-
-Should the security checks fail or some other error occur after prepare_creds()
-has been called, then the following function should be invoked:
-
- void abort_creds(struct cred *new);
-
-This releases the lock on current->cred_replace_mutex that prepare_creds() got
-and then releases the new credentials.
-
-
-A typical credentials alteration function would look something like this:
-
- int alter_suid(uid_t suid)
- {
- struct cred *new;
- int ret;
-
- new = prepare_creds();
- if (!new)
- return -ENOMEM;
-
- new->suid = suid;
- ret = security_alter_suid(new);
- if (ret < 0) {
- abort_creds(new);
- return ret;
- }
-
- return commit_creds(new);
- }
-
-
-MANAGING CREDENTIALS
---------------------
-
-There are some functions to help manage credentials:
-
- (*) void put_cred(const struct cred *cred);
-
- This releases a reference to the given set of credentials. If the
- reference count reaches zero, the credentials will be scheduled for
- destruction by the RCU system.
-
- (*) const struct cred *get_cred(const struct cred *cred);
-
- This gets a reference on a live set of credentials, returning a pointer to
- that set of credentials.
-
- (*) struct cred *get_new_cred(struct cred *cred);
-
- This gets a reference on a set of credentials that is under construction
- and is thus still mutable, returning a pointer to that set of credentials.
-
-
-=====================
-OPEN FILE CREDENTIALS
-=====================
-
-When a new file is opened, a reference is obtained on the opening task's
-credentials and this is attached to the file struct as 'f_cred' in place of
-'f_uid' and 'f_gid'. Code that used to access file->f_uid and file->f_gid
-should now access file->f_cred->fsuid and file->f_cred->fsgid.
-
-It is safe to access f_cred without the use of RCU or locking because the
-pointer will not change over the lifetime of the file struct, and nor will the
-contents of the cred struct pointed to, barring the exceptions listed above
-(see the Task Credentials section).
-
-
-=======================================
-OVERRIDING THE VFS'S USE OF CREDENTIALS
-=======================================
-
-Under some circumstances it is desirable to override the credentials used by
-the VFS, and that can be done by calling into such as vfs_mkdir() with a
-different set of credentials. This is done in the following places:
-
- (*) sys_faccessat().
-
- (*) do_coredump().
-
- (*) nfs4recover.c.
diff --git a/Documentation/security/keys-ecryptfs.txt b/Documentation/security/keys-ecryptfs.txt
deleted file mode 100644
index c3bbeba6356..00000000000
--- a/Documentation/security/keys-ecryptfs.txt
+++ /dev/null
@@ -1,68 +0,0 @@
- 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).
-
-Each FEK is in turn encrypted with a File Encryption Key Encryption Key (FEFEK)
-either in kernel space or in user space with a daemon called 'ecryptfsd'. In
-the former case the operation is performed directly by the kernel CryptoAPI
-using a key, the FEFEK, derived from a user prompted passphrase; in the latter
-the FEK is encrypted by 'ecryptfsd' with the help of external libraries in order
-to support other mechanisms like public key cryptography, PKCS#11 and TPM based
-operations.
-
-The data structure defined by eCryptfs to contain information required for the
-FEK decryption is called authentication token and, currently, can be stored in a
-kernel key of the 'user' type, inserted in the user's session specific keyring
-by the userspace utility 'mount.ecryptfs' shipped with the package
-'ecryptfs-utils'.
-
-The 'encrypted' key type has been extended with the introduction of the new
-format 'ecryptfs' in order to be used in conjunction with the eCryptfs
-filesystem. Encrypted keys of the newly introduced format store an
-authentication token in its payload with a FEFEK randomly generated by the
-kernel and protected by the parent master key.
-
-In order to avoid known-plaintext attacks, the datablob obtained through
-commands 'keyctl print' or 'keyctl pipe' does not contain the overall
-authentication token, which content is well known, but only the FEFEK in
-encrypted form.
-
-The eCryptfs filesystem may really benefit from using encrypted keys in that the
-required key can be securely generated by an Administrator and provided at boot
-time after the unsealing of a 'trusted' key in order to perform the mount in a
-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:
- 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
-
-
-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":
-
- $ keyctl add encrypted 1000100010001000 "new ecryptfs user:test 64" @u
- 19184530
-
- $ keyctl print 19184530
- ecryptfs user:test 64 490045d4bfe48c99f0d465fbbbb79e7500da954178e2de0697
- dd85091f5450a0511219e9f7cd70dcd498038181466f78ac8d4c19504fcc72402bfc41c2
- f253a41b7507ccaa4b2b03fff19a69d1cc0b16e71746473f023a95488b6edfd86f7fdd40
- 9d292e4bacded1258880122dd553a661
-
- $ keyctl pipe 19184530 > ecryptfs.blob
-
-Mount an eCryptfs filesystem using the created encrypted key "1000100010001000"
-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-request-key.txt b/Documentation/security/keys-request-key.txt
deleted file mode 100644
index 51987bfecfe..00000000000
--- a/Documentation/security/keys-request-key.txt
+++ /dev/null
@@ -1,202 +0,0 @@
- ===================
- 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*():
-
- struct key *request_key(const struct key_type *type,
- const char *description,
- const char *callout_info);
-
-or:
-
- struct key *request_key_with_auxdata(const struct key_type *type,
- const char *description,
- const char *callout_info,
- size_t callout_len,
- void *aux);
-
-or:
-
- struct key *request_key_async(const struct key_type *type,
- const char *description,
- const char *callout_info,
- size_t callout_len);
-
-or:
-
- struct key *request_key_async_with_auxdata(const struct key_type *type,
- const char *description,
- const char *callout_info,
- size_t callout_len,
- void *aux);
-
-Or by userspace invoking the request_key system call:
-
- key_serial_t request_key(const char *type,
- const char *description,
- const char *callout_info,
- key_serial_t dest_keyring);
-
-The main difference between the access points is that the in-kernel interface
-does not need to link the key to a keyring to prevent it from being immediately
-destroyed. The kernel interface returns a pointer directly to the key, and
-it's up to the caller to destroy the key.
-
-The request_key*_with_auxdata() calls are like the in-kernel request_key*()
-calls, except that they permit auxiliary data to be passed to the upcaller (the
-default is NULL). This is only useful for those key types that define their
-own upcall mechanism rather than using /sbin/request-key.
-
-The two async in-kernel calls may return keys that are still in the process of
-being constructed. The two non-async ones will wait for construction to
-complete first.
-
-The userspace interface links the key to a keyring associated with the process
-to prevent the key from going away, and returns the serial number of the key to
-the caller.
-
-
-The following example assumes that the key types involved don't define their
-own upcall mechanisms. If they do, then those should be substituted for the
-forking and execution of /sbin/request-key.
-
-
-===========
-THE PROCESS
-===========
-
-A request proceeds in the following manner:
-
- (1) Process A calls request_key() [the userspace syscall calls the kernel
- interface].
-
- (2) request_key() searches the process's subscribed keyrings to see if there's
- a suitable key there. If there is, it returns the key. If there isn't,
- and callout_info is not set, an error is returned. Otherwise the process
- proceeds to the next step.
-
- (3) request_key() sees that A doesn't have the desired key yet, so it creates
- two things:
-
- (a) An uninstantiated key U of requested type and description.
-
- (b) An authorisation key V that refers to key U and notes that process A
- is the context in which key U should be instantiated and secured, and
- from which associated key requests may be satisfied.
-
- (4) request_key() then forks and executes /sbin/request-key with a new session
- keyring that contains a link to auth key V.
-
- (5) /sbin/request-key assumes the authority associated with key U.
-
- (6) /sbin/request-key execs an appropriate program to perform the actual
- instantiation.
-
- (7) The program may want to access another key from A's context (say a
- Kerberos TGT key). It just requests the appropriate key, and the keyring
- search notes that the session keyring has auth key V in its bottom level.
-
- This will permit it to then search the keyrings of process A with the
- UID, GID, groups and security info of process A as if it was process A,
- and come up with key W.
-
- (8) The program then does what it must to get the data with which to
- instantiate key U, using key W as a reference (perhaps it contacts a
- Kerberos server using the TGT) and then instantiates key U.
-
- (9) Upon instantiating key U, auth key V is automatically revoked so that it
- may not be used again.
-
-(10) The program then exits 0 and request_key() deletes key V and returns key
- U to the caller.
-
-This also extends further. If key W (step 7 above) didn't exist, key W would
-be created uninstantiated, another auth key (X) would be created (as per step
-3) and another copy of /sbin/request-key spawned (as per step 4); but the
-context specified by auth key X will still be process A, as it was in auth key
-V.
-
-This is because process A's keyrings can't simply be attached to
-/sbin/request-key at the appropriate places because (a) execve will discard two
-of them, and (b) it requires the same UID/GID/Groups all the way through.
-
-
-====================================
-NEGATIVE INSTANTIATION AND REJECTION
-====================================
-
-Rather than instantiating a key, it is possible for the possessor of an
-authorisation key to negatively instantiate a key that's under construction.
-This is a short duration placeholder that causes any attempt at re-requesting
-the key whilst it exists to fail with error ENOKEY if negated or the specified
-error if rejected.
-
-This is provided to prevent excessive repeated spawning of /sbin/request-key
-processes for a key that will never be obtainable.
-
-Should the /sbin/request-key process exit anything other than 0 or die on a
-signal, the key under construction will be automatically negatively
-instantiated for a short amount of time.
-
-
-====================
-THE SEARCH ALGORITHM
-====================
-
-A search of any particular keyring proceeds in the following fashion:
-
- (1) When the key management code searches for a key (keyring_search_aux) it
- firstly calls key_permission(SEARCH) on the keyring it's starting with,
- if this denies permission, it doesn't search further.
-
- (2) It considers all the non-keyring keys within that keyring and, if any key
- matches the criteria specified, calls key_permission(SEARCH) on it to see
- if the key is allowed to be found. If it is, that key is returned; if
- not, the search continues, and the error code is retained if of higher
- priority than the one currently set.
-
- (3) It then considers all the keyring-type keys in the keyring it's currently
- searching. It calls key_permission(SEARCH) on each keyring, and if this
- grants permission, it recurses, executing steps (2) and (3) on that
- keyring.
-
-The process stops immediately a valid key is found with permission granted to
-use it. Any error from a previous match attempt is discarded and the key is
-returned.
-
-When search_process_keyrings() is invoked, it performs the following searches
-until one succeeds:
-
- (1) If extant, the process's thread keyring is searched.
-
- (2) If extant, the process's process keyring is searched.
-
- (3) The process's session keyring is searched.
-
- (4) If the process has assumed the authority associated with a request_key()
- authorisation key then:
-
- (a) If extant, the calling process's thread keyring is searched.
-
- (b) If extant, the calling process's process keyring is searched.
-
- (c) The calling process's session keyring is searched.
-
-The moment one succeeds, all pending errors are discarded and the found key is
-returned.
-
-Only if all these fail does the whole thing fail with the highest priority
-error. Note that several errors may have come from LSM.
-
-The error priority is:
-
- EKEYREVOKED > EKEYEXPIRED > ENOKEY
-
-EACCES/EPERM are only returned on a direct search of a specific keyring where
-the basal keyring does not grant Search permission.
diff --git a/Documentation/security/keys-trusted-encrypted.txt b/Documentation/security/keys-trusted-encrypted.txt
deleted file mode 100644
index e105ae97a4f..00000000000
--- a/Documentation/security/keys-trusted-encrypted.txt
+++ /dev/null
@@ -1,160 +0,0 @@
- 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,
-and in both cases all keys are created in the kernel, and user space sees,
-stores, and loads only encrypted blobs. Trusted Keys require the availability
-of a Trusted Platform Module (TPM) chip for greater security, while Encrypted
-Keys can be used on any system. All user level blobs, are displayed and loaded
-in hex ascii for convenience, and are integrity verified.
-
-Trusted Keys use a TPM both to generate and to seal the keys. Keys are sealed
-under a 2048 bit RSA key in the TPM, and optionally sealed to specified PCR
-(integrity measurement) values, and only unsealed by the TPM, if PCRs and blob
-integrity verifications match. A loaded Trusted Key can be updated with new
-(future) PCR values, so keys are easily migrated to new pcr values, such as
-when the kernel and initramfs are updated. The same key can have many saved
-blobs under different PCR values, so multiple boots are easily supported.
-
-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:
- keyctl add trusted name "new keylen [options]" ring
- keyctl add trusted name "load hex_blob [pcrlock=pcrnum]" ring
- keyctl update key "update [options]"
- keyctl print keyid
-
- options:
- keyhandle= ascii hex value of sealing key default 0x40000000 (SRK)
- keyauth= ascii hex auth for sealing key default 0x00...i
- (40 ascii zeros)
- blobauth= ascii hex auth for sealed data default 0x00...
- (40 ascii zeros)
- blobauth= ascii hex auth for sealed data default 0x00...
- (40 ascii zeros)
- pcrinfo= ascii hex of PCR_INFO or PCR_INFO_LONG (no default)
- pcrlock= pcr number to be extended to "lock" blob
- migratable= 0|1 indicating permission to reseal to new PCR values,
- default 1 (resealing allowed)
-
-"keyctl print" returns an ascii hex copy of the sealed key, which is in standard
-TPM_STORED_DATA format. The key length for new keys are always in bytes.
-Trusted Keys can be 32 - 128 bytes (256 - 1024 bits), the upper limit is to fit
-within the 2048 bit SRK (RSA) keylength, with all necessary structure/padding.
-
-Encrypted keys do not depend on a TPM, and are faster, as they use AES for
-encryption/decryption. New keys are created from kernel generated random
-numbers, and are encrypted/decrypted using a specified 'master' key. The
-'master' key can either be a trusted-key or user-key type. The main
-disadvantage of encrypted keys is that if they are not rooted in a trusted key,
-they are only as secure as the user key encrypting them. The master user key
-should therefore be loaded in as secure a way as possible, preferably early in
-boot.
-
-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:
- 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'
-
-
-Examples of trusted and encrypted key usage:
-
-Create and save a trusted key named "kmk" of length 32 bytes:
-
- $ keyctl add trusted kmk "new 32" @u
- 440502848
-
- $ keyctl show
- Session Keyring
- -3 --alswrv 500 500 keyring: _ses
- 97833714 --alswrv 500 -1 \_ keyring: _uid.500
- 440502848 --alswrv 500 500 \_ trusted: kmk
-
- $ keyctl print 440502848
- 0101000000000000000001005d01b7e3f4a6be5709930f3b70a743cbb42e0cc95e18e915
- 3f60da455bbf1144ad12e4f92b452f966929f6105fd29ca28e4d4d5a031d068478bacb0b
- 27351119f822911b0a11ba3d3498ba6a32e50dac7f32894dd890eb9ad578e4e292c83722
- a52e56a097e6a68b3f56f7a52ece0cdccba1eb62cad7d817f6dc58898b3ac15f36026fec
- d568bd4a706cb60bb37be6d8f1240661199d640b66fb0fe3b079f97f450b9ef9c22c6d5d
- dd379f0facd1cd020281dfa3c70ba21a3fa6fc2471dc6d13ecf8298b946f65345faa5ef0
- f1f8fff03ad0acb083725535636addb08d73dedb9832da198081e5deae84bfaf0409c22b
- e4a8aea2b607ec96931e6f4d4fe563ba
-
- $ keyctl pipe 440502848 > kmk.blob
-
-Load a trusted key from the saved blob:
-
- $ keyctl add trusted kmk "load `cat kmk.blob`" @u
- 268728824
-
- $ keyctl print 268728824
- 0101000000000000000001005d01b7e3f4a6be5709930f3b70a743cbb42e0cc95e18e915
- 3f60da455bbf1144ad12e4f92b452f966929f6105fd29ca28e4d4d5a031d068478bacb0b
- 27351119f822911b0a11ba3d3498ba6a32e50dac7f32894dd890eb9ad578e4e292c83722
- a52e56a097e6a68b3f56f7a52ece0cdccba1eb62cad7d817f6dc58898b3ac15f36026fec
- d568bd4a706cb60bb37be6d8f1240661199d640b66fb0fe3b079f97f450b9ef9c22c6d5d
- dd379f0facd1cd020281dfa3c70ba21a3fa6fc2471dc6d13ecf8298b946f65345faa5ef0
- f1f8fff03ad0acb083725535636addb08d73dedb9832da198081e5deae84bfaf0409c22b
- e4a8aea2b607ec96931e6f4d4fe563ba
-
-Reseal a trusted key under new pcr values:
-
- $ keyctl update 268728824 "update pcrinfo=`cat pcr.blob`"
- $ keyctl print 268728824
- 010100000000002c0002800093c35a09b70fff26e7a98ae786c641e678ec6ffb6b46d805
- 77c8a6377aed9d3219c6dfec4b23ffe3000001005d37d472ac8a44023fbb3d18583a4f73
- d3a076c0858f6f1dcaa39ea0f119911ff03f5406df4f7f27f41da8d7194f45c9f4e00f2e
- df449f266253aa3f52e55c53de147773e00f0f9aca86c64d94c95382265968c354c5eab4
- 9638c5ae99c89de1e0997242edfb0b501744e11ff9762dfd951cffd93227cc513384e7e6
- e782c29435c7ec2edafaa2f4c1fe6e7a781b59549ff5296371b42133777dcc5b8b971610
- 94bc67ede19e43ddb9dc2baacad374a36feaf0314d700af0a65c164b7082401740e489c9
- 7ef6a24defe4846104209bf0c3eced7fa1a672ed5b125fc9d8cd88b476a658a4434644ef
- df8ae9a178e9f83ba9f08d10fa47e4226b98b0702f06b3b8
-
-The initial consumer of trusted keys is EVM, which at boot time needs a high
-quality symmetric key for HMAC protection of file metadata. The use of a
-trusted key provides strong guarantees that the EVM key has not been
-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'
- $ keyctl add encrypted evm "new trusted:kmk 32" @u
- 159771175
-
-option 2: explicitly defining 'format' as 'default'
- $ keyctl add encrypted evm "new default trusted:kmk 32" @u
- 159771175
-
- $ keyctl print 159771175
- default trusted:kmk 32 2375725ad57798846a9bbd240de8906f006e66c03af53b1b3
- 82dbbc55be2a44616e4959430436dc4f2a7a9659aa60bb4652aeb2120f149ed197c564e0
- 24717c64 5972dcb82ab2dde83376d82b2e3c09ffc
-
- $ keyctl pipe 159771175 > evm.blob
-
-Load an encrypted key "evm" from saved blob:
-
- $ keyctl add encrypted evm "load `cat evm.blob`" @u
- 831684262
-
- $ keyctl print 831684262
- default trusted:kmk 32 2375725ad57798846a9bbd240de8906f006e66c03af53b1b3
- 82dbbc55be2a44616e4959430436dc4f2a7a9659aa60bb4652aeb2120f149ed197c564e0
- 24717c64 5972dcb82ab2dde83376d82b2e3c09ffc
-
-Other uses for trusted and encrypted keys, such as for disk and file encryption
-are anticipated. In particular the new format 'ecryptfs' has been defined in
-in order to use encrypted keys to mount an eCryptfs filesystem. More details
-about the usage can be found in the file
-'Documentation/security/keys-ecryptfs.txt'.
diff --git a/Documentation/security/keys.txt b/Documentation/security/keys.txt
deleted file mode 100644
index aa0dbd74b71..00000000000
--- a/Documentation/security/keys.txt
+++ /dev/null
@@ -1,1323 +0,0 @@
- ============================
- 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
-filesystems and other kernel services.
-
-Keyrings are permitted; these are a special type of key that can hold links to
-other keys. Processes each have three standard keyring subscriptions that a
-kernel service can search for relevant keys.
-
-The key service can be configured on by enabling:
-
- "Security options"/"Enable access key retention support" (CONFIG_KEYS)
-
-This document has the following sections:
-
- - Key overview
- - Key service overview
- - Key access permissions
- - SELinux support
- - New procfs files
- - Userspace system call interface
- - Kernel services
- - Notes on accessing payload contents
- - Defining a key type
- - Request-key callback service
- - Garbage collection
-
-
-============
-KEY OVERVIEW
-============
-
-In this context, keys represent units of cryptographic data, authentication
-tokens, keyrings, etc.. These are represented in the kernel by struct key.
-
-Each key has a number of attributes:
-
- - A serial number.
- - A type.
- - A description (for matching a key in a search).
- - Access control information.
- - An expiry time.
- - A payload.
- - State.
-
-
- (*) 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
- 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.
-
- Key types are represented in the kernel by struct key_type. This defines a
- number of operations that can be performed on a key of that type.
-
- 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
- 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
- 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
- instantiation function. Keys can also be immortal.
-
- (*) Each key can have a payload. This is a quantity of data that represent the
- actual "key". In the case of a keyring, this is a list of keys to which
- the keyring links; in the case of a user-defined key, it's an arbitrary
- blob of data.
-
- Having a payload is not required; and the payload can, in fact, just be a
- value stored in the struct key itself.
-
- When a key is instantiated, the key type's instantiation function is
- called with a blob of data, and that then creates the key's payload in
- some way.
-
- Similarly, when userspace wants to read back the contents of the key, if
- permitted, another key type operation will be called to convert the key's
- attached payload back into a blob of data.
-
- (*) Each key can be in one of a number of basic states:
-
- (*) Uninstantiated. The key exists, but does not have any data attached.
- Keys being requested from userspace will be in this state.
-
- (*) Instantiated. This is the normal state. The key is fully formed, and
- has data attached.
-
- (*) Negative. This is a relatively short-lived state. The key acts as a
- note saying that a previous call out to userspace failed, and acts as
- a throttle on key lookups. A negative key can be updated to a normal
- state.
-
- (*) Expired. Keys can have lifetimes set. If their lifetime is exceeded,
- they traverse to this state. An expired key can be updated back to a
- normal state.
-
- (*) Revoked. A key is put in this state by userspace action. It can't be
- found or operated upon (apart from by unlinking it).
-
- (*) Dead. The key's type was unregistered, and so the key is now useless.
-
-Keys in the last three states are subject to garbage collection. See the
-section on "Garbage collection".
-
-
-====================
-KEY SERVICE OVERVIEW
-====================
-
-The key service provides a number of features besides keys:
-
- (*) The key service defines three special key types:
-
- (+) "keyring"
-
- Keyrings are special keys that contain a list of other keys. Keyring
- lists can be modified using various system calls. Keyrings should not
- be given a payload when created.
-
- (+) "user"
-
- A key of this type has a description and a payload that are arbitrary
- blobs of data. These can be created, updated and read by userspace,
- and aren't intended for use by kernel services.
-
- (+) "logon"
-
- Like a "user" key, a "logon" key has a payload that is an arbitrary
- blob of data. It is intended as a place to store secrets which are
- accessible to the kernel but not to userspace programs.
-
- The description can be arbitrary, but must be prefixed with a non-zero
- length string that describes the key "subclass". The subclass is
- separated from the rest of the description by a ':'. "logon" keys can
- be created and updated from userspace, but the payload is only
- readable from kernel space.
-
- (*) Each process subscribes to three keyrings: a thread-specific keyring, a
- process-specific keyring, and a session-specific keyring.
-
- The thread-specific keyring is discarded from the child when any sort of
- clone, fork, vfork or execve occurs. A new keyring is created only when
- required.
-
- The process-specific keyring is replaced with an empty one in the child on
- clone, fork, vfork unless CLONE_THREAD is supplied, in which case it is
- shared. execve also discards the process's process keyring and creates a
- new one.
-
- The session-specific keyring is persistent across clone, fork, vfork and
- execve, even when the latter executes a set-UID or set-GID binary. A
- process can, however, replace its current session keyring with a new one
- by using PR_JOIN_SESSION_KEYRING. It is permitted to request an anonymous
- new one, or to attempt to create or join one of a specific name.
-
- The ownership of the thread keyring changes when the real UID and GID of
- the thread changes.
-
- (*) Each user ID resident in the system holds two special keyrings: a user
- specific keyring and a default user session keyring. The default session
- keyring is initialised with a link to the user-specific keyring.
-
- When a process changes its real UID, if it used to have no session key, it
- will be subscribed to the default session key for the new UID.
-
- If a process attempts to access its session key when it doesn't have one,
- it will be subscribed to the default for its current UID.
-
- (*) Each user has two quotas against which the keys they own are tracked. One
- limits the total number of keys and keyrings, the other limits the total
- amount of description and payload space that can be consumed.
-
- The user can view information on this and other statistics through procfs
- files. The root user may also alter the quota limits through sysctl files
- (see the section "New procfs files").
-
- Process-specific and thread-specific keyrings are not counted towards a
- user's quota.
-
- If a system call that modifies a key or keyring in some way would put the
- user over quota, the operation is refused and error EDQUOT is returned.
-
- (*) There's a system call interface by which userspace programs can create and
- manipulate keys and keyrings.
-
- (*) There's a kernel interface by which services can register types and search
- for keys.
-
- (*) There's a way for the a search done from the kernel to call back to
- userspace to request a key that can't be found in a process's keyrings.
-
- (*) An optional filesystem is available through which the key database can be
- viewed and manipulated.
-
-
-======================
-KEY ACCESS PERMISSIONS
-======================
-
-Keys have an owner user ID, a group access ID, and a permissions mask. The mask
-has up to eight bits each for possessor, user, group and other access. Only
-six of each set of eight bits are defined. These permissions granted are:
-
- (*) View
-
- This permits a key or keyring's attributes to be viewed - including key
- type and description.
-
- (*) Read
-
- This permits a key's payload to be viewed or a keyring's list of linked
- keys.
-
- (*) Write
-
- This permits a key's payload to be instantiated or updated, or it allows a
- link to be added to or removed from a keyring.
-
- (*) Search
-
- This permits keyrings to be searched and keys to be found. Searches can
- only recurse into nested keyrings that have search permission set.
-
- (*) Link
-
- This permits a key or keyring to be linked to. To create a link from a
- keyring to a key, a process must have Write permission on the keyring and
- Link permission on the key.
-
- (*) Set Attribute
-
- This permits a key's UID, GID and permissions mask to be changed.
-
-For changing the ownership, group ID or permissions mask, being the owner of
-the key or having the sysadmin capability is sufficient.
-
-
-===============
-SELINUX SUPPORT
-===============
-
-The security class "key" has been added to SELinux so that mandatory access
-controls can be applied to keys created within various contexts. This support
-is preliminary, and is likely to change quite significantly in the near future.
-Currently, all of the basic permissions explained above are provided in SELinux
-as well; SELinux is simply invoked after all basic permission checks have been
-performed.
-
-The value of the file /proc/self/attr/keycreate influences the labeling of
-newly-created keys. If the contents of that file correspond to an SELinux
-security context, then the key will be assigned that context. Otherwise, the
-key will be assigned the current context of the task that invoked the key
-creation request. Tasks must be granted explicit permission to assign a
-particular context to newly-created keys, using the "create" permission in the
-key security class.
-
-The default keyrings associated with users will be labeled with the default
-context of the user if and only if the login programs have been instrumented to
-properly initialize keycreate during the login process. Otherwise, they will
-be labeled with the context of the login program itself.
-
-Note, however, that the default keyrings associated with the root user are
-labeled with the default kernel context, since they are created early in the
-boot process, before root has a chance to log in.
-
-The keyrings associated with new threads are each labeled with the context of
-their associated thread, and both session and process keyrings are handled
-similarly.
-
-
-================
-NEW PROCFS FILES
-================
-
-Two files have been added to procfs by which an administrator can find out
-about the status of the key service:
-
- (*) /proc/keys
-
- This lists the keys that are currently viewable by the task reading the
- file, giving information about their type, description and permissions.
- It is not possible to view the payload of the key this way, though some
- information about it may be given.
-
- The only keys included in the list are those that grant View permission to
- the reading process whether or not it possesses them. Note that LSM
- security checks are still performed, and may further filter out keys that
- the current process is not authorised to view.
-
- The contents of the file look like this:
-
- SERIAL FLAGS USAGE EXPY PERM UID GID TYPE DESCRIPTION: SUMMARY
- 00000001 I----- 39 perm 1f3f0000 0 0 keyring _uid_ses.0: 1/4
- 00000002 I----- 2 perm 1f3f0000 0 0 keyring _uid.0: empty
- 00000007 I----- 1 perm 1f3f0000 0 0 keyring _pid.1: empty
- 0000018d I----- 1 perm 1f3f0000 0 0 keyring _pid.412: empty
- 000004d2 I--Q-- 1 perm 1f3f0000 32 -1 keyring _uid.32: 1/4
- 000004d3 I--Q-- 3 perm 1f3f0000 32 -1 keyring _uid_ses.32: empty
- 00000892 I--QU- 1 perm 1f000000 0 0 user metal:copper: 0
- 00000893 I--Q-N 1 35s 1f3f0000 0 0 user metal:silver: 0
- 00000894 I--Q-- 1 10h 003f0000 0 0 user metal:gold: 0
-
- The flags are:
-
- I Instantiated
- R Revoked
- D Dead
- Q Contributes to user's quota
- U Under construction by callback to userspace
- N Negative key
-
- This file must be enabled at kernel configuration time as it allows anyone
- to list the keys database.
-
- (*) /proc/key-users
-
- This file lists the tracking data for each user that has at least one key
- on the system. Such data includes quota information and statistics:
-
- [root@andromeda root]# cat /proc/key-users
- 0: 46 45/45 1/100 13/10000
- 29: 2 2/2 2/100 40/10000
- 32: 2 2/2 2/100 40/10000
- 38: 2 2/2 2/100 40/10000
-
- The format of each line is
- <UID>: User ID to which this applies
- <usage> Structure refcount
- <inst>/<keys> Total number of keys and number instantiated
- <keys>/<max> Key count quota
- <bytes>/<max> Key size quota
-
-
-Four new sysctl files have been added also for the purpose of controlling the
-quota limits on keys:
-
- (*) /proc/sys/kernel/keys/root_maxkeys
- /proc/sys/kernel/keys/root_maxbytes
-
- These files hold the maximum number of keys that root may have and the
- maximum total number of bytes of data that root may have stored in those
- keys.
-
- (*) /proc/sys/kernel/keys/maxkeys
- /proc/sys/kernel/keys/maxbytes
-
- These files hold the maximum number of keys that each non-root user may
- have and the maximum total number of bytes of data that each of those
- users may have stored in their keys.
-
-Root may alter these by writing each new limit as a decimal number string to
-the appropriate file.
-
-
-===============================
-USERSPACE SYSTEM CALL INTERFACE
-===============================
-
-Userspace can manipulate keys directly through three new syscalls: add_key,
-request_key and keyctl. The latter provides a number of functions for
-manipulating keys.
-
-When referring to a key directly, userspace programs should use the key's
-serial number (a positive 32-bit integer). However, there are some special
-values available for referring to special keys and keyrings that relate to the
-process making the call:
-
- CONSTANT VALUE KEY REFERENCED
- ============================== ====== ===========================
- KEY_SPEC_THREAD_KEYRING -1 thread-specific keyring
- KEY_SPEC_PROCESS_KEYRING -2 process-specific keyring
- KEY_SPEC_SESSION_KEYRING -3 session-specific keyring
- KEY_SPEC_USER_KEYRING -4 UID-specific keyring
- KEY_SPEC_USER_SESSION_KEYRING -5 UID-session keyring
- KEY_SPEC_GROUP_KEYRING -6 GID-specific keyring
- KEY_SPEC_REQKEY_AUTH_KEY -7 assumed request_key()
- authorisation key
-
-
-The main syscalls are:
-
- (*) Create a new key of given type, description and payload and add it to the
- nominated keyring:
-
- key_serial_t add_key(const char *type, const char *desc,
- const void *payload, size_t plen,
- key_serial_t keyring);
-
- If a key of the same type and description as that proposed already exists
- in the keyring, this will try to update it with the given payload, or it
- will return error EEXIST if that function is not supported by the key
- type. The process must also have permission to write to the key to be able
- to update it. The new key will have all user permissions granted and no
- group or third party permissions.
-
- Otherwise, this will attempt to create a new key of the specified type and
- description, and to instantiate it with the supplied payload and attach it
- to the keyring. In this case, an error will be generated if the process
- does not have permission to write to the keyring.
-
- The payload is optional, and the pointer can be NULL if not required by
- the type. The payload is plen in size, and plen can be zero for an empty
- payload.
-
- A new keyring can be generated by setting type "keyring", the keyring name
- as the description (or NULL) and setting the payload to NULL.
-
- User defined keys can be created by specifying type "user". It is
- recommended that a user defined key's description by prefixed with a type
- ID and a colon, such as "krb5tgt:" for a Kerberos 5 ticket granting
- ticket.
-
- Any other type must have been registered with the kernel in advance by a
- kernel service such as a filesystem.
-
- The ID of the new or updated key is returned if successful.
-
-
- (*) Search the process's keyrings for a key, potentially calling out to
- userspace to create it.
-
- key_serial_t request_key(const char *type, const char *description,
- const char *callout_info,
- key_serial_t dest_keyring);
-
- This function searches all the process's keyrings in the order thread,
- process, session for a matching key. This works very much like
- KEYCTL_SEARCH, including the optional attachment of the discovered key to
- a keyring.
-
- If a key cannot be found, and if callout_info is not NULL, then
- /sbin/request-key will be invoked in an attempt to obtain a key. The
- callout_info string will be passed as an argument to the program.
-
- See also Documentation/security/keys-request-key.txt.
-
-
-The keyctl syscall functions are:
-
- (*) Map a special key ID to a real key ID for this process:
-
- key_serial_t keyctl(KEYCTL_GET_KEYRING_ID, key_serial_t id,
- int create);
-
- The special key specified by "id" is looked up (with the key being created
- if necessary) and the ID of the key or keyring thus found is returned if
- it exists.
-
- If the key does not yet exist, the key will be created if "create" is
- non-zero; and the error ENOKEY will be returned if "create" is zero.
-
-
- (*) Replace the session keyring this process subscribes to with a new one:
-
- key_serial_t keyctl(KEYCTL_JOIN_SESSION_KEYRING, const char *name);
-
- If name is NULL, an anonymous keyring is created attached to the process
- as its session keyring, displacing the old session keyring.
-
- If name is not NULL, if a keyring of that name exists, the process
- attempts to attach it as the session keyring, returning an error if that
- is not permitted; otherwise a new keyring of that name is created and
- attached as the session keyring.
-
- To attach to a named keyring, the keyring must have search permission for
- the process's ownership.
-
- The ID of the new session keyring is returned if successful.
-
-
- (*) Update the specified key:
-
- long keyctl(KEYCTL_UPDATE, key_serial_t key, const void *payload,
- size_t plen);
-
- This will try to update the specified key with the given payload, or it
- will return error EOPNOTSUPP if that function is not supported by the key
- type. The process must also have permission to write to the key to be able
- to update it.
-
- The payload is of length plen, and may be absent or empty as for
- add_key().
-
-
- (*) Revoke a key:
-
- long keyctl(KEYCTL_REVOKE, key_serial_t key);
-
- This makes a key unavailable for further operations. Further attempts to
- use the key will be met with error EKEYREVOKED, and the key will no longer
- be findable.
-
-
- (*) Change the ownership of a key:
-
- long keyctl(KEYCTL_CHOWN, key_serial_t key, uid_t uid, gid_t gid);
-
- This function permits a key's owner and group ID to be changed. Either one
- of uid or gid can be set to -1 to suppress that change.
-
- Only the superuser can change a key's owner to something other than the
- key's current owner. Similarly, only the superuser can change a key's
- group ID to something other than the calling process's group ID or one of
- its group list members.
-
-
- (*) Change the permissions mask on a key:
-
- long keyctl(KEYCTL_SETPERM, key_serial_t key, key_perm_t perm);
-
- This function permits the owner of a key or the superuser to change the
- permissions mask on a key.
-
- Only bits the available bits are permitted; if any other bits are set,
- error EINVAL will be returned.
-
-
- (*) Describe a key:
-
- long keyctl(KEYCTL_DESCRIBE, key_serial_t key, char *buffer,
- size_t buflen);
-
- This function returns a summary of the key's attributes (but not its
- payload data) as a string in the buffer provided.
-
- Unless there's an error, it always returns the amount of data it could
- produce, even if that's too big for the buffer, but it won't copy more
- than requested to userspace. If the buffer pointer is NULL then no copy
- will take place.
-
- A process must have view permission on the key for this function to be
- successful.
-
- If successful, a string is placed in the buffer in the following format:
-
- <type>;<uid>;<gid>;<perm>;<description>
-
- Where type and description are strings, uid and gid are decimal, and perm
- is hexadecimal. A NUL character is included at the end of the string if
- the buffer is sufficiently big.
-
- This can be parsed with
-
- sscanf(buffer, "%[^;];%d;%d;%o;%s", type, &uid, &gid, &mode, desc);
-
-
- (*) Clear out a keyring:
-
- long keyctl(KEYCTL_CLEAR, key_serial_t keyring);
-
- This function clears the list of keys attached to a keyring. The calling
- process must have write permission on the keyring, and it must be a
- keyring (or else error ENOTDIR will result).
-
- This function can also be used to clear special kernel keyrings if they
- are appropriately marked if the user has CAP_SYS_ADMIN capability. The
- DNS resolver cache keyring is an example of this.
-
-
- (*) Link a key into a keyring:
-
- long keyctl(KEYCTL_LINK, key_serial_t keyring, key_serial_t key);
-
- This function creates a link from the keyring to the key. The process must
- have write permission on the keyring and must have link permission on the
- key.
-
- Should the keyring not be a keyring, error ENOTDIR will result; and if the
- keyring is full, error ENFILE will result.
-
- The link procedure checks the nesting of the keyrings, returning ELOOP if
- it appears too deep or EDEADLK if the link would introduce a cycle.
-
- Any links within the keyring to keys that match the new key in terms of
- type and description will be discarded from the keyring as the new one is
- added.
-
-
- (*) Unlink a key or keyring from another keyring:
-
- long keyctl(KEYCTL_UNLINK, key_serial_t keyring, key_serial_t key);
-
- This function looks through the keyring for the first link to the
- specified key, and removes it if found. Subsequent links to that key are
- ignored. The process must have write permission on the keyring.
-
- If the keyring is not a keyring, error ENOTDIR will result; and if the key
- is not present, error ENOENT will be the result.
-
-
- (*) Search a keyring tree for a key:
-
- key_serial_t keyctl(KEYCTL_SEARCH, key_serial_t keyring,
- const char *type, const char *description,
- key_serial_t dest_keyring);
-
- This searches the keyring tree headed by the specified keyring until a key
- is found that matches the type and description criteria. Each keyring is
- checked for keys before recursion into its children occurs.
-
- The process must have search permission on the top level keyring, or else
- error EACCES will result. Only keyrings that the process has search
- permission on will be recursed into, and only keys and keyrings for which
- a process has search permission can be matched. If the specified keyring
- is not a keyring, ENOTDIR will result.
-
- If the search succeeds, the function will attempt to link the found key
- into the destination keyring if one is supplied (non-zero ID). All the
- constraints applicable to KEYCTL_LINK apply in this case too.
-
- Error ENOKEY, EKEYREVOKED or EKEYEXPIRED will be returned if the search
- fails. On success, the resulting key ID will be returned.
-
-
- (*) Read the payload data from a key:
-
- long keyctl(KEYCTL_READ, key_serial_t keyring, char *buffer,
- size_t buflen);
-
- This function attempts to read the payload data from the specified key
- into the buffer. The process must have read permission on the key to
- succeed.
-
- The returned data will be processed for presentation by the key type. For
- instance, a keyring will return an array of key_serial_t entries
- representing the IDs of all the keys to which it is subscribed. The user
- defined key type will return its data as is. If a key type does not
- implement this function, error EOPNOTSUPP will result.
-
- As much of the data as can be fitted into the buffer will be copied to
- userspace if the buffer pointer is not NULL.
-
- On a successful return, the function will always return the amount of data
- available rather than the amount copied.
-
-
- (*) Instantiate a partially constructed key.
-
- long keyctl(KEYCTL_INSTANTIATE, key_serial_t key,
- const void *payload, size_t plen,
- key_serial_t keyring);
- long keyctl(KEYCTL_INSTANTIATE_IOV, key_serial_t key,
- const struct iovec *payload_iov, unsigned ioc,
- key_serial_t keyring);
-
- If the kernel calls back to userspace to complete the instantiation of a
- key, userspace should use this call to supply data for the key before the
- invoked process returns, or else the key will be marked negative
- automatically.
-
- The process must have write access on the key to be able to instantiate
- it, and the key must be uninstantiated.
-
- If a keyring is specified (non-zero), the key will also be linked into
- that keyring, however all the constraints applying in KEYCTL_LINK apply in
- this case too.
-
- The payload and plen arguments describe the payload data as for add_key().
-
- The payload_iov and ioc arguments describe the payload data in an iovec
- array instead of a single buffer.
-
-
- (*) Negatively instantiate a partially constructed key.
-
- long keyctl(KEYCTL_NEGATE, key_serial_t key,
- unsigned timeout, key_serial_t keyring);
- long keyctl(KEYCTL_REJECT, key_serial_t key,
- unsigned timeout, unsigned error, key_serial_t keyring);
-
- If the kernel calls back to userspace to complete the instantiation of a
- key, userspace should use this call mark the key as negative before the
- invoked process returns if it is unable to fulfill the request.
-
- The process must have write access on the key to be able to instantiate
- it, and the key must be uninstantiated.
-
- If a keyring is specified (non-zero), the key will also be linked into
- that keyring, however all the constraints applying in KEYCTL_LINK apply in
- this case too.
-
- If the key is rejected, future searches for it will return the specified
- error code until the rejected key expires. Negating the key is the same
- as rejecting the key with ENOKEY as the error code.
-
-
- (*) Set the default request-key destination keyring.
-
- long keyctl(KEYCTL_SET_REQKEY_KEYRING, int reqkey_defl);
-
- This sets the default keyring to which implicitly requested keys will be
- attached for this thread. reqkey_defl should be one of these constants:
-
- CONSTANT VALUE NEW DEFAULT KEYRING
- ====================================== ====== =======================
- KEY_REQKEY_DEFL_NO_CHANGE -1 No change
- KEY_REQKEY_DEFL_DEFAULT 0 Default[1]
- KEY_REQKEY_DEFL_THREAD_KEYRING 1 Thread keyring
- KEY_REQKEY_DEFL_PROCESS_KEYRING 2 Process keyring
- KEY_REQKEY_DEFL_SESSION_KEYRING 3 Session keyring
- KEY_REQKEY_DEFL_USER_KEYRING 4 User keyring
- KEY_REQKEY_DEFL_USER_SESSION_KEYRING 5 User session keyring
- KEY_REQKEY_DEFL_GROUP_KEYRING 6 Group keyring
-
- The old default will be returned if successful and error EINVAL will be
- returned if reqkey_defl is not one of the above values.
-
- The default keyring can be overridden by the keyring indicated to the
- request_key() system call.
-
- Note that this setting is inherited across fork/exec.
-
- [1] The default is: the thread keyring if there is one, otherwise
- the process keyring if there is one, otherwise the session keyring if
- there is one, otherwise the user default session keyring.
-
-
- (*) Set the timeout on a key.
-
- long keyctl(KEYCTL_SET_TIMEOUT, key_serial_t key, unsigned timeout);
-
- This sets or clears the timeout on a key. The timeout can be 0 to clear
- the timeout or a number of seconds to set the expiry time that far into
- the future.
-
- The process must have attribute modification access on a key to set its
- timeout. Timeouts may not be set with this function on negative, revoked
- or expired keys.
-
-
- (*) Assume the authority granted to instantiate a key
-
- long keyctl(KEYCTL_ASSUME_AUTHORITY, key_serial_t key);
-
- This assumes or divests the authority required to instantiate the
- specified key. Authority can only be assumed if the thread has the
- authorisation key associated with the specified key in its keyrings
- somewhere.
-
- Once authority is assumed, searches for keys will also search the
- requester's keyrings using the requester's security label, UID, GID and
- groups.
-
- If the requested authority is unavailable, error EPERM will be returned,
- likewise if the authority has been revoked because the target key is
- already instantiated.
-
- If the specified key is 0, then any assumed authority will be divested.
-
- The assumed authoritative key is inherited across fork and exec.
-
-
- (*) Get the LSM security context attached to a key.
-
- long keyctl(KEYCTL_GET_SECURITY, key_serial_t key, char *buffer,
- size_t buflen)
-
- This function returns a string that represents the LSM security context
- attached to a key in the buffer provided.
-
- Unless there's an error, it always returns the amount of data it could
- produce, even if that's too big for the buffer, but it won't copy more
- than requested to userspace. If the buffer pointer is NULL then no copy
- will take place.
-
- A NUL character is included at the end of the string if the buffer is
- sufficiently big. This is included in the returned count. If no LSM is
- in force then an empty string will be returned.
-
- A process must have view permission on the key for this function to be
- successful.
-
-
- (*) Install the calling process's session keyring on its parent.
-
- long keyctl(KEYCTL_SESSION_TO_PARENT);
-
- This functions attempts to install the calling process's session keyring
- on to the calling process's parent, replacing the parent's current session
- keyring.
-
- The calling process must have the same ownership as its parent, the
- keyring must have the same ownership as the calling process, the calling
- process must have LINK permission on the keyring and the active LSM module
- mustn't deny permission, otherwise error EPERM will be returned.
-
- Error ENOMEM will be returned if there was insufficient memory to complete
- the operation, otherwise 0 will be returned to indicate success.
-
- The keyring will be replaced next time the parent process leaves the
- kernel and resumes executing userspace.
-
-
- (*) Invalidate a key.
-
- long keyctl(KEYCTL_INVALIDATE, key_serial_t key);
-
- This function marks a key as being invalidated and then wakes up the
- garbage collector. The garbage collector immediately removes invalidated
- keys from all keyrings and deletes the key when its reference count
- reaches zero.
-
- Keys that are marked invalidated become invisible to normal key operations
- immediately, though they are still visible in /proc/keys until deleted
- (they're marked with an 'i' flag).
-
- A process must have search permission on the key for this function to be
- successful.
-
-
-===============
-KERNEL SERVICES
-===============
-
-The kernel services for key management are fairly simple to deal with. They can
-be broken down into two areas: keys and key types.
-
-Dealing with keys is fairly straightforward. Firstly, the kernel service
-registers its type, then it searches for a key of that type. It should retain
-the key as long as it has need of it, and then it should release it. For a
-filesystem or device file, a search would probably be performed during the open
-call, and the key released upon close. How to deal with conflicting keys due to
-two different users opening the same file is left to the filesystem author to
-solve.
-
-To access the key manager, the following header must be #included:
-
- <linux/key.h>
-
-Specific key types should have a header file under include/keys/ that should be
-used to access that type. For keys of type "user", for example, that would be:
-
- <keys/user-type.h>
-
-Note that there are two different types of pointers to keys that may be
-encountered:
-
- (*) struct key *
-
- This simply points to the key structure itself. Key structures will be at
- least four-byte aligned.
-
- (*) key_ref_t
-
- This is equivalent to a struct key *, but the least significant bit is set
- if the caller "possesses" the key. By "possession" it is meant that the
- calling processes has a searchable link to the key from one of its
- keyrings. There are three functions for dealing with these:
-
- key_ref_t make_key_ref(const struct key *key,
- unsigned long possession);
-
- struct key *key_ref_to_ptr(const key_ref_t key_ref);
-
- unsigned long is_key_possessed(const key_ref_t key_ref);
-
- The first function constructs a key reference from a key pointer and
- possession information (which must be 0 or 1 and not any other value).
-
- The second function retrieves the key pointer from a reference and the
- third retrieves the possession flag.
-
-When accessing a key's payload contents, certain precautions must be taken to
-prevent access vs modification races. See the section "Notes on accessing
-payload contents" for more information.
-
-(*) To search for a key, call:
-
- struct key *request_key(const struct key_type *type,
- const char *description,
- const char *callout_info);
-
- This is used to request a key or keyring with a description that matches
- the description specified according to the key type's match function. This
- permits approximate matching to occur. If callout_string is not NULL, then
- /sbin/request-key will be invoked in an attempt to obtain the key from
- userspace. In that case, callout_string will be passed as an argument to
- the program.
-
- Should the function fail error ENOKEY, EKEYEXPIRED or EKEYREVOKED will be
- returned.
-
- If successful, the key will have been attached to the default keyring for
- implicitly obtained request-key keys, as set by KEYCTL_SET_REQKEY_KEYRING.
-
- See also Documentation/security/keys-request-key.txt.
-
-
-(*) To search for a key, passing auxiliary data to the upcaller, call:
-
- struct key *request_key_with_auxdata(const struct key_type *type,
- const char *description,
- const void *callout_info,
- size_t callout_len,
- void *aux);
-
- This is identical to request_key(), except that the auxiliary data is
- passed to the key_type->request_key() op if it exists, and the callout_info
- is a blob of length callout_len, if given (the length may be 0).
-
-
-(*) A key can be requested asynchronously by calling one of:
-
- struct key *request_key_async(const struct key_type *type,
- const char *description,
- const void *callout_info,
- size_t callout_len);
-
- or:
-
- struct key *request_key_async_with_auxdata(const struct key_type *type,
- const char *description,
- const char *callout_info,
- size_t callout_len,
- void *aux);
-
- which are asynchronous equivalents of request_key() and
- request_key_with_auxdata() respectively.
-
- These two functions return with the key potentially still under
- construction. To wait for construction completion, the following should be
- called:
-
- int wait_for_key_construction(struct key *key, bool intr);
-
- The function will wait for the key to finish being constructed and then
- invokes key_validate() to return an appropriate value to indicate the state
- of the key (0 indicates the key is usable).
-
- If intr is true, then the wait can be interrupted by a signal, in which
- case error ERESTARTSYS will be returned.
-
-
-(*) When it is no longer required, the key should be released using:
-
- void key_put(struct key *key);
-
- Or:
-
- void key_ref_put(key_ref_t key_ref);
-
- These can be called from interrupt context. If CONFIG_KEYS is not set then
- the argument will not be parsed.
-
-
-(*) Extra references can be made to a key by calling the following function:
-
- struct key *key_get(struct key *key);
-
- These need to be disposed of by calling key_put() when they've been
- finished with. The key pointer passed in will be returned. If the pointer
- is NULL or CONFIG_KEYS is not set then the key will not be dereferenced and
- no increment will take place.
-
-
-(*) A key's serial number can be obtained by calling:
-
- key_serial_t key_serial(struct key *key);
-
- If key is NULL or if CONFIG_KEYS is not set then 0 will be returned (in the
- latter case without parsing the argument).
-
-
-(*) If a keyring was found in the search, this can be further searched by:
-
- key_ref_t keyring_search(key_ref_t keyring_ref,
- const struct key_type *type,
- const char *description)
-
- This searches the keyring tree specified for a matching key. Error ENOKEY
- is returned upon failure (use IS_ERR/PTR_ERR to determine). If successful,
- the returned key will need to be released.
-
- The possession attribute from the keyring reference is used to control
- access through the permissions mask and is propagated to the returned key
- reference pointer if successful.
-
-
-(*) To check the validity of a key, this function can be called:
-
- int validate_key(struct key *key);
-
- This checks that the key in question hasn't expired or and hasn't been
- revoked. Should the key be invalid, error EKEYEXPIRED or EKEYREVOKED will
- be returned. If the key is NULL or if CONFIG_KEYS is not set then 0 will be
- returned (in the latter case without parsing the argument).
-
-
-(*) To register a key type, the following function should be called:
-
- int register_key_type(struct key_type *type);
-
- This will return error EEXIST if a type of the same name is already
- present.
-
-
-(*) To unregister a key type, call:
-
- void unregister_key_type(struct key_type *type);
-
-
-Under some circumstances, it may be desirable to deal with a bundle of keys.
-The facility provides access to the keyring type for managing such a bundle:
-
- struct key_type key_type_keyring;
-
-This can be used with a function such as request_key() to find a specific
-keyring in a process's keyrings. A keyring thus found can then be searched
-with keyring_search(). Note that it is not possible to use request_key() to
-search a specific keyring, so using keyrings in this way is of limited utility.
-
-
-===================================
-NOTES ON ACCESSING PAYLOAD CONTENTS
-===================================
-
-The simplest payload is just a number in key->payload.value. In this case,
-there's no need to indulge in RCU or locking when accessing the payload.
-
-More complex payload contents must be allocated and a pointer to them set in
-key->payload.data. One of the following ways must be selected to access the
-data:
-
- (1) Unmodifiable key type.
-
- If the key type does not have a modify method, then the key's payload can
- be accessed without any form of locking, provided that it's known to be
- instantiated (uninstantiated keys cannot be "found").
-
- (2) The key's semaphore.
-
- The semaphore could be used to govern access to the payload and to control
- the payload pointer. It must be write-locked for modifications and would
- have to be read-locked for general access. The disadvantage of doing this
- is that the accessor may be required to sleep.
-
- (3) RCU.
-
- RCU must be used when the semaphore isn't already held; if the semaphore
- is held then the contents can't change under you unexpectedly as the
- semaphore must still be used to serialise modifications to the key. The
- key management code takes care of this for the key type.
-
- However, this means using:
-
- rcu_read_lock() ... rcu_dereference() ... rcu_read_unlock()
-
- to read the pointer, and:
-
- rcu_dereference() ... rcu_assign_pointer() ... call_rcu()
-
- to set the pointer and dispose of the old contents after a grace period.
- Note that only the key type should ever modify a key's payload.
-
- Furthermore, an RCU controlled payload must hold a struct rcu_head for the
- use of call_rcu() and, if the payload is of variable size, the length of
- the payload. key->datalen cannot be relied upon to be consistent with the
- payload just dereferenced if the key's semaphore is not held.
-
-
-===================
-DEFINING A KEY TYPE
-===================
-
-A kernel service may want to define its own key type. For instance, an AFS
-filesystem might want to define a Kerberos 5 ticket key type. To do this, it
-author fills in a key_type struct and registers it with the system.
-
-Source files that implement key types should include the following header file:
-
- <linux/key-type.h>
-
-The structure has a number of fields, some of which are mandatory:
-
- (*) const char *name
-
- The name of the key type. This is used to translate a key type name
- supplied by userspace into a pointer to the structure.
-
-
- (*) size_t def_datalen
-
- This is optional - it supplies the default payload data length as
- contributed to the quota. If the key type's payload is always or almost
- always the same size, then this is a more efficient way to do things.
-
- The data length (and quota) on a particular key can always be changed
- during instantiation or update by calling:
-
- int key_payload_reserve(struct key *key, size_t datalen);
-
- With the revised data length. Error EDQUOT will be returned if this is not
- viable.
-
-
- (*) int (*vet_description)(const char *description);
-
- This optional method is called to vet a key description. If the key type
- doesn't approve of the key description, it may return an error, otherwise
- it should return 0.
-
-
- (*) int (*instantiate)(struct key *key, const void *data, size_t datalen);
-
- This method is called to attach a payload to a key during construction.
- The payload attached need not bear any relation to the data passed to this
- function.
-
- If the amount of data attached to the key differs from the size in
- keytype->def_datalen, then key_payload_reserve() should be called.
-
- This method does not have to lock the key in order to attach a payload.
- The fact that KEY_FLAG_INSTANTIATED is not set in key->flags prevents
- anything else from gaining access to the key.
-
- It is safe to sleep in this method.
-
-
- (*) int (*update)(struct key *key, const void *data, size_t datalen);
-
- If this type of key can be updated, then this method should be provided.
- It is called to update a key's payload from the blob of data provided.
-
- key_payload_reserve() should be called if the data length might change
- before any changes are actually made. Note that if this succeeds, the type
- is committed to changing the key because it's already been altered, so all
- memory allocation must be done first.
-
- The key will have its semaphore write-locked before this method is called,
- but this only deters other writers; any changes to the key's payload must
- be made under RCU conditions, and call_rcu() must be used to dispose of
- the old payload.
-
- key_payload_reserve() should be called before the changes are made, but
- after all allocations and other potentially failing function calls are
- made.
-
- It is safe to sleep in this method.
-
-
- (*) int (*match)(const struct key *key, const void *desc);
-
- This method is called to match a key against a description. It should
- return non-zero if the two match, zero if they don't.
-
- This method should not need to lock the key in any way. The type and
- description can be considered invariant, and the payload should not be
- accessed (the key may not yet be instantiated).
-
- It is not safe to sleep in this method; the caller may hold spinlocks.
-
-
- (*) void (*revoke)(struct key *key);
-
- This method is optional. It is called to discard part of the payload
- data upon a key being revoked. The caller will have the key semaphore
- write-locked.
-
- It is safe to sleep in this method, though care should be taken to avoid
- a deadlock against the key semaphore.
-
-
- (*) void (*destroy)(struct key *key);
-
- This method is optional. It is called to discard the payload data on a key
- when it is being destroyed.
-
- This method does not need to lock the key to access the payload; it can
- consider the key as being inaccessible at this time. Note that the key's
- type may have been changed before this function is called.
-
- It is not safe to sleep in this method; the caller may hold spinlocks.
-
-
- (*) void (*describe)(const struct key *key, struct seq_file *p);
-
- This method is optional. It is called during /proc/keys reading to
- summarise a key's description and payload in text form.
-
- This method will be called with the RCU read lock held. rcu_dereference()
- should be used to read the payload pointer if the payload is to be
- accessed. key->datalen cannot be trusted to stay consistent with the
- contents of the payload.
-
- The description will not change, though the key's state may.
-
- It is not safe to sleep in this method; the RCU read lock is held by the
- caller.
-
-
- (*) long (*read)(const struct key *key, char __user *buffer, size_t buflen);
-
- This method is optional. It is called by KEYCTL_READ to translate the
- key's payload into something a blob of data for userspace to deal with.
- Ideally, the blob should be in the same format as that passed in to the
- instantiate and update methods.
-
- If successful, the blob size that could be produced should be returned
- rather than the size copied.
-
- This method will be called with the key's semaphore read-locked. This will
- prevent the key's payload changing. It is not necessary to use RCU locking
- when accessing the key's payload. It is safe to sleep in this method, such
- as might happen when the userspace buffer is accessed.
-
-
- (*) int (*request_key)(struct key_construction *cons, const char *op,
- void *aux);
-
- This method is optional. If provided, request_key() and friends will
- invoke this function rather than upcalling to /sbin/request-key to operate
- upon a key of this type.
-
- The aux parameter is as passed to request_key_async_with_auxdata() and
- similar or is NULL otherwise. Also passed are the construction record for
- the key to be operated upon and the operation type (currently only
- "create").
-
- This method is permitted to return before the upcall is complete, but the
- following function must be called under all circumstances to complete the
- instantiation process, whether or not it succeeds, whether or not there's
- an error:
-
- void complete_request_key(struct key_construction *cons, int error);
-
- The error parameter should be 0 on success, -ve on error. The
- construction record is destroyed by this action and the authorisation key
- will be revoked. If an error is indicated, the key under construction
- will be negatively instantiated if it wasn't already instantiated.
-
- If this method returns an error, that error will be returned to the
- caller of request_key*(). complete_request_key() must be called prior to
- returning.
-
- The key under construction and the authorisation key can be found in the
- key_construction struct pointed to by cons:
-
- (*) struct key *key;
-
- The key under construction.
-
- (*) struct key *authkey;
-
- The authorisation key.
-
-
-============================
-REQUEST-KEY CALLBACK SERVICE
-============================
-
-To create a new key, the kernel will attempt to execute the following command
-line:
-
- /sbin/request-key create <key> <uid> <gid> \
- <threadring> <processring> <sessionring> <callout_info>
-
-<key> is the key being constructed, and the three keyrings are the process
-keyrings from the process that caused the search to be issued. These are
-included for two reasons:
-
- (1) There may be an authentication token in one of the keyrings that is
- required to obtain the key, eg: a Kerberos Ticket-Granting Ticket.
-
- (2) The new key should probably be cached in one of these rings.
-
-This program should set it UID and GID to those specified before attempting to
-access any more keys. It may then look around for a user specific process to
-hand the request off to (perhaps a path held in placed in another key by, for
-example, the KDE desktop manager).
-
-The program (or whatever it calls) should finish construction of the key by
-calling KEYCTL_INSTANTIATE or KEYCTL_INSTANTIATE_IOV, which also permits it to
-cache the key in one of the keyrings (probably the session ring) before
-returning. Alternatively, the key can be marked as negative with KEYCTL_NEGATE
-or KEYCTL_REJECT; this also permits the key to be cached in one of the
-keyrings.
-
-If it returns with the key remaining in the unconstructed state, the key will
-be marked as being negative, it will be added to the session keyring, and an
-error will be returned to the key requestor.
-
-Supplementary information may be provided from whoever or whatever invoked this
-service. This will be passed as the <callout_info> parameter. If no such
-information was made available, then "-" will be passed as this parameter
-instead.
-
-
-Similarly, the kernel may attempt to update an expired or a soon to expire key
-by executing:
-
- /sbin/request-key update <key> <uid> <gid> \
- <threadring> <processring> <sessionring>
-
-In this case, the program isn't required to actually attach the key to a ring;
-the rings are provided for reference.
-
-
-==================
-GARBAGE COLLECTION
-==================
-
-Dead keys (for which the type has been removed) will be automatically unlinked
-from those keyrings that point to them and deleted as soon as possible by a
-background garbage collector.
-
-Similarly, revoked and expired keys will be garbage collected, but only after a
-certain amount of time has passed. This time is set as a number of seconds in:
-
- /proc/sys/kernel/keys/gc_delay
diff --git a/Documentation/security/tomoyo.txt b/Documentation/security/tomoyo.txt
deleted file mode 100644
index 200a2d37cbc..00000000000
--- a/Documentation/security/tomoyo.txt
+++ /dev/null
@@ -1,55 +0,0 @@
---- 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/ .
-Though these tutorials use non-LSM version of TOMOYO, they are useful for you
-to know what TOMOYO is.
-
---- How to enable TOMOYO? ---
-
-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? ---
-
-User <-> Kernel interface documentation is available at
-http://tomoyo.sourceforge.jp/2.3/policy-reference.html .
-
-Materials we prepared for seminars and symposiums are available at
-http://sourceforge.jp/projects/tomoyo/docs/?category_id=532&language_id=1 .
-Below lists are chosen from three aspects.
-
-What is TOMOYO?
- TOMOYO Linux Overview
- http://sourceforge.jp/projects/tomoyo/docs/lca2009-takeda.pdf
- TOMOYO Linux: pragmatic and manageable security for Linux
- http://sourceforge.jp/projects/tomoyo/docs/freedomhectaipei-tomoyo.pdf
- TOMOYO Linux: A Practical Method to Understand and Protect Your Own Linux Box
- http://sourceforge.jp/projects/tomoyo/docs/PacSec2007-en-no-demo.pdf
-
-What can TOMOYO do?
- Deep inside TOMOYO Linux
- http://sourceforge.jp/projects/tomoyo/docs/lca2009-kumaneko.pdf
- The role of "pathname based access control" in security.
- http://sourceforge.jp/projects/tomoyo/docs/lfj2008-bof.pdf
-
-History of TOMOYO?
- Realities of Mainlining
- http://sourceforge.jp/projects/tomoyo/docs/lfj2008.pdf
-
---- 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
-multiple LSM modules at the same time. We feel sorry that you have to give up
-SELinux/SMACK/AppArmor etc. when you want to use TOMOYO.
-
-We hope that LSM becomes stackable in future. Meanwhile, you can use non-LSM
-version of TOMOYO, available at http://tomoyo.sourceforge.jp/1.7/ .
-LSM version of TOMOYO is a subset of non-LSM version of TOMOYO. We are planning
-to port non-LSM version's functionalities to LSM versions.