7.7. Two-step Installation

To customize certain configuration parameters during installation, the installation process needs be done in two steps, with the configuration between them. For this, the pkispawn utility enables you to run the installation of a subsystem in two steps.

7.7.1. When to Use the Two-Step Installation

Use the two-step installation in scenarios such as:
  • Increasing security.
  • Customizing subsystem certificates.
  • Customizing the cipher list in the sslRangeCiphers parameter in the /etc/pki/instance_name/server.xml file when installing a new Certificate System instance to be connected to an existing Certificate System.
  • Installing CA clones, KRA, OCSP, TKS and TPS in FIPS mode.
  • Installing Certificate System with a Hardware Security Module (HSM) in FIPS mode.

7.7.2. The Two Major Parts of the Two-step Installation

The two-step installation consists of the following two major parts:
  1. Installation
    During this step, pkispawn copies configuration files from the /usr/share/pki/ directory to the instance-specific /etc/pki/instance_name/ directory. Additionally, pkispawn sets the settings based on values defined in the deployment configuration file.
    This part of the installation contains the following substeps:
    1. Section 7.7.3, “Creating the Configuration File for the First Step of the Installation”
    2. Section 7.7.4, “Starting the Installation Step”
  2. Configuration
    During this step, pkispawn continues the installation based on the configuration files in the instance-specific /etc/pki/instance_name/ directory.
    This part of the installation contains the following substeps:
    1. Section 7.7.5, “Customizing the Configuration Between the Installation Steps”
    2. Section 7.7.6, “Starting the Configuration Step”

7.7.3. Creating the Configuration File for the First Step of the Installation

Create a text file for the configuration settings, such as /root/config.txt, and fill it with the settings described below.

Important

This section describes a minimum configuration with Directory Server running on the same host as Certificate System. Depending on your environment, additional parameters may be necessary. For additional examples, see the EXAMPLES section in the pkispawn(8) man page.
For descriptions about the parameters covered in this section, see the pki_default.cfg(5) man page.

Subsystem-independent Settings

Independently of the subsystem you install, the following settings are required in the configuration file:
  1. Set the passwords of the Certificate System admin user, the PKCS #12 file, and Directory Server: 
    [DEFAULT]
pki_admin_password=password
pki_client_pkcs12_password=password
pki_ds_password=password
  2. To use an LDAPS connection to Directory Server running on the same host, add the following parameters to the [DEFAULT] section in the configuration file: 
    pki_ds_secure_connection=True
pki_ds_secure_connection_ca_pem_file=path_to_CA_or_self-signed_certificate

    Note

    For security reasons, Red Hat recommends using an encrypted connection to Directory Server.
    If you use a self-signed certificate in Directory Server use the following command to export it from the Directory Server's Network Security Services (NSS) database: 
    # certutil -L -d /etc/dirsrv/slapd-instance_name/ \
     -n "server-cert" -a -o /root/ds.crt

Important

By default, Certificate System removes the ~/.dogtag/instance_name/subsystem/alias client database after the installation. For security reasons, Red Hat recommends not enabling the pki_client_database_purge parameter in the configuration file. If you manually set this parameter to True, Certificate System does not remove the client database after the installation.
After you created the initial configuration file, add the subsystem-specific settings to it. See:

CA Settings

In addition to the section called “Subsystem-independent Settings”, you need the following settings to install a CA:
  1. To increase security, enable random serial numbers by adding the [CA] section with the following setting to the configuration file: 
    [CA]
pki_random_serial_numbers_enable=true
  2. Optionally, set the following parameters in the [CA] section to specify the data of the admin user, which will be automatically created during the installation: 
    pki_admin_nickname=caadmin
pki_admin_name=CA administrator account
pki_admin_password=password
pki_admin_uid=caadmin
pki_admin_email=caadmin@example.com
    Certificate System assigns administrator privileges to this account. Use this account after the installation to manage Certificate System and to create further user accounts.
  3. To enable Certificate System to generate unique nicknames, set the following parameters in the [DEFAULT] section: 
    pki_instance_name=instance_name
pki_security_domain_name=example.com Security Domain
pki_host=server.example.com

    Important

    If you install Certificate System with a network-shared Hardware Security Module (HSM), you must use unique certificate nicknames.
  4. Optionally, to use Elliptic Curve Cryptography (ECC) instead of RSA when generating certificates:
    1. Add the following parameters to the [DEFAULT] section: 
      pki_admin_key_algorithm=SHA256withEC
pki_admin_key_size=nistp256
pki_admin_key_type=ecc
pki_sslserver_key_algorithm=SHA256withEC
pki_sslserver_key_size=nistp256
pki_sslserver_key_type=ecc
pki_subsystem_key_algorithm=SHA256withEC
pki_subsystem_key_size=nistp256
pki_subsystem_key_type=ecc
    2. Add the following parameters to the [CA] section: 
      pki_ca_signing_key_algorithm=SHA256withEC
pki_ca_signing_key_size=nistp256
pki_ca_signing_key_type=ecc
pki_ca_signing_signing_algorithm=SHA256withEC
pki_ocsp_signing_key_algorithm=SHA256withEC
pki_ocsp_signing_key_size=nistp256
pki_ocsp_signing_key_type=ecc
pki_ocsp_signing_signing_algorithm=SHA256withEC
    3. Add the following parameters to the [CA] section to override the RSA profiles with ECC profiles: 
      pki_source_admincert_profile=/usr/share/pki/ca/conf/eccAdminCert.profile
pki_source_servercert_profile=/usr/share/pki/ca/conf/eccServerCert.profile
pki_source_subsystemcert_profile=/usr/share/pki/ca/conf/eccSubsystemCert.profile

