Implementer's Reference

Implementer's Reference

This page provides details to assist implementers of Keymaster HALs. It covers each tag and each function in the HAL.

Authorization tags

---

Except as noted in the tag descriptions, all of the tags below are used during key generation to specify key characteristics.

KM_TAG_PURPOSE

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

Possible values are defined by the following enumeration:

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 must fail with KM_ERROR_INCOMPATIBLE_PURPOSE.

KM_TAG_ALGORITHM

Specifies the cryptographic algorithm with which the key is used.

Possible values are defined by the following enumeration:

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

This tag is not repeatable.

KM_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, KM_TAG_KEY_SIZE specifies the size of the public modulus. For AES keys it specifies the length of the secret key material.

This tag is not repeatable.

KM_TAG_BLOCK_MODE

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:

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 a mode must be specified in the additional_params argument of begin. If the specified mode is not in the modes associated with the key, the operation must fail with KM_ERROR_INCOMPATIBLE_BLOCK_MODE.

KM_TAG_DIGEST

Specifies the digest algorithms which 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:

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 a digest must be specified in the additional_params argument of begin. If the specified digest is not in the digests associated with the key, the operation must fail with KM_ERROR_INCOMPATIBLE_DIGEST.

KM_TAG_PADDING

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

Possible values are defined by the following enumeration:

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;

KM_PAD_RSA_OAEP and KM_PAD_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. KM_PAD_RSA_PSS and KM_PAD_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. Note also that the RSA PSS padding mode is incompatible with KM_DIGEST_NONE.

KM_PAD_NONE may be used with either RSA or AES keys. For AES keys, if KM_PAD_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 KM_ERROR_INVALID_INPUT_LENGTH.

KM_PAD_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 must fail with KM_ERROR_INCOMPATIBLE_BLOCK_MODE.

KM_TAG_CALLER_NONCE

Specifies that the caller is allowed to 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 which provides KM_TAG_NONCE to begin with KM_ERROR_CALLER_NONCE_PROHIBITED.

This tag is not repeatable.

KM_TAG_MIN_MAC_LENGTH

Required for HMAC keys and AES keys that support GCM mode, this tag specifies the minimum length of MAC that can be requested or verified with this key.

This value is the minimum MAC length, in bits. It must be a multiple of 8. For HMAC keys, the value must be at least 64. For GCM keys it must be at least 96 and must not exceed 128.

KM_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 required for all RSA keys.

The value is a 64-bit unsigned integer that must satisfy the requirements of an RSA public exponent. Because it is specified by the caller and therefore cannot be chosen by the implementation, it must be a prime number. Trustlets are required to support the value 2^16+1. It is recommended that other reasonable values be supported, in particular the value 3. If no exponent is specified or if the specified exponent is not supported, key generation must fail with KM_ERROR_INVALID_ARGUMENT.

This tag is not repeatable.

KM_TAG_BLOB_USAGE_REQUIREMENTS

Specifies the system environment conditions which must hold for the generated key to be used.

Possible values are defined by the following enumeration:

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

This tag may be specified during key generation to require that the key be usable in the specified condition, and must be returned with the key characteristics (from generate_key and get_key_characteristics). If the caller specifies KM_TAG_BLOB_USAGE_REQUIREMENTS with value KM_BLOB_STANDALONE the trustlet must return a key blob which 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.

This tag is not repeatable.

KM_TAG_BOOTLOADER_ONLY

Specifies that the key may only be used by the bootloader.

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 KM_TAG_BOOTLOADER_ONLY from the Android system must fail with KM_ERROR_INVALID_KEY_BLOB.

This tag is not repeatable.

KM_TAG_ACTIVE_DATETIME

Specifies the date and time at which the key becomes active. Prior to this time, any attempt to use the key must fail with KM_ERROR_KEY_NOT_YET_VALID.

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

This tag is not repeatable.

KM_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 KM_PURPOSE_SIGN or KM_PURPOSE_ENCRYPT provided to begin must fail with KM_ERROR_KEY_EXPIRED.

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

This tag is not repeatable.

KM_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 KM_PURPOSE_VERIFY or KM_PURPOSE DECRYPT provided to begin must fail with KM_ERROR_KEY_EXPIRED.

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

This tag is not repeatable.

KM_TAG_MIN_SECONDS_BETWEEN_OPS

Specifies the minimum amount of time that must elapse 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, a timer should be started during the finish or abort call. Any call to begin that is received before the timer indicates that the interval specified by KM_TAG_MIN_SECONDS_BETWEEN_OPS has elapsed must fail with KM_ERROR_KEY_RATE_LIMIT_EXCEEDED. This requirement implies that a trustlet must keep a table of timers for keys with this tag. Because Keymaster memory is often limited, it is acceptable for this table to have a fixed maximum size and for Keymaster to fail operations which attempt to use keys with this tag when the table is full. At least 32 in-use keys must be accommodated, and table slots must be aggressively reused when key minimum-usage intervals expire. If an operation fails because the table is full, Keymaster should return KM_ERROR_TOO_MANY_OPERATIONS.

