Skip to content

MASTG-KNOW-0043: Android KeyStore

The Android KeyStore provides relatively secure credential storage. As of Android 4.3 (API level 18), it provides public APIs for storing and using app-private keys. An app can use a public key to generate a new private/public key pair to encrypt application secrets, and then decrypt them with the private key.

You can protect keys stored in the Android KeyStore using user authentication via a confirm credential flow. The user's lock screen credentials (pattern, PIN, password, or fingerprint) are used for authentication.

You can use stored keys in one of two modes:

  1. Users are authorized to use keys for a limited time after authentication. In this mode, all keys can be used as soon as the user unlocks the device. You can customize the authorization period for each key. You can use this option only if the secure lock screen is enabled. If the user disables the secure lock screen, all stored keys will become permanently invalid.

  2. Users are authorized to use a specific cryptographic operation associated with one key. In this mode, users must request separate authorization for each operation that involves the key. Currently, fingerprint authentication is the only way to request such authorization.

The security provided by the Android KeyStore depends on its implementation, which varies by device. Most modern devices offer a hardware-backed KeyStore implementation: keys are generated and used in a Trusted Execution Environment (TEE) or a Secure Element (SE), and the operating system can't access them directly. As a result, the encryption keys can't be easily retrieved, even on a rooted device. You can verify hardware-backed keys with Key Attestation. You can determine whether the keys are stored in secure hardware by checking the return value of the isInsideSecureHardware method, which is part of the KeyInfo class.

Note

The relevant KeyInfo indicates that secret and HMAC keys are insecurely stored on several devices, even though private keys are correctly stored on the secure hardware.

In a software-only implementation, the keys are encrypted with a per-user encryption master key. An attacker can access all keys stored on rooted devices that use this implementation in the /data/misc/keystore/ folder. Because the user's lock screen PIN or password is used to generate the master key, the Android KeyStore is unavailable when the device is locked. For added security, Android 9 (API level 28) introduces the unlockedDeviceRequired flag. By passing true to the setUnlockedDeviceRequired method, the app prevents its keys stored in AndroidKeystore from being decrypted when the device is locked and requires the screen to be unlocked before allowing decryption.

Hardware-backed Android KeyStore

The hardware-backed Android KeyStore adds another layer to Android's defense-in-depth security. The Keymaster Hardware Abstraction Layer (HAL) was introduced in Android 6 (API level 23). Applications can verify whether a key is stored in secure hardware by checking whether KeyInfo.isInsideSecureHardware returns true. Devices running Android 9 (API level 28) and higher can include a StrongBox Keymaster module, an implementation of the Keymaster HAL that resides in a hardware security module with its own CPU, secure storage, a true random number generator, and mechanisms to resist tampering. To use this feature, pass true to the setIsStrongBoxBacked method in either the KeyGenParameterSpec.Builder class or the KeyProtection.Builder class when generating or importing keys using AndroidKeystore. To ensure StrongBox is used at runtime, verify that isInsideSecureHardware returns true and that the system does not throw StrongBoxUnavailableException, which is thrown if the StrongBox Keymaster isn't available for the given algorithm and key size associated with a key. A description of the features of the hardware-based keystore can be found on the AOSP pages. You can also check the Android Device Security Database to see which devices support StrongBox and other hardware security features.

Keymaster HAL is an interface to hardware-backed components, such as a Trusted Execution Environment (TEE) or a Secure Element (SE), that Android Keystore uses. An example of such a hardware-backed component is Titan M.