tequilaOS/platform_hardware_interfaces
2
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

KeyMint HALs: clarifications

Browse source 
- 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
This commit is contained in:
David Drysdale 2021-10-06 09:59:08 +01:00
parent 19410a1fc3
commit 8d925aee2d
5 changed files with 36 additions and 19 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

29
security/keymint/aidl/android/hardware/security/keymint/IKeyMintDevice.aidl
View file

@ -336,6 +336,17 @@ interface IKeyMintDevice {
* 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 @@ interface IKeyMintDevice {
* 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 @@ interface IKeyMintDevice {
*
* -- 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 --
*

4
security/keymint/aidl/android/hardware/security/keymint/KeyPurpose.aidl
View file

@ -23,7 +23,7 @@ package android.hardware.security.keymint;
@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 @@ enum KeyPurpose {
/* 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 */

2
security/keymint/aidl/android/hardware/security/keymint/PaddingMode.aidl
View file

@ -26,7 +26,7 @@ package android.hardware.security.keymint;
@VintfStability
@Backing(type="int")
enum PaddingMode {
NONE = 1, /* deprecated */
NONE = 1,
RSA_OAEP = 2,
RSA_PSS = 3,
RSA_PKCS1_1_5_ENCRYPT = 4,

14
security/keymint/aidl/android/hardware/security/keymint/Tag.aidl
View file

@ -186,10 +186,16 @@ enum Tag {
* 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.
*/

6
security/sharedsecret/aidl/android/hardware/security/sharedsecret/SharedSecretParameters.aidl
View file

@ -33,9 +33,9 @@ parcelable SharedSecretParameters {
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;
}