<commit_before>			 ============================
			 KERNEL KEY RETENTION SERVICE
			 ============================

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

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

The key service can be configured on by enabling:

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

This document has the following sections:

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


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

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

Each key has a number of attributes:

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


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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Keys in the last three states are subject to garbage collection.  See the
section on "Garbage collection".


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

The key service provides a number of features besides keys:

 (*) The key service defines 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.<commit_msg>keys: update the documentation with info about "logon" keys<commit_after>			 ============================
			 KERNEL KEY RETENTION SERVICE
			 ============================

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

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

The key service can be configured on by enabling:

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

This document has the following sections:

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


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

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

Each key has a number of attributes:

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


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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Keys in the last three states are subject to garbage collection.  See the
section on "Garbage collection".


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

The key service provides a number of features besides keys:

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

     (+) "keyring"

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

     (+) "user"

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

     (+) "logon"

	 Like a "user" key, a "logon" key has a payload that is an arbitrary
	 blob of data. It is intended as a place to store secrets which are
	 accessible to the kernel but not to userspace programs.

	 The description can be arbitrary, but must be prefixed with a non-zero
	 length string that describes the key "subclass". The subclass is
	 separated from the rest of the description by a ':'. "logon" keys can
	 be created and updated from userspace, but the payload is only
	 readable from kernel space.

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

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

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

     The session-specific keyring is persistent across clone, fork, vfork and
     execve, even when the latter executes a set-UID or set-GID binary. A
     process can, however, replace its current session keyring with a new one
     by using PR_JOIN_SESSION_KEYRING. It is permitted to request an anonymous
     new one, or to attempt to create or join one of a specific name.
{'fraction_non_alphanumeric': 0.05952952472395583, 'fraction_numerical': 0.0003200512081933109, 'mean_word_length': 3.234078590785908, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '2862260', 'n_tokens_mistral': 3264, 'n_tokens_neox': 3036, 'n_words': 1932}