Procedures

The instructions in this guide refer to one server, with two network interfaces and unique IP addresses, on which the Red Hat applications are installed:

Application Domain IP Address

Red Hat Certificate System (RHCS)

pki.domain.com

10.0.0.2

Red Hat Directory Server (RHDS)

ldap.domain.com

10.0.0.3

When you follow the instructions, use the domain names and IP addresses of your system.

Install the Operating System

  1. Install Red Hat Enterprise Linux server on your target server platform or virtualized environment.

    No GUI is required for the installation of RHCS. However, to perform agent functions on the CA, you must use a system with a web browser (Mozilla Firefox is preferred).

  2. If FIPS mode is required, ensure that the system is operating in FIPS mode.

    To enable the cryptographic module self-checks mandated by the Federal Information Processing Standard (FIPS) 140-3, you must operate RHEL 10 in FIPS mode. The only correct way to switch the system to FIPS mode is to enable it during the RHEL installation. For more information, see Switching RHEL to FIPS mode.

  3. Ensure that the system is operating in SELinux enforcing mode:

    % getenforce
    
    Enforcing

    If the result is Permissive or Disabled, you need to enable SELinux before continuing.

    If the status was Permissive:

    1. Make SELinux enforcing on reboot by editing /etc/selinux/config. Change SELINUX=permissive to SELINUX=enforcing.

    2. Set SELinux to enforcing for this session:

      % setenforce 1
    3. Check SELinux status again:

      % getenforce

      It should now show Enforcing.

    If the status was Disabled:

    1. Make SELinux enforcing on reboot by editing /etc/selinux/config. Change SELINUX=disabled to SELINUX=enforcing.

    2. Enable a relabel operation on reboot:

      touch /.autorelabel
    3. Reboot the server.

    4. Check SELinux status again:

      getenforce

      It should now show Enforcing.

  4. Ensure that the firewalld service is enabled and running:

    systemctl enable firewalld
    systemctl start firewalld
  5. Configure the system time zone.
    For example, to use UTC:

    timedatectl set-timezone UTC
    timedatectl set-time "YYYY-MM-DD HH:MM:SS"
    (HH:MM:SS is in 24-hour time)

    If you are using NTP, see the Red Hat Enterprise Linux documentation.

  6. Configure the system hostname:

    hostnamectl set-hostname <pki.domain.com>

    Where <pki.domain.com> is the FQDN of your server.

  7. If you are using the nShield Connect model, configure network interfaces as needed for external access to the RHCS subsystems and for the HSM.
    If you are installing the RHDS component on an external system, a network interface must be able to communicate with that system as well.
    For instructions on configuring the network interfaces for your system, for example by using nmcli, see the Red Hat Enterprise Linux documentation.

    For example:

    1. Modify ens33 so that its IP address is 10.0.0.2:

      nmcli connection modify ens33 connection.autoconnect yes \
        ipv4.method manual ipv6.method auto \
        ipv4.addresses 10.0.0.2/24 ipv4.gateway 10.0.0.1 ipv4.dns 10.0.0.1
    2. Add a second IP address, 10.0.0.3, to ens33:

      nmcli connection modify ens33 connection.autoconnect yes \
        ipv4.method manual ipv6.method auto \
        +ipv4.addresses 10.0.0.3/24 +ipv4.gateway 10.0.0.1 +ipv4.dns 10.0.0.1
      nmcli connection up ens33
  8. If you are not using DNS, configure /etc/hosts to include any aliases that might be used for the RHCS and RHDS subsystems.

    If DNS or /etc/hosts is not configured to resolve the applicable hostnames, services, especially RHDS, might hang for a long time when they are started.

    The following is an example configuration, assuming the CA and LDAP are on separate servers:

    127.0.0.1 localhost
    10.0.0.2 pki.domain.com pki
    10.0.0.3 ldap.domain.com ldap
  9. Register the system:

    sudo subscription-manager register
  10. Configure the ulimits for the OS by adding the following lines to the end of the /etc/security/limits.conf file:

    root soft nofile 65536
    root hard nofile 65536
  11. Configure any system security settings and lockdown procedures, such as screensaver settings, to ensure that the system is secure before generating the CA private key(s).

Configure the HSM

Install the HSM by following the instructions in the Installation Guide for the HSM.

Install the nShield Security World software

To install the Security World software and create the Security World:

  1. Uninstall any existing Security World software before installing the new Security World software.

  2. Install the latest version of the Security World software as described in the User Guide for the HSM.

