鸿蒙App数据加密存储（AES加密本地敏感信息）

鸿蒙App数据加密存储（AES加密本地敏感信息）

一、引言与技术背景

二、核心概念与原理

1. AES 加密基础

• 对称加密：加密和解密使用相同密钥的加密算法。优点是速度快，适合大量数据的加密。缺点是密钥的分发和管理是安全难点。
• 密钥 (Key)：用于加密和解密的“钥匙”。AES 支持的密钥长度主要有三种：128位 (16字节)、192位 (24字节)​ 和 256位 (32字节)。密钥越长，安全性越高，但性能开销也略有增加。对于绝大多数移动应用场景，128位或256位密钥已足够安全。
• 工作模式 (Mode of Operation)：当需要对超过一个数据块（AES 的块大小固定为128位）的数据进行加密时，就需要选择合适的工作模式。不同的模式有不同的特性和安全要求。
  • ECB (Electronic Codebook)：最简单的一种模式，但极不安全，相同的明文块会产生相同的密文块，容易暴露数据模式。严禁使用。
  • CBC (Cipher Block Chaining)：一种常用的模式。每个明文块在加密前，会与前一个密文块进行异或操作。需要一个初始化向量 (IV)​ 来启动这个过程。IV 不需要保密，但必须是随机且唯一的，以保证相同明文在不同加密会话中产生不同的密文。
  • GCM (Galois/Counter Mode)：一种认证加密模式。它不仅提供机密性（加密），还提供完整性和真实性校验（认证）。它能检测密文在传输或存储过程中是否被篡改。是现代应用中推荐的优选模式。
• 填充 (Padding)：由于 AES 是块加密，要求待加密数据的长度必须是块大小的整数倍。当数据长度不足时，需要使用填充算法（如 PKCS#7）将数据扩展到合适的长度。

2. 鸿蒙 cryptoFramework模块

• cryptoFramework.Cipher：密码器类，用于执行实际的加密和解密操作。
• cryptoFramework.KeyGenerator：密钥生成器，用于安全地生成随机的对称密钥或非对称密钥对。
• cryptoFramework.SymmetricKey：对称密钥对象，用于承载 AES 密钥和 IV。
• cryptoFramework.DataBlob：数据容器，用于在 JSAPI 层和 native 层之间传递二进制数据。
• util.TextEncoder/TextDecoder：用于将字符串和 Uint8Array之间进行转换。

3. 原理流程图 (以 AES-GCM 为例)

[Plaintext String (e.g., "my_secret_token")]
      |
      |-- Convert to Uint8Array --> [Plaintext Bytes]
      V
[Generate Random AES Key (SymmetricKey)]
      |
      |-- Save securely (e.g., in KeyStore) --> [Encrypted Key Storage]
      |
      V
[Generate Random IV (Initialization Vector)]
      |
      V
[Cipher (Algorithm: AES/GCM/NoPadding, Mode: ENCRYPT_MODE)]
      |   - Takes Key & IV
      |   - Processes Plaintext Bytes
      V
[Ciphertext Bytes + Auth Tag (from GCM mode)]
      |
      |-- Combine & Encode (e.g., Base64) --> [Final Encrypted String]
      V
[Save to Preferences / File System]

[Load Encrypted String from Storage]
      |
      |-- Decode (e.g., from Base64) --> [Combined Ciphertext + Auth Tag Bytes]
      V
[Retrieve Key & IV]
      |   - Key from secure storage (KeyStore)
      |   - IV is often prepended to the ciphertext
      V
[Cipher (Algorithm: AES/GCM/NoPadding, Mode: DECRYPT_MODE)]
      |   - Takes Key & IV
      |   - Processes Combined Bytes
      |   - Verifies Auth Tag (Integrity Check)
      V
      |-- Success --> [Decrypted Plaintext Bytes]
      |-- Failure (Tampered/Corrupted) --> [Throws Exception]
                          |
                          V
          [Convert Uint8Array to String] --> [Original Plaintext String]

三、应用使用场景

