From 461a8ce5355a7d1aad63fd098d9e13baef7d1200 Mon Sep 17 00:00:00 2001 From: Michael Kerrisk Date: Mon, 17 Oct 2016 15:42:58 +0200 Subject: [PATCH] keyctl.2: srcfix: rewrap source lines Signed-off-by: Michael Kerrisk --- man2/keyctl.2 | 239 ++++++++++++++++++++++++++++++++------------------ 1 file changed, 155 insertions(+), 84 deletions(-) diff --git a/man2/keyctl.2 b/man2/keyctl.2 index d28de96be..cca22d8a6 100644 --- a/man2/keyctl.2 +++ b/man2/keyctl.2 @@ -30,8 +30,8 @@ keyctl \- manipulate the kernel's key management facility .BR keyctl () (along with .IR add_key (2)) -provides abilities for userspace key manipulation. The operation performed by -the +provides abilities for userspace key manipulation. +The operation performed by the .BR keyctl () call is determined by the value of the .I option @@ -44,10 +44,11 @@ Ask for a keyring's whose ID provided in .IR key_serial_t ). If the .I arg3 -argument contains non-zero value, new keyring would be created. Caller should -have +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 +permission on a keyring for it to be found. +Arguments .IR arg4 and arg5 are ignored. .TP @@ -58,16 +59,18 @@ 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 +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 +to successfully join. +Arguments .IR arg3 ", " arg4 ", " arg5 are ignored. .TP .B KEYCTL_UPDATE -Update a key's data payload using data provided. The +Update a key's data payload using data provided. +The .I arg2 argument (converted to .IR key_serial_t ) @@ -77,10 +80,12 @@ 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 +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 +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 @@ -91,12 +96,14 @@ Revoke a key with ID provided in .IR key_serial_t ). The caller should have .IR write " or " setattr -permissions. Arguments +permissions. +Arguments .IR arg3 ", " arg4 ", " arg5 are ignored. .TP .B KEYCTL_CHOWN -Set ownership of a key. The +Set ownership of a key. +The .I arg2 argument (converted to .IR key_serial_t ) @@ -111,14 +118,18 @@ argument (converted to 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 +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 +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 @@ -133,40 +144,49 @@ argument (converted to .IR key_perms_t ). The key must grant .I setattr -permission to the caller. If the caller doesn't have +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: +(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 +Allows reading attributes of a key. +Needed for .IR KEYCTL_DESCRIBE . .IP \(bu .BR Read . -Allows reading key's payload. Needed for +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 +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 +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 +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 +This permits a key's UID, GID and permissions mask to be changed. +Needed for .IR KEYCTL_REVOKE ", " KEYCTL_CHOWN ", " KEYCTL_SETPERM . .RE .IP @@ -175,7 +195,8 @@ The arguments are ignored. .TP .B KEYCTL_DESCRIBE -Describe a key. Key ID to be described should be provided in the +Describe a key. +Key ID to be described should be provided in the .I arg2 argument (converted to .IR key_serial_t ), @@ -187,9 +208,11 @@ and the .I arg4 argument should contain size of the buffer (of kernel's .I size_t -type). The key must grant the caller +type). +The key must grant the caller .I view -permission. Writing to buffer is attempted only in case buffer is non-NULL and +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 @@ -200,7 +223,8 @@ The description itself provided in .IR type ; uid ; gid ; perm ; description "" .RE .IP -format. The +format. +The .I arg5 argument is ignored. .TP @@ -211,7 +235,8 @@ argument (converted to .IR key_serial_t ). Caller should have .I write -permission. Arguments +permission. +Arguments .IR arg3 ", " arg4 ", " arg5 are ignored. .TP @@ -225,11 +250,13 @@ type) to a keyring (provided in the 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 +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 +permission on the keyring to which key being added to. +Arguments .IR arg4 " and " arg5 are ignored. .TP @@ -242,10 +269,13 @@ type) from a keyring (provided in the .I arg3 argument converted to .I key_serial_t -type). The caller should have +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 +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 @@ -254,7 +284,8 @@ Search for a key in a keyring with ID provided in the .I arg2 argument (converted to .I key_serial_t -type). The +type). +The .I arg3 argument should be a .I char * @@ -264,7 +295,8 @@ character string up to 32 bytes in size), and the 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 +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 @@ -272,7 +304,8 @@ Only keyrings that grant the caller permission will be searched (this includes the starting keyring). Only keys with .I search -permission can be found. If the +permission can be found. +If the .I arg5 argument (converted to .I key_serial_t @@ -292,11 +325,13 @@ type) of size provided in the .I arg4 argument (converted to kernel's .I size_t -type). The key must either grant the caller +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 +permission when searched for from the process keyrings. +The .I arg5 argument is ignored. .TP @@ -313,11 +348,13 @@ 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 +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). +type). +The caller must have the appropriate instantiation permit set (auth key). .TP .B KEYCTL_NEGATE Negatively instantiate a partially constructed key with ID provided in the @@ -328,18 +365,22 @@ 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 +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 +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 +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 +until the negative key expires. +Equivalent to .BI "keyctl(" KEYCTL_REJECT ", " arg2 ", " arg3 ", " ENOKEY ", " arg4 ) call. The @@ -349,7 +390,8 @@ argument is ignored. .BR KEYCTL_SET_REQKEY_KEYRING " (since Linux 2.6.13)" Read or set default keyring in which .BR request_key () -will cache keys. The +will cache keys. +The .I arg2 argument (converted to .I int @@ -372,12 +414,14 @@ type) should contain one of the following values, defined in All other values (including still-unsupported .BR KEY_REQKEY_DEFL_GROUP_KEYRING ) -are invalid. Arguments +are invalid. +Arguments .IR arg3 ", " arg4 " and " arg5 are ignored. .TP .BR KEYCTL_SET_TIMEOUT " (since Linux 2.6.16)" -Set timeout on a key. ID of a key provided in the +Set timeout on a key. +ID of a key provided in the .I arg2 argument (converted to .I key_serial_t @@ -385,36 +429,43 @@ 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 +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 +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 .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 +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 +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 +permission grant available to the caller. +If the ID given in the .I arg2 -argument is 0, then the setting will be cleared. Arguments +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 +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 +type). +Buffer where security label should be stored provided in the .I arg3 argument (converted to .I char * @@ -422,15 +473,17 @@ type) with its size provided in the .I arg4 argument (converted to kernel's .I size_t -type). The +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 +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. @@ -453,14 +506,17 @@ 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 +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 +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 +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. @@ -479,10 +535,13 @@ 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 +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 +command) set for this to work. +No other permissions are required. +The .I arg5 argument is ignored. .TP @@ -491,10 +550,13 @@ Invalidate a key with ID provided in the .I arg2 argument (converted to .I key_serial_t -type). The caller must have +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 +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 @@ -507,12 +569,15 @@ 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 +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 +Compute Diffie-Hellman values. +The .I arg2 argument is a pointer to .B struct kayctl_dh_params @@ -533,7 +598,8 @@ struct keyctl_dh_params { , 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 +calculation. +Result is calculated as .IR "base^private mod prime" . The .I arg3 @@ -543,9 +609,12 @@ 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 +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 @@ -578,7 +647,8 @@ 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 +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 @@ -640,7 +710,8 @@ and the key requested for unlinking isn't linked to the keyring. .I option is .B KEYCTL_DH_COMPUTE -and buffer size provided is not enough for the result to fit in. Provide 0 as +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