# FinAuth 海外接口统一加密说明文档

# 1 加密说明

# 1.1 加密方案概述

为保护用户敏感信息不被泄露，在调用 verify、liveness、compare 海外接口时，FinAuth 会对接口入参、返回值中包含的用户字符串信息、图片数据进行加密处理。海外环境仅支持 RSA 加密，不支持国密 SM2 加密。整体加密分为「入参加密」和「返回值加密」两套规则。

# a. 接口传入参数加密

加密方法
由原力金智生成密钥对，并在控制台对外提供公钥；应用方调用接口时使用 FinAuth 公钥对请求参数加密，原力金智服务端使用私钥完成解密。

加密内容

接口	加密参数	说明
verify	image	用户传入的自有照片
verify	image_ref	由应用方提供的参照人脸照片
liveness	image	用户传入的自有照片
compare	image	用户传入的自有照片
compare	image_ref	由应用方提供的参照人脸照片

# b. 接口返回值加密

加密方法
由应用方自行生成密钥对（公钥+私钥），将公钥配置至 FinAuth 控制台，私钥由应用方本地保管；原力金智使用应用方公钥对接口返回值加密，应用方使用本地私钥完成解密。

加密内容

接口	加密参数	说明
verify	images	一组采集的用户照片，包含 image_best
liveness	images	一组采集的用户照片，包含 image_best

# 1.2 如何开启加密

通过请求参数 encryption_type 控制加密开关，系统支持两种非对称加密算法，海外环境仅 RSA 生效，配置规则如下：

encryption_type = 0：不开启加密
encryption_type = 1：使用国密 SM2 加密（海外环境不支持）
encryption_type = 2：使用 RSA 加密（海外唯一可用方案）

# 2 密钥配置

# 2.1 如何生成密钥

# a. SM2 生成密钥（海外不支持）

国密 SM2 加解密基于标准 SM2 算法实现，公私钥必须为标准 PEM 格式。

生成参考：https://www.cnblogs.com/toolsMan/p/14045404.html

公钥示例

-----BEGIN PUBLIC KEY-----
MFkwEwYHKoZIzj0CAQYIKoEcz1UBgi0DQgAEpo36SP78mb5b3e3SGdE+QAn9X2ip
B9MW49nGNzOTe40ze78tnu5Th+g7VtiALeQdZHID2OZq2GIqCPvyrweU6w==
-----END PUBLIC KEY-----

私钥示例

# b. RSA 生成密钥（海外通用）

RSA 加解密规范：密钥长度 1024bit，填充方式 PKCS#1，公私钥必须为标准 PEM 格式。

生成参考：https://blog.csdn.net/aa464971/article/details/51035200

公钥示例

私钥示例

# 2.2 如何上传密钥

登录 FinAuth 控制台，进入「应用配置」-「信息加密」模块，将生成的公钥分别填入 RSA 加密配置或 SM2 加密配置栏，点击提交。若提交按钮下方展示 FinAuth RSA 公钥 / FinAuth SM2 公钥，代表密钥上传生效。

# 3 加解密示例说明

# 3.1 图片加密（全接口通用）

# a. 加密对象

接口	加密参数	说明
verify	image / image_ref	用户自有照片、参照人脸照片
liveness	image	用户传入的自有照片
compare	image / image_ref	用户自有照片、参照人脸照片

# b. 加密说明

1. 读取原始图片字节，计算文件长度 len；
2. **len ≤ 1024**：全文加密图片数据，将加密后数据长度转为 4 字节拼接至文件尾部，整体 Base64 编码；
3. **len &gt; 1024**：仅加密前 1024 字节，剩余数据明文拼接，加密段长度转为 4 字节拼接在整个文件尾部，整体 Base64 编码。

# c. 通用逻辑

<=1024: 原始图片data ---→ ENC加密后data1 ---→ data1+len(data1) ---→ Base64编码输出
len>1024:  原始图片data ---→ 前1024字节ENC加密得到data1 + 剩余明文data2 ---→ data1+data2+len(data1) ---→ Base64编码输出

# d. 实例公式（len>1024）

en_data = ENC(image[1024]) // 加密前1024个字节
Base64.en(en_data+plain_data+len(en_data)); // 最终Base64结果

# 3.2 图片解密（verify、liveness 接口返回值）

# a. 解密对象

接口	参数	说明
verify	images	采集用户照片集合（含 image_best）
liveness	images	采集用户照片集合（含 image_best）

# b. 解密对象

对返回的 Base64 密文解码，获取二进制数据；
截取尾部 4 字节，转换为整型得到加密数据长度 len；
截取前 len 字节使用本地私钥解密；
解密数据 + 剩余明文数据拼接，剔除尾部 4 字节，还原原始图片。

# b. 实例公式

DEC 为解密方法：RSA 对应 RSA.dc，SM2 对应 SM2.dc

b_data = Base64.dc(data);      // Base64解码
len = int(b_data[:-4]);         // 获取加密段长度
a_data = DEC(b_data[len]);      // 解密加密片段
res_data = a_data+b_data[len:-4];// 拼接得到原图

# 4 加解密示例代码

完整可运行的加解密 Demo 代码，请联系 FinAuth 客服或商务人员获取。