Tag di autorizzazione del Keymaster

This page provides details to assist implementers of Keymaster HALs. It covers each tag in the HAL, which Keymaster version that tag is available in, and whether the tag is repeatable. Except as noted in the tag descriptions, all of the tags below are used during key generation to specify key characteristics.

For Keymaster 4, tags are defined in platform/hardware/interfaces/keymaster/keymaster-version/types.hal, such as 3.0/types.hal for Keymaster 3 and 4.0/types.hal for Keymaster 4. For Keymaster 2 and below, tags are defined in platform/hardware/libhardware/include/hardware/keymaster_defs.h.

For functions, see the Keymaster Functions page.

Tag::ACTIVE_DATETIME

Version: 1, 2, 3, 4

Repeatable? No

Specifies the date and time at which the key becomes active. Prior to this time, any attempt to use the key fails with ErrorCode::KEY_NOT_YET_VALID.

The value is a 64-bit integer representing milliseconds since January 1, 1970.

Tag::ALGORITHM

Version: 1, 2, 3, 4

Repeatable? No

Specifies the cryptographic algorithm with which the key is used.

Possible values are defined by the following enumeration:

Keymaster 3

enum class Algorithm : uint32_t {
    RSA = 1,
    EC = 3,
    AES = 32,
    HMAC = 128,
};

Keymaster 2 and earlier

typedef enum {
    KM_ALGORITHM_RSA = 1,
    KM_ALGORITHM_EC = 3,
    KM_ALGORITHM_AES = 32,
    KM_ALGORITHM_HMAC = 128,
} keymaster_algorithm_t;

Tag::ALL_APPLICATIONS

Version: 1, 2, 3, 4

Repeatable? No

Reserved for future use.

Tag::ALLOW_WHILE_ON_BODY

Version: 2, 3, 4

Repeatable? No

This tag is applicable only for Android Wear devices with on-body sensors. At this point, it's not expected that any TEE will be able to provide secure access to an on-body sensor, or that on-body sensors are very secure, so this is expected to be a purely software-enforced feature.

Tag::ALL_USERS

Version: 3, 4

Repeatable? No

Reserved for future use.

Tag::APPLICATION_DATA

Version: 1, 2, 3, 4

Repeatable? No

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 need to provide the same value to the clientId parameter, and calls to begin need to provide this tag and the same associated data as part of the inParams set. If the correct data is not provided, the function returns ErrorCode::INVALID_KEY_BLOB.

The content of this tag is 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.

The value is a blob, an arbitrary-length array of bytes.

Tag::APPLICATION_ID

Version: 1, 2, 3, 4

Repeatable? No

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 need to provide the same value in the clientId parameter, and calls to begin need to provide this tag and the same associated data as part of the inParams set. If the correct data is not provided, the function returns ErrorCode::INVALID_KEY_BLOB.

The content of this tag is bound to the key cryptographically, meaning it an adversary who can access all of the secure world secrets—but does not have access to the tag content—can't decrypt the key (without brute-forcing the tag content).

The value is a blob, an arbitrary-length array of bytes.

Tag::ASSOCIATED_DATA

Version: 1, 2, 3, 4

Repeatable? No

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.

The value is a blob, an arbitrary-length array of bytes.

Tag::ATTESTATION_APPLICATION_ID

Version: 3, 4

Repeatable? No

Used to identify the set of possible applications of which one has initiated a key attestation.

The value is a blob, an arbitrary-length array of bytes.

Tag::ATTESTATION_CHALLENGE

Version: 3, 4

Repeatable? No

Used to provide challenge in attestation.

The value is a blob, an arbitrary-length array of bytes.

Tag::ATTESTATION_ID_BRAND

Version: 3, 4

Repeatable? No

Provides the device's brand name, as returned by Build.BRAND in Android. This field is 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 fails with ErrorCode::CANNOT_ATTEST_IDS.

The value is a blob, an arbitrary-length array of bytes.

Tag::ATTESTATION_ID_DEVICE

Version: 3, 4

Repeatable? No

Provides the device's device name, as returned by Build.DEVICE in Android. This field is 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 fails with ErrorCode::CANNOT_ATTEST_IDS.

The value is a blob, an arbitrary-length array of bytes.

Tag::ATTESTATION_ID_IMEI

Version: 3, 4

Repeatable? Yes

Provides the IMEIs for all radios on the device. This field is 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 fails with ErrorCode::CANNOT_ATTEST_IDS.

The value is a blob, an arbitrary-length array of bytes.

