Minor corrections to the Keymaster4 documentation.
Gramatical and punctuation corrections; addition of missing
userSecureId to AuthorizationList schema and removal of extraneous
rollbackResistant from same; correction of OS_PATCHLEVEL source
property; and addition of missing TAG_UNLOCKED_DEVICE_REQUIRED
documentation.
Bug: 69550260
Test: N/A
Change-Id: I04092b7df3af69201ba1467cddc09f6f44e861a8
diff --git a/keymaster/4.0/IKeymasterDevice.hal b/keymaster/4.0/IKeymasterDevice.hal
index 6c09ef3..74d13d8 100644
--- a/keymaster/4.0/IKeymasterDevice.hal
+++ b/keymaster/4.0/IKeymasterDevice.hal
@@ -217,8 +217,8 @@
* must be a TEE Keymaster as well. The HMAC key used to MAC and verify authentication tokens
* (HardwareAuthToken, VerificationToken and ConfirmationToken all use this HMAC key) must be
* shared between TEE and StrongBox so they can each validate tokens produced by the other.
- * This method is the first step in the process for for agreeing on a shared key. It is called
- * by Android during startup. The system calls it on each of the HAL instances and collects the
+ * This method is the first step in the process for agreeing on a shared key. It is called by
+ * Android during startup. The system calls it on each of the HAL instances and collects the
* results in preparation for the second step.
*
* @return error ErrorCode::OK on success, ErrorCode::UNIMPLEMENTED if HMAC agreement is not
@@ -324,7 +324,7 @@
* sharingCheck = HMAC(H, "Keymaster HMAC Verification")
*
* The string is UTF-8 encoded, 27 bytes in length. If the returned values of all
- * IKeymasterDevice instances don't match, Keystore will assume that HMAC agreement
+ * IKeymasterDevice instances don't match, clients must assume that HMAC agreement
* failed.
*/
computeSharedHmac(vec<HmacSharingParameters> params)
@@ -718,16 +718,19 @@
* AuthorizationList ::= SEQUENCE {
* purpose [1] EXPLICIT SET OF INTEGER OPTIONAL,
* algorithm [2] EXPLICIT INTEGER OPTIONAL,
- * keySize [3] EXPLICIT INTEGER OPTIONAL.
+ * keySize [3] EXPLICIT INTEGER OPTIONAL,
* blockMode [4] EXPLICIT SET OF INTEGER OPTIONAL,
* digest [5] EXPLICIT SET OF INTEGER OPTIONAL,
* padding [6] EXPLICIT SET OF INTEGER OPTIONAL,
+ * callerNonce [7] EXPLICIT NULL OPTIONAL,
+ * minMacLength [8] EXPLICIT INTEGER OPTIONAL,
* ecCurve [10] EXPLICIT INTEGER OPTIONAL,
* rsaPublicExponent [200] EXPLICIT INTEGER OPTIONAL,
* rollbackResistance [303] EXPLICIT NULL OPTIONAL,
- * activeDateTime [400] EXPLICIT INTEGER OPTIONAL
- * originationExpireDateTime [401] EXPLICIT INTEGER OPTIONAL
- * usageExpireDateTime [402] EXPLICIT INTEGER OPTIONAL
+ * activeDateTime [400] EXPLICIT INTEGER OPTIONAL,
+ * originationExpireDateTime [401] EXPLICIT INTEGER OPTIONAL,
+ * usageExpireDateTime [402] EXPLICIT INTEGER OPTIONAL,
+ * userSecureId [502] EXPLICIT INTEGER OPTIONAL,
* noAuthRequired [503] EXPLICIT NULL OPTIONAL,
* userAuthType [504] EXPLICIT INTEGER OPTIONAL,
* authTimeout [505] EXPLICIT INTEGER OPTIONAL,
@@ -735,15 +738,11 @@
* trustedUserPresenceReq [507] EXPLICIT NULL OPTIONAL,
* trustedConfirmationReq [508] EXPLICIT NULL OPTIONAL,
* unlockedDeviceReq [509] EXPLICIT NULL OPTIONAL,
- * allApplications [600] EXPLICIT NULL OPTIONAL,
- * applicationId [601] EXPLICIT OCTET_STRING OPTIONAL,
* creationDateTime [701] EXPLICIT INTEGER OPTIONAL,
* origin [702] EXPLICIT INTEGER OPTIONAL,
- * rollbackResistant [703] EXPLICIT NULL OPTIONAL,
* rootOfTrust [704] EXPLICIT RootOfTrust OPTIONAL,
* osVersion [705] EXPLICIT INTEGER OPTIONAL,
* osPatchLevel [706] EXPLICIT INTEGER OPTIONAL,
- * attestationChallenge [708] EXPLICIT OCTET_STRING OPTIONAL,
* attestationApplicationId [709] EXPLICIT OCTET_STRING OPTIONAL,
* attestationIdBrand [710] EXPLICIT OCTET_STRING OPTIONAL,
* attestationIdDevice [711] EXPLICIT OCTET_STRING OPTIONAL,
diff --git a/keymaster/4.0/types.hal b/keymaster/4.0/types.hal
index 85f181a..94dfec5 100644
--- a/keymaster/4.0/types.hal
+++ b/keymaster/4.0/types.hal
@@ -460,6 +460,8 @@
* called on one key with TRUSTED_USER_PRESENCE_REQUIRED, and another begin() comes in for that
* key or another with TRUSTED_USER_PRESENCE_REQUIRED, Keymaster must return
* ErrorCode::CONCURRENT_PROOF_OF_PRESENCE_REQUESTED.
+ *
+ * Must be hardware-enforced.
*/
TRUSTED_USER_PRESENCE_REQUIRED = TagType:BOOL | 507,
@@ -470,11 +472,17 @@
*
* If an attempt to use a key with this tag does not have a cryptographically valid
* CONFIRMATION_TOKEN provided to finish() or if the data provided to update()/finish() does not
- * match the data described in the token, keymaster must return NO_USER_CONFIRMATION. */
+ * match the data described in the token, keymaster must return NO_USER_CONFIRMATION.
+ *
+ * Must be hardware-enforced.
+ */
TRUSTED_CONFIRMATION_REQUIRED = TagType:BOOL | 508,
/**
+ * Tag::UNLOCKED_DEVICE_REQUIRED specifies that the key may only be used when the device is
+ * unlocked.
*
+ * Must be software-enforced.
*/
UNLOCKED_DEVICE_REQUIRED = TagType:BOOL | 509,
@@ -490,7 +498,7 @@
* access to the tag content to decrypt the key without brute-forcing the tag content, which
* applications can prevent by specifying sufficiently high-entropy content.
*
- * Must be hardware-enforced.
+ * Must never appear in KeyCharacteristics.
*/
APPLICATION_ID = TagType:BYTES | 601,
@@ -511,7 +519,7 @@
* access to the tag content to decrypt the key without brute-forcing the tag content, which
* applications can prevent by specifying sufficiently high-entropy content.
*
- * Must be hardware-enforced.
+ * Must never appear in KeyCharacteristics.
*/
APPLICATION_DATA = TagType:BYTES | 700,
@@ -557,11 +565,12 @@
* key generated on Android version 4.0.3, the value would be 040003.
*
* The IKeymasterDevice HAL must read the current OS version from the system property
- * ro.build.id and deliver it to the secure environment when the HAL is first loaded (mechanism
- * is implementation-defined). The secure environment must not accept another version until
- * after the next boot. If the content of ro.build.id has additional version information after
- * the sub-minor version number, it must not be included in Tag::OS_VERSION. If the content is
- * non-numeric, the secure environment must use 0 as the system version.
+ * ro.build.version.release and deliver it to the secure environment when the HAL is first
+ * loaded (mechanism is implementation-defined). The secure environment must not accept another
+ * version until after the next boot. If the content of ro.build.version.release has additional
+ * version information after the sub-minor version number, it must not be included in
+ * Tag::OS_VERSION. If the content is non-numeric, the secure environment must use 0 as the
+ * system version.
*
* Must be hardware-enforced.
*/
@@ -659,8 +668,8 @@
/**
* Tag::ATTESTATION_ID_BRAND provides the device's brand name, as returned by Build.BRAND in
- * Android, to attestKey(). This field is set only when requesting attestation of the device's
- * identifiers.
+ * Android, to attestKey(). This field must be set only when requesting attestation of the
+ * device's identifiers.
*
* If the device does not support ID attestation (or destroyAttestationIds() was previously
* called and the device can no longer attest its IDs), any key attestation request that
@@ -672,8 +681,8 @@
/**
* Tag::ATTESTATION_ID_DEVICE provides the device's device name, as returned by Build.DEVICE in
- * Android, to attestKey(). This field is set only when requesting attestation of the device's
- * identifiers.
+ * Android, to attestKey(). This field must be set only when requesting attestation of the
+ * device's identifiers.
*
* If the device does not support ID attestation (or destroyAttestationIds() was previously
* called and the device can no longer attest its IDs), any key attestation request that
@@ -685,7 +694,7 @@
/**
* Tag::ATTESTATION_ID_PRODUCT provides the device's product name, as returned by Build.PRODUCT
- * in Android, to attestKey(). This field is set only when requesting attestation of the
+ * in Android, to attestKey(). This field must be set only when requesting attestation of the
* device's identifiers.
*
* If the device does not support ID attestation (or destroyAttestationIds() was previously
@@ -697,7 +706,7 @@
ATTESTATION_ID_PRODUCT = TagType:BYTES | 712,
/**
- * Tag::ATTESTATION_ID_SERIAL the device's serial number. This field is set only when
+ * Tag::ATTESTATION_ID_SERIAL the device's serial number. This field must be set only when
* requesting attestation of the device's identifiers.
*
* If the device does not support ID attestation (or destroyAttestationIds() was previously
@@ -710,7 +719,7 @@
/**
* Tag::ATTESTATION_ID_IMEI provides the IMEIs for all radios on the device to attestKey().
- * This field is set only when requesting attestation of the device's identifiers.
+ * This field must be set only when requesting attestation of the device's identifiers.
*
* If the device does not support ID attestation (or destroyAttestationIds() was previously
* called and the device can no longer attest its IDs), any key attestation request that
@@ -723,7 +732,7 @@
/**
* Tag::ATTESTATION_ID_MEID provides the MEIDs for all radios on the device to attestKey().
- * This field will only be set when requesting attestation of the device's identifiers.
+ * This field must be set only when requesting attestation of the device's identifiers.
*
* If the device does not support ID attestation (or destroyAttestationIds() was previously
* called and the device can no longer attest its IDs), any key attestation request that
@@ -736,7 +745,7 @@
/**
* Tag::ATTESTATION_ID_MANUFACTURER provides the device's manufacturer name, as returned by
- * Build.MANUFACTURER in Android, to attstKey(). This field is set only when requesting
+ * Build.MANUFACTURER in Android, to attstKey(). This field must be set only when requesting
* attestation of the device's identifiers.
*
* If the device does not support ID attestation (or destroyAttestationIds() was previously
@@ -749,8 +758,8 @@
/**
* Tag::ATTESTATION_ID_MODEL provides the device's model name, as returned by Build.MODEL in
- * Android, to attestKey(). This field is set only when requesting attestation of the device's
- * identifiers.
+ * Android, to attestKey(). This field must be set only when requesting attestation of the
+ * device's identifiers.
*
* If the device does not support ID attestation (or destroyAttestationIds() was previously
* called and the device can no longer attest its IDs), any key attestation request that
@@ -815,7 +824,7 @@
* Tag::NONCE is used to provide or return a nonce or Initialization Vector (IV) for AES-GCM,
* AES-CBC, AES-CTR, or 3DES-CBC encryption or decryption. This tag is provided to begin during
* encryption and decryption operations. It is only provided to begin if the key has
- * Tag::CALLER_NONCE. If not provided, an appropriate nonce or IV will be randomly generated by
+ * Tag::CALLER_NONCE. If not provided, an appropriate nonce or IV must be randomly generated by
* Keymaster and returned from begin.
*
* The value is a blob, an arbitrary-length array of bytes. Allowed lengths depend on the mode: