Red Hat Summit Red Hat SummitSupportoConsoleSviluppatoriInizia una provaContatti

Questo contenuto non è disponibile nella lingua selezionata.

Chapter 7. Installing and configuring Red Hat Certificate System

Red Hat Certificate System provides different subsystems that can be installed individually. For example, you can install multiple subsystem instances on a single server or you can run them independently on different hosts. This enables you to adapt the installation to your environment to provide a higher availability, scalability, and fail-over support. This chapter describes the package installation and how to set up the individual subsystems.

The Certificate System includes the following subsystems:

  • Certificate Authority (CA)
  • Key Recovery Authority (KRA)
  • Online Certificate Status Protocol (OCSP) Responder
  • Token Key Service (TKS)
  • Token Processing System (TPS)

Each subsystem is installed and configured individually as a standalone Tomcat web server instance. However, Red Hat Certificate System additionally supports running a single shared Tomcat web server instance that can contain up to one of each subsystem.

7.1. Subsystem configuration order
Copia collegamento

The order in which the individual subsystems are set up is important because of relationships between the different subsystems:

  1. At least one CA running as a security domain is required before any of the other public key infrastructure (PKI) subsystems can be installed.
  2. Install the OCSP after the CA has been configured.
  3. The KRA, and TKS subsystems can be installed in any order, after the CA and OCSP have been configured.
  4. The TPS subsystem depends on the CA and TKS, and optionally on the KRA and OCSP subsystem.
Note

In certain situations, administrators want to install a standalone KRA or OCSP which do not require a CA running as a security domain. For details, see Section 7.4, “Installing PKI subsystems”.

7.2. Installing RHCS using the pkispawn utility
Copia collegamento

Note

If you are already familiar with pkispawn, you can go directly to Section 7.4, “Installing PKI subsystems”.

In Red Hat Certificate System, administrators set up the individual subsystems using the pkispawn utility. This section gives you an overall understanding of how installing using pkispawn works. Read it carefully to ensure that you make the right choices when following the installation procedures in Section 7.4, “Installing PKI subsystems”.

pkispawn provides two different modes of operation:

  • Interactive mode: The user is asked for the individual settings during the setup. Use this mode for simple deployments.
  • Batch mode: The values are read from a configuration file the user provides. Parameters not set in the configuration file use the defaults (details below).

In the remainder of this chapter, batch mode is assumed unless stated otherwise.

7.2.1. Creating the pkispawn configuration file
Copia collegamento

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:

  1. [DEFAULT] - subsystem-independent settings
  2. [Tomcat]
  3. [CA], [KRA], [OCSP], [TKS], [TPS], [ACME], or [EST] - the subsystem-specific sections

When it runs, pkispawn:

  1. Reads the default values from the /usr/share/pki/server/etc/default.cfg file. For further details, see the pki_default.cfg(5) man page.

    Important

    Do not edit the /usr/share/pki/server/etc/default.cfg file. Instead, you are instructed to create a configuration file that overrides the defaults. For details about using a configuration file, see the example pkispawn configuration files in the following sections that correspond to each different type of subsystem.

  2. Reads the administrator-provided configuration file mentioned above to override the default values.
  3. Performs the installation of the requested subsystem.
  4. Passes the settings to a Java servlet that performs the configuration based on the settings.

pkispawn settings

The following provides information on how to create a configuration file for pkispawn along with some of the major parameters. Please see the pkispawn(8) and pki_default.cfg(5) man pages, specifically /usr/share/pki/server/etc/default.cfg on details such as which [ ] section a parameter belongs to or the exact spelling of a parameter.

Create a text file for the pkispawn configuration settings, such as /root/pki/config.subsystem.txt, and fill it with the settings described below. You must add every setting under the corresponding [ ] section. You can refer to the /usr/share/pki/server/etc/default.cfg file to confirm the proper placement.

Important

This section describes a general minimum configuration. Depending on your environment, additional parameters may be necessary (see /usr/share/pki/server/etc/default.cfg). For additional examples, see the EXAMPLES section in the pkispawn(8) man page.

For descriptions about the parameters covered in this section, see the pki_default.cfg(5) man page.

Subsystem-independent settings

Both shared and separate PKI instances for subsystems are supported. A separate PKI instance runs as a standalone Java-based Apache Tomcat instance that contains a single PKI subsystem (CA, KRA, OCSP, TKS, or TPS), and must utilize a unique instance name and ports if co-located on the same machine. Whereas a shared instance runs as a single Java-based Apache Tomcat instance sharing the same instance name and ports, but may contain any combination of up to one of each type of PKI subsystem.

Independently of the subsystem you install, the following settings can be specified in the configuration file in the [DEFAULT] section:

  1. Set a unique instance name: 

    # pki_instance_name=instance_name
    Copy to Clipboard Toggle word wrap

  2. Set the host name: 

    # pki_hostname=server.example.com
    Copy to Clipboard Toggle word wrap
    Note

    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.

  3. Set the port numbers for the HTTP and HTTPS protocols: 

    pki_https_port=port_number
pki_http_port=port_number
    Copy to Clipboard Toggle word wrap
    Important

    To run more than one Certificate System instance on the same host, you must set unique ports in the pki_https_port and pki_http_port parameters that are not used by any other service on the host. By default, Certificate System uses port 8080 for HTTP and 8443 for HTTPS.

  4. Set the HSM-specific parameters: 

    pki_hsm_enable=<True|False>
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_name
    Copy to Clipboard Toggle word wrap

    For further details, see Section 6.2.4, “Preparing for installing Certificate System with an HSM”.

  5. 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=SHA256withRSA
    Copy to Clipboard Toggle word wrap

    Allowed choices for the key_algorithm parameters are: 

    SHA256withRSA
SHA384withRSA
SHA512withRSA
    Copy to Clipboard Toggle word wrap
    Note

    You can set these algorithm parameters to a value specified in the ca.profiles.defaultSigningAlgsAllowed parameter in the CA’s CS.cfg file. For details, see the B.2.10 Signing Algorithm Constraint appendix in the Administration Guide. Signature algorithm must match key_type.

  6. 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=SHA256withEC
    Copy to Clipboard Toggle word wrap

    Allowed choices for the key_algorithm parameters are: 

    SHA256withEC
SHA384withEC
SHA512withEC
    Copy to Clipboard Toggle word wrap
    Note

    You can set these algorithm parameters to a value specified in the ca.profiles.defaultSigningAlgsAllowed parameter in the CA’s CS.cfg file. For details, see the For details, see the Signing Algorithm Constraint appendix in the Administration Guide. The signature algorithm must match with key_type.

    For ECC, the allowed choices for key_size are: 

    nistp256
nistp384
nistp521
    Copy to Clipboard Toggle word wrap

    For ECC, the allowed choice for key_type is ecc.

  7. Set the client directory of the bootstrap admin user: 

    pki_client_dir=bootstrap_admin_directory
    Copy to Clipboard Toggle word wrap

    By default, the path is set to ~/.dogtag/instance_name/

    Important

    The pki_admin_* and pki_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.

  8. Set various passwords for the bootstrap admin user: 

    pki_admin_password=password
pki_client_database_password=password
pki_client_pkcs12_password=password
    Copy to Clipboard Toggle word wrap

  9. If you chose to set up TLS between Certificate System and Directory Server, use the following parameters in the configuration file:

    Note

    We need to first create a basic TLS server authentication connection. At the end, during post-installation, we will return and make the connection require a client authentication certificate to be presented to Directory Server. At that time, once client authentication is set up, the pki_ds_password would no longer be relevant. 

    pki_ds_database=back_end_database_name
pki_ds_hostname=host_name
pki_ds_secure_connection=True
pki_ds_secure_connection_ca_pem_file=path_to_CA_or_self-signed_certificate
pki_ds_password=password
pki_ds_ldaps_port=port
pki_ds_bind_dn=cn=Directory Manager
    Copy to Clipboard Toggle word wrap

    The value of the pki_ds_database parameter is a name used by the pkispawn utility to create the corresponding subsystem database on the Directory Server instance.

    The value of the pki_ds_hostname parameter depends on the install location of the Directory Server instance. This depends on the values used in Section 6.3.2.1, “Installing the Directory Server packages”.

    When you set pki_ds_secure_connection=True, the following parameters must be set:

    • pki_ds_secure_connection_ca_pem_file: Sets the fully-qualified path including the file name of the file which contains an exported copy of the Directory Server’s CA certificate. This file must exist prior to pkispawn being able to utilize it.
    • pki_ds_ldaps_port: Sets the value of the secure LDAPS port Directory Server is listening to. The default is 636.

  10. 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
    Copy to Clipboard Toggle word wrap

  11. For the CA that will act as a security domain, set the proper parameters: 

    # for a CA that acts as a security domain
pki_security_domain_hostname=
pki_security_domain_name=example.com Security Domain
pki_security_domain_user=caadmin
pki_security_domain_password=SD password
    Copy to Clipboard Toggle word wrap

[Tomcat] section:

  1. Set the Tomcat JServ Protocol (AJP) port: 

    pki_ajp_port=Tomcat_AJP_port
    Copy to Clipboard Toggle word wrap

  2. Set the Tomcat server port: 

    pki_tomcat_server_port=Tomcat_server_port
    Copy to Clipboard Toggle word wrap
Important

To run more than one PKI subsystem instance on the same host, you must set ports in the pki_ajp_port and pki_tomcat_server_port parameters that are not used by any other service on the host. By default, the pki_ajp_port is set to 8009 and pki_tomcat_server_port to 8005.

Subsystem-specific settings

After you have created the initial configuration file, add the subsystem-specific settings to it. Search for a list of the suitable parameters for each subsystem ([CA], [OCSP], [KRA], [TKS], [TPS], [ACME], or [EST]) in the /usr/share/pki/server/etc/default.cfg file.

7.2.2. Installation methods (single-step or two-step)
Copia collegamento

You can run pkispawn in either single-step installation or two-step installation:

Note

Unless overwritten by the <pki_instance_name> parameter, by default pkispawn installs the subsystem in a PKI server instance called pki-tomcat under the /var/lib/pki/pki-tomcat directory. Multiple subsystems can be installed in the same instance.

Sample deployment configuration files can be found in Appendix XXX [NEEDS UPDATING].

7.2.2.1. Single-step installation
Copia collegamento

In a single-step installation process, an administrator first creates a pkispawn configuration file and then runs pkispawn against this file as follows: 

# pkispawn -s [CA, OCSP, KRA, TKS, TPS, ACME, EST] -f cs_inst.cfg –debug
Copy to Clipboard Toggle word wrap
Note

Before starting the installation, it is good practice to first run the pkispawn command with the --precheck option to validate the configuration file.

For example, for the CA: 

# pkispawn -s CA -f rootca_inst.cfg --precheck --debug
# pkispawn -s CA -f rootca_inst.cfg --debug
Copy to Clipboard Toggle word wrap

For a complete example, see Section 7.3.1, “Installing a root CA using the pkispawn single-step method”.

7.2.2.2. Two-step installation
Copia collegamento

In a two-step installation, an administrator first creates a pkispawn configuration file and then runs pkispawn twice against the same pkispawn configuration file. In between the execution of the pkispawn utility, the administrator is allowed to manually update various configuration files, for example enrollment profiles, cs.cfg etc. This method allows for better customization.

These two distinct stages of the two-step installation method are outlined below:

  • First step (installation)

    • Create pkispawn configuration file.
    • Run pkispawn (installation)

  • Second step (configuration)

    • Customization of the configuration
    • Run pkispawn (configuration)

First step (installation)

During this step, when run, pkispawn copies configuration files from the /usr/share/pki/ directory to the instance-specific /etc/pki/instance_name/ directory. Additionally, pkispawn sets the settings based on values defined in the deployment configuration file.

This part of the installation requires the following two substeps by the administrators:

  1. Creating the pkispawn configuration file. See Section 7.2.1, “Creating the pkispawn configuration file”.

  2. Run pkispawn as follows: 

    # pkispawn -s [CA, OCSP, KRA, TKS, TPS] -f cs_inst.cfg --skip-configuration –debug
    Copy to Clipboard Toggle word wrap
    Note

    Before starting the installation, it is good practice to first run the pkispawn command with the --precheck option to validate the configuration file.

    For example, for the CA: 

    # pkispawn -s CA -f rootca_inst.cfg --skip-configuration --precheck --debug
# pkispawn -s CA -f rootca_inst.cfg --skip-configuration --debug
    Copy to Clipboard Toggle word wrap

Second step (configuration)

During the second step, pkispawn continues the installation based on the configuration files in the instance-specific /etc/pki/instance_name/ directory.

This part of the installation requires the following two substeps by the administrators:

  1. Customization: This is an opportunity to manually update some instance-specific configuration files before the next substep. Parameters you customize at this point are in general things that you cannot configure in the pkispawn configuration file but would affect the outcome or behavior of the system. For example, modifying system certificate enrollment profiles (*.profile) under /var/lib/pki/<CA instance name>/ca/conf/ (see Chapter 15, Configuring certificate profiles). For example:

    1. Adding a desired certificate extension (which is not in the default profile) to a system certificate by editing the corresponding system certificate profile
    2. Changing the validity period of a system certificate by editing the corresponding system certificate profile

  2. Run pkispawn against the same pkispawn file as the first step but in a different manner as the following: 

    # pkispawn -s [CA, OCSP, KRA, TKS, TPS] -f cs_inst.cfg --skip-installation –debug
    Copy to Clipboard Toggle word wrap
Note

Before starting the installation, it is good practice to first run a precheck using the configuration file.

For example, for the CA: 

# pkispawn -s CA -f rootca_inst.cfg --skip-installation --precheck --debug
# pkispawn -s CA -f rootca_inst.cfg --skip-installation --debug
Copy to Clipboard Toggle word wrap

For a complete example, see Section 7.3.2, “Installing a root CA using the pkispawn two-step method”.

7.3. Setting Up a Root Certificate Authority (examples)
Copia collegamento

Note

If you are already familiar with pkispawn, you can go directly to Section 7.4, “Installing PKI subsystems”)

This section provides two examples on how to install a root CA:

  • Installing a root CA using the pkispawn single-step method.
  • Installing a root CA using the pkispawn two-step method.

7.3.1. Installing a root CA using the pkispawn single-step method
Copia collegamento

Configuring a RootCA instance using the single-step method requires creating a configuration file and running the pkispawn tool once.

In this example, the RootCA is installed on pki.example.com (as well as other instances), with its internal directory server on dir.example.com.

Prerequisites

Procedure

  1. Create a CA installation file at a chosen location (e.g. /root/pki_rsa) on the machine that will host the RHCS instance (pki.example.com). 

    # cd /root/pki_rsa
# vi rootca_inst.cfg
    Copy to Clipboard Toggle word wrap
    Note

    Unless explicitly specified, system certificate nicknames are automatically named bearing the value specified for pki_instance_name. To avoid certificate nickname conflicts on a shared HSM, use a unique instance name for each instance creation.

    The values specified in the installation file below are examples. In addition to changing the HSM password, edit the values accordingly, for example ports, directories, nicknames, domains…​ 

    [DEFAULT]
pki_instance_name=rhcs10-RSA-RootCA
pki_https_port=8443
pki_http_port=8080

# Crypto Token
pki_hsm_enable=True
pki_hsm_libfile=/opt/nfast/toolkits/pkcs11/libcknfast.so
pki_hsm_modulename=nfast
pki_token_name=NHSM-CONN-XC
pki_token_password=<YourHSMpassword>

pki_audit_signing_token=NHSM-CONN-XC
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_subsystem_token=NHSM-CONN-XC
pki_subsystem_key_algorithm=SHA256withRSA
pki_subsystem_signing_algorithm=SHA256withRSA
pki_subsystem_key_size=2048
pki_subsystem_key_type=rsa

pki_sslserver_token=NHSM-CONN-XC
pki_sslserver_key_algorithm=SHA256withRSA
pki_sslserver_signing_algorithm=SHA256withRSA
pki_sslserver_key_size=2048
pki_sslserver_key_type=rsa

# Bootstrap Admin
pki_admin_password=SECret.123
pki_admin_key_type=rsa
pki_admin_key_size=2048
pki_admin_key_algorithm=SHA256withRSA

# Bootstrap Admin client dir
# by default, if pki_client_dir, pki_client_database_dir,
# and pki_client_admin_cert_p12 are not specified, items will be placed
# under some default directories in /root/.dogtag
pki_client_admin_cert_p12=/opt/pki_rsa/rhcs10-RSA-RootCA/ca_admin_cert.p12
pki_client_database_dir=/opt/pki_rsa/rhcs10-RSA-RootCA/certs_db
pki_client_database_password=SECret.123
pki_client_dir=/opt/pki_rsa/rhcs10-RSA-RootCA
pki_client_pkcs12_password=SECret.123

# Internal LDAP
pki_ds_bind_dn=cn=Directory Manager
pki_ds_ldap_port=389
pki_ds_ldaps_port=636
pki_ds_password=SECret.123
pki_ds_remove_data=True
pki_ds_secure_connection=True
pki_ds_secure_connection_ca_pem_file=/opt/pki_rsa/temp-dirsrv-rootca-cert.pem
pki_ds_secure_connection_ca_nickname=DS temp CA certificate

# Security Domain
pki_security_domain_hostname=rhcs10.example.com
pki_security_domain_name=Example-rhcs10-RSA-RootCA
pki_security_domain_password=SECret.123


[Tomcat]
pki_ajp_port=8009
pki_tomcat_server_port=8005


[CA]
pki_import_admin_cert=False
pki_admin_nickname=PKI Bootstrap Administrator for RSA-RootCA
pki_admin_name=caadmin
pki_admin_uid=caadmin
pki_admin_email=caadmin@example.com

pki_ca_signing_token=NHSM-CONN-XC
pki_ca_signing_key_algorithm=SHA256withRSA
pki_ca_signing_key_size=3072
pki_ca_signing_key_type=rsa
pki_ca_signing_nickname=CA Signing Cert - %(pki_instance_name)s
pki_ca_signing_signing_algorithm=SHA256withRSA

pki_ocsp_signing_token=NHSM-CONN-XC
pki_ocsp_signing_key_algorithm=SHA256withRSA
pki_ocsp_signing_key_size=3072
pki_ocsp_signing_key_type=rsa
pki_ocsp_signing_signing_algorithm=SHA256withRSA

pki_ds_hostname=dir.example.com
pki_ds_base_dn=dc=RSA-RootCA
pki_ds_database=CC-RSA-RootCA-LDAP
pki_share_db=False
    Copy to Clipboard Toggle word wrap

  2. Run the pkispawn tool to install the RHCS CA instance: 

    pkispawn -s CA -f rootca_inst.cfg --debug
    Copy to Clipboard Toggle word wrap

Verification steps

  1. Show the status of the installed CA: 

    pki-server status rhcs10-RSA-RootCA
    Copy to Clipboard Toggle word wrap

  2. Verify the sanity of the CA by running the following command. It should display certificates: 

    pki -p 8443 -h pki.example.com ca-cert-find
    Copy to Clipboard Toggle word wrap
    Note

    An untrusted issuer warning for the CA signing certificate will display when connecting to the RootCA with a pki command for the first time, as seen below: 

    WARNING: UNTRUSTED ISSUER encountered on 'CN=pki.example.com,OU=rhcs10-RSA-RootCA,O=Example-rhcs10-RSA-RootCA' indicates a non-trusted CA cert 'CN=CA Signing Certificate,OU=rhcs10-RSA-RootCA,O=Example-rhcs10-RSA-RootCA'
Trust this certificate (y/N)?
    Copy to Clipboard Toggle word wrap

    Select y to trust the CA signing cert if the Subject DN matches the hostname as expected. The warning will not display again.

7.3.2. Installing a root CA using the pkispawn two-step method
Copia collegamento

Configuring a RootCA instance using the two-step method requires creating a configuration file and running the pkispawn tool twice.

In this example, the RootCA is installed on pki.example.com.

Prerequisites

  • You are logged in to pki.example.com as root user.
  • You have run the steps in Section 6.3.2, “Set up a DS instance” [NEEDS UPDATING]. In our example, CC-RSA-RootCA-LDAP is the RootCA’s internal database.

7.3.2.1. First step of RootCA installation
Copia collegamento

  1. Create a CA installation file at a chosen location, for example, /root/pki_rsa, on the machine that will host the RHCS instance, pki.example.com. 

    cd /root/pki_rsa

vi rootca_inst.cfg
    Copy to Clipboard Toggle word wrap 
    [DEFAULT]
pki_instance_name=rhcs10-RSA-RootCA
pki_https_port=8443
pki_http_port=8080

# Crypto Token
pki_hsm_enable=True
pki_hsm_libfile=/opt/nfast/toolkits/pkcs11/libcknfast.so
pki_hsm_modulename=nfast
pki_token_name=NHSM-CONN-XC
pki_token_password=<YourHSMpassword>

pki_audit_signing_token=NHSM-CONN-XC
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_subsystem_token=NHSM-CONN-XC
pki_subsystem_key_algorithm=SHA256withRSA
pki_subsystem_signing_algorithm=SHA256withRSA
pki_subsystem_key_size=2048
pki_subsystem_key_type=rsa

pki_sslserver_token=NHSM-CONN-XC
pki_sslserver_key_algorithm=SHA256withRSA
pki_sslserver_signing_algorithm=SHA256withRSA
pki_sslserver_key_size=2048
pki_sslserver_key_type=rsa

# Bootstrap Admin
pki_admin_password=SECret.123
pki_admin_key_type=rsa
pki_admin_key_size=2048
pki_admin_key_algorithm=SHA256withRSA

# Bootstrap Admin client dir
# by default, if pki_client_dir, pki_client_database_dir,
# and pki_client_admin_cert_p12 are not specified, items will be placed
# under some default directories in /root/.dogtag
pki_client_dir=/opt/pki_rsa/rhcs10-RSA-RootCA
pki_client_admin_cert_p12=/opt/pki_rsa/rhcs10-RSA-RootCA/ca_admin_cert.p12
pki_client_database_dir=/opt/pki_rsa/rhcs10-RSA-RootCA/certs_db
pki_client_database_password=SECret.123
pki_client_pkcs12_password=SECret.123

# Internal LDAP
pki_ds_bind_dn=cn=Directory Manager
pki_ds_ldap_port=389
pki_ds_ldaps_port=636
pki_ds_password=SECret.123
pki_ds_remove_data=True
pki_ds_secure_connection=True
pki_ds_secure_connection_ca_pem_file=/opt/pki_rsa/temp-dirsrv-rootca-cert.pem
pki_ds_secure_connection_ca_nickname=DS temp CA certificate

# Security Domain
pki_security_domain_hostname=rhcs10.example.com
pki_security_domain_name=Example-rhcs10-RSA-RootCA
pki_security_domain_password=SECret.123


[Tomcat]
pki_ajp_port=8009
pki_tomcat_server_port=8005


[CA]
pki_import_admin_cert=False
pki_admin_nickname=PKI Bootstrap Administrator for RSA-RootCA
pki_admin_name=caadmin
pki_admin_uid=caadmin
pki_admin_email=caadmin@example.com

pki_ca_signing_token=NHSM-CONN-XC
pki_ca_signing_key_algorithm=SHA256withRSA
pki_ca_signing_key_size=3072
pki_ca_signing_key_type=rsa
pki_ca_signing_nickname=CA Signing Cert - %(pki_instance_name)s
pki_ca_signing_signing_algorithm=SHA256withRSA

pki_ocsp_signing_token=NHSM-CONN-XC
pki_ocsp_signing_key_algorithm=SHA256withRSA
pki_ocsp_signing_key_size=3072
pki_ocsp_signing_key_type=rsa
pki_ocsp_signing_signing_algorithm=SHA256withRSA

pki_ds_hostname=dir.example.com
pki_ds_base_dn=dc=RSA-RootCA
pki_ds_database=CC-RSA-RootCA-LDAP
pki_share_db=False
    Copy to Clipboard Toggle word wrap
    Note

    Unless explicitly specified, system certificate nicknames are automatically named bearing the value specified for pki_instance_name. To avoid certificate nickname conflicts on a shared HSM, use a unique instance name for each instance creation. However, in a two-step installation, the pki_instance_name value of both files should match. The following values are just examples.

  2. Run the pkispawn tool the first time to install the RHCS CA instance: 

    pkispawn -s CA -f rootca_inst.cfg --skip-configuration --debug
    Copy to Clipboard Toggle word wrap

7.3.2.2. Second step of RootCA configuration
Copia collegamento

As explained in Section 7.2.2, “Installation methods (single-step or two-step)”, there are two substeps in the second step of the two-step installation method.

Customization

In this substep, you can customize certain things, such as the certificate profile of a system certificate.

  • Setting the Subject Key Identifier extension message digest algorithm for the CA signing certificate:

    1. Open the enrollment profile for this CA’s signing certificate: 

      # vi /var/lib/pki/rhcs10-RSA-RootCA/ca/conf/caCert.profile
      Copy to Clipboard Toggle word wrap

    2. Add the following parameter: 

      7.default.params.messageDigest=SHA-256
      Copy to Clipboard Toggle word wrap
    3. Save the file.

  • Likewise, do the same for the CA signing cert that this CA will be issuing in the future:

    1. Open the enrollment profile for the CA signing certificate: 

      # vi /var/lib/pki/rhcs10-RSA-RootCA/ca/profiles/ca/caInstallCACert.cfg

# vi /var/lib/pki/rhcs10-RSA-RootCA/ca/profiles/ca/caCMCcaCert.cfg
      Copy to Clipboard Toggle word wrap

    2. Add the following parameter: 

      policyset.caCertSet.8.default.params.messageDigest=SHA-256
      Copy to Clipboard Toggle word wrap
    3. Save the file.

  • Other customization changes can take place here too. For example, if you wish to extend the validity period of the audit signing certificate of this subsystem:

    1. Open the corresponding configuration file: 

      # vi /var/lib/pki/rhcs10-RSA-RootCA/ca/profiles/ca/caInternalAuthAuditSigningCert.cfg
      Copy to Clipboard Toggle word wrap

    2. Change the following range parameters to the desired values: 

      policyset.auditSigningCertSet.2.constraint.params.range=720
policyset.auditSigningCertSet.2.default.params.range=720
      Copy to Clipboard Toggle word wrap
    3. Save the file. Once you have done the second step of pkispawn in the next section, you should expect the validity of the audit signing certificate of this subsystem to match the values you have changed to.

Running pkispawn the second time (Configuration)

The second step of pkispawn in this case involves running the tool against the same file in a different manner to configure the RHCS CA instance.

  • Run the pkispawn tool to configure the CA: 

    # pkispawn -s CA -f rootca_inst.cfg --skip-installation --debug
    Copy to Clipboard Toggle word wrap

Verification steps

  1. Show the status of the installed CA: 

    # pki-server status rhcs10-RSA-RootCA
    Copy to Clipboard Toggle word wrap

    Note down the Unsecure EE, Secure EE, Agent, Admin and pkiconsole URLs.

  2. Verify the sanity of the CA by running the following command. It should display certificates: 

    # pki -p 8443 -h pki.example.com ca-cert-find
    Copy to Clipboard Toggle word wrap
    Note

    An untrusted issuer warning for the CA signing certificate will display when connecting to the RootCA with a pki command for the first time, as seen below: 

    WARNING: UNTRUSTED ISSUER encountered on 'CN=pki.example.com,OU=rhcs10-RSA-RootCA,O=Example-rhcs10-RSA-RootCA' indicates a non-trusted CA cert 'CN=CA Signing Certificate,OU=rhcs10-RSA-RootCA,O=Example-rhcs10-RSA-RootCA'
Trust this certificate (y/N)?
    Copy to Clipboard Toggle word wrap

    Select y to trust the CA signing cert if the Subject DN matches the hostname as expected. The warning will not display again.

7.4. Installing PKI subsystems
Copia collegamento

Red Hat Certificate System provides different subsystems that can be installed individually. For example, you can install multiple subsystem instances on a single server or you can run them independently on different hosts. This enables you to adapt the installation to your environment to provide a higher availability, scalability, and fail-over support.

Refer to the required RHCS subsystem guide below for installation guidance.

If you are not familiar with pkispawn, refer to Section 7.2, “Installing RHCS using the pkispawn utility” for a better understanding of the choices presented for each subsystem installation.

Important

Once completed, refer to Section 7.5, “Post-installation tasks” and follow the sections pertaining to the subsystem you are installing.

7.4.1. Installing the CA subsystem
Copia collegamento

7.4.1.1. Installing a CA
Copia collegamento

Follow this process to install a CA subsystem instance with a self-signed CA signing certificate. It is also known as a "root CA".

Prior to installation, ensure that the Installation Prerequisites are configured.

7.4.1.1.1. Installing the CA subsystem
Copia collegamento

Prepare a deployment configuration, for example ca.cfg, to deploy CA subsystem. By default the subsystem is deployed into a Tomcat instance called pki-tomcat.

A sample deployment configuration is available at /usr/share/pki/server/examples/installation/ca.cfg.

To start the installation execute the following command: 

$ pkispawn -f ca.cfg -s CA
Copy to Clipboard Toggle word wrap
7.4.1.1.2. CA system certificates
Copia collegamento

After installation, the CA system certificates and keys are stored in the server NSS database (i.e. /var/lib/pki/pki-tomcat/conf/alias): 

$ certutil -L -d /var/lib/pki/pki-tomcat/conf/alias