Tag::ATTESTATION_ID_MANUFACTURER

Version: 3, 4

Repeatable? No

Provides the device's manufacturer name, as returned by Build.MANUFACTURER in Android. This field is 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 fails with ErrorCode::CANNOT_ATTEST_IDS.

The value is a blob, an arbitrary-length array of bytes.

Tag::ATTESTATION_ID_MEID

Version: 3, 4

Repeatable? Yes

Provides the MEIDs for all radios on the device. This field will only be set 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 fails with ErrorCode::CANNOT_ATTEST_IDS.

The value is a blob, an arbitrary-length array of bytes.

Tag::ATTESTATION_ID_MODEL

Version: 3, 4

Repeatable? No

Provides the device's model name, as returned by Build.MODEL in Android. This field is 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 fails with ErrorCode::CANNOT_ATTEST_IDS.

The value is a blob, an arbitrary-length array of bytes.

Tag::ATTESTATION_ID_PRODUCT

Version: 3, 4

Repeatable? No

Provides the device's product name, as returned by Build.PRODUCT in Android. This field is 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 fails with ErrorCode::CANNOT_ATTEST_IDS.

The value is a blob, an arbitrary-length array of bytes.

Tag::ATTESTATION_ID_SERIAL

Version: 3, 4

Repeatable? No

Provides the device's serial number. This field is 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 fails with ErrorCode::CANNOT_ATTEST_IDS.

The value is a blob, an arbitrary-length array of bytes.

Tag::AUTH_TIMEOUT

Version: 1, 2, 3, 4

Repeatable? No

Specifies the time in seconds for which the key is authorized for use, after authentication. If Tag::USER_SECURE_ID is present and this tag is not, then the key needs 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.

Tag::AUTH_TOKEN

Version: 1, 2, 3, 4

Repeatable? No

Provides an authentication token to begin, update or finish, to prove user authentication for a key operation that requires it (key has Tag::USER_SECURE_ID).

The value is a blob which contains a hw_auth_token_t structure.

Tag::BLOB_USAGE_REQUIREMENTS

Version: 1, 2, 3, 4

Repeatable? No

Specifies the necessary system environment conditions for the generated key to be used.

Possible values are defined by the following enumeration:

Keymaster 3

enum class KeyBlobUsageRequirements : uint32_t {
    STANDALONE = 0,
    REQUIRES_FILE_SYSTEM = 1,
};

Keymaster 2 and earlier

typedef enum {
    KM_BLOB_STANDALONE = 0,
    KM_BLOB_REQUIRES_FILE_SYSTEM = 1,
} keymaster_key_blob_usage_requirements_t;

This tag can be specified during key generation to require that the key is usable in the specified condition. It needs to be returned with the key characteristics from generateKey and getKeyCharacteristics. If the caller specifies Tag::BLOB_USAGE_REQUIREMENTS with value KeyBlobUsageRequirements::STANDALONE the trustlet returns 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.

Tag::BLOCK_MODE

Version: 1, 2, 3, 4

Repeatable? Yes

Specifies the block cipher mode(s) with which the key may be used. This tag is only relevant to AES keys.

Possible values are defined by the following enumeration:

Keymaster 3

enum class BlockMode : uint32_t {
    ECB = 1,
    CBC = 2,
    CTR = 3,
    GCM = 32,
};

Keymaster 2 and earlier

typedef enum {
    KM_MODE_ECB = 1,
    KM_MODE_CBC = 2,
    KM_MODE_CTR = 3,
    KM_MODE_GCM = 32,
} keymaster_block_mode_t;

This tag is repeatable, and for AES key operations specify a mode in the additionalParams argument of begin. If the specifiedmode is not in the modes associated with the key, the operation fails with ErrorCode::INCOMPATIBLE_BLOCK_MODE.

Tag::BOOT_PATCHLEVEL

Version: 4

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 causes 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.

Tag::BOOTLOADER_ONLY

Version: 1, 2, 3, 4

Repeatable? No

Specifies only the bootloader can use the key.

This tag is boolean, so the possible values are true (if the tag is present) and false (if the tag is not present).

Any attempt to use a key with Tag::BOOTLOADER_ONLY from the Android system fails with ErrorCode::INVALID_KEY_BLOB.

Tag::CALLER_NONCE

Version: 1, 2, 3, 4

Repeatable? No

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 keys, and is only relevant for CBC, CTR and GCM block modes. If the tag is not present, implementations should reject any operation that provides Tag::NONCE to begin with ErrorCode::CALLER_NONCE_PROHIBITED.

