Chapter 12. Configuring the Key Recovery Authority This chapter describes recovering keys with the Key Recovery Authority (KRA). 12.1. Manually setting up key archival IMPORTANT This procedure is unnecessary if the CA and KRA are in the same security domain. This procedure is only required for CAs outside the security domain. Configuring key archival manually demands two things: Having a trusted relationship between a CA and a KRA. Having the enrollment form enabled for key archival, meaning it has key archival configured and the KRA transport certificate stored in the form. In the same security domain, both of these configuration steps are done automatically when the KRA is configured because it is configured to have a trusted relationship with any CA in its security domain. It is possible to create that trusted relationship with Certificate Managers outside its security domain by manually configuring the trust relationships and profile enrollment forms. If necessary, create a trusted manager to establish a relationship between the Certificate Manager and the KRA. For the CA to be able to request key archival of the KRA, the two subsystems must be configured to recognize, trust, and communicate with each other. Verify that the Certificate Manager has been set up as a privileged user, with an appropriate TLS mutual authentication certificate, in the internal database of the KRA. By default, the Certificate Manager uses its subsystem certificate for TLS mutual authentication to the KRA. Copy the base-64 encoded transport certificate for the KRA. The transport certificate is stored in the KRA's certificate database, which can be retrieved using the certutil utility. If the transport certificate is signed by a Certificate Manager, then a copy of the certificate is available through the Certificate Manager end-entities page in the Retrieval tab. Alternatively, download the transport certificate using the pki utility: List the certificate, using the pki ca-cert-find command and the KRA transport certificate's subject common name. For example: Show the details of the certificate and save it as a .pem file: Note For more information on the pki command options, run the pki --help command. Add the transport certificate to the CA's CS.cfg file. Then edit the enrollment form and add or replace the transport certificate value in the keyTransportCert method. 12.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. 12.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. 12.2.2. Configuring the encryption algorithm in the KRA Note Only AES CBC (in case when kra.allowEncDecrypt.archival=true and kra.allowEncDecrypt.recovery=true ) and AES Key Wrap (in case when kra.allowEncDecrypt.archival=false and kra.allowEncDecrypt.recovery=false ) are allowed in the following configuration. Any FIPS 140-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): 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. 12.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.archival and kra.allowEncDecrypt.recovery . By default, both of these are false. See Section 12.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.archival 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.archival 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 . 12.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: the section called "Selecting a different algorithm for the key wrapping" the section called "Setting the KRA into encryption mode" 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.cfg file: Restart the instance: OR if using the Nuxwdog watchdog: 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 occasions 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.cfg file to true : Restart the service: OR if using the Nuxwdog watchdog: 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. 12.3. Setting up agent-approved key recovery schemes Key recovery agents collectively authorize and retrieve private encryption keys and associated certificates in a PKCS#12 package. To authorize key recovery, the required number of recovery agents access the KRA agent services page and use the Authorize Recovery area to enter each authorization separately. One of the agents initiates the key recovery process. For a synchronous recovery, each approving agent uses the reference number (which was returned with the initial request) to open the request and then authorizes key recovery separately. For an asynchronous recovery, the approving agents all search for the key recovery request and then authorize the key recovery. Either way, when all of the authorizations are entered, the KRA checks the information. If the information presented is correct, it retrieves the requested key and returns it along with the corresponding certificate in the form of a PKCS #12 package to the agent who initiated the key recovery process. The key recovery agent scheme configures the KRA to recognize to which group the key recovery agents belong and specifies how many of these agents are required to authorize a key recovery request before the archived key is restored. 12.3.1. Configuring agent-approved key recovery in the command line To set up agent-initiated key recovery, edit two parameters in the KRA configuration: Set the number of recovery managers to require to approve a recovery. Set the group to which these users must belong. These parameters are set in the KRA's CS.cfg configuration file. Stop the server before editing the configuration file. OR if using the Nuxwdog watchdog: Open the KRA's CS.cfg file. Edit the two recovery scheme parameters. Restart the server. OR Note For more information on how to configure agent-approved key recovery in the console, see 4.1 Configuring Agent-Approved Key Recovery in the Console in the Administration Guide (Common Criteria Edition) . 12.3.2. Customizing the Key Recovery Form The default key agent scheme requires a single agent from the Key Recovery Authority Agents group to be in charge of authorizing key recovery. It is also possible to customize the appearance of the key recovery form. Key recovery agents need an appropriate page to initiate the key recovery process. By default, the KRA's agent services page includes the appropriate HTML form to allow key recovery agents to initiate key recovery, authorize key recovery requests, and retrieve the encryption keys. This form is located in the /var/lib/pki/pki-tomcat/kra/webapps/kra/agent/kra/ directory, called confirmRecover.html . IMPORTANT If the key recovery confirmation form is customized, do not to delete any of the information for generating the response. This is vital to the functioning of the form. Restrict any changes to the content in and appearance of the form. 12.3.3. Rewrapping keys in a new private storage key Some private keys (mainly in older deployments) were wrapped in SHA-1, 1024-bit storage keys when they were archived in the KRA. These algorithms have become less secure as processor speeds improve and algorithms have been broken. As a security measure, it is possible to rewrap the private keys in a new, stronger storage key (SHA-256, 2048-bit keys). 12.3.3.1. About KRATool Rewrapping and moving keys and key enrollment and recovery requests is done using the KRATool utility (known in versions of Red Hat Certificate System as DRMTool ). The KRATool performs two operations: it can rewrap keys with a new private key, and it can renumber attributes in the LDIF file entries for key records, including enrollment and recovery requests. At least one operation (rewrap or renumber) must be performed and both can be performed in a single invocation. For rewrapping keys, the tool accesses the key entries in an exported LDIF file for the original KRA, unwraps the keys using the original KRA storage key, and then rewraps the keys in the new KRA's stronger storage key. Example 12.1. Rewrapping Keys When multiple KRA instances are being merged into a single instance, it is important to make sure that no key or request records have conflicting CNs, DNs, serial numbers, or request ID numbers. These values can be processed to append a new, larger number to the existing values. Example 12.2. Renumbering keys The KRATool options and its configuration file are discussed in more detail in the KRATool(1) man page. 12.3.3.2. Rewrapping and Merging Keys from One or More KRAs into a Single KRA This procedure rewraps the keys stored in one or more Certificate System KRA (for example, pki-tomcat on sourcekra.example.com ) and stores them into another Certificate System KRA (for example, pki-tomcat-2 on targetkra.example.com ). This is not the only use case; the tool can be run on the same instance as both the source and target, to rewrap existing keys, or it can be used simply to copy keys from multiple KRA instances into a single instance without rewrapping the keys at all. IMPORTANT The storage key size and type in the pki-tomcat-2 KRA must be set to 2048-bit and RSA. Log in to targetkra.example.com . Stop the pki-tomcat-2 KRA. Create a data directory to store the key data that will be imported from the pki-tomcat KRA instance residing on sourcekra.example.com . Export the public storage certificate for the pki-tomcat-2 KRA to a flat file in the new data directory. Stop the Directory Server instance for the pki-tomcat-2 KRA, if it is on the same machine. Export the configuration information for the pki-tomcat-2 KRA. IMPORTANT Make sure that the LDIF file contains a single blank line at the end. Log in to sourcekra.example.com . Stop the pki-tomcat KRA. Create a data directory to store the key data that will be exported to the pki-tomcat-2 KRA instance residing on targetkra.example.com . Stop the Directory Server instance for the pki-tomcat KRA, if it is on the same machine. Export the configuration information for the pki-tomcat KRA. IMPORTANT Make sure that the LDIF file contains a single blank line at the end. Copy the pki-tomcat KRA NSS security databases to this directory. Copy the file with the public storage key from the pki-tomcat-2 KRA machine to this machine. For example: If necessary, edit the default KRATool.cfg file to use with the tool. The default file can also be used without changes. Run the KRATool ; all of these parameters should be on a single line: Note The command may prompt for the password to the token stored in the pki-tomcat KRA NSS security databases. When it is done, the command creates the file specified in the -target_ldif_file parameter, source2targetKRA.ldif . Copy this LDIF file over to the pki-tomcat-2 KRA machine. For example: Important Make sure that the LDIF file contains a single blank line at the end. If multiple KRA instances are being merged, their data can be merged into a single import operation. Simply perform the same procedure for every KRA, which will be merged. Important Make sure to specify unique values for the -target_ldif_file parameter to create separate LDIF files, and to specify unique -append_id_offset values so that there are no conflicts when the LDIF files are concatenated. On the pki-tomcat-2 KRA machine, import the LDIF file(s) with the other key data by concatenating the pki-tomcat-2 KRA configuration LDIF file and every exported LDIF file for the other KRA instances. For example: Import this combined LDIF file into the Directory Server database for the pki-tomcat-2 KRA instance. Start the Directory Server instance for the pki-tomcat-2 KRA. Start the pki-tomcat-2 KRA.

