---
* keyctl.2 (SYNOPSIS): Added information regarding direct call via
sysctl(2).
(DESCRIPTION): Added information regarding argument usage for
KEYCTL_GET_KEYRING_ID, KEYCTL_JOIN_SESSION_KEYRING, KEYCTL_UPDATE,
KEYCTL_REVOKE, KEYCTL_CHOWN, KEYCTL_SETPERM, KEYCTL_DESCRIBE,
KEYCTL_CLEAR, KEYCTL_LINK, KEYCTL_UNLINK, KEYCTL_SEARCH, KEYCTL_READ,
KEYCTL_INSTANTIATE, KEYCTL_NEGATE, KEYCTL_SET_REQKEY_KEYRING,
KEYCTL_SET_TIMEOUT, KEYCTL_ASSUME_AUTHORITY commands; added
information about KEYCTL_GET_SECURITY, KEYCTL_SESSION_TO_PARENT,
KEYCTL_REJECT, KEYCTL_INSTANTIATE_IOV, KEYCTL_INVALIDATE,
KEYCTL_GET_PERSISTENT, KEYCTL_DH_COMPUTE commands.
(RETURN VALUE): Added information regarding command-specific return
values (where it is non-zero).
(ERRORS): Addad information regarding ENOTSUPP, ENOTDIR, ENFILE,
ENOENT, EINVAL error codes.
---
man2/keyctl.2 | 619 ++++++++++++++++++++++++++++++++++++++++++++++++++++-----
1 file changed, 568 insertions(+), 51 deletions(-)
diff --git a/man2/keyctl.2 b/man2/keyctl.2
index 2cb382a..001197c 100644
--- a/man2/keyctl.2
+++ b/man2/keyctl.2
@@ -8,30 +8,6 @@
.\" 2 of the License, or (at your option) any later version.
.\" %%%LICENSE_END
.\"
-.\" FIXME Document KEYCTL_GET_SECURITY (new in 2.6.26)
-.\" commit 70a5bb72b55e82fbfbf1e22cae6975fac58a1e2d
-.\" Author: David Howells <dhowells@xxxxxxxxxx>
-.\" Date: Tue Apr 29 01:01:26 2008 -0700
-.\" FIXME Document KEYCTL_SESSION_TO_PARENT (new in 2.6.32)
-.\" commit ee18d64c1f632043a02e6f5ba5e045bb26a5465f
-.\" Author: David Howells <dhowells@xxxxxxxxxx>
-.\" Date: Wed Sep 2 09:14:21 2009 +0100
-.\" FIXME Document KEYCTL_REJECT (new in 2.6.39)
-.\" commit fdd1b94581782a2ddf9124414e5b7a5f48ce2f9c
-.\" Author: David Howells <dhowells@xxxxxxxxxx>
-.\" Documentation/security/keys.txt
-.\" FIXME Document KEYCTL_INSTANTIATE_IOV (new in 2.6.39)
-.\" commit ee009e4a0d4555ed522a631bae9896399674f064
-.\" Author: David Howells <dhowells@xxxxxxxxxx>
-.\" Documentation/security/keys.txt
-.\" FIXME Document KEYCTL_INVALIDATE (new in 3.5)
-.\" commit fd75815f727f157a05f4c96b5294a4617c0557da
-.\" Author: David Howells <dhowells@xxxxxxxxxx>
-.\" Documentation/security/keys.txt
-.\" FIXME Document KEYCTL_GET_PERSISTENT (new in 3.13)
-.\" commit f36f8c75ae2e7d4da34f4c908cebdb4aa42c977e
-.\" Author: David Howells <dhowells@xxxxxxxxxx>
-.\"
.TH KEYCTL 2 2015-05-07 Linux "Linux Key Management Calls"
.SH NAME
keyctl \- manipulate the kernel's key management facility
@@ -39,73 +15,588 @@ keyctl \- manipulate the kernel's key management facility
.nf
.B #include <keyutils.h>
.sp
-.BI "long keyctl(int " cmd ", ...);"
+.BI "long keyctl(int " cmd ", ...)"
+.sp
+.IB "/* For direct call via the " syscall "(2): */"
+.B #include <asm/unistd.h>
+.B #include <linux/keyctl.h>
+.B #include <unistd.h>
+.sp
+.BI "long syscall(__NR_keyctl, int " option ", __kernel_ulong_t " arg2 \
+", __kernel_ulong_t " arg3 ", __kernel_ulong_t " arg4 ", __kernel_ulong_t " \
+arg5 ");"
.fi
.SH DESCRIPTION
.BR keyctl ()
-has a number of functions available:
+(along with
+.IR add_key (2))
+provides abilities for userspace key manipulation. The operation performed by
+the
+.BR keyctl ()
+call is determined by the value of the
+.I option
+argument, which could one of the following:
.TP
.B KEYCTL_GET_KEYRING_ID
-Ask for a keyring's ID.
+Ask for a keyring's whose ID provided in
+.I arg2
+(converted to
+.IR key_serial_t ).
+If the
+.I arg3
+argument contains non-zero value, new keyring would be created. Caller should
+have
+.I search
+permission on a keyring for it to be found. Arguments
+.IR arg4 and arg5
+are ignored.
.TP
.B KEYCTL_JOIN_SESSION_KEYRING
-Join or start named session keyring.
+Create new anonymous session keyring (in case
+.I arg2
+is
+.BR NULL )
+or join existing named session keyring
+.RI ( arg2
+should be pointer to a string containing session name in this case). The caller
+should have
+.I search
+permission on the keyring name of which is provided in order
+to successfully join. Arguments
+.IR arg3 ", " arg4 ", " arg5
+are ignored.
.TP
.B KEYCTL_UPDATE
-Update a key.
+Update a key's data payload using data provided. The
+.I arg2
+argument (converted to
+.IR key_serial_t )
+should contain key ID, the
+.I arg3
+argument is interpreted as a pointer to the new payload and
+.I arg4
+(converted to
+.IR size_t )
+should contain payload size in bytes. The caller should has
+.I write
+permission on the key specified and key type should support updating. Negative
+key can be positively instantiated with this call. The
+.I arg5
+argument is ignored.
.TP
.B KEYCTL_REVOKE
-Revoke a key.
+Revoke a key with ID provided in
+.I arg2
+(converted to
+.IR key_serial_t ).
+The caller should have
+.IR write " or " setattr
+permissions. Arguments
+.IR arg3 ", " arg4 ", " arg5
+are ignored.
.TP
.B KEYCTL_CHOWN
-Set ownership of a key.
+Set ownership of a key. The
+.I arg2
+argument (converted to
+.IR key_serial_t )
+contains key ID, the
+.I arg3
+argument (converted to
+.IR uid_t )
+contains new user ID (or -1 in case user ID shouldn't be changed), the
+.I arg4
+argument (converted to
+.IR gid_t )
+contains new group ID (or -1 in case group ID shouldn't be changed).
+The key must grant the caller
+.I setattr
+permission. 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
+.I CAP_SYS_ADMIN
+capability (see
+.IR capabilities (7)
+for details). 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 attribute be changed. The
+.I arg5
+argument is ignored.
.TP
.B KEYCTL_SETPERM
-Set perms on a key.
+Change the permissions of a key with ID provided in the
+.I arg2
+argument (converted to
+.IR key_serial_t )
+to the ones provided in the
+.I arg3
+argument (converted to
+.IR key_perms_t ).
+The key must grant
+.I setattr
+permission to the caller. If the caller doesn't have
+.I CAP_SYS_ADMIN
+capability, it can only change permissions of the keys it owns.
+Permissions contains mask of available operations for possessor
+(since Linux 2.6.14), user, group, other. Each mask is eight bit in size,
+with only six currently used. The available permissions are:
+.RS
+.IP \(bu 3
+.BR View .
+Allows reading attributes of a key. Needed for
+.IR KEYCTL_DESCRIBE .
+.IP \(bu
+.BR Read .
+Allows reading key's payload. Needed for
+.IR KEYCTL_READ .
+.IP \(bu
+.BR Write .
+Allows update or instantiation of key's payload. For a keyring, it enables
+adding and removal of keys to a keyring. Needed for
+.IR KEYCTL_UPDATE ", " KEYCTL_REVOKE ", " KEYCTL_CLEAR ", " KEYCTL_LINK ", "
+.IR KEYCTL_UNLINK .
+.IP \(bu
+.BR Search .
+This permits keyrings to be searched and keys to be found. Searches can
+only recurse into nested keyrings that have search permission set. Needed for
+.IR KEYCTL_GET_KEYRING_ID ", " KEYCTL_JOIN_SESSION_KEYRING ", " KEYCTL_SEARCH
+.IR KEYCTL_INVALIDATE .
+.IP \(bu
+.BR Link .
+This permits a key or keyring to be linked to. Needed for
+.IR KEYCTL_LINK ", " KEYCTL_SESSION_TO_PARENT .
+.IP \(bu
+.BR "Set attribute" " (since Linux. 2.6.15)."
+This permits a key's UID, GID and permissions mask to be changed. Needed for
+.IR KEYCTL_REVOKE ", " KEYCTL_CHOWN ", " KEYCTL_SETPERM .
+.RE
+.IP
+The
+.IR arg4 " and " arg5
+arguments are ignored.
.TP
.B KEYCTL_DESCRIBE
-Describe a key.
+Describe a key. Key ID to be described should be provided in the
+.I arg2
+argument (converted to
+.IR key_serial_t ),
+the
+.I arg3
+argument should point to destination buffer (of type
+.IR "char *" ),
+and the
+.I arg4
+argument should contain size of the buffer (of kernel's
+.I size_t
+type). The key must grant the caller
+.I view
+permission. Writing to buffer is attempted only in case buffer is non-NULL and
+has enough space to accept the description.
+'\" Function commentary says it copies up to buflen bytes, bu see the
+'\" (buffer && buflen >= ret) condition in keyctl_describe_key() in
+'\" security/keyctl.c
+The description itself provided in
+.RS
+.IP
+.IR type ; uid ; gid ; perm ; description "<NUL>"
+.RE
+.IP
+format. The
+.I arg5
+argument is ignored.
.TP
.B KEYCTL_CLEAR
-Clear contents of a keyring.
+Clear contents of a keyring with ID provided in the
+.I arg2
+argument (converted to
+.IR key_serial_t ).
+Caller should have
+.I write
+permission. Arguments
+.IR arg3 ", " arg4 ", " arg5
+are ignored.
.TP
.B KEYCTL_LINK
-Link a key into a keyring.
+Link a key (provided in the
+.I arg2
+argument converted to
+.I key_serial_t
+type) to a keyring (provided in the
+.I arg3
+argument converted to
+.I key_serial_t
+type) of there is no matching key in the keyring, or replace the link
+to the matching key with a link to the new key. The caller should have
+.I link
+permission on the key being added and
+.I write
+permission on the keyring to which key being added to. Arguments
+.IR arg4 " and " arg5
+are ignored.
.TP
.B KEYCTL_UNLINK
-Unlink a key from a keyring.
+Unlink a key (provided in the
+.I arg2
+argument converted to
+.I key_serial_t
+type) from a keyring (provided in the
+.I arg3
+argument converted to
+.I key_serial_t
+type). The caller should have
+.I write
+permission on the keyring from which key being removed from. If the last link
+to a key is removed then that key will be scheduled for destruction.Arguments
+.IR arg4 " and " arg5
+are ignored.
.TP
.B KEYCTL_SEARCH
-Search for a key in a keyring.
+Search for a key in a keyring with ID provided in the
+.I arg2
+argument (converted to
+.I key_serial_t
+type). The
+.I arg3
+argument should be a
+.I char *
+pointing to the name of the type the key being searched (NUL-terminated
+character string up to 32 bytes in size), and the
+.I arg4
+argument should be a
+.I char *
+pointing to the NUL-terminated character string (up to 4096 bytes in size) with
+the description of the key being searched. The search is performed recursively
+starting from the keyring with ID provided in
+.IR arg2 .
+Only keyrings that grant the caller
+.I search
+permission will be searched (this includes the starting keyring).
+Only keys with
+.I search
+permission can be found. If the
+.I arg5
+argument (converted to
+.I key_serial_t
+type) contains non-zero value, it is interpreted as a keyring ID to which
+the found key should be linked.
.TP
.B KEYCTL_READ
-Read a key or keyring's contents.
+Read a payload of a key ID of which provided in the
+.I arg2
+argument (converted to
+.I key_serial_t
+type) to a buffer pointed by the
+.I arg3
+argument (converted to
+.I char *
+type) of size provided in the
+.I arg4
+argument (converted to kernel's
+.I size_t
+type). The key must either grant the caller
+.I read
+permission, or it must grant the caller
+.I search
+permission when searched for from the process keyrings. The
+.I arg5
+argument is ignored.
.TP
.B KEYCTL_INSTANTIATE
-Instantiate a partially constructed key.
+Instantiate a partially constructed key ID of which provided in the
+.I arg2
+argument (converted to
+.I key_serial_t
+type) with a payload pointed by the
+.I arg3
+argument (converted to
+.I char *
+type) of size provided in the
+.I arg4
+argument (converted to kernel's
+.I size_t
+type). Instantiated key will be linked to keyring Id of which provided in the
+.I arg5
+argument (converted to
+.I key_serial_t
+type). The caller must have the appropriate instantiation permit set (auth key).
.TP
.B KEYCTL_NEGATE
-Negate a partially constructed key.
+Negatively instantiate a partially constructed key with ID provided in the
+.I arg2
+argument (converted to
+.I key_serial_t
+type), setting timeout (in seconds) to the value provided in the
+.I arg3
+argument (converted to
+.I unsigned int
+type). Instantiated key will be linked to keyring Id of which provided in the
+.I arg4
+argument (converted to
+.I key_serial_t
+type). The caller must have the appropriate instantiation permit set
+(authorisation key, see
+.I KEYCTL_ASSUME_AUTHORITY
+command). Negative keys are used to rate limit repeated
+.BR request_key ()
+calls by causing them to return
+.B -ENOKEY
+until the negative key expires. Equivalent to
+.BI "keyctl(" KEYCTL_REJECT ", " arg2 ", " arg3 ", " ENOKEY ", " arg4 )
+call.
+The
+.I arg5
+argument is ignored.
.TP
-.B KEYCTL_SET_REQKEY_KEYRING
-Set default request-key keyring.
+.BR KEYCTL_SET_REQKEY_KEYRING " (since Linux 2.6.13)"
+Read or set default keyring in which
+.BR request_key ()
+will cache keys. The
+.I arg2
+argument (converted to
+.I int
+type) should contain one of the following values, defined in
+.IR <linux/keyring.h> :
+
+.nf
+.in +4n
+#define KEY_REQKEY_DEFL_NO_CHANGE -1 /* No change */
+#define KEY_REQKEY_DEFL_DEFAULT 0 /* Default keyring */
+#define KEY_REQKEY_DEFL_THREAD_KEYRING 1 /* Thread-specific keyring */
+#define KEY_REQKEY_DEFL_PROCESS_KEYRING 2 /* Process-specific keyring */
+#define KEY_REQKEY_DEFL_SESSION_KEYRING 3 /* Session-specific keyring */
+#define KEY_REQKEY_DEFL_USER_KEYRING 4 /* UID-specific keyring */
+#define KEY_REQKEY_DEFL_USER_SESSION_KEYRING 5 /* Session keyring of UID */
+'\" 8bbf4976b59fc9fc2861e79cab7beb3f6d647640
+#define KEY_REQKEY_DEFL_REQUESTOR_KEYRING 7 /* since 2.6.29: requestor keyring */
+.in
+.fi
+
+All other values (including still-unsupported
+.BR KEY_REQKEY_DEFL_GROUP_KEYRING )
+are invalid. Arguments
+.IR arg3 ", " arg4 " and " arg5
+are ignored.
.TP
-.B KEYCTL_SET_TIMEOUT
-Set timeout on a key.
+.BR KEYCTL_SET_TIMEOUT " (since Linux 2.6.16)"
+Set timeout on a key. ID of a key provided in the
+.I arg2
+argument (converted to
+.I key_serial_t
+type), timeout value (in seconds from current time) provided in the
+.I arg3
+argument (converted to
+.I unsigned int
+type). the caller must either have the
+.I setattr
+permission or hold an instantiation authorisation token for the key. Timeout
+value of 0 clears the timeout. The key and any links to the key will be
+automatically garbage collected after the timeout expires. Arguments
+.IR arg4 " and " arg5
+are ignored.
.TP
-.B KEYCTL_ASSUME_AUTHORITY
-Assume authority to instantiate key.
+.BR KEYCTL_ASSUME_AUTHORITY " (since Linux 2.6.16)"
+Assume (or clear) the authority for the key instantiation. The ID of
+the authorisation key provided in the
+.I arg2
+argument (converted to
+.I key_serial_t
+type). The caller must have the instantiation key in their process keyrings
+with a
+.I search
+permission grant available to the caller. If the ID given in the
+.I arg2
+argument is 0, then the setting will be cleared. Arguments
+.IR arg3 ", " arg4 " and " arg5
+are ignored.
+.TP
+.BR KEYCTL_GET_SECURITY " (since Linux 2.6.26)"
+Get LSM security label of the specified key. The ID of the key should be provided
+in the
+.I arg2
+argument (converted to
+.I key_serial_t
+type). Buffer where security label should be stored provided in the
+.I arg3
+argument (converted to
+.I char *
+type) with its size provided in the
+.I arg4
+argument (converted to kernel's
+.I size_t
+type). The
+.I arg5
+argument is ignored.
+.TP
+.BR KEYCTL_SESSION_TO_PARENT " (since Linux 2.6.32)"
+Apply session keyring to parent process.
+.IP
+Attempt to install the calling process's session keyring on the process's parent
+process. The keyring must exist and must grant the caller
+.I link
+permission, and the parent process must be single-threaded and must have
+the same effective ownership as this process and mustn't be SUID/SGID.
+.IP
+The keyring will be emplaced on the parent when it next resumes userspace.
+Arguments
+.IR arg2 ", " arg3 ", " arg4 " and " arg5
+are ignored.
+.TP
+.BR KEYCTL_REJECT " (since Linux 2.6.39)"
+Negatively instantiate a partially constructed key with ID provided in the
+.I arg2
+argument (converted to
+.I key_serial_t
+type), setting timeout (in seconds) to the value provided in the
+.I arg3
+argument (converted to
+.I unsigned int
+type) and instantiation error to the value provided in the
+.I arg4
+argument (converted to
+.I unsigned int
+type). Instantiated key will be linked to keyring Id of which provided in the
+.I arg5
+argument (converted to
+.I key_serial_t
+type). The caller must have the appropriate instantiation permit set
+(authorisation key, see
+.I KEYCTL_ASSUME_AUTHORITY
+command). Negative keys are used to rate limit repeated
+.BR request_key ()
+calls by causing them to return the error specified until the negative key
+expires.
+.TP
+.BR KEYCTL_INSTANTIATE_IOV " (since Linux 2.6.39)"
+Instantiate a key (with ID specified in the
+.I arg2
+argument of type
+.IR key_serial_t )
+with the specified (in the
+.I arg3
+argument of type
+.IR "const struct iovec *" )
+multipart payload and link the key into
+the destination keyring (ID of which provided in the
+.I arg4
+argument of type
+.IR key_serial_t )
+if non-zero one is given. The caller must have the appropriate instantiation
+permit (authorisation key, see
+.I KEYCTL_ASSUME_AUTHORITY
+command) set for this to work. No other permissions are required. The
+.I arg5
+argument is ignored.
+.TP
+.BR KEYCTL_INVALIDATE " (since Linux 3.5)"
+Invalidate a key with ID provided in the
+.I arg2
+argument (converted to
+.I key_serial_t
+type). The caller must have
+.I search
+permission in order to perform invalidation. The key and any links to the key
+will be automatically garbage collected immediately. Arguments
+.IR arg3 ", " arg4 " and " arg5
+are ignored.
+.TP
+.BR KEYCTL_GET_PERSISTENT " (since Linux 3.13)"
+Get the persistent keyring of the user specified in the
+.I arg2
+(converted to
+.I uid_t
+type) and link it to the keyring with ID provided in the
+.I arg3
+argument (converted to
+.I key_serial_t
+type). If -1 is provided as UID, current user's ID is used. Arguments
+.IR arg4 " and " arg5
+are ignored.
+.TP
+.BR KEYCTL_DH_COMPUTE " (since Linux 4.7)"
+Compute Diffie-Hellman values. The
+.I arg2
+argument is a pointer to
+.B struct kayctl_dh_params
