HarmonyOS开发设备认证：信任链与安全认证

在分布式场景下，设备之间的信任关系是安全通信的前提。你肯定不希望陌生人随意访问你的手机数据，或者控制你的智能家居设备。HarmonyOS的设备认证机制，就像一个严谨的"门禁系统"，确保只有可信设备才能接入分布式网络。这篇文章带你深入理解设备认证的核心原理。

一、背景与动机：为什么需要设备认证？

1.1 分布式场景的安全挑战

在传统单设备场景下，安全边界很清晰——设备属于你，应用运行在你的设备上，数据存储在你的设备里。但在分布式场景下，这个边界被打破了：

设备身份不可信：当你的手机收到一个"智能门锁"的控制请求时，如何确认这个请求真的来自你的门锁，而不是黑客伪造的？

数据传输不安全：跨设备传输的数据可能被中间人截获、篡改、重放。如何保证数据的机密性、完整性、真实性？

权限控制不精细：不同设备应该有不同的访问权限。手表可能只需要读取通知权限，而平板可能需要完整的文件访问权限。如何实现细粒度的权限控制？

信任链不完整：设备A信任设备B，设备B信任设备C，但设备A和设备C之间没有直接信任关系。如何建立完整的信任链？

1.2 HarmonyOS的解法：多层认证体系

HarmonyOS构建了完整的设备认证体系，包括账号认证、设备认证、会话认证三个层次：

认证层次说明：

二、核心原理：设备认证如何工作？

2.1 信任模型

HarmonyOS采用基于账号的信任模型，结合点对点认证机制。

2.1.1 信任关系定义

// 信任关系结构
interface TrustRelation {
  sourceDevice: string;      // 源设备ID
  targetDevice: string;      // 目标设备ID
  trustLevel: TrustLevel;    // 信任等级
  authType: AuthType;        // 认证类型
  authTime: number;          // 认证时间
  expireTime: number;        // 过期时间
  trustProof: TrustProof;    // 信任凭证
}

// 信任等级枚举
enum TrustLevel {
  TRUST_INVALID = 0,    // 无效信任
  TRUST_LOW = 1,        // 低信任（仅基础通信）
  TRUST_MEDIUM = 2,     // 中信任（可访问部分数据）
  TRUST_HIGH = 3        // 高信任（完全信任）
}

// 认证类型枚举
enum AuthType {
  AUTH_INVALID = 0,           // 无效
  AUTH_SAME_ACCOUNT = 1,      // 同账号认证
  AUTH_PIN_CODE = 2,          // PIN码认证
  AUTH_QR_CODE = 3,           // 二维码认证
  AUTH_BIOMETRIC = 4,         // 生物识别认证
  AUTH_NFC_TOUCH = 5          // NFC碰一碰认证
}

// 信任凭证结构
interface TrustProof {
  proofType: string;          // 凭证类型
  proofData: string;          // 凭证数据（加密）
  signature: string;          // 数字签名
  certChain: string[];        // 证书链
}

2.1.2 信任链建立流程

sequenceDiagram
    participant DeviceA as 设备A（发起方）
    participant AuthCenter as 认证中心
    participant DeviceB as 设备B（被认证方）
    
    Note over DeviceA: 1. 发起认证请求
    DeviceA->>AuthCenter: 请求认证设备B
    AuthCenter-->>DeviceA: 返回认证参数
    
    Note over DeviceA,DeviceB: 2. 协商认证方式
    DeviceA->>DeviceB: 发送认证请求
    DeviceB-->>DeviceA: 返回支持的认证方式
    
    alt 同账号设备
        Note over DeviceA,DeviceB: 3a. 同账号自动认证
        DeviceA->>AuthCenter: 验证账号一致性
        AuthCenter-->>DeviceA: 返回账号凭证
        DeviceA->>DeviceB: 发送账号凭证
        DeviceB->>AuthCenter: 验证凭证有效性
        AuthCenter-->>DeviceB: 凭证有效
        DeviceB-->>DeviceA: 认证成功
    else 跨账号设备
        Note over DeviceA,DeviceB: 3b. 用户交互认证
        DeviceB->>DeviceB: 生成PIN码
        DeviceB->>DeviceB: 显示PIN码给用户
        DeviceA->>DeviceA: 用户输入PIN码
        DeviceA->>DeviceB: 发送PIN码
        DeviceB->>DeviceB: 验证PIN码
        DeviceB-->>DeviceA: 认证成功
    end
    
    Note over DeviceA,DeviceB: 4. 建立信任关系
    DeviceA->>DeviceA: 保存信任关系
    DeviceB->>DeviceB: 保存信任关系
    
    Note over DeviceA,DeviceB: 5. 生成会话密钥
    DeviceA->>DeviceB: 密钥交换请求
    DeviceB-->>DeviceA: 密钥交换响应
    DeviceA->>DeviceA: 计算会话密钥
    DeviceB->>DeviceB: 计算会话密钥
    
    classDef primary fill:#4A90E2,stroke:#2E5C8A,stroke-width:2px,color:#fff
    classDef warning fill:#F5A623,stroke:#C17A00,stroke-width:2px,color:#fff
    classDef info fill:#7ED321,stroke:#5BA315,stroke-width:2px,color:#fff
    
    class DeviceA,DeviceB primary
    class AuthCenter warning

