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
diff --git a/security/rkp/aidl/android/hardware/security/keymint/DeviceInfo.aidl b/security/rkp/aidl/android/hardware/security/keymint/DeviceInfo.aidl
index f0af619..bd27882 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 @@
* 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 @@
* ? "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;
}