Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

Commit 6700505f authored by Seth Moore's avatar Seth Moore Committed by Automerger Merge Worker
Browse files

Merge "Add UDS certificate requirements to RKP docs" into main am: c6f1566d am: 86ea821e 

Original change: https://android-review.googlesource.com/c/platform/hardware/interfaces/+/3307322



Change-Id: If46dcad9b49a2e0afc395e7280d69a0ad4ee8e95
Signed-off-by: default avatarAutomerger Merge Worker <android-build-automerger-merge-worker@system.gserviceaccount.com>
parents c8993b77 86ea821e

security/rkp/README.md

+54 −6
Original line number Diff line number Diff line
@@ -31,12 +31,13 @@ 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.  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,

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

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

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

    public key is registered with the provisioning server.

1.  The device OEM certifies the UDS\_pub using an x.509 certificate chain

    then stores the chain on the device rather than uploading a UDS\_pub for

    every device immediately. However, there are many disadvantages and costs

    associated with this option as the OEM will need to pass a security audit

    of their factory's physical security, CA and HSM configuration, and

    incident response processes before the OEM's public key is registered with

    the provisioning server.



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

sign certificate requests. Instead, UDS\_pub is just the first public key in a
@@ -124,6 +125,53 @@ 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.



## UDS certificates



As noted in the section [General approach](#general-approach), the UDS\_pub may

be authenticated by an OEM using an x.509 certificate chain. Additionally,

[RKP Phase 3](#phases) depends on the chip vendor signing the UDS\_pub and

issuing an x.509 certificate chain. This section describes the requirements for

both the signing keys and the resulting certificate chain.



### X.509 Certificates



X.509v3 public key certificates are the only supported mechanism for

authenticating a UDS\_pub. Certificates must be formatted according to

[RFC 5280](https://datatracker.ietf.org/doc/html/rfc5280), and certificate

chains must satisfy the certificate path validation described in the RFC. RFC

5280 covers most requirements for the chain, but this specification has some

additional requirements that must be met for the certificates:



*   [`BasicConstraints`](https://datatracker.ietf.org/doc/html/rfc5280#section-4.2.1.9)

    *   All CA certificates must include this as a critical extension.

    *   `pathLenConstraint` must be set correctly in each CA certificate to

        limit the maximum chain length.

    *   `cA` must be set to true for all certificates except the leaf

        certificate.

    *   `BasicConstraints` must be absent for the leaf/UDS certificate.

    *   Consider the chain `root -> intermediate -> UDS_pub`. In such a chain,

        `BasicConstraints` must be:

        *   `{ cA: TRUE, pathLenConstraint: 1}` for the root certificate

        *   `{ cA: TRUE, pathLenConstraint: 0}` for the intermediate certificate

        *   Absent for the UDS certificate

*   [`KeyUsage`](https://datatracker.ietf.org/doc/html/rfc5280#section-4.2.1.3)

    *   All certificates in a UDS certificate chain must include this as a

        critical extension.

    *   CA certificates must set `KeyUsage` to only `keyCertSign`.

    *   The UDS certificate must set `KeyUsage` to only `digitalSignature`.



### Supported Algorithms



UDS certificates must be signed using one of the following allowed algorithms:



*   `ecdsa-with-SHA256`

    ([RFC 5758](https://www.rfc-editor.org/rfc/rfc5758#section-3.2))

    *   Note: this algorithm is only usable with ECDSA P-256 keys

*   `ecdsa-with-SHA384`

    ([RFC 5758](https://www.rfc-editor.org/rfc/rfc5758#section-3.2))

    *   Note: this algorithm is only usable with ECDSA P-384 keys

*   `id-Ed25519` ([RFC 8410](https://www.rfc-editor.org/rfc/rfc8410#section-3))



## Design



### Certificate provisioning flow

security/rkp/aidl/android/hardware/security/keymint/generateCertificateRequestV2.cddl

+2 −1
Original line number Diff line number Diff line
@@ -52,7 +52,8 @@ SignedDataSigStruct<Data> = [ 
; example, this could be provided by the hardware vendor, who certifies all of their chips.

; The SignerName is a free-form string describing who generated the signature. The root

; certificate will need to be communicated to the verifier out of band, along with the

; SignerName that is expected for the given root certificate.

; SignerName that is expected for the given root certificate. UDS certificate

; requirements are defined in https://android.googlesource.com/platform/hardware/interfaces/+/main/security/rkp/README.md#uds-certificates.

UdsCerts = {

    * SignerName => UdsCertChain

}