Enroll the new HSM client with the HSM

  1. Enroll the client:

    • For a privileged client, such as the RFS, if enrolling as a client:

      nethsmenroll --privileged HSM_IP_ADDRESS
    • For an unprivileged client, which includes most application servers, such as a CA or an OCSP responder:

      nethsmenroll HSM_IP_ADDRESS
  2. Verify enrollment with the enquiry command:

    enquiry -m 1

Configure cknfastrc for RHCS

  1. Configure the /opt/nfast/cknfastrc file with the following settings:

    Key Protection Mechanism CKNFASTRC Configuration Parameters

    Module protection

    N/A: RHCS does not support this option

    Softcard protection

    CKNFAST_OVERRIDE_SECURITY_ASSURANCES=wrapping_crypt

    CKNFAST_LOADSHARING=1

    CKNFAST_NO_ACCELERATOR_SLOTS=1

    OCS protection

    (K-of-N with k=1)

    CKNFAST_OVERRIDE_SECURITY_ASSURANCES=wrapping_crypt

    CKNFAST_LOADSHARING=1

    CKNFAST_NO_ACCELERATOR_SLOTS=1

    OCS protection

    (K-of-N with k > 1)

    CKNFAST_OVERRIDE_SECURITY_ASSURANCES=wrapping_crypt

    CKNFAST_LOADSHARING=1

    CKNFAST_NO_ACCELERATOR_SLOTS=1

    NFAST_NFKM_TOKENSFILE=/opt/nfast/nfast-nfkm-tokensfile

  2. To troubleshoot the CA installation, check the following logs:

    • RHCS logs, in /var/log/pki/<instance>.

    • nShield hardserver logs, in /opt/nfast/log/hardserver.log.

Create or load a Security World

  1. Initialize a Security World as described in the User Guide for the HSM.

    The decision to create a new Security World or to load an existing Security World is based on your organization’s security practices.

Create an OCS or Softcard to protect the application keys

If you already have an OCS or a Softcard to use from an existing Security World:

  1. Make sure that the appropriate card or Softcard files are in /opt/nfast/kmdata/local.

  2. Continue with the instructions in Install RHDS.

Method #1: Create an OCS

This createocs command is an example. Use parameters that satisfy your organization’s security requirements.

  1. Use the following parameters to create a new OCS:

    • K-of-N defined as 1/3.

    • No time-out.

    • Persistent card set.

    • Do not name cards individually.

    • Enable PIN recovery.

    • Pick a name for your OCS. The example below uses OCS1.

      createocs -m 1 -N "OCS1" -Q 1/3 -T 0 --persist --pp-recovery
  2. If you are using a FIPS 140 Level 3 Security World, you need to present an ACS or OCS card for FIPS authorization.

  3. Enter a password for each OCS card in the quorum. Each card can have a unique password, but this is not recommended for most use cases.

  4. Verify that the OCS card set is visible:

    nfkminfo -c

Method #2: Create a Softcard

This ppmk command is an example. Use parameters that satisfy your organization’s security requirements.
  1. Create a new Softcard:

    • If you are using a FIPS 140 Level 3 Security World, you need to present an ACS or OCS to provide FIPS authentication.

  2. Pick a name for your Softcard. The example below uses SOFTCARD1.

  3. Make the Softcard container recoverable.

    ppmk --new --recoverable SOFTCARD1
  4. Verify that the Softcard was created:

    ppmk --list

Copy KMDATA files to other HSM client systems

The Security World files are located in the /opt/nfast/kmdata/local folder on the system where they were generated.

To use the Security World on other HSM clients, copy the following KMDATA files from /opt/nfast/kmdata/local to your other HSM clients:

  • world

  • cards_*

  • card_*

  • softcard_*

  • module_*

You can copy the files manually, using tools such as rsync or scp, or by configuring the rfs-sync capability of the nShield tools.

For information on configuring and using rfs-sync, see the User Guide for your HSM.

Install RHDS

You need the Red Hat Directory Server packages from the appropriate Red Hat Network channel. Some packages are in the RHEL OS channel, and some are in the RHDS channel. For instructions to install these packages, see the Red Hat Directory Server documentation.

These steps use the instance name ca-1. Entrust recommends that you use a more descriptive identifier to suit the requirements of your organization. It is most convenient to name the RHDS instance the same as the RHCS instance, especially if you plan to create multiple instances of either on their respective servers.

