Merge "Rewrite RKP readme in terms of DICE" am: 139b663e am: e8821b0f am:...

## Objective

## Objective

Design a HAL to support over-the-air provisioning of certificates for asymmetric

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

keys. The HAL must interact effectively with Keystore (and other services) and

protect device privacy and security.

protect device privacy and security.

Note that this API was originally designed for KeyMint, with the intention that

Note that this API was originally designed for KeyMint, with the intention that

To more securely and reliably get keys and certificates to Android devices, we

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

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

is responsible for managing private keys. The strategy we've chosen is to

deliver certificates over the air, using an asymmetric key pair created

deliver certificates over the air, using an asymmetric key pair derived from a

on-device in the factory as a root of trust to create an authenticated, secure

unique device secret (UDS) as a root of trust for authenticated requests from

channel. In this document we refer to this device-unique asymmetric key pair as

the secure components. We refer to the public half of this asymmetric key pair

Device Key (DK), its public half DK\_pub, its private half DK\_priv and a Device

as UDS\_pub.

Key Certificate containing DK\_pub is denoted DKC.

In order for the provisioning service to trust UDS\_pub we ask device OEMs to

In order for the provisioning service to use DK (or a key authenticated by DK),

use one of two mechanisms:

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:

1.  (Preferred, recommended) The device OEM extracts the UDS\_pub from each

    device they manufacture and uploads the public keys to a backend server.

1.  (Preferred, recommended) The device OEM extracts DK\_pub from each device it

    manufactures and uploads the public keys to a backend server.

1.  The device OEM signs the UDS\_pub and stores the certificates on the device

    rather than uploading a UDS\_pub for every device immediately. However,

1.  The device OEM signs the DK\_pub to produce DKC and stores it on the device.

    there are many disadvantages and costs associated with this option as the

    This has the advantage that they don't need to upload a DK\_pub for every

    OEM will need to pass a security audit of their factory's physical security,

    device immediately, but the disadvantage that they have to manage their

    CA and HSM configuration, and incident response processes before the OEM's

    private signing keys, which means they have to have HSMs, configure and

    public key is registered with the provisioning server.

    secure them correctly, etc. Some backend providers may also require that the

    OEM passes a factory security audit, and additionally promises to upload the

Note that in the full elaboration of this plan, UDS\_pub is not the key used to

    keys eventually as well.

sign certificate requests. Instead, UDS\_pub is just the first public key in a

chain of public keys that end the KeyMint public key. All keys in the chain are

Note that in the full elaboration of this plan, DK\_pub is not the key used to

transitively derived from the UDS and joined in a certificate chain following

establish a secure channel. Instead, DK\_pub is just the first public key in a

