欢迎加入开源鸿蒙跨平台社区：https://openharmonycrossplatform.csdn.net

前言

在开发 OpenHarmony 涉及用户隐私、支付或核心机密的 App 时，基础的 Base64 或简单的 MD5 已经无法满足安全需求。我们需要的是国际标准的现代密码学算法，如 AES-GCM、ChaCha20、ED25519 等。

cryptography 是目前 Flutter 生态中最推荐的现代密码学库。它不仅提供了极其丰富的算法实现，更关键的是它支持“分块处理”和“异步运算”，非常适合在鸿蒙设备上处理大文件加密。

一、核心加密体系解析

cryptography 采用了强类型的 API 设计，确保你不会错误地组合不兼容的参数。

二、核心 API 实战

2.1 对称加密 (AES-GCM)

AES-GCM 是目前公认的最安全的对称加密方案之一，自带真伪校验（MAC）。

import 'package:cryptography/cryptography.dart';

Future<void> aesEncrypt() async {
  final message = [1, 2, 3, 4]; // 待加密数据
  final algorithm = AesGcm.with256bits();
  
  // 1. 生成或指定密钥
  final secretKey = await algorithm.newSecretKey();
  
  // 2. 执行加密
  final secretBox = await algorithm.encrypt(
    message,
    secretKey: secretKey,
  );

  print('密文: ${secretBox.cipherText}');
  print('校验码: ${secretBox.mac.bytes}');
}

2.2 摘要算法 (SHA-256)

用于验证文件完整性。

final algorithm = Sha256();
final hash = await algorithm.hash([1, 2, 3]);
print('哈希值: $hash');

2.3 数字签名 (Ed25519)

用于验证鸿蒙端发送给服务器的消息确实来自于该设备且未被篡改。

final algorithm = Ed25519();
final keyPair = await algorithm.newKeyPair();
final signature = await algorithm.sign([1, 2, 3], keyPair: keyPair);

三、OpenHarmony 平台适配

3.1 性能优化

💡 技巧：在鸿蒙真机上进行海量数据加密时，cryptography 会自动并行化运算。配合前文提到的 isolate_manager 使用，可以确保加密过程完全不占用主线程资源。

3.2 密钥安全存储

在鸿蒙系统上，通过 algorithm.newSecretKey() 生成的密钥建议使用鸿蒙原生的 HUKS (HarmonyOS Universal KeyStore) 进行隔离保存，从而实现硬件级的安全保护。

四、完整实战示例：鸿蒙私密记事本加密引擎

本示例展示如何为一个记事本应用实现完整的“一键加解密”功能。

import 'package:cryptography/cryptography.dart';
import 'dart:convert';

class OhosSecurityEngine {
  final _algo = AesGcm.with256bits();
  SecretKey? _key;

  Future<void> init() async {
    _key = await _algo.newSecretKey(); // 💡 实际应从鸿蒙密钥库读取
  }

  /// 加密文本 (支持中文)
  Future<List<int>> encryptNote(String text) async {
    if (_key == null) throw Exception("引擎未初始化");
    final secretBox = await _algo.encrypt(
      utf8.encode(text), // 💡 使用 UTF-8 编码处理多字节字符
      secretKey: _key!,
    );
    // 💡 将密文、Nonce 和 MAC 组合打包返回
    return secretBox.concatenation();
  }

  /// 解密文本
  Future<String> decryptNote(List<int> combinedData) async {
    if (_key == null) throw Exception("引擎未初始化");
    final secretBox = SecretBox.fromConcatenation(
      combinedData,
      nonceLength: _algo.nonceLength,
      macLength: _algo.macAlgorithm.macLength,
    );
    
    final clearText = await _algo.decrypt(
      secretBox,
      secretKey: _key!,
    );
    return utf8.decode(clearText); // 💡 使用 UTF-8 解码还原字符串
  }
}

五、总结

cryptography 软件包为 OpenHarmony 开发者提供了最坚实的安全底座。它抛弃了陈旧、不安全的算法，通过现代密码学的最佳实践，让鸿蒙应用能以工业级的强度保护用户数据。在构建需要满足国家等保要求或金融安全标准的项目时，它是不二选择。