1KEYCTL_INSTANTIATE(3)     Linux Key Management Calls     KEYCTL_INSTANTIATE(3)
2
3
4

NAME

6       keyctl_assume_authority  -  Assume  the  authority to instantiate a key
7       keyctl_instantiate -  Instantiate  a  key  keyctl_negate  -  Negatively
8       instantiate a key
9

SYNOPSIS

11       #include <keyutils.h>
12
13       long keyctl_assume_authority(key_serial_t key);
14
15       long keyctl_instantiate(key_serial_t key, const char *payload,
16       size_t plen, key_serial_t keyring);
17
18       long keyctl_negate(key_serial_t key, unsigned timeout,
19       key_serial_t keyring);
20

DESCRIPTION

22       keyctl_assume_authority()  assumes the authority for the calling thread
23       to deal with and instantiate the specified uninstantiated key.
24
25       The calling thread must have the appopriate authorisation key  resident
26       in one of its keyrings for this to succeed, and that authority must not
27       have been revoked.
28
29       The authorising key is allocated by  request_key()  when  it  needs  to
30       invoke userspace to generate a key for the requesting process.  This is
31       then attached to one of the keyrings of the userspace process to  which
32       the task of instantiating the key is given:
33
34              requester -> request_key() -> instantiator
35
36       Calling  this function modifies the way request_key() works when called
37       thereafter by the calling (instantiator) thread; once the authority  is
38       assumed,  the  keyrings  of the initial process are added to the search
39       path, using the initial process's UID, GID, groups  and  security  con‐
40       text.
41
42       If  a thread has multiple instantiations to deal with, it may call this
43       function to change the authorisation key currently in effect.   Supply‐
44       ing a zero key de-assumes the currently assumed authority.
45
46       NOTE!   This  is  a per-thread setting and not a per-process setting so
47       that a multithreaded process can be used to instantiate several keys at
48       once.
49
50       keyctl_instantiate()  instantiates the payload of an uninstantiated key
51       from the data specified.  payload and plen specify the data for the new
52       payload.  payload may be NULL and plen may be zero if the key type per‐
53       mits that.  The key type may reject the data if it's in the wrong  for‐
54       mat or in some other way invalid.
55
56       keyctl_negate()  marks  a  key  as negatively instantiated and sets the
57       expiration timer on it.  timeout specifies the lifetime of the  key  in
58       seconds.
59
60       Only  a key for which authority has been assumed may be instantiated or
61       negatively instantiated, and once instantiated, the  authorisation  key
62       will be revoked and the requesting process will be able to resume.
63
64       The  destination keyring, if given, is assumed to belong to the initial
65       requester, and not the instantiating process.  Therefore,  the  special
66       keyring  IDs  refer to the requesting process's keyrings, not the call‐
67       er's, and the requester's UID, etc. will be used to access them.
68
69       The destination keyring can be zero if no extra link is desired.
70
71       The requester, not the caller, must have write permission on the desti‐
72       nation for a link to be made there.
73

RETURN VALUE

75       On success keyctl_instantiate() returns 0.  On error, the value -1 will
76       be returned and errno will have been set to an appropriate error.
77

ERRORS

79       ENOKEY The key or keyring specified is invalid.
80
81       EKEYEXPIRED
82              The keyring specified has expired.
83
84       EKEYREVOKED
85              The key or keyring specified had been revoked, or the authorisa‐
86              tion has been revoked.
87
88       EINVAL The payload data was invalid.
89
90       ENOMEM Insufficient  memory  to  store the new payload or to expand the
91              destination keyring.
92
93       EDQUOT The key quota for the key's user would be exceeded by increasing
94              the  size  of  the key to accommodate the new payload or the key
95              quota for the keyring's user would be exceeded by expanding  the
96              destination keyring.
97
98       EACCES The key exists, but is not writable by the requester.
99

LINKING

101       This  is  a  library  function  that can be found in libkeyutils.  When
102       linking, -lkeyutils should be specified to the linker.
103

SEE ALSO

105       keyctl(1),
106       add_key(2),
107       keyctl(2),
108       request_key(2),
109       keyctl_get_keyring_ID(3),
110       keyctl_join_session_keyring(3),
111       keyctl_update(3),
112       keyctl_revoke(3),
113       keyctl_chown(3),
114       keyctl_setperm(3),
115       keyctl_describe(3),
116       keyctl_clear(3),
117       keyctl_link(3),
118       keyctl_unlink(3),
119       keyctl_search(3),
120       keyctl_read(3),
121       keyctl_set_reqkey_keyring(3),
122       keyctl_set_timeout(3),
123       keyctl_describe_alloc(3),
124       keyctl_read_alloc(3),
125       request-key(8)
126
127
128
129Linux                             4 May 2006             KEYCTL_INSTANTIATE(3)