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

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

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

---
* keyctl.2 (SYNOPSIS): Added information regarding direct call via
  sysctl(2).
  (DESCRIPTION): Added information regarding argument usage for
  KEYCTL_GET_KEYRING_ID, KEYCTL_JOIN_SESSION_KEYRING, KEYCTL_UPDATE,
  KEYCTL_REVOKE, KEYCTL_CHOWN, KEYCTL_SETPERM, KEYCTL_DESCRIBE,
  KEYCTL_CLEAR, KEYCTL_LINK, KEYCTL_UNLINK, KEYCTL_SEARCH, KEYCTL_READ,
  KEYCTL_INSTANTIATE, KEYCTL_NEGATE, KEYCTL_SET_REQKEY_KEYRING,
  KEYCTL_SET_TIMEOUT, KEYCTL_ASSUME_AUTHORITY commands; added
  information about KEYCTL_GET_SECURITY, KEYCTL_SESSION_TO_PARENT,
  KEYCTL_REJECT, KEYCTL_INSTANTIATE_IOV, KEYCTL_INVALIDATE,
  KEYCTL_GET_PERSISTENT, KEYCTL_DH_COMPUTE commands.
  (RETURN VALUE): Added information regarding command-specific return
  values (where it is non-zero).
  (ERRORS): Addad information regarding ENOTSUPP, ENOTDIR, ENFILE,
  ENOENT, EINVAL error codes.
---
 man2/keyctl.2 |  619 ++++++++++++++++++++++++++++++++++++++++++++++++++++-----
 1 file changed, 568 insertions(+), 51 deletions(-)

diff --git a/man2/keyctl.2 b/man2/keyctl.2
index 2cb382a..001197c 100644
--- a/man2/keyctl.2
+++ b/man2/keyctl.2
@@ -8,30 +8,6 @@
 .\" 2 of the License, or (at your option) any later version.
 .\" %%%LICENSE_END
 .\"
-.\" FIXME Document KEYCTL_GET_SECURITY (new in 2.6.26)
-.\"		commit 70a5bb72b55e82fbfbf1e22cae6975fac58a1e2d
-.\"		Author: David Howells <dhowells-H+wXaHxf7aLQT0dZR+AlfA@public.gmane.org>
-.\"		Date:   Tue Apr 29 01:01:26 2008 -0700
-.\" FIXME Document KEYCTL_SESSION_TO_PARENT (new in 2.6.32)
-.\"		commit ee18d64c1f632043a02e6f5ba5e045bb26a5465f
-.\"		Author: David Howells <dhowells-H+wXaHxf7aLQT0dZR+AlfA@public.gmane.org>
-.\"		Date:   Wed Sep 2 09:14:21 2009 +0100
-.\" FIXME Document KEYCTL_REJECT (new in 2.6.39)
-.\"		commit fdd1b94581782a2ddf9124414e5b7a5f48ce2f9c
-.\"		Author: David Howells <dhowells-H+wXaHxf7aLQT0dZR+AlfA@public.gmane.org>
-.\"		Documentation/security/keys.txt
-.\" FIXME Document KEYCTL_INSTANTIATE_IOV (new in 2.6.39)
-.\"		commit ee009e4a0d4555ed522a631bae9896399674f064
-.\"		Author: David Howells <dhowells-H+wXaHxf7aLQT0dZR+AlfA@public.gmane.org>
-.\"		Documentation/security/keys.txt
-.\" FIXME Document KEYCTL_INVALIDATE (new in 3.5)
-.\"		commit fd75815f727f157a05f4c96b5294a4617c0557da
-.\"		Author: David Howells <dhowells-H+wXaHxf7aLQT0dZR+AlfA@public.gmane.org>
-.\"		Documentation/security/keys.txt
-.\" FIXME Document KEYCTL_GET_PERSISTENT (new in 3.13)
-.\"		commit f36f8c75ae2e7d4da34f4c908cebdb4aa42c977e
-.\"		Author: David Howells <dhowells-H+wXaHxf7aLQT0dZR+AlfA@public.gmane.org>
-.\"
 .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