Settings for Other Subsystems

In addition to the section called “Subsystem-independent Settings”, you need the following settings to install a subordinate CA, KRA, OCSP, TKS, or TPS:
  1. Add the following entry to [DEFAULT] section of your configuration file: 
    pki_client_database_password=password
  2. If you are installing a TPS:
    1. Add the following section with the following section: 
      [TPS]
pki_authdb_basedn=basedn_of_the_TPS_authentication_database
    2. Optionally, to configure that the TPS use server-side key generation utilizing a KRA that has already been installed in the shared CA instance, add the following entry to the [TPS] section: 
      pki_enable_server_side_keygen=True

7.7.4. Starting the Installation Step

After you prepared the configuration file as described in Section 7.7.3, “Creating the Configuration File for the First Step of the Installation”, start the first step of the installation: 
# pkispawn -f /root/config.txt -s subsystem --skip-configuration
Replace subsystem with one of the following subsystems: CA, KRA, OCSP, TKS, or TPS.

7.7.5. Customizing the Configuration Between the Installation Steps

After the installation step described in Section 7.7.4, “Starting the Installation Step” has finished successfully, you can manually update the instance-specific configuration files before the actual configuration begins. This section provides certain examples of what you can customize between the first and second step of the installation.

7.7.5.1. Configuring Certificate Profiles

In many cases, sites would want to customize certain certificate enrollment profiles (e.g. changing the default validity time of certificates), or to add/delete some profiles. For a complete list of options, see Chapter 15, Certificate Profiles Configuration.

7.7.5.2. Enabling Signed Audit Logging

The signed audit logging feature enables the detection of unauthorized log manipulation. For details, see Section 17.3.1, “Enabling and Configuring Signed Audit Log”.

7.7.5.3. Updating the Ciphers List

In certain situations, administrators want to update the ciphers list. For example:
  • To secure the Certificate System instance
  • To install a Certificate System instance and to add it to an existing site that supports only specific ciphers
For details on updating the cipher list, see Section 13.4.1.1.1, “Client TLS cipher Configuration”.

Default FIPS Mode Enabled Ciphers for RSA Encryption

By default, Certificate System contains the following FIPS mode enabled ciphers for RSA encryption:
  • TLS_DHE_RSA_WITH_AES_128_CBC_SHA
  • TLS_DHE_RSA_WITH_AES_128_CBC_SHA256
  • TLS_DHE_RSA_WITH_AES_128_GCM_SHA256
  • TLS_DHE_RSA_WITH_AES_256_CBC_SHA
  • TLS_DHE_RSA_WITH_AES_256_CBC_SHA256
  • TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA
  • TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256
  • TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
  • TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA
  • TLS_RSA_WITH_AES_128_CBC_SHA
  • TLS_RSA_WITH_AES_128_CBC_SHA256
  • TLS_RSA_WITH_AES_256_CBC_SHA
  • TLS_RSA_WITH_AES_256_CBC_SHA256

Default FIPS Mode Enabled Ciphers for ECC Encryption

By default, Certificate System contains the following FIPS mode enabled ciphers for Elliptic Curve Cryptography (ECC) encryption:
  • TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA
  • TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256
  • TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256
  • TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA
  • TLS_RSA_WITH_AES_256_CBC_SHA
  • TLS_RSA_WITH_AES_256_CBC_SHA256

Required RSA Ciphers When Running an HSM on System with FIPS Mode Enabled

If you install Certificate System with either LunaSA or Hardware Security Module (HSM) on systems with FIPS mode enabled for RSA, disable the following ciphers, as they are unsupported on HSMs:
  • TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA
  • TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA
  • TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
  • TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA

7.7.5.4. Configuring the PKI Console Timeout

For details on configuring the PKI console timeout, see the corresponding section in Section 13.4.2, “Session Timeout”.

7.7.5.5. Setting the KRA into Encryption Mode

If you are using a Hardware Security Module (HSM), it is necessary in certain situations to set the Key Recovery Authority (KRA) into encryption mode. For details, see the section called “Setting the KRA into Encryption Mode”.

7.7.5.6. Enabling OCSP

For details about enabling the Online Certificate Status Protocol (OCSP) see Section 13.4.1.3, “Enabling Certificate Revocation Checking for Subsystems”.

7.7.5.7. Configuring Ranges for Requests and Serial Numbers

For details about configuring ranges for requests and serial numbers, see Section 13.2.3.14, “Configuring Ranges for Requests and Serial Numbers”.

7.7.6. Starting the Configuration Step

After you have customized the configuration files according to Section 7.7.5, “Customizing the Configuration Between the Installation Steps”, start the second step of the installation: 
# pkispawn -f /root/config.txt -s subsystem --skip-installation
Replace subsystem with one of the following subsystems: CA, KRA, OCSP, TKS, or TPS.
If the configuration step succeeds, the pkispawn utility displays an installation summary. For example: 
================================================================
                       INSTALLATION SUMMARY
================================================================

  Administrator's username:             caadmin
  Administrator's PKCS #12 file:
        /root/.dogtag/instance_name/ca_admin_cert.p12

  To check the status of the subsystem:
        systemctl status pki-tomcatd@instance_name.service

  To restart the subsystem:
        systemctl restart pki-tomcatd@instance_name.service

  The URL for the subsystem is:
        https://server.example.com:8443/ca/

  PKI instances will be enabled upon system boot

================================================================

7.7.7. Post-Installation

Once you completed the procedures above, follow Section 7.10, “Post-installation Tasks” for additional post-installation actions.