| ============================ |
| 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: |
| |
| .. contents:: :local: |
| |
| |
| 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. |
| |
| 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. The root user may also alter the quota limits through sysctl files |
| (see the section "New 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. |
| |
| |
| SELinux Support |
| =============== |
| |
| The security class "key" has been added to SELinux so that mandatory access |
| controls can be applied to keys created within various contexts. This support |
| is preliminary, and is likely to change quite significantly in the near future. |
| Currently, all of the basic permissions explained above are provided in SELinux |
| as well; SELinux is simply invoked after all basic permission checks have been |
| performed. |
| |
| The value of the file /proc/self/attr/keycreate influences the labeling of |
| newly-created keys. If the contents of that file correspond to an SELinux |
| security context, then the key will be assigned that context. Otherwise, the |
| key will be assigned the current context of the task that invoked the key |
| creation request. Tasks must be granted explicit permission to assign a |
| particular context to newly-created keys, using the "create" permission in the |
| key security class. |
| |
| The default keyrings associated with users will be labeled with the default |
| context of the user if and only if the login programs have been instrumented to |
| properly initialize keycreate during the login process. Otherwise, they will |
| be labeled with the context of the login program itself. |
| |
| Note, however, that the default keyrings associated with the root user are |
| labeled with the default kernel context, since they are created early in the |
| boot process, before root has a chance to log in. |
| |
| The keyrings associated with new threads are each labeled with the context of |
| their associated thread, and both session and process keyrings are handled |
| similarly. |
| |
| |
| 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 the keys that are currently viewable by the task reading the |
| file, giving information about their type, description and permissions. |
| It is not possible to view the payload of the key this way, though some |
| information about it may be given. |
| |
| The only keys included in the list are those that grant View permission to |
| the reading process whether or not it possesses them. Note that LSM |
| 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:: |
| |
| 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 construction by callback to userspace |
| N Negative key |
| |
| |
| * /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 |
| |
| |
| 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_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/maxbytes |
| |
| These files hold the maximum number of keys that each non-root user may |
| have and the maximum total number of bytes of data that each of those |
| users may have stored in their keys. |
| |
| Root may alter these by writing each new limit as a decimal number string to |
| the appropriate file. |
| |
| |
| 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. |
| |
| If the key type supports it, if the description is NULL or an empty |
| string, the key type will try and generate a description from the content |
| of the payload. |
| |
| 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/security/keys/request-key.rst. |
| |
| |
| 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). |
| |
| This function can also be used to clear special kernel keyrings if they |
| are appropriately marked if the user has CAP_SYS_ADMIN capability. The |
| DNS resolver cache keyring is an example of this. |
| |
| |
| * 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. |
| |
| If the specified buffer is too small, then the size of the buffer required |
| will be returned. Note that in this case, the contents of the buffer may |
| have been overwritten in some undefined way. |
| |
| Otherwise, on success, the function will return the amount of data copied |
| into the buffer. |
| |
| * Instantiate a partially constructed key:: |
| |
| long keyctl(KEYCTL_INSTANTIATE, key_serial_t key, |
| const void *payload, size_t plen, |
| key_serial_t keyring); |
| long keyctl(KEYCTL_INSTANTIATE_IOV, key_serial_t key, |
| const struct iovec *payload_iov, unsigned ioc, |
| key_serial_t keyring); |
| |
| If the kernel calls back to userspace to complete the instantiation of a |
| key, userspace should use this call to supply data for the key before the |
| invoked process returns, or else the key will be marked negative |
| automatically. |
| |
| The process must have write access on the key to be able to instantiate |
| it, and the key must be uninstantiated. |
| |
| If a keyring is specified (non-zero), the key will also be linked into |
| that keyring, however all the constraints applying in KEYCTL_LINK apply in |
| this case too. |
| |
| The payload and plen arguments describe the payload data as for add_key(). |
| |
| The payload_iov and ioc arguments describe the payload data in an iovec |
| array instead of a single buffer. |
| |
| |
| * Negatively instantiate a partially constructed key:: |
| |
| long keyctl(KEYCTL_NEGATE, key_serial_t key, |
| unsigned timeout, key_serial_t keyring); |
| long keyctl(KEYCTL_REJECT, key_serial_t key, |
| unsigned timeout, unsigned error, key_serial_t keyring); |
| |
| If the kernel calls back to userspace to complete the instantiation of a |
| key, userspace should use this call mark the key as negative before the |
| invoked process returns if it is unable to fulfill the request. |
| |
| The process must have write access on the key to be able to instantiate |
| it, and the key must be uninstantiated. |
| |
| If a keyring is specified (non-zero), the key will also be linked into |
| that keyring, however all the constraints applying in KEYCTL_LINK apply in |
| this case too. |
| |
| If the key is rejected, future searches for it will return the specified |
| error code until the rejected key expires. Negating the key is the same |
| as rejecting the key with ENOKEY as the error code. |
| |
| |
| * 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:: |
| |
| CONSTANT VALUE NEW DEFAULT KEYRING |
| ====================================== ====== ======================= |
| KEY_REQKEY_DEFL_NO_CHANGE -1 No change |
| KEY_REQKEY_DEFL_DEFAULT 0 Default[1] |
| KEY_REQKEY_DEFL_THREAD_KEYRING 1 Thread keyring |
| KEY_REQKEY_DEFL_PROCESS_KEYRING 2 Process keyring |
| KEY_REQKEY_DEFL_SESSION_KEYRING 3 Session keyring |
| KEY_REQKEY_DEFL_USER_KEYRING 4 User keyring |
| KEY_REQKEY_DEFL_USER_SESSION_KEYRING 5 User session keyring |
| KEY_REQKEY_DEFL_GROUP_KEYRING 6 Group keyring |
| |
| The old default will be returned if successful and error EINVAL will be |
| returned if reqkey_defl is not one of the above values. |
| |
| The default keyring can be overridden by the keyring indicated to the |
| request_key() system call. |
| |
| Note that this setting is inherited across fork/exec. |
| |
| [1] The default is: the thread keyring if there is one, otherwise |
| the process keyring if there is one, otherwise the session keyring if |
| there is one, otherwise the user default session keyring. |
| |
| |
| * Set the timeout on a key:: |
| |
| long keyctl(KEYCTL_SET_TIMEOUT, key_serial_t key, unsigned timeout); |
| |
| This sets or clears the timeout on a key. The timeout can be 0 to clear |
| the timeout or a number of seconds to set the expiry time that far into |
| the future. |
| |
| The process must have attribute modification access on a key to set its |
| timeout. Timeouts may not be set with this function on negative, revoked |
| or expired keys. |
| |
| |
| * Assume the authority granted to instantiate a key:: |
| |
| long keyctl(KEYCTL_ASSUME_AUTHORITY, key_serial_t key); |
| |
| This assumes or divests the authority required to instantiate the |
| specified key. Authority can only be assumed if the thread has the |
| authorisation key associated with the specified key in its keyrings |
| somewhere. |
| |
| Once authority is assumed, searches for keys will also search the |
| requester's keyrings using the requester's security label, UID, GID and |
| groups. |
| |
| If the requested authority is unavailable, error EPERM will be returned, |
| likewise if the authority has been revoked because the target key is |
| already instantiated. |
| |
| If the specified key is 0, then any assumed authority will be divested. |
| |
| The assumed authoritative key is inherited across fork and exec. |
| |
| |
| * Get the LSM security context attached to a key:: |
| |
| long keyctl(KEYCTL_GET_SECURITY, key_serial_t key, char *buffer, |
| size_t buflen) |
| |
| This function returns a string that represents the LSM security context |
| attached to a key 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 NUL character is included at the end of the string if the buffer is |
| sufficiently big. This is included in the returned count. If no LSM is |
| in force then an empty string will be returned. |
| |
| A process must have view permission on the key for this function to be |
| successful. |
| |
| |
| * Install the calling process's session keyring on its parent:: |
| |
| long keyctl(KEYCTL_SESSION_TO_PARENT); |
| |
| This functions attempts to install the calling process's session keyring |
| on to the calling process's parent, replacing the parent's current session |
| keyring. |
| |
| The calling process must have the same ownership as its parent, the |
| keyring must have the same ownership as the calling process, the calling |
| process must have LINK permission on the keyring and the active LSM module |
| mustn't deny permission, otherwise error EPERM will be returned. |
| |
| Error ENOMEM will be returned if there was insufficient memory to complete |
| the operation, otherwise 0 will be returned to indicate success. |
| |
| The keyring will be replaced next time the parent process leaves the |
| kernel and resumes executing userspace. |
| |
| |
| * Invalidate a key:: |
| |
| long keyctl(KEYCTL_INVALIDATE, key_serial_t key); |
| |
| This function marks a key as being invalidated and then wakes up the |
| garbage collector. The garbage collector immediately removes invalidated |
| keys from all keyrings and deletes the key when its reference count |
| reaches zero. |
| |
| Keys that are marked invalidated become invisible to normal key operations |
| immediately, though they are still visible in /proc/keys until deleted |
| (they're marked with an 'i' flag). |
| |
| A process must have search permission on the key for this function to be |
| successful. |
| |
| * 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); |
| |
| 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:: |
| |
| result = base ^ private (mod prime) |
| |
| If the base is the shared generator, the result is the local |
| public key. If the base is the remote public key, the result is |
| the shared secret. |
| |
| If the parameter kdf is NULL, the following applies: |
| |
| - The buffer length must be at least the length of the prime, or zero. |
| |
| - If the buffer length is nonzero, the length of the result is |
| returned when it is successfully calculated and copied in to the |
| buffer. When the buffer length is zero, the minimum required |
| buffer length is returned. |
| |
| The kdf parameter allows the caller to apply a key derivation function |
| (KDF) on the Diffie-Hellman computation where only the result |
| 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 |
| 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 |
| 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. |
| |
| This function will return error EOPNOTSUPP if the key type is not |
| supported, error ENOKEY if the key could not be found, or error |
| EACCES if the key is not readable by the caller. In addition, the |
| function will return EMSGSIZE when the parameter kdf is non-NULL |
| and either the buffer length or the OtherInfo length exceeds the |
| allowed length. |
| |
| |
| * Restrict keyring linkage:: |
| |
| 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. |
| |
| "keyring" is the key ID for an existing keyring to apply a restriction |
| to. It may be empty or may already have keys linked. Existing linked keys |
| will remain in the keyring even if the new restriction would reject them. |
| |
| "type" is a registered key type. |
| |
| "restriction" is a string describing how key linkage is to be restricted. |
| The format varies depending on the key type, and the string is passed to |
| the lookup_restriction() function for the requested type. It may specify |
| a method and relevant data for the restriction such as signature |
| verification or constraints on key payload. If the requested key type is |
| later unregistered, no keys may be added to the keyring after the key type |
| is removed. |
| |
| To apply a keyring restriction the process must have Set Attribute |
| permission and the keyring must not be previously restricted. |
| |
| One application of restricted keyrings is to verify X.509 certificate |
| chains or individual certificate signatures using the asymmetric key type. |
| See Documentation/crypto/asymmetric-keys.txt for specific restrictions |
| applicable to the asymmetric key type. |
| |
| |
| * Query an asymmetric key:: |
| |
| long keyctl(KEYCTL_PKEY_QUERY, |
| key_serial_t key_id, unsigned long reserved, |
| struct keyctl_pkey_query *info); |
| |
| Get information about an asymmetric key. The information is returned in |
| the keyctl_pkey_query struct:: |
| |
| __u32 supported_ops; |
| __u32 key_size; |
| __u16 max_data_size; |
| __u16 max_sig_size; |
| __u16 max_enc_size; |
| __u16 max_dec_size; |
| __u32 __spare[10]; |
| |
| ``supported_ops`` contains a bit mask of flags indicating which ops are |
| supported. This is constructed from a bitwise-OR of:: |
| |
| KEYCTL_SUPPORTS_{ENCRYPT,DECRYPT,SIGN,VERIFY} |
| |
| ``key_size`` indicated the size of the key in bits. |
| |
| ``max_*_size`` indicate the maximum sizes in bytes of a blob of data to be |
| signed, a signature blob, a blob to be encrypted and a blob to be |
| decrypted. |
| |
| ``__spare[]`` must be set to 0. This is intended for future use to hand |
| over one or more passphrases needed unlock a key. |
| |
| If successful, 0 is returned. If the key is not an asymmetric key, |
| EOPNOTSUPP is returned. |
| |
| |
| * Encrypt, decrypt, sign or verify a blob using an asymmetric key:: |
| |
| long keyctl(KEYCTL_PKEY_ENCRYPT, |
| const struct keyctl_pkey_params *params, |
| const char *info, |
| const void *in, |
| void *out); |
| |
| long keyctl(KEYCTL_PKEY_DECRYPT, |
| const struct keyctl_pkey_params *params, |
| const char *info, |
| const void *in, |
| void *out); |
| |
| long keyctl(KEYCTL_PKEY_SIGN, |
| const struct keyctl_pkey_params *params, |
| const char *info, |
| const void *in, |
| void *out); |
| |
| long keyctl(KEYCTL_PKEY_VERIFY, |
| const struct keyctl_pkey_params *params, |
| const char *info, |
| const void *in, |
| const void *in2); |
| |
| Use an asymmetric key to perform a public-key cryptographic operation a |
| blob of data. For encryption and verification, the asymmetric key may |
| only need the public parts to be available, but for decryption and signing |
| the private parts are required also. |
| |
| The parameter block pointed to by params contains a number of integer |
| values:: |
| |
| __s32 key_id; |
| __u32 in_len; |
| __u32 out_len; |
| __u32 in2_len; |
| |
| ``key_id`` is the ID of the asymmetric key to be used. ``in_len`` and |
| ``in2_len`` indicate the amount of data in the in and in2 buffers and |
| ``out_len`` indicates the size of the out buffer as appropriate for the |
| above operations. |
| |
| For a given operation, the in and out buffers are used as follows:: |
| |
| Operation ID in,in_len out,out_len in2,in2_len |
| ======================= =============== =============== =============== |
| KEYCTL_PKEY_ENCRYPT Raw data Encrypted data - |
| KEYCTL_PKEY_DECRYPT Encrypted data Raw data - |
| KEYCTL_PKEY_SIGN Raw data Signature - |
| KEYCTL_PKEY_VERIFY Raw data - Signature |
| |
| ``info`` is a string of key=value pairs that supply supplementary |
| information. These include: |
| |
| ``enc=<encoding>`` The encoding of the encrypted/signature blob. This |
| can be "pkcs1" for RSASSA-PKCS1-v1.5 or |
| RSAES-PKCS1-v1.5; "pss" for "RSASSA-PSS"; "oaep" for |
| "RSAES-OAEP". If omitted or is "raw", the raw output |
| of the encryption function is specified. |
| |
| ``hash=<algo>`` If the data buffer contains the output of a hash |
| function and the encoding includes some indication of |
| which hash function was used, the hash function can be |
| specified with this, eg. "hash=sha256". |
| |
| The ``__spare[]`` space in the parameter block must be set to 0. This is |
| intended, amongst other things, to allow the passing of passphrases |
| required to unlock a key. |
| |
| If successful, encrypt, decrypt and sign all return the amount of data |
| written into the output buffer. Verification returns 0 on success. |
| |
| |
| Kernel Services |
| =============== |
| |
| The kernel services for key management are fairly simple to deal with. They can |
| be broken down into two areas: keys and key types. |
| |
| Dealing with keys is fairly straightforward. Firstly, the kernel service |
| registers its type, then it searches for a key of that type. It should retain |
| the key as long as it has need of it, and then it should release it. For a |
| filesystem or device file, a search would probably be performed during the open |
| 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:: |
| |
| <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:: |
| |
| <keys/user-type.h> |
| |
| Note that there are two different types of pointers to keys that may be |
| encountered: |
| |
| * struct key * |
| |
| This simply points to the key structure itself. Key structures will be at |
| least four-byte aligned. |
| |
| * key_ref_t |
| |
| 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:: |
| |
| key_ref_t make_key_ref(const struct key *key, bool possession); |
| |
| struct key *key_ref_to_ptr(const key_ref_t key_ref); |
| |
| bool is_key_possessed(const key_ref_t key_ref); |
| |
| The first function constructs a key reference from a key pointer and |
| possession information (which must be true or false). |
| |
| The second function retrieves the key pointer from a reference and the |
| third retrieves the possession flag. |
| |
| 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:: |
| |
| struct key *request_key(const struct key_type *type, |
| const char *description, |
| const char *callout_info); |
| |
| This is used to request a key or keyring with a description that matches |
| the description specified according to the key type's match_preparse() |
| method. This permits approximate matching to occur. If callout_string is |
| not NULL, then /sbin/request-key will be invoked in an attempt to obtain |
| the key from userspace. In that case, callout_string will be passed as an |
| argument to the program. |
| |
| Should the function fail error ENOKEY, EKEYEXPIRED or EKEYREVOKED will be |
| returned. |
| |
| If successful, the key will have been attached to the default keyring for |
| implicitly obtained request-key keys, as set by KEYCTL_SET_REQKEY_KEYRING. |
| |
| See also Documentation/security/keys/request-key.rst. |
| |
| |
| * 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, |
| const void *callout_info, |
| size_t callout_len, |
| void *aux); |
| |
| This is identical to request_key(), except that the auxiliary data is |
| passed to the key_type->request_key() op if it exists, and the callout_info |
| is a blob of length callout_len, if given (the length may be 0). |
| |
| |
| * 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:: |
| |
| struct key *request_key_async_with_auxdata(const struct key_type *type, |
| const char *description, |
| const char *callout_info, |
| size_t callout_len, |
| void *aux); |
| |
| which are asynchronous equivalents of request_key() and |
| request_key_with_auxdata() respectively. |
| |
| These two functions return with the key potentially still under |
| construction. To wait for construction completion, the following should be |
| called:: |
| |
| int wait_for_key_construction(struct key *key, bool intr); |
| |
| The function will wait for the key to finish being constructed and then |
| invokes key_validate() to return an appropriate value to indicate the state |
| of the key (0 indicates the key is usable). |
| |
| If intr is true, then the wait can be interrupted by a signal, in which |
| case error ERESTARTSYS will be returned. |
| |
| |
| * When it is no longer required, the key should be released using:: |
| |
| void key_put(struct key *key); |
| |
| Or:: |
| |
| void key_ref_put(key_ref_t key_ref); |
| |
| These can be called from interrupt context. If CONFIG_KEYS is not set then |
| the argument will not be parsed. |
| |
| |
| * 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); |
| |
| Keys so references will need to be disposed of by calling key_put() when |
| they've been finished with. The key pointer passed in will be returned. |
| |
| In the case of key_get(), if the pointer is NULL or CONFIG_KEYS is not set |
| then the key will not be dereferenced and no increment will take place. |
| |
| |
| * A key's serial number can be obtained by calling:: |
| |
| key_serial_t key_serial(struct key *key); |
| |
| If key is NULL or if CONFIG_KEYS is not set then 0 will be returned (in the |
| latter case without parsing the argument). |
| |
| |
| * 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, |
| const char *description) |
| |
| This searches the keyring tree specified for a matching key. Error ENOKEY |
| is returned upon failure (use IS_ERR/PTR_ERR to determine). If successful, |
| the returned key will need to be released. |
| |
| The possession attribute from the keyring reference is used to control |
| access through the permissions mask and is propagated to the returned key |
| reference pointer if successful. |
| |
| |
| * A keyring can be created by:: |
| |
| struct key *keyring_alloc(const char *description, uid_t uid, gid_t gid, |
| const struct cred *cred, |
| key_perm_t perm, |
| struct key_restriction *restrict_link, |
| unsigned long flags, |
| struct key *dest); |
| |
| This creates a keyring with the given attributes and returns it. If dest |
| is not NULL, the new keyring will be linked into the keyring to which it |
| points. No permission checks are made upon the destination keyring. |
| |
| Error EDQUOT can be returned if the keyring would overload the quota (pass |
| KEY_ALLOC_NOT_IN_QUOTA in flags if the keyring shouldn't be accounted |
| towards the user's quota). Error ENOMEM can also be returned. |
| |
| If restrict_link is not NULL, it should point to a structure that contains |
| the function that will be called each time an attempt is made to link a |
| key into the new keyring. The structure may also contain a key pointer |
| and an associated key type. The function is called to check whether a key |
| may be added into the keyring or not. The key type is used by the garbage |
| collector to clean up function or data pointers in this structure if the |
| given key type is unregistered. Callers of key_create_or_update() within |
| the kernel can pass KEY_ALLOC_BYPASS_RESTRICTION to suppress the check. |
| An example of using this is to manage rings of cryptographic keys that are |
| set up when the kernel boots where userspace is also permitted to add keys |
| - provided they can be verified by a key the kernel already has. |
| |
| When called, the restriction function will be passed the keyring being |
| added to, the key type, the payload of the key being added, and data to be |
| used in the restriction check. Note that when a new key is being created, |
| this is called between payload preparsing and actual key creation. The |
| function should return 0 to allow the link or an error to reject it. |
| |
| A convenience function, restrict_link_reject, exists to always return |
| -EPERM to in this case. |
| |
| |
| * To check the validity of a key, this function can be called:: |
| |
| int validate_key(struct key *key); |
| |
| This checks that the key in question hasn't expired or and hasn't been |
| revoked. Should the key be invalid, error EKEYEXPIRED or EKEYREVOKED will |
| be returned. If the key is NULL or if CONFIG_KEYS is not set then 0 will be |
| returned (in the latter case without parsing the argument). |
| |
| |
| * To register a key type, the following function should be called:: |
| |
| int register_key_type(struct key_type *type); |
| |
| This will return error EEXIST if a type of the same name is already |
| present. |
| |
| |
| * 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:: |
| |
| struct key_type key_type_keyring; |
| |
| This can be used with a function such as request_key() to find a specific |
| keyring in a process's keyrings. A keyring thus found can then be searched |
| 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 |
| =================================== |
| |
| The simplest payload is just data stored in key->payload directly. In this |
| case, there's no need to indulge in RCU or locking when accessing the payload. |
| |
| 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. |
| |
| 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. |
| |
| 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. |
| |
| 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:: |
| |
| rcu_read_lock() ... rcu_dereference() ... rcu_read_unlock() |
| |
| to read the pointer, and:: |
| |
| rcu_dereference() ... rcu_assign_pointer() ... call_rcu() |
| |
| to set the pointer and dispose of the old contents after a grace period. |
| Note that only the key type should ever modify a key's payload. |
| |
| Furthermore, an RCU controlled payload must hold a struct rcu_head for the |
| use of call_rcu() and, if the payload is of variable size, the length of |
| the payload. key->datalen cannot be relied upon to be consistent with the |
| payload just dereferenced if the key's semaphore is not held. |
| |
| Note that key->payload.data[0] has a shadow that is marked for __rcu |
| 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:: |
| |
| rcu_assign_keypointer(struct key *key, void *data); |
| |
| b) Read the first payload pointer with the key semaphore held:: |
| |
| [const] void *dereference_key_locked([const] struct key *key); |
| |
| Note that the return value will inherit its constness from the key |
| 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:: |
| |
| const void *dereference_key_rcu(const struct key *key); |
| |
| |
| 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:: |
| |
| <linux/key-type.h> |
| |
| The structure has a number of fields, some of which are mandatory: |
| |
| * ``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`` |
| |
| 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:: |
| |
| int key_payload_reserve(struct key *key, size_t datalen); |
| |
| With the revised data length. Error EDQUOT will be returned if this is not |
| viable. |
| |
| |
| * ``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);`` |
| |
| 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:: |
| |
| struct key_preparsed_payload { |
| char *description; |
| union key_payload payload; |
| const void *data; |
| size_t datalen; |
| size_t quotalen; |
| time_t expiry; |
| }; |
| |
| Before calling the method, the caller will fill in data and datalen with |
| the payload blob parameters; quotalen will be filled in with the default |
| quota size from the key type; expiry will be set to TIME_T_MAX and the |
| rest will be cleared. |
| |
| If a description can be proposed from the payload contents, that should be |
| attached as a string to the description field. This will be used for the |
| key description if the caller of add_key() passes NULL or "". |
| |
| The method can attach anything it likes to payload. This is merely passed |
| along to the instantiate() or update() operations. If set, the expiry |
| time will be applied to the key if it is instantiated from this data. |
| |
| The method should return 0 if successful or a negative error code |
| otherwise. |
| |
| |
| * ``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 |
| and payload fields of the key_preparsed_payload struct as filled in by the |
| preparse() method. It will always be called after preparse() returns |
| successfully, even if instantiate() or update() succeed. |
| |
| |
| * ``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 |
| function. |
| |
| The prep->data and prep->datalen fields will define the original payload |
| blob. If preparse() was supplied then other fields may be filled in also. |
| |
| If the amount of data attached to the key differs from the size in |
| keytype->def_datalen, then key_payload_reserve() should be called. |
| |
| This method does not have to lock the key in order to attach a payload. |
| The fact that KEY_FLAG_INSTANTIATED is not set in key->flags prevents |
| anything else from gaining access to the key. |
| |
| It is safe to sleep in this method. |
| |
| generic_key_instantiate() is provided to simply copy the data from |
| prep->payload.data[] to key->payload.data[], with RCU-safe assignment on |
| the first element. It will then clear prep->payload.data[] so that the |
| free_preparse method doesn't release the data. |
| |
| |
| * ``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. |
| |
| The prep->data and prep->datalen fields will define the original payload |
| blob. If preparse() was supplied then other fields may be filled in also. |
| |
| key_payload_reserve() should be called if the data length might change |
| before any changes are actually made. Note that if this succeeds, the type |
| is committed to changing the key because it's already been altered, so all |
| memory allocation must be done first. |
| |
| The key will have its semaphore write-locked before this method is called, |
| but this only deters other writers; any changes to the key's payload must |
| be made under RCU conditions, and call_rcu() must be used to dispose of |
| the old payload. |
| |
| key_payload_reserve() should be called before the changes are made, but |
| after all allocations and other potentially failing function calls are |
| made. |
| |
| It is safe to sleep in this method. |
| |
| |
| * ``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:: |
| |
| struct key_match_data { |
| bool (*cmp)(const struct key *key, |
| const struct key_match_data *match_data); |
| const void *raw_data; |
| void *preparsed; |
| unsigned lookup_type; |
| }; |
| |
| 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 |
| 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 |
| description to narrow down the search to a small number of keys. |
| |
| * 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. |
| |
| If preparsed is set, it may be necessary to use the match_free() method to |
| clean it up. |
| |
| 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 |
| 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);`` |
| |
| 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);`` |
| |
| 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 |
| write-locked. |
| |
| It is safe to sleep in this method, though care should be taken to avoid |
| a deadlock against the key semaphore. |
| |
| |
| * ``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. |
| |
| This method does not need to lock the key to access the payload; it can |
| consider the key as being inaccessible at this time. Note that the key's |
| type may have been changed before this function is called. |
| |
| It is not safe to sleep in this method; the caller may hold spinlocks. |
| |
| |
| * ``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. |
| |
| This method will be called with the RCU read lock held. rcu_dereference() |
| should be used to read the payload pointer if the payload is to be |
| accessed. key->datalen cannot be trusted to stay consistent with the |
| contents of the payload. |
| |
| The description will not change, though the key's state may. |
| |
| It is not safe to sleep in this method; the RCU read lock is held by the |
| caller. |
| |
| |
| * ``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. |
| Ideally, the blob should be in the same format as that passed in to the |
| instantiate and update methods. |
| |
| If successful, the blob size that could be produced should be returned |
| rather than the size copied. |
| |
| This method will be called with the key's semaphore read-locked. This will |
| prevent the key's payload changing. It is not necessary to use RCU locking |
| when accessing the key's payload. It is safe to sleep in this method, such |
| as might happen when the userspace buffer is accessed. |
| |
| |
| * ``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 |
| upon a key of this type. |
| |
| The aux parameter is as passed to request_key_async_with_auxdata() and |
| similar or is NULL otherwise. Also passed are the construction record for |
| the key to be operated upon and the operation type (currently only |
| "create"). |
| |
| 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:: |
| |
| void complete_request_key(struct key_construction *cons, int error); |
| |
| The error parameter should be 0 on success, -ve on error. The |
| construction record is destroyed by this action and the authorisation key |
| will be revoked. If an error is indicated, the key under construction |
| will be negatively instantiated if it wasn't already instantiated. |
| |
| If this method returns an error, that error will be returned to the |
| caller of request_key*(). complete_request_key() must be called prior to |
| returning. |
| |
| The key under construction and the authorisation key can be found in the |
| key_construction struct pointed to by cons: |
| |
| * ``struct key *key;`` |
| |
| The key under construction. |
| |
| * ``struct key *authkey;`` |
| |
| The authorisation key. |
| |
| |
| * ``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 |
| name) is passed in, and this method returns a pointer to a key_restriction |
| structure containing the relevant functions and data to evaluate each |
| attempted key link operation. If there is no match, -EINVAL is returned. |
| |
| |
| * ``int (*asym_eds_op)(struct kernel_pkey_params *params, |
| const void *in, void *out);`` |
| ``int (*asym_verify_signature)(struct kernel_pkey_params *params, |
| const void *in, const void *in2);`` |
| |
| These methods are optional. If provided the first allows a key to be |
| used to encrypt, decrypt or sign a blob of data, and the second allows a |
| key to verify a signature. |
| |
| In all cases, the following information is provided in the params block:: |
| |
| struct kernel_pkey_params { |
| struct key *key; |
| const char *encoding; |
| const char *hash_algo; |
| char *info; |
| __u32 in_len; |
| union { |
| __u32 out_len; |
| __u32 in2_len; |
| }; |
| enum kernel_pkey_operation op : 8; |
| }; |
| |
| This includes the key to be used; a string indicating the encoding to use |
| (for instance, "pkcs1" may be used with an RSA key to indicate |
| RSASSA-PKCS1-v1.5 or RSAES-PKCS1-v1.5 encoding or "raw" if no encoding); |
| the name of the hash algorithm used to generate the data for a signature |
| (if appropriate); the sizes of the input and output (or second input) |
| buffers; and the ID of the operation to be performed. |
| |
| For a given operation ID, the input and output buffers are used as |
| follows:: |
| |
| Operation ID in,in_len out,out_len in2,in2_len |
| ======================= =============== =============== =============== |
| kernel_pkey_encrypt Raw data Encrypted data - |
| kernel_pkey_decrypt Encrypted data Raw data - |
| kernel_pkey_sign Raw data Signature - |
| kernel_pkey_verify Raw data - Signature |
| |
| asym_eds_op() deals with encryption, decryption and signature creation as |
| specified by params->op. Note that params->op is also set for |
| asym_verify_signature(). |
| |
| Encrypting and signature creation both take raw data in the input buffer |
| and return the encrypted result in the output buffer. Padding may have |
| been added if an encoding was set. In the case of signature creation, |
| depending on the encoding, the padding created may need to indicate the |
| digest algorithm - the name of which should be supplied in hash_algo. |
| |
| Decryption takes encrypted data in the input buffer and returns the raw |
| data in the output buffer. Padding will get checked and stripped off if |
| an encoding was set. |
| |
| Verification takes raw data in the input buffer and the signature in the |
| second input buffer and checks that the one matches the other. Padding |
| will be validated. Depending on the encoding, the digest algorithm used |
| to generate the raw data may need to be indicated in hash_algo. |
| |
| If successful, asym_eds_op() should return the number of bytes written |
| into the output buffer. asym_verify_signature() should return 0. |
| |
| A variety of errors may be returned, including EOPNOTSUPP if the operation |
| is not supported; EKEYREJECTED if verification fails; ENOPKG if the |
| required crypto isn't available. |
| |
| |
| * ``int (*asym_query)(const struct kernel_pkey_params *params, |
| struct kernel_pkey_query *info);`` |
| |
| This method is optional. If provided it allows information about the |
| public or asymmetric key held in the key to be determined. |
| |
| The parameter block is as for asym_eds_op() and co. but in_len and out_len |
| are unused. The encoding and hash_algo fields should be used to reduce |
| the returned buffer/data sizes as appropriate. |
| |
| If successful, the following information is filled in:: |
| |
| struct kernel_pkey_query { |
| __u32 supported_ops; |
| __u32 key_size; |
| __u16 max_data_size; |
| __u16 max_sig_size; |
| __u16 max_enc_size; |
| __u16 max_dec_size; |
| }; |
| |
| The supported_ops field will contain a bitmask indicating what operations |
| are supported by the key, including encryption of a blob, decryption of a |
| blob, signing a blob and verifying the signature on a blob. The following |
| constants are defined for this:: |
| |
| KEYCTL_SUPPORTS_{ENCRYPT,DECRYPT,SIGN,VERIFY} |
| |
| The key_size field is the size of the key in bits. max_data_size and |
| max_sig_size are the maximum raw data and signature sizes for creation and |
| verification of a signature; max_enc_size and max_dec_size are the maximum |
| raw data and signature sizes for encryption and decryption. The |
| max_*_size fields are measured in bytes. |
| |
| If successful, 0 will be returned. If the key doesn't support this, |
| EOPNOTSUPP will be returned. |
| |
| |
| Request-Key Callback Service |
| ============================ |
| |
| To create a new key, the kernel will attempt to execute the following command |
| line:: |
| |
| /sbin/request-key create <key> <uid> <gid> \ |
| <threadring> <processring> <sessionring> <callout_info> |
| |
| <key> is the key being constructed, and the three keyrings are the process |
| 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 |
| required to obtain the key, eg: a Kerberos Ticket-Granting Ticket. |
| |
| 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 |
| hand the request off to (perhaps a path held in placed in another key by, for |
| example, the KDE desktop manager). |
| |
| The program (or whatever it calls) should finish construction of the key by |
| calling KEYCTL_INSTANTIATE or KEYCTL_INSTANTIATE_IOV, which also permits it to |
| cache the key in one of the keyrings (probably the session ring) before |
| returning. Alternatively, the key can be marked as negative with KEYCTL_NEGATE |
| or KEYCTL_REJECT; this also permits the key to be cached in one of the |
| keyrings. |
| |
| If it returns with the key remaining in the unconstructed state, the key will |
| be marked as being negative, it will be added to the session keyring, and an |
| error will be returned to the key requestor. |
| |
| Supplementary information may be provided from whoever or whatever invoked this |
| service. This will be passed as the <callout_info> parameter. If no such |
| information was made available, then "-" will be passed as this parameter |
| instead. |
| |
| |
| Similarly, the kernel may attempt to update an expired or a soon to expire key |
| by executing:: |
| |
| /sbin/request-key update <key> <uid> <gid> \ |
| <threadring> <processring> <sessionring> |
| |
| In this case, the program isn't required to actually attach the key to a ring; |
| the rings are provided for reference. |
| |
| |
| Garbage Collection |
| ================== |
| |
| Dead keys (for which the type has been removed) will be automatically unlinked |
| 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:: |
| |
| /proc/sys/kernel/keys/gc_delay |