keyctl.2: updates regarding command usage, return values and error codes

Hello.

I've drafted some updates to the keyctl.2 man page while preparing test for strace syscall decoder. It is focused mostly on description of argument format used in various commands and return values/error codes. Information is based on Documentation/security/keys.txt, include/uapi/linux/keyctl.h, and source code and comments in security/keys/ (mostly comments from security/keys/keyctl.c). Hope you find it useful.

---
* 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(-)

man2/keyctl.2 +568 -51

index 2cb382a..001197c 100644
@@ -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 <[email protected]>
-.\"		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 <[email protected]>
-.\"		Date:   Wed Sep 2 09:14:21 2009 +0100
-.\" FIXME Document KEYCTL_REJECT (new in 2.6.39)
-.\"		commit fdd1b94581782a2ddf9124414e5b7a5f48ce2f9c
-.\"		Author: David Howells <[email protected]>
-.\"		Documentation/security/keys.txt
-.\" FIXME Document KEYCTL_INSTANTIATE_IOV (new in 2.6.39)
-.\"		commit ee009e4a0d4555ed522a631bae9896399674f064
-.\"		Author: David Howells <[email protected]>
-.\"		Documentation/security/keys.txt
-.\" FIXME Document KEYCTL_INVALIDATE (new in 3.5)
-.\"		commit fd75815f727f157a05f4c96b5294a4617c0557da
-.\"		Author: David Howells <[email protected]>
-.\"		Documentation/security/keys.txt
-.\" FIXME Document KEYCTL_GET_PERSISTENT (new in 3.13)
-.\"		commit f36f8c75ae2e7d4da34f4c908cebdb4aa42c977e
-.\"		Author: David Howells <[email protected]>
-.\"
 .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
+which is defined in
+.I <linux/keyctl.h>
+as follows:
+
+.nf
+.in +4n
+struct keyctl_dh_params {
+    int32_t private;
+    int32_t prime;
+    int32_t base;
+};
+.in
+.fi
+
+, where
+.IR private ", " prime " and " base
+fields are ID's of the keys, payload of which would be used for DH values
+calculation. Result is calculated as
+.IR "base^private mod prime" .
+The
+.I arg3
+argument (converted to
+.I char *
+type) should point to output buffer with size passed in the
+.I arg4
+argument (converted to kernel's
+.I size_t
+type). Buffer should be big enough in order to accommodate output data,
+otherwise error is returned. NULL pointer can be provided as buffer in order
+to obtains required buffer size. The
+.I arg5
+argument is reserved and should be 0.
 .P
 These are wrapped by
 .B libkeyutils
 into individual functions (listed under SEE ALSO)
 to permit the compiler to check types.
 .SH RETURN VALUE
-On success
-.BR keyctl ()
-returns the serial number of the key it found.
-On error, the value \-1
-will be returned and errno will have been set to an appropriate error.
+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 description (including terminating NUL byte), irrespective
+of the provided buffer size.
+.TP
+.B KEYCTL_SEARCH
+The found key ID.
+.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
+Old setting (one of
+.IR KEY_REQKEY_DEFL_USER_* )
+.TP
+.B KEYCTL_ASSUME_AUTHORITY
+0, if the ID given is 0. ID of the authorisation key matching key with the given
+ID if non-zero key ID provided.
+.TP
+.B KEYCTL_GET_SECURITY
+The amount of information available (including terminating NUL byte),
+irrespective of the provided buffer size.
+.TP
+.B KEYCTL_GET_PERSISTENT
+ID of the persistent keyring.
+.TP
+.B KEYCTL_DH_COMPUTE
+Amount of bytes being copied.
+.TP
+All other commands
+Zero.
+.PP
+On error, \-1 is returned, and
+.I errno
+is set appropriately to indicate the error.
 .SH ERRORS
 .TP
 .B EACCES

@@ -126,6 +617,32 @@ A revoked key was found or specified.
 .TP
 .B ENOKEY
 No matching key was found or an invalid key was specified.
