Lines Matching full:key
2 Kernel Key Retention Service
9 Keyrings are permitted; these are a special type of key that can hold links to
13 The key service can be configured on by enabling:
15 "Security options"/"Enable access key retention support" (CONFIG_KEYS)
22 Key Overview
26 tokens, keyrings, etc.. These are represented in the kernel by struct key.
28 Each key has a number of attributes:
32 - A description (for matching a key in a search).
39 * Each key is issued a serial number of type key_serial_t that is unique for
40 the lifetime of that key. All serial numbers are positive non-zero 32-bit
43 Userspace programs can use a key's serial numbers as a way to gain access
46 * Each key is of a defined "type". Types must be registered inside the
50 Key types are represented in the kernel by struct key_type. This defines a
51 number of operations that can be performed on a key of that type.
56 * Each key has a description. This should be a printable string. The key
58 key and a criterion string.
60 * Each key has an owner user ID, a group ID and a permissions mask. These
61 are used to control what a process may do to a key from userspace, and
62 whether a kernel service will be able to find the key.
64 * Each key can be set to expire at a specific time by the key type's
67 * Each key can have a payload. This is a quantity of data that represent the
68 actual "key". In the case of a keyring, this is a list of keys to which
69 the keyring links; in the case of a user-defined key, it's an arbitrary
73 value stored in the struct key itself.
75 When a key is instantiated, the key type's instantiation function is
76 called with a blob of data, and that then creates the key's payload in
79 Similarly, when userspace wants to read back the contents of the key, if
80 permitted, another key type operation will be called to convert the key's
83 * Each key can be in one of a number of basic states:
85 * Uninstantiated. The key exists, but does not have any data attached.
88 * Instantiated. This is the normal state. The key is fully formed, and
91 * Negative. This is a relatively short-lived state. The key acts as a
93 a throttle on key lookups. A negative key can be updated to a normal
97 they traverse to this state. An expired key can be updated back to a
100 * Revoked. A key is put in this state by userspace action. It can't be
103 * Dead. The key's type was unregistered, and so the key is now useless.
109 Key Service Overview
112 The key service provides a number of features besides keys:
114 * The key service defines three special key types:
124 A key of this type has a description and a payload that are arbitrary
130 Like a "user" key, a "logon" key has a payload that is an arbitrary
135 length string that describes the key "subclass". The subclass is
165 When a process changes its real UID, if it used to have no session key, it
166 will be subscribed to the default session key for the new UID.
168 If a process attempts to access its session key when it doesn't have one,
182 If a system call that modifies a key or keyring in some way would put the
192 userspace to request a key that can't be found in a process's keyrings.
194 * An optional filesystem is available through which the key database can be
198 Key Access Permissions
207 This permits a key or keyring's attributes to be viewed - including key
212 This permits a key's payload to be viewed or a keyring's list of linked
217 This permits a key's payload to be instantiated or updated, or it allows a
227 This permits a key or keyring to be linked to. To create a link from a
228 keyring to a key, a process must have Write permission on the keyring and
229 Link permission on the key.
233 This permits a key's UID, GID and permissions mask to be changed.
236 the key or having the sysadmin capability is sufficient.
242 The security class "key" has been added to SELinux so that mandatory access
251 security context, then the key will be assigned that context. Otherwise, the
252 key will be assigned the current context of the task that invoked the key
255 key security class.
275 about the status of the key service:
281 It is not possible to view the payload of the key this way, though some
309 N Negative key
312 * /proc/key-users
314 This file lists the tracking data for each user that has at least one key
317 [root@andromeda root]# cat /proc/key-users
328 <keys>/<max> Key count quota
329 <bytes>/<max> Key size quota
360 When referring to a key directly, userspace programs should use the key's
365 CONSTANT VALUE KEY REFERENCED
374 authorisation key
379 * Create a new key of given type, description and payload and add it to the
386 If a key of the same type and description as that proposed already exists
388 will return error EEXIST if that function is not supported by the key
389 type. The process must also have permission to write to the key to be able
390 to update it. The new key will have all user permissions granted and no
393 Otherwise, this will attempt to create a new key of the specified type and
398 If the key type supports it, if the description is NULL or an empty
399 string, the key type will try and generate a description from the content
410 recommended that a user defined key's description by prefixed with a type
417 The ID of the new or updated key is returned if successful.
420 * Search the process's keyrings for a key, potentially calling out to
428 process, session for a matching key. This works very much like
429 KEYCTL_SEARCH, including the optional attachment of the discovered key to
432 If a key cannot be found, and if callout_info is not NULL, then
433 /sbin/request-key will be invoked in an attempt to obtain a key. The
436 To link a key into the destination keyring the key must grant link
437 permission on the key to the caller and the keyring must grant write
440 See also Documentation/security/keys/request-key.rst.
445 * Map a special key ID to a real key ID for this process::
450 The special key specified by "id" is looked up (with the key being created
451 if necessary) and the ID of the key or keyring thus found is returned if
454 If the key does not yet exist, the key will be created if "create" is
476 * Update the specified key::
478 long keyctl(KEYCTL_UPDATE, key_serial_t key, const void *payload,
481 This will try to update the specified key with the given payload, or it
482 will return error EOPNOTSUPP if that function is not supported by the key
483 type. The process must also have permission to write to the key to be able
490 * Revoke a key::
492 long keyctl(KEYCTL_REVOKE, key_serial_t key);
494 This makes a key unavailable for further operations. Further attempts to
495 use the key will be met with error EKEYREVOKED, and the key will no longer
499 * Change the ownership of a key::
501 long keyctl(KEYCTL_CHOWN, key_serial_t key, uid_t uid, gid_t gid);
503 This function permits a key's owner and group ID to be changed. Either one
506 Only the superuser can change a key's owner to something other than the
507 key's current owner. Similarly, only the superuser can change a key's
512 * Change the permissions mask on a key::
514 long keyctl(KEYCTL_SETPERM, key_serial_t key, key_perm_t perm);
516 This function permits the owner of a key or the superuser to change the
517 permissions mask on a key.
523 * Describe a key::
525 long keyctl(KEYCTL_DESCRIBE, key_serial_t key, char *buffer,
528 This function returns a summary of the key's attributes (but not its
536 A process must have view permission on the key for this function to be
565 * Link a key into a keyring::
567 long keyctl(KEYCTL_LINK, key_serial_t keyring, key_serial_t key);
569 This function creates a link from the keyring to the key. The process must
571 key.
579 Any links within the keyring to keys that match the new key in terms of
584 * Move a key from one keyring to another::
592 Move the key specified by "id" from the keyring specified by
597 with EEXIST if a matching key exists in the destination keyring, otherwise
598 such a key will be replaced.
600 A process must have link permission on the key for this function to be
605 * Unlink a key or keyring from another keyring::
607 long keyctl(KEYCTL_UNLINK, key_serial_t keyring, key_serial_t key);
610 specified key, and removes it if found. Subsequent links to that key are
613 If the keyring is not a keyring, error ENOTDIR will result; and if the key
617 * Search a keyring tree for a key::
623 This searches the keyring tree headed by the specified keyring until a key
633 If the search succeeds, the function will attempt to link the found key
638 fails. On success, the resulting key ID will be returned.
641 * Read the payload data from a key::
646 This function attempts to read the payload data from the specified key
647 into the buffer. The process must have read permission on the key to
650 The returned data will be processed for presentation by the key type. For
653 defined key type will return its data as is. If a key type does not
663 * Instantiate a partially constructed key::
665 long keyctl(KEYCTL_INSTANTIATE, key_serial_t key,
668 long keyctl(KEYCTL_INSTANTIATE_IOV, key_serial_t key,
673 key, userspace should use this call to supply data for the key before the
674 invoked process returns, or else the key will be marked negative
677 The process must have write access on the key to be able to instantiate
678 it, and the key must be uninstantiated.
680 If a keyring is specified (non-zero), the key will also be linked into
690 * Negatively instantiate a partially constructed key::
692 long keyctl(KEYCTL_NEGATE, key_serial_t key,
694 long keyctl(KEYCTL_REJECT, key_serial_t key,
698 key, userspace should use this call mark the key as negative before the
701 The process must have write access on the key to be able to instantiate
702 it, and the key must be uninstantiated.
704 If a keyring is specified (non-zero), the key will also be linked into
708 If the key is rejected, future searches for it will return the specified
709 error code until the rejected key expires. Negating the key is the same
710 as rejecting the key with ENOKEY as the error code.
713 * Set the default request-key destination keyring::
744 * Set the timeout on a key::
746 long keyctl(KEYCTL_SET_TIMEOUT, key_serial_t key, unsigned timeout);
748 This sets or clears the timeout on a key. The timeout can be 0 to clear
752 The process must have attribute modification access on a key to set its
757 * Assume the authority granted to instantiate a key::
759 long keyctl(KEYCTL_ASSUME_AUTHORITY, key_serial_t key);
762 specified key. Authority can only be assumed if the thread has the
763 authorisation key associated with the specified key in its keyrings
771 likewise if the authority has been revoked because the target key is
774 If the specified key is 0, then any assumed authority will be divested.
776 The assumed authoritative key is inherited across fork and exec.
779 * Get the LSM security context attached to a key::
781 long keyctl(KEYCTL_GET_SECURITY, key_serial_t key, char *buffer,
785 attached to a key in the buffer provided.
796 A process must have view permission on the key for this function to be
820 * Invalidate a key::
822 long keyctl(KEYCTL_INVALIDATE, key_serial_t key);
824 This function marks a key as being invalidated and then wakes up the
826 keys from all keyrings and deletes the key when its reference count
829 Keys that are marked invalidated become invisible to normal key operations
833 A process must have search permission on the key for this function to be
836 * Compute a Diffie-Hellman shared secret or public key::
844 - The local private key
846 remote public key
853 public key. If the base is the remote public key, the result is
865 The kdf parameter allows the caller to apply a key derivation function
880 This function will return error EOPNOTSUPP if the key type is not
881 supported, error ENOKEY if the key could not be found, or error
882 EACCES if the key is not readable by the caller. In addition, the
894 the contents of the key according to a restriction scheme.
896 "keyring" is the key ID for an existing keyring to apply a restriction
900 "type" is a registered key type.
902 "restriction" is a string describing how key linkage is to be restricted.
903 The format varies depending on the key type, and the string is passed to
906 verification or constraints on key payload. If the requested key type is
907 later unregistered, no keys may be added to the keyring after the key type
914 chains or individual certificate signatures using the asymmetric key type.
916 applicable to the asymmetric key type.
919 * Query an asymmetric key::
925 Get information about an asymmetric key. The information is returned in
941 ``key_size`` indicated the size of the key in bits.
948 over one or more passphrases needed unlock a key.
950 If successful, 0 is returned. If the key is not an asymmetric key,
954 * Encrypt, decrypt, sign or verify a blob using an asymmetric key::
980 Use an asymmetric key to perform a public-key cryptographic operation a
981 blob of data. For encryption and verification, the asymmetric key may
993 ``key_id`` is the ID of the asymmetric key to be used. ``in_len`` and
1007 ``info`` is a string of key=value pairs that supply supplementary
1023 required to unlock a key.
1032 The kernel services for key management are fairly simple to deal with. They can
1033 be broken down into two areas: keys and key types.
1036 registers its type, then it searches for a key of that type. It should retain
1037 the key as long as it has need of it, and then it should release it. For a
1039 call, and the key released upon close. How to deal with conflicting keys due to
1043 To access the key manager, the following header must be #included::
1045 <linux/key.h>
1047 Specific key types should have a header file under include/keys/ that should be
1055 * struct key *
1057 This simply points to the key structure itself. Key structures will be at
1062 This is equivalent to a ``struct key *``, but the least significant bit is set
1063 if the caller "possesses" the key. By "possession" it is meant that the
1064 calling processes has a searchable link to the key from one of its
1067 key_ref_t make_key_ref(const struct key *key, bool possession);
1069 struct key *key_ref_to_ptr(const key_ref_t key_ref);
1073 The first function constructs a key reference from a key pointer and
1076 The second function retrieves the key pointer from a reference and the
1079 When accessing a key's payload contents, certain precautions must be taken to
1083 * To search for a key, call::
1085 struct key *request_key(const struct key_type *type,
1089 This is used to request a key or keyring with a description that matches
1090 the description specified according to the key type's match_preparse()
1092 not NULL, then /sbin/request-key will be invoked in an attempt to obtain
1093 the key from userspace. In that case, callout_string will be passed as an
1099 If successful, the key will have been attached to the default keyring for
1100 implicitly obtained request-key keys, as set by KEYCTL_SET_REQKEY_KEYRING.
1102 See also Documentation/security/keys/request-key.rst.
1105 * To search for a key in a specific domain, call:
1107 struct key *request_key_tag(const struct key_type *type,
1118 * To search for a key, passing auxiliary data to the upcaller, call::
1120 struct key *request_key_with_auxdata(const struct key_type *type,
1133 * To search for a key under RCU conditions, call::
1135 struct key *request_key_rcu(const struct key_type *type,
1141 construct a key if it can't find a match.
1144 * When it is no longer required, the key should be released using::
1146 void key_put(struct key *key);
1156 * Extra references can be made to a key by calling one of the following
1159 struct key *__key_get(struct key *key);
1160 struct key *key_get(struct key *key);
1163 they've been finished with. The key pointer passed in will be returned.
1166 then the key will not be dereferenced and no increment will take place.
1169 * A key's serial number can be obtained by calling::
1171 key_serial_t key_serial(struct key *key);
1173 If key is NULL or if CONFIG_KEYS is not set then 0 will be returned (in the
1185 (recurse == true) specified for a matching key. Error ENOKEY is returned
1187 key will need to be released.
1190 access through the permissions mask and is propagated to the returned key
1196 struct key *keyring_alloc(const char *description, uid_t uid, gid_t gid,
1201 struct key *dest);
1213 key into the new keyring. The structure may also contain a key pointer
1214 and an associated key type. The function is called to check whether a key
1215 may be added into the keyring or not. The key type is used by the garbage
1217 given key type is unregistered. Callers of key_create_or_update() within
1221 - provided they can be verified by a key the kernel already has.
1224 added to, the key type, the payload of the key being added, and data to be
1225 used in the restriction check. Note that when a new key is being created,
1226 this is called between payload preparsing and actual key creation. The
1233 * To check the validity of a key, this function can be called::
1235 int validate_key(struct key *key);
1237 This checks that the key in question hasn't expired or and hasn't been
1238 revoked. Should the key be invalid, error EKEYEXPIRED or EKEYREVOKED will
1239 be returned. If the key is NULL or if CONFIG_KEYS is not set then 0 will be
1243 * To register a key type, the following function should be called::
1251 * To unregister a key type, call::
1270 The simplest payload is just data stored in key->payload directly. In this
1274 key->payload.data[] array. One of the following ways must be selected to
1277 1) Unmodifiable key type.
1279 If the key type does not have a modify method, then the key's payload can
1283 2) The key's semaphore.
1294 semaphore must still be used to serialise modifications to the key. The
1295 key management code takes care of this for the key type.
1306 Note that only the key type should ever modify a key's payload.
1310 the payload. key->datalen cannot be relied upon to be consistent with the
1311 payload just dereferenced if the key's semaphore is not held.
1313 Note that key->payload.data[0] has a shadow that is marked for __rcu
1314 usage. This is called key->payload.rcu_data0. The following accessors
1319 rcu_assign_keypointer(struct key *key, void *data);
1321 b) Read the first payload pointer with the key semaphore held::
1323 [const] void *dereference_key_locked([const] struct key *key);
1325 Note that the return value will inherit its constness from the key
1331 const void *dereference_key_rcu(const struct key *key);
1334 Defining a Key Type
1337 A kernel service may want to define its own key type. For instance, an AFS
1338 filesystem might want to define a Kerberos 5 ticket key type. To do this, it
1341 Source files that implement key types should include the following header file::
1343 <linux/key-type.h>
1349 The name of the key type. This is used to translate a key type name
1356 contributed to the quota. If the key type's payload is always or almost
1359 The data length (and quota) on a particular key can always be changed
1362 int key_payload_reserve(struct key *key, size_t datalen);
1370 This optional method is called to vet a key description. If the key type
1371 doesn't approve of the key description, it may return an error, otherwise
1377 This optional method permits the key type to attempt to parse payload
1378 before a key is created (add key) or the key semaphore is taken (update or
1379 instantiate key). The structure pointed to by prep looks like::
1392 quota size from the key type; expiry will be set to TIME_T_MAX and the
1397 key description if the caller of add_key() passes NULL or "".
1401 time will be applied to the key if it is instantiated from this data.
1416 * ``int (*instantiate)(struct key *key, struct key_preparsed_payload *prep);``
1418 This method is called to attach a payload to a key during construction.
1425 If the amount of data attached to the key differs from the size in
1428 This method does not have to lock the key in order to attach a payload.
1429 The fact that KEY_FLAG_INSTANTIATED is not set in key->flags prevents
1430 anything else from gaining access to the key.
1435 prep->payload.data[] to key->payload.data[], with RCU-safe assignment on
1440 * ``int (*update)(struct key *key, const void *data, size_t datalen);``
1442 If this type of key can be updated, then this method should be provided.
1443 It is called to update a key's payload from the blob of data provided.
1450 is committed to changing the key because it's already been altered, so all
1453 The key will have its semaphore write-locked before this method is called,
1454 but this only deters other writers; any changes to the key's payload must
1467 This method is optional. It is called when a key search is about to be
1471 bool (*cmp)(const struct key *key,
1479 a key by the caller and should not be modified. ``(*cmp)()`` will be pointing
1490 search that's not doing a simple direct match on the key description.
1495 ``(*cmp)()`` should return true if a key matches and false otherwise.
1516 * ``void (*revoke)(struct key *key);``
1519 data upon a key being revoked. The caller will have the key semaphore
1523 a deadlock against the key semaphore.
1526 * ``void (*destroy)(struct key *key);``
1528 This method is optional. It is called to discard the payload data on a key
1531 This method does not need to lock the key to access the payload; it can
1532 consider the key as being inaccessible at this time. Note that the key's
1538 * ``void (*describe)(const struct key *key, struct seq_file *p);``
1541 summarise a key's description and payload in text form.
1545 accessed. key->datalen cannot be trusted to stay consistent with the
1548 The description will not change, though the key's state may.
1554 * ``long (*read)(const struct key *key, char __user *buffer, size_t buflen);``
1557 key's payload into something a blob of data for userspace to deal with.
1564 This method will be called with the key's semaphore read-locked. This will
1565 prevent the key's payload changing. It is not necessary to use RCU locking
1566 when accessing the key's payload. It is safe to sleep in this method, such
1573 invoke this function rather than upcalling to /sbin/request-key to operate
1574 upon a key of this type.
1578 the key to be operated upon and the operation type (currently only
1589 construction record is destroyed by this action and the authorisation key
1590 will be revoked. If an error is indicated, the key under construction
1597 The key under construction and the authorisation key can be found in the
1600 * ``struct key *key;``
1602 The key under construction.
1604 * ``struct key *authkey;``
1606 The authorisation key.
1612 restrictions. The restriction parameter string (not including the key type
1615 attempted key link operation. If there is no match, -EINVAL is returned.
1625 These methods are optional. If provided the first allows a key to be
1627 key to verify a signature.
1632 struct key *key;
1644 This includes the key to be used; a string indicating the encoding to use
1645 (for instance, "pkcs1" may be used with an RSA key to indicate
1694 public or asymmetric key held in the key to be determined.
1712 are supported by the key, including encryption of a blob, decryption of a
1718 The key_size field is the size of the key in bits. max_data_size and
1724 If successful, 0 will be returned. If the key doesn't support this,
1728 Request-Key Callback Service
1731 To create a new key, the kernel will attempt to execute the following command
1734 /sbin/request-key create <key> <uid> <gid> \
1737 <key> is the key being constructed, and the three keyrings are the process
1742 required to obtain the key, eg: a Kerberos Ticket-Granting Ticket.
1744 2 The new key should probably be cached in one of these rings.
1748 hand the request off to (perhaps a path held in placed in another key by, for
1751 The program (or whatever it calls) should finish construction of the key by
1753 cache the key in one of the keyrings (probably the session ring) before
1754 returning. Alternatively, the key can be marked as negative with KEYCTL_NEGATE
1755 or KEYCTL_REJECT; this also permits the key to be cached in one of the
1758 If it returns with the key remaining in the unconstructed state, the key will
1760 error will be returned to the key requestor.
1768 Similarly, the kernel may attempt to update an expired or a soon to expire key
1771 /sbin/request-key update <key> <uid> <gid> \
1774 In this case, the program isn't required to actually attach the key to a ring;