# FinAuth Overseas Unified API Encryption Guide

# 1 Encryption Instructions

# 1.1 Overview of the Encryption Scheme

To protect users' sensitive information from being leaked, when calling the overseas verify, liveness, and compare APIs, FinAuth encrypts the user string information and image data contained in the request parameters and return values. The overseas environment supports RSA encryption only; the SM2 (Chinese national cryptography standard) algorithm is not supported. Encryption is divided into two rule sets: "request-parameter encryption" and "return-value encryption".

# a. Request-parameter encryption

Encryption methodYuanli Jinzhi generates the key pair and provides the public key in the console. The application encrypts the request parameters with the FinAuth public key when calling the API, and the Yuanli Jinzhi server decrypts them with the private key.

Encrypted content

API	Encrypted parameter	Description
verify	image	The user's own photo passed in.
verify	image_ref	Reference face photo provided by the application.
liveness	image	The user's own photo passed in.
compare	image	The user's own photo passed in.
compare	image_ref	Reference face photo provided by the application.

# b. Return-value encryption

Encryption methodThe application generates its own key pair (public key + private key), configures the public key in the FinAuth console, and keeps the private key locally. Yuanli Jinzhi encrypts the return value with the application's public key, and the application decrypts it with the local private key.

Encrypted content

API	Encrypted parameter	Description
verify	images	A set of collected user photos, including image_best.
liveness	images	A set of collected user photos, including image_best.

# 1.2 How to Enable Encryption

Encryption is controlled through the request parameter encryption_type. The system supports two asymmetric encryption algorithms; in the overseas environment only RSA takes effect. The configuration rules are as follows:

encryption_type = 0: encryption disabled
encryption_type = 1: SM2 encryption (not supported in the overseas environment)
encryption_type = 2: RSA encryption (the only option available overseas)

# 2 Key Configuration

# 2.1 How to Generate a Key

# a. SM2 key generation (not supported overseas)

SM2 encryption/decryption is implemented based on the standard SM2 algorithm. The public and private keys must be in standard PEM format.

Reference: https://www.cnblogs.com/toolsMan/p/14045404.html

Public key example:

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

Private key example:

# b. RSA key generation (overseas standard)

RSA encryption/decryption specification: key length 1024 bit, padding mode PKCS#1. The public and private keys must be in standard PEM format.

Reference: https://blog.csdn.net/aa464971/article/details/51035200

Public key example:

Private key example:

# 2.2 How to Upload a Key

Log in to the FinAuth console, go to the "Application Configuration" → "Information Encryption" module, fill the generated public key into the RSA encryption configuration or SM2 encryption configuration field, and click Submit. If the FinAuth RSA public key / FinAuth SM2 public key is displayed below the submit button, the key upload has taken effect.

# 3 Encryption & Decryption Examples

# 3.1 Image Encryption (common to all APIs)

# a. Encryption objects

API	Encrypted parameter	Description
verify	image / image_ref	The user's own photo and the reference face photo.
liveness	image	The user's own photo passed in.
compare	image / image_ref	The user's own photo and the reference face photo.

# b. Encryption instructions

Read the raw image bytes and calculate the file length len.
len ≤ 1024: encrypt the entire image data, convert the encrypted data length into 4 bytes and append them to the end of the file, then Base64-encode the whole.
len > 1024: encrypt only the first 1024 bytes, concatenate the remaining data in plaintext, convert the encrypted segment length into 4 bytes and append them to the end of the whole file, then Base64-encode the whole.

# c. General logic

<=1024: raw image data ---→ ENC-encrypted data1 ---→ data1+len(data1) ---→ Base64-encoded output
len>1024: raw image data ---→ first 1024 bytes ENC-encrypted to data1 + remaining plaintext data2 ---→ data1+data2+len(data1) ---→ Base64-encoded output

# d. Example formula (len>1024)

en_data = ENC(image[1024]) // encrypt the first 1024 bytes
Base64.en(en_data+plain_data+len(en_data)); // final Base64 result

# 3.2 Image Decryption (verify, liveness return values)

# a. Decryption objects

API	Parameter	Description
verify	images	Collected user photo set (including image_best).
liveness	images	Collected user photo set (including image_best).

# b. Decryption instructions

Base64-decode the returned ciphertext to obtain binary data.
Take the last 4 bytes and convert them to an integer to get the encrypted data length len.
Take the first len bytes and decrypt them with the local private key.
Concatenate the decrypted data with the remaining plaintext data and remove the trailing 4 bytes to restore the original image.

# c. Example formula

DEC is the decryption method: RSA corresponds to RSA.dc, SM2 corresponds to SM2.dc.

b_data = Base64.dc(data); // Base64 decode
len = int(b_data[:-4]); // get the encrypted segment length
a_data = DEC(b_data[len]); // decrypt the encrypted segment
res_data = a_data+b_data[len:-4];// concatenate to obtain the original image

# 4 Encryption & Decryption Sample Code

For complete, runnable encryption/decryption demo code, please contact FinAuth customer service or your sales representative.