This tag is not repeatable.

KM_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 should be incremented during the begin call. After the key counter has exceeded this value, all subsequent attempts to use the key must fail with KM_ERROR_MAX_OPS_EXCEEDED, until the device is restarted. This requirement implies that a trustlet must keep a table of use counters for keys with this tag. Because Keymaster memory is often limited, it is acceptable for this table to have a fixed maximum size and for Keymaster to fail operations that attempt to use keys with this tag when the table is full. At least 16 keys must be accommodated. If an operation fails because the table is full, Keymaster should return KM_ERROR_TOO_MANY_OPERATIONS.

This tag is not repeatable.

KM_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 KM_TAG_NO_AUTH_REQUIRED.

The value is a 64-bit integer specifying the authentication policy state value which must be present in an authentication token (provided to begin with the KM_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, must fail.

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 must fail with KM_ERROR_KEY_USER_NOT_AUTHENTICATED.

KM_TAG_NO_AUTH_REQUIRED

Specifies that no authentication is required to use this key. This tag is mutually exclusive with KM_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).

This tag is not repeatable.

KM_TAG_USER_AUTH_TYPE

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 must receive an authentication token, and the token's authenticator_type field must match the value in the tag. To be precise, it must be true that (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:

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;

This tag is not repeatable.

KM_TAG_AUTH_TIMEOUT

Specifies the time in seconds for which the key is authorized for use, after authentication. If KM_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 authentication of the user specified by KM_TAG_USER_SECURE_ID with the authentication method specified by KM_TAG_USER_AUTH_TYPE that the key can be used.

This tag is not repeatable.

KM_TAG_ALL_APPLICATIONS

Reserved for future use.

This tag is not repeatable.

KM_TAG_APPLICATION_ID

When provided to generate_key or import_key, this tag specifies data that must be provided during all uses of the key. In particular, calls to export_key and get_key_characteristics must provide the same value in the client_id parameter, and calls to begin must provide this tag and the same associated data as part of the in_params set. If the correct data is not provided the function must return KM_ERROR_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).

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

This tag is not repeatable.

KM_TAG_APPLICATION_DATA

When provided to generate_key or import_key, this tag specifies data that must be provided during all uses of the key. In particular, calls to export_key and get_key_characteristics must provide the same value to the client_id parameter, and calls to begin must provide this tag and the same associated data as part of the in_params set. If the correct data is not provided, the function must return KM_ERROR_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).

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

This tag is not repeatable.

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

This tag is not repeatable.

KM_TAG_ORIGIN

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.

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.

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

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

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

This tag is not repeatable.

KM_TAG_ROLLBACK_RESISTANT

Indicates that the key is rollback-resistant, meaning that when deleted by delete_key or delete_all_keys, 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).

This tag is not repeatable.

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

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

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

This tag is not repeatable.

KM_TAG_NONCE

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 may only be provided to begin if the key has KM_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.

This tag is not repeatable.

KM_TAG_AUTH_TOKEN

Provides an authentication token (see the Authentication page) to begin, update or finish, to prove user authentication for a key operation that requires it (key has KM_TAG_USER_SECURE_ID).

The value is a blob which contains a hw_auth_token_t structure.

This tag is not repeatable.

KM_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 must be at least as large as the value of KM_TAG_MIN_MAC_LENGTH associated with the key.

Functions

---

Deprecated functions

The following functions are in the keymaster1_device_t definition but should not be implemented. The function pointers should be set to NULL:

• generate_keypair
• import_keypair
• get_keypair_public
• delete_keypair
• delete_all
• sign_data
• verify_data

General implementation guidelines

The following guidelines apply to all functions in the API.

Input pointer parameters

Input pointer parameters that are not used for a given call may be NULL. The caller is not required to provide placeholders. For example, some key types and modes may not use any values from the in_params argument to begin, so the caller may set in_params to NULL or provide an empty parameter set. It is also acceptable for the caller to provide unused parameters, and Keymaster methods should not issue errors.

If a required input parameter is NULL, Keymaster methods should return KM_ERROR_UNEXPECTED_NULL_POINTER.

Output pointer parameters

Similar to input pointer parameters, unused output pointer parameters may be NULL. If a method needs to return data in an output parameter found to be NULL, it should return KM_ERROR_OUTPUT_PARAMETER_NULL.

API misuse

