Install Red Hat Certificate System and deploy the subsystem

This tutorial walks system administrators through installing Red Hat Certificate System (RHCS), configuring SELinux for CryptoHub integration, preparing a pkispawn override file, deploying a CA subsystem, and importing the administrator certificate. It also includes browser configuration for access.

Install RHCS

Perform the following steps to install Red Hat Certificate System and prerequisites:

RHCS requires Red Hat Directory Server (RHDS), which serves as an internal repository for certificate requests, certificates, and so on. Enable the RHCS and RHDS repositories with the following command:

subscription-manager repos \\
      \--enable=certsys-10.8-for-rhel-8-x86\_64-rpms \\
      \--enable=dirsrv-11-for-rhel-8-x86\_64-rpms

Install the directory server packages:

sudo dnf module install redhat-ds:11

Run the directory server configuration script:

sudo dscreate interactive

Enable specific versions of the maven and pki-deps modules to support successful redhat-pki installation in the next step.

sudo dnf module enable -y maven:3.8 pki-deps:10.6

Refresh the dnf cache:

sudo dnf clean all

  sudo rm -rf /var/cache/dnf/\*

  sudo dnf makecache

Install the certificate system packages:

sudo dnf install redhat-pki

Modify SELinux

To enable CryptoHub communication while SELinux is enforcing, perform these steps:

Reset the context for the Futurex PKCS #11 library:

sudo semanage fcontext -a -t lib\_t '/usr/lib/fxpkcs11(/.\*)?'

Apply the context changes:

sudo restorecon -RFv /usr/lib64/fxpkcs11

Set the context for the configuration file:

sudo semanage fcontext -a -t etc\_t '/etc/fxpkcs11.cfg'

Apply the context to the configuration file:

sudo restorecon -v /etc/fxpkcs11.cfg

Create a CA subsystem instance

Thepkispawn command line tool installs and configures a new PKI instance. It eliminates the need for separate installation and configuration steps, and you can run it interactively, as a batch process, or as a combination of both (batch process with prompts for passwords). Refer to the pkispawn man page for detailed information about all supported options by running man pkispawn. The pkispawn command reads in its default installation and configuration values from a plain text configuration file (/etc/pki/default.cfg). This file consists of name=value pairs divided into [DEFAULT], [Tomcat], [CA], [KRA], [OCSP], [TKS], and [TPS] sections.

We strongly recommend that you read the full documentation to understand the purpose of every parameter in the /etc/pki/default.cfg file. This enables you to customize your PKI environment to your specific needs.

The Red Hat recommended procedure for spawning a subsystem that uses an HSM is to create an override configuration file containing the parameters necessary to use the HSM as its token. Any parameter settings in this file override the parameter settings in the default.cfg file. You can spawn any RHCS subsystems (CA, KRA, OCSP, TKS, TPS) to use the CryptoHub, but this integration guide focuses on the Certificate Authority (CA) for brevity.

Prepare an override configuration file

Create an override configuration file to specify HSM parameters for the CA subsystem:

Create the override file:

sudo vi default\_futurex.txt

Populate the file with the following template. Set the pki_instance_name, pki_token_password, and pki_security_domain_name values to your specific values. Keep all other values unchanged.

The pkitokenpassword must match the CryptoHub identity password from the <CRYPTO-OPR-PASS> tag in fxpkcs11.cfg.

Text

[DEFAULT]
pki_instance_name=<instance_name>
pki_http_port=8080
pki_https_port=8443

# Admin & client credentials
pki_admin_email=caadmin@example.com
pki_admin_name=caadmin

# Security Domain (first CA or joining an existing one)
pki_security_domain_name=<security_domain_name>
pki_security_domain_https_port=8443

# 389-DS
pki_ds_url=ldap://127.0.0.1:389
pki_ds_database=userroot
pki_ds_bind_dn=cn=Directory Manager

# --- HSM (PKCS#11) ---
pki_hsm_enable=True
pki_hsm_libfile=/usr/lib64/fxpkcs11/libfxpkcs11.so
pki_hsm_modulename=FxPKCS11
pki_token_name=Futurex
pki_token_password=<hsm_user_pin>

[CA]
pki_audit_signing_token=Futurex
pki_ca_signing_token=Futurex
pki_ocsp_signing_token=Futurex
pki_sslserver_token=Futurex
pki_subsystem_token=Futurex

Run the pkispawn utility

Perform the following steps to run the pkispawn utility:

Deploy the CA subsystem with the CryptoHub using your override configuration:

sudo pkispawn -s CA -f default\_futurex.txt --debug

If the deployment succeeds, an installation summary similar to the following displays after the command completes:

\=============================================================
                      INSTALLATION SUMMARY
  \=============================================================

      Administrator's username:             caadmin
      Administrator's PKCS #12 file:
          /root/.dogtag/pki-tomcat/ca\admin\cert.p12

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

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

      The URL for the subsystem is:
          https\://localhost.localdomain:8443/ca

      PKI instances will be enabled upon system boot

  \=============================================================

Validation

After successful deployment, verify the following:

The CA subsystem service is active: systemctl status pki-tomcatd@pki-tomcat.service
The certificate file exists at: /root/.dogtag/pki-tomcat/ca_admin_cert.p12
The CA web interface is accessible: https://<hostname>:8443/ca

Import the PKCS #12 file

Import the CA administrator certificate into your browser to authenticate:

In Firefox, go to Settings > Privacy & Security > Certificates and select [ View Certificates ].

Under the Your Certificates tab, select [ Import ] to load the CA Administrator PKCS #12 file (ca_admin_cert.p12).

Enter the pki_client_pkcs12_password you set during the CA subsystem deployment.

Access the CA subsystem

Access the CA web interface and submit Certificate Signing Requests:

Open your browser and navigate tohttps://localhost.localdomain:8443/ca.

When submitting Certificate Signing Requests (CSRs) in RHCS, the Common Name and UID fields are both required. If you submit a request with only the Common Name field, the request fails, and you receive an error stating that the Subject Name does not match.

Next steps

For detailed CSR submission guidance, see: Red Hat Certificate System Administration Guide.

​Install RHCS

​Modify SELinux

​Create a CA subsystem instance

​Prepare an override configuration file

​Run the pkispawn utility

​Validation

​Import the PKCS #12 file

​Access the CA subsystem

​Next steps

Install RHCS

Modify SELinux

Create a CA subsystem instance

Prepare an override configuration file

Run the pkispawn utility

Validation

Import the PKCS #12 file

Access the CA subsystem

Next steps