diff options
| author | Alejandro Colomar <alx@kernel.org> | 2024-08-17 19:43:06 +0200 |
|---|---|---|
| committer | Alejandro Colomar <alx@kernel.org> | 2024-08-21 23:51:13 +0200 |
| commit | 0c8d443620472abfd81a72b7b8af369f12d98cb9 (patch) | |
| tree | 47718b9c906691effa71181296b27b4ed78b81b7 | |
| parent | 05df17de46c9031a2468c1ee6f8f94903f3a6fb9 (diff) | |
| download | man-pages-0c8d443620472abfd81a72b7b8af369f12d98cb9.tar.gz | |
keyctl.2, KEYCTL_SESSION_TO_PARENT.2const: Split KEYCTL_SESSION_TO_PARENT from keyctl(2)
Signed-off-by: Alejandro Colomar <alx@kernel.org>
| -rw-r--r-- | man/man2/keyctl.2 | 62 | ||||
| -rw-r--r-- | man/man2const/KEYCTL_SESSION_TO_PARENT.2const | 106 |
2 files changed, 108 insertions, 60 deletions
diff --git a/man/man2/keyctl.2 b/man/man2/keyctl.2 index 7236714be9..d5afe79293 100644 --- a/man/man2/keyctl.2 +++ b/man/man2/keyctl.2 @@ -81,50 +81,8 @@ are: .BR KEYCTL_ASSUME_AUTHORITY (2const) .TQ .BR KEYCTL_GET_SECURITY (2const) -.TP -.BR KEYCTL_SESSION_TO_PARENT " (since Linux 2.6.32)" -.\" commit ee18d64c1f632043a02e6f5ba5e045bb26a5465f -Replace the session keyring to which the -.I parent -of the calling process -subscribes with the session keyring of the calling process. -.\" What is the use case for KEYCTL_SESSION_TO_PARENT? -.\" David Howells: the Process Authentication Groups people requested this, -.\" but then didn't use it; maybe there are no users. -.IP -The keyring will be replaced in the parent process at the point -where the parent next transitions from kernel space to user space. -.IP -The keyring must exist and must grant the caller -.I link -permission. -The parent process must be single-threaded and have -the same effective ownership as this process -and must not be set-user-ID or set-group-ID. -The UID of the parent process's existing session keyring (f it has one), -as well as the UID of the caller's session keyring -much match the caller's effective UID. -.IP -The fact that it is the parent process that is affected by this operation -allows a program such as the shell to start a child process that -uses this operation to change the shell's session keyring. -(This is what the -.BR keyctl (1) -.B new_session -command does.) -.IP -The arguments -.IR arg2 , -.IR arg3 , -.IR arg4 , -and -.I arg5 -are ignored. -.IP -This operation is exposed by -.I libkeyutils -via the function -.BR keyctl_session_to_parent (3). +.TQ +.BR KEYCTL_SESSION_TO_PARENT (2const) .TP .BR KEYCTL_INVALIDATE " (since Linux 3.5)" .\" commit fd75815f727f157a05f4c96b5294a4617c0557da @@ -647,21 +605,6 @@ and the caller did not have the .B CAP_SETUID capability. .TP -.B EPERM -.I operation -was -.B KEYCTL_SESSION_TO_PARENT -and either: -all of the UIDs (GIDs) of the parent process do not match -the effective UID (GID) of the calling process; -the UID of the parent's existing session keyring or -the UID of the caller's session keyring did not match -the effective UID of the caller; -the parent process is not single-thread; -or the parent process is -.BR init (1) -or a kernel thread. -.TP .B ETIMEDOUT .I operation was @@ -973,7 +916,6 @@ main(int argc, char *argv[]) .BR keyctl_dh_compute_alloc (3), .BR keyctl_get_persistent (3), .BR keyctl_invalidate (3), -.BR keyctl_session_to_parent (3), .BR recursive_key_scan (3), .BR recursive_session_key_scan (3), .BR capabilities (7), diff --git a/man/man2const/KEYCTL_SESSION_TO_PARENT.2const b/man/man2const/KEYCTL_SESSION_TO_PARENT.2const new file mode 100644 index 0000000000..7897d78f5c --- /dev/null +++ b/man/man2const/KEYCTL_SESSION_TO_PARENT.2const @@ -0,0 +1,106 @@ +.\" 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_SESSION_TO_PARENT 2const (date) "Linux man-pages (unreleased)" +.SH NAME +KEYCTL_SESSION_TO_PARENT +\- +set the parent process's session keyring +.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_SESSION_TO_PARENT, unsigned long " arg2 , +.BI " unsigned long " arg3 ", unsigned long " arg4 , +.BI " unsigned long " arg5 ); +.fi +.SH DESCRIPTION +.TP +.BR KEYCTL_SESSION_TO_PARENT " (since Linux 2.6.32)" +.\" commit ee18d64c1f632043a02e6f5ba5e045bb26a5465f +Replace the session keyring to which the +.I parent +of the calling process +subscribes with the session keyring of the calling process. +.\" What is the use case for KEYCTL_SESSION_TO_PARENT? +.\" David Howells: the Process Authentication Groups people requested this, +.\" but then didn't use it; maybe there are no users. +.IP +The keyring will be replaced in the parent process at the point +where the parent next transitions from kernel space to user space. +.IP +The keyring must exist and must grant the caller +.I link +permission. +The parent process must be single-threaded and have +the same effective ownership as this process +and must not be set-user-ID or set-group-ID. +The UID of the parent process's existing session keyring (f it has one), +as well as the UID of the caller's session keyring +much match the caller's effective UID. +.IP +The fact that it is the parent process that is affected by this operation +allows a program such as the shell to start a child process that +uses this operation to change the shell's session keyring. +(This is what the +.BR keyctl (1) +.B new_session +command does.) +.IP +The arguments +.IR arg2 , +.IR arg3 , +.IR arg4 , +and +.I arg5 +are ignored. +.IP +This operation is exposed by +.I libkeyutils +via the function +.BR keyctl_session_to_parent (3). +.SH RETURN VALUE +On success, +0 is returned. +.P +On error, \-1 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EPERM +.I operation +was +.B KEYCTL_SESSION_TO_PARENT +and either: +all of the UIDs (GIDs) of the parent process do not match +the effective UID (GID) of the calling process; +the UID of the parent's existing session keyring or +the UID of the caller's session keyring did not match +the effective UID of the caller; +the parent process is not single-thread; +or the parent process is +.BR init (1) +or a kernel thread. +.SH VERSIONS +A wrapper is provided in the +.I libkeyutils +library: +.BR keyctl_session_to_parent (3). +.SH STANDARDS +Linux. +.SH HISTORY +Linux 2.6.32. +.SH SEE ALSO +.BR keyctl (2), +.BR keyctl_session_to_parent (3) |