path: root/Documentation/keys.txt

			 ============================
			 KERNEL KEY RETENTION SERVICE
			 ============================

This service allows cryptographic keys, authentication tokens, cross-domain
user mappings, and similar to be cached in the kernel for the use of
filesystems other kernel services.

Keyrings are permitted; these are a special type of key that can hold links to
other keys. Processes each have three standard keyring subscriptions that a
kernel service can search for relevant keys.

The key service can be configured on by enabling:

	"Security options"/"Enable access key retention support" (CONFIG_KEYS)

This document has the following sections:

	- Key overview
	- Key service overview
	- Key access permissions
	- New procfs files
	- Userspace system call interface
	- Kernel services
	- Notes on accessing payload contents
	- Defining a key type
	- Request-key callback service
	- Key access filesystem


============
KEY OVERVIEW
============

In this context, keys represent units of cryptographic data, authentication
tokens, keyrings, etc.. These are represented in the kernel by struct key.

Each key has a number of attributes:

	- A serial number.
	- A type.
	- A description (for matching a key in a search).
	- Access control information.
	- An expiry time.
	- A payload.
	- State.


 (*) Each key is issued a serial number of type key_serial_t that is unique for
     the lifetime of that key. All serial numbers are positive non-zero 32-bit
     integers.

     Userspace programs can use a key's serial numbers as a way to gain access
     to it, subject to permission checking.

 (*) Each key is of a defined "type". Types must be registered inside the
     kernel by a kernel service (such as a filesystem) before keys of that type
     can be added or used. Userspace programs cannot define new types directly.

     Key types are represented in the kernel by struct key_type. This defines a
     number of operations that can be performed on a key of that type.

     Should a type be removed from the system, all the keys of that type will
     be invalidated.

 (*) Each key has a description. This should be a printable string. The key
     type provides an operation to perform a match between the description on a
     key and a criterion string.

 (*) Each key has an owner user ID, a group ID and a permissions mask. These
     are used to control what a process may do to a key from userspace, and
     whether a kernel service will be able to find the key.

 (*) Each key can be set to expire at a specific time by the key type's
     instantiation function. Keys can also be immortal.

 (*) Each key can have a payload. This is a quantity of data that represent the
     actual "key". In the case of a keyring, this is a list of keys to which
     the keyring links; in the case of a user-defined key, it's an arbitrary
     blob of data.

     Having a payload is not required; and the payload can, in fact, just be a
     value stored in the struct key itself.

     When a key is instantiated, the key type's instantiation function is
     called with a blob of data, and that then creates the key's payload in
     some way.

     Similarly, when userspace wants to read back the contents of the key, if
     permitted, another key type operation will be called to convert the key's
     attached payload back into a blob of data.

 (*) Each key can be in one of a number of basic states:

     (*) Uninstantiated. The key exists, but does not have any data attached.
     	 Keys being requested from userspace will be in this state.

     (*) Instantiated. This is the normal state. The key is fully formed, and
	 has data attached.

     (*) Negative. This is a relatively short-lived state. The key acts as a
	 note saying that a previous call out to userspace failed, and acts as
	 a throttle on key lookups. A negative key can be updated to a normal
	 state.

     (*) Expired. Keys can have lifetimes set. If their lifetime is exceeded,
	 they traverse to this state. An expired key can be updated back to a
	 normal state.

     (*) Revoked. A key is put in this state by userspace action. It can't be
	 found or operated upon (apart from by unlinking it).

     (*) Dead. The key's type was unregistered, and so the key is now useless.


====================
KEY SERVICE OVERVIEW
====================

