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 return the key's serial number.
  39 .P
  40 The key type may reject the data if it is in the wrong format or
  41 is in some other way invalid.
  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, that key will be updated rather than a new
  50 key being created; if not, a new key will be created and it will displace the
  51 link to the extant key from the keyring.
  52 .\" FIXME In the previous paragraph, what is the significance of the fact
  53 .\" that in some cases the existing key is updated versus in other cases a
  54 .\" new key is created? Is it just that the key ID will be different?
  55 .P
  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, or it may be one of the following special keyring IDs:
  61 .TP
  62 .B KEY_SPEC_THREAD_KEYRING
  63 This specifies the caller's thread-specific keyring
  64 .RB ( thread-keyring (7)).
  65 .TP
  66 .B KEY_SPEC_PROCESS_KEYRING
  67 This specifies the caller's process-specific keyring
  68 .RB ( process-keyring (7)).
  69 .TP
  70 .B KEY_SPEC_SESSION_KEYRING
  71 This specifies the caller's session-specific keyring
  72 .RB ( session-keyring (7)).
  73 .TP
  74 .B KEY_SPEC_USER_KEYRING
  75 This specifies the caller's UID-specific keyring
  76 .RB ( user-keyring (7)).
  77 .TP
  78 .B KEY_SPEC_USER_SESSION_KEYRING
  79 This specifies the caller's UID-session keyring
  80 .RB ( user-session-keyring (7)).
  81 .SS Key types
  82 The key
  83 .I type
  84 is a string that specifies the key's type.
  85 Internally, the kernel defines a number of key types that are
  86 available in the core key management code.
  87 The following types are available for user-space use,
  88 and can be specified as the
  89 .I type
  90 argument to
  91 .BR add_key ():
  92 .TP
  93 .IR """user"""
  94 The payload for keys of this type is a blob of arbitrary data
  95 of up to 32,767 bytes.
  96 The
  97 .I description
  98 may be any valid string, though it is preferred that it
  99 start with a colon-delimited prefix representing the service
 100 to which the key is of interest
 101 (for instance
 102 .IR """afs:mykey""" ).
 103 .TP
 104 .I """keyring"""
 105 Keyrings are special key types that may contain links to sequences of other
 106 keys of any type.
 107 If this interface is used to create a keyring, then a NULL
 108 .I payload
 109 should be specified, and
 110 .I plen
 111 should be zero.
 112 .TP
 113 .IR """logon""" " (since Linux 3.3)"
 114 .\" commit 9f6ed2ca257fa8650b876377833e6f14e272848b
 115 This key type is essentially the same as
 116 .IR """user""" ,
 117 but does not provide reading (i.e., the
 118 .BR keyctl (2)
 119 .BR KEYCTL_READ
 120 operation),
 121 meaning that the key payload is never visible from user space.
 122 This is suitable for storing username and password pairs in the keyring
 123 that you do not want to be readable from user space.
 124
 125 This key type also 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 For this key type,
 138 the contents can be saved in a tmpfs filesystem and
 139 thus swapped out to disk when memory pressure is high.
 140 This key type is useful for tasks such as holding Kerberos ticket caches.
 141 .\" FIXME Are there any other key tpes available for user-space use?
 142 .SH RETURN VALUE
 143 On success,
 144 .BR add_key ()
 145 returns the serial number of the key it created or updated.
 146 On error, \-1 is returned and
 147 .I errno
 148 is set to indicate the cause of the error.
 149 .\" FIXME Is there any difference between the terms "key serial number"
 150 .\" and "key ID"? What about "special key IDs"? (Can one equally talk
 151 .\" of a "special key serial number"?
 152 .SH ERRORS
 153 .TP
 154 .B EACCES
 155 The keyring wasn't available for modification by the user.
 156 .TP
 157 .B EDQUOT
 158 The key quota for this user would be exceeded by creating this key or linking
 159 it to the keyring.
 160 .TP
 161 .B EINVAL
 162 The size of the string (including the terminating null byte) specified in
 163 .I type
 164 or
 165 .I description
 166 exceeded the limit (32 bytes and 4096 bytes respectively).
 167 .TP
 168 .B EINVAL
 169 The payload data was invalid.
 170 .TP
 171 .B EINVAL
 172 .IR type
 173 was
 174 .IR """logon"""
 175 and the
 176 .I description
 177 was not qualified with a prefix string of the form
 178 .IR """service:""" .
 179 .TP
 180 .B EKEYEXPIRED
 181 The keyring has expired.
 182 .TP
 183 .B EKEYREVOKED
 184 The keyring has been revoked.
 185 .TP
 186 .B ENOKEY
 187 The keyring doesn't exist.
 188 .TP
 189 .B ENOMEM
 190 Insufficient memory to create a key.
 191 .SH VERSIONS
 192 This system call first appeared in Linux 2.6.11.
 193 .SH CONFORMING TO
 194 This system call is a nonstandard Linux extension.
 195 .SH NOTES
 196 No wrapper for this system call is provided in glibc.
 197 A wrapper is provided in the
 198 .IR libkeyutils
 199 package.
 200 When employing the wrapper in that library, link with
 201 .IR \-lkeyutils .
 202 .SH EXAMPLE
 203 The program below creates a key with the type, description, and payload
 204 specified in its command-line arguments,
 205 and links that key into the session keyring.
 206 The following shell session demonstrates the use of the program:
 207
 208 .in +4n
 209 .nf
 210 $ \fB./a.out user mykey "Some payload"\fP
 211 Key ID is 64a4dca
 212 $ \fBgrep \(aq64a4dca\(aq /proc/keys\fP
 213 064a4dca I--Q---    1 perm 3f010000  1000  1000 user    mykey: 12
 214 .fi
 215 .in
 216 .SS Program source
 217 \&
 218 .nf
 219 #include <sys/types.h>
 220 #include <keyutils.h>
 221 #include <stdio.h>
 222 #include <stdlib.h>
 223 #include <string.h>
 224
 225 #define errExit(msg)    do { perror(msg); exit(EXIT_FAILURE); \\
 226                         } while (0)
 227
 228 int
 229 main(int argc, char *argv[])
 230 {
 231     key_serial_t key;
 232
 233     if (argc != 4) {
 234         fprintf(stderr, "Usage: %s type description payload\\n",
 235                 argv[0]);
 236         exit(EXIT_FAILURE);
 237     }
 238
 239     key = add_key(argv[1], argv[2], argv[3], strlen(argv[3]),
 240                 KEY_SPEC_SESSION_KEYRING);
 241     if (key == \-1)
 242         errExit("add_key");
 243
 244     printf("Key ID is %lx\\n", (long) key);
 245
 246     exit(EXIT_SUCCESS);
 247 }
 248 .fi
 249 .SH SEE ALSO
 250 .ad l
 251 .nh
 252 .BR keyctl (1),
 253 .BR keyctl (2),
 254 .BR request_key (2),
 255 .BR keyctl (3),
 256 .BR keyutils (7),
 257 .BR keyrings (7),
 258 .BR persistent\-keyring (7),
 259 .BR process\-keyring (7),
 260 .BR session\-keyring (7),
 261 .BR thread\-keyring (7),
 262 .BR user\-keyring (7),
 263 .BR user\-session\-keyring (7)
 264
 265 The kernel source files
 266 .IR Documentation/security/keys.txt
 267 and
 268 .IR Documentation/security/keys\-request\-key.txt .