Codebook Reshuffling

Describes the codebook reshuffling feature

Codebook reshuffling is a feature that provides an organization the ability to share protected data outside of its tokenization domain to meet data privacy, analysis, and regulatory requirements. A tokenization domain or a token domain can be defined as a business unit, a geographical location, or a subsidiary organization where protected data is stored. The data protected by enabling Codebook Reshuffling cannot be unprotected outside the tokenization domain.

Codebook reshuffling provides support for the following tokenization data elements:

Alpha (a-z, A-Z)
Alpha-Numeric (0-9, a-z, A-Z)
Binary
Credit Card (0-9)
Date (YYYY-MM-DD)
Date (DD/MM/YYYY)
Date (MM/DD/YYYY)
DateTime Date (YYYY-MM-DD HH:MM:SS MMM)
Decimal (numeric with decimal point and sign)
Email
Integer
Lower ASCII (Lower part of ASCII table)
Numeric (0-9)
Printable
Uppercase Alpha (A-Z)
Uppercase Alpha-Numeric (0-9, A-Z)
Unicode
Unicode Base64
Unicode Gen2

Ensure that you do not unprotect historically protected data using any token element as it causes data corruption if the shufflecodebooks parameter in the pepserver.cfg file is set to yes.
For example, if you have protected sensitive data using the Credit Card token in earlier releases of DSG, where Codebook Reshuffling is not supported for any tokens, and upgrade to the latest version of the DSG, then unprotecting the sensitive data using the same Credit Card token causes data corruption if the parameters in the pepserver.cfg file are configured for Codebook Reshuffling.

Note: As the Codebook Reshuffling feature is an advanced functionality, you must contact the Protegrity Professional Services team for more information about its usage.

Codebook Reshuffling can be enabled on the DSG for all the supported tokenization data elements to generate unique tokens for protected values across the tokenization domains. The following generic example will help you to understand more about the functionality of Codebook Reshuffling.

Codebook Reshuffling

Consider a scenario where an organization has two tokenization domains, Tokenization Domain 1 and Tokenization Domain 2, which are distributed in two different tokenization domains. The Tokenization Domain 1 contains an ESA connected to multiple DSG nodes. A separate TAC for ESAs and DSGs is created.
On the ESA, create a tokenization data element. Codebooks are generated on the ESA when a tokenization data element is created.
Add the newly created tokenization data element to a policy.
Create a Binary Large Object (BLOB) file on each DSG node using the BLOB creation utility (BCU) that contains random bytes. The BLOB file will be encrypted automatically using an AES encryption key fetched from the HSM.
Deploy the policy created on the master ESA to the DSG nodes in Token Domain 1 and Token Domain 2. The DSG nodes download the policy information from the ESA. After the policy is deployed on the DSG, if the codebook reshuffling parameter is enabled, then the codebook will be shuffled again by using the BLOB file created on the DSG.
Create a Ruleset on the DSG nodes to protect the sensitive data.
After a request is sent from the client, the DSG processes and protects the sensitive data. It generates unique tokens for protected values across the tokenization domains.

The advantage offered by codebook reshuffling is that sensitive data on Token Domain 1 cannot be accessed by Token Domain 2. It cannot be accessed because it is protected by a different codebook, available only on the Token Domain 1. The unique tokens generated for the protected data on the Token Domain 1 can be used to derive an insightful analysis for an organization without compromising on any data security compliance and regulatory norms.

Codebook Reshuffling in the PEP Server

Codebook Reshuffling in the PEP server uses the BCU to create a Binary Large Object (BLOB) file that contains random bytes. The HSM encrypts these random bytes and sends it to the DSG. DSG saves these encrypted random bytes in a file. When the PEP server starts, it sends the encrypted random bytes to HSM for decryption. The HSM then decrypts the random bytes and sends it back to DSG. These random bytes are used by DSG to reshuffle the code books.

The file with random bytes is encrypted using an AES encryption key from the HSM and saved to the disk.

The PEP server loads the BLOB file from the disk and decrypts it using the key from the HSM. It then re-shuffles the supported codebooks, whenever a policy is published to shared memory. Based on the random bytes decrypted from the BLOB, codebook Reshuffling generates unique tokens for protected values across the tokenization domains.

After the data is protected by enabling Codebook Reshuffling on the DSG, you must perform data security operations like protect, unprotect, and re-protect for the sensitive data by only using the Data Security Gateway (DSG) protector. Also, DSG does not support the migration of protected data, with the shufflecodebooks parameter in the pepserver.cfg file is set to yes, from the DSG to other protectors. An attempt to migrate the protected data and unprotecting it may cause data corruption.

The Codebook Reshuffling feature is tested and supported for the Safenet Luna 7.4 HSM devices. The procedure provided in this section is for the Safenet Luna 7.4 HSM devices.

To enable the reshuffling of codebooks in the PEP server:

Download the HSM library files. In this procedure, it is assumed that the HSM files are added to the /opt/protegrity/hsm directory.
Note: The HSM directory is not created on the DSG by default after DSG installation. Ensure that you use the following commands to create the HSM directory.
```
mkdir /opt/protegrity/hsm
```
Ensure that the required ownership and permissions are set for the HSM library files in the /opt/protegrity/hsm directory by running the following commands.
```
chown -R service_admin:service_admin /opt/protegrity/hsm
chmod -R 744 /opt/protegrity/hsm
```
Ensure that the HSM library configuration files are available on the DSG.

