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. Attach a Directory Server subscription to the host.
  2. Install the Directory Server and openldap-clients packages: 
    # yum install redhat-ds openldap-clients
  3. Set up a Directory Server instance. For example:
    1. Create a setup configuration file, such as /tmp/ds-setup.inf with the following content: 
      [General]
FullMachineName=server.example.com
SuiteSpotUserID=dirsrv
SuiteSpotGroup=dirsrv

[slapd]
ServerIdentifier=instance_name
ServerPort=389
Suffix=dc=example,dc=org
RootDN=cn=Directory Manager
RootDNPwd=password
    2. Create the instance using the setup configuration file: 
      setup-ds.pl --silent --file=/tmp/ds-setup.inf
    For a detailed procedure, see the Red Hat Directory Server Installation Guide.

6.5.2. Enabling TLS Support in Directory Server

Every Certificate System component communicates with the Directory Server instance using a TLS-encrypted connection where the Certificate System component is required to authenticate to the Directory Server using client-authentication (mutual authentication).
For details about enabling TLS support in Directory Server, see the Enabling TLS in Directory Server section in the Directory Server Administration Guide.
For details on how to request and issue a TLS server certificate for Directory Server, see the Using a Certificate Issued by Certificate System in Directory Server section in the Red Hat Certificate System Administration Guide (Common Criteria Edition).
As described in the Directory Server documentation, you can configure TLS either using a certificate issued by an external Certificate Authority (CA) or a temporary self-signed server certificate. However, after setting up the Certificate System CA, you can use this CA to issue a certificate and replace it with the one used when you set up Directory Server.

6.5.2.1. How to Enable LDAPS for new Red Hat Certificate System Subsystems Using Examples Values

Note

When performing this TLS LDAP procedure, the final goal is to have the connection over TLS client authentication. During the process, we have to move along step by step, with intermediate goals. One such goal is to simply set TLS server authentication running first. At the end, the process will double-back to get full client authentication operational.
  1. Stop the Directory Server instance to avoid concurrent changes to the NSS database: 
    # systemctl stop dirsrv@instance_name.service
  2. Store the Directory Manager's password in the /etc/dirsrv/instance_name/password.txt file. For example: 
    # echo password > /etc/dirsrv/slapd-instance_name/password.txt
# chown dirsrv.dirsrv /etc/dirsrv/slapd-instance_name/password.txt
# chmod 400 /etc/dirsrv/slapd-instance_name/password.txt
  3. Store the Directory Manager's password in the /etc/dirsrv/instance_name/pin.txt file. For example: 
    # echo "Internal (Software) Token:password" > /etc/dirsrv/slapd-instance_name/pin.txt
# chown dirsrv.dirsrv /etc/dirsrv/slapd-instance_name/pin.txt
# chmod 400 /etc/dirsrv/slapd-instance_name/pin.txt
  4. Set the NSS database password: 
    # certutil -W -d /etc/dirsrv/slapd-instance_name/ -f /etc/dirsrv/slapd-instance_name/password.txt
  5. Create a temporary self-signed certificate for Directory Server: 
    $ cd /etc/dirsrv/slapd-instance_name
$ openssl rand -out noise.bin 2048
$ certutil -S \
	-x \
	-d . \
	-f password.txt \
	-z noise.bin \
	-n "DS Certificate" \
	-s "CN=$HOSTNAME" \
	-t "CT,C,C" \
	-m $RANDOM \
	-k rsa \
	-g 2048 \
	-Z SHA256 \
	--keyUsage certSigning,keyEncipherment
  6. Verify whether the Directory Server certificate entry is available in the NSS database: 
    # certutil -L -d /etc/dirsrv/slapd-instance_name/
  7. Export the certificate: 
    # certutil -L -d /etc/dirsrv/slapd-instance_name -n "DS Certificate" -a > ds.crt
  8. Verify the Directory Server certificate is self-signed: 
    # certutil -L -d /etc/dirsrv/slapd-instance_name -n "DS Certificate"
Issuer: "CN=server.example.com"
Subject: "CN=server.example.com"
  9. Start the Directory Server instance: 
    # systemctl start dirsrv@instance_name
  10. Enable secure connection: 
    # ldapmodify -x -p 389 -h $HOSTNAME -D "cn=Directory Manager" -w password << EOF
dn: cn=config
changetype: modify
replace: nsslapd-security
nsslapd-security: on

dn: cn=RSA,cn=encryption,cn=config
changetype: add
objectclass: top
objectclass: nsEncryptionModule
cn: RSA
nsSSLPersonalitySSL: DS Certificate
nsSSLToken: internal (software)
nsSSLActivation: on
EOF
  11. Optionally, set a different LDAPS port than the default (636).
    1. For example, to set the LDAPS port to 11636: 
      ldapmodify -x -p 389 -h $HOSTNAME -D "cn=Directory Manager" -w password << EOF