Commands:
pki -p <Security Domain Port> -d <nss_db> -w <password> ca-cert-find --name "DRM Transport Certificate"
pki ca-cert-show <serial_number> --output transport.pem
ca.connector.KRA.enable=true ca.connector.KRA.host=server.example.com ca.connector.KRA.local=false ca.connector.KRA.nickName=subsystemCert cert-pki-ca ca.connector.KRA.port=8443 ca.connector.KRA.timeout=30 ca.connector.KRA.transportCert=MIIDbDCCAlSgAwIBAgIBDDANBgkqhkiG9w0BAQUFADA6MRgwFgYDVQQKEw9Eb21haW4gc28gbmFtZWQxHjAcBgNVBAMTFUNlcnRpZmljYXRlIEF1dGhvcml0eTAeFw0wNjExMTQxODI2NDdaFw0wODEwMTQxNzQwNThaMD4xGDAWBgNVBAoTD0RvbWFpbiBzbyBuYW1lZDEiMCAGA1UEAxMZRFJNIFRyYW5zcG9ydCBDZXJ0aWZpY2F0ZTCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEBAKnMGB3WkznueouwZjrWLFZBLpKt6TimNKV9iz5s0zrGUlpdt81/BTsU5A2sRUwNfoZSMs/d5KLuXOHPyGtmC6yVvaY719hr9EGYuv0Sw6jb3WnEKHpjbUO/vhFwTufJHWKXFN3V4pMbHTkqW/x5fu/3QyyUre/5IhG0fcEmfvYxIyvZUJx+aQBW437ATD99Kuh+I+FuYdW+SqYHznHY8BqOdJwJ1JiJMNceXYAuAdk+9t70RztfAhBmkK0OOP0vH5BZ7RCwE3Y/6ycUdSyPZGGc76a0HrKOz+lwVFulFStiuZIaG1pv0NNivzcj0hEYq6AfJ3hgxcC1h87LmCxgRWUCAwEAAaN5MHcwHwYDVR0jBBgwFoAURShCYtSg+Oh4rrgmLFB/Fg7X3qcwRAYIKwYBBQUHAQEEODA2MDQGCCsGAQUFBzABhihodHRwOi8vY2x5ZGUucmR1LnJlZGhhdC5jb206OTE4MC9jYS9vY3NwMA4GA1UdDwEB/wQEAwIE8DANBgkqhkiG9w0BAQUFAAOCAQEAFYz5ibujdIXgnJCbHSPWdKG0T+FmR67YqiOtoNlGyIgJ42fi5lsDPfCbIAe3YFqmF3wU472h8LDLGyBjy9RJxBj+aCizwHkuoH26KmPGntIayqWDH/UGsIL0mvTSOeLqI3KM0IuH7bxGXjlION83xWbxumW/kVLbT9RCbL4216tqq5jsjfOHNNvUdFhWyYdfEOjpp/UQZOhOM1d8GFiw8N8ClWBGc3mdlADQp6tviodXueluZ7UxJLNx3HXKFYLleewwIFhC82zqeQ1PbxQDL8QLjzca+IUzq6Cd/t7OAgvv3YmpXgNR0/xoWQGdM1/YwHxtcAcVlskXJw5ZR0Y2zA== ca.connector.KRA.uri=/kra/agent/kra/connector
vim /var/lib/pki/pki-tomcat/ca/webapps/ca/ee/ca/ProfileSelect.template var keyTransportCert = MIIDbDCCAlSgAwIBAgIBDDANBgkqhkiG9w0BAQUFADA6MRgwFgYDVQQKEw9Eb21haW4gc28gbmFtZWQxHjAcBgNVBAMTFUNlcnRpZmljYXRlIEF1dGhvcml0eTAeFw0wNjExMTQxODI2NDdaFw0wODEwMTQxNzQwNThaMD4xGDAWBgNVBAoTD0RvbWFpbiBzbyBuYW1lZDEiMCAGA1UEAxMZRFJNIFRyYW5zcG9ydCBDZXJ0aWZpY2F0ZTCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEBAKnMGB3WkznueouwZjrWLFZBLpKt6TimNKV9iz5s0zrGUlpdt81/BTsU5A2sRUwNfoZSMs/d5KLuXOHPyGtmC6yVvaY719hr9EGYuv0Sw6jb3WnEKHpjbUO/vhFwTufJHWKXFN3V4pMbHTkqW/x5fu/3QyyUre/5IhG0fcEmfvYxIyvZUJx+aQBW437ATD99Kuh+I+FuYdW+SqYHznHY8BqOdJwJ1JiJMNceXYAuAdk+9t70RztfAhBmkK0OOP0vH5BZ7RCwE3Y/6ycUdSyPZGGc76a0HrKOz+lwVFulFStiuZIaG1pv0NNivzcj0hEYq6AfJ3hgxcC1h87LmCxgRWUCAwEAAaN5MHcwHwYDVR0jBBgwFoAURShCYtSg+Oh4rrgmLFB/Fg7X3qcwRAYIKwYBBQUHAQEEODA2MDQGCCsGAQUFBzABhihodHRwOi8vY2x5ZGUucmR1LnJlZGhhdC5jb206OTE4MC9jYS9vY3NwMA4GA1UdDwEB/wQEAwIE8DANBgkqhkiG9w0BAQUFAAOCAQEAFYz5ibujdIXgnJCbHSPWdKG0T+FmR67YqiOtoNlGyIgJ42fi5lsDPfCbIAe3YFqmF3wU472h8LDLGyBjy9RJxBj+aCizwHkuoH26KmPGntIayqWDH/UGsIL0mvTSOeLqI3KM0IuH7bxGXjlION83xWbxumW/kVLbT9RCbL4216tqq5jsjfOHNNvUdFhWyYdfEOjpp/UQZOhOM1d8GFiw8N8ClWBGc3mdlADQp6tviodXueluZ7UxJLNx3HXKFYLleewwIFhC82zqeQ1PbxQDL8QLjzca+IUzq6Cd/t7OAgvv3YmpXgNR0/xoWQGdM1/YwHxtcAcVlskXJw5ZR0Y2zA==;
kra.allowEncDecrypt.archival=false kra.allowEncDecrypt.recovery=false kra.storageUnit.wrapping.1.payloadEncryptionAlgorithm=AES kra.storageUnit.wrapping.1.payloadEncryptionIVLen=16 kra.storageUnit.wrapping.1.payloadEncryptionMode=CBC kra.storageUnit.wrapping.1.payloadEncryptionPadding=PKCS5Padding kra.storageUnit.wrapping.1.payloadWrapAlgorithm=AES KeyWrap/Padding kra.storageUnit.wrapping.1.sessionKeyKeyGenAlgorithm=AES kra.storageUnit.wrapping.1.sessionKeyLength=128 kra.storageUnit.wrapping.1.sessionKeyType=AES kra.storageUnit.wrapping.1.sessionKeyWrapAlgorithm=RSA kra.storageUnit.wrapping.choice=1
kra.storageUnit.wrapping.1.payloadWrapAlgorithm=AES KeyWrap/Padding kra.storageUnit.wrapping.1.payloadWrapIVLen=16 kra.storageUnit.wrapping.1.sessionKeyLength=128
systemctl restart pki-tomcatd@instance_name.service
systemctl restart pki-tomcatd-nuxwdog@instance_name.service
kra.allowEncDecrypt.archival=true kra.allowEncDecrypt.recovery=true
systemctl restart pki-tomcatd@instance_name.service
systemctl restart pki-tomcatd-nuxwdog@instance_name.service
systemctl stop pki-tomcatd@instance_name.service
systemctl stop pki-tomcatd-nuxwdog@instance_name.service
vim /var/lib/pki/pki-tomcat/kra/conf/CS.cfg
kra.noOfRequiredRecoveryAgents=3 kra.recoveryAgentGroup=Key Recovery Authority Agents
systemctl start pki-tomcatd@instance_name.service
systemctl start pki-tomcatd-nuxwdog@instance_name.service
KRATool -kratool_config_file "/usr/share/pki/java-tools/KRATool.cfg" -source_ldif_file "/tmp/files/originalKRA.ldif" -target_ldif_file "/tmp/files/newKRA.ldif" -log_file "/tmp/kratool.log" -source_pki_security_database_path "/tmp/files/" -source_storage_token_name "Internal Key Storage Token" -source_storage_certificate_nickname "storageCert cert-pki-tomcat KRA" -target_storage_certificate_file "/tmp/files/omega.cert"
KRATool -kratool_config_file "/usr/share/pki/java-tools/KRATool.cfg" -source_ldif_file "/tmp/files/originalKRA.ldif" -target_ldif_file "/tmp/files/newKRA.ldif" -log_file "/tmp/kratool.log" -append_id_offset 100000000000 -source_kra_naming_context "pki-tomcat-KRA" -target_kra_naming_context "pki-tomcat-2-KRA" -process_requests_and_key_records_only
systemctl stop pki-tomcatd@pki-tomcat-2.service
mkdir -p /export/pki
certutil -L -d /var/lib/pki/pki-tomcat-2/alias -n "storageCert cert-pki-tomcat-2 KRA" -a > /export/pki/targetKRA.cert
systemctl stop dirsrv.target
grep nsslapd-localuser /etc/dirsrv/slapd-instanceName/dse.ldif nsslapd-localuser: dirsrv chown dirsrv:dirsrv /export/pki /usr/lib64/dirsrv/slapd-instanceName/db2ldif -n pki-tomcat-2-KRA -a /export/pki/pki-tomcat-2.ldif
systemctl stop pki-tomcatd@pki-tomcat.service
mkdir -p /export/pki
systemctl stop dirsrv.target
grep nsslapd-localuser /etc/dirsrv/slapd-instanceName/dse.ldif nsslapd-localuser: dirsrv chown dirsrv:dirsrv /export/pki /usr/lib64/dirsrv/slapd-instanceName/db2ldif -n pki-tomcat-KRA -a /export/pki/pki-tomcat.ldif
cp -p /var/lib/pki/pki-tomcat/alias/cert9.db /export/pki cp -p /var/lib/pki/pki-tomcat/alias/key4.db /export/pki cp -p /var/lib/pki/pki-tomcat/alias/pkcs11.txt /export/pki
cd /export/pki sftp root@targetkra.example.com sftp> cd /export/pki sftp> get targetKRA.cert sftp> quit
KRATool -kratool_config_file "/usr/share/pki/java-tools/KRATool.cfg" -source_ldif_file /export/pki/pki-tomcat.ldif -target_ldif_file /export/pki/source2targetKRA.ldif -log_file /export/pki/kratool.log -source_pki_security_database_path /export/pki -source_storage_token_name 'Internal Key Storage Token' -source_storage_certificate_nickname 'storageCert cert-pki-tomcat KRA' -target_storage_certificate_file /export/pki/targetKRA.cert -append_id_offset 100000000000 -source_kra_naming_context "pki-tomcat-KRA" -target_kra_naming_context "pki-tomcat-2-KRA" -process_requests_and_key_records_only
scp /export/pki/source2targetKRA.ldif root@targetkra.example.com:/export/pki
cd /export/pki cat pki-tomcat-2.ldif source2targetKRA.ldif > combined.ldif
/usr/lib64/dirsrv/slapd-instanceName/ldif2db -n pki-tomcat-2-KRA -i /export/pki/combined.ldif
systemctl start dirsrv.target
systemctl start pki-tomcatd@pki-tomcat-2.service