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 library.  (The accompanying package pro‐
139       vides the <keyutils.h> header file.)  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.13 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                             2021-08-27                        ADD_KEY(2)