Design a HAL to support over-the-air provisioning of certificates for asymmetric keys. The HAL must interact effectively with Keystore (and other daemons) and protect device privacy and security.
Note that this API was originally designed for KeyMint, with the intention that it should be usable for other HALs that require certificate provisioning. Throughout this document we'll refer to the Keystore and KeyMint (formerly called Keymaster) components, but only for concreteness and convenience; those labels could be replaced with the names of any system and secure area components, respectively, that need certificates provisioned.
To more securely and reliably get keys and certificates to Android devices, we need to create a system where no party outside of the device‘s secure components is responsible for managing private keys. The strategy we’ve chosen is to deliver certificates over the air, using an asymmetric key pair created on-device in the factory as a root of trust to create an authenticated, secure channel. In this document we refer to this device-unique asymmetric key pair as Device Key (DK), its public half DK_pub, its private half DK_priv and a Device Key Certificate containing DK_pub is denoted DKC.
In order for the provisioning service to use DK (or a key authenticated by DK), it must know whether a given DK_pub is known and trusted. To prove trust, we ask device OEMs to use one of two mechanisms:
(Preferred, recommended) The device OEM extracts DK_pub from each device it manufactures and uploads the public keys to a backend server.
The device OEM signs the DK_pub to produce DKC and stores it on the device. This has the advantage that they don't need to upload a DK_pub for every device immediately, but the disadvantage that they have to manage their private signing keys, which means they have to have HSMs, configure and secure them correctly, etc. Some backend providers may also require that the OEM passes a factory security audit, and additionally promises to upload the keys eventually as well.
Note that in the full elaboration of this plan, DK_pub is not the key used to establish a secure channel. Instead, DK_pub is just the first public key in a chain of public keys which ends with the KeyMint public key, KM_pub. All keys in the chain are device-unique and are joined in a certificate chain called the Boot Certificate Chain (BCC), because in phases 2 and 3 of the remote provisioning project it is a chain of certificates corresponding to boot phases. We speak of the BCC even for phase 1, though in phase 1 it contains only a single self-signed DKC. This is described in more depth in the Phases section below.
The BCC is authenticated by DK_pub. To authenticate DK_pub, we may have additional DKCs, from the SoC vendor, the device OEM, or both. Those are not part of the BCC but included as optional fields in the certificate request structure.
The format of the the DK and BCC is specified within [Open Profile for DICE] (https://pigweed.googlesource.com/open-dice/+/HEAD/docs/specification.md). To map phrases within this document to their equivalent terminology in the DICE specification, read the terms as follows: the DK corresponds to the UDS-derived key pair, DKC corresponds to the UDS certificate, and the BCC entries between DK_pub and KM_pub correspond to a chain of CDI certificates.
Note: In addition to allowing 32 byte hash values for fields in the BCC payload, this spec additionally constrains some of the choices allowed in open-DICE. Specifically, these include which entries are required and which are optional in the BCC payload, and which algorithms are acceptable for use.
RKP will be deployed in three phases, in terms of managing the root of trust binding between the device and the backend. To briefly describe them:
Because DK and the DKCs are unique, immutable, unspoofable hardware-bound identifiers for the device, we must limit access to them to the absolute minimum possible. We do this in two ways:
Although the details of the mechanisms for preventing the entity from abusing the BCC are, as stated, beyond the scope of this document, there is a subtle design decision here made specifically to enable abuse prevention. Specifically the CertificateRequest message sent to the server is (in CDDL):
cddl
CertificateRequest = [
DeviceInfo,
challenge : bstr,
ProtectedData,
MacedKeysToSign
]
The public keys to be attested by the server are in MacedKeysToSign, which is a COSE_Mac0 structure, MACed with a key that is found in ProtectedData. The MAC key is signed by DK_pub.
This structure allows the backend component that has access to EEK_priv to decrypt ProtectedData, validate that the request is from an authorized device, check that the request is fresh and verify and extract the MAC key. That backend component never sees any data related to the keys to be signed, but can provide the MAC key to another backend component that can verify MacedKeysToSign and proceed to generate the certificates.
In this way, we can partition the provisioning server into one component that knows the device identity, as represented by DK_pub, but never sees the keys to be certified or certificates generated, and another component that sees the keys to be certified and certificates generated but does not know the device identity.
For simplicity of generation and parsing, compactness of wire representation, and flexibility and standardization, we've settled on using the CBOR Object Signing and Encryption (COSE) standard, defined in RFC 8152. COSE provides compact and reasonably simple, yet easily-extensible, wire formats for:
COSE enables easy layering of these message formats, such as using a COSE_Sign structure to contain a COSE_Key with a public key in it. We call this a “certificate”.
Due to the complexity of the standard, we‘ll spell out the COSE structures completely in this document and in the HAL and other documentation, so that although implementors will need to understand CBOR and the CBOR Data Definition Language (CDDL, defined in RFC 8610), they shouldn’t need to understand COSE.
Note, however, that the certificate chains returned from the provisioning server are standard X.509 certificates.
This document uses:
We believe that Curve25519 offers the best tradeoff in terms of security, efficiency and global trustworthiness, and that it is now sufficiently widely-used and widely-implemented to make it a practical choice.
However, since hardware such as Secure Elements (SE) do not currently offer support for curve 25519, we are allowing implementations to instead make use of ECDSA and ECDH.
The CDDL in the rest of the document will use the ‘/’ operator to show areas where either curve 25519, P-256 or P-384 may be used. Since there is no easy way to bind choices across different CDDL groups, it is important that the implementor stays consistent in which type is chosen. E.g. taking ES256 as the choice for algorithm implies the implementor should also choose the P256 public key group further down in the COSE structure.
It's critical that the remote provisioning implementation be testable, to minimize the probability that broken devices are sold to end users. To support testing, the remote provisioning HAL methods take a testMode argument. Keys created in test mode are tagged to indicate this. The provisioning server will check for the test mode tag and issue test certificates that do not chain back to a trusted public key. In test mode, any EEK will be accepted, enabling testing tools to use EEKs for which they have the private key so they can validate the content of certificate requests. The BCC included in the CertificateRequest must contain freshly-generated keys, not the real BCC keys.
Keystore (or similar) will need to be able to handle both testMode keys and production keys and keep them distinct, generating test certificate requests when asked with a test EEK and production certificate requests when asked with a production EEK. Likewise, the interface used to instruct Keystore to create keys will need to be able to specify whether test or production keys are desired.
TODO(jbires): Replace this with a .png containing a sequence diagram. The provisioning flow looks something like this:
Provisioner -> Keystore: Prepare N keys Keystore -> KeyMint: generateKeyPair KeyMint -> KeyMint: Generate key pair KeyMint --> Keystore: key_blob,pubkey Keystore -> Keystore: Store key_blob,pubkey Provisioner -> Server: Get TEEK Server --> Provisioner: TEEK Provisioner -> Keystore: genCertReq(N, TEEK) Keystore -> KeyMint: genCertReq(pubkeys, TEEK) KeyMint -> KeyMint: Sign pubkeys & encrypt BCC KeyMint --> Keystore: signature, encrypted BCC Keystore -> Keystore: Construct cert_request Keystore --> Provisioner: cert_request Provisioner --> Server: cert_request Server -> Server: Validate cert_request Server -> Server: Generate certificates Server --> Provisioner: certificates Provisioner -> Keystore: certificates Keystore -> Keystore: Store certificates
The actors in the above diagram are:
BCCThe Boot Certificate Chain (BCC) is the chain of certificates that contains DK_pub as well as other often device-unique certificates. The BCC is represented as a COSE_Key containing DK_pub followed by an array of COSE_Sign1 “certificates” containing public keys and optional additional information, ordered from root to leaf, with each certificate signing the next. The first certificate in the array is signed by DK_pub, the last certificate has the KeyMint (or whatever) signing key's public key, KM_pub. In phase 1 there is only one entry; DK_pub and KM_pub are the same key and the certificate is self-signed.
Each COSE_Sign1 certificate is a CBOR Web Token (CWT) as described in RFC 8392 with additional fields as described in the Open Profile for DICE. Of these additional fields, only the subjectPublicKey and keyUsage fields are expected to be present for the KM_pub entry (that is, the last entry) in a BCC, but all fields required by the Open Profile for DICE are expected for other entries (each of which corresponds to a particular firmware component or boot stage). The CWT fields iss and sub identify the issuer and subject of the certificate and are consistent along the BCC entries; the issuer of a given entry matches the subject of the previous entry.
The BCC is designed to be constructed using the Open Profile for DICE. In this case the DK key pair is derived from the UDS as described by that profile and all BCC entries before the leaf are CBOR CDI certificates chained from DK_pub. The KM key pair is not part of the derived DICE chain. It is generated (not derived) by the KeyMint module, certified by the last key in the DICE chain, and added as the leaf BCC entry. The key usage field in this leaf certificate must indicate the key is not used to sign certificates. If a UDS certificate is available on the device it should appear in the certificate request as the leaf of a DKCertChain in AdditionalDKSignatures (see CertificateRequest).
The Open Profile for DICE specifies four possible modes with the most important mode being normal. A certificate must only set the mode to normal when all of the following conditions are met when loading and verifying the software component that is being described by the certificate:
If any of these conditions are not met then it is recommended to explicitly acknowledge this fact by using the debug mode. The mode should never be not configured.
The Open Profile for DICE allows for an arbitrary configuration descriptor. For BCC entries, this configuration descriptor is a CBOR map with the following optional fields. If no fields are relevant, an empty map should be encoded. Additional implementation-specific fields may be added using key values not in the range [-70000, -70999] (these are reserved for future additions here).
| Name | Key | Value type | Meaning | | ----------------- | ------ | ---------- | ----------------------------------| | Component name | -70002 | tstr | Name of firmware component / boot | : : : : stage : | Component version | -70003 | int / tstr | Version of firmware component / | : : : : boot stage : | Resettable | -70004 | null | If present, key changes on factory| : : : : reset : | Security version | -70005 | uint | Machine-comparable, monotonically | : : : : increasing version of the firmware: : : : : component / boot stage where a : : : : : greater value indicates a newer : : : : : version :
Please see ProtectedData.aidl for a full CDDL definition of the BCC.
CertificateRequestThe full CBOR message that will be sent to the server to request certificates is:
CertificateRequest = [ DeviceInfo, challenge : bstr, // Provided by the server ProtectedData, // See ProtectedData.aidl MacedKeysToSign // See IRemotelyProvisionedComponent.aidl ] DeviceInfo = [ VerifiedDeviceInfo, // See DeviceInfo.aidl UnverifiedDeviceInfo ] // Unverified info is anything provided by the HLOS. Subject to change out of // step with the HAL. UnverifiedDeviceInfo = { ? "fingerprint" : tstr, }
It will be the responsibility of Keystore and the Provisioner to construct the CertificateRequest. The HAL provides a method to generate the elements that need to be constructed on the secure side, which are the tag field of MacedKeysToSign, VerifiedDeviceInfo, and the ciphertext field of ProtectedData.
The remote provisioning HAL provides a simple interface that can be implemented by multiple secure components that require remote provisioning. It would be slightly simpler to extend the KeyMint API, but that approach would only serve the needs of KeyMint, this is more general.
NOTE the data structures defined in this HAL may look a little bloated and complex. This is because the COSE data structures are fully spelled-out; we could make it much more compact by not re-specifying the standardized elements and instead just referencing the standard, but it seems better to fully specify them. If the apparent complexity seems daunting, consider what the same would look like if traditional ASN.1 DER-based structures from X.509 and related standards were used and also fully elaborated.
Please see the related HAL documentation directly in the source code at the following links: