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

KeyMint AIDL tweaks

Browse source 
- Describe 3DES requirements
- Remove references to non-existent getKeyCharacteristics() entrypoint
- Remove references to non-existent attestKey() entrypoint
- Remove mention of asymmetric verification operations
- Remove text describing incomplete update()
- Remove text discussing padding for ECDSA
- EC keys can't encrypt/decrypt
- Force use of curve not key size for EC keys
- Drop TODO re: CBOR encoding of wrapped key
- Indicate caller-provided nonces must have correct size
- Add more reference to IKeyMintOperation
- Align parameter names with signatures
- Correct MIN_MAC_LENGTH error code
- Make CREATION_DATETIME consistently optional
- Describe use of MGF1 digest option
- Fix typos

Test: VtsKeyMintAidlTargetTest (CF)
Change-Id: Ie01b99d33be7336e872bf24a7761a3ac5b1d584c
This commit is contained in:
David Drysdale 2021-03-05 14:58:19 +00:00
parent b4be35f854
commit 40eb8f53ea
9 changed files with 235 additions and 243 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

5
security/keymint/aidl/android/hardware/security/keymint/BeginResult.aidl
View file

@ -25,7 +25,10 @@ import android.hardware.security.keymint.KeyParameter;
*/
@VintfStability
parcelable BeginResult {
/* This is the challenge used in verifyAuthorization. It must be a nonce. */
/**
* This is the challenge used to verify authorization of an operation.
* See IKeyMintOperation.aidl entrypoints updateAad() and update().
*/
long challenge;
/**

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

@ -107,7 +107,6 @@ import android.hardware.security.secureclock.TimeStampToken;
*
* - 168-bit keys.
* - CBC and ECB mode.
* - CBC and ECB modes must support unpadded and PKCS7 padding modes. With no padding CBC and
* ECB-mode operations must fail with ErrorCode::INVALID_INPUT_LENGTH if the input isn't a
* multiple of the DES block size.
@ -150,8 +149,8 @@ import android.hardware.security.secureclock.TimeStampToken;
*
* The IKeyMintDevice must ignore unknown tags.
*
* The caller must always provide the current date time in the keyParameter CREATION_DATETIME
* tags.
* The caller may provide the current date time in the keyParameter CREATION_DATETIME tag, but
* this is optional and informational only.
*
* All authorization tags and their values enforced by an IKeyMintDevice must be cryptographically
* bound to the private/secret key material such that any modification of the portion of the key
@ -185,7 +184,7 @@ import android.hardware.security.secureclock.TimeStampToken;
* startup, preferably by the bootloader. This bitstring must be cryptographically bound to every
* key managed by the IKeyMintDevice. As above, the recommended mechanism for this cryptographic
* binding is to include the Root of Trust data in the input to the key derivation function used to
* derive a key that is used to encryp the private/secret key material.
* derive a key that is used to encrypt the private/secret key material.
*
* The root of trust consists of a bitstring that must be derived from the public key used by
* Verified Boot to verify the signature on the boot image and from the lock state of the
@ -247,7 +246,7 @@ interface IKeyMintDevice {
* Generates a new cryptographic key, specifying associated parameters, which must be
* cryptographically bound to the key. IKeyMintDevice implementations must disallow any use
* of a key in any way inconsistent with the authorizations specified at generation time. With
* respect to parameters that the secure environment cannot enforce, the secure envionment's
* respect to parameters that the secure environment cannot enforce, the secure environment's
* obligation is limited to ensuring that the unenforceable parameters associated with the key
* cannot be modified. In addition, the characteristics returned by generateKey places
* parameters correctly in the tee-enforced and strongbox-enforced lists.
@ -268,7 +267,7 @@ interface IKeyMintDevice {
*
* The following parameters are required to generate an RSA key:
*
* o Tag::Key_SIZE specifies the size of the public modulus, in bits. If omitted, generateKey
* o Tag::KEY_SIZE specifies the size of the public modulus, in bits. If omitted, generateKey
* must return ErrorCode::UNSUPPORTED_KEY_SIZE. Required values for TEE IKeyMintDevice
* implementations are 1024, 2048, 3072 and 4096. StrongBox IKeyMintDevice implementations
* must support 2048.
@ -285,7 +284,7 @@ interface IKeyMintDevice {
* except AGREE_KEY must be supported for RSA keys.
*
* o Tag::DIGEST specifies digest algorithms that may be used with the new key. TEE
* IKeyMintDevice implementatiosn must support all Digest values (see digest.aidl) for RSA
* IKeyMintDevice implementations must support all Digest values (see digest.aidl) for RSA
* keys. StrongBox IKeyMintDevice implementations must support SHA_2_256.
*
* o Tag::PADDING specifies the padding modes that may be used with the new
@ -295,11 +294,9 @@ interface IKeyMintDevice {
*
* == ECDSA Keys ==
*
* Either Tag::KEY_SIZE or Tag::EC_CURVE must be provided to generate an ECDSA key. If neither
* is provided, generateKey must return ErrorCode::UNSUPPORTED_KEY_SIZE. If Tag::KEY_SIZE is
* provided, the possible values are 224, 256, 384 and 521, and must be mapped to Tag::EC_CURVE
* values P_224, P_256, P_384 and P_521, respectively. TEE IKeyMintDevice implementations
* must support all curves. StrongBox implementations must support P_256.
* Tag::EC_CURVE must be provided to generate an ECDSA key. If it is not provided, generateKey
* must return ErrorCode::UNSUPPORTED_KEY_SIZE. TEE IKeyMintDevice implementations must support
* all curves. StrongBox implementations must support P_256.
*
* == AES Keys ==
*
@ -309,6 +306,10 @@ interface IKeyMintDevice {
* If Tag::BLOCK_MODE is specified with value BlockMode::GCM, then the caller must also provide
* Tag::MIN_MAC_LENGTH. If omitted, generateKey must return ErrorCode::MISSING_MIN_MAC_LENGTH.
*
* == 3DES Keys ==
*
* 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.
*
* @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
@ -349,13 +350,12 @@ interface IKeyMintDevice {
*
* o Tag::ORIGIN (returned in keyCharacteristics) must have the value KeyOrigin::IMPORTED.
*
* @param inKeyParams Key generation parameters are defined as KeyMintDevice tag/value pairs,
* @param keyParams Key generation parameters are defined as KeyMintDevice tag/value pairs,
* provided in params.
*
* @param inKeyFormat The format of the key material to import. See KeyFormat in
* keyformat.aidl.
* @param keyFormat The format of the key material to import. See KeyFormat in keyformat.aidl.
*
* @param inKeyData The key material to import, in the format specified in keyFormat.
* @param keyData The key material to import, in the format specified in keyFormat.
*
* @param attestationKey, if provided, specifies the key that must be used to sign the
* attestation certificate. If `keyParams` does not contain a Tag::ATTESTATION_CHALLENGE
@ -378,9 +378,8 @@ interface IKeyMintDevice {
* Securely imports a key, or key pair, returning a key blob and a description of the imported
* key.
*
* @param inWrappedKeyData The wrapped key material to import.
* TODO(seleneh) Decide if we want the wrapped key in DER-encoded ASN.1 format or CBOR
* format or both. And specify the standarized format.
* @param wrappedKeyData The wrapped key material to import, as ASN.1 DER-encoded data
* corresponding to the following schema.
*
* KeyDescription ::= SEQUENCE(
* keyFormat INTEGER, # Values from KeyFormat enum.
@ -398,20 +397,20 @@ interface IKeyMintDevice {
*
* Where:
*
* o keyFormat is an integer from the KeyFormat enum, defining the format of the plaintext
* - keyFormat is an integer from the KeyFormat enum, defining the format of the plaintext
* key material.
* o keyParams is the characteristics of the key to be imported (as with generateKey or
* - keyParams is the characteristics of the key to be imported (as with generateKey or
* importKey). If the secure import is successful, these characteristics must be
* associated with the key exactly as if the key material had been insecurely imported
* with the IKeyMintDevice::importKey. See attestKey() for documentation of the
* AuthorizationList schema.
* o encryptedTransportKey is a 256-bit AES key, XORed with a masking key and then encrypted
* with the IKeyMintDevice::importKey. See KeyCreationResult.aidl for documentation of
* the AuthorizationList schema.
* - encryptedTransportKey is a 256-bit AES key, XORed with a masking key and then encrypted
* with the wrapping key specified by wrappingKeyBlob.
* o keyDescription is a KeyDescription, above.
* o encryptedKey is the key material of the key to be imported, in format keyFormat, and
* - keyDescription is a KeyDescription, above.
* - encryptedKey is the key material of the key to be imported, in format keyFormat, and
* encrypted with encryptedEphemeralKey in AES-GCM mode, with the DER-encoded
* representation of keyDescription provided as additional authenticated data.
* o tag is the tag produced by the AES-GCM encryption of encryptedKey.
* - tag is the tag produced by the AES-GCM encryption of encryptedKey.
*
* So, importWrappedKey does the following:
*
@ -440,7 +439,7 @@ interface IKeyMintDevice {
*
* @param passwordSid specifies the password secure ID (SID) of the user that owns the key being
* installed. If the authorization list in wrappedKeyData contains a
* Tag::USER_SECURE_IDwith a value that has the HardwareAuthenticatorType::PASSWORD bit
* Tag::USER_SECURE_ID with a value that has the HardwareAuthenticatorType::PASSWORD bit
* set, the constructed key must be bound to the SID value provided by this argument. If
* the wrappedKeyData does not contain such a tag and value, this argument must be
* ignored.
@ -483,9 +482,9 @@ interface IKeyMintDevice {
* patch level and OS version. This requirement is relaxed for 4.0::IKeymasterDevice and
* IKeyMintDevice, and the OS version in the boot image footer is no longer used.
*
* @param inKeyBlobToUpgrade The opaque descriptor returned by generateKey() or importKey();
* @param keyBlobToUpgrade The opaque descriptor returned by generateKey() or importKey().
*
* @param inUpgradeParams A parameter list containing any parameters needed to complete the
* @param upgradeParams A parameter list containing any parameters needed to complete the
* upgrade, including Tag::APPLICATION_ID and Tag::APPLICATION_DATA.
*
* @return A new key blob that references the same key as keyBlobToUpgrade, but is in the new
@ -499,7 +498,9 @@ interface IKeyMintDevice {
* render the key permanently unusable. Keys without Tag::ROLLBACK_RESISTANCE may or
* may not be rendered unusable.
*
* @param inKeyBlob The opaque descriptor returned by generateKey() or importKey();
* @param keyBlob The opaque descriptor returned by generateKey() or importKey();
*
* @return error See the ErrorCode enum.
*/
void deleteKey(in byte[] keyBlob);
@ -508,8 +509,6 @@ interface IKeyMintDevice {
* this function is called all keys with Tag::ROLLBACK_RESISTANCE in their hardware-enforced
* authorization lists must be rendered permanently unusable. Keys without
* Tag::ROLLBACK_RESISTANCE may or may not be rendered unusable.
*
* @return error See the ErrorCode enum.
*/
void deleteAllKeys();
@ -528,28 +527,27 @@ interface IKeyMintDevice {
/**
* Begins a cryptographic operation using the specified key. If all is well, begin() must
* return ErrorCode::OK and create an operation handle which must be passed to subsequent calls
* to update(), finish() or abort().
* return ErrorCode::OK and create an IKeyMintOperation handle which will be used to perform
* the cryptographic operation.
*
* It is critical that each call to begin() be paired with a subsequent call to finish() or
* abort(), to allow the IKeyMintDevice implementation to clean up any internal operation
* state. The caller's failure to do this may leak internal state space or other internal
* resources and may eventually cause begin() to return ErrorCode::TOO_MANY_OPERATIONS when it
* runs out of space for operations. Any result other than ErrorCode::OK from begin(), update()
* or finish() implicitly aborts the operation, in which case abort() need not be called (and
* must return ErrorCode::INVALID_OPERATION_HANDLE if called). IKeyMintDevice implementations
* must support 32 concurrent operations.
* It is critical that each successful call to begin() be paired with a subsequent call to
* finish() or abort() on the resulting IKeyMintOperation, to allow the IKeyMintDevice
* implementation to clean up any internal operation state. The caller's failure to do this may
* leak internal state space or other internal resources and may eventually cause begin() to
* return ErrorCode::TOO_MANY_OPERATIONS when it runs out of space for operations. Any result
* other than ErrorCode::OK from begin() will not return an IKeyMintOperation (in which case
* calling finish() or abort() is neither possible nor necessary). IKeyMintDevice
* implementations must support 32 concurrent operations.
*
* If Tag::APPLICATION_ID or Tag::APPLICATION_DATA were specified during key generation or
* import, calls to begin must include those tags with the originally-specified values in the
* inParams argument to this method. If not, begin() must return ErrorCode::INVALID_KEY_BLOB.
* params argument to this method. If not, begin() must return ErrorCode::INVALID_KEY_BLOB.
*
* == Authorization Enforcement ==
*
* The following key authorization parameters must be enforced by the IKeyMintDevice secure
* environment if the tags were returned in the "hardwareEnforced" list in the
* KeyCharacteristics. Public key operations, meaning KeyPurpose::ENCRYPT and
* KeyPurpose::VERIFY must be allowed to succeed even if authorization requirements are not met.
* KeyCharacteristics.
*
* -- All Key Types --
*
@ -578,9 +576,9 @@ interface IKeyMintDevice {
*
* o Tag::USER_SECURE_ID must be enforced by this method if and only if the key also has
* Tag::AUTH_TIMEOUT (if it does not have Tag::AUTH_TIMEOUT, the Tag::USER_SECURE_ID
* requirement must be enforced by update() and finish()). If the key has both, then this
* method must receive a non-empty HardwareAuthToken in the authToken argument. For the auth
* token to be valid, all of the following have to be true:
* requirement must be enforced by updateAad(), update() and finish()). If the key has both,
* then this method must receive a non-empty HardwareAuthToken in the authToken argument. For
* the auth token to be valid, all of the following have to be true:
*
* o The HMAC field must validate correctly.
*
@ -607,32 +605,30 @@ interface IKeyMintDevice {
*
* -- RSA Keys --
*
* All RSA key operations must specify exactly one padding mode in inParams. If unspecified or
* All RSA key operations must specify exactly one padding mode in params. If unspecified or
* specified more than once, the begin() must return ErrorCode::UNSUPPORTED_PADDING_MODE.
*
* RSA signing and verification operations need a digest, as do RSA encryption and decryption
* operations with OAEP padding mode. For those cases, the caller must specify exactly one
* digest in inParams. If unspecified or specified more than once, begin() must return
* RSA signing operations need a digest, as do RSA encryption and decryption operations with
* OAEP padding mode. For those cases, the caller must specify exactly one digest in params.
* If unspecified or specified more than once, begin() must return
* ErrorCode::UNSUPPORTED_DIGEST.
*
* Private key operations (KeyPurpose::DECRYPT and KeyPurpose::SIGN) need authorization of
* digest and padding, which means that the key authorizations need to contain the specified
* values. If not, begin() must return ErrorCode::INCOMPATIBLE_DIGEST or
* ErrorCode::INCOMPATIBLE_PADDING, as appropriate. Public key operations (KeyPurpose::ENCRYPT
* and KeyPurpose::VERIFY) are permitted with unauthorized digest or padding modes.
* ErrorCode::INCOMPATIBLE_PADDING_MODE, as appropriate.
*
* With the exception of PaddingMode::NONE, all RSA padding modes are applicable only to certain
* purposes. Specifically, PaddingMode::RSA_PKCS1_1_5_SIGN and PaddingMode::RSA_PSS only
* support signing and verification, while PaddingMode::RSA_PKCS1_1_5_ENCRYPT and
* PaddingMode::RSA_OAEP only support encryption and decryption. begin() must return
* ErrorCode::UNSUPPORTED_PADDING_MODE if the specified mode does not support the specified
* purpose.
* support signing, while PaddingMode::RSA_PKCS1_1_5_ENCRYPT and PaddingMode::RSA_OAEP only
* support encryption and decryption. begin() must return ErrorCode::UNSUPPORTED_PADDING_MODE
* if the specified mode does not support the specified purpose.
*
* There are some important interactions between padding modes and digests:
*
* o PaddingMode::NONE indicates that a "raw" RSA operation is performed. If signing or
* verifying, Digest::NONE is specified for the digest. No digest is necessary for unpadded
* encryption or decryption.
* o PaddingMode::NONE indicates that a "raw" RSA operation is performed. If signing,
* Digest::NONE is specified for the digest. No digest is necessary for unpadded encryption
* or decryption.
*
* o PaddingMode::RSA_PKCS1_1_5_SIGN padding requires a digest. The digest may be Digest::NONE,
* in which case the KeyMint implementation cannot build a proper PKCS#1 v1.5 signature
@ -644,37 +640,37 @@ interface IKeyMintDevice {
*
* o PaddingMode::RSA_PKCS1_1_1_5_ENCRYPT padding does not require a digest.
*
* o PaddingMode::RSA_PSS padding requires a digest, which may not be Digest::NONE. If
* Digest::NONE is specified, the begin() must return ErrorCode::INCOMPATIBLE_DIGEST. 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.
* o PaddingMode::RSA_PSS padding requires a digest, which must match one of the padding 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.
*
* o PaddingMode::RSA_OAEP padding requires a digest, which may not be Digest::NONE. If
* Digest::NONE is specified, begin() must return ErrorCode::INCOMPATIBLE_DIGEST. The OAEP
* mask generation function must be MGF1 and the MGF1 digest must be SHA1, regardless of the
* OAEP digest specified.
* o PaddingMode::RSA_OAEP padding requires a digest, which must match one of the padding 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
* padding values in the key authorizations and which may not be Digest::NONE. begin() must
* return ErrorCode::INCOMPATIBLE_MGF_DIGEST if this is not the case. The OAEP mask generation
* function must be MGF1.
*
* -- EC Keys --
*
* EC key operations must specify exactly one padding mode in inParams. If unspecified or
* specified more than once, begin() must return ErrorCode::UNSUPPORTED_PADDING_MODE.
*
* 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. Public key operations (KeyPurpose::VERIFY) are
* permitted with unauthorized digest or padding.
* return ErrorCode::INCOMPATIBLE_DIGEST.
*
* -- AES Keys --
*
* AES key operations must specify exactly one block mode (Tag::BLOCK_MODE) and one padding mode
* (Tag::PADDING) in inParams. If either value is unspecified or specified more than once,
* (Tag::PADDING) in params. If either value is unspecified or specified more than once,
* begin() must return ErrorCode::UNSUPPORTED_BLOCK_MODE or
* ErrorCode::UNSUPPORTED_PADDING_MODE. The specified modes must be authorized by the key,
* otherwise begin() must return ErrorCode::INCOMPATIBLE_BLOCK_MODE or
* ErrorCode::INCOMPATIBLE_PADDING_MODE.
*
* If the block mode is BlockMode::GCM, inParams must specify Tag::MAC_LENGTH, and the specified
* If the block mode is BlockMode::GCM, params must specify Tag::MAC_LENGTH, and the specified
* value must be a multiple of 8 that is not greater than 128 or less than the value of
* Tag::MIN_MAC_LENGTH in the key authorizations. For MAC lengths greater than 128 or
* non-multiples of 8, begin() must return ErrorCode::UNSUPPORTED_MAC_LENGTH. For values less
@ -687,43 +683,63 @@ interface IKeyMintDevice {
*
* If the block mode is BlockMode::CBC, BlockMode::CTR, or BlockMode::GCM, an initialization
* vector or nonce is required. In most cases, callers shouldn't provide an IV or nonce and the
* IKeyMintDevice implementation must generate a random IV or nonce and return it via
* Tag::NONCE in outParams. CBC and CTR IVs are 16 bytes. GCM nonces are 12 bytes. If the key
* IKeyMintDevice implementation must generate a random IV or nonce and return it via Tag::NONCE
* in outParams. CBC and CTR IVs are 16 bytes. GCM nonces are 12 bytes. If the key
* authorizations contain Tag::CALLER_NONCE, then the caller may provide an IV/nonce with
* Tag::NONCE in inParams. If a nonce is provided when Tag::CALLER_NONCE is not authorized,
* Tag::NONCE in params, which must be of the correct size (if not, return
* ErrorCode::INVALID_NONCE). If a nonce is provided when Tag::CALLER_NONCE is not authorized,
* begin() must return ErrorCode::CALLER_NONCE_PROHIBITED. If a nonce is not provided when
* Tag::CALLER_NONCE is authorized, IKeyMintDevice msut generate a random IV/nonce.
* Tag::CALLER_NONCE is authorized, IKeyMintDevice must generate a random IV/nonce.
*
* -- 3DES Keys --
*
* 3DES key operations must specify exactly one block mode (Tag::BLOCK_MODE) and one padding
* mode (Tag::PADDING) in params. If either value is unspecified or specified more than once,
* begin() must return ErrorCode::UNSUPPORTED_BLOCK_MODE or
* ErrorCode::UNSUPPORTED_PADDING_MODE. The specified modes must be authorized by the key,
* otherwise begin() must return ErrorCode::INCOMPATIBLE_BLOCK_MODE or
* ErrorCode::INCOMPATIBLE_PADDING_MODE.
*
* If the block mode is BlockMode::CBC, an initialization vector or nonce is required. In most
* cases, callers shouldn't provide an IV or nonce and the IKeyMintDevice implementation must
* generate a random IV or nonce and return it via Tag::NONCE in outParams. CBC IVs are 8
* bytes. If the key authorizations contain Tag::CALLER_NONCE, then the caller may provide an
* IV/nonce with Tag::NONCE in params, which must be of the correct size (if not, return
* ErrorCode::INVALID_NONCE). If a nonce is provided when Tag::CALLER_NONCE is not authorized,
* begin() must return ErrorCode::CALLER_NONCE_PROHIBITED. If a nonce is not provided when
* Tag::CALLER_NONCE is authorized, IKeyMintDevice must generate a random IV/nonce.
*
*
* -- HMAC keys --
*
* HMAC key operations must specify Tag::MAC_LENGTH in inParams. The specified value must be a
* HMAC key operations must specify Tag::MAC_LENGTH in params. The specified value must be a
* multiple of 8 that is not greater than the digest length or less than the value of
* Tag::MIN_MAC_LENGTH in the key authorizations. For MAC lengths greater than the digest
* length or non-multiples of 8, begin() must return ErrorCode::UNSUPPORTED_MAC_LENGTH. For
* values less than the key's minimum length, begin() must return ErrorCode::INVALID_MAC_LENGTH.
*
* @param inPurpose The purpose of the operation, one of KeyPurpose::ENCRYPT,
* KeyPurpose::DECRYPT, KeyPurpose::SIGN, KeyPurpose::VERIFY, or KeyPurpose::AGREE_KEY.
* Note that for AEAD modes, encryption and decryption imply signing and verification,
* respectively, but must be specified as KeyPurpose::ENCRYPT and KeyPurpose::DECRYPT.
* @param purpose The purpose of the operation, one of KeyPurpose::ENCRYPT, KeyPurpose::DECRYPT,
* KeyPurpose::SIGN, KeyPurpose::VERIFY, or KeyPurpose::AGREE_KEY. Note that for AEAD
* modes, encryption and decryption imply signing and verification, respectively, but
* must be specified as KeyPurpose::ENCRYPT and KeyPurpose::DECRYPT.
*
* @param inKeyBlob The opaque key descriptor returned by generateKey() or importKey(). The key
* @param keyBlob The opaque key descriptor returned by generateKey() or importKey(). The key
* must have a purpose compatible with purpose and all of its usage requirements must be
* satisfied, or begin() must return an appropriate error code (see above).
*
* @param inParams Additional parameters for the operation. If Tag::APPLICATION_ID or
* @param params Additional parameters for the operation. If Tag::APPLICATION_ID or
* Tag::APPLICATION_DATA were provided during generation, they must be provided here, or
* the operation must fail with ErrorCode::INVALID_KEY_BLOB. For operations that require
* a nonce or IV, on keys that were generated with Tag::CALLER_NONCE, inParams may
* a nonce or IV, on keys that were generated with Tag::CALLER_NONCE, params may
* contain a tag Tag::NONCE. If Tag::NONCE is provided for a key without
* Tag:CALLER_NONCE, ErrorCode::CALLER_NONCE_PROHIBITED must be returned.
*
* @param inAuthToken Authentication token.
* @param authToken Authentication token.
*
* @return BeginResult as output, which contains the challenge, KeyParameters which haves
* additional data from the operation initialization, notably to return the IV or nonce
* from operations that generate an IV or nonce, and IKeyMintOperation object pointer
* which is used to perform update(), finish() or abort() operations.
* which is used to perform updateAad(), update(), finish() or abort() operations.
*/
BeginResult begin(in KeyPurpose purpose, in byte[] keyBlob, in KeyParameter[] params,
in @nullable HardwareAuthToken authToken);
@ -740,7 +756,7 @@ interface IKeyMintDevice {
* Note that the IKeyMintDevice UNLOCKED_DEVICE_REQUIRED semantics are slightly different from
* the UNLOCKED_DEVICE_REQUIRED semantics enforced by keystore. Keystore handles device locking
* on a per-user basis. Because auth tokens do not contain an Android user ID, it's not
* possible to replicate the keystore enformcement logic in IKeyMintDevice. So from the
* possible to replicate the keystore enforcement logic in IKeyMintDevice. So from the
* IKeyMintDevice perspective, any user unlock unlocks all UNLOCKED_DEVICE_REQUIRED keys.
* Keystore will continue enforcing the per-user device locking.
*

108
security/keymint/aidl/android/hardware/security/keymint/IKeyMintOperation.aidl
View file

@ -31,12 +31,12 @@ interface IKeyMintOperation {
* update() is called. If updateAad() is called after update(), it must return
* ErrorCode::INVALID_TAG.
*
* If operation is in an invalid state (was aborted or had an error) update() must return
* If the operation is in an invalid state (was aborted or had an error) update() must return
* ErrorCode::INVALID_OPERATION_HANDLE.
*
* If this method returns an error code other than ErrorCode::OK, the operation is aborted and
* the operation handle must be invalidated. Any future use of the handle, with this method,
* finish, or abort, must return ErrorCode::INVALID_OPERATION_HANDLE.
* the operation handle must be invalidated. Any future use of this object must return
* ErrorCode::INVALID_OPERATION_HANDLE.
*
* == Authorization Enforcement ==
*
@ -58,9 +58,10 @@ interface IKeyMintOperation {
*
* o The key must have a Tag::USER_AUTH_TYPE that matches the auth type in the token.
*
* o The challenge field in the auth token must contain the operationHandle
* o The challenge field in the auth token must contain the value returned from
* IKeyMintDevice::begin(), given by the challenge field of the BeginResult structure.
*
* If any of these conditions are not met, update() must return
* If any of these conditions are not met, updateAad() must return
* ErrorCode::KEY_USER_NOT_AUTHENTICATED.
*
* The caller must provide the auth token on every call to updateAad(), update() and finish().
@ -74,7 +75,7 @@ interface IKeyMintOperation {
*
* @param input Additional Authentication Data to be processed.
*
* @param authToken Authentication token. Can be nullable if not provided.
* @param authToken Authentication token, if provided.
*
* @param timeStampToken timestamp token, certifies the freshness of an auth token in case
* the security domain of this KeyMint instance has a different clock than the
@ -93,18 +94,9 @@ interface IKeyMintOperation {
* If operation is in an invalid state (was aborted or had an error) update() must return
* ErrorCode::INVALID_OPERATION_HANDLE.
*
* To provide more flexibility for buffer handling, implementations of this method have the
* option of consuming less data than was provided. The caller is responsible for looping to
* feed the rest of the data in subsequent calls. The amount of input consumed must be returned
* in the inputConsumed parameter. Implementations must always consume at least one byte,
* unless the operation cannot accept any more; if more than zero bytes are provided and zero
* bytes are consumed, callers must consider this an error and abort the operation.
* TODO(seleneh) update the code to always consume alll the input data. b/168665179.
*
* Implementations may also choose how much data to return, as a result of the update. This is
* only relevant for encryption and decryption operations, because signing and verification
* return no data until finish. It is recommended to return data as early as possible, rather
* than buffer it.
* Implementations may choose how much data to return as a result of the update. This is
* only relevant for encryption and decryption operations, because signing returns no data
* until finish. It is recommended to return data as early as possible, rather than buffer it.
*
* If this method returns an error code other than ErrorCode::OK, the operation is aborted and
* the operation handle must be invalidated. Any future use of the handle, with this method,
@ -112,8 +104,8 @@ interface IKeyMintOperation {
*
* == Authorization Enforcement ==
*
* Key authorization enforcement is performed primarily in begin(). The one exception is the
* case where the key has:
* Key authorization enforcement is performed primarily in IKeyMintDevice::begin(). The one
* exception is the case where the key has:
*
* o One or more Tag::USER_SECURE_IDs, and
*
@ -130,7 +122,8 @@ interface IKeyMintOperation {
*
* o The key must have a Tag::USER_AUTH_TYPE that matches the auth type in the token.
*
* o The challenge field in the auth token must contain the operationHandle
* o The challenge field in the auth token must contain the challenge value contained in the
* BeginResult returned from IKeyMintDevice::begin().
*
* If any of these conditions are not met, update() must return
* ErrorCode::KEY_USER_NOT_AUTHENTICATED.
@ -139,22 +132,20 @@ interface IKeyMintOperation {
*
* -- RSA keys --
*
* For signing and verification operations with Digest::NONE, this method must accept the entire
* block to be signed or verified in a single update. It may not consume only a portion of the
* block in these cases. However, the caller may choose to provide the data in multiple
* updates, and update() must accept the data this way as well. If the caller provides more
* data to sign than can be used (length of data exceeds RSA key size), update() must return
* ErrorCode::INVALID_INPUT_LENGTH.
* For signing operations with Digest::NONE, this method must accept the entire block to be
* signed in a single update. It may not consume only a portion of the block in these cases.
* However, the caller may choose to provide the data in multiple updates, and update() must
* accept the data this way as well. If the caller provides more data to sign than can be used
* (length of data exceeds RSA key size), update() must return ErrorCode::INVALID_INPUT_LENGTH.
*
* -- ECDSA keys --
*
* For signing and verification operations with Digest::NONE, this method must accept the entire
* block to be signed or verified in a single update. This method may not consume only a
* portion of the block. However, the caller may choose to provide the data in multiple updates
* and update() must accept the data this way as well. If the caller provides more data to sign
* than can be used, the data is silently truncated. (This differs from the handling of excess
* data provided in similar RSA operations. The reason for this is compatibility with legacy
* clients.)
* For signing operations with Digest::NONE, this method must accept the entire block to be
* signed in a single update. This method may not consume only a portion of the block.
* However, the caller may choose to provide the data in multiple updates and update() must
* accept the data this way as well. If the caller provides more data to sign than can be used,
* the data is silently truncated. (This differs from the handling of excess data provided in
* similar RSA operations. The reason for this is compatibility with legacy clients.)
*
* -- AES keys --
*
@ -182,7 +173,7 @@ interface IKeyMintOperation {
in @nullable TimeStampToken timeStampToken);
/**
* Finalizes a cryptographic operation begun with begin() and invalidates operation.
* Finalizes a cryptographic operation begun with begin() and invalidates the operation.
*
* This method is the last one called in an operation, so all processed data must be returned.
*
@ -190,8 +181,7 @@ interface IKeyMintOperation {
* Any future use of the operation, with finish(), update(), or abort(), must return
* ErrorCode::INVALID_OPERATION_HANDLE.
*
* Signing operations return the signature as the output. Verification operations accept the
* signature in the signature parameter, and return no output.
* Signing operations return the signature as the output.
*
* == Authorization enforcement ==
*
@ -230,44 +220,35 @@ interface IKeyMintOperation {
* Some additional requirements, depending on the padding mode:
*
* o PaddingMode::NONE. For unpadded signing and encryption operations, if the provided data is
* shorter than the key, the data must be zero-padded on the left before
* signing/encryption. If the data is the same length as the key, but numerically larger,
* finish() must return ErrorCode::INVALID_ARGUMENT. For verification and decryption
* operations, the data must be exactly as long as the key. Otherwise, return
* ErrorCode::INVALID_INPUT_LENGTH.
* shorter than the key, the data must be zero-padded on the left before signing/encryption.
* If the data is the same length as the key, but numerically larger, finish() must return
* ErrorCode::INVALID_ARGUMENT. For decryption operations, the data must be exactly as long
* as the key. Otherwise, return ErrorCode::INVALID_INPUT_LENGTH.
*
* o PaddingMode::RSA_PSS. For PSS-padded signature operations, the PSS salt length must match
* the size of the PSS digest selected. The digest specified with Tag::DIGEST in inputParams
* the size of the PSS digest selected. The digest specified with Tag::DIGEST in params
* on begin() must be used as the PSS digest algorithm, MGF1 must be used as the mask
* generation function and SHA1 must be used as the MGF1 digest algorithm.
*
* o PaddingMode::RSA_OAEP. The digest specified with Tag::DIGEST in inputParams on begin is
* used as the OAEP digest algorithm, MGF1 must be used as the mask generation function and
* and SHA1 must be used as the MGF1 digest algorithm.
*
* -- ECDSA keys --
*
* If the data provided for unpadded signing or verification is too long, truncate it.
* If the data provided for undigested signing is too long, truncate it.
*
* -- AES keys --
*
* Some additional conditions, depending on block mode:
*
* o BlockMode::ECB or BlockMode::CBC. If padding is PaddingMode::NONE and the data length is
* not a multiple of the AES block size, finish() must return
* ErrorCode::INVALID_INPUT_LENGTH. If padding is PaddingMode::PKCS7, pad the data per the
* PKCS#7 specification, including adding an additional padding block if the data is a multiple
* of the block length.
* not a multiple of the AES block size, finish() must return
* ErrorCode::INVALID_INPUT_LENGTH. If padding is PaddingMode::PKCS7, pad the data per the
* PKCS#7 specification, including adding an additional padding block if the data is a
* multiple of the block length.
*
* o BlockMode::GCM. During encryption, after processing all plaintext, compute the tag
* (Tag::MAC_LENGTH bytes) and append it to the returned ciphertext. During decryption,
* process the last Tag::MAC_LENGTH bytes as the tag. If tag verification fails, finish()
* must return ErrorCode::VERIFICATION_FAILED.
*
* TODO: update() will need to be refactored into 2 function. b/168665179.
*
* @param inParams Additional parameters for the operation.
*
* @param input Data to be processed, per the parameters established in the call to begin().
* finish() must consume all provided data or return ErrorCode::INVALID_INPUT_LENGTH.
*
@ -281,11 +262,9 @@ interface IKeyMintOperation {
* token.
*
* @param confirmationToken is the confirmation token required by keys with
* Tag::TRUSTED_CONFIRMATION_REQUIRED.
* Tag::TRUSTED_CONFIRMATION_REQUIRED.
*
* @return The output data, if any.
*
* @return outParams Any output parameters generated by finish().
*/
byte[] finish(in @nullable byte[] input, in @nullable byte[] signature,
in @nullable HardwareAuthToken authToken,
@ -293,13 +272,10 @@ interface IKeyMintOperation {
in @nullable byte[] confirmationToken);
/**
* Aborts a cryptographic operation begun with begin(), freeing all internal resources. If an
* operation was finalized, calling update, finish, or abort yields
* ErrorCode::INVALID_OPERATION_HANDLE. An operation is finalized if finish or abort was
* called on it, or if update returned an ErrorCode.
*
* @param operationHandle The operation handle returned by begin(). This handle must be
* invalid when abort() returns.
* Aborts a cryptographic operation begun with IKeyMintDevice::begin(), freeing all internal
* resources. If an operation was finalized, calling updateAad, update, finish, or abort yields
* ErrorCode::INVALID_OPERATION_HANDLE. An operation is finalized if finish or abort was called
* on it, or if updateAad or update returned an ErrorCode.
*
* @return error See the ErrorCode enum in ErrorCode.aidl.
*/

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

@ -78,7 +78,7 @@ import android.hardware.security.keymint.RpcHardwareInfo;
* While a proper BCC, as described above, reflects the complete boot sequence from boot ROM to the
* secure area image of the IRemotelyProvisionedComponent, it's also possible to use a "degenerate"
* BCC which consists only of a single, self-signed certificate containing the public key of a
* hardware-bound key pair. This is an appopriate solution for devices which haven't implemented
* hardware-bound key pair. This is an appropriate solution for devices which haven't implemented
* everything necessary to produce a proper BCC, but can derive a unique key pair in the secure
* area. In this degenerate case, DK_pub is the same as KM_pub.
*

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

@ -58,7 +58,7 @@ parcelable KeyCreationResult {
* There are a few variations in what is contained in `certificateChain`, depending on whether
* the caller requested attestation, whether they provided an attestation key (via the
* `attestationKey` parameter of `generateKey()`, `importKey()` or `importWrappedKey()`), and in
* the non-attestaion case, whether the key can self-sign.
* the non-attestation case, whether the key can self-sign.
*
* 1. Asymmetric key attestation with factory key. If Tag::ATTESTATION_CHALLENGE is provided
* and the `attestationKey` parameter on the generate/import call is null, the returned
@ -70,7 +70,7 @@ parcelable KeyCreationResult {
* attestation keys.
*
* 2. Asymmetric key attestation with caller-provided key. If Tag::ATTESTATION_CHALLENGE is
* provided and the `attestationKey` parameter on the generat/import call is non-null and
* provided and the `attestationKey` parameter on the generate/import call is non-null and
* contains the key blob of a key with KeyPurpose::ATTEST_KEY, the returned certificate
* chain must contain only an attestation certificate signed with the specified key. The
* caller must know the certificate chain for the provided key. Tag::

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

@ -20,7 +20,7 @@ package android.hardware.security.keymint;
* The origin of a key (or pair), i.e. where it was generated. Note that ORIGIN can be found in
* either the hardware-enforced or software-enforced list for a key, indicating whether the key is
* hardware or software-based. Specifically, a key with GENERATED in the hardware-enforced list
* must be guaranteed never to have existed outide the secure hardware.
* must be guaranteed never to have existed outside the secure hardware.
* @hide
*/
@VintfStability

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

@ -23,10 +23,10 @@ package android.hardware.security.keymint;
@VintfStability
@Backing(type="int")
enum KeyPurpose {
/* Usable with RSA, EC and AES keys. */
/* Usable with RSA, 3DES and AES keys. */
ENCRYPT = 0,
/* Usable with RSA, EC and AES keys. */
/* Usable with RSA, 3DES and AES keys. */
DECRYPT = 1,
/* Usable with RSA, EC and HMAC keys. */
@ -36,6 +36,7 @@ enum KeyPurpose {
VERIFY = 3,
/* 4 is reserved */
/* Usable with wrapping keys. */
WRAP_KEY = 5,

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

@ -19,7 +19,7 @@ package android.hardware.security.keymint;
import android.hardware.security.keymint.TagType;
// TODO(seleneh) : note aidl currently does not support double nested enum definitions such as
// ROOT_OF_TRUST = TagType:BYTES | 704. So we are forced to write definations as
// ROOT_OF_TRUST = TagType:BYTES | 704. So we are forced to write definitions as
// ROOT_OF_TRUST = (9 << 28) for now. Will need to flip this back later when aidl support is added.
/**
@ -59,7 +59,7 @@ enum Tag {
ALGORITHM = (1 << 28) /* TagType:ENUM */ | 2,
/**
* Tag::KEY_SIZE pecifies the size, in bits, of the key, measuring in the normal way for the
* Tag::KEY_SIZE specifies the size, in bits, of the key, measuring in the normal way for the
* key's algorithm. For example, for RSA keys, Tag::KEY_SIZE specifies the size of the public
* modulus. For AES keys it specifies the length of the secret key material. For 3DES keys it
* specifies the length of the key material, not counting parity bits (though parity bits must
@ -75,9 +75,9 @@ enum Tag {
* is only relevant to AES and 3DES keys. Possible values are defined by the BlockMode enum.
*
* This tag is repeatable for key generation/import. For AES and 3DES operations the caller
* must specify a Tag::BLOCK_MODE in the additionalParams argument of begin(). If the mode is
* missing or the specified mode is not in the modes specified for the key during
* generation/import, the operation must fail with ErrorCode::INCOMPATIBLE_BLOCK_MODE.
* must specify a Tag::BLOCK_MODE in the params argument of begin(). If the mode is missing or
* the specified mode is not in the modes specified for the key during generation/import, the
* operation must fail with ErrorCode::INCOMPATIBLE_BLOCK_MODE.
*
* Must be hardware-enforced.
*/
@ -89,9 +89,9 @@ enum Tag {
* values are defined by the Digest enum.
*
* This tag is repeatable for key generation/import. For signing and verification operations,
* the caller must specify a digest in the additionalParams argument of begin(). If the digest
* is missing or the specified digest is not in the digests associated with the key, the
* operation must fail with ErrorCode::INCOMPATIBLE_DIGEST.
* the caller must specify a digest in the params argument of begin(). If the digest is missing
* or the specified digest is not in the digests associated with the key, the operation must
* fail with ErrorCode::INCOMPATIBLE_DIGEST.
*
* Must be hardware-enforced.
*/
@ -145,7 +145,7 @@ enum Tag {
* This value is the minimum MAC length, in bits. It must be a multiple of 8 bits. For HMAC
* keys, the value must be least 64 and no more than 512. For GCM keys, the value must be at
* least 96 and no more than 128. If the provided value violates these requirements,
* generateKey() or importKey() must return ErrorCode::UNSUPPORTED_KEY_SIZE.
* generateKey() or importKey() must return ErrorCode::UNSUPPORTED_MIN_MAC_LENGTH.
*
* Must be hardware-enforced.
*/
@ -154,9 +154,8 @@ enum Tag {
// Tag 9 reserved
/**
* Tag::EC_CURVE specifies the elliptic curve. EC key generation requests may have
* Tag:EC_CURVE, Tag::KEY_SIZE, or both. If both are provided and the size and curve do not
* match, IKeyMintDevice must return ErrorCode::INVALID_ARGUMENT.
* Tag::EC_CURVE specifies the elliptic curve. Possible values are defined in the EcCurve
* enumeration.
*
* Must be hardware-enforced.
*/
@ -188,16 +187,13 @@ enum Tag {
INCLUDE_UNIQUE_ID = (7 << 28) /* TagType:BOOL */ | 202,
/**
* Tag::RSA_OAEP_MGF_DIGEST specifies the MGF1 digest algorithms that may be used with
* RSA encryption/decryption with OAEP padding. If the key characteristics supports OAEP
* and this tag is absent then SHA1 digest is selected by default for MGF1.
* 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. If this tag is present in the key
* characteristics with one or more values from @4.0::Digest, then for RSA cipher
* operations with OAEP Padding, the caller must specify a digest in the additionalParams
* argument of begin operation. If this tag is missing or the specified digest is not in
* the digests associated with the key then begin operation must fail with
* ErrorCode::INCOMPATIBLE_MGF_DIGEST.
* 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.
*
* Must be hardware-enforced.
*/
@ -226,7 +222,7 @@ enum Tag {
* ErrorCode::ROLLBACK_RESISTANCE_UNAVAILABLE. IKeyMintDevice implementations are not
* required to support rollback resistance.
*
* Must be hardwared-enforced.
* Must be hardware-enforced.
*/
ROLLBACK_RESISTANCE = (7 << 28) /* TagType:BOOL */ | 303,
@ -236,7 +232,7 @@ enum Tag {
/**
* Keys tagged with EARLY_BOOT_ONLY may only be used during early boot, until
* IKeyMintDevice::earlyBootEnded() is called. Early boot keys may be created after
* early boot. Early boot keys may not be imprted at all, if Tag::EARLY_BOOT_ONLY is
* early boot. Early boot keys may not be imported at all, if Tag::EARLY_BOOT_ONLY is
* provided to IKeyMintDevice::importKey, the import must fail with
* ErrorCode::INVALID_ARGUMENT.
*/
@ -292,7 +288,7 @@ enum Tag {
* with ErrorCode::KEY_RATE_LIMIT_EXCEEDED. This implies that the IKeyMintDevice must keep a
* table of use counters for keys with this tag. Because memory is often limited, this table
* may have a fixed maximum size and KeyMint may fail operations that attempt to use keys with
* this tag when the table is full. The table must acommodate at least 8 in-use keys and
* this tag when the table is full. The table must accommodate at least 8 in-use keys and
* aggressively reuse table slots when key minimum-usage intervals expire. If an operation
* fails because the table is full, KeyMint returns ErrorCode::TOO_MANY_OPERATIONS.
*
@ -312,7 +308,7 @@ enum Tag {
* device is restarted. This implies that the IKeyMintDevice must keep a table of use
* counters for keys with this tag. Because KeyMint memory is often limited, this table can
* have a fixed maximum size and KeyMint can fail operations that attempt to use keys with
* this tag when the table is full. The table needs to acommodate at least 8 keys. If an
* this tag when the table is full. The table needs to accommodate at least 8 keys. If an
* operation fails because the table is full, IKeyMintDevice must
* ErrorCode::TOO_MANY_OPERATIONS.
*
@ -371,14 +367,14 @@ enum Tag {
* key, and may only be used if the difference between the current time when begin() is called
* and the timestamp in the HardwareAuthToken is less than the value in Tag::AUTH_TIMEOUT * 1000
* (the multiplier is because Tag::AUTH_TIMEOUT is in seconds, but the HardwareAuthToken
* timestamp is in milliseconds). Otherwise the IKeyMintDevice must returrn
* timestamp is in milliseconds). Otherwise the IKeyMintDevice must return
* ErrorCode::KEY_USER_NOT_AUTHENTICATED.
*
* If Tag::AUTH_TIMEOUT is not present, then the key is an "auth-per-operation" key. In this
* case, begin() must not require a HardwareAuthToken with appropriate contents. Instead,
* update() and finish() must receive a HardwareAuthToken with Tag::USER_SECURE_ID value in
* userId or authenticatorId fields, and the current operation's operation handle in the
* challenge field. Otherwise the IKeyMintDevice must returrn
* challenge field. Otherwise the IKeyMintDevice must return
* ErrorCode::KEY_USER_NOT_AUTHENTICATED.
*
* This tag is repeatable. If repeated, and any one of the values matches the HardwareAuthToken
@ -419,7 +415,7 @@ enum Tag {
/**
* Tag::AUTH_TIMEOUT specifies the time in seconds for which the key is authorized for use,
* after user authentication. If
* Tag::USER_SECURE_ID is present and this tag is not, then the key requies authentication for
* Tag::USER_SECURE_ID is present and this tag is not, then the key requires authentication for
* every usage (see begin() for the details of the authentication-per-operation flow).
*
* The value is a 32-bit integer specifying the time in seconds after a successful
@ -489,7 +485,7 @@ enum Tag {
* Tag::TRUSTED_CONFIRMATION_REQUIRED is only applicable to keys with KeyPurpose SIGN, and
* specifies that this key must not be usable unless the user provides confirmation of the data
* to be signed. Confirmation is proven to keyMint via an approval token. See
* CONFIRMATION_TOKEN, as well as the ConfirmatinUI HAL.
* CONFIRMATION_TOKEN, as well as the ConfirmationUI HAL.
*
* 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
@ -509,10 +505,10 @@ enum Tag {
/**
* Tag::APPLICATION_ID. When provided to generateKey or importKey, this tag specifies data
* that is necessary during all uses of the key. In particular, calls to exportKey() and
* getKeyCharacteristics() must provide the same value to the clientId parameter, and calls to
* begin must provide this tag and the same associated data as part of the inParams set. If
* the correct data is not provided, the method must return ErrorCode::INVALID_KEY_BLOB.
* that is necessary during all uses of the key. In particular, calls to exportKey() must
* provide the same value to the clientId parameter, and calls to begin() must provide this
* tag and the same associated data as part of the inParams set. If the correct data is not
* provided, the method must return ErrorCode::INVALID_KEY_BLOB.
*
* The content of this tag must be bound to the key cryptographically, meaning it must not be
* possible for an adversary who has access to all of the secure world secrets but does not have
@ -535,7 +531,7 @@ enum Tag {
* provide this tag and the same associated data as part of the inParams set. If the correct
* data is not provided, the method must return ErrorCode::INVALID_KEY_BLOB.
*
* The content of this tag msut be bound to the key cryptographically, meaning it must not be
* The content of this tag must be bound to the key cryptographically, meaning it must not be
* possible for an adversary who has access to all of the secure world secrets but does not have
* 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.
@ -546,10 +542,9 @@ enum Tag {
/**
* Tag::CREATION_DATETIME specifies the date and time the key was created, in milliseconds since
* January 1, 1970. This tag is optional and informational only.
* January 1, 1970. This tag is optional and informational only, and not enforced by anything.
*
* Tag::CREATED is informational only, and not enforced by anything. Must be in the
* software-enforced list, if provided.
* Must be in the software-enforced list, if provided.
*/
CREATION_DATETIME = (6 << 28) /* TagType:DATE */ | 701,
@ -578,8 +573,8 @@ enum Tag {
* Tag::OS_VERSION specifies the system OS version with which the key may be used. This tag is
* never sent to the IKeyMintDevice, but is added to the hardware-enforced authorization list
* by the TA. Any attempt to use a key with a Tag::OS_VERSION value different from the
* currently-running OS version must cause begin(), getKeyCharacteristics() or exportKey() to
* return ErrorCode::KEY_REQUIRES_UPGRADE. See upgradeKey() for details.
* currently-running OS version must cause begin() or exportKey() to return
* ErrorCode::KEY_REQUIRES_UPGRADE. See upgradeKey() for details.
*
* The value of the tag is an integer of the form MMmmss, where MM is the major version number,
* mm is the minor version number, and ss is the sub-minor version number. For example, for a
@ -601,9 +596,8 @@ enum Tag {
* Tag::OS_PATCHLEVEL specifies the system security patch level with which the key may be used.
* This tag is never sent to the keyMint TA, but is added to the hardware-enforced
* authorization list by the TA. Any attempt to use a key with a Tag::OS_PATCHLEVEL value
* different from the currently-running system patchlevel must cause begin(),
* getKeyCharacteristics() or exportKey() to return ErrorCode::KEY_REQUIRES_UPGRADE. See
* upgradeKey() for details.
* different from the currently-running system patchlevel must cause begin() or
* exportKey() to return ErrorCode::KEY_REQUIRES_UPGRADE. See upgradeKey() for details.
*
* The value of the tag is an integer of the form YYYYMM, where YYYY is the four-digit year of
* the last update and MM is the two-digit month of the last update. For example, for a key
@ -635,10 +629,11 @@ enum Tag {
* Tag::CREATION_DATETIME by 2592000000, dropping any remainder. T changes every 30 days
* (2592000000 = 30 * 24 * 60 * 60 * 1000).
*
* C is the value of Tag::ATTESTATION_APPLICATION_ID that is provided to attestKey().
* C is the value of Tag::ATTESTATION_APPLICATION_ID that is provided to attested key
* generation/import operations.
*
* R is 1 if Tag::RESET_SINCE_ID_ROTATION was provided to attestKey or 0 if the tag was not
* provided.
* R is 1 if Tag::RESET_SINCE_ID_ROTATION was provided to attested key generation/import or 0
* if the tag was not provided.
*
* HBK is a unique hardware-bound secret known to the secure environment and never revealed
* by it. The secret must contain at least 128 bits of entropy and be unique to the
@ -653,9 +648,9 @@ enum Tag {
UNIQUE_ID = (9 << 28) /* TagType:BYTES */ | 707,
/**
* Tag::ATTESTATION_CHALLENGE is used to deliver a "challenge" value to the attestKey() method,
* which must place the value in the KeyDescription SEQUENCE of the attestation extension. See
* attestKey().
* Tag::ATTESTATION_CHALLENGE is used to deliver a "challenge" value to the attested key
* generation/import methods, which must place the value in the KeyDescription SEQUENCE of the
* attestation extension.
*
* Must never appear in KeyCharacteristics.
*/
@ -663,7 +658,7 @@ enum Tag {
/**
* Tag::ATTESTATION_APPLICATION_ID identifies the set of applications which may use a key, used
* only with attestKey().
* only with attested key generation/import operations.
*
* The content of Tag::ATTESTATION_APPLICATION_ID is a DER-encoded ASN.1 structure, with the
* following schema:
@ -689,8 +684,8 @@ enum Tag {
/**
* Tag::ATTESTATION_ID_BRAND provides the device's brand name, as returned by Build.BRAND in
* Android, to attestKey(). This field must be set only when requesting attestation of the
* device's identifiers.
* Android, to attested key generation/import operations. 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
@ -702,8 +697,8 @@ enum Tag {
/**
* Tag::ATTESTATION_ID_DEVICE provides the device's device name, as returned by Build.DEVICE in
* Android, to attestKey(). This field must be set only when requesting attestation of the
* device's identifiers.
* Android, to attested key generation/import operations. 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
@ -715,8 +710,8 @@ enum Tag {
/**
* Tag::ATTESTATION_ID_PRODUCT provides the device's product name, as returned by Build.PRODUCT
* in Android, to attestKey(). This field must be set only when requesting attestation of the
* device's identifiers.
* in Android, to attested key generation/import operations. 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
@ -739,8 +734,9 @@ enum Tag {
ATTESTATION_ID_SERIAL = (9 << 28) /* TagType:BYTES */ | 713,
/**
* Tag::ATTESTATION_ID_IMEI provides the IMEIs for all radios on the device to attestKey().
* This field must be set only when requesting attestation of the device's identifiers.
* Tag::ATTESTATION_ID_IMEI provides the IMEIs for all radios on the device to attested key
* generation/import operations. 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
@ -751,8 +747,9 @@ enum Tag {
ATTESTATION_ID_IMEI = (9 << 28) /* TagType:BYTES */ | 714,
/**
* Tag::ATTESTATION_ID_MEID provides the MEIDs for all radios on the device to attestKey().
* This field must be set only when requesting attestation of the device's identifiers.
* Tag::ATTESTATION_ID_MEID provides the MEIDs for all radios on the device to attested key
* generation/import operations. 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
@ -764,8 +761,8 @@ enum Tag {
/**
* Tag::ATTESTATION_ID_MANUFACTURER provides the device's manufacturer name, as returned by
* Build.MANUFACTURER in Android, to attstKey(). This field must be set only when requesting
* attestation of the device's identifiers.
* Build.MANUFACTURER in Android, to attested key generation/import operations. 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
@ -777,8 +774,8 @@ enum Tag {
/**
* Tag::ATTESTATION_ID_MODEL provides the device's model name, as returned by Build.MODEL in
* Android, to attestKey(). This field must be set only when requesting attestation of the
* device's identifiers.
* Android, to attested key generation/import operations. 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
@ -792,9 +789,8 @@ enum Tag {
* Tag::VENDOR_PATCHLEVEL specifies the vendor image security patch level with which the key may
* be used. This tag is never sent to the keyMint TA, but is added to the hardware-enforced
* authorization list by the TA. Any attempt to use a key with a Tag::VENDOR_PATCHLEVEL value
* different from the currently-running system patchlevel must cause begin(),
* getKeyCharacteristics() or exportKey() to return ErrorCode::KEY_REQUIRES_UPGRADE. See
* upgradeKey() for details.
* different from the currently-running system patchlevel must cause begin() or
* exportKey() to return ErrorCode::KEY_REQUIRES_UPGRADE. See upgradeKey() for details.
*
* The value of the tag is an integer of the form YYYYMMDD, where YYYY is the four-digit year of
* the last update, MM is the two-digit month and DD is the two-digit day of the last
@ -815,8 +811,8 @@ enum Tag {
* key may be used. This tag is never sent to the keyMint TA, but is added to the
* hardware-enforced authorization list by the TA. Any attempt to use a key with a
* Tag::BOOT_PATCHLEVEL value different from the currently-running system patchlevel must
* cause begin(), getKeyCharacteristics() or exportKey() to return
* ErrorCode::KEY_REQUIRES_UPGRADE. See upgradeKey() for details.
* cause begin() or exportKey() to return ErrorCode::KEY_REQUIRES_UPGRADE. See upgradeKey() for
* details.
*
* The value of the tag is an integer of the form YYYYMMDD, where YYYY is the four-digit year of
* the last update, MM is the two-digit month and DD is the two-digit day of the last
@ -824,20 +820,20 @@ enum Tag {
* the value would be 20180605. If the day is not known, 00 may be substituted.
*
* During each boot, the bootloader must provide the patch level of the boot image to the secure
* envirionment (mechanism is implementation-defined).
* environment (mechanism is implementation-defined).
*
* Must be hardware-enforced.
*/
BOOT_PATCHLEVEL = (3 << 28) /* TagType:UINT */ | 719,
/**
* DEVICE_UNIQUE_ATTESTATION is an argument to IKeyMintDevice::attestKey(). It indicates that
* attestation using a device-unique key is requested, rather than a batch key. When a
* device-unique key is used, only the attestation certificate is returned; no additional
* chained certificates are provided. It's up to the caller to recognize the device-unique
* signing key. Only SecurityLevel::STRONGBOX IKeyMintDevices may support device-unique
* attestations. SecurityLevel::TRUSTED_ENVIRONMENT IKeyMintDevices must return
* ErrorCode::INVALID_ARGUMENT if they receive DEVICE_UNIQUE_ATTESTATION.
* DEVICE_UNIQUE_ATTESTATION is an argument to IKeyMintDevice::attested key generation/import
* operations. It indicates that attestation using a device-unique key is requested, rather
* than a batch key. When a device-unique key is used, only the attestation certificate is
* returned; no additional chained certificates are provided. It's up to the caller to
* recognize the device-unique signing key. Only SecurityLevel::STRONGBOX IKeyMintDevices may
* support device-unique attestations. SecurityLevel::TRUSTED_ENVIRONMENT IKeyMintDevices must
* return ErrorCode::INVALID_ARGUMENT if they receive DEVICE_UNIQUE_ATTESTATION.
* SecurityLevel::STRONGBOX IKeyMintDevices need not support DEVICE_UNIQUE_ATTESTATION, and
* return ErrorCode::CANNOT_ATTEST_IDS if they do not support it.
*

2
security/secureclock/aidl/android/hardware/security/secureclock/TimeStampToken.aidl
View file

@ -43,7 +43,7 @@ parcelable TimeStampToken {
*
* where:
*
* ``ISecureClock.TIME_STAMP_MAC_LABEL'' is a sting constant defined in ISecureClock.aidl.
* ``ISecureClock.TIME_STAMP_MAC_LABEL'' is a string constant defined in ISecureClock.aidl.
*
* ``H'' is the shared HMAC key (see computeSharedHmac() in ISharedSecret).
*