+.TP
+.B ENOTSUPP
+.I option
+is
+.B KEYCTL_UPDATE
+and key type does not support updating.
+.TP
+.B ENOTDIR
+Key of keyring type is expected but ID of a key with a different type provided.
+.TP
+.B ENFILE
+Keyring is full.
+.TP
+.B ENOENT
+.I option
+is
+.B KEYCTL_UNLINK
+and the key requested for unlinking isn't linked to the keyring.
+.TP
+.B EINVAL
+.I option
+is
+.B KEYCTL_DH_COMPUTE
+and buffer size provided is not enough for the result to fit in. Provide 0 as
+a buffer size in order to obtain minimum buffer size first.
+
 .SH LINKING
 Although this is a Linux system call, it is not present in
 .I libc

[CC extended:
[email protected]
Mat Martineau, as he added KEYCTL_DH_COMPUTE]

Hello Eugene,

Quoted 9 lines · Eugene Syromyatnikov

Hello.

I've drafted some updates to the keyctl.2 man page while preparing test for strace syscall decoder. It is focused mostly on description of argument format used in various commands and return values/error codes. Information is based on Documentation/security/keys.txt, include/uapi/linux/keyctl.h, and source code and comments in security/keys/ (mostly comments from security/keys/keyctl.c). Hope you find it useful.

This looks like a tremendous piece of work on a page that lacked a lot of detail. I'm inclined to apply the patch, but hope that we might first get some comment from David and Mat, in case there are details that could be improved.

Quoted 574 lines

---
* 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(-)

man2/keyctl.2 +459 -46

index 2cb382a..001197c 100644
@@ -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 <[email protected]>
-.\"		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 <[email protected]>
-.\"		Date:   Wed Sep 2 09:14:21 2009 +0100
-.\" FIXME Document KEYCTL_REJECT (new in 2.6.39)
-.\"		commit fdd1b94581782a2ddf9124414e5b7a5f48ce2f9c
-.\"		Author: David Howells <[email protected]>
-.\"		Documentation/security/keys.txt
-.\" FIXME Document KEYCTL_INSTANTIATE_IOV (new in 2.6.39)
-.\"		commit ee009e4a0d4555ed522a631bae9896399674f064
-.\"		Author: David Howells <[email protected]>
-.\"		Documentation/security/keys.txt
-.\" FIXME Document KEYCTL_INVALIDATE (new in 3.5)
-.\"		commit fd75815f727f157a05f4c96b5294a4617c0557da
-.\"		Author: David Howells <[email protected]>
-.\"		Documentation/security/keys.txt
-.\" FIXME Document KEYCTL_GET_PERSISTENT (new in 3.13)
-.\"		commit f36f8c75ae2e7d4da34f4c908cebdb4aa42c977e
-.\"		Author: David Howells <[email protected]>
-.\"
 .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

man2/keyctl.2 keyctl \- manipulate the kernel's key management facility · line 518

Quoted 8 lines

man2/keyctl.2 +8 -0

+.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

Quoted 9 lines

man2/keyctl.2 +9 -0

+which is defined in
+.I <linux/keyctl.h>
+as follows:
+
+.nf
+.in +4n
+struct keyctl_dh_params {
+    int32_t private;
+    int32_t prime;

man2/keyctl.2 keyctl \- manipulate the kernel's key management facility · line 535

Quoted 8 lines

man2/keyctl.2 +8 -0

+    int32_t base;
+};
+.in
+.fi
+
+, where
+.IR private ", " prime " and " base
+fields are ID's of the keys, payload of which would be used for DH values

Quoted 98 lines

man2/keyctl.2 +80 -5

+calculation. Result is calculated as
+.IR "base^private mod prime" .
+The
+.I arg3
+argument (converted to
+.I char *
+type) should point to output buffer with size passed in the
+.I arg4
+argument (converted to kernel's
+.I size_t
+type). Buffer should be big enough in order to accommodate output data,
+otherwise error is returned. NULL pointer can be provided as buffer in order
+to obtains required buffer size. The
+.I arg5
+argument is reserved and should be 0.
 .P
 These are wrapped by
 .B libkeyutils
 into individual functions (listed under SEE ALSO)
 to permit the compiler to check types.
 .SH RETURN VALUE
