# 1 加密说明

# 1.1 加密方案概述

为保护用户敏感信息不被泄露，在调用数字身份验证identity接口时，FaceID对接口传入参数和返回值中涉及用户信息的字符串和图片进行加密，加密规则如下:

# a. 接口传入参数加密

加密方法

• 由旷视生成密钥对，并在控制台提供公钥，应用方调接口时使用公钥对参数加密，旷视使用私钥进行解密。

加密内容

接口	加密参数	说明
identity	image	用户传入的自有照片
	image_ref	由应用方提供的参照人脸照片
	idcard_name	需要核实对象的姓名
	idcard_number	需要核实的对象的证件号码

# 1.2 如何开启加密

加密通过encryption_type字段进行配置，加密支持了两种非对称的加密方法，分别是RSA加密，国密SM2加密，通过以下规则配置：

• 当encryption_type 配置为“0”时，不开启加密；
• 当encryption_type 配置为“1”时，使用国密SM2加密；
• 当encryption_type 配置为“2”时，使用RSA加密。

# 2 密钥配置

# 2.1 如何生成密钥

# 2.1.1 生成 SM2 密钥

OpenSSL 1.1.1 及以上版本支持 SM2。生成前先检查本机版本和曲线支持情况：

openssl version
openssl ecparam -list_curves | grep -i sm2

生成 SM2 私钥和公钥：

openssl genpkey \
  -algorithm EC \
  -pkeyopt ec_paramgen_curve:SM2 \
  -out sm2_private_key.pem

openssl pkey \
  -in sm2_private_key.pem \
  -pubout \
  -out sm2_public_key.pem

openssl pkey \
  -in sm2_private_key.pem \
  -check \
  -noout

上传 sm2_public_key.pem。公钥必须包含完整的 PEM 边界：

-----BEGIN PUBLIC KEY-----
...
-----END PUBLIC KEY-----

不同 OpenSSL 版本可能使用不同的私钥 PEM 格式。请确认客户使用的 SM2 解密库能够读取生成的私钥，不要仅修改 PEM 头尾来转换格式。

# 2.1.2 生成 RSA 密钥

当前使用 1024-bit RSA 和 PKCS#1 v1.5 padding。
生成 RSA 私钥和公钥：

openssl genrsa \
 -out rsa_private_key.pem \
 1024

openssl rsa \
 -in rsa_private_key.pem \
 -pubout \
 -out rsa_public_key.pem

openssl rsa \
 -in rsa_private_key.pem \
 -check \
 -noout

上传 rsa_public_key.pem。公钥必须包含完整的 PEM 边界：

-----BEGIN PUBLIC KEY-----
...
-----END PUBLIC KEY-----

# 2.2 如何上传密钥

在控制台的应用配置中，点击信息加密后，将生成的密钥填到RSA加密配置或者SM2加密配置中，然后点击提交，提交按钮下方显示FaceID RSA公钥或者FaceID SM2公钥即上传成功。

# 3 加解密示例说明

# 3.1 传入参数加密

# a. 加密对象

接口	加密参数	说明
identity	idcard_name	需要核实对象的姓名
	idcard_number	需要核实的对象的证件号码

# b. 加密说明

加密字符串生成过程如下：

• 使用FaceID的公钥作为加密密钥，对字符串进行全文加密，得到一个加密串;
• 将生成的加密串进行Base64编码，生成最终的加密参数。

# c. 实例公式

ENC为加密方法，如RSA方法则ENC为RSA.en，国密SM2则为SM2.en。
Base64.en(ENC(args_string))

# 3.2 图片加密

# a. 加密对象

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

# b. 加密说明

加密图片生成过程如下：

• 计算图片len；
• 如果len<=1024,进行图片全文加密。使用公钥进行加密，加密后生成字符串长度int(len)，将len转化成4字节 ，合入文件尾部。将加密串进行Base64编码，生成最终的加密图片数据；
• 如果len > 1024，只加密前1024字节数据，1024字节之后的数据不进行加密，直接拼接在加密串之后，加密方法同上。请注意：len转化的4字节 ，请合入整个文件尾部，而不是合入加密串尾部。

# c. 具体方法

ENC为加密方法，如RSA方法则ENC为RSA.en，国密SM2则为SM2.en。

len<=1024: 原始图片data  ---→ENC加密后data1---→ data1+len(data1) ----→Base64(data1+len(data1))
len>1024:  原始图片data  ---→data[1024]ENC加密后data1---→ data1+未加密内容data2+len(data1) ----→Base64(data1+data2+len(data1))

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

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

# 4 加解密示例代码

请联系FaceID客服或商务