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