# 1. 加密说明

# 1.1 加密方案概述

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

# a. 接口传入参数加密

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

加密内容

活体方式	接口	加密参数	说明
炫彩活体	get_token	idcard_name idcard_number image_ref[x]	需要核实对象的姓名 需要核实对象的证件号码 由应用方提供的参照人脸照片
视频活体	validate_videoverify	video idcard_name idcard_number image_ref[x]	需用户上传的视频 需要核实对象的姓名 需要核实对象的证件号码 由应用方提供的参照人脸照片
静默活体	validate_stillverify	video idcard_name idcard_number image_ref[x]	需用户上传的视频 需要核实对象的姓名 需要核实对象的证件号码 由应用方提供的参照人脸照片

# b. 接口返回值加密

由应用方自己生成密钥对（包括公钥和私钥），将公钥配置到FaceID控制台，私钥由应用方自行保护，旷视使用公钥对返回值进行加密，应用方使用私钥进行解密。

加密内容

活体方式	接口	加密参数	说明
炫彩活体	get_result	image_best image_best_2	本字段仅调用成功且return_image字段配置为1或者2时才返回，返回为将会用于人脸比对的视频中的最佳质量的人脸照片。采用Base64字符串返回，图像格式为JPEG。在异常情况下，该字段有可能返回null 本字段仅调用成功且return_image字段配置为2时才返回，返回为质量最佳的另一张活体图像。采用Base64字符串返回，图像格式为JPEG。在异常情况下（如只存在一张符合质量的图片），该字段有可能返回null
视频活体	validate_video	image_best image_best_2	本字段仅调用成功且return_image字段配置为1或者2时才返回，返回为将会用于人脸比对的视频中的最佳质量的人脸照片。采用Base64字符串返回，图像格式为JPEG。在异常情况下，该字段有可能返回null 本字段仅调用成功且return_image字段配置为2时才返回，返回为质量最佳的另一张活体图像。采用Base64字符串返回，图像格式为JPEG。在异常情况下（如只存在一张符合质量的图片），该字段有可能返回null
静默活体	validate_still	image_best image_best_2	本字段仅调用成功且return_image字段配置为1或者2时才返回，返回为将会用于人脸比对的视频中的最佳质量的人脸照片。采用Base64字符串返回，图像格式为JPEG。在异常情况下，该字段有可能返回null 本字段仅调用成功且return_image字段配置为2时才返回，返回为质量最佳的另一张活体图像。采用Base64字符串返回，图像格式为JPEG。在异常情况下（如只存在一张符合质量的图片），该字段有可能返回null

# 1.2 如何开启加密

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

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

不同活体方式的encryption_type参数所在接口如下：

活体方式	接口
视频录制	get_random_number
静默录制	validate_still
炫彩RTC	get_token

# 2. 密钥配置

# 2.1 如何生成密钥

# a. SM2生成密钥

国密SM2加解密使用标准的SM2算法进行加密。

公私钥生成
公私钥必须为标准的PEM格式，参考基于openssl生成 https://www.cnblogs.com/toolsMan/p/14045404.html

示例

公钥：

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

私钥：

-----BEGIN EC PRIVATE KEY-----
MHcCAQEEID/OxQtw1fC4x1TtskSo6UQlCk5bJ1B6A8JXw9FxGnkKoAoGCCqBHM9V
AYItoUQDQgAEpo36SP78mb5b3e3SGdE+QAn9X2ipB9MW49nGNzOTe40ze78tnu5T
h+g7VtiALeQdZHID2OZq2GIqCPvyrweU6w==
-----END EC PRIVATE KEY-----

# b. RSA生成密钥

RSA加解密使用 1024bit 的密钥，padding 使用 PKCS#1 的方式。

公私钥生成
公私钥必须为标准的PEM格式，参考基于openssl 生成 https://blog.csdn.net/aa464971/article/details/51035200

示例

公钥：

-----BEGIN PUBLIC KEY-----
MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQCBSc4iLjnf7CQsF7KrmmXWXMDA
xPZbXIxf0Gdf5QsoBTOgwzSTIUgbdh7srEFrq3f2wjcpRuFHhhRNP1UujQM3onXi
La9SyckZluJhlFHmurY9P3YVnnXdtw4tMDHIkWhFIygArN4dYkbQdNw4HUMvKixu
JIZfGkDfBqT+0p2FfwIDAQAB
-----END PUBLIC KEY-----

