Lines Matching +full:key +full:-
2 Key Request Service
5 The key request service is part of the key retention service (refer to
12 struct key *request_key(const struct key_type *type,
18 struct key *request_key_tag(const struct key_type *type,
25 struct key *request_key_with_auxdata(const struct key_type *type,
34 struct key *request_key_rcu(const struct key_type *type,
45 The main difference between the access points is that the in-kernel interface
46 does not need to link the key to a keyring to prevent it from being immediately
47 destroyed. The kernel interface returns a pointer directly to the key, and
48 it's up to the caller to destroy the key.
50 The request_key_tag() call is like the in-kernel request_key(), except that it
56 NULL). This is only useful for those key types that define their own upcall
57 mechanism rather than using /sbin/request-key.
63 The userspace interface links the key to a keyring associated with the process
64 to prevent the key from going away, and returns the serial number of the key to
68 The following example assumes that the key types involved don't define their
70 forking and execution of /sbin/request-key.
82 a suitable key there. If there is, it returns the key. If there isn't,
86 3) request_key() sees that A doesn't have the desired key yet, so it creates
89 a) An uninstantiated key U of requested type and description.
91 b) An authorisation key V that refers to key U and notes that process A
92 is the context in which key U should be instantiated and secured, and
93 from which associated key requests may be satisfied.
95 4) request_key() then forks and executes /sbin/request-key with a new session
96 keyring that contains a link to auth key V.
98 5) /sbin/request-key assumes the authority associated with key U.
100 6) /sbin/request-key execs an appropriate program to perform the actual
103 7) The program may want to access another key from A's context (say a
104 Kerberos TGT key). It just requests the appropriate key, and the keyring
105 search notes that the session keyring has auth key V in its bottom level.
109 and come up with key W.
112 instantiate key U, using key W as a reference (perhaps it contacts a
113 Kerberos server using the TGT) and then instantiates key U.
115 9) Upon instantiating key U, auth key V is automatically revoked so that it
118 10) The program then exits 0 and request_key() deletes key V and returns key
121 This also extends further. If key W (step 7 above) didn't exist, key W would
122 be created uninstantiated, another auth key (X) would be created (as per step
123 3) and another copy of /sbin/request-key spawned (as per step 4); but the
124 context specified by auth key X will still be process A, as it was in auth key
128 /sbin/request-key at the appropriate places because (a) execve will discard two
135 Rather than instantiating a key, it is possible for the possessor of an
136 authorisation key to negatively instantiate a key that's under construction.
137 This is a short duration placeholder that causes any attempt at re-requesting
138 the key while it exists to fail with error ENOKEY if negated or the specified
141 This is provided to prevent excessive repeated spawning of /sbin/request-key
142 processes for a key that will never be obtainable.
144 Should the /sbin/request-key process exit anything other than 0 or die on a
145 signal, the key under construction will be automatically negatively
154 1) When the key management code searches for a key (keyring_search_rcu) it
158 2) It considers all the non-keyring keys within that keyring and, if any key
160 if the key is allowed to be found. If it is, that key is returned; if
164 3) It then considers all the keyring-type keys in the keyring it's currently
169 The process stops immediately a valid key is found with permission granted to
170 use it. Any error from a previous match attempt is discarded and the key is
173 When request_key() is invoked, if CONFIG_KEYS_REQUEST_CACHE=y, a per-task
174 one-key cache is first checked for a match.
186 authorisation key then:
194 The moment one succeeds, all pending errors are discarded and the found key is
195 returned. If CONFIG_KEYS_REQUEST_CACHE=y, then that key is placed in the
196 per-task cache, displacing the previous key. The cache is cleared on exit or