-- 
1.7.10.4

--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] keyctl.2: updates regarding command usage, return values and error codes

[Michael Kerrisk (man-pages)]

[CC extended:
keyrings-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
Mat Martineau, as he added KEYCTL_DH_COMPUTE]


Hello Eugene,

On 09/26/2016 04:24 AM, Eugene Syromyatnikov wrote:
> 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.

Cheers,

Michael

> ---
> * keyctl.2 (SYNOPSIS): Added information regarding direct call via
>   sysctl(2).
>   (DESCRIPTION): Added information regarding argument usage for
>   KEYCTL_GET_KEYRING_ID, KEYCTL_JOIN_SESSION_KEYRING, KEYCTL_UPDATE,
>   KEYCTL_REVOKE, KEYCTL_CHOWN, KEYCTL_SETPERM, KEYCTL_DESCRIBE,
>   KEYCTL_CLEAR, KEYCTL_LINK, KEYCTL_UNLINK, KEYCTL_SEARCH, KEYCTL_READ,
>   KEYCTL_INSTANTIATE, KEYCTL_NEGATE, KEYCTL_SET_REQKEY_KEYRING,
>   KEYCTL_SET_TIMEOUT, KEYCTL_ASSUME_AUTHORITY commands; added
>   information about KEYCTL_GET_SECURITY, KEYCTL_SESSION_TO_PARENT,
>   KEYCTL_REJECT, KEYCTL_INSTANTIATE_IOV, KEYCTL_INVALIDATE,
>   KEYCTL_GET_PERSISTENT, KEYCTL_DH_COMPUTE commands.
>   (RETURN VALUE): Added information regarding command-specific return
>   values (where it is non-zero).
>   (ERRORS): Addad information regarding ENOTSUPP, ENOTDIR, ENFILE,
>   ENOENT, EINVAL error codes.
> ---
>  man2/keyctl.2 |  619 ++++++++++++++++++++++++++++++++++++++++++++++++++++-----
>  1 file changed, 568 insertions(+), 51 deletions(-)
> 
> diff --git a/man2/keyctl.2 b/man2/keyctl.2
> index 2cb382a..001197c 100644
> --- a/man2/keyctl.2
> +++ b/man2/keyctl.2
> @@ -8,30 +8,6 @@
>  .\" 2 of the License, or (at your option) any later version.
>  .\" %%%LICENSE_END
>  .\"
> -.\" FIXME Document KEYCTL_GET_SECURITY (new in 2.6.26)
> -.\"		commit 70a5bb72b55e82fbfbf1e22cae6975fac58a1e2d
> -.\"		Author: David Howells <dhowells-H+wXaHxf7aLQT0dZR+AlfA@public.gmane.org>
> -.\"		Date:   Tue Apr 29 01:01:26 2008 -0700
> -.\" FIXME Document KEYCTL_SESSION_TO_PARENT (new in 2.6.32)
> -.\"		commit ee18d64c1f632043a02e6f5ba5e045bb26a5465f
> -.\"		Author: David Howells <dhowells-H+wXaHxf7aLQT0dZR+AlfA@public.gmane.org>
> -.\"		Date:   Wed Sep 2 09:14:21 2009 +0100
> -.\" FIXME Document KEYCTL_REJECT (new in 2.6.39)
> -.\"		commit fdd1b94581782a2ddf9124414e5b7a5f48ce2f9c
> -.\"		Author: David Howells <dhowells-H+wXaHxf7aLQT0dZR+AlfA@public.gmane.org>
> -.\"		Documentation/security/keys.txt
> -.\" FIXME Document KEYCTL_INSTANTIATE_IOV (new in 2.6.39)
> -.\"		commit ee009e4a0d4555ed522a631bae9896399674f064
> -.\"		Author: David Howells <dhowells-H+wXaHxf7aLQT0dZR+AlfA@public.gmane.org>
> -.\"		Documentation/security/keys.txt
> -.\" FIXME Document KEYCTL_INVALIDATE (new in 3.5)
> -.\"		commit fd75815f727f157a05f4c96b5294a4617c0557da
> -.\"		Author: David Howells <dhowells-H+wXaHxf7aLQT0dZR+AlfA@public.gmane.org>
> -.\"		Documentation/security/keys.txt
> -.\" FIXME Document KEYCTL_GET_PERSISTENT (new in 3.13)
> -.\"		commit f36f8c75ae2e7d4da34f4c908cebdb4aa42c977e
> -.\"		Author: David Howells <dhowells-H+wXaHxf7aLQT0dZR+AlfA@public.gmane.org>
> -.\"
>  .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
> 


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] keyctl.2: updates regarding command usage, return values and error codes