There are many ways that callers can make requests that don't make sense or are foolish but not technically wrong. Keymaster1 implementations are not required to fail in such cases or issue a diagnostic. Use of too-small keys, specification of irrelevant input parameters, reuse of IVs or nonces, generation of keys with no purposes (hence useless) and the like should not be diagnosed by implementations. Omission of required parameters, specification of invalid required parameters, and similar errors must be diagnosed.

It is the responsibility of apps, the framework, and Android keystore to ensure that the calls to Keymaster modules are sensible and useful.

get_supported_algorithms

Returns the list of algorithms supported by the Keymaster hardware implementation. A software implementation must return an empty list; a hybrid implementation must return a list containing only the algorithms that are supported by hardware.

Keymaster1 implementations must support RSA, EC, AES and HMAC.

get_supported_block_modes

Returns the list of AES block modes supported by the Keymaster hardware implementation for a specified algorithm and purpose.

For RSA, EC and HMAC, which are not block ciphers, the method must return an empty list for all valid purposes. Invalid purposes should cause the method to return KM_ERROR_INVALID_PURPOSE.

Keymaster1 implementations must support ECB, CBC, CTR and GCM for AES encryption and decryption.

get_supported_padding_modes

Returns the list of padding modes supported by the Keymaster hardware implementation for a specified algorithm and purpose.

HMAC and EC have no notion of padding so the method must return an empty list for all valid purposes. Invalid purposes should cause the method to return KM_ERROR_INVALID_PURPOSE.

For RSA, keymaster1 implementations must support:

• Unpadded encryption, decryption, signing and verification. For unpadded encryption and signing, if the message is shorter than the public modulus, implementations must left-pad it with zeros. For unpadded decryption and verification, the input length must match the public modulus size.
• PKCS#1 v1.5 encryption and signing padding modes
• PSS with a minimum salt length of 20
• OAEP

For AES in ECB and CBC modes, keymaster1 implementations must support no padding and PKCS#7-padding. CTR and GCM modes must support only no padding.

get_supported_digests

Returns the list of digest modes supported by the Keymaster hardware implementation for a specified algorithm and purpose.

No AES modes support or require digesting, so the method must return an empty list for valid purposes.

Keymaster1 implementations are allowed to implement a subset of the defined digests, but must provide SHA-256. It is strongly recommended that keymaster1 implementations provide MD5, SHA1, SHA-224, SHA-256, SHA384 and SHA512 (the full set of defined digests).

get_supported_import_formats

Returns the list of import formats supported by the Keymaster hardware implementation of a specified algorithm.

Keymaster1 implementations must support the PKCS#8 format (without password protection) for importing RSA and EC key pairs, and must support RAW import of AES and HMAC key material.

get_supported_export_formats

Returns the list of export formats supported by the Keymaster hardware implementation of a specified algorithm.

Keymaster1 implementations must support the X.509 format for exporting RSA and EC public keys. Export of private keys or asymmetric keys must not be supported.

add_rng_entropy

Adds caller-provided entropy to the pool used by the Keymaster1 implementation for generating random numbers, for keys, IVs, etc.

Keymaster1 implementations must securely mix the provided entropy into their pool, which must also contain internally-generated entropy from a hardware random number generator. Mixing must have the property that an attacker with complete control of either the add_rng_entropy-provided bits or the hardware-generated bits, but not both, cannot predict bits generated from the entropy pool with probability greater than ½.

Keymaster1 implementations that attempt to estimate the entropy in their internal pool must assume that data provided by add_rng_entropy contains no entropy.

generate_key

Generates a new cryptographic key, specifying associated authorizations, which will be permanently bound to the key. Keymaster1 implementations must make it impossible to use a key in any way inconsistent with the authorizations specified at generation time. With respect to authorizations that the secure hardware cannot enforce, the secure hardware's obligation is limited to ensuring that the unenforceable authorizations associated with the key cannot be modified, so that every call to get_key_characteristics will return the original value. In addition, the characteristics returned by generate_key must allocate authorizations correctly between the hardware-enforced and software-enforced lists. See get_key_characteristics for more details.

The parameters that must be provided to generate_key depend on the type of key being generated. This section will summarize the required and allowed tags for each type of key. KM_TAG_ALGORITHM is always required, to specify the type.

RSA keys

The following parameters are required when generating an RSA key.

• KM_TAG_KEY_SIZE specifies the size of the public modulus, in bits. If omitted, the method must return KM_ERROR_UNSUPPORTED_KEY_SIZE. Values that must be supported are 1024, 2048, 3072 and 4096. It is recommended to support all key sizes that are a multiple of 8.
• KM_TAG_RSA_PUBLIC_EXPONENT specifies the RSA public exponent value. If omitted, the method must return KM_ERROR_INVALID_ARGUMENT. Implementations must support the values 3 and 65537. It is recommended to support all prime values up to 2^64.

