此内容没有您所选择的语言版本。
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:
payloadWrapAlgorithmdetermines the wrapping algorithm used. The only one valid choice isAES KeyWrap.- When
payloadWrapAlgorithm=AES/CBC/PKCS5Padding, thenpayloadWrapIVLength=16has 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:
payloadEncryptionAlgorithmdetermines the encryption algorithm used. The only valid choice is AES.payloadEncryptionModedetermines the block chaining mode. The only valid choice is CBC.payloadEncryptionPaddingdetermines 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.
sessionKeyTypeis the type of key to generate. The only valid choice is AES.sessionKeyLengthis 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.sessionKeyWrapAlgorithmis 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:
- Set the following parameters in the
/var/lib/pki/pki-instance_name/conf/kra/CS.cfgfile:kra.storageUnit.wrapping.1.payloadWrapAlgorithm=AES KeyWrap kra.storageUnit.wrapping.1.payloadWrapIVLen=16 kra.storageUnit.wrapping.1.sessionKeyLength=128
- Restart the instance:
# systemctl restart pki-tomcatd@instance_name.service
OR (if usingnuxwdog 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:
- Set the following parameters in the
/var/lib/pki/pki-instance_name/conf/kra/CS.cfgfile totrue:kra.allowEncDecrypt.archive=true kra.allowEncDecrypt.recovery=true
- Restart the service:
# systemctl restart pki-tomcatd@instance_name.service
OR (if usingnuxwdog 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.