For instructions to enable LDAPS on the directory server before installing RHCS, see the Red Hat Directory Server documentation. There are generally two methods for this:

  • Existing CA:
    Create a TLS key/request and have the certificate signed by an already deployed CA, if one exists.

  • New CA:

    1. Create a TLS key/request.

    2. Self-sign it for temporary use in the LDAP server until the new RHCS CA is deployed.

    3. Re-sign the TLS certificate request on the new RHCS CA.

    4. Remove the self-signed certificate from the LDAP server’s NSS database.

    5. Install the new TLS certificate along with the new CA chain.

In the following steps, the RHDS instance is installed on the same system as RHCS. However, you can install them on separate servers.
  1. Enable the default RHEL repositories:

    sudo subscription-manager repos \
    	--enable=rhel-10-for-x86_64-appstream-rpms \
    	--enable=rhel-10-for-x86_64-baseos-rpms
  2. Enable the default Directory Server repository:

    sudo subscription-manager repos --enable=dirsrv-13-for-rhel-10-x86_64-rpms
  3. Install the RHDS packages and dependencies:

    sudo dnf install redhat-ds
  4. Check the installation:

    sudo subscription-manager list
    
    +-------------------------------------------+
        Installed Product Status
    +-------------------------------------------+
    Product Name: Red Hat Directory Server
    Product ID:   200
    Version:      13.2
    Arch:         x86_64
    
    Product Name: Red Hat Enterprise Linux for x86_64
    Product ID:   479
    Version:      10.2
    Arch:         x86_64
  5. Open the ports in the appropriate firewall zone:

    firewall-cmd --permanent --add-port={389/tcp,636/tcp} --zone=<zone>
    firewall-cmd --reload
  6. Configure the LDAP service account group:

    groupadd -r ldap
  7. Configure the LDAP service account user:

    useradd -g ldap ldap-ca-1
  8. Configure RHDS:

    % dscreate interactive
    
    # Here is an example:
    
    Enter system's hostname [pki.domain.com]: ldap.domain.com
    
    Enter the instance name [ldap]: ca-1
    
    Enter port number [389]:
    
    Create self-signed certificate database [yes]:
    
    Enter secure port number [636]:
    
    Enter Directory Manager DN [cn=Directory Manager]:
    
    Enter the Directory Manager password:
    Confirm the Directory Manager Password:
    
    Choose whether mdb or bdb is used. [mdb]:
    
    Enter the lmdb database size [20.0 GB]:
    
    Enter the database suffix (or enter "none" to skip) [dc=ldap,dc=domain,dc=com]: o=ca-1-CA
    
    Create sample entries in the suffix [no]:
    
    Create just the top suffix entry [no]:
    
    Do you want to start the instance after the installation? [yes]:
    
    Are you ready to install? [no]: yes
    Starting installation ...
    Validate installation settings ...
    Create file system structures ...
    Create self-signed certificate database ...
    Perform SELinux labeling ...
    Create database backend: o=ca-1-CA ...
    Perform post-installation tasks ...
    Completed installation for instance: slapd-ca-1

    You can control the RHDS instance with the following commands.

    Function Command

    Enable on boot

    systemctl enable dirsrv@<RHCS-instance>

    Start manually

    systemctl start dirsrv@<RHCS-instance>

    Stop manually

    systemctl stop dirsrv@<RHCS-instance>

    Restart manually

    systemctl restart dirsrv@<RHCS-instance>

  9. Test the RHDS connection:

    % sudo ldapsearch -o ldif-wrap=no -x -LLL \
      -H ldap://ldap.domain.com:389 \
      -D 'cn=Directory Manager' -W \
      -b 'cn=config' -s base '(objectclass=*)' \
      nsslapd-versionstring nsslapd-defaultnamingcontext
    
    Enter LDAP Password:
    dn: cn=config
    nsslapd-versionstring: 389-Directory/3.2.0
    nsslapd-defaultnamingcontext: o=ca-1-ca

Install RHCS

You need the Red Hat Certificate System packages from the appropriate Red Hat Network channel. The CA and KRA subsystems are part of the RHEL OS channel, but the TKS and TPS subsystems require access to the Red Hat Certificate System channel. Many dependency packages must be installed along with the RHCS packages, including apache/httpd and apache/tomcat. For package installation instructions, see the Red Hat Certificate System documentation.

The various subsystems for Red Hat Certificate System are installed and configured individually. The initial installation is performed using package management tools such as dnf. Each subsystem is set up with the pkispawn command-line tool.

Install the packages