The following parameters are not required to generate an RSA key, but creating an RSA key without them will produce a key that is unusable. The generate_key function should not return an error if these parameters are omitted.

• KM_TAG_PURPOSE specifies allowed purposes. All purposes must be supported for RSA keys, in any combination.
• KM_TAG_DIGEST specifies digest algorithms that may be used with the new key. Implementations that do not support all digest algorithms must accept key generation requests that include unsupported digests. The unsupported digests should be placed in the "software-enforced" list in the returned key characteristics. This is because the key will be usable with those other digests, but digesting will be performed in software. Then hardware will be called to perform the operation with KM_DIGEST_NONE.
• KM_TAG_PADDING specifies the padding modes that may be used with the new key. Implementations that do not support all digest algorithms must place KM_PAD_RSA_PSS and KM_PAD_RSA_OAEP in the software-enforced list of the key characteristics if any unsupported digest algorithms are specified.

ECDSA keys

Only KM_TAG_KEY_SIZE is required to generate an ECDSA key. It is used to select the EC group. Implementations must support values 224, 256, 384 and 521, which indicate the NIST p-224, p-256, p-384 and p521 curves, respectively.

KM_TAG_DIGEST is also needed for a useful ECDSA key, but is not required for generation.

AES keys

Only KM_TAG_KEY_SIZE is required when generating an AES key. If omitted, the method must return KM_ERROR_UNSUPPORTED_KEY_SIZE. Values that must be supported are 128 and 256. It is recommended to support 192-bit AES keys.

The following parameters are particularly relevant for AES keys, but not required to generate one:

• KM_TAG_BLOCK_MODE specifies the block modes with which the new key may be used.
• KM_TAG_PADDING specifies the padding modes that may be used. This is only relevant for ECB and CBC modes.

If the GCM block mode is specified, then KM_TAG_MIN_MAC_LENGTH must be provided. If omitted, the method must return KM_ERROR_MISSING_MIN_MAC_LENGTH. The value of the tag must be a multiple of 8 and must be at least 96 and no more than 128.

HMAC keys

The following parameters are required for HMAC key generation:

• KM_TAG_KEY_SIZE specifies the key size in bits. Values smaller than 64 and values that are not multiples of 8 must not be supported. All multiples of 8, from 64 to 512, must be supported. Larger values may be supported.
• KM_TAG_MIN_MAC_LENGTH specifies the minimum length of MACs that can be generated or verified with this key. The value must be a multiple of 8 and must be at least 64.
• KM_TAG_DIGEST specifies the digest algorithm for the key. Exactly one digest must be specified, otherwise return KM_ERROR_UNSUPPORTED_DIGEST. If the digest is not supported by the trustlet, return KM_ERROR_UNSUPPORTED_DIGEST.

Key characteristics

If the characteristics argument is non-NULL, generate_key must return the newly-generated key's characteristics divided appropriately into hardware-enforced and software-enforced lists. See get_key_characteristics for a description of which characteristics go in which list. The returned characteristics must include all of the parameters specified to key generation, except KM_TAG_APPLICATION_ID and KM_TAG_APPLICATION_DATA. If these tags were included in the key parameters, they must be removed from the returned characteristics; it must not be possible to find their values by examining the returned key blob. However, they must be cryptographically bound to the key blob, so that if the correct values are not provided when the key is used, usage will fail. Similarly, KM_TAG_ROOT_OF_TRUST must be cryptographically bound to the key, but it may not be specified during key creation or import and must never be returned.

In addition to the provided tags, the trustlet must also add KM_TAG_ORIGIN, with the value KM_ORIGIN_GENERATED, and if the key is rollback resistant, KM_TAG_ROLLBACK_RESISTANT.

Rollback resistance

Rollback resistance means that once a key is deleted with delete_key or delete_all_keys, it is guaranteed by secure hardware never to be usable again. Implementations without rollback resistance will typically return generated or imported key material to the caller as a key blob, an encrypted and authenticated form. When keystore deletes the key blob, the key is gone, but an attacker who has previously managed to retrieve the key material can potentially restore it to the device.

A key is rollback resistant if the secure hardware guarantees that deleted keys cannot be restored later. This is generally done by storing additional key metadata in a trusted location that cannot be manipulated by an attacker. On mobile devices, the mechanism used for this is usually Replay Protected Memory Blocks (RPMB). Because the number of keys that may be created is essentially unbounded and the trusted storage used for rollback resistance may be limited in size, it is required that this method succeed even if rollback resistance cannot be provided for the new key. In that case, KM_TAG_ROLLBACK_RESISTANT should not be added to the key characteristics.

get_key_characteristics

Returns parameters and authorizations associated with the provided key, divided into two sets: hardware-enforced and software-enforced. The description here applies equally to the key characteristics lists returned by generate_key and import_key.

