Package: android.hardware.keymaster@4.0

types

Properties

Timestamp

typedef uint64_t Timestamp

Time in milliseconds since some arbitrary point in time.Time must be monotonically increasing, and a secure environment's notion of "current time" must not repeat until the Android device reboots, or until at least 50 million years have elapsed(note that this requirement is satisfied by setting the clock to zero during each boot, and then counting time accurately).

OperationHandle

typedef uint64_t OperationHandle

Constants

enum Constants: uint32_t

A place to define any needed constants.

Details
Members
AUTH_TOKEN_MAC_LENGTH = 32

TagType

enum TagType: uint32_t
Details
Members
INVALID = 0 << 28
Invalid type, used to designate a tag as uninitialized.
ENUM = 1 << 28
Enumeration value.
ENUM_REP = 2 << 28
Repeatable enumeration value.
UINT = 3 << 28
32-bit unsigned integer.
UINT_REP = 4 << 28
Repeatable 32-bit unsigned integer.
ULONG = 5 << 28
64-bit unsigned integer.
DATE = 6 << 28
64-bit unsigned integer representing a date and time, in milliseconds since 1 Jan 1970.
BOOL = 7 << 28
Boolean.If a tag with this type is present, the value is "true".If absent, "false".
BIGNUM = 8 << 28
Byte string containing an arbitrary-length integer, big-endian ordering.
BYTES = 9 << 28
Byte string
ULONG_REP = 10 << 28
Repeatable 64-bit unsigned integer

Tag

