目录

SOTER免密认证

SOTER旨在提供一套生物认证平台和标准,使得业务可以采用设备上的传感器(如人脸传感器/指纹传感器)进行安全、高效的免密登录、免密支付等操作,当前已广泛应用于微信小程序/公众号、指纹支付等业务场景。

场景介绍

用户可以利用生物特征来代替传统的密码验证,实现免密认证。

约束与限制

业务流程

生成应用密钥流程说明:

  1. 应用客户端调用generateAppSecureKey接口生成应用密钥。
  2. 应用客户端将应用密钥上传至应用服务端,应用服务端校验后返回校验结果。

生成认证密钥流程说明:

  1. 应用客户端调用generateAuthKey接口生成认证密钥。
  2. 应用客户端将认证密钥上传至应用服务端,应用服务端校验后返回校验结果。

认证流程说明:

  1. 应用客户端向应用服务端请求数据。
  2. 应用客户端调用generateChallengeSync接口生成challenge。
  3. 应用客户端请求身份认证,完成生物特征认证。
  4. 应用客户端调用signWithAuthKeySync接口进行SOTER认证,获取签名结果。
  5. 应用客户端将签名结果上传至应用服务端,应用服务端校验后返回校验结果。

关闭免密支付流程说明:

应用客户端调用deleteAuthKey接口删除认证密钥。

接口说明

以下是开通、认证、注销的所需要的接口,具体API说明详见接口文档。

接口名 描述
generateAppSecureKey(keyType: KeyType): Promise<Uint8Array> 生成App应用密钥,使用Promise异步回调。
generateAuthKey(keyAlias: string, keyType: KeyType): Promise<SignedResult> 生成authKey,使用Promise异步回调。
generateChallengeSync(keyAlias: string): Uint8Array 生成Challenge,同步返回结果。
signWithAuthKeySync(keyAlias: string, authToken: Uint8Array, info: string): SignedResult SOTER免密认证,同步返回签名的报文。
deleteAuthKey(keyAlias: string): Promise<void> 删除AuthKey,使用Promise异步回调

开发步骤

  1. 导入SOTER模块。

    import { soter } from '@kit.OnlineAuthenticationKit';
    import { userAuth } from '@kit.UserAuthenticationKit';
    import { BusinessError } from '@kit.BasicServicesKit';
  2. 生成应用密钥和认证密钥用于后续的开通、认证流程。

    let keyType: soter.KeyType = soter.KeyType.ECC_P256; // 加密类型,只支持ECC_P256
    let keyAlias: string = 'keyAlias'; // 开发者自定义密钥别名
    
    // 生成应用密钥
    try {
      let appSecureKey: Promise<Uint8Array> = soter.generateAppSecureKey(keyType);
      // ...
    } catch (error) {
      const err = error as BusinessError;
      console.error(`Failed to generate app secure key. Code is ${err.code}, message is ${err.message}`);
      // ...
    }
    // 生成authKey
    try {
      let authKey: Promise<soter.SignedResult> = soter.generateAuthKey(keyAlias, keyType);
    } catch (error) {
      const err = error as BusinessError;
      console.error(`Failed to generate auth key. Code is ${err.code}, message is ${err.message}`);
    }
  3. 使用认证密钥签名,实现SOTER免密认证。

    let keyType: soter.KeyType = soter.KeyType.ECC_P256; // 加密类型,只支持ECC_P256
    let keyAlias: string = 'keyAlias'; // 开发者自定义密钥别名
    let info: string = 'Message to be signed.'; // info需要开发者的三方应用服务器下发,SOTER服务完成签名后需要重新上传给三方应用服务器
    
    // 获取此次免密支付的challenge
    let soterChallenge: Uint8Array = new Uint8Array([0]);
    try {
      soterChallenge = soter.generateChallengeSync(keyAlias);
    } catch (error) {
      const err = error as BusinessError;
      console.error(`Failed to generate challenge. Code is ${err.code}, message is ${err.message}`);
    }
    let authParam: userAuth.AuthParam = {
      challenge: soterChallenge,
      authType: [userAuth.UserAuthType.FINGERPRINT],
      authTrustLevel: userAuth.AuthTrustLevel.ATL4
    };
    // 使用authParam请求身份认证
    try {
      let userAuthInstance = userAuth.getUserAuthInstance(authParam, {title: ' '});
      // 未获取到authToken则会返回错误码1。
      userAuthInstance.on('result', {
        onResult(result) {
          let authToken = result.token;
          try {
            // 生物特征认证成功后,调用soter认证
            console.info('soter auth start');
            // 使用soter.signWithAuthKeySync接口为待认证数据签名。开发者根据业务需求选择同步/异步接口。
            let authResult: soter.SignedResult = soter.signWithAuthKeySync(keyAlias, authToken, info);
            console.info('Succeeded in doing authSyn authResult');
            // 开发者处理authResult
            // ...
          } catch (err) {
            console.error(`Failed to signWithAuthKeySync. Code: ${err.code}, message: ${err.message}`);
            // ...
          }
        }
      });
      userAuthInstance.start();
    } catch (error) {
      const err = error as BusinessError;
      console.error(`Failed to user auth. Code is ${err.code}, message is ${err.message}`);
    }
  4. 关闭免密认证时,删除认证密钥。

    let keyAlias: string = 'keyAlias'; // 开发者自定义密钥别名
    try {
      soter.deleteAuthKey(keyAlias);
      // ...
    } catch (error) {
      const err = error as BusinessError;
      console.error(`Failed to delete auth key. Code is ${err.code}, message is ${err.message}`);
      // ...
    }