大家好，我是[晚风依旧似温柔]，新人一枚，欢迎大家关注~

前言

在 HarmonyOS 应用开发中，数据安全往往是架构设计中不可忽视的一环。当业务涉及到用户敏感数据（如个人隐私、交易记录、本地缓存凭证）时，使用 ArkData 的关系型数据库（RDB，RelationalStore）进行本地加密存储是常见做法。

但在实际开发和运维周期中，加密并不是“一次配置、永久不管”的操作。出于合规要求、密钥泄露风险应对或定期的密钥轮换（Key Rotation）策略，业务系统往往需要对数据库密钥进行更换。

如果数据库已经存有大量数据，直接删库重建显然不可接受。ArkData 提供了 rekeyEx 等接口，专门用于解决运行期数据库重新配置加密参数与更换密钥的问题。本文将基于 HarmonyOS 官方规范，详细拆解 RDB 加密机制、rekeyEx 的正确使用姿势以及数据库密钥生命周期的设计方案。

一、数据库加密与普通 Asset 存储不是一回事

在动手写代码前，首先需要区分 HarmonyOS 中两个容易混淆的概念：关键资产存储服务（Asset Store Kit） 与 关系型数据库加密（ArkData RDB Encryption）。

维 度	关键资产存储服务（Asset Store Kit）	关系型数据库加密（ArkData RDB）
主要用途	存储少量、高敏感的凭证（如 Token、密码、数据库主密钥）	存储结构化、大规模的业务数据（如聊天记录、本地账本）
底层实现	基于 HUKS / TEE 硬件级安全隔离存储	基于 AES 算法对 SQLite 数据库文件页（Page）进行整体加密
容量限制	仅适合存储小块数据（通常为字节/KB 级）	支持 MB 到 GB 级别的结构化数据高效读写
相互关系	托管者：可用于安全生成和保管 RDB 加密所需的密钥	使用者：从 Asset 获取密钥后，传递给 RDB 进行落盘加解密

简单来说：Asset 负责管钥匙，RDB 负责用钥匙锁门。

当我们需要更换 RDB 的数据库加密密钥时，本质上包含两个动作：

1. 在安全区域（如 Asset Store）生成新的密钥凭证；
2. 调用 RDB 的 rekeyEx 接口，将已有数据库文件的底层加密页按新密钥重新加密。

二、官方接口规范与 API 约束

在 Stage 模型下，ArkData 提供了 @ohos.data.relationalStore 模块来管理关系型数据库。

• Kit 归属：ArkData Kit（数据管理 Kit）

• 导入模块：import { relationalStore } from '@kit.ArkData';

• 适用模型：Stage 模型

• 核心接口：

  • getRdbStore(context: Context, config: StoreConfig)：获取或创建数据库实例。
  • RdbStore.rekeyEx(newConfig: StoreConfig)：更新数据库的加密密钥及加密相关参数。

三、搭建最小实践场景：创建与正常读写

首先构造一个加密数据库的初始化与基础读写场景。

1. 数据库配置定义

在创建加密数据库时，必须在 StoreConfig 中将 encrypt 设置为 true。

import { relationalStore } from '@kit.ArkData';
import { UIAbility } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

// 假设从安全存储中获取到的原始密钥（推荐32字节/256位）
const ORIGINAL_KEY = new Uint8Array([
  0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08,
  0x09, 0x0A, 0x0B, 0x0C, 0x0D, 0x0E, 0x0F, 0x10,
  0x11, 0x12, 0x13, 0x14, 0x15, 0x16, 0x17, 0x18,
  0x19, 0x1A, 0x1B, 0x1C, 0x1D, 0x1E, 0x1F, 0x20
]);

const STORE_CONFIG: relationalStore.StoreConfig = {
  name: 'SecureBusiness.db',
  securityLevel: relationalStore.SecurityLevel.S3,
  encrypt: true,
  cryptoParam: {
    encryptionKey: ORIGINAL_KEY
  }
};

2. 初始化数据库并建表

export async function initEncryptedDatabase(context: Context): Promise<relationalStore.RdbStore> {
  try {
    const store = await relationalStore.getRdbStore(context, STORE_CONFIG);
    
    // 建表 SQL
    const SQL_CREATE_TABLE = `
      CREATE TABLE IF NOT EXISTS ACCOUNT (
        ID INTEGER PRIMARY KEY AUTOINCREMENT,
        USER_NAME TEXT NOT NULL,
        BALANCE REAL NOT NULL
      );
    `;
    await store.executeSql(SQL_CREATE_TABLE);
    return store;
  } catch (err) {
    const error = err as BusinessError;
    console.error(`[RDB_Demo] Failed to get RdbStore. Code: ${error.code}, message: ${error.message}`);
    throw error;
  }
}

四、核心实践：使用 rekeyEx 轮换数据库密钥

当应用触发密钥更换逻辑时（例如检测到密钥到期、安全策略升级，或用户主动重置了安全密码），我们需要使用新的密钥来重新加密现有数据库。

1. rekeyEx 接口实现示例

rekeyEx 支持传入全新的 StoreConfig 配置，从而更新加密密钥或加密参数。

import { relationalStore } from '@kit.ArkData';
import { BusinessError } from '@kit.BasicServicesKit';

/**
 * 轮换 RDB 数据库密钥
 * @param store 当前已打开的 RdbStore 实例
 * @param newKey 32字节的新密钥
 */
