1keyctl(2)                     System Calls Manual                    keyctl(2)
2
3
4

NAME

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

LIBRARY

9       Standard C library (libc, -lc)
10
11       Alternatively,  Linux  Key  Management  Utilities (libkeyutils, -lkeyu‐
12       tils); see VERSIONS.
13

SYNOPSIS

15       #include <linux/keyctl.h>     /* Definition of KEY* constants */
16       #include <sys/syscall.h>      /* Definition of SYS_* constants */
17       #include <unistd.h>
18
19       long syscall(SYS_keyctl, int operation, unsigned long arg2,
20                    unsigned long arg3, unsigned long arg4,
21                    unsigned long arg5);
22
23       Note: glibc provides no wrapper for keyctl(), necessitating the use  of
24       syscall(2).
25

DESCRIPTION

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

RETURN VALUE

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

ERRORS

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

VERSIONS

1123       A wrapper is provided in the libkeyutils  library.   (The  accompanying
1124       package  provides  the <keyutils.h> header file.)  However, rather than
1125       using this system call directly, you probably want to use  the  various
1126       library  functions  mentioned  in the descriptions of individual opera‐
1127       tions above.
1128

STANDARDS

1130       Linux.
1131

HISTORY

1133       Linux 2.6.10.
1134

EXAMPLES

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

SEE ALSO

1374       keyctl(1), add_key(2), request_key(2), keyctl(3),
1375       keyctl_assume_authority(3), keyctl_chown(3), keyctl_clear(3),
1376       keyctl_describe(3), keyctl_describe_alloc(3), keyctl_dh_compute(3),
1377       keyctl_dh_compute_alloc(3), keyctl_get_keyring_ID(3),
1378       keyctl_get_persistent(3), keyctl_get_security(3),
1379       keyctl_get_security_alloc(3), keyctl_instantiate(3),
1380       keyctl_instantiate_iov(3), keyctl_invalidate(3),
1381       keyctl_join_session_keyring(3), keyctl_link(3), keyctl_negate(3),
1382       keyctl_read(3), keyctl_read_alloc(3), keyctl_reject(3),
1383       keyctl_revoke(3), keyctl_search(3), keyctl_session_to_parent(3),
1384       keyctl_set_reqkey_keyring(3), keyctl_set_timeout(3), keyctl_setperm(3),
1385       keyctl_unlink(3), keyctl_update(3), recursive_key_scan(3),
1386       recursive_session_key_scan(3), capabilities(7), credentials(7),
1387       keyrings(7), keyutils(7), persistent-keyring(7), process-keyring(7),
1388       session-keyring(7), thread-keyring(7), user-keyring(7),
1389       user_namespaces(7), user-session-keyring(7), request-key(8)
1390
1391       The kernel source files under Documentation/security/keys/ (or, before
1392       Linux 4.13, in the file Documentation/security/keys.txt).
1393
1394
1395
1396Linux man-pages 6.04              2023-03-30                         keyctl(2)
Impressum