enum Tag: uint32_t
Details
Members
INVALID = TagType : INVALID | 0
PURPOSE = TagType : ENUM_REP | 1
Tag::PURPOSE specifies the set of purposes for which the key may be used.Possible values are defined in the KeyPurpose enumeration.
This tag is repeatable;keys may be generated with multiple values, although an operation has a single purpose.When begin() is called to start an operation, the purpose of the operation is specified.If the purpose specified for the operation is not authorized by the key(the key didn't have a corresponding Tag::PURPOSE provided during generation/import), the operation must fail with ErrorCode::INCOMPATIBLE_PURPOSE.
Must be hardware-enforced.
ALGORITHM = TagType : ENUM | 2
Tag::ALGORITHM specifies the cryptographic algorithm with which the key is used.This tag must be provided to generateKey and importKey, and must be specified in the wrapped key provided to importWrappedKey.
Must be hardware-enforced.
KEY_SIZE = TagType : UINT | 3
Tag::KEY_SIZE pecifies 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 be provided for import, etc .). Since only three-key 3DES keys are supported, 3DES Tag::KEY_SIZE must be 168.
Must be hardware-enforced.
BLOCK_MODE = TagType : ENUM_REP | 4
Tag::BLOCK_MODE specifies the block cipher mode(s)with which the key may be used.This 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 be hardware-enforced.
DIGEST = TagType : ENUM_REP | 5
Tag::DIGEST specifies the digest algorithms that may be used with the key to perform signing and verification operations.This tag is relevant to RSA, ECDSA and HMAC keys.Possible 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.
Must be hardware-enforced.
PADDING = TagType : ENUM_REP | 6
Tag::PADDING specifies the padding modes that may be used with the key.This tag is relevant to RSA, AES and 3DES keys.Possible values are defined by the PaddingMode enum.
PaddingMode::RSA_OAEP and PaddingMode::RSA_PKCS1_1_5_ENCRYPT are used only for RSA encryption/decryption keys and specify RSA OAEP padding and RSA PKCS#1 v1.5 randomized padding, respectively.PaddingMode::RSA_PSS and PaddingMode::RSA_PKCS1_1_5_SIGN are used only for RSA signing/verification keys and specify RSA PSS padding and RSA PKCS#1 v1.5 deterministic padding, respectively.
PaddingMode::NONE may be used with either RSA, AES or 3DES keys.For AES or 3DES keys, if PaddingMode::NONE is used with block mode ECB or CBC and the data to be encrypted or decrypted is not a multiple of the AES block size in length, the call to finish() must fail with ErrorCode::INVALID_INPUT_LENGTH.
PaddingMode::PKCS7 may only be used with AES and 3DES keys, and only with ECB and CBC modes.
In any case, if the caller specifies a padding mode that is not usable with the key's algorithm, the generation or import method must return ErrorCode::INCOMPATIBLE_PADDING_MODE.
This tag is repeatable.A padding mode must be specified in the call to begin().If the specified mode is not authorized for the key, the operation must fail with ErrorCode::INCOMPATIBLE_BLOCK_MODE.
Must be hardware-enforced.
CALLER_NONCE = TagType : BOOL | 7
Tag::CALLER_NONCE specifies that the caller can provide a nonce for nonce-requiring operations.This tag is boolean, so the possible values are true(if the tag is present)and false(if the tag is not present).
This tag is used only for AES and 3DES keys, and is only relevant for CBC, CTR and GCM block modes.If the tag is not present in a key's authorization list, implementations must reject any operation that provides Tag::NONCE to begin() with ErrorCode::CALLER_NONCE_PROHIBITED.
Must be hardware-enforced.
MIN_MAC_LENGTH = TagType : UINT | 8
Tag::MIN_MAC_LENGTH specifies the minimum length of MAC that can be requested or verified with this key for HMAC keys and AES keys that support GCM mode.
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.
Must be hardware-enforced.
EC_CURVE = TagType : ENUM | 10
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, IKeymasterDevice must return ErrorCode::INVALID_ARGUMENT.
Must be hardware-enforced.
RSA_PUBLIC_EXPONENT = TagType : ULONG | 200
Tag::RSA_PUBLIC_EXPONENT specifies the value of the public exponent for an RSA key pair.This tag is relevant only to RSA keys, and is required for all RSA keys.
The value is a 64-bit unsigned integer that satisfies the requirements of an RSA public exponent.This value must be a prime number.IKeymasterDevice implementations must support the value 2^16+1 and may support other reasonable values.If no exponent is specified or if the specified exponent is not supported, key generation must fail with ErrorCode::INVALID_ARGUMENT.
Must be hardware-enforced.
INCLUDE_UNIQUE_ID = TagType : BOOL | 202
Tag::INCLUDE_UNIQUE_ID is specified during key generation to indicate that an attestation certificate for the generated key should contain an application-scoped and time-bounded device-unique ID.See Tag::UNIQUE_ID.
Must be hardware-enforced.
BLOB_USAGE_REQUIREMENTS = TagType : ENUM | 301
Tag::BLOB_USAGE_REQUIREMENTS specifies the necessary system environment conditions for the generated key to be used.Possible values are defined by the KeyBlobUsageRequirements enum.
This tag is specified by the caller during key generation or import to require that the key is usable in the specified condition.If the caller specifies Tag::BLOB_USAGE_REQUIREMENTS with value KeyBlobUsageRequirements::STANDALONE the IKeymasterDevice must return a key blob that can be used without file system support.This is critical for devices with encrypted disks, where the file system may not be available until after a Keymaster key is used to decrypt the disk.
Must be hardware-enforced.
BOOTLOADER_ONLY = TagType : BOOL | 302
Tag::BOOTLOADER_ONLY specifies only the bootloader can use the key.
Any attempt to use a key with Tag::BOOTLOADER_ONLY from the Android system must fail with ErrorCode::INVALID_KEY_BLOB.
Must be hardware-enforced.
ROLLBACK_RESISTANCE = TagType : BOOL | 303
Tag::ROLLBACK_RESISTANCE specifies that the key has rollback resistance, meaning that when deleted with deleteKey() or deleteAllKeys(), the key is guaranteed to be permanently deleted and unusable.It's possible that keys without this tag could be deleted and then restored from backup.
This tag is specified by the caller during key generation or import to require.If the IKeymasterDevice cannot guarantee rollback resistance for the specified key, it must return ErrorCode::ROLLBACK_RESISTANCE_UNAVAILABLE.IKeymasterDevice implementations are not required to support rollback resistance.
Must be hardwared-enforced.
HARDWARE_TYPE = TagType : ENUM | 304
ACTIVE_DATETIME = TagType : DATE | 400
Tag::ACTIVE_DATETIME specifies the date and time at which the key becomes active, in milliseconds since Jan 1, 1970.If a key with this tag is used prior to the specified date and time, IKeymasterDevice::begin() must return ErrorCode::KEY_NOT_YET_VALID;
Need not be hardware-enforced.
ORIGINATION_EXPIRE_DATETIME = TagType : DATE | 401
Tag::ORIGINATION_EXPIRE_DATETIME specifies the date and time at which the key expires for signing and encryption purposes.After this time, any attempt to use a key with KeyPurpose::SIGN or KeyPurpose::ENCRYPT provided to begin() must fail with ErrorCode::KEY_EXPIRED.
The value is a 64-bit integer representing milliseconds since January 1, 1970.
Need not be hardware-enforced.
USAGE_EXPIRE_DATETIME = TagType : DATE | 402
Tag::USAGE_EXPIRE_DATETIME specifies the date and time at which the key expires for verification and decryption purposes.After this time, any attempt to use a key with KeyPurpose::VERIFY or KeyPurpose::DECRYPT provided to begin() must fail with ErrorCode::KEY_EXPIRED.
The value is a 64-bit integer representing milliseconds since January 1, 1970.
Need not be hardware-enforced.
MIN_SECONDS_BETWEEN_OPS = TagType : UINT | 403
Tag::MIN_SECONDS_BETWEEN_OPS specifies the minimum amount of time that elapses between allowed operations using a key.This can be used to rate-limit uses of keys in contexts where unlimited use may enable brute force attacks.
The value is a 32-bit integer representing seconds between allowed operations.
When a key with this tag is used in an operation, the IKeymasterDevice must start a timer during the finish() or abort() call.Any call to begin() that is received before the timer indicates that the interval specified by Tag::MIN_SECONDS_BETWEEN_OPS has elapsed must fail with ErrorCode::KEY_RATE_LIMIT_EXCEEDED.This implies that the IKeymasterDevice 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 Keymaster 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 aggressively reuse table slots when key minimum-usage intervals expire.If an operation fails because the table is full, Keymaster returns ErrorCode::TOO_MANY_OPERATIONS.
Must be hardware-enforced.
MAX_USES_PER_BOOT = TagType : UINT | 404
Tag::MAX_USES_PER_BOOT specifies the maximum number of times that a key may be used between system reboots.This is another mechanism to rate-limit key use.
The value is a 32-bit integer representing uses per boot.
When a key with this tag is used in an operation, a key-associated counter must be incremented during the begin() call.After the key counter has exceeded this value, all subsequent attempts to use the key must fail with ErrorCode::MAX_OPS_EXCEEDED, until the device is restarted.This implies that the IKeymasterDevice must keep a table of use counters for keys with this tag.Because Keymaster memory is often limited, this table can have a fixed maximum size and Keymaster 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 operation fails because the table is full, IKeymasterDevice must ErrorCode::TOO_MANY_OPERATIONS.
Must be hardware-enforced.
USER_ID = TagType : UINT | 501
Tag::USER_ID specifies the ID of the Android user that is permitted to use the key.
Must not be hardware-enforced.
USER_SECURE_ID = TagType : ULONG_REP | 502
Tag::USER_SECURE_ID specifies that a key may only be used under a particular secure user authentication state.This tag is mutually exclusive with Tag::NO_AUTH_REQUIRED.
The value is a 64-bit integer specifying the authentication policy state value which must be present in the userId or authenticatorId field of a HardwareAuthToken provided to begin(), update(), or finish().If a key with Tag::USER_SECURE_ID is used without a HardwareAuthToken with the matching userId or authenticatorId, the IKeymasterDevice must return ErrorCode::KEY_USER_NOT_AUTHENTICATED.
Tag::USER_SECURE_ID interacts with Tag::AUTH_TIMEOUT in a very important way.If Tag::AUTH_TIMEOUT is present in the key's characteristics then the key is a "timeout-based" 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 IKeymasterDevice must returrn 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 IKeymasterDevice must returrn ErrorCode::KEY_USER_NOT_AUTHENTICATED.
This tag is repeatable.If repeated, and any one of the values matches the HardwareAuthToken as described above, the key is authorized for use.Otherwise the operation must fail with ErrorCode::KEY_USER_NOT_AUTHENTICATED.
Must be hardware-enforced.
NO_AUTH_REQUIRED = TagType : BOOL | 503
Tag::NO_AUTH_REQUIRED specifies that no authentication is required to use this key.This tag is mutually exclusive with Tag::USER_SECURE_ID.
Must be hardware-enforced.
USER_AUTH_TYPE = TagType : ENUM | 504
Tag::USER_AUTH_TYPE specifies the types of user authenticators that may be used to authorize this key.
The value is one or more values from HardwareAuthenticatorType, ORed together.
When IKeymasterDevice is requested to perform an operation with a key with this tag, it must receive a HardwareAuthToken and one or more bits must be set in both the HardwareAuthToken's authenticatorType field and the Tag::USER_AUTH_TYPE value.That is, it must be true that
(token.authenticatorType & tag_user_auth_type)!= 0
where token.authenticatorType is the authenticatorType field of the HardwareAuthToken and tag_user_auth_type is the value of Tag:USER_AUTH_TYPE.
Must be hardware-enforced.
AUTH_TIMEOUT = TagType : UINT | 505
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 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 authentication of the user specified by Tag::USER_SECURE_ID with the authentication method specified by Tag::USER_AUTH_TYPE that the key can be used.
Must be hardware-enforced.
ALLOW_WHILE_ON_BODY = TagType : BOOL | 506
Tag::ALLOW_WHILE_ON_BODY specifies that the key may be used after authentication timeout if device is still on-body(requires on-body sensor).
Cannot be hardware-enforced.
TRUSTED_USER_PRESENCE_REQUIRED = TagType : BOOL | 507
TRUSTED_USER_PRESENCE_REQUIRED is an optional feature that specifies that this key must be unusable except when the user has provided proof of physical presence.Proof of physical presence must be a signal that cannot be triggered by an attacker who doesn't have one of:
a)Physical control of the device or
b)Control of the secure environment that holds the key.
For instance, proof of user identity may be considered proof of presence if it meets the requirements.However, proof of identity established in one security domain(e.g.TEE)does not constitute proof of presence in another security domain(e.g.StrongBox), and no mechanism analogous to the authentication token is defined for communicating proof of presence across security domains.
Some examples:
A hardware button hardwired to a pin on a StrongBox device in such a way that nothing other than a button press can trigger the signal constitutes proof of physical presence for StrongBox keys.
Fingerprint authentication provides proof of presence(and identity)for TEE keys if the TEE has exclusive control of the fingerprint scanner and performs fingerprint matching.
Password authentication does not provide proof of presence to either TEE or StrongBox, even if TEE or StrongBox does the password matching, because password input is handled by the non-secure world, which means an attacker who has compromised Android can spoof password authentication.
Note that no mechanism is defined for delivering proof of presence to an IKeymasterDevice, except perhaps as implied by an auth token.This means that Keymaster must be able to check proof of presence some other way.Further, the proof of presence must be performed between begin() and the first call to update() or finish().If the first update() or the finish() call is made without proof of presence, the keymaster method must return ErrorCode::PROOF_OF_PRESENCE_REQUIRED and abort the operation.The caller must delay the update() or finish() call until proof of presence has been provided, which means the caller must also have some mechanism for verifying that the proof has been provided.
Only one operation requiring TUP may be in flight at a time.If begin() has already been 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_CONFIRMATION_REQUIRED = TagType : BOOL | 508
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 keymaster via an approval token.See CONFIRMATION_TOKEN, as well as the ConfirmatinUI 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 match the data described in the token, keymaster must return NO_USER_CONFIRMATION.
Must be hardware-enforced.
UNLOCKED_DEVICE_REQUIRED = TagType : BOOL | 509
Tag::UNLOCKED_DEVICE_REQUIRED specifies that the key may only be used when the device is unlocked.
Must be software-enforced.
APPLICATION_ID = TagType : BYTES | 601
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.
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.
Must never appear in KeyCharacteristics.
APPLICATION_DATA = TagType : BYTES | 700
Tag::APPLICATION_DATA.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 appData 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 msut 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.
Must never appear in KeyCharacteristics.
CREATION_DATETIME = TagType : DATE | 701
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.
Tag::CREATED is informational only, and not enforced by anything.Must be in the software-enforced list, if provided.
ORIGIN = TagType : ENUM | 702
Tag::ORIGIN specifies where the key was created, if known.This tag must not be specified during key generation or import, and must be added to the key characteristics by the IKeymasterDevice.The possible values are defined in the KeyOrigin enum.
Must be hardware-enforced.
ROOT_OF_TRUST = TagType : BYTES | 704
Tag::ROOT_OF_TRUST specifies the root of trust, the key used by verified boot to validate the operating system booted(if any). This tag is never provided to or returned from Keymaster in the key characteristics.It exists only to define the tag for use in the attestation record.
Must never appear in KeyCharacteristics.
OS_VERSION = TagType : UINT | 705
Tag::OS_VERSION specifies the system OS version with which the key may be used.This tag is never sent to the IKeymasterDevice, 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.
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 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.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.
OS_PATCHLEVEL = TagType : UINT | 706
Tag::OS_PATCHLEVEL specifies the system security patch level with which the key may be used.This tag is never sent to the keymaster 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.
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 generated on an Android device last updated in December 2015, the value would be 201512.
The IKeymasterDevice HAL must read the current system patchlevel from the system property ro.build.version.security_patch and deliver it to the secure environment when the HAL is first loaded(mechanism is implementation-defined). The secure environment must not accept another patchlevel until after the next boot.
Must be hardware-enforced.
UNIQUE_ID = TagType : BYTES | 707
Tag::UNIQUE_ID specifies a unique, time-based identifier.This tag is never provided to or returned from Keymaster in the key characteristics.It exists only to define the tag for use in the attestation record.
When a key with Tag::INCLUDE_UNIQUE_ID is attested, the unique ID is added to the attestation record.The value is a 128-bit hash that is unique per device and per calling application, and changes monthly and on most password resets.It is computed with:
HMAC_SHA256(T || C || R, HBK)
Where:
T is the "temporal counter value", computed by dividing the value of 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().
R is 1 if Tag::RESET_SINCE_ID_ROTATION was provided to attestKey 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 individual device(probabilistic uniqueness is acceptable).
HMAC_SHA256 is the HMAC function, with SHA-2-256 as the hash.
The output of the HMAC function must be truncated to 128 bits.
Must be hardware-enforced.
ATTESTATION_CHALLENGE = TagType : BYTES | 708
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().
Must never appear in KeyCharacteristics.
ATTESTATION_APPLICATION_ID = TagType : BYTES | 709
Tag::ATTESTATION_APPLICATION_ID identifies the set of applications which may use a key, used only with attestKey().
The content of Tag::ATTESTATION_APPLICATION_ID is a DER-encoded ASN.1 structure, with the following schema:
AttestationApplicationId::= SEQUENCE{packageInfoRecords SET OF PackageInfoRecord, signatureDigests SET OF OCTET_STRING , }
PackageInfoRecord::= SEQUENCE{packageName OCTET_STRING, version INTEGER , }
See system/security/keystore/keystore_attestation_id.cpp for details of construction.IKeymasterDevice implementers do not need to create or parse the ASN.1 structure, but only copy the tag value into the attestation record.The DER-encoded string must not exceed 1 KiB in length.
Cannot be hardware-enforced.
ATTESTATION_ID_BRAND = TagType : BYTES | 710
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.
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 includes this tag must fail with ErrorCode::CANNOT_ATTEST_IDS.
Must never appear in KeyCharacteristics.
ATTESTATION_ID_DEVICE = TagType : BYTES | 711
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.
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 includes this tag must fail with ErrorCode::CANNOT_ATTEST_IDS.
Must never appear in KeyCharacteristics.
ATTESTATION_ID_PRODUCT = TagType : BYTES | 712
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.
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 includes this tag must fail with ErrorCode::CANNOT_ATTEST_IDS.
Must never appear in KeyCharacteristics.
ATTESTATION_ID_SERIAL = TagType : BYTES | 713
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 called and the device can no longer attest its IDs), any key attestation request that includes this tag must fail with ErrorCode::CANNOT_ATTEST_IDS.
Must never appear in KeyCharacteristics.
ATTESTATION_ID_IMEI = TagType : BYTES | 714
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.
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 includes this tag must fail with ErrorCode::CANNOT_ATTEST_IDS.
Must never appear in KeyCharacteristics.
ATTESTATION_ID_MEID = TagType : BYTES | 715
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.
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 includes this tag must fail with ErrorCode::CANNOT_ATTEST_IDS.
Must never appear in KeyCharacteristics.
ATTESTATION_ID_MANUFACTURER = TagType : BYTES | 716
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.
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 includes this tag must fail with ErrorCode::CANNOT_ATTEST_IDS.
Must never appear in KeyCharacteristics.
ATTESTATION_ID_MODEL = TagType : BYTES | 717
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.
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 includes this tag must fail with ErrorCode::CANNOT_ATTEST_IDS.
Must never appear in KeyCharacteristics.
VENDOR_PATCHLEVEL = TagType : UINT | 718
Tag::VENDOR_PATCHLEVEL specifies the vendor image security patch level with which the key may be used.This tag is never sent to the keymaster 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.
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 update.For example, for a key generated on an Android device last updated on June 5, 2018, the value would be 20180605.
The IKeymasterDevice HAL must read the current vendor patchlevel from the system property ro.vendor.build.security_patch and deliver it to the secure environment when the HAL is first loaded(mechanism is implementation-defined). The secure environment must not accept another patchlevel until after the next boot.
Must be hardware-enforced.
BOOT_PATCHLEVEL = TagType : UINT | 719
Tag::BOOT_PATCHLEVEL specifies the boot image(kernel)security patch level with which the key may be used.This tag is never sent to the keymaster 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.
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 update.For example, for a key generated on an Android device last updated on June 5, 2018, 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).
Must be hardware-enforced.
ASSOCIATED_DATA = TagType : BYTES | 1000
Tag::ASSOCIATED_DATA Provides "associated data" for AES-GCM encryption or decryption.This tag is provided to update and specifies data that is not encrypted/decrypted, but is used in computing the GCM tag.
Must never appear KeyCharacteristics.
NONCE = TagType : BYTES | 1001
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 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:GCM nonces are 12 bytes in length;AES-CBC and AES-CTR IVs are 16 bytes in length, 3DES-CBC IVs are 8 bytes in length.
Must never appear in KeyCharacteristics.
MAC_LENGTH = TagType : UINT | 1003
Tag::MAC_LENGTH provides the requested length of a MAC or GCM authentication tag, in bits.
The value is the MAC length in bits.It must be a multiple of 8 and at least as large as the value of Tag::MIN_MAC_LENGTH associated with the key.Otherwise, begin() must return ErrorCode::INVALID_MAC_LENGTH.
Must never appear in KeyCharacteristics.
RESET_SINCE_ID_ROTATION = TagType : BOOL | 1004
Tag::RESET_SINCE_ID_ROTATION specifies whether the device has been factory reset since the last unique ID rotation.Used for key attestation.
Must never appear in KeyCharacteristics.
CONFIRMATION_TOKEN = TagType : BYTES | 1005
Tag::CONFIRMATION_TOKEN is used to deliver a cryptographic token proving that the user confirmed a signing request.The content is a full-length HMAC-SHA256 value.See the ConfirmationUI HAL for details of token computation.
Must never appear in KeyCharacteristics.

