Merge "Minor corrections to the Keymaster4 documentation." into pi-dev
diff --git a/current.txt b/current.txt
index 413efae..9ddfdb6 100644
--- a/current.txt
+++ b/current.txt
@@ -347,8 +347,8 @@
675682dd3007805c985eaaec91612abc88f4c25b3431fb84070b7584a1a741fb android.hardware.health@2.0::IHealth
434c4c32c00b0e54bb05e40c79503208b40f786a318029a2a4f66e34f10f2a76 android.hardware.health@2.0::IHealthInfoCallback
c9e498f1ade5e26f00d290b4763a9671ec6720f915e7d592844b62e8cb1f9b5c android.hardware.health@2.0::types
-5c8e06f9945276d1a9e8f7e37cf0ea8894bdb906fa80809cb06c36abb39afc4f android.hardware.keymaster@4.0::IKeymasterDevice
-6695eb5744108035506004dd136068b1aaebe809cf9d4a69c2fe33b73058bb85 android.hardware.keymaster@4.0::types
+201f9723353fdbd40bf3705537fb7e015e4c399879425e68688fe0f43606ea4d android.hardware.keymaster@4.0::IKeymasterDevice
+1b7d2090c0a28b229d37c4b96160796b1f0d703950ac6ccc163fccd280830503 android.hardware.keymaster@4.0::types
6d5c646a83538f0f9d8438c259932509f4353410c6c76e56db0d6ca98b69c3bb android.hardware.media.bufferpool@1.0::IAccessor
b8c7ed58aa8740361e63d0ce9e7c94227572a629f356958840b34809d2393a7c android.hardware.media.bufferpool@1.0::IClientManager
4a2c0dc82780e6c90731725a103feab8ab6ecf85a64e049b9cbd2b2c61620fe1 android.hardware.media.bufferpool@1.0::IConnection
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:
