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.
tps.0.nickname=TPS-<tps host name>-8443 sharedSecret
tps.0.userid=,TPS-<tps host name>-8443


The above list can be extended when one TKS is connecting to multiple TPS instances.
conn.tks1.tksSharedSymKeyName=TPS-<tps host name>-8443 sharedSecret


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.


    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:
    tps.0.nickname=TPS-<tps host name>-8443 sharedSecret
    tps.0.userid=TPS-<tps host name>-8443 sharedSecret
  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