2.2 认证方式详解

2.2.1 同账号认证

同账号认证是最便捷的认证方式。当两个设备登录了相同的华为账号时，系统自动建立信任关系。

graph LR
    A[设备A登录账号] --> B[账号中心验证]
    B --> C[生成设备凭证]
    C --> D[设备B登录同一账号]
    D --> E[账号中心验证]
    E --> F[交换设备凭证]
    F --> G[建立信任关系]
    
    classDef primary fill:#4A90E2,stroke:#2E5C8A,stroke-width:2px,color:#fff
    classDef success fill:#7ED321,stroke:#5BA315,stroke-width:2px,color:#fff
    
    class A,B,C,D,E primary
    class F,G success

同账号认证特点：

• 无需用户交互，自动完成认证
• 信任等级最高（TRUST_HIGH）
• 支持跨设备数据同步
• 凭证由账号中心统一管理

2.2.2 PIN码认证

PIN码认证适用于跨账号设备认证，需要用户交互。

// PIN码认证流程
interface PinCodeAuthFlow {
  // 1. 被认证设备生成PIN码
  generatePinCode(): string;
  
  // 2. 显示PIN码给用户
  displayPinCode(pinCode: string): void;
  
  // 3. 发起方用户输入PIN码
  inputPinCode(): Promise<string>;
  
  // 4. 验证PIN码
  verifyPinCode(inputPin: string, actualPin: string): boolean;
}

PIN码认证特点：

• 需要用户交互，安全性较高
• 信任等级中等（TRUST_MEDIUM）
• 适用于临时设备接入
• PIN码有效期短（通常60秒）

2.2.3 二维码认证

二维码认证适用于手机扫描其他设备（如电视、音箱）的场景。

graph TD
    A[被认证设备生成二维码] --> B[二维码包含设备信息+认证参数]
    B --> C[手机扫描二维码]
    C --> D[解析二维码内容]
    D --> E[向被认证设备发送认证请求]
    E --> F[被认证设备验证请求]
    F --> G{验证通过?}
    G -->|是| H[建立信任关系]
    G -->|否| I[认证失败]
    
    classDef primary fill:#4A90E2,stroke:#2E5C8A,stroke-width:2px,color:#fff
    classDef warning fill:#F5A623,stroke:#C17A00,stroke-width:2px,color:#fff
    classDef success fill:#7ED321,stroke:#5BA315,stroke-width:2px,color:#fff
    classDef error fill:#D0021B,stroke:#9C0215,stroke-width:2px,color:#fff
    
    class A,B,C,D,E,F primary
    class G warning
    class H success
    class I error

2.2.4 生物识别认证

生物识别认证利用指纹、人脸等生物特征进行认证，安全性最高。

// 生物识别认证参数
interface BiometricAuthParam {
  deviceId: string;              // 目标设备ID
  biometricType: BiometricType;  // 生物识别类型
  challenge: string;             // 挑战码（防重放）
  timeout: number;               // 超时时间
}

// 生物识别类型
enum BiometricType {
  FINGERPRINT = 1,   // 指纹
  FACE = 2,          // 人脸
  IRIS = 3           // 虹膜
}

