Configure pkispawn

Modifying the sample pkispawn configuration file

Hostnames

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

  • RHCS server: pki_hostname=pki.domain.com

  • RHDS server: pki_ds_hostname=ldap.domain.com

Differences for a root CA and 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 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

The pki_subordinate* parameters are used if you want your root CA to be part of the same RHCS security domain. This is an unlikely scenario because the root will be offline. Do not change these parameters.

Ports

The defaults work for a single instance on the host. If you are using multiple hosts, 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

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

Change *_subject_dn= to your DN, based on 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

Six key pairs are created during installation. For policy reasons, 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_*)

  • Default administrator key (pki_admin_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

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.

[pkispawn-config-example] has a default value of password for all the passwords.

pki_replication_password is 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)

Default admin user passwords. They 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 be able 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.