2
.\" Copyright (C) 2006 Red Hat, Inc. All Rights Reserved.
3
.\" Written by David Howells (dhowells@redhat.com)
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.
10
.TH KEYCTL_INSTANTIATE 3 "4 May 2006" Linux "Linux Key Management Calls"
11
.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
13
keyctl_assume_authority \- Assume the authority to instantiate a key
15
keyctl_instantiate \- Instantiate a key from flat data
17
keyctl_instantiate_iov \- Instantiate a key from segmented data
19
keyctl_reject \- Negatively instantiate a key specifying search error
21
keyctl_negate \- Negatively instantiate a key
22
.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
25
.B #include <keyutils.h>
27
.BI "long keyctl_assume_authority(key_serial_t " key ");"
29
.BI "long keyctl_instantiate(key_serial_t " key ", const void *" payload ,
30
.BI "size_t " plen ", key_serial_t " keyring ");"
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 ");"
36
.BI "long keyctl_negate(key_serial_t " key ", unsigned " timeout ,
37
.BI "key_serial_t " keyring ");"
39
.BI "long keyctl_reject(key_serial_t " key ", unsigned " timeout ,
40
.BI "unsigned " error ", key_serial_t " keyring ");"
41
.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
43
.BR keyctl_assume_authority ()
44
assumes the authority for the calling thread to deal with and instantiate the
45
specified uninstantiated
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
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:
57
requester -> request_key() -> instantiator
59
Calling this function modifies the way
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
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
70
de-assumes the currently assumed authority.
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.
76
.BR keyctl_instantiate ()
77
instantiates the payload of an uninstantiated key from the data specified.
81
specify the data for the new payload.
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.
88
.BR keyctl_instantiate_iov ()
89
is similar, but the data is passed in an array of iovec structs instead of in
92
points to the base of the array and
94
indicates how many elements there are.
98
may be zero to indicate that no data is being supplied.
101
marks a key as negatively instantiated and sets the expiration timer on it.
103
specifies the lifetime of the key in seconds.
105
specifies the error to be returned when a search hits the key (this is
107
.IR EKEYREJECTED ", " EKEYREVOKED " or " EKEYEXPIRED ")."
108
Note that keyctl_reject() falls back to keyctl_negate() if the kernel does not
114
with an error code of
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.
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.
128
The destination keyring can be
130
if no extra link is desired.
132
The requester, not the caller, must have
134
permission on the destination for a link to be made there.
135
.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
138
.BR keyctl_instantiate ()
143
will be returned and errno will have been set to an appropriate error.
144
.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
148
The key or keyring specified is invalid.
151
The keyring specified has expired.
154
The key or keyring specified had been revoked, or the authorisation has been
158
The payload data was invalid.
161
Insufficient memory to store the new payload or to expand the destination
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.
170
The key exists, but is not
173
.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
175
This is a library function that can be found in
179
should be specified to the linker.
180
.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""