Keystore and hardware keys

The strongest encryption in the world is useless if the key is sitting in the same process as the data. Keystore's design premise is simple and strict: the key is never in your app's memory, and on most devices it is never in Android's memory either.

TL;DR#

• Keystore (glossary definition) is a system service that stores and uses keys. Apps ask for operations, not for key material.
• The key blob is encrypted such that Keystore can store it but not use it or reveal it. The operations happen in a TEE (glossary definition) or, on some devices, a StrongBox (glossary definition) chip.
• The hardware interface is KeyMint (glossary definition), which replaced Keymaster in Android 12.
• Attestation (glossary definition) gives a remote server a signed statement about the key and the device's security state.
• Keys can be bound to the user's authentication, so they are usable only after a recent unlock.

Mental model#

Think of a bank's safe-deposit service.

You do not take your valuables home with you. You give them to the bank, which puts them in a vault you cannot enter. When you need to use them, you go to the counter, prove who you are, and ask the bank to perform an operation. The bank does the operation inside the vault and hands you the result.

Keystore is the counter. The vault is the TEE. The proof of identity is your app's UID and, for auth-bound keys, a recent biometric or credential check.

Where the analogy breaks#

A bank holds your valuables; Keystore may never have seen the key in the clear at all. The key can be generated inside the vault and never leave it, which is a stronger property than custody. And a bank can be robbed; the threat model for the TEE assumes an attacker with code execution in Android and tries to remain safe against it.

The big picture#

Deep dive#

The components#

Four pieces, each in a different privilege domain:

1. AndroidKeyStore provider — the Java API an app calls.
2. The keystore daemon — a system service (keystore2) that owns key blobs and enforces access control. It is written in Rust since Android 12.
3. The KeyMint HAL — the interface to the secure environment, implementing IKeyMintDevice.aidl.
4. The KeyMint trusted app — the code inside the TEE that actually performs cryptographic operations and validates access-control conditions.

The key insight is at step 3: the HAL implementation is not supposed to perform sensitive operations in user space, or even in kernel space.¹ The operation happens in the secure environment.

Key descriptors and access control#

A key is identified by a descriptor that combines a domain with an identity:

• APP — the app's alias plus the caller's UID. The normal case.
• KEY_ID — an internal numeric id.
• GRANT — app-to-app delegation by UID.
• BLOB — system-only; the client stores the keyblob, used by vold for file encryption.
• SELINUX — system-only sharing by numeric SELinux label.

Each key carries authorizations that the TEE enforces before any operation: the purpose (encrypt, decrypt, sign, verify), the padding and digest, the key size, and whether authentication is required.

Authentication binding#

An auth-bound key is usable only if the user has authenticated recently. The mechanism involves three components: LockSettingsService (which knows the credential), Gatekeeper (which verifies it), and the biometric stack (which verifies a biometric and produces a token).

The token has a time limit and is signed by the secure environment. When an app requests an operation on an auth-bound key, it supplies the token, and the TEE checks it. That is why a banking app can require "fingerprint within the last 30 seconds" without the app having to enforce anything itself.

Attestation#

Key attestation is a signed certificate chain that describes the key and the device:²

• The key's algorithm, size, purposes and authorizations.
• Whether it is hardware-backed, and whether it is in a TEE or StrongBox.
• The device's verified boot state and lock state.
• The system and vendor patch levels.
• An ID attestation extension (from Android 8) that can include the serial number, product name and IMEI/MEID.

A remote server can verify the chain against Google's root and decide whether to trust the device. That is how a banking app can distinguish a genuine device with a locked bootloader from an emulator or a tampered one — without trusting the app, which might itself be running on a compromised device.

StrongBox versus TEE#

A TEE is a secure execution mode on the main SoC, with its own memory that Android cannot read. It is the default for hardware-backed keys on most devices.

StrongBox is a discrete security chip, separate from the SoC. It offers stronger isolation — a compromise of the SoC does not necessarily compromise the chip — at the cost of performance and silicon area.

An app can request StrongBox for a key, and it must handle the case where the device does not have one: setIsStrongBoxBacked(true) on a device without StrongBox fails, and the app should fall back to the TEE.

Biometrics#

The biometric stack is adjacent to Keystore and often confused with it.

BiometricPrompt is the API. Behind it, BiometricService coordinates the available modalities — fingerprint, face, iris — each implemented by a vendor HAL. The important security property is that a biometric match does not unlock a key directly. It produces an auth token, and that token satisfies the auth-bound key's condition.

That indirection is what allows the biometric to be spoofed-resistant in the way the platform measures: the biometric security classification (Class 3, formerly Strongunverified(the Class 1/2/3 naming replaced Strong/Weak in Android 11; the exact introduction is not confirmed here)) is about the sensor and the matching algorithm, and the token is the interface between that classification and the key policy.

What Keystore cannot protect#

• A rooted device with a compromised TEE. The threat model assumes the TEE is intact. If the vendor's TEE implementation is broken, the key protections are broken.
• A user who unlocks for an attacker. Auth-bound keys are bound to authentication, not to intent.
• A malicious app with the same UID. Keystore's identity is the UID; an app that can run code in your UID can use your keys.
• Screenshot-based exfiltration. Keystore protects keys, not the data they decrypt.

How it evolved#

The trajectory: a software keystore, then a hardware-backed one (Keymaster), then a Rust rewrite and a new HAL (KeyMint, Android 12), then attestation becoming the interface that remote services actually use. Each step moved more of the guarantee into hardware and more of the verification into cryptography.

Under the hood#

• ‹›↗the keystore daemon, rewritten in Rust for Android 12
• ‹›IKeystoreService.aidl↗the daemon's Binder interface
• ‹›IKeyMintDevice.aidl↗the HAL interface to the secure environment
• ‹›KeyPermission.aidl↗the per-key operation permissions

Curiosity corner#

• keystore2 is one of Android's largest Rust components. It is a security-critical daemon parsing untrusted input, which is exactly the profile Rust is chosen for.
• SELinux IDs for Keystore are partitioned by partition. System, system-ext, product and vendor each get a numeric range, so a vendor key cannot collide with a platform key.
• A key can be created with an expiry date and a usage count. The authorizations are enforced by the TEE, so a key can be made unusable after N operations or after a date, without any app logic.

Try it#

$ 
adb shell service list | grep keystore
adb shell dumpsys android.security.keystore2 | head -30
adb shell getprop ro.hardware.keystore

The ro.hardware.keystore property names the KeyMint implementation on the device, which is a rough indication of the secure environment behind it.

Check yourself#

Sources#