-On success
-.BR keyctl ()
-returns the serial number of the key it found.
-On error, the value \-1
-will be returned and errno will have been set to an appropriate error.
+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 description (including terminating NUL byte), irrespective
+of the provided buffer size.
+.TP
+.B KEYCTL_SEARCH
+The found key ID.
+.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
+Old setting (one of
+.IR KEY_REQKEY_DEFL_USER_* )
+.TP
+.B KEYCTL_ASSUME_AUTHORITY
+0, if the ID given is 0. ID of the authorisation key matching key with the given
+ID if non-zero key ID provided.
+.TP
+.B KEYCTL_GET_SECURITY
+The amount of information available (including terminating NUL byte),
+irrespective of the provided buffer size.
+.TP
+.B KEYCTL_GET_PERSISTENT
+ID of the persistent keyring.
+.TP
+.B KEYCTL_DH_COMPUTE
+Amount of bytes being copied.
+.TP
+All other commands
+Zero.
+.PP
+On error, \-1 is returned, and
+.I errno
+is set appropriately to indicate the error.
 .SH ERRORS
 .TP
 .B EACCES

@@ -126,6 +617,32 @@ A revoked key was found or specified.
 .TP
 .B ENOKEY
 No matching key was found or an invalid key was specified.
+.TP
+.B ENOTSUPP
+.I option
+is
+.B KEYCTL_UPDATE
+and key type does not support updating.
+.TP
+.B ENOTDIR
+Key of keyring type is expected but ID of a key with a different type provided.
+.TP
+.B ENFILE
+Keyring is full.
+.TP
+.B ENOENT
+.I option
+is
+.B KEYCTL_UNLINK
+and the key requested for unlinking isn't linked to the keyring.
+.TP
+.B EINVAL
+.I option
+is

Quoted 8 lines

man2/keyctl.2 +4 -0

+.B KEYCTL_DH_COMPUTE
+and buffer size provided is not enough for the result to fit in. Provide 0 as
+a buffer size in order to obtain minimum buffer size first.
+
 .SH LINKING
 Although this is a Linux system call, it is not present in
 .I libc

Signature · 3 lines

Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

Michael and Eugene -

Quoted 5 lines · Michael Kerrisk (man-pages)

[CC extended:
[email protected]
Mat Martineau, as he added KEYCTL_DH_COMPUTE]

Quoted 12 lines

Hello Eugene,

Quoted 9 lines · Eugene Syromyatnikov

Hello.

I've drafted some updates to the keyctl.2 man page while preparing test for strace syscall decoder. It is focused mostly on description of argument format used in various commands and return values/error codes. Information is based on Documentation/security/keys.txt, include/uapi/linux/keyctl.h, and source code and comments in security/keys/ (mostly comments from security/keys/keyctl.c). Hope you find it useful.

There's additional reference material from keyctl.1 and keyctl.3 in
https://git.kernel.org/cgit/linux/kernel/git/dhowells/keyutils.git/ . The 'next' branch has updates for KEYCTL_DH_COMPUTE

Quoted 1 line

Quoted 4 lines

This looks like a tremendous piece of work on a page that lacked a lot of detail. I'm inclined to apply the patch, but hope that we might first get some comment from David and Mat, in case there are details that could be improved.

Looking at the other sections of keyctl.2 (in particular LINKING and SEE ALSO), the intent is apparently to direct people to other libkeyutils functions rather than making direct use of the keyctl() syscall.

The
details of each keyctl command are documented in the relevant keyctl_*.3 man page. keyctl() itself is part of libkeyutils (not libc), so a user always has access to the more specific keyctl_* functions at the same time as keyctl().

If we stick with that model, then keyctl.2 would still need updates for the new KEYCTL_CMD_ functions that are currently available.

I favor keeping the details in section 3 so information isn't duplicated (and doesn't have to be kept consistent across multiple man pages as functionality evolves), and to encourage use of the relevant libkeyutils functions. keyctl.2 could be clarified to make sure everyone can be redirected properly. Would this be consistent with other syscalls? I spot checked a few that are referenced in syscalls.2 and it seems like they typically are called via library functions that have the proper argument types specified.

I have a couple of minor fixes for the KEYCTL_DH_COMPUTE content below.

Thanks,

Mat

Quoted 574 lines

Quoted 574 lines

---
* 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(-)

man2/keyctl.2 +459 -46

