Features

This page contains information about the cryptographic features of Keystore in Android 6.0 and above.

Cryptographic primitives

Keystore provides the following categories of operations:

  • Key generation
  • Import and export of asymmetric keys (no key wrapping)
  • Import of raw symmetric keys (no key wrapping)
  • Asymmetric encryption and decryption with appropriate padding modes
  • Asymmetric signing and verification with digesting and appropriate padding modes
  • Symmetric encryption and decryption in appropriate modes, including an AEAD mode
  • Generation and verification of symmetric message authentication codes

Protocol elements, such as purpose, mode and padding, as well as access control constraints, are specified when keys are generated or imported and are permanently bound to the key, ensuring the key cannot be used in any other way.

In addition to the list above, there is one more service that Keymaster implementations provide, but which isn't exposed as an API: Random number generation. This is used internally for generation of keys, Initialization Vectors (IVs), random padding and other elements of secure protocols that require randomness.

Necessary primitives

All Keymaster implementations provide:

  • RSA
    • 2048, 3072, and 4096-bit key support
    • Support for public exponent F4 (2^16+1)
    • Padding modes for RSA signing:
      • RSASSA-PSS (PaddingMode::RSA_PSS)
      • RSASSA-PKCS1-v1_5 (PaddingMode::RSA_PKCS1_1_5_SIGN)
    • Digest modes for RSA signing:
      • SHA-256
    • Padding modes for RSA encryption/decryption:
      • Unpadded
      • RSAES-OAEP (PaddingMode::RSA_OAEP)
      • RSAES-PKCS1-v1_5 (PaddingMode::RSA_PKCS1_1_5_ENCRYPT)
  • ECDSA
    • 224, 256, 384, and 521-bit key support are supported, using the NIST P-224, P-256, P-384, and P-521 curves, respectively
    • Digest modes for ECDSA:
      • No digest (deprecated, will be removed in the future)
      • SHA-256
  • AES
    • 128 and 256-bit keys are supported
    • CBC, CTR, ECB, and GCM. The GCM implementation does not allow the use of tags smaller than 96 bits or nonce lengths other than 96 bits.
    • Padding modes PaddingMode::NONE and PaddingMode::PKCS7 is supported for CBC and ECB modes. With no padding, CBC or ECB mode encryption fails if the input isn't a multiple of the block size.
  • HMAC SHA-256, with any key size up to at least 32 bytes.

SHA1 and the other members of the SHA2 family (SHA-224, SHA384 and SHA512) are strongly recommended for Keymaster implementations. Keystore provides them in software if the hardware Keymaster implementation doesn't provide them.

Some primitives are also recommended for interoperability with other systems:

  • Smaller key sizes for RSA
  • Arbitrary public exponents for RSA

Key access control

Hardware-based keys that can never be extracted from the device don't provide much security if an attacker can use them at will (though they're more secure than keys which can be exfiltrated). Thus, it's crucial that Keystore enforce access controls.

Access controls are defined as an "authorization list" of tag/value pairs. Authorization tags are 32-bit integers and the values are a variety of types. Some tags can be repeated to specify multiple values. Whether a tag can be repeated is specified in the documentation for the tag. When a key is created, the caller specifies an authorization list. The Keymaster implementation underlying Keystore modifies the list to specify some additional information, such as whether the key has rollback protection, and return a "final" authorization list, encoded into the returned key blob. Any attempt to use the key for any cryptographic operation fails if the final authorization list is modified.

For Keymaster 2 and earlier, the set of possible tags is defined in the enumeration keymaster_authorization_tag_t and is permanently fixed (though it can be extended). Names were prefixed with KM_TAG. The top four bits of tag IDs are used to indicate the type.

Keymaster 3 changed the KM_TAG prefix to Tag::.

Possible types include:

ENUM: Many tags' values are defined in enumerations. For example, the possible values of TAG::PURPOSE are defined in enum keymaster_purpose_t.

ENUM_REP: Same as ENUM, except that the tag can be repeated in an authorization list. Repetition indicates multiple authorized values. For example, an encryption key likely has KeyPurpose::ENCRYPT and KeyPurpose::DECRYPT.

UINT: 32-bit unsigned integers. Example: TAG::KEY_SIZE

UINT_REP: Same as UINT, except that the tag can be repeated in an authorization list. Repetition indicates multiple authorized values.

ULONG: 64-bit unsigned integers. Example: TAG::RSA_PUBLIC_EXPONENT

ULONG_REP: Same as ULONG, except that the tag can be repeated in an authorization list. Repetition indicates multiple authorized values.

DATE: Date/time values, expressed as milliseconds since January 1, 1970. Example: TAG::PRIVKEY_EXPIRE_DATETIME

BOOL: True or false. A tag of type BOOL is assumed to be "false" if the tag isn't present and "true" if present. Example: TAG::ROLLBACK_RESISTANT

BIGNUM: Arbitrary-length integers, expressed as a byte array in big-endian order. Example: TAG::RSA_PUBLIC_EXPONENT

BYTES: A sequence of bytes. Example: TAG::ROOT_OF_TRUST

Hardware versus software enforcement

Not all secure hardware implementations contain the same features. To support a variety of approaches, Keymaster distinguishes between secure and non-secure world access control enforcement, or hardware and software enforcement, respectively.

All implementations:

  • Enforce exact matching (not enforcement) of all authorizations. Authorization lists in key blobs exactly match the authorizations returned during key generation, including ordering. Any mismatch causes an error diagnostic.
  • Declare the authorizations whose semantic values are enforced.

The API mechanism for declaring hardware-enforced authorizations is in the keymaster_key_characteristics_t structure. It divides the authorization list into two sub-lists, hw_enforced and sw_enforced. The secure hardware is responsible for placing the appropriate values in each, based on what it can enforce.

In addition, Keystore implements software-based enforcement of all authorizations, whether they're enforced by the secure hardware or not.

For example, consider a TrustZone-based implementation that does not support key expiration. A key with an expiration date might still be created. That key's authorization list includes the tag TAG::ORIGINATION_EXPIRE_DATETIME with the expiration date. A request to Keystore for the key characteristics finds this tag in the sw_enforced list and the secure hardware doesn't enforce the expiration requirement. However, attempts to use the key after expiration are rejected by Keystore.

If the device is then upgraded with secure hardware that does support expiration, then a request for key characteristics finds TAG::ORIGINATION_EXPIRE_DATETIME in the hw_enforced list, and attempts to use the key after expiration fails even if the keystore is subverted or bypassed.

For more information about determining whether keys are hardware-backed, see Key attestation.

Cryptographic message construction authorizations

The following tags are used to define the cryptographic characteristics of operations using the associated key: TAG::ALGORITHM, TAG::KEY_SIZE, TAG::BLOCK_MODE, TAG::PADDING, TAG::CALLER_NONCE, and TAG::DIGEST

TAG::PADDING, TAG::DIGEST, and PaddingMode::BLOCK_MODE are repeatable, meaning that multiple values can be associated with a single key, and the value to be used is specified at operation time.

Purpose

Keys have an associated set of purposes, expressed as one or more authorization entries with tag TAG::PURPOSE, which defines how they can be used. The purposes are:

  • KeyPurpose::ENCRYPT
  • KeyPurpose::DECRYPT
  • KeyPurpose::SIGN
  • KeyPurpose::VERIFY

Any key can have any subset of these purposes. Note that some combinations create security problems. For example, an RSA key that can be used to both encrypt and to sign allows an attacker who can convince the system to decrypt arbitrary data to generate signatures.

Import and export

Keymaster supports export of public keys only, in X.509 format, and import of:

  • Public and private key pairs in DER-encoded PKCS#8 format, without password-based encryption
  • Symmetric keys as raw bytes

To ensure that imported keys can be distinguished from securely generated keys, TAG::ORIGIN is included in the appropriate key authorization list. For example, if a key was generated in secure hardware, TAG::ORIGIN with value KeyOrigin::GENERATED is found in the hw_enforced list of the key characteristics, while a key that was imported into secure hardware has the value KeyOrigin::IMPORTED.

User authentication

Secure Keymaster implementations do not implement user authentication, but depend on other trusted apps which do. For the interface that these apps implement, see the Gatekeeper page.

User authentication requirements are specified via two sets of tags. The first set indicate which user can use the key:

  • TAG::ALL_USERS indicates the key is usable by all users. If present, TAG::USER_ID and TAG::USER_SECURE_ID is not present.
  • TAG::USER_ID has a numeric value specifying the ID of the authorized user. Note that this is the Android user ID (for multi-user), not the app UID, and it is enforced by non-secure software only. If present, TAG::ALL_USERS isn't present.
  • TAG::USER_SECURE_ID has a 64-bit numeric value specifying the secure user ID that is provided in a secure authentication token to unlock use of the key. If repeated, the key can be used if any of the values is provided in a secure authentication token.

