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 <keyutils.h>
10
11       key_serial_t add_key(const char *type, const char *description,
12                            const void *payload, size_t plen,
13                            key_serial_t keyring);
14
15       Note: There is no glibc wrapper for this system call; see NOTES.
16

DESCRIPTION

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

RETURN VALUE

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

ERRORS

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

VERSIONS

131       This system call first appeared in Linux 2.6.10.
132

CONFORMING TO

134       This system call is a nonstandard Linux extension.
135

NOTES

137       Glibc does not provide a wrapper for this system call.   A  wrapper  is
138       provided  in  the  libkeyutils  package.  When employing the wrapper in
139       that library, link with -lkeyutils.
140

EXAMPLES

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

COLOPHON

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