私钥：

-----BEGIN EC PRIVATE KEY-----
MIICWwIBAAKBgQCBSc4iLjnf7CQsF7KrmmXWXMDAxPZbXIxf0Gdf5QsoBTOgwzST
IUgbdh7srEFrq3f2wjcpRuFHhhRNP1UujQM3onXiLa9SyckZluJhlFHmurY9P3YV
nnXdtw4tMDHIkWhFIygArN4dYkbQdNw4HUMvKixuJIZfGkDfBqT+0p2FfwIDAQAB
AoGABkxRyZPPIGLWLgrOYbXjqTowmSxNWcXKDpW4vFfv7fhiArARewgIWuDH3Rk4
a4X89YQ8wFc7Q8PsqQjocw34nNtea+qGZWFV1EQ/aaVpYrgCDjNAx9QTcPgVbq3/
QMdWoLAzdaOao7glo5VxG5+WQYJs1mjtPJdT2p1kSngol8kCQQCEyVKhz0S6N4dY
1yBaYFV/dK8HvdpxSPkfOHC3KePIkpv12vuGKjVTHm2PtMvm83UA4hwzEIAHATqS
6q/ilNCDAkEA+UGGRFCb2igRm6pKgaVKYJsAE1xtySJnGD5mDPr724ewzvQ4zdVv
JWcvX41jVf6rLt3b1qKcDm2u2QLMmTRuVQJAZWlsVm/5yU6Ha+5Ao0VXhtQSqRLy
NfrJaHKugvTXJmPyAL6RwlGSEDz45/vojiX5ggcuCkHbxX3GwlXCpoWJCQJAD0kQ
ZdIXrKo2YjhwN0EerYvz1jwd027Tqa3x7ivaFB1fH2HkteK33TBVvGNcSyLB9q7O
U3xHW68oQNCmIWMQvQJAVdDBEf3y65l/k2Ian3mJdpZT7JGOBjGbnoXNidVv8T+J
FlJtfbj7eoZne5bM1IDXDgPlYt36vFuPKvb89YvhCw==
-----END EC PRIVATE KEY-----

# 2.2 如何上传密钥

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

# 3、加解密示例说明

# 3.1 字符串加密说明

加密字符串生成过程如下

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

实例公式如下
ENC为加密方法，如RSA方法则ENC为RSA.en，国密SM2则为SM2.en。
Base64.en(ENC(args_string))

# 3.2 字符串解密说明

与加密相反，解密过程如下

• 将生成的加密串进行Base64解码，得到解密后的二进制内容。
• 使用私钥作为解密钥，对二进制进行全文解密，得到原始串。

实例公式如下
DEC为解密方法，如RSA方法则DEC为RSA.dc，国密SM2则为SM2.dc。
DEC(Base64.dec(args_string))

# 3.3 图片（视频）加密

加密图片（视频）生成过程如下

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

具体方法

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))

实例公式（len>1024）
en_data = ENC(image[1024]) // 加密1024个字节
Base64.en(en_data+plain_data+len(en_data)); // Base64加密结果

# 3.4 图片（视频）解密

解密图片（视频）的过程如下

• 将原始图片（视频）做Base64转化；
• 转化后从数据尾部获取4字节，转化成int类型的数据长度len
• 读取len长度的数据进行RSA解密，密钥为私钥；
• 将解密后的数据与剩余部分拼接，去掉尾部4字节即为结果。

具体方法

原始数据data ----->Base64转化data1----->读取尾部4字节计算出加密数据长度len---->解密len长度的数据data2,剩余部分data3---→ data2+data3-尾部4字节

实例公式

DEC为解密方法，如RSA方法则DEC为RSA.dc，国密SM2则为SM2.dc。

b_data = Base64.dc(data); // 对全文进行base64 解密

len = int(b_data[:-4]); // 获取Aes需解密len

a_data = DEC(b_data[len]); // 解密加密部分数据

res_data = a_data+b_data[len:-4]; // 拼接生成图片（视频）

# 4、加解密示例代码

https://github.com/FacePlusPlus/FaceID_Guomi_Encryption_Decryption_Sample_Code#faceid_guomi_encryption_decryption_sample_code