Tag::CREATION_DATETIME

Version: 1, 2, 3, 4

Repeatable? No

Specifies the date and time the key was created, in milliseconds since January 1, 1970. This tag is optional and informational only.

Tag::DIGEST

Version: 1, 2, 3, 4

Repeatable? Yes

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 following enumeration:

Keymaster 3

enum class Digest : uint32_t {
    NONE = 0,
    MD5 = 1,
    SHA1 = 2,
    SHA_2_224 = 3,
    SHA_2_256 = 4,
    SHA_2_384 = 5,
    SHA_2_512 = 6,
};

Keymaster 2 and earlier

typedef enum {
    KM_DIGEST_NONE = 0,
    KM_DIGEST_MD5 = 1,
    KM_DIGEST_SHA1 = 2,
    KM_DIGEST_SHA_2_224 = 3,
    KM_DIGEST_SHA_2_256 = 4,
    KM_DIGEST_SHA_2_384 = 5,
    KM_DIGEST_SHA_2_512 = 6,
}
keymaster_digest_t;

This tag is repeatable. For signing and verification operations, specify a digest in the additionalParams argument of begin. If the specified digest is not in the digests associated with the key, the operation fails with ErrorCode::INCOMPATIBLE_DIGEST.

Tag::EC_CURVE

Version: 2, 3, 4

Repeatable? No

In Keymaster 1, the curve used for EC keys was guessed from the specified key size. To improve flexibility moving forward, Keymaster 2 introduced an explicit way to specify curves. EC key generation requests may have Tag::EC_CURVE, Tag::KEY_SIZE, or both.

Possible values are defined by the following enumeration:

Keymaster 3

enum class EcCurve : uint32_t {
    P_224 = 0,
    P_256 = 1,
    P_384 = 2,
    P_521 = 3,
};

Keymaster 2 and earlier

enum class EcCurve : uint32_t {
    P_224 = 0,
    P_256 = 1,
    P_384 = 2,
P_521 = 3,
};

If a generation request only contains Tag::KEY_SIZE, fall back to the Keymaster 1 logic, choosing the appropriate NIST curve.

If the request only contains Tag::EC_CURVE, use the specified curve. For Keymaster 3 and later, curves are defined in EcCurve. For Keymaster 2 and earlier, curves are defined in keymaster_ec_curve_t.

If the request contains both, use the curve specified by Tag::EC_CURVE, and validate that the specified key size is appropriate for that curve. If not, return ErrorCode::INVALID_ARGUMENT.

Tag::INCLUDE_UNIQUE_ID

Version: 2, 3, 4

Repeatable? No

This tag 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, as specified by Tag::UNIQUE_ID.

This tag is boolean, so the possible values are true (if the tag is present) and false (if the tag is not present).

Tag::KEY_SIZE

Version: 1, 2, 3, 4

Repeatable? No

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.

Tag::MAC_LENGTH

Version: 1, 2, 3, 4

Repeatable? No

Provides the requested length of a MAC or GCM authentication tag, in bits.

The value is the MAC length in bits. It is a multiple of 8 and at least as large as the value of Tag::MIN_MAC_LENGTH associated with the key.

Tag::MAX_USES_PER_BOOT

Version: 1, 2, 3, 4

Repeatable? No

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 should be incremented during the begin call. After the key counter has exceeded this value, all subsequent attempts to use the key fail with ErrorCode::MAX_OPS_EXCEEDED, until the device is restarted. This implies that a trustlet keeps 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 16 keys. If an operation fails because the table is full, Keymaster returns ErrorCode::TOO_MANY_OPERATIONS.

Tag::MIN_MAC_LENGTH

Version: 1, 2, 3, 4

Repeatable? No

This tag 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 is a multiple of 8. For HMAC keys, the value is at least 64. For GCM keys, the value is at least 96 and no more than 128.

Tag::MIN_SECONDS_BETWEEN_OPS

Version: 1, 2, 3, 4

Repeatable? No

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, 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 fails with ErrorCode::KEY_RATE_LIMIT_EXCEEDED. This implies that a trustlet keeps 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 32 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.

Tag::NO_AUTH_REQUIRED

Version: 1, 2, 3, 4

Repeatable? No

Specifies that no authentication is required to use this key. This tag is mutually exclusive with Tag::USER_SECURE_ID.

This tag is boolean, so the possible values are true (if the tag is present) and false (if the tag is not present).

