一、插件介绍

Fluttertpc_Cryptography_Flutter 是一个功能强大的密码学库，为 Dart/Flutter 开发者提供了全面的加密算法支持。该库专为鸿蒙平台进行了适配和优化，提供了安全、高效的密码学操作，包括对称加密、非对称加密、哈希函数、密钥派生等多种功能。

核心功能

• 🔐 对称加密：AES-GCM、ChaCha20-Poly1305 等高级加密标准
• 📊 非对称加密：ECDH、RSA、X25519 等密钥交换和签名算法
• 📝 哈希函数：SHA-1、SHA-256、SHA-512 等安全哈希算法
• 🗝️ 密钥派生：PBKDF2、HKDF 等基于密码的密钥派生函数
• 🔏 消息认证：HMAC、MAC 等消息完整性验证
• 📦 跨平台支持：纯 Dart 实现和鸿蒙平台原生 API 结合，确保性能和安全性
• 🔄 后台计算：支持大文件加密解密的后台计算功能

适用场景

Fluttertpc_Cryptography_Flutter 适用于各种需要安全加密的 HarmonyOS Flutter 应用，如：

• 🔐 安全通信应用的数据加密
• 📱 移动支付应用的敏感信息保护
• 📊 企业级应用的数据安全存储
• 🔒 身份验证系统的密码哈希
• 📁 云存储应用的端到端加密
• 🔑 密钥管理和交换系统

二、安装与集成

2.1 环境要求

• Flutter: 3.7.12-ohos-1.1.3 或更高版本
• HarmonyOS SDK: 5.0.0(12) 或更高版本
• DevEco Studio: 5.1.0.828 或更高版本

2.2 依赖配置

由于这是一个自定义修改版本的密码学库，需要通过 Git 方式引入。在项目的 pubspec.yaml 文件中添加以下依赖配置：

dependencies:
  cryptography_ohos:
    git:
      url: "https://atomgit.com/openharmony-sig/fluttertpc_cryptography_flutter.git"
      path: "cryptography_ohos"

2.3 安装依赖

执行以下命令安装依赖：

flutter pub get

三、API 文档与使用示例

3.1 基础加密示例 - AES-GCM

AES-GCM 是一种常用的对称加密算法，提供了加密和认证功能：

import 'package:cryptography/cryptography.dart';

Future<void> main() async {
  // 创建 AES-GCM 256 位加密算法实例
  final algorithm = AesGcm.with256bits();

  // 生成随机的 256 位密钥
  final secretKey = await algorithm.newSecretKey();

  // 生成随机的 96 位 nonce（一次性使用的随机数）
  final nonce = algorithm.newNonce();

  // 要加密的明文数据
  final clearText = "Hello, HarmonyOS Cryptography!";
  final clearTextBytes = clearText.codeUnits;

  // 加密数据
  final secretBox = await algorithm.encrypt(
    clearTextBytes,
    secretKey: secretKey,
    nonce: nonce,
  );

  print('加密成功：');
  print('密文: ${secretBox.cipherText}');
  print('认证标签 (MAC): ${secretBox.mac}');

  // 解密数据
  final decryptedBytes = await algorithm.decrypt(
    secretBox,
    secretKey: secretKey,
  );

  final decryptedText = String.fromCharCodes(decryptedBytes);
  print('\n解密成功：');
  print('明文: $decryptedText');
}

3.2 哈希函数示例 - SHA-256

SHA-256 是一种广泛使用的安全哈希算法：

import 'package:cryptography/cryptography.dart';

Future<void> main() async {
  // 创建 SHA-256 哈希算法实例
  final algorithm = Sha256();

  // 要计算哈希的数据
  final data = "Hello, HarmonyOS!";
  final dataBytes = data.codeUnits;

  // 计算哈希值
  final hash = await algorithm.hash(dataBytes);

  print('数据: $data');
  print('SHA-256 哈希值: ${hash.bytes}');
  print('哈希值长度: ${hash.bytes.length} 字节');
}