Certificate Nickname                                         Trust Attributes
                                                             SSL,S/MIME,JAR/XPI

ca_signing                                                   CTu,Cu,Cu
ca_ocsp_signing                                              u,u,u
subsystem                                                    u,u,u
ca_audit_signing                                             u,u,Pu
sslserver                                                    u,u,u
Copy to Clipboard Toggle word wrap

If necessary, the certificates can be exported into PEM files by using the following command: 

$ pki-server cert-export <cert ID> --cert-file <filename>
Copy to Clipboard Toggle word wrap

The valid certificate IDs for CA are:

  • ca_signing
  • ca_ocsp_signing
  • ca_audit_signing
  • subsystem
  • sslserver

Note that the pki-server cert-export command takes a certificate ID instead of a nickname. For simplicity the nicknames in this example are configured to be the same as the certificate ID.

7.4.1.1.3. Admin certificate
Copia collegamento

After installation the admin certificate and key are stored in ~/.dogtag/pki-tomcat/ca_admin_cert.p12.

The PKCS #12 password is specified in the pki_client_pkcs12_password parameter.

To use the admin certificate, do the following.

  1. Export the CA signing certificate from the server NSS database: 

    $ pki-server cert-export ca_signing --cert-file ca_signing.crt
    Copy to Clipboard Toggle word wrap

  2. Import the CA signing certificate into the client NSS database: 

    $ pki nss-cert-import --cert ca_signing.crt --trust CT,C,C ca_signing
    Copy to Clipboard Toggle word wrap

  3. Import the admin certificate and key into the client NSS database (by default ~/.dogtag/nssdb) with the following command: 

    $ pki pkcs12-import \
    --pkcs12 ~/.dogtag/pki-tomcat/ca_admin_cert.p12 \
    --password Secret.123
    Copy to Clipboard Toggle word wrap

  4. Verify that the admin certificate can be used to access the CA subsystem by executing the following command: 

    $ pki -n caadmin ca-user-show caadmin
--------------
User "caadmin"
--------------
  User ID: caadmin
  Full name: caadmin
  Email: caadmin@example.com
  Type: adminType
  State: 1
    Copy to Clipboard Toggle word wrap

7.4.1.2. Installing CA clone
Copia collegamento

Follow this process to install a CA subsystem as a clone of an existing CA subsystem.

Prior to installation, ensure that the Installation Prerequisites are configured.

Additional useful tips:

  • Ensure that the firewall on the master allows external access to LDAP from the clone.
  • Ensure that the firewall on the clone allows external access to LDAP from the master.
7.4.1.2.1. Exporting existing CA system certificates
Copia collegamento

On the existing system, export the CA system certificates with the following command: 

$ pki-server ca-clone-prepare \
    --pkcs12-file ca-certs.p12 \
    --pkcs12-password Secret.123
Copy to Clipboard Toggle word wrap

The command exports the following certificates (including the certificate chain) and their keys into a PKCS #12 file:

  • CA signing certificate
  • OCSP signing certificate
  • audit signing certificate
  • subsystem certificate

Note that the existing SSL server certificate is not exported.

If necessary, third-party certificates, for example trust anchors, can be added into the same PKCS #12 file with the following command: 

$ pki -d /var/lib/pki/pki-tomcat/conf/alias -f /var/lib/pki/pki-tomcat/conf/password.conf \
    pkcs12-cert-import <nickname> \
    --pkcs12-file ca-certs.p12 \
    --pkcs12-password Secret.123 \
    --append
Copy to Clipboard Toggle word wrap

Optionally, the CSRs for the above certificates can be exported as well with the following commands: 

$ pki-server cert-export ca_signing \
    --csr-file ca_signing.csr

$ pki-server cert-export ca_ocsp_signing \
    --csr-file ca_ocsp_signing.csr

$ pki-server cert-export ca_audit_signing \
    --csr-file ca_audit_signing.csr

$ pki-server cert-export subsystem \
    --csr-file subsystem.csr
Copy to Clipboard Toggle word wrap
7.4.1.2.2. SELinux permissions
Copia collegamento

After copying the ca-certs.p12 to the clone machine, ensure that appropriate SELinux rules are added: 

$ semanage fcontext -a -t pki_tomcat_cert_t ca-certs.p12
$ restorecon -R -v ca-certs.p12
Copy to Clipboard Toggle word wrap

Ensure that the ca-certs.p12 file is owned by the pkiuser 

$ chown pkiuser:pkiuser ca-certs.p12
Copy to Clipboard Toggle word wrap
7.4.1.2.3. Installing the CA subsystem
Copia collegamento

Prepare a deployment configuration, for example ca-clone-w-p12.cfg, to deploy a CA subsystem clone. By default the subsystem is deployed into a Tomcat instance called pki-tomcat.

A sample deployment configuration is available at /usr/share/pki/server/examples/installation/ca-clone-w-p12.cfg.

It assumes that the:

  • The CA subsystem clone is running on a different machine than the primary CA subsystem. Note: In a test environment, if creating the clone on the same machine, the pki_instance_name and the port values (for PKI and DS) must be different.
  • CA signing certificate has been exported into ca_signing.crt
  • admin certificate and key have been exported into ca_admin_cert.p12
  • PKCS #12 password is specified in the pki_client_pkcs12_password parameter.
  • The CA is not using an HSM (which is a different installation case covered in section Installing CA clone with HSM).

See Installing CA for details.

If the CSRs are available, they can be specified with the following parameters: 

pki_ca_signing_csr_path=ca_signing.csr
pki_ocsp_signing_csr_path=ca_ocsp_signing.csr
pki_audit_signing_csr_path=ca_audit_signing.csr
pki_subsystem_csr_path=subsystem.csr
Copy to Clipboard Toggle word wrap

To start the installation, execute the following command: 

$ pkispawn -f ca-clone-w-p12.cfg -s CA
Copy to Clipboard Toggle word wrap
7.4.1.2.4. CA system certificates
Copia collegamento

After installation the existing CA system certificates (including the certificate chain) and their keys are stored in the server NSS database (i.e. /var/lib/pki/pki-tomcat/conf/alias), and a new SSL server certificate is created for the new instance: 

$ certutil -L -d /var/lib/pki/pki-tomcat/conf/alias

Certificate Nickname                                         Trust Attributes
                                                             SSL,S/MIME,JAR/XPI

ca_signing                                                   CTu,Cu,Cu
ca_ocsp_signing                                              u,u,u
subsystem                                                    u,u,u
ca_audit_signing                                             u,u,Pu
sslserver                                                    u,u,u
Copy to Clipboard Toggle word wrap

If necessary, the certificates can be exported into PEM files with the following command: 

$ pki-server cert-export <cert ID> --cert-file <filename>
Copy to Clipboard Toggle word wrap

The valid certificate IDs for CA are:

  • ca_signing
  • ca_ocsp_signing
  • ca_audit_signing
  • subsystem
  • sslserver

Note that the pki-server cert-export command takes a certificate ID instead of a nickname. For simplicity the nicknames in this example are configured to be the same as the certificate IDs.

7.4.1.2.5. Admin certificate
Copia collegamento

To use the admin certificate, do the following.

  1. Import the CA signing certificate into the client NSS database: 

    $ pki nss-cert-import --cert ca_signing.crt --trust CT,C,C ca_signing
    Copy to Clipboard Toggle word wrap

  2. Import the admin certificate and key into the client NSS database (by default ~/.dogtag/nssdb) with the following command: 

    $ pki pkcs12-import \
    --pkcs12 ca_admin_cert.p12 \
    --pkcs12-password Secret.123
    Copy to Clipboard Toggle word wrap

  3. To verify that the admin certificate can be used to access the CA subsystem clone, execute the following command: 

    $ pki -n caadmin ca-user-show caadmin
--------------
User "caadmin"
--------------
  User ID: caadmin
  Full name: caadmin
  Email: caadmin@example.com
  Type: adminType
  State: 1
    Copy to Clipboard Toggle word wrap

7.4.1.3. Installing CA clone with HSM
Copia collegamento

Follow this process to install a CA subsystem as a clone of an existing CA subsystem where the system certificates and their keys are stored on a HSM.

Prior to installation, ensure that the Installation Prerequisites are configured.

7.4.1.3.1. Exporting existing system certificates
Copia collegamento

Since the system certificates and the keys are already on a HSM, it is not necessary to export them into a PKCS #12 file to create a clone.

However, the CSRs for the system certificates are stored in CS.cfg instead of HSM.

They can optionally be exported with the following commands: 

$ pki-server cert-export ca_signing \
    --csr-file ca_signing.csr

$ pki-server cert-export ca_ocsp_signing \
    --csr-file ca_ocsp_signing.csr

$ pki-server cert-export ca_audit_signing \
    --csr-file ca_audit_signing.csr

$ pki-server cert-export subsystem \
    --csr-file subsystem.csr
Copy to Clipboard Toggle word wrap
7.4.1.3.2. CA subsystem installation
Copia collegamento

Note: It is assumed that the CA signing certificate has been exported into ca_signing.crt

  1. Prepare a file, for example ca.cfg, that contains the deployment configuration: 

    [DEFAULT]
pki_instance_name=pki-tomcat
pki_https_port=8443
pki_http_port=8080

pki_server_database_password=Secret.123

pki_hsm_enable=True
pki_hsm_libfile=/usr/lib64/pkcs11/libsofthsm2.so
pki_hsm_modulename=softhsm
pki_token_name=HSM
pki_token_password=Secret.HSM

pki_cert_chain_path=ca_signing.crt

[Tomcat]
pki_ajp_port=8009
pki_tomcat_server_port=8005

[CA]
pki_admin_email=caadmin@example.com
pki_admin_name=caadmin
pki_admin_nickname=caadmin
pki_admin_password=Secret.123
pki_admin_uid=caadmin

pki_client_pkcs12_password=Secret.123

pki_ds_url=ldap://localhost.localdomain:389
pki_ds_base_dn=dc=ca,dc=pki,dc=example,dc=com
pki_ds_database=ca
pki_ds_password=Secret.123

pki_security_domain_hostname=pki.example.com
pki_security_domain_https_port=8443
pki_security_domain_user=caadmin
pki_security_domain_password=Secret.123

pki_ca_signing_nickname=ca_signing
pki_ocsp_signing_nickname=ca_ocsp_signing
pki_audit_signing_nickname=ca_audit_signing
pki_sslserver_nickname=sslserver/replica.example.com
pki_subsystem_nickname=subsystem

pki_ca_signing_token=HSM
pki_ocsp_signing_token=HSM
pki_audit_signing_token=HSM
pki_sslserver_token=HSM
pki_subsystem_token=HSM

pki_clone=True
pki_clone_replicate_schema=True
pki_clone_uri=https://pki.example.com:8443
    Copy to Clipboard Toggle word wrap

  2. If the CSRs are available, they can be specified with the following parameters: 

    pki_ca_signing_csr_path=ca_signing.csr
pki_ocsp_signing_csr_path=ca_ocsp_signing.csr
pki_audit_signing_csr_path=ca_audit_signing.csr
pki_subsystem_csr_path=subsystem.csr
    Copy to Clipboard Toggle word wrap

  3. Execute the following command: 

    $ pkispawn -f ca.cfg -s CA
    Copy to Clipboard Toggle word wrap

It installs a CA subsystem in a Tomcat instance (default is pki-tomcat) and creates the following NSS databases:

  • server NSS database: /var/lib/pki/pki-tomcat/conf/alias
  • admin NSS database: ~/.dogtag/pki-tomcat/ca/alias
7.4.1.3.3. Verifying system certificates
Copia collegamento

  1. Verify that the internal token contains the following certificates: 

    $ certutil -L -d /var/lib/pki/pki-tomcat/conf/alias

Certificate Nickname                                         Trust Attributes
                                                             SSL,S/MIME,JAR/XPI

ca_signing                                                   CT,C,C
sslserver/replica.example.com                                ,,
ca_audit_signing                                             ,,P
    Copy to Clipboard Toggle word wrap

  2. Verify that the HSM contains the following certificates: 

    $ certutil -L -d /var/lib/pki/pki-tomcat/conf/alias -h HSM -f HSM.pwd

Certificate Nickname                                         Trust Attributes
                                                             SSL,S/MIME,JAR/XPI

HSM:ca_signing                                               CTu,Cu,Cu
HSM:ca_ocsp_signing                                          u,u,u
HSM:subsystem                                                u,u,u
HSM:ca_audit_signing                                         u,u,Pu
HSM:sslserver/replica.example.com                            u,u,u
    Copy to Clipboard Toggle word wrap
7.4.1.3.4. Verifying admin certificate
Copia collegamento

  1. Import the CA signing certificate: 

    $ pki nss-cert-import --cert ca_signing.crt --trust CT,C,C ca_signing
    Copy to Clipboard Toggle word wrap

  2. Import the master’s admin key and certificate: 

    $ pki -c Secret.123 pkcs12-import \
    --pkcs12 ca_admin_cert.p12 \
    --pkcs12-password Secret.123
    Copy to Clipboard Toggle word wrap

  3. Verify that the admin certificate can be used to access the CA clone by executing the following command: 

    $ pki -c Secret.123 -n caadmin ca-user-show caadmin
--------------
User "caadmin"
--------------
  User ID: caadmin
  Full name: caadmin
  Email: caadmin@example.com
  Type: adminType
  State: 1
    Copy to Clipboard Toggle word wrap

7.4.1.4. Installing CA clone with LDAPS connection
Copia collegamento

Follow this process to install a CA subsystem as clone of an existing CA subsystem with a secure database connection.

Prior to installation, ensure that the Installation Prerequisites are configured.

7.4.1.4.1. DS configuration
Copia collegamento

Once the prerequisites listed above are completed on the clone system, follow the procedure in enable SSL Connection with DS so that the CA clone’s DS is running with SSL enabled with a real server certificate issued by the CA.

Some useful tips:

  • Ensure the firewall on the master allows external access to LDAP from the clone.
  • Ensure the firewall on the clone allows external access to LDAP from the master.
7.4.1.4.2. Exporting existing CA system certificates
Copia collegamento

On the existing system, export the CA system certificates and copy them to the clone system with the following command: 

$ pki-server ca-clone-prepare --pkcs12-file ca-certs.p12 --pkcs12-password Secret.123
$ pki-server cert-export ca_signing --cert-file ca_signing.crt
Copy to Clipboard Toggle word wrap

The following certificates (including the certificate chain) and their keys are exported into a PKCS #12 file:

  • CA signing certificate
  • OCSP signing certificate
  • audit signing certificate
  • subsystem certificate

Note that the existing SSL server certificate is not exported.

If necessary, third-party certificates, for example trust anchors, can be added into the same PKCS #12 file with the following command: 

$ pki -d /var/lib/pki/pki-tomcat/conf/alias -f /var/lib/pki/pki-tomcat/conf/password.conf \
    pkcs12-cert-import <nickname> \
    --pkcs12-file ca-certs.p12 \
    --pkcs12-password Secret.123 \
    --append
Copy to Clipboard Toggle word wrap
7.4.1.4.3. SELinux permissions
Copia collegamento

After copying the ca-certs.p12 to the clone machine, ensure that appropriate SELinux rules are added: 

$ semanage fcontext -a -t pki_tomcat_cert_t ca-certs.p12
$ restorecon -R -v ca-certs.p12
Copy to Clipboard Toggle word wrap

Ensure that the ca-certs.p12 file is owned by the pkiuser 

$ chown pkiuser:pkiuser ca-certs.p12
Copy to Clipboard Toggle word wrap
7.4.1.4.4. Installing the CA subsystem
Copia collegamento

Prepare a deployment configuration, for example ca-secure-ds-secondary.cfg, to deploy a CA subsystem clone. By default the subsystem is deployed into a Tomcat instance called pki-tomcat.

Note

The sample pkispawn config file referenced below expects the DS server certificate’s signing certificate to be in a file named ds_signing.crt. Since the existing CA is being used as the signing certificate, copy the CA’s signing certificate into ds_signing.crt: 

$ cp ca_signing.crt ds_signing.crt
Copy to Clipboard Toggle word wrap

A sample deployment configuration is available at /usr/share/pki/server/examples/installation/ca-secure-ds-secondary.cfg.

It assumes that:

  • The existing CA and DS instances are running on primary.example.com.
  • The new CA and DS clones are being installed on secondary.example.com.
  • The CA signing certificate has been exported into ca_signing.crt.
  • The admin certificate and key have been exported into ca_admin_cert.p12.
  • The PKCS #12 password is specified in the pki_client_pkcs12_password parameter.

To start the installation, execute the following command: 

$ pkispawn -f ca-secure-ds-secondary.cfg -s CA
Copy to Clipboard Toggle word wrap
7.4.1.4.5. CA system certificates
Copia collegamento

After installation the existing CA system certificates (including the certificate chain) and their keys are stored in the server NSS database (i.e. /var/lib/pki/pki-tomcat/conf/alias), and a new SSL server certificate is created for the new instance. Note that if the ds_signing certificate is the same certificate as ca_signing, it does not show in the following certutil listing: 

$ certutil -L -d /var/lib/pki/pki-tomcat/conf/alias

Certificate Nickname                                         Trust Attributes
                                                             SSL,S/MIME,JAR/XPI

subsystem                                                    u,u,u
ca_signing                                                   CTu,Cu,Cu
ca_ocsp_signing                                              u,u,u
ca_audit_signing                                             u,u,Pu
ds_signing                                                   CT,C,C
sslserver                                                    u,u,u
Copy to Clipboard Toggle word wrap

If necessary, the clone CA system certificates can be exported into PEM files with the following command: 

$ pki-server cert-export <cert ID> --cert-file <filename>
Copy to Clipboard Toggle word wrap

The valid certificate IDs for CA are:

  • ca_signing
  • ca_ocsp_signing
  • ca_audit_signing
  • subsystem
  • sslserver

Note that the pki-server cert-export command takes a certificate ID instead of a nickname. For simplicity the nicknames in this example are configured to be the same as the certificate IDs.

7.4.1.4.6. Admin certificate
Copia collegamento

To use the admin certificate, do the following.

  1. Import the CA signing certificate into the client NSS database: 

    $ pki nss-cert-import --cert ca_signing.crt --trust CT,C,C ca_signing
    Copy to Clipboard Toggle word wrap

  2. Import the admin certificate and key from the master CA into the client NSS database (by default ~/.dogtag/nssdb) with the following command: 

    $ pki pkcs12-import \
    --pkcs12 ca_admin_cert.p12 \
    --pkcs12-password Secret.123
    Copy to Clipboard Toggle word wrap

  3. Verify that the admin certificate can be used to access the CA subsystem clone by running the following command: 

    $ pki -n caadmin ca-user-show caadmin
--------------
User "caadmin"
--------------
  User ID: caadmin
  Full name: caadmin
  Email: caadmin@example.com
  Type: adminType
  State: 1
    Copy to Clipboard Toggle word wrap

7.4.1.5. Installing CA clone with LDAPS using bootstrap DS certificates
Copia collegamento

Follow this process to install a CA subsystem as a clone of an existing CA subsystem that runs with a bootstrap SSL server certificate. It is assumed that the DS clone was created with self_sign_cert = False.

Prior to installation, please ensure that the Installation Prerequisites are configured.

7.4.1.5.1. DS configuration
Copia collegamento

  1. Once the prerequisites listed above are completed on the clone system, go on the existing system and export the DS signing certificate into ds_signing.p12 and copy the certificate into clone system with the following command: 

    $ pki -d /etc/dirsrv/slapd-localhost \
-C /etc/dirsrv/slapd-localhost/pwdfile.txt \
pkcs12-export --pkcs12-file ds_signing.p12 \
--pkcs12-password Secret.123 Self-Signed-CA
    Copy to Clipboard Toggle word wrap

  2. Import the ds_signing.p12 into the clone DS instance with the following command: 

    $ pki -d /etc/dirsrv/slapd-localhost \
-C /etc/dirsrv/slapd-localhost/pwdfile.txt \
pkcs12-import --pkcs12-file ds_signing.p12 \
--pkcs12-password Secret.123
    Copy to Clipboard Toggle word wrap

  3. On the DS clone, create a bootstrap DS server certificate as described in Creating DS Server Certificate.

    Note that the certificate subject DN should match the clone’s hostname, that is, --subject "CN=secondary.example.com".

  4. Enable the SSL connection as described in Enabling SSL Connection.

  5. After the successful DS restart, export the DS Signing Certificate into 'ds_signing.crt' as follows: 

    $ certutil -L -d /etc/dirsrv/slapd-localhost -n Self-Signed-CA -a > ds_signing.crt
    Copy to Clipboard Toggle word wrap

Some useful tips:

  • Ensure the DS firewall allows access from PKI server and other DS instances.
7.4.1.5.2. Exporting existing CA system certificates
Copia collegamento

  1. On the existing system, export the CA system certificates and copy to clone system with the following command: 

    $ pki-server ca-clone-prepare --pkcs12-file ca-certs.p12 --pkcs12-password Secret.123
$ pki-server cert-export ca_signing --cert-file ca_signing.crt
    Copy to Clipboard Toggle word wrap

    The following certificates (including the certificate chain) and their keys are exported into a PKCS #12 file:

    • CA signing certificate
    • OCSP signing certificate
    • audit signing certificate
    • subsystem certificate

    Note that the existing SSL server certificate is not exported.

  2. If necessary, third-party certificates, for example trust anchors, can be added into the same PKCS #12 file with the following command: 

    $ pki -d /var/lib/pki/pki-tomcat/conf/alias -f /var/lib/pki/pki-tomcat/conf/password.conf \
    pkcs12-cert-import <nickname> \
    --pkcs12-file ca-certs.p12 \
    --pkcs12-password Secret.123 \
    --append
    Copy to Clipboard Toggle word wrap
7.4.1.5.3. SELinux permissions
Copia collegamento

  1. After copying the ca-certs.p12 to the clone machine, ensure that appropriate SELinux rules are added: 

    $ semanage fcontext -a -t pki_tomcat_cert_t ca-certs.p12
$ restorecon -R -v ca-certs.p12
    Copy to Clipboard Toggle word wrap

  2. Ensure that the ca-certs.p12 file is owned by the pkiuser: 

    $ chown pkiuser:pkiuser ca-certs.p12
    Copy to Clipboard Toggle word wrap
7.4.1.5.4. Installing a CA subsystem
Copia collegamento

Prepare a deployment configuration, for example ca-secure-ds-secondary.cfg, to deploy CA subsystem clone. By default the subsystem is deployed into a Tomcat instance called pki-tomcat.

A sample deployment configuration is available at /usr/share/pki/server/examples/installation/ca-secure-ds-secondary.cfg.

It assumes that:

  • The existing CA and DS instances are running on primary.example.com.
  • The new CA and DS clones are being installed on secondary.example.com.
  • The CA signing certificate has been exported into ca_signing.crt.
  • The admin certificate and key have been exported into ca_admin_cert.p12.
  • The PKCS #12 password is specified in the pki_client_pkcs12_password parameter.

To start the installation execute the following command: 

$ pkispawn -f ca-secure-ds-secondary.cfg -s CA
Copy to Clipboard Toggle word wrap
7.4.1.5.5. CA system certificates
Copia collegamento

After installation, the existing CA system certificates (including the certificate chain) and their keys are stored in the server NSS database, that is, /var/lib/pki/pki-tomcat/conf/alias) and a new SSL server certificate is created for the new instance: 

$ certutil -L -d /var/lib/pki/pki-tomcat/conf/alias

Certificate Nickname                                         Trust Attributes
                                                             SSL,S/MIME,JAR/XPI

subsystem                                                    u,u,u
ca_signing                                                   CTu,Cu,Cu
ca_ocsp_signing                                              u,u,u
ca_audit_signing                                             u,u,Pu
ds_signing                                                   CT,C,C
sslserver                                                    u,u,u
Copy to Clipboard Toggle word wrap

If necessary, the clone CA system certificates can be exported into PEM files with the following command: 

$ pki-server cert-export <cert ID> --cert-file <filename>
Copy to Clipboard Toggle word wrap

The valid certificate IDs for CA are:

  • ca_signing
  • ca_ocsp_signing
  • ca_audit_signing
  • subsystem
  • sslserver

Note that the pki-server cert-export command takes a certificate ID instead of a nickname. For simplicity the nicknames in this example are configured to be the same as the certificate IDs.

7.4.1.5.6. Admin certificate
Copia collegamento

To use the admin certificate, do the following.

  1. Import the CA signing certificate into the client NSS database: 

    $ pki nss-cert-import --cert ca_signing.crt --trust CT,C,C ca_signing
    Copy to Clipboard Toggle word wrap

  2. Import the admin certificate and key into the client NSS database (by default ~/.dogtag/nssdb) with the following command: 

    $ pki pkcs12-import \
    --pkcs12 ca_admin_cert.p12 \
    --pkcs12-password Secret.123
    Copy to Clipboard Toggle word wrap

  3. Verify that the admin certificate can be used to access the CA subsystem clone, execute the following command: 

    $ pki -n caadmin ca-user-show caadmin
--------------
User "caadmin"
--------------
  User ID: caadmin
  Full name: caadmin
  Email: caadmin@example.com
  Type: adminType
  State: 1
    Copy to Clipboard Toggle word wrap

7.4.1.6. Installing CA with custom CA signing key
Copia collegamento

Follow this process to install a CA subsystem with a custom CA signing key, CSR, and certificate.

Prior to installation, please ensure that the Installation Prerequisites are configured.

7.4.1.6.1. Starting the CA subsystem installation
Copia collegamento

  1. Prepare a file, for example ca-step1.cfg, that contains the deployment configuration for step 1: 

    [DEFAULT]
pki_instance_name=pki-tomcat
pki_https_port=8443
pki_http_port=8080
pki_server_database_password=Secret.123

[Tomcat]
pki_ajp_port=8009
pki_tomcat_server_port=8005

[CA]
pki_admin_email=caadmin@example.com
pki_admin_name=caadmin
pki_admin_nickname=caadmin
pki_admin_password=Secret.123
pki_admin_uid=caadmin

pki_client_pkcs12_password=Secret.123

pki_ds_url=ldap://localhost.localdomain:389
pki_ds_base_dn=dc=ca,dc=pki,dc=example,dc=com
pki_ds_database=ca
pki_ds_password=Secret.123

pki_security_domain_name=EXAMPLE

pki_ca_signing_nickname=ca_signing
pki_ocsp_signing_nickname=ca_ocsp_signing
pki_audit_signing_nickname=ca_audit_signing
pki_sslserver_nickname=sslserver
pki_subsystem_nickname=subsystem

pki_external=True
pki_external_step_two=False
    Copy to Clipboard Toggle word wrap

  2. Execute the following command: 

    $ pkispawn -f ca-step1.cfg -s CA
    Copy to Clipboard Toggle word wrap

It installs a CA subsystem in a Tomcat instance (default is pki-tomcat) and creates the following NSS databases:

  • server NSS database: /var/lib/pki/pki-tomcat/conf/alias
  • admin NSS database: ~/.dogtag/pki-tomcat/ca/alias

Since there is no CSR path parameter specified, it does not generate the CA signing key by default.

7.4.1.6.2. Generating CA signing key, CSR, and certificate
Copia collegamento

Generate a custom CA signing key in the server NSS database, then generate a CSR and store it in a file, for example ca_signing.csr.

Use the CSR to issue the CA signing certificate:

  • For root CA installation, generate a self-signed CA signing certificate.
  • For subordinate CA installation, submit the CSR to an external CA to issue the CA signing certificate.

Store the CA signing certificate in a file, for example ca_signing.crt. The CA signing certificate can be specified as a single certificate or a PKCS #7 certificate chain in PEM format.

If the CA signing certificate was issued by an external CA, store the external CA certificate chain in a file, for example external.crt. The certificate chain can be specified as a single certificate or a PKCS #7 certificate chain in PEM format. The certificate chain should include all CA certificates from the root CA to the external CA that issued the CA signing certificate, but it should not include the CA signing certificate itself.

7.4.1.6.3. Finishing the CA subsystem installation
Copia collegamento

Prepare another file, for example ca-step2.cfg, that contains the deployment configuration for step 2. The file can be copied from step 1, that is ca-step1.cfg, with additional changes below.

  1. Specify step 2 with the following parameter: 

    pki_external_step_two=True
    Copy to Clipboard Toggle word wrap

  2. Specify the custom CA signing CSR with the following parameter: 

    pki_ca_signing_csr_path=ca_signing.csr
    Copy to Clipboard Toggle word wrap

  3. Specify the custom CA signing certificate with the following parameter: 

    pki_ca_signing_cert_path=ca_signing.crt
    Copy to Clipboard Toggle word wrap

  4. If the CA signing certificate was issued by an external CA, specify the external CA certificate chain with the following parameters: 

    pki_cert_chain_nickname=external
pki_cert_chain_path=external.crt
    Copy to Clipboard Toggle word wrap

  5. Execute the following command: 

    $ pkispawn -f ca-step2.cfg -s CA
    Copy to Clipboard Toggle word wrap
7.4.1.6.4. Verifying the system certificates
Copia collegamento

Verify that the server NSS database contains the following certificates: 

$ certutil -L -d /var/lib/pki/pki-tomcat/conf/alias

Certificate Nickname                                         Trust Attributes
                                                             SSL,S/MIME,JAR/XPI