Tag::NONCE

Version: 1, 2, 3, 4

Repeatable? No

Provides or returns a nonce or Initialization Vector (IV) for AES GCM, CBC, or CTR encryption or decryption. This tag is provided to begin during encryption and decryption operations. It is only provided to begin if the key has Tag::CALLER_NONCE. If not provided, an appropriate nonce or IV will be randomly generated by 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; CBC and CTR IVs are 16 bytes in length.

Tag::ORIGIN

Version: 1, 2, 3, 4

Repeatable? No

Specifies where the key was created, if known. This tag may not be specified during key generation or import, and must be added to the key characteristics by the trustlet.

Keymaster 3

The possible values are defined in android::hardware::keymaster::v3_0::KeyOrigin:

enum class KeyOrigin : uint32_t {
    GENERATED = 0,
    DERIVED = 1,
    IMPORTED = 2,
    UNKNOWN = 3,
};

Keymaster 2 and earlier

The possible values are defined in keymaster_origin_t:

typedef enum {
    KM_ORIGIN_GENERATED = 0,
    KM_ORIGIN_IMPORTED = 2,
    KM_ORIGIN_UNKNOWN = 3,
} keymaster_key_origin_t

The full meaning of the value depends not only on the value but on whether it's found in the hardware-enforced or software-enforced characteristics list.

GENERATED indicates that Keymaster generated the key. If in the hardware-enforced list, the key was generated in secure hardware and is permanently hardware bound. If in the software-enforced list, the key was generated in SoftKeymaster and is not hardware bound.

DERIVED indicates that the key was derived inside Keymaster. Likely exists off-device.

IMPORTED indicates that the key was generated outside of Keymaster and imported into Keymaster. If in the hardware-enforced list, it is permanently hardware bound, although copies outside of secure hardware may exist. If in the software-enforces list, the key was imported into SoftKeymaster and is not hardware bound.

UNKNOWN should only appear in the hardware-enforced list. It indicates that the key is hardware bound, but it is not known whether the key was originally generated in secure hardware or was imported. This only occurs when keymaster0 hardware is being used to emulate keymaster1 services.

Tag::ORIGINATION_EXPIRE_DATETIME

Version: 1, 2, 3, 4

Repeatable? No

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 fails with ErrorCode::KEY_EXPIRED.

The value is a 64-bit integer representing milliseconds since January 1, 1970.

Tag::OS_PATCHLEVEL

Version: 2, 3, 4

Repeatable? No

This tag is never sent to the keymaster TA, but is added to the hardware-enforced authorization list by the TA.

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.

Keys that have a patch level different than the current patch level are not usable. An attempt to use such a key causes begin, getKeyCharacteristics, or exportKey to return ErrorCode::KEY_REQUIRES_UPGRADE. See Version Binding for more details.

Tag::OS_VERSION

Version: 2, 3, 4

Repeatable? No

This tag is never sent to the keymaster TA, but is added to the hardware-enforced authorization list by the TA.

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.

Tag::PADDING

Version: 1, 2, 3, 4

Repeatable? Yes

Specifies the padding modes that may be used with the key. This tag is relevant to RSA and AES keys.

Possible values are defined by the following enumeration:

Keymaster 3

enum class PaddingMode : uint32_t {
    NONE = 1,
    RSA_OAEP = 2,
    RSA_PSS = 3,
    RSA_PKCS1_1_5_ENCRYPT = 4,
    RSA_PKCS1_1_5_SIGN = 5,
    PKCS7 = 64,
};

Keymaster 2 and earlier

typedef enum {
    KM_PAD_NONE = 1,
    KM_PAD_RSA_OAEP = 2,
    KM_PAD_RSA_PSS = 3,
    KM_PAD_RSA_PKCS1_1_5_ENCRYPT = 4,
    KM_PAD_RSA_PKCS1_1_5_SIGN = 5,
    KM_PAD_PKCS7 = 64,
} keymaster_padding_t;

PaddingMode::RSA_OAEP and PaddingMode::RSA_PKCS1_1_5_ENCRYPT are used only for RSA encryption/decryption keys and specify RSA PKCS#1v2 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 PKCS#1v2 PSS padding and RSA PKCS#1 v1.5 deterministic padding, respectively.

PaddingMode::NONE may be used with either RSA or AES keys. For AES 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 fails with ErrorCode::INVALID_INPUT_LENGTH.

PaddingMode::PKCS7 may only be used with AES keys, and only with ECB and CBC modes.

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 fails with ErrorCode::INCOMPATIBLE_BLOCK_MODE.

