12.6. 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 default in the format hostname-CS_instance_ID, which is the default format given during the instance configuration. For example, for a Certificate Manager named ca1, the database name would be host.example.com-ca1. The database name can be anything, depending on the name given 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 DRM 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.

12.6.1. Changing the Internal Database Configuration

To change the Directory Server instance that a subsystem instance uses as its internal database:

Log into the subsystem administrative console.

pkiconsole https://server.example.com:admin_port/subsystem_type

In the Configuration tab, select the Internal Database tab.
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.
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.

12.6.2. Enabling SSL 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 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 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.

Set up the Red Hat Directory Server database to run in SSL.
1. Request and install a server certificate for the Directory Server instance. This is covered in section 12.2, "Obtaining and Installing Server Certificates," in the Directory Server Administrator's Guide.
2. Configure the Directory Server instance to run over its SSL port. This is covered in section 12.4.1, "Enabling TLS/SSL in the Only Directory Server," in the Directory Server Administrator's Guide.
TIP
When SSL is enabled, the server prompts for a password to access the NSS security token for the Directory Server every time the instance is started or restarted. You can create a password file that contains the NSS token database password, and the server can automatically read that file so that it proceed without prompting for the password.
This is covered in the Directory Server Administrator's Guide in section 12.4.3, "Creating a Password File for the Directory Server."

If necessary, create the user on the Directory Server database that the Certificate System instance will used to authenticate to the internal database. For example:

ldapmodify -a -D "cn=Directory Manager" -w secret -p 389 -h server.example.com -x

dn: uid=SSLuser,ou=People, dc=server.example.com-instance-name    
objectclass: person
objectclass: inetorgperson
objectclass: top
uid: SSLuser
cn: SSLuser
email: admin@example.com
userPassword: secret

Adding users using ldapmodify or using the Directory Server Console is described in the Directory Server Administrator's Guide.

Set two ACIs for the Certificate System user (SSLuser), one on the data directory and one on the database plug-in instance.
1. Open the Directory Server Console.
```
redhat-idm-console
```
2. Select the Directory tab.
3. Select the instance's database, which will have a name like server.example.com-instance-name, and right-click.
4. Select Set Access Permissions from the drop-down menu.
5. In the bottom left of the Access Control Editor window, click the Edit Manually button.
6. Paste in the following ACI (with the appropriate LDAP URL for the target and the appropriate user DN).
```
(targetattr = "*") 
(version 3.0;
acl "Unnamed ACI>";
allow (all)
(userdn = "ldap:///uid=SSLuser,ou=People, dc=server.example.com-instance-name");)
```
7. Save the ACI.
8. Select the Configuration tab, and expand the Plugins folder.
9. Under the Plugins folder, expand the ldbm database folder, and select the plug-in instance for the Certificate System subsystem instance. This will have a name like server.example.com-instance-name.
10. Select Set Access Permissions from the drop-down menu.
11. In the bottom left of the Access Control Editor window, click the Edit Manually button.
12. Paste in the following ACI (with the appropriate LDAP URL for the target and the appropriate user DN).
```
(targetattr = "*") 
(version 3.0;
acl "Unnamed ACI>";
allow (read,compare,search)
(userdn = "ldap:///uid=SSLuser,ou=People, dc=server.example.com-instance-name");)
```
Request, approve, and import a user certificate for the SSLuser as described in Section 4.3.1, “Requesting and Receiving a User or Agent Certificate through the End-Entities Page”. Be sure to set the UID component to SSLuser and the OU component to People, so that the subject DN is UID=SSLuser,OU=People.
In the web browser, export the certificate from the browser's database into a PKCS #12 file. The procedure may vary, depending on the type of browser being used. In Mozilla Firefox:
1. Open the Tools menu, and select Options.
2. Open the Advanced tab, and select Encryption.
3. Click the View Certificates button.
4. In the Your Certificates tab, select the SSLuser user certificate, and click the Backup ... button.
5. Save the certificate to a file, like SSLuser.p12.
Stop the Certificate System instance.
```
service instance_name stop
```

Import the user certificate into the Certificate System subsystem instance's security database.

A password is required to access the security database. This password is located in the password.conf file.
```
cat /var/lib/instance_name/conf/password.conf
internal:195450686822
```
Import the PKCS #12 key and certificate into the security database using the pk12util command.
```
pk12util -d /var/lib/instance_name/alias -i /tmp/SSLuser.p12
```

Use certutil to verify that the certificate was properly installed. For example:

certutil -d /var/lib/instance_name/alias -L

 Certificate Nickname                        Trust Attributes
                                                          SSL,S/MIME,JAR/XPI
 's Example Domain u,u,u    
 subsystemCert cert-instance_name                   u,u,u
 Server-Cert cert-instance_name                     u,u,u
 auditSigningCert cert-instance_name                u,u,u

TIP

The nickname for user certificates is frequently blank or not friendly. To change the nickname of the certificate, re-import it with a specified nickname:

certutil -d /var/lib/instance_name/alias -D -n "'s Example Domain" 
certutil -d /var/lib/instance_name/alias -A -i /tmp/SSLuser.p12 -t u,u,u -n "SSLuser certificate"

Create the corresponding SSLuser user entry in the Certificate System subsystem instance, and import the user certificate into the user entry. This is covered in Section 13.4.2.1, “Creating Users” and in Section 13.6.2, “Adding Users” for the TPS.
Open the subsystem configuration directory.
```
cd /var/lib/instance_name/conf
```
Open the CS.cfg file.

Edit the following lines to the indicated values:

internaldb._000=##
internaldb._001=## Internal Database
internaldb._002=##
internaldb.basedn=dc=server.example.com-instance_name    
internaldb.database=server.example.com-instance_name     
internaldb.maxConns=15
internaldb.minConns=3
internaldb.ldapauth.authtype=SslClientAuth
internaldb.ldapauth.bindDN=cn=Directory Manager
internaldb.ldapauth.bindPWPrompt=Internal LDAP Database
internaldb.ldapauth.clientCertNickname=user_certificate_nickname    
internaldb.ldapconn.host=LDAP_host    
internaldb.ldapconn.port=SSL_port    
internaldb.ldapconn.secureConn=true
internaldb.multipleSuffix.enable=false

Start the Certificate System instance.
```
service instance_name start
```

12.6.3. 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.

Log into the Directory Server Console.
Select the Certificate System internal database entry, and click Open.
Select the Configuration tab.
In the navigation tree, expand Plug-ins, and select Pass-Through Authentication.
In the right pane, deselect the Enable plugin checkbox.
Click Save.
The server prompts to restart the server.
Click the Tasks tab, and click Restart the Directory Server.
Close the Directory Server Console.
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.