keyrings.7: Various reworkings and additions

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

man7/keyrings.7

@@ -13,9 +13,8 @@
 .SH NAME
 keyrings \- in-kernel key management and retention facility
 .SH DESCRIPTION
-The
-.B keyrings
-facility is primarily a way for drivers to retain or cache security data,
+The Linux key-management facility
+is primarily a way for drivers to retain or cache security data,
 authentication keys, encryption keys, and other data in the kernel.
 .P
 System call interfaces are provided so that user-space programs can manage those
@@ -24,114 +23,106 @@ objects and also use the facility for their own purposes.
 A library and some user-space utilities are provided to allow access to the
 facility.
 See
+.BR keyctl (1),
+.BR keyctl (3),
+and
 .BR keyutils (7)
 for more information.
-.P
-This document contains the following sections:
-.P
-.RS
-- Keys.
-.br
-- Key types.
-.br
-- Keyrings.
-.br
-- Anchoring keys.
-.br
-- Possession.
-.br
-- Access rights.
-.br
-- Searching for keys.
-.br
-- On-demand key creation.
-.br
-- Users.
-.br
 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
 .SS Keys
-The facility provides the concept of a '\fBkey\fR', where all of the above
-examples are encapsulated within objects of this type.
-.P
-A 'key' contains the following elements:
-.IP "\fBSerial number\fR"
+A key has the following attributes:
+.TP
+Serial number
 This is a unique integer handle by which a key is referred to in system call
 arguments.
-.IP "\fBType\fR"
-This defines what sort of data can be held in the key,
-how the proposed content of the key will be parsed and
-how the payload will be used.
-.IP
+The serial number is sometimes synonymously referred the key ID.
+Programmatically, key serial numbers are represented using the type
+.IR key_serial_t .
+.TP
+Type
+A key's type defines what sort of data can be held in the key,
+how the proposed content of the key will be parsed,
+and how the payload will be used.
+
 There are a number of general purpose types available, plus some specialist
 types defined by specific drivers.
-.IP "\fBDescription\fR"
-This is a printable string that is used as the search term for the key (in
-conjunction with the type) as well as a display name.
-The description may be partially matched or exactly matched.
-.IP "\fBPayload\fR"
-This is the actual content of a key.
+.TP
+Description (name)
+The key description is a printable string that is used as the search term
+for the key (in conjunction with the key type) as well as a display name.
+During searches, the description may be partially matched or exactly matched.
+.TP
+Payload
+The payload is the actual content of a key.
 This is usually set when a key is created,
 but it is possible for the kernel to upcall to user space to finish the
 instantiation of a key if that key wasn't already known to the kernel
 when it was requested.
-.IP
+(Details can be found in
+.BR request_key (2).)
+
 A key's payload can be read and updated if the key type supports it and if
 suitable permission is granted to the caller.
-.IP "\fBAccess rights\fR"
+.TP
+Access rights
 Much as files do,
 each key has an owning user ID, an owning group ID, and a security label.
 files do.
 They also have a set of permissions,
 though there are more than for a normal UNIX file,
 and there is an additional category beyond the usual user,
-group and other (see below).
-.IP
+group, and other (see below).
+
 Note that keys are quota controlled since they represent unswappable kernel
 memory and the owning user ID specifies whose quota is to be debited.
-.IP "\fBExpiration time\fR"
+.TP
+Expiration time
 Each key can have an expiration time set.
 When that time is reached,
 the key is marked as being expired and accesses to it fail with
 .BR EKEYEXPIRED .
-If not deleted, updated or replaced, after a set amount of time,
-expired keys are
-automatically removed along with all links to them and
-.B ENOKEY
-will be reported.
-.IP "\fBReference count\fR"
+If not deleted, updated, or replaced, after a set amount of time,
+expired keys are automatically removed along with all links to them,
+and attempts to access the key will fail with the error
+.BR ENOKEY .
+.TP
+Reference count
 Each key has a reference count.
-Keys are referenced by keyrings, by current active users
+Keys are referenced by keyrings, by currently active users,
 and by a process's credentials.
 When the reference count reaches zero,
 the key is scheduled for garbage collection.
-.P
-See
-.BR keyctl_describe (3)
-for more information.
 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
 .SS Key types
 The facility provides several basic types of key:
