keyctl_instantiate.3

   1 .\"
   2 .\" Copyright (C) 2006 Red Hat, Inc. All Rights Reserved.
   3 .\" Written by David Howells (dhowells@redhat.com)
   4 .\"
   5 .\" This program is free software; you can redistribute it and/or
   6 .\" modify it under the terms of the GNU General Public License
   7 .\" as published by the Free Software Foundation; either version
   8 .\" 2 of the License, or (at your option) any later version.
   9 .\"
  10 .TH KEYCTL_INSTANTIATE 3 "4 May 2006" Linux "Linux Key Management Calls"
  11 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
  12 .SH NAME
  13 keyctl_assume_authority \- Assume the authority to instantiate a key
  14 .br
  15 keyctl_instantiate \- Instantiate a key from flat data
  16 .br
  17 keyctl_instantiate_iov \- Instantiate a key from segmented data
  18 .br
  19 keyctl_reject \- Negatively instantiate a key specifying search error
  20 .br
  21 keyctl_negate \- Negatively instantiate a key
  22 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
  23 .SH SYNOPSIS
  24 .nf
  25 .B #include <keyutils.h>
  26 .sp
  27 .BI "long keyctl_assume_authority(key_serial_t " key ");"
  28 .sp
  29 .BI "long keyctl_instantiate(key_serial_t " key ", const void *" payload ,
  30 .BI "size_t " plen ", key_serial_t " keyring ");"
  31 .sp
  32 .BI "long keyctl_instantiate_iov(key_serial_t " key ,
  33 .BI "const struct iovec *" payload_iov ", unsigned " ioc ,
  34 .BI "key_serial_t " keyring ");"
  35 .sp
  36 .BI "long keyctl_negate(key_serial_t " key ", unsigned " timeout ,
  37 .BI "key_serial_t " keyring ");"
  38 .sp
  39 .BI "long keyctl_reject(key_serial_t " key ", unsigned " timeout ,
  40 .BI "unsigned " error ", key_serial_t " keyring ");"
  41 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
  42 .SH DESCRIPTION
  43 .BR keyctl_assume_authority ()
  44 assumes the authority for the calling thread to deal with and instantiate the
  45 specified uninstantiated
  46 .IR key .
  47 .P
  48 The calling thread must have the appopriate authorisation key resident in one
  49 of its keyrings for this to succeed, and that authority must not have been
  50 revoked.
  51 .P
  52 The authorising key is allocated by request_key() when it needs to invoke
  53 userspace to generate a key for the requesting process.  This is then attached
  54 to one of the keyrings of the userspace process to which the task of
  55 instantiating the key is given:
  56 .IP
  57 requester -> request_key() -> instantiator
  58 .P
  59 Calling this function modifies the way
  60 .BR request_key ()
  61 works when called thereafter by the calling (instantiator) thread; once the
  62 authority is assumed, the keyrings of the initial process are added to the
  63 search path, using the initial process's UID, GID, groups and security
  64 context.
  65 .P
  66 If a thread has multiple instantiations to deal with, it may call this
  67 function to change the authorisation key currently in effect.  Supplying a
  68 .B zero
  69 .I key
  70 de-assumes the currently assumed authority.
  71 .P
  72 .B NOTE!
  73 This is a per-thread setting and not a per-process setting so that a
  74 multithreaded process can be used to instantiate several keys at once.
  75 .P
  76 .BR keyctl_instantiate ()
  77 instantiates the payload of an uninstantiated key from the data specified.
  78 .I payload
  79 and
  80 .I plen
  81 specify the data for the new payload.
  82 .I payload
  83 may be NULL and
  84 .I plen
  85 may be zero if the key type permits that.  The key type may reject the data if
  86 it's in the wrong format or in some other way invalid.
  87 .P
  88 .BR keyctl_instantiate_iov ()
  89 is similar, but the data is passed in an array of iovec structs instead of in
  90 a flat buffer.
  91 .I payload_iov
  92 points to the base of the array and
  93 .I ioc
  94 indicates how many elements there are.
  95 .I payload_iov
  96 may be NULL or
  97 .I ioc
  98 may be zero to indicate that no data is being supplied.
  99 .P
 100 .BR keyctl_reject ()
 101 marks a key as negatively instantiated and sets the expiration timer on it.
 102 .I timeout
 103 specifies the lifetime of the key in seconds.
 104 .I error
 105 specifies the error to be returned when a search hits the key (this is
 106 typically
 107 .IR EKEYREJECTED ", " EKEYREVOKED " or " EKEYEXPIRED ")."
 108 Note that keyctl_reject() falls back to keyctl_negate() if the kernel does not
 109 support it.
 110 .P
 111 .BR keyctl_negate ()
 112 as
 113 .IR keyctl_reject ()
 114 with an error code of
 115 .IB ENOKEY .
 116 .P
 117 Only a key for which authority has been assumed may be instantiated or
 118 negatively instantiated, and once instantiated, the authorisation key will be
 119 revoked and the requesting process will be able to resume.
 120 .P
 121 The destination
 122 .IR keyring ,
 123 if given, is assumed to belong to the initial requester, and not the
 124 instantiating process.  Therefore, the special keyring IDs refer to the
 125 requesting process's keyrings, not the caller's, and the requester's UID,
 126 etc. will be used to access them.
 127 .P
 128 The destination keyring can be
 129 .B zero
 130 if no extra link is desired.
 131 .P
 132 The requester, not the caller, must have
 133 .B write
 134 permission on the destination for a link to be made there.
 135 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
 136 .SH RETURN VALUE
 137 On success
 138 .BR keyctl_instantiate ()
 139 returns
 140 .BR 0 .
 141 On error, the value
 142 .B -1
 143 will be returned and errno will have been set to an appropriate error.
 144 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
 145 .SH ERRORS
 146 .TP
 147 .B ENOKEY
 148 The key or keyring specified is invalid.
 149 .TP
 150 .B EKEYEXPIRED
 151 The keyring specified has expired.
 152 .TP
 153 .B EKEYREVOKED
 154 The key or keyring specified had been revoked, or the authorisation has been
 155 revoked.
 156 .TP
 157 .B EINVAL
 158 The payload data was invalid.
 159 .TP
 160 .B ENOMEM
 161 Insufficient memory to store the new payload or to expand the destination
 162 keyring.
 163 .TP
 164 .B EDQUOT
 165 The key quota for the key's user would be exceeded by increasing the size of
 166 the key to accommodate the new payload or the key quota for the keyring's user
 167 would be exceeded by expanding the destination keyring.
 168 .TP
 169 .B EACCES
 170 The key exists, but is not
 171 .B writable
 172 by the requester.
 173 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
 174 .SH LINKING
 175 This is a library function that can be found in
 176 .IR libkeyutils .
 177 When linking,
 178 .B -lkeyutils
 179 should be specified to the linker.
 180 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
 181 .SH SEE ALSO
 182 .BR keyctl (1),
 183 .br
 184 .BR add_key (2),
 185 .br
 186 .BR keyctl (2),
 187 .br
 188 .BR request_key (2),
 189 .br
 190 .BR keyctl (3),
 191 .br
 192 .BR request-key (8)