tequilaOS/platform_hardware_interfaces
2
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

rkp: pull out remaining CDDL and make compliant

Browse source 
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
This commit is contained in:
David Drysdale 2023-09-07 11:39:31 +01:00
parent 01fc1b7279
commit 04d2ed4ff0
9 changed files with 130 additions and 128 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

74
security/rkp/aidl/android/hardware/security/keymint/DeviceInfo.aidl
View file

@ -32,79 +32,9 @@ parcelable DeviceInfo {
* 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;
}

24
security/rkp/aidl/android/hardware/security/keymint/DeviceInfoV1.cddl Normal file
View file

@ -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.
}

21
security/rkp/aidl/android/hardware/security/keymint/DeviceInfoV2.cddl Normal file
View file

@ -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.
}

20
security/rkp/aidl/android/hardware/security/keymint/DeviceInfoV3.cddl Normal file
View file

@ -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.
}

27
security/rkp/aidl/android/hardware/security/keymint/MacedPublicKey.aidl
View file

@ -28,33 +28,8 @@ parcelable MacedPublicKey {
* 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;
}

15
security/rkp/aidl/android/hardware/security/keymint/MacedPublicKey.cddl Normal file
View file

@ -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

13
security/rkp/aidl/android/hardware/security/keymint/PublicKey.cddl Normal file
View file

@ -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.
}

35
security/rkp/aidl/android/hardware/security/keymint/generateCertificateRequest.cddl
View file

@ -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 @@ SignatureKeySignatureInput = [
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 @@ EekX25519 = { ; COSE_Key
-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 @@ EekSignatureInput = [
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 @@ MacedKeys = [ ; COSE_Mac0
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

29
security/rkp/aidl/android/hardware/security/keymint/generateCertificateRequestV2.cddl
View file

@ -6,7 +6,7 @@ Csr = AuthenticatedRequest<CsrPayload>
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 @@ CsrPayload = [ ; CBOR Array defining the payload for Csr
; - "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 @@ AuthenticatedRequest<T> = [
]>,
]
; COSE_Sign1 (untagged)
; COSE_Sign1 (untagged) [RFC9052 s4.2]
SignedData<Data> = [
protected: bstr .cbor { 1 : AlgorithmEdDSA / AlgorithmES256 / AlgorithmES384 },
unprotected: {},
@ -39,7 +39,7 @@ SignedData<Data> = [
; 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 @@ DiceChainEntryPayload = { ; CWT [RFC8392]
; 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 @@ DiceChainEntryInput = [
; 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 @@ PubKeyECDSA256 = { ; COSE_Key
-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