-.IP "\fBkeyring\fR"
+.TP
+.I """keyring"""
 Keys of this type are special.
 The payload consists of a set of links to other
 keys, analogous to a directory holding links to files.
 The main purpose of a keyring is to prevent other keys from
 being garbage collected because nothing refers to them.
-.IP "\fBuser\fR"
+.TP
+.I """user"""
 This is a general purpose key type.
 It may be instantiated with an arbitrary blob of data of up to about 32KB.
 It is kept entirely within kernel memory.
 It may be read and updated by user-space applications
-.IP "\fBbig_key\fR"
-This is similar to \fBuser\fR but it may hold data up to 1MB in size.
+.TP
+.I """big_key"""
+This is similar to the
+.I """user"""
+key type, but it may hold a payload of up to 1MiB in size.
 The data may be stored in the swap space rather than in kernel memory
 if the size exceeds the overhead of doing so
 (a tmpfs file is used, which requires filesystem structures
 to be allocated in the kernel).
-.IP "\fBlogon\fR"
-This is similar to \fBuser\fR but the contents may not be read by
-user-space applications.
-
+.TP
+.I """logon"""
+This is similar to the
+.I """user"""
+key type, but the contents may not be read by user-space applications.
+.PP
 There are more specialized key types available also, but they're not discussed
 here as they're not intended for normal user-space use.
 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
@@ -165,7 +156,7 @@ a particular type and description.
 See
 .BR keyctl_clear (3),
 .BR keyctl_link (3),
-.BR keyctl_search (3)
+.BR keyctl_search (3),
 and
 .BR keyctl_unlink (3)
 for more information.
@@ -223,7 +214,8 @@ for special purposes.
 An example of this is the \fBsystem keyring\fR used for holding
 encryption keys for module signature verification.
 .IP
-These are usually closed to direct alteration by user space.
+These special keyrings  are usually closed to direct alteration
+by user space.
 .P
 See
 .BR thread-keyring (7),
@@ -236,12 +228,13 @@ and
 for more information.
 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
 .SS Possession
-The concept of '\fBpossession\fR' is important to understanding the keyrings
+The concept of possession is important to understanding the keyrings
 security model.
 Whether a thread possesses a key is determined by the following rules:
-.IP (1)
-Any key or keyring that does not grant \fBSearch\fP permission to the caller is
-\fIignored\fP in all the following rules.
+.IP (1) 4
+Any key or keyring that does not grant
+.I search
+permission to the caller is ignored in all the following rules.
 .IP (2)
 A thread \fIpossesses\fR its \fBsession\fR, \fBprocess\fR, and \fBthread\fR
 keyrings directly because those are pointed to by its credentials.
@@ -252,82 +245,98 @@ If any key a keyring links to is itself a keyring, then rule (3) applies
 \fIrecursively\fP.
 .IP (5)
 If a process is upcalled from the kernel to instantiate a key, then it also
-possess's the \fIrequester's\fP keyrings as in rule (1) as if it were the
+possesses the \fIrequester's\fP keyrings as in rule (1) as if it were the
 requester.
 .P
 Note that possession is not a fundamental property of a key,
-but must rather be calculated each time it is needed.
+but must rather be calculated each time the key is needed.
 .P
-Possession is designed to allow setuid programs run from, say, a user's shell
-to access the user's keys.
+Possession is designed to allow set-user-ID programs run from, say
+a user's shell to access the user's keys.
 It also allows the prevention of access to keys
 just on the basis of UID and GID matches.
 .P
 When it creates the session keyring,
 .BR pam_keyinit (8)
-adds a link to the user keyring,
+adds a link to the
+.BR user-keyring (7),
 thus making the user keyring and anything it contains possessed by default.
 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
 .SS Access rights
 Each key has the following security-related attributes:
