diff options
Diffstat (limited to '')
| -rw-r--r-- | man2/request_key.2 | 50 |
1 files changed, 25 insertions, 25 deletions
diff --git a/man2/request_key.2 b/man2/request_key.2 index 80187d1..dd2e39d 100644 --- a/man2/request_key.2 +++ b/man2/request_key.2 @@ -4,7 +4,7 @@ .\" .\" SPDX-License-Identifier: GPL-2.0-or-later .\" -.TH request_key 2 2023-05-03 "Linux man-pages 6.05.01" +.TH request_key 2 2024-02-25 "Linux man-pages 6.7" .SH NAME request_key \- request a key from the kernel's key management facility .SH LIBRARY @@ -13,7 +13,7 @@ Linux Key Management Utilities .SH SYNOPSIS .nf .B #include <keyutils.h> -.PP +.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 ); @@ -30,13 +30,13 @@ If the key is found or created, attaches it to the keyring whose ID is specified in .I dest_keyring and returns the key's serial number. -.PP +.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. -.PP +.P If .BR request_key () is called from a program invoked by @@ -48,7 +48,7 @@ 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. -.PP +.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. @@ -57,18 +57,18 @@ Only keys for which the caller has permission be found, and only keyrings for which the caller has .I search permission may be searched. -.PP +.P If the key is not found and .I callout is NULL, then the call fails with the error .BR ENOKEY . -.PP +.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. -.PP +.P The .I dest_keyring serial number may be that of a valid keyring for which the caller has @@ -94,13 +94,13 @@ This specifies the caller's UID-specific keyring (see .B KEY_SPEC_USER_SESSION_KEYRING This specifies the caller's UID-session keyring (see .BR user\-session\-keyring (7)). -.PP +.P When the .I dest_keyring is specified as 0 and no key construction has been performed, then no additional linking is done. -.PP +.P Otherwise, if .I dest_keyring is 0 and a new key is constructed, the new key will be linked @@ -180,7 +180,7 @@ This keyring is also expected to always exist. .\" .\" will all create a keyring under some circumstances. Whereas the rest, .\" such as KEYCTL_GET_SECURITY, KEYCTL_READ and KEYCTL_REVOKE, won't. -.PP +.P If the .BR keyctl (2) .B KEYCTL_SET_REQKEY_KEYRING @@ -227,7 +227,7 @@ The authorization key is constructed as follows: .RS .IP \[bu] 3 The key type is -.IR """.request_key_auth""" . +.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. @@ -263,10 +263,10 @@ This program is supplied with the following command-line arguments: .RS .IP [0] 5 The string -.IR """/sbin/request\-key""" . +.IR \[dq]/sbin/request\-key\[dq] . .IP [1] The string -.I """create""" +.I \[dq]create\[dq] (indicating that a key is to be created). .IP [2] The ID of the key that is to be instantiated. @@ -337,7 +337,7 @@ At this point, the .BR request_key () call completes, and the requesting program can continue execution. .RE -.PP +.P If these steps are unsuccessful, then an .B ENOKEY error will be returned to the caller of @@ -353,7 +353,7 @@ The purpose of this negatively instantiated key is to prevent (that require expensive .BR request\-key (8) upcalls) for a key that can't (at the moment) be positively instantiated. -.PP +.P Once the key has been instantiated, the authorization key .RB ( KEY_SPEC_REQKEY_AUTH_KEY ) is revoked, and the destination keyring @@ -361,7 +361,7 @@ is revoked, and the destination keyring is no longer accessible from the .BR request\-key (8) program. -.PP +.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 @@ -429,7 +429,7 @@ argument started with a period (\[aq].\[aq]). Linux. .SH HISTORY Linux 2.6.10. -.PP +.P The ability to instantiate keys upon request was added .\" commit 3e30148c3d524a9c1c63ca28261bc24c457eb07a in Linux 2.6.13. @@ -444,11 +444,11 @@ and 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. -.PP +.P In order to demonstrate this program, we first create a suitable entry in the file .IR /etc/request\-key.conf . -.PP +.P .in +4n .EX $ sudo sh @@ -457,7 +457,7 @@ $ sudo sh # \fBexit\fP .EE .in -.PP +.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) @@ -482,11 +482,11 @@ See for details of these .I % specifiers. -.PP +.P Then we run the program and check the contents of .I /proc/keys to verify that the requested key has been instantiated: -.PP +.P .in +4n .EX $ \fB./t_request_key user mtk:key1 "Payload data"\fP @@ -494,7 +494,7 @@ $ \fBgrep \[aq]2dddaf50\[aq] /proc/keys\fP 2dddaf50 I\-\-Q\-\-\- 1 perm 3f010000 1000 1000 user mtk:key1: 12 .EE .in -.PP +.P For another example of the use of this program, see .BR keyctl (2). .SS Program source @@ -549,7 +549,7 @@ main(int argc, char *argv[]) .BR user\-keyring (7), .BR user\-session\-keyring (7), .BR request\-key (8) -.PP +.P The kernel source files .I Documentation/security/keys/core.rst and |