Weaver

The Weaver Hardware Abstraction Layer (HAL) (IWeaver.aidl), introduced in Android 8.1, provides a secure interface for user authentication with Lock Screen Knowledge Factor (LSKF) such as PIN, pattern, and password.

Weaver supersedes the LSKF-verification functionality of Gatekeeper. However, Gatekeeper is still used to generate hardware authentication tokens.

In Android 9 and higher, CDD 9.11.2 requires devices supporting StrongBox to provide dedicated secure hardware that backs secure user authentication. Implementing the Weaver HAL using this secure hardware satisfies the "secure user authentication" requirement.

On devices without a dedicated Secure Element (SE), Weaver can still be implemented in a Trusted Execution Environment (TEE) such as Trusty.

Components

Weaver consists of three components:

  • Weaver AIDL interface (IWeaver): The formal specification of the HAL. Android 13 and lower used HIDL instead of AIDL.
  • Weaver Hardware Abstraction Layer (HAL) service: A vendor-specific Android process that implements the IWeaver interface.
  • Weaver Trusted Application (TA): The core logic running in a secure environment. It does LSKF verification and enforces rate-limiting. The HAL service communicates with the TA using an implementation-specific secure channel.

Interface

Weaver's interface presents a fixed-size array of persistent slots, each containing a fixed-size key and a fixed-size value. Each slot is identified by its ID, an integer in the interval [0, numSlots - 1]. A slot's value is accessible only when a key matching the stored key is provided.

Weaver's interface consists of:

  • getConfig(): Retrieves the number of slots, key size, and value size supported by the implementation.
  • write(): Overwrites the specified slot with a new key-value pair. This operation is atomic and renders previous data permanently unrecoverable (secure deletion).
  • read(): Attempts to retrieve the value of the specified slot. This succeeds only when the rate-limiting timeout (enforced by the TA) isn't active and the provided key exactly matches the stored key.

For the full interface specification, see IWeaver.aidl.

Use by Android

When a Weaver implementation is available, LockSettingsService in the Android system server uses it to protect user data. For every user on the device, LockSettingsService manages a Weaver slot:

  • Slot key (weaverKey): A hash of the user's LSKF. If the user doesn't have a screen lock, a default string is used.
  • Slot value (weaverSecret): A high-entropy, randomly generated cryptographic secret.

The weaverSecret is designed to be retrieved only by either:

  • Providing the correct weaverKey to the Weaver TA within its rate-limiting policy.
  • Compromising the secure environment in which the Weaver TA runs. This is intended to be very difficult.

LockSettingsService uses both weaverKey and weaverSecret to encrypt the user's Synthetic Password. Because the Synthetic Password protects the user's Credential-Encrypted (CE) storage for File-Based Encryption (FBE) and the user's authentication-bound keys in the Android Keystore, data remains inaccessible until Weaver releases the secret.

Weaver vs. Gatekeeper

Historically, the Gatekeeper HAL performed two distinct roles in a single verify() call:

  1. Verification: Checking the LSKF, with TEE-enforced rate-limiting.
  2. Attestation: Issuing a HardwareAuthToken to notify KeyMint (previously Keymaster) that LSKF authentication succeeded.

Why the shift to Weaver?

With the introduction of secure passcode reset tokens in Android 8.1, the "Synthetic Password" became the primary cryptographic secret. The two roles described above are now handled by separate Gatekeeper enrollments, one for the LSKF under userId + 100000 and one for the Synthetic Password under userId.

Weaver was introduced to take over the first role, using a simpler HAL interface with support for Secure Element (SE) based implementations.

Feature Weaver Gatekeeper
Secure Deletion Secure deletion is required, and it's easy to implement it because the interface uses a fixed number of fixed-size slots. Secure deletion isn't required, and it's difficult to implement it because the interface supports an unbounded number of enrollments.
Hardware Optimized for SEs, but also works in TEEs. Effectively TEE-only. Implementing it in a SE doesn't provide a security benefit with the current design.
Error Handling Clearer error codes Ambiguous error codes. As a result, the lock screen doesn't differentiate between incorrect LSKFs and unrelated failures.
Atomicity The code in LockSettingsService that uses Weaver performs LSKF changes atomically. New data is written into a new Weaver slot, and the old slot is erased only when it's safe to do so. The code in LockSettingsService that uses Gatekeeper doesn't perform LSKF changes atomically. All user data may be lost if something goes wrong while the LSKF is being changed.

Reference code

Reference code for Weaver implementations in ISO/IEC7816-4 compatible secure elements is available in AOSP: external/libese/.

Testing

To validate a Weaver implementation, use VtsHalWeaverTargetTest: 

atest VtsHalWeaverTargetTest

or:

vts-tradefed run vts -m VtsHalWeaverTargetTest