单条短信AES加密发送接口文档

1 接口基础信息

2 完整加密流程规范

2.1 单次字段加密步骤（手机号/内容分别执行）

1. 生成随机IV

   算法AES-128-CBC固定IV长度16字节，使用密码安全随机函数生成16字节原始IV二进制串。

2. AES加密明文
   • 模式：AES-128-CBC
   • 填充：OpenSSL默认PKCS7填充
   • 参数：密钥=客服提供key，iv=步骤1生成二进制iv，输出原始密文字符串
3. Base64编码密文

   将AES加密后的原始密文做Base64编码，记为s1（value值）

4. Base64编码IV

   将二进制原始IV做Base64编码，记为s2（iv值）

5. 组装内层JSON

   构造JSON对象，禁止转义斜杠，格式：

   {"iv":"s2","value":"s1"}
   

6. 外层Base64编码

   将上述JSON字符串整体Base64编码，最终得到该字段加密后的最终字符串，替换原明文传入POST参数。

3 PHP标准加密代码

/**
 * AES-128-CBC 字段加密封装方法
 * @param string $key 客服分配16位加密密钥
 * @param string $value 待加密明文（手机号/短信内容）
 * @return string 加密完成外层base64字符串
 */
function aes_encrypt_field(string $key, string $value): string
{
    $cipher = 'AES-128-CBC';
    // 生成16字节随机IV
    $ivRaw = random_bytes(openssl_cipher_iv_length($cipher));
    // AES加密，0=不返回原始二进制，直接base64密文
    $encryptValue = openssl_encrypt($value, $cipher, $key, 0, $ivRaw);
    if ($encryptValue === false) {
        throw new RuntimeException('数据AES加密失败');
    }
    // IV base64编码
    $ivBase64 = base64_encode($ivRaw);
    // 组装内层JSON，禁止转义斜杠
    $jsonData = json_encode([
        'iv' => $ivBase64,
        'value' => $encryptValue
    ], JSON_UNESCAPED_SLASHES);
    if (json_last_error() !== JSON_ERROR_NONE) {
        throw new RuntimeException('加密JSON组装失败');
    }
    // 外层整体base64返回
    return base64_encode($jsonData);
}

4 调用示例

$key = '客服下发16位密钥';
$mobile = '13800138000';
$content = '您的验证码：123456';

// 手机号单独加密
$encryptMobile = aes_encrypt_field($key, $mobile);
// 短信内容单独加密
$encryptContent = aes_encrypt_field($key, $content);

// POST请求参数中mobile、content传加密后字符串
$postData = [
    'mobile' => $encryptMobile,
    'content' => $encryptContent,
    // 其他业务参数...
];

5 请求参数说明

说明：mobile、content 必须使用上文加密方法处理后的Base64字符串，不可传明文；其余业务参数按原有未加密接口规则不变。

6 加解密关键约束

• 密钥长度：必须16位字符，适配AES-128，密钥由客服统一分配，不可自定义；
• IV要求：每次加密手机号、每次加密内容都需重新生成全新随机IV，不可复用IV；
• 加密隔离：手机号、短信内容为两个独立字段，分开两次完整加密流程，不能合并加密；
• 编码标准：全程使用标准Base64（不做URL安全替换）；
• JSON规则：内层JSON必须携带JSON_UNESCAPED_SLASHES，避免斜杠转义导致解密失败；
• 加密模式：固定CBC模式，禁止ECB、CFB等其他模式。

7 常见错误排查

• 解密失败：IV复用、密钥位数错误、JSON斜杠转义、Base64编码异常；
• openssl加密返回false：密钥长度非16位、环境未开启openssl扩展；
• 接口返回参数非法：手机号/内容只加密其中一个字段，未分开独立加密；
• 明文过长报错：加密无长度限制，若报错检查内层JSON是否格式损坏。

8 其他语言开发提示

Java/Go/Python/JS 统一实现要点

• IV固定16字节随机字节数组；
• AES-128-CBC，PKCS7填充；
• openssl_encrypt 第4参数为0 = 输出Base64密文；
• IV二进制转Base64，和密文共同封装JSON；
• JSON字符串整体再一次Base64作为最终入参；
• 两个业务字段分开加密，两套独立IV、两套独立加密结果。