Create a soft link to link the HSM shared library file using the following commands.

cd /opt/protegrity/defiance_dps/data
su -s /bin/sh service_admin -c "ln -s /opt/protegrity/hsm/<HSM shared library file> pkcs11.plm"

Create the environment settings file using the following commands.

echo "export <Variable Name>=<HSM Configuration file path> >> /opt/protegrity/defiance_
dps/bin/dps.env
chown service_admin:service_admin /opt/protegrity/defiance_dps/bin/dps.env
chmod 644 /opt/protegrity/defiance_dps/bin/dps.env

Export the HSM Configuration file parameter in the current session using the following command.
```
source ../bin/dps.env
```

Create the AES encryption key in the HSM using the following commands.

cd /opt/protegrity/defiance_dps/data
../bin/bcu -lib ./pkcs11.plm -op createkey -label <labelname> -slot <slotnumber> -userpin <SOME_USER_PIN>

Create a BLOB file using the BLOB creation utility (BCU), encrypt the BLOB file with the created encryption key, and save the BLOB file to the disk using the following command.
```
../bin/bcu -lib ./pkcs11.plm -op createblob -label <labelname> -slot <slotnumber> -size <size> -userpin <password> -file random.dat
```
Create the credentials file for the PEP server to connect to the HSM using the following command.
```
../bin/bcu -op savepin -userpin <password> -file userpin.bin
```
Ensure that the required ownership and permissions are set for random.dat and userpin.bin files by using the following command.
```
chown service_admin:service_admin userpin.bin random.dat
```
CAUTION: Ensure that you backup the BLOB file and the user pin file and save it on your local machine. The BLOB file and the user pin files must not be saved on the DSG.
Ensure that you have set the shufflecodebooks configuration parameter to yes and the path to the file containing the random bytes in the pepserver.cfg configuration file using the following code snippet.
```
# shuffle token codebooks after they are downloaded.
# yes, no. default no.
shufflecodebooks = yes

# Path to the file that contains the random bytes for shuffling codebooks.
randomfile = ./random.dat
```
Note: The shufflecodebooks configuration parameter is available in the Policy Management section of the pepserver.cfg file.
Ensure that you have set the required path to the PKCS#11 provider library, slot number to be used on the HSM, and the required path to the userpin.bin file in the pepserver.cfg configuration file using the following code snippet.
```
# -----------------------------------
# PKCS#11 configuration
# Values in this section is only used
# when shufflecodebooks = yes
# -----------------------------------
[pkcs11]

# The path to the PKCS#11 provider library.
provider_library = ./pkcs11.plm

# The slot number to use on the HSM.
slot = 1 /Enter the slot number used at the time of the creation of the key/

# The scrambled user pin file.
userpin = ./userpin.bin
```
Note: The PKCS#11 configuration parameter is available in the PKCS#11 configuration section of the pepserver.cfg file.
Note: Ensure that the slot number added in step 8 of this procedure and the slot number added in step 12 are the same.
On the DSG Web UI, navigate to System > Services to restart the PEP server.

Re-protecting the Existing BLOB

This section describes the steps to reprotect the existing BLOB file with a new key. The user can encrypt the BLOB file by using the steps mentioned in the Codebook Reshuffling in the PEP Server section. These steps will allow the user to encrypt the BLOB using a key label of an AES key. After performing these operations, if the user wants to reprotect the BLOB with another key, then the user should create a new key and use the new key label to encrypt the BLOB. The reprotect operation provided will only reprotect the existing BLOB with a new key label and will not change the content in the BLOB.

To reprotect the existing BLOB:

Create the new AES encryption key in the HSM using the following commands.

./bcu -lib <safenet lib so file path> -slot <slotId> -userpin <userpin> 
-op createkey -label <new_labelname>

Run the following command to reprotect the existing BLOB.
```
./bcu -lib <safenet lib so file path> -slot <slotId> -userpin <userpin> 
-op reprotectblob -label <new_labelname> -file <blob filename>
```
Note: The BCU utility will not perform the reprotect operation of the BLOB, if the keys are used from different HSMs or from different slots or partitions.
Ensure that the required ownership and permission are set for the random.dat file by using the following commands.
```
chown service_admin:service_admin random.dat
chmod 640 random.dat
```
To have the changes made in the above steps reflected, login to the DSG Web UI and navigate to System > Services to restart the PEP server. You can view the success or failure logs of the reshuffling process on the PepServerLog screen on the DSG Web UI. To view the PepServerLog screen, navigate to Logs > PepServer.
On the PepServerLog screen, ensure that you have set the Log level to ALL in the pepserver.cfg file.
```
# ---------------------------------
# Logging configuration,
# Write application log to file as trace
# ---------------------------------
[logging]
# Logging level: OFF - No logging, SEVERE, WARNING, INFO, CONFIG, ALL
level = ALL
```
The following figure shows the PepServerLog after the BLOB file is encrypted with new key.

Restore Backed up Files for Codebook Reshuffling

Restore the backed up Codebook Reshuffling configuration files after upgrading the DSG.

Last modified February 7, 2025