17.3. Setting up Agent-Approved Key Recovery Schemes
17.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. 17.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 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 the see the Configuring Agent-Approved Key Recovery in the Console section in the Red Hat Certificate System Administration Guide . 17.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. 17.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). 17.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 17.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 17.2. Renumbering Keys The KRATool options and its configuration file are discussed in more detail in the KRATool(1) man page. 17.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. 17.3.4. Updating CA-KRA Connector Information After Cloning For more information on updating CA-KRA information after cloning, see Section 17.3.4, "Updating CA-KRA Connector Information After Cloning" .
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 root@targetkra ~]# 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