Red Hat Summit Red Hat SummitSuporteConsoleDesenvolvedoresComeçar um testeContato

Este conteúdo não está disponível no idioma selecionado.

Chapter 6. Prerequisites and Preparation for Installation

The Red Hat Certificate System installation process requires some preparation of the environment. This chapter describes the requirements, dependencies, and other prerequisites when installing Certificate System subsystems.

6.1. Installing Red Hat Enterprise Linux
Copiar o link

Red Hat Certificate System 10.8 requires the Red Hat Enterprise Linux 8.10 version. For details about installing Red Hat Enterprise Linux, see Performing a standard RHEL installation.

To enable the Federal Information Processing Standard (FIPS) on Red Hat Enterprise Linux, see the Red Hat Security Hardening Guide.

Important

It is strongly recommended that FIPS mode is enabled on the RHEL host before you install Certificate System.

  1. Enable FIPS: 

    # fips-mode-setup --enable
    Copy to Clipboard Toggle word wrap
  2. Restart the system.

  3. Verify FIPS mode is enabled: 

    # sysctl crypto.fips_enabled
    Copy to Clipboard Toggle word wrap

    If the returned value is 1, FIPS mode is enabled.

Important

When FIPS mode is enabled for RHEL, the attached HSM used by Certificate System must also be in FIPS mode. See Section 6.2.1, “Enabling FIPS mode on an HSM”.

6.1.1. Securing the system using SELinux
Copiar o link

Security-Enhanced Linux (SELinux) is an implementation of a mandatory access control mechanism in the Linux kernel, checking for allowed operations after standard discretionary access controls are checked. SELinux can enforce rules on files and processes in a Linux system, and on their actions, based on defined policies.

In most cases, no actions are required to run Certificate System with SELinux in enforcing mode. If a procedure in the Certificate System documentation requires to manually set SELinux-related settings, such as when using a Hardware Security Module (HSM), it is mentioned in the corresponding section.

By default, after installing Red Hat Enterprise Linux, SELinux is enabled and running in enforcing mode and no further actions are required.

  • To verify the current SELinux mode, enter: 

    # getenforce
    Copy to Clipboard Toggle word wrap

For further details about SELinux, see the Using SELinux Guide.

6.1.2. Configuring the firewall
Copiar o link

The following table lists the default ports used by Certificate System subsystems:

Expand
Table 6.1. Certificate System default ports
ServicePortProtocol

HTTP

8080

TCP

HTTPS

8443

TCP

Tomcat Management

8005

TCP

When you set up Certificate System using the pkispawn utility, you can customize the port numbers. If you use different ports than the defaults listed above, open them correspondingly in the firewall as described in Opening the required ports in the firewall. For further details about ports, see Section 5.5.3, “Planning ports”.

For ports required to access Directory Server, see the corresponding section in the DirectoryServer Installation Guide.

Opening the required ports in the firewall

To enable communication between the clients and Certificate System, open the required ports in your firewall:

  1. Make sure the firewalld service is running. 

    # systemctl status firewalld
    Copy to Clipboard Toggle word wrap

  2. To start firewalld and configure it to start automatically when the system boots: 

    # systemctl start firewalld
# systemctl enable firewalld
    Copy to Clipboard Toggle word wrap

  3. Open the required ports using the firewall-cmd utility. For example, to open the Certificate System default ports in the default firewall zone: 

    # firewall-cmd --permanent --add-port={8080/tcp,8443/tcp,8009/tcp,8005/tcp}
    Copy to Clipboard Toggle word wrap

    For details on using firewall-cmd to open ports on a system, see Securing Networks or the firewall-cmd(1) man page.

  4. Reload the firewall configuration to ensure that the change takes place immediately: 

    # firewall-cmd --reload
    Copy to Clipboard Toggle word wrap

6.2. Hardware Security Module
Copiar o link

To use a Hardware Security Module (HSM), a Federal Information Processing Standard (FIPS) 140-2 validated HSM is required. The Certificate System supports the nCipher nShield hardware security module (HSM) and Gemalto Safenet LunaSA HSM by default. Certificate System-supported HSMs are automatically added to the pkcs11.txt database with the modutil command during the pre-configuration stage of the installation, if the PKCS #11 library modules are in the specified installation paths.

