crypto-js 实现 AES 加解密：CBC/ECB 模式与 IV 配置详解

一、前置认知：AES 核心规范与 crypto-js 数据载体

AES 是一种对称分组加密算法，无论密钥长度是 128 位、192 位还是 256 位，其分组大小（Block Size）始终固定为 128 位（即 16 个字节）。这意味着待加密的明文数据在进入核心置换加密矩阵之前，必须被分割成若干个 16 字节的数据块；若最后一块不足 16 字节，则必须通过填充规则（如 PKCS#7）将其补齐至 16 字节。

在 JavaScript 中，原生字符串以 UTF-16 编码存储，而加密算法处理的是底层连续字节流。crypto-js 引入了 CryptoJS.lib.WordArray 对象作为字节流的核心容器。一个 WordArray 由一个 32 位无符号整数构成的 words 数组和一个标记实际有效字节数的 sigBytes 组成。

二、CBC 与 ECB 模式的原理解析与本质差异

分组密码算法不能直接加密任意长度的文本，必须依赖工作模式来协调多个分组的加密流程。在 crypto-js 中，最常用的两种模式是 CBC（Cipher Block Chaining）和 ECB（Electronic Codebook）。

1. ECB 模式（电子密码本模式）

ECB 是最原始的分组模式。该模式将明文分割为一个个 16 字节的独立块，每一个块使用相同的密钥独立进行 AES 加密，各块之间没有任何关联。因为没有链接机制，ECB 模式完全不需要 IV（初始向量）。

但 ECB 模式存在严重的结构缺陷：只要密钥不变，相同的明文分组加密后必然生成相同的密文分组。在加密结构化数据（如 JSON、XML 或位图）时，攻击者可以通过统计高频分组推断出原始数据的轮廓和特征，极易遭受模式泄露攻击与块重放篡改。因此，现代密码学规范严禁在生产环境中将 ECB 用于长文本加密。

2. CBC 模式（密码分组链接模式）

CBC 模式引入了链式反馈机制和 IV（Initialization Vector，初始向量）：

• 首块加密：第一个 16 字节的明文块先与 16 字节的 IV 执行异或（XOR）运算，异或后的结果再送入 AES 核心算法加密，得到第一个密文块。
• 后续块加密：从第二个明文块开始，每个明文块在送入 AES 加密前，必须先与前一个生成的密文块执行异或运算。

由于前一密文块参与了后一明文块的计算，哪怕文本中存在完全相同的明文段落，加密后生成的密文块也完全不同。只要每次加密时使用一个随机且不可预测的 IV，同一段明文多次加密的输出密文也会彻底随机化，从而有效抵御模式泄露和重放攻击。

三、使用 crypto-js 实现 CBC 模式加解密

CBC 模式是前后端接口交互中使用最广泛的 AES 模式。以下我们将通过具体代码，展示如何规范地完成密钥与 IV 的配置、明文加密以及密文的对称解密。

1. 依赖安装与导入

在 Node.js 或构建工具环境中使用 npm 安装：

npm install crypto-js

在代码中按需引入：

// CommonJS
const CryptoJS = require("crypto-js");

// 或 ES Module
import CryptoJS from "crypto-js";

2. CBC 模式加密实现与 IV 解析

以下是 CBC 模式的完整加密函数。注意我们对 Key 与 IV 均进行了严格的 CryptoJS.enc.Utf8.parse() 处理，确保其作为 16 字节原始数组输入：

/**
 * AES-128-CBC 加密示例
 * @param {string} plainText 待加密的明文字符串
 * @param {string} keyStr 16 字节密钥 (AES-128 需 16 字节，AES-256 需 32 字节)
 * @param {string} ivStr 16 字节初始向量 (CBC 模式必须严格等于 16 字节)
 * @returns {string} Base64 格式的密文字符串
 */
function encryptAES_CBC(plainText, keyStr, ivStr) {
  // 1. 将字符串显式解析为 WordArray
  const key = CryptoJS.enc.Utf8.parse(keyStr);
  const iv = CryptoJS.enc.Utf8.parse(ivStr);

  // 2. 配置加密选项
  const options = {
    iv: iv,
    mode: CryptoJS.mode.CBC,
    padding: CryptoJS.pad.Pkcs7
  };

  // 3. 执行加密
  const encrypted = CryptoJS.AES.encrypt(plainText, key, options);

  // 4. encrypted 是一个 CipherParams 对象，调用 toString() 默认输出 Base64 编码字符串
  return encrypted.toString();
}

