Merging upstream version 6.8.

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 562 insertions, 0 deletions

diff --git a/man/man2/request_key.2 b/man/man2/request_key.2
new file mode 100644
index 0000000..9ad563b
--- /dev/null
+++ b/man/man2/request_key.2
@@ -0,0 +1,562 @@
+.\" Copyright (C) 2006 Red Hat, Inc. All Rights Reserved.
+.\"     Written by David Howells (dhowells@redhat.com)
+.\" and Copyright (C) 2016 Michael Kerrisk <mtk.man-pages@gmail.com>
+.\"
+.\" SPDX-License-Identifier: GPL-2.0-or-later
+.\"
+.TH request_key 2 2024-05-02 "Linux man-pages (unreleased)"
+.SH NAME
+request_key \- request a key from the kernel's key management facility
+.SH LIBRARY
+Linux Key Management Utilities
+.RI ( libkeyutils ", " \-lkeyutils )
+.SH SYNOPSIS
+.nf
+.B #include <keyutils.h>
+.P
+.BI "key_serial_t request_key(const char *" type ", const char *" description ,
+.BI "                         const char *_Nullable " callout_info ,
+.BI "                         key_serial_t " dest_keyring );
+.fi
+.SH DESCRIPTION
+.BR request_key ()
+attempts to find a key of the given
+.I type
+with a description (name) that matches the specified
+.IR description .
+If such a key could not be found, then the key is optionally created.
+If the key is found or created,
+.BR request_key ()
+attaches it to the keyring whose ID is specified in
+.I dest_keyring
+and returns the key's serial number.
+.P
+.BR request_key ()
+first recursively searches for a matching key in all of the keyrings
+attached to the calling process.
+The keyrings are searched in the order: thread-specific keyring,
+process-specific keyring, and then session keyring.
+.P
+If
+.BR request_key ()
+is called from a program invoked by
+.BR request_key ()
+on behalf of some other process to generate a key, then the keyrings of that
+other process will be searched next,
+using that other process's user ID, group ID,
+supplementary group IDs, and security context to determine access.
+.\" David Howells: we can then have an arbitrarily long sequence
+.\" of "recursive" request-key upcalls. There is no limit, other
+.\" than number of PIDs, etc.
+.P
+The search of the keyring tree is breadth-first:
+the keys in each keyring searched are checked for a match before any child
+keyrings are recursed into.
+Only keys for which the caller has
+.I search
+permission be found, and only keyrings for which the caller has
+.I search
+permission may be searched.
+.P
+If the key is not found and
+.I callout
+is NULL, then the call fails with the error
+.BR ENOKEY .
+.P
+If the key is not found and
+.I callout
+is not NULL, then the kernel attempts to invoke a user-space
+program to instantiate the key.
+The details are given below.
+.P
+The
+.I dest_keyring
+serial number may be that of a valid keyring for which the caller has
+.I write
+permission, or it may be one of the following special keyring IDs:
+.TP
+.B KEY_SPEC_THREAD_KEYRING
+This specifies the caller's thread-specific keyring (see
+.BR thread\-keyring (7)).
+.TP
+.B KEY_SPEC_PROCESS_KEYRING
+This specifies the caller's process-specific keyring (see
+.BR process\-keyring (7)).
+.TP
+.B KEY_SPEC_SESSION_KEYRING
+This specifies the caller's session-specific keyring (see
+.BR session\-keyring (7)).
+.TP
+.B KEY_SPEC_USER_KEYRING
+This specifies the caller's UID-specific keyring (see
+.BR user\-keyring (7)).
+.TP
+.B KEY_SPEC_USER_SESSION_KEYRING
+This specifies the caller's UID-session keyring (see
+.BR user\-session\-keyring (7)).
+.P
+When the
+.I dest_keyring
+is specified as 0
+and no key construction has been performed,
+then no additional linking is done.
+.P
+Otherwise, if
+.I dest_keyring
+is 0 and a new key is constructed, the new key will be linked
+to the "default" keyring.
+More precisely, when the kernel tries to determine to which keyring the
+newly constructed key should be linked,
+it tries the following keyrings,
+beginning with the keyring set via the
+.BR keyctl (2)
+.B KEYCTL_SET_REQKEY_KEYRING
+operation and continuing in the order shown below
+until it finds the first keyring that exists:
+.IP \[bu] 3
+.\" 8bbf4976b59fc9fc2861e79cab7beb3f6d647640
+The requestor keyring
+.RB ( KEY_REQKEY_DEFL_REQUESTOR_KEYRING ,
+since Linux 2.6.29).
+.\" FIXME
+.\" Actually, is the preceding point correct?
+.\" If I understand correctly, we'll only get here if
+.\" 'dest_keyring' is zero, in which case KEY_REQKEY_DEFL_REQUESTOR_KEYRING
+.\" won't refer to a keyring. Have I misunderstood?
+.IP \[bu]
+The thread-specific keyring
+.RB ( KEY_REQKEY_DEFL_THREAD_KEYRING ;
+see
+.BR thread\-keyring (7)).
+.IP \[bu]
+The process-specific keyring
+.RB ( KEY_REQKEY_DEFL_PROCESS_KEYRING ;
+see
+.BR process\-keyring (7)).
+.IP \[bu]
+The session-specific keyring
+.RB ( KEY_REQKEY_DEFL_SESSION_KEYRING ;
+see
+.BR session\-keyring (7)).
+.IP \[bu]
+The session keyring for the process's user ID
+.RB ( KEY_REQKEY_DEFL_USER_SESSION_KEYRING ;
+see
+.BR user\-session\-keyring (7)).
+This keyring is expected to always exist.
+.IP \[bu]
+The UID-specific keyring
+.RB ( KEY_REQKEY_DEFL_USER_KEYRING ;
+see
+.BR user\-keyring (7)).
+This keyring is also expected to always exist.
+.\" mtk: Are there circumstances where the user sessions and UID-specific
+.\" keyrings do not exist?
+.\"
+.\" David Howells:
+.\"     The uid keyrings don't exist until someone tries to access them -
+.\"     at which point they're both created.  When you log in, pam_keyinit
+.\"     creates a link to your user keyring in the session keyring it just
+.\"     created, thereby creating the user and user-session keyrings.
+.\"
+.\" and David elaborated that "access" means:
+.\"
+.\"     It means lookup_user_key() was passed KEY_LOOKUP_CREATE.  So:
+.\"
+.\"         add_key() - destination keyring
+.\"         request_key() - destination keyring
+.\"         KEYCTL_GET_KEYRING_ID - if create arg is true
+.\"         KEYCTL_CLEAR
+.\"         KEYCTL_LINK - both args
+.\"         KEYCTL_SEARCH - destination keyring
+.\"         KEYCTL_CHOWN
+.\"         KEYCTL_SETPERM
+.\"         KEYCTL_SET_TIMEOUT
+.\"         KEYCTL_INSTANTIATE - destination keyring
+.\"         KEYCTL_INSTANTIATE_IOV - destination keyring
+.\"         KEYCTL_NEGATE - destination keyring
+.\"         KEYCTL_REJECT - destination keyring
+.\"         KEYCTL_GET_PERSISTENT - destination keyring
+.\"
+.\"     will all create a keyring under some circumstances.  Whereas the rest,
+.\"     such as KEYCTL_GET_SECURITY, KEYCTL_READ and KEYCTL_REVOKE, won't.
+.P
+If the
+.BR keyctl (2)
+.B KEYCTL_SET_REQKEY_KEYRING
+operation specifies
+.B KEY_REQKEY_DEFL_DEFAULT
+(or no
+.B KEYCTL_SET_REQKEY_KEYRING
+operation is performed),
+then the kernel looks for a keyring
+starting from the beginning of the list.
+.\"
+.SS Requesting user-space instantiation of a key
+If the kernel cannot find a key matching
+.I type
+and
+.IR description ,
+and
+.I callout
+is not NULL, then the kernel attempts to invoke a user-space
+program to instantiate a key with the given
+.I type
+and
+.IR description .
+In this case, the following steps are performed:
+.IP (1) 5
+The kernel creates an uninstantiated key, U, with the requested
+.I type
+and
+.IR description .
+.IP (2)
+The kernel creates an authorization key, V,
+.\" struct request_key_auth, defined in security/keys/internal.h
+that refers to the key U and records the facts that the caller of
+.BR request_key ()
+is:
+.RS
+.IP (2.1) 7
+the context in which the key U should be instantiated and secured, and
+.IP (2.2)
+the context from which associated key requests may be satisfied.
+.RE
+.IP
+The authorization key is constructed as follows:
+.RS
+.IP \[bu] 3
+The key type is
+.IR \[dq].request_key_auth\[dq] .
+.IP \[bu]
+The key's UID and GID are the same as the corresponding filesystem IDs
+of the requesting process.
+.IP \[bu]
+The key grants
+.IR view ,
+.IR read ,
+and
+.I search
+permissions to the key possessor as well as
+.I view
+permission for the key user.
+.IP \[bu]
+The description (name) of the key is the hexadecimal
+string representing the ID of the key that is to be instantiated
+in the requesting program.
+.IP \[bu]
+The payload of the key is taken from the data specified in
+.IR callout_info .
+.IP \[bu]
+Internally, the kernel also records the PID of the process that called
+.BR request_key ().
+.RE
+.IP (3)
+The kernel creates a process that executes a user-space service such as
+.BR request\-key (8)
+with a new session keyring that contains a link to the authorization key, V.
+.\" The request\-key(8) program can be invoked in circumstances *other* than
+.\" when triggered by request_key(2). For example, upcalls from places such
+.\" as the DNS resolver.
+.IP
+This program is supplied with the following command-line arguments:
+.RS
+.IP [0] 5
+The string
+.IR \[dq]/sbin/request\-key\[dq] .
+.IP [1]
+The string
+.I \[dq]create\[dq]
+(indicating that a key is to be created).
+.IP [2]
+The ID of the key that is to be instantiated.
+.IP [3]
+The filesystem UID of the caller of
+.BR request_key ().
+.IP [4]
+The filesystem GID of the caller of
+.BR request_key ().
+.IP [5]
+The ID of the thread keyring of the caller of
+.BR request_key ().
+This may be zero if that keyring hasn't been created.
+.IP [6]
+The ID of the process keyring of the caller of
+.BR request_key ().
+This may be zero if that keyring hasn't been created.
+.IP [7]
+The ID of the session keyring of the caller of
+.BR request_key ().
+.RE
+.IP
+.IR Note :
+each of the command-line arguments that is a key ID is encoded in
+.I decimal
+(unlike the key IDs shown in
+.IR /proc/keys ,
+which are shown as hexadecimal values).
+.IP (4)
+The program spawned in the previous step:
+.RS
+.IP \[bu] 3
+Assumes the authority to instantiate the key U using the
+.BR keyctl (2)
+.B KEYCTL_ASSUME_AUTHORITY
+operation (typically via the
+.BR keyctl_assume_authority (3)
+function).
+.IP \[bu]
+Obtains the callout data from the payload of the authorization key V
+(using the
+.BR keyctl (2)
+.B KEYCTL_READ
+operation (or, more commonly, the
+.BR keyctl_read (3)
+function) with a key ID value of
+.BR KEY_SPEC_REQKEY_AUTH_KEY ).
+.IP \[bu]
+Instantiates the key
+(or execs another program that performs that task),
+specifying the payload and destination keyring.
+(The destination keyring that the requestor specified when calling
+.BR request_key ()
+can be accessed using the special key ID
+.BR KEY_SPEC_REQUESTOR_KEYRING .)
+.\" Should an instantiating program be using KEY_SPEC_REQUESTOR_KEYRING?
+.\" I couldn't find a use in the keyutils git repo.
+.\" According to David Howells:
+.\" * This feature is provided, but not used at the moment.
+.\" * A key added to that ring is then owned by the requester
+Instantiation is performed using the
+.BR keyctl (2)
+.B KEYCTL_INSTANTIATE
+operation (or, more commonly, the
+.BR keyctl_instantiate (3)
+function).
+At this point, the
+.BR request_key ()
+call completes, and the requesting program can continue execution.
+.RE
+.P
+If these steps are unsuccessful, then an
+.B ENOKEY
+error will be returned to the caller of
+.BR request_key ()
+and a temporary, negatively instantiated key will be installed
+in the keyring specified by
+.IR dest_keyring .
+This will expire after a few seconds, but will cause subsequent calls to
+.BR request_key ()
+to fail until it does.
+The purpose of this negatively instantiated key is to prevent
+(possibly different) processes making repeated requests
+(that require expensive
+.BR request\-key (8)
+upcalls) for a key that can't (at the moment) be positively instantiated.
+.P
+Once the key has been instantiated, the authorization key
+.RB ( KEY_SPEC_REQKEY_AUTH_KEY )
+is revoked, and the destination keyring
+.RB ( KEY_SPEC_REQUESTOR_KEYRING )
+is no longer accessible from the
+.BR request\-key (8)
+program.
+.P
+If a key is created, then\[em]regardless of whether it is a valid key or
+a negatively instantiated key\[em]it will displace any other key with
+the same type and description from the keyring specified in
+.IR dest_keyring .
+.SH RETURN VALUE
+On success,
+.BR request_key ()
+returns the serial number of the key it found or caused to be created.
+On error, \-1 is returned and
+.I errno
+is set to indicate the error.
+.SH ERRORS
+.TP
+.B EACCES
+The keyring wasn't available for modification by the user.
+.TP
+.B EDQUOT
+The key quota for this user would be exceeded by creating this key or linking
+it to the keyring.
+.TP
+.B EFAULT
+One of
+.IR type ,
+.IR description ,
+or
+.I callout_info
+points outside the process's accessible address space.
+.TP
+.B EINTR
+The request was interrupted by a signal; see
+.BR signal (7).
+.TP
+.B EINVAL
+The size of the string (including the terminating null byte) specified in
+.I type
+or
+.I description
+exceeded the limit (32 bytes and 4096 bytes respectively).
+.TP
+.B EINVAL
+The size of the string (including the terminating null byte) specified in
+.I callout_info
+exceeded the system page size.
+.TP
+.B EKEYEXPIRED
+An expired key was found, but no replacement could be obtained.
+.TP
+.B EKEYREJECTED
+The attempt to generate a new key was rejected.
+.TP
+.B EKEYREVOKED
+A revoked key was found, but no replacement could be obtained.
+.TP
+.B ENOKEY
+No matching key was found.
+.TP
+.B ENOMEM
+Insufficient memory to create a key.
+.TP
+.B EPERM
+The
+.I type
+argument started with a period (\[aq].\[aq]).
+.SH STANDARDS
+Linux.
+.SH HISTORY
+Linux 2.6.10.
+.P
+The ability to instantiate keys upon request was added
+.\" commit 3e30148c3d524a9c1c63ca28261bc24c457eb07a
+in Linux 2.6.13.
+.SH EXAMPLES
+The program below demonstrates the use of
+.BR request_key ().
+The
+.IR type ,
+.IR description ,
+and
+.I callout_info
+arguments for the system call are taken from the values
+supplied in the command-line arguments.
+The call specifies the session keyring as the target keyring.
+.P
+In order to demonstrate this program,
+we first create a suitable entry in the file
+.IR /etc/request\-key.conf .
+.P
+.in +4n
+.EX
+$ sudo sh
+# \fBecho \[aq]create user mtk:* *   /bin/keyctl instantiate %k %c %S\[aq] \e\fP
+          \fB> /etc/request\-key.conf\fP
+# \fBexit\fP
+.EE
+.in
+.P
+This entry specifies that when a new "user" key with the prefix
+"mtk:" must be instantiated, that task should be performed via the
+.BR keyctl (1)
+command's
+.B instantiate
+operation.
+The arguments supplied to the
+.B instantiate
+operation are:
+the ID of the uninstantiated key
+.RI ( %k );
+the callout data supplied to the
+.BR request_key ()
+call
+.RI ( %c );
+and the session keyring
+.RI ( %S )
+of the requestor (i.e., the caller of
+.BR request_key ()).
+See
+.BR request\-key.conf (5)
+for details of these
+.I %
+specifiers.
+.P
+Then we run the program and check the contents of
+.I /proc/keys
+to verify that the requested key has been instantiated:
+.P
+.in +4n
+.EX
+$ \fB./t_request_key user mtk:key1 "Payload data"\fP
+$ \fBgrep \[aq]2dddaf50\[aq] /proc/keys\fP
+2dddaf50 I\-\-Q\-\-\-  1 perm 3f010000  1000  1000 user  mtk:key1: 12
+.EE
+.in
+.P
+For another example of the use of this program, see
+.BR keyctl (2).
+.SS Program source
+\&
+.\" SRC BEGIN (t_request_key.c)
+.EX
+/* t_request_key.c */
+\&
+#include <keyutils.h>
+#include <stdint.h>
+#include <stdio.h>
+#include <stdlib.h>
+\&
+int
+main(int argc, char *argv[])
+{
+    key_serial_t key;
+\&
+    if (argc != 4) {
+        fprintf(stderr, "Usage: %s type description callout\-data\en",
+                argv[0]);
+        exit(EXIT_FAILURE);
+    }
+\&
+    key = request_key(argv[1], argv[2], argv[3],
+                      KEY_SPEC_SESSION_KEYRING);
+    if (key == \-1) {
+        perror("request_key");
+        exit(EXIT_FAILURE);
+    }
+\&
+    printf("Key ID is %jx\en", (uintmax_t) key);
+\&
+    exit(EXIT_SUCCESS);
+}
+.EE
+.\" SRC END
+.SH SEE ALSO
+.ad l
+.nh
+.BR keyctl (1),
+.BR add_key (2),
+.BR keyctl (2),
+.BR keyctl (3),
+.BR capabilities (7),
+.BR keyrings (7),
+.BR keyutils (7),
+.BR persistent\-keyring (7),
+.BR process\-keyring (7),
+.BR session\-keyring (7),
+.BR thread\-keyring (7),
+.BR user\-keyring (7),
+.BR user\-session\-keyring (7),
+.BR request\-key (8)
+.P
+The kernel source files
+.I Documentation/security/keys/core.rst
+and
+.I Documentation/keys/request\-key.rst
+(or, before Linux 4.13, in the files
+.\" commit b68101a1e8f0263dbc7b8375d2a7c57c6216fb76
+.I Documentation/security/keys.txt
+and
+.\" commit 3db38ed76890565772fcca3279cc8d454ea6176b
+.IR Documentation/security/keys\-request\-key.txt ).