[Mat Martineau]

Michael and Eugene -

On Mon, 26 Sep 2016, Michael Kerrisk (man-pages) wrote:

> [CC extended:
> keyrings-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
> Mat Martineau, as he added KEYCTL_DH_COMPUTE]
>
>
> Hello Eugene,
>
> On 09/26/2016 04:24 AM, Eugene Syromyatnikov wrote:
>> 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

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


>> ---
>> * keyctl.2 (SYNOPSIS): Added information regarding direct call via
>>   sysctl(2).
>>   (DESCRIPTION): Added information regarding argument usage for
>>   KEYCTL_GET_KEYRING_ID, KEYCTL_JOIN_SESSION_KEYRING, KEYCTL_UPDATE,
>>   KEYCTL_REVOKE, KEYCTL_CHOWN, KEYCTL_SETPERM, KEYCTL_DESCRIBE,
>>   KEYCTL_CLEAR, KEYCTL_LINK, KEYCTL_UNLINK, KEYCTL_SEARCH, KEYCTL_READ,
>>   KEYCTL_INSTANTIATE, KEYCTL_NEGATE, KEYCTL_SET_REQKEY_KEYRING,
>>   KEYCTL_SET_TIMEOUT, KEYCTL_ASSUME_AUTHORITY commands; added
>>   information about KEYCTL_GET_SECURITY, KEYCTL_SESSION_TO_PARENT,
>>   KEYCTL_REJECT, KEYCTL_INSTANTIATE_IOV, KEYCTL_INVALIDATE,
>>   KEYCTL_GET_PERSISTENT, KEYCTL_DH_COMPUTE commands.
>>   (RETURN VALUE): Added information regarding command-specific return
>>   values (where it is non-zero).
>>   (ERRORS): Addad information regarding ENOTSUPP, ENOTDIR, ENFILE,
>>   ENOENT, EINVAL error codes.
>> ---
>>  man2/keyctl.2 |  619 ++++++++++++++++++++++++++++++++++++++++++++++++++++-----
>>  1 file changed, 568 insertions(+), 51 deletions(-)
>>
>> diff --git a/man2/keyctl.2 b/man2/keyctl.2
>> index 2cb382a..001197c 100644
>> --- a/man2/keyctl.2
>> +++ b/man2/keyctl.2
>> @@ -8,30 +8,6 @@
>>  .\" 2 of the License, or (at your option) any later version.
>>  .\" %%%LICENSE_END
>>  .\"
>> -.\" FIXME Document KEYCTL_GET_SECURITY (new in 2.6.26)
>> -.\"		commit 70a5bb72b55e82fbfbf1e22cae6975fac58a1e2d
>> -.\"		Author: David Howells <dhowells-H+wXaHxf7aLQT0dZR+AlfA@public.gmane.org>
>> -.\"		Date:   Tue Apr 29 01:01:26 2008 -0700
>> -.\" FIXME Document KEYCTL_SESSION_TO_PARENT (new in 2.6.32)
>> -.\"		commit ee18d64c1f632043a02e6f5ba5e045bb26a5465f
>> -.\"		Author: David Howells <dhowells-H+wXaHxf7aLQT0dZR+AlfA@public.gmane.org>
>> -.\"		Date:   Wed Sep 2 09:14:21 2009 +0100
>> -.\" FIXME Document KEYCTL_REJECT (new in 2.6.39)
>> -.\"		commit fdd1b94581782a2ddf9124414e5b7a5f48ce2f9c
>> -.\"		Author: David Howells <dhowells-H+wXaHxf7aLQT0dZR+AlfA@public.gmane.org>
>> -.\"		Documentation/security/keys.txt
>> -.\" FIXME Document KEYCTL_INSTANTIATE_IOV (new in 2.6.39)
>> -.\"		commit ee009e4a0d4555ed522a631bae9896399674f064
>> -.\"		Author: David Howells <dhowells-H+wXaHxf7aLQT0dZR+AlfA@public.gmane.org>
>> -.\"		Documentation/security/keys.txt
>> -.\" FIXME Document KEYCTL_INVALIDATE (new in 3.5)
>> -.\"		commit fd75815f727f157a05f4c96b5294a4617c0557da
>> -.\"		Author: David Howells <dhowells-H+wXaHxf7aLQT0dZR+AlfA@public.gmane.org>
>> -.\"		Documentation/security/keys.txt
>> -.\" FIXME Document KEYCTL_GET_PERSISTENT (new in 3.13)
>> -.\"		commit f36f8c75ae2e7d4da34f4c908cebdb4aa42c977e
>> -.\"		Author: David Howells <dhowells-H+wXaHxf7aLQT0dZR+AlfA@public.gmane.org>
>> -.\"
>>  .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

