User authentication (PIN, pattern, password) is the primary gateway to a secure Android device. Validating these credentials securely is critical, as they protect the device decryption keys. Android manages this process using the Gatekeeper subsystem.
The Gatekeeper HAL
The Gatekeeper subsystem consists of a userspace daemon (gatekeeperd) and a Hardware Abstraction Layer (HAL). Like KeyMint, the Gatekeeper HAL must be implemented within an isolated secure environment, typically a Trusted Execution Environment (TEE) like ARM TrustZone.
The Android OS never verifies the password directly. Instead, when a user enters a PIN on the lock screen, the framework passes the plain text PIN to gatekeeperd, which sends it down to the Gatekeeper HAL in the TEE. The TEE performs the verification and returns the result to Android.
PIN/Pattern/Password Verification in TEE
When a user sets up a PIN, the Gatekeeper HAL in the TEE derives a secure hash of the PIN. Crucially, this hash incorporates a hardware-specific secret key that is physically burned into the device's secure silicon and is inaccessible to the Android OS.
This hardware binding means that even if an attacker extracts the hashed password file from the /data/system/gatekeeper directory, they cannot perform an offline brute-force attack on a different device or a standard PC. The hash is useless without the specific device's hardware secret.
When the user unlocks the device, the entered PIN is hashed in the TEE using the same hardware secret and compared against the stored hash.
Secure User ID (SUID) and Auth Tokens
When Gatekeeper successfully verifies a credential, it doesn't just return a boolean "true" to Android. It generates a cryptographic Hardware Authentication Token (HAT).
This token contains:
- The Secure User ID (SUID), representing the authenticated user.
- A timestamp of the authentication event.
- A cryptographic HMAC generated by the TEE, proving the token's authenticity.
This Auth Token is passed back to Android and is subsequently used to unlock cryptographic keys stored in KeyMint. KeyMint can be configured to require a valid Auth Token (e.g., "user authenticated within the last 5 minutes") before it will perform operations with a specific key. KeyMint verifies the HMAC on the token using a shared secret between Gatekeeper and KeyMint (established entirely within the TEE), bypassing the Android OS completely for the security check.
Throttling Failed Attempts
One of Gatekeeper's most important functions is preventing online brute-force attacks. Because the PIN is often short (e.g., 4 or 6 digits), it would be trivial to guess programmatically if unchecked.
The Gatekeeper HAL implementation inside the TEE enforces strict rate limiting. After a certain number of failed attempts, it implements an exponentially increasing timeout. Because this timeout logic resides within the TEE, a compromised Android OS cannot bypass it. Even if an attacker roots the device and tries to feed PINs directly to the HAL, the TEE will refuse to process them until the timeout expires. If the device reboots during a timeout, the TEE securely stores the state and resumes the timeout upon boot.