Configure pkispawn

Modifying the sample pkispawn configuration file

Hostnames

Set these values as appropriate for your system. If you run multiple instances on the same server, it is not recommended to use the system FQDN as the RHCS server hostname.

  • RHCS server: pki_hostname=pki.domain.com

  • RHDS server: pki_ds_url=ldap://ldap.domain.com:389

Differences between a root CA and a subordinate CA

For a root CA, the caSigningCert is self-signed in pkispawn phase 1.

  • pki_external=False

For a subordinate CA, phase 1 completes the basic setup and creates the caSigningCert key and certificate request. Phase 2 imports the signed CA certificate chain and finishes the setup.

  • pki_external=True

  • Phase 1: pki_external_step_two=False

  • Phase 2: pki_external_step_two=True

Ports

The defaults work for a single instance on the host. If you are using multiple instances on the same host, it is recommended to use high ports, for example in the 63000 range.

  • pki_security_domain_https_port=8443

  • pki_http_port=8080

  • pki_https_port=8443

  • pki_ajp_port=8009

  • pki_tomcat_server_port=8005

Certificate distinguished names (DNs)

The six certificate DNs, especially the DN of the CA’s own certificate, are important to an enterprise-class PKI.

Change each *_subject_dn= value to the DN required by your policy.

  • pki_ca_signing_subject_dn=cn=<CA Common Name>,OU=Group,OU=Division,O=Company,C=US

  • pki_sslserver_subject_dn=cn=<server FQDN>,OU=Group,OU=Division,O=Company,C=US

  • pki_subsystem_subject_dn=cn=<CA Common Name> Subsystem Certificate,OU=Group,OU=Division,O=Company,C=US

  • pki_admin_subject_dn=cn=<CA Common Name> Agent Certificate,OU=Group,OU=Division,O=Company,C=US

  • pki_audit_signing_subject_dn=cn=<CA Common Name> Audit Certificate,OU=Group,OU=Division,O=Company,C=US

  • pki_ocsp_signing_subject_dn=cn=<CA Common Name> OCSP Certificate,OU=Group,OU=Division,O=Company,C=US

Algorithms and key size

Five key pairs are created during installation. For policy reasons, the keys should match.

For all keys, change all *_key_algorithm=, *_key_size=, and *_key_type= parameters to match your key configuration.

  • CA signing key (pki_ca_signing_key_*)

  • Instance subsystem key (pki_subsystem_key_*)

  • SSL/TLS web server key (pki_sslserver_key_*)

  • Internal OCSP (pki_ocsp_signing_key_*)

  • Instance audit signing key (pki_audit_signing_key_*)

Example for the CA’s signing key using RSA2048 and SHA-256:

  • pki_ca_signing_key_algorithm=SHA256withRSA

  • pki_ca_signing_key_size=2048

  • pki_ca_signing_key_type=rsa

Example for the CA’s signing key using ECC (nistp256) and SHA-256:

  • pki_ca_signing_key_algorithm=SHA256withEC

  • pki_ca_signing_key_size=nistp256

  • pki_ca_signing_key_type=ecc

Example for the CA’s signing key using a post-quantum algorithm (ML-DSA):

  • pki_ca_signing_key_algorithm=ML-DSA-44

  • pki_ca_signing_key_size=44

  • pki_ca_signing_key_type=mldsa

nShield HSM

Change all *_token= variables to match the name of your OCS or Softcard token.

  • pki_audit_signing_token=OCS1

  • pki_sslserver_token=OCS1

  • pki_subsystem_token=OCS1

  • pki_token_name=OCS1

  • pki_ca_signing_token=OCS1

  • pki_ocsp_signing_token=OCS1

Account passwords

Change all applicable *_password= variables from the defaults.

pki_replication_password is used only for cloning CAs.

  • For the RHCS security domain, to join additional subsystems to the CA’s security domain (pki_security_domain_password)

  • For the RHCS instance’s NSS database (pki_server_database_password)

  • For the LDAP directory server (pki_ds_password)

  • For the HSM token (pki_token_password)

The following default administrator passwords should match:

  • Administrator credential, for example for logging in to pkiconsole (pki_admin_password)

  • Default administrator credential in an NSS database (pki_client_database_password)

  • Default administrator credential in a PKCS #12 file (pki_client_pkcs12_password)

Default agent credential

Load this PKCS #12 file into Firefox, or another web browser on any system, to access the agent web page and issue certificates or CRLs.

After the installation completes, this file is located in /etc/pki/<instance>/agent_alias.

<instance> is the pki_instance_name variable in the pkispawn configuration file.

Post-quantum limitation

The SSL server certificate (pki_sslserver_*) cannot use a post-quantum algorithm (ML-DSA). All other system certificates (CA signing, OCSP signing, audit signing, and subsystem) can use ML-DSA.

When the SSL server certificate is configured with ML-DSA:

pki_sslserver_key_algorithm=ML-DSA-44
pki_sslserver_key_size=44
pki_sslserver_key_type=mldsa
pki_sslserver_signing_algorithm=ML-DSA-44

pkispawn generates the keys and certificates and starts Tomcat, but fails when it checks the server status over HTTPS:

INFO: Waiting for PKI server to start (1s)
DEBUG: Starting new HTTPS connection (1): pki.domain.com:8443
ERROR: Exception: Server unreachable due to SSL error: [SSL: BAD_SIGNATURE] bad signature (_ssl.c:998)
  File "/usr/lib/python3.12/site-packages/pki/server/pkispawn.py", line 594, in main
    deployer.spawn()
  File "/usr/lib/python3.12/site-packages/pki/server/deployment/__init__.py", line 6330, in spawn
    scriptlet.spawn(self)
  File "/usr/lib/python3.12/site-packages/pki/server/deployment/scriptlets/configuration.py", line 247, in spawn
    instance.start(
  File "/usr/lib/python3.12/site-packages/pki/server/__init__.py", line 536, in start
    raise Exception('Server unreachable due to SSL error: %s' % reason) from e

Installation failed: Server unreachable due to SSL error: [SSL: BAD_SIGNATURE] bad signature (_ssl.c:998)

  • Cause: The pkispawn client (Python 3.12 ssl, backed by the system OpenSSL) rejects the ML-DSA-44 signature that the server produces during the TLS handshake (signed through JSS/NSS and the nShield PKCS #11 library). ML-DSA works for certificate signatures, but ML-DSA TLS server authentication between these components does not work in this configuration. Most browsers also do not yet support ML-DSA TLS server certificates.

  • Workaround: Use a classical algorithm for the SSL server key only. The server certificate is still signed by the ML-DSA CA. The pkispawn.cfg files use the following settings:

pki_sslserver_key_algorithm=SHA256withRSA
pki_sslserver_key_size=2048
pki_sslserver_key_type=rsa

  • Result: sslserver key=rsaEncryption sig=ML-DSA-44 OK