KeyMint HALs: clarifications
- Remove KeyPurpose comments that refer to public key operations.
- Clarify/fix description of RSA_OAEP_MGF_DIGEST.
- Describe HMAC key requirements.
- Clarify RSA_PSS key length requirement
- Clarify when shared secret should change (on restart)
- Padding::NONE is not deprecated
- Fix typos
Test: none, just comment changes
Change-Id: If58e8d8644aac926a990e50f7a873dca74cd4896
diff --git a/security/keymint/aidl/android/hardware/security/keymint/IKeyMintDevice.aidl b/security/keymint/aidl/android/hardware/security/keymint/IKeyMintDevice.aidl
index b9694e9..2caa4d5 100644
--- a/security/keymint/aidl/android/hardware/security/keymint/IKeyMintDevice.aidl
+++ b/security/keymint/aidl/android/hardware/security/keymint/IKeyMintDevice.aidl
@@ -336,6 +336,17 @@
* Only Tag::KEY_SIZE is required to generate an 3DES key, and its value must be 168. If
* omitted, generateKey must return ErrorCode::UNSUPPORTED_KEY_SIZE.
*
+ * == HMAC Keys ==
+ *
+ * Tag::KEY_SIZE must be provided to generate an HMAC key, and its value must be >= 64 and a
+ * multiple of 8. All devices must support key sizes up to 512 bits, but StrongBox devices must
+ * not support key sizes larger than 512 bits. If omitted or invalid, generateKey() must return
+ * ErrorCode::UNSUPPORTED_KEY_SIZE.
+ *
+ * Tag::MIN_MAC_LENGTH must be provided, and must be a multiple of 8 in the range 64 to 512
+ * bits (inclusive). If omitted, generateKey must return ErrorCode::MISSING_MIN_MAC_LENGTH; if
+ * invalid, generateKey must return ErrorCode::UNSUPPORTED_MIN_MAC_LENGTH.
+ *
* @param keyParams Key generation parameters are defined as KeyMintDevice tag/value pairs,
* provided in params. See above for detailed specifications of which tags are required
* for which types of keys.
@@ -661,19 +672,19 @@
* structure, because it cannot add the DigestInfo structure. Instead, the IKeyMintDevice
* must construct 0x00 || 0x01 || PS || 0x00 || M, where M is the provided message and PS is a
* random padding string at least eight bytes in length. The size of the RSA key has to be at
- * least 11 bytes larger than the message, otherwise begin() must return
+ * least 11 bytes larger than the message, otherwise finish() must return
* ErrorCode::INVALID_INPUT_LENGTH.
*
* o PaddingMode::RSA_PKCS1_1_1_5_ENCRYPT padding does not require a digest.
*
- * o PaddingMode::RSA_PSS padding requires a digest, which must match one of the padding values
+ * o PaddingMode::RSA_PSS padding requires a digest, which must match one of the digest values
* in the key authorizations, and which may not be Digest::NONE. begin() must return
* ErrorCode::INCOMPATIBLE_DIGEST if this is not the case. In addition, the size of the RSA
- * key must be at least 2 + D bytes larger than the output size of the digest, where D is the
- * size of the digest, in bytes. Otherwise begin() must return
- * ErrorCode::INCOMPATIBLE_DIGEST. The salt size must be D.
+ * key must be at least (D + S + 9) bits, where D is the size of the digest (in bits) and
+ * S is the size of the salt (in bits). The salt size S must equal D, so the RSA key must
+ * be at least (2*D + 9) bits. Otherwise begin() must return ErrorCode::INCOMPATIBLE_DIGEST.
*
- * o PaddingMode::RSA_OAEP padding requires a digest, which must match one of the padding values
+ * o PaddingMode::RSA_OAEP padding requires a digest, which must match one of the digest values
* in the key authorizations, and which may not be Digest::NONE. begin() must return
* ErrorCode::INCOMPATIBLE_DIGEST if this is not the case. RSA_OAEP padding also requires an
* MGF1 digest, specified with Tag::RSA_OAEP_MGF_DIGEST, which must match one of the MGF1
@@ -683,9 +694,9 @@
*
* -- EC Keys --
*
- * Private key operations (KeyPurpose::SIGN) need authorization of digest and padding, which
- * means that the key authorizations must contain the specified values. If not, begin() must
- * return ErrorCode::INCOMPATIBLE_DIGEST.
+ * Private key operations (KeyPurpose::SIGN) need authorization of digest, which means that the
+ * key authorizations must contain the specified values. If not, begin() must return
+ * ErrorCode::INCOMPATIBLE_DIGEST.
*
* -- AES Keys --
*
diff --git a/security/keymint/aidl/android/hardware/security/keymint/KeyPurpose.aidl b/security/keymint/aidl/android/hardware/security/keymint/KeyPurpose.aidl
index fd103ef..32e71a7 100644
--- a/security/keymint/aidl/android/hardware/security/keymint/KeyPurpose.aidl
+++ b/security/keymint/aidl/android/hardware/security/keymint/KeyPurpose.aidl
@@ -23,7 +23,7 @@
@VintfStability
@Backing(type="int")
enum KeyPurpose {
- /* Usable with RSA, 3DES and AES keys. */
+ /* Usable with 3DES and AES keys. */
ENCRYPT = 0,
/* Usable with RSA, 3DES and AES keys. */
@@ -32,7 +32,7 @@
/* Usable with RSA, EC and HMAC keys. */
SIGN = 2,
- /* Usable with RSA, EC and HMAC keys. */
+ /* Usable with HMAC keys. */
VERIFY = 3,
/* 4 is reserved */
diff --git a/security/keymint/aidl/android/hardware/security/keymint/PaddingMode.aidl b/security/keymint/aidl/android/hardware/security/keymint/PaddingMode.aidl
index e71a9c9..6ff4b29 100644
--- a/security/keymint/aidl/android/hardware/security/keymint/PaddingMode.aidl
+++ b/security/keymint/aidl/android/hardware/security/keymint/PaddingMode.aidl
@@ -26,7 +26,7 @@
@VintfStability
@Backing(type="int")
enum PaddingMode {
- NONE = 1, /* deprecated */
+ NONE = 1,
RSA_OAEP = 2,
RSA_PSS = 3,
RSA_PKCS1_1_5_ENCRYPT = 4,
diff --git a/security/keymint/aidl/android/hardware/security/keymint/Tag.aidl b/security/keymint/aidl/android/hardware/security/keymint/Tag.aidl
index 42dfad5..871a1ac 100644
--- a/security/keymint/aidl/android/hardware/security/keymint/Tag.aidl
+++ b/security/keymint/aidl/android/hardware/security/keymint/Tag.aidl
@@ -186,10 +186,16 @@
* Tag::RSA_OAEP_MGF_DIGEST specifies the MGF1 digest algorithms that may be used with RSA
* encryption/decryption with OAEP padding. Possible values are defined by the Digest enum.
*
- * This tag is repeatable for key generation/import. RSA cipher operations with OAEP padding
- * must specify an MGF1 digest in the params argument of begin(). If this tag is missing or the
- * specified digest is not in the MGF1 digests associated with the key then begin operation must
- * fail with ErrorCode::INCOMPATIBLE_MGF_DIGEST.
+ * This tag is repeatable for key generation/import.
+ *
+ * If the caller specifies an MGF1 digest in the params argument of begin(), that digest must be
+ * present as an RSA_OAEP_MGF_DIGEST value in the key characteristics (or the begin() operation
+ * must fail with ErrorCode::INCOMPATIBLE_MGF_DIGEST).
+ *
+ * If the caller does not specify an MGF1 digest in the params argument of begin(), a default
+ * MGF1 digest of SHA1 is used. If the key characteristics have any explicitly specified values
+ * for RSA_OAEP_MGF_DIGEST, then SHA1 must be included (or the begin() operation must fail with
+ * ErrorCode::INCOMPATIBLE_MGF_DIGEST).
*
* Must be hardware-enforced.
*/
diff --git a/security/sharedsecret/aidl/android/hardware/security/sharedsecret/SharedSecretParameters.aidl b/security/sharedsecret/aidl/android/hardware/security/sharedsecret/SharedSecretParameters.aidl
index 8144699..b72f0de 100644
--- a/security/sharedsecret/aidl/android/hardware/security/sharedsecret/SharedSecretParameters.aidl
+++ b/security/sharedsecret/aidl/android/hardware/security/sharedsecret/SharedSecretParameters.aidl
@@ -33,9 +33,9 @@
byte[] seed;
/**
- * A 32-byte value which is guaranteed to be different each time
- * getSharedSecretParameters() is called. Probabilistic uniqueness (i.e. random) is acceptable,
- * though a stronger uniqueness guarantee (e.g. counter) is recommended where possible.
+ * A 32-byte value which is guaranteed to be different each time getSharedSecretParameters() is
+ * called after a restart. Probabilistic uniqueness (i.e. random) is acceptable, though a
+ * stronger uniqueness guarantee (e.g. counter) is recommended where possible.
*/
byte[] nonce;
}