Algorithm

enum Algorithm: uint32_t

Algorithms provided by IKeymasterDevice implementations.

Details
Members
RSA = 1
Asymmetric algorithms.
EC = 3
AES = 32
Block cipher algorithms
TRIPLE_DES = 33
HMAC = 128
MAC algorithms

BlockMode

enum BlockMode: uint32_t

Symmetric block cipher modes provided by keymaster implementations.

Details
Members
ECB = 1
CBC = 2
CTR = 3
GCM = 32

PaddingMode

enum PaddingMode: uint32_t

Padding modes that may be applied to plaintext for encryption operations.This list includes padding modes for both symmetric and asymmetric algorithms.Note that implementations should not provide all possible combinations of algorithm and padding, only the cryptographically-appropriate pairs.

Details
Members
NONE = 1
RSA_OAEP = 2
RSA_PSS = 3
RSA_PKCS1_1_5_ENCRYPT = 4
RSA_PKCS1_1_5_SIGN = 5
PKCS7 = 64

Digest

enum Digest: uint32_t

Digests provided by keymaster implementations.

Details
Members
NONE = 0
MD5 = 1
SHA1 = 2
SHA_2_224 = 3
SHA_2_256 = 4
SHA_2_384 = 5
SHA_2_512 = 6

EcCurve

enum EcCurve: uint32_t

Supported EC curves, used in ECDSA

Details
Members
P_224 = 0
P_256 = 1
P_384 = 2
P_521 = 3

KeyOrigin

enum KeyOrigin: uint32_t

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.

Details
Members
GENERATED = 0
Generated in keymaster.Should not exist outside the TEE.
DERIVED = 1
Derived inside keymaster.Likely exists off-device.
IMPORTED = 2
Imported into keymaster.Existed as cleartext in Android.
UNKNOWN = 3
Keymaster did not record origin.This value can only be seen on keys in a keymaster0 implementation.The keymaster0 adapter uses this value to document the fact that it is unkown whether the key was generated inside or imported into keymaster.
SECURELY_IMPORTED = 4
Securely imported into Keymaster.Was created elsewhere, and passed securely through Android to secure hardware.

KeyBlobUsageRequirements

enum KeyBlobUsageRequirements: uint32_t

Usability requirements of key blobs.This defines what system functionality must be available for the key to function.For example, key "blobs" which are actually handles referencing encrypted key material stored in the file system cannot be used until the file system is available, and should have BLOB_REQUIRES_FILE_SYSTEM.

Details
Members
STANDALONE = 0
REQUIRES_FILE_SYSTEM = 1

KeyPurpose