6.2.1. Enabling FIPS mode on an HSM
Copiar o link

Certain deployments require to setup their HSM to use FIPS mode. To enable FIPS Mode on HSMs, please refer to your HSM vendor’s documentation for specific instructions.

Important
nCipher HSM
On a nCipher HSM, the FIPS mode can only be enabled when generating the Security World, this cannot be changed afterwards. While there is a variety of ways to generate the Security World, the preferred method is always to use the new-world command. For guidance on how to generate a FIPS-compliant Security World, please follow the nCipher HSM vendor’s documentation.
LunaSA HSM
Similarly, enabling the FIPS mode on a Luna HSM must be done during the initial configuration, since changing this policy zeroizes the HSM as a security measure. For details, please refer to the Luna HSM vendor’s documentation.

6.2.2. Verifying if FIPS mode is enabled on an HSM
Copiar o link

This section describes how to verify if FIPS mode is enabled for certain HSMs. For other HSMs, see the hardware manufacturer’s documentation.

6.2.2.1. Verifying if FIPS mode is enabled on an nCipher HSM
Copiar o link

Note

Please refer to your HSM vendor’s documentation for the complete procedure.

To verify if the FIPS mode is enabled on an nCipher HSM, enter: 

# /opt/nfast/bin/nfkminfo
Copy to Clipboard Toggle word wrap

With older versions of the software, if the StrictFIPS140 is listed in the state flag, the FIPS mode is enabled. In newer vesions, it is however better to check the new mode line and look for fips1402level3. In all cases, there should also be an hkfips key present in the nfkminfo output.

6.2.2.2. Verifying if FIPS mode is enabled on a Luna SA HSM
Copiar o link

Note

Please refer to your HSM vendor’s documentation for the complete procedure.

To verify if the FIPS mode is enabled on a Luna SA HSM:

  1. Open the lunash management console

  2. Use the hsm show command and verify that the output contains the text The HSM is in FIPS 140-2 approved operation mode.: 

    lunash:> hsm show
...
       FIPS 140-2 Operation:
       =====================
       The HSM is in FIPS 140-2 approved operation mode.
...
    Copy to Clipboard Toggle word wrap

6.2.3. Setting up SELinux for an HSM
Copiar o link

Certain HSMs require that you manually update SELinux settings before you can install Certificate System.

The following section describes the required actions for supported HSMs:

nCipher nShield

After you installed the HSM and before you start installing Certificate System:

  1. Reset the context of files in the /opt/nfast/ directory: 

    # restorecon -R /opt/nfast/
    Copy to Clipboard Toggle word wrap

  2. Restart the nfast software. 

    # /opt/nfast/sbin/init.d-ncipher restart
    Copy to Clipboard Toggle word wrap
Gemalto Safenet LunaSA HSM
No SELinux-related actions are required before you start installing Certificate System.

For details about the supported HSMs, see Section 4.4, “Supported Hardware Security Modules”.

6.2.4. Preparing for installing Certificate System with an HSM
Copiar o link

In Section 7.2, “Installing RHCS using the pkispawn utility”, you are instructed to use the following parameters in the configuration file you pass to the pkispawn utility when installing Certificate System with an HSM: 

...
[DEFAULT]
##########################
# Provide HSM parameters #
##########################
pki_hsm_enable=True
pki_hsm_libfile=hsm_libfile
pki_hsm_modulename=hsm_modulename
pki_token_name=hsm_token_name
pki_token_password=pki_token_password

########################################
# Provide PKI-specific HSM token names #
########################################
pki_audit_signing_token=hsm_token_name
pki_ssl_server_token=hsm_token_name
pki_subsystem_token=hsm_token_name
...
Copy to Clipboard Toggle word wrap
  • The values of the pki_hsm_libfile and pki_token_name parameter depend on your specific HSM installation. These values allow the pkispawn utility to set up your HSM and enable Certificate System to connect to it.
  • The value of the pki_token_password depends upon your particular HSM token’s password. The password gives the pkispawn utility read and write permissions to create new keys on the HSM.
  • The value of the pki_hsm_modulename is a name used in later pkispawn operations to identify the HSM. The string is an identifier you can set as whatever you like. It allows pkispawn and Certificate System to refer to the HSM and configuration information by name in later operations.

