Lines Matching full:a
9 Keyrings are permitted; these are a special type of key that can hold links to
10 other keys. Processes each have three standard keyring subscriptions that a
28 Each key has a number of attributes:
30 - A serial number.
31 - A type.
32 - A description (for matching a key in a search).
35 - A payload.
39 * Each key is issued a serial number of type key_serial_t that is unique for
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
47 kernel by a kernel service (such as a filesystem) before keys of that type
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.
53 Should a type be removed from the system, all the keys of that type will
56 * Each key has a description. This should be a printable string. The key
57 type provides an operation to perform a match between the description on a
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
72 Having a payload is not required; and the payload can, in fact, just be a
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
81 attached payload back into a blob of data.
83 * Each key can be in one of a number of basic states:
91 * Negative. This is a relatively short-lived state. The key acts as a
92 note saying that a previous call out to userspace failed, and acts as
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
112 The key service provides a number of features besides keys:
118 Keyrings are special keys that contain a list of other keys. Keyring
120 be given a payload when created.
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
131 blob of data. It is intended as a place to store secrets which are
134 The description can be arbitrary, but must be prefixed with a non-zero
136 separated from the rest of the description by a ':'. "logon" keys can
140 * Each process subscribes to three keyrings: a thread-specific keyring, a
141 process-specific keyring, and a session-specific keyring.
144 clone, fork, vfork or execve occurs. A new keyring is created only when
149 shared. execve also discards the process's process keyring and creates a
153 execve, even when the latter executes a set-UID or set-GID binary. A
154 process can, however, replace its current session keyring with a new one
156 new one, or to attempt to create or join one of a specific name.
161 * Each user ID resident in the system holds two special keyrings: a user
162 specific keyring and a default user session keyring. The default session
163 keyring is initialised with a link to the user-specific keyring.
165 When a process changes its real UID, if it used to have no session key, it
168 If a process attempts to access its session key when it doesn't have one,
179 Process-specific and thread-specific keyrings are not counted towards a
182 If a system call that modifies a key or keyring in some way would put the
185 * There's a system call interface by which userspace programs can create and
188 * There's a kernel interface by which services can register types and search
191 * There's a way for the a search done from the kernel to call back to
192 userspace to request a key that can't be found in a process's keyrings.
201 Keys have an owner user ID, a group access ID, and a permissions mask. The mask
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
218 link to be added to or removed from a keyring.
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
233 This permits a key's UID, GID and permissions mask to be changed.
253 creation request. Tasks must be granted explicit permission to assign a
264 boot process, before root has a chance to log in.
349 Root may alter these by writing each new limit as a decimal number string to
357 request_key and keyctl. The latter provides a number of functions for
360 When referring to a key directly, userspace programs should use the key's
361 serial number (a positive 32-bit integer). However, there are some special
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
393 Otherwise, this will attempt to create a new key of the specified type and
399 string, the key type will try and generate a description from the content
406 A new keyring can be generated by setting type "keyring", the keyring name
410 recommended that a user defined key's description by prefixed with a type
411 ID and a colon, such as "krb5tgt:" for a Kerberos 5 ticket granting
414 Any other type must have been registered with the kernel in advance by a
415 kernel service such as a filesystem.
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
430 a keyring.
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
445 * Map a special key ID to a real key ID for this process::
458 * Replace the session keyring this process subscribes to with a new one::
465 If name is not NULL, if a keyring of that name exists, the process
467 is not permitted; otherwise a new keyring of that name is created and
470 To attach to a named keyring, the keyring must have search permission for
490 * Revoke a key::
494 This makes a key unavailable for further operations. Further attempts to
499 * Change the ownership of a key::
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::
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::
528 This function returns a summary of the key's attributes (but not its
529 payload data) as a string in the buffer provided.
536 A process must have view permission on the key for this function to be
539 If successful, a string is placed in the buffer in the following format::
544 is hexadecimal. A NUL character is included at the end of the string if
552 * Clear out a keyring::
556 This function clears the list of keys attached to a keyring. The calling
557 process must have write permission on the keyring, and it must be a
565 * Link a key into a keyring::
569 This function creates a link from the keyring to the key. The process must
573 Should the keyring not be a keyring, error ENOTDIR will result; and if the
577 it appears too deep or EDEADLK if the link would introduce a cycle.
584 * Move a key from one keyring to another::
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::
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
630 a process has search permission can be matched. If the specified keyring
631 is not a keyring, ENOTDIR will result.
641 * Read the payload data from a key::
651 instance, a keyring will return an array of key_serial_t entries
653 defined key type will return its data as is. If a key type does not
663 * Instantiate a partially constructed key::
672 If the kernel calls back to userspace to complete the instantiation of a
680 If a keyring is specified (non-zero), the key will also be linked into
687 array instead of a single buffer.
690 * Negatively instantiate a partially constructed key::
697 If the kernel calls back to userspace to complete the instantiation of a
704 If a keyring is specified (non-zero), the key will also be linked into
744 * Set the timeout on a key::
748 This sets or clears the timeout on a key. The timeout can be 0 to clear
749 the timeout or a number of seconds to set the expiry time that far into
752 The process must have attribute modification access on a key to set its
757 * Assume the authority granted to instantiate a key::
779 * Get the LSM security context attached to a key::
784 This function returns a string that represents the LSM security context
785 attached to a key in the buffer provided.
792 A NUL character is included at the end of the string if the buffer is
796 A process must have view permission on the key for this function to be
820 * Invalidate a key::
824 This function marks a key as being invalidated and then wakes up the
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::
845 - The base integer, which is either a shared generator or the
865 The kdf parameter allows the caller to apply a key derivation function
872 operation. The KDF implementation complies with SP800-56A as well
876 SP800-56A section 5.8.1.2. The length of the buffer is given with
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.
905 a method and relevant data for the restriction such as signature
910 To apply a keyring restriction the process must have Set Attribute
927 encodings may be queried by using the ``params`` argument. This is a
928 string containing a space- or tab-separated string of key-value pairs.
940 ``supported_ops`` contains a bit mask of flags indicating which ops are
941 supported. This is constructed from a bitwise-OR of::
947 ``max_*_size`` indicate the maximum sizes in bytes of a blob of data to be
948 signed, a signature blob, a blob to be encrypted and a blob to be
952 over one or more passphrases needed unlock a 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
989 The parameter block pointed to by params contains a number of integer
1002 For a given operation, the in and out buffers are used as follows::
1011 ``info`` is a string of key=value pairs that supply supplementary
1020 ``hash=<algo>`` If the data buffer contains the output of a hash
1027 required to unlock a key.
1033 * Watch a key or keyring for changes::
1038 This will set or remove a watch for changes on the specified key or
1043 "queue_fd" is a file descriptor referring to an open pipe which
1046 "filter" is either NULL to remove a watch or a filter specification to
1074 Where these indicate a key being instantiated/rejected, updated, a link
1075 being made in a keyring, a link being removed from a keyring, a keyring
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
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
1099 filesystem or device file, a search would probably be performed during the open
1108 Specific key types should have a header file under include/keys/ that should be
1123 This is equivalent to a ``struct key *``, but the least significant bit is set
1125 calling processes has a searchable link to the key from one of its
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::
1150 This is used to request a key or keyring with a description that matches
1166 * To search for a key in a specific domain, call::
1173 This is identical to request_key(), except that a domain tag may be
1175 tag. The domain_tag may be NULL, specifying a global domain that is
1179 * To search for a key, passing auxiliary data to the upcaller, call::
1190 callout_info is a blob of length callout_len, if given (the length may be
1194 * To search for a key under RCU conditions, call::
1202 construct a key if it can't find a match.
1217 * Extra references can be made to a key by calling one of the following
1230 * A key's serial number can be obtained by calling::
1238 * If a keyring was found in the search, this can be further searched by::
1246 (recurse == true) specified for a matching key. Error ENOKEY is returned
1255 * A keyring can be created by::
1264 This creates a keyring with the given attributes and returns it. If dest
1272 If restrict_link is not NULL, it should point to a structure that contains
1273 the function that will be called each time an attempt is made to link a
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
1282 - provided they can be verified by a key the kernel already has.
1286 used in the restriction check. Note that when a new key is being created,
1290 A convenience function, restrict_link_reject, exists to always return
1294 * To check the validity of a key, this function can be called::
1304 * To register a key type, the following function should be called::
1308 This will return error EEXIST if a type of the same name is already
1312 * To unregister a key type, call::
1317 Under some circumstances, it may be desirable to deal with a bundle of keys.
1318 The facility provides access to the keyring type for managing such a bundle::
1322 This can be used with a function such as request_key() to find a specific
1323 keyring in a process's keyrings. A keyring thus found can then be searched
1325 search a specific keyring, so using keyrings in this way is of limited utility.
1340 If the key type does not have a modify method, then the key's payload can
1366 to set the pointer and dispose of the old contents after a grace period.
1367 Note that only the key type should ever modify a key's payload.
1369 Furthermore, an RCU controlled payload must hold a struct rcu_head for the
1374 Note that key->payload.data[0] has a shadow that is marked for __rcu
1378 a) Set or change the first payload pointer::
1395 Defining a Key Type
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
1400 author fills in a key_type struct and registers it with the system.
1406 The structure has a number of fields, some of which are mandatory:
1410 The name of the key type. This is used to translate a key type name
1411 supplied by userspace into a pointer to the structure.
1418 always the same size, then this is a more efficient way to do things.
1420 The data length (and quota) on a particular key can always be changed
1431 This optional method is called to vet a key description. If the key type
1439 before a key is created (add key) or the key semaphore is taken (update or
1456 If a description can be proposed from the payload contents, that should be
1457 attached as a string to the description field. This will be used for the
1464 The method should return 0 if successful or a negative error code
1479 This method is called to attach a payload to a key during construction.
1489 This method does not have to lock the key in order to attach a payload.
1504 It is called to update a key's payload from the blob of data provided.
1528 This method is optional. It is called when a key search is about to be
1540 a key by the caller and should not be modified. ``(*cmp)()`` will be pointing
1542 against raw_data) and lookup_type will be set to indicate a direct lookup.
1546 * KEYRING_SEARCH_LOOKUP_DIRECT - A direct lookup hashes the type and
1547 description to narrow down the search to a small number of keys.
1551 search that's not doing a simple direct match on the key description.
1553 The method may set cmp to point to a function of its choice that does some
1556 ``(*cmp)()`` should return true if a key matches and false otherwise.
1561 The method should return 0 if successful or a negative error code
1574 match_data->preparsed after a successful call to match_preparse().
1580 data upon a key being revoked. The caller will have the key semaphore
1584 a deadlock against the key semaphore.
1589 This method is optional. It is called to discard the payload data on a key
1602 summarise a key's description and payload in text form.
1618 key's payload into something a blob of data for userspace to deal with.
1635 upon a key of this type.
1674 name) is passed in, and this method returns a pointer to a key_restriction
1686 These methods are optional. If provided the first allows a key to be
1687 used to encrypt, decrypt or sign a blob of data, and the second allows a
1688 key to verify a signature.
1705 This includes the key to be used; a string indicating the encoding to use
1708 the name of the hash algorithm used to generate the data for a signature
1712 For a given operation ID, the input and output buffers are used as
1744 A variety of errors may be returned, including EOPNOTSUPP if the operation
1772 The supported_ops field will contain a bitmask indicating what operations
1773 are supported by the key, including encryption of a blob, decryption of a
1774 blob, signing a blob and verifying the signature on a blob. The following
1781 verification of a signature; max_enc_size and max_dec_size are the maximum
1792 To create a new key, the kernel will attempt to execute the following command
1803 required to obtain the key, eg: a Kerberos Ticket-Granting Ticket.
1808 access any more keys. It may then look around for a user specific process to
1809 hand the request off to (perhaps a path held in placed in another key by, for
1829 Similarly, the kernel may attempt to update an expired or a soon to expire key
1835 In this case, the program isn't required to actually attach the key to a ring;
1843 from those keyrings that point to them and deleted as soon as possible by a
1846 Similarly, revoked and expired keys will be garbage collected, but only after a
1847 certain amount of time has passed. This time is set as a number of seconds in::