The key service provides a number of features besides keys:

 (*) The key service defines two special key types:

     (+) "keyring"

	 Keyrings are special keys that contain a list of other keys. Keyring
	 lists can be modified using various system calls. Keyrings should not
	 be given a payload when created.

     (+) "user"

	 A key of this type has a description and a payload that are arbitrary
	 blobs of data. These can be created, updated and read by userspace,
	 and aren't intended for use by kernel services.

 (*) Each process subscribes to three keyrings: a thread-specific keyring, a
     process-specific keyring, and a session-specific keyring.

     The thread-specific keyring is discarded from the child when any sort of
     clone, fork, vfork or execve occurs. A new keyring is created only when
     required.

     The process-specific keyring is replaced with an empty one in the child on
     clone, fork, vfork unless CLONE_THREAD is supplied, in which case it is
     shared. execve also discards the process's process keyring and creates a
     new one.

     The session-specific keyring is persistent across clone, fork, vfork and
     execve, even when the latter executes a set-UID or set-GID binary. A
     process can, however, replace its current session keyring with a new one
     by using PR_JOIN_SESSION_KEYRING. It is permitted to request an anonymous
     new one, or to attempt to create or join one of a specific name.

     The ownership of the thread keyring changes when the real UID and GID of
     the thread changes.

 (*) Each user ID resident in the system holds two special keyrings: a user
     specific keyring and a default user session keyring. The default session
     keyring is initialised with a link to the user-specific keyring.

     When a process changes its real UID, if it used to have no session key, it
     will be subscribed to the default session key for the new UID.

     If a process attempts to access its session key when it doesn't have one,
     it will be subscribed to the default for its current UID.

 (*) Each user has two quotas against which the keys they own are tracked. One
     limits the total number of keys and keyrings, the other limits the total
     amount of description and payload space that can be consumed.

     The user can view information on this and other statistics through procfs
     files.

     Process-specific and thread-specific keyrings are not counted towards a
     user's quota.

     If a system call that modifies a key or keyring in some way would put the
     user over quota, the operation is refused and error EDQUOT is returned.

 (*) There's a system call interface by which userspace programs can create and
     manipulate keys and keyrings.

 (*) There's a kernel interface by which services can register types and search
     for keys.

 (*) There's a way for the a search done from the kernel to call back to
     userspace to request a key that can't be found in a process's keyrings.

 (*) An optional filesystem is available through which the key database can be
     viewed and manipulated.


======================
KEY ACCESS PERMISSIONS
======================

Keys have an owner user ID, a group access ID, and a permissions mask. The mask
has up to eight bits each for possessor, user, group and other access. Only
six of each set of eight bits are defined. These permissions granted are:

 (*) View

     This permits a key or keyring's attributes to be viewed - including key
     type and description.

 (*) Read

     This permits a key's payload to be viewed or a keyring's list of linked
     keys.

 (*) Write

     This permits a key's payload to be instantiated or updated, or it allows a
     link to be added to or removed from a keyring.

 (*) Search

     This permits keyrings to be searched and keys to be found. Searches can
     only recurse into nested keyrings that have search permission set.

 (*) Link

     This permits a key or keyring to be linked to. To create a link from a
     keyring to a key, a process must have Write permission on the keyring and
     Link permission on the key.

 (*) Set Attribute

     This permits a key's UID, GID and permissions mask to be changed.

For changing the ownership, group ID or permissions mask, being the owner of
the key or having the sysadmin capability is sufficient.


================
NEW PROCFS FILES
================

Two files have been added to procfs by which an administrator can find out
about the status of the key service:

 (*) /proc/keys

     This lists all the keys on the system, giving information about their
     type, description and permissions. The payload of the key is not available
     this way:

	SERIAL   FLAGS  USAGE EXPY PERM     UID   GID   TYPE      DESCRIPTION: SUMMARY
	00000001 I-----    39 perm 1f3f0000     0     0 keyring   _uid_ses.0: 1/4
	00000002 I-----     2 perm 1f3f0000     0     0 keyring   _uid.0: empty
	00000007 I-----     1 perm 1f3f0000     0     0 keyring   _pid.1: empty
	0000018d I-----     1 perm 1f3f0000     0     0 keyring   _pid.412: empty
	000004d2 I--Q--     1 perm 1f3f0000    32    -1 keyring   _uid.32: 1/4
	000004d3 I--Q--     3 perm 1f3f0000    32    -1 keyring   _uid_ses.32: empty
	00000892 I--QU-     1 perm 1f000000     0     0 user      metal:copper: 0
	00000893 I--Q-N     1  35s 1f3f0000     0     0 user      metal:silver: 0
	00000894 I--Q--     1  10h 003f0000     0     0 user      metal:gold: 0

     The flags are:

	I	Instantiated
	R	Revoked
	D	Dead
	Q	Contributes to user's quota
	U	Under contruction by callback to userspace
	N	Negative key

     This file must be enabled at kernel configuration time as it allows anyone
     to list the keys database.

 (*) /proc/key-users

     This file lists the tracking data for each user that has at least one key
     on the system. Such data includes quota information and statistics:

	[root@andromeda root]# cat /proc/key-users
	0:     46 45/45 1/100 13/10000
	29:     2 2/2 2/100 40/10000
	32:     2 2/2 2/100 40/10000
	38:     2 2/2 2/100 40/10000

     The format of each line is
	<UID>:			User ID to which this applies
	<usage>			Structure refcount
	<inst>/<keys>		Total number of keys and number instantiated
	<keys>/<max>		Key count quota
	<bytes>/<max>		Key size quota


===============================
USERSPACE SYSTEM CALL INTERFACE
===============================

Userspace can manipulate keys directly through three new syscalls: add_key,
request_key and keyctl. The latter provides a number of functions for
manipulating keys.

