6.5. Installing Red Hat Directory Server

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 or any other host in the network.

6.5.1. Preparing a Directory Server Instance for Certificate System

Perform the following steps to install Red Hat Directory Server:
  1. Make sure you have attached a subscription that provides Directory Server to the host.
  2. Enable the Directory Server repository: 
    # subscription-manager repos --enable=dirsrv-10-for-rhel-7-x86_64-rpms
  3. Install the Directory Server and openldap-clients packages: 
    # dnf module install redhat-ds
    # dnf install openldap-clients
  4. Set up a Directory Server instance.
    1. Generate a DS configuration file; for example, /tmp/ds-setup.inf: 
      $ dscreate create-template /tmp/ds-setup.inf
    2. Customize the DS configuration file as follows: 
      $ sed -i \
            -e "s/;instance_name = .*/instance_name = localhost/g" \
            -e "s/;root_password = .*/root_password = Secret.123/g" \
            -e "s/;suffix = .*/suffix = dc=example,dc=com/g" \
            -e "s/;create_suffix_entry = .*/create_suffix_entry = True/g" \
            -e "s/;self_sign_cert = .*/self_sign_cert = False/g" \
            /tmp/ds-setup.inf
    3. Create the instance using the dscreate command with the setup configuration file: 
      # dscreate from-file /tmp/ds-setup.inf
    For a detailed procedure, see the Red Hat Directory Server Installation Guide.

6.5.2. Preparing for Configuring Certificate System

In Section 7.3, “Understanding the pkispawn Utility”, if you chose to set up TLS between Certificate System and Directory Server, use the following parameters in the configuration file you pass to the pkispawn utility when installing Certificate System:

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
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.5.1, “Preparing a Directory Server Instance for Certificate System”.
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.

6.5.3. Replacing the Temporary Certificate

Note

This section requires a root CA installed and running. You will be instructed to follow instruction in this section during post-installation.
This section describes the process to replace the temporary self-signed Directory Server certificate with a permanent Directory Server certificate issued by the newly-installed CA, or to replace an old Directory Server certificate with a new one.
  1. Obtain a new Directory Server server certificate. Submit the request for the new certificate signed by the CA. To get a new Directory Server certificate using the CMC method, see the Obtaining System and Server Certificates section in the Red Hat Certificate System Administration Guide.
    In the above section, follow the guidance to create a TLS server certificate. Once the certificate is created, it must be imported back into the Directory Server's certificate database.
  2. Stop the Directory Server instance before accessing the NSS database: 
    # systemctl stop dirsrv@instance_name
  3. Delete the old Directory Server certificate: 
    # certutil -F -d /etc/dirsrv/slapd-instance_name -f /etc/dirsrv/slapd-instance_name/password.txt -n "DS Certificate"
  4. Import the CA certificate downloaded earlier: 
    # PKICertImport -d /etc/dirsrv/slapd-instance_name -f /etc/dirsrv/slapd-instance_name/password.txt -n "CA Certificate" -t "CT,C,C" -a -i ca.crt -u L
  5. Import the new Directory Server certificate downloaded earlier: 
    # PKICertImport -d /etc/dirsrv/slapd-instance_name -f /etc/dirsrv/slapd-instance_name/password.txt -n "DS Certificate" -t ",," -a -i ds.crt -u V
    See also Section 14.4, “Importing a certificate into an HSM”.
  6. Start the Directory Server instance: 
    # systemctl start dirsrv@instance_name
  7. Remove the old Directory Server Certificate from PKI CA:
    1. Stop the Certificate System instance: 
      # systemctl stop pki-tomcatd@instance_name.service
    2. Remove the certificate: 
      # certutil -D -d /var/lib/pki/instance_name/alias/ -n "DS Certificate"
    3. Start the Certificate System instance: 
      # systemctl start pki-tomcatd@instance_name.service
  8. Verify that the new Directory Server certificate is signed by the CA installed in the NSS database:
    1. Display the Directory Server certificate 
      $ certutil -L -d /etc/dirsrv/slapd-instance_name -n "DS Certificate"

Issuer: "CN=CA Signing Certificate,O=EXAMPLE"
Subject: "CN=server.example.com"
    2. Verify the old Directory Server certificate no longer exists in the PKI NSS database: 
      $ certutil -L -d /var/lib/pki/instance_name/alias
    3. Verify Certificate System can connect to Directory Server using the new certificate: 
      $ pki cert-find

6.5.4. Enabling TLS Client Authentication

Note

This section requires a root CA installed and running. If you used a temporary LDAP server certificate, replace it first by following Section 6.5.3, “Replacing the Temporary Certificate”. Follow instruction in this section during post-installation.
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 9.8. Using Certificate-based Client Authentication in 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
    For example 
    certmap rhcs CN=CA Signing Certificate,OU=pki-tomcat-ca,O=pki-tomcat-ca-SD
rhcs:CmapLdapAttr seeAlso
rhcs:verifyCert on
  • 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
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
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.