enum KeyPurpose: uint32_t

Possible purposes of a key(or pair).

Details
Members
ENCRYPT = 0
DECRYPT = 1
SIGN = 2
VERIFY = 3
WRAP_KEY = 5

ErrorCode

enum ErrorCode: int32_t

Keymaster error codes.

Details
Members
OK = 0
ROOT_OF_TRUST_ALREADY_SET = -1
UNSUPPORTED_PURPOSE = -2
INCOMPATIBLE_PURPOSE = -3
UNSUPPORTED_ALGORITHM = -4
INCOMPATIBLE_ALGORITHM = -5
UNSUPPORTED_KEY_SIZE = -6
UNSUPPORTED_BLOCK_MODE = -7
INCOMPATIBLE_BLOCK_MODE = -8
UNSUPPORTED_MAC_LENGTH = -9
UNSUPPORTED_PADDING_MODE = -10
INCOMPATIBLE_PADDING_MODE = -11
UNSUPPORTED_DIGEST = -12
INCOMPATIBLE_DIGEST = -13
INVALID_EXPIRATION_TIME = -14
INVALID_USER_ID = -15
INVALID_AUTHORIZATION_TIMEOUT = -16
UNSUPPORTED_KEY_FORMAT = -17
INCOMPATIBLE_KEY_FORMAT = -18
UNSUPPORTED_KEY_ENCRYPTION_ALGORITHM = -19
UNSUPPORTED_KEY_VERIFICATION_ALGORITHM = -20
For PKCS8 & PKCS12
INVALID_INPUT_LENGTH = -21
For PKCS8 & PKCS12
KEY_EXPORT_OPTIONS_INVALID = -22
DELEGATION_NOT_ALLOWED = -23
KEY_NOT_YET_VALID = -24
KEY_EXPIRED = -25
KEY_USER_NOT_AUTHENTICATED = -26
OUTPUT_PARAMETER_NULL = -27
INVALID_OPERATION_HANDLE = -28
INSUFFICIENT_BUFFER_SPACE = -29
VERIFICATION_FAILED = -30
TOO_MANY_OPERATIONS = -31
UNEXPECTED_NULL_POINTER = -32
INVALID_KEY_BLOB = -33
IMPORTED_KEY_NOT_ENCRYPTED = -34
IMPORTED_KEY_DECRYPTION_FAILED = -35
IMPORTED_KEY_NOT_SIGNED = -36
IMPORTED_KEY_VERIFICATION_FAILED = -37
INVALID_ARGUMENT = -38
UNSUPPORTED_TAG = -39
INVALID_TAG = -40
MEMORY_ALLOCATION_FAILED = -41
IMPORT_PARAMETER_MISMATCH = -44
SECURE_HW_ACCESS_DENIED = -45
OPERATION_CANCELLED = -46
CONCURRENT_ACCESS_CONFLICT = -47
SECURE_HW_BUSY = -48
SECURE_HW_COMMUNICATION_FAILED = -49
UNSUPPORTED_EC_FIELD = -50
MISSING_NONCE = -51
INVALID_NONCE = -52
MISSING_MAC_LENGTH = -53
KEY_RATE_LIMIT_EXCEEDED = -54
CALLER_NONCE_PROHIBITED = -55
KEY_MAX_OPS_EXCEEDED = -56
INVALID_MAC_LENGTH = -57
MISSING_MIN_MAC_LENGTH = -58
UNSUPPORTED_MIN_MAC_LENGTH = -59
UNSUPPORTED_KDF = -60
UNSUPPORTED_EC_CURVE = -61
KEY_REQUIRES_UPGRADE = -62
ATTESTATION_CHALLENGE_MISSING = -63
KEYMASTER_NOT_CONFIGURED = -64
ATTESTATION_APPLICATION_ID_MISSING = -65
CANNOT_ATTEST_IDS = -66
ROLLBACK_RESISTANCE_UNAVAILABLE = -67
HARDWARE_TYPE_UNAVAILABLE = -68
PROOF_OF_PRESENCE_REQUIRED = -69
CONCURRENT_PROOF_OF_PRESENCE_REQUESTED = -70
NO_USER_CONFIRMATION = -71
DEVICE_LOCKED = -72
UNIMPLEMENTED = -100
VERSION_MISMATCH = -101
UNKNOWN_ERROR = -1000

