Debian Codegraph @

upstream/fedora-44/man2const/KEYCTL_ASSUME_AUTHORITY.2const

raw
1 .\" Copyright 2016, Michael Kerrisk <[email protected]>
2 .\" Copyright 2016, Eugene Syromyatnikov <[email protected]>
3 .\" A very few fragments remain from an earlier version of this page
4 .\" written by David Howells ([email protected])
5 .\" Copyright 2024, Alejandro Colomar <[email protected]>
6 .\"
7 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
8 .\"
9 .TH KEYCTL_ASSUME_AUTHORITY 2const 2024-08-21 "Linux man-pages 6.13"
10 .SH NAME
11 KEYCTL_ASSUME_AUTHORITY
12 \-
13 assume the authority to instantiate a key
14 .SH LIBRARY
15 Standard C library
16 .RI ( libc ,\~ \-lc )
17 .SH SYNOPSIS
18 .nf
19 .BR "#include <linux/keyctl.h>" " /* Definition of " KEY* " constants */"
20 .BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */"
21 .B #include <unistd.h>
22 .P
23 .BI "long syscall(SYS_keyctl, KEYCTL_ASSUME_AUTHORITY, key_serial_t " key );
24 .fi
25 .SH DESCRIPTION
26 Assume (or divest) the authority for the calling thread
27 to instantiate a key.
28 .P
29 The
30 .I key
31 argument
32 specifies either a nonzero key ID to assume authority,
33 or the value 0 to divest authority.
34 .P
35 If
36 .I key
37 is nonzero, then it specifies the ID of an uninstantiated key for which
38 authority is to be assumed.
39 That key can then be instantiated using one of
40 .BR KEYCTL_INSTANTIATE (2const),
41 .BR KEYCTL_INSTANTIATE_IOV (2const),
42 .BR KEYCTL_REJECT (2const),
43 or
44 .BR KEYCTL_NEGATE (2const).
45 Once the key has been instantiated,
46 the thread is automatically divested of authority to instantiate the key.
47 .P
48 Authority over a key can be assumed only if the calling thread has present
49 in its keyrings the authorization key that is
50 associated with the specified key.
51 (In other words, the
52 .B KEYCTL_ASSUME_AUTHORITY
53 operation is available only from a
54 .BR request\-key (8)-style
55 program; see
56 .BR request_key (2)
57 for an explanation of how this operation is used.)
58 The caller must have
59 .I search
60 permission on the authorization key.
61 .P
62 If the specified key has a matching authorization key,
63 then the ID of that key is returned.
64 The authorization key can be read
65 .RB ( KEYCTL_READ (2const))
66 to obtain the callout information passed to
67 .BR request_key (2).
68 .P
69 If the ID given in
70 .I key
71 is 0, then the currently assumed authority is cleared (divested),
72 and the value 0 is returned.
73 .P
74 The
75 .B KEYCTL_ASSUME_AUTHORITY
76 mechanism allows a program such as
77 .BR request\-key (8)
78 to assume the necessary authority to instantiate a new uninstantiated key
79 that was created as a consequence of a call to
80 .BR request_key (2).
81 For further information, see
82 .BR request_key (2)
83 and the kernel source file
84 .IR Documentation/security/keys\-request\-key.txt .
85 .SH RETURN VALUE
86 On success,
87 either 0, if the ID given was 0,
88 or the ID of the authorization key matching the specified key,
89 if a nonzero key ID was provided.
90 .P
91 On error, \-1 is returned, and
92 .I errno
93 is set to indicate the error.
94 .SH VERSIONS
95 A wrapper is provided in the
96 .I libkeyutils
97 library:
98 .BR keyctl_assume_authority (3).
99 .SH STANDARDS
100 Linux.
101 .SH HISTORY
102 Linux 2.6.16.
103 .SH SEE ALSO
104 .BR keyctl (2),
105 .BR keyctl_assume_authority (3)