Tag::PURPOSE

Version: 1, 2, 3, 4

Repeatable? Yes

Specifies the set of purposes for which the key may be used.

Possible values are defined by the following enumeration:

Keymaster 3

enum class KeyPurpose : uint32_t {
    ENCRYPT = 0,
    DECRYPT = 1,
    SIGN = 2,
    VERIFY = 3,
    DERIVE_KEY = 4,  // since 3.0
    WRAP_KEY = 5,    // since 3.0
};

Keymaster 2 and earlier

typedef enum {
    KM_PURPOSE_ENCRYPT = 0,
    KM_PURPOSE_DECRYPT = 1,
    KM_PURPOSE_SIGN = 2,
    KM_PURPOSE_VERIFY = 3,
} keymaster_purpose_t;

This tag is repeatable; keys may be generated with multiple values, although an operation has a single purpose. When the begin function is called to start an operation, the purpose of the operation is specified. If the purpose specified to the operation is not authorized by the key, the operation fails with ErrorCode::INCOMPATIBLE_PURPOSE.

Tag::RESET_SINCE_ID_ROTATION

Version: 3, 4

Repeatable? No

Specifies whether the device has been factory reset since the last unique ID rotation. Used for key attestation.

This tag is boolean, so the possible values are true (if the tag is present) and false (if the tag is not present).

Tag::ROLLBACK_RESISTANT

Version: 1, 2, 3, 4

Repeatable? No

Indicates that the key is rollback-resistant, meaning that when deleted by 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 boolean, so the possible values are true (if the tag is present) and false (if the tag is not present).

Tag::ROOT_OF_TRUST

Version: 1, 2, 3, 4

Repeatable? No

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.

Tag::RSA_PUBLIC_EXPONENT

Version: 1, 2, 3, 4

Repeatable? No

Specifies the value of the public exponent for an RSA key pair. This tag is relevant only to RSA keys, and necessary for all RSA keys.

The value is a 64-bit unsigned integer that satisfies the requirements of an RSA public exponent. This value has to be a prime number. Trustlets support the value 2^16+1 and may support other reasonable values, in particular the value 3. If no exponent is specified or if the specified exponent is not supported, key generation fails with ErrorCode::INVALID_ARGUMENT.

Tag::UNIQUE_ID

Version: 3, 4

Repeatable? No

Used to provide unique ID in attestation.

The value is a blob, an arbitrary-length array of bytes.

Tag::USAGE_EXPIRE_DATETIME

Version: 1, 2, 3, 4

Repeatable? No

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 fails with ErrorCode::KEY_EXPIRED.

The value is a 64-bit integer representing milliseconds since January 1, 1970.

Tag::USER_AUTH_TYPE

Version: 1, 2, 3, 4

Repeatable? No

Specifies the types of user authenticators that may be used to authorize this key. When Keymaster is requested to perform an operation with a key with this tag, it receives an authentication token, and the token's authenticator_type field needs to match the value in the tag. For example, (ntoh(token.authenticator_type) & auth_type_tag_value) != 0, where ntoh is a function that converts network-ordered integers to host-ordered integers and auth_type_tag_value is the value of this tag.

The value is a 32-bit integer bitmask of values from the enumeration:

Keymaster 3

enum class HardwareAuthenticatorType : uint32_t {
    NONE = 0u, // 0
    PASSWORD = 1 << 0,
    FINGERPRINT = 1 << 1,
    ANY = UINT32_MAX,
};

Keymaster 2 and earlier

typedef enum {
    HW_AUTH_NONE = 0,
    HW_AUTH_PASSWORD = 1 << 0,
    HW_AUTH_FINGERPRINT = 1 << 1,
    // Additional entries should be powers of 2.
    HW_AUTH_ANY = UINT32_MAX,
} hw_authenticator_type_t;

Tag::USER_SECURE_ID

Version: 1, 2, 3, 4

Repeatable? No

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 needs to be present in an authentication token (provided to begin with the Tag::AUTH_TOKEN) to authorize use of the key. Any call to begin with a key with this tag that does not provide an authentication token, or provides an authentication token without a matching policy state value, fails.

This tag is repeatable. If any of the provided values matches any policy state value in the authentication token, the key is authorized for use. Otherwise the operation fails with ErrorCode::KEY_USER_NOT_AUTHENTICATED.

Tag::VENDOR_PATCHLEVEL

Version: 4

This tag 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.