NJS 中 Crypto 模块实战教程：Hash 与 HMAC 加密详解

一、前置知识：NJS Crypto 模块基础

1.1 模块引入

NJS 从 0.7.0 版本开始，将 crypto 作为全局对象提供（无需额外安装依赖），也可通过 import 显式引入，两种方式均可：

// 方式1：全局对象直接使用（推荐，NJS 0.7.0+）
const hash = crypto.createHash('sha1');

// 方式2：显式导入（兼容写法）
import crypto from 'crypto';
const hmac = crypto.createHmac('sha1', 'my-secret-key');

1.2 核心概念区分

二、Hash 算法：无密钥的单向加密

2.1 核心 API 说明

crypto.createHash(algorithm) 是创建 Hash 对象的入口，核心参数和方法如下：

• algorithm：哈希算法，支持 md5、sha1、sha256（NJS 内置，无需额外配置）；
• hash.update(data)：追加待加密的字符串/数据（可多次调用，数据会拼接）；
• hash.digest([encoding])：计算最终哈希值，支持 hex、base64、base64url 编码，无编码参数时返回 Buffer 对象。

2.2 基础使用示例

示例1：单次输入计算 SHA1 哈希（Base64URL 编码）

import crypto from 'crypto';

// 1. 创建 SHA1 Hash 对象
const hash = crypto.createHash('sha1');
// 2. 传入待加密数据
hash.update('A');
// 3. 计算并输出 Base64URL 编码的哈希值
const result = hash.digest('base64url');
console.log(result); // 输出：BtlFlCqiamG-GMPiK_GbvKjdK10

示例2：多次输入拼接计算哈希

update() 可多次调用，数据会按调用顺序拼接，效果等同于单次传入拼接后的字符串：

const hash = crypto.createHash('sha1');
// 多次 update 等价于 update('AB')
hash.update('A').update('B'); 
const result = hash.digest('base64url');
console.log(result); // 输出：BtlFlCqiamG-GMPiK_GbvKjdK10（与单次传入'AB'结果一致）

示例3：不同编码输出对比

const hash = crypto.createHash('md5').update('test');
console.log(hash.digest('hex'));    // 16进制：098f6bcd4621d373cade4e832627b4f6
console.log(hash.digest('base64')); // Base64：CJ7gi1p+z8UYhhyw2bbQhg==
// 注意：digest() 只能调用一次，再次调用会报错，需重新创建 Hash 对象

2.3 NJS 中 Hash 实战：NGINX 响应头添加数据指纹

在 NGINX 配置中，可通过 NJS 计算响应体的 Hash 值并添加到响应头，用于客户端校验数据完整性：

# nginx.conf 配置
http {
    js_import crypto.js; # 导入 NJS 脚本
    
    server {
        listen 80;
        location / {
            # 响应体过滤，计算 Hash 并添加响应头
            js_filter crypto.addHashHeader;
            return 200 "Hello NJS Crypto";
        }
    }
}

# crypto.js 脚本
function addHashHeader(r) {
    const data = r.responseBody; // 获取响应体
    // 计算 SHA256 哈希（Hex 编码）
    const hash = crypto.createHash('sha256').update(data).digest('hex');
    // 添加到响应头
    r.headersOut['X-Data-Hash'] = hash;
}

三、HMAC 算法：带密钥的安全认证

3.1 核心 API 说明

crypto.createHmac(algorithm, secretKey) 是创建 HMAC 对象的入口，相比 Hash 多了密钥参数，核心规则：

• secretKey：自定义密钥（字符串），是 HMAC 安全的核心，丢失密钥无法验证/破解；
• hmac.update(data)/hmac.digest(encoding)：用法与 Hash 完全一致；
• 相同输入+不同密钥 → 完全不同的输出（核心优势）。

3.2 基础使用示例

示例1：基础 HMAC 计算（SHA1 + Base64URL）

import crypto from 'crypto';

// 1. 创建 HMAC 对象（算法+密钥）
const hmac = crypto.createHmac('sha1', 'secret.key');
// 2. 传入待加密数据
hmac.update('AB');
// 3. 计算 Base64URL 编码的结果
const result = hmac.digest('base64url');
console.log(result); // 输出：Oglm93xn23_MkiaEq_e9u8zk374

示例2：密钥的重要性（对比测试）

// 密钥1：secret.key
const hmac1 = crypto.createHmac('sha1', 'secret.key').update('AB').digest('hex');
// 密钥2：secret.key1（仅多1个字符）
const hmac2 = crypto.createHmac('sha1', 'secret.key1').update('AB').digest('hex');

console.log(hmac1); // 5e0659fddf19f777f3922684a7f7bdbbcec937ee
console.log(hmac2); // 7a8d9c8b7e6f5a4d3b2a1f0e9d8c7b6a5f4e3d2c1b0a9f8e7d6c5b4a3f2e1d0c
// 结果完全不同，体现密钥的唯一性

3.3 NJS 中 HMAC 实战：API 请求签名验证

在 NGINX 中拦截 API 请求，通过 HMAC 验证请求签名是否合法（防止篡改/伪造请求）：

# nginx.conf 配置
http {
    js_import crypto.js;
    server {
        listen 80;
        location /api {
            # 前置校验签名
            js_access crypto.verifyHmacSign;
            proxy_pass http://backend;
        }
    }
}

# crypto.js 脚本
function verifyHmacSign(r) {
    // 1. 获取请求参数：客户端传的签名 + 请求体
    const clientSign = r.headersIn['X-API-Sign'];
    const requestData = r.requestBody;
    // 2. 服务端密钥（与客户端约定）
    const secretKey = 'my-api-secret-2025';
    // 3. 计算服务端签名
    const serverSign = crypto.createHmac('sha256', secretKey)
                             .update(requestData)
                             .digest('base64url');
    // 4. 验证签名
    if (clientSign !== serverSign) {
        r.return(403, 'Invalid sign'); // 签名不匹配，拒绝请求
    }
}

四、注意事项与最佳实践

4.1 版本兼容

• NJS 0.7.0+：crypto 为全局对象，hash.copy() 从 0.7.12 开始支持；
• NJS 0.4.4+：digest() 无编码参数时返回 Buffer，0.4.4 之前返回字节字符串（建议升级到 0.7.0+）。

4.2 性能与安全建议

1. 算法选择：避免使用 md5/sha1（安全性低），优先选择 sha256；
2. 密钥管理：HMAC 密钥避免硬编码在 NJS 脚本中，可通过 NGINX 变量/配置文件注入；
3. 数据量：NJS 适合轻量数据加密（如请求参数、短字符串），大文件加密建议在后端处理。

4.3 常见错误

• digest() called twice：digest() 调用后 Hash/HMAC 对象会销毁，需重新创建对象才能再次计算；
• algorithm not supported：仅支持 md5/sha1/sha256，勿使用其他算法（如 sha512）。

五、总结

1. NJS 的 crypto 模块无需额外依赖，createHash() 适用于无密钥的单向哈希，createHmac() 基于密钥更适合安全认证；
2. update() 可多次拼接数据，digest() 是最终计算入口，支持 hex/base64/base64url 三种编码；
3. 实战中 Hash 用于数据完整性校验，HMAC 用于 API 签名等安全场景，结合 NGINX 配置可实现轻量化加密需求。