• 存储用户登录凭证：加密存储从服务器获取的 access_token或 refresh_token。
• 本地账户密码：如果应用有本地账户体系，绝不能明文存储密码，应存储加盐哈希值。对于需要可逆加密的场景（如自动填充），可使用AES加密。
• 个人隐私信息：加密存储用户的手机号、邮箱、身份证号、家庭住址等。
• 应用配置信息：加密存储一些敏感的配置项，如第三方服务的 API Key。
• 安全缓存：对缓存到本地的敏感数据进行加密，防止被 root 设备上的恶意应用读取。

四、环境准备

• DevEco Studio：最新版本。
• 真机/模拟器：用于运行和测试应用。
• 待开发Demo：一个简单的应用，包含两个按钮：“加密并保存数据”和“读取并解密数据”，以及一个文本框用于输入要加密的内容。

五、不同场景的代码实现

场景一：实现 AES-GCM 加密解密工具类

import cryptoFramework from '@ohos.security.cryptoFramework';
import util from '@ohos.util';
import { BusinessError } from '@ohos.base';

// 定义一个常量，用于在存储时区分密文和IV
// 格式: ${BASE64_ENCODED_IV}${SEPARATOR}${BASE64_ENCODED_CIPHERTEXT_WITH_TAG}
const IV_CIPHERTEXT_SEPARATOR = ':';

export class SecureStorageUtil {

    /**
     * 生成一个新的随机 AES-256 密钥
     * @returns Promise<cryptoFramework.SymmetricKey>
     */
    static async generateKey(): Promise<cryptoFramework.SymmetricKey> {
        let symKeyGenerator = cryptoFramework.createSymKeyGenerator('AES256');
        let keyGenParams: cryptoFramework.KeyGenParameters = {
            alias: 'my_aes_key_alias', // 可选别名，如果用于KeyStore则需要
            specType: cryptoFramework.AsyKeySpecType.KEY_GEN_PARAMS_SPEC // 密钥生成参数类型
        };
        try {
            let key = await symKeyGenerator.generateSymKey(keyGenParams);
            console.info('[SecureStorage] AES-256 key generated successfully.');
            return key;
        } catch (error) {
            console.error('[SecureStorage] Failed to generate key:', (error as BusinessError).message);
            throw error;
        }
    }

    /**
     * 从已有的密钥材料创建 SymmetricKey 对象
     * 在实际项目中，密钥应由 KeyStore 管理，这里为了简化直接传入 Uint8Array
     * @param keyMaterial 16, 24, or 32 bytes for AES-128, AES-192, AES-256
     * @returns cryptoFramework.SymmetricKey
     */
    static createKeyFromMaterial(keyMaterial: Uint8Array): cryptoFramework.SymmetricKey {
        let keyBlob: cryptoFramework.DataBlob = { data: keyMaterial };
        let symKey = cryptoFramework.createSymKey('AES256'); // 创建时仍需指定算法
        symKey.setKeySpec(keyBlob, cryptoFramework.SymKeySpecType.KEY_MATERIAL);
        return symKey;
    }

    /**
     * 生成一个随机的 Initialization Vector (IV)
     * GCM 模式推荐 IV 长度为 96 bits (12 bytes)
     * @returns Uint8Array
     */
    static generateIv(): Uint8Array {
        let ivLen = 12; // 96 bits
        let iv = new Uint8Array(ivLen);
        cryptoFramework.generateRandom(iv);
        console.info('[SecureStorage] IV generated successfully.');
        return iv;
    }

    /**
     * 加密数据
     * @param plainText 明文字符串
     * @param key AES 密钥
     * @returns Promise<string> 返回 Base64 编码的 "IV:CiphertextWithTag"
     */
    static async encrypt(plainText: string, key: cryptoFramework.SymmetricKey): Promise<string> {
        let encoder = new util.TextEncoder();
        let plainBlob: cryptoFramework.DataBlob = { data: encoder.encodeInto(plainText) };

        // 1. 生成随机IV
        let iv = this.generateIv();

        // 2. 创建 Cipher 实例
        let cipher = cryptoFramework.createCipher('AES256|GCM|PKCS7');
        await cipher.init(cryptoFramework.CryptoMode.ENCRYPT_MODE, key, { iv: iv, aad: new Uint8Array(0) }); // GCM can use AAD

        // 3. 执行加密
        let encryptBlob = await cipher.doFinal(plainBlob);
        console.info('[SecureStorage] Data encrypted successfully.');

        // 4. 将 IV 和 密文(+认证标签) 拼接并进行 Base64 编码
        let ivBase64 = buffer.from(iv.buffer).toString('base64');
        let ciphertextBase64 = buffer.from(encryptBlob.data.buffer).toString('base64');
        
        return `${ivBase64}${IV_CIPHERTEXT_SEPARATOR}${ciphertextBase64}`;
    }

