Descriptors encryption

To prevent malicious use of descriptors stolen from api or db descriptor encryption feature can be enabled. If enabled, only encrypted descriptor data will be kept in the database. Descriptors that are passed to save without encryption will be encrypted.

Encrypted descriptors are stored and received in following format: <encrypted_descriptor><tag><nonce><hash>

Descriptors that have already been encrypted before saving must correspond with this format. Only descriptors that were encrypted with the current key and algorithm can be received from the database. When updating face descriptors, all descriptors with different key or algorithm will be deleted. It is assumed that all descriptors can be encrypted with only one key + algorithm pair at once.

Configuring encryption

Encryption can be enabled through the DESCRIPTOR_ENCRYPTION setting.

  • enabled - whether descriptors encryption is enabled or not.

  • algorithm - name of the encryption algorithm used.

  • params - encryption params to specify the encryption key source.

Supported algorithms: aes256-gcm

Encryption params contain the following fields:

  • source - name of encryption key source.

  • key - encryption key or credentials for receiving it

Supported source types: raw, vaultKV

For both raw, vaultKV sources key must be encoded in base64 string

If you use Hashicorp Vault Key/Value storage as your key source, key must contain the following fields:

  • url - url for receiving encryption key

  • token - authentication token

    {
    "enabled": true,
    "algorithm": "aes256-gcm",
    "params": {
        "source": "vaultKV",
        "key": {
            "url": "https://vault.example.com/v1/secret/data/encryption_key",
            "token": "s.XYZ12345"
        }
    }
}

The contents of vault Key/Value storage are expected to be in the following format:

{
"key": "...",
"algorithm": "..."
}

Encryption migration script

To update the existing descriptors in the database you need to run the script called descriptors_encryption.py. It has three options:

Note

The script requires three environment variables to be set regardless of the option you choose:

  • OLD_ENCRYPTION_KEY (might be set to an empty string)

  • NEW_ENCRYPTION_KEY (might be set to an empty string)

  • ENCRYPTION_ALGORITHM (is always mandatory and can not be empty)

1. To encrypt the original descriptors. This option allows you to encrypt all the descriptors in the database if they were not encrypted previously. Already encrypted descriptors will be ignored, so the script may be run several times. If you choose this option, you need to fill in the NEW_ENCRYPTION_KEY variable and leave the OLD_ENCRYPTION_KEY variable empty.

2. To switch to a new encryption key. This option assumes that encryption has already been performed and you possess the existing encryption key which you want to refresh. Already encrypted descriptors will be ignored, so the script might be ran several times. You must specify both OLD_ENCRYPTION_KEY and NEW_ENCRYPTION_KEY.

3. To decrypt the encrypted descriptors. This options will turn the descriptors back to their original state. It will only will only process the encrypted descriptors and leave the original ones unchanged. To run this version of the script, you need to specify the OLD_ENCRYPTION_KEY variable and leave the NEW_ENCRYPTION_KEY variable empty.

Warning

PLEASE MAKE SURE YOU MADE THE DB’s BACKUP BEFORE RUNNING SCRIPT.

Also please note that all three options cause temporary attributes to be cleaned up.

To run the script you need to specify the way to get DB configs from

The default option is to pull settings from the configuration file.

To run the script:

export ENCRYPTION_ALGORITHM=aes256-gcm
export OLD_ENCRYPTION_KEY=B9pFvUkmaN7RFrr3HEC3U/VTHQcOaKTZ5flQyXwP5qo=
export NEW_ENCRYPTION_KEY=3gDyT4o+YlKLV4NZRjP/wznuhgxMI0mNNJWqc782Z9M=

python ./base_scripts/descriptors_encryption.py --config=./configs/myconfig.conf --LUNA_ATTRIBUTES_DB=ATTRIBUTES_DB

OR

python ./base_scripts/descriptors_encryption.py --luna-config=http://127.0.0.1:5070/1 --LUNA_FACES_DB=FACES_DB
 --DATABASE_NUMBER=DATABASE_NUMBER --LUNA_ATTRIBUTES_DB=ATTRIBUTES_DB