The following section provides settings for individual HSMs. If your HSM is not listed, consult your HSM manufacturer’s documentation.

For more information on using an HSM, see Using hardware security modules with subsystems.

6.2.4.1. nCipher HSM parameters
Copiar o link

For an nCipher HSM, set the following parameters: 

pki_hsm_libfile=/opt/nfast/toolkits/pkcs11/libcknfast.so
pki_hsm_modulename=nfast
Copy to Clipboard Toggle word wrap

Note that you can set the value of pki_hsm_modulename to any value. The above is a suggested value.

Example 6.1. Identifying the token name

To identify the token name, run the following command as the root user: 

[root@example911 ~]# /opt/nfast/bin/nfkminfo
World
 generation  2

...snip...

Cardset
 name          "NHSM-CONN-XC"
 k-out-of-n    1/4
 flags         NotPersistent PINRecoveryRequired(enabled) !RemoteEnabled
 timeout       none

...snip...
Copy to Clipboard Toggle word wrap

The value of the name field in the Cardset section lists the token name.

Set the token name as follows: 

pki_token_name=NHSM-CONN-XC
Copy to Clipboard Toggle word wrap

6.2.4.2. SafeNet / Luna SA HSM parameters
Copiar o link

For a SafeNet / Luna SA HSM, such as a SafeNet Luna Network HSM, specify the following parameters: 

pki_hsm_libfile=/usr/safenet/lunaclient/lib/libCryptoki2_64.so
pki_hsm_modulename=lunasa
Copy to Clipboard Toggle word wrap

Note that you can set the value of pki_hsm_modulename to any value. The above is a suggested value.

Example 6.2. Identifying the token name

To identify the token name, run the following command as the root user: 

# /usr/safenet/lunaclient/bin/vtl verify

The following Luna SA Slots/Partitions were found:

Slot    Serial #            Label
===    ===============    =====
   0       1209461834772     lunasaQE
Copy to Clipboard Toggle word wrap

The value in the label column lists the token name.

Set the token name as follows: 

pki_token_name=lunasaQE
Copy to Clipboard Toggle word wrap

6.3. Red Hat Directory Server installation prerequisites
Copiar o link

You must ensure certain prerequisites are met prior to installing PKI subsystems. Every system must have a correctly configured fully qualified domain name (FQDN)

Additionally, for every Certificate System instance installation, you must install a Directory Server instance and it is likely to be on a separate host from the Certificate System instance, you must ensure the hostname is configured correctly and recognized by the Certificate System instance hosts.

6.3.1. FQDN configuration
Copiar o link

In order to have a properly functioning PKI system, each machine in the system must have a correct fully qualified domain name.

Follow this process to configure the fully qualified domain name on each machine.

6.3.1.1. Verifying FQDN
Copiar o link

To verify the current FQDN, execute the following command: 

# hostname
pki.example.com
Copy to Clipboard Toggle word wrap

6.3.1.2. Configuring FQDN
Copiar o link

If the host name is not what you expect it to be, run hostnamectl to set the hostname. For example,

  1. Set the hostname of your pki machine as follows: 

    # hostnamectl set-hostname pki.example.com
    Copy to Clipboard Toggle word wrap

  2. Set the hostname of your DS machine as follows: 

    # hostnamectl set-hostname dir.example.com
    Copy to Clipboard Toggle word wrap

  3. Add both the CS and DS machine IP addresses and new hostnames as entries in /etc/hosts of both machines: 

    127.0.0.1 localhost localhost.localdomain localhost4 localhost4.localdomain4
::1 localhost localhost.localdomain localhost6 localhost6.localdomain6
10.1.111.111 pki.example.com
10.2.222.222 dir.example.com
    Copy to Clipboard Toggle word wrap

  4. Verify the FQDN again after the change: 

    # hostname
    Copy to Clipboard Toggle word wrap

6.3.2. Installing Red Hat Directory Server
Copiar o link

Red Hat Certificate System uses Red Hat Directory Server to store system certificates and user data. You can install both Directory Server and Certificate System on the same host or on different hosts in the network.

Important

If you are enabling FIPS mode on the RHEL system that is hosting the Directory Server, FIPS mode must be enabled on the RHEL host before you install the Directory Server.

