Add auth token parsing to IKeymasterDevice.hal
Auth tokens have an unfortunate dual character. To most of the system
they are opaque blobs that are intended only to be obtained from one
HAL (e.g. gatekeeper or fingerprint) and passed to another
HAL (keymaster), but keystore actually needs to extract some bits of
information from them in order to determine which of the available blobs
should be provided for a given keymaster key operation.
This CL adds a method that resolves this dual nature by moving the
responsibility of parsing blobs to the HAL so that no component of the
framework has to make any assumptions about their content and all can
treat them as fully opaque. This still means that the various HAL
implementers have to agree on content, but they also have to agree on an
HMAC key which much be securely distributed to all at every boot, so
asking them to agree on an auth token format is perfectly
acceptable. But now the Android system doesn't have to care about the
format.
Bug: 32962548
Test: CTS tests pass, plus manual testing.
Change-Id: I78aa6e4ea9c5d8f34906b0969909387e2c5894e6
diff --git a/keymaster/3.0/IKeymasterDevice.hal b/keymaster/3.0/IKeymasterDevice.hal
index 2664765..0c59e6c 100644
--- a/keymaster/3.0/IKeymasterDevice.hal
+++ b/keymaster/3.0/IKeymasterDevice.hal
@@ -59,6 +59,22 @@
string keymasterAuthorName);
/**
+ * Parses a hardware authentication token blob to extract the details needed to determine if the
+ * token is applicable to a given keymaster operation. This method is intended to be
+ * implemented by the HAL, without requiring a call into the trusted hardware. It is not
+ * necessary for this method to verify that the values in the blob are correct.
+ *
+ * @param token The token blob provided by the authentication app.
+ *
+ * @return error ErrorCode::OK or, if the blob is invalid, ErrorCode::INVALD_ARGUMENT if the
+ * blob is the wrong size, the wrong version, or incorrectly structured.
+ *
+ * @return tokenInfo Information extracted from the auth token.
+ */
+ parseHardwareAuthToken(vec<uint8_t> token)
+ generates(ErrorCode error, HardwareAuthTokenInfo tokenInfo);
+
+ /**
* Adds entropy to the RNG used by keymaster. Entropy added through this method is guaranteed
* not to be the only source of entropy used, and the mixing function is required to be secure,
* in the sense that if the RNG is seeded (from any source) with any data the attacker cannot