1 .\" Copyright (C) 2006 Red Hat, Inc. All Rights Reserved.
2 .\" Written by David Howells (dhowells@redhat.com)
3 .\" and Copyright (C) 2016 Michael Kerrisk <mtk.man-pages@gmail.com>
5 .\" %%%LICENSE_START(GPLv2+_SW_ONEPARA)
6 .\" This program is free software; you can redistribute it and/or
7 .\" modify it under the terms of the GNU General Public License
8 .\" as published by the Free Software Foundation; either version
9 .\" 2 of the License, or (at your option) any later version.
12 .TH ADD_KEY 2 2021-03-22 Linux "Linux Key Management Calls"
14 add_key \- add a key to the kernel's key management facility
17 .B #include <sys/types.h>
18 .B #include <keyutils.h>
20 .BI "key_serial_t add_key(const char *" type ", const char *" description ,
21 .BI " const void *" payload ", size_t " plen ,
22 .BI " key_serial_t " keyring ");"
26 There is no glibc wrapper for this system call; see NOTES.
29 creates or updates a key of the given
33 instantiates it with the
37 attaches it to the nominated
39 and returns the key's serial number.
41 The key may be rejected if the provided data is in the wrong format or
42 it is invalid in some other way.
46 already contains a key that matches the specified
50 then, if the key type supports it,
51 .\" FIXME The aforementioned phrases begs the question:
52 .\" which key types support this?
53 that key will be updated rather than a new key being created;
54 if not, a new key (with a different ID) will be created
55 and it will displace the link to the extant key from the keyring.
56 .\" FIXME Perhaps elaborate the implications here? Namely, the new
57 .\" key will have a new ID, and if the old key was a keyring that
58 .\" is consequently unlinked, then keys that it was anchoring
59 .\" will have their reference count decreased by one (and may
60 .\" consequently be garbage collected). Is this all correct?
64 serial number may be that of a valid keyring for which the caller has
67 Alternatively, it may be one of the following special keyring IDs:
68 .\" FIXME . Perhaps have a separate page describing special keyring IDs?
70 .B KEY_SPEC_THREAD_KEYRING
71 This specifies the caller's thread-specific keyring
72 .RB ( thread\-keyring (7)).
74 .B KEY_SPEC_PROCESS_KEYRING
75 This specifies the caller's process-specific keyring
76 .RB ( process\-keyring (7)).
78 .B KEY_SPEC_SESSION_KEYRING
79 This specifies the caller's session-specific keyring
80 .RB ( session\-keyring (7)).
82 .B KEY_SPEC_USER_KEYRING
83 This specifies the caller's UID-specific keyring
84 .RB ( user\-keyring (7)).
86 .B KEY_SPEC_USER_SESSION_KEYRING
87 This specifies the caller's UID-session keyring
88 .RB ( user\-session\-keyring (7)).
92 is a string that specifies the key's type.
93 Internally, the kernel defines a number of key types that are
94 available in the core key management code.
95 Among the types that are available for user-space use
96 and can be specified as the
103 Keyrings are special key types that may contain links to sequences of other
105 If this interface is used to create a keyring, then
112 This is a general purpose key type whose payload may be read and updated
113 by user-space applications.
114 The key is kept entirely within kernel memory.
115 The payload for keys of this type is a blob of arbitrary data
116 of up to 32,767 bytes.
118 .IR """logon""" " (since Linux 3.3)"
119 .\" commit 9f6ed2ca257fa8650b876377833e6f14e272848b
120 This key type is essentially the same as
122 but it does not permit the key to read.
123 This is suitable for storing payloads
124 that you do not want to be readable from user space.
126 This key type vets the
128 to ensure that it is qualified by a "service" prefix,
129 by checking to ensure that the
131 contains a ':' that is preceded by other characters.
133 .IR """big_key""" " (since Linux 3.13)"
134 .\" commit ab3c3587f8cda9083209a61dbe3a4407d3cada10
135 This key type is similar to
137 but may hold a payload of up to 1\ MiB.
138 If the key payload is large enough,
139 then it may be stored encrypted in tmpfs
140 (which can be swapped out) rather than kernel memory.
142 For further details on these key types, see
147 returns the serial number of the key it created or updated.
148 On error, \-1 is returned and
150 is set to indicate the error.
154 The keyring wasn't available for modification by the user.
157 The key quota for this user would be exceeded by creating this key or linking
166 points outside process's accessible address space.
169 The size of the string (including the terminating null byte) specified in
173 exceeded the limit (32 bytes and 4096 bytes respectively).
176 The payload data was invalid.
184 was not qualified with a prefix string of the form
188 The keyring has expired.
191 The keyring has been revoked.
194 The keyring doesn't exist.
197 Insufficient memory to create a key.
202 started with a period (\(aq.\(aq).
203 Key types that begin with a period are reserved to the implementation.
211 started with a period (\(aq.\(aq).
212 Keyrings with descriptions (names)
213 that begin with a period are reserved to the implementation.
215 This system call first appeared in Linux 2.6.10.
217 This system call is a nonstandard Linux extension.
219 Glibc does not provide a wrapper for this system call.
220 A wrapper is provided in the
223 When employing the wrapper in that library, link with
226 The program below creates a key with the type, description, and payload
227 specified in its command-line arguments,
228 and links that key into the session keyring.
229 The following shell session demonstrates the use of the program:
233 $ \fB./a.out user mykey "Some payload"\fP
235 $ \fBgrep \(aq64a4dca\(aq /proc/keys\fP
236 064a4dca I\-\-Q\-\-\- 1 perm 3f010000 1000 1000 user mykey: 12
242 #include <sys/types.h>
243 #include <keyutils.h>
250 main(int argc, char *argv[])
255 fprintf(stderr, "Usage: %s type description payload\en",
260 key = add_key(argv[1], argv[2], argv[3], strlen(argv[3]),
261 KEY_SPEC_SESSION_KEYRING);
267 printf("Key ID is %jx\en", (uintmax_t) key);
281 .BR persistent\-keyring (7),
282 .BR process\-keyring (7),
283 .BR session\-keyring (7),
284 .BR thread\-keyring (7),
285 .BR user\-keyring (7),
286 .BR user\-session\-keyring (7)
288 The kernel source files
289 .IR Documentation/security/keys/core.rst
291 .IR Documentation/keys/request\-key.rst
292 (or, before Linux 4.13, in the files
293 .\" commit b68101a1e8f0263dbc7b8375d2a7c57c6216fb76
294 .IR Documentation/security/keys.txt
296 .\" commit 3db38ed76890565772fcca3279cc8d454ea6176b
297 .IR Documentation/security/keys\-request\-key.txt ).