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