// 执行调用示例
const rawKey = "1234567890abcdef"; // 16 字节 ASCII 字符串
const rawIV  = "abcdef1234567890"; // 16 字节 ASCII 字符串
const message = "Hello, crypto-js AES CBC!";

const cipherBase64 = encryptAES_CBC(message, rawKey, rawIV);
console.log("加密输出(Base64):", cipherBase64);

3. CBC 模式解密实现

解密时必须传入与加密完全一致的 Key、IV、模式与填充配置。解密结果返回的是 WordArray，必须使用 CryptoJS.enc.Utf8.toString() 将其解码为正常的字符串：

/**
 * AES-128-CBC 解密示例
 * @param {string} cipherBase64 Base64 编码的密文字符串
 * @param {string} keyStr 16 字节密钥
 * @param {string} ivStr 16 字节初始向量
 * @returns {string} 解密后的 UTF-8 明文字符串
 */
function decryptAES_CBC(cipherBase64, keyStr, ivStr) {
  const key = CryptoJS.enc.Utf8.parse(keyStr);
  const iv = CryptoJS.enc.Utf8.parse(ivStr);

  const options = {
    iv: iv,
    mode: CryptoJS.mode.CBC,
    padding: CryptoJS.pad.Pkcs7
  };

  // 解密输入可以直接传入 Base64 字符串
  const decrypted = CryptoJS.AES.decrypt(cipherBase64, key, options);

  // 将解密出的 WordArray 转为 UTF-8 字符串
  const plainText = decrypted.toString(CryptoJS.enc.Utf8);

  // 校验解密有效性
  if (!plainText) {
    throw new Error("解密失败：密文损坏或密钥/IV/填充不匹配");
  }

  return plainText;
}

// 验证解密
const decryptedText = decryptAES_CBC(cipherBase64, rawKey, rawIV);
console.log("解密还原明文:", decryptedText); // 输出: "Hello, crypto-js AES CBC!"

四、使用 crypto-js 实现 ECB 模式加解密

虽然 ECB 模式在安全性上不及 CBC，但在某些对接遗留银行系统、硬件加密狗或处理单块短 Token 的场景中，仍然需要使用 ECB 模式。

在 ECB 模式下，配置对象中无需传入 iv 字段。即使传入了 iv，crypto-js 的底层实现也会直接忽略该参数。

/**
 * AES-128-ECB 加密与解密示例
 */
function testAES_ECB() {
  const keyStr = "1234567890abcdef"; // 16 字节
  const key = CryptoJS.enc.Utf8.parse(keyStr);
  const message = "Secret Payload in ECB";

  // 1. ECB 加密配置 (无需 iv 属性)
  const encryptOptions = {
    mode: CryptoJS.mode.ECB,
    padding: CryptoJS.pad.Pkcs7
  };

  const encrypted = CryptoJS.AES.encrypt(message, key, encryptOptions);
  const cipherBase64 = encrypted.toString();
  console.log("ECB 密文:", cipherBase64);

  // 2. ECB 解密配置
  const decrypted = CryptoJS.AES.decrypt(cipherBase64, key, {
    mode: CryptoJS.mode.ECB,
    padding: CryptoJS.pad.Pkcs7
  });

  const originalText = decrypted.toString(CryptoJS.enc.Utf8);
  console.log("ECB 解密还原:", originalText);
}

testAES_ECB();

五、跨语言联调致命陷阱：String 密钥与 WordArray 密钥

许多初学者在实现 crypto-js 加密时，往往直接写出如下代码：

// ⚠️ 极其危险的做法：直接将普通字符串作为密钥传入
const badCipher = CryptoJS.AES.encrypt("hello", "my-secret-key");

在开发者看来，这似乎是非常直观的简写。但在 crypto-js 内部，这种调用方式会触发一个完全不同的工作分支：

