Restore Backed up Files for Codebook Reshuffling

It is recommended to configure the HSM before restoring the backed up codebook re-shuffling configuration files.

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

1. Login to the DSG Web UI.

2. On the DSG Web UI, navigate to Settings > System > File Upload.

   Note: By default, the Max File Upload size is set to 25 MB on the DSG appliances. If the <filename>.tgz file size is more than 25 MB, the Max File Upload size must be changed. If this value is set to 2 GB, then the following steps can be ignored.

   Perform the following steps to increase the Max File Upload size:

   1. On the DSG Web UI, navigate to Settings > Network > Web Settings.
   2. Under General Settings, ensure that the Max File Upload is set to 2 GB to accommodate the patch upload.
   3. Ensure that the steps 1 and 2 are performed on each DSG node in the cluster.

3. On the File Selection screen, select the <filename>.tgz file, which consists of the following backed up codebook re-shuffling files, and click Upload:

   • BLOB (random.dat)
   • dps.env
   • User PIN (userpin.bin)

4. Login to the DSG CLI Manager.

5. Navigate to Administration > OS Console.

6. Enter the root password.

7. Navigate to the /products/uploads directory by running the following command.

   cd /products/uploads
   

8. Run the following command to extract the contents of the <filename>.tgz file.

   tar -xvpf <filename>.tgz -C /
   

   The contents of the <filename>.tgz file are extracted.

9. Setup the Token Domain for Codebook Re-shuffling by running the following commands.

   cd /opt/protegrity/defiance_dps/data
   su -s /bin/sh service_admin -c "ln -s /opt/protegrity/hsm/libCryptoki2_64.so pkcs11.plm"
   

10. Run the following command to source the dps.env file.

    . /opt/protegrity/defiance_dps/bin/dps.env
    

    Note: The command has a dot followed by a space and then the path.

11. 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
    

12. 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
    
    # 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.

13. On the DSG Web UI, navigate to System > Services to restart the PEP server.

The backed up Codebook Reshuffling configuration files are restored.