KeyDerivationFunction

enum KeyDerivationFunction: uint32_t

Key derivation functions, mostly used in ECIES.

Details
Members
NONE = 0
Do not apply a key derivation function;use the raw agreed key
RFC5869_SHA256 = 1
HKDF defined in RFC 5869 with SHA256
ISO18033_2_KDF1_SHA1 = 2
KDF1 defined in ISO 18033-2 with SHA1
ISO18033_2_KDF1_SHA256 = 3
KDF1 defined in ISO 18033-2 with SHA256
ISO18033_2_KDF2_SHA1 = 4
KDF2 defined in ISO 18033-2 with SHA1
ISO18033_2_KDF2_SHA256 = 5
KDF2 defined in ISO 18033-2 with SHA256

HardwareAuthenticatorType

enum HardwareAuthenticatorType: uint32_t

Hardware authentication type, used by HardwareAuthTokens to specify the mechanism used to authentiate the user, and in KeyCharacteristics to specify the allowable mechanisms for authenticating to activate a key.

Details
Members
NONE = 0
PASSWORD = 1 << 0
FINGERPRINT = 1 << 1
ANY = 0xFFFFFFFF

SecurityLevel

enum SecurityLevel: uint32_t

Device security levels.

Details
Members
SOFTWARE = 0
TRUSTED_ENVIRONMENT = 1
STRONGBOX = 2
STRONGBOX specifies that the secure hardware satisfies the requirements specified in CDD 9.11.2.