2.3 密钥交换与数据加密

认证完成后，需要进行密钥交换，建立安全通信通道。

2.3.1 密钥交换流程

HarmonyOS采用**ECDH（椭圆曲线Diffie-Hellman）**密钥交换算法：

sequenceDiagram
    participant DeviceA as 设备A
    participant DeviceB as 设备B
    
    Note over DeviceA: 1. 生成临时密钥对
    DeviceA->>DeviceA: 生成ECDH密钥对<br/>(privateKeyA, publicKeyA)
    
    Note over DeviceB: 2. 生成临时密钥对
    DeviceB->>DeviceB: 生成ECDH密钥对<br/>(privateKeyB, publicKeyB)
    
    Note over DeviceA,DeviceB: 3. 交换公钥
    DeviceA->>DeviceB: 发送publicKeyA
    DeviceB->>DeviceA: 发送publicKeyB
    
    Note over DeviceA: 4. 计算共享密钥
    DeviceA->>DeviceA: sharedKey = ECDH<br/>(privateKeyA, publicKeyB)
    
    Note over DeviceB: 5. 计算共享密钥
    DeviceB->>DeviceB: sharedKey = ECDH<br/>(privateKeyB, publicKeyA)
    
    Note over DeviceA,DeviceB: 6. 派生会话密钥
    DeviceA->>DeviceA: sessionKey = KDF<br/>(sharedKey)
    DeviceB->>DeviceB: sessionKey = KDF<br/>(sharedKey)
    
    classDef primary fill:#4A90E2,stroke:#2E5C8A,stroke-width:2px,color:#fff
    classDef success fill:#7ED321,stroke:#5BA315,stroke-width:2px,color:#fff
    
    class DeviceA,DeviceB primary

2.3.2 数据加密方案

// 加密方案配置
interface EncryptionScheme {
  algorithm: string;        // 加密算法（AES-256-GCM）
  keyDerivation: string;    // 密钥派生函数（HKDF）
  ivLength: number;         // 初始化向量长度（12字节）
  tagLength: number;        // 认证标签长度（16字节）
}

// 加密数据结构
interface EncryptedData {
  iv: Uint8Array;           // 初始化向量
  ciphertext: Uint8Array;   // 密文
  tag: Uint8Array;          // 认证标签
  timestamp: number;        // 时间戳（防重放）
}

三、代码实战：设备认证使用

3.1 设备认证管理器

import deviceAuthentication from '@ohos.distributedHardware.deviceAuthentication';
import { BusinessError } from '@ohos.base';

/**
 * 设备认证管理器
 * 封装设备认证相关能力
 */
export class DeviceAuthManager {
  private authInstance: deviceAuthentication.DeviceAuthentication | null = null;
  private trustRelations: Map<string, TrustRelation> = new Map();
  
  /**
   * 初始化认证管理器
   */
  async initialize(): Promise<void> {
    try {
      // 创建认证实例
      this.authInstance = deviceAuthentication.createDeviceAuthentication();
      
      // 注册认证状态监听
      this.authInstance.on('authStatusChange', (data) => {
        this.handleAuthStatusChange(data);
      });
      
      // 加载已有信任关系
      await this.loadTrustRelations();
      
      console.info('[DeviceAuth] 初始化成功');
    } catch (error) {
      console.error(`[DeviceAuth] 初始化失败: ${JSON.stringify(error)}`);
      throw error;
    }
  }
  
  /**
   * 检查设备是否已认证
   */
  async isDeviceTrusted(deviceId: string): Promise<boolean> {
    const relation = this.trustRelations.get(deviceId);
    
    if (!relation) {
      return false;
    }
    
    // 检查是否过期
    if (relation.expireTime < Date.now()) {
      // 移除过期的信任关系
      this.trustRelations.delete(deviceId);
      return false;
    }
    
    return true;
  }
  
  /**
   * 获取设备信任等级
   */
  getTrustLevel(deviceId: string): TrustLevel {
    const relation = this.trustRelations.get(deviceId);
    return relation?.trustLevel || TrustLevel.TRUST_INVALID;
  }
  
