# User Authentication Kit简介

User Authentication Kit（用户认证服务）提供了基于用户在设备本地注册的锁屏口令、人脸、指纹、伴随设备来认证用户身份的能力。

提供了系统级用户身份认证功能，并提供了多设备统一的、集多种认证方式（锁屏口令、人脸、指纹、伴随设备）于一体的系统级用户身份认证控件。

用户向应用/系统服务请求访问某些个人数据或执行某些敏感操作时，应用/系统服务将调用系统用户身份认证控件对用户身份进行认证，认证通过后，响应用户对于数据或敏感操作的执行请求。

用户身份认证可用于各种鉴权场景，如应用内账号登录、支付认证等。

## 场景介绍

### 单设备场景（口令认证、指纹认证、人脸认证）

![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/a8/v3/O6sWvNQvQda03A8Ij8Ssfw/zh-cn_image_0000002773904708.png?HW-CC-KV=V1&HW-CC-Date=20261026T101434Z&HW-CC-Expire=31536000000&HW-CC-Sign=6CADF332F3210860E78FCFCDC69B56C976609F5EF86C710738938CFD09D39B21)

### 伴随设备场景

伴随设备是一种协同认证能力，提供基于用户所持有的伴随设备对用户进行身份认证的功能。伴随设备认证的方式，从API版本26.0.0开始支持，其中代理认证待后续再对生态开放支持。

伴随设备认证三要素：

1. 设备间建立信任关系：伴随设备被用户在主设备上添加为自己的身份认证凭据。

2. 伴随设备确认用户身份：伴随设备确认当前佩戴或操作者自己的用户是机主本人。

3. 主设备确认机主授权：主设备通过伴随设备确认机主在附近或机主手动确认了操作。

伴随设备无感认证，伴随设备需具有持续跟踪用户能力。

![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/d8/v3/jkErMbv9RTmYgMKGffdWbQ/zh-cn_image_0000002803264493.png?HW-CC-KV=V1&HW-CC-Date=20261026T101434Z&HW-CC-Expire=31536000000&HW-CC-Sign=2A7B0231A0A10ED5A665CCAF457EC2A7C1A8FD2142C494965BF790D3E443A5B3)

伴随设备代理认证，伴随设备需具备独立认证用户身份的能力。如在多屏协同场景中，PC/2in1设备作为伴随设备，用户可通过PC/2in1设备完成本地人脸或指纹认证，当前该能力仅开放给系统应用。

![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/f1/v3/CdXWmp6zT4-GP1Q05mL0MA/zh-cn_image_0000002803224403.png?HW-CC-KV=V1&HW-CC-Date=20261026T101434Z&HW-CC-Expire=31536000000&HW-CC-Sign=43AA11FD33C862BE077652856FA0D0493F9B57A068833A2AF36F3DD8C8792824)

## 约束与限制

### 系统身份认证约束与限制

* 三方应用调用系统本地身份认证能力，必须使用系统自带的身份认证控件。

* 不允许三方应用在后台发起身份认证请求。

