11.4. Starting the Server with SSL Enabled
Most of the time, the server should run with SSL enabled. If SSL is temporarily disabled, re-enable it before processing transactions that require confidentiality, authentication, or data integrity.
Before TLS/SSL can be activated, first create a certificate database, obtain and install a server certificate, and trust the CA's certificate, as described in Section 11.2, “Obtaining and Installing Server Certificates”.
With TLS/SSL enabled, when the server restarts, it prompts for the PIN or password to unlock the key database. This is the same password used when the server certificate and key were imported into the database. Restarting the Directory Server without the password prompt is possible by using use a hardware crypto device or creating a PIN file (Section 11.4.3, “Creating a Password File for the Directory Server”).
On SSL-enabled servers, be sure to check the file permissions on certificate database files, key database files, and PIN files to protect the sensitive information they contain. Because the server does not enforce read-only permissions on these files, check the file modes to protect the sensitive information contained in these files.
The files must be owned by the Directory Server user, such as the default nobody. The key and cert databases should be owned by the Directory Server user and should typically have read/write access for the owner with no access allowed to any other user (mode 0600). The PIN file should also be owned by the Directory Server user and set to read-only by this user, with no access to anyone other user (mode 0400).
Obtain and install CA and server certificates.
Set the secure port for the server to use for TLS/SSL communications.
The encrypted port number must not be the same port number used for normal LDAP communications. By default, the standard port number is 389, and the secure port is 636.
Change the secure port number in the Configuration>Settings tab of the Directory Server Console.
Restart the Directory Server. It restarts over the regular port.
In the Directory Server Console, select the Configuration tab, and then select the top entry in the navigation tree in the left pane. Select the Encryption tab in the right pane.
Select the Enable SSL for this Server checkbox.
Check the Use this Cipher Family checkbox.
Select the certificate to use from the drop-down menu.
Click Cipher Settings.
The Cipher Preference dialog box opens. By default, all ciphers are selected.
Set the preferences for client authentication.
Do not allow client authentication. With this option, the server ignores the client's certificate. This does not mean that the bind will fail.
Allow client authentication. This is the default setting. With this option, authentication is performed on the client's request. For more information about certificate-based authentication, see Section 11.6, “Using Certificate-Based Authentication”.
Require client authentication. With this option, the server requests authentication from the client.
If TLS/SSL is only enabled in the Directory Server and not the Directory Server Console, do not select Require client authentication checkbox.
To use certificate-based authentication with replication, the consumer server must be configured either to allow or to require client authentication.
To verify the authenticity of requests, select the Check hostname against name in certificate for outbound SSL connections option. The server does this verification by matching the hostname against the value assigned to the common name (cn) attribute of the subject name in the being presented for authentication.
By default, this feature is disabled. If it's enabled and if the hostname does not match the cn attribute of the certificate, appropriate error and audit messages are logged. For example, in a replicated environment, messages similar to these are logged in the supplier server's log files if it finds that the peer server's hostname doesn't match the name specified in its certificate:
[DATE] - SSL alert: ldap_sasl_bind("",LDAP_SASL_EXTERNAL) 81 (Netscape runtime error -12276 -
Unable to communicate securely with peer: requested domain name does not match the server's
certificate.)
[DATE] NSMMReplicationPlugin - agmt="cn=to ultra60 client auth" (ultra60:1924): Replication
bind with SSL client authentication failed: LDAP error 81 (Can't contact LDAP server)
Red Hat recommends enabling this option to protect Directory Server's outbound SSL connections against a man-in-the-middle (MITM) attack.
Click Save.
Restart the Directory Server. The Directory Server must be restarted from the command line. [13]
service dirsrv restart instance
When the server restarts, it prompts for the PIN or password to unlock the key database. This is the same password used when the server certificate and key were imported into the database.
To restart the Directory Server without the password prompt, create a PIN file or use a hardware crypto device. See Section 11.4.3, “Creating a Password File for the Directory Server” for information on how to create a PIN file.
Obtain server certificates and CA certs, and install them on the Directory Server. This is described in Section 11.2, “Obtaining and Installing Server Certificates”.
Obtain and install server and CA certificates on the Administration Server. This is a similar process as for the Directory Server.
It is important that the Administration Server and Directory Server have a CA certificate in common so that they can trust the other's certificates.
If the default port number of 636 is not used, change the secure port setting.
Change the secure port number in the Configuration>Settings tab of the Directory Server Console, and save.
Restart the Directory Server. It restarts over the regular port. [13]
service dirsrv restart instance
In the Configuration tab of the Directory Server Console, highlight the server name at the top of the table, and select the Encryption tab.
Select the Enable SSL checkbox.
Check the Use this Cipher Family checkbox.
Select the certificate to use from the drop-down menu.
Click Cipher Settings.
The Cipher Preference dialog box opens. By default, all ciphers are selected.
Set the preferences for client authentication.
Do not allow client authentication. With this option, the server ignores the client's certificate. This does not mean that the bind will fail.
Allow client authentication. This is the default setting. With this option, authentication is performed on the client's request. For more information about certificate-based authentication, see Section 11.6, “Using Certificate-Based Authentication”.
Require client authentication. With this option, the server requests authentication from the client.
To use certificate-based authentication with replication, then configure the consumer server either to allow or to require client authentication.
To verify the authenticity of requests, select the Check hostname against name in certificate for outbound SSL connections option. The server does this verification by matching the hostname against the value assigned to the common name (cn) attribute of the subject name in the being presented for authentication.
By default, this feature is disabled. If it's enabled and if the hostname does not match the cn attribute of the certificate, appropriate error and audit messages are logged. For example, in a replicated environment, messages similar to these are logged in the supplier server's log files if it finds that the peer server's hostname doesn't match the name specified in its certificate:
[DATE] - SSL alert: ldap_sasl_bind("",LDAP_SASL_EXTERNAL) 81 (Netscape runtime error -12276 -
Unable to communicate securely with peer: requested domain name does not match the server's
certificate.)
[DATE] NSMMReplicationPlugin - agmt="cn=to ultra60 client auth" (ultra60:1924): Replication
bind with SSL client authentication failed: LDAP error 81 (Can't contact DAP server)
Red Hat recommends enabling this option to protect Directory Server's outbound SSL connections against a man-in-the-middle (MITM) attack.
Check the Use SSL in the Console box. Hit Save.
In the Administration Server Console, select the Configuration tab. Select the Encryption tab, check the Enable SSL checkbox, and fill in the appropriate certificate information.
In the Configuration DS tab, change the port number to the new Directory Server secure port information. See Section 1.5, “Changing Directory Server Port Numbers” for more information. Do this even if the default port of 636 is used. Check the Secure Connection checkbox.
In the User DS tab, select the Set User Directory radio button, and fill in the Directory Server secure port information, the LDAP URL, and the user database information. Check the Secure Connection checkbox.
Save the new SSL settings and Configuration DS and User DS information in the Administration Server Console.
Restart the Directory Server. The server must be restarted from the command line. [13]
service dirsrv restart instance
When the server restarts, it prompts for the PIN or password to unlock the key database. This is the same password used when the server certificate and key were imported into the database.
To restart the Directory Server without the password prompt, create a PIN file or use a hardware crypto device. See Section 11.4.3, “Creating a Password File for the Directory Server” for information on how to create a PIN file.
When next logging into the Directory Server Console, be certain that the address reads https; otherwise, the operation will time out, unable to find the server since it is running on a secure connection. After successfully connecting, a dialog box appears to accept the certificate. Click OK to accept the certificate (either only for that current session or permanently).
It is possible to store the certificate password in a password file. By placing the certificate database password in a file, the server can be started from the Directory Server Console and also restarted automatically when running unattended.
This password is stored in clear text within the password file, so its usage represents a significant security risk. Do not use a password file if the server is running in an unsecured environment.
The password file must be in the same directory where the other key and certificate databases for Directory Server are stored. This is usually the main configuration directory, /etc/dirsrv/slapd-. The file should be named instance_namepin.txt.
Include the token name and password in the file, such as Token:mypassword. For example:
Internal (Software) Token:mypassword
For the NSS software crypto module, the token is always called “Internal (Software) Token”.
The PIN file should be owned by the Directory Server user and set to read-only by the Directory Server user, with no access to anyone other user (mode 0400).
Like the Directory Server, the Administration Server can use a password file during login when SSL is enabled.
This password is stored in clear text within the password file, so its usage represents a significant security risk. Do not use a password file if the server is running in an unsecured environment.
Open the Administration Server configuration directory, /etc/dirsrv/admin-serv.
Create a password file named password.conf. The file should include a line with the token name and password, in the form Token:mypassword. For example:
Internal (Software) Token:mypassword
The password file should be owned by the Administration Server user and set to read-only by the Administration Server user, with no access to any other user (mode 0400).
To find out what the Administration Server user ID is, run grep in the Administration Server configuration directory:
cd /etc/dirsrv/admin-serv grep \^User console.conf
In the /etc/dirsrv/admin-serv directory, edit the nss.conf file to point to the location of the new password file.
# Pass Phrase Dialog: # Configure the pass phrase gathering process. # The filtering dialog program (`builtin' is a internal # terminal dialog) has to provide the pass phrase on stdout. NSSPassPhraseDialog file://///etc/dirsrv/admin-serv/password.conf
Restart the Administration Server. [13]
service dirsrv-admin restart
[13] The commands to start, stop, and restart the Directory Server on platforms other than Red Hat Enterprise Linux is described in Section 1.3, “Starting and Stopping Servers”.