-.P
-.RS
-- The owning user ID
-.br
-- The ID of a group that is permitted to access the key
-.br
-- A security label
-.br
-- A permissions mask
-.RE
-.P
-The permissions mask is used to govern the following rights:
-.IP \fBView\fR
-If set, the attributes of a key may be read.
-This includes the type,
-description and access rights (excluding the security label).
-.IP \fBRead\fR
-If set, the payload of a key may be read and a list of the serial numbers to
-which a keyring has links may be read.
-.IP \fBWrite\fR
-If set, the payload of a key may be updated, links may be added to or removed
-from a keyring, a keyring may be cleared completely and a key may be revoked.
-.IP \fBSearch\fR
-If set, keyrings and subkeyrings may be searched and keys and keyrings may be
-found by that search.
-.IP \fBLink\fR
-If set, an additional link may be made to a key from a keyring.
-The initial link to a key when it is created doesn't require this permit.
-.IP \fBSetattr\fR
-If set, the ownership details on a key and its security label may be changed,
-its expiration time may be set and it may be revoked.
+.IP * 3
+The owning user ID
+.IP *
+The ID of a group that is permitted to access the key
+.IP *
+A security label
+.IP *
+A permissions mask
 .P
 The permissions mask contains four sets of rights.
 The first three sets are mutually exclusive.
-One and only one will be in force at any one time.
-In order of descending priority:
-.IP \fBUser\fR
-Used if the key's user ID matches the caller's \fBfsuid\fR.
-.IP \fBGroup\fR
-Used if the user ID didn't match and the key's group ID matches the caller's
-\fBfsgid\fR or one of the caller's supplementary group list.
-.IP \fBOther\fR
-Used if neither the key's user ID nor group ID matched.
+One and only one will be in force for a particular access check.
+In order of descending priority, these three sets are:
+.IP \fIuser\fR
+The set specifies the rights granted
+if the key's user ID matches the caller's filesystem user ID.
+.IP \fIgroup\fR
+The set specifies the rights granted
+if the user ID didn't match and the key's group ID matches the caller's
+filesystem GID or one of the caller's supplementary group IDs.
+.IP \fIother\fR
+The set specifies the rights granted
+if neither the key's user ID nor group ID matched.
 .P
 The fourth set of rights is:
-.IP \fBPossessor\fR
-Used if a key is determined to be \fBpossessed\fR by the caller.
+.IP \fIpossessor\fR
+The set specifies the rights granted
+if a key is determined to be possessed by the caller.
 .P
-The complete set of rights for a key is the set union of whichever
-of the first three sets is selected plus the fourth
+The complete set of rights for a key is the union of whichever
+of the first three sets is applicable plus the fourth set
 if the key is possessed.
 .P
-If any right is granted to a thread for a key, then that thread will see the
-key listed in /proc/keys.
+The set of rights that may be granted in each of the four masks
+is as follows:
+.TP
+.I view
+The attributes of the key may be read.
+This includes the type,
+description, and access rights (excluding the security label).
+.TP
+.I read
+For a key: the payload of the key may be read.
+For a keyring: the list of serial numbers (keys) to
+which the keyring has links may be read.
+.TP
+.I write
+The payload of the key may be updated.
+For a keyring, links may be added to or removed from the keyring,
+the keyring may be cleared completely (all links are removed),
+and the key may be revoked.
+.TP
+.I search
+For a key (or a keyring): the key may be found by a search.
+For a keyring: keys and keyrings that are linked to by the
+keyring may be searched.
+.TP
+.I link
+Links may be created from keyrings to the key.
+The initial link to a key that is established when the key is created
+doesn't require this permission.
+.TP
+.I setattr
+The ownership details and security label of the key may be changed,
+the key's expiration time may be set, and the key may be revoked.
+.P
+If any right is granted to a thread for a key,
+then that thread will see the key listed in
+.IR /proc/keys .
 If no rights at all are granted, then that thread
 can't even tell that the key exists.
 .P
-In addition to access rights, any active \fBLinux Security Module\fP may
+In addition to access rights, any active Linux Security Module (LSM) may
 prevent access to a key if its policy so dictates.
 A key may be given a
 security label or other attribute by the LSM which can be retrieved.
@@ -336,24 +345,28 @@ See
 .BR keyctl_chown (3),
 .BR keyctl_describe (3),
 .BR keyctl_get_security (3),
-.BR keyctl_setperm (3)
+.BR keyctl_setperm (3),
 and
 .BR selinux (8)
 for more information.
 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
 .SS Searching for keys
-One of the key features of this facility is the ability to find a key that it
-is retaining.
+One of the key features of the Linux key-management facility
+is the ability to find a key that a process is retaining.
 The
 .BR request_key (2)
 system call is the primary point of
