Debian Codegraph @

upstream/debian-unstable/man2/KEYCTL_INSTANTIATE.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_INSTANTIATE 2const 2026-02-08 "Linux man-pages 6.18"
8 .SH NAME
9 KEYCTL_INSTANTIATE,
10 KEYCTL_INSTANTIATE_IOV,
11 KEYCTL_NEGATE,
12 KEYCTL_REJECT
13 \-
14 key instantiation functions
15 .SH LIBRARY
16 Standard C library
17 .RI ( libc ,\~ \-lc )
18 .SH SYNOPSIS
19 .nf
20 .BR "#include <linux/keyctl.h>" " /* Definition of " KEY* " constants */"
21 .BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */"
22 .B #include <unistd.h>
23 .P
24 .BR "long syscall(" "size_t n;"
25 .BI " SYS_keyctl, KEYCTL_INSTANTIATE, key_serial_t " key ,
26 .BI " const void " payload [ n "], size_t " n ,
27 .BI " key_serial_t " keyring );
28 .BR "long syscall(" "size_t n;"
29 .BI " SYS_keyctl, KEYCTL_INSTANTIATE_IOV, key_serial_t " key ,
30 .BI " const struct iovec " payload [ n "], unsigned int " n ,
31 .BI " key_serial_t " keyring );
32 .BI "long syscall(SYS_keyctl, KEYCTL_NEGATE, key_serial_t " key ,
33 .BI " unsigned int " timeout ", key_serial_t " keyring );
34 .BI "long syscall(SYS_keyctl, KEYCTL_REJECT, key_serial_t " key ,
35 .BI " unsigned int " timeout ", int " error \
36 ", key_serial_t " keyring );
37 .fi
38 .SH DESCRIPTION
39 .TP
40 .B KEYCTL_INSTANTIATE
41 (Positively) instantiate an uninstantiated key with a specified payload.
42 .IP
43 The ID of the key to be instantiated is provided in
44 .IR key .
45 .IP
46 The key payload is specified in the buffer pointed to by
47 .IR payload ;
48 the size of that buffer is specified in
49 .IR n .
50 .IP
51 The payload may be a null pointer and the buffer size may be 0
52 if this is supported by the key type (e.g., it is a keyring).
53 .IP
54 The operation may be fail if the payload data is in the wrong format
55 or is otherwise invalid.
56 .IP
57 If
58 .I keyring
59 is nonzero, then, subject to the same constraints and rules as
60 .BR KEYCTL_LINK (2const),
61 the instantiated key is linked into the keyring whose ID specified in
62 .IR keyring .
63 .IP
64 The caller must have the appropriate authorization key,
65 and once the uninstantiated key has been instantiated,
66 the authorization key is revoked.
67 In other words, this operation is available only from a
68 .BR request\-key (8)-style
69 program.
70 See
71 .BR request_key (2)
72 for an explanation of uninstantiated keys and key instantiation.
73 .TP
74 .B KEYCTL_INSTANTIATE_IOV
75 .\" commit ee009e4a0d4555ed522a631bae9896399674f063
76 Instantiate an uninstantiated key with a payload specified
77 via a vector of buffers.
78 .IP
79 This operation is the same as
80 .BR KEYCTL_INSTANTIATE ,
81 but the payload data is specified as an array of
82 .I iovec
83 structures (see
84 .BR iovec (3type)).
85 .IP
86 The pointer to the payload vector is specified in
87 .IR payload .
88 The number of items in the vector is specified in
89 .IR n .
90 .IP
91 The
92 .I key
93 and
94 .I keyring
95 are interpreted as for
96 .BR KEYCTL_INSTANTIATE .
97 .TP
98 .B KEYCTL_NEGATE
99 Negatively instantiate an uninstantiated key.
100 .IP
101 This operation is equivalent to the call:
102 .IP
103 .in +4n
104 .EX
105 keyctl(KEYCTL_REJECT, key, timeout, ENOKEY, keyring);
106 .EE
107 .in
108 .TP
109 .B KEYCTL_REJECT
110 .\" commit fdd1b94581782a2ddf9124414e5b7a5f48ce2f9c
111 Mark a key as negatively instantiated and set an expiration timer
112 on the key.
113 This operation provides a superset of the functionality of the earlier
114 .B KEYCTL_NEGATE
115 operation.
116 .IP
117 The ID of the key that is to be negatively instantiated is specified in
118 .IR key .
119 The
120 .I timeout
121 argument specifies the lifetime of the key, in seconds.
122 The
123 .I error
124 argument
125 specifies the error to be returned when a search hits this key;
126 typically, this is one of
127 .BR EKEYREJECTED ,
128 .BR EKEYREVOKED ,
129 or
130 .BR EKEYEXPIRED .
131 .IP
132 If
133 .I keyring
134 is nonzero, then, subject to the same constraints and rules as
135 .BR KEYCTL_LINK (2const),
136 the negatively instantiated key is linked into the keyring
137 whose ID is specified in
138 .IR keyring .
139 .IP
140 The caller must have the appropriate authorization key.
141 In other words, this operation is available only from a
142 .BR request\-key (8)-style
143 program.
144 See
145 .BR request_key (2).
146 .IP
147 The caller must have the appropriate authorization key,
148 and once the uninstantiated key has been instantiated,
149 the authorization key is revoked.
150 In other words, this operation is available only from a
151 .BR request\-key (8)-style
152 program.
153 See
154 .BR request_key (2)
155 for an explanation of uninstantiated keys and key instantiation.
156 .SH RETURN VALUE
157 On success,
158 0 is returned.
159 .P
160 On error, \-1 is returned, and
161 .I errno
162 is set to indicate the error.
163 .SH VERSIONS
164 Wrappers are provided in the
165 .I libkeyutils
166 library:
167 .BR keyctl_instantiate (3),
168 .BR keyctl_instantiate_iov (3),
169 .BR keyctl_negate (3),
170 and
171 .BR keyctl_reject (3).
172 .SH STANDARDS
173 Linux.
174 .SH HISTORY
175 .TP
176 .B KEYCTL_INSTANTIATE
177 .TQ
178 .B KEYCTL_NEGATE
179 Linux 2.6.10.
180 .TP
181 .B KEYCTL_INSTANTIATE_IOV
182 .TQ
183 .B KEYCTL_REJECT
184 Linux 2.6.39.
185 .SH SEE ALSO
186 .BR keyctl (2),
187 .BR keyctl_instantiate (3),
188 .BR keyctl_instantiate_iov (3),
189 .BR keyctl_negate (3),
190 .BR keyctl_reject (3)