为了保障数据传输的安全性，Payzilla OpenAPI 接口采用 RSA (非对称加密) + AES (对称加密) 的混合加密方案，并对请求进行时间戳校验以防止重放攻击。

[!info] 核心原理该方案利用 RSA 的非对称特性进行密钥交换，利用 AES 的高效性能进行大数据量加密。

1. 安全规范

字符编码：所有报文字符串必须使用 UTF-8 编码。
时间戳校验：请求参数中的 timestamp 与系统时间偏差不得超过 5分钟。
签名算法：使用 SHA256WithRSA 算法。

[!warning] 重要提示请确保服务器时间已同步 (NTP)，否则由于时间偏移可能导致请求被拦截。

2. 请求报文解密流程 (商户发送请求)

商户在调用外部接口时，需提交如下结构的 JSON 报文：

{
  "timestamp": "1710300000000",
  "data": "密文数据...",
  "key": "加密后的对称密钥...",
  "sign": "数字签名..."
}

步骤明细：

准备数据：将业务请求明文 JSON 序列化。
生成 AES 密文：生成一个随机的 AES 密钥，对业务明文进行加密得到 data。
对密钥加密：使用 Payzilla 提供的平台公钥 对上述 AES 密钥进行加密得到 key。
生成签名：对 data + key + timestamp 按字典序排序后拼接，使用 商户私钥 进行签名得到 sign。

3. 响应报文加密流程 (商户接收响应)

Payzilla 返回的加密响应结构如下：

{
  "code": 0,
  "message": "Operation successful",
  "timestamp": "1710300005000",
  "data": "密文响应数据...",
  "key": "加密后的对称密钥...",
  "sign": "数字签名..."
}

步骤明细：

验签：商户接收到响应后，需使用 Payzilla 平台公钥 对 data + key + timestamp 进行验签。
解密密钥：验证通过后，使用 商户私钥 对 key 字段进行解密，获取原始 AES 密钥。
解密数据：使用该 AES 密钥对 data 密文进行解密，得到最终的业务 JSON 数据。

4. 常见问题

验签失败：请检查待签名字符串的拼接顺序及是否包含空格。
解密失败：请确认公私钥配对是否正确，以及 AES 变换算法是否一致。

5. 加密签名示例

5.1 请求加密与签名流程

生成AES密钥

const crypto = require('crypto');

/**
 * 生成 256 位 AES 密钥（32 字节）
 * @returns {Buffer} AES 密钥
 */
function generateAESKey() {
    return crypto.randomBytes(32); // 256 位 = 32 字节
}

/**
 * 生成 128 位 IV（初始化向量，16 字节）
 * @returns {Buffer} IV
 */
function generateIvKey() {
    return crypto.randomBytes(16); // 通常 AES-CBC/GCM 模式下 IV 长度为 16 字节
}

使用AES加密请求参数

const crypto = require('crypto');

/**
 * 使用 AES-256-GCM 模式加密内容
 * @param {string} content - 要加密的明文内容
 * @param {Buffer} aesKey - 32 字节 AES 密钥
 * @param {Buffer} iv - 16 字节的初始化向量（IV）
 * @returns {string} Base64 编码的加密字符串（密文 + auth tag）
 */
function encrypt(content, aesKey, iv) {
    const cipher = crypto.createCipheriv('aes-256-gcm', aesKey, iv);

    const encrypted = Buffer.concat([
        cipher.update(content, 'utf8'),
        cipher.final()
    ]);

    const authTag = cipher.getAuthTag();

    // 输出格式为：密文 + AuthTag
    const combined = Buffer.concat([encrypted, authTag]);

    return combined.toString('base64');
}

加密 AES Key + IV

const crypto = require('crypto');

/**
 * RSA-OAEP 加密
 * @param {Buffer} plainBytes - 明文（AES 密钥 + IV）
 * @param {string} publicKeyPem - PEM 格式的 RSA 公钥（4096位）---- 平台公钥
 * @returns {string} Base64 编码的密文
 */
function encryptRsaOaep(plainBytes, publicKeyPem) {
    const encrypted = crypto.publicEncrypt(
        {
            key: publicKeyPem,
            padding: crypto.constants.RSA_PKCS1_OAEP_PADDING,
            oaepHash: 'sha256'
        },
        plainBytes
    );
    return encrypted.toString('base64');
}

/**
 * 拼接 AES 密钥和 IV，并使用 RSA 公钥加密
 * @param {Buffer} aesKey - 32 字节 AES 密钥
 * @param {Buffer} iv - 16 字节 IV
 * @param {string} publicKeyPem - RSA 公钥 PEM 字符串
 * @returns {string} Base64 编码加密结果
 */
function encryptAesKey(aesKey, iv, publicKeyPem) {
    const combined = Buffer.concat([aesKey, iv]); // 共 48 字节
    return encryptRsaOaep(combined, publicKeyPem);
}

