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

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

# systemctl stop pki-tomcatd@instance_name.service

OR (if using nuxwdog watchdog)

# systemctl stop pki-tomcatd-nuxwdog@instance_name.service

Open the KRA's CS.cfg file.

# vim /var/lib/pki/pki-tomcat/kra/conf/CS.cfg

Edit the two recovery scheme parameters.

kra.noOfRequiredRecoveryAgents=3
kra.recoveryAgentGroup=Key Recovery Authority Agents

Restart the server.

# systemctl start pki-tomcatd@instance_name.service

# systemctl start pki-tomcatd-nuxwdog@instance_name.service

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.

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

16.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).

16.3.3.1. About KRATool

Rewrapping and moving keys and key enrollment and recovery requests is done using the KRATool utility (known in previous 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 16.1. Rewrapping Keys

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"

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

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

The KRATool options and its configuration file are discussed in more detail in the KRATool(1) man page.

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

Stop the pki-tomcat-2 KRA.

[root@targetkra ~]# systemctl stop pki-tomcatd@pki-tomcat-2.service

Create a data directory to store the key data that will be imported from the pki-tomcat KRA instance residing on sourcekra.example.com.
```
[root@targetkra ~]# mkdir -p /export/pki
```

Export the public storage certificate for the pki-tomcat-2 KRA to a flat file in the new data directory.

[root@targetkra ~]# certutil -L -d /var/lib/pki/pki-tomcat-2/alias -n "storageCert cert-pki-tomcat-2 KRA" -a > /export/pki/targetKRA.cert

Stop the Directory Server instance for the pki-tomcat-2 KRA, if it is on the same machine.
```
[root@newkra ~]# systemctl stop dirsrv.target
```

Export the configuration information for the pki-tomcat-2 KRA.

[root@targetkra ~]# grep nsslapd-localuser /etc/dirsrv/slapd-instanceName/dse.ldif
  nsslapd-localuser: dirsrv

  [root@targetkra ~]# chown dirsrv:dirsrv /export/pki

  [root@targetkra ~]# /usr/lib64/dirsrv/slapd-instanceName/db2ldif -n pki-tomcat-2-KRA -a /export/pki/pki-tomcat-2.ldif

Important

Make sure that the LDIF file contains a single blank line at the end.

Stop the pki-tomcat KRA.

[root@sourcekra ~]# systemctl stop pki-tomcatd@pki-tomcat.service

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.
```
[root@sourcekra ~]# mkdir -p /export/pki
```
Stop the Directory Server instance for the pki-tomcat KRA, if it is on the same machine.
```
[root@sourcekra ~]# systemctl stop dirsrv.target
```

Export the configuration information for the pki-tomcat KRA.

[root@sourcekra ~]# grep nsslapd-localuser /etc/dirsrv/slapd-instanceName/dse.ldif
  nsslapd-localuser: dirsrv

  [root@sourcekra ~]# chown dirsrv:dirsrv /export/pki

  [root@sourcekra ~]# /usr/lib64/dirsrv/slapd-instanceName/db2ldif -n pki-tomcat-KRA -a /export/pki/pki-tomcat.ldif

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.

[root@sourcekra ~]# cp -p /var/lib/pki/pki-tomcat/alias/cert8.db /export/pki

  [root@sourcekra ~]# cp -p /var/lib/pki/pki-tomcat/alias/key3.db /export/pki

  [root@sourcekra ~]# cp -p /var/lib/pki/pki-tomcat/alias/secmod.db /export/pki

Copy the file with the public storage key from the pki-tomcat-2 KRA machine to this machine. For example:

[root@sourcekra ~]# cd /export/pki

  [root@sourcekra ~]# sftp root@targetkra.example.com
  sftp> cd /export/pki
  sftp> get targetKRA.cert
  sftp> quit

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:

[root@sourcekra ~]# 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

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:
```
[root@sourcekra ~]# scp /export/pki/source2targetKRA.ldif root@targetkra.example.com:/export/pki
```
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:
```
[root@targetkra ~]# cd /export/pki
  [root@targetkra ~]# cat pki-tomcat-2.ldif source2targetKRA.ldif > combined.ldif
```

Import this combined LDIF file into the Directory Server database for the pki-tomcat-2 KRA instance.

[root@targetkra ~]# /usr/lib64/dirsrv/slapd-instanceName/ldif2db -n pki-tomcat-2-KRA -i /export/pki/combined.ldif

Start the Directory Server instance for the pki-tomcat-2 KRA.
```
[root@targetkra ~]# systemctl start dirsrv.target
```

Start the pki-tomcat-2 KRA.

[root@targetkra ~]# systemctl start pki-tomcatd@pki-tomcat-2.service

16.3.4. Updating CA-KRA Connector Information After Cloning

For more information on updating CA-KRA information after cloning, see Section 16.3.4, “Updating CA-KRA Connector Information After Cloning”.

16.3. Setting up Agent-Approved Key Recovery Schemes

16.3.1. Configuring Agent-Approved Key Recovery in the Command Line

16.3.2. Customizing the Key Recovery Form

16.3.3. Rewrapping Keys in a New Private Storage Key

16.3.3.1. About KRATool

16.3.3.2. Rewrapping and Merging Keys from One or More KRAs into a Single KRA

16.3.4. Updating CA-KRA Connector Information After Cloning

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

Making open source more inclusive

About Red Hat

Red Hat legal and privacy links

Red Hat legal and privacy links