If KM_TAG_APPLICATION_ID was provided during key generation or import, the same value must provided to this method in the client_id argument. Otherwise, the method must return KM_ERROR_INVALID_KEY_BLOB. Similarly, if KM_TAG_APPLICATION_DATA was provided during generation or import, the same value must be provided to this method in the app_data argument.

The characteristics returned by this method completely describe the type and usage of the specified key.

The general rule for deciding whether a given tag belongs in the hardware-enforced or software-enforced list is that if the meaning of the tag is fully assured by secure hardware, it is hardware-enforced. Otherwise, it's software enforced. Below is a list of specific tags whose correct allocation may be unclear:

• KM_TAG_ALGORITHM, KM_TAG_KEY_SIZE, and KM_TAG_RSA_PUBLIC_EXPONENT are intrinsic properties of the key. For any key that is secured by hardware, these will be in the hardware-enforced list, because the statement that, for example, "This RSA key material is only used as an RSA key" is enforced by hardware because the hardware will use it in no other way and software has no access to the key material and cannot use it at all.
• KM_TAG_DIGEST values that are supported by the secure hardware are to be placed in the hardware-supported list. Unsupported digests go in the software-supported list.
• KM_TAG_PADDING values generally go in the hardware-supported list, but if there is a possibility that a specific padding mode may have to be performed by software, they go in the software-enforced list. Such a possibility arises for RSA keys that permit PSS or OAEP padding with digest algorithms that are not supported by the secure hardware.
• KM_TAG_USER_SECURE_ID and KM_TAG_USER_AUTH_TYPE are hardware-enforced only if user authentication is hardware enforced. For that to be true, the Keymaster trustlet and the relevant authentication trustlet must both be secure and must share a secret HMAC key used to sign and validate authentication tokens. See the Authentication page for details.
• KM_TAG_ACTIVE_DATETIME, KM_TAG_ORIGINATION_EXPIRE_DATETIME, and KM_TAG_USAGE_EXPIRE_DATETIME tags require access to a verifiably correct wall clock. Most secure hardware will only have access to time information provided by the non-secure OS, which means the tags are software-enforced.
• KM_TAG_ORIGIN is always in the hardware list for hardware-bound keys. Its presence in that list is the way higher layers determine that a key is hardware-backed.

import_key

Imports key material into Keymaster hardware. Key definition parameters and output characteristics are handled the same as for generate_key, with the following exceptions:

• KM_TAG_KEY_SIZE and KM_TAG_RSA_PUBLIC_EXPONENT (for RSA keys only) are not required in the input parameters. If not provided, the trustlet must deduce the values from the provided key material and add appropriate tags and values to the key characteristics. If the parameters are provided, the trustlet must validate them against the key material. In the event of a mismatch, the method must return KM_ERROR_IMPORT_PARAMETER_MISMATCH.
• The returned KM_TAG_ORIGIN must have the value KM_ORIGIN_IMPORTED.

export_key

Exports a public key from a Keymaster RSA or EC key pair.

If KM_TAG_APPLICATION_ID was provided during key generation or import, the same value must provided to this method in the client_id argument. Otherwise, the method must return KM_ERROR_INVALID_KEY_BLOB. Similarly, if KM_TAG_APPLICATION_DATA was provided during generation or import, the same value must be provided to this method in the app_data argument.

delete_key

Deletes the provided key. This method is optional, and will likely be implemented only by Keymaster modules that provide rollback resistance.

delete_all_keys

Deletes all keys. This method is optional, and will likely be implemented only by Keymaster modules that provide rollback resistance.

begin

Begins a cryptographic operation, using the specified key, for the specified purpose, with the specified parameters (as appropriate), and returns an operation handle which is used with update and finish to complete the operation. The operation handle is also used as the "challenge" token in authenticated operations, and for such operations must be included in the challenge field of the authentication token.

A Keymaster implementation must support at least 16 concurrent operations. Keystore will use up to 15, leaving one for vold to use for password encryption. When Keystore has 15 operations in progress (begin has been called, but finish or abort have not yet been called) and it receives a request to begin a 16th, it will call abort on the least-recently used operation to reduce the number of active operations to 14 before calling begin to start the newly-requested operation.

If KM_TAG_APPLICATION_ID or KM_TAG_APPLICATION_DATA were specified during key generation or import, calls to begin must include those tags with the originally-specified values in the in_params argument to this method.

Authorization enforcement

During this method, the following key authorizations must be enforced by the trustlet if the implementation placed them in the "hardware-enforced" characteristics and if the operation is not a public key operation. Public key operations, meaning KM_PURPOSE_ENCRYPT and KM_PURPOSE_VERIFY, with RSA or EC keys, must be allowed to succeed even if authorization requirements are not met.

