1=================== 2Key Request Service 3=================== 4 5The key request service is part of the key retention service (refer to 6Documentation/security/keys/core.rst). This document explains more fully how 7the requesting algorithm works. 8 9The process starts by either the kernel requesting a service by calling 10``request_key*()``:: 11 12 struct key *request_key(const struct key_type *type, 13 const char *description, 14 const char *callout_info, 15 struct key_acl *acl); 16 17or:: 18 19 struct key *request_key_tag(const struct key_type *type, 20 const char *description, 21 const struct key_tag *domain_tag, 22 const char *callout_info, 23 struct key_acl *acl); 24 25or:: 26 27 struct key *request_key_with_auxdata(const struct key_type *type, 28 const char *description, 29 const struct key_tag *domain_tag, 30 const char *callout_info, 31 size_t callout_len, 32 void *aux, 33 struct key_acl *acl); 34 35or:: 36 37 struct key *request_key_rcu(const struct key_type *type, 38 const char *description, 39 const struct key_tag *domain_tag); 40 41Or by userspace invoking the request_key system call:: 42 43 key_serial_t request_key(const char *type, 44 const char *description, 45 const char *callout_info, 46 key_serial_t dest_keyring); 47 48The main difference between the access points is that the in-kernel interface 49does not need to link the key to a keyring to prevent it from being immediately 50destroyed. The kernel interface returns a pointer directly to the key, and 51it's up to the caller to destroy the key. 52 53The request_key_tag() call is like the in-kernel request_key(), except that it 54also takes a domain tag that allows keys to be separated by namespace and 55killed off as a group. 56 57The request_key_with_auxdata() calls is like the request_key_tag() call, except 58that they permit auxiliary data to be passed to the upcaller (the default is 59NULL). This is only useful for those key types that define their own upcall 60mechanism rather than using /sbin/request-key. 61 62The request_key_rcu() call is like the request_key_tag() call, except that it 63doesn't check for keys that are under construction and doesn't attempt to 64construct missing keys. 65 66The userspace interface links the key to a keyring associated with the process 67to prevent the key from going away, and returns the serial number of the key to 68the caller. 69 70 71The following example assumes that the key types involved don't define their 72own upcall mechanisms. If they do, then those should be substituted for the 73forking and execution of /sbin/request-key. 74 75 76The Process 77=========== 78 79A request proceeds in the following manner: 80 81 1) Process A calls request_key() [the userspace syscall calls the kernel 82 interface]. 83 84 2) request_key() searches the process's subscribed keyrings to see if there's 85 a suitable key there. If there is, it returns the key. If there isn't, 86 and callout_info is not set, an error is returned. Otherwise the process 87 proceeds to the next step. 88 89 3) request_key() sees that A doesn't have the desired key yet, so it creates 90 two things: 91 92 a) An uninstantiated key U of requested type and description. 93 94 b) An authorisation key V that refers to key U and notes that process A 95 is the context in which key U should be instantiated and secured, and 96 from which associated key requests may be satisfied. 97 98 4) request_key() then forks and executes /sbin/request-key with a new session 99 keyring that contains a link to auth key V. 100 101 5) /sbin/request-key assumes the authority associated with key U. 102 103 6) /sbin/request-key execs an appropriate program to perform the actual 104 instantiation. 105 106 7) The program may want to access another key from A's context (say a 107 Kerberos TGT key). It just requests the appropriate key, and the keyring 108 search notes that the session keyring has auth key V in its bottom level. 109 110 This will permit it to then search the keyrings of process A with the 111 UID, GID, groups and security info of process A as if it was process A, 112 and come up with key W. 113 114 8) The program then does what it must to get the data with which to 115 instantiate key U, using key W as a reference (perhaps it contacts a 116 Kerberos server using the TGT) and then instantiates key U. 117 118 9) Upon instantiating key U, auth key V is automatically revoked so that it 119 may not be used again. 120 121 10) The program then exits 0 and request_key() deletes key V and returns key 122 U to the caller. 123 124This also extends further. If key W (step 7 above) didn't exist, key W would 125be created uninstantiated, another auth key (X) would be created (as per step 1263) and another copy of /sbin/request-key spawned (as per step 4); but the 127context specified by auth key X will still be process A, as it was in auth key 128V. 129 130This is because process A's keyrings can't simply be attached to 131/sbin/request-key at the appropriate places because (a) execve will discard two 132of them, and (b) it requires the same UID/GID/Groups all the way through. 133 134 135Negative Instantiation And Rejection 136==================================== 137 138Rather than instantiating a key, it is possible for the possessor of an 139authorisation key to negatively instantiate a key that's under construction. 140This is a short duration placeholder that causes any attempt at re-requesting 141the key while it exists to fail with error ENOKEY if negated or the specified 142error if rejected. 143 144This is provided to prevent excessive repeated spawning of /sbin/request-key 145processes for a key that will never be obtainable. 146 147Should the /sbin/request-key process exit anything other than 0 or die on a 148signal, the key under construction will be automatically negatively 149instantiated for a short amount of time. 150 151 152The Search Algorithm 153==================== 154 155A search of any particular keyring proceeds in the following fashion: 156 157 1) When the key management code searches for a key (keyring_search_rcu) it 158 firstly calls key_permission(SEARCH) on the keyring it's starting with, 159 if this denies permission, it doesn't search further. 160 161 2) It considers all the non-keyring keys within that keyring and, if any key 162 matches the criteria specified, calls key_permission(SEARCH) on it to see 163 if the key is allowed to be found. If it is, that key is returned; if 164 not, the search continues, and the error code is retained if of higher 165 priority than the one currently set. 166 167 3) It then considers all the keyring-type keys in the keyring it's currently 168 searching. It calls key_permission(SEARCH) on each keyring, and if this 169 grants permission, it recurses, executing steps (2) and (3) on that 170 keyring. 171 172The process stops immediately a valid key is found with permission granted to 173use it. Any error from a previous match attempt is discarded and the key is 174returned. 175 176When request_key() is invoked, if CONFIG_KEYS_REQUEST_CACHE=y, a per-task 177one-key cache is first checked for a match. 178 179When search_process_keyrings() is invoked, it performs the following searches 180until one succeeds: 181 182 1) If extant, the process's thread keyring is searched. 183 184 2) If extant, the process's process keyring is searched. 185 186 3) The process's session keyring is searched. 187 188 4) If the process has assumed the authority associated with a request_key() 189 authorisation key then: 190 191 a) If extant, the calling process's thread keyring is searched. 192 193 b) If extant, the calling process's process keyring is searched. 194 195 c) The calling process's session keyring is searched. 196 197The moment one succeeds, all pending errors are discarded and the found key is 198returned. If CONFIG_KEYS_REQUEST_CACHE=y, then that key is placed in the 199per-task cache, displacing the previous key. The cache is cleared on exit or 200just prior to resumption of userspace. 201 202Only if all these fail does the whole thing fail with the highest priority 203error. Note that several errors may have come from LSM. 204 205The error priority is:: 206 207 EKEYREVOKED > EKEYEXPIRED > ENOKEY 208 209EACCES/EPERM are only returned on a direct search of a specific keyring where 210the basal keyring does not grant Search permission. 211