index 2cb382a..001197c 100644
@@ -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 <[email protected]>
-.\"		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 <[email protected]>
-.\"		Date:   Wed Sep 2 09:14:21 2009 +0100
-.\" FIXME Document KEYCTL_REJECT (new in 2.6.39)
-.\"		commit fdd1b94581782a2ddf9124414e5b7a5f48ce2f9c
-.\"		Author: David Howells <[email protected]>
-.\"		Documentation/security/keys.txt
-.\" FIXME Document KEYCTL_INSTANTIATE_IOV (new in 2.6.39)
-.\"		commit ee009e4a0d4555ed522a631bae9896399674f064
-.\"		Author: David Howells <[email protected]>
-.\"		Documentation/security/keys.txt
-.\" FIXME Document KEYCTL_INVALIDATE (new in 3.5)
-.\"		commit fd75815f727f157a05f4c96b5294a4617c0557da
-.\"		Author: David Howells <[email protected]>
-.\"		Documentation/security/keys.txt
-.\" FIXME Document KEYCTL_GET_PERSISTENT (new in 3.13)
-.\"		commit f36f8c75ae2e7d4da34f4c908cebdb4aa42c977e
-.\"		Author: David Howells <[email protected]>
-.\"
 .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

Quoted 8 lines

man2/keyctl.2 keyctl \- manipulate the kernel's key management facility · line 518

Quoted 8 lines

man2/keyctl.2 +8 -0

+.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

kayctl -> keyctl

Quoted 9 lines

Quoted 9 lines

man2/keyctl.2 +9 -0

+which is defined in
+.I <linux/keyctl.h>
+as follows:
+
+.nf
+.in +4n
+struct keyctl_dh_params {
+    int32_t private;
+    int32_t prime;

Quoted 8 lines

man2/keyctl.2 keyctl \- manipulate the kernel's key management facility · line 535

Quoted 8 lines

man2/keyctl.2 +8 -0

+    int32_t base;
+};
+.in
+.fi
+
+, where
+.IR private ", " prime " and " base
+fields are ID's of the keys, payload of which would be used for DH values

ID's -> IDs

Quoted 98 lines

Quoted 98 lines

man2/keyctl.2 +80 -5

+calculation. Result is calculated as
+.IR "base^private mod prime" .
+The
+.I arg3
+argument (converted to
+.I char *
+type) should point to output buffer with size passed in the
+.I arg4
+argument (converted to kernel's
+.I size_t
+type). Buffer should be big enough in order to accommodate output data,
+otherwise error is returned. NULL pointer can be provided as buffer in order
+to obtains required buffer size. The
+.I arg5
+argument is reserved and should be 0.
 .P
 These are wrapped by
 .B libkeyutils
 into individual functions (listed under SEE ALSO)
 to permit the compiler to check types.
 .SH RETURN VALUE
-On success
-.BR keyctl ()
-returns the serial number of the key it found.
-On error, the value \-1
-will be returned and errno will have been set to an appropriate error.
+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 description (including terminating NUL byte), irrespective
+of the provided buffer size.
+.TP
+.B KEYCTL_SEARCH
+The found key ID.
+.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
+Old setting (one of
+.IR KEY_REQKEY_DEFL_USER_* )
+.TP
+.B KEYCTL_ASSUME_AUTHORITY
+0, if the ID given is 0. ID of the authorisation key matching key with the given
+ID if non-zero key ID provided.
+.TP
+.B KEYCTL_GET_SECURITY
+The amount of information available (including terminating NUL byte),
+irrespective of the provided buffer size.
+.TP
+.B KEYCTL_GET_PERSISTENT
+ID of the persistent keyring.
+.TP
+.B KEYCTL_DH_COMPUTE
+Amount of bytes being copied.
+.TP
+All other commands
+Zero.
+.PP
+On error, \-1 is returned, and
+.I errno
+is set appropriately to indicate the error.
 .SH ERRORS
 .TP
 .B EACCES

@@ -126,6 +617,32 @@ A revoked key was found or specified.
 .TP
 .B ENOKEY
 No matching key was found or an invalid key was specified.
+.TP
+.B ENOTSUPP
+.I option
+is
+.B KEYCTL_UPDATE
+and key type does not support updating.
+.TP
+.B ENOTDIR
+Key of keyring type is expected but ID of a key with a different type provided.
+.TP
+.B ENFILE
+Keyring is full.
+.TP
+.B ENOENT
+.I option
+is
+.B KEYCTL_UNLINK
+and the key requested for unlinking isn't linked to the keyring.
+.TP
+.B EINVAL
+.I option
+is

Quoted 15 lines

Quoted 8 lines

man2/keyctl.2 +4 -0

+.B KEYCTL_DH_COMPUTE
+and buffer size provided is not enough for the result to fit in. Provide 0 as
+a buffer size in order to obtain minimum buffer size first.
+
 .SH LINKING
 Although this is a Linux system call, it is not present in
 .I libc

