security/keys/request-key.rst

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,
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.
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.
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
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
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