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 (nistp384) and SHA-384:

  • pki_ca_signing_key_algorithm=SHA384withEC

  • pki_ca_signing_key_size=nistp384

  • 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.

Sample pkispawn configuration file 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.

Sample pkispawn configuration file

The following is a sample pkispawn configuration file for Red Hat Certificate System v9. For Red Hat Certificate System v10 and later versions, see Red Hat documentation or the default.cfg file on your RHCS system for an updated example. The following is a sample pkispawn configuration file for Red Hat Certificate System v9. For Red Hat Certificate System v10 and later versions, see the Red Hat documentation or the default.cfg file on your RHCS system for an updated example.

[DEFAULT]
JAVA_HOME=%(java_home)s
NSS_DEFAULT_DB_TYPE=%(nss_default_db_type)s
pki_admin_cert_file=%(pki_client_dir)s/admin.cer
pki_admin_cert_request_type=pkcs10
pki_admin_dualkey=False
pki_admin_key_algorithm=SHA256withRSA
pki_admin_key_size=2048
pki_admin_key_type=rsa
pki_admin_password=password
pki_audit_group=pkiaudit
pki_audit_signing_key_algorithm=SHA256withRSA
pki_audit_signing_key_size=2048
pki_audit_signing_key_type=rsa
pki_audit_signing_signing_algorithm=SHA256withRSA
pki_audit_signing_token=OCS1
pki_ca_hostname=%(pki_security_domain_hostname)s
pki_ca_port=%(pki_security_domain_https_port)s
pki_ca_signing_cert_path=/etc/pki/ca-1/alias/ca-1_caSigningCert.cer
pki_ca_signing_nickname=caSigningCert cert-%(pki_instance_name)s CA
pki_cert_chain_nickname=caSigningCert External CA
pki_cert_chain_path=/etc/pki/ca-1/alias/caChain.p7c
pki_client_admin_cert=%(pki_client_dir)s/%(pki_subsystem_type)s_admin.cer
pki_client_admin_cert_p12=%(pki_client_dir)s/%(pki_subsystem_type)s_admin.p12
pki_client_cert_database=%(pki_client_database_dir)s/cert8.db
pki_client_database_dir=%(pki_client_subsystem_dir)s
pki_client_database_password=password
pki_client_database_purge=False
pki_client_dir=/etc/pki/ca-1/agent_alias
pki_client_key_database=%(pki_client_database_dir)s/key3.db
pki_client_password_conf=%(pki_client_subsystem_dir)s/password.conf
pki_client_pkcs12_password=password
pki_client_pkcs12_password_conf=%(pki_client_subsystem_dir)s/pkcs12_password.conf
pki_client_secmod_database=%(pki_client_database_dir)s/secmod.db
pki_client_subsystem_dir=%(pki_client_dir)s
pki_configuration_path=%(pki_root_prefix)s/etc/pki
pki_ds_bind_dn=cn=Directory Manager
pki_ds_create_new_db=True
pki_ds_ldap_port=389
pki_ds_ldaps_port=636
pki_ds_password=password
pki_ds_remove_data=True
pki_ds_secure_connection=False
pki_ds_secure_connection_ca_nickname=Directory Server CA certificate
pki_ds_secure_connection_ca_pem_file=
pki_existing=False
pki_external_ca_cert_chain_path=%(pki_cert_chain_path)s
pki_group=pkiuser
pki_hostname=pki.domain.com
pki_hsm_enable=True
pki_hsm_libfile=/opt/nfast/toolkits/pkcs11/libcknfast.so
pki_hsm_modulename=nfast
pki_http_port=8080
pki_https_port=8443
pki_instance_conf_link=%(pki_instance_path)s/conf
pki_instance_configuration_path=%(pki_configuration_path)s/%(pki_instance_name)s
pki_instance_database_link=%(pki_instance_path)s/alias
pki_instance_log_path=%(pki_log_path)s/%(pki_instance_name)s
pki_instance_logs_link=%(pki_instance_path)s/logs
pki_instance_name=ca-1
pki_instance_path=%(pki_path)s/%(pki_instance_name)s
pki_issuing_ca=%(pki_issuing_ca_uri)s
pki_issuing_ca_hostname=%(pki_security_domain_hostname)s
pki_issuing_ca_https_port=%(pki_security_domain_https_port)s
pki_issuing_ca_uri=https://%(pki_issuing_ca_hostname)s:%(pki_issuing_ca_https_port)s
pki_log_path=%(pki_root_prefix)s/var/log/pki
pki_path=%(pki_root_prefix)s/var/lib/pki
pki_pkcs12_password=password
pki_pkcs12_path=
pki_registry_path=%(pki_root_prefix)s/etc/sysconfig/pki
pki_replication_password=password
pki_restart_configured_instance=True
pki_san_for_server_cert=
pki_san_inject=False
pki_security_domain_hostname=%(pki_hostname)s
pki_security_domain_https_port=8443
pki_security_domain_name=Security Domain
pki_security_domain_password=password
pki_security_domain_user=admin
pki_self_signed_token=internal
pki_server_database_password=password
pki_server_database_path=%(pki_instance_configuration_path)s/alias
pki_skip_configuration=False
pki_skip_ds_verify=False
pki_skip_installation=False
pki_skip_sd_verify=False
pki_source_conf_path=/usr/share/pki/%(pki_subsystem_type)s/conf
pki_source_cs_cfg=/usr/share/pki/%(pki_subsystem_type)s/conf/CS.cfg
pki_source_registry=/usr/share/pki/setup/pkidaemon_registry
pki_source_server_path=/usr/share/pki/server/conf
pki_source_setup_path=/usr/share/pki/setup
pki_source_subsystem_path=/usr/share/pki/%(pki_subsystem_type)s
pki_sslserver_key_algorithm=SHA256withRSA
pki_sslserver_key_size=2048
pki_sslserver_key_type=rsa
pki_sslserver_nickname=Server-Cert cert-%(pki_instance_name)s CA
pki_sslserver_subject_dn=cn=ca-1.domain.com,OU=Group,OU=Division,O=nCipher Security,C=US
pki_sslserver_token=OCS1
pki_subsystem_archive_log_path=%(pki_subsystem_log_path)s/archive
pki_subsystem_conf_link=%(pki_subsystem_path)s/conf
pki_subsystem_configuration_path=%(pki_instance_configuration_path)s/%(pki_subsystem_
type)s
pki_subsystem_database_link=%(pki_subsystem_path)s/alias
pki_subsystem_key_algorithm=SHA256withRSA
pki_subsystem_key_size=2048
pki_subsystem_key_type=rsa
pki_subsystem_log_path=%(pki_instance_log_path)s/%(pki_subsystem_type)s
pki_subsystem_logs_link=%(pki_subsystem_path)s/logs
pki_subsystem_nickname=subsystemCert cert-%(pki_instance_name)s CA
pki_subsystem_path=%(pki_instance_path)s/%(pki_subsystem_type)s
pki_subsystem_registry_link=%(pki_subsystem_path)s/registry
pki_subsystem_subject_dn=cn=CA-1 Subsystem Certificate,OU=Group,OU=Division,O=nCipher
Security,C=US
pki_subsystem_token=OCS1
pki_theme_enable=True
pki_theme_server_dir=/usr/share/pki/common-ui
pki_token_name=OCS1
pki_token_password=password
pki_user=pkiuser-ca-1
[Tomcat]
pki_ajp_host=localhost
pki_ajp_port=8009
pki_cgroup_cpu_systemd_service=%(pki_cgroup_cpu_systemd_service_path)s/%(pki_systemd_service)
s
pki_cgroup_cpu_systemd_service_path=/sys/fs/cgroup/cpu\,cpuacct/system/%(pki_systemd_
service)s
pki_cgroup_systemd_service=%(pki_cgroup_systemd_service_path)s/%(pki_instance_name)s
pki_cgroup_systemd_service_path=/sys/fs/cgroup/systemd/system/%(pki_systemd_service)s
pki_clone=False
pki_clone_pkcs12_password=password
pki_clone_pkcs12_path=
pki_clone_reindex_data=False
pki_clone_replicate_schema=True
pki_clone_replication_clone_port=
pki_clone_replication_master_port=
pki_clone_replication_security=None
pki_clone_setup_replication=True
pki_clone_uri=https://%(pki_master_hostname)s:%(pki_master_https_port)s
pki_enable_access_log=True
pki_enable_java_debugger=False
pki_enable_on_system_boot=True
pki_enable_proxy=False
pki_instance_conf_log4j_properties=%(pki_instance_configuration_path)s/log4j.properties
pki_instance_lib=%(pki_instance_path)s/lib
pki_instance_lib_log4j_properties=%(pki_instance_lib)s/log4j.properties
pki_instance_registry_path=%(pki_instance_type_registry_path)s/%(pki_instance_name)s
pki_instance_systemd_link=%(pki_instance_path)s/%(pki_instance_name)s
pki_instance_type=Tomcat
pki_instance_type_registry_path=%(pki_registry_path)s/tomcat
pki_master_hostname=%(pki_security_domain_hostname)s
pki_master_https_port=%(pki_security_domain_https_port)s
pki_proxy_http_port=80
pki_proxy_https_port=443
pki_security_manager=true
pki_server_external_certs_path=
pki_server_pkcs12_password=password
pki_server_pkcs12_path=
pki_source_catalina_properties=%(pki_source_server_path)s/catalina.properties
pki_source_context_xml=%(pki_source_server_path)s/context.xml
pki_source_server_xml=%(pki_source_server_path)s/server.xml
pki_source_servercertnick_conf=%(pki_source_server_path)s/serverCertNick.conf
pki_source_tomcat_conf=%(pki_source_server_path)s/tomcat.conf
pki_subsystem_registry_path=%(pki_instance_registry_path)s/%(pki_subsystem_type)s
pki_subsystem_signed_audit_log_path=%(pki_subsystem_log_path)s/signedAudit
pki_systemd_service=/lib/systemd/system/pki-tomcatd@.service
pki_systemd_service_link=%(pki_systemd_target_wants)s/pki-tomcatd@%(pki_instance_
name)s.service
pki_systemd_target=/lib/systemd/system/pki-tomcatd.target
pki_systemd_target_wants=/etc/systemd/system/pki-tomcatd.target.wants
pki_tomcat_bin_link=%(pki_instance_path)s/bin
pki_tomcat_bin_path=/usr/share/tomcat/bin
pki_tomcat_common_lib_path=%(pki_tomcat_common_path)s/lib
pki_tomcat_common_path=%(pki_instance_path)s/common
pki_tomcat_common_webapps_path=%(pki_instance_path)s/common/webapps
pki_tomcat_lib_path=/usr/share/tomcat/lib
pki_tomcat_server_port=8005
pki_tomcat_subsystem_webapps_path=%(pki_subsystem_path)s/webapps
pki_tomcat_systemd=/usr/sbin/tomcat
pki_tomcat_tmpdir_path=%(pki_instance_path)s/temp
pki_tomcat_webapps_path=%(pki_instance_path)s/webapps
pki_tomcat_webapps_subsystem_path=%(pki_tomcat_subsystem_webapps_path)s/%(pki_subsystem_
type)s
pki_tomcat_webapps_subsystem_webinf_classes_path=%(pki_tomcat_webapps_subsystem_
path)s/WEB-INF/classes
pki_tomcat_webapps_subsystem_webinf_lib_path=%(pki_tomcat_webapps_subsystem_path)s/WEBINF/
lib
pki_tomcat_work_catalina_host_path=%(pki_tomcat_work_catalina_path)s/localhost
pki_tomcat_work_catalina_host_run_path=%(pki_tomcat_work_catalina_host_path)s/_
pki_tomcat_work_catalina_host_subsystem_path=%(pki_tomcat_work_catalina_host_path)s/%
(pki_subsystem_type)s
pki_tomcat_work_catalina_path=%(pki_tomcat_work_path)s/Catalina
pki_tomcat_work_path=%(pki_instance_path)s/work
[CA]
pki_admin_email=%(pki_admin_name)s@localhost
pki_admin_name=%(pki_admin_uid)s
pki_admin_nickname=CA-1 Agent Certificate
pki_admin_subject_dn=cn=CA-1 Agent Certificate,OU=Group,OU=Division,O=nCipher Security,
C=US
pki_admin_uid=admin
pki_audit_signing_cert_path=
pki_audit_signing_csr_path=
pki_audit_signing_nickname=auditSigningCert cert-%(pki_instance_name)s CA
pki_audit_signing_subject_dn=cn=CA-1 Audit Certificate,OU=Group,OU=Division,O=nCipher
Security,C=US
pki_ca_signing_csr_path=/etc/pki/ca-1/alias/ca-1_caSigningCert.req
pki_ca_signing_key_algorithm=SHA256withRSA
pki_ca_signing_key_size=2048
pki_ca_signing_key_type=rsa
pki_ca_signing_record_create=True
pki_ca_signing_serial_number=1
pki_ca_signing_signing_algorithm=SHA256withRSA
pki_ca_signing_subject_dn=cn=CA-1,OU=Group,OU=Division,O=nCipher Security,C=US
pki_ca_signing_token=OCS1
pki_ca_starting_crl_number=0
pki_default_ocsp_uri=
pki_ds_base_dn=o=%(pki_instance_name)s-CA
pki_ds_database=%(pki_instance_name)s-CA
pki_ds_hostname=ldap.domain.com
pki_external=False
pki_external_pkcs12_password=password
pki_external_pkcs12_path=%(pki_pkcs12_path)s
pki_external_step_two=False
pki_import_admin_cert=False
pki_master_crl_enable=True
pki_ocsp_signing_cert_path=
pki_ocsp_signing_csr_path=
pki_ocsp_signing_key_algorithm=SHA256withRSA
pki_ocsp_signing_key_size=2048
pki_ocsp_signing_key_type=rsa
pki_ocsp_signing_nickname=ocspSigningCert cert-%(pki_instance_name)s CA
pki_ocsp_signing_signing_algorithm=SHA256withRSA
pki_ocsp_signing_subject_dn=cn=CA-1 OCSP Certificate,OU=Group,OU=Division,O=nCipher Security,
C=US
pki_ocsp_signing_token=OCS1
pki_profiles_in_ldap=False
pki_random_serial_numbers_enable=False
pki_replica_number_range_end=100
pki_replica_number_range_start=1
pki_req_ext_add=False
pki_req_ext_critical=False
pki_req_ext_data=1E0A00530075006200430041
pki_req_ext_oid=1.3.6.1.4.1.311.20.2
pki_request_number_range_end=10000000
pki_request_number_range_start=1
pki_serial_number_range_end=10000000
pki_serial_number_range_start=1
pki_share_db=False
pki_source_admincert_profile=%(pki_source_conf_path)s/%(pki_admin_key_type)sAdminCert.
profile
pki_source_caauditsigningcert_profile=%(pki_source_conf_path)s/caAuditSigningCert.profile
pki_source_cacert_profile=%(pki_source_conf_path)s/caCert.profile
pki_source_caocspcert_profile=%(pki_source_conf_path)s/caOCSPCert.profile
pki_source_emails=/usr/share/pki/ca/emails
pki_source_flatfile_txt=%(pki_source_conf_path)s/flatfile.txt
pki_source_profiles=/usr/share/pki/ca/profiles
pki_source_proxy_conf=%(pki_source_conf_path)s/proxy.conf
pki_source_registry_cfg=%(pki_source_conf_path)s/registry.cfg
pki_source_servercert_profile=%(pki_source_conf_path)s/%(pki_sslserver_key_type)sServer-
Cert.profile
pki_source_subsystemcert_profile=%(pki_source_conf_path)s/%(pki_subsystem_key_
type)sSubsystemCert.profile
pki_sslserver_cert_path=
pki_sslserver_csr_path=
pki_subordinate=False
pki_subordinate_create_new_security_domain=False
pki_subordinate_security_domain_name=%(pki_dns_domainname)s Subordinate Security Domain
pki_subsystem_cert_path=
pki_subsystem_csr_path=
pki_subsystem_emails_path=%(pki_subsystem_path)s/emails
pki_subsystem_name=CA %(pki_hostname)s %(pki_https_port)s
pki_subsystem_profiles_path=%(pki_subsystem_path)s/profiles