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 <sys/types.h>
10       #include <keyutils.h>
11
12       long keyctl(int operation, ...)
13
14       /* For direct call via syscall(2): */
15       #include <asm/unistd.h>
16       #include <linux/keyctl.h>
17       #include <unistd.h>
18
19       long syscall(__NR_keyctl, int operation, __kernel_ulong_t arg2,
20                    __kernel_ulong_t arg3, __kernel_ulong_t arg4,
21                    __kernel_ulong_t arg5);
22
23       No glibc wrapper is provided for this system call; see NOTES.
24

DESCRIPTION

26       keyctl() allows user-space programs to perform key manipulation.
27
28       The  operation  performed by keyctl() is determined by the value of the
29       operation argument.   Each  of  these  operations  is  wrapped  by  the
30       libkeyutils  library (provided by the keyutils package) into individual
31       functions (noted below) to permit the compiler to check types.
32
33       The permitted values for operation are:
34
35       KEYCTL_GET_KEYRING_ID (since Linux 2.6.10)
36              Map a special key ID to a real key ID for this process.
37
38              This operation looks up the special key whose ID is provided  in
39              arg2  (cast  to key_serial_t).  If the special key is found, the
40              ID of the corresponding real key is  returned  as  the  function
41              result.  The following values may be specified in arg2:
42
43              KEY_SPEC_THREAD_KEYRING
44                     This   specifies  the  calling  thread's  thread-specific
45                     keyring.  See thread-keyring(7).
46
47              KEY_SPEC_PROCESS_KEYRING
48                     This specifies  the  caller's  process-specific  keyring.
49                     See process-keyring(7).
50
51              KEY_SPEC_SESSION_KEYRING
52                     This  specifies  the  caller's  session-specific keyring.
53                     See session-keyring(7).
54
55              KEY_SPEC_USER_KEYRING
56                     This specifies the caller's  UID-specific  keyring.   See
57                     user-keyring(7).
58
59              KEY_SPEC_USER_SESSION_KEYRING
60                     This  specifies  the  caller's  UID-session keyring.  See
61                     user-session-keyring(7).
62
63              KEY_SPEC_REQKEY_AUTH_KEY (since Linux 2.6.16)
64                     This  specifies  the   authorization   key   created   by
65                     request_key(2)  and  passed  to  the process it spawns to
66                     generate a key.  This key is available only in a request-
67                     key(8)-style program that was passed an authorization key
68                     by the  kernel  and  ceases  to  be  available  once  the
69                     requested key has been instantiated; see request_key(2).
70
71              KEY_SPEC_REQUESTOR_KEYRING (since Linux 2.6.29)
72                     This specifies the key ID for the request_key(2) destina‐
73                     tion keyring.   This  keyring  is  available  only  in  a
74                     request-key(8)-style  program  that  was passed an autho‐
75                     rization key by the kernel and  ceases  to  be  available
76                     once   the  requested  key  has  been  instantiated;  see
77                     request_key(2).
78
79              The behavior if the key specified in arg2 does not exist depends
80              on  the value of arg3 (cast to int).  If arg3 contains a nonzero
81              value, then—if it is appropriate to do so (e.g., when looking up
82              the user, user-session, or session key)—a new key is created and
83              its real key ID returned as the function result.  Otherwise, the
84              operation fails with the error ENOKEY.
85
86              If a valid key ID is specified in arg2, and the key exists, then
87              this operation simply returns the key ID.  If the key  does  not
88              exist, the call fails with error ENOKEY.
89
90              The caller must have search permission on a keyring in order for
91              it to be found.
92
93              The arguments arg4 and arg5 are ignored.
94
95              This operation  is  exposed  by  libkeyutils  via  the  function
96              keyctl_get_keyring_ID(3).
97
98       KEYCTL_JOIN_SESSION_KEYRING (since Linux 2.6.10)
99              Replace  the  session  keyring this process subscribes to with a
100              new session keyring.
101
102              If arg2 is NULL,  an  anonymous  keyring  with  the  description
103              "_ses"  is created and the process is subscribed to that keyring
104              as its session keyring, displacing the previous session keyring.
105
106              Otherwise, arg2 (cast to char *) is treated as  the  description
107              (name) of a keyring, and the behavior is as follows:
108
109              *  If  a keyring with a matching description exists, the process
110                 will attempt to subscribe to  that  keyring  as  its  session
111                 keyring  if  possible;  if  that is not possible, an error is
112                 returned.  In order to subscribe to the keyring,  the  caller
113                 must have search permission on the keyring.
114
115              *  If a keyring with a matching description does not exist, then
116                 a new keyring with the specified description is created,  and
117                 the  process  is  subscribed  to  that keyring as its session
118                 keyring.
119
120              The arguments arg3, arg4, and arg5 are ignored.
121
122              This operation  is  exposed  by  libkeyutils  via  the  function
123              keyctl_join_session_keyring(3).
124
125       KEYCTL_UPDATE (since Linux 2.6.10)
126              Update a key's data payload.
127
128              The arg2 argument (cast to key_serial_t) specifies the ID of the
129              key to be updated.  The arg3 argument (cast to void *) points to
130              the  new payload and arg4 (cast to size_t) contains the new pay‐
131              load size in bytes.
132
133              The caller must have write permission on the key  specified  and
134              the key type must support updating.
135
136              A   negatively   instantiated   key   (see  the  description  of
137              KEYCTL_REJECT) can be positively instantiated with  this  opera‐
138              tion.
139
140              The arg5 argument is ignored.
141
142              This  operation  is  exposed  by  libkeyutils  via  the function
143              keyctl_update(3).
144
145       KEYCTL_REVOKE (since Linux 2.6.10)
146              Revoke  the  key  with  the  ID  provided  in  arg2   (cast   to
147              key_serial_t).   The key is scheduled for garbage collection; it
148              will no longer be findable, and will be unavailable for  further
149              operations.   Further attempts to use the key will fail with the
150              error EKEYREVOKED.
151
152              The caller must have write or setattr permission on the key.
153
154              The arguments arg3, arg4, and arg5 are ignored.
155
156              This operation  is  exposed  by  libkeyutils  via  the  function
157              keyctl_revoke(3).
158
159       KEYCTL_CHOWN (since Linux 2.6.10)
160              Change the ownership (user and group ID) of a key.
161
162              The  arg2  argument  (cast to key_serial_t) contains the key ID.
163              The arg3 argument (cast to uid_t) contains the new user  ID  (or
164              -1 in case the user ID shouldn't be changed).  The arg4 argument
165              (cast to gid_t) contains the new group ID (or  -1  in  case  the
166              group ID shouldn't be changed).
167
168              The key must grant the caller setattr permission.
169
170              For  the  UID  to  be changed, or for the GID to be changed to a
171              group the caller is not a member of, the caller  must  have  the
172              CAP_SYS_ADMIN capability (see capabilities(7)).
173
174              If  the  UID is to be changed, the new user must have sufficient
175              quota to accept the key.  The quota deduction  will  be  removed
176              from the old user to the new user should the UID be changed.
177
178              The arg5 argument is ignored.
179
180              This  operation  is  exposed  by  libkeyutils  via  the function
181              keyctl_chown(3).
182
183       KEYCTL_SETPERM (since Linux 2.6.10)
184              Change the permissions of the key with the ID  provided  in  the
185              arg2 argument (cast to key_serial_t) to the permissions provided
186              in the arg3 argument (cast to key_perm_t).
187
188              If the caller doesn't have the CAP_SYS_ADMIN capability, it  can
189              change  permissions only for the keys it owns.  (More precisely:
190              the caller's filesystem UID must match the UID of the key.)
191
192              The key must grant setattr permission to the  caller  regardless
193              of the caller's capabilities.
194
195              The  permissions  in  arg3 specify masks of available operations
196              for each of the following user categories:
197
198              possessor (since Linux 2.6.14)
199                     This is the permission granted to  a  process  that  pos‐
200                     sesses  the key (has it attached searchably to one of the
201                     process's keyrings); see keyrings(7).
202
203              user   This  is  the  permission  granted  to  a  process  whose
204                     filesystem UID matches the UID of the key.
205
206              group  This  is  the  permission  granted  to  a  process  whose
207                     filesystem GID or any of its supplementary  GIDs  matches
208                     the GID of the key.
209
210              other  This is the permission granted to other processes that do
211                     not match the user and group categories.
212
213              The user, group,  and  other  categories  are  exclusive:  if  a
214              process  matches  the user category, it will not receive permis‐
215              sions granted in the group category; if a  process  matches  the
216              user  or  group  category,  then it will not receive permissions
217              granted in the other category.
218
219              The possessor category grants permissions  that  are  cumulative
220              with the grants from the user, group, or other category.
221
222              Each  permission  mask is eight bits in size, with only six bits
223              currently used.  The available permissions are:
224
225              view   This permission allows reading attributes of a key.
226
227                     This permission is required for the KEYCTL_DESCRIBE oper‐
228                     ation.
229
230                     The  permission  bits for each category are KEY_POS_VIEW,
231                     KEY_USR_VIEW, KEY_GRP_VIEW, and KEY_OTH_VIEW.
232
233              read   This permission allows reading a key's payload.
234
235                     This permission is required for  the  KEYCTL_READ  opera‐
236                     tion.
237
238                     The  permission  bits for each category are KEY_POS_READ,
239                     KEY_USR_READ, KEY_GRP_READ, and KEY_OTH_READ.
240
241              write  This permission allows update or instantiation of a key's
242                     payload.   For a keyring, it allows keys to be linked and
243                     unlinked from the keyring,
244
245                     This  permission  is  required  for  the   KEYCTL_UPDATE,
246                     KEYCTL_REVOKE,     KEYCTL_CLEAR,     KEYCTL_LINK,     and
247                     KEYCTL_UNLINK operations.
248
249                     The permission bits for each category are  KEY_POS_WRITE,
250                     KEY_USR_WRITE, KEY_GRP_WRITE, and KEY_OTH_WRITE.
251
252              search This  permission  allows keyrings to be searched and keys
253                     to be found.   Searches  can  recurse  only  into  nested
254                     keyrings that have search permission set.
255
256                     This      permission      is     required     for     the
257                     KEYCTL_GET_KEYRING_ID,       KEYCTL_JOIN_SESSION_KEYRING,
258                     KEYCTL_SEARCH, and KEYCTL_INVALIDATE operations.
259
260                     The permission bits for each category are KEY_POS_SEARCH,
261                     KEY_USR_SEARCH, KEY_GRP_SEARCH, and KEY_OTH_SEARCH.
262
263              link   This permission allows a key or keyring to be linked to.
264
265                     This permission  is  required  for  the  KEYCTL_LINK  and
266                     KEYCTL_SESSION_TO_PARENT operations.
267
268                     The  permission  bits for each category are KEY_POS_LINK,
269                     KEY_USR_LINK, KEY_GRP_LINK, and KEY_OTH_LINK.
270
271              setattr (since Linux 2.6.15).
272                     This permission allows a key's UID, GID, and  permissions
273                     mask to be changed.
274
275                     This   permission  is  required  for  the  KEYCTL_REVOKE,
276                     KEYCTL_CHOWN, and KEYCTL_SETPERM operations.
277
278                     The   permission   bits    for    each    category    are
279                     KEY_POS_SETATTR,  KEY_USR_SETATTR,  KEY_GRP_SETATTR,  and
280                     KEY_OTH_SETATTR.
281
282              As a convenience, the following macros are defined as masks  for
283              all  of  the  permission  bits  in  each of the user categories:
284              KEY_POS_ALL, KEY_USR_ALL, KEY_GRP_ALL, and KEY_OTH_ALL.
285
286              The arg4 and arg5 arguments are ignored.
287
288              This operation  is  exposed  by  libkeyutils  via  the  function
289              keyctl_setperm(3).
290
291       KEYCTL_DESCRIBE (since Linux 2.6.10)
292              Obtain a string describing the attributes of a specified key.
293
294              The  ID of the key to be described is specified in arg2 (cast to
295              key_serial_t).  The descriptive string is returned in the buffer
296              pointed to by arg3 (cast to char *); arg4 (cast to size_t) spec‐
297              ifies the size of that buffer in bytes.
298
299              The key must grant the caller view permission.
300
301              The returned string is null-terminated and contains the  follow‐
302              ing information about the key:
303
304                  type;uid;gid;perm;description
305
306              In  the above, type and description are strings, uid and gid are
307              decimal strings, and perm is  a  hexadecimal  permissions  mask.
308              The descriptive string is written with the following format:
309
310                  %s;%d;%d;%08x;%s
311
312              Note:  the  intention  is  that the descriptive string should be
313              extensible  in  future  kernel  versions.   In  particular,  the
314              description  field  will  not  contain  semicolons; it should be
315              parsed by working backwards from the end of the string  to  find
316              the  last  semicolon.   This  allows  future semicolon-delimited
317              fields to be inserted in the descriptive string in the future.
318
319              Writing to the buffer is attempted only when  arg3  is  non-NULL
320              and  the  specified  buffer  size  is large enough to accept the
321              descriptive string (including the terminating  null  byte).   In
322              order  to determine whether the buffer size was too small, check
323              to see if the return value of  the  operation  is  greater  than
324              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
348              key_serial_t);  the  keyring  is  specified  in  arg3  (cast  to
349              key_serial_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
375              unlinked 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.
508              Implicit  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-session-
548                     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
580              request_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
584              access the key will then fail with the error EKEYEXPIRED.
585
586              This operation cannot  be  used  to  set  timeouts  on  revoked,
587              expired, 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
596              instantiate a key.
597
598              The  arg2  argument  (cast  to  key_serial_t) specifies either a
599              nonzero key ID to assume authority, or the  value  0  to  divest
600              authority.
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,
605              KEYCTL_INSTANTIATE_IOV, KEYCTL_REJECT, or  KEYCTL_NEGATE.   Once
606              the  key  has  been  instantiated,  the  thread is automatically
607              divested of 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
612              KEYCTL_ASSUME_AUTHORITY  operation  is  available  only  from  a
613              request-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
620              request_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
629              request_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
701              unsigned  int)  argument  specifies  the lifetime of the key, in
702              seconds.  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
708              instantiated key is linked into the keyring whose ID  is  speci‐
709              fied in arg5.
710
711              The  caller  must  have  the  appropriate authorization key.  In
712              other words, this operation is available only  from  a  request-
713              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:
730
731                  struct iovec {
732                      void  *iov_base;    /* Starting address of buffer */
733                      size_t iov_len;     /* Size of buffer (in bytes) */
734                  };
735
736              The pointer to the payload vector is specified in arg3 (cast  as
737              const  struct  iovec *).   The  number of items in the vector is
738              specified in arg4 (cast as unsigned int).
739
740              The arg2 (key ID) and arg5 (keyring ID) are interpreted  as  for
741              KEYCTL_INSTANTIATE.
742
743              This  operation  is  exposed  by  libkeyutils  via  the function
744              keyctl_instantiate_iov(3).
745
746       KEYCTL_INVALIDATE (since Linux 3.5)
747              Mark a key as invalid.
748
749              The ID of the key to be invalidated is specified in  arg2  (cast
750              to key_serial_t).
751
752              To  invalidate  a key, the caller must have search permission on
753              the key.
754
755              This operation marks the key as invalid and schedules  immediate
756              garbage  collection.   The garbage collector removes the invali‐
757              dated key from all keyrings and deletes the key when its  refer‐
758              ence  count reaches zero.  After this operation, the key will be
759              ignored by all searches, even if it is not yet deleted.
760
761              Keys that are marked invalid  become  invisible  to  normal  key
762              operations   immediately,  though  they  are  still  visible  in
763              /proc/keys (marked with an 'i' flag)  until  they  are  actually
764              removed.
765
766              The arguments arg3, arg4, and arg5 are ignored.
767
768              This  operation  is  exposed  by  libkeyutils  via  the function
769              keyctl_invalidate(3).
770
771       KEYCTL_GET_PERSISTENT (since Linux 3.13)
772              Get the persistent keyring (persistent-keyring(7)) for a  speci‐
773              fied user and link it to a specified keyring.
774
775              The  user ID is specified in arg2 (cast to uid_t).  If the value
776              -1 is specified, the caller's real user ID is used.  The  ID  of
777              the   destination   keyring   is  specified  in  arg3  (cast  to
778              key_serial_t).
779
780              The caller must have  the  CAP_SETUID  capability  in  its  user
781              namespace in order to fetch the persistent keyring for a user ID
782              that does not match either the real or effective user ID of  the
783              caller.
784
785              If  the  call is successful, a link to the persistent keyring is
786              added to the keyring whose ID was specified in arg3.
787
788              The caller must have write permission on the keyring.
789
790              The persistent keyring will be created by the kernel if it  does
791              not yet exist.
792
793              Each  time the KEYCTL_GET_PERSISTENT operation is performed, the
794              persistent keyring will have its expiration timeout reset to the
795              value in:
796
797                  /proc/sys/kernel/keys/persistent_keyring_expiry
798
799              Should  the  timeout  be reached, the persistent keyring will be
800              removed and everything it pins can then be garbage collected.
801
802              Persistent keyrings were added to Linux in kernel version 3.13.
803
804              The arguments arg4 and arg5 are ignored.
805
806              This operation  is  exposed  by  libkeyutils  via  the  function
807              keyctl_get_persistent(3).
808
809       KEYCTL_DH_COMPUTE (since Linux 4.7)
810              Compute a Diffie-Hellman shared secret or public key, optionally
811              applying key derivation function (KDF) to the result.
812
813              The arg2 argument is a pointer to a set of parameters containing
814              serial  numbers for three "user" keys used in the Diffie-Hellman
815              calculation, packaged in a structure of the following form:
816
817                  struct keyctl_dh_params {
818                      int32_t private; /* The local private key */
819                      int32_t prime; /* The prime, known to both parties */
820                      int32_t base;  /* The base integer: either a shared
821                                        generator or the remote public key */
822                  };
823
824              Each of the three keys specified in this  structure  must  grant
825              the caller read permission.  The payloads of these keys are used
826              to calculate the Diffie-Hellman result as:
827
828                  base ^ private mod prime
829
830              If the base is the shared generator, the  result  is  the  local
831              public key.  If the base is the remote public key, the result is
832              the shared secret.
833
834              The arg3 argument (cast to char *) points to a buffer where  the
835              result of the calculation is placed.  The size of that buffer is
836              specified in arg4 (cast to size_t).
837
838              The buffer must be large enough to accommodate the output  data,
839              otherwise  an  error is returned.  If arg4 is specified zero, in
840              which case the buffer is not used and the operation returns  the
841              minimum required buffer size (i.e., the length of the prime).
842
843              Diffie-Hellman  computations can be performed in user space, but
844              require a multiple-precision integer (MPI) library.  Moving  the
845              implementation  into  the  kernel gives access to the kernel MPI
846              implementation, and allows  access  to  secure  or  acceleration
847              hardware.
848
849              Adding  support  for  DH computation to the keyctl() system call
850              was considered a good fit due to  the  DH  algorithm's  use  for
851              deriving  shared  keys;  it  also  allows the type of the key to
852              determine which DH  implementation  (software  or  hardware)  is
853              appropriate.
854
855              If  the  arg5  argument  is  NULL,  then the DH result itself is
856              returned.  Otherwise (since Linux 4.12), it is a  pointer  to  a
857              structure  which specifies parameters of the KDF operation to be
858              applied:
859
860                  struct keyctl_kdf_params {
861                      char *hashname;     /* Hash algorithm name */
862                      char *otherinfo;    /* SP800-56A OtherInfo */
863                      __u32 otherinfolen; /* Length of otherinfo data */
864                      __u32 __spare[8];   /* Reserved */
865                  };
866
867              The hashname field is a null-terminated string which specifies a
868              hash name (available in the kernel's crypto API; the list of the
869              hashes available is rather tricky to observe;  please  refer  to
870              the "Kernel Crypto API Architecture" ⟨https://www.kernel.org/doc
871              /html/latest/crypto/architecture.html⟩  documentation  for   the
872              information  regarding  how  hash names are constructed and your
873              kernel's source and configuration  regarding  what  ciphers  and
874              templates  with  type CRYPTO_ALG_TYPE_SHASH are available) to be
875              applied to DH result in KDF operation.
876
877              The otherinfo  field  is  an  OtherInfo  data  as  described  in
878              SP800-56A  section 5.8.1.2 and is algorithm-specific.  This data
879              is concatenated with the result of DH operation and is  provided
880              as  an  input to the KDF operation.  Its size is provided in the
881              otherinfolen field and is limited by KEYCTL_KDF_MAX_OI_LEN  con‐
882              stant that defined in security/keys/internal.h to a value of 64.
883
884              The  __spare  field  is  currently unused.  It was ignored until
885              Linux 4.13 (but still should be  user-addressable  since  it  is
886              copied  to  the  kernel),  and should contain zeroes since Linux
887              4.13.
888
889              The KDF implementation complies with SP800-56A as well  as  with
890              SP800-108 (the counter KDF).
891
892              This  operation  is  exposed by libkeyutils (from version 1.5.10
893              onwards)   via   the    functions    keyctl_dh_compute(3)    and
894              keyctl_dh_compute_alloc(3).
895
896       KEYCTL_RESTRICT_KEYRING (since Linux 4.12)
897              Apply  a key-linking restriction to the keyring with the ID pro‐
898              vided in arg2 (cast to  key_serial_t).   The  caller  must  have
899              setattr  permission on the key.  If arg3 is NULL, any attempt to
900              add a key to the keyring is blocked;  otherwise  it  contains  a
901              pointer  to  a  string  with a key type name and arg4 contains a
902              pointer to string that describes the type-specific  restriction.
903              As  of  Linux  4.12, only the type "asymmetric" has restrictions
904              defined:
905
906              builtin_trusted
907                     Allows only keys that are signed by a key linked  to  the
908                     builtin keyring (".builtin_trusted_keys").
909
910              builtin_and_secondary_trusted
911                     Allows  only  keys that are signed by a key linked to the
912                     secondary  keyring  (".secondary_trusted_keys")  or,   by
913                     extension,  a  key in a builtin keyring, as the latter is
914                     linked to the former.
915
916              key_or_keyring:key
917              key_or_keyring:key:chain
918                     If key specifies the ID of a key  of  type  "asymmetric",
919                     then only keys that are signed by this key are allowed.
920
921                     If key specifies the ID of a keyring, then only keys that
922                     are signed by a key linked to this keyring are allowed.
923
924                     If ":chain" is specified, keys that are signed by a  keys
925                     linked  to  the destination keyring (that is, the keyring
926                     with the ID specified in  the  arg2  argument)  are  also
927                     allowed.
928
929              Note  that  a  restriction  can  be configured only once for the
930              specified keyring; once a restriction is set, it can't be  over‐
931              ridden.
932
933              The argument arg5 is ignored.
934

RETURN VALUE

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

ERRORS

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

VERSIONS

1127       This system call first appeared in Linux 2.6.10.
1128

CONFORMING TO

1130       This system call is a nonstandard Linux extension.
1131

NOTES

1133       No wrapper for this system call is provided in  glibc.   A  wrapper  is
1134       provided  in  the  libkeyutils  library.  When employing the wrapper in
1135       that library, link with -lkeyutils.  However, rather  than  using  this
1136       system  call  directly,  you  probably  want to use the various library
1137       functions mentioned in the descriptions of individual operations above.
1138

EXAMPLE

1140       The program below provide subset of the functionality of  the  request-
1141       key(8)  program  provided  by  the keyutils package.  For informational
1142       purposes, the program records various information in a log file.
1143
1144       As described in request_key(2), the request-key(8) program  is  invoked
1145       with command-line arguments that describe a key that is to be instanti‐
1146       ated.  The example program fetches and logs these arguments.  The  pro‐
1147       gram  assumes  authority  to  instantiate  the  requested key, and then
1148       instantiates that key.
1149
1150       The following shell session demonstrates the use of this  program.   In
1151       the  session,  we  compile  the  program and then use it to temporarily
1152       replace the standard request-key(8) program.   (Note  that  temporarily
1153       disabling  the  standard request-key(8) program may not be safe on some
1154       systems.)  While our example program is installed, we use  the  example
1155       program shown in request_key(2) to request a key.
1156
1157           $ cc -o key_instantiate key_instantiate.c -lkeyutils
1158           $ sudo mv /sbin/request-key /sbin/request-key.backup
1159           $ sudo cp key_instantiate /sbin/request-key
1160           $ ./t_request_key user mykey somepayloaddata
1161           Key ID is 20d035bf
1162           $ sudo mv /sbin/request-key.backup /sbin/request-key
1163
1164       Looking  at  the  log file created by this program, we can see the com‐
1165       mand-line arguments supplied to our example program:
1166
1167           $ cat /tmp/key_instantiate.log
1168           Time: Mon Nov  7 13:06:47 2016
1169
1170           Command line arguments:
1171             argv[0]:            /sbin/request-key
1172             operation:          create
1173             key_to_instantiate: 20d035bf
1174             UID:                1000
1175             GID:                1000
1176             thread_keyring:     0
1177             process_keyring:    0
1178             session_keyring:    256e6a6
1179
1180           Key description:      user;1000;1000;3f010000;mykey
1181           Auth key payload:     somepayloaddata
1182           Destination keyring:  256e6a6
1183           Auth key description: .request_key_auth;1000;1000;0b010000;20d035bf
1184
1185       The last few lines of the above output show that  the  example  program
1186       was able to fetch:
1187
1188       *  the  description  of  the key to be instantiated, which included the
1189          name of the key (mykey);
1190
1191       *  the payload of the authorization key, which consisted  of  the  data
1192          (somepayloaddata) passed to request_key(2);
1193
1194       *  the   destination   keyring  that  was  specified  in  the  call  to
1195          request_key(2); and
1196
1197       *  the description of the authorization key, where we can see that  the
1198          name  of  the authorization key matches the ID of the key that is to
1199          be instantiated (20d035bf).
1200
1201       The example program in request_key(2) specified the destination keyring
1202       as  KEY_SPEC_SESSION_KEYRING.  By examining the contents of /proc/keys,
1203       we can see that this was  translated  to  the  ID  of  the  destination
1204       keyring  (0256e6a6)  shown in the log output above; we can also see the
1205       newly created key with the name mykey and ID 20d035bf.
1206
1207           $ cat /proc/keys | egrep 'mykey|256e6a6'
1208           0256e6a6 I--Q---  194 perm 3f030000  1000  1000 keyring  _ses: 3
1209           20d035bf I--Q---    1 perm 3f010000  1000  1000 user     mykey: 16
1210
1211   Program source
1212
1213       /* key_instantiate.c */
1214
1215       #include <sys/types.h>
1216       #include <keyutils.h>
1217       #include <time.h>
1218       #include <fcntl.h>
1219       #include <stdio.h>
1220       #include <stdlib.h>
1221       #include <unistd.h>
1222       #include <string.h>
1223       #include <errno.h>
1224
1225       #ifndef KEY_SPEC_REQUESTOR_KEYRING
1226       #define KEY_SPEC_REQUESTOR_KEYRING      -8
1227       #endif
1228
1229       int
1230       main(int argc, char *argv[])
1231       {
1232           FILE *fp;
1233           time_t t;
1234           char *operation;
1235           key_serial_t key_to_instantiate, dest_keyring;
1236           key_serial_t thread_keyring, process_keyring, session_keyring;
1237           uid_t uid;
1238           gid_t gid;
1239           char dbuf[256];
1240           char auth_key_payload[256];
1241           int akp_size;       /* Size of auth_key_payload */
1242
1243           fp = fopen("/tmp/key_instantiate.log", "w");
1244           if (fp == NULL)
1245               exit(EXIT_FAILURE);
1246
1247           setbuf(fp, NULL);
1248
1249           t = time(NULL);
1250           fprintf(fp, "Time: %s\n", ctime(&t));
1251
1252           /*
1253            * The kernel passes a fixed set of arguments to the program
1254            * that it execs; fetch them.
1255            */
1256           operation = argv[1];
1257           key_to_instantiate = atoi(argv[2]);
1258           uid = atoi(argv[3]);
1259           gid = atoi(argv[4]);
1260           thread_keyring = atoi(argv[5]);
1261           process_keyring = atoi(argv[6]);
1262           session_keyring = atoi(argv[7]);
1263
1264           fprintf(fp, "Command line arguments:\n");
1265           fprintf(fp, "  argv[0]:            %s\n", argv[0]);
1266           fprintf(fp, "  operation:          %s\n", operation);
1267           fprintf(fp, "  key_to_instantiate: %lx\n",
1268                   (long) key_to_instantiate);
1269           fprintf(fp, "  UID:                %ld\n", (long) uid);
1270           fprintf(fp, "  GID:                %ld\n", (long) gid);
1271           fprintf(fp, "  thread_keyring:     %lx\n", (long) thread_keyring);
1272           fprintf(fp, "  process_keyring:    %lx\n", (long) process_keyring);
1273           fprintf(fp, "  session_keyring:    %lx\n", (long) 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:          %lx\n", (long) 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:  %lx\n", (long) 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 4.15 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                             2017-09-15                         KEYCTL(2)
Impressum