Mercurial > repos > rliterman > csp2

annotate CSP2/CSP2_env/env-d9b9114564458d9d-741b3de822f2aaca6c6caa4325c4afce/share/man/man3/keyctl_instantiate.3 @ 68:5028fdace37b

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