man2/add_key.2

   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>
   4 .\"
   5 .\" SPDX-License-Identifier: GPL-2.0-or-later
   6 .\"
   7 .TH ADD_KEY 2 2021-08-27 Linux "Linux Key Management Calls"
   8 .SH NAME
   9 add_key \- add a key to the kernel's key management facility
  10 .SH SYNOPSIS
  11 .nf
  12 .B #include <keyutils.h>
  13 .PP
  14 .BI "key_serial_t add_key(const char *" type ", const char *" description ,
  15 .BI "                     const void *" payload ", size_t " plen ,
  16 .BI "                     key_serial_t " keyring ");"
  17 .fi
  18 .PP
  19 .IR Note :
  20 There is no glibc wrapper for this system call; see NOTES.
  21 .SH DESCRIPTION
  22 .BR add_key ()
  23 creates or updates a key of the given
  24 .I type
  25 and
  26 .IR description ,
  27 instantiates it with the
  28 .I payload
  29 of length
  30 .IR plen ,
  31 attaches it to the nominated
  32 .IR keyring ,
  33 and returns the key's serial number.
  34 .PP
  35 The key may be rejected if the provided data is in the wrong format or
  36 it is invalid in some other way.
  37 .PP
  38 If the destination
  39 .I keyring
  40 already contains a key that matches the specified
  41 .IR type
  42 and
  43 .IR description ,
  44 then, if the key type supports it,
  45 .\" FIXME The aforementioned phrases begs the question:
  46 .\" which key types support this?
  47 that key will be updated rather than a new key being created;
  48 if not, a new key (with a different ID) will be created
  49 and it will displace the link to the extant key from the keyring.
  50 .\" FIXME Perhaps elaborate the implications here? Namely, the new
  51 .\" key will have a new ID, and if the old key was a keyring that
  52 .\" is consequently unlinked, then keys that it was anchoring
  53 .\" will have their reference count decreased by one (and may
  54 .\" consequently be garbage collected). Is this all correct?
  55 .PP
  56 The destination
  57 .I keyring
  58 serial number may be that of a valid keyring for which the caller has
  59 .I write
  60 permission.
  61 Alternatively, it may be one of the following special keyring IDs:
  62 .\" FIXME . Perhaps have a separate page describing special keyring IDs?
  63 .TP
  64 .B KEY_SPEC_THREAD_KEYRING
  65 This specifies the caller's thread-specific keyring
  66 .RB ( thread\-keyring (7)).
  67 .TP
  68 .B KEY_SPEC_PROCESS_KEYRING
  69 This specifies the caller's process-specific keyring
  70 .RB ( process\-keyring (7)).
  71 .TP
  72 .B KEY_SPEC_SESSION_KEYRING
  73 This specifies the caller's session-specific keyring
  74 .RB ( session\-keyring (7)).
  75 .TP
  76 .B KEY_SPEC_USER_KEYRING
  77 This specifies the caller's UID-specific keyring
  78 .RB ( user\-keyring (7)).
  79 .TP
  80 .B KEY_SPEC_USER_SESSION_KEYRING
  81 This specifies the caller's UID-session keyring
  82 .RB ( user\-session\-keyring (7)).
  83 .SS Key types
  84 The key
  85 .I type
  86 is a string that specifies the key's type.
  87 Internally, the kernel defines a number of key types that are
  88 available in the core key management code.
  89 Among the types that are available for user-space use
  90 and can be specified as the
  91 .I type
  92 argument to
  93 .BR add_key ()
  94 are the following:
  95 .TP
  96 .I """keyring"""
  97 Keyrings are special key types that may contain links to sequences of other
  98 keys of any type.
  99 If this interface is used to create a keyring, then
 100 .I payload
 101 should be NULL and
 102 .I plen
 103 should be zero.
 104 .TP
 105 .IR """user"""
 106 This is a general purpose key type whose payload may be read and updated
 107 by user-space applications.
 108 The key is kept entirely within kernel memory.
 109 The payload for keys of this type is a blob of arbitrary data
 110 of up to 32,767 bytes.
 111 .TP
 112 .IR """logon""" " (since Linux 3.3)"
 113 .\" commit 9f6ed2ca257fa8650b876377833e6f14e272848b
 114 This key type is essentially the same as
 115 .IR """user""" ,
 116 but it does not permit the key to read.
 117 This is suitable for storing payloads
 118 that you do not want to be readable from user space.
 119 .PP
 120 This key type vets the
 121 .I description
 122 to ensure that it is qualified by a "service" prefix,
 123 by checking to ensure that the
 124 .I description
 125 contains a ':' that is preceded by other characters.
 126 .TP
 127 .IR """big_key""" " (since Linux 3.13)"
 128 .\" commit ab3c3587f8cda9083209a61dbe3a4407d3cada10
 129 This key type is similar to
 130 .IR """user""" ,
 131 but may hold a payload of up to 1\ MiB.
 132 If the key payload is large enough,
 133 then it may be stored encrypted in tmpfs
 134 (which can be swapped out) rather than kernel memory.
 135 .PP
 136 For further details on these key types, see
 137 .BR keyrings (7).
 138 .SH RETURN VALUE
 139 On success,
 140 .BR add_key ()
 141 returns the serial number of the key it created or updated.
 142 On error, \-1 is returned and
 143 .I errno
 144 is set to indicate the error.
 145 .SH ERRORS
 146 .TP
 147 .B EACCES
 148 The keyring wasn't available for modification by the user.
 149 .TP
 150 .B EDQUOT
 151 The key quota for this user would be exceeded by creating this key or linking
 152 it to the keyring.
 153 .TP
 154 .B EFAULT
 155 One or more of
 156 .IR type ,
 157 .IR description ,
 158 and
 159 .I payload
 160 points outside process's accessible address space.
 161 .TP
 162 .B EINVAL
 163 The size of the string (including the terminating null byte) specified in
 164 .I type
 165 or
 166 .I description
 167 exceeded the limit (32 bytes and 4096 bytes respectively).
 168 .TP
 169 .B EINVAL
 170 The payload data was invalid.
 171 .TP
 172 .B EINVAL
 173 .IR type
 174 was
 175 .IR """logon"""
 176 and the
 177 .I description
 178 was not qualified with a prefix string of the form
 179 .IR """service:""" .
 180 .TP
 181 .B EKEYEXPIRED
 182 The keyring has expired.
 183 .TP
 184 .B EKEYREVOKED
 185 The keyring has been revoked.
 186 .TP
 187 .B ENOKEY
 188 The keyring doesn't exist.
 189 .TP
 190 .B ENOMEM
 191 Insufficient memory to create a key.
 192 .TP
 193 .B EPERM
 194 The
 195 .I type
 196 started with a period (\(aq.\(aq).
 197 Key types that begin with a period are reserved to the implementation.
 198 .TP
 199 .B EPERM
 200 .I type
 201 was
 202 .I """keyring"""
 203 and the
 204 .I description
 205 started with a period (\(aq.\(aq).
 206 Keyrings with descriptions (names)
 207 that begin with a period are reserved to the implementation.
 208 .SH VERSIONS
 209 This system call first appeared in Linux 2.6.10.
 210 .SH CONFORMING TO
 211 This system call is a nonstandard Linux extension.
 212 .SH NOTES
 213 Glibc does not provide a wrapper for this system call.
 214 A wrapper is provided in the
 215 .IR libkeyutils
 216 library.
 217 (The accompanying package provides the
 218 .I <keyutils.h>
 219 header file.)
 220 When employing the wrapper in that library, link with
 221 .IR \-lkeyutils .
 222 .SH EXAMPLES
 223 The program below creates a key with the type, description, and payload
 224 specified in its command-line arguments,
 225 and links that key into the session keyring.
 226 The following shell session demonstrates the use of the program:
 227 .PP
 228 .in +4n
 229 .EX
 230 $ \fB./a.out user mykey "Some payload"\fP
 231 Key ID is 64a4dca
 232 $ \fBgrep \(aq64a4dca\(aq /proc/keys\fP
 233 064a4dca I\-\-Q\-\-\-    1 perm 3f010000  1000  1000 user    mykey: 12
 234 .EE
 235 .in
 236 .SS Program source
 237 \&
 238 .EX
 239 #include <sys/types.h>
 240 #include <keyutils.h>
 241 #include <stdint.h>
 242 #include <stdio.h>
 243 #include <stdlib.h>
 244 #include <string.h>
 245
 246 int
 247 main(int argc, char *argv[])
 248 {
 249     key_serial_t key;
 250
 251     if (argc != 4) {
 252         fprintf(stderr, "Usage: %s type description payload\en",
 253                 argv[0]);
 254         exit(EXIT_FAILURE);
 255     }
 256
 257     key = add_key(argv[1], argv[2], argv[3], strlen(argv[3]),
 258                 KEY_SPEC_SESSION_KEYRING);
 259     if (key == \-1) {
 260         perror("add_key");
 261         exit(EXIT_FAILURE);
 262     }
 263
 264     printf("Key ID is %jx\en", (uintmax_t) key);
 265
 266     exit(EXIT_SUCCESS);
 267 }
 268 .EE
 269 .SH SEE ALSO
 270 .ad l
 271 .nh
 272 .BR keyctl (1),
 273 .BR keyctl (2),
 274 .BR request_key (2),
 275 .BR keyctl (3),
 276 .BR keyrings (7),
 277 .BR keyutils (7),
 278 .BR persistent\-keyring (7),
 279 .BR process\-keyring (7),
 280 .BR session\-keyring (7),
 281 .BR thread\-keyring (7),
 282 .BR user\-keyring (7),
 283 .BR user\-session\-keyring (7)
 284 .PP
 285 The kernel source files
 286 .IR Documentation/security/keys/core.rst
 287 and
 288 .IR Documentation/keys/request\-key.rst
 289 (or, before Linux 4.13, in the files
 290 .\" commit b68101a1e8f0263dbc7b8375d2a7c57c6216fb76
 291 .IR Documentation/security/keys.txt
 292 and
 293 .\" commit 3db38ed76890565772fcca3279cc8d454ea6176b
 294 .IR Documentation/security/keys\-request\-key.txt ).