man-pages/man7/keyrings.7

.\"
.\" Copyright (C) 2014 Red Hat, Inc. All Rights Reserved.
.\" Written by David Howells (dhowells@redhat.com)
.\"
.\" %%%LICENSE_START(GPLv2+_SW_ONEPARA)
.\" This program is free software; you can redistribute it and/or
.\" modify it under the terms of the GNU General Public Licence
.\" as published by the Free Software Foundation; either version
.\" 2 of the Licence, or (at your option) any later version.
.\" %%%LICENSE_END
.\"
.TH KEYRINGS 7 2016-11-01 Linux "Linux Programmer's Manual"
.SH NAME
keyrings \- in-kernel key management and retention facility
.SH DESCRIPTION
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
objects and also use the facility for their own purposes.
.P
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.
.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.SS Keys
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.
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.
.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.
(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.
.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).

Note that keys are quota controlled since they represent unswappable kernel
memory and the owning user ID specifies whose quota is to be debited.
.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 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 currently active users,
and by a process's credentials.
When the reference count reaches zero,
the key is scheduled for garbage collection.
.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.SS Key types
The facility provides several basic types of key:
.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.
.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
.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).
.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.
.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.SS Keyrings
As previously mentioned, keyrings are a special type of key that contain links
to other keys (which may include other keyrings).
Keys may be linked to by multiple keyrings.
Keyrings may be considered as analogous to UNIX directories
where each directory contains a set of hard links to files.
.P
Various operations (system calls) may be applied only to keyrings:
.IP "\fBAdding\fR"
A key may be added to a keyring by system calls that create keys.
This prevents the new key from being immediately deleted
when the system call driver releases its last reference to the key.
.IP "\fBLinking\fR"
A link may be added to a keyring pointing to a key that is already known,
provided this does not create a self-referential cycle.
.IP "\fBUnlinking\fR"
A link may be removed from a keyring.
When the last link to a key is removed,
that key will be scheduled for deletion by the garbage collector.
.IP "\fBClearing\fR"
All the links may be removed from a keyring.
.IP "\fBSearching\fR"
A keyring may be considered the root of a tree or subtree in which keyrings
form the branches and non-keyrings the leaves.
This tree may be searched for a leaf matching
a particular type and description.
.P
See
.BR keyctl_clear (3),
.BR keyctl_link (3),
.BR keyctl_search (3),
and
.BR keyctl_unlink (3)
for more information.
.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.SS Anchoring keys
To prevent a key from being prematurely garbage collected,
it must anchored to keep its reference count elevated
when it is not in active use by the kernel.
.P
\fBKeyrings\fR are used to anchor other keys - each link is a reference on a
key - but whilst keyrings are available to link to keys, keyrings themselves
are just keys and are also subject to the same anchoring necessity.
.P
The kernel makes available a number of anchor keyrings.
Note that some of these keyrings will be created only when first accessed.
.IP "\fBProcess keyrings\fR"
Process credentials themselves reference keyrings with specific semantics.
These keyrings are pinned as long as the set of credentials exists,
which is usually as long as the process exists.
.IP
There are three keyrings with different inheritance/sharing rules:
The
.BR session-keyring (7)
(inherited and shared by all child processes),
the
.BR process-keyring (7)
(shared by all threads in a process) and
the
.BR thread-keyring (7)
(specific to a particular thread).
.IP "\fBUser keyrings\fR"
Each UID known to the kernel has a record that contains two keyrings: The
.BR user-keyring (7)
and the
.BR user-session-keyring (7).
These exist for as long as the UID record in the kernel exists.
A link to the user keyring is placed in a new session keyring by
.BR pam_keyinit (8) 
when a new login session is initiated.
.IP "\fBPersistent keyrings\fR"
There is a
.BR persistent-keyring (7)
available to each UID known to the system.
It may persist beyond the life of the UID record previously mentioned,
but has an expiration time set such that it is automatically cleaned up
after a set time.
This, for example, permits cron scripts to use credentials left when the
user logs out.
.IP
Note that the expiration time is reset every time the persistent key is
requested.
.IP "\fBSpecial keyrings\fR"
There are special keyrings owned by the kernel that can anchor keys
for special purposes.
An example of this is the \fBsystem keyring\fR used for holding
encryption keys for module signature verification.
.IP
These special keyrings  are usually closed to direct alteration
by user space.
.P
See
.BR thread-keyring (7),
.BR process-keyring (7),
.BR session-keyring (7),
.BR user-keyring (7),
.BR user-session-keyring (7),
and
.BR persistent-keyring (7)
for more information.
.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.SS Possession
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) 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.
.IP (3)
If a keyring is possessed, then any key it links to is \fIalso\fR possessed.
.IP (4)
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
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 the key is needed.
.P
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
.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:
.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 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 \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 union of whichever
of the first three sets is applicable plus the fourth set
if the key is possessed.
.P
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 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.
.P
See
.BR keyctl_chown (3),
.BR keyctl_describe (3),
.BR keyctl_get_security (3),
.BR keyctl_setperm (3),
and
.BR selinux (8)
for more information.
.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.SS Searching for keys
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.
(!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) 4
The three process keyrings are searched in the following order: the thread
.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)
if that exists.
.IP (2)
If the caller was a process that was invoked by the
.BR request_key (2)
upcall mechanism then the keyrings of the original caller of that
.BR request_key (2)
will be searched as well.
.IP (3)
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.
.IP (5)
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; 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.
.P
See
.BR request_key (2)
and
.BR keyctl_search (3)
for more information.
.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.SS On-demand key creation
If a key cannot be found,
.BR request_key (2)
will, if given a
.I callout_info
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 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.
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 (8)
and
.BR request-key.conf (5)
for more information.
.SS /proc files
.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.\" FIXME document /proc files
.TP
.IR /proc/keys " (since Linux 2.6.10)"
.TP
.IR /proc/key-users " (since Linux 2.6.10)"
.TP
.IR /proc/sys/kernel/keys/gc_delay " (since Linux 2.6.32)"
.\" commit 5d135440faf7db8d566de0c6fab36b16cf9cfc3b
The value in this file specifies the interval (in seconds)
after which revoked and expired keys will garbage collected.