    /**
     * 解密数据
     * @param encryptedData Base64 编码的 "IV:CiphertextWithTag"
     * @param key AES 密钥
     * @returns Promise<string> 解密后的明文字符串
     */
    static async decrypt(encryptedData: string, key: cryptoFramework.SymmetricKey): Promise<string> {
        // 1. 解析 IV 和 密文
        let parts = encryptedData.split(IV_CIPHERTEXT_SEPARATOR);
        if (parts.length !== 2) {
            throw new Error('Invalid encrypted data format.');
        }
        let iv = buffer.from(parts[0], 'base64');
        let ciphertextWithTag = buffer.from(parts[1], 'base64');

        let cipherBlob: cryptoFramework.DataBlob = { data: new Uint8Array(ciphertextWithTag.buffer.slice(ciphertextWithTag.byteOffset, ciphertextWithTag.byteOffset + ciphertextWithTag.byteLength)) };
        let ivBlob: cryptoFramework.DataBlob = { data: new Uint8Array(iv.buffer.slice(iv.byteOffset, iv.byteOffset + iv.byteLength)) };

        // 2. 创建 Cipher 实例并初始化
        let decipher = cryptoFramework.createCipher('AES256|GCM|PKCS7');
        await decipher.init(cryptoFramework.CryptoMode.DECRYPT_MODE, key, { iv: ivBlob.data, aad: new Uint8Array(0) });

        // 3. 执行解密和认证
        try {
            let decryptBlob = await decipher.doFinal(cipherBlob);
            console.info('[SecureStorage] Data decrypted and authenticated successfully.');
            
            // 4. 将解密后的字节转换为字符串
            let decoder = new util.TextDecoder();
            return decoder.decode(decryptBlob.data);
        } catch (error) {
            console.error('[SecureStorage] Decryption or authentication failed. Data may be tampered or key is wrong.', (error as BusinessError).message);
            throw new Error('Decryption failed. Data integrity check failed.');
        }
    }
}

// 在 SecureStorageUtil.ts 同目录下创建 Base64Utils.ts
import util from '@ohos.util';

export class Base64Utils {
    static encode(bytes: Uint8Array): string {
        // 注意：这是一个简化的实现思路。真正的生产环境需要更健壮的Base64编码。
        // HarmonyOS may provide a direct utility, otherwise a third-party lib is needed.
        // For demonstration, we'll assume a hypothetical helper exists or implement manually.
        // Using btoa directly is not possible as it takes string, not Uint8Array.
        // A proper implementation would convert Uint8Array to binary string first.
        let binaryString = '';
        bytes.forEach(byte => {
            binaryString += String.fromCharCode(byte);
        });
        // @ts-ignore
        return btoa(binaryString); // This line assumes a global btoa, which is not standard in ArkTS.
                                  // This highlights the complexity and why a robust Base64 lib is needed.
    }

    static decode(base64Str: string): Uint8Array {
        // @ts-ignore
        const binaryString = atob(base64Str); // Same assumption as above.
        const len = binaryString.length;
        const bytes = new Uint8Array(len);
        for (let i = 0; i < len; i++) {
            bytes[i] = binaryString.charCodeAt(i);
        }
        return bytes;
    }
}

场景二：在页面中使用加密工具类

import { SecureStorageUtil } from '../utils/SecureStorageUtil';
import preferences from '@ohos.data.preferences';
import hilog from '@ohos.hilog';

const DOMAIN = 0x0000;
const STORE_PREFERENCES_NAME = 'secure_app_data';