dn: cn=config
changetype: modify
replace: nsslapd-secureport
nsslapd-secureport: 11636
EOF
    2. Set the SELinux policy for this non-standard port: 
      # semanage port -a -t ldap_port_t -p tcp 11636
  12. Restart the Directory Server instance: 
    # systemctl restart dirsrv@instance_name
  13. Verify in the /var/log/dirsrv/slapd-instance_name/errors file that Directory Server started in TLS mode: 
    [30/Jun/2016:00:23:31 +0200] - SSL alert: Security Initialization: Enabling default cipher set.
[30/Jun/2016:00:23:31 +0200] - SSL alert: Configured NSS Ciphers
[30/Jun/2016:00:23:31 +0200] - SSL alert:       TLS_ECDHE_PSK_WITH_AES_128_GCM_SHA256: enabled
[30/Jun/2016:00:23:31 +0200] - SSL alert:       TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256: enabled
[30/Jun/2016:00:23:31 +0200] - SSL alert:       TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256: enabled
[30/Jun/2016:00:23:31 +0200] - SSL alert:       TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256: enabled
[30/Jun/2016:00:23:31 +0200] - SSL alert:       TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256: enabled
[30/Jun/2016:00:23:31 +0200] - SSL alert:       TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA: enabled
[30/Jun/2016:00:23:31 +0200] - SSL alert:       TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA: enabled
[30/Jun/2016:00:23:31 +0200] - SSL alert:       TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA: enabled
[30/Jun/2016:00:23:31 +0200] - SSL alert:       TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256: enabled
[30/Jun/2016:00:23:31 +0200] - SSL alert:       TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256: enabled
[30/Jun/2016:00:23:31 +0200] - SSL alert:       TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA: enabled
[30/Jun/2016:00:23:31 +0200] - SSL alert:       TLS_DHE_RSA_WITH_AES_128_GCM_SHA256: enabled
[30/Jun/2016:00:23:31 +0200] - SSL alert:       TLS_DHE_RSA_WITH_CHACHA20_POLY1305_SHA256: enabled
[30/Jun/2016:00:23:31 +0200] - SSL alert:       TLS_DHE_RSA_WITH_AES_128_CBC_SHA: enabled
[30/Jun/2016:00:23:31 +0200] - SSL alert:       TLS_DHE_DSS_WITH_AES_128_CBC_SHA: enabled
[30/Jun/2016:00:23:31 +0200] - SSL alert:       TLS_DHE_RSA_WITH_AES_128_CBC_SHA256: enabled
[30/Jun/2016:00:23:31 +0200] - SSL alert:       TLS_DHE_RSA_WITH_AES_256_CBC_SHA: enabled
[30/Jun/2016:00:23:31 +0200] - SSL alert:       TLS_DHE_DSS_WITH_AES_256_CBC_SHA: enabled
[30/Jun/2016:00:23:31 +0200] - SSL alert:       TLS_DHE_RSA_WITH_AES_256_CBC_SHA256: enabled
[30/Jun/2016:00:23:31 +0200] - SSL alert:       TLS_RSA_WITH_AES_128_GCM_SHA256: enabled
[30/Jun/2016:00:23:31 +0200] - SSL alert:       TLS_RSA_WITH_AES_128_CBC_SHA: enabled
[30/Jun/2016:00:23:31 +0200] - SSL alert:       TLS_RSA_WITH_AES_128_CBC_SHA256: enabled
[30/Jun/2016:00:23:31 +0200] - SSL alert:       TLS_RSA_WITH_AES_256_CBC_SHA: enabled
[30/Jun/2016:00:23:31 +0200] - SSL alert:       TLS_RSA_WITH_AES_256_CBC_SHA256: enabled
[30/Jun/2016:00:23:31 +0200] SSL Initialization - Configured SSL version range: min: TLS1.0, max: TLS1.2
[30/Jun/2016:00:23:31 +0200] - 389-Directory/1.3.4.11 B2016.166.1911 starting up
  14. Verify the TLS connection using the openldap-clients and NSS database: 
    $ LDAPTLS_CACERTDIR=/etc/dirsrv/slapd-instance_name \
	ldapsearch -H ldaps://$HOSTNAME:11636 \
	-x -D "cn=Directory Manager" -w Secret.123 \
	-b "dc=example,dc=org" -s base "(objectClass=*)"

6.5.3. Preparing for Configuring Certificate System

In Section 7.3, “Installing 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:

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” and Section 6.5.2, “Enabling TLS Support in Directory Server”.
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.4. 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 (Common Criteria Edition).
    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 10.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.5. 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.4, “Replacing the Temporary Certificate”. Follow instruction in this section during post-installation.
The basic TLS server authentication has been configured and running during installation of 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/pki-tomcat/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.