The default value in this file is 300 (i.e., 5 minutes).
.TP
.IR /proc/sys/kernel/keys/persistent_keyring_expiry " (since Linux 3.13)"
.\" commit f36f8c75ae2e7d4da34f4c908cebdb4aa42c977e
This file defines an interval, in seconds,
to which the persistent keyring's expiration timer is reset
each time the keyring is accessed (via
.BR keyctl_get_persistent (3)
or the
.BR keyctl (2)
.B KEYCTL_GET_PERSISTENT
operation.)

The default value in this file is 259200 (i.e., 3 days).
.PP
The following files (which are writable by privileged processies)
are used to enforce quotas on the number of keys
and number of bytes of data that can be stored in key payloads:
.TP
.IR /proc/sys/kernel/keys/maxbytes " (since Linux 2.6.26)"
.\" commit 0b77f5bfb45c13e1e5142374f9d6ca75292252a4
.\" Previously: KEYQUOTA_MAX_BYTES      10000
This is the maximum number of bytes of data that a nonroot user
can hold in the payloads of the keys owned by the user.

The default value in this file is 20,000.
.TP
.IR /proc/sys/kernel/keys/maxkeys " (since Linux 2.6.26)"
.\" commit 0b77f5bfb45c13e1e5142374f9d6ca75292252a4
.\" Previously: KEYQUOTA_MAX_KEYS       100
This is the maximum number of keys that a nonroot user may own.

The default value in this file is 200.
.TP
.IR /proc/sys/kernel/keys/root_maxbytes " (since Linux 2.6.26)"
This is the maximum number of bytes of data that the root user
(UID 0 in the root user namespace)
can hold in the payloads of the keys owned by root.

The default value in this file is 25,000,000.
.\" commit 0b77f5bfb45c13e1e5142374f9d6ca75292252a4
.TP
.IR /proc/sys/kernel/keys/root_maxkeys " (since Linux 2.6.26)"
.\" commit 0b77f5bfb45c13e1e5142374f9d6ca75292252a4
This is the maximum number of keys that the root user
(UID 0 in the root user namespace)
may own.

The default value in this file is 1,000,000.
.PP
With respect to keyrings,
note that each link in a keyring consumes 4 bytes of the keyring payload.
.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.SS Users
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
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 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"
The kernel build process can be made to cryptographically sign modules.
That signature is then checked when a module is loaded.
.P
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
has logged out so that cron scripts can use them.
.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.SH SEE ALSO
.ad l
.nh
.BR keyutils (7),
.BR persistent\-keyring (7),
.BR process\-keyring (7),
.BR session\-keyring (7),
.BR thread\-keyring (7),
.BR user\-keyring (7),
.BR user\-session\-keyring (7),
.BR pam_keyinit (8)