README.md
1# Security-Related HALs
2
3The `security/` subdirectory holds various security-related HALs. (The final two sections of this
4document also describe security-related HALs that are in other places under `hardware/interfaces/`.)
5
6The most significant HAL is KeyMint (**`IKeyMintDevice`** in the
7`hardware/interfaces/security/keymint/` directory), which allows access to cryptographic
8functionality where the key material is restricted to a secure environment. This functionality is
9used by Android system services, and is also made available to apps via Android Keystore.
10
11A KeyMint implementation (or an implementation of its predecessor, Keymaster) that runs in an
12isolated execution environment (e.g. ARM TrustZone) is required for most Android devices; see [CDD
139.11](https://source.android.com/docs/compatibility/13/android-13-cdd#911_keys_and_credentials).
14
15A device may optionally also support a second KeyMint instance, running in a dedicated secure
16processor; this is known as StrongBox ([CDD
179.11.2](https://source.android.com/docs/compatibility/13/android-13-cdd#9112_strongbox)).
18
19Two specific features of KeyMint are worth highlighting, as they have an impact on the other
20security-related HALs:
21
22- KeyMint supports keys that can only be used when the operation is authenticated by the user,
23 either by their lock screen knowledge factor (LSKF, e.g. PIN or pattern) or by a strong biometric
24 (e.g. fingerprint).
25- KeyMint supports *attestation* of public keys: when an asymmetric keypair is created, the secure
26 environment produces a chain of signed certificates:
27 - starting from a trusted root certificate
28 - terminating in a leaf certificate that holds the public key; this leaf certificate may also
29 describe the state of the device and the policies attached to the key.
30
31## Authentication Verification
32
33User authentication must also take place in a secure environment (see the final section below), but
34the results of that authentication are communicated to KeyMint via Android. As such, the
35authentication result (a *hardware auth token*) is signed with a per-boot shared HMAC key known only
36to the secure components, so that it's authenticity can be verified.
37
38If an authenticator, for example GateKeeper (described by the **`IGatekeeper`** HAL in
39`hardware/interfaces/gatekeeper/`), is co-located in the same secure environment as KeyMint, it can
40use a local, vendor-specific, method to communicate the shared HMAC key.
41
42However, if the authenticator is in a different environment than the KeyMint instance then a local
43communication mechanism may not be possible. For example, a StrongBox KeyMint instance running in a
44separate secure processor may not have a communication channel with a TEE on the main processor.
45
46To allow for this, the **`ISharedSecret`** HAL (in `hardware/interfaces/security/sharedsecret`)
47describes an N-party shared key agreement protocol for per-boot derivation of the shared HMAC key,
48based on a pre-provisioned shared secret. This HAL can be implemented by any security component
49– whether KeyMint instance or authenticator – that needs access to the shared HMAC key.
50
51User authentication operations are also timestamped, but a StrongBox KeyMint instance may not have
52access to a secure time source that is aligned with the authenticator's time source.
53
54To allow for this, the **`ISecureClock`** HAL (in `hardware/interfaces/secureclock`) describes a
55challenge-based timestamp authentication protocol. This HAL is optional; it need only be
56implemented if there is a KeyMint instance without a secure source of time.
57
58## Attestation Key Provisioning
59
60As noted above, key generation may also generate an attestation certificate chain, which requires
61that the secure environment have access to a signing key which in turn chains back to the Google
62root.
63
64Historically these signing keys were created by Google and provided to vendors for installation in
65batches of devices (to prevent their use as unique device identifiers). However, this mechanism had
66significant disadvantages, as it required secure handling of key material and only allowed for
67coarse-grained revocation.
68
69The remote key provisioning HAL (**`IRemotelyProvisionedComponent`** in
70`hardware/interfaces/security/rkp/`) provides a mechanism whereby signing certificates for
71attestation can be retrieved at runtime from Google servers based on pre-registered device identity
72information. This mechanism is used to provision certificates for KeyMint's signing keys, but is
73not restricted to that purpose; it can also be used in other scenarios where keys need to be
74provisioned (for example, for [Widevine](https://developers.google.com/widevine/drm/overview)).
75
76## Keymaster
77
78The Keymaster HAL (**`IKeymasterDevice`** in `hardware/interfaces/keymaster/`) is the historical
79ancestor of many of the HALs here (and may still be present on older devices). Its functionality is
80effectively the union of the following current HALs:
81
82- **`IKeyMintDevice`**
83- **`ISharedSecret`**
84- **`ISecureClock`**
85
86## Related Authentication HALs
87
88Authentication of users needs to happen in a secure environment, using vendor-specific
89functionality, and so involves the use of one of the following HALs (all of which are outside the
90`security/` subdirectory).
91
92- The **`IGatekeeper`** HAL (in `hardware/interfaces/gatekeeper/`) provides user authentication
93 functionality based on the user's lock-screen knowledge factor (LSKF), including throttling
94 behaviour to prevent attacks. Authentication tokens produced by this HAL are consumed by KeyMint,
95 validated using the shared HMAC key described above.
96 - The optional **`IWeaver`** HAL (in `hardware/interfaces/weaver`) improves the security of LSKF
97 authentication by converting the user's LSKF into a *synthetic password* via hashing and
98 stretching. This is required to be implemented on a separate secure element, which prevents
99 offline attacks on Gatekeeper storage. Note that Weaver does not directly interact with KeyMint;
100 the synthetic password is fed into Gatekeeper in place of the plain user password, and then
101 Gatekeeper interacts with KeyMint as normal.
102- The **`IFingerprint`** and **`IFace`** HAL definitions (under `hardware/interfaces/biometrics/`)
103 allow access to biometric authentication functionality that is implemented in a secure
104 environment. Authentication tokens produced by these HALs are consumed by KeyMint, validated
105 using the shared HMAC key described above.
106- The optional **`IConfirmationUI`** HAL (in `hardware/interfaces/confirmationui`) supports
107 functionality where the user confirms that they have seen a specific message in a secure manner.
108 Confirmation tokens produced by this HAL are consumed by KeyMint, validated using the shared HMAC
109 key described above.
110