3.4. Encryption Of KRA Operations

Certificate System encrypts the following key operations in the Key Recovery Agent (KRA):
  • Archival:
    • Encryption of keys to archive in a Certificate Request Message Format (CRMF) package for transport to the KRA.
    • Encryption of the key for storage in the KRA LDAP database.
  • Recovery:
    • Encryption of a user-provided session key for transport to the key.
    • Decryption of the secret and re-encryption using the user provided session key or creation of a PKCS#12 package.
  • Generation:
    • Encryption of a generated key for storage.

3.4.1. How Clients Manage Key Operation Encryption

The Certificate System client automatically uses the encryption algorithm set in the KRA's configuration and no further actions are required.

3.4.2. Configuring the Encryption Algorithm in the KRA

Certificate System defines groups of configuration parameters related to key operation encryption in the /var/lib/pki/pki-instance_name/conf/kra/CS.cfg file: 
kra.storageUnit.wrapping.0.sessionKeyLength=0
kra.storageUnit.wrapping.0.sessionKeyWrapAlgorithm=RSA
kra.storageUnit.wrapping.0.payloadEncryptionPadding=PKCS5Padding
kra.storageUnit.wrapping.0.sessionKeyKeyGenAlgorithm=DES3
kra.storageUnit.wrapping.0.payloadEncryptionAlgorithm=DES3
kra.storageUnit.wrapping.0.payloadEncryptionMode=CBC
kra.storageUnit.wrapping.0.payloadWrapAlgorithm=DES3/CBC/PAD
kra.storageUnit.wrapping.0.sessionKeyType=DES3

kra.storageUnit.wrapping.1.sessionKeyLength=128
kra.storageUnit.wrapping.1.sessionKeyWrapAlgorithm=RSA
kra.storageUnit.wrapping.1.payloadEncryptionPadding=PKCS5Padding
kra.storageUnit.wrapping.1.sessionKeyKeyGenAlgorithm=AES
kra.storageUnit.wrapping.1.payloadEncryptionAlgorithm=AES
kra.storageUnit.wrapping.1.payloadEncryptionMode=CBC
kra.storageUnit.wrapping.1.payloadWrapAlgorithm=AES KeyWrap/Padding
kra.storageUnit.wrapping.1.sessionKeyType=AES
Each group has individual settings, and the number defines in each parameter's name which settings belong to the same configuration group. The configuration group, which is currently enabled, is set in the kra.storageUnit.wrapping.choice parameter in the /var/lib/pki/pki-instance_name/conf/kra/CS.cfg file.

Important

If you install the KRA using Certificate System 9.3 or later, all key operations use the AES algorithm by default. In this case, the kra.storageUnit.wrapping.choice parameter is set to 1 by default.
Instances installed using a version earlier then 9.3, use the older 3DES algorithm. If you updated these instances to 9.3 or later, the new configuration group for AES encryption would be automatically added to the configuration. However, the kra.storageUnit.wrapping.choice parameter is set to 0 and the 3DES algorithm is still used.
To manually change the encryption parameter group used by Certificate System:
  1. Edit the /var/lib/pki/pki-instance_name/conf/kra/CS.cfg file and set the kra.storageUnit.wrapping.choice parameter to the required configuration group. For example, to enable AES encryption, set: 
    kra.storageUnit.wrapping.choice=1
  2. Restart the instance: 
    # systemctl restart pki-tomcatd@instance_name.service
    If the KRA runs in a difference instance as the CA, you need to restart both instances.

Note

Certificate System adds the information required to decrypt the data to the record in the KRA database. Therefore, even after changing the encryption algorithm, Certificate System is still able to decrypt data previously stored in the KRA using a different encryption algorithm.

3.4.2.1. Solving Limitations of HSMs When Using AES Encryption in KRAs

If you run Certificate System with AES enabled in the KRA, but the Hardware Security Module (HSM) does not support the AES key wrapping feature, key archival fails. To solve the problem, the following solutions are supported:

Selecting a Different Algorithm for the Key Wrapping

For example, to use AES-128-CBC as the key wrapping algorithm:
  1. Set the following parameters in the /var/lib/pki/pki-instance_name/conf/kra/CS.cfg file: 
    kra.storageUnit.wrapping.1.payloadWrapAlgorithm=AES/CBC/PKCS5Padding
kra.storageUnit.wrapping.1.payloadWrapIVLen=16
  2. Restart the instance: 
    # systemctl restart pki-tomcatd@instance_name.service
    If the KRA runs in a difference instance then the CA, you need to restart both instances.
Selecting a different algorithm for the key wrapping has the benefit that if the HSM later adds support for AES key wrapping, you can revert the settings because the key records have the relevant information set.

Setting the KRA into Encryption Mode

When setting the KRA into encryption mode, all keys will be stored using encryption algorithms rather than key wrapping algorithms.
To set the KRA into encryption mode:
  1. Set the following parameters in the /var/lib/pki/pki-instance_name/conf/kra/CS.cfg file to true: 
    kra.allowEncDecrypt.archive=true
kra.allowEncDecrypt.recovery=true
  2. Restart the service: 
    # systemctl restart pki-tomcatd@instance_name.service
    If the KRA runs in a difference instance than the CA, you need to restart both instances.

Note

If you later switch to a different algorithm for the key wrapping according to the section called “Selecting a Different Algorithm for the Key Wrapping”, you must manually add the appropriate meta data to records created before you set the KRA into encryption mode.