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