To ensure FIPS mode is enabled: 

# sysctl crypto.fips_enabled
Copy to Clipboard Toggle word wrap

If the returned value is 1, FIPS mode is enabled.

6.3.2.1. Installing the Directory Server packages
Copiar o link

Perform the following steps to install the Red Hat Directory Server packages:

  1. Pin the RHEL version to 8.10 by using the subscription-manager release --set command. For example: 

    # subscription-manager release --list
# subscription-manager release --set 8.10
    Copy to Clipboard Toggle word wrap

    Verification: 

    subscription-manager release --show
    Copy to Clipboard Toggle word wrap
  2. Make sure you have attached a subscription that provides Directory Server to the host.

  3. Enable the Directory Server packages repository: 

    # subscription-manager repos --enable=dirsrv-11.9-for-rhel-8-x86_64-rpms
    Copy to Clipboard Toggle word wrap

  4. Install the Directory Server and the openldap-clients packages: 

    # dnf module install redhat-ds:11
    Copy to Clipboard Toggle word wrap

6.3.2.2. Directory Server instance creation
Copiar o link

Note: Prior to installing DS instances, make sure the following procedures are done:

Follow this process to prepare a local DS instance for PKI server.

Note: The DS installation automatically generates a bootstrap self-signed signing certificate which issues a bootstrap server certificate for SSL connection. The PKI installation takes advantage of this security offer to complete its installation. The bootstrap server certificate could be replaced by a server certificate issued by an actual CA at a later step after the installation.

If you wish to disable bootstrap certificate generation and SSL connection, set self_sign_cert = False in the sed command below. You can still enable SSL later by following Enabling SSL Connection in DS with Bootstrap Cert.

6.3.2.2.1. Creating a DS Instance
Copiar o link
6.3.2.2.1.1. Generating a DS configuration file, for example ds.inf:
Copiar o link
$ dscreate create-template ds.inf
Copy to Clipboard Toggle word wrap

Customize the DS configuration file as follows: 

$ sed -i \
    -e "s/^;instance_name = .*/instance_name = localhost/" \
    -e "s/^;root_password = .*/root_password = Secret.123/" \
    -e "s/^;suffix = .*/suffix = dc=example,dc=com/" \
    -e "s/^;create_suffix_entry = .*/create_suffix_entry = True/" \
    -e "s/^;self_sign_cert = .*/self_sign_cert = True/" \
    ds.inf
Copy to Clipboard Toggle word wrap

+ where

  • instance_name specifies the name of the DS instance. In this example it’s set to localhost.
  • root_password specifies the password for DS admin, that is cn=Directory Manager. In this example it is set to Secret.123.
  • suffix specifies the namespace for the DS instance. In this example it is set to dc=example,dc=com.

  • self_sign_cert specifies whether to create self-signed certificates for SSL connection. In this example it is set to True. The SSL connection is enabled.

    For more information see the parameter descriptions in the DS configuration file itself, that is, ds.inf, and in DS documentation.

For more information see the parameter descriptions in the DS configuration file itself (i.e. ds.inf) and in DS documentation.

6.3.2.2.1.2. Creating an instance
Copiar o link

Finally, create the instance: 

$ dscreate from-file ds.inf
Copy to Clipboard Toggle word wrap
6.3.2.2.2. Creating PKI subtree
Copiar o link

Note: The dc=pki,dc=example,dc=com subtree is not mandatory, but it is highly recommended in order to avoid conflicts with other applications sharing the same DS instance.

Initially the DS instance is empty. Use an LDAP client to add a root entry and PKI base entry, for example: 

$ ldapadd -H ldap://$HOSTNAME -x -D "cn=Directory Manager" -w Secret.123 << EOF
dn: dc=pki,dc=example,dc=com
objectClass: domain
dc: pki
EOF
Copy to Clipboard Toggle word wrap

The subtree for each PKI subsystem is created when the subsystem is installed. When all PKI subsystems are created, the LDAP tree looks like the following: 

dc=example,dc=com
+ dc=pki
  + dc=ca
  + dc=kra
  + dc=ocsp
  + dc=tks
  + dc=tps
  + dc=acme
  + dc=est