kayctl -> keyctl

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

ID's -> IDs

>> +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
>>
>
>
> -- 
> 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
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] keyctl.2: updates regarding command usage, return values and error codes

[Michael Kerrisk (man-pages)]

[Dave Howells, your input is desired :-)]

Hello Mat,

On 09/26/2016 08:03 PM, Mat Martineau wrote:
> 
> Michael and Eugene -
> 
> On Mon, 26 Sep 2016, Michael Kerrisk (man-pages) wrote:
> 
>> [CC extended:
>> keyrings-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
>> Mat Martineau, as he added KEYCTL_DH_COMPUTE]
>>
>>
>> Hello Eugene,
>>
>> On 09/26/2016 04:24 AM, Eugene Syromyatnikov wrote:
>>> 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
> 
>>
>> 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. 

I'm not sure what the intent was, but this page was always very thin.

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

Okay.

> 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 think there's actually value in documenting the system call API also.
It's useful information for anyone who might implement another
library layer, for example. It also provides a check for what's
documented in the keyctl_*(3) pages. But while we're at it it, it'd make 
sense also to include references to each library function at the 
appropriate point in the keyctl(2) page.

I'd also be interested to hear Dave Howells' perspective.

Thanks,

Michael

> I have a couple of minor fixes for the KEYCTL_DH_COMPUTE content below.
> 
> Thanks,
> 
> Mat
> 
> 
>>> ---
>>> * keyctl.2 (SYNOPSIS): Added information regarding direct call via
>>>   sysctl(2).
>>>   (DESCRIPTION): Added information regarding argument usage for
>>>   KEYCTL_GET_KEYRING_ID, KEYCTL_JOIN_SESSION_KEYRING, KEYCTL_UPDATE,
>>>   KEYCTL_REVOKE, KEYCTL_CHOWN, KEYCTL_SETPERM, KEYCTL_DESCRIBE,
>>>   KEYCTL_CLEAR, KEYCTL_LINK, KEYCTL_UNLINK, KEYCTL_SEARCH, KEYCTL_READ,
>>>   KEYCTL_INSTANTIATE, KEYCTL_NEGATE, KEYCTL_SET_REQKEY_KEYRING,
>>>   KEYCTL_SET_TIMEOUT, KEYCTL_ASSUME_AUTHORITY commands; added
>>>   information about KEYCTL_GET_SECURITY, KEYCTL_SESSION_TO_PARENT,
>>>   KEYCTL_REJECT, KEYCTL_INSTANTIATE_IOV, KEYCTL_INVALIDATE,
>>>   KEYCTL_GET_PERSISTENT, KEYCTL_DH_COMPUTE commands.
>>>   (RETURN VALUE): Added information regarding command-specific return
>>>   values (where it is non-zero).
>>>   (ERRORS): Addad information regarding ENOTSUPP, ENOTDIR, ENFILE,
>>>   ENOENT, EINVAL error codes.
>>> ---
>>>  man2/keyctl.2 |  619 ++++++++++++++++++++++++++++++++++++++++++++++++++++-----
>>>  1 file changed, 568 insertions(+), 51 deletions(-)
>>>
>>> diff --git a/man2/keyctl.2 b/man2/keyctl.2
>>> index 2cb382a..001197c 100644
>>> --- a/man2/keyctl.2
>>> +++ b/man2/keyctl.2
>>> @@ -8,30 +8,6 @@
>>>  .\" 2 of the License, or (at your option) any later version.
>>>  .\" %%%LICENSE_END
>>>  .\"
>>> -.\" FIXME Document KEYCTL_GET_SECURITY (new in 2.6.26)
>>> -.\"		commit 70a5bb72b55e82fbfbf1e22cae6975fac58a1e2d
>>> -.\"		Author: David Howells <dhowells-H+wXaHxf7aLQT0dZR+AlfA@public.gmane.org>
>>> -.\"		Date:   Tue Apr 29 01:01:26 2008 -0700
>>> -.\" FIXME Document KEYCTL_SESSION_TO_PARENT (new in 2.6.32)
>>> -.\"		commit ee18d64c1f632043a02e6f5ba5e045bb26a5465f
>>> -.\"		Author: David Howells <dhowells-H+wXaHxf7aLQT0dZR+AlfA@public.gmane.org>
>>> -.\"		Date:   Wed Sep 2 09:14:21 2009 +0100
>>> -.\" FIXME Document KEYCTL_REJECT (new in 2.6.39)
>>> -.\"		commit fdd1b94581782a2ddf9124414e5b7a5f48ce2f9c
>>> -.\"		Author: David Howells <dhowells-H+wXaHxf7aLQT0dZR+AlfA@public.gmane.org>
>>> -.\"		Documentation/security/keys.txt
>>> -.\" FIXME Document KEYCTL_INSTANTIATE_IOV (new in 2.6.39)
>>> -.\"		commit ee009e4a0d4555ed522a631bae9896399674f064
>>> -.\"		Author: David Howells <dhowells-H+wXaHxf7aLQT0dZR+AlfA@public.gmane.org>
>>> -.\"		Documentation/security/keys.txt
>>> -.\" FIXME Document KEYCTL_INVALIDATE (new in 3.5)
>>> -.\"		commit fd75815f727f157a05f4c96b5294a4617c0557da
>>> -.\"		Author: David Howells <dhowells-H+wXaHxf7aLQT0dZR+AlfA@public.gmane.org>
>>> -.\"		Documentation/security/keys.txt
>>> -.\" FIXME Document KEYCTL_GET_PERSISTENT (new in 3.13)
>>> -.\"		commit f36f8c75ae2e7d4da34f4c908cebdb4aa42c977e
>>> -.\"		Author: David Howells <dhowells-H+wXaHxf7aLQT0dZR+AlfA@public.gmane.org>
>>> -.\"
>>>  .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
> 
> kayctl -> keyctl
> 
>>> +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
> 
> ID's -> IDs
> 
>>> +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
>>>
>>
>>
>> -- 
>> 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 Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] keyctl.2: updates regarding command usage, return values and error codes