• KM_TAG_PURPOSE requires that the purpose specified for this method match one of the purposes in the key authorizations, unless the requested operation is a public key operation, meaning that the key is RSA or EC and the purpose is KM_PURPOSE_ENCRYPT or KM_PURPOSE_VERIFY. Note that KM_PURPOSE_ENCRYPT is not valid for EC keys. Begin should return KM_ERROR_UNSUPPORTED_PURPOSE in that case.
• KM_TAG_ACTIVE_DATETIME requires comparison with a trusted UTC time source. If the current date and time is prior to the tag value, the method must return KM_ERROR_KEY_NOT_YET_VALID.
• KM_TAG_ORIGINATION_EXPIRE_DATETIME requires comparison with a trusted UTC time source. If the current date and time is later than the tag value and the purpose is KM_PURPOSE_ENCRYPT or KM_PURPOSE_SIGN, the method must return KM_ERROR_KEY_EXPIRED.
• KM_TAG_USAGE_EXPIRE_DATETIME requires comparison with a trusted UTC time source. If the current date and time is later than the tag value and the purpose is KM_PURPOSE_DECRYPT or KM_PURPOSE_VERIFY, the method must return KM_ERROR_KEY_EXPIRED.
• KM_TAG_MIN_SECONDS_BETWEEN_OPS requires comparison with a trusted relative timer indicating the last use of the key. If the last use time plus the tag value is less than the current time, the method must return KM_ERROR_KEY_RATE_LIMIT_EXCEEDED. See the tag description for important implementation requirements.
• KM_TAG_MAX_USES_PER_BOOT requires comparison against a secure counter that tracks the uses of the key since boot time. If the count of previous uses exceeds the tag value, the method must return KM_ERROR_KEY_MAX_OPS_EXCEEDED.
• KM_TAG_USER_SECURE_ID is enforced by this method only if the key also has KM_TAG_AUTH_TIMEOUT. If the key has both, then this method must have received a KM_TAG_AUTH_TOKEN in in_params and that token must be valid, meaning that the HMAC field validates correctly. In addition, at least one of the KM_TAG_USER_SECURE_ID values from the key must match at least one of the secure ID values in the token. Finally, the key must also have a KM_TAG_USER_AUTH_TYPE and it must match the auth type in the token. If any of these requirements is not met, the method must return KM_ERROR_KEY_USER_NOT_AUTHENTICATED.
• KM_TAG_CALLER_NONCE allows the caller to specify a nonce or initialization vector (IV). If the key does not have this tag but the caller provided KM_TAG_NONCE to this method, KM_ERROR_CALLER_NONCE_PROHIBITED must be returned.
• KM_TAG_BOOTLOADER_ONLY specifies that the key may only be used by the bootloader. If this method is called with a bootloader-only key after the bootloader has finished executing, it must return KM_ERROR_INVALID_KEY_BLOB.

RSA keys

All RSA key operations must specify exactly one padding mode in in_params. If unspecified or specified more than once, the method must return KM_ERROR_UNSUPPORTED_PADDING_MODE.

RSA signing and verification operations require a digest, as do RSA encryption and decryption operations with OAEP padding mode. For those cases, the caller must specify exactly one digest in in_params. If unspecified or specified more than once, the method must return KM_ERROR_UNSUPPORTED_DIGEST.

Private key operations (KM_PURPOSE_DECYPT and KM_PURPOSE_SIGN) require authorization of digest and padding, which means that the specified values must be in the key authorizations. If not, the method must return KM_ERROR_INCOMPATIBLE_DIGEST or KM_ERROR_INCOMPATIBLE_PADDING, as appropriate. Public key operations (KM_PURPOSE_ENCRYPT and KM_PURPOSE_VERIFY) are permitted with unauthorized digest or padding.

With the exception of KM_PAD_NONE, all RSA padding modes are applicable only to certain purposes. Specifically, KM_PAD_RSA_PKCS1_1_5_SIGN and KM_PAD_RSA_PSS only support signing and verification, while KM_PAD_RSA_PKCS1_1_1_5_ENCRYPT and KM_PAD_RSA_OAEP only support encryption and decryption. The method must return KM_ERROR_UNSUPPORTED_PADDING_MODE if the specified mode does not support the specified purpose.

There are some important interactions between padding modes and digests:

• KM_PAD_NONE indicates that a "raw" RSA operation will be performed. If signing or verifying, KM_DIGEST_NONE must be specified for the digest. No digest is required for unpadded encryption or decryption.
• KM_PAD_RSA_PKCS1_1_5_SIGN padding requires a digest. The digest may be KM_DIGEST_NONE, in which case the Keymaster implementation cannot build a proper PKCS#1 v1.5 signature structure, because it cannot add the DigestInfo structure. Instead, the implementation must construct 0x00 || 0x01 || PS || 0x00 || M, where M is the provided message and PS is the padding string. The size of the RSA key must be at least 11 bytes larger than the message, otherwise the method must return KM_ERROR_INVALID_INPUT_LENGTH.
• KM_PAD_RSA_PKCS1_1_1_5_ENCRYPT padding does not require a digest.
• KM_PAD_RSA_PSS padding requires a digest, which may not be KM_DIGEST_NONE. If KM_DIGEST_NONE is specified, the method must return KM_ERROR_INCOMPATIBLE_DIGEST. In addition, the size of the RSA key must be at least 22 bytes larger than the output size of the digest. Otherwise, the method must return KM_ERROR_INCOMPATIBLE_DIGEST.
• KM_PAD_RSA_OAEP padding requires a digest, which may not be KM_DIGEST_NONE. If KM_DIGEST_NONE is specified, the method must return KM_ERROR_INCOMPATIBLE_DIGEST.

EC keys

EC key operations must specify exactly one padding mode in in_params. If unspecified or specified more than once, return KM_ERROR_UNSUPPORTED_PADDING_MODE.

Private key operations (KM_PURPOSE_SIGN) require authorization of the digest, which means that the specified value must be in the key authorizations. If not, return KM_ERROR_INCOMPATIBLE_DIGEST. Public key operations (KM_PURPOSE_VERIFY) are permitted with unauthorized digest or padding.

AES keys

AES key operations must specify exactly one block mode and one padding mode in in_params. If either value is unspecified or specified more than once, return KM_ERROR_UNSUPPORTED_BLOCK_MODE or KM_ERROR_UNSUPPORTED_PADDING_MODE. The specified modes must be authorized by the key. Otherwise, the method must return KM_ERROR_INCOMPATIBLE_BLOCK_MODE or KM_ERROR_INCOMPATIBLE_PADDING_MODE.

If the block mode is KM_MODE_GCM, in_params must specify KM_TAG_MAC_LENGTH, and the specified value must be a multiple of 8 and must not be greater than 128, or less than the value of KM_TAG_MIN_MAC_LENGTH in the key authorizations. For MAC lengths greater than 128 or non-multiples of 8, return KM_ERROR_UNSUPPORTED_MAC_LENGTH. For values less than the key's minimum length, return KM_ERROR_INVALID_MAC_LENGTH.

If the block mode is KM_MODE_GCM or KM_MODE_CTR, the specified padding mode must be KM_PAD_NONE. For KM_MODE_ECB or KM_MODE_CBC, the mode may be KM_PAD_NONE or KM_PAD_PKCS7. If the padding mode doesn't meet these requirements, return KM_ERROR_INCOMPATIBLE_PADDING_MODE.

If the block mode is KM_MODE_CBC, KM_MODE_CTR, or KM_MODE_GCM, an initialization vector or nonce is needed. In most cases, callers should not provide an IV or nonce and the Keymaster implementation must generate a random IV or nonce and return it via KM_TAG_NONCE in out_params. CBC and CTR IVs are 16 bytes. GCM nonces are 12 bytes. If the key authorizations contain KM_TAG_CALLER_NONCE, then the caller may provide an IV/nonce with KM_TAG_NONCE in in_params. If a nonce is provided when KM_TAG_CALLER_NONCE is not authorized, return KM_ERROR_CALLER_NONCE_PROHIBITED. If a nonce is not provided when KM_TAG_CALLER_NONCE is authorized, generate a random IV/nonce.

HMAC keys

HMAC key operations must specify KM_TAG_MAC_LENGTH in in_params. The specified value must be a multiple of 8 and must not be greater than the digest length, or less than the value of KM_TAG_MIN_MAC_LENGTH in the key authorizations. For MAC lengths greater than the digest length or non-multiples of 8, return KM_ERROR_UNSUPPORTED_MAC_LENGTH. For values less than the key's minimum length, return KM_ERROR_INVALID_MAC_LENGTH.

update

Provides data to process in an ongoing operation started with begin. The operation is specified by the operation_handle parameter.

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 input_consumed 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 will consider this an error and abort the operation.

Implementations may also choose how much data to return, as a result of the update. This is only relevant for encryption and decryption operations, since signing and verification return no data until finish. It is recommended to return data as early as possible, rather than buffer it.

Error handling

If this method returns an error code other than KM_ERROR_OK, the operation is aborted and the operation handle must be invalidated. Any future use of the handle, with this method or finish or abort, must return KM_ERROR_INVALID_OPERATION_HANDLE.

Authorization enforcement

Key authorization enforcement is performed primarily in begin. The one exception is the case where the key has:

• One or more KM_TAG_USER_SECURE_IDs, and
• Does not have a KM_TAG_AUTH_TIMEOUT