The redhat-pki package installs packages to support all RHCS subsystems.

  1. Enable the repository:

    sudo subscription-manager repos --enable=certsys-11.0-for-rhel-10-x86_64-rpms
  2. Install the Certificate System packages:

    sudo dnf install redhat-pki
  3. Check the installation:

    sudo subscription-manager list
    
    +-------------------------------------------+
        Installed Product Status
    +-------------------------------------------+
    Product Name: Red Hat Directory Server
    Product ID:   200
    Version:      13.2
    Arch:         x86_64
    
    Product Name: Red Hat Certificate System
    Product ID:   216
    Version:      11.0
    Arch:         x86_64
    
    Product Name: Red Hat Enterprise Linux for x86_64
    Product ID:   479
    Version:      10.2
    Arch:         x86_64
  4. Restore the SELinux context on /opt/nfast to account for the new pki-selinux policy:

    sudo restorecon -FRvv /opt/nfast
    Ensure that your RHEL OS packages are updated, in particular httpd, tomcat, and nss. RHCS packages do not always have the correct dependency versions, and sometimes key generation might fail because nss needs to be updated to the latest version.
  5. Restart the nfast hardserver:

    sudo /opt/nfast/sbin/init.d-ncipher restart

Check the PKCS #11 connection to the HSM

Check with Mozilla NSS database tools

  1. Create the temporary NSS database:

    sudo mkdir -p /opt/tempnssdb
    cd /opt/tempnssdb
    sudo modutil -dbdir . -create -force
  2. Add the nShield PKCS #11 library to the temporary NSS database:

    modutil -dbdir . -add nfast \
      -libfile /opt/nfast/toolkits/pkcs11/libcknfast.so -force
    Module "nfast" added to database.
  3. After the NSS database is created and linked to the HSM, check the PKCS #11 token information with the RHCS tools:

    % sudo TokenInfo .
    
    Database Path: .
    Found external module 'NSS Internal PKCS #11 Module'
    Found external module 'nfast'
    Found external module 'p11-kit-proxy'
    Found external token 'testSC'
  4. Remove the temporary NSS database:

    sudo rm -rf /opt/tempnssdb

Check using HSM tools

Use the ckcheckinst command to test the PKCS #11 installation with nShield tools. This example uses an OCS. Modify it if you are using Softcard protection.

In some cases, ckcheckinst might fail. However, this does not necessarily indicate a system configuration problem. Consult Entrust nShield Support if necessary.
sudo /opt/nfast/bin/ckcheckinst

PKCS#11 library interface version 3.2
                            flags 0
                   manufacturerID "nCipher Corp. Ltd               "
               libraryDescription "nCipher PKCS#11 13.9.6-628-875bd"
           implementation version 13.09
         Loadsharing and Failover enabled

Slot  Status            Label
====  ======            =====
   0  Operator card     "testOCS2                        "

Select slot number to run library test or 'R'etry or to 'E'xit: 0
Using slot number 0.

Please enter the passphrase for this token (No echo set).
Passphrase:

Test                      Pass/Failed
----                      -----------

1 Generate RSA key pair   Pass
2 Generate DSA key pair   Pass
3 Encryption/Decryption   Pass
4 Signing/Verification    Pass

Deleting test keys         ok

PKCS#11 library test successful.

Configure the firewall

  1. Open ports to support RHCS functions. These ports are the default for RHCS. If you plan to use non-default ports, add those ports to the firewall instead of the ones listed in this table.

    Service Port

    CA HTTP Proxy

    8080/tcp

    CA HTTPS Proxy

    8443/tcp

    CA Security Domain

    8443/tcp

    CA Tomcat Server

    8005/tcp

    CA AJP

    8009/tcp

  2. Configure the firewall:

    sudo firewall-cmd --permanent --add-port={8080/tcp,8443/tcp,8005/tcp,8009/tcp}
    sudo firewall-cmd --reload

Configure service account users and groups

Create the appropriate user and group accounts before staging the system.

Members of the pkiadmin system group have full access to tasks in the agent service interface:

groupadd -r pkiadmin

Members of the pkiaudit system group can read the signed audit logs.

groupadd -r pkiaudit

To create a new service account user and assign it to the nfast, pkiadmin, and pkiaudit groups:

useradd -g pkiuser -G nfast,pkiadmin,pkiaudit \
  -d /usr/share/pki -s /sbin/nologin \
  -c "RHCS ca-1" -r pkiuser-ca-1

Pre-configure the RHCS instance

Run pkispawn for an initial creation phase so you can pre-configure parameters, such as certificate distinguished names and validity periods. For information on the two-step installation, see the RHCS Installation Guide.

Do not modify /usr/share/pki/server/etc/default.cfg directly.
  1. Create a copy of /usr/share/pki/server/etc/default.cfg, for example, at /opt/pkispawn.cfg.

  2. Modify it to match your system.

    For information on how to modify the default configuration file, see:

    • Configure pkispawn.

    • man 5 pki_default.cfg.

    • Red Hat Certificate System Planning, Installation, and Deployment Guide.