When referring to a key directly, userspace programs should use the key's
serial number (a positive 32-bit integer). However, there are some special
values available for referring to special keys and keyrings that relate to the
process making the call:

	CONSTANT			VALUE	KEY REFERENCED
	==============================	======	===========================
	KEY_SPEC_THREAD_KEYRING		-1	thread-specific keyring
	KEY_SPEC_PROCESS_KEYRING	-2	process-specific keyring
	KEY_SPEC_SESSION_KEYRING	-3	session-specific keyring
	KEY_SPEC_USER_KEYRING		-4	UID-specific keyring
	KEY_SPEC_USER_SESSION_KEYRING	-5	UID-session keyring
	KEY_SPEC_GROUP_KEYRING		-6	GID-specific keyring
	KEY_SPEC_REQKEY_AUTH_KEY	-7	assumed request_key()
						  authorisation key


The main syscalls are:

 (*) Create a new key of given type, description and payload and add it to the
     nominated keyring:

	key_serial_t add_key(const char *type, const char *desc,
			     const void *payload, size_t plen,
			     key_serial_t keyring);

     If a key of the same type and description as that proposed already exists
     in the keyring, this will try to update it with the given payload, or it
     will return error EEXIST if that function is not supported by the key
     type. The process must also have permission to write to the key to be able
     to update it. The new key will have all user permissions granted and no
     group or third party permissions.

     Otherwise, this will attempt to create a new key of the specified type and
     description, and to instantiate it with the supplied payload and attach it
     to the keyring. In this case, an error will be generated if the process
     does not have permission to write to the keyring.

     The payload is optional, and the pointer can be NULL if not required by
     the type. The payload is plen in size, and plen can be zero for an empty
     payload.

     A new keyring can be generated by setting type "keyring", the keyring name
     as the description (or NULL) and setting the payload to NULL.

     User defined keys can be created by specifying type "user". It is
     recommended that a user defined key's description by prefixed with a type
     ID and a colon, such as "krb5tgt:" for a Kerberos 5 ticket granting
     ticket.

     Any other type must have been registered with the kernel in advance by a
     kernel service such as a filesystem.

     The ID of the new or updated key is returned if successful.


 (*) Search the process's keyrings for a key, potentially calling out to
     userspace to create it.

	key_serial_t request_key(const char *type, const char *description,
				 const char *callout_info,
				 key_serial_t dest_keyring);

     This function searches all the process's keyrings in the order thread,
     process, session for a matching key. This works very much like
     KEYCTL_SEARCH, including the optional attachment of the discovered key to
     a keyring.

     If a key cannot be found, and if callout_info is not NULL, then
     /sbin/request-key will be invoked in an attempt to obtain a key. The
     callout_info string will be passed as an argument to the program.

     See also Documentation/keys-request-key.txt.


