add_key(2)

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

NAME

6       add_key - add a key to the kernel's key management facility
7

SYNOPSIS

9       #include <sys/types.h>
10       #include <keyutils.h>
11
12       key_serial_t add_key(const char *type, const char *description,
13                            const void *payload, size_t plen,
14                            key_serial_t keyring);
15
16       No glibc wrapper is provided for this system call; see NOTES.
17

DESCRIPTION

19       add_key()  creates  or updates a key of the given type and description,
20       instantiates it with the payload of length plen,  attaches  it  to  the
21       nominated keyring, and returns the key's serial number.
22
23       The  key may be rejected if the provided data is in the wrong format or
24       it is invalid in some other way.
25
26       If the destination keyring already contains  a  key  that  matches  the
27       specified type and description, then, if the key type supports it, that
28       key will be updated rather than a new key being created; if not, a  new
29       key (with a different ID) will be created and it will displace the link
30       to the extant key from the keyring.
31
32       The destination keyring serial number may be that of  a  valid  keyring
33       for  which  the  caller has write permission.  Alternatively, it may be
34       one of the following special keyring IDs:
35
36       KEY_SPEC_THREAD_KEYRING
37              This specifies the  caller's  thread-specific  keyring  (thread-
38              keyring(7)).
39
40       KEY_SPEC_PROCESS_KEYRING
41              This  specifies  the caller's process-specific keyring (process-
42              keyring(7)).
43
44       KEY_SPEC_SESSION_KEYRING
45              This specifies the caller's session-specific  keyring  (session-
46              keyring(7)).
47
48       KEY_SPEC_USER_KEYRING
49              This   specifies   the   caller's  UID-specific  keyring  (user-
50              keyring(7)).
51
52       KEY_SPEC_USER_SESSION_KEYRING
53              This specifies the caller's UID-session  keyring  (user-session-
54              keyring(7)).
55
56   Key types
57       The  key  type  is a string that specifies the key's type.  Internally,
58       the kernel defines a number of key types that are available in the core
59       key management code.  Among the types that are available for user-space
60       use and can be specified as the type argument to add_key() are the fol‐
61       lowing:
62
63       "keyring"
64              Keyrings  are  special  key  types that may contain links to se‐
65              quences of other keys of any type.  If this interface is used to
66              create a keyring, then payload should be NULL and plen should be
67              zero.
68
69       "user" This is a general purpose key type whose payload may be read and
70              updated  by  user-space  applications.  The key is kept entirely
71              within kernel memory.  The payload for keys of this  type  is  a
72              blob of arbitrary data of up to 32,767 bytes.
73
74       "logon" (since Linux 3.3)
75              This key type is essentially the same as "user", but it does not
76              permit the key to read.  This is suitable for  storing  payloads
77              that you do not want to be readable from user space.
78
79       This  key type vets the description to ensure that it is qualified by a
80       "service" prefix, by checking to ensure that the description contains a
81       ':' that is preceded by other characters.
82
83       "big_key" (since Linux 3.13)
84              This key type is similar to "user", but may hold a payload of up
85              to 1 MiB.  If the key payload is large enough, then  it  may  be
86              stored encrypted in tmpfs (which can be swapped out) rather than
87              kernel memory.
88
89       For further details on these key types, see keyrings(7).
90

RETURN VALUE

92       On success, add_key() returns the serial number of the key  it  created
93       or  updated.  On error, -1 is returned and errno is set to indicate the
94       cause of the error.
95

ERRORS

97       EACCES The keyring wasn't available for modification by the user.
98
99       EDQUOT The key quota for this user would be exceeded by  creating  this
100              key or linking it to the keyring.
101
102       EFAULT One  or  more  of  type, description, and payload points outside
103              process's accessible address space.
104
105       EINVAL The size of the string (including  the  terminating  null  byte)
106              specified  in  type  or description exceeded the limit (32 bytes
107              and 4096 bytes respectively).
108
109       EINVAL The payload data was invalid.
110
111       EINVAL type was "logon" and the description was not  qualified  with  a
112              prefix string of the form "service:".
113
114       EKEYEXPIRED
115              The keyring has expired.
116
117       EKEYREVOKED
118              The keyring has been revoked.
119
120       ENOKEY The keyring doesn't exist.
121
122       ENOMEM Insufficient memory to create a key.
123
124       EPERM  The type started with a period ('.').  Key types that begin with
125              a period are reserved to the implementation.
126
127       EPERM  type was "keyring" and the description  started  with  a  period
128              ('.').  Keyrings with descriptions (names) that begin with a pe‐
129              riod are reserved to the implementation.
130

VERSIONS

132       This system call first appeared in Linux 2.6.10.
133

CONFORMING TO

135       This system call is a nonstandard Linux extension.
136

NOTES

138       No wrapper for this system call is provided in  glibc.   A  wrapper  is
139       provided  in  the  libkeyutils  package.  When employing the wrapper in
140       that library, link with -lkeyutils.
141

EXAMPLES

143       The program below creates a key with the type, description, and payload
144       specified  in  its  command-line arguments, and links that key into the
145       session keyring.  The following shell session demonstrates the  use  of
146       the program:
147
148           $ ./a.out user mykey "Some payload"
149           Key ID is 64a4dca
150           $ grep '64a4dca' /proc/keys
151           064a4dca I--Q---    1 perm 3f010000  1000  1000 user    mykey: 12
152
153   Program source
154
155       #include <sys/types.h>
156       #include <keyutils.h>
157       #include <stdint.h>
158       #include <stdio.h>
159       #include <stdlib.h>
160       #include <string.h>
161
162       int
163       main(int argc, char *argv[])
164       {
165           key_serial_t key;
166
167           if (argc != 4) {
168               fprintf(stderr, "Usage: %s type description payload\n",
169                       argv[0]);
170               exit(EXIT_FAILURE);
171           }
172
173           key = add_key(argv[1], argv[2], argv[3], strlen(argv[3]),
174                       KEY_SPEC_SESSION_KEYRING);
175           if (key == -1) {
176               perror("add_key");
177               exit(EXIT_FAILURE);
178           }
179
180           printf("Key ID is %jx\n", (uintmax_t) key);
181
182           exit(EXIT_SUCCESS);
183       }
184

COLOPHON

197       This page is part of release 5.10 of the Linux man-pages project.  A
198       description of the project, information about reporting bugs, and the
199       latest version of this page, can be found at
200       https://www.kernel.org/doc/man-pages/.
201
202
203
204Linux                             2020-11-01                        ADD_KEY(2)