此内容没有您所选择的语言版本。
7.3. Installing Using the pkispawn Utility
Read the following section carefully to ensure that you make the right choices when following the installation examples in this section.
7.3.1. About the pkispawn Utility 复制链接链接已复制到粘贴板!
复制链接链接已复制到粘贴板!
In Red Hat Certificate System, administrators set up the individual public key infrastructure (PKI) subsystems by running the
pkispawn utility.
The
pkispawn utility requires a configuration file. This file contains parameters that are grouped into sections. These sections are stacked, so that parameters defined in earlier sections can be overridden by parameters defined in later sections. The sections are read in the following order:
[DEFAULT][Tomcat]- The subsystem-specific sections:
[CA],[KRA],[OCSP],[TKS], or[TPS]
During the setup,
pkispawn:
- First reads the default values from the
/etc/pki/default.cfgfile.Important
Do not edit the/etc/pki/default.cfgfile. You will be instructed to create a configuration file that overrides the defaults when passed to thepkispawnutility. Parameters not set in the configuration file use the defaults. For details about using a configuration file, see Section 7.3.2, “Two-step Installation Usingpkispawn”. - Reads the administrator-provided configuration file mentioned above to override the default values.
- Performs the installation of the requested PKI subsystem.
- Passes the settings to a Java servlet that performs the configuration based on the settings.
For general information about
pkispawn and examples, see the pkispawn(8) and pki_default.cfg(5) man pages.
For instructions about how to install a CA, KRA, or OCSP subsystem, see Section 7.3.2, “Two-step Installation Using
pkispawn”.
For instructions about how to install a TKS or TPS subsystem, see Section 7.3.3, “Single-step Installation Using
pkispawn (TMS-only)”.
7.3.2. Two-step Installation Using pkispawn 复制链接链接已复制到粘贴板!
复制链接链接已复制到粘贴板!
To install a CA, KRA, or OCSP subsystem, use the
pkispawn two-step installation to enable the administrator to manually update configuration files between the two parts of the installation.
The name
two-step installation comes from the fact that the pkispawn utility is often run twice with a slightly different set of parameters in its overwrite configuration file to complete the installation.
The two-step installation is consisted of the following major parts:
- Installation using the
pkispawnUtility (Step 1)During this step,pkispawncopies configuration files from the/usr/share/pki/directory to the instance-specific/etc/pki/instance_name/directory. Additionally,pkispawnsets the settings based on values defined in the deployment configuration file.This part of the installation contains the following substeps: - Between-step configuration and customization
- Configuration Using the
pkispawnUtility (Step 2)During this step,pkispawnis run to continue the installation based on the configuration files in the instance-specific/etc/pki/instance_name/directory.For details about this part of the installation see Section 7.3.2.4, “Starting thepkispawnStep Two Installation”.
Depending on your environment, additional configuration and customization steps are required.
Create a text file for the
pkispawn configuration settings, such as /root/pki/config.subsystem.txt, and fill it with the settings described below. Every setting must be added.
Important
This section describes a minimum configuration with Directory Server running on the same host as Certificate System. Depending on your environment, additional parameters may be necessary. For additional examples, see the EXAMPLES section in the pkispawn(8) man page.
Subsystem-independent Settings
Independently of the subsystem you install, the following settings are required in the configuration file in the:
[DEFAULT]section:- Set a unique instance name:
pki_instance_name=instance_name - Set the host name and security domain name:
pki_host=server.example.com pki_security_domain_name=example.com Security Domain pki_security_domain_user=caadmin pki_security_domain_password=SD passwordNote
Certificate System creates unique certificate nicknames based on these parameters and the instance name. The uniqueness of certificate nicknames is very important in keeping the HSM token shared by multiple PKI instances functional. - Set the port numbers for the HTTP and HTTPS protocols:
pki_https_port=port_number pki_http_port=port_numberImportant
To run more than one Certificate System instance on the same host, you must set ports in thepki_https_portandpki_http_portparameters that are not used by any other service on the host. By default, Certificate System uses port8080for HTTP and8443for HTTPS. - Set the HSM-specific parameters:
pki_hsm_enable=True pki_hsm_libfile=HSM_PKCS11_library_path pki_hsm_modulename=HSM_module_name pki_token_name=HSM_token_name pki_token_password=HSM_token_password pki_audit_signing_token=HSM_token_name pki_subsystem_token=HSM_token_name pki_sslserver_token=HSM_token_nameFor further details, see Section 6.4.4, “Preparing for Installing Certificate System with an HSM”. - If building an RSA Certificate System instance, use the following configuration:
pki_admin_key_algorithm=SHA256withRSA pki_admin_key_size=4096 pki_admin_key_type=rsa pki_sslserver_key_algorithm=SHA256withRSA pki_sslserver_key_size=4096 pki_sslserver_key_type=rsa pki_subsystem_key_algorithm=SHA256withRSA pki_subsystem_key_size=4096 pki_subsystem_key_type=rsa pki_audit_signing_key_algorithm=SHA256withRSA pki_audit_signing_key_size=4096 pki_audit_signing_key_type=rsa pki_audit_signing_signing_algorithm=SHA256withRSAAllowed choices for thekey_algorithmparameters are:SHA256withRSASHA384withRSASHA512withRSA
Note
You can set this parameter to each value specified in theca.profiles.defaultSigningAlgsAllowedparameter in the CA'sCS.cfgfile. For details, see the Signing Algorithm Constraint section in the Red Hat Certificate System Administration Guide (Common Criteria Edition).Signature algorithm (RSA) must matchkey_type(rsa).Allowed choices forkey_typeis onlyrsa.Allowed choices forkey_sizeare2048and4096. - To use Elliptic Curve Cryptography (ECC) instead of RSA when creating certificates, set:
pki_admin_key_algorithm=SHA256withEC pki_admin_key_size=nistp256 pki_admin_key_type=ecc pki_sslserver_key_algorithm=SHA256withEC pki_sslserver_key_size=nistp256 pki_sslserver_key_type=ecc pki_subsystem_key_algorithm=SHA256withEC pki_subsystem_key_size=nistp256 pki_subsystem_key_type=ecc pki_audit_signing_key_algorithm=SHA256withEC pki_audit_signing_key_size=nistp256 pki_audit_signing_key_type=ecc pki_audit_signing_signing_algorithm=SHA256withECAllowed choices for thekey_algorithmparameters are:SHA256withECSHA384withECSHA512withEC
Note
You can set this parameter to each value specified in theca.profiles.defaultSigningAlgsAllowedparameter in the CA'sCS.cfgfile. For details, see the Signing Algorithm Constraint section in the Red Hat Certificate System Administration Guide (Common Criteria Edition).Signature algorithm (EC) must matchkey_type(ecc).Allowed choices forkey_sizeare:nistp256nistp384nistp521
Allowed choice forkey_typeisecc - Set the client directory of the bootstrap
adminuser:pki_client_dir=bootstrap_admin_directoryBy default, the path is set to~/.dogtag/instance_name/Important
Thepki_admin_*andpki_client_*parameters belong to the bootstrap user that is automatically created by the installation process. For further information about default roles (privileges) and the bootstrap user, see Section 2.6.6, “Users, Authorization, and Access Controls”.For descriptions about the parameters covered in this section, see the pki_default.cfg(5) man page. - Set various passwords for the bootstrap
adminuser:pki_admin_password=password pki_client_database_password=password pki_client_pkcs12_password=password - Set the parameters for the LDAPS connection to Directory Server running on the same host:
pki_ds_database=back-end database name pki_ds_hostname=hostname pki_ds_secure_connection=True pki_ds_secure_connection_ca_pem_file=path_to_CA_or_self-signed_certificate pki_ds_password=password - If you use a self-signed certificate in Directory Server use the following command to export it from the Directory Server's Network Security Services (NSS) database:
# certutil -L -d /etc/dirsrv/slapd-instance_name/ \ -n "server-cert" -a -o /root/ds.crt
[Tomcat]section:- Set the Tomcat JServ Protocol (AJP) port:
pki_ajp_port=Tomcat_AJP_port - Set the Tomcat server port:
pki_tomcat_server_port=Tomcat_server_port
Important
To run more than one PKI subsystem instance on the same host, you must set ports in thepki_ajp_portandpki_tomcat_server_portparameters that are not used by any other service on the host. By default, thepki_ajp_portis set to8009andpki_tomcat_server_portto8005.
For non-TMS, after you created the initial configuration file, add the subsystem-specific settings to it. See:
For TMS, to continue creating the configuration file for the
pkispawn single-step Installation, see Section 7.3.3.1, “Creating the Configuration File for pkispawn single-step Installation”.
CA Settings
In addition to the section called “Subsystem-independent Settings”, you need the following settings in the
[CA] section to install a CA:
- Enable random serial numbers by adding following setting:
pki_random_serial_numbers_enable=true - Set the following parameters to specify the data of the bootstrap
adminuser, which will be automatically created during the installation:pki_admin_nickname=bootstrap_CA_admin pki_admin_name=bootstrap_CA_administrator_name pki_admin_uid=caadmin pki_admin_email=caadmin@example.comCertificate System assigns administrator and agent privileges to this bootstrap account. Use this account after the installation to create actual administrator, agent, and auditor accounts. - Specify the HSM token for the subsystem-dependent certificates:
pki_ca_signing_token=HSM_token_name pki_ocsp_signing_token=HSM_token_name - If building an RSA-based CA, use the following configuration:
pki_ca_signing_key_algorithm=SHA256withRSA pki_ca_signing_key_size=4096 pki_ca_signing_key_type=rsa pki_ca_signing_signing_algorithm=SHA256withRSA pki_ocsp_signing_key_algorithm=SHA256withRSA pki_ocsp_signing_key_size=4096 pki_ocsp_signing_key_type=rsa pki_ocsp_signing_signing_algorithm=SHA256withRSAAllowed choices for thekey_algorithmparameters are:SHA256withRSASHA384withRSASHA384withRSA
Note
You can set this parameter to each value specified in theca.profiles.defaultSigningAlgsAllowedparameter in the CA'sCS.cfgfile. For details, see the Signing Algorithm Constraint section in the Red Hat Certificate System Administration Guide (Common Criteria Edition).Signature algorithm (RSA) must matchkey_type(rsa).Allowed choices forkey_sizeparameters are:20484096
Allowed choices forkey_typeparameters are onlyrsa. - By default, the key type for system certificates is
rsaand the key length is2048bit. To use Elliptic Curve Cryptography (ECC) instead of RSA when creating certificates, set:pki_ocsp_signing_key_algorithm=SHA256withEC pki_ocsp_signing_key_size=nisp256 pki_ocsp_signing_key_type=ecc pki_ocsp_signing_signing_algorithm=SHA256withECAllowed choices forkey_algorithmparameters are:SHA256withECSHA384withECSHA512withEC
Note
You can set this parameter to each value specified in theca.profiles.defaultSigningAlgsAllowedparameter in the CA'sCS.cfgfile. For details, see the Signing Algorithm Constraint section in the Red Hat Certificate System Administration Guide (Common Criteria Edition).Signature algorithm (EC) must matchkey_type(ecc).Allowed choices forkey_sizeparameters are:nistp256nistp384nistp521
Allowed choices forkey_typeparameters isecc.
Settings for Other Subsystems
In addition to the section called “Subsystem-independent Settings”, you need the following settings in the
[CA], [KRA], or [OCSP] section to install a subordinate CA, KRA, or OCSP:
- Subsystems that are not a root CA use the two-step installation mechanism that is sometimes referred to as External CA. For the first step, add the following parameters under each respective subsystem-specific section:
pki_external=True pki_external_step_two=False - This step depends on the subsystem you are installing:
- Subordinate CA
- Add the following settings to the
[CA]section:- Add all settings from the
[CA]section of the root CA. - Set the output paths for the system certificate signing requests (CSR):
pki_ca_signing_csr_path=path pki_ocsp_signing_csr_path=path pki_audit_signing_csr_path=path pki_sslserver_csr_path=path pki_subsystem_csr_path=path pki_admin_csr_path=path
- OCSP
- Set the following in the
[OCSP]section:- Specify the following parameters to set the data of the bootstrap OCSP
adminuser which is automatically created during the installation:pki_admin_nickname=bootstrap_OCSP_admin pki_admin_name=bootstrap_OCSP_administrator_name pki_admin_uid=ocspadmin pki_admin_email=ocspadmin@example.comCertificate System assigns administrator and agent privileges to this bootstrap account. Use this account after the installation to create actual administrator, agent, and auditor accounts. - Specify the HSM token for the subsystem-dependent certificates:
pki_ocsp_signing_token=HSM_token_name - If building an RSA Certificate System instance, use the following configuration:
pki_ocsp_signing_key_algorithm=SHA256withRSA pki_ocsp_signing_key_size=4096 pki_ocsp_signing_key_type=rsa pki_ocsp_signing_signing_algorithm=SHA256withRSAAllowed choices for thekey_algorithmparameters are:SHA256withRSASHA384withRSASHA384withRSA
Note
You can set this parameter to each value specified in theca.profiles.defaultSigningAlgsAllowedparameter in the CA'sCS.cfgfile. For details, see the Signing Algorithm Constraint section in the Red Hat Certificate System Administration Guide (Common Criteria Edition).Signature algorithm (RSA) must matchkey_type(rsa).Allowed choices forkey_sizeparameters are:20484096
Allowed choices forkey_typeparameters are onlyrsa.Note
It is suggested to match your CA instance type (RSA or ECC) with your OCSP responder type (RSA or ECC). - To use Elliptic Curve Cryptography (ECC) instead of RSA when creating certificates, set:
pki_ocsp_signing_key_algorithm=SHA256withEC pki_ocsp_signing_key_size=nisp256 pki_ocsp_signing_key_type=ecc pki_ocsp_signing_signing_algorithm=SHA256withECAllowed choices for thekey_algorithmparameters are:SHA256withECSHA384withECSHA512withEC
Note
You can set this parameter to each value specified in theca.profiles.defaultSigningAlgsAllowedparameter in the CA'sCS.cfgfile. For details, see the Signing Algorithm Constraint section in the Red Hat Certificate System Administration Guide (Common Criteria Edition).Signature algorithm (EC) must matchkey_type(ecc).Allowed choices forkey_sizeparameters are:nistp256nistp384nistp521
Allowed choices forkey_typeparameters are onlyecc.Note
It is suggested to match your CA instance type (RSA or ECC) with your OCSP responder type (RSA or ECC). - Set the output paths for the system certificate signing requests (CSR):
pki_ocsp_signing_csr_path=path pki_audit_signing_csr_path=path pki_sslserver_csr_path=path pki_subsystem_csr_path=path pki_admin_csr_path=path
- KRA
- Set the following in the
[KRA]section:- Specify the following parameters to set the data of the bootstrap KRA
adminuser which is automatically created during the installation:pki_admin_nickname=bootstrap_KRA_admin pki_admin_name=bootstrap_KRA_administrator_name pki_admin_uid=kraadmin pki_admin_email=kraadmin@example.comCertificate System assigns administrator and agent privileges to this bootstrap account. Use this account after the installation to create actual administrator, agent, and auditor accounts. - Specify the HSM token for the subsystem-dependent certificates:
pki_transport_token=HSM_token_name pki_storage_token=HSM_token_name - RSA is the only key type supported for both the KRA storage and transport certificates. By default, the key length is
2048bit. To choose a4096bit key instead, add the following parameters:pki_transport_key_size=4096 pki_storage_key_size=4096 - Set the output paths for the system certificate signing requests (CSR):
pki_kra_signing_csr_path=path pki_audit_signing_csr_path=path pki_sslserver_csr_path=path pki_subsystem_csr_path=path pki_admin_csr_path=path
7.3.2.2. Starting the pkispawn Step One Installation 复制链接链接已复制到粘贴板!
复制链接链接已复制到粘贴板!
After you prepared the configuration file as described in Section 7.3.2.1, “Creating the Configuration File for the First Step of the Installation”, start the first step of the installation:
- For a root CA:
# pkispawn -f /root/pki/config.root-CA.txt -s CA - For a subordinate CA or other non-CA subsystems:
# pkispawn -f /root/pki/config.subsystem.txt -s subsystemReplace subsystem with one of the following subsystems:CA,KRA, orOCSP. For example, for a KRA installation:# pkispawn -f /root/pki/config.KRA.txt -s KRA
After the installation step described in Section 7.3.2.2, “Starting the
pkispawn Step One Installation” has finished successfully, you can manually update the instance-specific configuration files before Section 7.3.2.4, “Starting the pkispawn Step Two Installation” is performed, where the actual configuration begins.
For required procedures, perform the actions described in this section after you have completed step 1 of the
pkispawn procedure.
For optional procedures, see Part III, “Configuring Certificate System”. Useful between-installation-step procedures include:
7.3.2.3.1. Enabling Signed Audit Logging 复制链接链接已复制到粘贴板!
复制链接链接已复制到粘贴板!
The signed audit logging feature enables the prevention of unauthorized log manipulation.
For details, see Section 13.3.1, “Enabling and Configuring Signed Audit Log”.
7.3.2.3.2. Setting the KRA into Encryption Mode 复制链接链接已复制到粘贴板!
复制链接链接已复制到粘贴板!
If you are using a Hardware Security Module (HSM) that does not support secure key extraction, it is necessary to set the Key Recovery Authority (KRA) into encryption mode. For details, see Section 12.2.2.2, “Solving Limitations of HSMs When Using AES Encryption in KRAs”.
7.3.2.3.3. Enabling OCSP 复制链接链接已复制到粘贴板!
复制链接链接已复制到粘贴板!
For details about enabling the Online Certificate Status Protocol (OCSP) see Section 9.4.1.2, “Enabling Certificate Revocation Checking for Subsystems”.
7.3.2.4. Starting the pkispawn Step Two Installation 复制链接链接已复制到粘贴板!
复制链接链接已复制到粘贴板!
After you have completed Section 7.3.2.3, “Configuration Between the Two
pkispawn Installation Steps”, start the second step of the pkispawn installation:
- Root CA:
# pkispawn -f /root/pki/config.root-CA.txt -s CA --skip-installationIf the configuration step succeeds, thepkispawnutility displays an installation summary. For example:================================================================ INSTALLATION SUMMARY ================================================================ Administrator's username: caadmin Administrator's PKCS #12 file: /root/.dogtag/instance_name/ca_admin_cert.p12 To check the status of the subsystem: systemctl status pki-tomcatd@instance_name.service To restart the subsystem: systemctl restart pki-tomcatd@instance_name.service The URL for the subsystem is: https://server.example.com:8443/ca/ PKI instances will be enabled upon system boot ================================================================ - Subordinate CA or other non-CA subsystems:
- Submit the CSRs to a CA to issue the certificates.One major difference between installing non-root CA subsystems and a root CA is that prior to running step two of the
pkispawnutility, other subsystems require submitting the system certificate signing requests (CSR) to a CA:In the first step of the section called “Settings for Other Subsystems”, you added the*_csr_pathparameters in thepkispawnconfiguration file for the subsystems to be installed. If the first step ofpkispawnsucceeded, Certificate System generated and stored the CSRs in the specified paths. These certificate requests are in PKCS#10 format and you must convert them to Certificate Management over CMS (CMC) format before submitting them to the CA. Follow instructions specified at 4.2. Creating Certificate Signing Requests in Red Hat Certificate System Administration Guide. You need the resulting system certificates when you execute the second step of thepkispawncommand.Additionally, you need the issuing CA's certificate chain in PKCS#7 format. To retrieve it:- Access the issuing CA's EE URL.
- Navigate to
and click Display the CA certificate chain in PKCS#7 for importing into a server. - Click .
- Copy the displayed PKCS#7-formatted output into a text file, such as
/root/pki/cert_chain.p7b, on the Certificate System host.
- Create a configuration file for the second step of the
pkispawncommand:- Copy the
pkispawnconfiguration file from the first step and edit the newly created file for step two of thepkispawncommand:- In the
[DEFAULT]section, set the path to the issuing CA's certificate chain file you prepared in the previous step and the CA signing certificate's nickname. For example:[DEFAULT] pki_ca_signing_nickname=CA Signing Certificate pki_ca_signing_cert_path=/root/pki/cert_chain.p7b - Add the following settings to the subsystem-specific section (
[CA],[KRA], or[OCSP]) depending on the subsystem you install:- Subordinate CA
pki_ca_signing_crt_path=/root/pki/subsystem/ocsp_signing.crt pki_subsystem_crt_path=/root/pki/subsystem/subsystem.crt pki_sslserver_crt_path=/root/pki/subsystem/sslserver.crt pki_audit_signing_crt_path=/root/pki/subsystem/ca_audit_signing.crt pki_admin_crt_path=/root/pki/subsystem/ca_admin.crt pki_external_step_two=True- OCSP
pki_ocsp_signing_crt_path=/root/pki/subsystem/ocsp_signing.crt pki_subsystem_crt_path=/root/pki/subsystem/subsystem.crt pki_sslserver_crt_path=/root/pki/subsystem/sslserver.crt pki_audit_signing_crt_path=/root/pki/subsystem/ocsp_audit_signing.crt pki_admin_crt_path=/root/pki/subsystem/ocsp_admin.crt pki_external_step_two=True- KRA
pki_storage_crt_path=/root/pki/subsystem/kra_storage.crt pki_transport_crt_path=/root/pki/subsystem/kra_transport.crt pki_subsystem_crt_path=/root/pki/subsystem/subsystem.crt pki_sslserver_crt_path=/root/pki/subsystem/sslserver.crt pki_audit_signing_crt_path=/root/pki/subsystem/kra_audit_signing.crt pki_admin_crt_path=/root/pki/subsystem/kra_admin.crt pki_external_step_two=True
- Run the pkispawn command:
# pkispawn -f /root/pki/config.subsystem.txt -s subsystemReplace subsystem with one of the following subsystems:CA,KRA, orOCSP. For example, for a KRA installation:# pkispawn -f /root/pki/config.KRA.txt -s KRA
TPS and TKS subsystems can be installed by using the
pkispawn single-step installation process.
pkispawn requires a configuration file.
Follow the section called “Subsystem-independent Settings” to fill in the subsystem-independent part of the
pkispawn configuration file.
In addition, under the
[DEFAULT] section add the following:
pki_security_domain_hostname=example.redhat.com
pki_security_domain_https_port=8443
pki_security_domain_user=caadmin
pki_security_domain_password=[SD password]
Then add the subsystem-specific section (
[TKS] or [TPS]) as following:
- TKS
- Set the following in the
[TKS]section:- Specify the following parameters to set the data of the bootstrap
TKSadmin user which is automatically created during the installation:pki_admin_nickname=bootstrap_TKS_admin pki_admin_name=bootstrap_TKS_administrator_name pki_admin_uid=tksadmin pki_admin_email=tksadmin@example.comRed Hat Certificate System assigns administrator and agent privileges to this bootstrap account. Use this account after the installation to create the administrator, and auditor accounts.
- TPS
- Set the following in the
[TPS]section:- Specify the following parameters to set the data of the bootstrap
TPSadmin user, which is automatically created during the installation:pki_admin_nickname=bootstrap_TPS_admin pki_admin_name=bootstrap_TPS_administrator_name pki_admin_uid=tpsadmin pki_admin_email=tpsadmin@example.comRed Hat Certificate System assigns administrator and agent privileges to this bootstrap account. Use this account after the installation to create the administrator, and the auditor accounts. - Set the LDAP base DN of the
TPSauthentication database:pki_authdb_basedn=base_DN_of_the_TPS_authentication_database - Enable the server-side key generation and archival:
pki_enable_server_side_keygen=True
7.3.3.2. Running pkispawn for single-step Installation 复制链接链接已复制到粘贴板!
复制链接链接已复制到粘贴板!
Run the pkispawn command:
# pkispawn -f /root/pki/config.TKS.txt -s TKS
or
# pkispawn -f /root/pki/config.TPS.txt -s TPS
7.3.3.3. Post-Installation for Single-Step Installation 复制链接链接已复制到粘贴板!
复制链接链接已复制到粘贴板!
Follow the procedures below:
Once you completed the procedures above, follow Section 7.4, “Post-installation Tasks” for additional post-installation actions.