In this case, the key requires an authorization per operation, and the update method must receive a KM_TAG_AUTH_TOKEN in the in_params argument. The token must be valid (HMAC must verify) and it must contain a matching secure user ID, must match the key's KM_TAG_USER_AUTH_TYPE, and must contain the operation handle of the current operation in the challenge field. If these requirements aren't met, return KM_ERROR_KEY_USER_NOT_AUTHENTICATED.

The caller must provide the authentication token to every call to update and finish. The implementation need only validate the token once if it prefers.

RSA keys

For signing and verification operations with KM_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. It still must accept the data in multiple updates if the caller chooses to provide it that way, however. If the caller provides more data to sign than can be used (length of data exceeds RSA key size), return KM_ERROR_INVALID_INPUT_LENGTH.

ECDSA keys

For signing and verification operations with KM_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, this method still must accept the data in multiple updates if the caller chooses to provide it that way. If the caller provides more data to sign than can be used, the data should be 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

AES GCM mode supports "associated authentication data," provided via the KM_TAG_ASSOCIATED_DATA tag in the in_params argument. The associated data may be provided in repeated calls (important if the data is too large to send in a single block) but must always precede data to be encrypted or decrypted. An update call may receive both associated data and data to encrypt/decrypt, but subsequent updates may not include associated data. If the caller provides associated data to an update call after a call that includes data to encrypt/decrypt, return KM_ERROR_INVALID_TAG.

For GCM encryption, the tag is appended to the ciphertext by finish. During decryption, the last KM_TAG_MAC_LENGTH bytes of the data provided to the last update call is the tag. Since a given invocation of update cannot know if it's the last invocation, it must process all but the tag length and buffer the possible tag data for processing during finish.

finish

Finished an ongoing operation started with begin, processing all of the as-yet-unprocessed data provided by update(s).

This method is the last one called in an operation, so all processed data must be returned.

Whether it completes successfully or returns an error, this method finalizes the operation and therefore invalidates the provided operation handle. Any future use of the handle, with this method or update or abort, must return KM_ERROR_INVALID_OPERATION_HANDLE.

Signing operations return the signature as the output. Verification operations accept the signature in the signature parameter, and return no output.

Authorization enforcement

Key authorization enforcement is performed primarily in begin. The one exception is the case where the key has:

• One or more KM_TAG_USER_SECURE_IDs, and
• Does not have a KM_TAG_AUTH_TIMEOUT

In this case, the key requires an authorization per operation, and the update method must receive a KM_TAG_AUTH_TOKEN in the in_params argument. The token must be valid (HMAC must verify) and it must contain a matching secure user ID, must match the key's KM_TAG_USER_AUTH_TYPE, and must contain the operation handle of the current operation in the challenge field. If these requirements aren't met, return KM_ERROR_KEY_USER_NOT_AUTHENTICATED.

The caller must provide the authentication token to every call to update and finish. The implementation need only validate the token once if it prefers.

RSA keys

Some additional requirements, depending on the padding mode:

• KM_PAD_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, return KM_ERROR_INVALID_ARGUMENT. For verification and decryption operations, the data must be exactly as long as the key. Otherwise, return KM_ERROR_INVALID_INPUT_LENGTH.
• KM_PAD_RSA_PSS. For PSS-padded signature operations, the PSS salt must be at least 20 bytes in length and randomly-generated. The salt may be longer; the reference implementation uses maximally-sized salt. The digest specified with KM_TAG_DIGEST in input_params on begin is used as the PSS digest algorithm, and SHA1 is used as the MGF1 digest algorithm.
• KM_PAD_RSA_OAEP. The digest specified with KM_TAG_DIGEST in input_params on begin is used as the OAEP digest algorithm, and SHA1 is used as the MGF1 digest algorithm.

ECDSA keys

If the data provided for unpadded signing or verification is too long, truncate it.

AES keys

Some additional requirements, depending on block mode:

• KM_MODE_ECB or KM_MODE_CBC. If padding is KM_PAD_NONE and the data length is not a multiple of the AES block size, return KM_ERROR_INVALID_INPUT_LENGTH. If padding is KM_PAD_PKCS7, pad the data per the PKCS#7 specification. Note that PKCS#7 requires that if the data is a multiple of the block length, an additional padding block must be added.
• KM_MODE_GCM. During encryption, after processing all plaintext, compute the tag (KM_TAG_MAC_LENGTH bytes) and append it to the returned ciphertext. During decryption, process the last KM_TAG_MAC_LENGTH bytes as the tag. If tag verification fails, return KM_ERROR_VERIFICATION_FAILED.

abort

Aborts the in-progress operation. After the call to abort, return KM_ERROR_INVALID_OPERATION_HANDLE for any subsequent use of the provided operation handle with update, finish, or abort.