Signature · 3 lines

Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

--
Mat Martineau
Intel OTC

Michael and Eugene -

Quoted 5 lines · Michael Kerrisk (man-pages)

[CC extended:
[email protected]
Mat Martineau, as he added KEYCTL_DH_COMPUTE]

Quoted 14 lines

Hello Eugene,

Quoted 11 lines · Eugene Syromyatnikov

Hello.

I've drafted some updates to the keyctl.2 man page while preparing test for strace syscall decoder. It is focused mostly on description of argument
format used in various commands and return values/error codes. Information is based on Documentation/security/keys.txt, include/uapi/linux/keyctl.h, and source code and comments in security/keys/ (mostly comments from security/keys/keyctl.c). Hope you find it useful.

There's additional reference material from keyctl.1 and keyctl.3 in
https://git.kernel.org/cgit/linux/kernel/git/dhowells/keyutils.git/ . The 'next' branch has updates for KEYCTL_DH_COMPUTE

Hello Mat,

Quoted 26 lines · Mat Martineau

Michael and Eugene -

Quoted 5 lines · Michael Kerrisk (man-pages)

[CC extended:
[email protected]
Mat Martineau, as he added KEYCTL_DH_COMPUTE]

Quoted 14 lines

Hello Eugene,

Quoted 11 lines · Eugene Syromyatnikov

Hello.

I've drafted some updates to the keyctl.2 man page while preparing test for strace syscall decoder. It is focused mostly on description of argument
format used in various commands and return values/error codes. Information is based on Documentation/security/keys.txt, include/uapi/linux/keyctl.h, and source code and comments in security/keys/ (mostly comments from security/keys/keyctl.c). Hope you find it useful.

Quoted 3 lines

There's additional reference material from keyctl.1 and keyctl.3 in
https://git.kernel.org/cgit/linux/kernel/git/dhowells/keyutils.git/ . The 'next' branch has updates for KEYCTL_DH_COMPUTE

Thanks.

One thing that the man page and the commit message for the DH compute feature lack is a rationale for why this operation was added.

So, why was it added? It'd be good to document that.

Hi Michael,

Quoted 34 lines · Michael Kerrisk (man-pages)

Hello Mat,

Quoted 26 lines · Mat Martineau

Michael and Eugene -

Quoted 5 lines · Michael Kerrisk (man-pages)

[CC extended:
[email protected]
Mat Martineau, as he added KEYCTL_DH_COMPUTE]

Quoted 14 lines

Hello Eugene,

Quoted 11 lines · Eugene Syromyatnikov

Hello.

I've drafted some updates to the keyctl.2 man page while preparing test for strace syscall decoder. It is focused mostly on description of argument
format used in various commands and return values/error codes. Information is based on Documentation/security/keys.txt, include/uapi/linux/keyctl.h, and source code and comments in security/keys/ (mostly comments from security/keys/keyctl.c). Hope you find it useful.

Quoted 3 lines

There's additional reference material from keyctl.1 and keyctl.3 in
https://git.kernel.org/cgit/linux/kernel/git/dhowells/keyutils.git/ . The 'next' branch has updates for KEYCTL_DH_COMPUTE

Quoted 6 lines

Thanks.

One thing that the man page and the commit message for the DH compute feature lack is a rationale for why this operation was added.

So, why was it added? It'd be good to document that.

You can find some context here:

http://www.spinics.net/lists/keyrings/msg00654.html

Diffie-Hellman computations can be performed in userspace, but require a multiple-precision integer library. Using the kernel gives access to the kernel MPI implementation, and allows access to secure or acceleration hardware.

The keyctl() system call was a good fit due to the DH algorithm's use for deriving shared keys, and allows the type of the key to determine which DH implementation (software or hardware) is appropriate.

Hello.

I've drafted some updates to the keyctl.2 man page while preparing test for strace syscall decoder. It is focused mostly on description of argument format used in various commands and return values/error codes. Information is based on Documentation/security/keys.txt, include/uapi/linux/keyctl.h, and source code and comments in security/keys/ (mostly comments from security/keys/keyctl.c). Hope you find it useful.

---
* 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(-)

man2/keyctl.2 +568 -51