external                                                     CT,C,C
ca_signing                                                   CTu,Cu,Cu
ca_ocsp_signing                                              u,u,u
subsystem                                                    u,u,u
ca_audit_signing                                             u,u,Pu
sslserver                                                    u,u,u
Copy to Clipboard Toggle word wrap
7.4.1.6.5. Verifying admin certificate
Copia collegamento

  1. Import the external CA certificate chain: 

    $ pki -c Secret.123 client-cert-import --ca-cert external.crt
    Copy to Clipboard Toggle word wrap

  2. Import the CA signing certificate: 

    $ pki nss-cert-import --cert ca_signing.crt --trust CT,C,C ca_signing
    Copy to Clipboard Toggle word wrap

  3. Import admin certificate and key into the client NSS database (by default ~/.dogtag/nssdb) with the following command: 

    $ pki -c Secret.123 pkcs12-import \
    --pkcs12 ~/.dogtag/pki-tomcat/ca_admin_cert.p12 \
    --pkcs12-password Secret.123
    Copy to Clipboard Toggle word wrap

  4. Verify that the admin certificate can be used to access the CA subsystem by executing the following command: 

    $ pki -c Secret.123 -n caadmin ca-user-show caadmin
--------------
User "caadmin"
--------------
  User ID: caadmin
  Full name: caadmin
  Email: caadmin@example.com
  Type: adminType
  State: 1
    Copy to Clipboard Toggle word wrap

7.4.1.7. Installing CA with ECC
Copia collegamento

Follow this process to install a CA subsystem with ECC self-signed CA signing certificate.

Supported ECC curves:

  • nistp256
  • nistp384
  • nistp521

Supported ECC key algorithms:

  • SHA256withEC
  • SHA384withEC
  • SHA512withEC

Prior to installation, ensure that the Installation Prerequisites are configured.

7.4.1.7.1. Installing a CA subsystem
Copia collegamento

Prepare a deployment configuration, for example ca-ecc.cfg, to deploy CA subsystem. By default the subsystem is deployed into a Tomcat instance called pki-tomcat.

A sample deployment configuration is available at /usr/share/pki/server/examples/installation/ca-ecc.cfg.

To start the installation execute the following command: 

$ pkispawn -f ca-ecc.cfg -s CA
Copy to Clipboard Toggle word wrap
7.4.1.7.2. CA system certificates
Copia collegamento

After installation the CA system certificates and keys are stored in the server NSS database (i.e. /var/lib/pki/pki-tomcat/conf/alias): 

$ certutil -L -d /var/lib/pki/pki-tomcat/conf/alias

Certificate Nickname                                         Trust Attributes
                                                             SSL,S/MIME,JAR/XPI

ca_signing                                                   CTu,Cu,Cu
ca_ocsp_signing                                              u,u,u
subsystem                                                    u,u,u
ca_audit_signing                                             u,u,Pu
sslserver                                                    u,u,u
Copy to Clipboard Toggle word wrap

If necessary, the certificates can be exported into PEM files with the following command: 

$ pki-server cert-export <cert ID> --cert-file <filename>
Copy to Clipboard Toggle word wrap

The valid certificate IDs for CA are:

  • ca_signing
  • ca_ocsp_signing
  • ca_audit_signing
  • subsystem
  • sslserver

Note that the pki-server cert-export command takes a certificate ID instead of a nickname. For simplicity the nicknames in this example are configured to be the same as the certificate ID.

7.4.1.7.3. Admin certificate
Copia collegamento

After installation, the admin certificate and key are stored in ~/.dogtag/pki-tomcat/ca_admin_cert.p12. The PKCS #12 password is specified in the pki_client_pkcs12_password parameter.

To use the admin certificate, do the following.

  1. Export the CA signing certificate from the server NSS database: 

    $ pki-server cert-export ca_signing --cert-file ca_signing.crt
    Copy to Clipboard Toggle word wrap

  2. Import the CA signing certificate into the client NSS database: 

    $ pki nss-cert-import --cert ca_signing.crt --trust CT,C,C ca_signing
    Copy to Clipboard Toggle word wrap

  3. Import admin certificate and key into the client NSS database (by default ~/.dogtag/nssdb) with the following command: 

    $ pki pkcs12-import \
    --pkcs12 ~/.dogtag/pki-tomcat/ca_admin_cert.p12 \
    --pkcs12-password Secret.123
    Copy to Clipboard Toggle word wrap

  4. To verify that the admin certificate can be used to access the CA subsystem, execute the following command: 

    $ pki -n caadmin ca-user-show caadmin
--------------
User "caadmin"
--------------
  User ID: caadmin
  Full name: caadmin
  Email: caadmin@example.com
  Type: adminType
  State: 1
    Copy to Clipboard Toggle word wrap

7.4.1.8. Installing CA with existing keys in HSM
Copia collegamento

Follow this process to install a CA subsystem with the system keys, CSRs, and certificates from an existing CA where the keys are stored on a HSM.

To avoid conflicts with the existing CA subsystem, the new CA subsystem uses new SSL server and subsystem certificates, so they will not be included in the installation process.

Prior to installation, please ensure that the Installation Prerequisites are configured.

7.4.1.8.1. Starting a CA subsystem
Copia collegamento

  1. Prepare a file, for example ca-step1.cfg, that contains the deployment configuration in step 1: 

    [DEFAULT]
pki_instance_name=pki-tomcat
pki_https_port=8443
pki_http_port=8080
pki_server_database_password=Secret.123

pki_hsm_enable=True
pki_hsm_libfile=/usr/lib64/pkcs11/libsofthsm2.so
pki_hsm_modulename=softhsm
pki_token_name=HSM
pki_token_password=Secret.123

[Tomcat]
pki_ajp_port=8009
pki_tomcat_server_port=8005

[CA]
pki_admin_email=caadmin@example.com
pki_admin_name=caadmin
pki_admin_nickname=caadmin
pki_admin_password=Secret.123
pki_admin_uid=caadmin

pki_client_pkcs12_password=Secret.123

pki_ds_url=ldap://localhost.localdomain:389
pki_ds_base_dn=dc=ca,dc=pki,dc=example,dc=com
pki_ds_database=ca
pki_ds_password=Secret.123

pki_security_domain_name=EXAMPLE

pki_ca_signing_nickname=ca_signing
pki_ocsp_signing_nickname=ca_ocsp_signing
pki_audit_signing_nickname=ca_audit_signing
pki_sslserver_nickname=sslserver/pki.example.com
pki_subsystem_nickname=subsystem/pki.example.com

pki_external=True
pki_external_step_two=False
    Copy to Clipboard Toggle word wrap

  2. Execute the following command: 

    $ pkispawn -f ca-step1.cfg -s CA
    Copy to Clipboard Toggle word wrap

It installs a CA subsystem in a Tomcat instance (default is pki-tomcat) and creates the following NSS databases:

  • server NSS database: /var/lib/pki/pki-tomcat/conf/alias
  • admin NSS database: ~/.dogtag/pki-tomcat/ca/alias

Since there are no CSR path parameters specified, it does not generate CA system and admin keys.

7.4.1.8.2. Exporting existing system certificates and CSRs
Copia collegamento

  1. Export the system certificates from the existing CA with the following commands: 

    $ certutil -L -d /var/lib/pki/pki-tomcat/conf/alias -h HSM -f HSM.pwd -n "HSM:ca_signing" -a > ca_signing.crt
$ certutil -L -d /var/lib/pki/pki-tomcat/conf/alias -h HSM -f HSM.pwd -n "HSM:ca_ocsp_signing" -a > ca_ocsp_signing.crt
$ certutil -L -d /var/lib/pki/pki-tomcat/conf/alias -h HSM -f HSM.pwd -n "HSM:ca_audit_signing" -a > ca_audit_signing.crt
    Copy to Clipboard Toggle word wrap

  2. Export the CSRs from the existing CA with the following commands: 

    $ pki-server cert-export ca_signing \
    --csr-file ca_signing.csr

$ pki-server cert-export ca_ocsp_signing \
    --csr-file ca_ocsp_signing.csr

$ pki-server cert-export ca_audit_signing \
    --csr-file ca_audit_signing.csr
    Copy to Clipboard Toggle word wrap
7.4.1.8.3. Finishing a CA subsystem installation
Copia collegamento

Prepare another file, for example ca-step2.cfg, that contains the deployment configuration for step 2. The file can be copied from step 1, that is ca-step1.cfg, with additional changes below.

  1. Specify step 2 with the following parameter: 

    pki_external_step_two=True
    Copy to Clipboard Toggle word wrap

  2. Specify the existing certificates with the following parameters: 

    pki_ca_signing_cert_path=ca_signing.crt
pki_ocsp_signing_cert_path=ca_ocsp_signing.crt
pki_audit_signing_cert_path=ca_audit_signing.crt
    Copy to Clipboard Toggle word wrap

  3. Specify the existing CSRs with the following parameters: 

    pki_ca_signing_csr_path=ca_signing.csr
pki_ocsp_signing_csr_path=ca_ocsp_signing.csr
pki_audit_signing_csr_path=ca_audit_signing.csr
    Copy to Clipboard Toggle word wrap

  4. Execute the following command: 

    $ pkispawn -f ca-step2.cfg -s CA
    Copy to Clipboard Toggle word wrap
7.4.1.8.4. Verifying system certificates
Copia collegamento

  1. Verify that the internal token contains the following certificates: 

    $ certutil -L -d /var/lib/pki/pki-tomcat/conf/alias

Certificate Nickname                                         Trust Attributes
                                                             SSL,S/MIME,JAR/XPI

ca_signing                                                   CT,C,C
ca_audit_signing                                             ,,P
    Copy to Clipboard Toggle word wrap

  2. Verify that the HSM contains the following certificates: 

    $ certutil -L -d /var/lib/pki/pki-tomcat/conf/alias -h HSM -f HSM.pwd

Certificate Nickname                                         Trust Attributes
                                                             SSL,S/MIME,JAR/XPI

HSM:ca_signing                                               CTu,Cu,Cu
HSM:ca_ocsp_signing                                          u,u,u
HSM:subsystem/pki.example.com                                u,u,u
HSM:ca_audit_signing                                         u,u,Pu
HSM:sslserver/pki.example.com                                u,u,u
    Copy to Clipboard Toggle word wrap
7.4.1.8.5. Verifying the admin certificate
Copia collegamento

  1. Import the CA signing certificate: 

    $ pki nss-cert-import --cert ca_signing.crt --trust CT,C,C ca_signing
    Copy to Clipboard Toggle word wrap

  2. Import the admin certificate and key into the client NSS database (by default ~/.dogtag/nssdb) with the following command: 

    $ pki -c Secret.123 pkcs12-import \
    --pkcs12 ~/.dogtag/pki-tomcat/ca_admin_cert.p12 \
    --pkcs12-password Secret.123
    Copy to Clipboard Toggle word wrap

  3. Verify that the admin certificate can be used to access the CA subsystem by executing the following command: 

    $ pki -c Secret.123 -n caadmin ca-user-show caadmin
--------------
User "caadmin"
--------------
  User ID: caadmin
  Full name: caadmin
  Email: caadmin@example.com
  Type: adminType
  State: 1
    Copy to Clipboard Toggle word wrap

7.4.1.9. Installing CA with existing keys in internal token
Copia collegamento

Follow this process to install a CA subsystem with the system keys, CSRs, and certificates from an existing CA where the keys are stored on an internal token.

This method of installation could be useful for situations such as restoring an independent instance from a backup where the original server might not be available anymore.

To avoid conflicts with the existing CA subsystem, the new CA subsystem uses new SSL server and subsystem certificates, so they are not included in the installation process.

Prior to installation, ensure that the Installation Prerequisites are configured.

7.4.1.9.1. Starting a CA subsystem installation
Copia collegamento

Prepare a file, for example ca-existing-certs-step1.cfg, that contains the first deployment configuration.

A sample deployment configuration is available at /usr/share/pki/server/examples/installation/ca-existing-certs-step1.cfg.

Execute the following command: 

$ pkispawn -f ca-existing-certs-step1.cfg -s CA
Copy to Clipboard Toggle word wrap

It installs a CA subsystem in a Tomcat instance (default is pki-tomcat) and creates the following NSS databases:

  • server NSS database: /var/lib/pki/pki-tomcat/conf/alias
  • admin NSS database: ~/.dogtag/pki-tomcat/ca/alias

Since there are no CSR path parameters specified, it does not generate CA system and admin keys.

7.4.1.9.2. Exporting existing system keys, CSRs, certificates
Copia collegamento

  1. Export the system keys and certificates from the existing CA into a PKCS #12 file with the following command: 

    $ pki -d /var/lib/pki/pki-tomcat/conf/alias -c Secret.123 pkcs12-export \
  --pkcs12 ca-certs.p12 \
  --password Secret.123
