diff options
| author | Alejandro Colomar <alx@kernel.org> | 2024-08-17 16:19:49 +0200 |
|---|---|---|
| committer | Alejandro Colomar <alx@kernel.org> | 2024-08-21 23:51:12 +0200 |
| commit | 82d1ecdfe7a9048bd013c18ebd244f8e6d0b8df9 (patch) | |
| tree | 8ca8fe3fe7a96b150760376f0f918c7ef3a5d218 | |
| parent | 50222772957d1d7543809fdf9c3bf0e195b9c6f7 (diff) | |
| download | man-pages-82d1ecdfe7a9048bd013c18ebd244f8e6d0b8df9.tar.gz | |
keyctl.2, KEYCTL_ASSUME_AUTHORITY.2const: Split KEYCTL_ASSUME_AUTHORITY from keyctl(2)
Signed-off-by: Alejandro Colomar <alx@kernel.org>
| -rw-r--r-- | man/man2/keyctl.2 | 82 | ||||
| -rw-r--r-- | man/man2const/KEYCTL_ASSUME_AUTHORITY.2const | 123 |
2 files changed, 125 insertions, 80 deletions
diff --git a/man/man2/keyctl.2 b/man/man2/keyctl.2 index 7e211fa90c..519f638430 100644 --- a/man/man2/keyctl.2 +++ b/man/man2/keyctl.2 @@ -77,80 +77,8 @@ are: .BR KEYCTL_SET_REQKEY_KEYRING (2const) .TQ .BR KEYCTL_SET_TIMEOUT (2const) -.TP -.BR KEYCTL_ASSUME_AUTHORITY " (since Linux 2.6.16)" -Assume (or divest) the authority for the calling thread -to instantiate a key. -.IP -The -.I arg2 -argument (cast to -.IR key_serial_t ) -specifies either a nonzero key ID to assume authority, -or the value 0 to divest authority. -.IP -If -.I arg2 -is nonzero, then it specifies the ID of an uninstantiated key for which -authority is to be assumed. -That key can then be instantiated using one of -.BR KEYCTL_INSTANTIATE (2const), -.BR KEYCTL_INSTANTIATE_IOV (2const), -.BR KEYCTL_REJECT (2const), -or -.BR KEYCTL_NEGATE (2const). -Once the key has been instantiated, -the thread is automatically divested of authority to instantiate the key. -.IP -Authority over a key can be assumed only if the calling thread has present -in its keyrings the authorization key that is -associated with the specified key. -(In other words, the -.B KEYCTL_ASSUME_AUTHORITY -operation is available only from a -.BR request\-key (8)-style -program; see -.BR request_key (2) -for an explanation of how this operation is used.) -The caller must have -.I search -permission on the authorization key. -.IP -If the specified key has a matching authorization key, -then the ID of that key is returned. -The authorization key can be read -.RB ( KEYCTL_READ (2const)) -to obtain the callout information passed to -.BR request_key (2). -.IP -If the ID given in -.I arg2 -is 0, then the currently assumed authority is cleared (divested), -and the value 0 is returned. -.IP -The -.B KEYCTL_ASSUME_AUTHORITY -mechanism allows a program such as -.BR request\-key (8) -to assume the necessary authority to instantiate a new uninstantiated key -that was created as a consequence of a call to -.BR request_key (2). -For further information, see -.BR request_key (2) -and the kernel source file -.IR Documentation/security/keys\-request\-key.txt . -.IP -The arguments -.IR arg3 , -.IR arg4 , -and -.I arg5 -are ignored. -.IP -This operation is exposed by -.I libkeyutils -via the function -.BR keyctl_assume_authority (3). +.TQ +.BR KEYCTL_ASSUME_AUTHORITY (2const) .TP .BR KEYCTL_GET_SECURITY " (since Linux 2.6.26)" .\" commit 70a5bb72b55e82fbfbf1e22cae6975fac58a1e2d @@ -558,11 +486,6 @@ is ignored. .SH RETURN VALUE For a successful call, the return value depends on the operation. .TP -.B KEYCTL_ASSUME_AUTHORITY -Either 0, if the ID given was 0, -or the ID of the authorization key matching the specified key, -if a nonzero key ID was provided. -.TP .B KEYCTL_GET_SECURITY The size of the LSM security label string (including the terminating null byte), @@ -1104,7 +1027,6 @@ main(int argc, char *argv[]) .\" .BR find_key_by_type_and_name (3) .\" There is a man page, but this function seems not to exist .BR keyctl (3), -.BR keyctl_assume_authority (3), .BR keyctl_dh_compute (3), .BR keyctl_dh_compute_alloc (3), .BR keyctl_get_persistent (3), diff --git a/man/man2const/KEYCTL_ASSUME_AUTHORITY.2const b/man/man2const/KEYCTL_ASSUME_AUTHORITY.2const new file mode 100644 index 0000000000..9f9693a90e --- /dev/null +++ b/man/man2const/KEYCTL_ASSUME_AUTHORITY.2const @@ -0,0 +1,123 @@ +.\" Copyright 2016, Michael Kerrisk <mtk.manpages@gmail.com> +.\" Copyright 2016, Eugene Syromyatnikov <evgsyr@gmail.com> +.\" A very few fragments remain from an earlier version of this page +.\" written by David Howells (dhowells@redhat.com) +.\" Copyright 2024, Alejandro Colomar <alx@kernel.org> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH KEYCTL_ASSUME_AUTHORITY 2const (date) "Linux man-pages (unreleased)" +.SH NAME +KEYCTL_ASSUME_AUTHORITY +\- +assume the authority to instantiate a key +.SH LIBRARY +Standard C library +.RI ( libc ,\~ \-lc ) +.SH SYNOPSIS +.nf +.BR "#include <linux/keyctl.h>" " /* Definition of " KEY* " constants */" +.BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */" +.B #include <unistd.h> +.P +.BI "long syscall(SYS_keyctl, KEYCTL_ASSUME_AUTHORITY, unsigned long " arg2 , +.BI " unsigned long " arg3 ", unsigned long " arg4 , +.BI " unsigned long " arg5 ); +.fi +.SH DESCRIPTION +.TP +.BR KEYCTL_ASSUME_AUTHORITY " (since Linux 2.6.16)" +Assume (or divest) the authority for the calling thread +to instantiate a key. +.IP +The +.I arg2 +argument (cast to +.IR key_serial_t ) +specifies either a nonzero key ID to assume authority, +or the value 0 to divest authority. +.IP +If +.I arg2 +is nonzero, then it specifies the ID of an uninstantiated key for which +authority is to be assumed. +That key can then be instantiated using one of +.BR KEYCTL_INSTANTIATE (2const), +.BR KEYCTL_INSTANTIATE_IOV (2const), +.BR KEYCTL_REJECT (2const), +or +.BR KEYCTL_NEGATE (2const). +Once the key has been instantiated, +the thread is automatically divested of authority to instantiate the key. +.IP +Authority over a key can be assumed only if the calling thread has present +in its keyrings the authorization key that is +associated with the specified key. +(In other words, the +.B KEYCTL_ASSUME_AUTHORITY +operation is available only from a +.BR request\-key (8)-style +program; see +.BR request_key (2) +for an explanation of how this operation is used.) +The caller must have +.I search +permission on the authorization key. +.IP +If the specified key has a matching authorization key, +then the ID of that key is returned. +The authorization key can be read +.RB ( KEYCTL_READ (2const)) +to obtain the callout information passed to +.BR request_key (2). +.IP +If the ID given in +.I arg2 +is 0, then the currently assumed authority is cleared (divested), +and the value 0 is returned. +.IP +The +.B KEYCTL_ASSUME_AUTHORITY +mechanism allows a program such as +.BR request\-key (8) +to assume the necessary authority to instantiate a new uninstantiated key +that was created as a consequence of a call to +.BR request_key (2). +For further information, see +.BR request_key (2) +and the kernel source file +.IR Documentation/security/keys\-request\-key.txt . +.IP +The arguments +.IR arg3 , +.IR arg4 , +and +.I arg5 +are ignored. +.IP +This operation is exposed by +.I libkeyutils +via the function +.BR keyctl_assume_authority (3). +.SH RETURN VALUE +.TP +.B KEYCTL_ASSUME_AUTHORITY +Either 0, if the ID given was 0, +or the ID of the authorization key matching the specified key, +if a nonzero key ID was provided. +.P +On error, \-1 is returned, and +.I errno +is set to indicate the error. +.SH VERSIONS +A wrapper is provided in the +.I libkeyutils +library: +.BR keyctl_assume_authority (3). +.SH STANDARDS +Linux. +.SH HISTORY +Linux 2.6.16. +.SH SEE ALSO +.BR keyctl (2), +.BR keyctl_assume_authority (3) |