1. 触发 OpenSSL 兼容 KDF：当第二个参数是普通 string 而非 WordArray 时，crypto-js 认为传入的是一个口令（Passphrase）。它会自动生成一个 8 字节的随机盐（Salt），然后调用 EVP_BytesToKey 算法派生出真正的 256 位密钥和 16 字节 IV。
2. 密文携带随机 Salt：导出的密文字符串会以 Salted__ 作为 Base64 编码的头部前缀。由于每次加密生成的 Salt 都是随机的，导致相同的明文使用相同的密钥，每次执行得到的密文都不一样。
3. 忽略显式 IV 配置：如果此时你在第三个参数中传入了 iv，该 iv 会被直接抛弃，系统依然采用由 Salt 派生出来的假 IV。
4. 跨语言联调全面瘫痪：当密文发送给 Java（使用标准 Cipher.getInstance("AES/CBC/PKCS5Padding")）、Go（使用 cipher.NewCBCDecrypter）或 Python（使用 cryptography 库）时，后端使用标准的 AES 密钥直接解密，无法识别这套由 OpenSSL 派生出来的 Salt 机制，导致解密报 BadPaddingException 或返回乱码。

六、生产级实践：IV 的生成与安全传递策略

在前面的示例中，为了方便演示，我们使用了硬编码的字符串作为 IV。但在真实的生产环境中，固定硬编码的 IV 违背了密码学安全原则。

在 CBC 模式中，IV 不需要保密（攻击者知道 IV 并不会降低 AES 算法本身的数学安全性），但IV 必须保证每次加密都具备唯一性与不可预测性。标准的工业级做法如下：

1. 前端生成随机 IV：使用 CryptoJS.lib.WordArray.random(16) 生成 16 字节的高强度随机数。
2. 拼装传输：将生成的 16 字节 IV 与后续密文拼接在一起传输（例如：IV(16字节) + Ciphertext(N字节)，或者作为独立的 JSON 字段 { iv: "...", data: "..." } 提交给服务端）。
3. 服务端提取解密：服务端收到报文后，先截取前 16 字节作为 IV，再使用协商好的对称 Key 对剩余的密文块执行 CBC 解密。

/**
 * 生产推荐：随机生成 IV 并将其拼接在密文头部
 */
function encryptWithRandomIV(message, keyStr) {
  const key = CryptoJS.enc.Utf8.parse(keyStr);

  // 1. 生成 16 字节安全随机 IV (WordArray)
  const iv = CryptoJS.lib.WordArray.random(16);

  // 2. 加密
  const encrypted = CryptoJS.AES.encrypt(message, key, {
    iv: iv,
    mode: CryptoJS.mode.CBC,
    padding: CryptoJS.pad.Pkcs7
  });

  // 3. 将 IV 与密文拼接（均转为 Hex 十六进制字符串）
  const ivHex = iv.toString(CryptoJS.enc.Hex);
  const cipherHex = encrypted.ciphertext.toString(CryptoJS.enc.Hex);

  // 拼接格式：前 32 个十六进制字符为 IV，后续为真实密文
  return ivHex + cipherHex;
}

function decryptWithEmbeddedIV(combinedHex, keyStr) {
  const key = CryptoJS.enc.Utf8.parse(keyStr);

  // 1. 拆分提取 IV (前 32 字符 = 16 字节)
  const ivHex = combinedHex.substring(0, 32);
  const cipherHex = combinedHex.substring(32);

  const iv = CryptoJS.enc.Hex.parse(ivHex);
  const cipherBytes = CryptoJS.enc.Hex.parse(cipherHex);
  const cipherBase64 = cipherBytes.toString(CryptoJS.enc.Base64);

  // 2. 执行 CBC 解密
  const decrypted = CryptoJS.AES.decrypt(cipherBase64, key, {
    iv: iv,
    mode: CryptoJS.mode.CBC,
    padding: CryptoJS.pad.Pkcs7
  });

  return decrypted.toString(CryptoJS.enc.Utf8);
}

七、模式选择决策与配置速查

为了帮助开发者在实际业务中快速确定模式、排查参数问题，下表给出了 CBC 与 ECB 模式的核心特性速查矩阵：