KeyFormat

enum KeyFormat: uint32_t

Formats for key import and export.

Details
Members
X509 = 0
X.509 certificate format, for public key export.
PKCS8 = 1
PCKS#8 format, asymmetric key pair import.
RAW = 3
Raw bytes, for symmetric key import.

KeyParameter

struct KeyParameter {Tag tag; union IntegerParams }; IntegerParams f; vec blob}
Details
Members
tag
Discriminates the union/blob field used.The blob cannot be placed in the union, but only one of "f" and "blob" may ever be used at a time.
}
f
blob

KeyCharacteristics

struct KeyCharacteristics {vec softwareEnforced; vec hardwareEnforced}

KeyCharacteristics defines the attributes of a key, including cryptographic parameters, and usage restrictions.It consits of two vectors of KeyParameters, one for "softwareEnforced" attributes and one for "hardwareEnforced" attributes.

KeyCharacteristics objects are returned by generateKey, importKey, importWrappedKey and getKeyCharacteristics.The IKeymasterDevice secure environment is responsible for allocating the parameters, all of which are Tags with associated values, to the correct vector.The hardwareEnforced vector must contain only those attributes which are enforced by secure hardware.All others should be in the softwareEnforced vector.See the definitions of individual Tag enums for specification of which must be hardware-enforced, which may be software-enforced and which must never appear in KeyCharacteristics.

