add_key(2)

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

NAME

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

LIBRARY

9       Standard C library (libc, -lc)
10

SYNOPSIS

12       #include <keyutils.h>
13
14       key_serial_t add_key(const char *type, const char *description,
15                            const void payload[.plen], size_t plen,
16                            key_serial_t keyring);
17
18       Note: There is no glibc wrapper for this system call; see NOTES.
19

DESCRIPTION

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

RETURN VALUE

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

ERRORS

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

STANDARDS

134       Linux.
135

HISTORY

137       Linux 2.6.10.
138

NOTES

140       glibc does not provide a wrapper for this system call.   A  wrapper  is
141       provided  in  the  libkeyutils library.  (The accompanying package pro‐
142       vides the <keyutils.h> header file.)  When  employing  the  wrapper  in
143       that library, link with -lkeyutils.
144

EXAMPLES

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