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