7.6. 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 run the installation of a subsystem in two steps.

7.6.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.6.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, pkispwan sets the settings based on values defined in the deployment configuration file.
    This part of the installation contains the following substeps:
    1. Section 7.6.3, “Creating the Configuration File for the First Step of the Installation”
    2. Section 7.6.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.6.5, “Customizing the Configuration Between the Installation Steps”
    2. Section 7.6.6, “Starting the Configuration Step”

7.6.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/ECadminCert.profile
pki_source_servercert_profile=/usr/share/pki/ca/conf/ECserverCert.profile
pki_source_subsystemcert_profile=/usr/share/pki/ca/conf/ECsubsystemCert.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.6.4. Starting the Installation Step

After you prepared the configuration file as described in Section 7.6.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.6.5. Customizing the Configuration Between the Installation Steps

After the installation step described in Section 7.6.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.6.5.1. Disabling Certificate Profiles

In certain situations, administrators want to disable unused enrollment profiles on the Certificate Authority (CA). To disable a certificate profile, edit the corresponding *.cfg file in the /var/lib/pki/instance_name/ca/profiles/ca/ directory and set the visible and enable parameters to false.
To disable all non-CMC profiles:
  1. List all non-CMC profiles: 
    # ls -l /var/lib/pki/instance_name/ca/profiles/ca/ | grep -v "CMC"
  2. In each of the displayed files, set the following parameters to false: 
    visible=false
enable=false
Optionally, set visible=false in all CMC profiles to make them invisible on the end entity page:
  1. List all CMC profiles: 
    # ls -l /var/lib/pki/instance_name/ca/profiles/ca/*CMC*
  2. In each of the displayed files, set: 
    visible=false

7.6.5.2. Changing the Default Validity Time of Certificates

In each profile on a Certificate Authority (CA), you can set how long certificates issued using a profile are valid. You can change this value for security reasons.
For example, to set the validity of the generated Certificate Authority (CA) signing certificate to 825 days (approximately 27 months), open the /var/lib/pki/instance_name/ca/profiles/ca/caCACert.cfg file in an editor and set: 
policyset.caCertSet.2.default.params.range=825

7.6.5.3. Enabling Signed Audit Logging

The signed audit logging feature enables the prevention of unauthorized log manipulation.

Note

Enable signed audit logging to improve security.
To enable signed audit logging, open the /var/lib/pki/instance_name/subsystem/conf/CS.cfg file in an editor and set: 
log.instance.SignedAudit.logSigning=true
log.instance.SignedAudit.signedAuditCertNickname=audit_signing_certificate
Optionally, configure an audit filter. For details, see the Filtering Audit Events section in the Red Hat Certificate System Administration Guide. After you configured audit filtering, do not restart Certificate System at this point of the installation.

7.6.5.4. 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 the corresponding section in the Red Hat Certificate System Administration Guide.

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 Thales 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.6.5.5. Configuring the PKI Console Timeout

For details, see the corresponding section in the Red Hat Certificate System Administration Guide.
Follow the procedure, but make sure to skip the steps that stop and start Certificate System.

7.6.5.6. 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 Red Hat Certificate System Administration Guide.

7.6.5.7. Enabling OCSP

For details about enabling the Online Certificate Status Protocol (OCSP) see Enabling Revocation Checking in the Red Hat Certificate System Administration Guide.

7.6.5.8. Configuring Ranges for Requests and Serial Numbers

Specify the ranges Certificate System will use for requests and serial numbers in the /etc/pki/instance_name/subsystem/CS.cfg file: 
dbs.beginRequestNumber=1001001007001
dbs.endRequestNumber=11001001007000
dbs.requestIncrement=10000000000000
dbs.requestLowWaterMark=2000000000000
dbs.requestCloneTransferNumber=10000
dbs.requestDN=ou=ca, ou=requests
dbs.requestRangeDN=ou=requests, ou=ranges
dbs.beginSerialNumber=1001001007001
dbs.endSerialNumber=11001001007000
dbs.serialIncrement=10000000000000
dbs.serialLowWaterMark=2000000000000
dbs.serialCloneTransferNumber=10000
dbs.serialDN=ou=certificateRepository, ou=ca
dbs.serialRangeDN=ou=certificateRepository, ou=ranges
dbs.beginReplicaNumber=1
dbs.endReplicaNumber=100
dbs.replicaIncrement=100
dbs.replicaLowWaterMark=20
dbs.replicaCloneTransferNumber=5
dbs.replicaDN=ou=replica
dbs.replicaRangeDN=ou=replica, ou=ranges
dbs.ldap=internaldb
dbs.newSchemaEntryAdded=true

Note

Certificate System supports BigInteger values for the ranges.

7.6.6. Starting the Configuration Step

After you have customized the configuration files according to Section 7.6.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

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