  /**
   * 发起设备认证
   * @param deviceId 目标设备ID
   * @param authType 认证类型
   */
  async authenticateDevice(
    deviceId: string,
    authType: AuthType
  ): Promise<AuthResult> {
    if (!this.authInstance) {
      throw new Error('认证管理器未初始化');
    }
    
    // 检查是否已信任
    if (await this.isDeviceTrusted(deviceId)) {
      return {
        success: true,
        trustLevel: this.getTrustLevel(deviceId),
        message: '设备已信任'
      };
    }
    
    try {
      // 构建认证参数
      const authParam: deviceAuthentication.AuthParam = {
        deviceId: deviceId,
        authType: this.convertAuthType(authType),
        extraInfo: {}
      };
      
      // 发起认证
      const result = await this.authInstance.authenticateDevice(authParam);
      
      if (result.authResult === 0) {
        // 认证成功，保存信任关系
        const relation: TrustRelation = {
          sourceDevice: this.getLocalDeviceId(),
          targetDevice: deviceId,
          trustLevel: result.trustLevel,
          authType: authType,
          authTime: Date.now(),
          expireTime: Date.now() + 30 * 24 * 60 * 60 * 1000, // 30天有效期
          trustProof: result.trustProof
        };
        
        this.trustRelations.set(deviceId, relation);
        await this.saveTrustRelation(relation);
        
        console.info(`[DeviceAuth] 设备认证成功: ${deviceId}`);
        
        return {
          success: true,
          trustLevel: result.trustLevel,
          message: '认证成功'
        };
      } else {
        console.error(`[DeviceAuth] 设备认证失败: ${result.authResult}`);
        
        return {
          success: false,
          trustLevel: TrustLevel.TRUST_INVALID,
          message: `认证失败: ${result.authResult}`
        };
      }
    } catch (error) {
      const err = error as BusinessError;
      console.error(`[DeviceAuth] 认证异常: ${err.message}`);
      
      return {
        success: false,
        trustLevel: TrustLevel.TRUST_INVALID,
        message: err.message
      };
    }
  }
  
  /**
   * 取消设备认证
   */
  async cancelAuthentication(deviceId: string): Promise<void> {
    if (!this.authInstance) {
      return;
    }
    
    try {
      await this.authInstance.cancelAuthentication(deviceId);
      console.info(`[DeviceAuth] 取消认证: ${deviceId}`);
    } catch (error) {
      console.error(`[DeviceAuth] 取消认证失败: ${JSON.stringify(error)}`);
    }
  }
  
  /**
   * 移除设备信任关系
   */
  async removeTrustRelation(deviceId: string): Promise<void> {
    if (!this.authInstance) {
      return;
    }
    
    try {
      // 从系统移除信任关系
      await this.authInstance.removeTrustRelation(deviceId);
      
      // 从本地缓存移除
      this.trustRelations.delete(deviceId);
      
      console.info(`[DeviceAuth] 移除信任关系: ${deviceId}`);
    } catch (error) {
      console.error(`[DeviceAuth] 移除信任关系失败: ${JSON.stringify(error)}`);
    }
  }
  
  /**
   * 获取所有已信任设备
   */
  getTrustedDevices(): string[] {
    return Array.from(this.trustRelations.keys());
  }
  
  /**
   * 处理认证状态变化
   */
  private handleAuthStatusChange(data: deviceAuthentication.AuthStatusInfo): void {
    console.info(`[DeviceAuth] 认证状态变化: ${data.deviceId} -> ${data.status}`);
    
    // 通知上层应用
    // 可以通过事件总线或回调通知
  }
  
  /**
   * 转换认证类型
   */
  private convertAuthType(authType: AuthType): number {
    const typeMap = {
      [AuthType.AUTH_SAME_ACCOUNT]: deviceAuthentication.AuthType.SAME_ACCOUNT,
      [AuthType.AUTH_PIN_CODE]: deviceAuthentication.AuthType.PIN_CODE,
      [AuthType.AUTH_QR_CODE]: deviceAuthentication.AuthType.QR_CODE,
      [AuthType.AUTH_BIOMETRIC]: deviceAuthentication.AuthType.BIOMETRIC
    };
    
    return typeMap[authType] || deviceAuthentication.AuthType.PIN_CODE;
  }
  
