1KEYCTL(2)                 Linux Key Management Calls                 KEYCTL(2)
2
3
4

NAME

6       keyctl - manipulate the kernel's key management facility
7

SYNOPSIS

9       #include <linux/keyctl.h>     /* Definition of KEY* constants */
10       #include <sys/syscall.h>      /* Definition of SYS_* constants */
11       #include <unistd.h>
12
13       long syscall(SYS_keyctl, int operation, unsigned long arg2,
14                    unsigned long arg3, unsigned long arg4,
15                    unsigned long arg5);
16
17       Note:  glibc provides no wrapper for keyctl(), necessitating the use of
18       syscall(2).
19

DESCRIPTION

21       keyctl() allows user-space programs to perform key manipulation.
22
23       The operation performed by keyctl() is determined by the value  of  the
24       operation  argument.   Each  of  these  operations  is  wrapped  by the
25       libkeyutils library (provided by the keyutils package) into  individual
26       functions (noted below) to permit the compiler to check types.
27
28       The permitted values for operation are:
29
30       KEYCTL_GET_KEYRING_ID (since Linux 2.6.10)
31              Map a special key ID to a real key ID for this process.
32
33              This  operation looks up the special key whose ID is provided in
34              arg2 (cast to key_serial_t).  If the special key is  found,  the
35              ID of the corresponding real key is returned as the function re‐
36              sult.  The following values may be specified in arg2:
37
38              KEY_SPEC_THREAD_KEYRING
39                     This  specifies  the  calling  thread's   thread-specific
40                     keyring.  See thread-keyring(7).
41
42              KEY_SPEC_PROCESS_KEYRING
43                     This  specifies  the  caller's  process-specific keyring.
44                     See process-keyring(7).
45
46              KEY_SPEC_SESSION_KEYRING
47                     This specifies  the  caller's  session-specific  keyring.
48                     See session-keyring(7).
49
50              KEY_SPEC_USER_KEYRING
51                     This  specifies  the  caller's UID-specific keyring.  See
52                     user-keyring(7).
53
54              KEY_SPEC_USER_SESSION_KEYRING
55                     This specifies the  caller's  UID-session  keyring.   See
56                     user-session-keyring(7).
57
58              KEY_SPEC_REQKEY_AUTH_KEY (since Linux 2.6.16)
59                     This  specifies  the  authorization  key  created  by re‐
60                     quest_key(2) and passed to the process it spawns to  gen‐
61                     erate  a  key.   This  key  is  available  only  in a re‐
62                     quest-key(8)-style program that was passed an  authoriza‐
63                     tion  key  by  the kernel and ceases to be available once
64                     the  requested  key  has  been  instantiated;   see   re‐
65                     quest_key(2).
66
67              KEY_SPEC_REQUESTOR_KEYRING (since Linux 2.6.29)
68                     This specifies the key ID for the request_key(2) destina‐
69                     tion keyring.  This keyring is available only  in  a  re‐
70                     quest-key(8)-style  program that was passed an authoriza‐
71                     tion key by the kernel and ceases to  be  available  once
72                     the   requested   key  has  been  instantiated;  see  re‐
73                     quest_key(2).
74
75              The behavior if the key specified in arg2 does not exist depends
76              on  the value of arg3 (cast to int).  If arg3 contains a nonzero
77              value, then—if it is appropriate to do so (e.g., when looking up
78              the user, user-session, or session key)—a new key is created and
79              its real key ID returned as the function result.  Otherwise, the
80              operation fails with the error ENOKEY.
81
82              If a valid key ID is specified in arg2, and the key exists, then
83              this operation simply returns the key ID.  If the key  does  not
84              exist, the call fails with error ENOKEY.
85
86              The caller must have search permission on a keyring in order for
87              it to be found.
88
89              The arguments arg4 and arg5 are ignored.
90
91              This operation  is  exposed  by  libkeyutils  via  the  function
92              keyctl_get_keyring_ID(3).
93
94       KEYCTL_JOIN_SESSION_KEYRING (since Linux 2.6.10)
95              Replace  the  session  keyring this process subscribes to with a
96              new session keyring.
97
98              If arg2 is NULL,  an  anonymous  keyring  with  the  description
99              "_ses"  is created and the process is subscribed to that keyring
100              as its session keyring, displacing the previous session keyring.
101
102              Otherwise, arg2 (cast to char *) is treated as  the  description
103              (name) of a keyring, and the behavior is as follows:
104
105              *  If  a keyring with a matching description exists, the process
106                 will attempt to subscribe to  that  keyring  as  its  session
107                 keyring if possible; if that is not possible, an error is re‐
108                 turned.  In order to subscribe to  the  keyring,  the  caller
109                 must have search permission on the keyring.
110
111              *  If a keyring with a matching description does not exist, then
112                 a new keyring with the specified description is created,  and
113                 the  process  is  subscribed  to  that keyring as its session
114                 keyring.
115
116              The arguments arg3, arg4, and arg5 are ignored.
117
118              This operation  is  exposed  by  libkeyutils  via  the  function
119              keyctl_join_session_keyring(3).
120
121       KEYCTL_UPDATE (since Linux 2.6.10)
122              Update a key's data payload.
123
124              The arg2 argument (cast to key_serial_t) specifies the ID of the
125              key to be updated.  The arg3 argument (cast to void *) points to
126              the  new payload and arg4 (cast to size_t) contains the new pay‐
127              load size in bytes.
128
129              The caller must have write permission on the key  specified  and
130              the key type must support updating.
131
132              A negatively instantiated key (see the description of KEYCTL_RE‐
133              JECT) can be positively instantiated with this operation.
134
135              The arg5 argument is ignored.
136
137              This operation  is  exposed  by  libkeyutils  via  the  function
138              keyctl_update(3).
139
140       KEYCTL_REVOKE (since Linux 2.6.10)
141              Revoke  the  key  with  the ID provided in arg2 (cast to key_se‐
142              rial_t).  The key is scheduled for garbage collection;  it  will
143              no longer be findable, and will be unavailable for further oper‐
144              ations.  Further attempts to use the key will fail with the  er‐
145              ror EKEYREVOKED.
146
147              The caller must have write or setattr permission on the key.
148
149              The arguments arg3, arg4, and arg5 are ignored.
150
151              This  operation  is  exposed  by  libkeyutils  via  the function
152              keyctl_revoke(3).
153
154       KEYCTL_CHOWN (since Linux 2.6.10)
155              Change the ownership (user and group ID) of a key.
156
157              The arg2 argument (cast to key_serial_t) contains  the  key  ID.
158              The  arg3  argument (cast to uid_t) contains the new user ID (or
159              -1 in case the user ID shouldn't be changed).  The arg4 argument
160              (cast  to  gid_t)  contains  the new group ID (or -1 in case the
161              group ID shouldn't be changed).
162
163              The key must grant the caller setattr permission.
164
165              For the UID to be changed, or for the GID to  be  changed  to  a
166              group  the  caller  is not a member of, the caller must have the
167              CAP_SYS_ADMIN capability (see capabilities(7)).
168
169              If the UID is to be changed, the new user must  have  sufficient
170              quota  to  accept  the key.  The quota deduction will be removed
171              from the old user to the new user should the UID be changed.
172
173              The arg5 argument is ignored.
174
175              This operation  is  exposed  by  libkeyutils  via  the  function
176              keyctl_chown(3).
177
178       KEYCTL_SETPERM (since Linux 2.6.10)
179              Change  the  permissions  of the key with the ID provided in the
180              arg2 argument (cast to key_serial_t) to the permissions provided
181              in the arg3 argument (cast to key_perm_t).
182
183              If  the caller doesn't have the CAP_SYS_ADMIN capability, it can
184              change permissions only for the keys it owns.  (More  precisely:
185              the caller's filesystem UID must match the UID of the key.)
186
187              The  key  must grant setattr permission to the caller regardless
188              of the caller's capabilities.
189
190              The permissions in arg3 specify masks  of  available  operations
191              for each of the following user categories:
192
193              possessor (since Linux 2.6.14)
194                     This  is  the  permission  granted to a process that pos‐
195                     sesses the key (has it attached searchably to one of  the
196                     process's keyrings); see keyrings(7).
197
198              user   This  is  the  permission  granted  to  a  process  whose
199                     filesystem UID matches the UID of the key.
200
201              group  This  is  the  permission  granted  to  a  process  whose
202                     filesystem  GID  or any of its supplementary GIDs matches
203                     the GID of the key.
204
205              other  This is the permission granted to other processes that do
206                     not match the user and group categories.
207
208              The  user,  group,  and  other  categories  are  exclusive: if a
209              process matches the user category, it will not  receive  permis‐
210              sions  granted  in  the group category; if a process matches the
211              user or group category, then it  will  not  receive  permissions
212              granted in the other category.
213
214              The  possessor  category  grants permissions that are cumulative
215              with the grants from the user, group, or other category.
216
217              Each permission mask is eight bits in size, with only  six  bits
218              currently used.  The available permissions are:
219
220              view   This permission allows reading attributes of a key.
221
222                     This permission is required for the KEYCTL_DESCRIBE oper‐
223                     ation.
224
225                     The permission bits for each category  are  KEY_POS_VIEW,
226                     KEY_USR_VIEW, KEY_GRP_VIEW, and KEY_OTH_VIEW.
227
228              read   This permission allows reading a key's payload.
229
230                     This  permission  is  required for the KEYCTL_READ opera‐
231                     tion.
232
233                     The permission bits for each category  are  KEY_POS_READ,
234                     KEY_USR_READ, KEY_GRP_READ, and KEY_OTH_READ.
235
236              write  This permission allows update or instantiation of a key's
237                     payload.  For a keyring, it allows keys to be linked  and
238                     unlinked from the keyring,
239
240                     This   permission  is  required  for  the  KEYCTL_UPDATE,
241                     KEYCTL_REVOKE, KEYCTL_CLEAR, KEYCTL_LINK, and  KEYCTL_UN‐
242                     LINK operations.
243
244                     The  permission bits for each category are KEY_POS_WRITE,
245                     KEY_USR_WRITE, KEY_GRP_WRITE, and KEY_OTH_WRITE.
246
247              search This permission allows keyrings to be searched  and  keys
248                     to  be  found.   Searches  can  recurse  only into nested
249                     keyrings that have search permission set.
250
251                     This     permission     is     required      for      the
252                     KEYCTL_GET_KEYRING_ID,       KEYCTL_JOIN_SESSION_KEYRING,
253                     KEYCTL_SEARCH, and KEYCTL_INVALIDATE operations.
254
255                     The permission bits for each category are KEY_POS_SEARCH,
256                     KEY_USR_SEARCH, KEY_GRP_SEARCH, and KEY_OTH_SEARCH.
257
258              link   This permission allows a key or keyring to be linked to.
259
260                     This  permission  is  required  for  the  KEYCTL_LINK and
261                     KEYCTL_SESSION_TO_PARENT operations.
262
263                     The permission bits for each category  are  KEY_POS_LINK,
264                     KEY_USR_LINK, KEY_GRP_LINK, and KEY_OTH_LINK.
265
266              setattr (since Linux 2.6.15).
267                     This  permission allows a key's UID, GID, and permissions
268                     mask to be changed.
269
270                     This  permission  is  required  for  the   KEYCTL_REVOKE,
271                     KEYCTL_CHOWN, and KEYCTL_SETPERM operations.
272
273                     The  permission  bits  for  each category are KEY_POS_SE‐
274                     TATTR, KEY_USR_SETATTR, KEY_GRP_SETATTR, and  KEY_OTH_SE‐
275                     TATTR.
276
277              As  a convenience, the following macros are defined as masks for
278              all of the permission bits  in  each  of  the  user  categories:
279              KEY_POS_ALL, KEY_USR_ALL, KEY_GRP_ALL, and KEY_OTH_ALL.
280
281              The arg4 and arg5 arguments are ignored.
282
283              This  operation  is  exposed  by  libkeyutils  via  the function
284              keyctl_setperm(3).
285
286       KEYCTL_DESCRIBE (since Linux 2.6.10)
287              Obtain a string describing the attributes of a specified key.
288
289              The ID of the key to be described is specified in arg2 (cast  to
290              key_serial_t).  The descriptive string is returned in the buffer
291              pointed to by arg3 (cast to char *); arg4 (cast to size_t) spec‐
292              ifies the size of that buffer in bytes.
293
294              The key must grant the caller view permission.
295
296              The  returned string is null-terminated and contains the follow‐
297              ing information about the key:
298
299                  type;uid;gid;perm;description
300
301              In the above, type and description are strings, uid and gid  are
302              decimal  strings,  and  perm  is a hexadecimal permissions mask.
303              The descriptive string is written with the following format:
304
305                  %s;%d;%d;%08x;%s
306
307              Note: the intention is that the descriptive string should be ex‐
308              tensible in future kernel versions.  In particular, the descrip‐
309              tion field will not contain semicolons; it should be  parsed  by
310              working  backwards  from  the end of the string to find the last
311              semicolon.  This allows future semicolon-delimited fields to  be
312              inserted in the descriptive string in the future.
313
314              Writing  to  the  buffer is attempted only when arg3 is non-NULL
315              and the specified buffer size is large enough to accept the  de‐
316              scriptive  string (including the terminating null byte).  In or‐
317              der to determine whether the buffer size was too small, check to
318              see if the return value of the operation is greater than arg4.
319
320              The arg5 argument is ignored.
321
322              This  operation  is  exposed  by  libkeyutils  via  the function
323              keyctl_describe(3).
324
325       KEYCTL_CLEAR
326              Clear the contents of (i.e., unlink all keys from) a keyring.
327
328              The ID of the key (which must be of keyring type) is provided in
329              arg2 (cast to key_serial_t).
330
331              The caller must have write permission on the keyring.
332
333              The arguments arg3, arg4, and arg5 are ignored.
334
335              This  operation  is  exposed  by  libkeyutils  via  the function
336              keyctl_clear(3).
337
338       KEYCTL_LINK (since Linux 2.6.10)
339              Create a link from a keyring to a key.
340
341              The key to be linked is  specified  in  arg2  (cast  to  key_se‐
342              rial_t);  the  keyring  is  specified  in  arg3 (cast to key_se‐
343              rial_t).
344
345              If a key with the same type and description is already linked in
346              the keyring, then that key is displaced from the keyring.
347
348              Before  creating  the link, the kernel checks the nesting of the
349              keyrings and returns appropriate errors if the link  would  pro‐
350              duce  a  cycle  or  if the nesting of keyrings would be too deep
351              (The limit on the nesting of keyrings is determined by the  ker‐
352              nel constant KEYRING_SEARCH_MAX_DEPTH, defined with the value 6,
353              and is necessary to prevent overflows on the kernel  stack  when
354              recursively searching keyrings).
355
356              The  caller must have link permission on the key being added and
357              write permission on the keyring.
358
359              The arguments arg4 and arg5 are ignored.
360
361              This operation  is  exposed  by  libkeyutils  via  the  function
362              keyctl_link(3).
363
364       KEYCTL_UNLINK (since Linux 2.6.10)
365              Unlink a key from a keyring.
366
367              The  ID  of the key to be unlinked is specified in arg2 (cast to
368              key_serial_t); the ID of the keyring from which it is to be  un‐
369              linked is specified in arg3 (cast to key_serial_t).
370
371              If  the  key  is not currently linked into the keyring, an error
372              results.
373
374              The caller must have write permission on the keyring from  which
375              the key is being removed.
376
377              If  the  last  link  to  a key is removed, then that key will be
378              scheduled for destruction.
379
380              The arguments arg4 and arg5 are ignored.
381
382              This operation  is  exposed  by  libkeyutils  via  the  function
383              keyctl_unlink(3).
384
385       KEYCTL_SEARCH (since Linux 2.6.10)
386              Search for a key in a keyring tree, returning its ID and option‐
387              ally linking it to a specified keyring.
388
389              The tree to be searched is specified by passing the  ID  of  the
390              head keyring in arg2 (cast to key_serial_t).  The search is per‐
391              formed breadth-first and recursively.
392
393              The arg3 and arg4 arguments specify the key to be searched  for:
394              arg3  (cast  as char *) contains the key type (a null-terminated
395              character string up to 32 bytes in size, including the terminat‐
396              ing  null byte), and arg4 (cast as char *) contains the descrip‐
397              tion of the key (a null-terminated character string up  to  4096
398              bytes in size, including the terminating null byte).
399
400              The  source  keyring must grant search permission to the caller.
401              When performing the recursive search, only keyrings  that  grant
402              the  caller  search permission will be searched.  Only keys with
403              for which the caller has search permission can be found.
404
405              If the key is found, its ID is returned as the function result.
406
407              If the key is found and arg5 (cast to key_serial_t) is  nonzero,
408              then,  subject to the same constraints and rules as KEYCTL_LINK,
409              the key is linked into the keyring  whose  ID  is  specified  in
410              arg5.  If the destination keyring specified in arg5 already con‐
411              tains a link to a key that has the same  type  and  description,
412              then  that  link will be displaced by a link to the key found by
413              this operation.
414
415              Instead of valid existing keyring IDs,  the  source  (arg2)  and
416              destination  (arg5)  keyrings  can be one of the special keyring
417              IDs listed under KEYCTL_GET_KEYRING_ID.
418
419              This operation  is  exposed  by  libkeyutils  via  the  function
420              keyctl_search(3).
421
422       KEYCTL_READ (since Linux 2.6.10)
423              Read the payload data of a key.
424
425              The  ID  of  the key whose payload is to be read is specified in
426              arg2 (cast to key_serial_t).  This can be the ID of an  existing
427              key,    or   any   of   the   special   key   IDs   listed   for
428              KEYCTL_GET_KEYRING_ID.
429
430              The payload is placed in the buffer pointed  by  arg3  (cast  to
431              char *); the size of that buffer must be specified in arg4 (cast
432              to size_t).
433
434              The returned data will be processed for  presentation  according
435              to the key type.  For example, a keyring will return an array of
436              key_serial_t entries representing the IDs of all the  keys  that
437              are linked to it.  The user key type will return its data as is.
438              If a key type does not implement this  function,  the  operation
439              fails with the error EOPNOTSUPP.
440
441              If  arg3 is not NULL, as much of the payload data as will fit is
442              copied into the buffer.  On  a  successful  return,  the  return
443              value  is  always the total size of the payload data.  To deter‐
444              mine whether the buffer was of sufficient  size,  check  to  see
445              that  the  return  value is less than or equal to the value sup‐
446              plied in arg4.
447
448              The key must either grant the caller read permission,  or  grant
449              the  caller search permission when searched for from the process
450              keyrings (i.e., the key is possessed).
451
452              The arg5 argument is ignored.
453
454              This operation  is  exposed  by  libkeyutils  via  the  function
455              keyctl_read(3).
456
457       KEYCTL_INSTANTIATE (since Linux 2.6.10)
458              (Positively)  instantiate an uninstantiated key with a specified
459              payload.
460
461              The ID of the key to be instantiated is provided in  arg2  (cast
462              to key_serial_t).
463
464              The  key  payload  is specified in the buffer pointed to by arg3
465              (cast to void *); the size of that buffer is specified  in  arg4
466              (cast to size_t).
467
468              The  payload  may be a NULL pointer and the buffer size may be 0
469              if this is supported by the key type (e.g., it is a keyring).
470
471              The operation may be fail if the payload data is  in  the  wrong
472              format or is otherwise invalid.
473
474              If  arg5 (cast to key_serial_t) is nonzero, then, subject to the
475              same constraints and rules as KEYCTL_LINK, the instantiated  key
476              is linked into the keyring whose ID specified in arg5.
477
478              The caller must have the appropriate authorization key, and once
479              the uninstantiated key has been instantiated, the  authorization
480              key  is  revoked.   In  other words, this operation is available
481              only from a request-key(8)-style  program.   See  request_key(2)
482              for an explanation of uninstantiated keys and key instantiation.
483
484              This  operation  is  exposed  by  libkeyutils  via  the function
485              keyctl_instantiate(3).
486
487       KEYCTL_NEGATE (since Linux 2.6.10)
488              Negatively instantiate an uninstantiated key.
489
490              This operation is equivalent to the call:
491
492                  keyctl(KEYCTL_REJECT, arg2, arg3, ENOKEY, arg4);
493
494              The arg5 argument is ignored.
495
496              This operation  is  exposed  by  libkeyutils  via  the  function
497              keyctl_negate(3).
498
499       KEYCTL_SET_REQKEY_KEYRING (since Linux 2.6.13)
500              Set  the default keyring to which implicitly requested keys will
501              be linked for this thread, and return the previous setting.  Im‐
502              plicit  key  requests  are  those made by internal kernel compo‐
503              nents, such as can occur when, for example, opening files on  an
504              AFS  or NFS filesystem.  Setting the default keyring also has an
505              effect when requesting a key from user space; see request_key(2)
506              for details.
507
508              The  arg2  argument (cast to int) should contain one of the fol‐
509              lowing values, to specify the new default keyring:
510
511              KEY_REQKEY_DEFL_NO_CHANGE
512                     Don't change the default keyring.  This can  be  used  to
513                     discover  the  current  default keyring (without changing
514                     it).
515
516              KEY_REQKEY_DEFL_DEFAULT
517                     This selects the default behaviour, which is to  use  the
518                     thread-specific  keyring  if  there is one, otherwise the
519                     process-specific keyring if there is one,  otherwise  the
520                     session  keyring  if there is one, otherwise the UID-spe‐
521                     cific  session  keyring,  otherwise   the   user-specific
522                     keyring.
523
524              KEY_REQKEY_DEFL_THREAD_KEYRING
525                     Use  the  thread-specific  keyring (thread-keyring(7)) as
526                     the new default keyring.
527
528              KEY_REQKEY_DEFL_PROCESS_KEYRING
529                     Use the process-specific keyring (process-keyring(7))  as
530                     the new default keyring.
531
532              KEY_REQKEY_DEFL_SESSION_KEYRING
533                     Use  the session-specific keyring (session-keyring(7)) as
534                     the new default keyring.
535
536              KEY_REQKEY_DEFL_USER_KEYRING
537                     Use the UID-specific keyring (user-keyring(7)) as the new
538                     default keyring.
539
540              KEY_REQKEY_DEFL_USER_SESSION_KEYRING
541                     Use   the   UID-specific   session   keyring   (user-ses‐
542                     sion-keyring(7)) as the new default keyring.
543
544              KEY_REQKEY_DEFL_REQUESTOR_KEYRING (since Linux 2.6.29)
545                     Use the requestor keyring.
546
547              All other values are invalid.
548
549              The arguments arg3, arg4, and arg5 are ignored.
550
551              The setting controlled by this operation  is  inherited  by  the
552              child of fork(2) and preserved across execve(2).
553
554              This  operation  is  exposed  by  libkeyutils  via  the function
555              keyctl_set_reqkey_keyring(3).
556
557       KEYCTL_SET_TIMEOUT (since Linux 2.6.16)
558              Set a timeout on a key.
559
560              The ID of the key is specified in arg2 (cast  to  key_serial_t).
561              The  timeout  value, in seconds from the current time, is speci‐
562              fied in arg3 (cast to unsigned int).  The  timeout  is  measured
563              against the realtime clock.
564
565              Specifying the timeout value as 0 clears any existing timeout on
566              the key.
567
568              The /proc/keys file displays the remaining time until  each  key
569              will  expire.  (This is the only method of discovering the time‐
570              out on a key.)
571
572              The caller must either have the setattr permission on the key or
573              hold  an  instantiation authorization token for the key (see re‐
574              quest_key(2)).
575
576              The key and any links to the key will be  automatically  garbage
577              collected after the timeout expires.  Subsequent attempts to ac‐
578              cess the key will then fail with the error EKEYEXPIRED.
579
580              This operation cannot be used to set timeouts  on  revoked,  ex‐
581              pired, or negatively instantiated keys.
582
583              The arguments arg4 and arg5 are ignored.
584
585              This  operation  is  exposed  by  libkeyutils  via  the function
586              keyctl_set_timeout(3).
587
588       KEYCTL_ASSUME_AUTHORITY (since Linux 2.6.16)
589              Assume (or divest) the authority for the calling thread  to  in‐
590              stantiate a key.
591
592              The arg2 argument (cast to key_serial_t) specifies either a non‐
593              zero key ID to assume authority, or the value 0  to  divest  au‐
594              thority.
595
596              If  arg2  is nonzero, then it specifies the ID of an uninstanti‐
597              ated key for which authority is to be  assumed.   That  key  can
598              then be instantiated using one of KEYCTL_INSTANTIATE, KEYCTL_IN‐
599              STANTIATE_IOV, KEYCTL_REJECT, or KEYCTL_NEGATE.   Once  the  key
600              has  been  instantiated, the thread is automatically divested of
601              authority to instantiate the key.
602
603              Authority over a key can be assumed only if the  calling  thread
604              has  present in its keyrings the authorization key that is asso‐
605              ciated with the specified key.  (In other words, the  KEYCTL_AS‐
606              SUME_AUTHORITY   operation   is   available   only  from  a  re‐
607              quest-key(8)-style program; see request_key(2) for  an  explana‐
608              tion  of  how  this  operation  is  used.)  The caller must have
609              search permission on the authorization key.
610
611              If the specified key has a matching authorization key, then  the
612              ID  of  that key is returned.  The authorization key can be read
613              (KEYCTL_READ) to obtain the callout information  passed  to  re‐
614              quest_key(2).
615
616              If the ID given in arg2 is 0, then the currently assumed author‐
617              ity is cleared (divested), and the value 0 is returned.
618
619              The KEYCTL_ASSUME_AUTHORITY mechanism allows a program  such  as
620              request-key(8)  to assume the necessary authority to instantiate
621              a new uninstantiated key that was created as a consequence of  a
622              call  to  request_key(2).   For  further  information,  see  re‐
623              quest_key(2) and  the  kernel  source  file  Documentation/secu‐
624              rity/keys-request-key.txt.
625
626              The arguments arg3, arg4, and arg5 are ignored.
627
628              This  operation  is  exposed  by  libkeyutils  via  the function
629              keyctl_assume_authority(3).
630
631       KEYCTL_GET_SECURITY (since Linux 2.6.26)
632              Get the LSM (Linux Security Module) security label of the speci‐
633              fied key.
634
635              The ID of the key whose security label is to be fetched is spec‐
636              ified in arg2 (cast to key_serial_t).  The security label  (ter‐
637              minated  by a null byte) will be placed in the buffer pointed to
638              by arg3 argument (cast to char *); the size of the  buffer  must
639              be provided in arg4 (cast to size_t).
640
641              If  arg3  is  specified  as NULL or the buffer size specified in
642              arg4 is too small, the full size of the  security  label  string
643              (including  the  terminating null byte) is returned as the func‐
644              tion result, and nothing is copied to the buffer.
645
646              The caller must have view permission on the specified key.
647
648              The returned security label string will be rendered  in  a  form
649              appropriate  to the LSM in force.  For example, with SELinux, it
650              may look like:
651
652                  unconfined_u:unconfined_r:unconfined_t:s0-s0:c0.c1023
653
654              If no LSM is currently in force, then an empty string is  placed
655              in the buffer.
656
657              The arg5 argument is ignored.
658
659              This  operation  is  exposed  by  libkeyutils  via the functions
660              keyctl_get_security(3) and keyctl_get_security_alloc(3).
661
662       KEYCTL_SESSION_TO_PARENT (since Linux 2.6.32)
663              Replace the session keyring to which the parent of  the  calling
664              process  subscribes  with  the  session  keyring  of the calling
665              process.
666
667              The keyring will be replaced in the parent process at the  point
668              where  the  parent  next  transitions  from kernel space to user
669              space.
670
671              The keyring must exist and must grant the  caller  link  permis‐
672              sion.   The  parent process must be single-threaded and have the
673              same effective ownership as this process and must  not  be  set-
674              user-ID or set-group-ID.  The UID of the parent process's exist‐
675              ing session keyring (f it has one), as well as the  UID  of  the
676              caller's session keyring much match the caller's effective UID.
677
678              The  fact that it is the parent process that is affected by this
679              operation allows a program such as the shell to  start  a  child
680              process  that  uses this operation to change the shell's session
681              keyring.  (This is what the keyctl(1) new_session command does.)
682
683              The arguments arg2, arg3, arg4, and arg5 are ignored.
684
685              This operation  is  exposed  by  libkeyutils  via  the  function
686              keyctl_session_to_parent(3).
687
688       KEYCTL_REJECT (since Linux 2.6.39)
689              Mark  a  key  as  negatively  instantiated and set an expiration
690              timer on the key.  This operation provides  a  superset  of  the
691              functionality of the earlier KEYCTL_NEGATE operation.
692
693              The ID of the key that is to be negatively instantiated is spec‐
694              ified in arg2 (cast to key_serial_t).  The  arg3  (cast  to  un‐
695              signed  int) argument specifies the lifetime of the key, in sec‐
696              onds.  The arg4 argument (cast to unsigned  int)  specifies  the
697              error  to  be  returned  when a search hits this key; typically,
698              this is one of EKEYREJECTED, EKEYREVOKED, or EKEYEXPIRED.
699
700              If arg5 (cast to key_serial_t) is nonzero, then, subject to  the
701              same  constraints  and  rules as KEYCTL_LINK, the negatively in‐
702              stantiated key is linked into the keyring whose ID is  specified
703              in arg5.
704
705              The  caller  must  have  the  appropriate authorization key.  In
706              other words,  this  operation  is  available  only  from  a  re‐
707              quest-key(8)-style program.  See request_key(2).
708
709              The caller must have the appropriate authorization key, and once
710              the uninstantiated key has been instantiated, the  authorization
711              key  is  revoked.   In  other words, this operation is available
712              only from a request-key(8)-style  program.   See  request_key(2)
713              for an explanation of uninstantiated keys and key instantiation.
714
715              This  operation  is  exposed  by  libkeyutils  via  the function
716              keyctl_reject(3).
717
718       KEYCTL_INSTANTIATE_IOV (since Linux 2.6.39)
719              Instantiate an uninstantiated key with a payload specified via a
720              vector of buffers.
721
722              This  operation  is the same as KEYCTL_INSTANTIATE, but the pay‐
723              load data is specified as an array of iovec structures:
724
725                  struct iovec {
726                      void  *iov_base;    /* Starting address of buffer */
727                      size_t iov_len;     /* Size of buffer (in bytes) */
728                  };
729
730              The pointer to the payload vector is specified in arg3 (cast  as
731              const  struct  iovec *).   The  number of items in the vector is
732              specified in arg4 (cast as unsigned int).
733
734              The arg2 (key ID) and arg5 (keyring ID) are interpreted  as  for
735              KEYCTL_INSTANTIATE.
736
737              This  operation  is  exposed  by  libkeyutils  via  the function
738              keyctl_instantiate_iov(3).
739
740       KEYCTL_INVALIDATE (since Linux 3.5)
741              Mark a key as invalid.
742
743              The ID of the key to be invalidated is specified in  arg2  (cast
744              to key_serial_t).
745
746              To  invalidate  a key, the caller must have search permission on
747              the key.
748
749              This operation marks the key as invalid and schedules  immediate
750              garbage  collection.   The garbage collector removes the invali‐
751              dated key from all keyrings and deletes the key when its  refer‐
752              ence  count reaches zero.  After this operation, the key will be
753              ignored by all searches, even if it is not yet deleted.
754
755              Keys that are marked invalid become invisible to normal key  op‐
756              erations   immediately,   though   they  are  still  visible  in
757              /proc/keys (marked with an 'i' flag) until they are actually re‐
758              moved.
759
760              The arguments arg3, arg4, and arg5 are ignored.
761
762              This  operation  is  exposed  by  libkeyutils  via  the function
763              keyctl_invalidate(3).
764
765       KEYCTL_GET_PERSISTENT (since Linux 3.13)
766              Get the persistent keyring (persistent-keyring(7)) for a  speci‐
767              fied user and link it to a specified keyring.
768
769              The  user ID is specified in arg2 (cast to uid_t).  If the value
770              -1 is specified, the caller's real user ID is used.  The  ID  of
771              the  destination  keyring  is specified in arg3 (cast to key_se‐
772              rial_t).
773
774              The caller must have the CAP_SETUID capability in its user name‐
775              space  in  order  to  fetch the persistent keyring for a user ID
776              that does not match either the real or effective user ID of  the
777              caller.
778
779              If  the  call is successful, a link to the persistent keyring is
780              added to the keyring whose ID was specified in arg3.
781
782              The caller must have write permission on the keyring.
783
784              The persistent keyring will be created by the kernel if it  does
785              not yet exist.
786
787              Each  time the KEYCTL_GET_PERSISTENT operation is performed, the
788              persistent keyring will have its expiration timeout reset to the
789              value in:
790
791                  /proc/sys/kernel/keys/persistent_keyring_expiry
792
793              Should  the  timeout  be reached, the persistent keyring will be
794              removed and everything it pins can then be garbage collected.
795
796              Persistent keyrings were added to Linux in kernel version 3.13.
797
798              The arguments arg4 and arg5 are ignored.
799
800              This operation  is  exposed  by  libkeyutils  via  the  function
801              keyctl_get_persistent(3).
802
803       KEYCTL_DH_COMPUTE (since Linux 4.7)
804              Compute a Diffie-Hellman shared secret or public key, optionally
805              applying key derivation function (KDF) to the result.
806
807              The arg2 argument is a pointer to a set of parameters containing
808              serial  numbers for three "user" keys used in the Diffie-Hellman
809              calculation, packaged in a structure of the following form:
810
811                  struct keyctl_dh_params {
812                      int32_t private; /* The local private key */
813                      int32_t prime; /* The prime, known to both parties */
814                      int32_t base;  /* The base integer: either a shared
815                                        generator or the remote public key */
816                  };
817
818              Each of the three keys specified in this  structure  must  grant
819              the caller read permission.  The payloads of these keys are used
820              to calculate the Diffie-Hellman result as:
821
822                  base ^ private mod prime
823
824              If the base is the shared generator, the  result  is  the  local
825              public key.  If the base is the remote public key, the result is
826              the shared secret.
827
828              The arg3 argument (cast to char *) points to a buffer where  the
829              result of the calculation is placed.  The size of that buffer is
830              specified in arg4 (cast to size_t).
831
832              The buffer must be large enough to accommodate the output  data,
833              otherwise  an  error is returned.  If arg4 is specified zero, in
834              which case the buffer is not used and the operation returns  the
835              minimum required buffer size (i.e., the length of the prime).
836
837              Diffie-Hellman  computations can be performed in user space, but
838              require a multiple-precision integer (MPI) library.  Moving  the
839              implementation  into  the  kernel gives access to the kernel MPI
840              implementation, and allows  access  to  secure  or  acceleration
841              hardware.
842
843              Adding  support  for  DH computation to the keyctl() system call
844              was considered a good fit due to the DH algorithm's use for  de‐
845              riving shared keys; it also allows the type of the key to deter‐
846              mine which DH implementation (software or hardware) is appropri‐
847              ate.
848
849              If  the  arg5 argument is NULL, then the DH result itself is re‐
850              turned.  Otherwise (since Linux 4.12), it  is  a  pointer  to  a
851              structure  which specifies parameters of the KDF operation to be
852              applied:
853
854                  struct keyctl_kdf_params {
855                      char *hashname;     /* Hash algorithm name */
856                      char *otherinfo;    /* SP800-56A OtherInfo */
857                      __u32 otherinfolen; /* Length of otherinfo data */
858                      __u32 __spare[8];   /* Reserved */
859                  };
860
861              The hashname field is a null-terminated string which specifies a
862              hash name (available in the kernel's crypto API; the list of the
863              hashes available is rather tricky to observe;  please  refer  to
864              the "Kernel Crypto API Architecture" ⟨https://www.kernel.org/doc
865              /html/latest/crypto/architecture.html⟩ documentation for the in‐
866              formation regarding how hash names are constructed and your ker‐
867              nel's source and configuration regarding what ciphers  and  tem‐
868              plates  with type CRYPTO_ALG_TYPE_SHASH are available) to be ap‐
869              plied to DH result in KDF operation.
870
871              The otherinfo  field  is  an  OtherInfo  data  as  described  in
872              SP800-56A  section 5.8.1.2 and is algorithm-specific.  This data
873              is concatenated with the result of DH operation and is  provided
874              as  an  input to the KDF operation.  Its size is provided in the
875              otherinfolen field and is limited by KEYCTL_KDF_MAX_OI_LEN  con‐
876              stant that defined in security/keys/internal.h to a value of 64.
877
878              The  __spare  field  is  currently unused.  It was ignored until
879              Linux 4.13 (but still should be  user-addressable  since  it  is
880              copied  to  the  kernel),  and  should contain zeros since Linux
881              4.13.
882
883              The KDF implementation complies with SP800-56A as well  as  with
884              SP800-108 (the counter KDF).
885
886              This  operation  is  exposed by libkeyutils (from version 1.5.10
887              onwards)   via   the    functions    keyctl_dh_compute(3)    and
888              keyctl_dh_compute_alloc(3).
889
890       KEYCTL_RESTRICT_KEYRING (since Linux 4.12)
891              Apply  a key-linking restriction to the keyring with the ID pro‐
892              vided in arg2 (cast to key_serial_t).  The caller must have  se‐
893              tattr  permission  on  the key.  If arg3 is NULL, any attempt to
894              add a key to the keyring is blocked;  otherwise  it  contains  a
895              pointer  to  a  string  with a key type name and arg4 contains a
896              pointer to string that describes the type-specific  restriction.
897              As  of  Linux  4.12, only the type "asymmetric" has restrictions
898              defined:
899
900              builtin_trusted
901                     Allows only keys that are signed by a key linked  to  the
902                     built-in keyring (".builtin_trusted_keys").
903
904              builtin_and_secondary_trusted
905                     Allows  only  keys that are signed by a key linked to the
906                     secondary keyring (".secondary_trusted_keys") or, by  ex‐
907                     tension,  a  key  in a built-in keyring, as the latter is
908                     linked to the former.
909
910              key_or_keyring:key
911              key_or_keyring:key:chain
912                     If key specifies the ID of a key  of  type  "asymmetric",
913                     then only keys that are signed by this key are allowed.
914
915                     If key specifies the ID of a keyring, then only keys that
916                     are signed by a key linked to this keyring are allowed.
917
918                     If ":chain" is specified, keys that are signed by a  keys
919                     linked  to  the destination keyring (that is, the keyring
920                     with the ID specified in the arg2 argument) are also  al‐
921                     lowed.
922
923              Note  that  a  restriction  can  be configured only once for the
924              specified keyring; once a restriction is set, it can't be  over‐
925              ridden.
926
927              The argument arg5 is ignored.
928

RETURN VALUE

930       For a successful call, the return value depends on the operation:
931
932       KEYCTL_GET_KEYRING_ID
933              The ID of the requested keyring.
934
935       KEYCTL_JOIN_SESSION_KEYRING
936              The ID of the joined session keyring.
937
938       KEYCTL_DESCRIBE
939              The  size  of  the  description  (including the terminating null
940              byte), irrespective of the provided buffer size.
941
942       KEYCTL_SEARCH
943              The ID of the key that was found.
944
945       KEYCTL_READ
946              The amount of data that is available in the key, irrespective of
947              the provided buffer size.
948
949       KEYCTL_SET_REQKEY_KEYRING
950              The  ID  of the previous default keyring to which implicitly re‐
951              quested keys were linked (one of KEY_REQKEY_DEFL_USER_*).
952
953       KEYCTL_ASSUME_AUTHORITY
954              Either 0, if the ID given was 0, or the ID of the  authorization
955              key  matching  the  specified  key, if a nonzero key ID was pro‐
956              vided.
957
958       KEYCTL_GET_SECURITY
959              The size of the LSM security label string (including the  termi‐
960              nating null byte), irrespective of the provided buffer size.
961
962       KEYCTL_GET_PERSISTENT
963              The ID of the persistent keyring.
964
965       KEYCTL_DH_COMPUTE
966              The  number of bytes copied to the buffer, or, if arg4 is 0, the
967              required buffer size.
968
969       All other operations
970              Zero.
971
972       On error, -1 is returned, and errno is set to indicate the error.
973

ERRORS

975       EACCES The requested operation wasn't permitted.
976
977       EAGAIN operation was KEYCTL_DH_COMPUTE and there was  an  error  during
978              crypto module initialization.
979
980       EDEADLK
981              operation was KEYCTL_LINK and the requested link would result in
982              a cycle.
983
984       EDEADLK
985              operation was KEYCTL_RESTRICT_KEYRING and the requested  keyring
986              restriction would result in a cycle.
987
988       EDQUOT The  key quota for the caller's user would be exceeded by creat‐
989              ing a key or linking it to the keyring.
990
991       EEXIST operation was KEYCTL_RESTRICT_KEYRING and  keyring  provided  in
992              arg2 argument already has a restriction set.
993
994       EFAULT operation  was  KEYCTL_DH_COMPUTE  and  one of the following has
995              failed:
996
997              •  copying of the struct keyctl_dh_params, provided in the  arg2
998                 argument, from user space;
999
1000              •  copying of the struct keyctl_kdf_params, provided in the non-
1001                 NULL arg5 argument, from user space (in case kernel  supports
1002                 performing KDF operation on DH operation result);
1003
1004              •  copying  of  data pointed by the hashname field of the struct
1005                 keyctl_kdf_params from user space;
1006
1007              •  copying of data pointed by the otherinfo field of the  struct
1008                 keyctl_kdf_params  from  user space if the otherinfolen field
1009                 was nonzero;
1010
1011              •  copying of the result to user space.
1012
1013       EINVAL operation was KEYCTL_SETPERM and an invalid permission  bit  was
1014              specified in arg3.
1015
1016       EINVAL operation  was  KEYCTL_SEARCH and the size of the description in
1017              arg4 (including the terminating null byte) exceeded 4096 bytes.
1018
1019       EINVAL size of the string (including the terminating null byte)  speci‐
1020              fied  in  arg3  (the key type) or arg4 (the key description) ex‐
1021              ceeded the limit (32 bytes and 4096 bytes respectively).
1022
1023       EINVAL (Linux kernels before 4.12)
1024              operation was KEYCTL_DH_COMPUTE, argument arg5 was non-NULL.
1025
1026       EINVAL operation was KEYCTL_DH_COMPUTE And the digest size of the hash‐
1027              ing algorithm supplied is zero.
1028
1029       EINVAL operation  was KEYCTL_DH_COMPUTE and the buffer size provided is
1030              not enough to hold the result.  Provide 0 as a  buffer  size  in
1031              order to obtain the minimum buffer size.
1032
1033       EINVAL operation  was  KEYCTL_DH_COMPUTE  and the hash name provided in
1034              the hashname field of the struct  keyctl_kdf_params  pointed  by
1035              arg5  argument  is too big (the limit is implementation-specific
1036              and varies between kernel versions, but it is deemed big  enough
1037              for all valid algorithm names).
1038
1039       EINVAL operation  was  KEYCTL_DH_COMPUTE  and  the __spare field of the
1040              struct keyctl_kdf_params provided in the arg5 argument  contains
1041              nonzero values.
1042
1043       EKEYEXPIRED
1044              An expired key was found or specified.
1045
1046       EKEYREJECTED
1047              A rejected key was found or specified.
1048
1049       EKEYREVOKED
1050              A revoked key was found or specified.
1051
1052       ELOOP  operation was KEYCTL_LINK and the requested link would cause the
1053              maximum nesting depth for keyrings to be exceeded.
1054
1055       EMSGSIZE
1056              operation was KEYCTL_DH_COMPUTE and the  buffer  length  exceeds
1057              KEYCTL_KDF_MAX_OUTPUT_LEN  (which is 1024 currently) or the oth‐
1058              erinfolen field of the struct keyctl_kdf_parms  passed  in  arg5
1059              exceeds KEYCTL_KDF_MAX_OI_LEN (which is 64 currently).
1060
1061       ENFILE (Linux kernels before 3.13)
1062              operation  was  KEYCTL_LINK  and  the  keyring is full.  (Before
1063              Linux 3.13, the available space for storing  keyring  links  was
1064              limited  to  a single page of memory; since Linux 3.13, there is
1065              no fixed limit.)
1066
1067       ENOENT operation was KEYCTL_UNLINK and the key  to  be  unlinked  isn't
1068              linked to the keyring.
1069
1070       ENOENT operation was KEYCTL_DH_COMPUTE and the hashing algorithm speci‐
1071              fied in the  hashname  field  of  the  struct  keyctl_kdf_params
1072              pointed by arg5 argument hasn't been found.
1073
1074       ENOENT operation  was  KEYCTL_RESTRICT_KEYRING and the type provided in
1075              arg3 argument doesn't support setting key linking restrictions.
1076
1077       ENOKEY No matching key was found or an invalid key was specified.
1078
1079       ENOKEY The value KEYCTL_GET_KEYRING_ID was specified in operation,  the
1080              key  specified in arg2 did not exist, and arg3 was zero (meaning
1081              don't create the key if it didn't exist).
1082
1083       ENOMEM One of kernel memory allocation routines failed during the  exe‐
1084              cution of the syscall.
1085
1086       ENOTDIR
1087              A  key  of  keyring type was expected but the ID of a key with a
1088              different type was provided.
1089
1090       EOPNOTSUPP
1091              operation was KEYCTL_READ and the  key  type  does  not  support
1092              reading (e.g., the type is "login").
1093
1094       EOPNOTSUPP
1095              operation  was  KEYCTL_UPDATE  and the key type does not support
1096              updating.
1097
1098       EOPNOTSUPP
1099              operation was KEYCTL_RESTRICT_KEYRING, the type provided in arg3
1100              argument was "asymmetric", and the key specified in the restric‐
1101              tion specification provided in arg4 has type other  than  "asym‐
1102              metric" or "keyring".
1103
1104       EPERM  operation  was KEYCTL_GET_PERSISTENT, arg2 specified a UID other
1105              than the calling thread's real or effective UID, and the  caller
1106              did not have the CAP_SETUID capability.
1107
1108       EPERM  operation  was  KEYCTL_SESSION_TO_PARENT  and either: all of the
1109              UIDs (GIDs) of the parent process do not match the effective UID
1110              (GID)  of  the calling process; the UID of the parent's existing
1111              session keyring or the UID of the caller's session  keyring  did
1112              not match the effective UID of the caller; the parent process is
1113              not single-thread; or the parent process is init(1) or a  kernel
1114              thread.
1115
1116       ETIMEDOUT
1117              operation was KEYCTL_DH_COMPUTE and the initialization of crypto
1118              modules has timed out.
1119

VERSIONS

1121       This system call first appeared in Linux 2.6.10.
1122

CONFORMING TO

1124       This system call is a nonstandard Linux extension.
1125

NOTES

1127       A wrapper is provided in the libkeyutils  library.   (The  accompanying
1128       package  provides  the  <keyutils.h>  header file.)  When employing the
1129       wrapper in that library, link with -lkeyutils.   However,  rather  than
1130       using  this  system call directly, you probably want to use the various
1131       library functions mentioned in the descriptions  of  individual  opera‐
1132       tions above.
1133

EXAMPLES

1135       The  program  below  provide  subset  of  the  functionality of the re‐
1136       quest-key(8) program provided by the keyutils  package.   For  informa‐
1137       tional purposes, the program records various information in a log file.
1138
1139       As  described  in request_key(2), the request-key(8) program is invoked
1140       with command-line arguments that describe a key that is to be instanti‐
1141       ated.   The example program fetches and logs these arguments.  The pro‐
1142       gram assumes authority to instantiate the requested key, and  then  in‐
1143       stantiates that key.
1144
1145       The  following  shell session demonstrates the use of this program.  In
1146       the session, we compile the program and then use it to temporarily  re‐
1147       place the standard request-key(8) program.  (Note that temporarily dis‐
1148       abling the standard request-key(8) program may not be safe on some sys‐
1149       tems.)  While our example program is installed, we use the example pro‐
1150       gram shown in request_key(2) to request a key.
1151
1152           $ cc -o key_instantiate key_instantiate.c -lkeyutils
1153           $ sudo mv /sbin/request-key /sbin/request-key.backup
1154           $ sudo cp key_instantiate /sbin/request-key
1155           $ ./t_request_key user mykey somepayloaddata
1156           Key ID is 20d035bf
1157           $ sudo mv /sbin/request-key.backup /sbin/request-key
1158
1159       Looking at the log file created by this program, we can  see  the  com‐
1160       mand-line arguments supplied to our example program:
1161
1162           $ cat /tmp/key_instantiate.log
1163           Time: Mon Nov  7 13:06:47 2016
1164
1165           Command line arguments:
1166             argv[0]:            /sbin/request-key
1167             operation:          create
1168             key_to_instantiate: 20d035bf
1169             UID:                1000
1170             GID:                1000
1171             thread_keyring:     0
1172             process_keyring:    0
1173             session_keyring:    256e6a6
1174
1175           Key description:      user;1000;1000;3f010000;mykey
1176           Auth key payload:     somepayloaddata
1177           Destination keyring:  256e6a6
1178           Auth key description: .request_key_auth;1000;1000;0b010000;20d035bf
1179
1180       The  last  few  lines of the above output show that the example program
1181       was able to fetch:
1182
1183       *  the description of the key to be instantiated,  which  included  the
1184          name of the key (mykey);
1185
1186       *  the  payload  of  the authorization key, which consisted of the data
1187          (somepayloaddata) passed to request_key(2);
1188
1189       *  the destination keyring that  was  specified  in  the  call  to  re‐
1190          quest_key(2); and
1191
1192       *  the  description of the authorization key, where we can see that the
1193          name of the authorization key matches the ID of the key that  is  to
1194          be instantiated (20d035bf).
1195
1196       The example program in request_key(2) specified the destination keyring
1197       as KEY_SPEC_SESSION_KEYRING.  By examining the contents of  /proc/keys,
1198       we  can  see  that  this  was  translated  to the ID of the destination
1199       keyring (0256e6a6) shown in the log output above; we can also  see  the
1200       newly created key with the name mykey and ID 20d035bf.
1201
1202           $ cat /proc/keys | egrep 'mykey|256e6a6'
1203           0256e6a6 I--Q---  194 perm 3f030000  1000  1000 keyring  _ses: 3
1204           20d035bf I--Q---    1 perm 3f010000  1000  1000 user     mykey: 16
1205
1206   Program source
1207
1208       /* key_instantiate.c */
1209
1210       #include <sys/types.h>
1211       #include <keyutils.h>
1212       #include <time.h>
1213       #include <fcntl.h>
1214       #include <stdint.h>
1215       #include <stdio.h>
1216       #include <stdlib.h>
1217       #include <unistd.h>
1218       #include <string.h>
1219       #include <errno.h>
1220
1221       #ifndef KEY_SPEC_REQUESTOR_KEYRING
1222       #define KEY_SPEC_REQUESTOR_KEYRING      -8
1223       #endif
1224
1225       int
1226       main(int argc, char *argv[])
1227       {
1228           FILE *fp;
1229           time_t t;
1230           char *operation;
1231           key_serial_t key_to_instantiate, dest_keyring;
1232           key_serial_t thread_keyring, process_keyring, session_keyring;
1233           uid_t uid;
1234           gid_t gid;
1235           char dbuf[256];
1236           char auth_key_payload[256];
1237           int akp_size;       /* Size of auth_key_payload */
1238           int auth_key;
1239
1240           fp = fopen("/tmp/key_instantiate.log", "w");
1241           if (fp == NULL)
1242               exit(EXIT_FAILURE);
1243
1244           setbuf(fp, NULL);
1245
1246           t = time(NULL);
1247           fprintf(fp, "Time: %s\n", ctime(&t));
1248
1249           /*
1250            * The kernel passes a fixed set of arguments to the program
1251            * that it execs; fetch them.
1252            */
1253           operation = argv[1];
1254           key_to_instantiate = atoi(argv[2]);
1255           uid = atoi(argv[3]);
1256           gid = atoi(argv[4]);
1257           thread_keyring = atoi(argv[5]);
1258           process_keyring = atoi(argv[6]);
1259           session_keyring = atoi(argv[7]);
1260
1261           fprintf(fp, "Command line arguments:\n");
1262           fprintf(fp, "  argv[0]:            %s\n", argv[0]);
1263           fprintf(fp, "  operation:          %s\n", operation);
1264           fprintf(fp, "  key_to_instantiate: %jx\n",
1265                   (uintmax_t) key_to_instantiate);
1266           fprintf(fp, "  UID:                %jd\n", (intmax_t) uid);
1267           fprintf(fp, "  GID:                %jd\n", (intmax_t) gid);
1268           fprintf(fp, "  thread_keyring:     %jx\n",
1269                   (uintmax_t) thread_keyring);
1270           fprintf(fp, "  process_keyring:    %jx\n",
1271                   (uintmax_t) process_keyring);
1272           fprintf(fp, "  session_keyring:    %jx\n",
1273                   (uintmax_t) session_keyring);
1274           fprintf(fp, "\n");
1275
1276           /*
1277            * Assume the authority to instantiate the key named in argv[2].
1278            */
1279           if (keyctl(KEYCTL_ASSUME_AUTHORITY, key_to_instantiate) == -1) {
1280               fprintf(fp, "KEYCTL_ASSUME_AUTHORITY failed: %s\n",
1281                       strerror(errno));
1282               exit(EXIT_FAILURE);
1283           }
1284
1285           /*
1286            * Fetch the description of the key that is to be instantiated.
1287            */
1288           if (keyctl(KEYCTL_DESCRIBE, key_to_instantiate,
1289                       dbuf, sizeof(dbuf)) == -1) {
1290               fprintf(fp, "KEYCTL_DESCRIBE failed: %s\n", strerror(errno));
1291               exit(EXIT_FAILURE);
1292           }
1293
1294           fprintf(fp, "Key description:      %s\n", dbuf);
1295
1296           /*
1297            * Fetch the payload of the authorization key, which is
1298            * actually the callout data given to request_key().
1299            */
1300           akp_size = keyctl(KEYCTL_READ, KEY_SPEC_REQKEY_AUTH_KEY,
1301                             auth_key_payload, sizeof(auth_key_payload));
1302           if (akp_size == -1) {
1303               fprintf(fp, "KEYCTL_READ failed: %s\n", strerror(errno));
1304               exit(EXIT_FAILURE);
1305           }
1306
1307           auth_key_payload[akp_size] = '\0';
1308           fprintf(fp, "Auth key payload:     %s\n", auth_key_payload);
1309
1310           /*
1311            * For interest, get the ID of the authorization key and
1312            * display it.
1313            */
1314           auth_key = keyctl(KEYCTL_GET_KEYRING_ID,
1315                   KEY_SPEC_REQKEY_AUTH_KEY);
1316           if (auth_key == -1) {
1317               fprintf(fp, "KEYCTL_GET_KEYRING_ID failed: %s\n",
1318                       strerror(errno));
1319               exit(EXIT_FAILURE);
1320           }
1321
1322           fprintf(fp, "Auth key ID:          %jx\n", (uintmax_t) auth_key);
1323
1324           /*
1325            * Fetch key ID for the request_key(2) destination keyring.
1326            */
1327           dest_keyring = keyctl(KEYCTL_GET_KEYRING_ID,
1328                                 KEY_SPEC_REQUESTOR_KEYRING);
1329           if (dest_keyring == -1) {
1330               fprintf(fp, "KEYCTL_GET_KEYRING_ID failed: %s\n",
1331                       strerror(errno));
1332               exit(EXIT_FAILURE);
1333           }
1334
1335           fprintf(fp, "Destination keyring:  %jx\n", (uintmax_t) dest_keyring);
1336
1337           /*
1338            * Fetch the description of the authorization key. This
1339            * allows us to see the key type, UID, GID, permissions,
1340            * and description (name) of the key. Among other things,
1341            * we will see that the name of the key is a hexadecimal
1342            * string representing the ID of the key to be instantiated.
1343            */
1344           if (keyctl(KEYCTL_DESCRIBE, KEY_SPEC_REQKEY_AUTH_KEY,
1345                       dbuf, sizeof(dbuf)) == -1) {
1346               fprintf(fp, "KEYCTL_DESCRIBE failed: %s\n", strerror(errno));
1347               exit(EXIT_FAILURE);
1348           }
1349
1350           fprintf(fp, "Auth key description: %s\n", dbuf);
1351
1352           /*
1353            * Instantiate the key using the callout data that was supplied
1354            * in the payload of the authorization key.
1355            */
1356           if (keyctl(KEYCTL_INSTANTIATE, key_to_instantiate,
1357                      auth_key_payload, akp_size + 1, dest_keyring) == -1) {
1358               fprintf(fp, "KEYCTL_INSTANTIATE failed: %s\n",
1359                       strerror(errno));
1360               exit(EXIT_FAILURE);
1361           }
1362
1363           exit(EXIT_SUCCESS);
1364       }
1365

SEE ALSO

1367       keyctl(1), add_key(2), request_key(2), keyctl(3),
1368       keyctl_assume_authority(3), keyctl_chown(3), keyctl_clear(3),
1369       keyctl_describe(3), keyctl_describe_alloc(3), keyctl_dh_compute(3),
1370       keyctl_dh_compute_alloc(3), keyctl_get_keyring_ID(3),
1371       keyctl_get_persistent(3), keyctl_get_security(3),
1372       keyctl_get_security_alloc(3), keyctl_instantiate(3),
1373       keyctl_instantiate_iov(3), keyctl_invalidate(3),
1374       keyctl_join_session_keyring(3), keyctl_link(3), keyctl_negate(3),
1375       keyctl_read(3), keyctl_read_alloc(3), keyctl_reject(3),
1376       keyctl_revoke(3), keyctl_search(3), keyctl_session_to_parent(3),
1377       keyctl_set_reqkey_keyring(3), keyctl_set_timeout(3), keyctl_setperm(3),
1378       keyctl_unlink(3), keyctl_update(3), recursive_key_scan(3),
1379       recursive_session_key_scan(3), capabilities(7), credentials(7),
1380       keyrings(7), keyutils(7), persistent-keyring(7), process-keyring(7),
1381       session-keyring(7), thread-keyring(7), user-keyring(7),
1382       user_namespaces(7), user-session-keyring(7), request-key(8)
1383
1384       The kernel source files under Documentation/security/keys/ (or, before
1385       Linux 4.13, in the file Documentation/security/keys.txt).
1386

COLOPHON

1388       This page is part of release 5.13 of the Linux man-pages project.  A
1389       description of the project, information about reporting bugs, and the
1390       latest version of this page, can be found at
1391       https://www.kernel.org/doc/man-pages/.
1392
1393
1394
1395Linux                             2021-08-27                         KEYCTL(2)
Impressum