* 由于设备硬件差异，系统存在不支持人脸、指纹等认证能力情形，该情形可以通过查询支持的认证能力加以判断，请参考对应的[userAuth.getAvailableStatus](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/js-apis-useriam-userauth#userauthgetavailablestatus9)。

### 模拟器支持情况

本Kit支持模拟器。

模拟器与真机存在通用差异，详情请参见[模拟器与真机的差异](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/ide-emulator-specification)。

## 能力介绍

* **归一化认证接口提供多种身份认证能力**

  提供系统级身份认证能力：锁屏口令认证、人脸认证、指纹认证、伴随设备认证，核心认证逻辑下沉TEE（Trust Execution Environment，可信执行环境）中。其中伴随设备认证的方式，从API版本26.0.0开始支持。

  屏蔽不同认证因子的差异，调用锁屏口令、人脸、指纹、伴随设备认证的接口归一。

  同一套接口提供人脸、指纹、锁屏口令等组合认证方式。

  同一套接口提供人脸认证、指纹认证、业务自定义认证等组合。
* **支持感知认证可信等级差异**

  支持调用者指定期望的认证可信等级，避免将低安全认证能力应用在高风险操作的用户鉴权场景。例如将防伪能力不够的2D人脸认证用于支付场景。
* **支持业务自定义认证方式**

  支持带导航键的认证界面，用户点击导航键可切换业务自定义认证界面。
* **支持短时间内复用任意应用的认证结果**

  支持选择复用锁屏认证结果或任意应用的身份认证结果，认证后调用者指定的时间范围内（最长5min），可直接返回认证通过结果，无需重复认证。

  支持认证方式无关的复用模式，采用此模式，无论上次认证使用何种方式，只要在认证后调用者指定的时间范围内（最长5min），可直接返回认证通过结果，无需重复认证。

  支持认证方式匹配的复用模式，采用此模式，不仅需要处于调用者指定的认证后时间范围内（最长5min），还需要认证使用的认证方式与调用者指定的一致，才能复用解锁认证结果并返回认证通过。
* **提供系统级用户身份认证界面**

  支持调用者自定义认证界面的标题和导航键文字。

  用户身份认证控件会根据设备屏幕状态自适应调整窗口显示模式。
* **支持感知注册凭据的变化**

  业务开通时，从认证成功结果中获取用户凭据的状态，或者直接查询用户凭据的状态，并存储注册的凭据状态。当调用者需要感知用户凭据变化时，需要从当前认证成功结果获取凭据的状态，或者查询当前凭据的状态，通过对比差异感知凭据状态的变化。

## 运作机制

统一用户认证框架架构如下图所示。

![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/8f/v3/GqRqm_-TRwOoPaDRTaPhMQ/zh-cn_image_0000002774064684.png?HW-CC-KV=V1&HW-CC-Date=20261026T101434Z&HW-CC-Expire=31536000000&HW-CC-Sign=EB6A94478BAE00C9F95EE82A7EE6E5ADA075DB34A6CF6927F0912135B64BC85D)

用户认证框架主要包括四个部分：

1. 统一用户认证API：提供归一化的系统用户身份认证能力调用接口。屏蔽认证差异，便于开发者调用系统能力认证用户身份。

2. 统一用户认证框架：包括框架层的SA和驱动，负责调度系统上的各种身份认证能力和用户认证控件，来完成业务通过统一用户认证API发起的用户认证请求。

3. 统一用户认证控件：实现了各种认证方式的用户身份认证交互界面，确保一致的用户身份认证体验，供统一用户认证框架调用。

4. 各种认证能力：包括口令认证、人脸认证、指纹认证和伴随设备认证，分别实现了基于锁屏口令、人脸、指纹和伴随设备认证用户身份的能力，供统一用户认证框架调度。

用户身份认证通过后，统一用户认证框架会在设备可信执行环境中签发用户身份认证通过证明，简称AuthToken。

从图的左侧，可以看到应用使用用户身份认证功能完成用户鉴权的过程：当应用需要调用通用密钥库服务中需用户授权才能访问的密钥时，应用可以将获取到的AuthToken随密钥调用请求一同提供给[通用密钥库服务](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/huks-overview)，作为密钥二次访问控制的用户鉴权证明。通用密钥库服务在可信执行环境中校验了AuthToken的合法性和有效性后，便会响应业务请求，执行对应的密钥操作。

### AuthToken数据结构

**明文段**

|名称|内容|类型|说明|
|:-------------|:------------|:----------|:-----------------------------------------------------------------------------------------------|
|version|token版本号|uint32_t|版本号，当前为2.0。|
|challenge|认证随机挑战|uint8_t[32]|需要校验认证结果的业务方生成的一次性随机挑战。|
|time|认证通过时间戳|uint64_t|认证通过时间戳。在复用场景中，该时间戳为用户认证通过的时间，而不是复用认证结果时AuthToken的签发时间。|
|authTrustLevel|认证可信等级|uint32_t|表示用户认证结果的可信等级，取决于设备上认证执行器本身的能力，正常情况下应该大于或者等于调用者传入的authTrustLevel。见[生物认证可信等级划分原则](#生物认证可信等级划分原则)。|
|authType|认证类型|uint32_t|认证通过采用的认证类型，包括人脸、指纹、口令（特指锁屏口令认证）、伴随设备。|
|authMode|操作类型|uint32_t|操作类型包括识别、认证。|
|securityLevel|token签发环境安全等级|uint32_t|token签发环境安全等级。|

**密文段**

|名称|内容|类型|说明|
|:-----------|:-------|:-------|:--------------------------------------------------|
|userId|用户ID|int32_t|系统在创建用户时给用户分配的ID。|
|secureUid|安全用户ID|uint64_t|用户注册系统口令时为用户随机分配的ID，在用户删除口令时删除，变更口令时该ID不变。|
|enrolledId|凭据注册ID|uint64_t|用户每录入一个凭据，该用户的该类型凭据的enrolledId便会更换一个随机值，删除凭据时该ID不变。|
|credentialId|匹配上的凭据ID|uint64_t|随机分配给用户注册的人脸、指纹等凭据的ID。|

**标签段**

|名称|内容|类型|说明|
|:---|:------------|:----------|:----------------------|
|tag|密文段的TAG|uint8_t[16]|密文字段采用AES-GCM加密生成的TAG。|
|iv|密文段加密使用的IV|uint8_t[12]|密文字段采用AES-GCM加密采用的随机IV。|
|sign|token的完整性保护签名|uint8_t[32]|保护AuthToken的完整性。|

### 生物认证可信等级划分原则

认证可信等级评估的是系统用户身份认证能力的安全性，取决于认证方案能力等级（Authentication Capability Level，ACL）和该认证系统的实现安全等级（Authentication Security Level，ASL）。

系统采用三种指标来衡量生物认证方案能力等级，具体定义如下表所示：

* FRR（False Rejection Rate）：将合法用户当做非法用户拒绝的概率。

* FAR（False Acceptance Rate）：将非法用户当做合法用户接受的概率，又称为误闯率。

* SAR（Spoof Acceptance Rate）：接受一个基于合法生物特征复制的、非活体的样本概率。

FAR越低，FRR越高，认证的安全性越高，但合法用户被错误拒绝的概率越高，导致使用便捷性越差；反之FAR越高，FRR越低，则认证安全性越差，使用便捷性越好。

|认证方案能力等级|认证能力指标|
|:-------|:-----------------------------|
|ACL4|FRR=10%时，FAR≤0.0001%，SAR≤3%|
|ACL3|FRR=10%时，FAR≤0.002%，SAR≤7%|
|ACL2|FRR=10%时，FAR≤0.002%，7%<SAR≤20%|
|ACL1|FRR=10%时，FAR≤1%，7%<SAR≤20%|

生物认证系统一般分为以下5个执行单元：生物特征源数据的采集、生物特征的提取、生物特征的存储、生物特征的比对和认证结果的签发。系统将认证过程中的各个执行单元的运行环境安全ESL（Executor Security Level）分为以下4个等级：

|执行单元安全等级|定义|
|:-------|:-------------------------------|
|ESL3|操作在高安全硬件可信环境中完成，如安全协处理器、安全芯片等。|
|ESL2|操作在基于硬件可信根隔离的可信执行环境中完成，如TEE、SGX。|
|ESL1|操作在有访问控制的执行环境中完成，如Linux。|
|ESL0|操作在无访问控制的运行环境中完成，如单进程的轻量级系统。|

整个认证系统的实现安全等级ASL等于生物认证5个执行单元中最低的ESL级别。例如，有一个人脸认证系统，其特征存储和比对都在安全隔离环境TEE中执行（即ESL=2），但特征提取算法运行在普通系统环境中（即ESL=1），则该人脸认证系统的ASL=1。

由认证方案能力等级和认证方案安全等级映射得到认证结果可信等级的具体规则如下表：

|认证可信等级|映射规则|说明&举例|典型应用场景|
|:-----|:----------------------|:---------------------------------------------------------------|:---------------|
|ATL4|ACL≥3，ASL≥2|能高精度地识别用户个体，有很强的活体检测能力，如：有特殊安全增强的指纹与3D人脸认证。|小额支付。|
|ATL3|ACL≥3，ASL≥1 ACL≥2，ASL≥2|能精确识别用户个体，有较强的活体检测能力，如：有特殊安全增强的2D人脸认证，有TEE环境的伴随设备如智能眼镜。|设备解锁、应用登录、账号登录。|
|ATL2|ACL≥2，ASL≥1 ACL≥1，ASL≥2|能精确识别用户个体，有一定的活体检测能力，如：使用普通相机采集图像的2D人脸认证，无TEE环境业务特殊安全增强的伴随设备如耳机。|维持设备解锁状态。|
|ATL1|ACL=1，ASL=1|能识别用户个体，有一定的活体检测能力，如声纹认证。|业务风控、精准推荐、个性化服务。|

### 支持的认证能力

提供系统级身份认证能力：锁屏口令认证、人脸认证、指纹认证、伴随设备认证，核心认证逻辑下沉TEE中。其中伴随设备认证的方式，从API版本26.0.0开始支持。

**锁屏口令认证**

锁屏口令输入界面由系统级应用提供，锁屏口令信息在完成数据采集和脱敏处理后，传递给密码认证框架，在TEE中完成密码数据的比对，认证过程密码原文及中间计算结果不外传，也不会被穷举逆推出用户的锁屏口令。密码认证有防暴力破解机制，锁屏口令比对失败，会导致用户的锁屏口令防暴计数增加，并触发防暴惩罚。

**人脸认证**

提供2D和3D两种人脸认证方案的支持。3D人脸认证方案依赖特殊的深度摄像头实现，2D人脸认证技术则基于普通的前置摄像头实现。3D人脸认证的准确率和防伪能力均显著优于2D人脸认证。3D人脸认证技术可支持支付应用，2D人脸认证技术不能支持支付应用。不同的终端设备型号根据其产品定位选择其搭载的人脸认证类型。

在摄像头和TEE之间建立安全通道，人脸图像信息通过安全通道传递到TEE中，特征提取、活体检测、特征比对等处理也完全在TEE中，基于TrustZone进行安全隔离，外部的人脸框架只负责人脸认证相关任务的调度和人脸认证结果等数据的传递，不接触人脸原始数据。

**指纹认证**

目前可提供电容指纹和光学指纹的支持。两种技术方案的体验及安全能力基本一致。不同的终端设备根据其产品定位选择其搭载的指纹认证技术类型。

在指纹传感器和TEE之间建立安全通道，指纹图像通过安全通道传递到TEE中，特征提取、活体检测、特征比对等处理也完全在TEE中进行，基于TrustZone进行安全隔离。REE（Rich Execution Environment，普通执行环境）的指纹认证框架只负责指纹认证相关任务的调度和指纹认证结果等数据的传递，不接触指纹原始数据。

**伴随设备认证**

伴随设备是一种协同认证能力，提供基于用户所持有的伴随设备对用户进行身份认证的功能。

伴随设备认证是系统支持的一种用户认证执行器，按照统一用户认证定义的资源注册接口，将伴随设备认证相关资源信息注册到统一用户认证框架，并根据框架调完成可信设备的注册、删除和认证。

主设备添加伴随设备过程中，主设备和伴随设备会交换各自的认证相关信息，该凭据主要用于保护认证阶段主设备与伴随设备之间交互信息的安全性。因此，主设备侧和伴随设备侧都需要在可信执行环境内保存和使用该凭据信息。

**伴随设备认证可信等级划分原则**

|认证方案能力等级|伴随设备认证关系证明|伴随设备确认用户身份|确认用户意图|举例|
|:-------|:--------------------------------------------------------------------------------------|:-------------------------------------------------------|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:-----------------------------------------------------------|
|ACL4|采用等价于AES 256bit密钥安全性的随机密钥作为认证凭据；认证设备和伴随设备的双向认证协议，抗重放攻击和中间人攻击，协议报文传输不依赖通道安全性。|采用本地多因子强密码（生物认证+密码/密码+OTP）；从佩戴在同一用户身体上的设备或0.5m范围内的主设备获取。|1. 主设备确认用户在场。用户在场检测灵敏度：用户在场与否的检测精度≥99%且用户离场/返场变化检测时延<1s；用户所处空间范围探测精度：能够确定认证时用户与认证设备间的距离≤1m，实际距离大于阈值但误报成低于阈值的概率≤1%，测距能力需防中继攻击。 2. 伴随设备确认用户意图。用户在已经确认机主身份的伴随设备侧进行了确认意图的操作；操作指令来自已经确认用户身份的伴随设备；用户在伴随设备认证过程中在伴随设备侧进行了一次实时身份认证；100%可靠，适用于所有等级。|基于锁屏口令，基于OTP（one-time passwords）确认验证码的U盾/电子口令卡识别用户的伴随设备认证方案。|
|ACL3|采用等价于AES 256bit密钥安全性的随机密钥作为认证凭据；认证设备和伴随设备的双向认证协议，抗重放攻击和中间人攻击，协议报文传输不依赖通道安全性。|采用本地单因子强身份认证方式（密码/高安全人脸/指纹）；从2m范围内的主设备获取。|1. 主设备确认用户在场。用户在场检测灵敏度：用户在场与否的检测精度≥95%且用户离场/返场变化检测时延<3s；用户所处空间范围探测精度：能够确定认证时用户与认证设备间的距离≤5m，实际距离大于阈值但误报成低于阈值的概率≤5%，测距能力需防中继攻击。 2. 伴随设备确认用户意图。用户在已经确认机主身份的伴随设备侧进行了确认意图的操作；操作指令来自已经确认用户身份的伴随设备；用户在伴随设备认证过程中在伴随设备侧进行了一次实时身份认证；100%可靠，适用于所有等级。|基于有锁屏口令认证能力且支持高精度、抗干扰测距的智能手表识别用户的伴随设备认证方案。|
|ACL2|采用等价于AES 128bit密钥安全性的随机密钥作为认证凭据；认证设备对伴随设备的单向认证协议（主设备认证伴随设备），抗重放攻击和中间人攻击，协议报文传输不依赖通道安全性。|采用本地中等安全强度的身份认证方式；从5m范围内的主设备获取。|1. 主设备确认用户在场。用户在场检测灵敏度：用户在场与否的检测精度≥90%且用户离场/返场变化检测时延<3s；用户所处空间范围探测精度：能够确定认证时用户与认证设备间的距离≤10m，实际距离大于阈值但误报成低于阈值的概率≤20%。 2. 伴随设备确认用户意图。用户在已经确认机主身份的伴随设备侧进行了确认意图的操作；操作指令来自已经确认用户身份的伴随设备；用户在伴随设备认证过程中在伴随设备侧进行了一次实时身份认证；100%可靠，适用于所有等级。|基于无用户认证能力，支持普通蓝牙测距的手环、耳机等识别用户的伴随设备认证方案。|
|ACL1|基于通用连接协议的认证（如蓝牙绑定）。|采用本地弱认证方式；从连接的主设备获取。|1. 主设备确认用户在场。用户在场检测灵敏度：不做要求；用户所处空间范围探测精度：不做要求，但要能够判断设备连接状态。 2. 伴随设备确认用户意图。用户在已经确认机主身份的伴随设备侧进行了确认意图的操作；操作指令来自已经确认用户身份的伴随设备；用户在伴随设备认证过程中在伴随设备侧进行了一次实时身份认证；100%可靠，适用于所有等级。|基于不支持测距的普通蓝牙连接设备识别用户身份的可选伴随设备认证方案。|
|ACL0|无认证交互协议，基于设备通用标识的识别伴随设备（如MAC地址、SN号等）。|采用本地弱认证方式；从连接的主设备获取。|1. 主设备确认用户在场。用户在场检测灵敏度：不做要求；用户所处空间范围探测精度：不做要求，但要能够判断设备连接状态。 2. 伴随设备确认用户意图。用户在已经确认机主身份的伴随设备侧进行了确认意图的操作；操作指令来自已经确认用户身份的伴随设备；用户在伴随设备认证过程中在伴随设备侧进行了一次实时身份认证；100%可靠，适用于所有等级。|通过设备连接状态识别用户身份的伴随设备认证方案。|

**应用场景**

应用场景1：眼镜/耳机作为伴随设备支持语音助手免解锁执行语音指令。

应用场景2：平板、PC作为手机的伴随设备，通过伴随设备认证用户身份后支持投屏手机解锁，避免了分布式场景下用户在设备间的来回切换。