The keyctl syscall functions are:

 (*) Map a special key ID to a real key ID for this process:

	key_serial_t keyctl(KEYCTL_GET_KEYRING_ID, key_serial_t id,
			    int create);

     The special key specified by "id" is looked up (with the key being created
     if necessary) and the ID of the key or keyring thus found is returned if
     it exists.

     If the key does not yet exist, the key will be created if "create" is
     non-zero; and the error ENOKEY will be returned if "create" is zero.


 (*) Replace the session keyring this process subscribes to with a new one:

	key_serial_t keyctl(KEYCTL_JOIN_SESSION_KEYRING, const char *name);

     If name is NULL, an anonymous keyring is created attached to the process
     as its session keyring, displacing the old session keyring.

     If name is not NULL, if a keyring of that name exists, the process
     attempts to attach it as the session keyring, returning an error if that
     is not permitted; otherwise a new keyring of that name is created and
     attached as the session keyring.

     To attach to a named keyring, the keyring must have search permission for
     the process's ownership.

     The ID of the new session keyring is returned if successful.


 (*) Update the specified key:

	long keyctl(KEYCTL_UPDATE, key_serial_t key, const void *payload,
		    size_t plen);

     This will try to update the specified key with the given payload, or it
     will return error EOPNOTSUPP if that function is not supported by the key
     type. The process must also have permission to write to the key to be able
     to update it.

     The payload is of length plen, and may be absent or empty as for
     add_key().


 (*) Revoke a key:

	long keyctl(KEYCTL_REVOKE, key_serial_t key);

     This makes a key unavailable for further operations. Further attempts to
     use the key will be met with error EKEYREVOKED, and the key will no longer
     be findable.


 (*) Change the ownership of a key:

	long keyctl(KEYCTL_CHOWN, key_serial_t key, uid_t uid, gid_t gid);

     This function permits a key's owner and group ID to be changed. Either one
     of uid or gid can be set to -1 to suppress that change.

     Only the superuser can change a key's owner to something other than the
     key's current owner. Similarly, only the superuser can change a key's
     group ID to something other than the calling process's group ID or one of
     its group list members.


 (*) Change the permissions mask on a key:

	long keyctl(KEYCTL_SETPERM, key_serial_t key, key_perm_t perm);

     This function permits the owner of a key or the superuser to change the
     permissions mask on a key.

     Only bits the available bits are permitted; if any other bits are set,
     error EINVAL will be returned.


 (*) Describe a key:

	long keyctl(KEYCTL_DESCRIBE, key_serial_t key, char *buffer,
		    size_t buflen);

     This function returns a summary of the key's attributes (but not its
     payload data) as a string in the buffer provided.

     Unless there's an error, it always returns the amount of data it could
     produce, even if that's too big for the buffer, but it won't copy more
     than requested to userspace. If the buffer pointer is NULL then no copy
     will take place.

     A process must have view permission on the key for this function to be
     successful.

     If successful, a string is placed in the buffer in the following format:

	<type>;<uid>;<gid>;<perm>;<description>

     Where type and description are strings, uid and gid are decimal, and perm
     is hexadecimal. A NUL character is included at the end of the string if
     the buffer is sufficiently big.

     This can be parsed with

	sscanf(buffer, "%[^;];%d;%d;%o;%s", type, &uid, &gid, &mode, desc);


 (*) Clear out a keyring:

	long keyctl(KEYCTL_CLEAR, key_serial_t keyring);

     This function clears the list of keys attached to a keyring. The calling
     process must have write permission on the keyring, and it must be a
     keyring (or else error ENOTDIR will result).


 (*) Link a key into a keyring:

	long keyctl(KEYCTL_LINK, key_serial_t keyring, key_serial_t key);

     This function creates a link from the keyring to the key. The process must
     have write permission on the keyring and must have link permission on the
     key.

     Should the keyring not be a keyring, error ENOTDIR will result; and if the
     keyring is full, error ENFILE will result.

     The link procedure checks the nesting of the keyrings, returning ELOOP if
     it appears too deep or EDEADLK if the link would introduce a cycle.

     Any links within the keyring to keys that match the new key in terms of
     type and description will be discarded from the keyring as the new one is
     added.


 (*) Unlink a key or keyring from another keyring:

	long keyctl(KEYCTL_UNLINK, key_serial_t keyring, key_serial_t key);

     This function looks through the keyring for the first link to the
     specified key, and removes it if found. Subsequent links to that key are
     ignored. The process must have write permission on the keyring.

     If the keyring is not a keyring, error ENOTDIR will result; and if the key
     is not present, error ENOENT will be the result.


 (*) Search a keyring tree for a key:

	key_serial_t keyctl(KEYCTL_SEARCH, key_serial_t keyring,
			    const char *type, const char *description,
			    key_serial_t dest_keyring);

     This searches the keyring tree headed by the specified keyring until a key
     is found that matches the type and description criteria. Each keyring is
     checked for keys before recursion into its children occurs.

     The process must have search permission on the top level keyring, or else
     error EACCES will result. Only keyrings that the process has search
     permission on will be recursed into, and only keys and keyrings for which
     a process has search permission can be matched. If the specified keyring
     is not a keyring, ENOTDIR will result.

     If the search succeeds, the function will attempt to link the found key
     into the destination keyring if one is supplied (non-zero ID). All the
     constraints applicable to KEYCTL_LINK apply in this case too.

     Error ENOKEY, EKEYREVOKED or EKEYEXPIRED will be returned if the search
     fails. On success, the resulting key ID will be returned.


 (*) Read the payload data from a key:

	long keyctl(KEYCTL_READ, key_serial_t keyring, char *buffer,
		    size_t buflen);

     This function attempts to read the payload data from the specified key
     into the buffer. The process must have read permission on the key to
     succeed.

     The returned data will be processed for presentation by the key type. For
     instance, a keyring will return an array of key_serial_t entries
     representing the IDs of all the keys to which it is subscribed. The user
     defined key type will return its data as is. If a key type does not
     implement this function, error EOPNOTSUPP will result.

     As much of the data as can be fitted into the buffer will be copied to
     userspace if the buffer pointer is not NULL.

     On a successful return, the function will always return the amount of data
     available rather than the amount copied.


 (*) Instantiate a partially constructed key.

	long keyctl(KEYCTL_INSTANTIATE, key_serial_t key,
		    const void *payload, size_t plen,
		    key_serial_t keyring);

     If the kernel calls back to userspace to complete the instantiation of a
     key, userspace should use th