export async function rotateDatabaseKey(
  store: relationalStore.RdbStore, 
  newKey: Uint8Array
): Promise<boolean> {
  // 1. 构造带有新密钥的 StoreConfig
  const newConfig: relationalStore.StoreConfig = {
    name: 'SecureBusiness.db',
    securityLevel: relationalStore.SecurityLevel.S3,
    encrypt: true,
    cryptoParam: {
      encryptionKey: newKey
    }
  };

  try {
    // 2. 调用 rekeyEx 执行数据库重加密
    await store.rekeyEx(newConfig);
    console.info('[RDB_Demo] Database rekeyEx executed successfully.');
    return true;
  } catch (err) {
    const error = err as BusinessError;
    // 错误码 14800011 通常代表数据库损坏或密钥错误，错误码 14800000 代表一般内部错误
    console.error(`[RDB_Demo] Rekey failed. Code: ${error.code}, message: ${error.message}`);
    return false;
  }
}

2. 换密钥后的数据访问验证

调用 rekeyEx 成功后，当前句柄（store）即可继续正常进行读写操作，无需手动关闭或重新打开句柄。但在下一次应用冷启动时，必须使用新密钥才能正确初始化 RdbStore。

export async function verifyDataAccess(store: relationalStore.RdbStore): Promise<void> {
  const predicates = new relationalStore.RdbPredicates('ACCOUNT');
  try {
    const resultSet = await store.query(predicates, ['ID', 'USER_NAME', 'BALANCE']);
    console.info(`[RDB_Demo] Row count after rekey: ${resultSet.rowCount}`);
    resultSet.close();
  } catch (err) {
    const error = err as BusinessError;
    console.error(`[RDB_Demo] Query failed post-rekey. Code: ${error.code}`);
  }
}

五、关键开发细节点与逻辑拆解

在调用 rekeyEx 时，以下几个关键逻辑点需要特别留心：

1. 操作原子性与数据安全：

   • rekeyEx 执行过程中，系统内部会对数据库文件进行逐页重加密。在此期间，应当避免发起耗时极长的大批量写事务，尽量确保 rekeyEx 在相对平静的上下文环境中进行。

2. 新旧密钥交接的次序问题：

   • 绝对不能提前把 Asset Store 里的旧密钥覆写掉。推荐的更新流程为：

     1. 生成新密钥 Key_B；
     2. 调用 store.rekeyEx(newConfigWithKeyB)；
     3. 当 rekeyEx 返回成功（Promise resolve）后，再将 Key_B 写入 Asset Store 覆盖 Key_A；
     4. 如果 rekeyEx 抛出异常，保持 Asset Store 里的 Key_A 不变，避免下次启动时因密钥不匹配导致数据库无法打开。

3. 密钥长度与格式约束：

   • ArkData 加密参数要求密钥具有固定的安全强度，通常要求传入 32 字节（256 位）的 Uint8Array 数据。格式不合规直接触发参数校验异常。

六、常见错误分析与排查清单

当更换密钥出现问题时，可以按照以下清单依次排查：

[排查流程]
  │
  ├─ 1. 检查错误码 Error Code
  │     ├─ Code 401: 参数检查失败（检查 cryptoParam 格式及密钥长度）
  │     ├─ Code 14800000: 数据库内部错误（检查磁盘空间是否不足，重加密需要临时额外空间）
  │     └─ Code 14800011: 数据库可能已损坏或旧密钥错误
  │
  ├─ 2. 检查内存句柄状态
  │     └─ 是否在 rekeyEx 前手动关闭了 RdbStore？（rekeyEx 需要在已打开的 store 上调用）
  │
  └─ 3. 检查冷启动配置
        └─ 下一次重新 getRdbStore 时，是否配置了更新后的新密钥？

七、数据库密钥全生命周期管理架构设计

为了保障数据库密钥在实际生产环境中的可靠性，建议设计如下的完整生命周期管理体系：

【建议插图3：数据库密钥生命周期状态机图（生成 -> 使用 -> 轮换 -> 销毁/备份）】

1. 密钥生成：应用首次启动时，由 HUKS（OpenHarmony 通用密钥库系统）或算法安全库生成 256 位高熵随机数作为 RDB 加密密钥。
2. 密钥托管：将该密钥持久化存入 Asset Store（关键资产存储服务），设置合理的访问控制权限（如仅解锁后可读）。
3. 密钥读取与加载：应用启动时，先从 Asset Store 读取密钥，构造 StoreConfig 唤醒 RdbStore。
4. 动态轮换（Rekey）：当触发安全审计策略时，生成新密钥，通过 rekeyEx 完成落盘数据更新，同步更新 Asset Store 中的存储凭证。
5. 异常恢复机制：预留密钥损坏/重置后的恢复策略（例如提示用户重新登录以从服务端拉取同步数据重新建库）。

八、总结

数据库加密不是一劳永逸的工作，密钥轮换是构建高安全级别 HarmonyOS 应用的标准动作。ArkData 提供的 rekeyEx 接口简化了重加密的过程，开发者在实际落地时，只需把握好 “Asset 凭证管理” 与 “RDB 数据页重加密” 的次序逻辑，即可平滑完成密钥变更。

你在开发过程中是否遇到过加密数据库版本升级或密钥轮换的特殊场景？欢迎在评论区交流你的实践经验！

参考资料

1. 《ArkData (数据管理 Kit) 开发指南 - 关系型数据库》 华为开发者联盟
2. 《@ohos.data.relationalStore API 参考》 华为开发者联盟
3. 《关键资产存储服务 (Asset Store Kit) 开发指南》 华为开发者联盟

如果觉得有帮助，别忘了点个赞+关注支持一下~
喜欢记得关注，别让好内容被埋没～