生成签名

const crypto = require('crypto');

/**
 * 用 SHA256WithRSA 签名字符串
 * @param {string} content - 需要签名的内容---序列化后的参数：appKey=...&data=...&key=...&timestamp=...
 * @param {string} privateKeyPem - PEM 格式 RSA 私钥----应用私钥
 * @returns {string} Base64 编码签名结果
 */
function sign(content, privateKeyPem) {
    const sign = crypto.createSign('RSA-SHA256');
    sign.update(content, 'utf8');
    sign.end();

    const signature = sign.sign(privateKeyPem);
    return signature.toString('base64');
}

5.2 响应解密与验签流程

验签

const crypto = require('crypto');

/**
 * 使用 RSA 公钥验证签名（SHA256withRSA）
 * @param {string} content - 原始内容---序列化后的参数：data=...&key=...&timestamp=..
 * @param {string} signatureBase64 - Base64 编码签名---响应里的sign
 * @param {string} publicKeyPem - PEM 格式公钥---应用公钥
 * @returns {boolean} 是否验签成功
 */
function verifySignature(content, signatureBase64, publicKeyPem) {
    const verifier = crypto.createVerify('RSA-SHA256');
    verifier.update(content, 'utf8');
    verifier.end();

    const signature = Buffer.from(signatureBase64, 'base64');
    return verifier.verify(publicKeyPem, signature);
}

解密获取 AES Key + IV

const crypto = require('crypto');

/**
 * 使用 RSA 私钥和 OAEP(SHA-256) 算法解密数据（分段）
 * @param {string} base64Encrypted - Base64 编码的密文---响应里的key
 * @param {string} privateKeyPem - PEM 格式私钥---应用私钥
 * @returns {Buffer} 解密后的明文---拼接后的 AES Key + IV，按32、16字节分别截取获取key和iv
 */
function decryptRSA_OAEP(base64Encrypted, privateKeyPem) {
    const encryptedBuffer = Buffer.from(base64Encrypted, 'base64');

    const maxBlockSize = 512;
    const chunks = [];
    for (let offset = 0; offset < encryptedBuffer.length; offset += maxBlockSize) {
        const chunk = encryptedBuffer.slice(offset, offset + maxBlockSize);
        const decrypted = crypto.privateDecrypt(
            {
                key: privateKeyPem,
                padding: crypto.constants.RSA_PKCS1_OAEP_PADDING,
                oaepHash: 'sha256'
            },
            chunk
        );
        chunks.push(decrypted);
    }

    return Buffer.concat(chunks);
}

解密业务数据

const crypto = require('crypto');

/**
 * 使用 AES-GCM 解密
 * @param {string} base64Ciphertext - Base64 编码的密文---响应里的data
 * @param {Buffer} aesKey - 256 位 AES 密钥，长度为 32 字节---上一步获取
 * @param {Buffer} iv - 初始化向量（IV），长度为16 字节---上一步获取
 * @returns {string} 解密后的明文字符串---实际响应内容JSON
 */
function decryptAesGcm(base64Ciphertext, aesKey, iv) {
    const encryptedData = Buffer.from(base64Ciphertext, 'base64');

    // 提取 GCM 的 tag
    const tagLength = 16; // GCM 的默认 tag 长度为 16 字节
    const ciphertext = encryptedData.slice(0, -tagLength);
    const authTag = encryptedData.slice(-tagLength);

    const decipher = crypto.createDecipheriv('aes-256-gcm', aesKey, iv);
    decipher.setAuthTag(authTag);

    const decrypted = Buffer.concat([
        decipher.update(ciphertext),
        decipher.final()
    ]);

    return decrypted.toString('utf8');
}

5.3 完整调用示例

const crypto = require('crypto');

// 假设这是您的配置
const config = {
    // 平台公钥（Payzilla 提供）
    platformPublicKey: `-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA...
-----END PUBLIC KEY-----`,
    // 应用私钥（您自己生成）
    appPrivateKey: `-----BEGIN PRIVATE KEY-----
MIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwggSjAgEAAoIBAQDH...
-----END PRIVATE KEY-----`,
    // 您的 appKey
    appKey: 'your_app_key_here'
};

/**
 * 完整请求加密流程
 * @param {Object} businessData - 业务请求数据
 * @returns {Object} 加密后的请求参数
 */