the specification of the [Android Profile for DICE](#android-profile-for-dice).

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.

### Phases

### Phases

RKP will be deployed in three phases, in terms of managing the root of trust

RKP will be deployed with phased management of the root of trust

binding between the device and the backend. To briefly describe them:

binding between the device and the backend. To briefly describe them:

* Phase 1: In phase 1 there is only one entry in the BCC; DK_pub and KM_pub are

* Degenerate DICE (Phase 1): A TEE root of trust key pair is used to sign

  the same key and the certificate is self-signed.

  certificate requests; a single self-signed certificate signifies this phase.

* Phase 2: This is identical to phase 1, except it leverages the hardware root

* DICE (Phase 2): A hardware root of trust key pair is only accessible to ROM

  of trust process described by DICE. Instead of trust being rooted in the TEE,

  code; the boot process follows the [Android Profile for

  it is now rooted in the ROM by key material blown into fuses which are only

  DICE](#android-profile-for-dice).

  accessible to the ROM code.

* SoC vendor certified DICE (Phase 3): This is identical to Phase 2, except the

* Phase 3: This is identical to Phase 2, except the SoC vendor also does the

  SoC vendor also does the UDS\_pub extraction or certification in their

  public key extraction or certification in their facilities, along with the OEM

  facilities, along with the OEM doing it in the factory. This tightens up the

  doing it in the factory. This tightens up the "supply chain" and aims to make

  "supply chain" and aims to make key upload management more secure.

  key upload management more secure.

### Privacy considerations

### Privacy considerations

Because DK and the DKCs are unique, immutable, unspoofable hardware-bound

Because the UDS, CDIs and derived values are unique, immutable, unspoofable

identifiers for the device, we must limit access to them to the absolute minimum

hardware-bound identifiers for the device, we must limit access to them. We

possible. We do this in two ways:

require that the values are never exposed in public APIs and are only available

to the minimum set of system components that require access to them to function

1.  We require KeyMint (which knows the BCC and either knows or at least has the

correctly.

ability to use KM\_priv) to refuse to ever divulge the BCC or additional

signatures in plaintext. Instead, KeyMint requires the caller to provide an

_Endpoint Encryption Key_ (EEK), with which it will encrypt the data before

returning it. When provisioning production keys, the EEK must be signed by an

approved authority whose public key is embedded in KeyMint. When certifying test

keys, KeyMint will accept any EEK without checking the signature, but will

encrypt and return a test BCC, rather than the real one.  The result is that

only an entity in possession of an Trusted EEK (TEEK) private key can discover

the plaintext of the production BCC.

1.  Having thus limited access to the public keys to the trusted party only, we

need to prevent the entity from abusing this unique device identifier.  The

approach and mechanisms for doing that are beyond the scope of this document

(they must be addressed in the server design), but generally involve taking care

to ensure that we do not create any links between user IDs, IP addresses or

issued certificates and the device pubkey.

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](https://tools.ietf.org/html/rfc8610)):

```

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.

### Key and cryptographic message formatting

### Key and cryptographic message formatting

choice for algorithm implies the implementor should also choose the P256 public

choice for algorithm implies the implementor should also choose the P256 public

key group further down in the COSE structure.

key group further down in the COSE structure.

### Testability

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.

## Design

## Design

### Certificate provisioning flow

### Certificate provisioning flow

TODO(jbires): Replace this with a `.png` containing a sequence diagram.  The

TODO(jbires): Replace this with a `.png` containing a sequence diagram.  The

provisioning flow looks something like this:

provisioning flow looks something like this:

Provisioner -> Keystore: Prepare N keys

rkpd -> KeyMint: generateKeyPair

Keystore -> KeyMint: generateKeyPair

KeyMint -> KeyMint: Generate key pair

KeyMint -> KeyMint: Generate key pair

KeyMint --> Keystore: key\_blob,pubkey

KeyMint --> rkpd: key\_blob,pubkey

Keystore -> Keystore: Store key\_blob,pubkey

rkpd -> rkpd: Store key\_blob,pubkey

Provisioner -> Server: Get TEEK

rkpd -> Server: Get challenge

Server --> Provisioner: TEEK

Server --> rkpd: challenge

Provisioner -> Keystore: genCertReq(N, TEEK)

rkpd -> KeyMint: genCertReq(pubkeys, challenge)

Keystore -> KeyMint: genCertReq(pubkeys, TEEK)

KeyMint -> KeyMint: Sign CSR

KeyMint -> KeyMint: Sign pubkeys & encrypt BCC

KeyMint --> rkpd: signed CSR

KeyMint --> Keystore: signature, encrypted BCC

rkpd --> Server: CSR

Keystore -> Keystore: Construct cert\_request

Server -> Server: Validate CSR

Keystore --> Provisioner: cert\_request

Provisioner --> Server: cert\_request

Server -> Server: Validate cert\_request

Server -> Server: Generate certificates

Server -> Server: Generate certificates

Server --> Provisioner: certificates

Server --> rkpd: certificates

Provisioner -> Keystore: certificates

rkpd -> rkpd: Store certificates

Keystore -> Keystore: Store certificates

The actors in the above diagram are:

The actors in the above diagram are:

    the uploaded device public keys and is responsible for providing encryption

    the uploaded device public keys and is responsible for providing encryption

    keys, decrypting and validating requests, and generating certificates in

    keys, decrypting and validating requests, and generating certificates in

    response to requests.

    response to requests.

*   **Provisioner** is an application that is responsible for communicating with

*   **rkpd** is, optionally, a modular system component that is responsible for

    the server and all of the system components that require key certificates

    communicating with the server and all of the system components that require

    from the server. It also implements the policy that defines how many key

    key certificates from the server. It also implements the policy that defines

    pairs each client should keep in their pool.

    how many key pairs each client should keep in their pool. When a system

    ships with rkpd as a modular component, it may be updated independently from

    the rest of the system.

*   **Keystore** is the [Android keystore

*   **Keystore** is the [Android keystore

    daemon](https://developer.android.com/training/articles/keystore) (or, more

    daemon](https://developer.android.com/training/articles/keystore) (or, more

    generally, whatever system component manages communications with a

    generally, whatever system component manages communications with a

*   **KeyMint** is the secure area component that manages cryptographic keys and

*   **KeyMint** is the secure area component that manages cryptographic keys and

    performs attestations (or perhaps some other secure area component).

    performs attestations (or perhaps some other secure area component).

### `BCC`

### Android Profile for DICE

The _Boot Certificate Chain_ (BCC) is the chain of certificates that contains

The Android Profile for DICE is based on the [Open Profile for

DK\_pub as well as other often device-unique certificates. The BCC is

DICE](https://pigweed.googlesource.com/open-dice/+/refs/heads/main/docs/specification.md),

represented as a COSE\_Key containing DK\_pub followed by an array of

with additional constraints for details that the Open Profile for DICE leaves

COSE\_Sign1 "certificates" containing public keys and optional additional

intentionally underspecified. This section describes the differences from the

information, ordered from root to leaf, with each certificate signing the next.

Open Profile for DICE.

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

#### Algorithms

there is only one entry; DK\_pub and KM\_pub are the same key and the

certificate is self-signed.

The choice of algorithm must remain consistent with a given certificate e.g. if

SHA-256 is used for the code hash then the authority hash, config hash, etc.

Each COSE\_Sign1 certificate is a CBOR Web Token (CWT) as described in [RFC

must also use SHA-256.

8392](https://tools.ietf.org/html/rfc8392) with additional fields as described

in the Open Profile for DICE. Of these additional fields, only the

* UDS and CDI key pairs:

_subjectPublicKey_ and _keyUsage_ fields are expected to be present for the

  * Ed25519 / P-256 / P-384

KM\_pub entry (that is, the last entry) in a BCC, but all fields required by the

* Hash algorithms (digests can be encoded with their natural size and do not

Open Profile for DICE are expected for other entries (each of which corresponds

  need to be the 64-bytes specified by the Open Profile for DICE):

to a particular firmware component or boot stage). The CWT fields _iss_ and

  * SHA-256 / SHA-384 / SHA-512

_sub_ identify the issuer and subject of the certificate and are consistent

* HKDF with a supported message digest for all key derivation

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](#certificaterequest)).

#### Mode

#### Mode

The Open Profile for DICE specifies four possible modes with the most important

A certificate must only set the mode to `normal` when all of the following

mode being `normal`. A certificate must only set the mode to `normal` when all

conditions are met when loading and verifying the software component that is

of the following conditions are met when loading and verifying the software

being described by the certificate:

component that is being described by the certificate:

* verified boot with anti-rollback protection is enabled

* verified boot with anti-rollback protection is enabled

* only the verified boot authorities for production images are enabled

* only the verified boot authorities for production images are enabled

*   debug ports, fuses or other debug facilities are disabled

* debug ports, fuses, or other debug facilities are disabled

* device booted software from the normal primary source e.g. internal flash

* device booted software from the normal primary source e.g. internal flash

The mode should never be `not configured`.

The mode should never be `not configured`.

#### Configuration descriptor

#### Configuration descriptor

The Open Profile for DICE allows for an arbitrary configuration descriptor. For

The configuration descriptor is a CBOR map with the following optional fields.

BCC entries, this configuration descriptor is a CBOR map with the following

If no fields are relevant, an empty map should be encoded. The key value range

optional fields. If no fields are relevant, an empty map should be encoded.

\[-70000, -70999\] is reserved for the Android Profile for DICE.

Additional implementation-specific fields may be added using key values not in

Implementation-specific fields may be added using key values outside of the

the range \[-70000, -70999\] (these are reserved for future additions here).

reserved range.

```

```

| Name              | Key    | Value type | Meaning                           |

| Name              | Key    | Value type | Meaning                           |

:                   :        :            : version                           :

:                   :        :            : version                           :

```

```

Please see

[ProtectedData.aidl](https://cs.android.com/android/platform/superproject/+/master:hardware/interfaces/security/rkp/aidl/android/hardware/security/keymint/ProtectedData.aidl)

for a full CDDL definition of the BCC.

### `CertificateRequest`

The full CBOR message that will be sent to the server to request certificates

is:

```cddl

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`.

### HAL

### HAL

The remote provisioning HAL provides a simple interface that can be implemented

The remote provisioning HAL provides a simple interface that can be implemented