LDP
/
man-pages
mirror of https://github.com/mkerrisk/man-pages
0
1
Fork 0
Code Releases Activity

keyctl.2: srcfix: rewrap source lines 

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
This commit is contained in:
Michael Kerrisk 2016-10-17 15:42:58 +02:00
parent 9a9febc854
commit 461a8ce535
1 changed files with 155 additions and 84 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

239
man2/keyctl.2
View File

@ -30,8 +30,8 @@ keyctl \- manipulate the kernel's key management facility
.BR keyctl () .BR keyctl ()
(along with (along with
.IR add_key (2)) .IR add_key (2))
provides abilities for userspace key manipulation. The operation performed by provides abilities for userspace key manipulation.
the The operation performed by the
.BR keyctl () .BR keyctl ()
call is determined by the value of the call is determined by the value of the
.I option .I option
@ -44,10 +44,11 @@ Ask for a keyring's whose ID provided in
.IR key_serial_t ). .IR key_serial_t ).
If the If the
.I arg3 .I arg3
argument contains non-zero value, new keyring would be created. Caller should argument contains non-zero value, new keyring would be created.
have Caller should have
.I search .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 .IR arg4 and arg5
are ignored. are ignored.
.TP .TP
@ -58,16 +59,18 @@ is
.BR NULL ) .BR NULL )
or join existing named session keyring or join existing named session keyring
.RI ( arg2 .RI ( arg2
should be pointer to a string containing session name in this case). The caller should be pointer to a string containing session name in this case).
should have The caller should have
.I search .I search
permission on the keyring name of which is provided in order permission on the keyring name of which is provided in order
to successfully join. Arguments to successfully join.
Arguments
.IR arg3 ", " arg4 ", " arg5 .IR arg3 ", " arg4 ", " arg5
are ignored. are ignored.
.TP .TP
.B KEYCTL_UPDATE .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 .I arg2
argument (converted to argument (converted to
.IR key_serial_t ) .IR key_serial_t )
@ -77,10 +80,12 @@ argument is interpreted as a pointer to the new payload and
.I arg4 .I arg4
(converted to (converted to
.IR size_t ) .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 .I write
permission on the key specified and key type should support updating. Negative permission on the key specified and key type should support updating.
key can be positively instantiated with this call. The Negative key can be positively instantiated with this call.
The
.I arg5 .I arg5
argument is ignored. argument is ignored.
.TP .TP
@ -91,12 +96,14 @@ Revoke a key with ID provided in
.IR key_serial_t ). .IR key_serial_t ).
The caller should have The caller should have
.IR write " or " setattr .IR write " or " setattr
permissions. Arguments permissions.
Arguments
.IR arg3 ", " arg4 ", " arg5 .IR arg3 ", " arg4 ", " arg5
are ignored. are ignored.
.TP .TP
.B KEYCTL_CHOWN .B KEYCTL_CHOWN
Set ownership of a key. The Set ownership of a key.
The
.I arg2 .I arg2
argument (converted to argument (converted to
.IR key_serial_t ) .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). contains new group ID (or -1 in case group ID shouldn't be changed).
The key must grant the caller The key must grant the caller
.I setattr .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 the caller is not a member of, the caller must have
.I CAP_SYS_ADMIN .I CAP_SYS_ADMIN
capability (see capability (see
.IR capabilities (7) .IR capabilities (7)
for details). If the UID is to be changed, the new user must have sufficient for details).
quota to accept the key. The quota deduction will be removed from the old user If the UID is to be changed, the new user must have sufficient
to the new user should the attribute be changed. The 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 .I arg5
argument is ignored. argument is ignored.
.TP .TP
@ -133,40 +144,49 @@ argument (converted to
.IR key_perms_t ). .IR key_perms_t ).
The key must grant The key must grant
.I setattr .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 .I CAP_SYS_ADMIN
capability, it can only change permissions of the keys it owns. capability, it can only change permissions of the keys it owns.
Permissions contains mask of available operations for possessor Permissions contains mask of available operations for possessor
(since Linux 2.6.14), user, group, other. Each mask is eight bit in size, (since Linux 2.6.14), user, group, other.
with only six currently used. The available permissions are: Each mask is eight bit in size, with only six currently used.
The available permissions are:
.RS .RS
.IP \(bu 3 .IP \(bu 3
.BR View . .BR View .
Allows reading attributes of a key. Needed for Allows reading attributes of a key.
Needed for
.IR KEYCTL_DESCRIBE . .IR KEYCTL_DESCRIBE .
.IP \(bu .IP \(bu
.BR Read . .BR Read .
Allows reading key's payload. Needed for Allows reading key's payload.
Needed for
.IR KEYCTL_READ . .IR KEYCTL_READ .
.IP \(bu .IP \(bu
.BR Write . .BR Write .
Allows update or instantiation of key's payload. For a keyring, it enables Allows update or instantiation of key's payload.
adding and removal of keys to a keyring. Needed for 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_UPDATE ", " KEYCTL_REVOKE ", " KEYCTL_CLEAR ", " KEYCTL_LINK ", "
.IR KEYCTL_UNLINK . .IR KEYCTL_UNLINK .
.IP \(bu .IP \(bu
.BR Search . .BR Search .
This permits keyrings to be searched and keys to be found. Searches can This permits keyrings to be searched and keys to be found.
only recurse into nested keyrings that have search permission set. Needed for 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_GET_KEYRING_ID ", " KEYCTL_JOIN_SESSION_KEYRING ", " KEYCTL_SEARCH
.IR KEYCTL_INVALIDATE . .IR KEYCTL_INVALIDATE .
.IP \(bu .IP \(bu
.BR Link . .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 . .IR KEYCTL_LINK ", " KEYCTL_SESSION_TO_PARENT .
.IP \(bu .IP \(bu
.BR "Set attribute" " (since Linux. 2.6.15)." .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 . .IR KEYCTL_REVOKE ", " KEYCTL_CHOWN ", " KEYCTL_SETPERM .
.RE .RE
.IP .IP
@ -175,7 +195,8 @@ The
arguments are ignored. arguments are ignored.
.TP .TP
.B KEYCTL_DESCRIBE .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 .I arg2
argument (converted to argument (converted to
.IR key_serial_t ), .IR key_serial_t ),
@ -187,9 +208,11 @@ and the
.I arg4 .I arg4
argument should contain size of the buffer (of kernel's argument should contain size of the buffer (of kernel's
.I size_t .I size_t
type). The key must grant the caller type).
The key must grant the caller
.I view .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. has enough space to accept the description.
'\" Function commentary says it copies up to buflen bytes, bu see the '\" Function commentary says it copies up to buflen bytes, bu see the
'\" (buffer && buflen >= ret) condition in keyctl_describe_key() in '\" (buffer && buflen >= ret) condition in keyctl_describe_key() in
@ -200,7 +223,8 @@ The description itself provided in
.IR type ; uid ; gid ; perm ; description "<NUL>" .IR type ; uid ; gid ; perm ; description "<NUL>"
.RE .RE
.IP .IP
format. The format.
The
.I arg5 .I arg5
argument is ignored. argument is ignored.
.TP .TP
@ -211,7 +235,8 @@ argument (converted to
.IR key_serial_t ). .IR key_serial_t ).
Caller should have Caller should have
.I write .I write
permission. Arguments permission.
Arguments
.IR arg3 ", " arg4 ", " arg5 .IR arg3 ", " arg4 ", " arg5
are ignored. are ignored.
.TP .TP
@ -225,11 +250,13 @@ type) to a keyring (provided in the
argument converted to argument converted to
.I key_serial_t .I key_serial_t
type) of there is no matching key in the keyring, or replace the link 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 .I link
permission on the key being added and permission on the key being added and
.I write .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 .IR arg4 " and " arg5
are ignored. are ignored.
.TP .TP
@ -242,10 +269,13 @@ type) from a keyring (provided in the
.I arg3 .I arg3
argument converted to argument converted to
.I key_serial_t .I key_serial_t
type). The caller should have type).
The caller should have
.I write .I write
permission on the keyring from which key being removed from. If the last link permission on the keyring from which key being removed from.
to a key is removed then that key will be scheduled for destruction.Arguments If the last link
to a key is removed then that key will be scheduled for destruction.
Arguments
.IR arg4 " and " arg5 .IR arg4 " and " arg5
are ignored. are ignored.
.TP .TP
@ -254,7 +284,8 @@ Search for a key in a keyring with ID provided in the
.I arg2 .I arg2
argument (converted to argument (converted to
.I key_serial_t .I key_serial_t
type). The type).
The
.I arg3 .I arg3
argument should be a argument should be a
.I char * .I char *
@ -264,7 +295,8 @@ character string up to 32 bytes in size), and the
argument should be a argument should be a
.I char * .I char *
pointing to the NUL-terminated character string (up to 4096 bytes in size) with 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 starting from the keyring with ID provided in
.IR arg2 . .IR arg2 .
Only keyrings that grant the caller 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). permission will be searched (this includes the starting keyring).
Only keys with Only keys with
.I search .I search
permission can be found. If the permission can be found.
If the
.I arg5 .I arg5
argument (converted to argument (converted to
.I key_serial_t .I key_serial_t
@ -292,11 +325,13 @@ type) of size provided in the
.I arg4 .I arg4
argument (converted to kernel's argument (converted to kernel's
.I size_t .I size_t
type). The key must either grant the caller type).
The key must either grant the caller
.I read .I read
permission, or it must grant the caller permission, or it must grant the caller
.I search .I search
permission when searched for from the process keyrings. The permission when searched for from the process keyrings.
The
.I arg5 .I arg5
argument is ignored. argument is ignored.
.TP .TP
@ -313,11 +348,13 @@ type) of size provided in the
.I arg4 .I arg4
argument (converted to kernel's argument (converted to kernel's
.I size_t .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 .I arg5
argument (converted to argument (converted to
.I key_serial_t .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 .TP
.B KEYCTL_NEGATE .B KEYCTL_NEGATE
Negatively instantiate a partially constructed key with ID provided in the 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 .I arg3
argument (converted to argument (converted to
.I unsigned int .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 .I arg4
argument (converted to argument (converted to
.I key_serial_t .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 (authorisation key, see
.I KEYCTL_ASSUME_AUTHORITY .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 () .BR request_key ()
calls by causing them to return calls by causing them to return
.B -ENOKEY .B -ENOKEY
until the negative key expires. Equivalent to until the negative key expires.
Equivalent to
.BI "keyctl(" KEYCTL_REJECT ", " arg2 ", " arg3 ", " ENOKEY ", " arg4 ) .BI "keyctl(" KEYCTL_REJECT ", " arg2 ", " arg3 ", " ENOKEY ", " arg4 )
call. call.
The The
@ -349,7 +390,8 @@ argument is ignored.
.BR KEYCTL_SET_REQKEY_KEYRING " (since Linux 2.6.13)" .BR KEYCTL_SET_REQKEY_KEYRING " (since Linux 2.6.13)"
Read or set default keyring in which Read or set default keyring in which
.BR request_key () .BR request_key ()
will cache keys. The will cache keys.
The
.I arg2 .I arg2
argument (converted to argument (converted to
.I int .I int
@ -372,12 +414,14 @@ type) should contain one of the following values, defined in
All other values (including still-unsupported All other values (including still-unsupported
.BR KEY_REQKEY_DEFL_GROUP_KEYRING ) .BR KEY_REQKEY_DEFL_GROUP_KEYRING )
are invalid. Arguments are invalid.
Arguments
.IR arg3 ", " arg4 " and " arg5 .IR arg3 ", " arg4 " and " arg5
are ignored. are ignored.
.TP .TP
.BR KEYCTL_SET_TIMEOUT " (since Linux 2.6.16)" .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 .I arg2
argument (converted to argument (converted to
.I key_serial_t .I key_serial_t
@ -385,36 +429,43 @@ type), timeout value (in seconds from current time) provided in the
.I arg3 .I arg3
argument (converted to argument (converted to
.I unsigned int .I unsigned int
type). the caller must either have the type).
the caller must either have the
.I setattr .I setattr
permission or hold an instantiation authorisation token for the key. Timeout permission or hold an instantiation authorisation token for the key.
value of 0 clears the timeout. The key and any links to the key will be Timeout value of 0 clears the timeout.
automatically garbage collected after the timeout expires. Arguments The key and any links to the key will be
automatically garbage collected after the timeout expires.
Arguments
.IR arg4 " and " arg5 .IR arg4 " and " arg5
are ignored. are ignored.
.TP .TP
.BR KEYCTL_ASSUME_AUTHORITY " (since Linux 2.6.16)" .BR KEYCTL_ASSUME_AUTHORITY " (since Linux 2.6.16)"
Assume (or clear) the authority for the key instantiation. The ID of Assume (or clear) the authority for the key instantiation.
the authorisation key provided in the The ID of the authorisation key provided in the
.I arg2 .I arg2
argument (converted to argument (converted to
.I key_serial_t .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 with a
.I search .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 .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 .IR arg3 ", " arg4 " and " arg5
are ignored. are ignored.
.TP .TP
.BR KEYCTL_GET_SECURITY " (since Linux 2.6.26)" .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 Get LSM security label of the specified key.
in the The ID of the key should be provided in the
.I arg2 .I arg2
argument (converted to argument (converted to
.I key_serial_t .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 .I arg3
argument (converted to argument (converted to
.I char * .I char *
@ -422,15 +473,17 @@ type) with its size provided in the
.I arg4 .I arg4
argument (converted to kernel's argument (converted to kernel's
.I size_t .I size_t
type). The type).
The
.I arg5 .I arg5
argument is ignored. argument is ignored.
.TP .TP
.BR KEYCTL_SESSION_TO_PARENT " (since Linux 2.6.32)" .BR KEYCTL_SESSION_TO_PARENT " (since Linux 2.6.32)"
Apply session keyring to parent process. Apply session keyring to parent process.
.IP .IP
Attempt to install the calling process's session keyring on the process's parent Attempt to install the calling process's session keyring
process. The keyring must exist and must grant the caller on the process's parent process.
The keyring must exist and must grant the caller
.I link .I link
permission, and the parent process must be single-threaded and must have 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. 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 .I arg4
argument (converted to argument (converted to
.I unsigned int .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 .I arg5
argument (converted to argument (converted to
.I key_serial_t .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 (authorisation key, see
.I KEYCTL_ASSUME_AUTHORITY .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 () .BR request_key ()
calls by causing them to return the error specified until the negative key calls by causing them to return the error specified until the negative key
expires. expires.
@ -479,10 +535,13 @@ the destination keyring (ID of which provided in the
.I arg4 .I arg4
argument of type argument of type
.IR key_serial_t ) .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 permit (authorisation key, see
.I KEYCTL_ASSUME_AUTHORITY .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 .I arg5
argument is ignored. argument is ignored.
.TP .TP
@ -491,10 +550,13 @@ Invalidate a key with ID provided in the
.I arg2 .I arg2
argument (converted to argument (converted to
.I key_serial_t .I key_serial_t
type). The caller must have type).
The caller must have
.I search .I search
permission in order to perform invalidation. The key and any links to the key permission in order to perform invalidation.
will be automatically garbage collected immediately. Arguments The key and any links to the key
will be automatically garbage collected immediately.
Arguments
.IR arg3 ", " arg4 " and " arg5 .IR arg3 ", " arg4 " and " arg5
are ignored. are ignored.
.TP .TP
@ -507,12 +569,15 @@ type) and link it to the keyring with ID provided in the
.I arg3 .I arg3
argument (converted to argument (converted to
.I key_serial_t .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 .IR arg4 " and " arg5
are ignored. are ignored.
.TP .TP
.BR KEYCTL_DH_COMPUTE " (since Linux 4.7)" .BR KEYCTL_DH_COMPUTE " (since Linux 4.7)"
Compute Diffie-Hellman values. The Compute Diffie-Hellman values.
The
.I arg2 .I arg2
argument is a pointer to argument is a pointer to
.B struct kayctl_dh_params .B struct kayctl_dh_params
@ -533,7 +598,8 @@ struct keyctl_dh_params {
, where , where
.IR private ", " prime " and " base .IR private ", " prime " and " base
fields are ID's of the keys, payload of which would be used for DH values 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" . .IR "base^private mod prime" .
The The
.I arg3 .I arg3
@ -543,9 +609,12 @@ type) should point to output buffer with size passed in the
.I arg4 .I arg4
argument (converted to kernel's argument (converted to kernel's
.I size_t .I size_t
type). Buffer should be big enough in order to accommodate output data, type).
otherwise error is returned. NULL pointer can be provided as buffer in order Buffer should be big enough in order to accommodate output data,
to obtains required buffer size. The otherwise error is returned.
NULL pointer can be provided as buffer in order
to obtains required buffer size.
The
.I arg5 .I arg5
argument is reserved and should be 0. argument is reserved and should be 0.
.P .P
@ -578,7 +647,8 @@ Old setting (one of
.IR KEY_REQKEY_DEFL_USER_* ) .IR KEY_REQKEY_DEFL_USER_* )
.TP .TP
.B KEYCTL_ASSUME_AUTHORITY .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. ID if non-zero key ID provided.
.TP .TP
.B KEYCTL_GET_SECURITY .B KEYCTL_GET_SECURITY
@ -640,7 +710,8 @@ and the key requested for unlinking isn't linked to the keyring.
.I option .I option
is is
.B KEYCTL_DH_COMPUTE .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. a buffer size in order to obtain minimum buffer size first.
.SH LINKING .SH LINKING