rkp: pull out remaining CDDL and make compliant
Extract CDDL from MacedPublicKey.aidl and DeviceInfo.aidl.
Make -70000 optional in `PublicKey`.
Make CDDL compliant with RFC8610:
- Move `bstr` contents for generated data (e.g. `ECDSA(..)`) to comments.
- Fix alternatives in CBOR-encoded bstr instances.
Add more RFC references and unify reference style.
Try to use a standard format to indicate that external files are needed
for the complete CDDL schema. (Hopefully in the future we might have
tooling that uses these to check the schemas.)
Test: Compile with docs.rs/cddl-cat and https://cddl.anweiss.tech/
Change-Id: Ie1d6c39f1cc0314e312df9205b570b89178ebd16
diff --git a/security/rkp/aidl/android/hardware/security/keymint/DeviceInfo.aidl b/security/rkp/aidl/android/hardware/security/keymint/DeviceInfo.aidl
index 8456148..f668536 100644
--- a/security/rkp/aidl/android/hardware/security/keymint/DeviceInfo.aidl
+++ b/security/rkp/aidl/android/hardware/security/keymint/DeviceInfo.aidl
@@ -32,79 +32,9 @@
* non-canonical to group similar entries semantically.
*
* The DeviceInfo has changed across versions 1, 2, and 3 of the HAL. All versions of the
- * DeviceInfo CDDL are described as follows. Please refer to the CDDL structure version
- * that corresponds to the HAL version you are working with:
+ * DeviceInfo CDDL are described in the DeviceInfoV*.cddl files. Please refer to the CDDL
+ * structure version that corresponds to the HAL version you are working with.
*
- * Version 3, introduced in Android 14:
- * DeviceInfo = {
- * "brand" : tstr,
- * "manufacturer" : tstr,
- * "product" : tstr,
- * "model" : tstr,
- * "device" : tstr,
- * "vb_state" : "green" / "yellow" / "orange", ; Taken from the AVB values
- * "bootloader_state" : "locked" / "unlocked", ; Taken from the AVB values
- * "vbmeta_digest": bstr, ; Taken from the AVB values
- * ? "os_version" : tstr, ; Same as
- * ; android.os.Build.VERSION.release
- * ; Not optional for TEE.
- * "system_patch_level" : uint, ; YYYYMM, must match KeyMint OS_PATCHLEVEL
- * "boot_patch_level" : uint, ; YYYYMMDD, must match KeyMint BOOT_PATCHLEVEL
- * "vendor_patch_level" : uint, ; YYYYMMDD, must match KeyMint VENDOR_PATCHLEVEL
- * "security_level" : "tee" / "strongbox",
- * "fused": 1 / 0, ; 1 if secure boot is enforced for the processor that the IRPC
- * ; implementation is contained in. 0 otherwise.
- * }
- *
- * ---------------------------------------------------------------------------------------------
- *
- * Version 2, introduced in Android 13:
- * DeviceInfo = {
- * "brand" : tstr,
- * "manufacturer" : tstr,
- * "product" : tstr,
- * "model" : tstr,
- * "device" : tstr,
- * "vb_state" : "green" / "yellow" / "orange", ; Taken from the AVB values
- * "bootloader_state" : "locked" / "unlocked", ; Taken from the AVB values
- * "vbmeta_digest": bstr, ; Taken from the AVB values
- * ? "os_version" : tstr, ; Same as
- * ; android.os.Build.VERSION.release
- * ; Not optional for TEE.
- * "system_patch_level" : uint, ; YYYYMM, must match KeyMint OS_PATCHLEVEL
- * "boot_patch_level" : uint, ; YYYYMMDD, must match KeyMint BOOT_PATCHLEVEL
- * "vendor_patch_level" : uint, ; YYYYMMDD, must match KeyMint VENDOR_PATCHLEVEL
- * "version" : 2, ; The CDDL schema version.
- * "security_level" : "tee" / "strongbox",
- * "fused": 1 / 0, ; 1 if secure boot is enforced for the processor that the IRPC
- * ; implementation is contained in. 0 otherwise.
- *
- * ---------------------------------------------------------------------------------------------
- *
- * Version 1, introduced in Android 12:
- * DeviceInfo = {
- * ? "brand" : tstr,
- * ? "manufacturer" : tstr,
- * ? "product" : tstr,
- * ? "model" : tstr,
- * ? "board" : tstr,
- * ? "vb_state" : "green" / "yellow" / "orange", ; Taken from the AVB values
- * ? "bootloader_state" : "locked" / "unlocked", ; Taken from the AVB values
- * ? "vbmeta_digest": bstr, ; Taken from the AVB values
- * ? "os_version" : tstr, ; Same as
- * ; android.os.Build.VERSION.release
- * ? "system_patch_level" : uint, ; YYYYMM, must match KeyMint OS_PATCHLEVEL
- * ? "boot_patch_level" : uint, ; YYYYMMDD, must match KeyMint BOOT_PATCHLEVEL
- * ? "vendor_patch_level" : uint, ; YYYYMMDD, must match KeyMint VENDOR_PATCHLEVEL
- * "version" : 1, ; The CDDL schema version.
- * "security_level" : "tee" / "strongbox"
- * "att_id_state": "locked" / "open", ; Attestation IDs State. If "locked", this
- * ; indicates a device's attestable IDs are
- * ; factory-locked and immutable. If "open",
- * ; this indicates the device is still in a
- * ; provisionable state and the attestable IDs
- * ; are not yet frozen.
- * }
*/
byte[] deviceInfo;
}
diff --git a/security/rkp/aidl/android/hardware/security/keymint/DeviceInfoV1.cddl b/security/rkp/aidl/android/hardware/security/keymint/DeviceInfoV1.cddl
new file mode 100644
index 0000000..056316b
--- /dev/null
+++ b/security/rkp/aidl/android/hardware/security/keymint/DeviceInfoV1.cddl
@@ -0,0 +1,24 @@
+; Version 1, introduced in Android 12:
+DeviceInfo = {
+ ? "brand" : tstr,
+ ? "manufacturer" : tstr,
+ ? "product" : tstr,
+ ? "model" : tstr,
+ ? "board" : tstr,
+ ? "vb_state" : "green" / "yellow" / "orange", ; Taken from the AVB values
+ ? "bootloader_state" : "locked" / "unlocked", ; Taken from the AVB values
+ ? "vbmeta_digest": bstr, ; Taken from the AVB values
+ ? "os_version" : tstr, ; Same as
+ ; android.os.Build.VERSION.release
+ ? "system_patch_level" : uint, ; YYYYMM, must match KeyMint OS_PATCHLEVEL
+ ? "boot_patch_level" : uint, ; YYYYMMDD, must match KeyMint BOOT_PATCHLEVEL
+ ? "vendor_patch_level" : uint, ; YYYYMMDD, must match KeyMint VENDOR_PATCHLEVEL
+ "version" : 1, ; The CDDL schema version.
+ "security_level" : "tee" / "strongbox"
+ "att_id_state": "locked" / "open", ; Attestation IDs State. If "locked", this
+ ; indicates a device's attestable IDs are
+ ; factory-locked and immutable. If "open",
+ ; this indicates the device is still in a
+ ; provisionable state and the attestable IDs
+ ; are not yet frozen.
+}
diff --git a/security/rkp/aidl/android/hardware/security/keymint/DeviceInfoV2.cddl b/security/rkp/aidl/android/hardware/security/keymint/DeviceInfoV2.cddl
new file mode 100644
index 0000000..e49471e
--- /dev/null
+++ b/security/rkp/aidl/android/hardware/security/keymint/DeviceInfoV2.cddl
@@ -0,0 +1,21 @@
+; Version 2, introduced in Android 13:
+DeviceInfo = {
+ "brand" : tstr,
+ "manufacturer" : tstr,
+ "product" : tstr,
+ "model" : tstr,
+ "device" : tstr,
+ "vb_state" : "green" / "yellow" / "orange", ; Taken from the AVB values
+ "bootloader_state" : "locked" / "unlocked", ; Taken from the AVB values
+ "vbmeta_digest": bstr, ; Taken from the AVB values
+ ? "os_version" : tstr, ; Same as
+ ; android.os.Build.VERSION.release
+ ; Not optional for TEE.
+ "system_patch_level" : uint, ; YYYYMM, must match KeyMint OS_PATCHLEVEL
+ "boot_patch_level" : uint, ; YYYYMMDD, must match KeyMint BOOT_PATCHLEVEL
+ "vendor_patch_level" : uint, ; YYYYMMDD, must match KeyMint VENDOR_PATCHLEVEL
+ "version" : 2, ; The CDDL schema version.
+ "security_level" : "tee" / "strongbox",
+ "fused": 1 / 0, ; 1 if secure boot is enforced for the processor that the IRPC
+ ; implementation is contained in. 0 otherwise.
+}
\ No newline at end of file
diff --git a/security/rkp/aidl/android/hardware/security/keymint/DeviceInfoV3.cddl b/security/rkp/aidl/android/hardware/security/keymint/DeviceInfoV3.cddl
new file mode 100644
index 0000000..e841706
--- /dev/null
+++ b/security/rkp/aidl/android/hardware/security/keymint/DeviceInfoV3.cddl
@@ -0,0 +1,20 @@
+; Version 3, introduced in Android 14:
+DeviceInfo = {
+ "brand" : tstr,
+ "manufacturer" : tstr,
+ "product" : tstr,
+ "model" : tstr,
+ "device" : tstr,
+ "vb_state" : "green" / "yellow" / "orange", ; Taken from the AVB values
+ "bootloader_state" : "locked" / "unlocked", ; Taken from the AVB values
+ "vbmeta_digest": bstr, ; Taken from the AVB values
+ ? "os_version" : tstr, ; Same as
+ ; android.os.Build.VERSION.release
+ ; Not optional for TEE.
+ "system_patch_level" : uint, ; YYYYMM, must match KeyMint OS_PATCHLEVEL
+ "boot_patch_level" : uint, ; YYYYMMDD, must match KeyMint BOOT_PATCHLEVEL
+ "vendor_patch_level" : uint, ; YYYYMMDD, must match KeyMint VENDOR_PATCHLEVEL
+ "security_level" : "tee" / "strongbox",
+ "fused": 1 / 0, ; 1 if secure boot is enforced for the processor that the IRPC
+ ; implementation is contained in. 0 otherwise.
+}
diff --git a/security/rkp/aidl/android/hardware/security/keymint/MacedPublicKey.aidl b/security/rkp/aidl/android/hardware/security/keymint/MacedPublicKey.aidl
index 1e41d1b..a290817 100644
--- a/security/rkp/aidl/android/hardware/security/keymint/MacedPublicKey.aidl
+++ b/security/rkp/aidl/android/hardware/security/keymint/MacedPublicKey.aidl
@@ -28,33 +28,8 @@
* only to the secure environment, as proof that the public key was generated by that
* environment. In CDDL, assuming the contained key is a P-256 public key:
*
- * MacedPublicKey = [ ; COSE_Mac0
- * protected: bstr .cbor { 1 : 5}, ; Algorithm : HMAC-256
- * unprotected: { },
- * payload : bstr .cbor PublicKey,
- * tag : bstr HMAC-256(K_mac, MAC_structure)
- * ]
+ * See MacedPublicKey.cddl for CDDL definition.
*
- * ; NOTE: -70000 is deprecated for v3 HAL implementations.
- * ; NOTE: Integer encoding is different for Ed25519 and P256 keys:
- * ; - Ed25519 is LE: https://www.rfc-editor.org/rfc/rfc8032#section-3.1
- * ; - P256 is BE: https://www.secg.org/sec1-v2.pdf#page=19 (section 2.3.7)
- * PublicKey = { ; COSE_Key
- * 1 : 2, ; Key type : EC2
- * 3 : -7, ; Algorithm : ES256
- * -1 : 1, ; Curve : P256
- * -2 : bstr, ; X coordinate, big-endian
- * -3 : bstr, ; Y coordinate, big-endian
- * -70000 : nil ; Presence indicates this is a test key. If set, K_mac is
- * ; all zeros.
- * },
- *
- * MAC_structure = [
- * context : "MAC0",
- * protected : bstr .cbor { 1 : 5 },
- * external_aad : bstr .size 0,
- * payload : bstr .cbor PublicKey
- * ]
*/
byte[] macedKey;
}
diff --git a/security/rkp/aidl/android/hardware/security/keymint/MacedPublicKey.cddl b/security/rkp/aidl/android/hardware/security/keymint/MacedPublicKey.cddl
new file mode 100644
index 0000000..6ae4be4
--- /dev/null
+++ b/security/rkp/aidl/android/hardware/security/keymint/MacedPublicKey.cddl
@@ -0,0 +1,15 @@
+MacedPublicKey = [ ; COSE_Mac0 [RFC9052 s6.2]
+ protected: bstr .cbor { 1 : 5}, ; Algorithm : HMAC-256
+ unprotected: { },
+ payload : bstr .cbor PublicKey,
+ tag : bstr ; HMAC-256(K_mac, MAC_structure)
+]
+
+MAC_structure = [ ; [RFC9052 s6.3]
+ context : "MAC0",
+ protected : bstr .cbor { 1 : 5 },
+ external_aad : bstr .size 0,
+ payload : bstr .cbor PublicKey
+]
+
+; INCLUDE PublicKey.cddl for: PublicKey
diff --git a/security/rkp/aidl/android/hardware/security/keymint/PublicKey.cddl b/security/rkp/aidl/android/hardware/security/keymint/PublicKey.cddl
new file mode 100644
index 0000000..4c1050d
--- /dev/null
+++ b/security/rkp/aidl/android/hardware/security/keymint/PublicKey.cddl
@@ -0,0 +1,13 @@
+; NOTE: -70000 is deprecated for v3 HAL implementations.
+; NOTE: Integer encoding is different for Ed25519 and P256 keys:
+; - Ed25519 is LE: https://www.rfc-editor.org/rfc/rfc8032#section-3.1
+; - P256 is BE: https://www.secg.org/sec1-v2.pdf#page=19 (section 2.3.7)
+PublicKey = { ; COSE_Key [RFC9052 s7]
+ 1 : 2, ; Key type : EC2
+ 3 : -7, ; Algorithm : ES256
+ -1 : 1, ; Curve : P256
+ -2 : bstr, ; X coordinate, big-endian
+ -3 : bstr, ; Y coordinate, big-endian
+ ? -70000 : nil ; Presence indicates this is a test key. If set, K_mac is
+ ; all zeros.
+}
diff --git a/security/rkp/aidl/android/hardware/security/keymint/generateCertificateRequest.cddl b/security/rkp/aidl/android/hardware/security/keymint/generateCertificateRequest.cddl
index 82930bc..fb11492 100644
--- a/security/rkp/aidl/android/hardware/security/keymint/generateCertificateRequest.cddl
+++ b/security/rkp/aidl/android/hardware/security/keymint/generateCertificateRequest.cddl
@@ -3,25 +3,25 @@
EekChain = [ + SignedSignatureKey, SignedEek ]
-SignedSignatureKey = [ ; COSE_Sign1
+SignedSignatureKey = [ ; COSE_Sign1 [RFC9052 s4.2]
protected: bstr .cbor {
1 : AlgorithmEdDSA / AlgorithmES256, ; Algorithm
},
unprotected: {},
payload: bstr .cbor SignatureKeyEd25519 /
bstr .cbor SignatureKeyP256,
- signature: bstr PureEd25519(.cbor SignatureKeySignatureInput) /
- bstr ECDSA(.cbor SignatureKeySignatureInput)
+ signature: bstr ; PureEd25519(.cbor SignatureKeySignatureInput) /
+ ; ECDSA(.cbor SignatureKeySignatureInput)
]
-SignatureKeyEd25519 = { ; COSE_Key
+SignatureKeyEd25519 = { ; COSE_Key [RFC9052 s7]
1 : 1, ; Key type : Octet Key Pair
3 : AlgorithmEdDSA, ; Algorithm
-1 : 6, ; Curve : Ed25519
-2 : bstr ; Ed25519 public key
}
-SignatureKeyP256 = { ; COSE_Key
+SignatureKeyP256 = { ; COSE_Key [RC9052 s7]
1 : 2, ; Key type : EC2
3 : AlgorithmES256, ; Algorithm
-1 : 1, ; Curve: P256
@@ -37,16 +37,15 @@
bstr .cbor SignatureKeyP256
]
-; COSE_Sign1
-SignedEek = [
+SignedEek = [ ; COSE_Sign1 [RFC9052 s4.2]
protected: bstr .cbor { 1 : AlgorithmEdDSA / AlgorithmES256 },
unprotected: {},
- payload: bstr .cbor EekX25519 / .cbor EekP256,
- signature: bstr PureEd25519(.cbor EekSignatureInput) /
- bstr ECDSA(.cbor EekSignatureInput)
+ payload: bstr .cbor EekX25519 / EekP256,
+ signature: bstr ; PureEd25519(.cbor EekSignatureInput) /
+ ; ECDSA(.cbor EekSignatureInput)
]
-EekX25519 = { ; COSE_Key
+EekX25519 = { ; COSE_Key [RFC9052 s7]
1 : 1, ; Key type : Octet Key Pair
2 : bstr ; KID : EEK ID
3 : -25, ; Algorithm : ECDH-ES + HKDF-256
@@ -54,7 +53,7 @@
-2 : bstr ; X25519 public key, little-endian
}
-EekP256 = { ; COSE_Key
+EekP256 = { ; COSE_Key [RFC9052 s7]
1 : 2, ; Key type : EC2
2 : bstr ; KID : EEK ID
3 : -25, ; Algorithm : ECDH-ES + HKDF-256
@@ -67,13 +66,13 @@
context: "Signature1",
body_protected: bstr .cbor { 1 : AlgorithmEdDSA / AlgorithmES256 },
external_aad: bstr .size 0,
- payload: bstr .cbor EekX25519 / .cbor EekP256
+ payload: bstr .cbor EekX25519 / EekP256
]
-AlgorithmES256 = -7 ; RFC 8152 section 8.1
-AlgorithmEdDSA = -8 ; RFC 8152 section 8.2
+AlgorithmES256 = -7 ; [RFC8152 s8.1]
+AlgorithmEdDSA = -8 ; [RFC8152 s8.2]
-MacedKeys = [ ; COSE_Mac0
+MacedKeys = [ ; COSE_Mac0 [RFC9052 s6.2]
protected : bstr .cbor {
1 : 5, ; Algorithm : HMAC-256
},
@@ -83,10 +82,12 @@
tag: bstr
]
-KeysToMacStructure = [
+KeysToMacStructure = [ ; [RFC9052 s6.3]
context : "MAC0",
protected : bstr .cbor { 1 : 5 }, ; Algorithm : HMAC-256
external_aad : bstr .size 0,
; Payload is PublicKeys from keysToSign argument, in provided order.
payload : bstr .cbor [ * PublicKey ]
]
+
+; INCLUDE PublicKey.cddl for: PublicKey
diff --git a/security/rkp/aidl/android/hardware/security/keymint/generateCertificateRequestV2.cddl b/security/rkp/aidl/android/hardware/security/keymint/generateCertificateRequestV2.cddl
index ea71f98..80f7cbd 100644
--- a/security/rkp/aidl/android/hardware/security/keymint/generateCertificateRequestV2.cddl
+++ b/security/rkp/aidl/android/hardware/security/keymint/generateCertificateRequestV2.cddl
@@ -6,7 +6,7 @@
CsrPayload = [ ; CBOR Array defining the payload for Csr
version: 3, ; The CsrPayload CDDL Schema version.
CertificateType, ; The type of certificate being requested.
- DeviceInfo, ; Defined in DeviceInfo.aidl
+ DeviceInfo, ; Defined in the relevant DeviceInfoV*.cddl file.
KeysToSign, ; Provided by the method parameters
]
@@ -18,7 +18,7 @@
; - "keymint"
CertificateType = tstr
-KeysToSign = [ * PublicKey ] ; Please see MacedPublicKey.aidl for the PublicKey definition.
+KeysToSign = [ * PublicKey ] ; Please see PublicKey.cddl for the PublicKey definition.
AuthenticatedRequest<T> = [
version: 1, ; The AuthenticatedRequest CDDL Schema version.
@@ -30,7 +30,7 @@
]>,
]
-; COSE_Sign1 (untagged)
+; COSE_Sign1 (untagged) [RFC9052 s4.2]
SignedData<Data> = [
protected: bstr .cbor { 1 : AlgorithmEdDSA / AlgorithmES256 / AlgorithmES384 },
unprotected: {},
@@ -39,7 +39,7 @@
; ECDSA(CDI_Leaf_Priv, SignedDataSigStruct<Data>)
]
-; Sig_structure for SignedData
+; Sig_structure for SignedData [ RFC9052 s4.4]
SignedDataSigStruct<Data> = [
context: "Signature1",
protected: bstr .cbor { 1 : AlgorithmEdDSA / AlgorithmES256 / AlgorithmES384 },
@@ -113,7 +113,7 @@
; Each entry in the DICE chain is a DiceChainEntryPayload signed by the key from the previous
; entry in the DICE chain array.
-DiceChainEntry = [ ; COSE_Sign1 (untagged)
+DiceChainEntry = [ ; COSE_Sign1 (untagged), [RFC9052 s4.2]
protected : bstr .cbor { 1 : AlgorithmEdDSA / AlgorithmES256 / AlgorithmES384 },
unprotected: {},
payload: bstr .cbor DiceChainEntryPayload,
@@ -135,14 +135,14 @@
; NOTE: Integer encoding is different for Ed25519 and P256 keys:
; - Ed25519 is LE: https://www.rfc-editor.org/rfc/rfc8032#section-3.1
; - P256 is BE: https://www.secg.org/sec1-v2.pdf#page=19 (section 2.3.7)
-PubKeyEd25519 = { ; COSE_Key
+PubKeyEd25519 = { ; COSE_Key [RFC9052 s7]
1 : 1, ; Key type : octet key pair
3 : AlgorithmEdDSA, ; Algorithm : EdDSA
-1 : 6, ; Curve : Ed25519
-2 : bstr ; X coordinate, little-endian
}
-PubKeyECDSA256 = { ; COSE_Key
+PubKeyECDSA256 = { ; COSE_Key [RFC9052 s7]
1 : 2, ; Key type : EC2
3 : AlgorithmES256, ; Algorithm : ECDSA w/ SHA-256
-1 : 1, ; Curve: P256
@@ -150,14 +150,17 @@
-3 : bstr ; Y coordinate, big-endian
}
-PubKeyECDSA384 = { ; COSE_Key
+PubKeyECDSA384 = { ; COSE_Key [RFC9052 s7]
1 : 2, ; Key type : EC2
3 : AlgorithmES384, ; Algorithm : ECDSA w/ SHA-384
-1 : 2, ; Curve: P384
- -2 : bstr, ; X coordinate
- -3 : bstr ; Y coordinate
+ -2 : bstr, ; X coordinate, big-endian
+ -3 : bstr ; Y coordinate, big-endian
}
-AlgorithmES256 = -7
-AlgorithmES384 = -35
-AlgorithmEdDSA = -8
+AlgorithmES256 = -7 ; [RFC9053 s2.1]
+AlgorithmES384 = -35 ; [RFC9053 s2.1]
+AlgorithmEdDSA = -8 ; [RFC9053 s2.2]
+
+; INCLUDE PublicKey.cddl for: PublicKey
+; INCLUDE DeviceInfoV3.cddl for: DeviceInfo