Copy to Clipboard Toggle word wrap
6.3.2.2.3. Enabling SSL connection
Copiar o link

If you set self_sign_cert = False earlier, and now decide to create bootstrap certs so that your PKI can be installed using SSL connection to DS, follow Enabling SSL Connection in DS

Note: The bootstrap server certificate could be replaced by a server certificate issued by an actual CA at a later step after the installation.

6.3.2.2.4. Configuring replication
Copiar o link

See Configuring DS Replication.

6.3.2.2.5. Removing DS instance
Copiar o link

To remove DS instance: 

$ dsctl localhost remove --do-it
Copy to Clipboard Toggle word wrap
6.3.2.2.6. Log Files
Copiar o link

DS log files are available in /var/log/dirsrv/slapd-localhost:

  • access
  • audit
  • errors
6.3.2.2.7. See Also
Copiar o link

Before you can install and update Certificate System, you must enable the corresponding repository:

  1. Pin the RHEL version to 8.10 by using the subscription-manager release --set command. For example: 

    # subscription-manager release --list
# subscription-manager release --set 8.10
    Copy to Clipboard Toggle word wrap

    Verification: 

    subscription-manager release --show
    Copy to Clipboard Toggle word wrap

  2. Attach the Red Hat subscriptions to the system:

    Skip this step, if your system is already registered or has a subscription that provides Certificate System attached.

    1. Register the system to the Red Hat subscription management service.

      You can use the --auto-attach option to automatically apply an available subscription for the operating system. 

      # subscription-manager register --auto-attach
Username: admin@example.com
Password:
The system has been registered with id: 566629db-a4ec-43e1-aa02-9cbaa6177c3f

Installed Product Current Status:
Product Name:           Red Hat Enterprise Linux Server
Status:                 Subscribed
      Copy to Clipboard Toggle word wrap

    2. List the available subscriptions and note the pool ID providing the Red Hat Certificate System. For example: 

      # subscription-manager list --available --all
...
Subscription Name:   Red Hat Enterprise Linux Developer Suite
Provides:            ...
                     Red Hat Certificate System
                     ...
Pool ID:             7aba89677a6a38fc0bba7dac673f7993
Available:           1
...
      Copy to Clipboard Toggle word wrap

      In case you have a lot of subscriptions, the output of the command can be very long. You can optionally redirect the output to a file: 

      # subscription-manager list --available --all > /root/subscriptions.txt
      Copy to Clipboard Toggle word wrap

    3. Attach the Certificate System subscription to the system using the pool ID from the previous step: 

      # subscription-manager attach --pool=7aba89677a6a38fc0bba7dac673f7993
Successfully attached a subscription for: Red Hat Enterprise Linux Developer Suite
      Copy to Clipboard Toggle word wrap

  3. Enable the Certificate System repository: 

    # subscription-manager repos --enable certsys-10.x-for-rhel-8-x86_64-rpms
Repository 'certsys-10-for-rhel-8-x86_64-rpms' is enabled for this system.
    Copy to Clipboard Toggle word wrap

  4. Enable the Certificate System module stream: 

    # dnf module enable redhat-pki
    Copy to Clipboard Toggle word wrap

Installing the required packages is described in the Chapter 7, Installing and configuring Red Hat Certificate System.

Note

For compliance, only enable Red Hat approved repositories. Only Red Hat approved repositories can be enabled through subscription-manager utility.

6.4. Certificate System packages
Copiar o link

When installing the Certificate System packages you can either install them for each subsystem individually or all at once.

Important

To install and update Certificate System packages, you must enable the corresponding repository. For details, see Section 6.3.2.3, “Attaching a Red Hat subscription and enabling the Certificate System package repository”.

The following subsystem packages and components are available in Red Hat Certificate System:

  • pki-ca: Provides the Certificate Authority (CA) subsystem.
  • pki-kra: Provides the Key Recovery Authority (KRA) subsystem.
  • pki-ocsp: Provides the Online Certificate Status Protocol (OCSP) responder.
  • pki-tks: Provides the Token Key Service (TKS).
  • pki-tps: Provides the Token Processing Service (TPS).
  • pki-console and redhat-pki-console-theme: Provides the Java-based Red Hat PKI console. Both packages must be installed.

  • pki-server and redhat-pki-server-theme: Provides the web-based Certificate System interface. Both packages must be installed.

    This package is installed as a dependency if you install one of the following packages: pki-ca, pki-kra, pki-ocsp, pki-tks, pki-tps

  • pki-acme: Provides Automatic Certificate Management Environment (ACME).
  • pki-est: Provides Enrollment over Secure Transport (EST).

