Skip to main content
This tutorial walks system administrators through installing Red Hat Certificate System (RHCS), configuring SELinux for HSM 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:
1
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
2
Install the directory server packages:
sudo dnf module install redhat-ds:11
3
Run the directory server configuration script:
sudo dscreate interactive
4
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
5
Refresh the dnf cache:
sudo dnf clean all

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

  sudo dnf makecache
6
Install the certificate system packages:
sudo dnf install redhat-pki

​
Modify SELinux

To enable HSM communication while SELinux is enforcing, perform these steps:
1
Reset the context for the Futurex PKCS #11 library:
sudo semanage fcontext -a -t lib\_t '/usr/lib/fxpkcs11(/.\*)?'
2
Apply the context changes:
sudo restorecon -RFv /usr/lib64/fxpkcs11
3
Set the context for the configuration file:
sudo semanage fcontext -a -t etc\_t '/etc/fxpkcs11.cfg'
4
Apply the context to the configuration file:
sudo restorecon -v /etc/fxpkcs11.cfg

​
Create a CA subsystem instance

The pkispawn 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 that contains only the parameters necessary for using 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 HSM, 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:
1
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.
You must define the password of the identity you created on the Vectera Plus in the pkitokenpassword parameter.
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:
1
Deploy the CA subsystem with the Vectera Plus 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:
1
In Firefox, go to Settings > Privacy & Security > Certificates and select [ View Certificates ].
2
Under the Your Certificates tab, select [ Import ] to load the CA Administrator PKCS #12 file (ca_admin_cert.p12).
3
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:
1
Open your browser and navigate to https://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.