ZOLOZZOLOZDOCS

报文加密和报文解密

ZOLOZ网关协议能够实现报文加密，保证数据在传输过程中不被篡改。如果商户发送了加密请求，ZOLOZ服务会返回加密响应；如果商户发送了未加密请求，ZOLOZ服务会返回未加密响应。

由于ZOLOZ服务处理的数据可能包含敏感信息，为加强报文传输安全性，ZOLOZ服务会对响应报文进行加密。敏感信息包括所有敏感的个人身份信息，例如姓名、身份证号码、生日、地址、人脸等。

报文加密

报文加密流程

下图展示了从商户角度如何进行请求报文加密，以及从ZOLOZ服务角度如何进行响应报文加密。

image.png

图1. 报文加密活动图

报文加密步骤

1. 获取公钥

  • 对于请求报文，在创建商户账号时ZOLOZ系统会生成一个RSA 2048密钥对。每个商户的密钥对都是唯一的，且包含一个公钥。商户需提前获取公钥。
  • 对于响应报文，商户端必须生成一个RSA 2048密钥对。生成的密钥对包含一个公钥，您必须在ZOLOZ系统中成功注册公钥后才能发送请求。ZOLOZ服务可以使用已注册的公钥对后续的响应报文进行加密。

2. 准备待加密内容

待加密内容是业务请求或业务响应相关的明文报文，通常为JSON字符串格式。

3. 生成AES对称密钥

AES对称密钥是随机生成的一个256位数据。

4. 加密内容

内容加密公式：

copy
ENCYRPTED_CONTENT_STRING=base64urlsafe_encode(aes_encrypt($CONTENT_TO_BE_ENCRYPTED, $AES_KEY))

内容加密公式由以下几部分组成：

  • 依赖的函数
    • aes_encrypt：使用AES算法对报文进行加密。更多信息，请参见aes_encrypt。
    • base64urlsafe_encode：该函数用于对加密数据进行编码。更多信息，请参见base64urlsafe_encode。
  • 输入参数
    • CONTENT_TO_BE_ENCRYPTED：步骤2中准备的待加密内容字符串。
    • AES_KEY：步骤3中生成的AES对称密钥。
  • 输出参数
    • ENCYRPTED_CONTENT_STRING：加密内容字符串。

5. 加密AES密钥

AES密钥加密公式：

copy
ENCYRPTED_AES_KEY=base64urlsafe_encode(rsa_encrypt($AES_KEY, $PUBLIC_KEY))

AES密钥加密公式由以下几部分组成：

  • 依赖的函数
    • rsa_encrypt：该函数用于加密AES密钥。更多信息，请参见rsa_encrypt。
    • base64urlsafe_encode：该函数用于对加密数据进行编码。更多信息，请参见base64urlsafe_encode。
  • 输入参数
    • AES_KEY：步骤3中生成的AES对称密钥。
    • PUBLIC_KEY：步骤1中获取的公钥。
  • 输出参数
    • ENCYRPTED_AES_KEY：加密AES密钥字符串。

6. 配置header和body

    1. 配置Encrypt头。
      在HTTP头的Encrypt字段中指定加密的AES密钥。格式如下：
copy
Encrypt: algorithm=RSA_AES, symmetricKey=<ENCYRPTED_AES_KEY>
    1. 配置Content-Type头，将内容格式设置为text/plain。
copy
content-type: text/plain
    1. 配置HTTP正文。
      将加密内容字符串设置为HTTP的正文，加密内容字符串是从步骤4中获取的ENCYRPTED_CONTENT_STRING。

报文解密

报文解密流程

下图展示了从ZOLOZ服务角度如何进行请求报文解密，以及从商户角度如何进行响应报文解密。

消息解密活动图.png

图2. 报文解密活动图

报文解密步骤

1. 获取私钥

  • 对于请求报文，在创建商户账号时ZOLOZ系统会生成一个RSA 2048密钥对。每个商户的密钥对都是唯一的，且包含一个私钥。ZOLOZ服务可以使用该私钥解密包含在加密请求中的对称密钥。
  • 对于响应报文，商户端必须生成一个RSA 2048密钥对。生成的密钥对包含一个私钥，商户可以使用该私钥解密包含在加密响应中的对称密钥。

2. 获取待解密内容

待解密的内容为整个已加密的HTTP body。

3. 提取加密AES对称密钥

在HTTP请求头或HTTP响应头的Encrypt字段中提取加密的AES对称密钥。

Encrypt: algorithm=RSA_AES, symmetricKey=<AES_KEY_TO_BE_EXTRACTED>

4. 解密AES密钥

AES密钥解密公式：

copy
AES_KEY=rsa_decrypt(base64urlsafe_decode($ENCRYPTED_AES_KEY), $PRIVATE_KEY)

AES密钥解密公式由以下几部分组成：

  • 依赖的函数
    • base64urlsafe_decode：该函数用于解码加密数据。更多信息，请参见base64urlsafe_decode。
    • rsa_decrypt：该函数用于解密密文。更多信息，请参见rsa_decrypt。
  • 输入参数
    • ENCRYPTED_AES_KEY：从步骤3中提取的加密AES密钥。
    • PRIVATE_KEY：从步骤1中获取的私钥。
  • 输出参数
    • AES_KEY：加密报文内容时随机生成的初始AES密钥。

5. 解密内容

内容解密公式：

copy
PLAIN_CONTENT_STRING=utf8_encode(aes_decrypt(base64urlsafe_decode($Content_To_Be_Decrypted, $AES_KEY))

内容解密公式由以下几部分组成：

  • 依赖的函数
    • base64urlsafe_decode：该函数用于解码加密数据。更多信息，请参见base64urlsafe_decode。
    • aes_decrypt：该函数用于解密密文。更多信息，请参见aes_decrypt。
    • utf8_encode：该函数用于将二进制数据编码为UTF-8格式的文本字符串。更多信息，请参见utf8_encode。
  • 输入参数
    • Content_To_Be_Decrypted：从步骤2中获取的待解密内容。
    • AES_KEY：从步骤4中获取的AES对称密钥。
  • 输出参数
    • PLAIN_CONTENT_STRING：待使用的明文内容字符串，通常为JSON字符串格式。