[Michael Kerrisk (man-pages)]

Hello Eugene,

On 09/26/2016 04:24 AM, Eugene Syromyatnikov wrote:
> 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.

Yes, thanks! It was very useful, and provided me with the motivation
to do even more work on the page. (For the moment, these changes 
are sitting in a private branch.) In the process, virtually all of
the original page text is now gone, and since you and I are now the 
principal copyright holders, 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?

Thanks,

Michael


> 
> ---
> * keyctl.2 (SYNOPSIS): Added information regarding direct call via
>   sysctl(2).
>   (DESCRIPTION): Added information regarding argument usage for
>   KEYCTL_GET_KEYRING_ID, KEYCTL_JOIN_SESSION_KEYRING, KEYCTL_UPDATE,
>   KEYCTL_REVOKE, KEYCTL_CHOWN, KEYCTL_SETPERM, KEYCTL_DESCRIBE,
>   KEYCTL_CLEAR, KEYCTL_LINK, KEYCTL_UNLINK, KEYCTL_SEARCH, KEYCTL_READ,
>   KEYCTL_INSTANTIATE, KEYCTL_NEGATE, KEYCTL_SET_REQKEY_KEYRING,
>   KEYCTL_SET_TIMEOUT, KEYCTL_ASSUME_AUTHORITY commands; added
>   information about KEYCTL_GET_SECURITY, KEYCTL_SESSION_TO_PARENT,
>   KEYCTL_REJECT, KEYCTL_INSTANTIATE_IOV, KEYCTL_INVALIDATE,
>   KEYCTL_GET_PERSISTENT, KEYCTL_DH_COMPUTE commands.
>   (RETURN VALUE): Added information regarding command-specific return
>   values (where it is non-zero).
>   (ERRORS): Addad information regarding ENOTSUPP, ENOTDIR, ENFILE,
>   ENOENT, EINVAL error codes.
> ---
>  man2/keyctl.2 |  619 ++++++++++++++++++++++++++++++++++++++++++++++++++++-----
>  1 file changed, 568 insertions(+), 51 deletions(-)
> 
> diff --git a/man2/keyctl.2 b/man2/keyctl.2
> index 2cb382a..001197c 100644
> --- a/man2/keyctl.2
> +++ b/man2/keyctl.2
> @@ -8,30 +8,6 @@
>  .\" 2 of the License, or (at your option) any later version.
>  .\" %%%LICENSE_END
>  .\"
> -.\" FIXME Document KEYCTL_GET_SECURITY (new in 2.6.26)
> -.\"		commit 70a5bb72b55e82fbfbf1e22cae6975fac58a1e2d
> -.\"		Author: David Howells <dhowells-H+wXaHxf7aLQT0dZR+AlfA@public.gmane.org>
> -.\"		Date:   Tue Apr 29 01:01:26 2008 -0700
> -.\" FIXME Document KEYCTL_SESSION_TO_PARENT (new in 2.6.32)
> -.\"		commit ee18d64c1f632043a02e6f5ba5e045bb26a5465f
> -.\"		Author: David Howells <dhowells-H+wXaHxf7aLQT0dZR+AlfA@public.gmane.org>
> -.\"		Date:   Wed Sep 2 09:14:21 2009 +0100
> -.\" FIXME Document KEYCTL_REJECT (new in 2.6.39)
> -.\"		commit fdd1b94581782a2ddf9124414e5b7a5f48ce2f9c
> -.\"		Author: David Howells <dhowells-H+wXaHxf7aLQT0dZR+AlfA@public.gmane.org>
> -.\"		Documentation/security/keys.txt
> -.\" FIXME Document KEYCTL_INSTANTIATE_IOV (new in 2.6.39)
> -.\"		commit ee009e4a0d4555ed522a631bae9896399674f064
> -.\"		Author: David Howells <dhowells-H+wXaHxf7aLQT0dZR+AlfA@public.gmane.org>
> -.\"		Documentation/security/keys.txt
> -.\" FIXME Document KEYCTL_INVALIDATE (new in 3.5)
> -.\"		commit fd75815f727f157a05f4c96b5294a4617c0557da
> -.\"		Author: David Howells <dhowells-H+wXaHxf7aLQT0dZR+AlfA@public.gmane.org>
> -.\"		Documentation/security/keys.txt
> -.\" FIXME Document KEYCTL_GET_PERSISTENT (new in 3.13)
> -.\"		commit f36f8c75ae2e7d4da34f4c908cebdb4aa42c977e
> -.\"		Author: David Howells <dhowells-H+wXaHxf7aLQT0dZR+AlfA@public.gmane.org>
> -.\"
>  .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
> 


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] keyctl.2: updates regarding command usage, return values and error codes