$ pki pkcs12-cert-del --pkcs12-file ca-certs.p12 --pkcs12-password Secret.123 sslserver
$ pki pkcs12-cert-del --pkcs12-file ca-certs.p12 --pkcs12-password Secret.123 subsystem
    Copy to Clipboard Toggle word wrap

  2. Copy the CSRs from the existing CA to the pkispawn directory on the host where the new CA is being created, for example: 

    cp /etc/pki/pki-tomcat/certs/* /root
    Copy to Clipboard Toggle word wrap
7.4.1.9.3. Finishing a CA subsystem installation
Copia collegamento

  1. Prepare another file, for example ca-existing-certs-step2.cfg, that contains the second deployment configuration.

    The file can be created from the first file, that is ca-existing-certs-step1.cfg, with the following changes: 

    pki_external_step_two=True
    Copy to Clipboard Toggle word wrap

  2. Specify the existing keys and certificates in the PKCS #12 file with the following parameters: 

    pki_pkcs12_path=ca-certs.p12
pki_pkcs12_password=Secret.123
    Copy to Clipboard Toggle word wrap

  3. Specify the existing CSRs with the following parameters: 

    pki_ca_signing_csr_path=ca_signing.csr
pki_ocsp_signing_csr_path=ca_ocsp_signing.csr
pki_audit_signing_csr_path=ca_audit_signing.csr
    Copy to Clipboard Toggle word wrap

    A sample deployment configuration is available at /usr/share/pki/server/examples/installation/ca-existing-certs-step2.cfg.

  4. Execute the following command: 

    $ pkispawn -f ca-existing-certs-step2.cfg -s CA
    Copy to Clipboard Toggle word wrap
7.4.1.9.4. Verifying system certificates
Copia collegamento

Verify that the server NSS database contains the following certificates: 

$ certutil -L -d /var/lib/pki/pki-tomcat/conf/alias

Certificate Nickname                                         Trust Attributes
                                                             SSL,S/MIME,JAR/XPI

ca_signing                                                   CTu,Cu,Cu
ca_ocsp_signing                                              u,u,u
subsystem                                                    u,u,u
ca_audit_signing                                             u,u,Pu
sslserver                                                    u,u,u
Copy to Clipboard Toggle word wrap
7.4.1.9.5. Verifying admin certificate
Copia collegamento

  1. Import the CA signing certificate: 

    $ pki nss-cert-import --cert ca_signing.crt --trust CT,C,C ca_signing
    Copy to Clipboard Toggle word wrap

  2. Import admin certificate and key into the client NSS database (by default ~/.dogtag/nssdb) with the following command: 

    $ pki -c Secret.123 pkcs12-import \
    --pkcs12 ~/.dogtag/pki-tomcat/ca_admin_cert.p12 \
    --pkcs12-password Secret.123
    Copy to Clipboard Toggle word wrap

  3. Verify that the admin certificate can be used to access the CA subsystem by executing the following command: 

    $ pki -c Secret.123 -n caadmin ca-user-show caadmin
--------------
User "caadmin"
--------------
  User ID: caadmin
  Full name: caadmin
  Email: caadmin@example.com
  Type: adminType
  State: 1
    Copy to Clipboard Toggle word wrap

7.4.1.10. Installing CA with external CA signing certificate
Copia collegamento

An external CA is a CA that is not in the same security domain as that of the PKI subsystem that is being installed.

Follow this process to install a CA subsystem with an external CA signing certificate.

Prior to installation, ensure that the Installation Prerequisites are configured.

7.4.1.10.1. Starting a CA subsystem installation
Copia collegamento

Prepare a file, for example ca-external-cert-step1.cfg, that contains the first deployment configuration.

A sample deployment configuration is available at /usr/share/pki/server/examples/installation/ca-external-cert-step1.cfg

Execute the following command: 

$ pkispawn -f ca-external-cert-step1.cfg -s CA
Copy to Clipboard Toggle word wrap

It installs a CA subsystem in a Tomcat instance (default is pki-tomcat) and creates the following NSS databases:

  • server NSS database: /var/lib/pki/pki-tomcat/conf/alias
  • admin NSS database: ~/.dogtag/pki-tomcat/ca/alias

It also generates the CA signing key in the server NSS database and the CSR in the specified path.

7.4.1.10.2. Generating a CA signing certificate
Copia collegamento

Use the CSR to issue the CA signing certificate:

  • For root CA installation, generate a self-signed CA signing certificate.
  • For subordinate CA installation, submit the CSR to an external CA to issue the CA signing certificate.

Store the CA signing certificate in a file, for example ca_signing.crt. The CA signing certificate can be specified as a single certificate or a PKCS #7 certificate chain in PEM format.

If the CA signing certificate was issued by an external CA, store the external CA certificate chain in a file, for example root-ca_signing.crt.

The certificate chain can be specified as a single certificate or a PKCS #7 certificate chain in PEM format.

The certificate chain should include all CA certificates from the root CA to the external CA that issued the CA signing certificate, but it should not include the CA signing certificate itself.

7.4.1.10.3. Finishing the CA subsystem installation
Copia collegamento

  1. Prepare another file, for example ca-external-cert-step2.cfg, that contains the second deployment configuration. The file can be created from the first file, that is ca-external-cert-step1.cfg, with the following changes: 

    pki_external_step_two=True
    Copy to Clipboard Toggle word wrap

  2. Specify the custom CA signing certificate with the following parameter: 

    pki_ca_signing_cert_path=ca_signing.crt
    Copy to Clipboard Toggle word wrap

  3. If the CA signing certificate was issued by an external CA, specify the external CA certificate chain with the following parameters: 

    pki_cert_chain_nickname=root-ca_signing
pki_cert_chain_path=root-ca_signing.crt
    Copy to Clipboard Toggle word wrap

    A sample deployment configuration is available at /usr/share/pki/server/examples/installation/ca-external-cert-step2.cfg.

  4. Execute the following command: 

    $ pkispawn -f ca-external-cert-step2.cfg -s CA
    Copy to Clipboard Toggle word wrap
7.4.1.10.4. Verifying system certificates
Copia collegamento

Verify that the server NSS database contains the following certificates: 

$ certutil -L -d /var/lib/pki/pki-tomcat/conf/alias

Certificate Nickname                                         Trust Attributes
                                                             SSL,S/MIME,JAR/XPI

root-ca_signing                                              CT,C,C
ca_signing                                                   CTu,Cu,Cu
ca_ocsp_signing                                              u,u,u
subsystem                                                    u,u,u
ca_audit_signing                                             u,u,Pu
sslserver                                                    u,u,u
Copy to Clipboard Toggle word wrap
7.4.1.10.5. Verifying admin certificate
Copia collegamento

  1. Import the external CA certificate chain: 

    $ pki -c Secret.123 client-cert-import --ca-cert root-ca_signing.crt
    Copy to Clipboard Toggle word wrap

  2. Import the CA signing certificate: 

    $ pki nss-cert-import --cert ca_signing.crt --trust CT,C,C ca_signing
    Copy to Clipboard Toggle word wrap

  3. Import the admin certificate and key into the client NSS database (by default ~/.dogtag/nssdb) with the following command: 

    $ pki -c Secret.123 pkcs12-import \
    --pkcs12 ~/.dogtag/pki-tomcat/ca_admin_cert.p12 \
    --pkcs12-password Secret.123
    Copy to Clipboard Toggle word wrap

  4. Verify that the admin certificate can be used to access the CA subsystem by executing the following command: 

    $ pki -c Secret.123 -n caadmin ca-user-show caadmin
--------------
User "caadmin"
--------------
  User ID: caadmin
  Full name: caadmin
  Email: caadmin@example.com
  Type: adminType
  State: 1
    Copy to Clipboard Toggle word wrap

7.4.1.11. Installing a CA with HSM
Copia collegamento

Follow this process to install a CA subsystem with a self-signed CA signing certificate where the system certificates and their keys are stored on a HSM.

Prior to installation, ensure that the Installation Prerequisites are configured.

7.4.1.11.1. Installing a CA subsystem
Copia collegamento

  1. Prepare a file, for example ca.cfg, that contains the deployment configuration: 

    [DEFAULT]
pki_instance_name=pki-tomcat
pki_https_port=8443
pki_http_port=8080
pki_server_database_password=Secret.123

pki_hsm_enable=True
pki_hsm_libfile=/usr/lib64/pkcs11/libsofthsm2.so
pki_hsm_modulename=softhsm
pki_token_name=HSM
pki_token_password=Secret.HSM

[Tomcat]
pki_ajp_port=8009
pki_tomcat_server_port=8005

[CA]
pki_admin_email=caadmin@example.com
pki_admin_name=caadmin
pki_admin_nickname=caadmin
pki_admin_password=Secret.123
pki_admin_uid=caadmin

pki_client_pkcs12_password=Secret.123

pki_ds_url=ldap://localhost.localdomain:389
pki_ds_base_dn=dc=ca,dc=pki,dc=example,dc=com
pki_ds_database=ca
pki_ds_password=Secret.123

pki_security_domain_name=EXAMPLE

pki_ca_signing_nickname=ca_signing
pki_ocsp_signing_nickname=ca_ocsp_signing
pki_audit_signing_nickname=ca_audit_signing
pki_sslserver_nickname=sslserver/pki.example.com
pki_subsystem_nickname=subsystem
    Copy to Clipboard Toggle word wrap

  2. Execute the following command: 

    $ pkispawn -f ca.cfg -s CA
    Copy to Clipboard Toggle word wrap

It installs a CA subsystem in a Tomcat instance (default is pki-tomcat) and creates the following NSS databases:

  • server NSS database: /var/lib/pki/pki-tomcat/conf/alias
  • admin NSS database: ~/.dogtag/pki-tomcat/ca/alias
7.4.1.11.2. Verifying the system certificates
Copia collegamento

  1. Verify that the internal token contains the following certificates: 

    $ certutil -L -d /var/lib/pki/pki-tomcat/conf/alias

Certificate Nickname                                         Trust Attributes
                                                             SSL,S/MIME,JAR/XPI

ca_signing                                                   CT,C,C
ca_audit_signing                                             ,,P
    Copy to Clipboard Toggle word wrap

  2. Verify that the HSM contains the following certificates: 

    $ certutil -L -d /var/lib/pki/pki-tomcat/conf/alias -h HSM -f HSM.pwd

Certificate Nickname                                         Trust Attributes
                                                             SSL,S/MIME,JAR/XPI

HSM:ca_signing                                               CTu,Cu,Cu
HSM:ca_ocsp_signing                                          u,u,u
HSM:subsystem                                                u,u,u
HSM:ca_audit_signing                                         u,u,Pu
HSM:sslserver/pki.example.com                                u,u,u
    Copy to Clipboard Toggle word wrap
7.4.1.11.3. Verifying the Admin certificate
Copia collegamento

  1. Import the CA signing certificate: 

    $ pki nss-cert-import --cert ca_signing.crt --trust CT,C,C ca_signing
    Copy to Clipboard Toggle word wrap

  2. Import the admin certificate and key into the client NSS database (by default ~/.dogtag/nssdb) with the following command: 

    $ pki -c Secret.123 pkcs12-import \
    --pkcs12 ~/.dogtag/pki-tomcat/ca_admin_cert.p12 \
    --pkcs12-password Secret.123
    Copy to Clipboard Toggle word wrap

  3. Verify that the admin certificate can be used to access the CA subsystem by executing the following command: 

    $ pki -c Secret.123 -n caadmin ca-user-show caadmin
--------------
User "caadmin"
--------------
  User ID: caadmin
  Full name: caadmin
  Email: caadmin@example.com
  Type: adminType
  State: 1
    Copy to Clipboard Toggle word wrap

7.4.1.12. Installing CA with LDAPS connection
Copia collegamento

Follow this process to install a CA subsystem with a secure database connection.

Prior to installation, ensure that the Installation Prerequisites are configured.

7.4.1.12.1. DS configuration
Copia collegamento

Once the prerequisites listed above are completed, if you chose to use the DS bootstrap certificates during DS instance creation, then export the bootstrap self-signed certificate into ds_signing.crt as follows: 

$ certutil -L -d /etc/dirsrv/slapd-localhost -n Self-Signed-CA -a > ds_signing.crt
Copy to Clipboard Toggle word wrap
7.4.1.12.2. CA subsystem installation
Copia collegamento

Prepare a deployment configuration, for example ca-secure-ds.cfg, to deploy CA subsystem. By default the subsystem is deployed into a Tomcat instance called pki-tomcat.

A sample deployment configuration is available at /usr/share/pki/server/examples/installation/ca-secure-ds.cfg.

To start the installation, execute the following command: 

$ pkispawn -f ca-secure-ds.cfg -s CA
Copy to Clipboard Toggle word wrap
7.4.1.12.3. CA system certificates
Copia collegamento

After installation the CA system certificates with their keys are generated and stored in the server NSS database, that is /var/lib/pki/pki-tomcat/conf/alias, and the DS signing certificate is imported into the same NSS database: 

$ certutil -L -d /var/lib/pki/pki-tomcat/conf/alias

Certificate Nickname                                         Trust Attributes
                                                             SSL,S/MIME,JAR/XPI

ds_signing                                                   CT,C,C
ca_signing                                                   CTu,Cu,Cu
ca_ocsp_signing                                              u,u,u
subsystem                                                    u,u,u
ca_audit_signing                                             u,u,Pu
sslserver                                                    u,u,u
Copy to Clipboard Toggle word wrap

If necessary, the CA system certificates can be exported into PEM files with the following command: 

$ pki-server cert-export <cert ID> --cert-file <filename>
Copy to Clipboard Toggle word wrap

The valid IDs for CA system certificates are:

  • ca_signing
  • ca_ocsp_signing
  • ca_audit_signing
  • subsystem
  • sslserver

Note that the pki-server cert-export command takes a certificate ID instead of a nickname. For simplicity the nicknames in this example are configured to be the same as the certificate ID.

7.4.1.12.4. CA database configuration
Copia collegamento

The CA database configuration can be displayed with the following command: 

$ pki-server ca-db-config-show
  Hostname: pki.example.com
  Port: 636
  Secure: true
  Authentication: BasicAuth
  Bind DN: cn=Directory Manager
  Bind Password Prompt: internaldb
  Database: ca
  Base DN: dc=ca,dc=pki,dc=example,dc=com
  Multiple suffix: false
  Maximum connections: 15
  Minimum connections: 3
Copy to Clipboard Toggle word wrap
7.4.1.12.5. Admin certificate
Copia collegamento

After installation the admin certificate and key are stored in ~/.dogtag/pki-tomcat/ca_admin_cert.p12. The PKCS #12 password is specified in the pki_client_pkcs12_password parameter.

To use the admin certificate, do the following.

  1. Export the CA signing certificate from the server NSS database: 

    $ pki-server cert-export ca_signing --cert-file ca_signing.crt
    Copy to Clipboard Toggle word wrap

  2. Import the CA signing certificate into the client NSS database: 

    $ pki nss-cert-import --cert ca_signing.crt --trust CT,C,C ca_signing
    Copy to Clipboard Toggle word wrap

  3. Import admin certificate and key into the client NSS database (by default ~/.dogtag/nssdb) with the following command: 

    $ pki pkcs12-import \
    --pkcs12 ~/.dogtag/pki-tomcat/ca_admin_cert.p12 \
    --pkcs12-password Secret.123
    Copy to Clipboard Toggle word wrap

  4. To verify that the admin certificate can be used to access the CA subsystem, execute the following command: 

    $ pki -n caadmin ca-user-show caadmin
--------------
User "caadmin"
--------------
  User ID: caadmin
  Full name: caadmin
  Email: caadmin@example.com
  Type: adminType
  State: 1
    Copy to Clipboard Toggle word wrap
7.4.1.12.6. Getting real DS certificate from the CA
Copia collegamento

If desired, follow this procedure to get real DS certificate issued by the CA.

7.4.1.13. Installing a subordinate CA
Copia collegamento

Follow this process to install a subordinate CA subsystem with a signing certificate issued by a root CA.

Prior to installation, ensure that the Installation Prerequisites are configured.

7.4.1.13.1. Installing a subordinate CA subsystem
Copia collegamento

  1. Prepare a file, for example subca.cfg, that contains the deployment configuration.

    A sample deployment configuration is available at /usr/share/pki/server/examples/installation/subca.cfg.

    It assumes that the root CA is already running at https://root.example.com:8443 and the root CA signing certificate has been exported into root-ca_signing.crt.

  2. Execute the following command: 

    $ pkispawn -f subca.cfg -s CA
    Copy to Clipboard Toggle word wrap

It installs a CA subsystem in a Tomcat instance (default is pki-tomcat) and creates the following NSS databases:

  • server NSS database: /var/lib/pki/pki-tomcat/conf/alias
  • admin NSS database: ~/.dogtag/pki-tomcat/ca/alias
7.4.1.13.2. Verifying system certificates
Copia collegamento

Verify that the server NSS database contains the following certificates: 

$ certutil -L -d /var/lib/pki/pki-tomcat/conf/alias

Certificate Nickname                                         Trust Attributes
                                                             SSL,S/MIME,JAR/XPI

ca_signing                                                   CTu,Cu,Cu
ca_ocsp_signing                                              u,u,u
subsystem                                                    u,u,u
ca_audit_signing                                             u,u,Pu
sslserver                                                    u,u,u
Copy to Clipboard Toggle word wrap
7.4.1.13.3. Verifying admin certificate
Copia collegamento

  1. Import the root CA signing certificate: 

    $ pki nss-cert-import --cert ca_signing.crt --trust CT,C,C ca_signing
    Copy to Clipboard Toggle word wrap

  2. Import admin certificate and key into the client NSS database (by default ~/.dogtag/nssdb) with the following command: 

    $ pki pkcs12-import \
    --pkcs12 /root/.dogtag/pki-tomcat/ca_admin_cert.p12 \
    --pkcs12-password Secret.123
    Copy to Clipboard Toggle word wrap

  3. Verify that the admin certificate can be used to access the subordinate CA subsystem by executing the following command: 

    $ pki -n caadmin ca-user-show caadmin
--------------
User "caadmin"
--------------
  User ID: caadmin
  Full name: caadmin
  Email: caadmin@example.com
  Type: adminType
  State: 1
    Copy to Clipboard Toggle word wrap

7.4.2. Installing the KRA subsystem
Copia collegamento

7.4.2.1. Installing KRA
Copia collegamento

Follow this process to install a KRA subsystem.

Prior to installation, ensure that the Installation Prerequisites are configured.

7.4.2.1.1. Installing KRA subsystem installation
Copia collegamento
  1. Prepare a file, for example kra.cfg, that contains the deployment configuration. A sample deployment configuration is available at /usr/share/pki/server/examples/installation/kra.cfg.

  2. Execute the following command: 

    $ pkispawn -f kra.cfg -s KRA
    Copy to Clipboard Toggle word wrap

It installs a KRA subsystem in a Tomcat instance (default is pki-tomcat) and creates the following NSS databases:

  • server NSS database: /var/lib/pki/pki-tomcat/conf/alias
  • admin NSS database: ~/.dogtag/pki-tomcat/kra/alias
Note

When KRA is installed on a new system without any other subsystems, it is necessary to provide the CA’s root certificate. Specify the path to the CA PKCS#7 PEM file in the pki_cert_chain_path. This allows the server to verify the CA’s SSL server certificate when contacting the security domain. It is up to the administrator to securely transport the CA root certificate (public key only!) to the system prior to KRA installation.

7.4.2.1.2. Verifying system certificates
Copia collegamento

Verify that the server NSS database contains the following certificates: 

$ certutil -L -d /var/lib/pki/pki-tomcat/conf/alias

Certificate Nickname                                         Trust Attributes
                                                             SSL,S/MIME,JAR/XPI

ca_signing                                                   CT,C,C
kra_transport                                                u,u,u
kra_storage                                                  u,u,u
subsystem                                                    u,u,u
kra_audit_signing                                            u,u,Pu
sslserver                                                    u,u,u
Copy to Clipboard Toggle word wrap
7.4.2.1.3. Verifying admin certificate
Copia collegamento

  1. Import the CA signing certificate: 

    $ pki nss-cert-import --cert ca_signing.crt --trust CT,C,C ca_signing
    Copy to Clipboard Toggle word wrap

  2. Import admin certificate and key into the client NSS database (by default ~/.dogtag/nssdb) with the following command: 

    $ pki -c Secret.123 pkcs12-import \
    --pkcs12 ca_admin_cert.p12 \
    --pkcs12-password Secret.123
    Copy to Clipboard Toggle word wrap

  3. Verify that the admin certificate can be used to access the KRA subsystem by executing the following command: 

    $ pki -c Secret.123 -n caadmin kra-user-show kraadmin
---------------
User "kraadmin"
---------------
  User ID: kraadmin
  Full name: kraadmin
  Email: kraadmin@example.com
  Type: adminType
  State: 1
    Copy to Clipboard Toggle word wrap
7.4.2.1.4. Verifying KRA connector
Copia collegamento

Verify that the KRA connector is configured in the CA subsystem: 

$ pki -c Secret.123 -n caadmin ca-kraconnector-show

Host: pki.example.com:8443
Enabled: true
Local: false
Timeout: 30
URI: /kra/agent/kra/connector
Transport Cert:

<base-64 certificate>
Copy to Clipboard Toggle word wrap

7.4.2.2. Installing KRA clone
Copia collegamento

Follow this process to install a KRA subsystem as a clone of an existing KRA subsystem.

Prior to installation, ensure that the Installation Prerequisites are configured.

7.4.2.2.1. Exporting existing KRA system certificates
Copia collegamento

On the existing system, export the KRA system certificates with the following command: 

$ pki-server kra-clone-prepare \
    --pkcs12-file kra-certs.p12 \
    --pkcs12-password Secret.123
Copy to Clipboard Toggle word wrap

The command exports the following certificates (including the certificate chain) and their keys into a PKCS #12 file:

  • KRA storage certificate
  • KRA transport certificate
  • audit signing certificate
  • subsystem certificate

Note that the existing SSL server certificate is not exported.

If necessary, third-party certificates, for example trust anchors, can be added into the same PKCS #12 file with the following command: 

$ pki -d /var/lib/pki/pki-tomcat/conf/alias -f /var/lib/pki/pki-tomcat/conf/password.conf \
    pkcs12-cert-import <nickname> \
    --pkcs12-file kra-certs.p12 \
    --pkcs12-password Secret.123 \
    --append
Copy to Clipboard Toggle word wrap
7.4.2.2.2. Installing KRA subsystem
Copia collegamento

Prepare a deployment configuration, for example kra-clone.cfg, to deploy KRA subsystem clone. By default the subsystem is deployed into a Tomcat instance called pki-tomcat.

A sample deployment configuration is available at /usr/share/pki/server/examples/installation/kra-clone.cfg.

It assumes that the:

  • Primary CA and KRA subsystems are running at https://primary.example.com:8443.
  • CA signing certificate has been exported into ca_signing.crt.
  • Admin certificate and key have been exported into ca_admin_cert.p12.
  • The PKCS #12 password is specified in the pki_client_pkcs12_password parameter.

See Installing CA for details.

To start the installation execute the following command: 

$ pkispawn -f kra-clone.cfg -s KRA
Copy to Clipboard Toggle word wrap
7.4.2.2.3. KRA system certificates
Copia collegamento

After installation, the existing KRA system certificates (including the certificate chain) and their keys are stored in the server NSS database (i.e. /var/lib/pki/pki-tomcat/conf/alias), and a new SSL server certificate is created for the new instance: 

$ certutil -L -d /var/lib/pki/pki-tomcat/conf/alias

Certificate Nickname                                         Trust Attributes
                                                             SSL,S/MIME,JAR/XPI

ca_signing                                                   CT,C,C
kra_storage                                                  u,u,u
sslserver                                                    u,u,u
subsystem                                                    u,u,u
kra_audit_signing                                            u,u,Pu
kra_transport                                                u,u,u
Copy to Clipboard Toggle word wrap

If necessary, the certificates can be exported into PEM files with the following command: 

$ pki-server cert-export <cert ID> --cert-file <filename>
Copy to Clipboard Toggle word wrap

The valid certificate IDs for KRA are:

  • kra_storage_signing
  • kra_transport_signing
  • kra_audit_signing
  • subsystem
  • sslserver

Note that the pki-server cert-export command takes a certificate ID instead of a nickname. For simplicity the nicknames in this example are configured to be the same as the certificate IDs.

7.4.2.2.4. Admin certificate
Copia collegamento

To use the admin certificate, do the following.

  1. Import the CA signing certificate into the client NSS database: 

    $ pki nss-cert-import --cert ca_signing.crt --trust CT,C,C ca_signing
    Copy to Clipboard Toggle word wrap

  2. Import admin certificate and key into the client NSS database (by default ~/.dogtag/nssdb) with the following command: 

    $ pki pkcs12-import \
    --pkcs12 ca_admin_cert.p12 \
    --pkcs12-password Secret.123
    Copy to Clipboard Toggle word wrap

  3. To verify that the admin certificate can be used to access the KRA subsystem clone, execute the following command: 

    $ pki -n caadmin kra-user-show kraadmin
---------------
User "kraadmin"
---------------
  User ID: kraadmin
  Full name: kraadmin
  Email: kraadmin@example.com
  Type: adminType
  State: 1
    Copy to Clipboard Toggle word wrap

7.4.2.3. Installing KRA clone with HSM
Copia collegamento

Follow this process to install a KRA subsystem as a clone of an existing KRA subsystem where the system certificates and their keys are stored on a HSM.

Since the certificates and the keys are already on the HSM, it is not necessary to export them into a PKCS #12 file to create a clone.

Prior to installation, ensure that the Installation Prerequisites are configured.

7.4.2.3.1. Installing KRA subsystem
Copia collegamento

Note: It is assumed that the CA signing certificate has been exported into ca_signing.crt.

  1. Prepare a file, for example kra.cfg, that contains the deployment configuration: 

    [DEFAULT]
pki_instance_name=pki-tomcat
pki_https_port=8443
pki_http_port=8080
pki_server_database_password=Secret.123

pki_hsm_enable=True
pki_hsm_libfile=/usr/lib64/pkcs11/libsofthsm2.so
pki_hsm_modulename=softhsm
pki_token_name=HSM
pki_token_password=Secret.HSM

pki_cert_chain_path=ca_signing.crt

[Tomcat]
pki_ajp_port=8009
pki_tomcat_server_port=8005

[KRA]
pki_admin_email=kraadmin@example.com
pki_admin_name=kraadmin
pki_admin_nickname=kraadmin
pki_admin_password=Secret.123
pki_admin_uid=kraadmin

pki_client_pkcs12_password=Secret.123

pki_ds_url=ldap://localhost.localdomain:389
pki_ds_base_dn=dc=kra,dc=pki,dc=example,dc=com
pki_ds_database=kra
pki_ds_password=Secret.123

pki_security_domain_hostname=pki.example.com
pki_security_domain_https_port=8443
pki_security_domain_user=caadmin
pki_security_domain_password=Secret.123

pki_storage_nickname=kra_storage
pki_transport_nickname=kra_transport
pki_audit_signing_nickname=kra_audit_signing
pki_sslserver_nickname=sslserver/replica.example.com
pki_subsystem_nickname=subsystem

pki_storage_token=HSM
pki_transport_token=HSM
pki_audit_signing_token=HSM
pki_sslserver_token=HSM
pki_subsystem_token=HSM

pki_clone=True
pki_clone_replicate_schema=True
pki_clone_uri=https://pki.example.com:8443
    Copy to Clipboard Toggle word wrap

  2. Execute the following command: 

    $ pkispawn -f kra.cfg -s KRA
    Copy to Clipboard Toggle word wrap

It installs a KRA subsystem in a Tomcat instance (default is pki-tomcat) and creates the following NSS databases:

  • server NSS database: /var/lib/pki/pki-tomcat/conf/alias
  • admin NSS database: ~/.dogtag/pki-tomcat/kra/alias
7.4.2.3.2. Verifying system certificates
Copia collegamento

  1. Verify that the internal token contains the following certificates: 

    $ certutil -L -d /var/lib/pki/pki-tomcat/conf/alias

Certificate Nickname                                         Trust Attributes
                                                             SSL,S/MIME,JAR/XPI

ca_signing                                                   CT,C,C
sslserver/replica.example.com                                ,,
kra_audit_signing                                            ,,P
    Copy to Clipboard Toggle word wrap

  2. Verify that the HSM contains the following certificates: 

    $ certutil -L -d /var/lib/pki/pki-tomcat/conf/alias -h HSM -f HSM.pwd

Certificate Nickname                                         Trust Attributes
                                                             SSL,S/MIME,JAR/XPI

HSM:kra_transport                                            u,u,u
HSM:kra_storage                                              u,u,u
HSM:subsystem                                                u,u,u
HSM:kra_audit_signing                                        u,u,Pu
HSM:sslserver/replica.example.com                            u,u,u
    Copy to Clipboard Toggle word wrap
7.4.2.3.3. Verifying admin certificate
Copia collegamento

  1. Import the CA signing certificate: 

    $ pki nss-cert-import --cert ca_signing.crt --trust CT,C,C ca_signing
    Copy to Clipboard Toggle word wrap

  2. Import admin certificate and key into the client NSS database (by default ~/.dogtag/nssdb) with the following command: 

    $ pki -c Secret.123 pkcs12-import \
    --pkcs12 ca_admin_cert.p12 \
    --pkcs12-password Secret.123
    Copy to Clipboard Toggle word wrap

  3. Verify that the admin certificate can be used to access the KRA subsystem by executing the following command: 

    $ pki -c Secret.123 -n caadmin kra-user-show kraadmin
---------------
User "kraadmin"
---------------
  User ID: kraadmin
  Full name: kraadmin
  Email: kraadmin@example.com
  Type: adminType
  State: 1
    Copy to Clipboard Toggle word wrap
7.4.2.3.4. Verifying KRA connector
Copia collegamento

Verify that the KRA connector is configured in the CA subsystem: 

$ pki -c Secret.123 -n caadmin ca-kraconnector-show

Host: pki.example.com:8443
Enabled: true
Local: false
Timeout: 30
URI: /kra/agent/kra/connector
Transport Cert:

<base-64 certificate>
Copy to Clipboard Toggle word wrap

7.4.2.4. Installing KRA with ECC
Copia collegamento

Follow this process to install a KRA subsystem with ECC.

Supported ECC curves:

  • nistp256
  • nistp384
  • nistp521

Supported ECC key algorithms:

  • SHA256withEC
  • SHA384withEC
  • SHA512withEC

Prior to installation, ensure that the Installation Prerequisites are configured.

7.4.2.4.1. Installing KRA subsystem
Copia collegamento

  1. Prepare a file, for example kra.cfg, that contains the deployment configuration: 

    [DEFAULT]
pki_instance_name=pki-tomcat
pki_https_port=8443
pki_http_port=8080
pki_server_database_password=Secret.123

[Tomcat]
pki_ajp_port=8009
pki_tomcat_server_port=8005

[KRA]
pki_admin_cert_file=ca_admin.cert
pki_admin_email=kraadmin@example.com
pki_admin_name=kraadmin
pki_admin_nickname=kraadmin
pki_admin_password=Secret.123
pki_admin_uid=kraadmin

pki_client_pkcs12_password=Secret.123

pki_ds_url=ldap://localhost.localdomain:389
pki_ds_base_dn=dc=kra,dc=pki,dc=example,dc=com
pki_ds_database=kra
pki_ds_password=Secret.123

pki_security_domain_name=EXAMPLE
pki_security_domain_user=caadmin
pki_security_domain_password=Secret.123

pki_storage_nickname=kra_storage
pki_storage_key_type=rsa
pki_storage_key_algorithm=SHA512withRSA
pki_storage_key_size=2048
pki_storage_signing_algorithm=SHA512withRSA

pki_transport_nickname=kra_transport
pki_transport_key_type=rsa
pki_transport_key_algorithm=SHA512withRSA
pki_transport_key_size=2048
pki_transport_signing_algorithm=SHA512withRSA

pki_audit_signing_nickname=kra_audit_signing
pki_audit_signing_key_type=ecc
pki_audit_signing_key_algorithm=SHA512withEC
pki_audit_signing_key_size=nistp521
pki_audit_signing_signing_algorithm=SHA512withEC

pki_sslserver_nickname=sslserver
pki_sslserver_key_type=ecc
pki_sslserver_key_algorithm=SHA512withEC
pki_sslserver_key_size=nistp521

pki_subsystem_nickname=subsystem
pki_subsystem_key_type=ecc
pki_subsystem_key_algorithm=SHA512withEC
pki_subsystem_key_size=nistp521
    Copy to Clipboard Toggle word wrap

  2. Execute the following command: 

    $ pkispawn -f kra.cfg -s KRA
    Copy to Clipboard Toggle word wrap

It installs a KRA subsystem in a Tomcat instance (default is pki-tomcat) and creates the following NSS databases:

  • server NSS database: /var/lib/pki/pki-tomcat/conf/alias
  • admin NSS database: ~/.dogtag/pki-tomcat/kra/alias
7.4.2.4.2. Verifying system certificates
Copia collegamento

Verify that the server NSS database contains the following certificates: 

$ certutil -L -d /var/lib/pki/pki-tomcat/conf/alias

Certificate Nickname                                         Trust Attributes
                                                             SSL,S/MIME,JAR/XPI

ca_signing                                                   CT,C,C
kra_transport                                                u,u,u
kra_storage                                                  u,u,u
subsystem                                                    u,u,u
kra_audit_signing                                            u,u,Pu
sslserver                                                    u,u,u
Copy to Clipboard Toggle word wrap
7.4.2.4.3. Verifying admin certificate
Copia collegamento

  1. Import the CA signing certificate: 

    $ pki nss-cert-import --cert ca_signing.crt --trust CT,C,C ca_signing
    Copy to Clipboard Toggle word wrap

  2. Import admin certificate and key into the client NSS database (by default ~/.dogtag/nssdb) with the following command: 

    $ pki -c Secret.123 pkcs12-import \
    --pkcs12 ca_admin_cert.p12 \
    --pkcs12-password Secret.123
    Copy to Clipboard Toggle word wrap

  3. Verify that the admin certificate can be used to access the KRA subsystem by executing the following command: 

    $ pki -c Secret.123 -n caadmin kra-user-show kraadmin
--------------
User "kraadmin"
--------------
  User ID: kraadmin
  Full name: kraadmin
  Email: kraadmin@example.com
  Type: adminType
  State: 1
    Copy to Clipboard Toggle word wrap

7.4.2.5. Installing KRA with HSM
Copia collegamento

Follow this process to install a KRA subsystem where the system certificates and their keys are stored on a HSM.

Prior to installation, ensure that the Installation Prerequisites are configured.

7.4.2.5.1. Installing KRA subsystem
Copia collegamento

  1. Prepare a file, for example kra.cfg, that contains the deployment configuration: 

    [DEFAULT]
pki_instance_name=pki-tomcat
pki_https_port=8443
pki_http_port=8080
pki_server_database_password=Secret.123

pki_hsm_enable=True
pki_hsm_libfile=/usr/lib64/pkcs11/libsofthsm2.so
pki_hsm_modulename=softhsm
pki_token_name=HSM
pki_token_password=Secret.HSM

[Tomcat]
pki_ajp_port=8009
pki_tomcat_server_port=8005

[KRA]
pki_admin_cert_file=ca_admin.cert
pki_admin_email=kraadmin@example.com
pki_admin_name=kraadmin
pki_admin_nickname=kraadmin
pki_admin_password=Secret.123
pki_admin_uid=kraadmin

pki_client_pkcs12_password=Secret.123

pki_ds_url=ldap://localhost.localdomain:389
pki_ds_base_dn=dc=kra,dc=pki,dc=example,dc=com
pki_ds_database=kra
pki_ds_password=Secret.123

pki_security_domain_name=EXAMPLE
pki_security_domain_user=caadmin
pki_security_domain_password=Secret.123

pki_storage_nickname=kra_storage
pki_transport_nickname=kra_transport
pki_audit_signing_nickname=kra_audit_signing
pki_sslserver_nickname=sslserver/pki.example.com
pki_subsystem_nickname=subsystem
    Copy to Clipboard Toggle word wrap

  2. Execute the following command: 

    $ pkispawn -f kra.cfg -s KRA
    Copy to Clipboard Toggle word wrap

It installs a KRA subsystem in a Tomcat instance (default is pki-tomcat) and creates the following NSS databases:

  • server NSS database: /var/lib/pki/pki-tomcat/conf/alias
  • admin NSS database: ~/.dogtag/pki-tomcat/kra/alias
7.4.2.5.2. Verifying system certificates
Copia collegamento

  1. Verify that the internal token contains the following certificates: 

    $ certutil -L -d /var/lib/pki/pki-tomcat/conf/alias

Certificate Nickname                                         Trust Attributes
                                                             SSL,S/MIME,JAR/XPI

ca_signing                                                   CT,C,C
kra_audit_signing                                            ,,P
    Copy to Clipboard Toggle word wrap

  2. Verify that the HSM contains the following certificates: 

    $ certutil -L -d /var/lib/pki/pki-tomcat/conf/alias -h HSM -f HSM.pwd

Certificate Nickname                                         Trust Attributes
                                                             SSL,S/MIME,JAR/XPI

HSM:kra_transport                                            u,u,u
HSM:kra_storage                                              u,u,u
HSM:subsystem                                                u,u,u
HSM:kra_audit_signing                                        u,u,Pu
HSM:sslserver/pki.example.com                                u,u,u
    Copy to Clipboard Toggle word wrap
7.4.2.5.3. Verifying admin certificate
Copia collegamento

  1. Import the CA signing certificate: 

    $ pki nss-cert-import --cert ca_signing.crt --trust CT,C,C ca_signing
    Copy to Clipboard Toggle word wrap

  2. Import admin certificate and key into the client NSS database (by default ~/.dogtag/nssdb) with the following command: 

    $ pki -c Secret.123 pkcs12-import \
    --pkcs12 ca_admin_cert.p12 \
    --pkcs12-password Secret.123
    Copy to Clipboard Toggle word wrap

  3. Verify that the admin certificate can be used to access the KRA subsystem by executing the following command: 

    $ pki -c Secret.123 -n caadmin kra-user-show kraadmin
---------------
User "kraadmin"
---------------
  User ID: kraadmin
  Full name: kraadmin
  Email: kraadmin@example.com
  Type: adminType
  State: 1
    Copy to Clipboard Toggle word wrap
7.4.2.5.4. Verifying KRA connector
Copia collegamento

Verify that the KRA connector is configured in the CA subsystem: 

$ pki -c Secret.123 -n caadmin ca-kraconnector-show

Host: pki.example.com:8443
Enabled: true
Local: false
Timeout: 30
URI: /kra/agent/kra/connector
Transport Cert:

<base-64 certificate>
Copy to Clipboard Toggle word wrap

7.4.2.6. Installing KRA with LDAPS connection
Copia collegamento

Follow this process to install a KRA subsystem with a secure database connection.

Prior to installation, ensure that the Installation Prerequisites are configured.

7.4.2.6.1. DS configuration
Copia collegamento

Once the prerequisites listed above are configured, if you chose to use the DS bootstrap certificates during DS instance creation, then export the bootstrap self-signed certificate into ds_signing.crt as follows: 

$ certutil -L -d /etc/dirsrv/slapd-localhost -n Self-Signed-CA -a > ds_signing.crt
Copy to Clipboard Toggle word wrap
7.4.2.6.2. Installing KRA subsystem
Copia collegamento

  1. Prepare a file, for example kra.cfg, that contains the deployment configuration: 

    [DEFAULT]
pki_server_database_password=Secret.123

[KRA]
pki_admin_cert_file=ca_admin.cert
pki_admin_email=kraadmin@example.com
pki_admin_name=kraadmin
pki_admin_nickname=kraadmin
pki_admin_password=Secret.123
pki_admin_uid=kraadmin

pki_client_pkcs12_password=Secret.123

pki_ds_url=ldaps://localhost.localdomain:636
pki_ds_secure_connection_ca_nickname=ds_signing
pki_ds_secure_connection_ca_pem_file=ds_signing.crt

pki_ds_base_dn=dc=kra,dc=pki,dc=example,dc=com
pki_ds_database=kra
pki_ds_password=Secret.123

pki_security_domain_name=EXAMPLE
pki_security_domain_user=caadmin
pki_security_domain_password=Secret.123

pki_storage_nickname=kra_storage
pki_transport_nickname=kra_transport
pki_audit_signing_nickname=kra_audit_signing
pki_sslserver_nickname=sslserver
pki_subsystem_nickname=subsystem
    Copy to Clipboard Toggle word wrap

  2. Execute the following command: 

    $ pkispawn -f kra.cfg -s KRA
    Copy to Clipboard Toggle word wrap

It installs a KRA subsystem in a Tomcat instance (default is pki-tomcat) and creates the following NSS databases:

  • server NSS database: /var/lib/pki/pki-tomcat/conf/alias
  • admin NSS database: ~/.dogtag/pki-tomcat/kra/alias
7.4.2.6.3. Verifying system certificates
Copia collegamento

Verify that the server NSS database contains the following certificates: 

$ certutil -L -d /var/lib/pki/pki-tomcat/conf/alias

Certificate Nickname                                         Trust Attributes
                                                             SSL,S/MIME,JAR/XPI

ds_signing                                                   CT,C,C
ca_signing                                                   CT,C,C
kra_transport                                                u,u,u
kra_storage                                                  u,u,u
subsystem                                                    u,u,u
kra_audit_signing                                            u,u,Pu
sslserver                                                    u,u,u
Copy to Clipboard Toggle word wrap
7.4.2.6.4. Verifying database configuration
Copia collegamento

Verify that the KRA database is configured with a secure connection: 

$ pki-server kra-db-config-show
  Hostname: pki.example.com
  Port: 636
  Secure: true
  Authentication: BasicAuth
  Bind DN: cn=Directory Manager
  Bind Password Prompt: internaldb
  Database: kra
  Base DN: dc=kra,dc=pki,dc=example,dc=com
  Multiple suffix: false
  Maximum connections: 15
  Minimum connections: 3
Copy to Clipboard Toggle word wrap
7.4.2.6.5. Verifying admin certificate
Copia collegamento

  1. Import the CA signing certificate: 

    $ pki nss-cert-import --cert ca_signing.crt --trust CT,C,C ca_signing
    Copy to Clipboard Toggle word wrap

  2. Import admin certificate and key into the client NSS database (by default ~/.dogtag/nssdb) with the following command: 

    $ pki -c Secret.123 pkcs12-import \
    --pkcs12 ca_admin_cert.p12 \
    --pkcs12-password Secret.123
    Copy to Clipboard Toggle word wrap

  3. Verify that the admin certificate can be used to access the KRA subsystem by executing the following command: 

    $ pki -c Secret.123 -n caadmin kra-user-show kraadmin
---------------
User "kraadmin"
---------------
  User ID: kraadmin
  Full name: kraadmin
  Email: kraadmin@example.com
  Type: adminType
  State: 1
    Copy to Clipboard Toggle word wrap
7.4.2.6.6. Verifying KRA connector
Copia collegamento

Verify that the KRA connector is configured in the CA subsystem: 

$ pki -c Secret.123 -n caadmin ca-kraconnector-show

Host: pki.example.com:8443
Enabled: true
Local: false
Timeout: 30
URI: /kra/agent/kra/connector
Transport Cert:

<base-64 certificate>
Copy to Clipboard Toggle word wrap
7.4.2.6.7. Getting real DS certificate from the CA
Copia collegamento

If desired, follow this procedure to get the real DS certificate issued by the CA.

7.4.2.7. Installing standalone KRA
Copia collegamento

Follow this process to install a standalone KRA subsystem.

In regular KRA installation the KRA certificates are issued automatically by the CA and the KRA will join the CA’s security domain.

In standalone KRA installation, the KRA certificates are issued manually and the KRA has its own security domain.

The installation process consists multiple steps:

  • Generating certificate requests
  • Issuing the certificates
  • Completing installation with the certificates
7.4.2.7.1. Generating certificate requests
Copia collegamento

  1. Prepare a file, for example kra-standalone-step1.cfg, that contains the first deployment configuration.

    A sample deployment configuration is available at /usr/share/pki/server/examples/installation/kra-standalone-step1.cfg.

  2. Execute the following command: 

    $ pkispawn -f kra-standalone-step1.cfg -s KRA
    Copy to Clipboard Toggle word wrap

It creates an NSS database in /var/lib/pki/pki-tomcat/alias and generate CSRs in the specified paths.

7.4.2.7.2. Issuing certificates
Copia collegamento

Use the CSRs to obtain KRA certificates by submitting the CSRs to an external CA to issue the KRA system certificates. In the section that follows, it is assumed that the KRA system certificates are stored in the following files:

  • kra_storage.crt
  • kra_transport.crt
  • subsystem.crt
  • sslserver.crt
  • kra_audit_signing.crt
  • kra_admin.crt
7.4.2.7.3. Completing the installation
Copia collegamento

  1. Prepare another file, for example kra-standalone-step2.cfg, that contains the second deployment configuration. The file can be created from the first file, that is kra-standalone-step1.cfg, with the following changes: 

    pki_external_step_two=True
    Copy to Clipboard Toggle word wrap

  2. Specify the certificate files with the following parameters: 

    pki_storage_cert_path=kra_storage.crt
pki_transport_cert_path=kra_transport.crt
pki_subsystem_cert_path=subsystem.crt
pki_sslserver_cert_path=sslserver.crt
pki_audit_signing_cert_path=kra_audit_signing.crt
pki_admin_cert_path=kra_admin.crt
    Copy to Clipboard Toggle word wrap

    Each certificate file can contain either a single PEM certificate or a PKCS #7 certificate chain.

  3. Specify the CA certificate chain with the following parameters: 

    pki_cert_chain_nickname=ca_signing
pki_cert_chain_path=ca_signing.crt
    Copy to Clipboard Toggle word wrap

    The CA certificate chain file can contain either a single PEM certificate or a PKCS #7 certificate chain as well.

    A sample deployment configuration is available at /usr/share/pki/server/examples/installation/kra-standalone-step2.cfg.

  4. Execute the following command: 

    $ pkispawn -f kra-standalone-step2.cfg -s KRA
    Copy to Clipboard Toggle word wrap
7.4.2.7.4. Verifying admin certificate
Copia collegamento

  1. Import the CA signing certificate: 

    $ pki nss-cert-import --cert ca_signing.crt --trust CT,C,C ca_signing
    Copy to Clipboard Toggle word wrap

  2. Import admin certificate and key into the client NSS database (by default ~/.dogtag/nssdb) with the following command: 

    $ pki pkcs12-import \
    --pkcs12 kra_admin_cert.p12 \
    --pkcs12-password Secret.123
    Copy to Clipboard Toggle word wrap

  3. Verify that the admin certificate can be used to access the KRA subsystem by executing the following command: 

    $ pki -n kraadmin kra-user-show kraadmin
---------------
User "kraadmin"
---------------
  User ID: kraadmin
  Full name: kraadmin
  Email: kraadmin@example.com
  Type: adminType
  State: 1
    Copy to Clipboard Toggle word wrap

7.4.3. Installing the OCSP subsystem
Copia collegamento

7.4.3.1. Installing OCSP
Copia collegamento

Follow this process to install an OCSP subsystem.

Prior to installation, ensure that the Installation Prerequisites are configured.

7.4.3.1.1. Installing OCSP subsystem
Copia collegamento
  1. Prepare a file, for example ocsp.cfg, that contains the deployment configuration. A sample deployment configuration is available at /usr/share/pki/server/examples/installation/ocsp.cfg.

  2. Execute the following command: 

    $ pkispawn -f ocsp.cfg -s OCSP
    Copy to Clipboard Toggle word wrap

It installs a OCSP subsystem in a Tomcat instance (default is pki-tomcat) and creates the following NSS databases:

  • server NSS database: /var/lib/pki/pki-tomcat/conf/alias
  • admin NSS database: ~/.dogtag/pki-tomcat/ocsp/alias
Note

When OCSP is installed on a new system without any other subsystems, it is necessary to provide the CA’s root certificate. Specify the path to the CA PKCS#7 PEM file in the pki_cert_chain_path. This allows the server to verify the CA’s SSL server certificate when contacting the security domain. It is up to the administrator to securely transport the CA root certificate (public key only) to the system prior to OCSP installation.

7.4.3.1.2. Verifying system certificates
Copia collegamento

Verify that the server NSS database contains the following certificates: 

$ certutil -L -d /var/lib/pki/pki-tomcat/conf/alias

Certificate Nickname                                         Trust Attributes
                                                             SSL,S/MIME,JAR/XPI

ca_signing                                                   CT,C,C
ocsp_signing                                                 u,u,u
subsystem                                                    u,u,u
ocsp_audit_signing                                           u,u,Pu
sslserver                                                    u,u,u
Copy to Clipboard Toggle word wrap
7.4.3.1.3. Verifying admin certificate
Copia collegamento

  1. Import the CA signing certificate: 

    $ pki nss-cert-import --cert ca_signing.crt --trust CT,C,C ca_signing
    Copy to Clipboard Toggle word wrap

  2. Import admin certificate and key into the client NSS database (by default ~/.dogtag/nssdb) with the following command: 

    $ pki -c Secret.123 pkcs12-import \
    --pkcs12 ca_admin_cert.p12 \
    --pkcs12-password Secret.123
    Copy to Clipboard Toggle word wrap

  3. Verify that the admin certificate can be used to access the OCSP subsystem by executing the following command: 

    $ pki -c Secret.123 -n caadmin ocsp-user-show ocspadmin
----------------
User "ocspadmin"
----------------
  User ID: ocspadmin
  Full name: ocspadmin
  Email: ocspadmin@example.com
  Type: adminType
  State: 1
    Copy to Clipboard Toggle word wrap
7.4.3.1.4. Verifying OCSP client
Copia collegamento

  1. Publish the CRL in CA to the directory server as follows:

    1. Go to CA Agent UI (https://pki.example.com:8443/ca/agent/ca/).
    2. Click Update Directory Server.
    3. Select Update the certificate revocation list to the directory.
    4. Click Update Directory.

  2. Verify that the OCSPClient can be used to validate a certificate: 

    $ OCSPClient \
 -d /var/lib/pki/pki-tomcat/conf/alias \
 -h pki.example.com \
 -p 8080 \
 -t /ocsp/ee/ocsp \
 -c ca_signing \
 --serial 1
CertID.serialNumber=1
CertStatus=Good
    Copy to Clipboard Toggle word wrap

7.4.3.2. Installing OCSP with ECC
Copia collegamento

Follow this process to install an OCSP subsystem with ECC.

Supported ECC curves:

  • nistp256
  • nistp384
  • nistp521

Supported ECC key algorithms:

  • SHA256withEC
  • SHA384withEC
  • SHA512withEC

Prior to installation, ensure that the Installation Prerequisites are configured.

7.4.3.2.1. Installing OCSP subsystem
Copia collegamento

  1. Prepare a file, for example ocsp.cfg, that contains the deployment configuration: 

    [DEFAULT]
pki_instance_name=pki-tomcat
pki_https_port=8443
pki_http_port=8080
pki_server_database_password=Secret.123

[Tomcat]
pki_ajp_port=8009
pki_tomcat_server_port=8005

[OCSP]
pki_admin_cert_file=ca_admin.cert
pki_admin_email=ocspadmin@example.com
pki_admin_name=ocspadmin
pki_admin_nickname=ocspadmin
pki_admin_password=Secret.123
pki_admin_uid=ocspadmin

pki_client_pkcs12_password=Secret.123

pki_ds_url=ldap://localhost.localdomain:389
pki_ds_base_dn=dc=ocsp,dc=pki,dc=example,dc=com
pki_ds_database=ocsp
pki_ds_password=Secret.123

pki_security_domain_name=EXAMPLE
pki_security_domain_user=caadmin
pki_security_domain_password=Secret.123

pki_ocsp_signing_nickname=ocsp_signing
pki_ocsp_signing_key_type=ecc
pki_ocsp_signing_key_algorithm=SHA512withEC
pki_ocsp_signing_key_size=nistp521

pki_audit_signing_nickname=ocsp_audit_signing
pki_audit_signing_key_type=ecc
pki_audit_signing_key_algorithm=SHA512withEC
pki_audit_signing_key_size=nistp521
pki_audit_signing_signing_algorithm=SHA512withEC

pki_sslserver_nickname=sslserver
pki_sslserver_key_type=ecc
pki_sslserver_key_algorithm=SHA512withEC
pki_sslserver_key_size=nistp521

pki_subsystem_nickname=subsystem
pki_subsystem_key_type=ecc
pki_subsystem_key_algorithm=SHA512withEC
pki_subsystem_key_size=nistp521
    Copy to Clipboard Toggle word wrap

  2. Execute the following command: 

    $ pkispawn -f ocsp.cfg -s OCSP
    Copy to Clipboard Toggle word wrap

It installs a OCSP subsystem in a Tomcat instance (default is pki-tomcat) and creates the following NSS databases:

  • server NSS database: /var/lib/pki/pki-tomcat/conf/alias
  • admin NSS database: ~/.dogtag/pki-tomcat/kra/alias
7.4.3.2.2. Verifying system certificates
Copia collegamento

Verify that the server NSS database contains the following certificates: 

$ certutil -L -d /var/lib/pki/pki-tomcat/conf/alias

Certificate Nickname                                         Trust Attributes
                                                             SSL,S/MIME,JAR/XPI

ca_signing                                                   CT,C,C
subsystem                                                    u,u,u
ocsp_audit_signing                                           u,u,Pu
ocsp_signing                                                 u,u,u
sslserver                                                    u,u,u
Copy to Clipboard Toggle word wrap
7.4.3.2.3. Verifying admin certificate
Copia collegamento

  1. Import the CA signing certificate: 

    $ pki nss-cert-import --cert ca_signing.crt --trust CT,C,C ca_signing
    Copy to Clipboard Toggle word wrap

  2. Import admin certificate and key into the client NSS database (by default ~/.dogtag/nssdb) with the following command: 

    $ pki -c Secret.123 pkcs12-import \
    --pkcs12 ca_admin_cert.p12 \
    --pkcs12-password Secret.123
    Copy to Clipboard Toggle word wrap

  3. Verify that the admin certificate can be used to access the OCSP subsystem by executing the following command: 

    $ pki -c Secret.123 -n caadmin ocsp-user-show ocspadmin
--------------
User "ocspadmin"
--------------
  User ID: ocspadmin
  Full name: ocspadmin
  Email: ocspadmin@example.com
  Type: adminType
  State: 1
    Copy to Clipboard Toggle word wrap

7.4.3.3. Installing OCSP with HSM
Copia collegamento

Follow this process to install an OCSP subsystem where the system certificates and their keys are stored on a HSM.

Prior to installation, ensure that the Installation Prerequisites are configured.

7.4.3.3.1. Installing OCSP subsystem
Copia collegamento

  1. Prepare a file, for example ocsp.cfg, that contains the deployment configuration: 

    [DEFAULT]
pki_instance_name=pki-tomcat
pki_https_port=8443
pki_http_port=8080
pki_server_database_password=Secret.123

pki_hsm_enable=True
pki_hsm_libfile=/usr/lib64/pkcs11/libsofthsm2.so
pki_hsm_modulename=softhsm
pki_token_name=HSM
pki_token_password=Secret.HSM

[Tomcat]
pki_ajp_port=8009
pki_tomcat_server_port=8005

[OCSP]
pki_admin_cert_file=ca_admin.cert
pki_admin_email=ocspadmin@example.com
pki_admin_name=ocspadmin
pki_admin_nickname=ocspadmin
pki_admin_password=Secret.123
pki_admin_uid=ocspadmin

pki_client_pkcs12_password=Secret.123

pki_ds_url=ldap://localhost.localdomain:389
pki_ds_base_dn=dc=ocsp,dc=pki,dc=example,dc=com
pki_ds_database=ocsp
pki_ds_password=Secret.123

pki_security_domain_name=EXAMPLE
pki_security_domain_user=caadmin
pki_security_domain_password=Secret.123

pki_ocsp_signing_nickname=ocsp_signing
pki_audit_signing_nickname=ocsp_audit_signing
pki_sslserver_nickname=sslserver/pki.example.com
pki_subsystem_nickname=subsystem
    Copy to Clipboard Toggle word wrap

  2. Execute the following command: 

    $ pkispawn -f ocsp.cfg -s OCSP
    Copy to Clipboard Toggle word wrap

It installs a OCSP subsystem in a Tomcat instance (default is pki-tomcat) and creates the following NSS databases:

  • server NSS database: /var/lib/pki/pki-tomcat/conf/alias
  • admin NSS database: ~/.dogtag/pki-tomcat/ocsp/alias
7.4.3.3.2. Verifying system certificates
Copia collegamento

  1. Verify that the internal token contains the following certificates: 

    $ certutil -L -d /var/lib/pki/pki-tomcat/conf/alias

Certificate Nickname                                         Trust Attributes
                                                             SSL,S/MIME,JAR/XPI

ca_signing                                                   CT,C,C
ocsp_audit_signing                                           ,,P
    Copy to Clipboard Toggle word wrap

  2. Verify that the HSM contains the following certificates: 

    $ certutil -L -d /var/lib/pki/pki-tomcat/conf/alias -h HSM -f HSM.pwd

Certificate Nickname                                         Trust Attributes
                                                             SSL,S/MIME,JAR/XPI

HSM:ocsp_signing                                             u,u,u
HSM:subsystem                                                u,u,u
HSM:ocsp_audit_signing                                       u,u,Pu
HSM:sslserver/pki.example.com                                u,u,u
    Copy to Clipboard Toggle word wrap
7.4.3.3.3. Verifying admin certificate
Copia collegamento

  1. Import the CA signing certificate: 

    $ pki nss-cert-import --cert ca_signing.crt --trust CT,C,C ca_signing
    Copy to Clipboard Toggle word wrap

  2. Import admin certificate and key into the client NSS database (by default ~/.dogtag/nssdb) with the following command: 

    $ pki -c Secret.123 pkcs12-import \
    --pkcs12 ca_admin_cert.p12 \
    --pkcs12-password Secret.123
    Copy to Clipboard Toggle word wrap

  3. Verify that the admin certificate can be used to access the OCSP subsystem by executing the following command: 

    $ pki -c Secret.123 -n caadmin ocsp-user-show ocspadmin
----------------
User "ocspadmin"
----------------
  User ID: ocspadmin
  Full name: ocspadmin
  Email: ocspadmin@example.com
  Type: adminType
  State: 1
    Copy to Clipboard Toggle word wrap
7.4.3.3.4. Verifying OCSP client
Copia collegamento

  1. Publish the CRL in CA to the directory server as follows:

    1. Go to CA Agent UI (https://pki.example.com:8443/ca/agent/ca/).
    2. Click Update Directory Server.
    3. Select Update the certificate revocation list to the directory.
    4. Click Update Directory.

  2. Verify that the OCSPClient can be used to validate a certificate: 

    $ OCSPClient \
 -d /var/lib/pki/pki-tomcat/conf/alias \
 -h pki.example.com \
 -p 8080 \
 -t /ocsp/ee/ocsp \
 -c ca_signing \
 --serial 1
CertID.serialNumber=1
CertStatus=Good
    Copy to Clipboard Toggle word wrap

7.4.3.4. Installing OCSP with LDAPS connection
Copia collegamento

Follow this process to install an OCSP subsystem with a secure database connection.

Prior to installation, ensure that the Installation Prerequisites are configured.

7.4.3.4.1. DS configuration
Copia collegamento

Once the prerequisites listed above are completed, if you chose to use the DS bootstrap certificates during DS instance creation, then export the bootstrap self-signed certificate into ds_signing.crt as follows 

$ certutil -L -d /etc/dirsrv/slapd-localhost -n Self-Signed-CA -a > ds_signing.crt
Copy to Clipboard Toggle word wrap
7.4.3.4.2. Installing OCSP subsystem
Copia collegamento

  1. Prepare a file, for example ocsp.cfg, that contains the deployment configuration: 

    [DEFAULT]
pki_instance_name=pki-tomcat
pki_https_port=8443
pki_http_port=8080
pki_server_database_password=Secret.123

[Tomcat]
pki_ajp_port=8009
pki_tomcat_server_port=8005

[OCSP]
pki_admin_cert_file=ca_admin.cert
pki_admin_email=ocspadmin@example.com
pki_admin_name=ocspadmin
pki_admin_nickname=ocspadmin
pki_admin_password=Secret.123
pki_admin_uid=ocspadmin

pki_client_pkcs12_password=Secret.123

pki_ds_url=ldaps://localhost.localdomain:636
pki_ds_secure_connection_ca_nickname=ds_signing
pki_ds_secure_connection_ca_pem_file=ds_signing.crt

pki_ds_base_dn=dc=ocsp,dc=pki,dc=example,dc=com
pki_ds_database=ocsp
pki_ds_password=Secret.123

pki_security_domain_name=EXAMPLE
pki_security_domain_user=caadmin
pki_security_domain_password=Secret.123

pki_ocsp_signing_nickname=ocsp_signing
pki_audit_signing_nickname=ocsp_audit_signing
pki_sslserver_nickname=sslserver
pki_subsystem_nickname=subsystem
    Copy to Clipboard Toggle word wrap

  2. Execute the following command: 

    $ pkispawn -f ocsp.cfg -s OCSP
    Copy to Clipboard Toggle word wrap

It installs a OCSP subsystem in a Tomcat instance (default is pki-tomcat) and creates the following NSS databases:

  • server NSS database: /var/lib/pki/pki-tomcat/conf/alias
  • admin NSS database: ~/.dogtag/pki-tomcat/ocsp/alias
7.4.3.4.3. Verifying system certificates
Copia collegamento

Verify that the server NSS database contains the following certificates: 

$ certutil -L -d /var/lib/pki/pki-tomcat/conf/alias

Certificate Nickname                                         Trust Attributes
                                                             SSL,S/MIME,JAR/XPI

ds_signing                                                   CT,C,C
ca_signing                                                   CT,C,C
ocsp_signing                                                 u,u,u
subsystem                                                    u,u,u
ocsp_audit_signing                                           u,u,Pu
sslserver                                                    u,u,u
Copy to Clipboard Toggle word wrap
7.4.3.4.4. Verifying database configuration
Copia collegamento

Verify that the OCSP database is configured with a secure connection: 

$ pki-server ocsp-db-config-show
  Hostname: pki.example.com
  Port: 636
  Secure: true
  Authentication: BasicAuth
  Bind DN: cn=Directory Manager
  Bind Password Prompt: internaldb
  Database: ocsp
  Base DN: dc=ocsp,dc=pki,dc=example,dc=com
  Multiple suffix: false
  Maximum connections: 15
  Minimum connections: 3
Copy to Clipboard Toggle word wrap
7.4.3.4.5. Verifying admin certificate
Copia collegamento

  1. Import the CA signing certificate: 

    $ pki nss-cert-import --cert ca_signing.crt --trust CT,C,C ca_signing
    Copy to Clipboard Toggle word wrap

  2. Import admin certificate and key into the client NSS database (by default ~/.dogtag/nssdb) with the following command: 

    $ pki -c Secret.123 pkcs12-import \
    --pkcs12 ca_admin_cert.p12 \
    --pkcs12-password Secret.123
    Copy to Clipboard Toggle word wrap

  3. Verify that the admin certificate can be used to access the OCSP subsystem by executing the following command: 

    $ pki -c Secret.123 -n caadmin ocsp-user-show ocspadmin
----------------
User "ocspadmin"
----------------
  User ID: ocspadmin
  Full name: ocspadmin
  Email: ocspadmin@example.com
  Type: adminType
  State: 1
    Copy to Clipboard Toggle word wrap
7.4.3.4.6. Verifying OCSP client
Copia collegamento

  1. Publish the CRL in CA to the directory server as follows:

    1. Go to CA Agent UI (https://pki.example.com:8443/ca/agent/ca/).
    2. Click Update Directory Server.
    3. Select Update the certificate revocation list to the directory.
    4. Click Update Directory.

  2. Verify that the OCSPClient can be used to validate a certificate: 

    $ OCSPClient \
 -d /var/lib/pki/pki-tomcat/conf/alias \
 -h pki.example.com \
 -p 8080 \
 -t /ocsp/ee/ocsp \
 -c ca_signing \
 --serial 1
CertID.serialNumber=1
CertStatus=Good
    Copy to Clipboard Toggle word wrap
7.4.3.4.7. Getting real DS Certificate from the CA
Copia collegamento

If desired, follow this procedure to get real DS certificate issued by the CA.

7.4.3.5. Installing standalone OCSP
Copia collegamento

Follow this process to install a standalone OCSP subsystem.

In regular OCSP installation the OCSP certificates are issued automatically by the CA and the OCSP will join the CA’s security domain.

In standalone OCSP installation, the OCSP certificates are issued manually and the OCSP has its own security domain.

The installation process consists multiple steps:

  • Generating certificate requests
  • Issuing the certificates
  • Completing installation with the certificates
7.4.3.5.1. Generating certificate requests
Copia collegamento

  1. Prepare a file, for example ocsp-standalone-step1.cfg, that contains the first deployment configuration.

    A sample deployment configuration is available at /usr/share/pki/server/examples/installation/ocsp-standalone-step1.cfg.

  2. Execute the following command: 

    $ pkispawn -f ocsp-standalone-step1.cfg -s OCSP
    Copy to Clipboard Toggle word wrap

It creates an NSS database in /var/lib/pki/pki-tomcat/alias and generates CSRs in the specified paths.

7.4.3.5.2. Issuing certificates
Copia collegamento

Use the CSRs to obtain OCSP certificates by submitting the CSRs to an external CA to issue the KRA system certificates. In the section that follows, it is assumed that the KRA system certificates are stored in the following files:

  • ocsp_signing.crt
  • subsystem.crt
  • sslserver.crt
  • ocsp_audit_signing.crt
  • ocsp_admin.crt
7.4.3.5.3. Completing installation
Copia collegamento

  1. Prepare another file, for example ocsp-standalone-step2.cfg, that contains the second deployment configuration. The file can be created from the first file, that is ocsp-standalone-step1.cfg, with the following changes: 

    pki_external_step_two=True
    Copy to Clipboard Toggle word wrap

  2. Specify the certificate files with the following parameters: 

    pki_ocsp_signing_cert_path=ocsp_signing.crt
pki_subsystem_cert_path=subsystem.crt
pki_sslserver_cert_path=sslserver.crt
pki_audit_signing_cert_path=ocsp_audit_signing.crt
pki_admin_cert_path=ocsp_admin.crt
    Copy to Clipboard Toggle word wrap

    Each certificate file can contain either a single PEM certificate or a PKCS #7 certificate chain.

  3. Specify the CA certificate chain with the following parameters: 

    pki_cert_chain_nickname=ca_signing
pki_cert_chain_path=ca_signing.crt
    Copy to Clipboard Toggle word wrap

    The CA certificate chain file can contain either a single PEM certificate or a PKCS #7 certificate chain as well.

    A sample deployment configuration is available at /usr/share/pki/server/examples/installation/ocsp-standalone-step2.cfg.

  4. Execute the following command: 

    $ pkispawn -f ocsp-standalone-step2.cfg -s OCSP
    Copy to Clipboard Toggle word wrap
7.4.3.5.4. Verifying Admin Certificate
Copia collegamento

  1. Import the CA signing certificate: 

    $ pki nss-cert-import --cert ca_signing.crt --trust CT,C,C ca_signing
    Copy to Clipboard Toggle word wrap

  2. Import admin certificate and key into the client NSS database (by default ~/.dogtag/nssdb) with the following command: 

    $ pki pkcs12-import \
    --pkcs12 ocsp_admin_cert.p12 \
    --pkcs12-password Secret.123
    Copy to Clipboard Toggle word wrap

  3. Verify that the admin certificate can be used to access the OCSP subsystem by executing the following command: 

    $ pki -n ocspadmin ocsp-user-show ocspadmin
----------------
User "ocspadmin"
----------------
  User ID: ocspadmin
  Full name: ocspadmin
  Email: ocspadmin@example.com
  Type: adminType
  State: 1
    Copy to Clipboard Toggle word wrap

7.4.4. Installing the TKS subsystem
Copia collegamento

7.4.4.1. Installing TKS
Copia collegamento

Follow this process to install a TKS subsystem.

Prior to installation, ensure that the Installation Prerequisites are configured.

7.4.4.1.1. Installing TKS subsystem
Copia collegamento
  1. Prepare a file, for example tks.cfg, that contains the deployment configuration. A sample deployment configuration is available at /usr/share/pki/server/examples/installation/tks.cfg.

  2. Execute the following command: 

    $ pkispawn -f tks.cfg -s TKS
    Copy to Clipboard Toggle word wrap

It installs a TKS subsystem in a Tomcat instance (default is pki-tomcat) and creates the following NSS databases:

  • server NSS database: /var/lib/pki/pki-tomcat/conf/alias
  • admin NSS database: ~/.dogtag/pki-tomcat/tks/alias
Note

When TKS is installed on a new system without any other subsystems, it is necessary to provide the CA’s root certificate. Specify the path to the CA PKCS#7 PEM file in the pki_cert_chain_path. This allows the server to verify the CA’s SSL server certificate when contacting the security domain. It is up to the administrator to securely transport the CA root certificate (public key only!) to the system prior to TKS installation.

7.4.4.1.2. Verifying system certificates
Copia collegamento

Verify that the server NSS database contains the following certificates: 

$ certutil -L -d /var/lib/pki/pki-tomcat/conf/alias

Certificate Nickname                                         Trust Attributes
                                                             SSL,S/MIME,JAR/XPI

ca_signing                                                   CT,C,C
subsystem                                                    u,u,u
tks_audit_signing                                            u,u,Pu
sslserver                                                    u,u,u
Copy to Clipboard Toggle word wrap
7.4.4.1.3. Verifying admin certificate
Copia collegamento

  1. Import the CA signing certificate: 

    $ pki nss-cert-import --cert ca_signing.crt --trust CT,C,C ca_signing
    Copy to Clipboard Toggle word wrap

  2. Import admin certificate and key into the client NSS database (by default ~/.dogtag/nssdb) with the following command: 

    $ pki -c Secret.123 pkcs12-import \
    --pkcs12 ca_admin_cert.p12 \
    --pkcs12-password Secret.123
    Copy to Clipboard Toggle word wrap

  3. Verify that the admin certificate can be used to access the TKS subsystem by executing the following command: 

    $ pki -c Secret.123 -n caadmin tks-user-show tksadmin
---------------
User "tksadmin"
---------------
  User ID: tksadmin
  Full name: tksadmin
  Email: tksadmin@example.com
  Type: adminType
  State: 1
    Copy to Clipboard Toggle word wrap

7.4.4.2. Installing TKS with HSM
Copia collegamento

Follow this process to install a TKS subsystem where the system certificates and their keys are stored on a HSM.

Prior to installation, ensure that the Installation Prerequisites are configured.

7.4.4.2.1. Installing TKS subsystem
Copia collegamento

  1. Prepare a file, for example tks.cfg, that contains the deployment configuration: 

    [DEFAULT]
pki_instance_name=pki-tomcat
pki_https_port=8443
pki_http_port=8080
pki_server_database_password=Secret.123

pki_hsm_enable=True
pki_hsm_libfile=/usr/lib64/pkcs11/libsofthsm2.so
pki_hsm_modulename=softhsm
pki_token_name=HSM
pki_token_password=Secret.HSM

[Tomcat]
pki_ajp_port=8009
pki_tomcat_server_port=8005

[TKS]
pki_admin_cert_file=ca_admin.cert
pki_admin_email=tksadmin@example.com
pki_admin_name=tksadmin
pki_admin_nickname=tksadmin
pki_admin_password=Secret.123
pki_admin_uid=tksadmin

pki_client_pkcs12_password=Secret.123

pki_ds_url=ldap://localhost.localdomain:389
pki_ds_base_dn=dc=tks,dc=pki,dc=example,dc=com
pki_ds_database=tks
pki_ds_password=Secret.123

pki_security_domain_name=EXAMPLE
pki_security_domain_user=caadmin
pki_security_domain_password=Secret.123

pki_audit_signing_nickname=tks_audit_signing
pki_sslserver_nickname=sslserver
pki_subsystem_nickname=subsystem
    Copy to Clipboard Toggle word wrap

  2. Execute the following command: 

    $ pkispawn -f tks.cfg -s TKS
    Copy to Clipboard Toggle word wrap

It installs a TKS subsystem in a Tomcat instance (default is pki-tomcat) and creates the following NSS databases:

  • server NSS database: /var/lib/pki/pki-tomcat/conf/alias
  • admin NSS database: ~/.dogtag/pki-tomcat/tks/alias
7.4.4.2.2. Verifying system certificates
Copia collegamento

  1. Verify that the internal token contains the following certificates: 

    $ certutil -L -d /var/lib/pki/pki-tomcat/conf/alias

Certificate Nickname                                         Trust Attributes
                                                             SSL,S/MIME,JAR/XPI

ca_signing                                                   CT,C,C
tks_audit_signing                                            ,,P
    Copy to Clipboard Toggle word wrap

  2. Verify that the HSM contains the following certificates: 

    $ certutil -L -d /var/lib/pki/pki-tomcat/conf/alias -h HSM -f HSM.pwd

Certificate Nickname                                         Trust Attributes
                                                             SSL,S/MIME,JAR/XPI

HSM:subsystem                                                u,u,u
HSM:tks_audit_signing                                        u,u,Pu
HSM:sslserver                                                u,u,u
    Copy to Clipboard Toggle word wrap
7.4.4.2.3. Verifying admin certificate
Copia collegamento

  1. Import the CA signing certificate: 

    $ pki nss-cert-import --cert ca_signing.crt --trust CT,C,C ca_signing
    Copy to Clipboard Toggle word wrap

  2. Import admin certificate and key into the client NSS database (by default ~/.dogtag/nssdb) with the following command: 

    $ pki -c Secret.123 pkcs12-import \
    --pkcs12 ca_admin_cert.p12 \
    --pkcs12-password Secret.123
    Copy to Clipboard Toggle word wrap

  3. Verify that the admin certificate can be used to access the TKS subsystem by executing the following command: 

    $ pki -c Secret.123 -n caadmin tks-user-show tksadmin
---------------
User "tksadmin"
---------------
  User ID: tksadmin
  Full name: tksadmin
  Email: tksadmin@example.com
  Type: adminType
  State: 1
    Copy to Clipboard Toggle word wrap

7.4.4.3. Installing TKS with LDAPS connection
Copia collegamento

Follow this process to install a TKS subsystem with a secure database connection.

Prior to installation, ensure that the Installation Prerequisites are configured.

7.4.4.3.1. DS configuration
Copia collegamento

Once the prerequisites listed above are completed, if you chose to use the DS bootstrap certificates during DS instance creation, then export the bootstrap self-signed certificate into ds_signing.crt as follows: 

$ certutil -L -d /etc/dirsrv/slapd-localhost -n Self-Signed-CA -a > ds_signing.crt
Copy to Clipboard Toggle word wrap
7.4.4.3.2. Installing TKS subsystem
Copia collegamento

  1. Prepare a file, for example tks.cfg, that contains the deployment configuration: 

    [DEFAULT]
pki_instance_name=pki-tomcat
pki_https_port=8443
pki_http_port=8080
pki_server_database_password=Secret.123

[Tomcat]
pki_ajp_port=8009
pki_tomcat_server_port=8005

[TKS]
pki_admin_cert_file=ca_admin.cert
pki_admin_email=tksadmin@example.com
pki_admin_name=tksadmin
pki_admin_nickname=tksadmin
pki_admin_password=Secret.123
pki_admin_uid=tksadmin

pki_client_pkcs12_password=Secret.123

pki_ds_url=ldaps://localhost.localdomain:636
pki_ds_secure_connection_ca_nickname=ds_signing
pki_ds_secure_connection_ca_pem_file=ds_signing.crt

pki_ds_base_dn=dc=tks,dc=pki,dc=example,dc=com
pki_ds_database=tks
pki_ds_password=Secret.123

pki_security_domain_name=EXAMPLE
pki_security_domain_user=caadmin
pki_security_domain_password=Secret.123

pki_audit_signing_nickname=tks_audit_signing
pki_sslserver_nickname=sslserver
pki_subsystem_nickname=subsystem
    Copy to Clipboard Toggle word wrap

  2. Execute the following command: 

    $ pkispawn -f tks.cfg -s TKS
    Copy to Clipboard Toggle word wrap

It installs a TKS subsystem in a Tomcat instance (default is pki-tomcat) and creates the following NSS databases:

  • server NSS database: /var/lib/pki/pki-tomcat/conf/alias
  • admin NSS database: ~/.dogtag/pki-tomcat/tks/alias
7.4.4.3.3. Verifying system certificates
Copia collegamento

Verify that the server NSS database contains the following certificates: 

$ certutil -L -d /var/lib/pki/pki-tomcat/conf/alias

Certificate Nickname                                         Trust Attributes
                                                             SSL,S/MIME,JAR/XPI

ds_signing                                                   CT,C,C
ca_signing                                                   CT,C,C
subsystem                                                    u,u,u
tks_audit_signing                                            u,u,Pu
sslserver                                                    u,u,u
Copy to Clipboard Toggle word wrap
7.4.4.3.4. Verifying database configuration
Copia collegamento

Verify that the TKS database is configured with a secure connection: 

$ pki-server tks-db-config-show
  Hostname: pki.example.com
  Port: 636
  Secure: true
  Authentication: BasicAuth
  Bind DN: cn=Directory Manager
  Bind Password Prompt: internaldb
  Database: tks
  Base DN: dc=tks,dc=pki,dc=example,dc=com
  Multiple suffix: false
  Maximum connections: 15
  Minimum connections: 3
Copy to Clipboard Toggle word wrap
7.4.4.3.5. Verifying admin certificate
Copia collegamento

  1. Import the CA signing certificate: 

    $ pki nss-cert-import --cert ca_signing.crt --trust CT,C,C ca_signing
    Copy to Clipboard Toggle word wrap

  2. Import admin certificate and key into the client NSS database (by default ~/.dogtag/nssdb) with the following command: 

    $ pki -c Secret.123 pkcs12-import \
    --pkcs12 ca_admin_cert.p12 \
    --pkcs12-password Secret.123
    Copy to Clipboard Toggle word wrap

  3. Verify that the admin certificate can be used to access the TKS subsystem by executing the following command: 

    $ pki -c Secret.123 -n caadmin tks-user-show tksadmin
---------------
User "tksadmin"
---------------
  User ID: tksadmin
  Full name: tksadmin
  Email: tksadmin@example.com
  Type: adminType
  State: 1
    Copy to Clipboard Toggle word wrap
7.4.4.3.6. Getting real DS Certificate from the CA
Copia collegamento

If desired, follow this procedure to get real DS certificate issued by the CA.

7.4.5. Installing the TPS subsystem
Copia collegamento

7.4.5.1. Installing TPS
Copia collegamento

Follow this process to install a TPS subsystem.

Prior to installation, ensure that the Installation Prerequisites are configured.

7.4.5.1.1. Installing TPS subsystem
Copia collegamento
  1. Prepare a file, for example tps.cfg, that contains the deployment configuration. A sample deployment configuration is available at /usr/share/pki/server/examples/installation/tps.cfg.

  2. Execute the following command: 

    $ pkispawn -f tps.cfg -s TPS
    Copy to Clipboard Toggle word wrap

It installs a TPS subsystem in a Tomcat instance (default is pki-tomcat) and creates the following NSS databases:

  • server NSS database: /var/lib/pki/pki-tomcat/conf/alias
  • admin NSS database: ~/.dogtag/pki-tomcat/tps/alias
Note

When TPS is installed on a new system without any other subsystems, it is necessary to provide the CA’s root certificate. Specify the path to the CA PKCS#7 PEM file in the pki_cert_chain_path. This allows the server to verify the CA’s SSL server certificate when contacting the security domain. It is up to the administrator to securely transport the CA root certificate (public key only) to the system prior to TPS installation.

7.4.5.1.2. Verifying system certificates
Copia collegamento

Verify that the server NSS database contains the following certificates: 

$ certutil -L -d /var/lib/pki/pki-tomcat/conf/alias

Certificate Nickname                                         Trust Attributes
                                                             SSL,S/MIME,JAR/XPI

ca_signing                                                   CT,C,C
subsystem                                                    u,u,u
tps_audit_signing                                            u,u,Pu
sslserver                                                    u,u,u
Copy to Clipboard Toggle word wrap
7.4.5.1.3. Verifying admin certificate
Copia collegamento

  1. Import the CA signing certificate: 

    $ pki nss-cert-import --cert ca_signing.crt --trust CT,C,C ca_signing
    Copy to Clipboard Toggle word wrap

  2. Import admin certificate and key into the client NSS database (by default ~/.dogtag/nssdb) with the following command: 

    $ pki -c Secret.123 pkcs12-import \
    --pkcs12 ca_admin_cert.p12 \
    --pkcs12-password Secret.123
    Copy to Clipboard Toggle word wrap

  3. Verify that the admin certificate can be used to access the TPS subsystem by executing the following command: 

    $ pki -c Secret.123 -n caadmin tps-user-show tpsadmin
---------------
User "tpsadmin"
---------------
  User ID: tpsadmin
  Full name: tpsadmin
  Email: tpsadmin@example.com
  Type: adminType
  State: 1
  TPS Profiles:
    All Profiles
    Copy to Clipboard Toggle word wrap

7.4.5.2. Installing TPS with HSM
Copia collegamento

Follow this process to install a TPS subsystem where the system certificates and their keys are stored on a HSM.

Prior to installation, ensure that the Installation Prerequisites are configured.

7.4.5.2.1. Installing TPS subsystem
Copia collegamento

  1. Prepare a file, for example tps.cfg, that contains the deployment configuration: 

    [DEFAULT]
pki_instance_name=pki-tomcat
pki_https_port=8443
pki_http_port=8080
pki_server_database_password=Secret.123

pki_hsm_enable=True
pki_hsm_libfile=/usr/lib64/pkcs11/libsofthsm2.so
pki_hsm_modulename=softhsm
pki_token_name=HSM
pki_token_password=Secret.HSM

[Tomcat]
pki_ajp_port=8009
pki_tomcat_server_port=8005

[TPS]
pki_admin_cert_file=ca_admin.cert
pki_admin_email=tpsadmin@example.com
pki_admin_name=tpsadmin
pki_admin_nickname=tpsadmin
pki_admin_password=Secret.123
pki_admin_uid=tpsadmin

pki_client_pkcs12_password=Secret.123

pki_ds_url=ldap://localhost.localdomain:389
pki_ds_base_dn=dc=tps,dc=pki,dc=example,dc=com
pki_ds_database=tps
pki_ds_password=Secret.123

pki_security_domain_name=EXAMPLE
pki_security_domain_user=caadmin
pki_security_domain_password=Secret.123

pki_audit_signing_nickname=tps_audit_signing
pki_sslserver_nickname=sslserver
pki_subsystem_nickname=subsystem
    Copy to Clipboard Toggle word wrap

  2. Execute the following command: 

    $ pkispawn -f tps.cfg -s TPS
    Copy to Clipboard Toggle word wrap

It installs a TPS subsystem in a Tomcat instance (default is pki-tomcat) and creates the following NSS databases:

  • server NSS database: /var/lib/pki/pki-tomcat/conf/alias
  • admin NSS database: ~/.dogtag/pki-tomcat/tps/alias
7.4.5.2.2. Verifying system certificates
Copia collegamento

  1. Verify that the internal token contains the following certificates: 

    $ certutil -L -d /var/lib/pki/pki-tomcat/conf/alias

Certificate Nickname                                         Trust Attributes
                                                             SSL,S/MIME,JAR/XPI

ca_signing                                                   CT,C,C
tps_audit_signing                                            ,,P
    Copy to Clipboard Toggle word wrap

  2. Verify that the HSM contains the following certificates: 

    $ certutil -L -d /var/lib/pki/pki-tomcat/conf/alias -h HSM -f HSM.pwd

Certificate Nickname                                         Trust Attributes
                                                             SSL,S/MIME,JAR/XPI

HSM:subsystem                                                u,u,u
HSM:tps_audit_signing                                        u,u,Pu
HSM:sslserver                                                u,u,u
    Copy to Clipboard Toggle word wrap
7.4.5.2.3. Verifying admin certificate
Copia collegamento

  1. Import the CA signing certificate: 

    $ pki nss-cert-import --cert ca_signing.crt --trust CT,C,C ca_signing
    Copy to Clipboard Toggle word wrap

  2. Import admin certificate and key into the client NSS database (by default ~/.dogtag/nssdb) with the following command: 

    $ pki -c Secret.123 pkcs12-import \
    --pkcs12 ca_admin_cert.p12 \
    --pkcs12-password Secret.123
    Copy to Clipboard Toggle word wrap

  3. Verify that the admin certificate can be used to access the TPS subsystem by executing the following command: 

    $ pki -c Secret.123 -n caadmin tps-user-show tpsadmin
---------------
User "tpsadmin"
---------------
  User ID: tpsadmin
  Full name: tpsadmin
  Email: tpsadmin@example.com
  Type: adminType
  State: 1
  TPS Profiles:
    All Profiles
    Copy to Clipboard Toggle word wrap

7.4.5.3. Installing TPS with LDAPS connection
Copia collegamento

Follow this process to install a TPS subsystem a secure database connection.

Prior to installation, ensure that the Installation Prerequisites are configured.

7.4.5.3.1. DS configuration
Copia collegamento

Once the prerequisites listed above are completed, if you had chosen to use the DS bootstrap certificates during DS instance creation, then export the bootstrap self-signed certificate into ds_signing.crt as follows: 

$ certutil -L -d /etc/dirsrv/slapd-localhost -n Self-Signed-CA -a > ds_signing.crt
Copy to Clipboard Toggle word wrap
7.4.5.3.2. Installing TPS subsystem
Copia collegamento

  1. Prepare a file, for example tps.cfg, that contains the deployment configuration: 

    [DEFAULT]
pki_instance_name=pki-tomcat
pki_https_port=8443
pki_http_port=8080
pki_server_database_password=Secret.123

[Tomcat]
pki_ajp_port=8009
pki_tomcat_server_port=8005

[TPS]
pki_admin_cert_file=ca_admin.cert
pki_admin_email=tpsadmin@example.com
pki_admin_name=tpsadmin
pki_admin_nickname=tpsadmin
pki_admin_password=Secret.123
pki_admin_uid=tpsadmin

pki_client_pkcs12_password=Secret.123

pki_ds_url=ldaps://localhost.localdomain:636
pki_ds_secure_connection_ca_nickname=ds_signing
pki_ds_secure_connection_ca_pem_file=ds_signing.crt

pki_ds_base_dn=dc=tps,dc=pki,dc=example,dc=com
pki_ds_database=tps
pki_ds_password=Secret.123

pki_security_domain_name=EXAMPLE
pki_security_domain_user=caadmin
pki_security_domain_password=Secret.123

pki_audit_signing_nickname=tps_audit_signing
pki_sslserver_nickname=sslserver
pki_subsystem_nickname=subsystem
    Copy to Clipboard Toggle word wrap

  2. Execute the following command: 

    $ pkispawn -f tps.cfg -s TPS
    Copy to Clipboard Toggle word wrap

It installs a TPS subsystem in a Tomcat instance (default is pki-tomcat) and creates the following NSS databases:

  • server NSS database: /var/lib/pki/pki-tomcat/conf/alias
  • admin NSS database: ~/.dogtag/pki-tomcat/tps/alias
7.4.5.3.3. Verifying system certificates
Copia collegamento

Verify that the server NSS database contains the following certificates: 

$ certutil -L -d /var/lib/pki/pki-tomcat/conf/alias

Certificate Nickname                                         Trust Attributes
                                                             SSL,S/MIME,JAR/XPI

ds_signing                                                   CT,C,C
ca_signing                                                   CT,C,C
subsystem                                                    u,u,u
tps_audit_signing                                            u,u,Pu
sslserver                                                    u,u,u
Copy to Clipboard Toggle word wrap
7.4.5.3.4. Verifying database configuration
Copia collegamento

Verify that the TPS database is configured with a secure connection: 

$ pki-server tps-db-config-show
  Hostname: pki.example.com
  Port: 636
  Secure: true
  Authentication: BasicAuth
  Bind DN: cn=Directory Manager
  Bind Password Prompt: internaldb
  Database: tps
  Base DN: dc=tps,dc=pki,dc=example,dc=com
  Multiple suffix: false
  Maximum connections: 15
  Minimum connections: 3
Copy to Clipboard Toggle word wrap
7.4.5.3.5. Verifying admin certificate
Copia collegamento

  1. Import the CA signing certificate: 

    $ pki nss-cert-import --cert ca_signing.crt --trust CT,C,C ca_signing
    Copy to Clipboard Toggle word wrap

  2. Import admin certificate and key into the client NSS database (by default ~/.dogtag/nssdb) with the following command: 

    $ pki -c Secret.123 pkcs12-import \
    --pkcs12 ca_admin_cert.p12 \
    --pkcs12-password Secret.123
    Copy to Clipboard Toggle word wrap

  3. Verify that the admin certificate can be used to access the TPS subsystem by executing the following command: 

    $ pki -c Secret.123 -n caadmin tps-user-show tpsadmin
---------------
User "tpsadmin"
---------------
  User ID: tpsadmin
  Full name: tpsadmin
  Email: tpsadmin@example.com
  Type: adminType
  State: 1
  TPS Profiles:
    All Profiles
    Copy to Clipboard Toggle word wrap
7.4.5.3.6. Getting real DS certificate from the CA
Copia collegamento

If desired, follow this procedure to get real DS certificate issued by the CA.

7.4.6. Installing the EST subsystem
Copia collegamento

7.4.6.1. Installing EST
Copia collegamento

Follow this process to install an EST subsystem.

The EST subsystem requires the package dogtag-pki-est installed on the server where the instance is run: 

# dnf install dogtag-pki-est
Copy to Clipboard Toggle word wrap
7.4.6.1.1. Prerequisites
Copia collegamento

On the CA, create a user group for EST RA accounts (EST RA Agents), and an EST RA account (est-ra-1). The EST subsystem uses this account to authenticate to the CA subsystem and issue certificates on behalf of EST clients.

Note: The commands below assume that the CA is running on the same host with the default port and the nssdb is located in ~/.dogtag/nssdb. To point to a CA on a different host or with a different port use the options -h <hostname>, -p <port_number> or -U <CA_uri. To use a different nssdb use the option -d <nssdb_path>. 

# pki -n caadmin ca-group-add "EST RA Agents"
---------------------------
Added group "EST RA Agents"
---------------------------
  Group ID: EST RA Agents

# pki -n caadmin ca-user-add \
      est-ra-1 --fullName "EST RA 1" --password password4ESTUser
---------------------
Added user "est-ra-1"
---------------------
  User ID: est-ra-1
  Full name: EST RA 1
# pki -n caadmin ca-group-member-add "EST RA Agents" est-ra-1
-----------------------------
  Added group member "est-ra-1"
-----------------------------
  User: est-ra-1
Copy to Clipboard Toggle word wrap

Add and enable the EST enrollment profile estServiceCert.cfg, which is available in /usr/share/pki/ca/profiles/ca if the dogtag-pki-ca package is installed: 

# pki -n caadmin ca-profile-add --raw /usr/share/pki/ca/profiles/ca/estServiceCert.cfg
----------------------------
Added profile estServiceCert
----------------------------
# pki -n caadmin ca-profile-enable estServiceCert
--------------------------------
Enabled profile "estServiceCert"
--------------------------------
Copy to Clipboard Toggle word wrap

Note: Before enabling the profile, verify if the options satisfy the requirement for the deployment.

EST subsystem has its own realm authentication with a separate user DB. LDAP, PostreSQL and file based DB are supported. The DB has to be prepared in advance for authentication to work. Instructions to set up the user DB are available in Configure EST Realm DB.

7.4.6.1.2. Installing EST subsystem
Copia collegamento

There are two options for the installation:

  • Basic installation with pkispawn. See Installing EST pkispawn;
  • Advanced installation with pki-server. See Installing EST pki-server. It requires more manual configuration but provides more control over the installation process since each step can be verified and eventually customized and repeated.
7.4.6.1.3. Verifying EST
Copia collegamento

Before enrolling certificates, EST users must be added in the user database. The user management is not part of EST commands and has to be done outside of EST. Information on how to add users on each database platform can be found in the Administration Guide.

Use curl to verify that the EST subsystem is deployed and is able to communicate with the CA subsystem.

The following command prints the CA signing certificate obtained from the server: 

$ curl --cacert ./ca_signing.crt  https://<EST_HOSTNAME>:<EST_PORT>/.well-known/est/cacerts | openssl base64 -d | openssl pkcs7 -inform der -print_certs | openssl x509 -text -noout
Copy to Clipboard Toggle word wrap

Replace $EST_HOSTNAME and $EST_PORT with the hostname and port of the EST subsystem, respectively.

If successful, the server CA certificate chain is printed on standard output and the command will exit with status 0 (success).

To test the enrollment using curl, generate a CSR and submit using a user from the EST user DB associated with the realm. The following commands will perform the enrollment and print the final certificate: 

$ pki nss-cert-request --csr testServer.csr \
    --ext /usr/share/pki/server/certs/sslserver.conf --subject 'CN=test.example.com'
$ openssl req -in testServer.csr -outform der | openssl base64 -out testServer.p10

$ curl --cacert ./ca_signing.crt --anyauth -u est-test-user:Secret.123 \
    --data-binary @testServer.p10 -H "Content-Type: application/pkcs10" \
    -o newCert.p7 https://<EST_HOSTNAME>:<EST_PORT>/.well-known/est/simpleenroll

$ openssl base64 -d -in newCert.p7 | openssl pkcs7 -inform der -print_certs | openssl x509 -text -noout
Copy to Clipboard Toggle word wrap

Note: The testServer.p10 file is a base64 encoded pkcs10 DER without header/footer.

In case the enrollment is done using mutual TLS authentication in the curl command above, the credentials have to be replaced with the certificate and related key as follows: 

$ curl --cacert ./ca_signing.crt --cert cert.pem --key key-x-x.pem \
    --data-binary @testServer.p10 -H "Content-Type: application/pkcs10"
    -o newCert.p7 https://<EST_HOSTNAME>:<EST_PORT>/.well-known/est/simpleenroll
Copy to Clipboard Toggle word wrap

When mutual TLS authentication is performed, the CSR subject and SAN has to match with the subject and SAN of the certificate used for the authentication in order to get authorized. Differently, using the basic authentication the CSR subject and SAN will be verified with user full name or user id. This check can be disabled for the simpleenroll operation. To disable this check add the following option to the file /etc/pki/<instance_name>/est/authorizer.conf: 

enrollMatchTLSSubjSAN=false
Copy to Clipboard Toggle word wrap

7.4.6.2. EST installation using pkispawn
Copia collegamento

Once the prerequisites in Installing EST are configured, it is possible to install EST.

7.4.6.2.1. Installation
Copia collegamento

An example pkispawn installation configuration is provided in /usr/share/pki/server/examples/installation/est.cfg with the following content: 

[DEFAULT]
pki_server_database_password=Secret.123
pki_admin_setup=False

[EST]
est_realm_type=ds
est_realm_url=ldap://localhost.localdomain:389
est_realm_bind_password=Secret.123
est_ca_user_name=est-ra-1
est_ca_user_password=Secret.est
pki_sslserver_nickname=sslserver
Copy to Clipboard Toggle word wrap

The following commands install an EST subsystem on a PKI server instance that already has a CA subsystem in it. By default the PKI server instance is called pki-tomcat and it uses HTTP port 8080 and HTTPS port 8443. To use a different instance name or port numbers refer to the command’s manual page.

To install EST in the same instance of the CA and with the DS realm, run the command: 

# pkispawn \
    -f /usr/share/pki/server/examples/installation/est.cfg \
    -s EST \
    -D est_realm_url=ldap://estds.example.com:389 \
    -v
Copy to Clipboard Toggle word wrap

Note that the est_realm_url points to the user DB. The other configurations that could be modified according to the deployment are: 

est_ca_profile=estServiceCert
est_ca_user_name=
est_ca_user_password=
est_ca_user_password_file=
est_ca_user_certificate=
est_realm_type=
est_realm_custom=
est_realm_url=
est_realm_auth_type=BasicAuth
est_realm_bind_dn=cn=Directory Manager
est_realm_bind_password=
est_realm_nickname=
est_realm_user=
est_realm_username=
est_realm_password=
est_realm_users_dn=ou=people,dc=est,dc=pki,dc=example,dc=com
est_realm_groups_dn=ou=groups,dc=est,dc=pki,dc=example,dc=com
est_realm_statements=/usr/share/pki/est/conf/realm/postgresql/statements.conf
est_authorizer_exec_path=/usr/share/pki/est/bin/estauthz
Copy to Clipboard Toggle word wrap

The est_ca_* provides information related to the user and profile configured in the CA for the EST subsystem.

The est_authorizer_exec_path is the path to the executable responsible for verifying the authorization. The default script estauthz is a simple authorization example that checks only that the user has the role estclient.

The est_realm_* options allow one to customize the realm. Possible types are: ds, postgresql and in-memory.

As an example, to install EST with PostgreSQL the command is: 

# pkispawn \
    -f /usr/share/pki/server/examples/installation/est.cfg \
    -s EST \
    -D est_realm_url="jdbc:postgresql://postgresql.example.com:5432/est?ssl=true&sslmode=require" \
    -D est_realm_type=postgresql \
    -D est_realm_user=est \
    -D est_realm_password=mysecretpassword \
    -v
Copy to Clipboard Toggle word wrap

The est_realm_custom is a path to a custom realm configuration for Tomcat and if provided it will overwrite all other realm related configurations.

7.4.6.2.1.1. Installation on separate instance with certificates
Copia collegamento

EST can also be installed on a Tomcat instance that is separate from the CA.

In addition to the configuration above, installing EST in a separate instance requires some extra steps to configure the certificates.

Note: The commands below assume that the CA is running on the same host with the default port and the nssdb is located in ~/.dogtag/nssdb. To point to a CA on a different host or with a different port use the options -h <hostname>, -p <port_number> or -U <CA_uri. To use a different nssdb use the option -d <nssdb_path>.

The EST server cert (and a subsystem certificate to connect with the CA) has to be pre-issued and provided to pkispawn with its full chain in a PKCS#12 bundle supplied via the pki_server_pkcs12_* parameters on the pkispawn command line as shown below.

It is important that the certificate aliases in the PKCS#12 matches with the nickname used by EST. For the SSL certificate the nickname configured in est.cfg is sslserver but can be modified.

To create the PKCS12 with the certificate it is possible to request a server certificate for EST from the CA (and later the RA user certificate) and then export them as shown below: 

# pki nss-cert-request --csr estSSLServer.csr \
    --ext /usr/share/pki/server/certs/sslserver.conf --subject 'CN=est.example.com'

# pki -n caadmin \
    ca-cert-issue \
    --csr-file estSSLServer.csr \
    --profile caServerCert \
    --output-file estSSLServer.crt

# pki nss-cert-import --cert estSSLServer.crt sslserver

# pki pkcs12-cert-import sslserver --pkcs12-file $SHARED/est_server.p12 --pkcs12-password Secret.123
Copy to Clipboard Toggle word wrap

Similarly, to generate a subsystem certificate for EST, associate to the EST RA user (est-ra-1) previously configured in the CA, and add in the same PKCS12 of the SSL server certificate: 

# pki nss-cert-request --csr est-ra-1.csr \
    --ext /usr/share/pki/server/certs/admin.conf \
    --subject 'CN=EST Subsystem Certificate,OU=pki-tomcat,O=EXAMPLE'

# pki -n caadmin -cert-issue \
    --csr-file est-ra-1.csr \
    --profile caSubsystemCert \
    --output-file est-ra-1.crt

# pki nss-cert-import --cert est-ra-1.crt "est-ra-1"

# pki -n caadmin ca-user-cert-add est-ra-1 --input est-ra-1.crt

# pki pkcs12-cert-import "est-ra-1" --pkcs12-file $SHARED/est_server.p12 --pkcs12-password Secret.123 --append
Copy to Clipboard Toggle word wrap

Using the generated PKCS#12 bundle, the command to deploy EST is: 

# pkispawn \
    -f /usr/share/pki/server/examples/installation/est.cfg \
    -s EST \
    -D est_realm_url=ldap://estds.example.com:389 \
    -D pki_ca_uri=https://ca.example.com:8443 \
    -D est_ca_user_password= \
    -D est_ca_user_certificate=est-ra-1 \
    -D pki_server_pkcs12_path=est_server.p12 \
    -D pki_server_pkcs12_password=Secret.123 \
    -v
Copy to Clipboard Toggle word wrap
7.4.6.2.1.2. Installation on separate instance without certificates
Copia collegamento

If the PKCS#12 bundle certificates are not provided to pkispawn, during the installation, the EST server cert is issued automatically using the profile configured for EST. The connection with the CA uses the credentials (username/password) provided in the configuration file. In such a case the CA signing certificate is needed. Retrieving the certificate can be done in the CA server with the command: 

# pki-server cert-export ca_signing --cert-file ca_signing.crt
Copy to Clipboard Toggle word wrap

It is possible to install EST with the following command: 

# pkispawn \
    -f /usr/share/pki/server/examples/installation/est.cfg \
    -s EST \
    -D est_realm_url=ldap://estds.example.com:389 \
    -D pki_ca_uri=https://ca.example.com:8443 \
    -D pki_cert_chain_path=ca_signing.crt \
    -D pki_cert_chain_nickname=caSigning \
    -v
Copy to Clipboard Toggle word wrap

After the installation it is possible to update the EST server certificates with a new certificate using a different profile if the EST released certificates are not meant for the server. Additionally, a certificate for TLS authentication could be added in the EST nssdb and configured in the file /var/lib/pki/pki-tomcat/conf/est/backend.conf.

7.4.6.2.2. Removing EST
Copia collegamento

To remove the EST subsystem, it is possible to use the pkidestroy command as follows: 

# pkidestroy -s EST -v
Copy to Clipboard Toggle word wrap

Note: the configuration and log folders are not removed. To remove everything add the the options: --remove-conf --remove-logs.

7.4.6.3. EST installation using pki-server
Copia collegamento

Once the prerequisite in Installing EST are configured, it is possible to install EST.

A PKI Tomcat instance has to be already available, if it is not present then it is possible to create a new one with pki-server create (see more details here).

Create the EST subsystem inside the pki server instance: 

# pki-server est-create
Copy to Clipboard Toggle word wrap

Configure the issuance backend. The class org.dogtagpki.est.DogtagRABackend is used for the EST instance to communicate with the CA. This requires:

  • The url parameter pointing to the CA subsystem;

  • Credentials of an EST RA account using either of the following methods that authorizes the account to request certificate issuance using the configured enrollment profile:

    • username and password if the EST RA account;
    • TLS client certificate that belongs to the EST RA account.
  • The enrollment profile. 
# cat >/var/lib/pki/pki-tomcat/conf/est/backend.conf <<EOF
class=org.dogtagpki.est.DogtagRABackend
url=https://$(hostname):8443
profile=estServiceCert
username=est-ra-1
password=password4ESTUser
EOF
Copy to Clipboard Toggle word wrap

Note: To use TLS mutual authentication instead of username/password, one needs to:

  • Get issuance for a TLS client certificate from the CA, using the EST instance’s crypto token for generating keys and CSR in the instance alias directory;
  • Import the certificate into the EST instance’s crypto token;
  • Assign the nickname to the parameter nickname (leave out username and password);
  • Add the certificate to the EST RA user account on the CA.

An example on how to get the certificate and configure EST with TLS mutual configuration is provided in the pkispawn installation guide here.

Configure request authorization. The class org.dogtagpki.est.ExternalProcessRequestAuthorizer allows to delegate the authorization to an external process configured with the parameter executable: 

# cat >/var/lib/pki/pki-tomcat/conf/est/authorizer.conf <<EOF
class=org.dogtagpki.est.ExternalProcessRequestAuthorizer
executable=/usr/share/pki/est/bin/estauthz
EOF
Copy to Clipboard Toggle word wrap

The executable script in this example performs a simple check of the user role and it is available at /usr/share/pki/est/bin/estauthz. It can be replaced if a more sophisticated authorization framework has to be adopted.

Deploy the EST application: 

# pki-server est-deploy
Copy to Clipboard Toggle word wrap

Configure the authentication. The authentication allows one to use realms from Tomcat or developed for dogtag. As an example we use an in memory realm: 

# cat >/var/lib/pki/pki-tomcat/conf/est/realm.conf <<EOF
class=com.netscape.cms.realm.PKIInMemoryRealm
username=alice
password=4me2Test
roles=estclient
EOF
Copy to Clipboard Toggle word wrap

Finally, restart the server: 

# pki-server restart --wait
Copy to Clipboard Toggle word wrap

7.4.6.4. Configure EST Realm DB
Copia collegamento

7.4.6.4.1. Preparing DS DB
Copia collegamento

If you have chosen to use an LDAP instance for user management, before adding users, ensure that you have configured the directory server and added base entries. Directory server setup instructions can be found in the Installation Prerequisites.

The user DB requires a group node for the people and one for the groups. A simple ldif file is available in /usr/share/pki/est/conf/realm/ds/create.ldif. The base DN in this is dc=pki,dc=example,dc=com but it can be modified and the new value specified during the following EST installation. The file can be imported with the following command: 

ldapadd -x -H ldap://<ds_server_hostname>:<ds_server_port> \
    -D "cn=Directory Manager"  -w Secret.123 \
    -f /usr/share/pki/est/conf/realm/ds/create.ldif
Copy to Clipboard Toggle word wrap

The command creates also the group EST Users and it is used as default group for users to access EST. Using a different group requires you to modify the authorization script /usr/share/pki/est/bin/estauthz.

7.4.6.4.2. Preparaing PostgreSQL DB
Copia collegamento

If you have chosen to use PostgreSQL for user management, you first need to prepare a database, for example est, to access the database. Installation instructions can be found here.

After the installation, verify the database connection with the following command: 

$ psql -U est -d est
Copy to Clipboard Toggle word wrap

To use the PostreSQL DB, the user tables should be created with the sql file provided in /usr/share/pki/est/conf/realm/postgresql/create.sql and then filled with the user information. The tables can be created with the command: 

$ psql -U est -t -A -f /usr/share/pki/est/conf/realm/postgresql/create.sql
Copy to Clipboard Toggle word wrap

The command creates also the group EST Users and it is used as default group for user to access EST. Using a different group requires you to modify the authorization script /usr/share/pki/est/bin/estauthz.

It is possible to use different schemas but in this case a custom statements.conf file (provided in the same folder) has to be provided in order to retrieve the user information from the DB.

Additionally, a Java driver for PostgreSQL needs to be installed in the EST server and linked into library folder of pki: 

# dnf install -y postgresql-jdbc
# ln -s /usr/share/java/postgresql-jdbc/postgresql.jar /usr/share/pki/server/common/lib
# ln -s /usr/share/java/ongres-scram/scram-client.jar /usr/share/pki/server/common/lib
# ln -s /usr/share/java/ongres-scram/scram-common.jar /usr/share/pki/server/common/lib
# ln -s /usr/share/java/ongres-stringprep/saslprep.jar /usr/share/pki/server/common/lib/
# ln -s /usr/share/java/ongres-stringprep/stringprep.jar /usr/share/pki/server/common/lib/
Copy to Clipboard Toggle word wrap

7.5. Post-installation tasks
Copia collegamento

Once installation using the pkispawn utility is complete, further steps could be taken to customize the configuration, depending on the site’s preferences. These are described in Part III, “Configuring Certificate System”.

This section provides a list of operations from Part III, “Configuring Certificate System” which are suggested for improving the security for the deployment.

7.5.1. Setting date/time for Red Hat Certificate System
Copia collegamento

It is important to have the time set up correctly for running RHCS; see the Setting time and date section in the Red Hat Certificate System Administration Guide.

7.5.2. Getting DS certificate issued by actual CA
Copia collegamento

Follow this process using pki CLI (run man pki-client) commands to get DS certificate issued by the actual CA.

This section assumes that a DS instance named localhost already exists,

Two conditions are covered by this section:

  • The DS instance does not already have any SSL server certificate, bootstrap or otherwise, and it is time to create an actual server cert for it.
  • The DS instance has a bootstrap SSL server certificate, and you wish to replace it.

It is assumed that an actual trusted CA is available for issuing certificates.

7.5.2.1. Export the CA signing certificate
Copia collegamento

pki-server cert-export ca_signing --cert-file ca_signing.crt
Copy to Clipboard Toggle word wrap

7.5.2.2. Creating DS server certificate
Copia collegamento

7.5.2.2.1. Generate DS server CSR
Copia collegamento

As a DS administrator: 

$ pki \
    -d /etc/dirsrv/slapd-localhost \
    -C /etc/dirsrv/slapd-localhost/pwdfile.txt \
    nss-cert-request \
    --subject "CN=server.example.com" \
    --subjectAltName "critical, DNS:server.example.com" \
    --csr ds_server.csr
Copy to Clipboard Toggle word wrap

Note: Make sure the certificate subject DN and SAN match the system hostname.

7.5.2.2.2. Submit DS server certificate request:
Copia collegamento

As a DS admin: 

$ pki ca-cert-request-submit --profile caServerCert --csr-file ds_server.csr
Copy to Clipboard Toggle word wrap
7.5.2.2.3. Approve the certificate request:
Copia collegamento

As a PKI agent: 

$ pki -n caadmin ca-cert-request-approve <request ID>
Copy to Clipboard Toggle word wrap

7.5.2.3. Retrieve the certificate
Copia collegamento

Retrieve the cert as the DS admin user: 

$  pki ca-cert-export <certificate ID> --output-file ds_server.crt
Copy to Clipboard Toggle word wrap

7.5.2.4. Stop the DS instance
Copia collegamento

Stop the DS instance prior to changing the NSS database. 

$ dsctl localhost stop
Copy to Clipboard Toggle word wrap

7.5.2.5. Import the CA signing certificate
Copia collegamento

As a DS administrator, import the CA signing cert into the nssdb of the DS instance. 

# pki \
    -d /etc/dirsrv/slapd-localhost \
    -C /etc/dirsrv/slapd-localhost/pwdfile.txt \
    nss-cert-import \
    --cert ca_signing.crt \
    --trust CT,C,C \
    "CA Signing Cert"
Copy to Clipboard Toggle word wrap

7.5.2.6. Delete DS bootstrap certificates
Copia collegamento

If you already had boostrap DS certificates, delete them: 

$ certutil -F -d /etc/dirsrv/slapd-localhost \
    -f /etc/dirsrv/slapd-localhost/pwdfile.txt \
    -n Server-Cert
$ certutil -D -d /etc/dirsrv/slapd-localhost \
    -f /etc/dirsrv/slapd-localhost/pwdfile.txt \
    -n Self-Signed-CA
Copy to Clipboard Toggle word wrap

7.5.2.7. Import DS server certificate:
Copia collegamento

$ pki \
    -d /etc/dirsrv/slapd-localhost \
    -C /etc/dirsrv/slapd-localhost/pwdfile.txt \
    nss-cert-import \
    --cert ds_server.crt \
    Server-Cert
Copy to Clipboard Toggle word wrap

To verify the DS server certificate: 

$ certutil -L -d /etc/dirsrv/slapd-localhost -n Server-Cert
...
    Certificate Trust Flags:
        SSL Flags:
            User
        Email Flags:
            User
        Object Signing Flags:
            User
Copy to Clipboard Toggle word wrap

7.5.2.8. Enabling SSL Connection
Copia collegamento

This section only applies if you did not enable SSL in your DS earlier.

  1. To enable SSL connection in the DS instance: 

    $ dsconf localhost config replace nsslapd-security=on
    Copy to Clipboard Toggle word wrap

  2. Start the DS instance: 

    $ dsctl localhost start
    Copy to Clipboard Toggle word wrap

  3. Verify the SSL connection: 

    $ LDAPTLS_REQCERT=never ldapsearch \
    -H ldaps://$HOSTNAME:636 \
    -x \
    -D "cn=Directory Manager" \
    -w Secret.123 \
    -b "" \
    -s base
    Copy to Clipboard Toggle word wrap

7.5.2.9. Delete DS bootstrap signing certificate from PKI instance
Copia collegamento

If you are replacing the DS bootstrap certs, as a PKI administrator, stop the PKI then delete the DS bootstrap signing cert from the PKI nssdb as follows. 

$ certutil -F -d /var/lib/pki/pki-tomcat/conf/alias \
    -f /var/lib/pki/pki-tomcat/conf/alias/pwdfile.txt \
    -n ds_signing
Copy to Clipboard Toggle word wrap

Start the PKI.

7.5.2.10. See Also
Copia collegamento

7.5.3. Enabling SSL connection in DS using bootstrap certs
Copia collegamento

If you already have an active trusted CA, and you wish to issue a server cert for your DS, follow this section instead.

Follow this process using pki CLI (run man pki-client) commands to enable SSL connection in DS by creating a bootstrap DS self-signed signing certificate and the bootstrap server certificate issued by it.

This section assumes that a DS instance named localhost already exists, it does not have certificates, and the SSL connection is disabled.

Note: In newer DS versions the certificates are created and the SSL connection is enabled by default, so in general it is not necessary to follow this procedure.

7.5.3.1. Creating DS signing certificate
Copia collegamento

  1. Generate DS signing CSR with the following command: 

    $ pki \
    -d /etc/dirsrv/slapd-localhost \
    -C /etc/dirsrv/slapd-localhost/pwdfile.txt \
    nss-cert-request \
    --subject "CN=DS Signing Certificate" \
    --ext /usr/share/pki/server/certs/ca_signing.conf \
    --csr ds_signing.csr
    Copy to Clipboard Toggle word wrap

  2. Issue DS signing certificate: 

    $ pki \
    -d /etc/dirsrv/slapd-localhost \
    -C /etc/dirsrv/slapd-localhost/pwdfile.txt \
    nss-cert-issue \
    --csr ds_signing.csr \
    --ext /usr/share/pki/server/certs/ca_signing.conf \
    --cert ds_signing.crt
    Copy to Clipboard Toggle word wrap

  3. Import DS signing certificate: 

    $ pki \
    -d /etc/dirsrv/slapd-localhost \
    -C /etc/dirsrv/slapd-localhost/pwdfile.txt \
    nss-cert-import \
    --cert ds_signing.crt \
    --trust CT,C,C \
    Self-Signed-CA
    Copy to Clipboard Toggle word wrap

  4. Verify the DS signing certificate: 

    $ certutil -L -d /etc/dirsrv/slapd-localhost -n Self-Signed-CA
...
    Certificate Trust Flags:
        SSL Flags:
            Valid CA
            Trusted CA
            User
            Trusted Client CA
        Email Flags:
            Valid CA
            Trusted CA
            User
        Object Signing Flags:
            Valid CA
            Trusted CA
            User
    Copy to Clipboard Toggle word wrap

7.5.3.2. Creating DS Server Certificate
Copia collegamento

  1. Generate DS server CSR with the following command: 

    $ pki \
    -d /etc/dirsrv/slapd-localhost \
    -C /etc/dirsrv/slapd-localhost/pwdfile.txt \
    nss-cert-request \
    --subject "CN=$HOSTNAME" \
    --subjectAltName "critical, DNS:$HOSTNAME" \
    --ext /usr/share/pki/server/certs/sslserver.conf \
    --csr ds_server.csr
    Copy to Clipboard Toggle word wrap

  2. Issue DS server certificate: 

    $ pki \
    -d /etc/dirsrv/slapd-localhost \
    -C /etc/dirsrv/slapd-localhost/pwdfile.txt \
    nss-cert-issue \
    --issuer Self-Signed-CA \
    --csr ds_server.csr \
    --ext /usr/share/pki/server/certs/sslserver.conf \
    --cert ds_server.crt
    Copy to Clipboard Toggle word wrap

  3. Import DS server certificate: 

    $ pki \
    -d /etc/dirsrv/slapd-localhost \
    -C /etc/dirsrv/slapd-localhost/pwdfile.txt \
    nss-cert-import \
    --cert ds_server.crt \
    Server-Cert
    Copy to Clipboard Toggle word wrap

  4. Verify the DS server certificate: 

    $ certutil -L -d /etc/dirsrv/slapd-localhost -n Server-Cert
...
    Certificate Trust Flags:
        SSL Flags:
            User
        Email Flags:
            User
        Object Signing Flags:
            User
    Copy to Clipboard Toggle word wrap

7.5.3.3. Enabling SSL Connection
Copia collegamento

  1. To enable SSL connection in the DS instance: 

    $ dsconf localhost config replace nsslapd-security=on
    Copy to Clipboard Toggle word wrap

  2. Restart the DS instance: 

    $ dsctl localhost restart
    Copy to Clipboard Toggle word wrap

  3. Verify the SSL connection: 

    $ LDAPTLS_REQCERT=never ldapsearch \
    -H ldaps://$HOSTNAME:636 \
    -x \
    -D "cn=Directory Manager" \
    -w Secret.123 \
    -b "" \
    -s base
    Copy to Clipboard Toggle word wrap

7.5.3.4. See Also
Copia collegamento

7.5.4. Enabling TLS mutual authentication from CS to DS
Copia collegamento

Note

This section requires a root CA installed and running. If you used a bootstrap self-signed LDAP server certificate, replace it first by following Section 7.5.2, “Getting DS certificate issued by actual CA”. These steps are to be performed once the installation is complete.

If you choose to enable TLS client authentication, once the basic TLS server authentication has been configured and running when installing the CS subsystem, we can now double back and attempt to enable client authentication from a given subsystem to the LDAP server.

There are two parts to setting up client authentication. The first part is configuring the LDAP directory to require TLS mutual authentication. This procedure is detailed in Using certificate-based client authentication in the Red Hat Directory Server Administration Guide.

Note the following:

  • pkispawn already automatically created a pkidbuser on its internal Directory Server, where the CS instance’s "subsystem certificate" (for example subsystemCert cert-pki-ca) that is used for outbound TLS client authentication is stored in the user entry. Therefore, there is no need to create another LDAP user or another certificate for the TLS client-authentication.

  • When creating content for /etc/dirsrv/slapd-instance_name/certmap.conf, use the following format: 

    certmap rhcs <certificate issuer DN>
		rhcs:CmapLdapAttr seeAlso
		rhcs:verifyCert on
    Copy to Clipboard Toggle word wrap

    For example 

    certmap rhcs CN=CA Signing Certificate,OU=pki-tomcat-ca,O=pki-tomcat-ca-SD
		rhcs:CmapLdapAttr seeAlso
		rhcs:verifyCert on
    Copy to Clipboard Toggle word wrap
  • After configuring, restart the Directory Server.

The second part is adding configuration to the Red Hat Certificate System instance so that it knows which port and certificate is to be used to communicate with its internal LDAP server using TLS mutual authentication. This involves editing the RHCS instance’s CS.cfg file located at <instance directory>/<subsystem type>/conf/CS.cfg. For example /var/lib/pki/ instance_name/ca/conf/CS.cfg

In the CS.cfg, please add the RHCS instance’s subsystem certificate nickname to internaldb.ldapauth.clientCertNickname, and remove the two unused entries: 

internaldb.ldapauth.bindDN
		internaldb.ldapauth.bindPWPrompt
Copy to Clipboard Toggle word wrap

As shown below: 

internaldb._000=##
		internaldb._001=## Internal Database
		internaldb._002=##
		internaldb.basedn=o=pki-tomcat-ca-SD
		internaldb.database=pki-tomcat-ca
		internaldb.maxConns=15
		internaldb.minConns=3
		internaldb.ldapauth.authtype=SslClientAuth
		internaldb.ldapauth.clientCertNickname=HSM-A:subsystemCert pki-tomcat-ca
		internaldb.ldapconn.host=example.com
		internaldb.ldapconn.port=11636
		internaldb.ldapconn.secureConn=true
Copy to Clipboard Toggle word wrap

Restart the CS instance at the end of the post-installation step.

Note

The internaldb.basedn and internaldb.database parameters must be configured to match your specific LDAP instance.

For compliance, internaldb.ldapauth.authtype=SslClientAuth and internaldb.ldapconn.secureConn=true must be set, and the value of the internaldb.ldapauth.clientCertNickname must match the nickname of the TLS client certificate to authenticate against LDAP with in the NSS DB.

All other values can be changed as desired to reflect your environment or availability needs.

7.5.5. Configuring session timeout
Copia collegamento

Various timeout configurations exist on the system that could affect how long a TLS session is allowed to remain idle before termination. For details, see Section 13.4.2, “Session timeout”.

7.5.6. CRL or certificate publishing
Copia collegamento

CRL publishing is critical in providing OCSP service. Certificate publishing is optional but often desired by sites. For details, see the Publishing Certificates and CRLs section in the Red Hat Certificate System Administration Guide.

7.5.7. Configuring certificate enrollment profiles (CA)
Copia collegamento

RHCS has a rich profile framework that allows for customization of the certificate enrollment profiles. It is very common for a site to enable/disable default profiles that come with the system, or modify existing profiles, or create their own profiles. For details, see Chapter 15, Configuring certificate profiles.

7.5.8. CA’s enrollment profile configuration with CRL Distribution Points
Copia collegamento

Enable the desired profile(s) to include the CRL Distribution Points. These are the profiles corresponding to the configuration in the sections above.

  1. Open the caCMCserverCertWithCRLDP.cfg profile (for enrollments with RSA keys) in the /var/lib/pki/<ca instance directory/ca/profiles/ca/ directory and update as follows: 

    vi /var/lib/pki/rhcs10-RSA-RootCA/ca/profiles/ca/caCMCserverCertWithCRLDP.cfg
…
enable=true
…
policyset.serverCertSet.10.default.params.crlDistPointsPointName_0=http://rhcs10.example.com:8085/crl/ServerCertCRL.crl
…
    Copy to Clipboard Toggle word wrap

  2. Open the caCMCECserverCertWithCRLDP.cfg (for enrollments with ECC keys) in the /var/lib/pki/<ca instance directory/ca/profiles/ca/ directory and update as follows: 

    vi /var/lib/pki/rhcs10-ECC-RootCA/ca/profiles/ca/caCMCECserverCertWithCRLDP.cfg
…
enable=true
…
policyset.serverCertSet.10.default.params.crlDistPointsPointName_0=http://rhcs10.example.com:20085/crl/ServerCertCRL.crl
…
    Copy to Clipboard Toggle word wrap

  3. Set user:group ownership: 

    chown -R pkiuser:pkiuser  /var/lib/pki/rhcs10-RSA-RootCA/ca/profiles/ca/caCMCserverCertWithCRLDP.cfg
chown -R pkiuser:pkiuser  /var/lib/pki/rhcs10-RSA-RootCA/ca/profiles/ca/caCMCECserverCertWithCRLDP.cfg
    Copy to Clipboard Toggle word wrap

  4. Register a new profile in the CA’s CS.cfg:

    1. Add the following lines for each profile: 

      profile.caCMCserverCertWithCRLDP.class_id=caEnrollImpl
profile.caCMCserverCertWithCRLDP.config=/var/lib/pki/rhcs10-RSA-RootCA/ca/profiles/ca/caCMCserverCertWithCRLDP.cfg

profile.caCMCECserverCertWithCRLDP.class_id=caEnrollImpl
profile.caCMCECserverCertWithCRLDP.config=/var/lib/pki/rhcs10-RSA-RootCA/ca/profiles/ca/caCMCECserverCertWithCRLDP.cfg
      Copy to Clipboard Toggle word wrap

    2. Edit the profile.list entry to add the two new profiles. For example:: 

      profile.list=caCMCserverCertWithCRLDP,caCMCECserverCertWithCRLDP,acmeServerCert,caCMCserverCert,caCMCECserverCert, …
      Copy to Clipboard Toggle word wrap

7.5.9. Configure support for CRL Distribution Point
Copia collegamento

Note

For more information on CRL Distribution Points, why they are needed and where they are best suited, see Enabling automatic revocation checking on the CA.

To configure support for CRL Distribution Points, as an example, we describe how to set up a file-based CRL publisher as well as the partitioning of the CRL. You will also learn how to enable a certificate enrollment profile to issue certificates with the CRL Distribution Point extension. Finally, we describe how to replace the temporary Server-Cert of the CA’s LDAP server with a certificate issued from the CRL Distribution Point profiles.

Before proceeding with the following changes, stop the RootCA instance: 

pki-server stop rhcs10-RSA-RootCA
Copy to Clipboard Toggle word wrap

7.5.9.1. CA setup to support Server Cert CRL File Publishing
Copia collegamento

Note

Before proceeding, save a copy of the configuration file before editing: 

cp /var/lib/pki/rhcs10-RSA-RootCA/ca/conf/CS.cfg  /var/lib/pki/rhcs10-RSA-RootCA/ca/conf/CS.cfg.bak.<date>
Copy to Clipboard Toggle word wrap
7.5.9.1.1. Set up the file-based publisher: crlFilePublisher
Copia collegamento

The configuration in this section creates a file-based CRL publisher called crlFilePublisher. When set up correctly, the CRL is stored under directory /var/lib/pki/rhcs10-RSA-RootCA/crl in DER format.

  1. Create the CRL directory for publishing the file-based partitioned CRL: 

    mkdir /var/lib/pki/rhcs10-RSA-RootCA/crl
chown pkiuser.pkiuser /var/lib/pki/rhcs10-RSA-RootCA/crl
    Copy to Clipboard Toggle word wrap

  2. Add the following to the CA’s CS.cfg: 

    ca.publish.publisher.instance.crlFilePublisher.Filename.b64=false
ca.publish.publisher.instance.crlFilePublisher.Filename.der=true
ca.publish.publisher.instance.crlFilePublisher.crlLinkExt=crl
ca.publish.publisher.instance.crlFilePublisher.directory=/var/lib/pki/rhcs10-RSA-RootCA/crl
ca.publish.publisher.instance.crlFilePublisher.latestCrlLink=true
ca.publish.publisher.instance.crlFilePublisher.maxAge=0
ca.publish.publisher.instance.crlFilePublisher.maxFullCRLs=0
ca.publish.publisher.instance.crlFilePublisher.pluginName=FileBasedPublisher
ca.publish.publisher.instance.crlFilePublisher.timeStamp=LocalTime
ca.publish.publisher.instance.crlFilePublisher.zipCRLs=false
ca.publish.publisher.instance.crlFilePublisher.zipLevel=9
    Copy to Clipboard Toggle word wrap
7.5.9.1.2. Set up the file-based publishing rule: FileCrlRule
Copia collegamento

The configuration in this section creates a file-based publishing rule called FileCrlRule. The predicate specifies the issuing point to a partitioned CRL called ServerCertCRL(defined in Set up the CRL-partitioning for certificates issued via a profile.

  • Add the following to the CA’s CS.cfg: 
ca.publish.rule.instance.FileCrlRule.enable=true
ca.publish.rule.instance.FileCrlRule.mapper=NoMap
ca.publish.rule.instance.FileCrlRule.pluginName=Rule
ca.publish.rule.instance.FileCrlRule.predicate=issuingPointId==ServerCertCRL
ca.publish.rule.instance.FileCrlRule.publisher=crlFilePublisher
ca.publish.rule.instance.FileCrlRule.type=crl
Copy to Clipboard Toggle word wrap
7.5.9.1.3. Modify the LDAP-based publishing rule: LdapCrlRule
Copia collegamento

This configuration explicitly sets the LdapCrlRule predicate to the master (full) CRL. The master CRL is continuously supplied to the OCSP responder for proper OCSP support.

Modify the following in the CA’s CS.cfg: 

ca.publish.rule.instance.LdapCrlRule.predicate=issuingPointId==MasterCRL
Copy to Clipboard Toggle word wrap
7.5.9.1.4. Set up the CRL-partitioning for certificates issued via a profile
Copia collegamento

The configuration in this section demonstrates how to partition a CRL to a smaller subset that could be utilized in the FileCrlRule defined above. The CRL is partitioned by the certificate enrollment profile(s) specified in the profileList parameter. A comma-separated list can be used for multiple profiles (for example, caCMCserverCertWithCRLDP.cfg and caCMCECserverCertWithCRLDP.cfg).

Add the following to the CA’s CS.cfg: 

ca.crl.ServerCertCRL.allowExtensions=true
ca.crl.ServerCertCRL.alwaysUpdate=false
ca.crl.ServerCertCRL.autoUpdateInterval=240
ca.crl.ServerCertCRL.caCertsOnly=false
ca.crl.ServerCertCRL.cacheUpdateInterval=15
ca.crl.ServerCertCRL.class=com.netscape.ca.CRLIssuingPoint
ca.crl.ServerCertCRL.dailyUpdates=1:00
ca.crl.ServerCertCRL.description=CA's Certificate Revocation List containing certificates issued via the caCMCserverCertWithCRLDP and caCMCECserverCertWithCRLDP enrollment profile
ca.crl.ServerCertCRL.enable=true
ca.crl.ServerCertCRL.enableCRLCache=false
ca.crl.ServerCertCRL.enableCRLUpdates=true
ca.crl.ServerCertCRL.enableCacheRecovery=true
ca.crl.ServerCertCRL.enableCacheTesting=false
ca.crl.ServerCertCRL.enableDailyUpdates=true
ca.crl.ServerCertCRL.enableUpdateInterval=true
ca.crl.ServerCertCRL.extendedNextUpdate=true
ca.crl.ServerCertCRL.extension.AuthorityInformationAccess.accessLocation0=""
ca.crl.ServerCertCRL.extension.AuthorityInformationAccess.accessLocationType0=URI
ca.crl.ServerCertCRL.extension.AuthorityInformationAccess.accessMethod0=caIssuers
ca.crl.ServerCertCRL.extension.AuthorityInformationAccess.class=com.netscape.cms.crl.CMSAuthInfoAccessExtension
ca.crl.ServerCertCRL.extension.AuthorityInformationAccess.critical=false
ca.crl.ServerCertCRL.extension.AuthorityInformationAccess.enable=false
ca.crl.ServerCertCRL.extension.AuthorityInformationAccess.numberOfAccessDescriptions=1
ca.crl.ServerCertCRL.extension.AuthorityInformationAccess.type=CRLExtension
ca.crl.ServerCertCRL.extension.AuthorityKeyIdentifier.class=com.netscape.cms.crl.CMSAuthorityKeyIdentifierExtension
ca.crl.ServerCertCRL.extension.AuthorityKeyIdentifier.critical=false
ca.crl.ServerCertCRL.extension.AuthorityKeyIdentifier.enable=false
ca.crl.ServerCertCRL.extension.AuthorityKeyIdentifier.type=CRLExtension
ca.crl.ServerCertCRL.extension.CRLNumber.class=com.netscape.cms.crl.CMSCRLNumberExtension
ca.crl.ServerCertCRL.extension.CRLNumber.critical=false
ca.crl.ServerCertCRL.extension.CRLNumber.enable=true
ca.crl.ServerCertCRL.extension.CRLNumber.type=CRLExtension
ca.crl.ServerCertCRL.extension.CRLReason.class=com.netscape.cms.crl.CMSCRLReasonExtension
ca.crl.ServerCertCRL.extension.CRLReason.critical=false
ca.crl.ServerCertCRL.extension.CRLReason.enable=true
ca.crl.ServerCertCRL.extension.CRLReason.type=CRLEntryExtension
ca.crl.ServerCertCRL.extension.DeltaCRLIndicator.class=com.netscape.cms.crl.CMSDeltaCRLIndicatorExtension
ca.crl.ServerCertCRL.extension.DeltaCRLIndicator.critical=true
ca.crl.ServerCertCRL.extension.DeltaCRLIndicator.enable=false
ca.crl.ServerCertCRL.extension.DeltaCRLIndicator.type=CRLExtension
ca.crl.ServerCertCRL.extension.FreshestCRL.class=com.netscape.cms.crl.CMSFreshestCRLExtension
ca.crl.ServerCertCRL.extension.FreshestCRL.critical=false
ca.crl.ServerCertCRL.extension.FreshestCRL.enable=false
ca.crl.ServerCertCRL.extension.FreshestCRL.numPoints=0
ca.crl.ServerCertCRL.extension.FreshestCRL.pointName0=""
ca.crl.ServerCertCRL.extension.FreshestCRL.pointType0=""
ca.crl.ServerCertCRL.extension.FreshestCRL.type=CRLExtension
ca.crl.ServerCertCRL.extension.InvalidityDate.class=com.netscape.cms.crl.CMSInvalidityDateExtension
ca.crl.ServerCertCRL.extension.InvalidityDate.critical=false
ca.crl.ServerCertCRL.extension.InvalidityDate.enable=true
ca.crl.ServerCertCRL.extension.InvalidityDate.type=CRLEntryExtension
ca.crl.ServerCertCRL.extension.IssuerAlternativeName.class=com.netscape.cms.crl.CMSIssuerAlternativeNameExtension
ca.crl.ServerCertCRL.extension.IssuerAlternativeName.critical=false
ca.crl.ServerCertCRL.extension.IssuerAlternativeName.enable=false
ca.crl.ServerCertCRL.extension.IssuerAlternativeName.name0=""
ca.crl.ServerCertCRL.extension.IssuerAlternativeName.nameType0=""
ca.crl.ServerCertCRL.extension.IssuerAlternativeName.numNames=0
ca.crl.ServerCertCRL.extension.IssuerAlternativeName.type=CRLExtension
ca.crl.ServerCertCRL.extension.IssuingDistributionPoint.class=com.netscape.cms.crl.CMSIssuingDistributionPointExtension
ca.crl.ServerCertCRL.extension.IssuingDistributionPoint.critical=true
ca.crl.ServerCertCRL.extension.IssuingDistributionPoint.enable=false
ca.crl.ServerCertCRL.extension.IssuingDistributionPoint.indirectCRL=false
ca.crl.ServerCertCRL.extension.IssuingDistributionPoint.onlyContainsCACerts=false
ca.crl.ServerCertCRL.extension.IssuingDistributionPoint.onlyContainsUserCerts=false
ca.crl.ServerCertCRL.extension.IssuingDistributionPoint.onlySomeReasons=""
ca.crl.ServerCertCRL.extension.IssuingDistributionPoint.pointName=
ca.crl.ServerCertCRL.extension.IssuingDistributionPoint.pointType=
ca.crl.ServerCertCRL.extension.IssuingDistributionPoint.type=CRLExtension
ca.crl.ServerCertCRL.includeExpiredCerts=false
ca.crl.ServerCertCRL.includeExpiredCertsOneExtraTime=false
ca.crl.ServerCertCRL.minUpdateInterval=0
ca.crl.ServerCertCRL.nextAsThisUpdateExtension=0
ca.crl.ServerCertCRL.nextUpdateGracePeriod=0
ca.crl.ServerCertCRL.profileCertsOnly=true
ca.crl.ServerCertCRL.profileList=caCMCserverCertWithCRLDP,caCMCECserverCertWithCRLDP
ca.crl.ServerCertCRL.publishOnStart=false
ca.crl.ServerCertCRL.saveMemory=false
ca.crl.ServerCertCRL.signingAlgorithm=SHA256withRSA
ca.crl.ServerCertCRL.updateSchema=1
Copy to Clipboard Toggle word wrap
Note

For an ECC CA, set the following to SHA512withEC: 

ca.crl.ServerCertCRL.signingAlgorithm=SHA512withEC
Copy to Clipboard Toggle word wrap

7.5.9.2. Set up CRL HTTP service in the CA
Copia collegamento

The CRL served by the CRL Distribution Point is published to a file (see sections above). This file is served by a non-SSL Tomcat service that we are adding to the CA’s server.xml as shown below:

  1. Add the following CRL service before the Catalina service in the file /var/lib/pki/rhcs10-RSA-RootCA/conf/server.xml: 

    <Service name="CRL">
  <Connector port="8085" protocol="HTTP/1.1" connectionTimeout="80000"
   maxParameterCount="1000" name="Unsecure" maxHttpHeaderSize="8192"
   acceptCount="100" maxThreads="15" minSpareThreads="25"
   enableLookups="false" disableUploadTimeout="true"/>
  <Engine name="CRL" defaultHost="localhost">
    <Host name="localhost" appBase="webapps" unpackWARs="true" autoDeploy="true">
      <Valve className="org.apache.catalina.valves.AccessLogValve" directory="logs"
       prefix="localhost_crl_access_log" suffix=".txt" pattern="common"/>
    </Host>
  </Engine>
</Service>
    Copy to Clipboard Toggle word wrap

  2. In the above CRL service, choose a connector port number that has not been used. For example, if the root CA’s HTTP port is 8080, then pick 8085. Ensure that the port is added for SELinux and firewall, for example: 

    semanage port -a -t http_port_t -p tcp 8085
firewall-cmd --permanent --add-port=8085/tcp
firewall-cmd --reload
    Copy to Clipboard Toggle word wrap
    Note

    If your selected port has been pre-assigned with another SELinux context, you will see an error message that looks like the following: 

    ValueError: Port tcp/8085 already defined
    Copy to Clipboard Toggle word wrap

    You can also search and find out whether the CRL HTTP port is pre-assigned by using the following command: 

    # semanage port -l | grep <port>
    Copy to Clipboard Toggle word wrap

    We recommend that you select another port. However, if you wish to use the same port, you could do the following: 

    # semanage port -m -t http_port_t -p tcp 8085
    Copy to Clipboard Toggle word wrap

  3. When the server is restarted, the directory CRL/localhost is created under the CA’s conf directory if it does not exist. However, to prepare for the addition of the crl.xml file, do the following: 

    mkdir -p  /var/lib/pki/rhcs10-RSA-RootCA/conf/CRL/localhost
chown -R pkiuser:pkiuser /var/lib/pki/rhcs10-RSA-RootCA/conf/CRL/localhost
    Copy to Clipboard Toggle word wrap

  4. Create a crl.xml file under /var/lib/pki/rhcs10-RSA-RootCA/conf/CRL/localhost, and add the following content: 

    <Context docBase="/var/lib/pki/rhcs10-RSA-RootCA/crl">
 <Resources allowLinking="true" cachingAllowed="false" />
</Context>
    Copy to Clipboard Toggle word wrap

  5. Set the user:group ownership for the crl.xml file: 

    chown pkiuser:pkiuser  /var/lib/pki/rhcs10-RSA-RootCA/conf/CRL/localhost/crl.xml
    Copy to Clipboard Toggle word wrap
Note

The CRL Distribution Point set in the enrollment profile looks like this (see next section for full example): http://rhcs10.example.com:8085/crl/ServerCertCRL.crl

Important

File-based CRL publisher is only recommended for smaller CRLs with less frequently issued or revoked certificates. It is only recommended if necessary, such as in the case of CA startup setup described in this section.

7.5.9.3. CA’s enrollment profile configuration with CRL Distribution Points
Copia collegamento

Enable the desired profile(s) to include the CRL Distribution Points. These are the profiles corresponding to the configuration in the sections above.

  1. Open the caCMCserverCertWithCRLDP.cfg profile (for enrollments with RSA keys) in the /var/lib/pki/<ca instance directory/ca/profiles/ca/ directory and update as follows: 

    # vi /var/lib/pki/rhcs10-RSA-RootCA/ca/profiles/ca/caCMCserverCertWithCRLDP.cfg
…
enable=true
…
policyset.serverCertSet.10.default.params.crlDistPointsPointName_0=http://rhcs10.example.com:8085/crl/ServerCertCRL.crl
…
    Copy to Clipboard Toggle word wrap

  2. Open the caCMCECserverCertWithCRLDP.cfg (for enrollments with ECC keys) in the /var/lib/pki/<ca instance directory/ca/profiles/ca/ directory and update as follows: 

    # vi /var/lib/pki/rhcs10-ECC-RootCA/ca/profiles/ca/caCMCECserverCertWithCRLDP.cfg
…
enable=true
…
policyset.serverCertSet.10.default.params.crlDistPointsPointName_0=http://rhcs10.example.com:20085/crl/ServerCertCRL.crl
…
    Copy to Clipboard Toggle word wrap

  3. Set user:group ownership: 

    chown -R pkiuser:pkiuser  /var/lib/pki/rhcs10-RSA-RootCA/ca/profiles/ca/caCMCserverCertWithCRLDP.cfg
chown -R pkiuser:pkiuser  /var/lib/pki/rhcs10-RSA-RootCA/ca/profiles/ca/caCMCECserverCertWithCRLDP.cfg
    Copy to Clipboard Toggle word wrap

  4. Register a new profile in the CA’s CS.cfg:

    1. Add the following lines for each profile: 

      profile.caCMCserverCertWithCRLDP.class_id=caEnrollImpl
profile.caCMCserverCertWithCRLDP.config=/var/lib/pki/rhcs10-RSA-RootCA/ca/profiles/ca/caCMCserverCertWithCRLDP.cfg

profile.caCMCECserverCertWithCRLDP.class_id=caEnrollImpl
profile.caCMCECserverCertWithCRLDP.config=/var/lib/pki/rhcs10-RSA-RootCA/ca/profiles/ca/caCMCECserverCertWithCRLDP.cfg
      Copy to Clipboard Toggle word wrap

    2. Edit the profile.list entry to add the two new profiles. For example:: 

      profile.list=caCMCserverCertWithCRLDP,caCMCECserverCertWithCRLDP,acmeServerCert,caCMCserverCert,caCMCECserverCert, …
      Copy to Clipboard Toggle word wrap

7.5.9.4. Set up for more immediate CRL update
Copia collegamento

Since server certs do not often get revoked, it is reasonable to update the CRL as soon as there is a revocation. Edit the CA’s CS.cfg: 

ca.crl.ServerCertCRL.alwaysUpdate=true
Copy to Clipboard Toggle word wrap

7.5.9.5. Restart the CA once the CA’s configuration is updated
Copia collegamento

Once configuration is complete, restart the CA: 

pki-server restart rhcs10-RSA-RootCA
Copy to Clipboard Toggle word wrap
Note

To verify that the CRL Distribution Point is working, follow Verifying the CRL Distribution Point.

7.5.10. Verifying the CRL Distribution Point
Copia collegamento

If you have replaced the server-cert of the root CA’s directory server using the profile caCMCserverCertWithCRLDP, this effectively triggers the CRL distribution point to be referenced by the CA during startup when initiating a connection with its internal directory server.

This section provides a rudimentary method to verify the CRL Distribution Point setup in the CA (see Configure support for CRL Distribution Point):

Prior to verification, you need to enable revocation checks as follows:

  1. To enable certificate revocation checks, in the respective /var/lib/pki/rhcs10-RSA-RootCA/conf/server.xml file:

    1. Set enableOCSP or enableRevocationCheck to true: 

      enableOCSP=true
or
enableRevocationCheck=true
      Copy to Clipboard Toggle word wrap

    2. Additionally, remove these two parameters and their assigned values: 

      ocspResponderURL
ocspResponderCertNickname
      Copy to Clipboard Toggle word wrap

  2. Disable the legacy revocation check method by editing the CA’s CS.cfg file and setting the following to false: 

    auths.revocationChecking.enabled=false
    Copy to Clipboard Toggle word wrap

  3. Start the RootCA instance: 

    pki-server start rhcs10-RSA-RootCA
    Copy to Clipboard Toggle word wrap

7.5.10.1. Verification of the CRL Distribution Point
Copia collegamento

To verify the CRL Distribution Point:

  1. Check the publishing of the file-based CRL: 

    # ls -l /var/lib/pki/rhcs10-RSA-RootCA/crl
total 8
-rw-r--r--. 1 pkiuser pkiuser 574 Jun 20 18:08 ServerCertCRL-20240620-180859.der
-rw-r--r--. 1 pkiuser pkiuser 613 Jun 20 18:09 ServerCertCRL-20240620-180938.der
lrwxrwxrwx. 1 pkiuser pkiuser  68 Jun 20 18:09 ServerCertCRL.crl -> /var/lib/pki/rhcs10-RSA-RootCA/crl/ServerCertCRL-20240620-180938.der
    Copy to Clipboard Toggle word wrap

  2. Display and verify the content of the CRL 

    # BtoA /var/lib/pki/rhcs10-RSA-RootCA/crl/ServerCertCRL.crl /var/lib/pki/rhcs10-RSA-RootCA/crl/ServerCertCRL.bin
# PrettyPrintCrl /var/lib/pki/rhcs10-RSA-RootCA/crl/ServerCertCRL.bin
Certificate Revocation List:
        Data:
            Version:  v2
            Signature Algorithm: SHA256withRSA - 1.2.840.113549.1.1.11
            Issuer: CN=CA Signing Certificate,OU=rhcs10-RSA-RootCA,O=Example-rhcs10-RSA-RootCA
            This Update: Thursday, June 20, 2024 6:09:38 PM EDT America/New_York
            Next Update: Thursday, June 20, 2024 9:00:00 PM EDT America/New_York
            Revoked Certificates:
                Serial Number: 0xF6FDEF3
                Revocation Date: Thursday, June 20, 2024 6:09:38 PM EDT America/New_York
                Extensions:
                    Identifier: Revocation Reason - 2.5.29.21
                        Critical: no
                        Reason: Certificate_Hold
        Extensions:
            Identifier: CRL Number - 2.5.29.20
                Critical: no
                Number: 21
        Signature:
            Algorithm: SHA256withRSA - 1.2.840.113549.1.1.11
            Signature:
                69:38:47:5D:E4:50:17:C5:6C:60:3F:1B:D8:B4:62:4D:
                8B:11:FC:31:E4:26:6B:07:B6:BB:2C:7E:48:10:F4:DD:
                0A:67:17:CB:DF:4E:1A:50:BE:4F:8F:61:B4:91:AE:DA:
                E5:58:D5:FE:54:D9:94:B3:38:E1:B6:2C:19:C4:93:54:
                D5:5E:8B:61:4F:89:52:5A:F7:F5:1B:2F:59:19:AD:23:
                1F:6F:3C:93:17:F3:1A:1C:0B:9A:D2:8F:01:76:08:6E:
                DA:DD:6F:2D:75:54:D3:D4:40:9A:2B:5D:8B:D5:BB:8B:
                AF:89:E4:13:A7:F1:8A:AF:0A:72:26:E3:3D:FE:B3:90:
                2B:F7:88:57:E9:8B:E7:82:B6:D3:F3:80:CD:F7:87:77:
                69:AF:39:90:5E:46:9C:C2:C4:FA:44:01:77:6D:8F:2D:
                5A:BD:B9:39:3F:E4:99:E7:F9:FD:2D:CD:FA:87:C1:42:
                A4:D0:3B:87:0B:28:30:2D:2A:68:F2:68:7C:00:A8:4B:
                AC:38:49:5A:03:D1:B2:CE:45:D8:C1:6A:3F:42:F0:04:
                F6:CC:43:83:E8:19:41:6F:0A:64:95:C3:57:8F:54:53:
                31:40:58:D4:CD:29:0E:0A:D9:15:E9:08:0C:B8:74:F4:
                82:B4:4E:51:8F:1C:86:A3:2E:BF:BB:F8:4A:DD:17:07:
                37:27:0F:8B:5C:5E:75:28:B4:0C:DE:F2:38:B9:0E:AE:
                73:06:A1:3D:36:85:54:74:E6:C3:4B:78:80:9F:76:42:
                85:D2:94:FF:A0:0C:7D:23:61:AB:4E:7A:D0:5B:EC:CF:
                91:E9:CB:80:C4:A1:EB:86:FB:D8:E6:65:AC:48:D0:9F:
                8B:95:07:A9:CA:D7:34:A9:7B:32:25:1E:F4:21:A8:06:
                44:73:B4:99:79:B5:69:77:D1:18:3B:40:C5:20:AF:5C:
                8E:D0:65:AE:34:CF:1F:90:82:97:33:7F:90:E6:D9:BC:
                49:8F:BE:59:22:FE:09:E5:FA:F2:5F:31:77:6D:F8:99
    Copy to Clipboard Toggle word wrap
Important

Do not remove the CRL file (soft link file ServerCertCRL.crl, and its associated der file).

If you encounter a situation where the CRL file is missing or has been accidentally deleted from /var/lib/pki/rhcs10-RSA-RootCA/crl/, preventing the CA from starting, follow the steps below to regenerate the CRL file:

  1. Stop the CA service. 

    pki-server stop rhcs10-RSA-RootCA
    Copy to Clipboard Toggle word wrap
  2. Set the enableRevocationCheck or enableOCSP parameter to false (if it is currently set to true) in CA’s server.xml.
  3. Set the ca.crl.ServerCertCRL.publishOnStart= parameter to true in CA’s CS.cfg.

  4. Start the CA service to regenerate the missing CRL file: 

    pki-server start rhcs10-RSA-RootCA
    Copy to Clipboard Toggle word wrap
  5. After the CRL file has been recovered, stop the CA service once again.
  6. Revert the ca.crl.ServerCertCRL.publishOnStart= parameter to false in CA’s CS.cfg.
  7. Set the enableRevocationCheck or enableOCSP parameter to true in CA’s server.xml.
  8. Start the CA service again to apply the changes.

By following these steps, you successfully recover the missing CRL file and ensure the CA can start correctly.

7.5.11. Enabling access banner
Copia collegamento

To enable user interface banners, refer to Section 13.7.1, “Enabling an access banner”.

7.5.12. Enabling the watchdog service
Copia collegamento

The watchdog (nuxwdog) service provides secure system password management. For details, see Section 13.3.2.1, “Enabling the watchdog service”.

7.5.13. Configuration for CMc enrollment and revocation (CA)
Copia collegamento

Certificate enrollments and revocation can be done via CMC.

7.5.14. TLS client-authentication for the Java console
Copia collegamento

To require Certificate System administrators to present a user TLS client certificate when logging into the Java console, see Section 13.2.3.14, “Setting requirement for pkiconsole to use TLS client certificate authentication”.

Note

pkiconsole is being deprecated.

7.5.15. Creating a role user
Copia collegamento

Create real role users so that you can remove the bootstrap user.

To create users and assign them to different privileged roles to manage Certificate System, see Chapter 18, Creating a role user.

7.5.16. Removing the bootstrap user
Copia collegamento

Once the real role users are created, the bootstrap user that was created automatically during the installation is not needed anymore. To delete this account, see Chapter 19, Deleting the Bootstrap User after making sure you created a new administrator account assigned to an individual person.

7.5.17. Disabling multi-role support
Copia collegamento

To disable the multi-role support once the bootstrap user is removed, see Section 19.1, “Disabling multi-roles support”.

7.5.18. KRA configurations
Copia collegamento

To set up a requirement for multiple KRA agents to approve key recovery, see the Configuring agent-approved key recovery in the command line section in the Red Hat Certificate System Administration Guide.

7.5.18.2. Configuring KRA encryption settings
Copia collegamento

To configure key encryption/wrapping algorithms, see Section 16.2, “Encryption of KRA operations”.

7.5.19. Setting up users to use user interfaces
Copia collegamento

Before a user could use an approved user interface, initialization needs to be performed. Users (administrative roles or otherwise) are required to setup their clients for accessing the user interface. See the Client NSS database initialization section in the Red Hat Certificate System Administration Guide.

7.5.20. Enabling signed audit logging
Copia collegamento

By default, audit logging is enabled upon installation. However, log signing needs to be enabled manually after installation.

To display the current audit logging configuration: 

# pki-server subsystem-audit-config-show
  Enabled: True
  Log File: audit_signing_log_file
  Buffer Size (bytes): 512
  Flush Interval (seconds): 5
  Max File Size (bytes): 2000
  Rollover Interval (seconds): 2592000
  Expiration Time (seconds): 0
  Log Signing: False
  Signing Certificate: audit_signing_certificate
Copy to Clipboard Toggle word wrap

To enable signed audit logging:

  1. Use the pki-server utility to set the --logSigning option to true: 

    # pki-server subsystem-audit-config-mod --logSigning True
  ...
  Log Signing: True
  ...
    Copy to Clipboard Toggle word wrap

  2. Restart the instance: 

    # systemctl restart pki-tomcatd@instance_name.service
    Copy to Clipboard Toggle word wrap

    OR (if using nuxwdog watchdog) 

    # systemctl start pki-tomcatd-nuxwdog@instance_name.service
    Copy to Clipboard Toggle word wrap

7.5.21. Update the ciphers list
Copia collegamento

Red Hat Certificate System allows to set restrictions on acceptable ciphers when acting as a server or as a client. These cipher controls are configured at different locations.

An RHCS instance is acting as a server when it is accepting requests from another entity. For example:

  • When a RHCS cli talks to a CA for certificate enrollment (in this case, the CA is the server)
  • When a RHCS administrator uses the pkiconsole to talk to a CA (in this case, the CA is the server)
  • When a CA talks to a KRA for key archival (in this case, the KRA is the server, and the CA is the client)

An RHCS instance is acting as a client when it attempts to reach out to another server. For example:

  • When a CA talks to a KRA for key archival (in this case, the CA is the client while the KRA is the server)
  • When a CA talks to its internal LDAP database (in this case, the CA is the client while Directory Server is the server)

The following sections provide instructions on how to configure the ciphers for these different scenarios.

7.5.21.1. Configuring the ciphers for a CS instance acting as a server
Copia collegamento

The desired set of ciphers for a given instance is defined by the SSLHostConfig element in the <CS instance directory>/conf/server.xml file.

Follow the instructions below to configure each CS instance.

Important

Back up the original server.xml file before editing, for example to server.xml.orig.

  1. Edit the server.xml file, navigate to the main SSL port’s Connector declaration and find the SSLHostConfig element.

  2. Modify the SSLHostConfig element with the following configuration: 

    <SSLHostConfig sslProtocol="TLS" protocols="TLSv1.2" certificateVerification="optional" ciphers="ECDHE-RSA-AES128-GCM-SHA256:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-RSA-AES128-SHA256:ECDHE-RSA-AES256-SHA384">
    Copy to Clipboard Toggle word wrap

The above cipher list represents the set of ciphers claimed in this RHCS release in OpenSSL format, where:

  • ciphers=" …​ ": establishes the restricted ciphers desired (for example TLS). In this format, cipher names are separated by a colon.
  • protocols=" …​ ": establishes which TLS version you want (for example, 1.2).

7.5.21.2. Configuring the ciphers for a CS instance acting as a client
Copia collegamento

When a CS instance acts as a client, add the desired list of ciphers in the instance’s CS.cfg configuration file. Configure all the client instances as relevant based on their roles.

Important

Back up the original CS.cfg file before editing, for example to CS.cfg.orig.

  • When a CS instance is acting as a client to its internal LDAP database.

    Add the following line to the <instance directory>/<instance type>/conf/CS.cfg file: 

    tcp.clientCiphers=TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256,TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
    Copy to Clipboard Toggle word wrap
    Note

    To ensure that the internal LDAP database has the desired ciphers enabled, please follow Configuring the ciphers for a DS instance.

  • When a CA instance is acting as a client to the KRA.

    Add the following line to the <instance directory>/ca/conf/CS.cfg file: 

    ca.connector.KRA.clientCiphers=TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256,TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
    Copy to Clipboard Toggle word wrap

  • When a TPS instance is acting as a client to the CA, KRA, or TKS.

    Add the following line to the <instance directory>/tps/conf/CS.cfg file: 

    tps.connector.<ca|kra|tks id>.clientCiphers=TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256,TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
    Copy to Clipboard Toggle word wrap
Note

You must restart each server instance for the modifications to take effect, for example: 

# pki-server restart rhcs10-RSA-RootCA
# pki-server restart rhcs10-RSA-SubCA
# pki-server restart rhcs10-RSA-OCSP-rootca
# pki-server restart rhcs10-RSA-OCSP-subca
# pki-server restart rhcs10-RSA-KRA
Copy to Clipboard Toggle word wrap

OR if using the Nuxwdog watchdog: 

# systemctl restart rhcs10-RSA-RootCA
# systemctl restart pki-tomcatd-nuxwdog@rhcs10-RSA-SubCA.service
# systemctl restart pki-tomcatd-nuxwdog@rhcs10-RSA-OCSP-rootca.service
# systemctl restart pki-tomcatd-nuxwdog@rhcs10-RSA-OCSP-subca.service
# systemctl restart pki-tomcatd-nuxwdog@rhcs10-RSA-KRA.service
Copy to Clipboard Toggle word wrap

7.5.21.3. Configuring the ciphers for a DS instance
Copia collegamento

By default, a Directory Server instance inherits the ciphers enabled on the OS. If you wish to set it so that the cipher list matches that of the Certificate System, proceed with the following steps for each DS instance:

  • On the DS host dir.example.com:

    1. Enable the intended ciphers (use the non-SSL port of the DS instance): 

      # dsconf -D "cn=Directory Manager" ldap://dir.example.com:7389 security ciphers set "+TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256,+TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,+TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384,+TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384"
      Copy to Clipboard Toggle word wrap

    2. Restart the DS instance: 

      # dsctl slapd-CC-RSA-SubCA-LDAP stop
      Copy to Clipboard Toggle word wrap 
      # dsctl slapd-CC-RSA-SubCA-LDAP start
      Copy to Clipboard Toggle word wrap

    3. Verify by listing the enabled ciphers: 

      # dsconf -D "cn=Directory Manager" ldap://dir.example.com:7389 security ciphers list --enabled

Enter password for cn=Directory Manager on ldap://dir.example.com:7389:
TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256
TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384
TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
      Copy to Clipboard Toggle word wrap

7.5.22. Enabling OAEP support for KRA, TKS, AND TPS
Copia collegamento

The Optimal Asymmetric Encryption Padding (OAEP) key wrapping algorithm is now supported in RHCS in favor of the older PKCS#1 algorithm. Newer HSM devices and later FIPS-enabled versions of NSS often require this algorithm for use. This operation mainly comes into play when there is an ultimate interaction with the KRA. The KRA’s transport certificate is used to perform a public key wrap of some other key, such as an AES symmetric key. When OAEP is utilized, OAEP must be used on both ends of the wrapping and unwrapping sequence, with the wrapping taking part on perhaps a client and the unwrapping taking place on a server such as the RHCS KRA or other subsystems.

There are two scenarios where OAEP is most often used:

  • Within our RHCS subsystems such as the KRA, TPS, and TKS.
  • Use through various command line tools that interact with one of the RHCS subsystems.

The client to server interaction requires that both ends use OAEP wrapping or not at all. For instance, if the KRA is configured for OAEP, command line tools that interact with the KRA must use OAEP when using the transport certificate to wrap keys.

Due to the fact that our JSS crypto bindings component has supported OAEP for some time, it is now a simple matter to configure clients or servers to make use of OAEP. The choice for Certificate System subsystems is binary in nature, meaning we must chose to do everything in OAEP (when called for) or do nothing in OAEP in similar scenarios. Once the user of client programs knows if the server is configured for OAEP or not, a decision on how to operate the client in question can be made based on command line parameters utilized or not utilized if defaults exist.

This section deals with the configuration of subsystems for OAEP. This configuration of the subsystems is performed after pkispawn has successfully created the RHCS subsystem instance.

Note

Limited support for Thales Luna: Red Hat is not able to confirm that the Thales HSM unit supports AES key wrapping/unwrapping via OAEP. Be aware that those features requiring support of this algorithm will not function without such support. These features include: KRA: key archival and recovery CMC SharedToken authentication mechanism for enrollments TKS TPS shared secret automatic transport during installation

Note: For examples of using the command line interface with OAEP, refer to the administration guide.

7.5.22.1. KRA
Copia collegamento

The KRA is one of the main Certificate System subsystems to make use of OAEP. This is due to the fact that the KRA transport certificate is often used by client programs to wrap keys which are subsequently unwrapped by the KRA itself.

This section contains settings other than OAEP to appease HSM devices that supports the AES key wrapping/unwrapping operations, such as an Entrust nShield Connect XC unit with firmware v12.72.1.

Perform the following (as root) on the host containing the subsystem:

  1. Stop the kra 

    pki-server stop <subsystem instance name>
    Copy to Clipboard Toggle word wrap

  2. Edit the /var/lib/pki/<subsystem instance name>/CS.cfg configuration file and add the following three lines: 

    keyWrap.useOAEP=true
kra.legacyPKCS12=false
kra.nonLegacyAlg=AES/None/PKCS5Padding/Kwp/256
    Copy to Clipboard Toggle word wrap

    The first line above relates to OAEP while the final two settings are complimentary settings that allow for proper KRA operation under the OAEP scenario. The AES based “KWP” algorithm is used in the situation above.

  3. Start the KRA: 

    pki-server start <subsystem instance name>
    Copy to Clipboard Toggle word wrap

7.5.22.2. TKS
Copia collegamento

Perform the following (as root) on the host containing the subsystem:

  1. Stop the TKS 

    pki-server stop <subsystem instance name>
    Copy to Clipboard Toggle word wrap

  2. Edit the /var/lib/pki/<subsystem instance name>/CS.cfg configuration file and add the following entry: 

    keyWrap.useOAEP=true
    Copy to Clipboard Toggle word wrap

  3. Start the TKS: 

    pki-server start <subsystem instance name>
    Copy to Clipboard Toggle word wrap

7.5.22.3. TPS
Copia collegamento

The TPS and TKS work together when using the Token Management System. OAEP needs to be enabled on both subsystems for normal operation. The normal sequence of installation of TKS and TPS has TKS installed first, followed by TPS. The following instructions apply when it is known that the TKS has been configured for OAEP.

Perform the following (as root) on the host containing the subsystem:

  1. Stop the TKS 

    pki-server stop <subsystem instance name>
    Copy to Clipboard Toggle word wrap

  2. Edit the /var/lib/pki/<subsystem instance name>/CS.cfg configuration file and add the following entry: 

    keyWrap.useOAEP=true
    Copy to Clipboard Toggle word wrap

  3. Start the TKS: 

    pki-server start <subsystem instance name>
    Copy to Clipboard Toggle word wrap
Torna in cima
Red Hat logoGithubredditYoutubeTwitter

Formazione

Prova, acquista e vendi

Community

Informazioni sulla documentazione di Red Hat

Aiutiamo gli utenti Red Hat a innovarsi e raggiungere i propri obiettivi con i nostri prodotti e servizi grazie a contenuti di cui possono fidarsi. Esplora i nostri ultimi aggiornamenti.

Rendiamo l’open source più inclusivo

Red Hat si impegna a sostituire il linguaggio problematico nel codice, nella documentazione e nelle proprietà web. Per maggiori dettagli, visita il Blog di Red Hat.

Informazioni su Red Hat

Forniamo soluzioni consolidate che rendono più semplice per le aziende lavorare su piattaforme e ambienti diversi, dal datacenter centrale all'edge della rete.

Theme

© 2025 Red Hat