Documentation 9.0

# Encryption Parameters

T5-IDencode provides a way to encrypt data in a cryptograph. Encryption is performed via dotnet, pkcs11 and aes providers.

# dotnet provider

  • dotnet provider performs software encryption
  • supports RSA with different hashing algoritms (see link)
  • allows to generate X509 certificates with private and public parts
  • allows to load and store X509 certificates with public part

# pkcs11 provider

  • pkcs11 provider works with any provider which supports pkcs11 (for example, HSM)
  • if you use HSM, note that T5-IDencode platform has no access to public or private key and only able to send data to HSM and get it back encrypted
  • supports RSA with different hashing algoritms (see link)
  • provider doesn't allow to generate or load X509 certificates

# aes provider

  • aes provider performs software encryption
  • uses AES encryption algorithm
  • encryption key is specified in the pipeline
    Note: iv_salt is specified in encryption service configuration by service administrator

# Encryption JSON request

JSON object includes JSON arrays of encryption parameters for every field to encrypt.
Same field can be encrypted more than once with different algorithms and also with several keys from one provider.

# JSON parameters

Parameter Type Description Required Possible values
provider_id string Encryption algorithm type yes dotnet, pkcs11, aes
key_id string ID of generated key or SHA256(KEY) as hex-string in case of AES yes Value from your provider or KMS. See key_id parameters below.

WARNING

if you use HSM, note that T5-IDencode platform has no access to public or private key and only able to send data to HSM and get it back encrypted

# key_id parameters
  • for dotnet provider key_id is an id from /v1/encryption request
  • for pkcs11 provider certificate id can be external only
  • for aes provider key_id is a hexadecimal string that represents a 256-bit value as a KEY_ID and uses it as a key for AES. If iv_salt is specified in encryption service configuration, iv_salt will be added to this string. If iv_salt parameter is not specified, original string remains unchanged. In both cases MD5 will be computed from result and used as iv for AES. If key_salt is set in configuration, key_id is adding to the key_salt. SHA256 of the result is used as a key for AES.

# Sample encryption parameters

{
  "encryption": {
        "face_image": [
            { "provider_id": "dotnet", "key_id": "5E068FCEF308845AA112002C0A2C548FFAD858B9" }
        ],
        "left_slap": [
            { "provider_id": "pkcs11", "key_id": "727361323031382D6B6579" }
            { "provider_id": "aes", "key_id": "00112233445566778899AABBCCDDEEFF0123456789ABCDEF0123456789ABCDEF" }
        ],
        "extra": [
            { "provider_id": "dotnet", "key_id": "9F528F5F4F756830C5A94B283AE6394F1CB45DEB" }
        ]
    }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14

◽ Notice: "encryption" is a json object.
◽ Notice: object "encryption" is optional.

# Encryption order

Principle "from general to specific" is applied for encryption.

# Examples

Encryption of all finger templates of right slap with key_1:

{
  "encryption": {
        "right_slap": [
            { "provider_id": "dotnet", "key_id": "key_1" }
        ]
  }
}
1
2
3
4
5
6
7

Encryption of one finger template from a slap with key_2 and other fingers with key_1:

{
  "encryption": {
        "right_slap": [
            { "provider_id": "dotnet", "key_id": "key_1" }
        ],
        "finger_template_r3": [
            { "provider_id": "dotnet", "key_id": "key_2" }
        ]
  }
}
1
2
3
4
5
6
7
8
9
10

"Specific" instruction (one finger_template) prevails over "general" (whole slap).

For encryption of face_template only without encryption of compressed_image you need to specify only face_template in encryption section:

{
  "facePipeline": {
        "performTemplateExtraction": true,
        "faceDetectorConfidence": 0.6,
        "faceSelectorAlg": 1,
        "performCompression": true,
        "compressionLevel": 2
  },
  "encryption": {
        "face_template": [
            { "provider_id": "dotnet", "key_id": "key_1" }
        ]
  }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14

facePipeline will produce face_template and compressed_image, but only face_template will be encrypted.

In case if specified section is not found, you will see 400 response code with the list of not found sections in body.

Error text example:

Nothing to encrypt for sections finger_template_r3, finger_template_r4
1