[Eugene Syromyatnikov]

On Thu, Oct 27, 2016 at 9:30 AM, Michael Kerrisk (man-pages)
<mtk.manpages-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org> wrote:
> 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?
Yes, sure.


-- 
Eugene "eSyr" Syromyatnikov
mailto:evgSyr-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org
xmpp:eSyr@jabber.{ru|org}
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] keyctl.2: updates regarding command usage, return values and error codes

[Michael Kerrisk (man-pages)]

Hello Mat,

On 26 September 2016 at 20:03, Mat Martineau
<mathew.j.martineau-VuQAYsv1563Yd54FQh9/CA@public.gmane.org> wrote:
>
> Michael and Eugene -
>
> On Mon, 26 Sep 2016, Michael Kerrisk (man-pages) wrote:
>
>> [CC extended:
>> keyrings-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
>> Mat Martineau, as he added KEYCTL_DH_COMPUTE]
>>
>>
>> Hello Eugene,
>>
>> On 09/26/2016 04:24 AM, Eugene Syromyatnikov wrote:
>>>
>>> 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

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.

Cheers,

Michael
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] keyctl.2: updates regarding command usage, return values and error codes

[Mat Martineau]

Hi Michael,

On Thu, 3 Nov 2016, Michael Kerrisk (man-pages) wrote:

> Hello Mat,
>
> On 26 September 2016 at 20:03, Mat Martineau
> <mathew.j.martineau-VuQAYsv1563Yd54FQh9/CA@public.gmane.org> wrote:
>>
>> Michael and Eugene -
>>
>> On Mon, 26 Sep 2016, Michael Kerrisk (man-pages) wrote:
>>
>>> [CC extended:
>>> keyrings-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
>>> Mat Martineau, as he added KEYCTL_DH_COMPUTE]
>>>
>>>
>>> Hello Eugene,
>>>
>>> On 09/26/2016 04:24 AM, Eugene Syromyatnikov wrote:
>>>>
>>>> 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
>
> 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.

--
Mat Martineau
Intel OTC
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] keyctl.2: updates regarding command usage, return values and error codes

[Michael Kerrisk (man-pages)]

Hello Mat,

On 11/04/2016 04:20 PM, Mat Martineau wrote:
> 
> Hi Michael,
> 
> On Thu, 3 Nov 2016, Michael Kerrisk (man-pages) wrote:
> 
>> Hello Mat,
>>
>> On 26 September 2016 at 20:03, Mat Martineau
>> <mathew.j.martineau-VuQAYsv1563Yd54FQh9/CA@public.gmane.org> wrote:
>>>
>>> Michael and Eugene -
>>>
>>> On Mon, 26 Sep 2016, Michael Kerrisk (man-pages) wrote:
>>>
>>>> [CC extended:
>>>> keyrings-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
>>>> Mat Martineau, as he added KEYCTL_DH_COMPUTE]
>>>>
>>>>
>>>> Hello Eugene,
>>>>
>>>> On 09/26/2016 04:24 AM, Eugene Syromyatnikov wrote:
>>>>>
>>>>> 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
>>
>> 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.

Thanks. I've added much of this text you wrote to the keyctl(2) page.

Cheers,

Michael


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html