diff options
| author | Linus Torvalds <torvalds@linux-foundation.org> | 2017-07-03 21:13:25 -0700 |
|---|---|---|
| committer | Linus Torvalds <torvalds@linux-foundation.org> | 2017-07-03 21:13:25 -0700 |
| commit | 650fc870a2ef35b83397eebd35b8c8df211bff78 (patch) | |
| tree | 14a293fa894d0f166aa60f1f5ca672a2bdb312c0 /Documentation/security | |
| parent | f4dd029ee0b92b77769a1ac6dce03e829e74763e (diff) | |
| parent | 1cb566ba5634d7593b8b2a0a5c83f1c9e14b2e09 (diff) | |
| download | linux-650fc870a2ef35b83397eebd35b8c8df211bff78.tar.bz2 | |
Merge tag 'docs-4.13' of git://git.lwn.net/linux
Pull documentation updates from Jonathan Corbet:
"There has been a fair amount of activity in the docs tree this time
around. Highlights include:
- Conversion of a bunch of security documentation into RST
- The conversion of the remaining DocBook templates by The Amazing
Mauro Machine. We can now drop the entire DocBook build chain.
- The usual collection of fixes and minor updates"
* tag 'docs-4.13' of git://git.lwn.net/linux: (90 commits)
scripts/kernel-doc: handle DECLARE_HASHTABLE
Documentation: atomic_ops.txt is core-api/atomic_ops.rst
Docs: clean up some DocBook loose ends
Make the main documentation title less Geocities
Docs: Use kernel-figure in vidioc-g-selection.rst
Docs: fix table problems in ras.rst
Docs: Fix breakage with Sphinx 1.5 and upper
Docs: Include the Latex "ifthen" package
doc/kokr/howto: Only send regression fixes after -rc1
docs-rst: fix broken links to dynamic-debug-howto in kernel-parameters
doc: Document suitability of IBM Verse for kernel development
Doc: fix a markup error in coding-style.rst
docs: driver-api: i2c: remove some outdated information
Documentation: DMA API: fix a typo in a function name
Docs: Insert missing space to separate link from text
doc/ko_KR/memory-barriers: Update control-dependencies example
Documentation, kbuild: fix typo "minimun" -> "minimum"
docs: Fix some formatting issues in request-key.rst
doc: ReSTify keys-trusted-encrypted.txt
doc: ReSTify keys-request-key.txt
...
Diffstat (limited to 'Documentation/security')
19 files changed, 463 insertions, 1464 deletions
diff --git a/Documentation/security/00-INDEX b/Documentation/security/00-INDEX deleted file mode 100644 index 45c82fd3e9d3..000000000000 --- a/Documentation/security/00-INDEX +++ /dev/null @@ -1,26 +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-ecryptfs.txt - - description of the encryption keys for the ecryptfs filesystem. -keys-request-key.txt - - description of the kernel key request service. -keys-trusted-encrypted.txt - - 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. -IMA-templates.txt - - documentation on the template management mechanism for IMA. diff --git a/Documentation/security/IMA-templates.txt b/Documentation/security/IMA-templates.rst index 839b5dad9226..2cd0e273cc9a 100644 --- a/Documentation/security/IMA-templates.txt +++ b/Documentation/security/IMA-templates.rst @@ -1,9 +1,12 @@ - IMA Template Management Mechanism +================================= +IMA Template Management Mechanism +================================= -==== INTRODUCTION ==== +Introduction +============ -The original 'ima' template is fixed length, containing the filedata hash +The original ``ima`` template is fixed length, containing the filedata hash and pathname. The filedata hash is limited to 20 bytes (md5/sha1). The pathname is a null terminated string, limited to 255 characters. To overcome these limitations and to add additional file metadata, it is @@ -28,61 +31,64 @@ a new data type, developers define the field identifier and implement two functions, init() and show(), respectively to generate and display measurement entries. Defining a new template descriptor requires specifying the template format (a string of field identifiers separated -by the '|' character) through the 'ima_template_fmt' kernel command line +by the ``|`` character) through the ``ima_template_fmt`` kernel command line parameter. At boot time, IMA initializes the chosen template descriptor by translating the format into an array of template fields structures taken from the set of the supported ones. -After the initialization step, IMA will call ima_alloc_init_template() +After the initialization step, IMA will call ``ima_alloc_init_template()`` (new function defined within the patches for the new template management mechanism) to generate a new measurement entry by using the template descriptor chosen through the kernel configuration or through the newly -introduced 'ima_template' and 'ima_template_fmt' kernel command line parameters. +introduced ``ima_template`` and ``ima_template_fmt`` kernel command line parameters. It is during this phase that the advantages of the new architecture are clearly shown: the latter function will not contain specific code to handle -a given template but, instead, it simply calls the init() method of the template +a given template but, instead, it simply calls the ``init()`` method of the template fields associated to the chosen template descriptor and store the result (pointer to allocated data and data length) in the measurement entry structure. The same mechanism is employed to display measurements entries. -The functions ima[_ascii]_measurements_show() retrieve, for each entry, +The functions ``ima[_ascii]_measurements_show()`` retrieve, for each entry, the template descriptor used to produce that entry and call the show() method for each item of the array of template fields structures. -==== SUPPORTED TEMPLATE FIELDS AND DESCRIPTORS ==== +Supported Template Fields and Descriptors +========================================= In the following, there is the list of supported template fields -('<identifier>': description), that can be used to define new template +``('<identifier>': description)``, that can be used to define new template descriptors by adding their identifier to the format string (support for more data types will be added later): - 'd': the digest of the event (i.e. the digest of a measured file), - calculated with the SHA1 or MD5 hash algorithm; + calculated with the SHA1 or MD5 hash algorithm; - 'n': the name of the event (i.e. the file name), with size up to 255 bytes; - 'd-ng': the digest of the event, calculated with an arbitrary hash - algorithm (field format: [<hash algo>:]digest, where the digest - prefix is shown only if the hash algorithm is not SHA1 or MD5); + algorithm (field format: [<hash algo>:]digest, where the digest + prefix is shown only if the hash algorithm is not SHA1 or MD5); - 'n-ng': the name of the event, without size limitations; - 'sig': the file signature. Below, there is the list of defined template descriptors: - - "ima": its format is 'd|n'; - - "ima-ng" (default): its format is 'd-ng|n-ng'; - - "ima-sig": its format is 'd-ng|n-ng|sig'. + - "ima": its format is ``d|n``; + - "ima-ng" (default): its format is ``d-ng|n-ng``; + - "ima-sig": its format is ``d-ng|n-ng|sig``. -==== USE ==== + +Use +=== To specify the template descriptor to be used to generate measurement entries, currently the following methods are supported: - select a template descriptor among those supported in the kernel - configuration ('ima-ng' is the default choice); + configuration (``ima-ng`` is the default choice); - specify a template descriptor name from the kernel command line through - the 'ima_template=' parameter; + the ``ima_template=`` parameter; - register a new template descriptor with custom format through the kernel - command line parameter 'ima_template_fmt='. + command line parameter ``ima_template_fmt=``. diff --git a/Documentation/security/LSM.rst b/Documentation/security/LSM.rst new file mode 100644 index 000000000000..d75778b0fa10 --- /dev/null +++ b/Documentation/security/LSM.rst @@ -0,0 +1,14 @@ +================================= +Linux Security Module Development +================================= + +Based on https://lkml.org/lkml/2007/10/26/215, +a new LSM is accepted into the kernel when its intent (a description of +what it tries to protect against and in what cases one would expect to +use it) has been appropriately documented in ``Documentation/security/LSM``. +This allows an LSM's code to be easily compared to its goals, and so +that end users and distros can make a more informed decision about which +LSMs suit their requirements. + +For extensive documentation on the available LSM hook interfaces, please +see ``include/linux/lsm_hooks.h``. diff --git a/Documentation/security/LSM.txt b/Documentation/security/LSM.txt deleted file mode 100644 index c2683f28ed36..000000000000 --- a/Documentation/security/LSM.txt +++ /dev/null @@ -1,41 +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. - -A list of the active security modules can be found by reading -/sys/kernel/security/lsm. This is a comma separated list, and -will always include the capability module. The list reflects the -order in which checks are made. The capability module will always -be first, followed by any "minor" modules (e.g. Yama) and then -the one "major" module (e.g. SELinux) if there is one configured. - -Based on https://lkml.org/lkml/2007/10/26/215, -a new LSM is accepted into the kernel when its intent (a description of -what it tries to protect against and in what cases one would expect to -use it) has been appropriately documented in Documentation/security/. -This allows an LSM's code to be easily compared to its goals, and so -that end users and distros can make a more informed decision about which -LSMs suit their requirements. - -For extensive documentation on the available LSM hook interfaces, please -see include/linux/security.h. diff --git a/Documentation/security/LoadPin.txt b/Documentation/security/LoadPin.txt deleted file mode 100644 index e11877f5d3d4..000000000000 --- a/Documentation/security/LoadPin.txt +++ /dev/null @@ -1,17 +0,0 @@ -LoadPin is a Linux Security Module that ensures all kernel-loaded files -(modules, firmware, etc) all originate from the same filesystem, with -the expectation that such a filesystem is backed by a read-only device -such as dm-verity or CDROM. This allows systems that have a verified -and/or unchangeable filesystem to enforce module and firmware loading -restrictions without needing to sign the files individually. - -The LSM is selectable at build-time with CONFIG_SECURITY_LOADPIN, and -can be controlled at boot-time with the kernel command line option -"loadpin.enabled". By default, it is enabled, but can be disabled at -boot ("loadpin.enabled=0"). - -LoadPin starts pinning when it sees the first file loaded. If the -block device backing the filesystem is not read-only, a sysctl is -created to toggle pinning: /proc/sys/kernel/loadpin/enabled. (Having -a mutable filesystem means pinning is mutable too, but having the -sysctl allows for easy testing on systems with a mutable filesystem.) diff --git a/Documentation/security/SELinux.txt b/Documentation/security/SELinux.txt deleted file mode 100644 index 07eae00f3314..000000000000 --- 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 945cc633d883..000000000000 --- a/Documentation/security/Smack.txt +++ /dev/null @@ -1,752 +0,0 @@ - - - "Good for you, you've decided to clean the elevator!" - - The Elevator, from Dark Star - -Smack is 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. - -Smack is used in the Tizen operating system. Please -go to http://wiki.tizen.org for information about how -Smack is used in Tizen. - -The current git repository for Smack user space is: - - git://github.com/smack-team/smack.git - -This should make and install on most modern distributions. -There are five commands included in smackutil: - -chsmack - display or set Smack extended attribute values -smackctl - load the Smack access rules -smackaccess - report if a process with one label has access - to an object with another - -These two commands are obsolete with the introduction of -the smackfs/load2 and smackfs/cipso2 interfaces. - -smackload - properly formats data for writing to smackfs/load -smackcipso - properly formats data for writing to smackfs/cipso - -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 /sys/fs/smackfs smackfs defaults 0 0 - -The /sys/fs/smackfs directory is created by the kernel. - -Smack uses extended attributes (xattrs) to store labels on filesystem -objects. The attributes are stored in the extended attribute security -name space. A process must have CAP_MAC_ADMIN to change any of these -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 mounted -on /sys/fs/smackfs. - -access - Provided for backward compatibility. The access2 interface - is preferred and should be used instead. - 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. -change-rule - This interface allows modification of existing access control rules. - The format accepted on write is: - "%s %s %s %s" - where the first string is the subject label, the second the - object label, the third the access to allow and the fourth the - access to deny. The access strings may contain only the characters - "rwxat-". If a rule for a given subject and object exists it will be - modified by enabling the permissions in the third string and disabling - those in the fourth string. If there is no such rule it will be - created using the access specified in the third and the fourth strings. -cipso - Provided for backward compatibility. The cipso2 interface - is preferred and should be used instead. - This interface allows a specific CIPSO header to be assigned - to a Smack label. The format accepted on write is: - "%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. -ipv6host - This interface allows specific IPv6 internet addresses to be - treated as single label hosts. Packets are sent to single - label hosts only from processes that have Smack write access - to the host label. All packets received from single label hosts - are given the specified label. The format accepted on write is: - "%h:%h:%h:%h:%h:%h:%h:%h label" or - "%h:%h:%h:%h:%h:%h:%h:%h/%d label". - The "::" address shortcut is not supported. - If label is "-DELETE" a matched entry will be deleted. -load - Provided for backward compatibility. The load2 interface - is preferred and should be used instead. - This interface allows access control rules in addition to - the system defined rules to be specified. The format accepted - on write is: - "%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 - Provided for backward compatibility. The load-self2 interface - is preferred and should be used instead. - 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". - If the label specified is "-CIPSO" the address is treated - as a host that supports CIPSO headers. -onlycap - This contains labels processes must have for CAP_MAC_ADMIN - and CAP_MAC_OVERRIDE to be effective. If this file is empty - these capabilities are effective at for processes with any - label. The values are set by writing the desired labels, separated - by spaces, to the file or cleared by writing "-" to the file. -ptrace - This is used to define the current ptrace policy - 0 - default: this is the policy that relies on Smack access rules. - For the PTRACE_READ a subject needs to have a read access on - object. For the PTRACE_ATTACH a read-write access is required. - 1 - exact: this is the policy that limits PTRACE_ATTACH. Attach is - only allowed when subject's and object's labels are equal. - PTRACE_READ is not affected. Can be overridden with CAP_SYS_PTRACE. - 2 - draconian: this policy behaves like the 'exact' above with an - exception that it can't be overridden with CAP_SYS_PTRACE. -revoke-subject - Writing a Smack label here sets the access to '-' for all access - rules with that subject label. -unconfined - If the kernel is configured with CONFIG_SECURITY_SMACK_BRINGUP - a process with CAP_MAC_ADMIN can write a label into this interface. - Thereafter, accesses that involve that label will be logged and - the access permitted if it wouldn't be otherwise. Note that this - is dangerous and can ruin the proper labeling of your system. - It should never be used in production. -relabel-self - This interface contains a list of labels to which the process can - transition to, by writing to /proc/self/attr/current. - Normally a process can change its own label to any legal value, but only - if it has CAP_MAC_ADMIN. This interface allows a process without - CAP_MAC_ADMIN to relabel itself to one of labels from predefined list. - A process without CAP_MAC_ADMIN can change its label only once. When it - does, this list will be cleared. - The values are set by writing the desired labels, separated - by spaces, to the file or cleared by writing "-" to the file. - -If you are using the smackload utility -you can add access rules in /etc/smack/accesses. They take the form: - - subjectlabel objectlabel access - -access is a combination of the letters rwxatb 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. They can be up to 255 characters -long, but keeping them to twenty-three characters is recommended. -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. The Smack label -of a process will usually be assigned by the system initialization -mechanism. - -Access Rules - -Smack uses the traditional access modes of Linux. These modes are read, -execute, write, and occasionally append. There are a few cases where the -access mode may not be obvious. These include: - - Signals: A signal is a write operation from the subject task to - 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. - b: indicates that the rule should be reported for bring-up. - -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 - Snap Crackle rwxatb - 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 (rwxatbRWXATB) 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 -/sys/fs/smackfs/load2. Rules can be added 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. - -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 or CAP_MAC_ADMIN is privileged. -CAP_MAC_OVERRIDE allows the process access to objects it would -be denied otherwise. CAP_MAC_ADMIN allows a process to change -Smack data, including rules and attributes. - -Smack Networking - -As mentioned before, Smack enforces access control on network protocol -transmissions. Every packet sent by a Smack process is tagged with its Smack -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 -/sys/fs/smackfs/doi and can be changed by writing to /sys/fs/smackfs/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 -/sys/fs/smackfs/cipso2. - -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 /sys/fs/smackfs/direct and changed by writing to -/sys/fs/smackfs/direct. - -Socket Attributes - -There are two attributes that are associated with sockets. These attributes -can only be set by privileged tasks, but any task can read them for their own -sockets. - - SMACK64IPIN: The Smack label of the task object. A privileged - 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 /sys/fs/smackfs/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 /sys/fs/smackfs/netlabel file are matched by longest mask -first, like in classless IPv4 routing. - -A special label '@' and an option '-CIPSO' can be used there : -@ means Internet, any application with any label has access to it --CIPSO means standard CIPSO networking - -If you don't know what CIPSO is and don't plan to use it, you can just do : -echo 127.0.0.1 -CIPSO > /sys/fs/smackfs/netlabel -echo 0.0.0.0/0 @ > /sys/fs/smackfs/netlabel - -If you use CIPSO on your 192.168.0.0/16 local network and need also unlabeled -Internet access, you can have : -echo 127.0.0.1 -CIPSO > /sys/fs/smackfs/netlabel -echo 192.168.0.0/16 -CIPSO > /sys/fs/smackfs/netlabel -echo 0.0.0.0/0 @ > /sys/fs/smackfs/netlabel - - -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 /sys/fs/smackfs/logging file : -0 : no logging -1 : log denied (default) -2 : log accepted -3 : log denied & accepted - -Events are logged as 'key=value' pairs, for each event you at least will get -the subject, the object, the rights requested, the action, the kernel function -that triggered the event, plus other pairs depending on the type of event -audited. - -Bringup Mode - -Bringup mode provides logging features that can make application -configuration and system bringup easier. Configure the kernel with -CONFIG_SECURITY_SMACK_BRINGUP to enable these features. When bringup -mode is enabled accesses that succeed due to rules marked with the "b" -access mode will logged. When a new label is introduced for processes -rules can be added aggressively, marked with the "b". The logging allows -tracking of which rules actual get used for that label. - -Another feature of bringup mode is the "unconfined" option. Writing -a label to /sys/fs/smackfs/unconfined makes subjects with that label -able to access any object, and objects with that label accessible to -all subjects. Any access that is granted because a label is unconfined -is logged. This feature is dangerous, as files and directories may -be created in places they couldn't if the policy were being enforced. diff --git a/Documentation/security/Yama.txt b/Documentation/security/Yama.txt deleted file mode 100644 index d9ee7d7a6c7f..000000000000 --- a/Documentation/security/Yama.txt +++ /dev/null @@ -1,71 +0,0 @@ -Yama is a Linux Security Module that collects system-wide DAC security -protections that are not handled by the core kernel itself. This is -selectable at build-time with CONFIG_SECURITY_YAMA, and can be controlled -at run-time through sysctls in /proc/sys/kernel/yama: - -- ptrace_scope - -============================================================== - -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 descendants) are allowed to call PTRACE_ATTACH -against it. Only one such declared debugging process can exists for -each inferior at a time. For example, this is used by KDE, Chromium, and -Firefox's crash handlers, and by Wine for allowing only Wine processes -to ptrace each other. If a process wishes to entirely disable these ptrace -restrictions, it can call prctl(PR_SET_PTRACER, PR_SET_PTRACER_ANY, ...) -so that any otherwise allowed process (even those in external pid namespaces) -may attach. - -The sysctl settings (writable only with CAP_SYS_PTRACE) 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). Similarly, PTRACE_TRACEME is - unchanged. - -1 - restricted ptrace: a process must have a predefined relationship - with the inferior it wants to call PTRACE_ATTACH on. By default, - this relationship is that of only its descendants when the above - classic criteria is also met. To change the relationship, an - inferior can call prctl(PR_SET_PTRACER, debugger, ...) to declare - an allowed debugger PID to call PTRACE_ATTACH on the inferior. - Using PTRACE_TRACEME is unchanged. - -2 - admin-only attach: only processes with CAP_SYS_PTRACE may use ptrace - with PTRACE_ATTACH, or through children calling PTRACE_TRACEME. - -3 - no attach: no processes may use ptrace with PTRACE_ATTACH nor via - PTRACE_TRACEME. Once set, this sysctl value cannot be changed. - -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 93c1fd7d0635..000000000000 --- 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/conf.py b/Documentation/security/conf.py deleted file mode 100644 index 472fc9a8eb67..000000000000 --- a/Documentation/security/conf.py +++ /dev/null @@ -1,8 +0,0 @@ -project = "The kernel security subsystem manual" - -tags.add("subproject") - -latex_documents = [ - ('index', 'security.tex', project, - 'The kernel development community', 'manual'), -] diff --git a/Documentation/security/credentials.txt b/Documentation/security/credentials.rst index 86257052e31a..038a7e19eff9 100644 --- a/Documentation/security/credentials.txt +++ b/Documentation/security/credentials.rst @@ -1,38 +1,18 @@ - ==================== - CREDENTIALS IN LINUX - ==================== +==================== +Credentials in Linux +==================== By: David Howells <dhowells@redhat.com> -Contents: - - (*) Overview. - - (*) Types of credentials. - - (*) File markings. - - (*) Task credentials. +.. contents:: :local: - - Immutable credentials. - - Accessing task credentials. - - Accessing another task's credentials. - - Altering credentials. - - Managing credentials. - - (*) Open file credentials. - - (*) Overriding the VFS's use of credentials. - - -======== -OVERVIEW +Overview ======== There are several parts to the security check performed by Linux when one object acts upon another: - (1) Objects. + 1. Objects. Objects are things in the system that may be acted upon directly by userspace programs. Linux has a variety of actionable objects, including: @@ -48,7 +28,7 @@ object acts upon another: As a part of the description of all these objects there is a set of credentials. What's in the set depends on the type of object. - (2) Object ownership. + 2. Object ownership. Amongst the credentials of most objects, there will be a subset that indicates the ownership of that object. This is used for resource @@ -57,7 +37,7 @@ object acts upon another: In a standard UNIX filesystem, for instance, this will be defined by the UID marked on the inode. - (3) The objective context. + 3. The objective context. Also amongst the credentials of those objects, there will be a subset that indicates the 'objective context' of that object. This may or may not be @@ -67,7 +47,7 @@ object acts upon another: The objective context is used as part of the security calculation that is carried out when an object is acted upon. - (4) Subjects. + 4. Subjects. A subject is an object that is acting upon another object. @@ -77,10 +57,10 @@ object acts upon another: Objects other than tasks may under some circumstances also be subjects. For instance an open file may send SIGIO to a task using the UID and EUID - given to it by a task that called fcntl(F_SETOWN) upon it. In this case, + given to it by a task that called ``fcntl(F_SETOWN)`` upon it. In this case, the file struct will have a subjective context too. - (5) The subjective context. + 5. The subjective context. A subject has an additional interpretation of its credentials. A subset of its credentials forms the 'subjective context'. The subjective context @@ -92,7 +72,7 @@ object acts upon another: from the real UID and GID that normally form the objective context of the task. - (6) Actions. + 6. Actions. Linux has a number of actions available that a subject may perform upon an object. The set of actions available depends on the nature of the subject @@ -101,7 +81,7 @@ object acts upon another: Actions include reading, writing, creating and deleting files; forking or signalling and tracing tasks. - (7) Rules, access control lists and security calculations. + 7. Rules, access control lists and security calculations. When a subject acts upon an object, a security calculation is made. This involves taking the subjective context, the objective context and the @@ -111,7 +91,7 @@ object acts upon another: There are two main sources of rules: - (a) Discretionary access control (DAC): + a. Discretionary access control (DAC): Sometimes the object will include sets of rules as part of its description. This is an 'Access Control List' or 'ACL'. A Linux @@ -127,7 +107,7 @@ object acts upon another: A Linux file might also sport a POSIX ACL. This is a list of rules that grants various permissions to arbitrary subjects. - (b) Mandatory access control (MAC): + b. Mandatory access control (MAC): The system as a whole may have one or more sets of rules that get applied to all subjects and objects, regardless of their source. @@ -139,65 +119,65 @@ object acts upon another: that says that this action is either granted or denied. -==================== -TYPES OF CREDENTIALS +Types of Credentials ==================== The Linux kernel supports the following types of credentials: - (1) Traditional UNIX credentials. + 1. Traditional UNIX credentials. - Real User ID - Real Group ID + - Real User ID + - Real Group ID The UID and GID are carried by most, if not all, Linux objects, even if in some cases it has to be invented (FAT or CIFS files for example, which are derived from Windows). These (mostly) define the objective context of that object, with tasks being slightly different in some cases. - Effective, Saved and FS User ID - Effective, Saved and FS Group ID - Supplementary groups + - Effective, Saved and FS User ID + - Effective, Saved and FS Group ID + - Supplementary groups These are additional credentials used by tasks only. Usually, an EUID/EGID/GROUPS will be used as the subjective context, and real UID/GID will be used as the objective. For tasks, it should be noted that this is not always true. - (2) Capabilities. + 2. Capabilities. - Set of permitted capabilities - Set of inheritable capabilities - Set of effective capabilities - Capability bounding set + - Set of permitted capabilities + - Set of inheritable capabilities + - Set of effective capabilities + - Capability bounding set These are only carried by tasks. They indicate superior capabilities granted piecemeal to a task that an ordinary task wouldn't otherwise have. These are manipulated implicitly by changes to the traditional UNIX - credentials, but can also be manipulated directly by the capset() system - call. + credentials, but can also be manipulated directly by the ``capset()`` + system call. The permitted capabilities are those caps that the process might grant - itself to its effective or permitted sets through capset(). This + itself to its effective or permitted sets through ``capset()``. This inheritable set might also be so constrained. The effective capabilities are the ones that a task is actually allowed to make use of itself. The inheritable capabilities are the ones that may get passed across - execve(). + ``execve()``. The bounding set limits the capabilities that may be inherited across - execve(), especially when a binary is executed that will execute as UID 0. + ``execve()``, especially when a binary is executed that will execute as + UID 0. - (3) Secure management flags (securebits). + 3. Secure management flags (securebits). These are only carried by tasks. These govern the way the above credentials are manipulated and inherited over certain operations such as execve(). They aren't used directly as objective or subjective credentials. - (4) Keys and keyrings. + 4. Keys and keyrings. These are only carried by tasks. They carry and cache security tokens that don't fit into the other standard UNIX credentials. They are for @@ -218,7 +198,7 @@ The Linux kernel supports the following types of credentials: For more information on using keys, see Documentation/security/keys.txt. - (5) LSM + 5. LSM The Linux Security Module allows extra controls to be placed over the operations that a task may do. Currently Linux supports several LSM @@ -228,7 +208,7 @@ The Linux kernel supports the following types of credentials: rules (policies) that say what operations a task with one label may do to an object with another label. - (6) AF_KEY + 6. AF_KEY This is a socket-based approach to credential management for networking stacks [RFC 2367]. It isn't discussed by this document as it doesn't @@ -244,25 +224,19 @@ network filesystem where the credentials of the opened file should be presented to the server, regardless of who is actually doing a read or a write upon it. -============= -FILE MARKINGS +File Markings ============= Files on disk or obtained over the network may have annotations that form the objective security context of that file. Depending on the type of filesystem, this may include one or more of the following: - (*) UNIX UID, GID, mode; - - (*) Windows user ID; - - (*) Access control list; - - (*) LSM security label; - - (*) UNIX exec privilege escalation bits (SUID/SGID); - - (*) File capabilities exec privilege escalation bits. + * UNIX UID, GID, mode; + * Windows user ID; + * Access control list; + * LSM security label; + * UNIX exec privilege escalation bits (SUID/SGID); + * File capabilities exec privilege escalation bits. These are compared to the task's subjective security context, and certain operations allowed or disallowed as a result. In the case of execve(), the @@ -270,8 +244,7 @@ privilege escalation bits come into play, and may allow the resulting process extra privileges, based on the annotations on the executable file. -================ -TASK CREDENTIALS +Task Credentials ================ In Linux, all of a task's credentials are held in (uid, gid) or through @@ -282,20 +255,20 @@ task_struct. Once a set of credentials has been prepared and committed, it may not be changed, barring the following exceptions: - (1) its reference count may be changed; + 1. its reference count may be changed; - (2) the reference count on the group_info struct it points to may be changed; + 2. the reference count on the group_info struct it points to may be changed; - (3) the reference count on the security data it points to may be changed; + 3. the reference count on the security data it points to may be changed; - (4) the reference count on any keyrings it points to may be changed; + 4. the reference count on any keyrings it points to may be changed; - (5) any keyrings it points to may be revoked, expired or have their security - attributes changed; and + 5. any keyrings it points to may be revoked, expired or have their security + attributes changed; and - (6) the contents of any keyrings to which it points may be changed (the whole - point of keyrings being a shared set of credentials, modifiable by anyone - with appropriate access). + 6. the contents of any keyrings to which it points may be changed (the whole + point of keyrings being a shared set of credentials, modifiable by anyone + with appropriate access). To alter anything in the cred struct, the copy-and-replace principle must be adhered to. First take a copy, then alter the copy and then use RCU to change @@ -303,37 +276,37 @@ the task pointer to make it point to the new copy. There are wrappers to aid with this (see below). A task may only alter its _own_ credentials; it is no longer permitted for a -task to alter another's credentials. This means the capset() system call is no -longer permitted to take any PID other than the one of the current process. -Also keyctl_instantiate() and keyctl_negate() functions no longer permit -attachment to process-specific keyrings in the requesting process as the -instantiating process may need to create them. +task to alter another's credentials. This means the ``capset()`` system call +is no longer permitted to take any PID other than the one of the current +process. Also ``keyctl_instantiate()`` and ``keyctl_negate()`` functions no +longer permit attachment to process-specific keyrings in the requesting +process as the instantiating process may need to create them. -IMMUTABLE CREDENTIALS +Immutable Credentials --------------------- -Once a set of credentials has been made public (by calling commit_creds() for -example), it must be considered immutable, barring two exceptions: +Once a set of credentials has been made public (by calling ``commit_creds()`` +for example), it must be considered immutable, barring two exceptions: - (1) The reference count may be altered. + 1. The reference count may be altered. - (2) Whilst the keyring subscriptions of a set of credentials may not be - changed, the keyrings subscribed to may have their contents altered. + 2. Whilst the keyring subscriptions of a set of credentials may not be + changed, the keyrings subscribed to may have their contents altered. To catch accidental credential alteration at compile time, struct task_struct has _const_ pointers to its credential sets, as does struct file. Furthermore, -certain functions such as get_cred() and put_cred() operate on const pointers, -thus rendering casts unnecessary, but require to temporarily ditch the const -qualification to be able to alter the reference count. +certain functions such as ``get_cred()`` and ``put_cred()`` operate on const +pointers, thus rendering casts unnecessary, but require to temporarily ditch +the const qualification to be able to alter the reference count. -ACCESSING TASK CREDENTIALS +Accessing Task Credentials -------------------------- A task being able to alter only its own credentials permits the current process to read or replace its own credentials without the need for any form of locking -- which simplifies things greatly. It can just call: +-- which simplifies things greatly. It can just call:: const struct cred *current_cred() @@ -341,7 +314,7 @@ to get a pointer to its credentials structure, and it doesn't have to release it afterwards. There are convenience wrappers for retrieving specific aspects of a task's -credentials (the value is simply returned in each case): +credentials (the value is simply returned in each case):: uid_t current_uid(void) Current's real UID gid_t current_gid(void) Current's real GID @@ -354,7 +327,7 @@ credentials (the value is simply returned in each case): struct user_struct *current_user(void) Current's user account There are also convenience wrappers for retrieving specific associated pairs of -a task's credentials: +a task's credentials:: void current_uid_gid(uid_t *, gid_t *); void current_euid_egid(uid_t *, gid_t *); @@ -365,12 +338,12 @@ them from the current task's credentials. In addition, there is a function for obtaining a reference on the current -process's current set of credentials: +process's current set of credentials:: const struct cred *get_current_cred(void); and functions for getting references to one of the credentials that don't -actually live in struct cred: +actually live in struct cred:: struct user_struct *get_current_user(void); struct group_info *get_current_groups(void); @@ -378,22 +351,22 @@ actually live in struct cred: which get references to the current process's user accounting structure and supplementary groups list respectively. -Once a reference has been obtained, it must be released with put_cred(), -free_uid() or put_group_info() as appropriate. +Once a reference has been obtained, it must be released with ``put_cred()``, +``free_uid()`` or ``put_group_info()`` as appropriate. -ACCESSING ANOTHER TASK'S CREDENTIALS +Accessing Another Task's Credentials ------------------------------------ Whilst a task may access its own credentials without the need for locking, the same is not true of a task wanting to access another task's credentials. It -must use the RCU read lock and rcu_dereference(). +must use the RCU read lock and ``rcu_dereference()``. -The rcu_dereference() is wrapped by: +The ``rcu_dereference()`` is wrapped by:: const struct cred *__task_cred(struct task_struct *task); -This should be used inside the RCU read lock, as in the following example: +This should be used inside the RCU read lock, as in the following example:: void foo(struct task_struct *t, struct foo_data *f) { @@ -410,39 +383,40 @@ This should be used inside the RCU read lock, as in the following example: Should it be necessary to hold another task's credentials for a long period of time, and possibly to sleep whilst doing so, then the caller should get a -reference on them using: +reference on them using:: const struct cred *get_task_cred(struct task_struct *task); This does all the RCU magic inside of it. The caller must call put_cred() on the credentials so obtained when they're finished with. - [*] Note: The result of __task_cred() should not be passed directly to - get_cred() as this may race with commit_cred(). +.. note:: + The result of ``__task_cred()`` should not be passed directly to + ``get_cred()`` as this may race with ``commit_cred()``. There are a couple of convenience functions to access bits of another task's -credentials, hiding the RCU magic from the caller: +credentials, hiding the RCU magic from the caller:: uid_t task_uid(task) Task's real UID uid_t task_euid(task) Task's effective UID -If the caller is holding the RCU read lock at the time anyway, then: +If the caller is holding the RCU read lock at the time anyway, then:: __task_cred(task)->uid __task_cred(task)->euid should be used instead. Similarly, if multiple aspects of a task's credentials -need to be accessed, RCU read lock should be used, __task_cred() called, the -result stored in a temporary pointer and then the credential aspects called +need to be accessed, RCU read lock should be used, ``__task_cred()`` called, +the result stored in a temporary pointer and then the credential aspects called from that before dropping the lock. This prevents the potentially expensive RCU magic from being invoked multiple times. Should some other single aspect of another task's credentials need to be -accessed, then this can be used: +accessed, then this can be used:: task_cred_xxx(task, member) -where 'member' is a non-pointer member of the cred struct. For instance: +where 'member' is a non-pointer member of the cred struct. For instance:: uid_t task_cred_xxx(task, suid); @@ -451,7 +425,7 @@ magic. This may not be used for pointer members as what they point to may disappear the moment the RCU read lock is dropped. -ALTERING CREDENTIALS +Altering Credentials -------------------- As previously mentioned, a task may only alter its own credentials, and may not @@ -459,7 +433,7 @@ alter those of another task. This means that it doesn't need to use any locking to alter its own credentials. To alter the current process's credentials, a function should first prepare a -new set of credentials by calling: +new set of credentials by calling:: struct cred *prepare_creds(void); @@ -467,9 +441,10 @@ this locks current->cred_replace_mutex and then allocates and constructs a duplicate of the current process's credentials, returning with the mutex still held if successful. It returns NULL if not successful (out of memory). -The mutex prevents ptrace() from altering the ptrace state of a process whilst -security checks on credentials construction and changing is taking place as -the ptrace state may alter the outcome, particularly in the case of execve(). +The mutex prevents ``ptrace()`` from altering the ptrace state of a process +whilst security checks on credentials construction and changing is taking place +as the ptrace state may alter the outcome, particularly in the case of +``execve()``. The new credentials set should be altered appropriately, and any security checks and hooks done. Both the current and the proposed sets of credentials @@ -478,36 +453,37 @@ still at this point. When the credential set is ready, it should be committed to the current process -by calling: +by calling:: int commit_creds(struct cred *new); This will alter various aspects of the credentials and the process, giving the -LSM a chance to do likewise, then it will use rcu_assign_pointer() to actually -commit the new credentials to current->cred, it will release -current->cred_replace_mutex to allow ptrace() to take place, and it will notify -the scheduler and others of the changes. +LSM a chance to do likewise, then it will use ``rcu_assign_pointer()`` to +actually commit the new credentials to ``current->cred``, it will release +``current->cred_replace_mutex`` to allow ``ptrace()`` to take place, and it +will notify the scheduler and others of the changes. This function is guaranteed to return 0, so that it can be tail-called at the -end of such functions as sys_setresuid(). +end of such functions as ``sys_setresuid()``. Note that this function consumes the caller's reference to the new credentials. -The caller should _not_ call put_cred() on the new credentials afterwards. +The caller should _not_ call ``put_cred()`` on the new credentials afterwards. Furthermore, once this function has been called on a new set of credentials, those credentials may _not_ be changed further. -Should the security checks fail or some other error occur after prepare_creds() -has been called, then the following function should be invoked: +Should the security checks fail or some other error occur after +``prepare_creds()`` has been called, then the following function should be +invoked:: void abort_creds(struct cred *new); -This releases the lock on current->cred_replace_mutex that prepare_creds() got -and then releases the new credentials. +This releases the lock on ``current->cred_replace_mutex`` that +``prepare_creds()`` got and then releases the new credentials. -A typical credentials alteration function would look something like this: +A typical credentials alteration function would look something like this:: int alter_suid(uid_t suid) { @@ -529,53 +505,50 @@ A typical credentials alteration function would look something like this: } -MANAGING CREDENTIALS +Managing Credentials -------------------- There are some functions to help manage credentials: - (*) void put_cred(const struct cred *cred); + - ``void put_cred(const struct cred *cred);`` This releases a reference to the given set of credentials. If the reference count reaches zero, the credentials will be scheduled for destruction by the RCU system. - (*) const struct cred *get_cred(const struct cred *cred); + - ``const struct cred *get_cred(const struct cred *cred);`` This gets a reference on a live set of credentials, returning a pointer to that set of credentials. - (*) struct cred *get_new_cred(struct cred *cred); + - ``struct cred *get_new_cred(struct cred *cred);`` This gets a reference on a set of credentials that is under construction and is thus still mutable, returning a pointer to that set of credentials. -===================== -OPEN FILE CREDENTIALS +Open File Credentials ===================== When a new file is opened, a reference is obtained on the opening task's -credentials and this is attached to the file struct as 'f_cred' in place of -'f_uid' and 'f_gid'. Code that used to access file->f_uid and file->f_gid -should now access file->f_cred->fsuid and file->f_cred->fsgid. +credentials and this is attached to the file struct as ``f_cred`` in place of +``f_uid`` and ``f_gid``. Code that used to access ``file->f_uid`` and +``file->f_gid`` should now access ``file->f_cred->fsuid`` and +``file->f_cred->fsgid``. -It is safe to access f_cred without the use of RCU or locking because the +It is safe to access ``f_cred`` without the use of RCU or locking because the pointer will not change over the lifetime of the file struct, and nor will the contents of the cred struct pointed to, barring the exceptions listed above (see the Task Credentials section). -======================================= -OVERRIDING THE VFS'S USE OF CREDENTIALS +Overriding the VFS's Use of Credentials ======================================= Under some circumstances it is desirable to override the credentials used by -the VFS, and that can be done by calling into such as vfs_mkdir() with a +the VFS, and that can be done by calling into such as ``vfs_mkdir()`` with a different set of credentials. This is done in the following places: - (*) sys_faccessat(). - - (*) do_coredump(). - - (*) nfs4recover.c. + * ``sys_faccessat()``. + * ``do_coredump()``. + * nfs4recover.c. diff --git a/Documentation/security/index.rst b/Documentation/security/index.rst index 9bae6bb20e7f..298a94a33f05 100644 --- a/Documentation/security/index.rst +++ b/Documentation/security/index.rst @@ -1,7 +1,13 @@ ====================== -Security documentation +Security Documentation ====================== .. toctree:: + :maxdepth: 1 + credentials + IMA-templates + keys/index + LSM + self-protection tpm/index diff --git a/Documentation/security/keys.txt b/Documentation/security/keys/core.rst index cd5019934d7f..0d831a7afe4f 100644 --- a/Documentation/security/keys.txt +++ b/Documentation/security/keys/core.rst @@ -1,6 +1,6 @@ - ============================ - KERNEL KEY RETENTION SERVICE - ============================ +============================ +Kernel Key Retention Service +============================ This service allows cryptographic keys, authentication tokens, cross-domain user mappings, and similar to be cached in the kernel for the use of @@ -29,8 +29,7 @@ This document has the following sections: - Garbage collection -============ -KEY OVERVIEW +Key Overview ============ In this context, keys represent units of cryptographic data, authentication @@ -47,14 +46,14 @@ Each key has a number of attributes: - State. - (*) Each key is issued a serial number of type key_serial_t that is unique for + * Each key is issued a serial number of type key_serial_t that is unique for the lifetime of that key. All serial numbers are positive non-zero 32-bit integers. Userspace programs can use a key's serial numbers as a way to gain access to it, subject to permission checking. - (*) Each key is of a defined "type". Types must be registered inside the + * Each key is of a defined "type". Types must be registered inside the kernel by a kernel service (such as a filesystem) before keys of that type can be added or used. Userspace programs cannot define new types directly. @@ -64,18 +63,18 @@ Each key has a number of attributes: Should a type be removed from the system, all the keys of that type will be invalidated. - (*) Each key has a description. This should be a printable string. The key + * Each key has a description. This should be a printable string. The key type provides an operation to perform a match between the description on a key and a criterion string. - (*) Each key has an owner user ID, a group ID and a permissions mask. These + * Each key has an owner user ID, a group ID and a permissions mask. These are used to control what a process may do to a key from userspace, and whether a kernel service will be able to find the key. - (*) Each key can be set to expire at a specific time by the key type's + * Each key can be set to expire at a specific time by the key type's instantiation function. Keys can also be immortal. - (*) Each key can have a payload. This is a quantity of data that represent the + * Each key can have a payload. This is a quantity of data that represent the actual "key". In the case of a keyring, this is a list of keys to which the keyring links; in the case of a user-defined key, it's an arbitrary blob of data. @@ -91,39 +90,38 @@ Each key has a number of attributes: permitted, another key type operation will be called to convert the key's attached payload back into a blob of data. - (*) Each key can be in one of a number of basic states: + * Each key can be in one of a number of basic states: - (*) Uninstantiated. The key exists, but does not have any data attached. + * Uninstantiated. The key exists, but does not have any data attached. Keys being requested from userspace will be in this state. - (*) Instantiated. This is the normal state. The key is fully formed, and + * Instantiated. This is the normal state. The key is fully formed, and has data attached. - (*) Negative. This is a relatively short-lived state. The key acts as a + * Negative. This is a relatively short-lived state. The key acts as a note saying that a previous call out to userspace failed, and acts as a throttle on key lookups. A negative key can be updated to a normal state. - (*) Expired. Keys can have lifetimes set. If their lifetime is exceeded, + * Expired. Keys can have lifetimes set. If their lifetime is exceeded, they traverse to this state. An expired key can be updated back to a normal state. - (*) Revoked. A key is put in this state by userspace action. It can't be + * Revoked. A key is put in this state by userspace action. It can't be found or operated upon (apart from by unlinking it). - (*) Dead. The key's type was unregistered, and so the key is now useless. + * Dead. The key's type was unregistered, and so the key is now useless. Keys in the last three states are subject to garbage collection. See the section on "Garbage collection". -==================== -KEY SERVICE OVERVIEW +Key Service Overview ==================== The key service provides a number of features besides keys: - (*) The key service defines three special key types: + * The key service defines three special key types: (+) "keyring" @@ -149,7 +147,7 @@ The key service provides a number of features besides keys: be created and updated from userspace, but the payload is only readable from kernel space. - (*) Each process subscribes to three keyrings: a thread-specific keyring, a + * Each process subscribes to three keyrings: a thread-specific keyring, a process-specific keyring, and a session-specific keyring. The thread-specific keyring is discarded from the child when any sort of @@ -170,7 +168,7 @@ The key service provides a number of features besides keys: The ownership of the thread keyring changes when the real UID and GID of the thread changes. - (*) Each user ID resident in the system holds two special keyrings: a user + * Each user ID resident in the system holds two special keyrings: a user specific keyring and a default user session keyring. The default session keyring is initialised with a link to the user-specific keyring. @@ -180,7 +178,7 @@ The key service provides a number of features besides keys: If a process attempts to access its session key when it doesn't have one, it will be subscribed to the default for its current UID. - (*) Each user has two quotas against which the keys they own are tracked. One + * Each user has two quotas against which the keys they own are tracked. One limits the total number of keys and keyrings, the other limits the total amount of description and payload space that can be consumed. @@ -194,54 +192,53 @@ The key service provides a number of features besides keys: If a system call that modifies a key or keyring in some way would put the user over quota, the operation is refused and error EDQUOT is returned. - (*) There's a system call interface by which userspace programs can create and + * There's a system call interface by which userspace programs can create and manipulate keys and keyrings. - (*) There's a kernel interface by which services can register types and search + * There's a kernel interface by which services can register types and search for keys. - (*) There's a way for the a search done from the kernel to call back to + * There's a way for the a search done from the kernel to call back to userspace to request a key that can't be found in a process's keyrings. - (*) An optional filesystem is available through which the key database can be + * An optional filesystem is available through which the key database can be viewed and manipulated. -====================== -KEY ACCESS PERMISSIONS +Key Access Permissions ====================== Keys have an owner user ID, a group access ID, and a permissions mask. The mask has up to eight bits each for possessor, user, group and other access. Only six of each set of eight bits are defined. These permissions granted are: - (*) View + * View This permits a key or keyring's attributes to be viewed - including key type and description. - (*) Read + * Read This permits a key's payload to be viewed or a keyring's list of linked keys. - (*) Write + * Write This permits a key's payload to be instantiated or updated, or it allows a link to be added to or removed from a keyring. - (*) Search + * Search This permits keyrings to be searched and keys to be found. Searches can only recurse into nested keyrings that have search permission set. - (*) Link + * Link This permits a key or keyring to be linked to. To create a link from a keyring to a key, a process must have Write permission on the keyring and Link permission on the key. - (*) Set Attribute + * Set Attribute This permits a key's UID, GID and permissions mask to be changed. @@ -249,8 +246,7 @@ For changing the ownership, group ID or permissions mask, being the owner of the key or having the sysadmin capability is sufficient. -=============== -SELINUX SUPPORT +SELinux Support =============== The security class "key" has been added to SELinux so that mandatory access @@ -282,14 +278,13 @@ their associated thread, and both session and process keyrings are handled similarly. -================ -NEW PROCFS FILES +New ProcFS Files ================ Two files have been added to procfs by which an administrator can find out about the status of the key service: - (*) /proc/keys + * /proc/keys This lists the keys that are currently viewable by the task reading the file, giving information about their type, description and permissions. @@ -301,7 +296,7 @@ about the status of the key service: security checks are still performed, and may further filter out keys that the current process is not authorised to view. - The contents of the file look like this: + The contents of the file look like this:: SERIAL FLAGS USAGE EXPY PERM UID GID TYPE DESCRIPTION: SUMMARY 00000001 I----- 39 perm 1f3f0000 0 0 keyring _uid_ses.0: 1/4 @@ -314,7 +309,7 @@ about the status of the key service: 00000893 I--Q-N 1 35s 1f3f0000 0 0 user metal:silver: 0 00000894 I--Q-- 1 10h 003f0000 0 0 user metal:gold: 0 - The flags are: + The flags are:: I Instantiated R Revoked @@ -324,10 +319,10 @@ about the status of the key service: N Negative key - (*) /proc/key-users + * /proc/key-users This file lists the tracking data for each user that has at least one key - on the system. Such data includes quota information and statistics: + on the system. Such data includes quota information and statistics:: [root@andromeda root]# cat /proc/key-users 0: 46 45/45 1/100 13/10000 @@ -335,7 +330,8 @@ about the status of the key service: 32: 2 2/2 2/100 40/10000 38: 2 2/2 2/100 40/10000 - The format of each line is + The format of each line is:: + <UID>: User ID to which this applies <usage> Structure refcount <inst>/<keys> Total number of keys and number instantiated @@ -346,14 +342,14 @@ about the status of the key service: Four new sysctl files have been added also for the purpose of controlling the quota limits on keys: - (*) /proc/sys/kernel/keys/root_maxkeys + * /proc/sys/kernel/keys/root_maxkeys /proc/sys/kernel/keys/root_maxbytes These files hold the maximum number of keys that root may have and the maximum total number of bytes of data that root may have stored in those keys. - (*) /proc/sys/kernel/keys/maxkeys + * /proc/sys/kernel/keys/maxkeys /proc/sys/kernel/keys/maxbytes These files hold the maximum number of keys that each non-root user may @@ -364,8 +360,7 @@ Root may alter these by writing each new limit as a decimal number string to the appropriate file. -=============================== -USERSPACE SYSTEM CALL INTERFACE +Userspace System Call Interface =============================== Userspace can manipulate keys directly through three new syscalls: add_key, @@ -375,7 +370,7 @@ manipulating keys. When referring to a key directly, userspace programs should use the key's serial number (a positive 32-bit integer). However, there are some special values available for referring to special keys and keyrings that relate to the -process making the call: +process making the call:: CONSTANT VALUE KEY REFERENCED ============================== ====== =========================== @@ -391,8 +386,8 @@ process making the call: The main syscalls are: - (*) Create a new key of given type, description and payload and add it to the - nominated keyring: + * Create a new key of given type, description and payload and add it to the + nominated keyring:: key_serial_t add_key(const char *type, const char *desc, const void *payload, size_t plen, @@ -432,8 +427,8 @@ The main syscalls are: The ID of the new or updated key is returned if successful. - (*) Search the process's keyrings for a key, potentially calling out to - userspace to create it. + * Search the process's keyrings for a key, potentially calling out to + userspace to create it:: key_serial_t request_key(const char *type, const char *description, const char *callout_info, @@ -453,7 +448,7 @@ The main syscalls are: The keyctl syscall functions are: - (*) Map a special key ID to a real key ID for this process: + * Map a special key ID to a real key ID for this process:: key_serial_t keyctl(KEYCTL_GET_KEYRING_ID, key_serial_t id, int create); @@ -466,7 +461,7 @@ The keyctl syscall functions are: non-zero; and the error ENOKEY will be returned if "create" is zero. - (*) Replace the session keyring this process subscribes to with a new one: + * Replace the session keyring this process subscribes to with a new one:: key_serial_t keyctl(KEYCTL_JOIN_SESSION_KEYRING, const char *name); @@ -484,7 +479,7 @@ The keyctl syscall functions are: The ID of the new session keyring is returned if successful. - (*) Update the specified key: + * Update the specified key:: long keyctl(KEYCTL_UPDATE, key_serial_t key, const void *payload, size_t plen); @@ -498,7 +493,7 @@ The keyctl syscall functions are: add_key(). - (*) Revoke a key: + * Revoke a key:: long keyctl(KEYCTL_REVOKE, key_serial_t key); @@ -507,7 +502,7 @@ The keyctl syscall functions are: be findable. - (*) Change the ownership of a key: + * Change the ownership of a key:: long keyctl(KEYCTL_CHOWN, key_serial_t key, uid_t uid, gid_t gid); @@ -520,7 +515,7 @@ The keyctl syscall functions are: its group list members. - (*) Change the permissions mask on a key: + * Change the permissions mask on a key:: long keyctl(KEYCTL_SETPERM, key_serial_t key, key_perm_t perm); @@ -531,7 +526,7 @@ The keyctl syscall functions are: error EINVAL will be returned. - (*) Describe a key: + * Describe a key:: long keyctl(KEYCTL_DESCRIBE, key_serial_t key, char *buffer, size_t buflen); @@ -547,7 +542,7 @@ The keyctl syscall functions are: A process must have view permission on the key for this function to be successful. - If successful, a string is placed in the buffer in the following format: + If successful, a string is placed in the buffer in the following format:: <type>;<uid>;<gid>;<perm>;<description> @@ -555,12 +550,12 @@ The keyctl syscall functions are: is hexadecimal. A NUL character is included at the end of the string if the buffer is sufficiently big. - This can be parsed with + This can be parsed with:: sscanf(buffer, "%[^;];%d;%d;%o;%s", type, &uid, &gid, &mode, desc); - (*) Clear out a keyring: + * Clear out a keyring:: long keyctl(KEYCTL_CLEAR, key_serial_t keyring); @@ -573,7 +568,7 @@ The keyctl syscall functions are: DNS resolver cache keyring is an example of this. - (*) Link a key into a keyring: + * Link a key into a keyring:: long keyctl(KEYCTL_LINK, key_serial_t keyring, key_serial_t key); @@ -592,7 +587,7 @@ The keyctl syscall functions are: added. - (*) Unlink a key or keyring from another keyring: + * Unlink a key or keyring from another keyring:: long keyctl(KEYCTL_UNLINK, key_serial_t keyring, key_serial_t key); @@ -604,7 +599,7 @@ The keyctl syscall functions are: is not present, error ENOENT will be the result. - (*) Search a keyring tree for a key: + * Search a keyring tree for a key:: key_serial_t keyctl(KEYCTL_SEARCH, key_serial_t keyring, const char *type, const char *description, @@ -628,7 +623,7 @@ The keyctl syscall functions are: fails. On success, the resulting key ID will be returned. - (*) Read the payload data from a key: + * Read the payload data from a key:: long keyctl(KEYCTL_READ, key_serial_t keyring, char *buffer, size_t buflen); @@ -650,7 +645,7 @@ The keyctl syscall functions are: available rather than the amount copied. - (*) Instantiate a partially constructed key. + * Instantiate a partially constructed key:: long keyctl(KEYCTL_INSTANTIATE, key_serial_t key, const void *payload, size_t plen, @@ -677,7 +672,7 @@ The keyctl syscall functions are: array instead of a single buffer. - (*) Negatively instantiate a partially constructed key. + * Negatively instantiate a partially constructed key:: long keyctl(KEYCTL_NEGATE, key_serial_t key, unsigned timeout, key_serial_t keyring); @@ -700,12 +695,12 @@ The keyctl syscall functions are: as rejecting the key with ENOKEY as the error code. - (*) Set the default request-key destination keyring. + * Set the default request-key destination keyring:: long keyctl(KEYCTL_SET_REQKEY_KEYRING, int reqkey_defl); This sets the default keyring to which implicitly requested keys will be - attached for this thread. reqkey_defl should be one of these constants: + attached for this thread. reqkey_defl should be one of these constants:: CONSTANT VALUE NEW DEFAULT KEYRING ====================================== ====== ======================= @@ -731,7 +726,7 @@ The keyctl syscall functions are: there is one, otherwise the user default session keyring. - (*) Set the timeout on a key. + * Set the timeout on a key:: long keyctl(KEYCTL_SET_TIMEOUT, key_serial_t key, unsigned timeout); @@ -744,7 +739,7 @@ The keyctl syscall functions are: or expired keys. - (*) Assume the authority granted to instantiate a key + * Assume the authority granted to instantiate a key:: long keyctl(KEYCTL_ASSUME_AUTHORITY, key_serial_t key); @@ -766,7 +761,7 @@ The keyctl syscall functions are: The assumed authoritative key is inherited across fork and exec. - (*) Get the LSM security context attached to a key. + * Get the LSM security context attached to a key:: long keyctl(KEYCTL_GET_SECURITY, key_serial_t key, char *buffer, size_t buflen) @@ -787,7 +782,7 @@ The keyctl syscall functions are: successful. - (*) Install the calling process's session keyring on its parent. + * Install the calling process's session keyring on its parent:: long keyctl(KEYCTL_SESSION_TO_PARENT); @@ -807,7 +802,7 @@ The keyctl syscall functions are: kernel and resumes executing userspace. - (*) Invalidate a key. + * Invalidate a key:: long keyctl(KEYCTL_INVALIDATE, key_serial_t key); @@ -823,20 +818,19 @@ The keyctl syscall functions are: A process must have search permission on the key for this function to be successful. - (*) Compute a Diffie-Hellman shared secret or public key + * Compute a Diffie-Hellman shared secret or public key:: - long keyctl(KEYCTL_DH_COMPUTE, struct keyctl_dh_params *params, - char *buffer, size_t buflen, - struct keyctl_kdf_params *kdf); + long keyctl(KEYCTL_DH_COMPUTE, struct keyctl_dh_params *params, + char *buffer, size_t buflen, struct keyctl_kdf_params *kdf); - The params struct contains serial numbers for three keys: + The params struct contains serial numbers for three keys:: - The prime, p, known to both parties - The local private key - The base integer, which is either a shared generator or the remote public key - The value computed is: + The value computed is:: result = base ^ private (mod prime) @@ -858,12 +852,12 @@ The keyctl syscall functions are: of the KDF is returned to the caller. The KDF is characterized with struct keyctl_kdf_params as follows: - - char *hashname specifies the NUL terminated string identifying + - ``char *hashname`` specifies the NUL terminated string identifying the hash used from the kernel crypto API and applied for the KDF operation. The KDF implemenation complies with SP800-56A as well as with SP800-108 (the counter KDF). - - char *otherinfo specifies the OtherInfo data as documented in + - ``char *otherinfo`` specifies the OtherInfo data as documented in SP800-56A section 5.8.1.2. The length of the buffer is given with otherinfolen. The format of OtherInfo is defined by the caller. The otherinfo pointer may be NULL if no OtherInfo shall be used. @@ -875,10 +869,10 @@ The keyctl syscall functions are: and either the buffer length or the OtherInfo length exceeds the allowed length. - (*) Restrict keyring linkage + * Restrict keyring linkage:: - long keyctl(KEYCTL_RESTRICT_KEYRING, key_serial_t keyring, - const char *type, const char *restriction); + long keyctl(KEYCTL_RESTRICT_KEYRING, key_serial_t keyring, + const char *type, const char *restriction); An existing keyring can restrict linkage of additional keys by evaluating the contents of the key according to a restriction scheme. @@ -900,8 +894,7 @@ The keyctl syscall functions are: To apply a keyring restriction the process must have Set Attribute permission and the keyring must not be previously restricted. -=============== -KERNEL SERVICES +Kernel Services =============== The kernel services for key management are fairly simple to deal with. They can @@ -915,29 +908,29 @@ call, and the key released upon close. How to deal with conflicting keys due to two different users opening the same file is left to the filesystem author to solve. -To access the key manager, the following header must be #included: +To access the key manager, the following header must be #included:: <linux/key.h> Specific key types should have a header file under include/keys/ that should be -used to access that type. For keys of type "user", for example, that would be: +used to access that type. For keys of type "user", for example, that would be:: <keys/user-type.h> Note that there are two different types of pointers to keys that may be encountered: - (*) struct key * + * struct key * This simply points to the key structure itself. Key structures will be at least four-byte aligned. - (*) key_ref_t + * key_ref_t - This is equivalent to a struct key *, but the least significant bit is set + This is equivalent to a ``struct key *``, but the least significant bit is set if the caller "possesses" the key. By "possession" it is meant that the calling processes has a searchable link to the key from one of its - keyrings. There are three functions for dealing with these: + keyrings. There are three functions for dealing with these:: key_ref_t make_key_ref(const struct key *key, bool possession); @@ -955,7 +948,7 @@ When accessing a key's payload contents, certain precautions must be taken to prevent access vs modification races. See the section "Notes on accessing payload contents" for more information. -(*) To search for a key, call: + * To search for a key, call:: struct key *request_key(const struct key_type *type, const char *description, @@ -977,7 +970,7 @@ payload contents" for more information. See also Documentation/security/keys-request-key.txt. -(*) To search for a key, passing auxiliary data to the upcaller, call: + * To search for a key, passing auxiliary data to the upcaller, call:: struct key *request_key_with_auxdata(const struct key_type *type, const char *description, @@ -990,14 +983,14 @@ payload contents" for more information. is a blob of length callout_len, if given (the length may be 0). -(*) A key can be requested asynchronously by calling one of: + * A key can be requested asynchronously by calling one of:: struct key *request_key_async(const struct key_type *type, const char *description, const void *callout_info, size_t callout_len); - or: + or:: struct key *request_key_async_with_auxdata(const struct key_type *type, const char *description, @@ -1010,7 +1003,7 @@ payload contents" for more information. These two functions return with the key potentially still under construction. To wait for construction completion, the following should be - called: + called:: int wait_for_key_construction(struct key *key, bool intr); @@ -1022,11 +1015,11 @@ payload contents" for more information. case error ERESTARTSYS will be returned. -(*) When it is no longer required, the key should be released using: + * When it is no longer required, the key should be released using:: void key_put(struct key *key); - Or: + Or:: void key_ref_put(key_ref_t key_ref); @@ -1034,8 +1027,8 @@ payload contents" for more information. the argument will not be parsed. -(*) Extra references can be made to a key by calling one of the following - functions: + * Extra references can be made to a key by calling one of the following + functions:: struct key *__key_get(struct key *key); struct key *key_get(struct key *key); @@ -1047,7 +1040,7 @@ payload contents" for more information. then the key will not be dereferenced and no increment will take place. -(*) A key's serial number can be obtained by calling: + * A key's serial number can be obtained by calling:: key_serial_t key_serial(struct key *key); @@ -1055,7 +1048,7 @@ payload contents" for more information. latter case without parsing the argument). -(*) If a keyring was found in the search, this can be further searched by: + * If a keyring was found in the search, this can be further searched by:: key_ref_t keyring_search(key_ref_t keyring_ref, const struct key_type *type, @@ -1070,7 +1063,7 @@ payload contents" for more information. reference pointer if successful. -(*) A keyring can be created by: + * A keyring can be created by:: struct key *keyring_alloc(const char *description, uid_t uid, gid_t gid, const struct cred *cred, @@ -1109,7 +1102,7 @@ payload contents" for more information. -EPERM to in this case. -(*) To check the validity of a key, this function can be called: + * To check the validity of a key, this function can be called:: int validate_key(struct key *key); @@ -1119,7 +1112,7 @@ payload contents" for more information. returned (in the latter case without parsing the argument). -(*) To register a key type, the following function should be called: + * To register a key type, the following function should be called:: int register_key_type(struct key_type *type); @@ -1127,13 +1120,13 @@ payload contents" for more information. present. -(*) To unregister a key type, call: + * To unregister a key type, call:: void unregister_key_type(struct key_type *type); Under some circumstances, it may be desirable to deal with a bundle of keys. -The facility provides access to the keyring type for managing such a bundle: +The facility provides access to the keyring type for managing such a bundle:: struct key_type key_type_keyring; @@ -1143,8 +1136,7 @@ with keyring_search(). Note that it is not possible to use request_key() to search a specific keyring, so using keyrings in this way is of limited utility. -=================================== -NOTES ON ACCESSING PAYLOAD CONTENTS +Notes On Accessing Payload Contents =================================== The simplest payload is just data stored in key->payload directly. In this @@ -1154,31 +1146,31 @@ More complex payload contents must be allocated and pointers to them set in the key->payload.data[] array. One of the following ways must be selected to access the data: - (1) Unmodifiable key type. + 1) Unmodifiable key type. If the key type does not have a modify method, then the key's payload can be accessed without any form of locking, provided that it's known to be instantiated (uninstantiated keys cannot be "found"). - (2) The key's semaphore. + 2) The key's semaphore. The semaphore could be used to govern access to the payload and to control the payload pointer. It must be write-locked for modifications and would have to be read-locked for general access. The disadvantage of doing this is that the accessor may be required to sleep. - (3) RCU. + 3) RCU. RCU must be used when the semaphore isn't already held; if the semaphore is held then the contents can't change under you unexpectedly as the semaphore must still be used to serialise modifications to the key. The key management code takes care of this for the key type. - However, this means using: + However, this means using:: rcu_read_lock() ... rcu_dereference() ... rcu_read_unlock() - to read the pointer, and: + to read the pointer, and:: rcu_dereference() ... rcu_assign_pointer() ... call_rcu() @@ -1194,11 +1186,11 @@ access the data: usage. This is called key->payload.rcu_data0. The following accessors wrap the RCU calls to this element: - (a) Set or change the first payload pointer: + a) Set or change the first payload pointer:: rcu_assign_keypointer(struct key *key, void *data); - (b) Read the first payload pointer with the key semaphore held: + b) Read the first payload pointer with the key semaphore held:: [const] void *dereference_key_locked([const] struct key *key); @@ -1206,39 +1198,38 @@ access the data: parameter. Static analysis will give an error if it things the lock isn't held. - (c) Read the first payload pointer with the RCU read lock held: + c) Read the first payload pointer with the RCU read lock held:: const void *dereference_key_rcu(const struct key *key); -=================== -DEFINING A KEY TYPE +Defining a Key Type =================== A kernel service may want to define its own key type. For instance, an AFS filesystem might want to define a Kerberos 5 ticket key type. To do this, it author fills in a key_type struct and registers it with the system. -Source files that implement key types should include the following header file: +Source files that implement key types should include the following header file:: <linux/key-type.h> The structure has a number of fields, some of which are mandatory: - (*) const char *name + * ``const char *name`` The name of the key type. This is used to translate a key type name supplied by userspace into a pointer to the structure. - (*) size_t def_datalen + * ``size_t def_datalen`` This is optional - it supplies the default payload data length as contributed to the quota. If the key type's payload is always or almost always the same size, then this is a more efficient way to do things. The data length (and quota) on a particular key can always be changed - during instantiation or update by calling: + during instantiation or update by calling:: int key_payload_reserve(struct key *key, size_t datalen); @@ -1246,18 +1237,18 @@ The structure has a number of fields, some of which are mandatory: viable. - (*) int (*vet_description)(const char *description); + * ``int (*vet_description)(const char *description);`` This optional method is called to vet a key description. If the key type doesn't approve of the key description, it may return an error, otherwise it should return 0. - (*) int (*preparse)(struct key_preparsed_payload *prep); + * ``int (*preparse)(struct key_preparsed_payload *prep);`` This optional method permits the key type to attempt to parse payload before a key is created (add key) or the key semaphore is taken (update or - instantiate key). The structure pointed to by prep looks like: + instantiate key). The structure pointed to by prep looks like:: struct key_preparsed_payload { char *description; @@ -1285,7 +1276,7 @@ The structure has a number of fields, some of which are mandatory: otherwise. - (*) void (*free_preparse)(struct key_preparsed_payload *prep); + * ``void (*free_preparse)(struct key_preparsed_payload *prep);`` This method is only required if the preparse() method is provided, otherwise it is unused. It cleans up anything attached to the description @@ -1294,7 +1285,7 @@ The structure has a number of fields, some of which are mandatory: successfully, even if instantiate() or update() succeed. - (*) int (*instantiate)(struct key *key, struct key_preparsed_payload *prep); + * ``int (*instantiate)(struct key *key, struct key_preparsed_payload *prep);`` This method is called to attach a payload to a key during construction. The payload attached need not bear any relation to the data passed to this @@ -1318,7 +1309,7 @@ The structure has a number of fields, some of which are mandatory: free_preparse method doesn't release the data. - (*) int (*update)(struct key *key, const void *data, size_t datalen); + * ``int (*update)(struct key *key, const void *data, size_t datalen);`` If this type of key can be updated, then this method should be provided. It is called to update a key's payload from the blob of data provided. @@ -1343,10 +1334,10 @@ The structure has a number of fields, some of which are mandatory: It is safe to sleep in this method. - (*) int (*match_preparse)(struct key_match_data *match_data); + * ``int (*match_preparse)(struct key_match_data *match_data);`` This method is optional. It is called when a key search is about to be - performed. It is given the following structure: + performed. It is given the following structure:: struct key_match_data { bool (*cmp)(const struct key *key, @@ -1357,23 +1348,23 @@ The structure has a number of fields, some of which are mandatory: }; On entry, raw_data will be pointing to the criteria to be used in matching - a key by the caller and should not be modified. (*cmp)() will be pointing + a key by the caller and should not be modified. ``(*cmp)()`` will be pointing to the default matcher function (which does an exact description match against raw_data) and lookup_type will be set to indicate a direct lookup. The following lookup_type values are available: - [*] KEYRING_SEARCH_LOOKUP_DIRECT - A direct lookup hashes the type and + * KEYRING_SEARCH_LOOKUP_DIRECT - A direct lookup hashes the type and description to narrow down the search to a small number of keys. - [*] KEYRING_SEARCH_LOOKUP_ITERATE - An iterative lookup walks all the + * KEYRING_SEARCH_LOOKUP_ITERATE - An iterative lookup walks all the keys in the keyring until one is matched. This must be used for any search that's not doing a simple direct match on the key description. The method may set cmp to point to a function of its choice that does some other form of match, may set lookup_type to KEYRING_SEARCH_LOOKUP_ITERATE - and may attach something to the preparsed pointer for use by (*cmp)(). - (*cmp)() should return true if a key matches and false otherwise. + and may attach something to the preparsed pointer for use by ``(*cmp)()``. + ``(*cmp)()`` should return true if a key matches and false otherwise. If preparsed is set, it may be necessary to use the match_free() method to clean it up. @@ -1381,20 +1372,20 @@ The structure has a number of fields, some of which are mandatory: The method should return 0 if successful or a negative error code otherwise. - It is permitted to sleep in this method, but (*cmp)() may not sleep as + It is permitted to sleep in this method, but ``(*cmp)()`` may not sleep as locks will be held over it. If match_preparse() is not provided, keys of this type will be matched exactly by their description. - (*) void (*match_free)(struct key_match_data *match_data); + * ``void (*match_free)(struct key_match_data *match_data);`` This method is optional. If given, it called to clean up match_data->preparsed after a successful call to match_preparse(). - (*) void (*revoke)(struct key *key); + * ``void (*revoke)(struct key *key);`` This method is optional. It is called to discard part of the payload data upon a key being revoked. The caller will have the key semaphore @@ -1404,7 +1395,7 @@ The structure has a number of fields, some of which are mandatory: a deadlock against the key semaphore. - (*) void (*destroy)(struct key *key); + * ``void (*destroy)(struct key *key);`` This method is optional. It is called to discard the payload data on a key when it is being destroyed. @@ -1416,7 +1407,7 @@ The structure has a number of fields, some of which are mandatory: It is not safe to sleep in this method; the caller may hold spinlocks. - (*) void (*describe)(const struct key *key, struct seq_file *p); + * ``void (*describe)(const struct key *key, struct seq_file *p);`` This method is optional. It is called during /proc/keys reading to summarise a key's description and payload in text form. @@ -1432,7 +1423,7 @@ The structure has a number of fields, some of which are mandatory: caller. - (*) long (*read)(const struct key *key, char __user *buffer, size_t buflen); + * ``long (*read)(const struct key *key, char __user *buffer, size_t buflen);`` This method is optional. It is called by KEYCTL_READ to translate the key's payload into something a blob of data for userspace to deal with. @@ -1448,8 +1439,7 @@ The structure has a number of fields, some of which are mandatory: as might happen when the userspace buffer is accessed. - (*) int (*request_key)(struct key_construction *cons, const char *op, - void *aux); + * ``int (*request_key)(struct key_construction *cons, const char *op, void *aux);`` This method is optional. If provided, request_key() and friends will invoke this function rather than upcalling to /sbin/request-key to operate @@ -1463,7 +1453,7 @@ The structure has a number of fields, some of which are mandatory: This method is permitted to return before the upcall is complete, but the following function must be called under all circumstances to complete the instantiation process, whether or not it succeeds, whether or not there's - an error: + an error:: void complete_request_key(struct key_construction *cons, int error); @@ -1479,16 +1469,16 @@ The structure has a number of fields, some of which are mandatory: The key under construction and the authorisation key can be found in the key_construction struct pointed to by cons: - (*) struct key *key; + * ``struct key *key;`` The key under construction. - (*) struct key *authkey; + * ``struct key *authkey;`` The authorisation key. - (*) struct key_restriction *(*lookup_restriction)(const char *params); + * ``struct key_restriction *(*lookup_restriction)(const char *params);`` This optional method is used to enable userspace configuration of keyring restrictions. The restriction parameter string (not including the key type @@ -1497,12 +1487,11 @@ The structure has a number of fields, some of which are mandatory: attempted key link operation. If there is no match, -EINVAL is returned. -============================ -REQUEST-KEY CALLBACK SERVICE +Request-Key Callback Service ============================ To create a new key, the kernel will attempt to execute the following command -line: +line:: /sbin/request-key create <key> <uid> <gid> \ <threadring> <processring> <sessionring> <callout_info> @@ -1511,10 +1500,10 @@ line: keyrings from the process that caused the search to be issued. These are included for two reasons: - (1) There may be an authentication token in one of the keyrings that is + 1 There may be an authentication token in one of the keyrings that is required to obtain the key, eg: a Kerberos Ticket-Granting Ticket. - (2) The new key should probably be cached in one of these rings. + 2 The new key should probably be cached in one of these rings. This program should set it UID and GID to those specified before attempting to access any more keys. It may then look around for a user specific process to @@ -1539,7 +1528,7 @@ instead. Similarly, the kernel may attempt to update an expired or a soon to expire key -by executing: +by executing:: /sbin/request-key update <key> <uid> <gid> \ <threadring> <processring> <sessionring> @@ -1548,8 +1537,7 @@ In this case, the program isn't required to actually attach the key to a ring; the rings are provided for reference. -================== -GARBAGE COLLECTION +Garbage Collection ================== Dead keys (for which the type has been removed) will be automatically unlinked @@ -1557,6 +1545,6 @@ from those keyrings that point to them and deleted as soon as possible by a background garbage collector. Similarly, revoked and expired keys will be garbage collected, but only after a -certain amount of time has passed. This time is set as a number of seconds in: +certain amount of time has passed. This time is set as a number of seconds in:: /proc/sys/kernel/keys/gc_delay diff --git a/Documentation/security/keys-ecryptfs.txt b/Documentation/security/keys/ecryptfs.rst index c3bbeba63562..4920f3a8ea75 100644 --- a/Documentation/security/keys-ecryptfs.txt +++ b/Documentation/security/keys/ecryptfs.rst @@ -1,4 +1,6 @@ - Encrypted keys for the eCryptfs filesystem +========================================== +Encrypted keys for the eCryptfs filesystem +========================================== ECryptfs is a stacked filesystem which transparently encrypts and decrypts each file using a randomly generated File Encryption Key (FEK). @@ -35,20 +37,23 @@ controlled environment. Another advantage is that the key is not exposed to threats of malicious software, because it is available in clear form only at kernel level. -Usage: +Usage:: + keyctl add encrypted name "new ecryptfs key-type:master-key-name keylen" ring keyctl add encrypted name "load hex_blob" ring keyctl update keyid "update key-type:master-key-name" -name:= '<16 hexadecimal characters>' -key-type:= 'trusted' | 'user' -keylen:= 64 +Where:: + + name:= '<16 hexadecimal characters>' + key-type:= 'trusted' | 'user' + keylen:= 64 Example of encrypted key usage with the eCryptfs filesystem: Create an encrypted key "1000100010001000" of length 64 bytes with format -'ecryptfs' and save it using a previously loaded user key "test": +'ecryptfs' and save it using a previously loaded user key "test":: $ keyctl add encrypted 1000100010001000 "new ecryptfs user:test 64" @u 19184530 @@ -62,7 +67,7 @@ Create an encrypted key "1000100010001000" of length 64 bytes with format $ keyctl pipe 19184530 > ecryptfs.blob Mount an eCryptfs filesystem using the created encrypted key "1000100010001000" -into the '/secret' directory: +into the '/secret' directory:: $ mount -i -t ecryptfs -oecryptfs_sig=1000100010001000,\ ecryptfs_cipher=aes,ecryptfs_key_bytes=32 /secret /secret diff --git a/Documentation/security/keys/index.rst b/Documentation/security/keys/index.rst new file mode 100644 index 000000000000..647d58f2588e --- /dev/null +++ b/Documentation/security/keys/index.rst @@ -0,0 +1,11 @@ +=========== +Kernel Keys +=========== + +.. toctree:: + :maxdepth: 1 + + core + ecryptfs + request-key + trusted-encrypted diff --git a/Documentation/security/keys-request-key.txt b/Documentation/security/keys/request-key.rst index 51987bfecfed..aba32784174c 100644 --- a/Documentation/security/keys-request-key.txt +++ b/Documentation/security/keys/request-key.rst @@ -1,19 +1,19 @@ - =================== - KEY REQUEST SERVICE - =================== +=================== +Key Request Service +=================== The key request service is part of the key retention service (refer to Documentation/security/keys.txt). This document explains more fully how the requesting algorithm works. The process starts by either the kernel requesting a service by calling -request_key*(): +``request_key*()``:: struct key *request_key(const struct key_type *type, const char *description, const char *callout_info); -or: +or:: struct key *request_key_with_auxdata(const struct key_type *type, const char *description, @@ -21,14 +21,14 @@ or: size_t callout_len, void *aux); -or: +or:: struct key *request_key_async(const struct key_type *type, const char *description, const char *callout_info, size_t callout_len); -or: +or:: struct key *request_key_async_with_auxdata(const struct key_type *type, const char *description, @@ -36,7 +36,7 @@ or: size_t callout_len, void *aux); -Or by userspace invoking the request_key system call: +Or by userspace invoking the request_key system call:: key_serial_t request_key(const char *type, const char *description, @@ -67,38 +67,37 @@ own upcall mechanisms. If they do, then those should be substituted for the forking and execution of /sbin/request-key. -=========== -THE PROCESS +The Process =========== A request proceeds in the following manner: - (1) Process A calls request_key() [the userspace syscall calls the kernel + 1) Process A calls request_key() [the userspace syscall calls the kernel interface]. - (2) request_key() searches the process's subscribed keyrings to see if there's + 2) request_key() searches the process's subscribed keyrings to see if there's a suitable key there. If there is, it returns the key. If there isn't, and callout_info is not set, an error is returned. Otherwise the process proceeds to the next step. - (3) request_key() sees that A doesn't have the desired key yet, so it creates + 3) request_key() sees that A doesn't have the desired key yet, so it creates two things: - (a) An uninstantiated key U of requested type and description. + a) An uninstantiated key U of requested type and description. - (b) An authorisation key V that refers to key U and notes that process A + b) An authorisation key V that refers to key U and notes that process A is the context in which key U should be instantiated and secured, and from which associated key requests may be satisfied. - (4) request_key() then forks and executes /sbin/request-key with a new session + 4) request_key() then forks and executes /sbin/request-key with a new session keyring that contains a link to auth key V. - (5) /sbin/request-key assumes the authority associated with key U. + 5) /sbin/request-key assumes the authority associated with key U. - (6) /sbin/request-key execs an appropriate program to perform the actual + 6) /sbin/request-key execs an appropriate program to perform the actual instantiation. - (7) The program may want to access another key from A's context (say a + 7) The program may want to access another key from A's context (say a Kerberos TGT key). It just requests the appropriate key, and the keyring search notes that the session keyring has auth key V in its bottom level. @@ -106,15 +105,15 @@ A request proceeds in the following manner: 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 + 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 + 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. + 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 @@ -127,8 +126,7 @@ This is because process A's keyrings can't simply be attached to of them, and (b) it requires the same UID/GID/Groups all the way through. -==================================== -NEGATIVE INSTANTIATION AND REJECTION +Negative Instantiation And Rejection ==================================== Rather than instantiating a key, it is possible for the possessor of an @@ -145,23 +143,22 @@ signal, the key under construction will be automatically negatively instantiated for a short amount of time. -==================== -THE SEARCH ALGORITHM +The Search Algorithm ==================== A search of any particular keyring proceeds in the following fashion: - (1) When the key management code searches for a key (keyring_search_aux) it + 1) When the key management code searches for a key (keyring_search_aux) it firstly calls key_permission(SEARCH) on the keyring it's starting with, if this denies permission, it doesn't search further. - (2) It considers all the non-keyring keys within that keyring and, if any key + 2) It considers all the non-keyring keys within that keyring and, if any key matches the criteria specified, calls key_permission(SEARCH) on it to see if the key is allowed to be found. If it is, that key is returned; if not, the search continues, and the error code is retained if of higher priority than the one currently set. - (3) It then considers all the keyring-type keys in the keyring it's currently + 3) It then considers all the keyring-type keys in the keyring it's currently searching. It calls key_permission(SEARCH) on each keyring, and if this grants permission, it recurses, executing steps (2) and (3) on that keyring. @@ -173,20 +170,20 @@ returned. When search_process_keyrings() is invoked, it performs the following searches until one succeeds: - (1) If extant, the process's thread keyring is searched. + 1) If extant, the process's thread keyring is searched. - (2) If extant, the process's process keyring is searched. + 2) If extant, the process's process keyring is searched. - (3) The process's session keyring is searched. + 3) The process's session keyring is searched. - (4) If the process has assumed the authority associated with a request_key() + 4) If the process has assumed the authority associated with a request_key() authorisation key then: - (a) If extant, the calling process's thread keyring is searched. + a) If extant, the calling process's thread keyring is searched. - (b) If extant, the calling process's process keyring is searched. + b) If extant, the calling process's process keyring is searched. - (c) The calling process's session keyring is searched. + c) The calling process's session keyring is searched. The moment one succeeds, all pending errors are discarded and the found key is returned. @@ -194,7 +191,7 @@ returned. Only if all these fail does the whole thing fail with the highest priority error. Note that several errors may have come from LSM. -The error priority is: +The error priority is:: EKEYREVOKED > EKEYEXPIRED > ENOKEY diff --git a/Documentation/security/keys-trusted-encrypted.txt b/Documentation/security/keys/trusted-encrypted.rst index b20a993a32af..7b503831bdea 100644 --- a/Documentation/security/keys-trusted-encrypted.txt +++ b/Documentation/security/keys/trusted-encrypted.rst @@ -1,4 +1,6 @@ - Trusted and Encrypted Keys +========================== +Trusted and Encrypted Keys +========================== Trusted and Encrypted Keys are two new key types added to the existing kernel key ring service. Both of these new types are variable length symmetric keys, @@ -20,7 +22,8 @@ By default, trusted keys are sealed under the SRK, which has the default authorization value (20 zeros). This can be set at takeownership time with the trouser's utility: "tpm_takeownership -u -z". -Usage: +Usage:: + keyctl add trusted name "new keylen [options]" ring keyctl add trusted name "load hex_blob [pcrlock=pcrnum]" ring keyctl update key "update [options]" @@ -64,19 +67,22 @@ The decrypted portion of encrypted keys can contain either a simple symmetric key or a more complex structure. The format of the more complex structure is application specific, which is identified by 'format'. -Usage: +Usage:: + keyctl add encrypted name "new [format] key-type:master-key-name keylen" ring keyctl add encrypted name "load hex_blob" ring keyctl update keyid "update key-type:master-key-name" -format:= 'default | ecryptfs' -key-type:= 'trusted' | 'user' +Where:: + + format:= 'default | ecryptfs' + key-type:= 'trusted' | 'user' Examples of trusted and encrypted key usage: -Create and save a trusted key named "kmk" of length 32 bytes: +Create and save a trusted key named "kmk" of length 32 bytes:: $ keyctl add trusted kmk "new 32" @u 440502848 @@ -99,7 +105,7 @@ Create and save a trusted key named "kmk" of length 32 bytes: $ keyctl pipe 440502848 > kmk.blob -Load a trusted key from the saved blob: +Load a trusted key from the saved blob:: $ keyctl add trusted kmk "load `cat kmk.blob`" @u 268728824 @@ -114,7 +120,7 @@ Load a trusted key from the saved blob: f1f8fff03ad0acb083725535636addb08d73dedb9832da198081e5deae84bfaf0409c22b e4a8aea2b607ec96931e6f4d4fe563ba -Reseal a trusted key under new pcr values: +Reseal a trusted key under new pcr values:: $ keyctl update 268728824 "update pcrinfo=`cat pcr.blob`" $ keyctl print 268728824 @@ -135,11 +141,13 @@ compromised by a user level problem, and when sealed to specific boot PCR values, protects against boot and offline attacks. Create and save an encrypted key "evm" using the above trusted key "kmk": -option 1: omitting 'format' +option 1: omitting 'format':: + $ keyctl add encrypted evm "new trusted:kmk 32" @u 159771175 -option 2: explicitly defining 'format' as 'default' +option 2: explicitly defining 'format' as 'default':: + $ keyctl add encrypted evm "new default trusted:kmk 32" @u 159771175 @@ -150,7 +158,7 @@ option 2: explicitly defining 'format' as 'default' $ keyctl pipe 159771175 > evm.blob -Load an encrypted key "evm" from saved blob: +Load an encrypted key "evm" from saved blob:: $ keyctl add encrypted evm "load `cat evm.blob`" @u 831684262 @@ -164,4 +172,4 @@ Other uses for trusted and encrypted keys, such as for disk and file encryption are anticipated. In particular the new format 'ecryptfs' has been defined in in order to use encrypted keys to mount an eCryptfs filesystem. More details about the usage can be found in the file -'Documentation/security/keys-ecryptfs.txt'. +``Documentation/security/keys-ecryptfs.txt``. diff --git a/Documentation/security/self-protection.txt b/Documentation/security/self-protection.rst index 141acfebe6ef..60c8bd8b77bf 100644 --- a/Documentation/security/self-protection.txt +++ b/Documentation/security/self-protection.rst @@ -1,4 +1,6 @@ -# Kernel Self-Protection +====================== +Kernel Self-Protection +====================== Kernel self-protection is the design and implementation of systems and structures within the Linux kernel to protect against security flaws in @@ -26,7 +28,8 @@ mentioning them, since these aspects need to be explored, dealt with, and/or accepted. -## Attack Surface Reduction +Attack Surface Reduction +======================== The most fundamental defense against security exploits is to reduce the areas of the kernel that can be used to redirect execution. This ranges @@ -34,13 +37,15 @@ from limiting the exposed APIs available to userspace, making in-kernel APIs hard to use incorrectly, minimizing the areas of writable kernel memory, etc. -### Strict kernel memory permissions +Strict kernel memory permissions +-------------------------------- When all of kernel memory is writable, it becomes trivial for attacks to redirect execution flow. To reduce the availability of these targets the kernel needs to protect its memory with a tight set of permissions. -#### Executable code and read-only data must not be writable +Executable code and read-only data must not be writable +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Any areas of the kernel with executable memory must not be writable. While this obviously includes the kernel text itself, we must consider @@ -51,18 +56,19 @@ kernel, they are implemented in a way where the memory is temporarily made writable during the update, and then returned to the original permissions.) -In support of this are CONFIG_STRICT_KERNEL_RWX and -CONFIG_STRICT_MODULE_RWX, which seek to make sure that code is not +In support of this are ``CONFIG_STRICT_KERNEL_RWX`` and +``CONFIG_STRICT_MODULE_RWX``, which seek to make sure that code is not writable, data is not executable, and read-only data is neither writable nor executable. Most architectures have these options on by default and not user selectable. For some architectures like arm that wish to have these be selectable, the architecture Kconfig can select ARCH_OPTIONAL_KERNEL_RWX to enable -a Kconfig prompt. CONFIG_ARCH_OPTIONAL_KERNEL_RWX_DEFAULT determines +a Kconfig prompt. ``CONFIG_ARCH_OPTIONAL_KERNEL_RWX_DEFAULT`` determines the default setting when ARCH_OPTIONAL_KERNEL_RWX is enabled. -#### Function pointers and sensitive variables must not be writable +Function pointers and sensitive variables must not be writable +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Vast areas of kernel memory contain function pointers that are looked up by the kernel and used to continue execution (e.g. descriptor/vector @@ -74,8 +80,8 @@ so that they live in the .rodata section instead of the .data section of the kernel, gaining the protection of the kernel's strict memory permissions as described above. -For variables that are initialized once at __init time, these can -be marked with the (new and under development) __ro_after_init +For variables that are initialized once at ``__init`` time, these can +be marked with the (new and under development) ``__ro_after_init`` attribute. What remains are variables that are updated rarely (e.g. GDT). These @@ -85,7 +91,8 @@ of their lifetime read-only. (For example, when being updated, only the CPU thread performing the update would be given uninterruptible write access to the memory.) -#### Segregation of kernel memory from userspace memory +Segregation of kernel memory from userspace memory +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The kernel must never execute userspace memory. The kernel must also never access userspace memory without explicit expectation to do so. These @@ -95,10 +102,11 @@ By blocking userspace memory in this way, execution and data parsing cannot be passed to trivially-controlled userspace memory, forcing attacks to operate entirely in kernel memory. -### Reduced access to syscalls +Reduced access to syscalls +-------------------------- One trivial way to eliminate many syscalls for 64-bit systems is building -without CONFIG_COMPAT. However, this is rarely a feasible scenario. +without ``CONFIG_COMPAT``. However, this is rarely a feasible scenario. The "seccomp" system provides an opt-in feature made available to userspace, which provides a way to reduce the number of kernel entry @@ -112,7 +120,8 @@ to trusted processes. This would keep the scope of kernel entry points restricted to the more regular set of normally available to unprivileged userspace. -### Restricting access to kernel modules +Restricting access to kernel modules +------------------------------------ The kernel should never allow an unprivileged user the ability to load specific kernel modules, since that would provide a facility to @@ -127,11 +136,12 @@ for debate in some scenarios.) To protect against even privileged users, systems may need to either disable module loading entirely (e.g. monolithic kernel builds or modules_disabled sysctl), or provide signed modules (e.g. -CONFIG_MODULE_SIG_FORCE, or dm-crypt with LoadPin), to keep from having +``CONFIG_MODULE_SIG_FORCE``, or dm-crypt with LoadPin), to keep from having root load arbitrary kernel code via the module loader interface. -## Memory integrity +Memory integrity +================ There are many memory structures in the kernel that are regularly abused to gain execution control during an attack, By far the most commonly @@ -139,16 +149,18 @@ understood is that of the stack buffer overflow in which the return address stored on the stack is overwritten. Many other examples of this kind of attack exist, and protections exist to defend against them. -### Stack buffer overflow +Stack buffer overflow +--------------------- The classic stack buffer overflow involves writing past the expected end of a variable stored on the stack, ultimately writing a controlled value to the stack frame's stored return address. The most widely used defense is the presence of a stack canary between the stack variables and the -return address (CONFIG_CC_STACKPROTECTOR), which is verified just before +return address (``CONFIG_CC_STACKPROTECTOR``), which is verified just before the function returns. Other defenses include things like shadow stacks. -### Stack depth overflow +Stack depth overflow +-------------------- A less well understood attack is using a bug that triggers the kernel to consume stack memory with deep function calls or large stack @@ -158,27 +170,31 @@ important changes need to be made for better protections: moving the sensitive thread_info structure elsewhere, and adding a faulting memory hole at the bottom of the stack to catch these overflows. -### Heap memory integrity +Heap memory integrity +--------------------- The structures used to track heap free lists can be sanity-checked during allocation and freeing to make sure they aren't being used to manipulate other memory areas. -### Counter integrity +Counter integrity +----------------- Many places in the kernel use atomic counters to track object references or perform similar lifetime management. When these counters can be made to wrap (over or under) this traditionally exposes a use-after-free flaw. By trapping atomic wrapping, this class of bug vanishes. -### Size calculation overflow detection +Size calculation overflow detection +----------------------------------- Similar to counter overflow, integer overflows (usually size calculations) need to be detected at runtime to kill this class of bug, which traditionally leads to being able to write past the end of kernel buffers. -## Statistical defenses +Probabilistic defenses +====================== While many protections can be considered deterministic (e.g. read-only memory cannot be written to), some protections provide only statistical @@ -186,7 +202,8 @@ defense, in that an attack must gather enough information about a running system to overcome the defense. While not perfect, these do provide meaningful defenses. -### Canaries, blinding, and other secrets +Canaries, blinding, and other secrets +------------------------------------- It should be noted that things like the stack canary discussed earlier are technically statistical defenses, since they rely on a secret value, @@ -201,7 +218,8 @@ It is critical that the secret values used must be separate (e.g. different canary per stack) and high entropy (e.g. is the RNG actually working?) in order to maximize their success. -### Kernel Address Space Layout Randomization (KASLR) +Kernel Address Space Layout Randomization (KASLR) +------------------------------------------------- Since the location of kernel memory is almost always instrumental in mounting a successful attack, making the location non-deterministic @@ -209,22 +227,25 @@ raises the difficulty of an exploit. (Note that this in turn makes the value of information exposures higher, since they may be used to discover desired memory locations.) -#### Text and module base +Text and module base +~~~~~~~~~~~~~~~~~~~~ By relocating the physical and virtual base address of the kernel at -boot-time (CONFIG_RANDOMIZE_BASE), attacks needing kernel code will be +boot-time (``CONFIG_RANDOMIZE_BASE``), attacks needing kernel code will be frustrated. Additionally, offsetting the module loading base address means that even systems that load the same set of modules in the same order every boot will not share a common base address with the rest of the kernel text. -#### Stack base +Stack base +~~~~~~~~~~ If the base address of the kernel stack is not the same between processes, or even not the same between syscalls, targets on or beyond the stack become more difficult to locate. -#### Dynamic memory base +Dynamic memory base +~~~~~~~~~~~~~~~~~~~ Much of the kernel's dynamic memory (e.g. kmalloc, vmalloc, etc) ends up being relatively deterministic in layout due to the order of early-boot @@ -232,7 +253,8 @@ initializations. If the base address of these areas is not the same between boots, targeting them is frustrated, requiring an information exposure specific to the region. -#### Structure layout +Structure layout +~~~~~~~~~~~~~~~~ By performing a per-build randomization of the layout of sensitive structures, attacks must either be tuned to known kernel builds or expose @@ -240,26 +262,30 @@ enough kernel memory to determine structure layouts before manipulating them. -## Preventing Information Exposures +Preventing Information Exposures +================================ Since the locations of sensitive structures are the primary target for attacks, it is important to defend against exposure of both kernel memory addresses and kernel memory contents (since they may contain kernel addresses or other sensitive things like canary values). -### Unique identifiers +Unique identifiers +------------------ Kernel memory addresses must never be used as identifiers exposed to userspace. Instead, use an atomic counter, an idr, or similar unique identifier. -### Memory initialization +Memory initialization +--------------------- Memory copied to userspace must always be fully initialized. If not explicitly memset(), this will require changes to the compiler to make sure structure holes are cleared. -### Memory poisoning +Memory poisoning +---------------- When releasing memory, it is best to poison the contents (clear stack on syscall return, wipe heap memory on a free), to avoid reuse attacks that @@ -267,9 +293,10 @@ rely on the old contents of memory. This frustrates many uninitialized variable attacks, stack content exposures, heap content exposures, and use-after-free attacks. -### Destination tracking +Destination tracking +-------------------- To help kill classes of bugs that result in kernel addresses being written to userspace, the destination of writes needs to be tracked. If -the buffer is destined for userspace (e.g. seq_file backed /proc files), +the buffer is destined for userspace (e.g. seq_file backed ``/proc`` files), it should automatically censor sensitive values. diff --git a/Documentation/security/tomoyo.txt b/Documentation/security/tomoyo.txt deleted file mode 100644 index 200a2d37cbc8..000000000000 --- 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. |