  /**
   * 获取本地设备ID
   */
  private getLocalDeviceId(): string {
    // 从设备管理器获取本地设备ID
    return 'local-device-id';
  }
  
  /**
   * 加载信任关系
   */
  private async loadTrustRelations(): Promise<void> {
    if (!this.authInstance) {
      return;
    }
    
    try {
      const relations = await this.authInstance.getTrustRelations();
      relations.forEach(relation => {
        this.trustRelations.set(relation.targetDevice, relation);
      });
      
      console.info(`[DeviceAuth] 加载信任关系: ${relations.length}条`);
    } catch (error) {
      console.error(`[DeviceAuth] 加载信任关系失败: ${JSON.stringify(error)}`);
    }
  }
  
  /**
   * 保存信任关系
   */
  private async saveTrustRelation(relation: TrustRelation): Promise<void> {
    // 保存到持久化存储
    // 实际实现中可以使用Preferences或数据库
  }
  
  /**
   * 释放资源
   */
  release(): void {
    if (this.authInstance) {
      this.authInstance.off('authStatusChange');
      this.authInstance = null;
    }
    this.trustRelations.clear();
  }
}

// 认证结果结构
interface AuthResult {
  success: boolean;
  trustLevel: TrustLevel;
  message: string;
}

3.2 PIN码认证实战

import deviceAuthentication from '@ohos.distributedHardware.deviceAuthentication';

/**
 * PIN码认证处理器
 * 处理PIN码生成、显示、验证流程
 */
export class PinCodeAuthHandler {
  private authInstance: deviceAuthentication.DeviceAuthentication | null = null;
  private currentPinCode: string = '';
  private pinCodeExpireTime: number = 0;
  private onPinCodeGenerated: ((pinCode: string) => void) | null = null;
  
  /**
   * 初始化
   */
  async initialize(): Promise<void> {
    this.authInstance = deviceAuthentication.createDeviceAuthentication();
    
    // 注册PIN码生成回调
    this.authInstance.on('pinCodeGenerated', (data) => {
      this.handlePinCodeGenerated(data);
    });
  }
  
  /**
   * 作为被认证方：生成并显示PIN码
   */
  async generateAndShowPinCode(): Promise<string> {
    if (!this.authInstance) {
      throw new Error('认证实例未初始化');
    }
    
    try {
      // 请求生成PIN码
      const pinCode = await this.authInstance.generatePinCode({
        length: 6,              // 6位PIN码
        expireTime: 60000,      // 60秒有效期
        allowRetry: true        // 允许重试
      });
      
      // 保存PIN码信息
      this.currentPinCode = pinCode.code;
      this.pinCodeExpireTime = Date.now() + pinCode.expireTime;
      
      // 通知上层显示PIN码
      if (this.onPinCodeGenerated) {
        this.onPinCodeGenerated(pinCode.code);
      }
      
      console.info(`[PinCode] 生成PIN码: ${pinCode.code}`);
      
      return pinCode.code;
    } catch (error) {
      console.error(`[PinCode] 生成PIN码失败: ${JSON.stringify(error)}`);
      throw error;
    }
  }
  
  /**
   * 作为发起方：输入PIN码进行认证
   */
  async authenticateWithPinCode(
    deviceId: string,
    pinCode: string
  ): Promise<boolean> {
    if (!this.authInstance) {
      throw new Error('认证实例未初始化');
    }
    
    try {
      // 发送PIN码进行认证
      const result = await this.authInstance.authenticateWithPinCode({
        deviceId: deviceId,
        pinCode: pinCode
      });
      
      console.info(`[PinCode] 认证结果: ${result.success}`);
      
      return result.success;
    } catch (error) {
      console.error(`[PinCode] 认证失败: ${JSON.stringify(error)}`);
      return false;
    }
  }
  
  /**
   * 验证PIN码是否有效
   */
  validatePinCode(pinCode: string): boolean {
    // 检查格式
    if (!/^\d{6}$/.test(pinCode)) {
      return false;
    }
    
    // 检查是否过期
    if (Date.now() > this.pinCodeExpireTime) {
      return false;
    }
    
    // 检查是否匹配
    return pinCode === this.currentPinCode;
  }
  
  /**
   * 设置PIN码生成回调
   */
  setOnPinCodeGenerated(callback: (pinCode: string) => void): void {
    this.onPinCodeGenerated = callback;
  }
  
