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 tkstool utility, 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

  1. Install the Token Key Service on the first system. See the Red Hat Certificate System Planning, Installation, and Deployment Guide for installation instructions.
  2. Stop the TKS service: 
    #systemctl stop pki-tomcatd@pki-tomcat.service
  3. Change into the /var/lib/pki/pki-tomcat/alias directory, and use tkstool to create the shared secret key on the TKS. Make sure to generate the shared key before you restart the new TKS instance.

    Important

    The tkstool script 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 sharedSecret
Generating 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!
  4. 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
  5. Start the TKS: 
    #systemctl start pki-tomcatd@pki-tomcat.service

Procedure 6.4. Manual Shared Secret Key Method - TPS side

  1. Install the Token Processing System on the second system. See the Red Hat Certificate System 9 Planning, Installation, and Deployment Guide for installation instructions.
  2. Stop the TPS service: 
    #systemctl stop pki-tomcatd@pki-tomcat.service
  3. Change into the /var/lib/pki/pki-tomcat/alias directory, and use tkstool to 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 sharedSecret
    At 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.
  4. Configure the shared secret in the TPS: 
    conn.tks1.tksSharedSymKeyName=TPS-<tps host name>-8443 sharedSecret
  5. Start the TPS service: 
    #systemctl start pki-tomcatd@pki-tomcat.service