diff options
Diffstat (limited to 'man2/keyctl.2')
| -rw-r--r-- | man2/keyctl.2 | 2297 |
1 files changed, 0 insertions, 2297 deletions
diff --git a/man2/keyctl.2 b/man2/keyctl.2 deleted file mode 100644 index a2a4ab047..000000000 --- a/man2/keyctl.2 +++ /dev/null @@ -1,2297 +0,0 @@ -.\" Copyright (C) 2016 Michael Kerrisk <mtk.manpages@gmail.com> -.\" and Copyright (C) 2016 Eugene Syromyatnikov <evgsyr@gmail.com> -.\" A very few fragments remain from an earlier version of this page -.\" written by David Howells (dhowells@redhat.com) -.\" -.\" SPDX-License-Identifier: Linux-man-pages-copyleft -.\" -.TH keyctl 2 (date) "Linux man-pages (unreleased)" -.SH NAME -keyctl \- manipulate the kernel's key management facility -.SH LIBRARY -Standard C library -.RI ( libc ", " \-lc ) -.P -Alternatively, Linux Key Management Utilities -.RI ( libkeyutils ", " \-lkeyutils ); -see VERSIONS. -.SH SYNOPSIS -.nf -.BR "#include <linux/keyctl.h>" " /* Definition of " KEY* " constants */" -.BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */" -.B #include <unistd.h> -.P -.BI "long syscall(SYS_keyctl, int " operation ", unsigned long " arg2 , -.BI " unsigned long " arg3 ", unsigned long " arg4 , -.BI " unsigned long " arg5 ); -.fi -.P -.IR Note : -glibc provides no wrapper for -.BR keyctl (), -necessitating the use of -.BR syscall (2). -.SH DESCRIPTION -.BR keyctl () -allows user-space programs to perform key manipulation. -.P -The operation performed by -.BR keyctl () -is determined by the value of the -.I operation -argument. -Each of these operations is wrapped by the -.I libkeyutils -library (provided by the -.I keyutils -package) into individual functions (noted below) -to permit the compiler to check types. -.P -The permitted values for -.I operation -are: -.TP -.BR KEYCTL_GET_KEYRING_ID " (since Linux 2.6.10)" -Map a special key ID to a real key ID for this process. -.IP -This operation looks up the special key whose ID is provided in -.I arg2 -(cast to -.IR key_serial_t ). -If the special key is found, -the ID of the corresponding real key is returned as the function result. -The following values may be specified in -.IR arg2 : -.RS -.TP -.B KEY_SPEC_THREAD_KEYRING -This specifies the calling thread's thread-specific keyring. -See -.BR thread\-keyring (7). -.TP -.B KEY_SPEC_PROCESS_KEYRING -This specifies the caller's process-specific keyring. -See -.BR process\-keyring (7). -.TP -.B KEY_SPEC_SESSION_KEYRING -This specifies the caller's session-specific keyring. -See -.BR session\-keyring (7). -.TP -.B KEY_SPEC_USER_KEYRING -This specifies the caller's UID-specific keyring. -See -.BR user\-keyring (7). -.TP -.B KEY_SPEC_USER_SESSION_KEYRING -This specifies the caller's UID-session keyring. -See -.BR user\-session\-keyring (7). -.TP -.BR KEY_SPEC_REQKEY_AUTH_KEY " (since Linux 2.6.16)" -.\" commit b5f545c880a2a47947ba2118b2509644ab7a2969 -This specifies the authorization key created by -.BR request_key (2) -and passed to the process it spawns to generate a key. -This key is available only in a -.BR request\-key (8)-style -program that was passed an authorization key by the kernel and -ceases to be available once the requested key has been instantiated; see -.BR request_key (2). -.TP -.BR KEY_SPEC_REQUESTOR_KEYRING " (since Linux 2.6.29)" -.\" commit 8bbf4976b59fc9fc2861e79cab7beb3f6d647640 -This specifies the key ID for the -.BR request_key (2) -destination keyring. -This keyring is available only in a -.BR request\-key (8)-style -program that was passed an authorization key by the kernel and -ceases to be available once the requested key has been instantiated; see -.BR request_key (2). -.RE -.IP -The behavior if the key specified in -.I arg2 -does not exist depends on the value of -.I arg3 -(cast to -.IR int ). -If -.I arg3 -contains a nonzero value, then\[em]if it is appropriate to do so -(e.g., when looking up the user, user-session, or session key)\[em]a new key -is created and its real key ID returned as the function result. -.\" The keyctl_get_keyring_ID.3 page says that a new key -.\" "will be created *if it is appropriate to do so**. What is the -.\" determiner for appropriate? -.\" David Howells: Some special keys such as KEY_SPEC_REQKEY_AUTH_KEY -.\" wouldn't get created but user/user-session/session keyring would -.\" be created. -Otherwise, the operation fails with the error -.BR ENOKEY . -.IP -If a valid key ID is specified in -.IR arg2 , -and the key exists, then this operation simply returns the key ID. -If the key does not exist, the call fails with error -.BR ENOKEY . -.IP -The caller must have -.I search -permission on a keyring in order for it to be found. -.IP -The arguments -.I arg4 -and -.I arg5 -are ignored. -.IP -This operation is exposed by -.I libkeyutils -via the function -.BR keyctl_get_keyring_ID (3). -.TP -.BR KEYCTL_JOIN_SESSION_KEYRING " (since Linux 2.6.10)" -Replace the session keyring this process subscribes to with -a new session keyring. -.\" This may be useful in conjunction with some sort of -.\" session management framework that is employed by the application. -.IP -If -.I arg2 -is NULL, -an anonymous keyring with the description "_ses" is created -and the process is subscribed to that keyring as its session keyring, -displacing the previous session keyring. -.IP -Otherwise, -.I arg2 -(cast to -.IR "char\ *" ) -is treated as the description (name) of a keyring, -and the behavior is as follows: -.RS -.IP \[bu] 3 -If a keyring with a matching description exists, -the process will attempt to subscribe to that keyring -as its session keyring if possible; -if that is not possible, an error is returned. -In order to subscribe to the keyring, -the caller must have -.I search -permission on the keyring. -.IP \[bu] -If a keyring with a matching description does not exist, -then a new keyring with the specified description is created, -and the process is subscribed to that keyring as its session keyring. -.RE -.IP -The arguments -.IR arg3 , -.IR arg4 , -and -.I arg5 -are ignored. -.IP -This operation is exposed by -.I libkeyutils -via the function -.BR keyctl_join_session_keyring (3). -.TP -.BR KEYCTL_UPDATE " (since Linux 2.6.10)" -Update a key's data payload. -.IP -The -.I arg2 -argument (cast to -.IR key_serial_t ) -specifies the ID of the key to be updated. -The -.I arg3 -argument (cast to -.IR "void\ *" ) -points to the new payload and -.I arg4 -(cast to -.IR size_t ) -contains the new payload size in bytes. -.IP -The caller must have -.I write -permission on the key specified and the key type must support updating. -.IP -A negatively instantiated key (see the description of -.BR KEYCTL_REJECT ) -can be positively instantiated with this operation. -.IP -The -.I arg5 -argument is ignored. -.IP -This operation is exposed by -.I libkeyutils -via the function -.BR keyctl_update (3). -.TP -.BR KEYCTL_REVOKE " (since Linux 2.6.10)" -Revoke the key with the ID provided in -.I arg2 -(cast to -.IR key_serial_t ). -The key is scheduled for garbage collection; -it will no longer be findable, -and will be unavailable for further operations. -Further attempts to use the key will fail with the error -.BR EKEYREVOKED . -.IP -The caller must have -.I write -or -.I setattr -permission on the key. -.\" Keys with the KEY_FLAG_KEEP bit set cause an EPERM -.\" error for KEYCTL_REVOKE. Does this need to be documented? -.\" David Howells: No significance for user space. -.IP -The arguments -.IR arg3 , -.IR arg4 , -and -.I arg5 -are ignored. -.IP -This operation is exposed by -.I libkeyutils -via the function -.BR keyctl_revoke (3). -.TP -.BR KEYCTL_CHOWN " (since Linux 2.6.10)" -Change the ownership (user and group ID) of a key. -.IP -The -.I arg2 -argument (cast to -.IR key_serial_t ) -contains the key ID. -The -.I arg3 -argument (cast to -.IR uid_t ) -contains the new user ID (or \-1 in case the user ID shouldn't be changed). -The -.I arg4 -argument (cast to -.IR gid_t ) -contains the new group ID (or \-1 in case the group ID shouldn't be changed). -.IP -The key must grant the caller -.I setattr -permission. -.IP -For the UID to be changed, or for the GID to be changed to a group -the caller is not a member of, the caller must have the -.B CAP_SYS_ADMIN -capability (see -.BR capabilities (7)). -.IP -If the UID is to be changed, the new user must have sufficient -quota to accept the key. -The quota deduction will be removed from the old user -to the new user should the UID be changed. -.IP -The -.I arg5 -argument is ignored. -.IP -This operation is exposed by -.I libkeyutils -via the function -.BR keyctl_chown (3). -.TP -.BR KEYCTL_SETPERM " (since Linux 2.6.10)" -Change the permissions of the key with the ID provided in the -.I arg2 -argument (cast to -.IR key_serial_t ) -to the permissions provided in the -.I arg3 -argument (cast to -.IR key_perm_t ). -.IP -If the caller doesn't have the -.B CAP_SYS_ADMIN -capability, it can change permissions only for the keys it owns. -(More precisely: the caller's filesystem UID must match the UID of the key.) -.IP -The key must grant -.I setattr -permission to the caller -.I regardless -of the caller's capabilities. -.\" FIXME Above, is it really intended that a privileged process can't -.\" override the lack of the 'setattr' permission? -.IP -The permissions in -.I arg3 -specify masks of available operations -for each of the following user categories: -.RS -.TP -.IR possessor " (since Linux 2.6.14)" -.\" commit 664cceb0093b755739e56572b836a99104ee8a75 -This is the permission granted to a process that possesses the key -(has it attached searchably to one of the process's keyrings); -see -.BR keyrings (7). -.TP -.I user -This is the permission granted to a process -whose filesystem UID matches the UID of the key. -.TP -.I group -This is the permission granted to a process -whose filesystem GID or any of its supplementary GIDs -matches the GID of the key. -.TP -.I other -This is the permission granted to other processes -that do not match the -.I user -and -.I group -categories. -.RE -.IP -The -.IR user , -.IR group , -and -.I other -categories are exclusive: if a process matches the -.I user -category, it will not receive permissions granted in the -.I group -category; if a process matches the -.I user -or -.I group -category, then it will not receive permissions granted in the -.I other -category. -.IP -The -.I possessor -category grants permissions that are cumulative with the grants from the -.IR user , -.IR group , -or -.I other -category. -.IP -Each permission mask is eight bits in size, -with only six bits currently used. -The available permissions are: -.RS -.TP -.I view -This permission allows reading attributes of a key. -.IP -This permission is required for the -.B KEYCTL_DESCRIBE -operation. -.IP -The permission bits for each category are -.BR KEY_POS_VIEW , -.BR KEY_USR_VIEW , -.BR KEY_GRP_VIEW , -and -.BR KEY_OTH_VIEW . -.TP -.I read -This permission allows reading a key's payload. -.IP -This permission is required for the -.B KEYCTL_READ -operation. -.IP -The permission bits for each category are -.BR KEY_POS_READ , -.BR KEY_USR_READ , -.BR KEY_GRP_READ , -and -.BR KEY_OTH_READ . -.TP -.I write -This permission allows update or instantiation of a key's payload. -For a keyring, it allows keys to be linked and unlinked from the keyring, -.IP -This permission is required for the -.BR KEYCTL_UPDATE , -.BR KEYCTL_REVOKE , -.BR KEYCTL_CLEAR , -.BR KEYCTL_LINK , -and -.B KEYCTL_UNLINK -operations. -.IP -The permission bits for each category are -.BR KEY_POS_WRITE , -.BR KEY_USR_WRITE , -.BR KEY_GRP_WRITE , -and -.BR KEY_OTH_WRITE . -.TP -.I search -This permission allows keyrings to be searched and keys to be found. -Searches can recurse only into nested keyrings that have -.I search -permission set. -.IP -This permission is required for the -.BR KEYCTL_GET_KEYRING_ID , -.BR KEYCTL_JOIN_SESSION_KEYRING , -.BR KEYCTL_SEARCH , -and -.B KEYCTL_INVALIDATE -operations. -.IP -The permission bits for each category are -.BR KEY_POS_SEARCH , -.BR KEY_USR_SEARCH , -.BR KEY_GRP_SEARCH , -and -.BR KEY_OTH_SEARCH . -.TP -.I link -This permission allows a key or keyring to be linked to. -.IP -This permission is required for the -.B KEYCTL_LINK -and -.B KEYCTL_SESSION_TO_PARENT -operations. -.IP -The permission bits for each category are -.BR KEY_POS_LINK , -.BR KEY_USR_LINK , -.BR KEY_GRP_LINK , -and -.BR KEY_OTH_LINK . -.TP -.IR setattr " (since Linux 2.6.15)." -This permission allows a key's UID, GID, and permissions mask to be changed. -.IP -This permission is required for the -.BR KEYCTL_REVOKE , -.BR KEYCTL_CHOWN , -and -.B KEYCTL_SETPERM -operations. -.IP -The permission bits for each category are -.BR KEY_POS_SETATTR , -.BR KEY_USR_SETATTR , -.BR KEY_GRP_SETATTR , -and -.BR KEY_OTH_SETATTR . -.RE -.IP -As a convenience, the following macros are defined as masks for -all of the permission bits in each of the user categories: -.BR KEY_POS_ALL , -.BR KEY_USR_ALL , -.BR KEY_GRP_ALL , -and -.BR KEY_OTH_ALL . -.IP -The -.I arg4 -and -.I arg5 -arguments are ignored. -.IP -This operation is exposed by -.I libkeyutils -via the function -.BR keyctl_setperm (3). -.TP -.BR KEYCTL_DESCRIBE " (since Linux 2.6.10)" -Obtain a string describing the attributes of a specified key. -.IP -The ID of the key to be described is specified in -.I arg2 -(cast to -.IR key_serial_t ). -The descriptive string is returned in the buffer pointed to by -.I arg3 -(cast to -.IR char\~* ); -.I arg4 -(cast to -.IR size_t ) -specifies the size of that buffer in bytes. -.IP -The key must grant the caller -.I view -permission. -.IP -The returned string is null-terminated and -contains the following information about the key: -.IP -.in +4n -.IR type ; uid ; gid ; perm ; description -.in -.IP -In the above, -.I type -and -.I description -are strings, -.I uid -and -.I gid -are decimal strings, and -.I perm -is a hexadecimal permissions mask. -The descriptive string is written with the following format: -.IP -.in +4n -.EX -%s;%d;%d;%08x;%s -.EE -.in -.IP -.B Note: the intention is that the descriptive string should -.B be extensible in future kernel versions. -In particular, the -.I description -field will not contain semicolons; -.\" FIXME But, the kernel does not enforce the requirement -.\" that the key description contains no semicolons! -.\" So, user space has no guarantee here?? -.\" Either something more needs to be said here, -.\" or a kernel fix is required. -it should be parsed by working backwards from the end of the string -to find the last semicolon. -This allows future semicolon-delimited fields to be inserted -in the descriptive string in the future. -.IP -Writing to the buffer is attempted only when -.I arg3 -is non-NULL and the specified buffer size -is large enough to accept the descriptive string -(including the terminating null byte). -.\" Function commentary says it copies up to buflen bytes, but see the -.\" (buffer && buflen >= ret) condition in keyctl_describe_key() in -.\" security/keyctl.c -In order to determine whether the buffer size was too small, -check to see if the return value of the operation is greater than -.IR arg4 . -.IP -The -.I arg5 -argument is ignored. -.IP -This operation is exposed by -.I libkeyutils -via the function -.BR keyctl_describe (3). -.TP -.B KEYCTL_CLEAR -Clear the contents of (i.e., unlink all keys from) a keyring. -.IP -The ID of the key -(which must be of keyring type) -.\" or the error ENOTDIR results -is provided in -.I arg2 -(cast to -.IR key_serial_t ). -.\" According to Documentation/security/keys.txt: -.\" 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. -.IP -The caller must have -.I write -permission on the keyring. -.IP -The arguments -.IR arg3 , -.IR arg4 , -and -.I arg5 -are ignored. -.IP -This operation is exposed by -.I libkeyutils -via the function -.BR keyctl_clear (3). -.TP -.BR KEYCTL_LINK " (since Linux 2.6.10)" -Create a link from a keyring to a key. -.IP -The key to be linked is specified in -.I arg2 -(cast to -.IR key_serial_t ); -the keyring is specified in -.I arg3 -(cast to -.IR key_serial_t ). -.IP -If a key with the same type and description is already linked in the keyring, -then that key is displaced from the keyring. -.IP -Before creating the link, -the kernel checks the nesting of the keyrings and returns appropriate errors -if the link would produce a cycle -or if the nesting of keyrings would be too deep -(The limit on the nesting of keyrings is determined by the kernel constant -.BR KEYRING_SEARCH_MAX_DEPTH , -defined with the value 6, and is necessary to prevent overflows -on the kernel stack when recursively searching keyrings). -.IP -The caller must have -.I link -permission on the key being added and -.I write -permission on the keyring. -.IP -The arguments -.I arg4 -and -.I arg5 -are ignored. -.IP -This operation is exposed by -.I libkeyutils -via the function -.BR keyctl_link (3). -.TP -.BR KEYCTL_UNLINK " (since Linux 2.6.10)" -Unlink a key from a keyring. -.IP -The ID of the key to be unlinked is specified in -.I arg2 -(cast to -.IR key_serial_t ); -the ID of the keyring from which it is to be unlinked is specified in -.I arg3 -(cast to -.IR key_serial_t ). -.IP -If the key is not currently linked into the keyring, an error results. -.IP -The caller must have -.I write -permission on the keyring from which the key is being removed. -.IP -If the last link to a key is removed, -then that key will be scheduled for destruction. -.IP -The arguments -.I arg4 -and -.I arg5 -are ignored. -.IP -This operation is exposed by -.I libkeyutils -via the function -.BR keyctl_unlink (3). -.TP -.BR KEYCTL_SEARCH " (since Linux 2.6.10)" -Search for a key in a keyring tree, -returning its ID and optionally linking it to a specified keyring. -.IP -The tree to be searched is specified by passing -the ID of the head keyring in -.I arg2 -(cast to -.IR key_serial_t ). -The search is performed breadth-first and recursively. -.IP -The -.I arg3 -and -.I arg4 -arguments specify the key to be searched for: -.I arg3 -(cast as -.IR char\~* ) -contains the key type -(a null-terminated character string up to 32 bytes in size, -including the terminating null byte), and -.I arg4 -(cast as -.IR char\~* ) -contains the description of the key -(a null-terminated character string up to 4096 bytes in size, -including the terminating null byte). -.IP -The source keyring must grant -.I search -permission to the caller. -When performing the recursive search, only keyrings that grant the caller -.I search -permission will be searched. -Only keys with for which the caller has -.I search -permission can be found. -.IP -If the key is found, its ID is returned as the function result. -.IP -If the key is found and -.I arg5 -(cast to -.IR key_serial_t ) -is nonzero, then, subject to the same constraints and rules as -.BR KEYCTL_LINK , -the key is linked into the keyring whose ID is specified in -.IR arg5 . -If the destination keyring specified in -.I arg5 -already contains a link to a key that has the same type and description, -then that link will be displaced by a link to -the key found by this operation. -.IP -Instead of valid existing keyring IDs, the source -.RI ( arg2 ) -and destination -.RI ( arg5 ) -keyrings can be one of the special keyring IDs listed under -.BR KEYCTL_GET_KEYRING_ID . -.IP -This operation is exposed by -.I libkeyutils -via the function -.BR keyctl_search (3). -.TP -.BR KEYCTL_READ " (since Linux 2.6.10)" -Read the payload data of a key. -.IP -The ID of the key whose payload is to be read is specified in -.I arg2 -(cast to -.IR key_serial_t ). -This can be the ID of an existing key, -or any of the special key IDs listed for -.BR KEYCTL_GET_KEYRING_ID . -.\" including KEY_SPEC_REQKEY_AUTH_KEY -.IP -The payload is placed in the buffer pointed by -.I arg3 -(cast to -.IR "char\ *" ); -the size of that buffer must be specified in -.I arg4 -(cast to -.IR size_t ). -.IP -The returned data will be processed for presentation -according to the key type. -For example, a keyring will return an array of -.I key_serial_t -entries representing the IDs of all the keys that are linked to it. -The -.I user -key type will return its data as is. -If a key type does not implement this function, -the operation fails with the error -.BR EOPNOTSUPP . -.IP -If -.I arg3 -is not NULL, -as much of the payload data as will fit is copied into the buffer. -On a successful return, -the return value is always the total size of the payload data. -To determine whether the buffer was of sufficient size, -check to see that the return value is less than or equal to -the value supplied in -.IR arg4 . -.IP -The key must either grant the caller -.I read -permission, or grant the caller -.I search -permission when searched for from the process keyrings -(i.e., the key is possessed). -.IP -The -.I arg5 -argument is ignored. -.IP -This operation is exposed by -.I libkeyutils -via the function -.BR keyctl_read (3). -.TP -.BR KEYCTL_INSTANTIATE " (since Linux 2.6.10)" -(Positively) instantiate an uninstantiated key with a specified payload. -.IP -The ID of the key to be instantiated is provided in -.I arg2 -(cast to -.IR key_serial_t ). -.IP -The key payload is specified in the buffer pointed to by -.I arg3 -(cast to -.IR "void\ *"); -the size of that buffer is specified in -.I arg4 -(cast to -.IR size_t ). -.IP -The payload may be a null pointer and the buffer size may be 0 -if this is supported by the key type (e.g., it is a keyring). -.IP -The operation may be fail if the payload data is in the wrong format -or is otherwise invalid. -.IP -If -.I arg5 -(cast to -.IR key_serial_t ) -is nonzero, then, subject to the same constraints and rules as -.BR KEYCTL_LINK , -the instantiated key is linked into the keyring whose ID specified in -.IR arg5 . -.IP -The caller must have the appropriate authorization key, -and once the uninstantiated key has been instantiated, -the authorization key is revoked. -In other words, this operation is available only from a -.BR request\-key (8)-style -program. -See -.BR request_key (2) -for an explanation of uninstantiated keys and key instantiation. -.IP -This operation is exposed by -.I libkeyutils -via the function -.BR keyctl_instantiate (3). -.TP -.BR KEYCTL_NEGATE " (since Linux 2.6.10)" -Negatively instantiate an uninstantiated key. -.IP -This operation is equivalent to the call: -.IP -.in +4n -.EX -keyctl(KEYCTL_REJECT, arg2, arg3, ENOKEY, arg4); -.EE -.in -.IP -The -.I arg5 -argument is ignored. -.IP -This operation is exposed by -.I libkeyutils -via the function -.BR keyctl_negate (3). -.TP -.BR KEYCTL_SET_REQKEY_KEYRING " (since Linux 2.6.13)" -Set the default keyring to which implicitly requested keys -will be linked for this thread, and return the previous setting. -Implicit key requests are those made by internal kernel components, -.\" I.e., calls to the kernel's internal request_key() interface, -.\" which is distinct from the request_key(2) system call (which -.\" ultimately employs the kernel-internal interface). -such as can occur when, for example, opening files -on an AFS or NFS filesystem. -Setting the default keyring also has an effect when requesting -a key from user space; see -.BR request_key (2) -for details. -.IP -The -.I arg2 -argument (cast to -.IR int ) -should contain one of the following values, -to specify the new default keyring: -.RS -.TP -.B KEY_REQKEY_DEFL_NO_CHANGE -Don't change the default keyring. -This can be used to discover the current default keyring -(without changing it). -.TP -.B KEY_REQKEY_DEFL_DEFAULT -This selects the default behaviour, -which is to use the thread-specific keyring if there is one, -otherwise the process-specific keyring if there is one, -otherwise the session keyring if there is one, -otherwise the UID-specific session keyring, -otherwise the user-specific keyring. -.TP -.B KEY_REQKEY_DEFL_THREAD_KEYRING -Use the thread-specific keyring -.RB ( thread\-keyring (7)) -as the new default keyring. -.TP -.B KEY_REQKEY_DEFL_PROCESS_KEYRING -Use the process-specific keyring -.RB ( process\-keyring (7)) -as the new default keyring. -.TP -.B KEY_REQKEY_DEFL_SESSION_KEYRING -Use the session-specific keyring -.RB ( session\-keyring (7)) -as the new default keyring. -.TP -.B KEY_REQKEY_DEFL_USER_KEYRING -Use the UID-specific keyring -.RB ( user\-keyring (7)) -as the new default keyring. -.TP -.B KEY_REQKEY_DEFL_USER_SESSION_KEYRING -Use the UID-specific session keyring -.RB ( user\-session\-keyring (7)) -as the new default keyring. -.TP -.BR KEY_REQKEY_DEFL_REQUESTOR_KEYRING " (since Linux 2.6.29)" -.\" 8bbf4976b59fc9fc2861e79cab7beb3f6d647640 -Use the requestor keyring. -.\" FIXME The preceding explanation needs to be expanded. -.\" Is the following correct: -.\" -.\" The requestor keyring is the dest_keyring that -.\" was supplied to a call to request_key(2)? -.\" -.\" David Howells said: to be checked -.RE -.IP -All other values are invalid. -.\" (including the still-unsupported KEY_REQKEY_DEFL_GROUP_KEYRING) -.IP -The arguments -.IR arg3 , -.IR arg4 , -and -.I arg5 -are ignored. -.IP -The setting controlled by this operation is inherited by the child of -.BR fork (2) -and preserved across -.BR execve (2). -.IP -This operation is exposed by -.I libkeyutils -via the function -.BR keyctl_set_reqkey_keyring (3). -.TP -.BR KEYCTL_SET_TIMEOUT " (since Linux 2.6.16)" -Set a timeout on a key. -.IP -The ID of the key is specified in -.I arg2 -(cast to -.IR key_serial_t ). -The timeout value, in seconds from the current time, -is specified in -.I arg3 -(cast to -.IR "unsigned int" ). -The timeout is measured against the realtime clock. -.IP -Specifying the timeout value as 0 clears any existing timeout on the key. -.IP -The -.I /proc/keys -file displays the remaining time until each key will expire. -(This is the only method of discovering the timeout on a key.) -.IP -The caller must either have the -.I setattr -permission on the key -or hold an instantiation authorization token for the key (see -.BR request_key (2)). -.IP -The key and any links to the key will be -automatically garbage collected after the timeout expires. -Subsequent attempts to access the key will then fail with the error -.BR EKEYEXPIRED . -.IP -This operation cannot be used to set timeouts on revoked, expired, -or negatively instantiated keys. -.IP -The arguments -.I arg4 -and -.I arg5 -are ignored. -.IP -This operation is exposed by -.I libkeyutils -via the function -.BR keyctl_set_timeout (3). -.TP -.BR KEYCTL_ASSUME_AUTHORITY " (since Linux 2.6.16)" -Assume (or divest) the authority for the calling thread -to instantiate a key. -.IP -The -.I arg2 -argument (cast to -.IR key_serial_t ) -specifies either a nonzero key ID to assume authority, -or the value 0 to divest authority. -.IP -If -.I arg2 -is nonzero, then it specifies the ID of an uninstantiated key for which -authority is to be assumed. -That key can then be instantiated using one of -.BR KEYCTL_INSTANTIATE , -.BR KEYCTL_INSTANTIATE_IOV , -.BR KEYCTL_REJECT , -or -.BR KEYCTL_NEGATE . -Once the key has been instantiated, -the thread is automatically divested of authority to instantiate the key. -.IP -Authority over a key can be assumed only if the calling thread has present -in its keyrings the authorization key that is -associated with the specified key. -(In other words, the -.B KEYCTL_ASSUME_AUTHORITY -operation is available only from a -.BR request\-key (8)-style -program; see -.BR request_key (2) -for an explanation of how this operation is used.) -The caller must have -.I search -permission on the authorization key. -.IP -If the specified key has a matching authorization key, -then the ID of that key is returned. -The authorization key can be read -.RB ( KEYCTL_READ ) -to obtain the callout information passed to -.BR request_key (2). -.IP -If the ID given in -.I arg2 -is 0, then the currently assumed authority is cleared (divested), -and the value 0 is returned. -.IP -The -.B KEYCTL_ASSUME_AUTHORITY -mechanism allows a program such as -.BR request\-key (8) -to assume the necessary authority to instantiate a new uninstantiated key -that was created as a consequence of a call to -.BR request_key (2). -For further information, see -.BR request_key (2) -and the kernel source file -.IR Documentation/security/keys\-request\-key.txt . -.IP -The arguments -.IR arg3 , -.IR arg4 , -and -.I arg5 -are ignored. -.IP -This operation is exposed by -.I libkeyutils -via the function -.BR keyctl_assume_authority (3). -.TP -.BR KEYCTL_GET_SECURITY " (since Linux 2.6.26)" -.\" commit 70a5bb72b55e82fbfbf1e22cae6975fac58a1e2d -Get the LSM (Linux Security Module) security label of the specified key. -.IP -The ID of the key whose security label is to be fetched is specified in -.I arg2 -(cast to -.IR key_serial_t ). -The security label (terminated by a null byte) -will be placed in the buffer pointed to by -.I arg3 -argument (cast to -.IR "char\ *" ); -the size of the buffer must be provided in -.I arg4 -(cast to -.IR size_t ). -.IP -If -.I arg3 -is specified as NULL or the buffer size specified in -.I arg4 -is too small, the full size of the security label string -(including the terminating null byte) -is returned as the function result, -and nothing is copied to the buffer. -.IP -The caller must have -.I view -permission on the specified key. -.IP -The returned security label string will be rendered in a form appropriate -to the LSM in force. -For example, with SELinux, it may look like: -.IP -.in +4n -.EX -unconfined_u:unconfined_r:unconfined_t:s0-s0:c0.c1023 -.EE -.in -.IP -If no LSM is currently in force, -then an empty string is placed in the buffer. -.IP -The -.I arg5 -argument is ignored. -.IP -This operation is exposed by -.I libkeyutils -via the functions -.BR keyctl_get_security (3) -and -.BR keyctl_get_security_alloc (3). -.TP -.BR KEYCTL_SESSION_TO_PARENT " (since Linux 2.6.32)" -.\" commit ee18d64c1f632043a02e6f5ba5e045bb26a5465f -Replace the session keyring to which the -.I parent -of the calling process -subscribes with the session keyring of the calling process. -.\" What is the use case for KEYCTL_SESSION_TO_PARENT? -.\" David Howells: the Process Authentication Groups people requested this, -.\" but then didn't use it; maybe there are no users. -.IP -The keyring will be replaced in the parent process at the point -where the parent next transitions from kernel space to user space. -.IP -The keyring must exist and must grant the caller -.I link -permission. -The parent process must be single-threaded and have -the same effective ownership as this process -and must not be set-user-ID or set-group-ID. -The UID of the parent process's existing session keyring (f it has one), -as well as the UID of the caller's session keyring -much match the caller's effective UID. -.IP -The fact that it is the parent process that is affected by this operation -allows a program such as the shell to start a child process that -uses this operation to change the shell's session keyring. -(This is what the -.BR keyctl (1) -.B new_session -command does.) -.IP -The arguments -.IR arg2 , -.IR arg3 , -.IR arg4 , -and -.I arg5 -are ignored. -.IP -This operation is exposed by -.I libkeyutils -via the function -.BR keyctl_session_to_parent (3). -.TP -.BR KEYCTL_REJECT " (since Linux 2.6.39)" -.\" commit fdd1b94581782a2ddf9124414e5b7a5f48ce2f9c -Mark a key as negatively instantiated and set an expiration timer -on the key. -This operation provides a superset of the functionality of the earlier -.B KEYCTL_NEGATE -operation. -.IP -The ID of the key that is to be negatively instantiated is specified in -.I arg2 -(cast to -.IR key_serial_t ). -The -.I arg3 -(cast to -.IR "unsigned int" ) -argument specifies the lifetime of the key, in seconds. -The -.I arg4 -argument (cast to -.IR "unsigned int" ) -specifies the error to be returned when a search hits this key; -typically, this is one of -.BR EKEYREJECTED , -.BR EKEYREVOKED , -or -.BR EKEYEXPIRED . -.IP -If -.I arg5 -(cast to -.IR key_serial_t ) -is nonzero, then, subject to the same constraints and rules as -.BR KEYCTL_LINK , -the negatively instantiated key is linked into the keyring -whose ID is specified in -.IR arg5 . -.IP -The caller must have the appropriate authorization key. -In other words, this operation is available only from a -.BR request\-key (8)-style -program. -See -.BR request_key (2). -.IP -The caller must have the appropriate authorization key, -and once the uninstantiated key has been instantiated, -the authorization key is revoked. -In other words, this operation is available only from a -.BR request\-key (8)-style -program. -See -.BR request_key (2) -for an explanation of uninstantiated keys and key instantiation. -.IP -This operation is exposed by -.I libkeyutils -via the function -.BR keyctl_reject (3). -.TP -.BR KEYCTL_INSTANTIATE_IOV " (since Linux 2.6.39)" -.\" commit ee009e4a0d4555ed522a631bae9896399674f063 -Instantiate an uninstantiated key with a payload specified -via a vector of buffers. -.IP -This operation is the same as -.BR KEYCTL_INSTANTIATE , -but the payload data is specified as an array of -.I iovec -structures (see -.BR iovec (3type)). -.IP -The pointer to the payload vector is specified in -.I arg3 -(cast as -.IR "const struct iovec\~*" ). -The number of items in the vector is specified in -.I arg4 -(cast as -.IR "unsigned int" ). -.IP -The -.I arg2 -(key ID) -and -.I arg5 -(keyring ID) -are interpreted as for -.BR KEYCTL_INSTANTIATE . -.IP -This operation is exposed by -.I libkeyutils -via the function -.BR keyctl_instantiate_iov (3). -.TP -.BR KEYCTL_INVALIDATE " (since Linux 3.5)" -.\" commit fd75815f727f157a05f4c96b5294a4617c0557da -Mark a key as invalid. -.IP -The ID of the key to be invalidated is specified in -.I arg2 -(cast to -.IR key_serial_t ). -.IP -To invalidate a key, -the caller must have -.I search -permission on the key. -.\" CAP_SYS_ADMIN is permitted to invalidate certain special keys -.IP -This operation marks the key as invalid -and schedules immediate garbage collection. -The garbage collector removes the invalidated key from all keyrings and -deletes the key when its reference count reaches zero. -After this operation, -the key will be ignored by all searches, -even if it is not yet deleted. -.IP -Keys that are marked invalid become invisible to normal key operations -immediately, though they are still visible in -.I /proc/keys -(marked with an 'i' flag) -until they are actually removed. -.IP -The arguments -.IR arg3 , -.IR arg4 , -and -.I arg5 -are ignored. -.IP -This operation is exposed by -.I libkeyutils -via the function -.BR keyctl_invalidate (3). -.TP -.BR KEYCTL_GET_PERSISTENT " (since Linux 3.13)" -.\" commit f36f8c75ae2e7d4da34f4c908cebdb4aa42c977e -Get the persistent keyring -.RB ( persistent\-keyring (7)) -for a specified user and link it to a specified keyring. -.IP -The user ID is specified in -.I arg2 -(cast to -.IR uid_t ). -If the value \-1 is specified, the caller's real user ID is used. -The ID of the destination keyring is specified in -.I arg3 -(cast to -.IR key_serial_t ). -.IP -The caller must have the -.B CAP_SETUID -capability in its user namespace in order to fetch the persistent keyring -for a user ID that does not match either the real or effective user ID -of the caller. -.IP -If the call is successful, -a link to the persistent keyring is added to the keyring -whose ID was specified in -.IR arg3 . -.IP -The caller must have -.I write -permission on the keyring. -.IP -The persistent keyring will be created by the kernel -if it does not yet exist. -.IP -Each time the -.B KEYCTL_GET_PERSISTENT -operation is performed, the persistent keyring will -have its expiration timeout reset to the value in: -.IP -.in +4n -.EX -/proc/sys/kernel/keys/persistent_keyring_expiry -.EE -.in -.IP -Should the timeout be reached, -the persistent keyring will be removed and -everything it pins can then be garbage collected. -.IP -Persistent keyrings were added in Linux 3.13. -.IP -The arguments -.I arg4 -and -.I arg5 -are ignored. -.IP -This operation is exposed by -.I libkeyutils -via the function -.BR keyctl_get_persistent (3). -.TP -.BR KEYCTL_DH_COMPUTE " (since Linux 4.7)" -.\" commit ddbb41148724367394d0880c516bfaeed127b52e -Compute a Diffie-Hellman shared secret or public key, -optionally applying key derivation function (KDF) to the result. -.IP -The -.I arg2 -argument is a pointer to a set of parameters containing -serial numbers for three -.I \[dq]user\[dq] -keys used in the Diffie-Hellman calculation, -packaged in a structure of the following form: -.IP -.in +4n -.EX -struct keyctl_dh_params { - int32_t private; /* The local private key */ - int32_t prime; /* The prime, known to both parties */ - int32_t base; /* The base integer: either a shared - generator or the remote public key */ -}; -.EE -.in -.IP -Each of the three keys specified in this structure must grant the caller -.I read -permission. -The payloads of these keys are used to calculate the Diffie-Hellman -result as: -.IP -.in +4n -.EX -base \[ha] private mod prime -.EE -.in -.IP -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. -.IP -The -.I arg3 -argument (cast to -.IR char\~* ) -points to a buffer where the result of the calculation is placed. -The size of that buffer is specified in -.I arg4 -(cast to -.IR size_t ). -.IP -The buffer must be large enough to accommodate the output data, -otherwise an error is returned. -If -.I arg4 -is specified zero, -in which case the buffer is not used and -the operation returns the minimum required buffer size -(i.e., the length of the prime). -.IP -Diffie-Hellman computations can be performed in user space, -but require a multiple-precision integer (MPI) library. -Moving the implementation into the kernel gives access to -the kernel MPI implementation, -and allows access to secure or acceleration hardware. -.IP -Adding support for DH computation to the -.BR keyctl () -system call was considered a good fit due to the DH algorithm's use -for deriving shared keys; -it also allows the type of the key to determine -which DH implementation (software or hardware) is appropriate. -.\" commit f1c316a3ab9d24df6022682422fe897492f2c0c8 -.IP -If the -.I arg5 -argument is -.BR NULL , -then the DH result itself is returned. -Otherwise (since Linux 4.12), it is a pointer to a structure which specifies -parameters of the KDF operation to be applied: -.IP -.in +4n -.EX -struct keyctl_kdf_params { - char *hashname; /* Hash algorithm name */ - char *otherinfo; /* SP800\-56A OtherInfo */ - __u32 otherinfolen; /* Length of otherinfo data */ - __u32 __spare[8]; /* Reserved */ -}; -.EE -.in -.IP -The -.I hashname -field is a null-terminated string which specifies a hash name -(available in the kernel's crypto API; the list of the hashes available -is rather tricky to observe; please refer to the -.UR https://www.kernel.org\:/doc\:/html\:/latest\:/crypto\:/architecture.html -"Kernel Crypto API Architecture" -.UE -documentation for the information regarding how hash names are constructed and -your kernel's source and configuration regarding what ciphers -and templates with type -.B CRYPTO_ALG_TYPE_SHASH -are available) -to be applied to DH result in KDF operation. -.IP -The -.I otherinfo -field is an -.I OtherInfo -data as described in SP800-56A section 5.8.1.2 and is algorithm-specific. -This data is concatenated with the result of DH operation and is provided as -an input to the KDF operation. -Its size is provided in the -.I otherinfolen -field and is limited by -.B KEYCTL_KDF_MAX_OI_LEN -constant that defined in -.I security/keys/internal.h -to a value of 64. -.IP -The -.B __spare -field is currently unused. -.\" commit 4f9dabfaf8df971f8a3b6aa324f8f817be38d538 -It was ignored until Linux 4.13 (but still should be -user-addressable since it is copied to the kernel), -and should contain zeros since Linux 4.13. -.IP -The KDF implementation complies with SP800-56A as well -as with SP800-108 (the counter KDF). -.IP -.\" keyutils commit 742c9d7b94051d3b21f9f61a73ed6b5f3544cb82 -.\" keyutils commit d68a981e5db41d059ac782071c35d1e8f3aaf61c -This operation is exposed by -.I libkeyutils -(from -.I libkeyutils -1.5.10 onwards) via the functions -.BR keyctl_dh_compute (3) -and -.BR keyctl_dh_compute_alloc (3). -.TP -.BR KEYCTL_RESTRICT_KEYRING " (since Linux 4.12)" -.\" commit 6563c91fd645556c7801748f15bc727c77fcd311 -.\" commit 7228b66aaf723a623e578aa4db7d083bb39546c9 -Apply a key-linking restriction to the keyring with the ID provided in -.I arg2 -(cast to -.IR key_serial_t ). -The caller must have -.I setattr -permission on the key. -If -.I arg3 -is NULL, any attempt to add a key to the keyring is blocked; -otherwise it contains a pointer to a string with a key type name and -.I arg4 -contains a pointer to string that describes the type-specific restriction. -As of Linux 4.12, only the type "asymmetric" has restrictions defined: -.RS -.TP -.B builtin_trusted -Allows only keys that are signed by a key linked to the built-in keyring -(".builtin_trusted_keys"). -.TP -.B builtin_and_secondary_trusted -Allows only keys that are signed by a key linked to the secondary keyring -(".secondary_trusted_keys") or, by extension, a key in a built-in keyring, -as the latter is linked to the former. -.TP -.BI key_or_keyring: key -.TQ -.BI key_or_keyring: key :chain -If -.I key -specifies the ID of a key of type "asymmetric", -then only keys that are signed by this key are allowed. -.IP -If -.I key -specifies the ID of a keyring, -then only keys that are signed by a key linked -to this keyring are allowed. -.IP -If ":chain" is specified, keys that are signed by a keys linked to the -destination keyring (that is, the keyring with the ID specified in the -.I arg2 -argument) are also allowed. -.RE -.IP -Note that a restriction can be configured only once for the specified keyring; -once a restriction is set, it can't be overridden. -.IP -The argument -.I arg5 -is ignored. -.\" FIXME Document KEYCTL_RESTRICT_KEYRING, added in Linux 4.12 -.\" commit 6563c91fd645556c7801748f15bc727c77fcd311 -.\" Author: Mat Martineau <mathew.j.martineau@linux.intel.com> -.\" See Documentation/security/keys.txt -.SH RETURN VALUE -For a successful call, the return value depends on the operation: -.TP -.B KEYCTL_GET_KEYRING_ID -The ID of the requested keyring. -.TP -.B KEYCTL_JOIN_SESSION_KEYRING -The ID of the joined session keyring. -.TP -.B KEYCTL_DESCRIBE -The size of the description (including the terminating null byte), -irrespective of the provided buffer size. -.TP -.B KEYCTL_SEARCH -The ID of the key that was found. -.TP -.B KEYCTL_READ -The amount of data that is available in the key, -irrespective of the provided buffer size. -.TP -.B KEYCTL_SET_REQKEY_KEYRING -The ID of the previous default keyring -to which implicitly requested keys were linked -(one of -.BR KEY_REQKEY_DEFL_USER_* ). -.TP -.B KEYCTL_ASSUME_AUTHORITY -Either 0, if the ID given was 0, -or the ID of the authorization key matching the specified key, -if a nonzero key ID was provided. -.TP -.B KEYCTL_GET_SECURITY -The size of the LSM security label string -(including the terminating null byte), -irrespective of the provided buffer size. -.TP -.B KEYCTL_GET_PERSISTENT -The ID of the persistent keyring. -.TP -.B KEYCTL_DH_COMPUTE -The number of bytes copied to the buffer, or, if -.I arg4 -is 0, the required buffer size. -.TP -All other operations -Zero. -.P -On error, \-1 is returned, and -.I errno -is set to indicate the error. -.SH ERRORS -.TP -.B EACCES -The requested operation wasn't permitted. -.TP -.B EAGAIN -.I operation -was -.B KEYCTL_DH_COMPUTE -and there was an error during crypto module initialization. -.TP -.B EDEADLK -.I operation -was -.B KEYCTL_LINK -and the requested link would result in a cycle. -.TP -.B EDEADLK -.I operation -was -.B KEYCTL_RESTRICT_KEYRING -and the requested keyring restriction would result in a cycle. -.TP -.B EDQUOT -The key quota for the caller's user would be exceeded by creating a key or -linking it to the keyring. -.TP -.B EEXIST -.I operation -was -.B KEYCTL_RESTRICT_KEYRING -and keyring provided in -.I arg2 -argument already has a restriction set. -.TP -.B EFAULT -.I operation -was -.B KEYCTL_DH_COMPUTE -and one of the following has failed: -.RS -.IP \[bu] 3 -copying of the -.IR "struct keyctl_dh_params" , -provided in the -.I arg2 -argument, from user space; -.IP \[bu] -copying of the -.IR "struct keyctl_kdf_params" , -provided in the non-NULL -.I arg5 -argument, from user space -(in case kernel supports performing KDF operation on DH operation result); -.IP \[bu] -copying of data pointed by the -.I hashname -field of the -.I "struct keyctl_kdf_params" -from user space; -.IP \[bu] -copying of data pointed by the -.I otherinfo -field of the -.I struct keyctl_kdf_params -from user space if the -.I otherinfolen -field was nonzero; -.IP \[bu] -copying of the result to user space. -.RE -.TP -.B EINVAL -.I operation -was -.B KEYCTL_SETPERM -and an invalid permission bit was specified in -.IR arg3 . -.TP -.B EINVAL -.I operation -was -.B KEYCTL_SEARCH -and the size of the description in -.I arg4 -(including the terminating null byte) exceeded 4096 bytes. -.TP -.B EINVAL -size of the string (including the terminating null byte) specified in -.I arg3 -(the key type) -or -.I arg4 -(the key description) -exceeded the limit (32 bytes and 4096 bytes respectively). -.TP -.BR EINVAL " (before Linux 4.12)" -.I operation -was -.BR KEYCTL_DH_COMPUTE , -argument -.I arg5 -was non-NULL. -.TP -.B EINVAL -.I operation -was -.B KEYCTL_DH_COMPUTE -And the digest size of the hashing algorithm supplied is zero. -.TP -.B EINVAL -.I operation -was -.B KEYCTL_DH_COMPUTE -and the buffer size provided is not enough to hold the result. -Provide 0 as a buffer size in order to obtain the minimum buffer size. -.TP -.B EINVAL -.I operation -was -.B KEYCTL_DH_COMPUTE -and the hash name provided in the -.I hashname -field of the -.I struct keyctl_kdf_params -pointed by -.I arg5 -argument is too big (the limit is implementation-specific and varies between -kernel versions, but it is deemed big enough for all valid algorithm names). -.TP -.B EINVAL -.\" commit 4f9dabfaf8df971f8a3b6aa324f8f817be38d538 -.I operation -was -.B KEYCTL_DH_COMPUTE -and the -.I __spare -field of the -.I struct keyctl_kdf_params -provided in the -.I arg5 -argument contains nonzero values. -.TP -.B EKEYEXPIRED -An expired key was found or specified. -.TP -.B EKEYREJECTED -A rejected key was found or specified. -.TP -.B EKEYREVOKED -A revoked key was found or specified. -.TP -.B ELOOP -.I operation -was -.B KEYCTL_LINK -and the requested link would cause the maximum nesting depth -for keyrings to be exceeded. -.TP -.B EMSGSIZE -.I operation -was -.B KEYCTL_DH_COMPUTE -and the buffer length exceeds -.B KEYCTL_KDF_MAX_OUTPUT_LEN -(which is 1024 currently) -or the -.I otherinfolen -field of the -.I struct keyctl_kdf_parms -passed in -.I arg5 -exceeds -.B KEYCTL_KDF_MAX_OI_LEN -(which is 64 currently). -.TP -.BR ENFILE " (before Linux 3.13)" -.I operation -was -.B KEYCTL_LINK -and the keyring is full. -(Before Linux 3.13, -.\" commit b2a4df200d570b2c33a57e1ebfa5896e4bc81b69 -the available space for storing keyring links was limited to -a single page of memory; since Linux 3.13, there is no fixed limit.) -.TP -.B ENOENT -.I operation -was -.B KEYCTL_UNLINK -and the key to be unlinked isn't linked to the keyring. -.TP -.B ENOENT -.I operation -was -.B KEYCTL_DH_COMPUTE -and the hashing algorithm specified in the -.I hashname -field of the -.I struct keyctl_kdf_params -pointed by -.I arg5 -argument hasn't been found. -.TP -.B ENOENT -.I operation -was -.B KEYCTL_RESTRICT_KEYRING -and the type provided in -.I arg3 -argument doesn't support setting key linking restrictions. -.TP -.B ENOKEY -No matching key was found or an invalid key was specified. -.TP -.B ENOKEY -The value -.B KEYCTL_GET_KEYRING_ID -was specified in -.IR operation , -the key specified in -.I arg2 -did not exist, and -.I arg3 -was zero (meaning don't create the key if it didn't exist). -.TP -.B ENOMEM -One of kernel memory allocation routines failed during the execution of the -syscall. -.TP -.B ENOTDIR -A key of keyring type was expected but the ID of a key with -a different type was provided. -.TP -.B EOPNOTSUPP -.I operation -was -.B KEYCTL_READ -and the key type does not support reading -(e.g., the type is -.IR \[dq]login\[dq] ). -.TP -.B EOPNOTSUPP -.I operation -was -.B KEYCTL_UPDATE -and the key type does not support updating. -.TP -.B EOPNOTSUPP -.I operation -was -.BR KEYCTL_RESTRICT_KEYRING , -the type provided in -.I arg3 -argument was "asymmetric", -and the key specified in the restriction specification provided in -.I arg4 -has type other than "asymmetric" or "keyring". -.TP -.B EPERM -.I operation -was -.BR KEYCTL_GET_PERSISTENT , -.I arg2 -specified a UID other than the calling thread's real or effective UID, -and the caller did not have the -.B CAP_SETUID -capability. -.TP -.B EPERM -.I operation -was -.B KEYCTL_SESSION_TO_PARENT -and either: -all of the UIDs (GIDs) of the parent process do not match -the effective UID (GID) of the calling process; -the UID of the parent's existing session keyring or -the UID of the caller's session keyring did not match -the effective UID of the caller; -the parent process is not single-thread; -or the parent process is -.BR init (1) -or a kernel thread. -.TP -.B ETIMEDOUT -.I operation -was -.B KEYCTL_DH_COMPUTE -and the initialization of crypto modules has timed out. -.SH VERSIONS -A wrapper is provided in the -.I libkeyutils -library. -(The accompanying package provides the -.I <keyutils.h> -header file.) -However, rather than using this system call directly, -you probably want to use the various library functions -mentioned in the descriptions of individual operations above. -.SH STANDARDS -Linux. -.SH HISTORY -Linux 2.6.10. -.SH EXAMPLES -The program below provide subset of the functionality of the -.BR request\-key (8) -program provided by the -.I keyutils -package. -For informational purposes, -the program records various information in a log file. -.P -As described in -.BR request_key (2), -the -.BR request\-key (8) -program is invoked with command-line arguments that -describe a key that is to be instantiated. -The example program fetches and logs these arguments. -The program assumes authority to instantiate the requested key, -and then instantiates that key. -.P -The following shell session demonstrates the use of this program. -In the session, -we compile the program and then use it to temporarily replace the standard -.BR request\-key (8) -program. -(Note that temporarily disabling the standard -.BR request\-key (8) -program may not be safe on some systems.) -While our example program is installed, -we use the example program shown in -.BR request_key (2) -to request a key. -.P -.in +4n -.EX -$ \fBcc \-o key_instantiate key_instantiate.c \-lkeyutils\fP -$ \fBsudo mv /sbin/request\-key /sbin/request\-key.backup\fP -$ \fBsudo cp key_instantiate /sbin/request\-key\fP -$ \fB./t_request_key user mykey somepayloaddata\fP -Key ID is 20d035bf -$ \fBsudo mv /sbin/request\-key.backup /sbin/request\-key\fP -.EE -.in -.P -Looking at the log file created by this program, -we can see the command-line arguments supplied to our example program: -.P -.in +4n -.EX -$ \fBcat /tmp/key_instantiate.log\fP -Time: Mon Nov 7 13:06:47 2016 -\& -Command line arguments: - argv[0]: /sbin/request\-key - operation: create - key_to_instantiate: 20d035bf - UID: 1000 - GID: 1000 - thread_keyring: 0 - process_keyring: 0 - session_keyring: 256e6a6 -\& -Key description: user;1000;1000;3f010000;mykey -Auth key payload: somepayloaddata -Destination keyring: 256e6a6 -Auth key description: .request_key_auth;1000;1000;0b010000;20d035bf -.EE -.in -.P -The last few lines of the above output show that the example program -was able to fetch: -.IP \[bu] 3 -the description of the key to be instantiated, -which included the name of the key -.RI ( mykey ); -.IP \[bu] -the payload of the authorization key, which consisted of the data -.RI ( somepayloaddata ) -passed to -.BR request_key (2); -.IP \[bu] -the destination keyring that was specified in the call to -.BR request_key (2); -and -.IP \[bu] -the description of the authorization key, -where we can see that the name of the authorization key matches -the ID of the key that is to be instantiated -.RI ( 20d035bf ). -.P -The example program in -.BR request_key (2) -specified the destination keyring as -.BR KEY_SPEC_SESSION_KEYRING . -By examining the contents of -.IR /proc/keys , -we can see that this was translated to the ID of the destination keyring -.RI ( 0256e6a6 ) -shown in the log output above; -we can also see the newly created key with the name -.I mykey -and ID -.IR 20d035bf . -.P -.in +4n -.EX -$ \fBcat /proc/keys | egrep \[aq]mykey|256e6a6\[aq]\fP -0256e6a6 I\-\-Q\-\-\- 194 perm 3f030000 1000 1000 keyring _ses: 3 -20d035bf I\-\-Q\-\-\- 1 perm 3f010000 1000 1000 user mykey: 16 -.EE -.in -.SS Program source -\& -.\" SRC BEGIN (key_instantiate.c) -.EX -/* key_instantiate.c */ -\& -#include <errno.h> -#include <keyutils.h> -#include <stdint.h> -#include <stdio.h> -#include <stdlib.h> -#include <string.h> -#include <sys/types.h> -#include <time.h> -\& -#ifndef KEY_SPEC_REQUESTOR_KEYRING -#define KEY_SPEC_REQUESTOR_KEYRING (\-8) -#endif -\& -int -main(int argc, char *argv[]) -{ - int akp_size; /* Size of auth_key_payload */ - int auth_key; - char dbuf[256]; - char auth_key_payload[256]; - char *operation; - FILE *fp; - gid_t gid; - uid_t uid; - time_t t; - key_serial_t key_to_instantiate, dest_keyring; - key_serial_t thread_keyring, process_keyring, session_keyring; -\& - if (argc != 8) { - fprintf(stderr, "Usage: %s op key uid gid thread_keyring " - "process_keyring session_keyring\en", argv[0]); - exit(EXIT_FAILURE); - } -\& - fp = fopen("/tmp/key_instantiate.log", "w"); - if (fp == NULL) - exit(EXIT_FAILURE); -\& - setbuf(fp, NULL); -\& - t = time(NULL); - fprintf(fp, "Time: %s\en", ctime(&t)); -\& - /* - * The kernel passes a fixed set of arguments to the program - * that it execs; fetch them. - */ - operation = argv[1]; - key_to_instantiate = atoi(argv[2]); - uid = atoi(argv[3]); - gid = atoi(argv[4]); - thread_keyring = atoi(argv[5]); - process_keyring = atoi(argv[6]); - session_keyring = atoi(argv[7]); -\& - fprintf(fp, "Command line arguments:\en"); - fprintf(fp, " argv[0]: %s\en", argv[0]); - fprintf(fp, " operation: %s\en", operation); - fprintf(fp, " key_to_instantiate: %jx\en", - (uintmax_t) key_to_instantiate); - fprintf(fp, " UID: %jd\en", (intmax_t) uid); - fprintf(fp, " GID: %jd\en", (intmax_t) gid); - fprintf(fp, " thread_keyring: %jx\en", - (uintmax_t) thread_keyring); - fprintf(fp, " process_keyring: %jx\en", - (uintmax_t) process_keyring); - fprintf(fp, " session_keyring: %jx\en", - (uintmax_t) session_keyring); - fprintf(fp, "\en"); -\& - /* - * Assume the authority to instantiate the key named in argv[2]. - */ - if (keyctl(KEYCTL_ASSUME_AUTHORITY, key_to_instantiate) == \-1) { - fprintf(fp, "KEYCTL_ASSUME_AUTHORITY failed: %s\en", - strerror(errno)); - exit(EXIT_FAILURE); - } -\& - /* - * Fetch the description of the key that is to be instantiated. - */ - if (keyctl(KEYCTL_DESCRIBE, key_to_instantiate, - dbuf, sizeof(dbuf)) == \-1) { - fprintf(fp, "KEYCTL_DESCRIBE failed: %s\en", strerror(errno)); - exit(EXIT_FAILURE); - } -\& - fprintf(fp, "Key description: %s\en", dbuf); -\& - /* - * Fetch the payload of the authorization key, which is - * actually the callout data given to request_key(). - */ - akp_size = keyctl(KEYCTL_READ, KEY_SPEC_REQKEY_AUTH_KEY, - auth_key_payload, sizeof(auth_key_payload)); - if (akp_size == \-1) { - fprintf(fp, "KEYCTL_READ failed: %s\en", strerror(errno)); - exit(EXIT_FAILURE); - } -\& - auth_key_payload[akp_size] = \[aq]\e0\[aq]; - fprintf(fp, "Auth key payload: %s\en", auth_key_payload); -\& - /* - * For interest, get the ID of the authorization key and - * display it. - */ - auth_key = keyctl(KEYCTL_GET_KEYRING_ID, - KEY_SPEC_REQKEY_AUTH_KEY); - if (auth_key == \-1) { - fprintf(fp, "KEYCTL_GET_KEYRING_ID failed: %s\en", - strerror(errno)); - exit(EXIT_FAILURE); - } -\& - fprintf(fp, "Auth key ID: %jx\en", (uintmax_t) auth_key); -\& - /* - * Fetch key ID for the request_key(2) destination keyring. - */ - dest_keyring = keyctl(KEYCTL_GET_KEYRING_ID, - KEY_SPEC_REQUESTOR_KEYRING); - if (dest_keyring == \-1) { - fprintf(fp, "KEYCTL_GET_KEYRING_ID failed: %s\en", - strerror(errno)); - exit(EXIT_FAILURE); - } -\& - fprintf(fp, "Destination keyring: %jx\en", (uintmax_t) dest_keyring); -\& - /* - * Fetch the description of the authorization key. This - * allows us to see the key type, UID, GID, permissions, - * and description (name) of the key. Among other things, - * we will see that the name of the key is a hexadecimal - * string representing the ID of the key to be instantiated. - */ - if (keyctl(KEYCTL_DESCRIBE, KEY_SPEC_REQKEY_AUTH_KEY, - dbuf, sizeof(dbuf)) == \-1) - { - fprintf(fp, "KEYCTL_DESCRIBE failed: %s\en", strerror(errno)); - exit(EXIT_FAILURE); - } -\& - fprintf(fp, "Auth key description: %s\en", dbuf); -\& - /* - * Instantiate the key using the callout data that was supplied - * in the payload of the authorization key. - */ - if (keyctl(KEYCTL_INSTANTIATE, key_to_instantiate, - auth_key_payload, akp_size + 1, dest_keyring) == \-1) - { - fprintf(fp, "KEYCTL_INSTANTIATE failed: %s\en", - strerror(errno)); - exit(EXIT_FAILURE); - } -\& - exit(EXIT_SUCCESS); -} -.EE -.\" SRC END -.SH SEE ALSO -.ad l -.nh -.BR keyctl (1), -.BR add_key (2), -.BR request_key (2), -.\" .BR find_key_by_type_and_name (3) -.\" There is a man page, but this function seems not to exist -.BR keyctl (3), -.BR keyctl_assume_authority (3), -.BR keyctl_chown (3), -.BR keyctl_clear (3), -.BR keyctl_describe (3), -.BR keyctl_describe_alloc (3), -.BR keyctl_dh_compute (3), -.BR keyctl_dh_compute_alloc (3), -.BR keyctl_get_keyring_ID (3), -.BR keyctl_get_persistent (3), -.BR keyctl_get_security (3), -.BR keyctl_get_security_alloc (3), -.BR keyctl_instantiate (3), -.BR keyctl_instantiate_iov (3), -.BR keyctl_invalidate (3), -.BR keyctl_join_session_keyring (3), -.BR keyctl_link (3), -.BR keyctl_negate (3), -.BR keyctl_read (3), -.BR keyctl_read_alloc (3), -.BR keyctl_reject (3), -.BR keyctl_revoke (3), -.BR keyctl_search (3), -.BR keyctl_session_to_parent (3), -.BR keyctl_set_reqkey_keyring (3), -.BR keyctl_set_timeout (3), -.BR keyctl_setperm (3), -.BR keyctl_unlink (3), -.BR keyctl_update (3), -.BR recursive_key_scan (3), -.BR recursive_session_key_scan (3), -.BR capabilities (7), -.BR credentials (7), -.BR keyrings (7), -.BR keyutils (7), -.BR persistent\-keyring (7), -.BR process\-keyring (7), -.BR session\-keyring (7), -.BR thread\-keyring (7), -.BR user\-keyring (7), -.BR user_namespaces (7), -.BR user\-session\-keyring (7), -.BR request\-key (8) -.P -The kernel source files under -.I Documentation/security/keys/ -(or, before Linux 4.13, in the file -.IR Documentation/security/keys.txt ). |