index 2cb382a..001197c 100644
@@ -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 <[email protected]>
-.\"		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 <[email protected]>
-.\"		Date:   Wed Sep 2 09:14:21 2009 +0100
-.\" FIXME Document KEYCTL_REJECT (new in 2.6.39)
-.\"		commit fdd1b94581782a2ddf9124414e5b7a5f48ce2f9c
-.\"		Author: David Howells <[email protected]>
-.\"		Documentation/security/keys.txt
-.\" FIXME Document KEYCTL_INSTANTIATE_IOV (new in 2.6.39)
-.\"		commit ee009e4a0d4555ed522a631bae9896399674f064
-.\"		Author: David Howells <[email protected]>
-.\"		Documentation/security/keys.txt
-.\" FIXME Document KEYCTL_INVALIDATE (new in 3.5)
-.\"		commit fd75815f727f157a05f4c96b5294a4617c0557da
-.\"		Author: David Howells <[email protected]>
-.\"		Documentation/security/keys.txt
-.\" FIXME Document KEYCTL_GET_PERSISTENT (new in 3.13)
-.\"		commit f36f8c75ae2e7d4da34f4c908cebdb4aa42c977e
-.\"		Author: David Howells <[email protected]>
-.\"
 .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
+which is defined in
+.I <linux/keyctl.h>
+as follows:
+
+.nf
+.in +4n
+struct keyctl_dh_params {
+    int32_t private;
+    int32_t prime;
+    int32_t base;
+};
+.in
+.fi
+
+, where
+.IR private ", " prime " and " base
+fields are ID's of the keys, payload of which would be used for DH values
+calculation. Result is calculated as
+.IR "base^private mod prime" .
+The
+.I arg3
+argument (converted to
+.I char *
+type) should point to output buffer with size passed in the
+.I arg4
+argument (converted to kernel's
+.I size_t
+type). Buffer should be big enough in order to accommodate output data,
+otherwise error is returned. NULL pointer can be provided as buffer in order
+to obtains required buffer size. The
+.I arg5
+argument is reserved and should be 0.
 .P
 These are wrapped by
 .B libkeyutils
 into individual functions (listed under SEE ALSO)
 to permit the compiler to check types.
 .SH RETURN VALUE
-On success
-.BR keyctl ()
-returns the serial number of the key it found.
-On error, the value \-1
-will be returned and errno will have been set to an appropriate error.
+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 description (including terminating NUL byte), irrespective
+of the provided buffer size.
+.TP
+.B KEYCTL_SEARCH
+The found key ID.
+.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
+Old setting (one of
+.IR KEY_REQKEY_DEFL_USER_* )
+.TP
+.B KEYCTL_ASSUME_AUTHORITY
+0, if the ID given is 0. ID of the authorisation key matching key with the given
+ID if non-zero key ID provided.
+.TP
+.B KEYCTL_GET_SECURITY
+The amount of information available (including terminating NUL byte),
+irrespective of the provided buffer size.
+.TP
+.B KEYCTL_GET_PERSISTENT
+ID of the persistent keyring.
+.TP
+.B KEYCTL_DH_COMPUTE
+Amount of bytes being copied.
+.TP
+All other commands
+Zero.
+.PP
+On error, \-1 is returned, and
+.I errno
+is set appropriately to indicate the error.
 .SH ERRORS
 .TP
 .B EACCES

@@ -126,6 +617,32 @@ A revoked key was found or specified.
 .TP
 .B ENOKEY
 No matching key was found or an invalid key was specified.
+.TP
+.B ENOTSUPP
+.I option
+is
+.B KEYCTL_UPDATE
+and key type does not support updating.
+.TP
+.B ENOTDIR
+Key of keyring type is expected but ID of a key with a different type provided.
+.TP
+.B ENFILE
+Keyring is full.
+.TP
+.B ENOENT
+.I option
+is
+.B KEYCTL_UNLINK
+and the key requested for unlinking isn't linked to the keyring.
+.TP
+.B EINVAL
+.I option
+is
+.B KEYCTL_DH_COMPUTE
+and buffer size provided is not enough for the result to fit in. Provide 0 as
+a buffer size in order to obtain minimum buffer size first.
+
 .SH LINKING
 Although this is a Linux system call, it is not present in
 .I libc

I'd like to propose that we switch the
licenses to my preferred licenses for man pages:

https://www.kernel.org/doc/man-pages/licenses.html#verbatim

Would you be agreeable?