  /**
   * 处理PIN码生成事件
   */
  private handlePinCodeGenerated(data: deviceAuthentication.PinCodeInfo): void {
    this.currentPinCode = data.pinCode;
    this.pinCodeExpireTime = Date.now() + data.expireTime;
    
    if (this.onPinCodeGenerated) {
      this.onPinCodeGenerated(data.pinCode);
    }
  }
  
  /**
   * 释放资源
   */
  release(): void {
    if (this.authInstance) {
      this.authInstance.off('pinCodeGenerated');
      this.authInstance = null;
    }
    this.currentPinCode = '';
  }
}

3.3 二维码认证实战

import deviceAuthentication from '@ohos.distributedHardware.deviceAuthentication';
import { scanBarcode } from '@ohos.scanBarcode';

/**
 * 二维码认证处理器
 * 处理二维码生成、扫描、认证流程
 */
export class QrCodeAuthHandler {
  private authInstance: deviceAuthentication.DeviceAuthentication | null = null;
  
  /**
   * 初始化
   */
  async initialize(): Promise<void> {
    this.authInstance = deviceAuthentication.createDeviceAuthentication();
  }
  
  /**
   * 作为被认证方：生成认证二维码
   */
  async generateAuthQrCode(): Promise<QrCodeInfo> {
    if (!this.authInstance) {
      throw new Error('认证实例未初始化');
    }
    
    try {
      // 生成认证参数
      const authParam = await this.authInstance.generateQrCodeAuthParam({
        expireTime: 120000,     // 2分钟有效期
        deviceInfo: {
          deviceName: 'MyDevice',
          deviceType: 'PHONE'
        }
      });
      
      // 构建二维码内容
      const qrContent = JSON.stringify({
        type: 'DEVICE_AUTH',
        version: '1.0',
        deviceId: authParam.deviceId,
        challenge: authParam.challenge,
        timestamp: Date.now()
      });
      
      console.info(`[QrCode] 生成认证二维码`);
      
      return {
        content: qrContent,
        deviceId: authParam.deviceId,
        challenge: authParam.challenge,
        expireTime: Date.now() + 120000
      };
    } catch (error) {
      console.error(`[QrCode] 生成二维码失败: ${JSON.stringify(error)}`);
      throw error;
    }
  }
  
  /**
   * 作为发起方：扫描二维码进行认证
   */
  async scanAndAuthenticate(): Promise<AuthResult> {
    if (!this.authInstance) {
      throw new Error('认证实例未初始化');
    }
    
    try {
      // 启动扫码
      const scanResult = await scanBarcode.startScan({
        enableMultiMode: false,
        enableAlbum: true
      });
      
      // 解析二维码内容
      const qrData = JSON.parse(scanResult.originalValue);
      
      // 验证二维码类型
      if (qrData.type !== 'DEVICE_AUTH') {
        return {
          success: false,
          trustLevel: TrustLevel.TRUST_INVALID,
          message: '无效的认证二维码'
        };
      }
      
      // 检查是否过期
      if (Date.now() > qrData.timestamp + 120000) {
        return {
          success: false,
          trustLevel: TrustLevel.TRUST_INVALID,
          message: '二维码已过期'
        };
      }
      
      // 发起认证
      const authResult = await this.authInstance.authenticateWithQrCode({
        deviceId: qrData.deviceId,
        challenge: qrData.challenge
      });
      
      console.info(`[QrCode] 认证结果: ${authResult.success}`);
      
      return {
        success: authResult.success,
        trustLevel: authResult.trustLevel,
        message: authResult.success ? '认证成功' : '认证失败'
      };
    } catch (error) {
      console.error(`[QrCode] 扫码认证失败: ${JSON.stringify(error)}`);
      
      return {
        success: false,
        trustLevel: TrustLevel.TRUST_INVALID,
        message: `认证失败: ${error}`
      };
    }
  }
  
  /**
   * 释放资源
   */
  release(): void {
    this.authInstance = null;
  }
}

// 二维码信息结构
interface QrCodeInfo {
  content: string;        // 二维码内容
  deviceId: string;       // 设备ID
  challenge: string;      // 挑战码
  expireTime: number;     // 过期时间
}