Details
Members
softwareEnforced
hardwareEnforced

HardwareAuthToken

struct HardwareAuthToken {uint64_t challenge; uint64_t userId; uint64_t authenticatorId; HardwareAuthenticatorType authenticatorType; Timestamp timestamp; vec mac}

HardwareAuthToken is used to prove successful user authentication, to unlock the use of a key.

HardwareAuthTokens are produced by other secure environment applications, notably GateKeeper and Fingerprint, in response to successful user authentication events.These tokens are passed to begin(), update(), and finish() to prove that authentication occurred.See those methods for more details.It is up to the caller to determine which of the generated auth tokens is appropriate for a given key operation.

Details
Members
challenge
challenge is a value that's used to enable authentication tokens to authorize specific events.The primary use case for challenge is to authorize an IKeymasterDevice cryptographic operation, for keys that require authentication per operation.See begin() for details.
userId
userId is the a "secure" user ID.It is not related to any Android user ID or UID, but is created in the Gatekeeper application in the secure environment.
authenticatorId
authenticatorId is the a "secure" user ID.It is not related to any Android user ID or UID, but is created in an authentication application in the secure environment, such as the Fingerprint application.
authenticatorType
authenticatorType describes the type of authentication that took place, e.g.password or fingerprint.
timestamp
timestamp indicates when the user authentication took place, in milliseconds since some starting point(generally the most recent device boot)which all of the applications within one secure environment must agree upon.This timestamp is used to determine whether or not the authentication occurred recently enough to unlock a key(see Tag::AUTH_TIMEOUT).
mac
MACs are computed with a backward-compatible method, used by Keymaster 3.0, Gatekeeper 1.0 and Fingerprint 1.0, as well as pre-treble HALs.
The MAC is Constants::AUTH_TOKEN_MAC_LENGTH bytes in length and is computed as follows:
HMAC_SHA256(H, 0 || challenge || user_id || authenticator_id || authenticator_type || timestamp)
where ``||'' represents concatenation, the leading zero is a single byte, and all integers are represented as unsigned values, the full width of the type.The challenge, userId and authenticatorId values are in machine order, but authenticatorType and timestamp are in network order(big-endian). This odd construction is compatible with the hw_auth_token_t structure,
Note that mac is a vec rather than an array, not because it's actually variable-length but because it could be empty.As documented in the IKeymasterDevice::begin, IKeymasterDevice::update and IKeymasterDevice::finish doc comments, an empty mac indicates that this auth token is empty.

HmacSharingParameters

struct HmacSharingParameters {vec seed; uint8_t nonce}

HmacSharingParameters holds the data used in the process of establishing a shared HMAC key between multiple Keymaster instances.Sharing parameters are returned in this struct by getHmacSharingParameters() and send to computeSharedHmac().See the named methods in IKeymaster for details of usage.

Details
Members
seed
Either empty or contains a persistent value that is associated with the pre-shared HMAC agreement key(see documentation of computeSharedHmac in@4.0::IKeymaster). It is either empty or 32 bytes in length.
nonce
A 32-byte value which is guaranteed to be different each time getHmacSharingParameters() is called.Probabilistic uniqueness(i.e.random)is acceptable, though a stronger uniqueness guarantee(e.g.counter)is recommended where possible.

VerificationToken

struct VerificationToken {uint64_t challenge; Timestamp timestamp; vec parametersVerified; SecurityLevel securityLevel; vec mac}

VerificationToken enables one Keymaster instance to validate authorizations for another.See verifyAuthorizations() in IKeymaster for details.

Details
Members
challenge
The operation handle, used to ensure freshness.
timestamp
The current time of the secure environment that generates the VerificationToken.This can be checked against auth tokens generated by the same secure environment, which avoids needing to synchronize clocks.
parametersVerified
A list of the parameters verified.Empty if the only parameters verified are time-related.In that case the timestamp is the payload.
securityLevel
SecurityLevel of the secure environment that generated the token.
mac
32-byte HMAC-SHA256 of the above values, computed as:
HMAC(H, "Auth Verification" || challenge || timestamp || securityLevel || parametersVerified)
where:
``HMAC'' is the shared HMAC key(see computeSharedHmac() in IKeymaster).
``||'' represents concatenation
The representation of challenge and timestamp is as 64-bit unsigned integers in big-endian order.securityLevel is represented as a 32-bit unsigned integer in big-endian order.
If parametersVerified is non-empty, the representation of parametersVerified is an ASN.1 DER encoded representation of the values.The ASN.1 schema used is the AuthorizationList schema from the Keystore attestation documentation.If parametersVerified is empty, it is simply omitted from the HMAC computation.