Debian Codegraph @

upstream/debian-unstable/man2/KEYCTL_SETPERM.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_SETPERM 2const 2026-02-08 "Linux man-pages 6.18"
8 .SH NAME
9 KEYCTL_SETPERM
10 \-
11 change the permissions mask on 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_SETPERM, key_serial_t " key ,
22 .BI " key_perm_t " perms );
23 .fi
24 .SH DESCRIPTION
25 Change the permissions of the key with the ID provided in the
26 .I key
27 argument
28 to the permissions provided in the
29 .I perms
30 argument.
31 .P
32 If the caller doesn't have the
33 .B CAP_SYS_ADMIN
34 capability, it can change permissions only for the keys it owns.
35 (More precisely: the caller's filesystem UID must match the UID of the key.)
36 .P
37 The key must grant
38 .I setattr
39 permission to the caller
40 .I regardless
41 of the caller's capabilities.
42 .\" FIXME Above, is it really intended that a privileged process can't
43 .\" override the lack of the 'setattr' permission?
44 .P
45 The permissions in
46 .I perms
47 specify masks of available operations
48 for each of the following user categories:
49 .TP
50 .IR possessor " (since Linux 2.6.14)"
51 .\" commit 664cceb0093b755739e56572b836a99104ee8a75
52 This is the permission granted to a process that possesses the key
53 (has it attached searchably to one of the process's keyrings);
54 see
55 .BR keyrings (7).
56 .TP
57 .I user
58 This is the permission granted to a process
59 whose filesystem UID matches the UID of the key.
60 .TP
61 .I group
62 This is the permission granted to a process
63 whose filesystem GID or any of its supplementary GIDs
64 matches the GID of the key.
65 .TP
66 .I other
67 This is the permission granted to other processes
68 that do not match the
69 .I user
70 and
71 .I group
72 categories.
73 .P
74 The
75 .IR user ,
76 .IR group ,
77 and
78 .I other
79 categories are exclusive:
80 if a process matches the
81 .I user
82 category,
83 it will not receive permissions granted in the
84 .I group
85 category;
86 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)