This page provides details to assist implementers of Keymaster HALs. It covers each tag and each function in the HAL.
Except as noted in the tag descriptions, all of the tags below are used during key generation to specify key characteristics.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
Reserved for future use.
This tag is not repeatable.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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
The following guidelines apply to all functions in the API.
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.
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.
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.
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.
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.
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:
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.
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).
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.
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.
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.
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.
The following parameters are required when generating an RSA key.
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_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_DIGEST_NONE.
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.
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.
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.
The following parameters are required for HMAC key generation:
KM_ERROR_UNSUPPORTED_DIGEST. If the digest is not supported
by the trustlet, return KM_ERROR_UNSUPPORTED_DIGEST.
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 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.
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:
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_ERROR_IMPORT_PARAMETER_MISMATCH.
KM_ORIGIN_IMPORTED.
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.
Deletes the provided key. This method is optional, and will likely be implemented only by Keymaster modules that provide rollback resistance.
Deletes all keys. This method is optional, and will likely be implemented only by Keymaster modules that provide rollback resistance.
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.
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_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_ERROR_KEY_NOT_YET_VALID.
KM_PURPOSE_ENCRYPT or KM_PURPOSE_SIGN,
the method must return KM_ERROR_KEY_EXPIRED.
KM_PURPOSE_DECRYPT or KM_PURPOSE_VERIFY,
the method must return KM_ERROR_KEY_EXPIRED.
KM_ERROR_KEY_RATE_LIMIT_EXCEEDED. See the tag description for
important implementation requirements.
KM_ERROR_KEY_MAX_OPS_EXCEEDED.
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_ERROR_CALLER_NONCE_PROHIBITED must be returned.
KM_ERROR_INVALID_KEY_BLOB.
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 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 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 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.
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.
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.
Key authorization enforcement is performed primarily in begin. The one exception is the case where the key has:
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.
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.
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 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.
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.
Key authorization enforcement is performed primarily in begin. The one exception is the case where the key has:
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.
Some additional requirements, depending on the padding mode:
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.
input_params on begin is used as the PSS digest algorithm, and SHA1 is used as the MGF1 digest
algorithm.
input_params on begin is used as the OAEP digest algorithm, and SHA1 is used as the MGF1 digest
algorithm.
If the data provided for unpadded signing or verification is too long, truncate it.
Some additional requirements, depending on block mode:
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_ERROR_VERIFICATION_FAILED.
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.