7.6.3. Setting up RAs

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.5, “Configuring an RA” and Chapter 11, Silent Configuration for other options.

IMPORTANT

Before any RA can be set up, a Certificate System CA must be installed, configured, and running. This subsystem depends 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”.
  1. If the CA which will be used to configure the RA is configured to prefer client authentication (sslClientAuth = want is set in the server.xml file), then this setting must be disabled before the RA can be configured. Otherwise, the CA requests client authentication when the RA attempts to connect with it during configuration, which the RA cannot perform, and the configuration process hangs.
    The procedure for changing the client authentication settings is in the Administrator's Guide.
  2. 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.
  3. Open the configuration wizard using the URL returned by running pkicreate.
    https://server.example.com:12889/ra/admin/console/config/login?pin=kI7E1MByNIUcPJ6RKHmH
  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.
    The hostname for the security domain CA can be the fully-qualified domain name or an IPv4 or IPv6 address, if IPv6 was configured before the packages were installed.
  5. Enter a name for the new instance.
  6. Select the CA which will issue, renew, and revoke certificates for certificates processed through the RA. All of the CAs configured in the security domain are listed in a dropdown menu.
  7. Click Next on the Internal Database panel; the SQLite database is created automatically.

    NOTE

    The RA uses a SQLite database to store its configuration and user data rather than an LDAP database, as the other subsystems do.
  8. 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
  9. 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 (RSA) or curves (ECC) for each certificate, click the [Advanced] link to expand the form so each key pair is listed.
    The hashing 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.
    The default RSA key size is 2048 and for ECC, 256.
    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 RA.
  10. Optionally, change the subject names for the 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.
  11. 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.
  12. Provide the information for the new subsystem administrator.
  13. Click Next through the remaining panels to import the agent certificate into the browser and complete the configuration.
  14. When the configuration is complete, restart the subsystem.
    service pki-ra 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.