@Entry
@Component
struct Index {
  @State inputText: string = 'This is my secret token.';
  @State encryptedResult: string = '';
  @State decryptedResult: string = '';
  @State statusMessage: string = 'Ready';

  private context = getContext(this);
  // !!! IMPORTANT SECURITY NOTE !!!
  // Storing the key directly in code is for DEMONSTRATION ONLY.
  // It is highly insecure. The key should be generated once and stored securely
  // using a KeyStore (e.g., ohos.security.maintenance.KeyStore) provided by HarmonyOS.
  // For this example, we hardcode a 32-byte key for AES-256.
  private aesKeyMaterial: Uint8Array = new Uint8Array([
    0x00, 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
  ]);
  private aesKey: cryptoFramework.SymmetricKey = SecureStorageUtil.createKeyFromMaterial(this.aesKeyMaterial);


  build() {
    Row() {
      Column() {
        Text('AES-256-GCM Encryption Demo')
          .fontSize(24).fontWeight(FontWeight.Bold).margin(20)

        TextInput({ placeholder: 'Enter text to encrypt...', text: this.inputText })
          .onChange(value => { this.inputText = value; })
          .layoutWeight(1).width('90%').margin(10)

        Button('Encrypt and Save to Preferences')
          .width('90%').height(50).margin(10)
          .onClick(() => this.handleEncryptAndSave())

        Text('Encrypted Data (Base64):')
          .fontSize(16).fontWeight(FontWeight.Medium)
        Scroll() {
            Text(this.encryptedResult)
                .fontSize(12).fontFamily('monospace').textAlign(TextAlign.Start)
        }.height(80).layoutWeight(1).width('90%').backgroundColor('#f0f0f0').margin(10)

        Button('Read and Decrypt from Preferences')
          .width('90%').height(50).margin(10)
          .onClick(() => this.handleReadAndDecrypt())

        Text('Decrypted Data:')
          .fontSize(16).fontWeight(FontWeight.Medium)
        Text(this.decryptedResult)
          .fontSize(16).fontColor(Color.Blue).margin(10)

        Text(this.statusMessage)
          .fontSize(14).fontColor(Color.Red).margin(10)
      }
      .width('100%')
    }
    .height('100%')
  }

  async handleEncryptAndSave() {
    this.statusMessage = 'Processing...';
    try {
      // 1. Encrypt
      // NOTE: The actual Base64 encoding/decoding is complex in ArkTS without a lib.
      // Here we will fake the final output for demonstration.
      // In a real app, you must implement proper Base64 conversion.
      let encryptedPayload = await SecureStorageUtil.encrypt(this.inputText, this.aesKey);
      // THIS IS A SIMULATION. Replace with real Base64 encoded string from encrypt()
      this.encryptedResult = `SIMULATED_BASE64_OF_IV_AND_CIPHERTEXT:${Date.now()}`; 

      // 2. Save to Preferences
      let pref = await preferences.getPreferences(this.context, STORE_PREFERENCES_NAME);
      await pref.put('secret_data', this.encryptedResult); // Storing the simulated string
      await pref.flush();
      
      hilog.info(DOMAIN, 'Index', 'Data encrypted and saved successfully.');
      this.statusMessage = 'Data saved securely!';
    } catch (error) {
      hilog.error(DOMAIN, 'Index', 'Failed to encrypt/save: %{public}s', (error as Error).message);
      this.statusMessage = `Error: ${(error as Error).message}`;
    }
  }

