7.6.4. Setting up DRMs, OCSPs, and TKSs

DRM, OCSP, and TKS subsystems use the same options both to create and to configure new instances.
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.4, “Configuring a DRM” and Chapter 11, Silent Configuration for other options.

IMPORTANT

Before any DRM, OCSP, or TKS subsystem can be set up, a Certificate System CA must be installed, configured, and running. These subsystems depend on the CA to issue their certificates and to create a security domain. If the security domain CA is not available, then the configuration process fails.

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

NOTE

A Data Recovery Manager (DRM) is also known as a Key Recovery Authority (KRA). All command-line tools and many files for the DRM use the abbreviation kra for this reason. In the documentation, the subsystem used to archive and recover keys is called the DRM or KRA interchangeably.
  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:10180/kra/admin/console/config/login?pin=kI7E1MByNIUcPJ6RKHmH
    Alternatively, log into the setup wizard through the admin link on the services page and supply the preop.pin value from the /var/lib/instance_name/conf/CS.cfg file when prompted.
    https://server.example.com:10445/kra/services
  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. 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.
  7. Set the key size and the algorithm (RSA) or curve (ECC) to use for the subsystem instance keys.
    To set different key types, sizes, or algorithms (RSA) or curves (ECC) for each certificate, click the [Advanced] link to expand the form so each key pair is listed.
    The default RSA key size is 2048 and for ECC, 256.

    IMPORTANT

    ECC can be used for any keys for the subsystem, with one exception: only RSA can be used for audit signing keys. To use ECC, you must open the Advanced tab and set the audit signing keys to RSA with the desired algorithm and length. All other keys can use ECC.
    An ECC module must be loaded for ECC certificates to be generated. Adding ECC support is covered in Section 9.3, “Installing an Instance with ECC Enabled”. Any ECC-enabled PKCS#11 module must be loaded before beginning to configure the CA.
    The algorithms or curves that are available depend on whether RSA or ECC is selected as the key type. The available algorithms and curves are listed in Appendix A, Supported Algorithms and Curves.
  8. 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.
  9. 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 subsystem database, and then proceed with the installation. Click Apply to view the certificates as they are imported.
  10. If the subsystem will ever be cloned, or as a protection if keys or certificates are ever lost, back up the keys and certificates when prompted. It is also possible to extract these keys later, as long as they are not stored on an HSM.

    NOTE

    It is not possible to export keys and certificates stored on an HSM to a .p12 file. If this instance will be cloned, use the HSM tools to export the keys when necessary.
  11. Provide the information for the new subsystem administrator.
  12. Click Next through the remaining panels to import the agent certificate into the browser and complete the configuration.
  13. TKS only. Before restarting the new TKS instance, create a shared secret key.
    The tkstool script prints information about the shared secret key as it creates the key. These session key shares are required to import the shared key onto the TPS, so record this information.

    NOTE

    Creating shared keys for the TKS and TPS is covered in the Administrator's Guide.
    tkstool -T -d /var/lib/pki-tks/alias -n 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!

    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-tks/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.
  14. When the configuration is complete, restart the subsystem.
    service pki-kra 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.

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.