The second set indicates whether and when the user needs to be authenticated. If neither of these tags is present, but TAG::USER_SECURE_ID is, authentication is required for every use of the key.

  • NO_AUTHENTICATION_REQUIRED indicates no user authentication is required, though the key still can be used only by apps running as the users specified by TAG::USER_ID.
  • TAG::AUTH_TIMEOUT is a numeric value specifying, in seconds, how fresh the user authentication needs to be to authorize key usage. This applies only to private/secret key operations. Public key operations don't require authentication. Timeouts don't cross reboots; after a reboot, all keys are never authenticated. The timeout can be set to a large value to indicate that authentication is required once per boot (2^32 seconds is ~136 years; presumably Android devices are rebooted more often than that).

Require an unlocked device

Keys with TAG::UNLOCKED_DEVICE_REQUIRED are usable only while the device is unlocked. For the detailed semantics, see KeyProtection.Builder#setUnlockedDeviceRequired(boolean).

UNLOCKED_DEVICE_REQUIRED is enforced by Keystore, not by Keymaster. However, in Android 12 and higher, Keystore cryptographically protects UNLOCKED_DEVICE_REQUIRED keys while the device is locked to ensure that, in most cases, they cannot be used even if Keystore is compromised while the device is locked.

To achieve this, Keystore "superencrypts" all UNLOCKED_DEVICE_REQUIRED keys before storing them in its database, and when possible it protects the superencryption keys (super keys) while the device is locked in such a way that they can be recovered only by a successful device unlock. (The term "superencryption" is used because this layer of encryption is applied in addition to the layer of encryption that Keymaster already applies to all keys.)

Each user (including profiles) has two super keys associated with UNLOCKED_DEVICE_REQUIRED:

  • The UnlockedDeviceRequired symmetric super key. This is an AES‑256‑GCM key. It encrypts UNLOCKED_DEVICE_REQUIRED keys that are imported or generated while the device is unlocked for the user.
  • The UnlockedDeviceRequired asymmetric super key. This is an ECDH P‑521 key pair. It encrypts UNLOCKED_DEVICE_REQUIRED keys that are imported or generated while the device is locked for the user. Keys that are encrypted with this asymmetric key are re-encrypted with the symmetric key on first use (which can occur only while the device is unlocked).

Keystore generates these super keys at user creation time and stores them in its database, encrypted by the user's synthetic password. This allows them to be recovered using PIN, pattern, or password equivalent.

Keystore also caches these super keys in memory, allowing it to operate on UNLOCKED_DEVICE_REQUIRED keys. However, it tries to cache the secret parts of these keys only while the device is unlocked for the user. When the device is locked for the user, Keystore zeroizes its cached copy of the secret parts of these super keys, if possible. Specifically, when the device is locked for the user, Keystore selects and applies one of three protection levels for the user's UnlockedDeviceRequired super keys:

  • If the user has only PIN, pattern, or password enabled, then Keystore zeroizes the secret parts of its cached super keys. This makes the super keys recoverable only via the encrypted copy in the database that can be decrypted only by PIN, pattern, or password equivalent.
  • If the user has only class 3 ("strong") biometrics and PIN, pattern, or password enabled, then Keystore arranges for the super keys to be recoverable by any of the user's enrolled class 3 biometrics (commonly fingerprint), as an alternative to PIN, pattern, or password equivalent. To do this, it generates a new AES‑256‑GCM key, encrypts the secret parts of the super keys with it, imports the AES‑256‑GCM key into Keymaster as a biometric-bound key that requires biometric authentication to have succeeded within the last 15 seconds, and zeroizes the plaintext copies of all these keys.
  • If the user has a class 1 ("convenience") biometric, class 2 ("weak") biometric, or active unlock trust agent enabled, then Keystore keeps the super keys cached in plaintext. In this case, cryptographic security for UNLOCKED_DEVICE_REQUIRED keys isn't provided. Users can avoid this less secure fallback by not enabling these unlock methods. The most common unlock methods that fall into these categories are face unlock on many devices, and unlock with a paired smartwatch.

When the device is unlocked for the user, Keystore recovers the user's UnlockedDeviceRequired super keys if possible. For PIN, pattern, or password equivalent unlock, it decrypts the copy of these keys that is stored in the database. Otherwise, it checks if it saved a copy of these keys encrypted with a biometric-bound key, and if so tries to decrypt that. This succeeds only if the user has successfully authenticated with a class 3 biometric within the last 15 seconds, enforced by Keymaster (not Keystore).

