User Authentication Kit provides the capability of authenticating user identity based on the lock screen password, facial biometrics, fingerprint biometrics, and companion device registered by the user on the device.
It provides system-level user identity authentication functions and a system-level user identity authentication control that integrates multiple authentication modes (lock screen password, facial biometrics, fingerprint biometrics, and companion device) for multiple devices.
When a user requests access to personal data or perform sensitive operations, the application or system service invokes the user authentication widget to verify the user identity. The system responds to the user request accordingly only when the authentication is successful.
User Authentication Kit can be used in authentication scenarios, such as in-app login and payment.
[h2]Companion device scenario
A companion device provides a collaborative authentication capability that help authenticate user identity. The companion device authentication mode is supported since API version 26.0.0. The proxy authentication mode will be supported in the future.
The three elements of companion device authentication are as follows:
-
Trust relationship established between devices: The companion device is added by the user to the primary device as the user's identity authentication credential.
-
User identity confirmation on the companion device: The companion device confirms that the user who is wearing or operating the device is the device owner.
-
Owner authorization confirmation on the primary device: The primary device confirms that the owner is nearby or the owner manually confirms the operation.
For companion device–based seamless authentication, the companion device must be capable of continuously tracking the user.
For companion device–based proxy authentication, the companion device must be capable of independently authenticating the user identity. For example, in the multi-screen collaboration scenario, a PC or 2-in-1 device can be used as a companion device, and users can complete local facial or fingerprint authentication via the device. Currently, this capability is available only to system apps.
[h2]System Identity Authentication Constraints
-
The built-in user authentication widget must be used when a third-party application needs to use the authentication capability of the system.
-
Third-party applications are not allowed to initiate user authentication requests in the background.
-
The system may not support identity authentication methods such as facial and fingerprint authentication due to device hardware differences. You can check whether the system supports these authentication methods by querying the supported authentication capabilities. For details, see userAuth.getAvailableStatus.
[h2]Emulator Support
This kit is supported on the Emulator.
There are some general differences between the Emulator and real devices. For details, see Differences Between the Emulator and the Real Device.
Capabilities
-
Multiple identity authentication capabilities via the unified authentication API
Provides system-level identity authentication capabilities, including lock screen password authentication, facial authentication, fingerprint authentication, and device companion authentication. The core authentication logic is deployed in the Trusted Execution Environment (TEE). The device companion authentication mode is supported since API version 26.0.0.
The differences between different authentication factors are shielded, and the APIs for lock screen password authentication, facial authentication, fingerprint authentication, and device companion authentication are unified.
A set of APIs is provided to support combined authentication modes, such as facial authentication, fingerprint authentication, and lock screen password authentication.
You can also implement a combined authentication approach using facial authentication, fingerprint authentication, and custom authentication.
-
Trust level awareness in authentication
The caller can specify the expected authentication trust level to avoid using low-security authentication capabilities in user authentication scenarios with high risks. For example, 2D facial authentication with insufficient anti-counterfeiting capabilities is used in payment scenarios.
-
Custom authentication modes
User Authentication Kit provides authentication UI with navigation buttons, allowing users to switch to a custom authentication screen.
-
Short-term authentication result reuse
The screen lock authentication result or any application's authentication result can be reused within a caller-specified duration (up to 5 minutes), avoiding redundant authentication requests.
The system supports authentication-agnostic reuse mode. In this mode, the authentication result remains valid regardless of the authentication mode used, as long as it is within the specified duration.
The system also supports authentication-matching reuse mode. In this mode, authentication result is valid only if the same authentication mode is used and the time limit (up to 5 minutes) is not exceeded.
-
System-level user authentication UX
The caller can customize the title of the authentication page and the text on the navigation button.
The user authentication widget automatically adjusts the window display mode based on the screen status.
-
Awareness of the change in credential status
When a service is activated, the system can query the credential status or retrieve it from the authentication result and store the credential status. If the caller needs to detect changes in credentials, it can compare the stored credential status with the latest credential status obtained.
Working Principles
The following figure shows the architecture of the unified user authentication framework.
The unified user authentication framework consists of the following:
-
Unified user authentication APIs: mask differences between authentication factors, making it easier for implementing authentication capabilities.
-
Unified user authentication framework: consists of authentication SAs and drivers, responsible for scheduling various authentication capabilities and the user authentication widget to complete user authentication requests initiated by services through the unified user authentication APIs.
-
Unified user authentication widget: provides interactive authentication interfaces for different authentication modes to ensure consistent user authentication experience. This widget can be called by the unified user authentication framework.
-
Various authentication capabilities: include password authentication, facial authentication, fingerprint authentication, and companion device authentication. These capabilities are used to authenticate user identities based on the lock screen password, facial biometrics, fingerprint biometrics, and companion device, respectively. They are scheduled by the unified user authentication framework.
If the user authentication is successful, the unified user authentication framework issues an AuthToken in the TEE of the device.
As shown on the left side of the above figure, user authentication can also be used to control the access to the keys in the universal keystore. For the keys that can be accessed only with user authentication, the application must provide a key invocation request with the obtained AuthToken to the universal keystore service. The AuthToken serves as authentication proof for secondary access control of the key. After verifying the legitimacy and validity of the AuthToken in the TEE, the universal keystore service responds to the service request and performs the related key operation.
[h2]AuthToken Struct
Plaintext
| Name | Content | Type | Description |
|---|---|---|---|
| version | Token version | uint32_t | Version number. Currently, the version number is 2.0. |
| challenge | Random challenge for authentication | uint8_t[32] | One-off random challenge generated by the service that needs to verify the authentication result. |
| time | Timestamp of successful authentication | uint64_t | Timestamp of successful authentication. In the reuse scenario, the timestamp is the time when the user is successfully authenticated, not the time when the AuthToken is issued during the reuse of the authentication result. |
| authTrustLevel | Authentication trust level | uint32_t | Trust level of the authentication result, which relies on the capabilities of the authentication executor on the device. In normal cases, the trust level should be greater than or equal to authTrustLevel provided by the caller. For details, see Principles for Classifying Biometric Authentication Trust Levels. |
| authType | Authentication type | uint32_t | Authentication type, including authentication based on facial biometrics, fingerprint biometrics, password (specifically, screen lock password), and companion device. |
| authMode | Operation type | uint32_t | Operation types include identification and authentication. |
| securityLevel | Security level of the token issuing environment | uint32_t | Security level of the environment where the token is issued. |
Ciphertext
| Name | Content | Type | Description |
|---|---|---|---|
| userId | User ID. | int32_t | ID allocated by the system to a user when the user is created. |
| secureUid | Secure user ID | uint64_t | ID randomly allocated to a user who enrolls the system password. The ID is deleted when the user deletes the password and remains unchanged when the password is changed. |
| enrolledId | Credential enrollment ID | uint64_t | ID generated each time a credential of this type is enrolled. The ID remains unchanged if the credential is deleted. |
| credentialId | Credential ID | uint64_t | ID of a credential (such as the facial or fingerprint biometrics) enrolled by the user. |
Tag
| Name | Content | Type | Description |
|---|---|---|---|
| tag | Tag of the ciphertext | uint8_t[16] | Tag generated during AES-GCM encryption of the ciphertext. |
| iv | Initialization vector (IV) used to encrypt the ciphertext. | uint8_t[12] | Random IV used for AES-GCM encryption. |
| sign | Signature of the AuthToken | uint8_t[32] | Signature that protects the integrity of the AuthToken. |
[h2]Principles for Classifying Biometric Authentication Trust Levels
The authentication trust level evaluates the security of the user identity authentication capability of the system, which depends on the authentication capability level (ACL) and authentication security level (ASL) of the authentication system.
The system uses three indicators to measure the capability level of a biometric authentication scheme. The following table describes the indicators.
-
False Rejection Rate (FRR): percentage of the times that a user is incorrectly rejected by a system.
-
False Acceptance Rate (FAR): percentage of times that an imposter is incorrectly accepted by a system.
-
Spoof Acceptance Rate (SAR): percentage of times that a non-lived, previously recorded sample is accepted by a system.
A lower FAR corresponds to a higher FRR, which enhances authentication security but increases the probability of erroneously rejecting legitimate users, thereby impairing usability. Conversely, a higher FAR results in a lower FRR, lowering authentication security while improving overall user convenience.
| Authentication Capability Level | Metrics |
|---|---|
| ACL4 | FAR ≤ 0.0001%, SAR ≤ 3% when FRR = 10% |
| ACL3 | FAR ≤ 0.002%, SAR ≤ 7% when FRR = 10% |
| ACL2 | FAR ≤ 0.002%, 7% < SAR ≤ 20% when FRR = 10% |
| ACL1 | FAR ≤ 1%, 7% < SAR ≤ 20% when FRR = 10% |
Generally, the biometric authentication system comprises five execution units: source data collection, biometric feature extraction, biometric feature storage, biometric feature comparison, and authentication result issuance. The following Executor Security Levels (ESLs) are defined for the execution units.
| ESL | Definition |
|---|---|
| ESL3 | Operations are performed in a secure hardware-backed trusted environment, such as a secure coprocessor or a secure element (SE). |
| ESL2 | Operations are performed in a trusted execution environment isolated by a hardware RoT, such as a TEE and an SGX. |
| ESL1 | Operations are performed in an execution environment with access control, such as Linux. |
| ESL0 | Operations are performed in an execution environment without access control, such as a single-process lightweight system. |
The ASL of the entire authentication system is equal to the lowest ESL among the five execution units of biometric authentication. For example, there is a facial authentication system where the feature storage and comparison are performed in a TEE (ESL=2), but the feature extraction algorithm runs in a common system environment (ESL=1), the ASL of the facial authentication system is 1.
The following table lists the mappings between authentication trust levels and ACLs/ASLs.
| Authentication Trust Level | Mapping Rule | Description | Application Scenario |
|---|---|---|---|
| ATL4 | ACL ≥ 3, ASL ≥ 2 | Capable of accurately identifying individual users with strong liveness detection capabilities, such as specially enhanced secure fingerprint and 3D facial authentication. | Small-amount payment. |
| ATL3 | ACL ≥ 3, ASL ≥ 1 ACL ≥ 2, ASL ≥ 2 | Accurately identifies individual users with strong liveness detection capabilities, such as 2D facial authentication with special security enhancements, and companion devices with TEE like smart glasses. | Device unlocking, app login, and account login. |
| ATL2 | ACL ≥ 2, ASL ≥ 1 ACL ≥ 1, ASL ≥ 2 | Accurately identifies individual users with a certain degree of liveness detection capabilities, such as 2D facial authentication capturing images via standard cameras, and companion devices without the TEE or specialized business security enhancements like earbuds. | Maintaining the unlocked state of the device. |
| ATL1 | ACL = 1, ASL = 1 | Identifies individual users with a certain degree of liveness detection capabilities, such as voiceprint authentication. | Service risk control, precise recommendation, and personalized services. |
[h2]Supported Authentication Capabilities
Provides the following system-level identity authentication capabilities: screen lock password authentication, facial authentication, fingerprint authentication, and companion device authentication, with core authentication logic offloaded to the TEE. Companion device authentication is supported from API version 26.0.0.
Screen lock password authentication
The screen lock password input screen is provided by the system-level application. After the screen lock password is collected and anonymized, the password is sent to the password authentication framework for verification within the TEE. During the authentication, the raw password and intermediate calculation result are not transmitted externally, and the user's screen lock password will not be reversely deduced through exhaustive brute-force attacks. Password authentication includes a brute-force protection mechanism. Failed lock screen password verifications increase the user's brute-force attempt count and trigger anti-brute-force penalties.
Facial authentication
The system supports 2D and 3D facial authentication. The 3D facial authentication solution is implemented using a special depth camera lens, while the 2D facial authentication solution is implemented using a common front-facing camera lens. The accuracy and anti-counterfeiting capability of 3D facial authentication are significantly better than those of 2D facial authentication. 3D facial authentication can be used in payment apps, while 2D facial authentication cannot. Different device models select the facial authentication mode based on their product positioning.
A secure channel is established between the cameras and TEE. The facial image information is transmitted to the TEE through the secure channel. The feature extraction, liveness detection, and feature comparison are also performed within the TEE under TrustZone-based security isolation. The external facial framework is only responsible for scheduling facial authentication tasks and transferring data such as facial authentication results, and does not access the original facial image data.
Fingerprint authentication
Currently, capacitive fingerprint and optical fingerprint authentication are supported. They have equivalent user experience and security capabilities. Different device models select the fingerprint authentication technology based on their product positioning.
A secure channel is established between the fingerprint sensor and the TEE. The fingerprint image is transmitted to the TEE through the secure channel. The feature extraction, liveness detection, and feature comparison are also performed in the TEE under TrustZone-based security isolation. The fingerprint authentication framework in the rich execution environment (REE) is only responsible for scheduling fingerprint authentication-related tasks and transferring data such as fingerprint authentication results. It does not access the raw fingerprint data.
Companion Device Authentication
A companion device provides a collaborative authentication capability that helps authenticate user identity.
Companion device authentication is a system-supported user authentication executor. It registers companion device authentication resource information with the unified user authentication framework according to defined resource registration interfaces, and completes the registration, deletion, and authentication of trusted devices under framework orchestration.
When a companion device is added to the primary device, they exchange their authentication-related information. This credential is used to protect the security of the information exchanged during the authentication phase. Therefore, the credential information needs to be stored and used in the TEE on both the primary device and the companion device.
Trust level classification principles for companion device authentication
| Authentication Capability Level | Proof of Companion Device Authentication Relationship | Companion Device Confirming User Identity | Confirming User Intent | Example |
|---|---|---|---|---|
| ACL4 | A random key equivalent in security to an AES 256-bit key is used as the authentication credential. The mutual authentication protocol between the authenticating device and the companion device provides resistance against replay attacks and man-in-the-middle (MITM) attacks, ensuring protocol message transmission does not rely on underlying channel security. | A local multi-factor strong authentication combining biometrics with passwords or passwords with OTP. Authentication factors are retrieved from devices worn on the same user's body or from primary devices located within a range of 0.5 meters. | 1. The primary device confirms that the user is present. User presence detection achieves an accuracy rate of 99% or higher with a state-change latency of less than 1 second when users leave or return. For spatial range detection, the system determines whether the distance between the user and the authenticating device is within 1 meter, maintaining a false positive rate of 1% or less for distances exceeding the threshold. Distance measurement mechanisms are engineered to resist relay attacks. 2. The companion device confirms the user intent. The user performs an intent confirmation operation on a companion device where owner identity has already been verified. Operation commands originate from a companion device with confirmed user identity. During the companion device authentication process, the user undergoes real-time identity authentication on the companion device side. This mechanism ensures 100% reliability and applies across all security levels. | The companion device authentication scheme identifies users via USB keys or electronic token cards, relying on lock screen passwords and One-Time Password (OTP) verification codes for authentication. |
| ACL3 | A random key equivalent in security to an AES 256-bit key is used as the authentication credential. The mutual authentication protocol between the authenticating device and the companion device provides resistance against replay attacks and MITM attacks, ensuring protocol message transmission does not rely on underlying channel security. | A local single-factor strong identity authentication mode (such as passwords, high-security facial recognition, or fingerprint biometrics) is used. Authentication factors are retrieved from primary devices located within a range of 2 meters. | 1. The primary device confirms that the user is present. User presence detection achieves an accuracy rate of 95% or higher with a state-change latency of less than 3 seconds when users leave or return. For spatial range detection, the system determines whether the distance between the user and the authenticating device is within 5 meters, maintaining a false positive rate of 5% or less for distances exceeding the threshold. Distance measurement mechanisms are engineered to resist relay attacks. 2. The companion device confirms the user intent. The user performs an intent confirmation operation on a companion device where owner identity has already been verified. Operation commands originate from a companion device with confirmed user identity. During the companion device authentication process, the user undergoes real-time identity authentication on the companion device side. This mechanism ensures 100% reliability and applies across all security levels. | Companion device authentication scheme using smartwatches based on lock screen password authentication and high-precision, anti-interference distance measurement capabilities. |
| ACL2 | A random key equivalent in security to an AES 128-bit key is used as the authentication credential. The unidirectional authentication protocol (where the primary device authenticates the companion device) provides resistance against replay attacks and MITM attacks, ensuring protocol message transmission does not rely on underlying channel security. | The local identity authentication method with medium security strength is used. Authentication factors are obtained from primary devices within a range of 5 meters. | 1. The primary device confirms that the user is present. User presence detection achieves an accuracy rate of 90% or higher with a state-change latency of less than 3 seconds when users leave or return. For spatial range detection, the system determines whether the distance between the user and the authenticating device is within 10 meters, maintaining a false positive rate of 20% or less for distances exceeding the threshold. 2. The companion device confirms the user intent. The user performs an intent confirmation operation on a companion device where owner identity has already been verified. Operation commands originate from a companion device with confirmed user identity. During the companion device authentication process, the user undergoes real-time identity authentication on the companion device side. This mechanism ensures 100% reliability and applies across all security levels. | Companion device authentication scheme that identifies users via peripherals lacking user authentication capabilities (such as smartbands or earphones) while relying on standard Bluetooth distance measurement. |
| ACL1 | Authentication based on general connection protocols, such as Bluetooth pairing | The local weak authentication method is used. Authentication factors are obtained from the connected primary device. | 1. The primary device confirms that the user is present. No requirements are specified for user presence detection sensitivity or spatial range detection accuracy. However, the system must be capable of evaluating the current connection status of the device. 2. The companion device confirms the user intent. The user performs an intent confirmation operation on a companion device where owner identity has already been verified. Operation commands originate from a companion device with confirmed user identity. During the companion device authentication process, the user undergoes real-time identity authentication on the companion device side. This mechanism ensures 100% reliability and applies across all security levels. | Optional companion device authentication scheme that identifies users via standard Bluetooth-connected devices without distance measurement capabilities. |
| ACL0 | Companion devices are identified using universal device identifiers, such as MAC addresses or serial numbers, without executing an authentication interaction protocol. | The local weak authentication method is used. Authentication factors are obtained from the connected primary device. | 1. The primary device confirms that the user is present. No requirements are specified for user presence detection sensitivity or spatial range detection accuracy. However, the system must be capable of evaluating the current connection status of the device. 2. The companion device confirms the user intent. The user performs an intent confirmation operation on a companion device where owner identity has already been verified. Operation commands originate from a companion device with confirmed user identity. During the companion device authentication process, the user undergoes real-time identity authentication on the companion device side. This mechanism ensures 100% reliability and applies across all security levels. | Companion device authentication scheme based on device connection status for user identification. |
Application scenario
Application scenario 1: Hands-free voice command execution without device unlocking when smart glasses or earphones serve as companion devices
Application scenario 2: Screen-projection phone unlocking following user authentication via tablets or PCs acting as companion devices, mitigating frequent device switching in distributed scenarios