16.2. Encryption Of KRA Operations

Certificate System encrypts the following key operations in the Key Recovery Authority (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.

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

16.2.2. Configuring the Encryption Algorithm in the KRA

Note

Only AES CBC (in case when kra.allowEncDecrypt.archive=true and kra.allowEncDecrypt.recovery=true) and AES Key Wrap (in case when kra.allowEncDecrypt.archive=false and kra.allowEncDecrypt.recovery=false) are allowed in the following configuration. Any FIPS140-2 validated HSM that supports either algorithm is allowed for the key archival and recovery feature provided by 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. We recommend the following set of parameters (see note above for other option): 
kra.allowEncDecrypt.archive=false
kra.allowEncDecrypt.recovery=false
kra.storageUnit.wrapping.1.sessionKeyLength=256
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
kra.storageUnit.wrapping.1.sessionKeyType=AES
kra.storageUnit.wrapping.1.payloadWrapIVLen=16
kra.storageUnit.wrapping.choice=1
Each group (kra.storageUnit.wrapping.0.* vs kra.storageUnit.wrapping.1.*) has individual settings, and the number defines which settings belong to the same configuration group. The current configuration group is set in the kra.storageUnit.wrapping.choice parameter in the /var/lib/pki/pki-instance_name/conf/kra/CS.cfg file.
Ensure that kra.storageUnit.wrapping.choice=1 is set in the configuration file before continuing.

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.

16.2.2.1. Explanation of Parameters and their Values

Each secret (a "payload") is encrypted with a session key. Parameters controlling this encryption are prefixed with payload. The set of parameters to be used depends on the value of kra.allowEncDecrypt.archive and kra.allowEncDecrypt.recovery. By default, both of these are false. See Section 16.2.2.2, “Solving Limitations of HSMs When Using AES Encryption in KRAs” for the effect of these two parameters on HSMs.
When kra.allowEncDecrypt.archive and kra.allowEncDecrypt.recovery are both false:
  • payloadWrapAlgorithm determines the wrapping algorithm used. The only one valid choice is AES KeyWrap.
  • When payloadWrapAlgorithm=AES/CBC/PKCS5Padding, then payloadWrapIVLength=16 has to be specified to tell PKI that we need to generate an IV (as CBC requires one).
When kra.allowEncDecrypt.archive and kra.allowEncDecrypt.recovery are both true:
  • payloadEncryptionAlgorithm determines the encryption algorithm used. The only valid choice is AES.
  • payloadEncryptionMode determines the block chaining mode. The only valid choice is CBC.
  • payloadEncryptionPadding determines the padding scheme. The only valid choice is PKCS5Padding.
The session key is then wrapped with the KRA Storage Certificate, an RSA token. Parameters controlling the session key and its encryption are prefixed with sessionKey.
  • sessionKeyType is the type of key to generate. The only valid choice is AES.
  • sessionKeyLength is the length of the generated session key. Valid choices are 128 and 256, to encrypt the payload with 128-bit AES or 256-bit AES respectively.
  • sessionKeyWrapAlgorithm is the type of key the KRA Storage Certificate is. The only valid choice in this guide is RSA.

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

Sometimes the KRA does not support the default key wrapping algorithm, but it supports other algorithms. 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 KeyWrap
kra.storageUnit.wrapping.1.payloadWrapIVLen=16
kra.storageUnit.wrapping.1.sessionKeyLength=128
  2. Restart the instance: 
    # systemctl restart pki-tomcatd@instance_name.service
    OR (if using nuxwdog watchdog) 
    # systemctl restart pki-tomcatd-nuxwdog@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.
This configuration uses the kra.storageUnit.wrapping.1.payloadWrap{Algorithm,IVLen} and kra.storageUnit.wrapping.1.payloadEncryption{Algorithm,Mode,Padding} parameters.

Setting the KRA into Encryption Mode

If the HSM does not support any KeyWrap algorithms, on some occassions it is necessary to place 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
    OR (if using nuxwdog watchdog) 
    # systemctl restart pki-tomcatd-nuxwdog@instance_name.service
    If the KRA runs in a difference instance than the CA, you need to restart both instances.
This configuration uses kra.storageUnit.wrapping.1.payloadEncryption{Algorithm,Mode,Padding} and kra.storageUnit.wrapping.1.payloadWrap{Algorithm,IVLen} parameters.

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.