function buildEncryptedRequest(businessData) {
    // 1. 生成 AES 密钥和 IV
    const aesKey = generateAESKey();
    const iv = generateIvKey();

    // 2. 序列化业务数据
    const jsonData = JSON.stringify(businessData);

    // 3. 使用 AES-GCM 加密业务数据
    const encryptedData = encrypt(jsonData, aesKey, iv);

    // 4. 使用平台公钥加密 AES 密钥和 IV
    const encryptedKey = encryptAesKey(aesKey, iv, config.platformPublicKey);

    // 5. 生成时间戳
    const timestamp = Date.now().toString();

    // 6. 生成待签名内容（按字典序排序）
    // 注意：签名内容不含 appKey，只含 data、key、timestamp
    const signContent = `data=${encryptedData}&key=${encryptedKey}&timestamp=${timestamp}`;

    // 7. 使用应用私钥签名
    const signature = sign(signContent, config.appPrivateKey);

    // 8. 返回最终请求参数
    return {
        appKey: config.appKey,
        timestamp: timestamp,
        data: encryptedData,
        key: encryptedKey,
        sign: signature
    };
}

/**
 * 完整响应解密流程
 * @param {Object} response - Payzilla 返回的加密响应
 * @returns {Object} 解密后的业务数据
 */
function decryptResponse(response) {
    // 1. 构造待验签内容
    const signContent = `data=${response.data}&key=${response.key}&timestamp=${response.timestamp}`;

    // 2. 使用平台公钥验签
    // 注意：实际应使用应用公钥验签，此处需根据业务配置选择
    const isValid = verifySignature(signContent, response.sign, config.platformPublicKey);

    if (!isValid) {
        throw new Error('签名验证失败');
    }

    // 3. 使用应用私钥解密获取 AES 密钥和 IV
    const decryptedKey = decryptRSA_OAEP(response.key, config.appPrivateKey);

    // 4. 分离 AES 密钥和 IV
    const aesKey = decryptedKey.slice(0, 32);
    const iv = decryptedKey.slice(32, 48);

    // 5. 使用 AES-GCM 解密业务数据
    const businessData = decryptAesGcm(response.data, aesKey, iv);

    return JSON.parse(businessData);
}

[!callout] 💡 提示 ReadMe 支持在导出 OpenAPI 时自动嵌入该指南，您可以将其关联到首页的说明栏中。

加密与签名规范

为了保障数据传输的安全性，Payzilla OpenAPI 接口采用 RSA (非对称加密) + AES (对称加密) 的混合加密方案，并对请求进行时间戳校验以防止重放攻击。

对称加密算法：AES
非对称加密/签名算法：RSA

公共参数描述

请求参数

Header

参数名	类型	描述
appKey	string	平台分配应用唯一标识

Body

参数名	类型	描述
data	string	业务请求参数 AES 加密后数据
timestamp	string	请求时间戳，UNIX 毫秒格式字符串
key	string	使用系统 RSA 公钥对随机 AES Key 加密后的数据
sign	string	使用您的应用 RSA 私钥对请求参数签名得到的签名数据

返回参数

Body

参数名	类型	描述
code	int	响应结果码
message	string	响应结果描述
data	string	加密业务数据
timestamp	string	响应时间戳，UNIX 毫秒格式字符串
key	string	使用您的 API RSA 公钥对随机 AES Key 加密后的数据
sign	string	平台使用私钥对响应参数签名得到的签名数据

请求加密与签名流程（客户端 → Savo Open）

客户端（您的系统）在发起 API 请求时，按照以下步骤执行加密与签名：

1. 序列化业务数据

将请求业务参数序列化为 JSON 字符串

2. 生成加密参数

随机生成 32 字节的 AES 密钥（Key）
随机生成 16 字节的初始化向量（IV）

3. 加密业务数据

使用算法：AES/GCM/NoPadding
使用生成的 AES 密钥 Key + IV 加密请求参数 JSON 字符串
加密结果进行 Base64 编码，作为参数 data 传输

4. 加密 AES Key + IV

将 AES Key 与 IV 合并为 48 字节
使用Savo Open平台 RSA 公钥进行加密
加密算法：RSA/ECB/OAEPWithSHA-256AndMGF1Padding
加密结果 Base64 编码，作为参数 key 传输

5. 生成签名字符串

将所有参数按参数名升序排序
序列化为字符串格式，例如：appKey=...&data=...&key=...&timestamp=...

6. 签名

使用您的应用RSA私钥对序列化后对字符串进行签名
签名算法：SHA256WithRSA
签名结果 Base64 编码，作为参数 sign 传输

响应解密与验签流程（Savo Open → 客户端）

平台返回响应后，您可以按照以下流程进行解密与验签：

1. 构造验签字符串

将响应字段按字典序排序
序列化为字符串，例如：data=...&key=...&timestamp=...

2. 验签

使用 Savo Open平台提供的 RSA 公钥
验证签名字段 sign 是否匹配
签名算法：SHA256WithRSA

3. 解密 AES Key + IV

使用您的应用 RSA 私钥解密响应参数 key
算法：RSA/ECB/OAEPWithSHA-256AndMGF1Padding
获取 32 字节 AES Key + 16 字节 IV

4. 解密业务数据

使用 AES Key 和 IV 解密 data
算法：AES/GCM/NoPadding，还原业务 JSON 数据

加密签名示例

请求加密与签名流程