Debian Codegraph @

upstream/fedora-44/man2const/KEYCTL_SETPERM.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_SETPERM 2const 2024-08-21 "Linux man-pages 6.13"
10 .SH NAME
11 KEYCTL_SETPERM
12 \-
13 change the permissions mask on 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_SETPERM, key_serial_t " key ,
24 .BI " key_perm_t " perms );
25 .fi
26 .SH DESCRIPTION
27 Change the permissions of the key with the ID provided in the
28 .I key
29 argument
30 to the permissions provided in the
31 .I perms
32 argument.
33 .P
34 If the caller doesn't have the
35 .B CAP_SYS_ADMIN
36 capability, it can change permissions only for the keys it owns.
37 (More precisely: the caller's filesystem UID must match the UID of the key.)
38 .P
39 The key must grant
40 .I setattr
41 permission to the caller
42 .I regardless
43 of the caller's capabilities.
44 .\" FIXME Above, is it really intended that a privileged process can't
45 .\" override the lack of the 'setattr' permission?
46 .P
47 The permissions in
48 .I perms
49 specify masks of available operations
50 for each of the following user categories:
51 .TP
52 .IR possessor " (since Linux 2.6.14)"
53 .\" commit 664cceb0093b755739e56572b836a99104ee8a75
54 This is the permission granted to a process that possesses the key
55 (has it attached searchably to one of the process's keyrings);
56 see
57 .BR keyrings (7).
58 .TP
59 .I user
60 This is the permission granted to a process
61 whose filesystem UID matches the UID of the key.
62 .TP
63 .I group
64 This is the permission granted to a process
65 whose filesystem GID or any of its supplementary GIDs
66 matches the GID of the key.
67 .TP
68 .I other
69 This is the permission granted to other processes
70 that do not match the
71 .I user
72 and
73 .I group
74 categories.
75 .P
76 The
77 .IR user ,
78 .IR group ,
79 and
80 .I other
81 categories are exclusive:
82 if a process matches the
83 .I user
84 category, it will not receive permissions granted in the
85 .I group
86 category; if a process matches the
87 .I user
88 or
89 .I group
90 category, then it will not receive permissions granted in the
91 .I other
92 category.
93 .P
94 The
95 .I possessor
96 category grants permissions that are cumulative with the grants from the
97 .IR user ,
98 .IR group ,
99 or
100 .I other
101 category.
102 .P
103 Each permission mask is eight bits in size,
104 with only six bits currently used.
105 The available permissions are:
106 .TP
107 .I view
108 This permission allows reading attributes of a key.
109 .IP
110 This permission is required for the
111 .BR KEYCTL_DESCRIBE (2const)
112 operation.
113 .P
114 The permission bits for each category are:
115 .RS
116 .TP
117 .B KEY_POS_VIEW
118 .TQ
119 .B KEY_USR_VIEW
120 .TQ
121 .B KEY_GRP_VIEW
122 .TQ
123 .B KEY_OTH_VIEW
124 .RE
125 .TP
126 .I read
127 This permission allows reading a key's payload.
128 .IP
129 This permission is required for the
130 .BR KEYCTL_READ (2const)
131 operation.
132 .IP
133 The permission bits for each category are
134 .RS
135 .TP
136 .B KEY_POS_READ
137 .TQ
138 .B KEY_USR_READ
139 .TQ
140 .B KEY_GRP_READ
141 .TQ
142 .B KEY_OTH_READ
143 .RE
144 .TP
145 .I write
146 This permission allows update or instantiation of a key's payload.
147 For a keyring, it allows keys to be linked and unlinked from the keyring,
148 .IP
149 This permission is required for the
150 .BR KEYCTL_UPDATE (2const),
151 .BR KEYCTL_REVOKE (2const),
152 .BR KEYCTL_CLEAR (2const),
153 .BR KEYCTL_LINK (2const),
154 and
155 .BR KEYCTL_UNLINK (2const)
156 operations.
157 .IP
158 The permission bits for each category are:
159 .RS
160 .TP
161 .B KEY_POS_WRITE
162 .TQ
163 .B KEY_USR_WRITE
164 .TQ
165 .B KEY_GRP_WRITE
166 .TQ
167 .B KEY_OTH_WRITE
168 .RE
169 .TP
170 .I search
171 This permission allows keyrings to be searched and keys to be found.
172 Searches can recurse only into nested keyrings that have
173 .I search
174 permission set.
175 .IP
176 This permission is required for the
177 .BR KEYCTL_GET_KEYRING_ID (2const),
178 .BR KEYCTL_JOIN_SESSION_KEYRING (2const),
179 .BR KEYCTL_SEARCH (2const),
180 and
181 .B KEYCTL_INVALIDATE (2const)
182 operations.
183 .IP
184 The permission bits for each category are:
185 .RS
186 .TP
187 .B KEY_POS_SEARCH
188 .TQ
189 .B KEY_USR_SEARCH
190 .TQ
191 .B KEY_GRP_SEARCH
192 .TQ
193 .B KEY_OTH_SEARCH
194 .RE
195 .TP
196 .I link
197 This permission allows a key or keyring to be linked to.
198 .IP
199 This permission is required for the
200 .BR KEYCTL_LINK (2const)
201 and
202 .BR KEYCTL_SESSION_TO_PARENT (2const)
203 operations.
204 .IP
205 The permission bits for each category are:
206 .RS
207 .TP
208 .B KEY_POS_LINK
209 .TQ
210 .B KEY_USR_LINK
211 .TQ
212 .B KEY_GRP_LINK
213 .TQ
214 .B KEY_OTH_LINK
215 .RE
216 .TP
217 .IR setattr " (since Linux 2.6.15)"
218 This permission allows a key's UID, GID, and permissions mask to be changed.
219 .IP
220 This permission is required for the
221 .BR KEYCTL_REVOKE (2const),
222 .BR KEYCTL_CHOWN (2const),
223 and
224 .B KEYCTL_SETPERM (2const)
225 operations.
226 .IP
227 The permission bits for each category are:
228 .RS
229 .TP
230 .B KEY_POS_SETATTR
231 .TQ
232 .B KEY_USR_SETATTR
233 .TQ
234 .B KEY_GRP_SETATTR
235 .TQ
236 .B KEY_OTH_SETATTR
237 .RE
238 .P
239 As a convenience, the following macros are defined as masks for
240 all of the permission bits in each of the user categories:
241 .RS
242 .TP
243 .B KEY_POS_ALL
244 .TQ
245 .B KEY_USR_ALL
246 .TQ
247 .B KEY_GRP_ALL
248 .TQ
249 .B KEY_OTH_ALL
250 .RE
251 .SH RETURN VALUE
252 On success,
253 0 is returned.
254 .P
255 On error, \-1 is returned, and
256 .I errno
257 is set to indicate the error.
258 .SH ERRORS
259 .TP
260 .B EINVAL
261 .I operation
262 was
263 .B KEYCTL_SETPERM
264 and an invalid permission bit was specified in
265 .IR perms .
266 .SH VERSIONS
267 A wrapper is provided in the
268 .I libkeyutils
269 library:
270 .BR keyctl_setperm (3).
271 .SH STANDARDS
272 Linux.
273 .SH HISTORY
274 Linux 2.6.10.
275 .SH SEE ALSO
276 .BR keyctl (2),
277 .BR keyctl_setperm (3)