6.14. Setting Up a TKS/TPS Shared Symmetric Key
The shared symmetric key must be present in the
NSS databases of both the TPS and TKS subsystems. This key is automatically generated when creating the a TPS subsystem. If both the TPS and TKS are installed within the same Tomcat instance, no additional setup is required as the TKS will automatically use the key created by TPS; however, if both subsystems are on separate instances, or even different physical hosts, you must follow the procedure described in this section to securely transport the key to the TKS.
Several possible methods are available to securely transport the shared key between the TPS and TKS:
- The authomatic method: This method works in cases where the subsystem certificates for the TPS are kept in the software NSS database.
- If the above method fails, a fallback manual method is available where the shared key is generated on the TPS using the
tkstoolutility, which can wrap the key from the TPS, allowing for secure transport without exposing the key in transit, and unwrap it into the TKS NSS database.
The following describes the general configuration for both the TPS and TKS, regardless of the method which will be used to import the key. Note that the automatic method will generate these configurations automatically.
- TKS
tks.useNewSharedSecretNames=true tps.0.host=dhcp-16-206.sjc.example.com tps.0.nickname=TPS-<tps host name>-8443 sharedSecret tps.0.port=8443 tps.0.userid=,TPS-<tps host name>-8443 tps.list=0
Note
The above list can be extended when one TKS is connecting to multiple TPS instances.- TPS
conn.tks1.tksSharedSymKeyName=TPS-<tps host name>-8443 sharedSecret
Note
The host name must be the same as the one configured on the TKS side.
6.14.1. Manually Generating and Transporting a Shared Symmetric Key
This section describes how to generate and transport a shared symmetric key manually. This method is useful in cases where automatic generation and transport fails, but should be avoided otherwise.
The manual method consists of two procedures. The first one is performed on the Token Key Service side, and the second one on the Token Processing System.
Procedure 6.3. Manual Shared Secret Key Method - TKS side
- Install the Token Key Service on the first system. See the Red Hat Certificate System Planning, Installation, and Deployment Guide for installation instructions.
- Stop the TKS service:
#systemctl stop pki-tomcatd@pki-tomcat.service - Change into the
/var/lib/pki/pki-tomcat/aliasdirectory, and usetkstoolto create the shared secret key on the TKS. Make sure to generate the shared key before you restart the new TKS instance.Important
Thetkstoolscript will display information about the key during the key creation process. Make sure to note down this information, because it will be required later to import the key into the TPS.#cd /var/lib/pki/pki-tomcat/alias#tkstool -T -d /var/lib/pki/pki-tomcat/tks/alias -n TPS-<tps host name>-8443 sharedSecretGenerating the first session key share . . . first session key share: 792F AB89 8989 D902 9429 6137 8632 7CC4 first session key share KCV: D1B6 14FD Generating the second session key share . . . second session key share: 4CDF C8E0 B385 68EC 380B 6D5E 1C19 3E5D second session key share KCV: 1EC7 8D4B Generating the third session key share . . . third session key share: CD32 3140 25B3 C789 B54F 2C94 26C4 9752 third session key share KCV: 73D6 8633 Generating first symmetric key . . . Generating second symmetric key . . . Generating third symmetric key . . . Extracting transport key from operational token . . . transport key KCV: A8D0 97A2 Storing transport key on final specified token . . . Naming transport key "sharedSecret" . . . Successfully generated, stored, and named the transport key! - Configure the new key in the TKS:
tks.useNewSharedSecretNames=true tps.0.host=dhcp-16-206.sjc.redhat.com tps.0.nickname=TPS-<tps host name>-8443 sharedSecret tps.0.port=8443 tps.0.userid=TPS-<tps host name>-8443 sharedSecret tps.list=0
- Start the TKS:
#systemctl start pki-tomcatd@pki-tomcat.service
Procedure 6.4. Manual Shared Secret Key Method - TPS side
- Install the Token Processing System on the second system. See the Red Hat Certificate System 9 Planning, Installation, and Deployment Guide for installation instructions.
- Stop the TPS service:
#systemctl stop pki-tomcatd@pki-tomcat.service - Change into the
/var/lib/pki/pki-tomcat/aliasdirectory, and usetkstoolto import the shared key into the NSS software token:#cd /var/lib/pki/pki-tomcat/alias#tkstool -I -d . -n TPS-<tps host name>-8443 sharedSecretAt this point, the script will prompt you for session key shares which were displayed to you when generating and wrapping the shared keys on the TKS side in the procedure above. - Configure the shared secret in the TPS:
conn.tks1.tksSharedSymKeyName=TPS-<tps host name>-8443 sharedSecret
- Start the TPS service:
#systemctl start pki-tomcatd@pki-tomcat.service
