摘要

随着 HarmonyOS 不断向多设备、多场景方向发展，应用早已不只是“单机 App”。数据会在本地存储、设备之间同步、甚至参与分布式协同计算。
在这个背景下，如果数据仍然以明文方式存储，本地文件一旦被拷走、被调试、被反编译，几乎没有任何防护能力。

鸿蒙并没有让开发者从零实现加密算法，而是通过 KeyStore、加密首选项、硬件安全能力 等机制，把安全能力下沉到系统层。
本文从开发者视角出发，结合实际业务场景，系统梳理鸿蒙中加密存储的实现方式，并通过完整 Demo 代码说明如何在真实项目中落地。

引言

在实际开发中，经常能看到这样的情况：

• token 明文存在 Preferences
• 用户隐私数据直接写文件
• 配置文件被反编译后随意修改
• 分布式场景中设备凭证无任何保护

这些问题并不是因为开发者不重视安全，而是不知道鸿蒙已经提供了什么能力，也不知道该怎么用。

鸿蒙的安全模型和传统 Android 有明显区别，它更强调：

• 系统级密钥托管
• 应用与设备强绑定
• 分布式场景下的统一安全能力

理解这些前提，是正确实现加密存储的基础。

鸿蒙加密存储为什么要“分层设计”

在鸿蒙中，加密存储并不是一个单一接口，而是分成多个层级。原因很简单：
不是所有数据都值得用最高安全等级处理。

数据安全等级的现实划分

在真实项目中，数据大致可以分成三类：

• 不敏感数据：日志、缓存、临时状态
• 一般敏感数据：token、用户信息、配置
• 高敏感数据：设备身份、密钥材料、认证结果

如果所有数据都走硬件级加密，性能和开发成本都会明显上升。

鸿蒙的分层安全策略

鸿蒙提供的加密能力，正好对应这三类数据：

• 系统安全首选项：解决 80% 的轻量敏感数据
• KeyStore + AES：解决绝大多数业务敏感数据
• 硬件级密钥：解决高安全场景

理解这一点，可以避免“过度设计”。

系统安全首选项的真实使用场景扩展

为什么它适合存 token

token 有几个特点：

• 数据量小
• 生命周期短
• 不需要跨设备共享
• 一旦失效可重新获取

安全首选项正好满足这些需求。

实际业务示例：登录态管理

export async function saveLoginState(
  context: Context,
  token: string,
  expireTime: number
) {
  const pref = await preferences.getPreferences(context, 'login_state');
  await pref.put('token', token);
  await pref.put('expire', expireTime);
  await pref.flush();
}

这样做的好处

• 系统自动加密
• 应用卸载后数据自动清理
• 不需要开发者维护密钥

在真实项目中，这是性价比最高的一种方案。

KeyStore + AES 的底层逻辑扩展说明

这是很多人“会写代码，但不太理解原理”的部分。

KeyStore 到底解决了什么问题

KeyStore 的核心作用只有一个：
让密钥永远不以明文形式出现。

即使你能反编译应用代码，也拿不到密钥本体。

为什么一定要“系统生成密钥”

如果密钥由你自己生成：

• 你必须存储它
• 你无法保证不被拷走
• 加密就变成了“自欺欺人”

而系统生成的密钥：

• 与应用 UID 绑定
• 与设备环境绑定
• 可结合硬件安全模块

AES-GCM 模式为什么适合鸿蒙

AES-GCM 有两个重要特性：

1. 加密数据
2. 校验数据是否被篡改

在移动端和分布式场景下，这是非常重要的。

完整 Demo：从生成密钥到数据恢复

初始化密钥（应用首次启动）

let globalKey: cryptoFramework.SymKey | null = null;

export async function initCryptoKey() {
  if (!globalKey) {
    globalKey = await generateAesKey();
  }
}

保存用户隐私信息

export async function saveUserProfile(profile: string) {
  if (!globalKey) {
    throw new Error('key not initialized');
  }
  const encrypted = encryptData(globalKey, profile);
  saveEncryptedFile('/data/user/profile.dat', encrypted);
}

读取并解密

export async function loadUserProfile(): Promise<string> {
  if (!globalKey) {
    throw new Error('key not initialized');
  }
  const encrypted = readEncryptedFile('/data/user/profile.dat');
  return decryptData(globalKey, encrypted);
}

这个 Demo 在真实项目中的意义

• 数据在磁盘上始终是密文
• 密钥无法被导出
• 解密只能在本应用内完成

分布式场景下的加密存储扩展说明

分布式场景的新问题

在分布式系统中，数据可能：

• 本地生成
• 跨设备同步
• 多端共同使用

如果存储环节不安全，后续的分布式认证都是空谈。

示例：设备认证结果加密存储

const authResult = {
  deviceId: 'device_xxx',
  trustLevel: 3,
  timestamp: Date.now()
};

saveEncryptedFile(
  '/data/distributed/auth.dat',
  encryptData(globalKey, JSON.stringify(authResult))
);

即使认证文件被复制到另一台设备，也无法解密。

常见误区的进一步拆解

“我只是本地用，用不着加密”

本地文件是最容易被拷走的。

“我自己写一套加密逻辑更灵活”

除非你在做安全产品，否则不建议。

“只要加密了就安全了”

错误。
密钥管理比算法更重要。

QA 环节

Q：加密会不会影响性能？
A：对大多数业务来说，影响可以忽略，远小于网络请求成本。

Q：应用卸载后数据还能恢复吗？
A：不能。密钥会被系统一并清理。

Q：可以在多设备间共享密钥吗？
A：不建议，应通过分布式认证机制重新生成。

总结

在 HarmonyOS 中实现加密存储，并不是“加几行代码”的问题，而是一种安全设计思维。

真正安全的做法是：

• 密钥永远不出系统
• 数据始终以密文形式落盘
• 不同安全等级采用不同方案

当你把这套思路用在项目里时，加密存储就不再是负担，而是应用质量的一部分。