If you are using a FIPS Level 3 world file, have an OCS card connected to provide FIPS authorization. For post-quantum keys, use the PQ ML-DSA-XX algorithms in the configuration. Update the /opt/nfast/cknfastrc file according to the protection method that you are using.
  1. Generate an INF for subsystem setup.

    If you are using OCS-protected keys and K>1, use the preload command with pkispawn:

    sudo preload -m <module number> -f "<preload FilePath>" \
      --cardset-name=<OCS Cardset-Name> \
      pkispawn -f /path/to/pkispawn.cfg -s CA --skip-configuration

    Insert the OCS cards and, if prompted, enter the OCS passphrase.

    For other OCS scenarios and other protection methods, run pkispawn on its own:

    sudo pkispawn -f /path/to/pkispawn.cfg -s CA --skip-configuration
  2. At this point, you can modify any of the pre-configuration files as necessary. See the information on two-step installation in the RHCS Installation Guide.

The output of the pkispawn commands above should resemble the following:

Loading deployment configuration from /opt/pkispawn.cfg.
Installing CA into /var/lib/pki/ca-1.
Created symlink '/etc/systemd/system/pki-tomcatd.target.wants/pki-tomcatd@ca-1.service' → '/usr/lib/systemd/system/pki-tomcatd@.service'.

    ==========================================================================
                                INSTALLATION SUMMARY
    ==========================================================================

      The CA subsystem of the 'ca-1' instance
      must still be configured!

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

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

      The URL for the subsystem is:
            https://pki.domain.com:8443/ca

      PKI instances will be enabled upon system boot

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

Configure the CA instance

Determine whether you are creating a root CA or a subordinate (issuing) CA, then define an appropriate configuration file for pkispawn by using one of the following procedures:

Create a root CA

Set pki_external=False for the pkispawn.cfg file so that pkispawn self-signs the caSigningCert object.

If you are using OCS-protected keys and K>1, use the preload command with pkispawn:

preload -m <module number> -f "<preload FilePath>" \
  --cardset-name=<OCS Cardset-Name> \
  pkispawn -s CA --debug -f /path/to/pkispawn.cfg --skip-installation

Insert the OCS cards and, if prompted, enter the OCS passphrase.

For other OCS scenarios and other protection methods, run the single-phase pkispawn on its own:

pkispawn -s CA --debug -f /path/to/pkispawn.cfg --skip-installation

The output should resemble the following:

...
...
    ==========================================================================
                                INSTALLATION SUMMARY
    ==========================================================================

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

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

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

      The URL for the subsystem is:
            https://pki.domain.com:8443/ca

      PKI instances will be enabled upon system boot

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

