Debian Codegraph @

upstream/debian-unstable/man2/KEYCTL_ASSUME_AUTHORITY.2const

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