Name |
Date |
Size |
#Lines |
LOC |
||
---|---|---|---|---|---|---|
.. | - | - | ||||
aidl/ | 06-Sep-2024 | - | 3,145 | 1,445 | ||
CHANGELOG.md | D | 06-Sep-2024 | 2.5 KiB | 49 | 44 | |
OWNERS | D | 06-Sep-2024 | 79 | 6 | 4 | |
README.md | D | 06-Sep-2024 | 11 KiB | 220 | 175 | |
TEST_MAPPING | D | 06-Sep-2024 | 98 | 8 | 7 |
README.md
1# Remote Provisioning HAL 2 3## Objective 4 5Design a HAL to support over-the-air provisioning of certificates for asymmetric 6keys. The HAL must interact effectively with Keystore (and other services) and 7protect device privacy and security. 8 9Note that this API was originally designed for KeyMint, with the intention that 10it should be usable for other HALs that require certificate provisioning. 11Throughout this document we'll refer to the Keystore and KeyMint (formerly 12called Keymaster) components, but only for concreteness and convenience; those 13labels could be replaced with the names of any system and secure area 14components, respectively, that need certificates provisioned. 15 16## Key design decisions 17 18### General approach 19 20To more securely and reliably get keys and certificates to Android devices, we 21need to create a system where no party outside of the device's secure components 22is responsible for managing private keys. The strategy we've chosen is to 23deliver certificates over the air, using an asymmetric key pair derived from a 24unique device secret (UDS) as a root of trust for authenticated requests from 25the secure components. We refer to the public half of this asymmetric key pair 26as UDS\_pub. 27 28In order for the provisioning service to trust UDS\_pub we ask device OEMs to 29use one of two mechanisms: 30 311. (Preferred, recommended) The device OEM extracts the UDS\_pub from each 32 device they manufacture and uploads the public keys to a backend server. 33 341. The device OEM signs the UDS\_pub and stores the certificates on the device 35 rather than uploading a UDS\_pub for every device immediately. However, 36 there are many disadvantages and costs associated with this option as the 37 OEM will need to pass a security audit of their factory's physical security, 38 CA and HSM configuration, and incident response processes before the OEM's 39 public key is registered with the provisioning server. 40 41Note that in the full elaboration of this plan, UDS\_pub is not the key used to 42sign certificate requests. Instead, UDS\_pub is just the first public key in a 43chain of public keys that end the KeyMint public key. All keys in the chain are 44transitively derived from the UDS and joined in a certificate chain following 45the specification of the [Android Profile for DICE](android-profile-for-dice). 46 47[android-profile-for-dice]: https://pigweed.googlesource.com/open-dice/+/refs/heads/main/docs/android.md 48 49### Phases 50 51RKP will be deployed with phased management of the root of trust 52binding between the device and the backend. To briefly describe them: 53 54* Degenerate DICE (Phase 1): A TEE root of trust key pair is used to sign 55 certificate requests; a single self-signed certificate signifies this phase. 56* DICE (Phase 2): A hardware root of trust key pair is only accessible to ROM 57 or ROM extension code; the boot process follows the [Android Profile for 58 DICE](android-profile-for-dice). 59* SoC vendor certified DICE (Phase 3): This is identical to Phase 2, except the 60 SoC vendor also does the UDS\_pub extraction or certification in their 61 facilities, along with the OEM doing it in the factory. This tightens up the 62 "supply chain" and aims to make key upload management more secure. 63 64### Privacy considerations 65 66Because the UDS, CDIs and derived values are unique, immutable, unspoofable 67hardware-bound identifiers for the device, we must limit access to them. We 68require that the values are never exposed in public APIs and are only available 69to the minimum set of system components that require access to them to function 70correctly. 71 72### Key and cryptographic message formatting 73 74For simplicity of generation and parsing, compactness of wire representation, 75and flexibility and standardization, we've settled on using the CBOR Object 76Signing and Encryption (COSE) standard, defined in [RFC 778152](https://tools.ietf.org/html/rfc8152). COSE provides compact and reasonably 78simple, yet easily-extensible, wire formats for: 79 80* Keys, 81* MACed messages, 82* Signed messages, and 83* Encrypted messages 84 85COSE enables easy layering of these message formats, such as using a COSE\_Sign 86structure to contain a COSE\_Key with a public key in it. We call this a 87"certificate". 88 89Due to the complexity of the standard, we'll spell out the COSE structures 90completely in this document and in the HAL and other documentation, so that 91although implementors will need to understand CBOR and the CBOR Data Definition 92Language ([CDDL, defined in RFC 8610](https://tools.ietf.org/html/rfc8610)), 93they shouldn't need to understand COSE. 94 95Note, however, that the certificate chains returned from the provisioning server 96are standard X.509 certificates. 97 98### Algorithm choices 99 100This document uses: 101 102* ECDSA P-256 for attestation signing keys; 103* Remote provisioning protocol signing keys: 104 * Ed25519 / P-256 / P-384 105* ECDH keys: 106 * X25519 / P-256 107* AES-GCM for all encryption; 108* SHA-256 / SHA-384 / SHA-512 for message digesting; 109* HMAC with a supported message digest for all MACing; and 110* HKDF with a supported message digest for all key derivation. 111 112We believe that Curve25519 offers the best tradeoff in terms of security, 113efficiency and global trustworthiness, and that it is now sufficiently 114widely-used and widely-implemented to make it a practical choice. 115 116However, since hardware such as Secure Elements (SE) do not currently offer 117support for curve 25519, we are allowing implementations to instead make use of 118ECDSA and ECDH. 119 120The CDDL in the rest of the document will use the '/' operator to show areas 121where either curve 25519, P-256 or P-384 may be used. Since there is no easy way 122to bind choices across different CDDL groups, it is important that the 123implementor stays consistent in which type is chosen. E.g. taking ES256 as the 124choice for algorithm implies the implementor should also choose the P256 public 125key group further down in the COSE structure. 126 127## Design 128 129### Certificate provisioning flow 130 131TODO(jbires): Replace this with a `.png` containing a sequence diagram. The 132provisioning flow looks something like this: 133 134rkpd -> KeyMint: generateKeyPair 135KeyMint -> KeyMint: Generate key pair 136KeyMint --> rkpd: key\_blob,pubkey 137rkpd -> rkpd: Store key\_blob,pubkey 138rkpd -> Server: Get challenge 139Server --> rkpd: challenge 140rkpd -> KeyMint: genCertReq(pubkeys, challenge) 141KeyMint -> KeyMint: Sign CSR 142KeyMint --> rkpd: signed CSR 143rkpd --> Server: CSR 144Server -> Server: Validate CSR 145Server -> Server: Generate certificates 146Server --> rkpd: certificates 147rkpd -> rkpd: Store certificates 148 149The actors in the above diagram are: 150 151* **Server** is the backend certificate provisioning server. It has access to 152 the uploaded device public keys and is responsible for providing encryption 153 keys, decrypting and validating requests, and generating certificates in 154 response to requests. 155* **rkpd** is, optionally, a modular system component that is responsible for 156 communicating with the server and all of the system components that require 157 key certificates from the server. It also implements the policy that defines 158 how many key pairs each client should keep in their pool. When a system 159 ships with rkpd as a modular component, it may be updated independently from 160 the rest of the system. 161* **Keystore** is the [Android keystore 162 daemon](https://developer.android.com/training/articles/keystore) (or, more 163 generally, whatever system component manages communications with a 164 particular secure aread component). 165* **KeyMint** is the secure area component that manages cryptographic keys and 166 performs attestations (or perhaps some other secure area component). 167 168### HAL 169 170The remote provisioning HAL provides a simple interface that can be implemented 171by multiple secure components that require remote provisioning. It would be 172slightly simpler to extend the KeyMint API, but that approach would only serve 173the needs of KeyMint, this is more general. 174 175NOTE the data structures defined in this HAL may look a little bloated and 176complex. This is because the COSE data structures are fully spelled-out; we 177could make it much more compact by not re-specifying the standardized elements 178and instead just referencing the standard, but it seems better to fully specify 179them. If the apparent complexity seems daunting, consider what the same would 180look like if traditional ASN.1 DER-based structures from X.509 and related 181standards were used and also fully elaborated. 182 183Please see the related HAL documentation directly in the source code at the 184following links: 185 186* [IRemotelyProvisionedComponent 187 HAL](https://cs.android.com/android/platform/superproject/+/master:hardware/interfaces/security/rkp/aidl/android/hardware/security/keymint/IRemotelyProvisionedComponent.aidl) 188* [ProtectedData](https://cs.android.com/android/platform/superproject/+/master:hardware/interfaces/security/rkp/aidl/android/hardware/security/keymint/ProtectedData.aidl) 189* [MacedPublicKey](https://cs.android.com/android/platform/superproject/+/master:hardware/interfaces/security/rkp/aidl/android/hardware/security/keymint/MacedPublicKey.aidl) 190* [RpcHardwareInfo](https://cs.android.com/android/platform/superproject/+/master:hardware/interfaces/security/rkp/aidl/android/hardware/security/keymint/RpcHardwareInfo.aidl) 191* [DeviceInfo](https://cs.android.com/android/platform/superproject/+/master:hardware/interfaces/security/rkp/aidl/android/hardware/security/keymint/DeviceInfo.aidl) 192 193### Support for Android Virtualization Framework 194 195The Android Virtualization Framwork (AVF) relies on RKP to provision keys for VMs. A 196privileged vm, the RKP VM, is reponsible for generating and managing the keys for client 197VMs that run virtualized workloads. See the following for more background information on the 198RKP VM: 199* [rkp-vm](https://android.googlesource.com/platform/packages/modules/Virtualization/+/main/service_vm/README.md#rkp-vm-remote-key-provisioning-virtual-machine) 200* [rkp-service](https://source.android.com/docs/core/ota/modular-system/remote-key-provisioning#stack-architecture) 201 202It is important to distinquish the RKP VM from other components, such as KeyMint. An 203[RKP VM marker](https://pigweed.googlesource.com/open-dice/+/HEAD/docs/android.md#configuration-descriptor) 204(key `-70006`) is used for this purpose. The existence or absence of this marker is used to 205identify the type of component decribed by a given DICE chain. 206 207The following describes which certificate types may be request based on the RKP VM marker: 2081. "rkp-vm": If a DICE chain has zero or more certificates without the RKP VM 209 marker followed by one or more certificates with the marker, then that chain 210 describes an RKP VM. If there are further certificates without the RKP VM 211 marker, then the chain does not describe an RKP VM. 212 213 Implementations must include the first RKP VM marker as early as possible 214 after the point of divergence between TEE and non-TEE components in the DICE 215 chain, prior to loading the Android Bootloader (ABL). 2162. "widevine" or "keymint": If there are no certificates with the RKP VM 217 marker then it describes a TEE component. 2183. None: Any component described by a DICE chain that does not match the above 219 two categories. 220