# 1 加密说明

# 1.1 加密方案概述

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

# 1.1.1 接口传入参数加密

加密方法

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

加密内容

接口	参数	参数说明
ocrprcard	image	一张图片，二进制文件

# 1.1.2 接口返回值加密

加密方法

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

加密内容

接口	字段	参数说明
ocrprcard	name_eng	英文姓名
	name_chs	中文姓名
	gender	性别（男/女）
	nationality	国籍
	date_of_birth	出生日期
	idcard_number	永居证号
	portrait	永居证图片上的头像图片（仅在return_portrait参数设定为1时返回）
	valid_date_start	有效日期的起始时间
	valid_date_end	有效日期的结束时间

# 1.2 如何开启加密

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

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

# 2 密钥配置

# 2.1 如何生成密钥

# 2.1.1 SM2生成密钥

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

公私钥生成

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

示例

公钥：

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

私钥：

# 2.1.2 RSA生成密钥

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

公私钥生成

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

示例

公钥：

私钥：

# 2.2 如何上传密钥

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

# 3 加解密示例说明

# 3.1 请求参数加密

# 3.1.1加密对象

接口	参数	参数说明
ocrprcard	image	一张图片，二进制文件

# 3.1.2 图片RSA加密说明

加密使用RSA加密方法，密钥采用的padding为PKCS#1, 密钥长度为1024bits。

# a.加密图片生成过程

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

# b.具体方法

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

# c.实例公式

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

# 3.1.3 图片SM2加密方法

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

# a.加密图片生成过程

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

# b.具体方法

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

# c.实例公式

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

# 3.2 返回信息解密

# 3.2.1 解密对象

接口	字段	参数说明
ocrprcard	name_eng	英文姓名
	name_chs	中文姓名
	gender	性别（男/女）
	nationality	国籍
	date_of_birth	出生日期
	idcard_number	永居证号
	portrait	永居证图片上的头像图片（仅在return_portrait参数设定为1时返回）
	valid_date_start	有效日期的起始时间
	valid_date_end	有效日期的结束时间

# 3.2.2 解密过程

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

# 3.2.3 实例公式

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

DEC(Base64.dec(args_string))