-access for user-space applications to find a key to use
-(the kernel has something similar available).
+access for user-space applications to find a key.
+(!nternally, the kernel has something similar available
+for use by internal components that make use of keys.)
 .P
 The search algorithm works as follows:
-.IP (1)
+.IP (1) 4
 The three process keyrings are searched in the following order: the thread
-keyring if it exists, the process keyring if it exists and then either the
+.BR thread-keyring (7)
+if it exists, the
+.BR process-keyring (7)
+if it exists, and then either the
 .BR session-keyring (7)
 if it exists or the
 .BR user-session-keyring (7)
@@ -365,17 +378,20 @@ upcall mechanism then the keyrings of the original caller of that
 .BR request_key (2)
 will be searched as well.
 .IP (3)
-Each keyring is searched first for a match, then the keyrings referred to by
-that keyring are searched.
+The search of the keyring tree is in preorder:
+each keyring is searched first for a match,
+then the keyrings referred to by that keyring are searched.
 .IP (4)
-If a matching key is found that is valid, then the search terminates and that
-key is returned.
+If a matching key is found that is valid,
+then the search terminates and that key is returned.
 .IP (5)
-If a matching key is found that has an error state attached, that error state
-is noted and the search continues.
+If a matching key is found that has an error state attached,
+that error state is noted and the search continues.
 .IP (6)
 If valid matching key is found,
-then the first noted error state is returned or else \fBENOKEY\fR is returned.
+then the first noted error state is returned; otherwise, an 
+.B ENOKEY
+error is returned.
 .P
 It is also possible to search a specific keyring, in which case only steps (3)
 to (6) apply.
@@ -395,42 +411,43 @@ argument, create a new key and then upcall to user space to
 instantiate the key.
 This allows keys to be created on an as-needed basis.
 .P
-Typically, this will involve the kernel forking and exec'ing
+Typically, this will involve the kernel forking and exec'ing the
 .BR request-key (8)
 program, which will then execute the appropriate handler based on its
 configuration.
 .P
-The handler is passed a special authorization key that allows it and only it to
-instantiate the new key.
+The handler is passed a special authorization key that allows it
+and only it to instantiate the new key.
 This is also used to permit searches performed by the
 handler program to also search the requester's keyrings.
 .P
 See
+.BR request_key (2),
 .BR keyctl_assume_authority (3),
 .BR keyctl_instantiate (3),
 .BR keyctl_negate (3),
 .BR keyctl_reject (3),
-.BR request_key (2),
 .BR request-key (8)
 and
 .BR request-key.conf (5)
 for more information.
 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
 .SS Users
-The facility has a number of users and usages, but is not limited to those
-that already exist.
+The Linux key-management facility has a number of users and usages,
+but is not limited to those that already exist.
 .P
 In-kernel users of this facility include:
 .IP "\fBNetwork filesystems - DNS\fR"
 The kernel uses the upcall mechanism provided by the keys to upcall to
 user space to do DNS lookups and then to cache the results.
 .IP "\fBAF_RXRPC and kAFS - Authentication\fR"
-The AF_RXRPC network protocol and the in-kernel AFS filesystem store the ticket
-needed to do secured or encrypted traffic in keys.
+The AF_RXRPC network protocol and the in-kernel AFS filesystem
+use keys to store the ticket needed to do secured or encrypted traffic.
 These are then looked up by
 network operations on AF_RXRPC and filesystem operations on kAFS.
 .IP "\fBNFS - User ID mapping\fR"
-The NFS filesystem uses keys to store foreign user ID to local user ID mapping.
+The NFS filesystem uses keys to store mappings of
+foreign user IDs to local user IDs.
 .IP "\fBCIFS - Password\fR"
 The CIFS filesystem uses keys to store passwords for accessing remote shares.
 .IP "\fBModule verification\fR"
@@ -441,7 +458,8 @@ User-space users of this facility include:
 .IP "\fBKerberos key storage\fR"
 The MIT Kerberos 5 facility (libkrb5) can use keys to store authentication
 tokens which can be made to be automatically cleaned up a set time after the
-user last uses them, but until then permits them to hang around after the user
+user last uses them,
+but until then permits them to hang around after the user
 has logged out so that cron scripts can use them.
 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
 .SH SEE ALSO