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 2016-07-17 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 <sys/types.h>
  18 .B #include <keyutils.h>
  19 .sp
  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 ");"
  23 .fi
  24
  25 No glibc wrapper is provided 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 .P
  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 .P
  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 Which key types support this?
  51 that key will be updated rather than a new key being created;
  52 if not, a new key (with a different ID) will be created
  53 and it will displace the link to the extant key from the keyring.
  54 .\" FIXME Perhaps elaborate the implications here? Namely, the new
  55 .\" key will have a new ID, and if the old key was a keyring tha
  56 .\" is consequently unlinked, then keys that it was anchrorin
  57 .\" will have their refgerence count decreased by one (and ma
  58 .\" consequently be garbage collected).
  59 .P
  60 The destination
  61 .I keyring
  62 serial number may be that of a valid keyring for which the caller has
  63 .I write
  64 permission, or 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 .IR """user"""
 100 This is a general purpose key type whose payload may be read and updated
 101 by user-space applications.
 102 The key is kept entirely within kernel memory.
 103 The payload for keys of this type is a blob of arbitrary data
 104 of up to 32,767 bytes.
 105 .TP
 106 .I """keyring"""
 107 Keyrings are special key types that may contain links to sequences of other
 108 keys of any type.
 109 If this interface is used to create a keyring, then a NULL
 110 .I payload
 111 should be specified, and
 112 .I plen
 113 should be zero.
 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 provide reading.
 120 This is suitable for storing payloads
 121 that you do not want to be readable from user space.
 122
 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 in tmpfs (which can be swapped out) rather than kernel
 137 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 cause of 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 (Part of)
 159 .IR type ", " description " or " payload
 160 points outside process' 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 from dot.
 197 .TP
 198 .B EPERM
 199 .I type
 200 was
 201 .I """keyring"""
 202 and the
 203 .I description
 204 started from dot.
 205 .SH VERSIONS
 206 This system call first appeared in Linux 2.6.10.
 207 .SH CONFORMING TO
 208 This system call is a nonstandard Linux extension.
 209 .SH NOTES
 210 No wrapper for this system call is provided in glibc.
 211 A wrapper is provided in the
 212 .IR libkeyutils
 213 package.
 214 When employing the wrapper in that library, link with
 215 .IR \-lkeyutils .
 216 .SH EXAMPLE
 217 The program below creates a key with the type, description, and payload
 218 specified in its command-line arguments,
 219 and links that key into the session keyring.
 220 The following shell session demonstrates the use of the program:
 221
 222 .in +4n
 223 .nf
 224 $ \fB./a.out user mykey "Some payload"\fP
 225 Key ID is 64a4dca
 226 $ \fBgrep \(aq64a4dca\(aq /proc/keys\fP
 227 064a4dca I--Q---    1 perm 3f010000  1000  1000 user    mykey: 12
 228 .fi
 229 .in
 230 .SS Program source
 231 \&
 232 .nf
 233 #include <sys/types.h>
 234 #include <keyutils.h>
 235 #include <stdio.h>
 236 #include <stdlib.h>
 237 #include <string.h>
 238
 239 int
 240 main(int argc, char *argv[])
 241 {
 242     key_serial_t key;
 243
 244     if (argc != 4) {
 245         fprintf(stderr, "Usage: %s type description payload\\n",
 246                 argv[0]);
 247         exit(EXIT_FAILURE);
 248     }
 249
 250     key = add_key(argv[1], argv[2], argv[3], strlen(argv[3]),
 251                 KEY_SPEC_SESSION_KEYRING);
 252     if (key == \-1) {
 253         perror("add_key");
 254         exit(EXIT_FAILURE);
 255     }
 256
 257     printf("Key ID is %lx\\n", (long) key);
 258
 259     exit(EXIT_SUCCESS);
 260 }
 261 .fi
 262 .SH SEE ALSO
 263 .ad l
 264 .nh
 265 .BR keyctl (1),
 266 .BR keyctl (2),
 267 .BR request_key (2),
 268 .BR keyctl (3),
 269 .BR keyutils (7),
 270 .BR keyrings (7),
 271 .BR persistent\-keyring (7),
 272 .BR process\-keyring (7),
 273 .BR session\-keyring (7),
 274 .BR thread\-keyring (7),
 275 .BR user\-keyring (7),
 276 .BR user\-session\-keyring (7)
 277
 278 The kernel source files
 279 .IR Documentation/security/keys.txt
 280 and
 281 .IR Documentation/security/keys\-request\-key.txt .