Client binding

Client binding, the association of a key with a particular client app, is done via an optional client ID and some optional client data (TAG::APPLICATION_ID and TAG::APPLICATION_DATA, respectively). Keystore treats these values as opaque blobs, only ensuring that the same blobs presented during key generation/import are presented for every use and are byte-for-byte identical. The client binding data isn't returned by Keymaster. The caller has to know it in order to use the key.

This feature isn't exposed to apps.

Expiration

Keystore supports restricting key usage by date. Key start of validity and key expirations can be associated with a key and Keymaster refuses to perform key operations if the current date/time is outside of the valid range. The key validity range is specified with the tags TAG::ACTIVE_DATETIME, TAG::ORIGINATION_EXPIRE_DATETIME, and TAG::USAGE_EXPIRE_DATETIME. The distinction between "origination" and "usage" is based on whether the key is being used to "originate" a new ciphertext/signature/etc., or to "use" an existing ciphertext/signature/etc. Note that this distinction isn't exposed to apps.

The TAG::ACTIVE_DATETIME, TAG::ORIGINATION_EXPIRE_DATETIME, and TAG::USAGE_EXPIRE_DATETIME tags are optional. If the tags are absent, it is assumed that the key in question can always be used to decrypt/verify messages.

Because wall-clock time is provided by the non-secure world, it's unlikely that the expiration-related tags are in the hardware-enforced list. Hardware enforcement of expiry would require that the secure world somehow obtain trusted time and data, for example, through a challenge response protocol with a trusted remote timeserver.

Root of trust binding

Keystore requires keys to be bound to a root of trust, which is a bitstring provided to the Keymaster secure hardware during startup, preferably by the bootloader. This bitstring is cryptographically bound to every key managed by Keymaster.

The root of trust consists of the public key used to verify the signature on the boot image and the lock state of the device. If the public key is changed to allow a different system image to be used or if the lock state is changed, then none of the Keymaster-protected keys created by the previous system are usable, unless the previous root of trust is restored and a system that is signed by that key is booted. The goal is to increase the value of the software-enforced key access controls by making it impossible for an attacker-installed operating system to use Keymaster keys.

Standalone keys

Some Keymaster secure hardware can choose to store key material internally and return handles rather than encrypted key material. Or there might be other cases in which keys cannot be used until some other non-secure or secure world system component is available. The Keymaster HAL allows the caller to request that a key be "standalone," via the TAG::STANDALONE tag, meaning that no resources other than the blob and the running Keymaster system are required. The tags associated with a key can be inspected to see whether a key is standalone. At present, only two values are defined:

  • KeyBlobUsageRequirements::STANDALONE
  • KeyBlobUsageRequirements::REQUIRES_FILE_SYSTEM

This feature isn't exposed to apps.

Velocity

When it's created, the maximum usage velocity can be specified with TAG::MIN_SECONDS_BETWEEN_OPS. TrustZone implementations refuse to perform cryptographic operations with that key if an operation was performed less than TAG::MIN_SECONDS_BETWEEN_OPS seconds earlier.

The simple approach to implementing velocity limits is a table of key IDs and last-use timestamps. This table is a limited size, but accommodates at least 16 entries. In the event that the table is full and no entries can be updated or discarded, secure hardware implementations "fail safe," preferring to refuse all velocity-limited key operations until one of the entries expires. It is acceptable for all entries to expire upon reboot.

Keys can also be limited to n uses per boot with TAG::MAX_USES_PER_BOOT. This also requires a tracking table, which accommodates at least four keys and also fails safe. Note that apps can't create per-boot limited keys. This feature isn't exposed through Keystore and is reserved for system operations.

This feature isn't exposed to apps.

Random number generator re-seeding

Because secure hardware generates random numbers for key material and initialization vectors (IVs), and because hardware random number generators might not always be fully trustworthy, the Keymaster HAL provides an interface to allow the client to provide additional entropy, which is mixed into the random numbers generated.

Use a hardware random-number generator as the primary seed source. The seed data provided through the external API can't be the sole source of randomness used for number generation. Further, the mixing operation used needs to ensure that the random output is unpredictable if any one of the seed sources is unpredictable.

This feature isn't exposed to apps but is used by the framework, which regularly provides additional entropy, retrieved from a Java SecureRandom instance, to the secure hardware.