3.3 密钥派生示例 - PBKDF2

PBKDF2 用于从密码生成安全的加密密钥：

import 'package:cryptography/cryptography.dart';

Future<void> main() async {
  // 创建 PBKDF2 密钥派生实例
  final algorithm = Pbkdf2(
    macAlgorithm: Hmac(Sha256()),
    iterations: 100000,
    bits: 256,
  );

  // 用户密码
  final password = "my_strong_password";
  final passwordBytes = password.codeUnits;

  // 盐值（应随机生成并存储）
  final salt = [1, 2, 3, 4, 5, 6, 7, 8];

  // 生成密钥
  final secretKey = await algorithm.deriveKey(
    secretKey: SecretKey(passwordBytes),
    nonce: salt,
  );

  // 获取密钥的字节表示
  final secretKeyBytes = await secretKey.extractBytes();

  print('密码: $password');
  print('生成的 256 位密钥: $secretKeyBytes');
  print('密钥长度: ${secretKeyBytes.length} 字节');
}

3.4 非对称加密示例 - ECDH 密钥交换

ECDH 用于在不安全的通道上安全地交换密钥：

import 'package:cryptography/cryptography.dart';

Future<void> main() async {
  // 创建 ECDH P-256 密钥交换算法实例
  final algorithm = Ecdh.p256();

  print('=== 用户 A 生成密钥对 ===');
  final aliceKeyPair = await algorithm.newKeyPair();
  final alicePublicKey = await aliceKeyPair.extractPublicKey();

  print('=== 用户 B 生成密钥对 ===');
  final bobKeyPair = await algorithm.newKeyPair();
  final bobPublicKey = await bobKeyPair.extractPublicKey();

  print('=== 用户 A 计算共享密钥 ===');
  final aliceSharedSecret = await algorithm.sharedSecretKey(
    keyPair: aliceKeyPair,
    remotePublicKey: bobPublicKey,
  );

  print('=== 用户 B 计算共享密钥 ===');
  final bobSharedSecret = await algorithm.sharedSecretKey(
    keyPair: bobKeyPair,
    remotePublicKey: alicePublicKey,
  );

  // 验证两个共享密钥是否相同
  final aliceSecretBytes = await aliceSharedSecret.extractBytes();
  final bobSecretBytes = await bobSharedSecret.extractBytes();

  print('\n=== 共享密钥验证 ===');
  print('用户 A 共享密钥: $aliceSecretBytes');
  print('用户 B 共享密钥: $bobSecretBytes');
  print('密钥是否相同: ${aliceSecretBytes.toString() == bobSecretBytes.toString()}');
}

3.5 消息认证示例 - HMAC

HMAC 用于验证消息的完整性和真实性：

import 'package:cryptography/cryptography.dart';

Future<void> main() async {
  // 创建 HMAC-SHA256 消息认证算法实例
  final algorithm = Hmac(Sha256());

  // 密钥
  final secretKey = await algorithm.newSecretKeyFromBytes([1, 2, 3, 4]);

  // 消息
  final message = "This is a secure message!";
  final messageBytes = message.codeUnits;

  // 计算 HMAC
  final mac = await algorithm.calculateMac(
    messageBytes,
    secretKey: secretKey,
  );

  print('消息: $message');
  print('HMAC: ${mac.bytes}');
  print('HMAC 长度: ${mac.bytes.length} 字节');

  // 验证 HMAC
  final isMacValid = await algorithm.checkMac(
    mac,
    messageBytes,
    secretKey: secretKey,
  );

  print('HMAC 验证结果: $isMacValid');
}

3.6 后台加密示例

对于大文件加密，可以使用后台计算功能避免阻塞 UI：

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

