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)
27 - Defining a key type
28 - Request-key callback service
37 tokens, keyrings, etc.. These are represented in the kernel by struct key.
39 Each key has a number of attributes:
43 - A description (for matching a key in a search).
50 (*) Each key is issued a serial number of type key_serial_t that is unique for
51 the lifetime of that key. All serial numbers are positive non-zero 32-bit
54 Userspace programs can use a key's serial numbers as a way to gain access
57 (*) Each key is of a defined "type". Types must be registered inside the
62 number of operations that can be performed on a key of that type.
67 (*) Each key has a description. This should be a printable string. The key
69 key and a criterion string.
71 (*) Each key has an owner user ID, a group ID and a permissions mask. These
72 are used to control what a process may do to a key from userspace, and
73 whether a kernel service will be able to find the key.
75 (*) Each key can be set to expire at a specific time by the key type's
78 (*) Each key can have a payload. This is a quantity of data that represent the
79 actual "key". In the case of a keyring, this is a list of keys to which
80 the keyring links; in the case of a user-defined key, it's an arbitrary
84 value stored in the struct key itself.
86 When a key is instantiated, the key type's instantiation function is
87 called with a blob of data, and that then creates the key's payload in
90 Similarly, when userspace wants to read back the contents of the key, if
91 permitted, another key type operation will be called to convert the key's
94 (*) Each key can be in one of a number of basic states:
96 (*) Uninstantiated. The key exists, but does not have any data attached.
99 (*) Instantiated. This is the normal state. The key is fully formed, and
102 (*) Negative. This is a relatively short-lived state. The key acts as a
104 a throttle on key lookups. A negative key can be updated to a normal
108 they traverse to this state. An expired key can be updated back to a
111 (*) Revoked. A key is put in this state by userspace action. It can't be
114 (*) Dead. The key's type was unregistered, and so the key is now useless.
124 The key service provides a number of features besides keys:
126 (*) The key service defines three special key types:
136 A key of this type has a description and a payload that are arbitrary
142 Like a "user" key, a "logon" key has a payload that is an arbitrary
147 length string that describes the key "subclass". The subclass is
177 When a process changes its real UID, if it used to have no session key, it
178 will be subscribed to the default session key for the new UID.
180 If a process attempts to access its session key when it doesn't have one,
194 If a system call that modifies a key or keyring in some way would put the
204 userspace to request a key that can't be found in a process's keyrings.
206 (*) An optional filesystem is available through which the key database can be
220 This permits a key or keyring's attributes to be viewed - including key
225 This permits a key's payload to be viewed or a keyring's list of linked
230 This permits a key's payload to be instantiated or updated, or it allows a
240 This permits a key or keyring to be linked to. To create a link from a
241 keyring to a key, a process must have Write permission on the keyring and
242 Link permission on the key.
246 This permits a key's UID, GID and permissions mask to be changed.
249 the key or having the sysadmin capability is sufficient.
256 The security class "key" has been added to SELinux so that mandatory access
265 security context, then the key will be assigned that context. Otherwise, the
266 key will be assigned the current context of the task that invoked the key
269 key security class.
290 about the status of the key service:
296 It is not possible to view the payload of the key this way, though some
324 N Negative key
327 (*) /proc/key-users
329 This file lists the tracking data for each user that has at least one key
332 [root@andromeda root]# cat /proc/key-users
375 When referring to a key directly, userspace programs should use the key's
389 authorisation key
394 (*) Create a new key of given type, description and payload and add it to the
401 If a key of the same type and description as that proposed already exists
403 will return error EEXIST if that function is not supported by the key
404 type. The process must also have permission to write to the key to be able
405 to update it. The new key will have all user permissions granted and no
408 Otherwise, this will attempt to create a new key of the specified type and
413 If the key type supports it, if the description is NULL or an empty
414 string, the key type will try and generate a description from the content
425 recommended that a user defined key's description by prefixed with a type
432 The ID of the new or updated key is returned if successful.
435 (*) Search the process's keyrings for a key, potentially calling out to
443 process, session for a matching key. This works very much like
444 KEYCTL_SEARCH, including the optional attachment of the discovered key to
447 If a key cannot be found, and if callout_info is not NULL, then
448 /sbin/request-key will be invoked in an attempt to obtain a key. The
451 See also Documentation/security/keys-request-key.txt.
456 (*) Map a special key ID to a real key ID for this process:
461 The special key specified by "id" is looked up (with the key being created
462 if necessary) and the ID of the key or keyring thus found is returned if
465 If the key does not yet exist, the key will be created if "create" is
487 (*) Update the specified key:
489 long keyctl(KEYCTL_UPDATE, key_serial_t key, const void *payload,
492 This will try to update the specified key with the given payload, or it
493 will return error EOPNOTSUPP if that function is not supported by the key
494 type. The process must also have permission to write to the key to be able
501 (*) Revoke a key:
503 long keyctl(KEYCTL_REVOKE, key_serial_t key);
505 This makes a key unavailable for further operations. Further attempts to
506 use the key will be met with error EKEYREVOKED, and the key will no longer
510 (*) Change the ownership of a key:
512 long keyctl(KEYCTL_CHOWN, key_serial_t key, uid_t uid, gid_t gid);
514 This function permits a key's owner and group ID to be changed. Either one
517 Only the superuser can change a key's owner to something other than the
518 key's current owner. Similarly, only the superuser can change a key's
523 (*) Change the permissions mask on a key:
525 long keyctl(KEYCTL_SETPERM, key_serial_t key, key_perm_t perm);
527 This function permits the owner of a key or the superuser to change the
528 permissions mask on a key.
534 (*) Describe a key:
536 long keyctl(KEYCTL_DESCRIBE, key_serial_t key, char *buffer,
539 This function returns a summary of the key's attributes (but not its
547 A process must have view permission on the key for this function to be
576 (*) Link a key into a keyring:
578 long keyctl(KEYCTL_LINK, key_serial_t keyring, key_serial_t key);
580 This function creates a link from the keyring to the key. The process must
582 key.
590 Any links within the keyring to keys that match the new key in terms of
595 (*) Unlink a key or keyring from another keyring:
597 long keyctl(KEYCTL_UNLINK, key_serial_t keyring, key_serial_t key);
600 specified key, and removes it if found. Subsequent links to that key are
603 If the keyring is not a keyring, error ENOTDIR will result; and if the key
607 (*) Search a keyring tree for a key:
613 This searches the keyring tree headed by the specified keyring until a key
623 If the search succeeds, the function will attempt to link the found key
628 fails. On success, the resulting key ID will be returned.
631 (*) Read the payload data from a key:
636 This function attempts to read the payload data from the specified key
637 into the buffer. The process must have read permission on the key to
640 The returned data will be processed for presentation by the key type. For
643 defined key type will return its data as is. If a key type does not
653 (*) Instantiate a partially constructed key.
655 long keyctl(KEYCTL_INSTANTIATE, key_serial_t key,
658 long keyctl(KEYCTL_INSTANTIATE_IOV, key_serial_t key,
663 key, userspace should use this call to supply data for the key before the
664 invoked process returns, or else the key will be marked negative
667 The process must have write access on the key to be able to instantiate
668 it, and the key must be uninstantiated.
670 If a keyring is specified (non-zero), the key will also be linked into
680 (*) Negatively instantiate a partially constructed key.
682 long keyctl(KEYCTL_NEGATE, key_serial_t key,
684 long keyctl(KEYCTL_REJECT, key_serial_t key,
688 key, userspace should use this call mark the key as negative before the
691 The process must have write access on the key to be able to instantiate
692 it, and the key must be uninstantiated.
694 If a keyring is specified (non-zero), the key will also be linked into
698 If the key is rejected, future searches for it will return the specified
699 error code until the rejected key expires. Negating the key is the same
700 as rejecting the key with ENOKEY as the error code.
703 (*) Set the default request-key destination keyring.
734 (*) Set the timeout on a key.
736 long keyctl(KEYCTL_SET_TIMEOUT, key_serial_t key, unsigned timeout);
738 This sets or clears the timeout on a key. The timeout can be 0 to clear
742 The process must have attribute modification access on a key to set its
747 (*) Assume the authority granted to instantiate a key
749 long keyctl(KEYCTL_ASSUME_AUTHORITY, key_serial_t key);
752 specified key. Authority can only be assumed if the thread has the
753 authorisation key associated with the specified key in its keyrings
761 likewise if the authority has been revoked because the target key is
764 If the specified key is 0, then any assumed authority will be divested.
766 The assumed authoritative key is inherited across fork and exec.
769 (*) Get the LSM security context attached to a key.
771 long keyctl(KEYCTL_GET_SECURITY, key_serial_t key, char *buffer,
775 attached to a key in the buffer provided.
786 A process must have view permission on the key for this function to be
810 (*) Invalidate a key.
812 long keyctl(KEYCTL_INVALIDATE, key_serial_t key);
814 This function marks a key as being invalidated and then wakes up the
816 keys from all keyrings and deletes the key when its reference count
819 Keys that are marked invalidated become invisible to normal key operations
823 A process must have search permission on the key for this function to be
831 The kernel services for key management are fairly simple to deal with. They can
832 be broken down into two areas: keys and key types.
835 registers its type, then it searches for a key of that type. It should retain
836 the key as long as it has need of it, and then it should release it. For a
838 call, and the key released upon close. How to deal with conflicting keys due to
842 To access the key manager, the following header must be #included:
844 <linux/key.h>
846 Specific key types should have a header file under include/keys/ that should be
854 (*) struct key *
856 This simply points to the key structure itself. Key structures will be at
861 This is equivalent to a struct key *, but the least significant bit is set
862 if the caller "possesses" the key. By "possession" it is meant that the
863 calling processes has a searchable link to the key from one of its
866 key_ref_t make_key_ref(const struct key *key, bool possession);
868 struct key *key_ref_to_ptr(const key_ref_t key_ref);
872 The first function constructs a key reference from a key pointer and
875 The second function retrieves the key pointer from a reference and the
878 When accessing a key's payload contents, certain precautions must be taken to
882 (*) To search for a key, call:
884 struct key *request_key(const struct key_type *type,
888 This is used to request a key or keyring with a description that matches
889 the description specified according to the key type's match_preparse()
891 not NULL, then /sbin/request-key will be invoked in an attempt to obtain
892 the key from userspace. In that case, callout_string will be passed as an
898 If successful, the key will have been attached to the default keyring for
899 implicitly obtained request-key keys, as set by KEYCTL_SET_REQKEY_KEYRING.
901 See also Documentation/security/keys-request-key.txt.
904 (*) To search for a key, passing auxiliary data to the upcaller, call:
906 struct key *request_key_with_auxdata(const struct key_type *type,
917 (*) A key can be requested asynchronously by calling one of:
919 struct key *request_key_async(const struct key_type *type,
926 struct key *request_key_async_with_auxdata(const struct key_type *type,
935 These two functions return with the key potentially still under
939 int wait_for_key_construction(struct key *key, bool intr);
941 The function will wait for the key to finish being constructed and then
943 of the key (0 indicates the key is usable).
949 (*) When it is no longer required, the key should be released using:
951 void key_put(struct key *key);
961 (*) Extra references can be made to a key by calling one of the following
964 struct key *__key_get(struct key *key);
965 struct key *key_get(struct key *key);
968 they've been finished with. The key pointer passed in will be returned.
971 then the key will not be dereferenced and no increment will take place.
974 (*) A key's serial number can be obtained by calling:
976 key_serial_t key_serial(struct key *key);
978 If key is NULL or if CONFIG_KEYS is not set then 0 will be returned (in the
988 This searches the keyring tree specified for a matching key. Error ENOKEY
990 the returned key will need to be released.
993 access through the permissions mask and is propagated to the returned key
999 struct key *keyring_alloc(const char *description, uid_t uid, gid_t gid,
1003 struct key *dest);
1014 (*) To check the validity of a key, this function can be called:
1016 int validate_key(struct key *key);
1018 This checks that the key in question hasn't expired or and hasn't been
1019 revoked. Should the key be invalid, error EKEYEXPIRED or EKEYREVOKED will
1020 be returned. If the key is NULL or if CONFIG_KEYS is not set then 0 will be
1024 (*) To register a key type, the following function should be called:
1032 (*) To unregister a key type, call:
1052 The simplest payload is just a number in key->payload.value. In this case,
1056 key->payload.data. One of the following ways must be selected to access the
1059 (1) Unmodifiable key type.
1061 If the key type does not have a modify method, then the key's payload can
1065 (2) The key's semaphore.
1076 semaphore must still be used to serialise modifications to the key. The
1077 key management code takes care of this for the key type.
1088 Note that only the key type should ever modify a key's payload.
1092 the payload. key->datalen cannot be relied upon to be consistent with the
1093 payload just dereferenced if the key's semaphore is not held.
1100 A kernel service may want to define its own key type. For instance, an AFS
1101 filesystem might want to define a Kerberos 5 ticket key type. To do this, it
1104 Source files that implement key types should include the following header file:
1106 <linux/key-type.h>
1112 The name of the key type. This is used to translate a key type name
1119 contributed to the quota. If the key type's payload is always or almost
1122 The data length (and quota) on a particular key can always be changed
1125 int key_payload_reserve(struct key *key, size_t datalen);
1133 This optional method is called to vet a key description. If the key type
1134 doesn't approve of the key description, it may return an error, otherwise
1140 This optional method permits the key type to attempt to parse payload
1141 before a key is created (add key) or the key semaphore is taken (update or
1142 instantiate key). The structure pointed to by prep looks like:
1156 quota size from the key type; expiry will be set to TIME_T_MAX and the
1161 key description if the caller of add_key() passes NULL or "".
1165 set, the expiry time will be applied to the key if it is instantiated from
1182 (*) int (*instantiate)(struct key *key, struct key_preparsed_payload *prep);
1184 This method is called to attach a payload to a key during construction.
1191 If the amount of data attached to the key differs from the size in
1194 This method does not have to lock the key in order to attach a payload.
1195 The fact that KEY_FLAG_INSTANTIATED is not set in key->flags prevents
1196 anything else from gaining access to the key.
1201 (*) int (*update)(struct key *key, const void *data, size_t datalen);
1203 If this type of key can be updated, then this method should be provided.
1204 It is called to update a key's payload from the blob of data provided.
1211 is committed to changing the key because it's already been altered, so all
1214 The key will have its semaphore write-locked before this method is called,
1215 but this only deters other writers; any changes to the key's payload must
1228 This method is optional. It is called when a key search is about to be
1232 bool (*cmp)(const struct key *key,
1240 a key by the caller and should not be modified. (*cmp)() will be pointing
1251 search that's not doing a simple direct match on the key description.
1256 (*cmp)() should return true if a key matches and false otherwise.
1277 (*) void (*revoke)(struct key *key);
1280 data upon a key being revoked. The caller will have the key semaphore
1284 a deadlock against the key semaphore.
1287 (*) void (*destroy)(struct key *key);
1289 This method is optional. It is called to discard the payload data on a key
1292 This method does not need to lock the key to access the payload; it can
1293 consider the key as being inaccessible at this time. Note that the key's
1299 (*) void (*describe)(const struct key *key, struct seq_file *p);
1302 summarise a key's description and payload in text form.
1306 accessed. key->datalen cannot be trusted to stay consistent with the
1309 The description will not change, though the key's state may.
1315 (*) long (*read)(const struct key *key, char __user *buffer, size_t buflen);
1318 key's payload into something a blob of data for userspace to deal with.
1325 This method will be called with the key's semaphore read-locked. This will
1326 prevent the key's payload changing. It is not necessary to use RCU locking
1327 when accessing the key's payload. It is safe to sleep in this method, such
1335 invoke this function rather than upcalling to /sbin/request-key to operate
1336 upon a key of this type.
1340 the key to be operated upon and the operation type (currently only
1351 construction record is destroyed by this action and the authorisation key
1352 will be revoked. If an error is indicated, the key under construction
1359 The key under construction and the authorisation key can be found in the
1362 (*) struct key *key;
1364 The key under construction.
1366 (*) struct key *authkey;
1368 The authorisation key.
1375 To create a new key, the kernel will attempt to execute the following command
1378 /sbin/request-key create <key> <uid> <gid> \
1381 <key> is the key being constructed, and the three keyrings are the process
1386 required to obtain the key, eg: a Kerberos Ticket-Granting Ticket.
1388 (2) The new key should probably be cached in one of these rings.
1392 hand the request off to (perhaps a path held in placed in another key by, for
1395 The program (or whatever it calls) should finish construction of the key by
1397 cache the key in one of the keyrings (probably the session ring) before
1398 returning. Alternatively, the key can be marked as negative with KEYCTL_NEGATE
1399 or KEYCTL_REJECT; this also permits the key to be cached in one of the
1402 If it returns with the key remaining in the unconstructed state, the key will
1404 error will be returned to the key requestor.
1412 Similarly, the kernel may attempt to update an expired or a soon to expire key
1415 /sbin/request-key update <key> <uid> <gid> \
1418 In this case, the program isn't required to actually attach the key to a ring;