6.4.1. Installing Certificate System packages
Copiar o link

  • With the redhat-pki module, you can install all Certificate System subsystem packages and components at once on a RHEL 8 system which include CA, KRA, OCSP, TKS, TPS, ACME, and EST. 

    # dnf install redhat-pki
    Copy to Clipboard Toggle word wrap

  • Alternatively, you can install packages separately. For example, to install the CA subsystem and the optional web interface: 

    # dnf install pki-ca redhat-pki-server-theme
    Copy to Clipboard Toggle word wrap

    For other subsystems, replace the pki-ca package name with the one of the subsystem you want to install.

  • If you require the optional PKI console: 

    # dnf install pki-console redhat-pki-console-theme
    Copy to Clipboard Toggle word wrap
    Note

    The pkiconsole tool will be deprecated.

  • If you are installing the PKI CLI on a machine that does not have a PKI server, execute the following command: 

    # dnf install redhat-pki-tools
    Copy to Clipboard Toggle word wrap

6.4.2. Updating Certificate System packages
Copiar o link

To update Certificate System and operating system packages, use the following procedure:

  1. Follow instructions in Section 6.4.3, “Determining Certificate System product version” to check the product version.

  2. Execute \# dnf update

    The command above updates the whole system including the RHCS packages.

    Note

    We suggest scheduling a maintenance window during which you can take the PKI infrastructure offline to install the update.

    Important

    Updating Certificate System requires the PKI infrastructure to be restarted.

  3. Then check version again by following Section 6.4.3, “Determining Certificate System product version”.

    The version number should confirm that the update was successfully installed.

To optionally download updates without installing, use the --downloadonly option in the above procedure: 

dnf update --downloadonly
Copy to Clipboard Toggle word wrap

The downloaded packages are stored in the /var/cache/dnf/ directory. The dnf update will later use the packages if they are the latest versions.

6.4.3. Determining Certificate System product version
Copiar o link

The Red Hat Certificate System product version is stored in the /usr/share/pki/CS`SERVER_VERSION file. To display the version: 

# cat /usr/share/pki/CS_SERVER_VERSION
Red Hat Certificate System {Version} (Batch Update 1)
Copy to Clipboard Toggle word wrap

To find the product version of a running server, access the following URLs from your browser:

  • http://<hostname>:<port_number>/ca/admin/ca/getStatus
  • http://<hostname>:<port_number>/kra/admin/kra/getStatus
  • http://<hostname>:<port_number>/ocsp/admin/ocsp/getStatus
  • http://<hostname>:<port_number>/tks/admin/tks/getStatus
  • http://<hostname>:<port_number>/tps/admin/tps/getStatus
Note

Note that each component is a separate package and thus could have a separate version number. The above will show the version number for each currently running component.

6.5. Certificate System operating system users and groups
Copiar o link

When installing Certificate System, the pkiuser account and the corresponding pkiuser group are automatically created. Certificate System uses this account and group to start services.

As part of a post-installation procedure, you will later be instructed to create an operating system user for each Certificate System administrator who should be able to start and stop or directly configure the instance on the operating system. For details, see Section 7.5, “Post-installation tasks”.

Voltar ao topo
Red Hat logoGithubredditYoutubeTwitter

Aprender

Experimente, compre e venda

Comunidades

Sobre a documentação da Red Hat

Ajudamos os usuários da Red Hat a inovar e atingir seus objetivos com nossos produtos e serviços com conteúdo em que podem confiar. Explore nossas atualizações recentes.

Tornando o open source mais inclusivo

A Red Hat está comprometida em substituir a linguagem problemática em nosso código, documentação e propriedades da web. Para mais detalhes veja o Blog da Red Hat.

Sobre a Red Hat

Fornecemos soluções robustas que facilitam o trabalho das empresas em plataformas e ambientes, desde o data center principal até a borda da rede.

Theme

© 2025 Red Hat