Check the status of the deployment

  1. Check the status of the service:

    sudo systemctl status pki-tomcatd@ca-1.service
    
         Loaded: loaded (/usr/lib/systemd/system/pki-tomcatd@.service; enabled; preset: disabled)
         Active: active (running) since Tue 2026-10-13 20:36:44 UTC; 4min 26s ago
     Invocation: 165b7b2f63644a30afdbbc309a536f3a
        Process: 42121 ExecStartPre=/usr/sbin/pki-server upgrade ca-1 (code=exited, status=0/SUCCESS)
        Process: 42123 ExecStartPre=/usr/sbin/pki-server migrate ca-1 (code=exited, status=0/SUCCESS)
        Process: 42176 ExecStartPre=/usr/bin/pkidaemon start ca-1 (code=exited, status=0/SUCCESS)
       Main PID: 42194 (java)
          Tasks: 95 (limit: 22820)
         Memory: 216.7M (peak: 218.4M)
            CPU: 17.428s
         CGroup: /system.slice/system-pki\x2dtomcatd.slice/pki-tomcatd@ca-1.service
                 └─42194 /usr/lib/jvm/jre-21-openjdk/bin/java -Dcom.redhat.fips=false -Dredhat.crypto-policies=false --add-opens=java.base/j>
    
    Oct 13 20:36:50 pki.domain.com pki-tomcat-start[42194]: SLF4J: Found binding in [jar:file:/usr/share/pki/server/webapps/pki/>
    Oct 13 20:36:50 pki.domain.com pki-tomcat-start[42194]: SLF4J: Found binding in [jar:file:/usr/share/pki/lib/slf4j-jdk14-1.7>
    Oct 13 20:36:50 pki.domain.com pki-tomcat-start[42194]: SLF4J: See http://www.slf4j.org/codes.html#multiple_bindings for an >
    Oct 13 20:36:50 pki.domain.com pki-tomcat-start[42194]: SLF4J: Actual binding is of type [org.slf4j.impl.JDK14LoggerFactory]
    Oct 13 20:36:51 pki.domain.com pki-tomcat-start[42194]: SLF4J: Class path contains multiple SLF4J bindings.
    Oct 13 20:36:51 pki.domain.com pki-tomcat-start[42194]: SLF4J: Found binding in [jar:file:/usr/share/pki/ca/webapps/ca/WEB-I>
    Oct 13 20:36:51 pki.domain.com pki-tomcat-start[42194]: SLF4J: Found binding in [jar:file:/usr/share/pki/lib/slf4j-jdk14-1.7>
    Oct 13 20:36:51 pki.domain.com pki-tomcat-start[42194]: SLF4J: See http://www.slf4j.org/codes.html#multiple_bindings for an >
    Oct 13 20:36:51 pki.domain.com pki-tomcat-start[42194]: SLF4J: Actual binding is of type [org.slf4j.impl.JDK14LoggerFactory]
    Oct 13 20:36:55 pki.domain.com pki-tomcat-start[42194]: Enter password for testOCS
  2. Get the status over HTTPS:

    curl -k https://pki.domain.com:8443/ca/admin/ca/getStatus
    
    {
      "Response" : {
        "State" : "1",
        "Type" : "CA",
        "Status" : "running",
        "Version" : "11.10.1",
        "ProductVersion" : "Red Hat Certificate System 11.0.0"
      }
  3. List the certificates:

    sudo pki-server cert-find -i ca-1
    
      Cert ID: ca_signing
      Nickname: caSigningCert cert-ca-1 CA
      Token: testSC
      Serial Number: 0x87a66228bb8f66fb571cfe1d258f94e0
      Subject DN: CN=CA Signing Certificate,OU=ca-1,O=domain.com Security Domain
      Issuer DN: CN=CA Signing Certificate,OU=ca-1,O=domain.com Security Domain
      Not Valid Before: Tue Oct 13 20:34:36 2026
      Not Valid After: Sat Oct 13 20:34:36 2046
      Trust Flags: CTu,Cu,Cu
    
      Cert ID: ca_ocsp_signing
      Nickname: ocspSigningCert cert-ca-1 CA
      Token: testSC
      Serial Number: 0xe216f7bbbdb54cdf05d90db71aa32bb9
      Subject DN: CN=CA OCSP Signing Certificate,OU=ca-1,O=domain.com Security Domain
      Issuer DN: CN=CA Signing Certificate,OU=ca-1,O=domain.com Security Domain
      Not Valid Before: Tue Oct 13 20:34:49 2026
      Not Valid After: Mon Oct 02 20:34:49 2028
      Trust Flags: u,u,u
    
      Cert ID: sslserver
      Nickname: Server-Cert cert-ca-1
      Token: testSC
      Serial Number: 0x37043749d9d02a5a93b04afe550b28a5
      Subject DN: CN=pki.domain.com,OU=ca-1,O=domain.com Security Domain
      Issuer DN: CN=CA Signing Certificate,OU=ca-1,O=domain.com Security Domain
      Not Valid Before: Tue Oct 13 20:35:04 2026
      Not Valid After: Mon Oct 02 20:35:04 2028
      Trust Flags: u,u,u
    
      Cert ID: subsystem
      Nickname: subsystemCert cert-ca-1
      Token: testSC
      Serial Number: 0x38294671b44b6bd3e626699ee0b25f6a
      Subject DN: CN=Subsystem Certificate,OU=ca-1,O=domain.com Security Domain
      Issuer DN: CN=CA Signing Certificate,OU=ca-1,O=domain.com Security Domain
      Not Valid Before: Tue Oct 13 20:35:19 2026
      Not Valid After: Mon Oct 02 20:35:19 2028
      Trust Flags: u,u,u
    
      Cert ID: ca_audit_signing
      Nickname: auditSigningCert cert-ca-1 CA
      Token: testSC
      Serial Number: 0xe964d7f84b22933facff0a015f435a44
      Subject DN: CN=CA Audit Signing Certificate,OU=ca-1,O=domain.com Security Domain
      Issuer DN: CN=CA Signing Certificate,OU=ca-1,O=domain.com Security Domain
      Not Valid Before: Tue Oct 13 20:35:34 2026
      Not Valid After: Mon Oct 02 20:35:34 2028
      Trust Flags: u,u,Pu
  4. List the keys in the HSM:

    % nfkminfo -k
    
    Key list - 10 keys
     AppName pkcs11               Ident umedb3d45a28e5a6b22b033684ce589d9e198272c2-2ab64e740db29dbb9d04861f0598cf8c76e2a8d5
     AppName pkcs11               Ident ucedb3d45a28e5a6b22b033684ce589d9e198272c2-754c792a76eca7fdf47817e4e74909701a68562d
     AppName pkcs11               Ident umedb3d45a28e5a6b22b033684ce589d9e198272c2-ae962c4c96cb108dc02f42d25ee8235bbb023c97
     AppName pkcs11               Ident umedb3d45a28e5a6b22b033684ce589d9e198272c2-17c72cdb1633e7a48cfe8fc5f69180207590d0e7
     AppName pkcs11               Ident ucedb3d45a28e5a6b22b033684ce589d9e198272c2-178aed468a4117359991d6e997c5461d8be64202
     AppName pkcs11               Ident ucedb3d45a28e5a6b22b033684ce589d9e198272c2-0f95a22faeee7d8cc72824da91c49c9adcea097a
     AppName pkcs11               Ident umedb3d45a28e5a6b22b033684ce589d9e198272c2-7c0ce91f4aa02d6c303eee1676ddea2840ac492f
     AppName pkcs11               Ident ucedb3d45a28e5a6b22b033684ce589d9e198272c2-06c390b93003a4e524a7a1675f48f272c78d352d
     AppName pkcs11               Ident umedb3d45a28e5a6b22b033684ce589d9e198272c2-2df90386487d1ba092d1ba732d650dc386631ca8
     AppName pkcs11               Ident ucedb3d45a28e5a6b22b033684ce589d9e198272c2-b27910037cb4446c2dbf1edc38bfa361a8d4f33b
    
    % rocs
    `rocs' key recovery tool
    Useful commands: `help', `help intro', `quit'.
    rocs> list keys
      No. Name                     App        Protected by
        1 subsystemCert cert-ca-1  pkcs11     module (testOCS)
        2 Id: ucedb3d45a28e5a6b22b pkcs11     testOCS
        3 auditSigningCert cert-ca pkcs11     module (testOCS)
        4 caSigningCert cert-ca-1  pkcs11     module (testOCS)
        5 Id: ucedb3d45a28e5a6b22b pkcs11     testOCS
        6 Id: ucedb3d45a28e5a6b22b pkcs11     testOCS
        7 ocspSigningCert cert-ca- pkcs11     module (testOCS)
        8 Id: ucedb3d45a28e5a6b22b pkcs11     testOCS
        9 Server-Cert cert-ca-1    pkcs11     module (testOCS)
       10 Id: ucedb3d45a28e5a6b22b pkcs11     testOCS
  5. Show the keys and their types:

    % sudo certutil -K -d /var/lib/pki/ca-1/conf/alias -h testSC
    
    certutil: Checking token "testSC" in slot "testSC"
    Enter Password or Pin for "testSC":
    < 0> mldsa    0d042533ce18dfa507dcb14c2a138b97e62a6d3c   testSC:caSigningCert cert-ca-1 CA
    < 1> mldsa    0e047b7e72386d949eadb38cada850008a6ef925   testSC:ocspSigningCert cert-ca-1 CA
    < 2> rsa      ed81516b98f6987dd0676b6cdb15589c09c3b373   testSC:Server-Cert cert-ca-1
    < 3> mldsa    351f7282fae4138eda8e5d603017cbfe06791c24   testSC:subsystemCert cert-ca-1
    < 4> mldsa    6c8e384a7fa533d6e356fe7ba79b08b617db89d9   testSC:auditSigningCert cert-ca-1 CA

Create a subordinate or issuing CA

Set pki_external=True for the pkispawn.cfg file so that pkispawn does not self-sign the caSigningCert object, but instead creates a PKCS #10 certificate request file for an external root CA to sign.
  1. Set the pki_external_step_two parameter to false in the pkispawn.cfg file.

  2. Run pkispawn phase 1:

    pkispawn -s CA --debug -f /path/to/pkispawn.cfg --skip-installation
  3. Sign the certificate request generated at the end of phase 1, and put it in /etc/pki/<instance>/alias/<instance>_caSigningCert.cer.

  4. Put the CA chain PKCS #7 in /etc/pki/<instance>/alias/caChain.p7c.

    This file should not include the new subordinate CA’s certificate, only the signing CA hierarchy.

  5. Change the pki_external_step_two parameter to true in pkispawn.cfg.

  6. Run pkispawn phase 2.

    If you are using OCS-protected keys and K>1, use the preload command with pkispawn:

    preload -m <module number> -f "<preload FilePath>" \
      --cardset-name=<OCS Cardset-Name> \
      pkispawn -s CA --debug -f /path/to/pkispawn.cfg

    Insert the OCS cards and, if prompted, enter the OCS passphrase.

    For other OCS scenarios and other protection methods, run pkispawn on its own:

    pkispawn -s CA --debug -f /path/to/pkispawn.cfg

Configure the CA and CRL profiles

Restart the CA service after modifying profiles or modifying /etc/pki/<instance>/ca/CS.cfg.

RHCS instance control commands

If you are using OCS-protected keys and K>1:

  1. Open another terminal.

  2. Run the following command:

    preload -m <module number> -f "<preload FilePath>" \
      --cardset-name=<OCS Cardset-Name> pause
  3. Insert the OCS cards and, if prompted, enter the OCS passphrase.

  4. Leave the preload command paused until you have finished running the control commands that you intend to run, for example systemctl start or systemctl restart. This might take a minute or two. Before you cancel the preload command, check the CA web page to ensure that the system is up and running.

Function Command

Enable on boot

Do not use. The service fails because it needs the OCS passphrase to unlock the CA private signing key.

Start manually

systemctl start pki-tomcatd@<instance>

Stop manually

systemctl stop pki-tomcatd@<instance>

Check status

systemctl status pki-tomcatd@<instance>

pkidaemon status <instance>

Import the CA chain and user credentials into Firefox

Launch Firefox.

If this is a subordinate CA, manually import the external certificates in the CA chain:

  1. Navigate to the drop-down menu in the upper-right corner (three horizontal bars).

  2. Navigate to Preferences > Privacy and Security.

  3. Scroll down to Certificates, and select View Certificates.

  4. On the Authorities tab, select Import to import the CA chain certificates into the store.

    Repeat for each certificate in the external trust chain.

  5. Configure certificate trust:

    1. If prompted during import, select all the options to trust the certificate for various activities.

    2. On the Authorities tab, find your CA certificate in the list organized by the organization name specified during installation. Select Edit Trust, select all of the options to trust the root certificate, and select OK.

    3. Repeat for each certificate that was imported.

  6. Select OK.

To import the CA’s own chain, for both root and sub CA types:

  1. Navigate to the Retrieval tab on the end-entity page.

  2. Select the Import CA Certificate Chain link.

  3. Select Import the CA certificate chain into your browser, and select Submit.

  4. Select all of the trust options, and select OK.

To import the default agent’s credential for both root and sub CA types:

  1. Navigate to the drop-down menu in the upper-right corner (three horizontal bars).

  2. Navigate to Preferences > Privacy and Security.

  3. Scroll down to Certificates, and select View Certificates.

  4. On the Your Certificates tab, select Personal, then select Import.

  5. Navigate to the folder in which your default agent credential was created, for example /etc/pki/<instance>/agent_alias, and select the admin PKCS #12 file that is located there.

  6. Enter the PKCS #12 passphrase defined in the pkispawn configuration and select OK.

  7. Select OK to close View Certificates.

Basic system tests

CA application URLs

The following table lists the application URLs, using pki.domain.com as an example:

Web Site URL

Unsecure URL

http://<pki.domain.com>:8080/ca/ee/ca

Secure Agent URL

https://<pki.domain.com>:8443/ca/agent/ca

Secure EE URL

https://<pki.domain.com>:8443/ca/ee/ca

Secure Admin URL

https://<pki.domain.com>:8443/ca/services

Test the CA functionality

  1. Open a web browser from the CA.

  2. Open the Secure Agent URL.

  3. Choose the appropriate agent certificate, then select OK.

  4. Enter the Firefox security database password if it is configured.

  5. Navigate to Update Revocation List.

  6. Ensure that Issuing Point is set to MasterCRL.

  7. Select the appropriate Signature Algorithm. The default is likely to change when you configure /etc/pki/<instance>/ca/CS.cfg, but for testing, select the algorithm that you plan to use in the final configuration.

  8. Create a new CRL:

    1. Select Update.

    2. When the Certification Revocation List Update has been scheduled, check the CS logs for the results.

  9. Select the link on the left for Display Revocation List.

  10. Ensure that Issuing Point is set to MasterCRL.

  11. Ensure that Display Type is set to Entire CRL.

  12. Select Display to view the new CRL.

  13. To verify the CRL, check that its timestamp is within the last minute.