7.6.5. Setting up TPSs

The TPS is typically one of the last subsystems set up because it depends on existing CA, DRM, and TKS instances for its configuration.
Subsystem configuration is done by accessing a unique web-based configuration page for the instance. The only supported web browser for subsystem configuration is Mozilla Firefox. To configure the system silently, through the command line, see Example 11.6, “Configuring a TPS” and Chapter 11, Silent Configuration for other options.

IMPORTANT

Before the TPS can be set up, a Certificate System CA and TKS must be installed and configured. If you want to enable server-side key generation, then the DRM must also be installed and configured. The TPS configuration wizard automatically establishes relationships between the CA, TKS, and DRM and the TPS, so specific CA, TKS, and DRM instances must be available to the TPS.

IMPORTANT

Make sure that the system which the subsystem will run on is properly configured and has all of the necessary prerequisite programs and dependencies. These are described in Section 6.3, “Before Installation: Setting up the Operating Environment”.
If the CA, TKS, or DRM which will be used to work with the TPS is configured to prefer client authentication (sslClientAuth = want is set in the server.xml file), then this setting must be disabled before the TPS can be configured. Otherwise, the CA, TKS, or DRM will request client authentication when the TPS attempts to connect with it during configuration, which the TPS cannot perform.
The procedure for changing the client authentication settings is in the Administrator's Guide.
  1. Download the CA certificate chain for the CA which will issue the CA certificate, and import the CA chain into the browser.
    1. Open the CA web services page.
      https://server.example.com:9444/ca/ee/ca
    2. Click the Retrieval tab.
    3. Click the Import CA Certificate Chain link.
    4. Select the radio button to import the CA certificate into the browser.
    5. Click Submit.
  2. Open the configuration wizard using the URL returned by running pkicreate.
    http://server.example.com:7888/tps/admin/console/config/login?pin=kI7E1MByNIUcPJ6RKHmH
  3. Select the token which will store the Certificate System certificates and keys; a list of detected hardware tokens and databases is given.

    IMPORTANT

    Any hardware tokens used with the instance must be configured before configuring the subsystem instance. If the HSM is not properly configured, it may not be listed in the key stores panel or the instance may not function properly. HSM configuration is described in Section 6.3.9.2, “Using Hardware Security Modules with Subsystems”.
    To determine whether a token is detected by the Certificate System, use the TokenInfo tool, as described in Section 6.3.9.4, “Detecting Tokens”.
    The Certificate System automatically discovers Safenet's LunaSA and nCipher's netHSM hardware security modules. The discovery process assumes that the client software installations for these modules are local to the Certificate System subsystem and are in the following locations:
    • LunaSA: /usr/lunasa/lib/libCryptoki2.so
    • LunaSA: /usr/lunasa/lib/libCryptoki2_64.so
    • nCipher: /opt/nfast/toolkits/pkcs11/libcknfast.so
  4. Join an existing security domain by entering the CA information. This URL can be identified by running service pki-ca status on the CA's host; the security domain URL is returned with the other configuration settings. For example:
    https://server.example.com:9445
    When the CA is successfully contacted, then supply the admin username and password for the CA so that it can be properly accessed.
  5. Enter a name for the new instance.
  6. Select the CA which will issue, renew, and revoke certificates for token operations requested through the TPS subsystem.
  7. Supply information about the TKS which will manage the TPS keys. Select the TKS from the drop-down menu of TKS subsystems within the security domain.
  8. There is an option for server-side key generation for tokens enrolled through the TPS. If server-side key generation is selected, supply information about the DRM which will generate keys and archive encryption keys. Key and certificate recovery is initiated automatically through the TPS, which is a DRM agent. Select the DRM from the drop-down menu of DRM subsystems within the security domain.
    The hostname for the DRM can be the fully-qualified domain name or an IPv4 or IPv6 address.
  9. Fill in the Directory Server authentication directory. This directory is used by the TPS to authenticate users which access the Enterprise Security Client and as an additional database for certificates and keys.
    This Directory Server instance must not be the same Directory Server instance used as the TPS's internal database. This is a general user directory, which may be accessed by other applications or users, whereas the TPS's internal database is used exclusively by the TPS and is created on the fly as the TPS is configured.
    To configure SSL client authentication, make sure that the SSL port is set and the SSL checkbox is selected. The Directory Server must be configured to run in SSL, as described in Section 7.5, “Configuring Server SSL Connections Between Red Hat Directory Server and Red Hat Certificate System”.
    The hostname of the LDAP server can be the fully-qualified domain name or an IPv4 or IPv6 address.
  10. Fill in the information for the LDAP server which will be used for the instance's internal database. This requires connection information for the Directory Server instance, such as the hostname, port number, bind DN (username), and password. This step also creates a database in the Directory Server and a corresponding base directory entry (base DN) to use for the subsystem's entries.
    To configure SSL client authentication, make sure that the SSL port is set and the SSL checkbox is selected. The Directory Server must be configured to run in SSL, as described in Section 7.5, “Configuring Server SSL Connections Between Red Hat Directory Server and Red Hat Certificate System”.
    The hostname can be the fully-qualified domain name or an IPv4 or IPv6 address.

    NOTE

    One thing that can derail subsystem configuration or function is having services that are unable to connect with each other. If servers that need to communicate with each other are on different servers or networks, when the firewalls and iptables must be configured to give the required access.
    If the Red Hat Directory Server instances is on a different server or network than the Certificate System subsystem, then make sure that the Certificate System host's firewall allows access to whatever LDAP port was set in the previous configuration panel.
    Installation will not complete if iptables is not configured properly. To configure iptables, see the Red Hat Enterprise Linux Deployment Guide, such as "Using iptables." It is also possible to simply turn iptables off.
  11. Set the key size and type (RSA or ECC) to use for the subsystem instance keys.
    By default, the settings for the signing key are applied to the keys for every certificate for the CA. To set different key types, sizes, or hashing algorithms for each certificate, click the [Advanced] link to expand the form so each key pair is listed.
    The default RSA key size is 2048. The available algorithms are listed in Section A.1, “RSA Hashing Algorithms”. The default size for ECC is 256, and the only supported curve is nistp256.
  12. Optionally, change subject names to the listed certificates.

    NOTE

    Certificate nicknames must be unique, and changing the default nicknames is one way to ensure that.
    Having unique certificate nicknames is vital for using an HSM, since any nickname conflicts (even for subsystems on different servers) will cause configuration to fail.
  13. The next panels generate and show certificate requests, certificates, and key pairs.
    If an external CA is used to issue the certificates, configuration cannot go forward until they are received from the CA. When they are issued, paste the certificates into this panel to add them to the TPS database, and then proceed with the installation. Click Apply to view the certificates as they are imported.
  14. Provide the information for the new subsystem administrator.
  15. Click Next through the remaining panels to import the agent certificate into the browser and complete the configuration.
  16. When the configuration is complete, restart the subsystem.
    service pki-tps restart

    IMPORTANT

    The new instance is not active until it is restarted, and weird behaviors can occur if you try to use the instance without restarting it first.
  17. Stop the TPS.
    service pki-tps stop
  18. Use the tkstool script to import the shared key into the NSS software token.
    tkstool -I -d /var/lib/pki-tps/alias -n sharedSecret
    The script will prompts for the session key shares that were printed when the key was created in the TKS. Enter the information from the TKS.

    NOTE

    If you are using a hardware token, the tkstool script could return an error requiring you to set environment variables before running the tool. Set the environment variables as directed, and then re-run the tool.
    List the keys to make sure the shared key was properly imported.
    tkstool -I -d /var/lib/pki-tps/alias -L
    
     slot:  NSS User Private Key and Certificate Services                  
    token:  NSS Certificate DB
    
    Enter Password or Pin for "NSS Certificate DB": xxxxx
            <0> sharedSecret
    The shared key is sharedSecret, which is the default name. The TPS can be configured to set a different name for the shared key by changing the value of the conn.tks1.tksSharedSymKeyName value in the CS.cfg. This value must be the same as the nickname for the key imported into the token, or the TPS cannot locate the key.

IMPORTANT

After setting up the subsystem, then look at additional configuration steps such as creating users. The most common features are listed in Chapter 8, After Configuration: Checklist of Configuration Areas for Deploying Certificate System.