Lines Matching refs:key
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)
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
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.
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
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
360 When referring to a key directly, userspace programs should use the key's
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::
926 Get information about an asymmetric key. Specific algorithms and
928 string containing a space- or tab-separated string of key-value pairs.
945 ``key_size`` indicated the size of the key in bits.
952 over one or more passphrases needed unlock a key.
954 If successful, 0 is returned. If the key is not an asymmetric key,
958 * Encrypt, decrypt, sign or verify a blob using an asymmetric key::
984 Use an asymmetric key to perform a public-key cryptographic operation a
985 blob of data. For encryption and verification, the asymmetric key may
997 ``key_id`` is the ID of the asymmetric key to be used. ``in_len`` and
1011 ``info`` is a string of key=value pairs that supply supplementary
1027 required to unlock a key.
1033 * Watch a key or keyring for changes::
1035 long keyctl(KEYCTL_WATCH_KEY, key_serial_t key, int queue_fd,
1038 This will set or remove a watch for changes on the specified key or
1041 "key" is the ID of the key to be watched.
1047 indicate what events are required from the key.
1051 Note that only one watch may be emplaced for any particular { key,
1074 Where these indicate a key being instantiated/rejected, updated, a link
1076 being cleared, a key being revoked, a key being invalidated or a key
1080 If a watched key is deleted, a basic watch_notification will be issued
1087 "Provide key/keyring change notifications" (KEY_NOTIFICATIONS)
1093 The kernel services for key management are fairly simple to deal with. They can
1094 be broken down into two areas: keys and key types.
1097 registers its type, then it searches for a key of that type. It should retain
1098 the key as long as it has need of it, and then it should release it. For a
1100 call, and the key released upon close. How to deal with conflicting keys due to
1104 To access the key manager, the following header must be #included::
1106 <linux/key.h>
1108 Specific key types should have a header file under include/keys/ that should be
1116 * struct key *
1118 This simply points to the key structure itself. Key structures will be at
1123 This is equivalent to a ``struct key *``, but the least significant bit is set
1124 if the caller "possesses" the key. By "possession" it is meant that the
1125 calling processes has a searchable link to the key from one of its
1128 key_ref_t make_key_ref(const struct key *key, bool possession);
1130 struct key *key_ref_to_ptr(const key_ref_t key_ref);
1134 The first function constructs a key reference from a key pointer and
1137 The second function retrieves the key pointer from a reference and the
1140 When accessing a key's payload contents, certain precautions must be taken to
1144 * To search for a key, call::
1146 struct key *request_key(const struct key_type *type,
1150 This is used to request a key or keyring with a description that matches
1151 the description specified according to the key type's match_preparse()
1153 not NULL, then /sbin/request-key will be invoked in an attempt to obtain
1154 the key from userspace. In that case, callout_string will be passed as an
1160 If successful, the key will have been attached to the default keyring for
1161 implicitly obtained request-key keys, as set by KEYCTL_SET_REQKEY_KEYRING.
1163 See also Documentation/security/keys/request-key.rst.
1166 * To search for a key in a specific domain, call::
1168 struct key *request_key_tag(const struct key_type *type,
1179 * To search for a key, passing auxiliary data to the upcaller, call::
1181 struct key *request_key_with_auxdata(const struct key_type *type,
1194 * To search for a key under RCU conditions, call::
1196 struct key *request_key_rcu(const struct key_type *type,
1202 construct a key if it can't find a match.
1205 * When it is no longer required, the key should be released using::
1207 void key_put(struct key *key);
1217 * Extra references can be made to a key by calling one of the following
1220 struct key *__key_get(struct key *key);
1221 struct key *key_get(struct key *key);
1224 they've been finished with. The key pointer passed in will be returned.
1227 then the key will not be dereferenced and no increment will take place.
1230 * A key's serial number can be obtained by calling::
1232 key_serial_t key_serial(struct key *key);
1234 If key is NULL or if CONFIG_KEYS is not set then 0 will be returned (in the
1246 (recurse == true) specified for a matching key. Error ENOKEY is returned
1248 key will need to be released.
1251 access through the permissions mask and is propagated to the returned key
1257 struct key *keyring_alloc(const char *description, uid_t uid, gid_t gid,
1262 struct key *dest);
1274 key into the new keyring. The structure may also contain a key pointer
1275 and an associated key type. The function is called to check whether a key
1276 may be added into the keyring or not. The key type is used by the garbage
1278 given key type is unregistered. Callers of key_create_or_update() within
1282 - provided they can be verified by a key the kernel already has.
1285 added to, the key type, the payload of the key being added, and data to be
1286 used in the restriction check. Note that when a new key is being created,
1287 this is called between payload preparsing and actual key creation. The
1294 * To check the validity of a key, this function can be called::
1296 int validate_key(struct key *key);
1298 This checks that the key in question hasn't expired or and hasn't been
1299 revoked. Should the key be invalid, error EKEYEXPIRED or EKEYREVOKED will
1300 be returned. If the key is NULL or if CONFIG_KEYS is not set then 0 will be
1304 * To register a key type, the following function should be called::
1312 * To unregister a key type, call::
1331 The simplest payload is just data stored in key->payload directly. In this
1335 key->payload.data[] array. One of the following ways must be selected to
1338 1) Unmodifiable key type.
1340 If the key type does not have a modify method, then the key's payload can
1344 2) The key's semaphore.
1355 semaphore must still be used to serialise modifications to the key. The
1356 key management code takes care of this for the key type.
1367 Note that only the key type should ever modify a key's payload.
1371 the payload. key->datalen cannot be relied upon to be consistent with the
1372 payload just dereferenced if the key's semaphore is not held.
1374 Note that key->payload.data[0] has a shadow that is marked for __rcu
1375 usage. This is called key->payload.rcu_data0. The following accessors
1380 rcu_assign_keypointer(struct key *key, void *data);
1382 b) Read the first payload pointer with the key semaphore held::
1384 [const] void *dereference_key_locked([const] struct key *key);
1386 Note that the return value will inherit its constness from the key
1392 const void *dereference_key_rcu(const struct key *key);
1398 A kernel service may want to define its own key type. For instance, an AFS
1399 filesystem might want to define a Kerberos 5 ticket key type. To do this, it
1402 Source files that implement key types should include the following header file::
1404 <linux/key-type.h>
1410 The name of the key type. This is used to translate a key type name
1417 contributed to the quota. If the key type's payload is always or almost
1420 The data length (and quota) on a particular key can always be changed
1423 int key_payload_reserve(struct key *key, size_t datalen);
1431 This optional method is called to vet a key description. If the key type
1432 doesn't approve of the key description, it may return an error, otherwise
1438 This optional method permits the key type to attempt to parse payload
1439 before a key is created (add key) or the key semaphore is taken (update or
1440 instantiate key). The structure pointed to by prep looks like::
1453 quota size from the key type; expiry will be set to TIME_T_MAX and the
1458 key description if the caller of add_key() passes NULL or "".
1462 time will be applied to the key if it is instantiated from this data.
1477 * ``int (*instantiate)(struct key *key, struct key_preparsed_payload *prep);``
1479 This method is called to attach a payload to a key during construction.
1486 If the amount of data attached to the key differs from the size in
1489 This method does not have to lock the key in order to attach a payload.
1490 The fact that KEY_FLAG_INSTANTIATED is not set in key->flags prevents
1491 anything else from gaining access to the key.
1496 prep->payload.data[] to key->payload.data[], with RCU-safe assignment on
1501 * ``int (*update)(struct key *key, const void *data, size_t datalen);``
1503 If this type of key can be updated, then this method should be provided.
1504 It is called to update a key's payload from the blob of data provided.
1511 is committed to changing the key because it's already been altered, so all
1514 The key will have its semaphore write-locked before this method is called,
1515 but this only deters other writers; any changes to the key's payload must
1528 This method is optional. It is called when a key search is about to be
1532 bool (*cmp)(const struct key *key,
1540 a key by the caller and should not be modified. ``(*cmp)()`` will be pointing
1551 search that's not doing a simple direct match on the key description.
1556 ``(*cmp)()`` should return true if a key matches and false otherwise.
1577 * ``void (*revoke)(struct key *key);``
1580 data upon a key being revoked. The caller will have the key semaphore
1584 a deadlock against the key semaphore.
1587 * ``void (*destroy)(struct key *key);``
1589 This method is optional. It is called to discard the payload data on a key
1592 This method does not need to lock the key to access the payload; it can
1593 consider the key as being inaccessible at this time. Note that the key's
1599 * ``void (*describe)(const struct key *key, struct seq_file *p);``
1602 summarise a key's description and payload in text form.
1606 accessed. key->datalen cannot be trusted to stay consistent with the
1609 The description will not change, though the key's state may.
1615 * ``long (*read)(const struct key *key, char __user *buffer, size_t buflen);``
1618 key's payload into something a blob of data for userspace to deal with.
1625 This method will be called with the key's semaphore read-locked. This will
1626 prevent the key's payload changing. It is not necessary to use RCU locking
1627 when accessing the key's payload. It is safe to sleep in this method, such
1634 invoke this function rather than upcalling to /sbin/request-key to operate
1635 upon a key of this type.
1639 the key to be operated upon and the operation type (currently only
1650 construction record is destroyed by this action and the authorisation key
1651 will be revoked. If an error is indicated, the key under construction
1658 The key under construction and the authorisation key can be found in the
1661 * ``struct key *key;``
1663 The key under construction.
1665 * ``struct key *authkey;``
1667 The authorisation key.
1673 restrictions. The restriction parameter string (not including the key type
1676 attempted key link operation. If there is no match, -EINVAL is returned.
1686 These methods are optional. If provided the first allows a key to be
1688 key to verify a signature.
1693 struct key *key;
1705 This includes the key to be used; a string indicating the encoding to use
1706 (for instance, "pkcs1" may be used with an RSA key to indicate
1755 public or asymmetric key held in the key to be determined.
1773 are supported by the key, including encryption of a blob, decryption of a
1779 The key_size field is the size of the key in bits. max_data_size and
1785 If successful, 0 will be returned. If the key doesn't support this,
1792 To create a new key, the kernel will attempt to execute the following command
1795 /sbin/request-key create <key> <uid> <gid> \
1798 <key> is the key being constructed, and the three keyrings are the process
1803 required to obtain the key, eg: a Kerberos Ticket-Granting Ticket.
1805 2 The new key should probably be cached in one of these rings.
1809 hand the request off to (perhaps a path held in placed in another key by, for
1812 The program (or whatever it calls) should finish construction of the key by
1814 cache the key in one of the keyrings (probably the session ring) before
1815 returning. Alternatively, the key can be marked as negative with KEYCTL_NEGATE
1816 or KEYCTL_REJECT; this also permits the key to be cached in one of the
1819 If it returns with the key remaining in the unconstructed state, the key will
1821 error will be returned to the key requestor.
1829 Similarly, the kernel may attempt to update an expired or a soon to expire key
1832 /sbin/request-key update <key> <uid> <gid> \
1835 In this case, the program isn't required to actually attach the key to a ring;