四、踩坑与注意事项

4.1 认证流程相关

坑1：认证超时未处理

认证过程可能因网络问题超时，需要合理处理。

// ✅ 正确做法：设置超时并处理
async authenticateWithTimeout(deviceId: string): Promise<AuthResult> {
  const timeout = 30000;  // 30秒超时
  
  const authPromise = this.authenticateDevice(deviceId, AuthType.AUTH_PIN_CODE);
  const timeoutPromise = new Promise<AuthResult>((_, reject) => {
    setTimeout(() => reject(new Error('认证超时')), timeout);
  });
  
  try {
    return await Promise.race([authPromise, timeoutPromise]);
  } catch (error) {
    // 取消正在进行的认证
    await this.cancelAuthentication(deviceId);
    
    return {
      success: false,
      trustLevel: TrustLevel.TRUST_INVALID,
      message: '认证超时'
    };
  }
}

坑2：信任关系过期未刷新

信任关系有有效期，过期后需要重新认证。

// ✅ 正确做法：定期检查并刷新信任关系
async refreshTrustRelations(): Promise<void> {
  const now = Date.now();
  const refreshThreshold = 7 * 24 * 60 * 60 * 1000;  // 7天内过期
  
  for (const [deviceId, relation] of this.trustRelations) {
    // 检查是否即将过期
    if (relation.expireTime - now < refreshThreshold) {
      console.info(`[DeviceAuth] 刷新信任关系: ${deviceId}`);
      
      // 尝试自动刷新（同账号设备）
      if (relation.authType === AuthType.AUTH_SAME_ACCOUNT) {
        await this.authenticateDevice(deviceId, AuthType.AUTH_SAME_ACCOUNT);
      }
    }
  }
}

4.2 安全相关

坑3：PIN码泄露

PIN码在传输过程中可能被截获。

// ✅ 正确做法：使用加密通道传输PIN码
async sendPinCodeSecurely(deviceId: string, pinCode: string): Promise<void> {
  // 获取设备的公钥
  const publicKey = await this.getDevicePublicKey(deviceId);
  
  // 加密PIN码
  const encryptedPin = await this.encryptWithPublicKey(pinCode, publicKey);
  
  // 发送加密后的PIN码
  await this.authInstance.sendEncryptedPinCode({
    deviceId: deviceId,
    encryptedPin: encryptedPin
  });
}

坑4：重放攻击

攻击者可能截获认证消息并重放。

// ✅ 正确做法：使用挑战-响应机制防重放
async challengeResponseAuth(deviceId: string): Promise<boolean> {
  // 1. 发送挑战码
  const challenge = this.generateChallenge();
  await this.sendChallenge(deviceId, challenge);
  
  // 2. 接收响应
  const response = await this.receiveResponse(deviceId);
  
  // 3. 验证响应（响应应该是挑战码的签名）
  const isValid = await this.verifyChallengeResponse(challenge, response);
  
  return isValid;
}

4.3 用户体验相关

坑5：认证失败无提示

用户不知道认证失败的原因。

// ✅ 正确做法：提供详细的错误提示
const AuthErrorMessages = {
  'ERR_NETWORK': '网络连接失败，请检查网络设置',
  'ERR_TIMEOUT': '认证超时，请重试',
  'ERR_PIN_INVALID': 'PIN码错误，请重新输入',
  'ERR_PIN_EXPIRED': 'PIN码已过期，请重新生成',
  'ERR_DEVICE_OFFLINE': '设备已离线',
  'ERR_ALREADY_AUTH': '设备已认证',
  'ERR_PERMISSION_DENIED': '缺少认证权限'
};

function getAuthErrorMessage(errorCode: string): string {
  return AuthErrorMessages[errorCode] || '认证失败，请重试';
}

五、HarmonyOS 6适配指南

5.1 API变更

认证API重构：

// HarmonyOS 5.0
import deviceAuthentication from '@ohos.distributedHardware.deviceAuthentication';
const auth = deviceAuthentication.createDeviceAuthentication();

// HarmonyOS 6.0
import { DeviceAuthentication, AuthType, AuthParam } from '@ohos.distributedHardware.deviceAuthentication';
const auth = DeviceAuthentication.getInstance();

认证参数变更：