Future<void> main() async {
  // 启用 Flutter 加密支持
  FlutterCryptography.enable();

  // 创建支持后台计算的 AES-GCM 实例
  final algorithm = BackgroundAesGcm.with256bits();

  // 生成密钥和 nonce
  final secretKey = await algorithm.newSecretKey();
  final nonce = algorithm.newNonce();

  // 假设这是一个大文件的数据
  final largeData = List<int>.filled(10 * 1024 * 1024, 0x42); // 10MB 数据

  print('开始加密大文件...');
  final stopwatch = Stopwatch()..start();

  // 在后台加密大文件
  final secretBox = await algorithm.encrypt(
    largeData,
    secretKey: secretKey,
    nonce: nonce,
  );

  stopwatch.stop();
  print('加密完成！耗时: ${stopwatch.elapsedMilliseconds} 毫秒');
  print('密文长度: ${secretBox.cipherText.length} 字节');
  print('MAC 长度: ${secretBox.mac.bytes.length} 字节');

  // 解密
  stopwatch.reset();
  stopwatch.start();
  print('\n开始解密大文件...');

  final decryptedData = await algorithm.decrypt(
    secretBox,
    secretKey: secretKey,
  );

  stopwatch.stop();
  print('解密完成！耗时: ${stopwatch.elapsedMilliseconds} 毫秒');
  print('解密后数据长度: ${decryptedData.length} 字节');
  print('数据是否匹配: ${decryptedData.length == largeData.length}');
}

四、HarmonyOS 平台特定配置

4.1 权限配置

在 HarmonyOS 平台上使用密码学功能，一般不需要特殊权限。但如果需要访问设备的安全存储或生物识别功能，可能需要在 module.json5 文件中配置相关权限。

4.2 性能优化

对于性能敏感的应用，可以考虑以下优化：

1. 使用平台特定实现：鸿蒙平台原生实现通常比纯 Dart 实现更快
2. 后台计算：对于大文件加密解密，使用 BackgroundAesGcm、BackgroundChacha 等类
3. 合理选择算法：根据需求选择合适的算法（如 ChaCha20-Poly1305 在移动设备上通常比 AES 更快）
4. 复用密钥和 nonce：避免频繁生成密钥和 nonce，除非必要

五、API 参考

5.1 主要算法类

算法类	类型	描述	HarmonyOS 支持
AesGcm	对称加密	AES-GCM 加密算法	✅
ChaCha20Poly1305Aead	对称加密	ChaCha20-Poly1305 加密算法	✅
Sha256	哈希函数	SHA-256 哈希算法	✅
Sha512	哈希函数	SHA-512 哈希算法	✅
Ecdh.p256()	密钥交换	ECDH P-256 密钥交换算法	✅
Ecdh.p384()	密钥交换	ECDH P-384 密钥交换算法	✅
Ecdh.p521()	密钥交换	ECDH P-521 密钥交换算法	✅
Pbkdf2	密钥派生	PBKDF2 密钥派生函数	✅
Hmac	消息认证	HMAC 消息认证码	✅
X25519	密钥交换	X25519 密钥交换算法	✅

5.2 核心方法

方法名	说明	HarmonyOS 支持
encrypt()	加密数据	✅
decrypt()	解密数据	✅
hash()	计算哈希值	✅
newSecretKey()	生成随机密钥	✅
newNonce()	生成随机 nonce	✅
calculateMac()	计算消息认证码	✅
checkMac()	验证消息认证码	✅
deriveKey()	派生密钥	✅
sharedSecretKey()	计算共享密钥	✅

六、总结

Fluttertpc_Cryptography_Flutter 是一款功能全面、易于使用的密码学库，为 HarmonyOS 平台的 Flutter 开发者提供了强大的加密功能支持。它不仅提供了丰富的加密算法，还针对鸿蒙平台进行了优化，确保了良好的性能和安全性。

使用 Fluttertpc_Cryptography_Flutter，开发者可以轻松实现各种加密需求，从简单的数据加密到复杂的密钥管理系统，都能找到合适的解决方案。该库的 API 设计简洁直观，同时提供了足够的灵活性，可以满足不同应用场景的需求。

无论你是开发安全通信应用、移动支付系统还是企业级应用，Fluttertpc_Cryptography_Flutter 都是你在 HarmonyOS 平台上的理想选择。

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