From 47194fa0894e7758cf4f73e5e6ee950ac7eac11a Mon Sep 17 00:00:00 2001 From: Seth Moore Date: Thu, 16 Mar 2023 09:09:40 -0700 Subject: [PATCH] Add old DeviceInfo version documentation Since comments are stripped from the stable AIDL snapshots, the CDDL describing the DeviceInfo contents is lost for the older versions. Add the comments from older DeviceInfo versions as a reference for maintainers of older HAL implementations. Test: n/a Change-Id: I7dd3d285b3d8422a6df4228ad0cf5797e78609c1 --- .../hardware/security/keymint/DeviceInfo.aidl | 67 +++++++++++++++++-- 1 file changed, 61 insertions(+), 6 deletions(-) diff --git a/security/rkp/aidl/android/hardware/security/keymint/DeviceInfo.aidl b/security/rkp/aidl/android/hardware/security/keymint/DeviceInfo.aidl index f0af619fc0..bd278824f6 100644 --- a/security/rkp/aidl/android/hardware/security/keymint/DeviceInfo.aidl +++ b/security/rkp/aidl/android/hardware/security/keymint/DeviceInfo.aidl @@ -17,11 +17,11 @@ package android.hardware.security.keymint; /** - * DeviceInfo contains information about the device that's fed in as AAD in the signature of the - * device private key over the MAC key used for the bundle of public keys. These values are intended - * to be checked by the server to verify that the certificate signing request crafted by - * an IRemotelyProvisionedComponent HAL instance is coming from the expected device based - * on values initially uploaded during device manufacture in the factory. + * DeviceInfo contains information about the device that's signed by the + * IRemotelyProvisionedComponent HAL. These values are intended to be checked by the server to + * verify that the certificate signing request crafted by an IRemotelyProvisionedComponent HAL + * instance is coming from the expected device based on values initially uploaded during device + * manufacture in the factory. * @hide */ @VintfStability @@ -31,6 +31,11 @@ parcelable DeviceInfo { * canonicalized according to the specification in RFC 7049. The ordering presented here is * 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: + * + * Version 3, introduced in Android 14: * DeviceInfo = { * "brand" : tstr, * "manufacturer" : tstr, @@ -43,13 +48,63 @@ parcelable DeviceInfo { * ? "os_version" : tstr, ; Same as * ; android.os.Build.VERSION.release * ; Not optional for TEE. - * "system_patch_level" : uint, ; YYYYMMDD + * "system_patch_level" : uint, ; YYYYMM * "boot_patch_level" : uint, ; YYYYMMDD * "vendor_patch_level" : uint, ; YYYYMMDD * "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 + * "boot_patch_level" : uint, ; YYYYMMDD + * "vendor_patch_level" : uint, ; YYYYMMDD + * "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 + * ? "boot_patch_level" : uint, ; YYYYMMDD + * ? "vendor_patch_level" : uint, ; YYYYMMDD + * "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; }