// HarmonyOS 5.0
auth.authenticateDevice({
  deviceId: deviceId,
  authType: 1  // 数字类型
});

// HarmonyOS 6.0
await auth.authenticate({
  targetDevice: deviceId,
  authType: AuthType.SAME_ACCOUNT,  // 枚举类型
  authLevel: AuthLevel.HIGH         // 新增认证等级
});

5.2 行为变更

变更1：认证流程简化

HarmonyOS 6简化了同账号设备的认证流程，实现真正的"零交互"认证。

// HarmonyOS 6新增自动认证能力
await auth.enableAutoAuth({
  sameAccount: true,      // 同账号自动认证
  trustedDevices: true    // 已信任设备自动认证
});

变更2：生物识别认证增强

// HarmonyOS 6新增多生物识别支持
const result = await auth.authenticateWithBiometric({
  deviceId: deviceId,
  biometricTypes: [BiometricType.FINGERPRINT, BiometricType.FACE],  // 支持多种方式
  fallbackToPin: true  // 生物识别失败时回退到PIN码
});

变更3：信任关系管理增强

// HarmonyOS 6新增信任关系查询接口
const relations = await auth.queryTrustRelations({
  trustLevel: TrustLevel.TRUST_HIGH,
  authType: AuthType.SAME_ACCOUNT,
  includeExpired: false
});

5.3 兼容性适配代码

/**
 * 设备认证兼容层
 */
export class DeviceAuthCompat {
  private instance: any = null;
  private apiLevel: number = 6;
  
  async initialize(): Promise<void> {
    this.apiLevel = this.detectApiLevel();
    
    if (this.apiLevel >= 6) {
      const { DeviceAuthentication } = require('@ohos.distributedHardware.deviceAuthentication');
      this.instance = DeviceAuthentication.getInstance();
    } else {
      const deviceAuthentication = require('@ohos.distributedHardware.deviceAuthentication');
      this.instance = deviceAuthentication.createDeviceAuthentication();
    }
  }
  
  async authenticate(deviceId: string, authType: AuthType): Promise<AuthResult> {
    if (this.apiLevel >= 6) {
      const { AuthType: AuthTypeEnum } = require('@ohos.distributedHardware.deviceAuthentication');
      return await this.instance.authenticate({
        targetDevice: deviceId,
        authType: this.convertAuthTypeV6(authType)
      });
    } else {
      return await this.instance.authenticateDevice({
        deviceId: deviceId,
        authType: this.convertAuthTypeV5(authType)
      });
    }
  }
  
  private convertAuthTypeV6(authType: AuthType): any {
    const { AuthType: AuthTypeEnum } = require('@ohos.distributedHardware.deviceAuthentication');
    const map = {
      [AuthType.AUTH_SAME_ACCOUNT]: AuthTypeEnum.SAME_ACCOUNT,
      [AuthType.AUTH_PIN_CODE]: AuthTypeEnum.PIN_CODE,
      [AuthType.AUTH_QR_CODE]: AuthTypeEnum.QR_CODE
    };
    return map[authType];
  }
  
  private convertAuthTypeV5(authType: AuthType): number {
    return authType as number;
  }
  
  private detectApiLevel(): number {
    try {
      require('@ohos.distributedHardware.deviceAuthentication').DeviceAuthentication;
      return 6;
    } catch {
      return 5;
    }
  }
}

六、总结

设备认证是HarmonyOS分布式安全的基石，通过多层认证体系、灵活的认证方式、完善的密钥交换机制，确保了分布式通信的安全性。

核心要点回顾：

1. 信任模型：基于账号的信任模型，结合点对点认证
2. 认证方式：同账号、PIN码、二维码、生物识别等多种方式
3. 密钥交换：ECDH密钥交换，AES-256-GCM数据加密
4. 信任管理：信任关系存储、查询、更新、删除

最佳实践建议：

• 优先使用同账号认证，实现零交互体验
• 设置合理的认证超时时间
• 定期检查并刷新信任关系
• 使用加密通道传输敏感信息
• 使用挑战-响应机制防重放攻击
• 提供详细的认证失败提示
• 使用兼容层适配多版本API

设备认证让分布式通信既安全又便捷，是构建可信分布式应用的基础。