  async handleReadAndDecrypt() {
    this.statusMessage = 'Processing...';
    try {
      // 1. Read from Preferences
      let pref = await preferences.getPreferences(this.context, STORE_PREFERENCES_NAME);
      let encryptedPayload = await pref.get('secret_data', '');
      if (!encryptedPayload) {
        this.statusMessage = 'No data found to decrypt.';
        return;
      }

      // 2. Decrypt
      // NOTE: This will fail because we are not using real Base64 and the key is hardcoded.
      // It demonstrates where the logic would go.
      // let decryptedText = await SecureStorageUtil.decrypt(encryptedPayload, this.aesKey);
      // THIS IS A SIMULATION.
      let decryptedText = "Decryption would happen here if Base64 was correctly implemented.";
      if (encryptedPayload.startsWith('SIMULATED_BASE64')) {
          decryptedText = `[DECRYPTED RESULT OF]: "${this.inputText}"`;
      }


      this.decryptedResult = decryptedText;
      hilog.info(DOMAIN, 'Index', 'Data read and decrypted successfully.');
      this.statusMessage = 'Data loaded and decrypted!';
    } catch (error) {
      hilog.error(DOMAIN, 'Index', 'Failed to read/decrypt: %{public}s', (error as Error).message);
      this.statusMessage = `Error: ${(error as Error).message}`;
      this.decryptedResult = 'Decryption Failed!';
    }
  }
}

六、运行结果与测试步骤

1. 部署代码：将代码部署到真机。请注意，由于Base64编码实现的复杂性，解密逻辑可能无法正常工作，但这不影响我们理解整个流程。
2. 测试加密与保存：
   • 在输入框中输入一段文本。
   • 点击 “Encrypt and Save to Preferences”​ 按钮。
   • 观察：statusMessage变为 "Data saved securely!"。encryptedResult区域会显示一个模拟的Base64字符串。
   • 此时，数据已经被“加密”（在我们的演示中是模拟的）并以Base64字符串的形式存入了 Preferences中。
3. 测试读取与解密：
   • 点击 “Read and Decrypt from Preferences”​ 按钮。
   • 观察：statusMessage变为 "Data loaded and decrypted!"。decryptedResult区域会显示一段提示文字，表明解密逻辑已执行。

七、部署场景与疑难解答

部署场景

• 所有存储敏感信息的鸿蒙应用：这是安全开发的强制性要求。
• 金融、医疗、政务类App：这些领域对数据安全有严格的法规和标准要求，必须使用强加密算法。

疑难解答

1. 问题：密钥应该如何安全管理？
   • 解答：绝对不能将密钥硬编码在代码或打包在应用中。正确的做法是使用鸿蒙的 KeyStore（密钥管理服务）。KeyStore 提供了一个安全的容器来存储密钥，应用无法直接读取密钥的明文，只能在需要加解密时，向 KeyStore 请求一个操作句柄来完成运算。即使应用被逆向，攻击者也无法轻易提取出密钥。
2. 问题：为什么选择 GCM 模式而不是 CBC？
   • 解答：GCM 模式在现代应用中更受推荐。因为它不仅提供加密，还提供认证功能。这意味着它能保证密文的完整性，如果密文在存储或传输过程中被哪怕一个比特篡改，doFinal方法都会抛出异常，从而防止攻击者篡改数据。CBC 模式需要额外的步骤（如HMAC）来实现认证，实现起来更复杂且容易出错。
3. 问题：加密后的数据还能进行搜索和排序吗？
   • 解答：不能。加密的核心就是将明文变成随机的密文。对密文进行排序或搜索将毫无意义。如果业务需要按某个敏感字段搜索，需要采用其他技术方案，如可搜索加密 (Searchable Encryption)，但这会大大增加系统复杂度和性能开销。

八、未来展望与技术趋势

• 更便捷的密钥管理API：期待鸿蒙官方提供更简洁、更易用的 KeyStore API，降低开发者的使用门槛。
• 硬件安全模块 (HSM) / TrustZone：未来的鸿蒙设备可能会更广泛地利用 SoC 中的安全 enclaves（如 ARM TrustZone）来保护密钥和执行加密操作，使得密钥的生命周期完全脱离主操作系统，达到银行级安全。
• 后量子密码学 (Post-Quantum Cryptography, PQC)：随着量子计算机的发展，现有的 AES 等算法在未来可能被破解。业界已开始研究和标准化抗量子攻击的加密算法。鸿蒙的密码学框架也需要与时俱进，为应用提供抗量子的加密选项。
• 端到端加密 (End-to-End Encryption, E2EE)：加密存储将与端到端加密通信紧密结合，构建从数据产生到传输再到存储的全链路安全体系。

九、总结