13.5. Configuring the LDAP Database

The Certificate System performs certificate- and key-management functions in response to the requests it receives. These functions include the following:
  • Storing and retrieving certificate requests
  • Storing and retrieving certificate records
  • Storing CRLs
  • Storing ACLs
  • Storing privileged user and role information
  • Storing and retrieving end users' encryption private key records
To fulfill these functions, the Certificate System is incorporated with a Red Hat Directory Server, referred to as the internal database or local database. The Directory Server is referenced as part of the Certificate System configuration; when the Certificate System subsystem is configured, a new database is created within the Directory Server. This database is used as an embedded database exclusively by the Certificate System instance and can be managed using directory management tools that come with the Directory Server.
The Certificate System instance database is listed with the other Directory Server databases in the serverRoot/slapd-DS_name/db/ directory. These databases are named by the value determined by the value of the pki_ds_database variable under the specified subsystem section within the /etc/pki/default.cfg file (CS_instance_name-CA, CS_instance_name-KRA, CS_instance_name-OCSP, CS_instance_name-TKS, and CS_instance_name-TPS by default), which is the default format given during the instance configuration. For example, for a Certificate Manager named ca1, the database name would be ca1-CA. Similarly, the database name is determined by the value of the pki_ds_base_dn variable under the specified subsystem section within the /etc/pki/default.cfg file ((o=CS_instance_name-CA, o=CS_instance_name-KRA, o=CS_instance_name-OCSP, o=CS_instance_name-TKS, or o=CS_instance_name-TPS by default), and is also set during the configuration.
The subsystems use the database for storing different objects. A Certificate Manager stores all the data, certificate requests, certificates, CRLs, and related information, while a KRA only stores key records and related data.

Warning

The internal database schema are configured to store only Certificate System data. Do not make any changes to it or configure the Certificate System to use any other LDAP directory. Doing so can result in data loss.
Additionally, do not use the internal LDAP database for any other purpose.

13.5.1. Changing the Internal Database Configuration

To change the Directory Server instance that a subsystem instance uses as its internal database:
  1. Log into the subsystem administrative console. 
    pkiconsole https://server.example.com:admin_port/subsystem_type
  2. In the Configuration tab, select the Internal Database tab.
  3. Change the Directory Server instance by changing the hostname, port, and bind DN fields.
    The hostname is the fully qualified hostname of the machine on which the Directory Server is installed, such as certificates.example.com. The Certificate System uses this name to access the directory.
    By default, the hostname of the Directory Server instance used as the internal database is shown as localhost instead of the actual hostname. This is done to insulate the internal database from being visible outside the system since a server on localhost can only be accessed from the local machine. Thus, the default configuration minimizes the risk of someone connecting to this Directory Server instance from outside the local machine.
    The hostname can be changed to something other than localhost if the visibility of the internal database can be limited to a local subnet. For example, if the Certificate System and Directory Server are installed on separate machines for load balancing, specify the hostname of the machine in which the Directory Server is installed.
    The port number is the TCP/IP port used for non-SSL communications with the Directory Server.
    The DN should be the Directory Manager DN. The Certificate System subsystem uses this DN when it accesses the directory tree to communicate with the directory.
  4. Click Save.
    The configuration is modified. If the changes require restarting the server, a prompt appears with that message. In that case, restart the server.

13.5.2. Using a Certificate Issued by Certificate System in Directory Server

To use an encrypted connection to Directory Server when you installed Certificate System, it was necessary to either use a certificate issued by an external Certificate Authority (CA) or a self-signed certificate. However, after setting up the Certificate System CA, administrators often want to replace this certificate with one issued by Certificate System.
To replace the TLS certificate used by Directory Server with a certificate issued by Certificate System:
  1. On the Directory Server host:
    1. Stop the Directory Server instance: 
      # systemctl stop dirsrv@instance_name
    2. Generate a Certificate Signing Request (CSR).
      For example, to generate a CSR which uses 2048 bit RSA encryption, and to store it in the ~/ds.csr file: 
      # PKCS10Client -d /etc/dirsrv/slapd-instance_name/ -p password -a rsa -l 2048 -o ~/ds.csr -n "CN=$HOSTNAME"
PKCS10Client: Debug: got token.
PKCS10Client: Debug: thread token set.
PKCS10Client: token Internal Key Storage Token logged in...
PKCS10Client: key pair generated.
PKCS10Client: CertificationRequest created.
PKCS10Client: b64encode completes.
Keypair private key id: -3387b397ebe254b91c5d6c06dc36618d2ea8b7e6

-----BEGIN CERTIFICATE REQUEST-----
...
-----END CERTIFICATE REQUEST-----
PKCS10Client: done. Request written to file: ~/ds.csr
    3. Start the Directory Server instance to enable the CA to process the request: 
      # systemctl start dirsrv@instance_name
    4. Submit the CSR to the Certificate System's CA. For example: 
      # pki -d /etc/dirsrv/slapd-instance_name/ ca-cert-request-submit --profile caServerCert --csr-file ~/ds.csr
-----------------------------
Submitted certificate request
-----------------------------
  Request ID: 13
  Type: enrollment
  Request Status: pending
  Operation Result: success
  2. On the Certificate System host:
    1. Import the CA agent certificate into a Network Security Services (NSS) database to sign the CMC full request:
      1. Create a new directory. For example: 
        # mkdir ~/certs_db/
      2. Initialize the database in the newly created directory: 
        # certutil -N -d ~/certs_db/
      3. Display the serial number of the CA signing certificate: 
        # pki -p 8080 ca-cert-find --name "CA Signing Certificate"
---------------
1 entries found
---------------
Serial Number: 0x87bbe2d
...
      4. Use the serial number from the previous step to download the CA signing certificate into the ~/certs_db/CA.pem file: 
        # pki -p 8080 ca-cert-show 0x87bbe2d --output ~/certs_db/CA.pem
      5. Import the CA signing certificate into the NSS database: 
        # pki -d ~/certs_db/ -c password client-cert-import "CA Certificate" --ca-cert ~/certs_db/CA.pem
      6. Import the agent certificate: 
        # pk12util -d ~/certs_db/ -i ~/.dogtag/instance_name/ca_admin_cert.p12
Enter Password or Pin for "NSS FIPS 140-2 Certificate DB": password
Enter password for PKCS12 file: password
pk12util: PKCS12 IMPORT SUCCESSFUL
    2. Create the Certificate Management over CMS (CMC) request:
      1. Create a configuration file, such as ~/sslserver-cmc-request.cfg, with the following content: 
        # NSS database directory where the CA agent certificate is stored.
dbdir=~/certs_db/

# NSS database password.
password=password

# Token name (default is internal).
tokenname=internal

# Nickname for CA agent certificate.
nickname=caadmin

# Request format: pkcs10 or crmf.
format=pkcs10

# Total number of PKCS10/CRMF requests.
numRequests=1

# Path to the PKCS10/CRMF request.
# The content must be in Base-64 encoded format.
# Multiple files are supported. They must be separated by space.
input=~/ds.csr

# Path for the CMC request.
output=~/sslserver-cmc-request.bin
      2. Create the CMC request: 
        # CMCRequest ~/sslserver-cmc-request.cfg
...
The CMC enrollment request in base-64 encoded format:
...
The CMC enrollment request in binary format is stored in ~/sslserver-cmc-request.bin
    3. Submit the CMC request:
      1. Create a configuration file, such as ~/sslserver-cmc-submit.cfg, with the following content: 
        # PKI server host name.
host=server.example.com

# PKI server port number.
port=8443

# Use secure connection.
secure=true

# Use client authentication.
clientmode=true

# NSS database directory where the CA agent certificate is stored.
dbdir=~/certs_db/

# NSS database password.
password=password

# Token name (default: internal).
tokenname=internal

# Nickname of CA agent certificate.
nickname=caadmin

# CMC servlet path
servlet=/ca/ee/ca/profileSubmitCMCFull?profileId=caCMCserverCert

# Path for the CMC request.
input=~/sslserver-cmc-request.bin

# Path for the CMC response.
output=~/sslserver-cmc-response.bin
      2. Submit the request: 
        # HttpClient sslserver-cmc-submit.cfg
...
The response in binary format is stored in
~/sslserver-cmc-response.bin
      3. Optionally, verify the result: 
        # CMCResponse -d ~/certs_db/ -i ~/sslserver-cmc-response.bin
...
Number of controls is 1
Control #0: CMCStatusInfoV2
   OID: {1 3 6 1 5 5 7 7 25}
   BodyList: 1
   Status: SUCCESS
    4. Display the serial number of the Directory Server certificate: 
      # pki -p 8080 ca-cert-find --name "DS Certificate"
---------------
1 entries found
---------------
Serial Number: 0xc3eeb0c
...
    5. Use the serial number from the previous step to download the certificate: 
      # pki -p 8080 ca-cert-show 0xc3eeb0c --output ~/ds.crt
    6. Copy the certificate for Directory Server and the CA certificate to the Directory Server host. For example: 
      # scp ~/ds.crt ~/certs_db/CA.pem ds.example.com:~/
    7. Stop Certificate System: 
      # systemctl stop pki-tomcatd@instance_name.service
  3. On the Directory Server host:
    1. Stop the Directory Server instance: 
      # systemctl stop dirsrv@instance_name
    2. Replace the certificates. For details, see the corresponding sections in the Red Hat Directory Server Administration Guide:
      1. Remove the old certificate and CA certificate. See Removing a Certificate.
      2. Install the CA certificate issued by Certificate System. See Installing a CA Certificate.
      3. Install the certificate for Directory Server issued by Certificate System. See Installing a Certificate.
    3. Start the Directory Server instance: 
      # systemctl start dirsrv@instance_name
  4. Start Certificate System: 
    # systemctl stop pki-tomcatd@instance_name.service
  5. Optionally, configure certificate-based authentication. For details, see Section 13.5.3, “Enabling SSL/TLS Client Authentication with the Internal Database”.

13.5.3. Enabling SSL/TLS Client Authentication with the Internal Database

Client authentication allows one entity to authenticate to another entity by presenting a certificate. This method of authentication is used by Certificate System agents to log into agent services pages, for example.
To use an SSL/TLS connection between a Certificate System instance and the LDAP directory instance that it uses as its internal database, client authentication must be enabled to allow the Certificate System instance to authenticate and bind to the LDAP directory.
There are two parts to setting up client authentication. The first is configuring the LDAP directory, such as setting up SSL/TLS and setting ACIs to control the Certificate System instance access. The second is creating a user on the Certificate System instance which it will use to bind to the LDAP directory and setting up its certificate.
To configure LDAPS for a PKI instance, see the pkispawn(8) man page (Example: Installing a PKI subsystem with a secure LDAP connection).

13.5.4. Restricting Access to the Internal Database

The Red Hat Directory Server Console displays an entry or icon for the Directory Server instance that the Certificate System uses as its internal database.
Unlike the Certificate System Console, in which access is restricted to users with Certificate System administrator privileges, the Directory Server Console can be accessed by any user. The user can open the Directory Server Console for the internal database and change to the data stored there, such as deleting users from the Certificate System administrators group or adding his own entry to the group.
Access can be restricted to the internal database to only those users who know the Directory Manager DN and password. This password can be changed by modifying the single sign-on password cache.
  1. Log into the Directory Server Console.
  2. Select the Certificate System internal database entry, and click Open.
  3. Select the Configuration tab.
  4. In the navigation tree, expand Plug-ins, and select Pass-Through Authentication.
  5. In the right pane, deselect the Enable plugin checkbox.
  6. Click Save.
    The server prompts to restart the server.
  7. Click the Tasks tab, and click Restart the Directory Server.
  8. Close the Directory Server Console.
  9. When the server is restarted, open the Directory Server Console for the internal database instance.
    The Login to Directory dialog box appears; the Distinguished Name field displays the Directory Manager DN; enter the password.
    The Directory Server Console for the internal database opens only if the correct password is entered.