Add UDS certificate requirements to RKP docs
Add a section to the RKP README that describes the requirements for UDS
certificates.
Change-Id: Id1dac4f20495a25792c5f0e4c601433b26c82297
diff --git a/security/rkp/README.md b/security/rkp/README.md
index 67cf72e..43a00fb 100644
--- a/security/rkp/README.md
+++ b/security/rkp/README.md
@@ -31,12 +31,13 @@
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 @@
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
diff --git a/security/rkp/aidl/android/hardware/security/keymint/generateCertificateRequestV2.cddl b/security/rkp/aidl/android/hardware/security/keymint/generateCertificateRequestV2.cddl
index 7a02ff5..c519086 100644
--- a/security/rkp/aidl/android/hardware/security/keymint/generateCertificateRequestV2.cddl
+++ b/security/rkp/aidl/android/hardware/security/keymint/generateCertificateRequestV2.cddl
@@ -52,7 +52,8 @@
; 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
}