Directory server instance with the SSL and TLS protocols

Edit online

You can configure a directory server with the SSL and TLS protocols. You must identify and set the available secure communication protocols in your LDAP environment to meet the security requirements.

When you configure a directory server for secure communications, the server uses the TLS 1.2/TLS 1.3 protocol suite or the Start TLS extended operation to secure connections.

In IBM® Verify Directory, Version 11.0.1, you can configure a server for secure communications with the following protocols:

  • SSLv3
  • TLS 1.0
  • TLS 1.1
  • TLS 1.2
  • TLS 1.3
Note: The TLS 1.2 and TLS 1.3 protocols are enabled by default.

SSLv3, TLS 1.0, TLS 1.1, TLS 1.2, or TLS 1.3 protocols

To use the SSLv3, TLS 1.0, TLS 1.1, TLS 1.2, or TLS 1.3 protocol or a combination of these protocols, set the ibm-slapdSecurityProtocol attribute with an appropriate value. You must verify whether the server contains the OIDs for the required protocols before you set the protocols. To verify whether the required OID is present, run a root DSE search with the ibm-supportedCapabilities attribute as the search filter.

Table 1. The protocols and the OID values

The table lists the OID values that are associated with the protocols.
Protocols OID value that is assigned to the ibm-supportedCapabilities attribute
TLS 1.0 1.3.18.0.2.32.102
TLS 1.2 1.3.18.0.2.32.103
TLS 1.2 1.3.18.0.2.32.104
TLS 1.3 1.3.18.0.2.32.111

To set multiple secure communication protocols, run the idsldapmodify command to add multiple entries of the ibm-slapdSecurityProtocol attribute with the protocol values. You must add the ibm-slapdSecurityProtocol attribute in the configuration file under the cn=SSL, cn=Configuration DN entry. If you assign an invalid value to ibm-slapdSecurityProtocol, the server generates an error when the server starts.

To use the protocols, add the appropriate ciphers in the configuration file. You can add multiple ciphers for the protocol by adding the ibm-slapdSslCipherSpec attribute multiple times. Add the appropriate ciphers in the configuration file under the cn=SSL,cn=Configuration entry. If ciphers are not set in the configuration file for the protocols, the server generates an error when the server starts. For more information about the supported protocols and ciphers, see Protocols and ciphers.

If you assign an invalid cipher to ibm-slapdSslCipherSpec, the server generates an error when the server starts. For example, if you add the ibm-slapdSslCipherSpec attribute with a value, HELLO, the server generates the following error and exits: 
GLPSSL009E An incorrect value of HELLO was given for the SSL cipher 
specification.

For the TLS 1.1 protocol, the directory server supports six ciphers from the eight ciphers that are in the configuration file. The RC4-40-MD5 and RC2-40-MD5 ciphers are not supported by the server with the TLS 1.1 protocol. If you set only the RC4-40-MD5 and RC2-40-MD5 ciphers and configure the server with the TLS 1.1 protocol, the server generates an error and exits.

When you configure a directory server to use only the TLS 1.2 protocol, then all other protocols, such as SSLv3, TLS 1.0, and TLS 1.1, are disabled. The directory server ignores the SSLv3, TLS 1.0, or TLS 1.1 supported ciphers that are in the configuration file when you configure the server only with the TLS 1.2 protocol.

When you successfully set the server with the protocols, the root DSE search shows the OIDs that are associated with the protocols in the ibm-enabledCapabilities attribute.

Table 2. Relationship between the ibm-slapdSecurityProtocol attribute, the ibm-slapdSecurity attribute, the secure communication mode, the parameter, and the port

The relationship between the ibm-slapdSecurityProtocol attribute value, the ibm-slapdSecurity attribute value, the mode of secure communication, the parameter to provide with a client utility, and the supported port.
Value of ibm-slapdSecurityProtocol Value of ibm-slapdSecurity Mode of secure communication Secure port with the -Z option Unsecured port with the -Y option
SSLV3 SSL | SSLOnly SSLv3 protocol Yes No
SSLTLS SSLv3 protocol Yes No
TLS Start TLS extended operation No No
SSLTLS Start TLS extended operation No No
TLS10 SSL | SSLOnly TLS 1.0 protocol Yes No
SSLTLS TLS 1.0 protocol Yes No
TLS Start TLS extended operation No Yes
SSLTLS Start TLS extended operation No Yes
TLS11 SSL | SSLOnly TLS 1.1 protocol Yes No
SSLTLS TLS 1.1 protocol Yes No
TLS Start TLS extended operation No Yes
SSLTLS Start TLS extended operation No Yes
TLS12 SSL | SSLOnly TLS 1.2 protocol Yes No
SSLTLS TLS 1.2 protocol Yes No
TLS Start TLS extended operation No Yes
SSLTLS Start TLS extended operation No Yes
TLS13 SSL | SSLOnly TLS 1.3 protocol Yes No
SSLTLS TLS 1.3 protocol Yes No
TLS Start TLS extended operation No Yes
SSLTLS Start TLS extended operation No Yes

A directory server with a key database file that is created with a previous version of GSKit might work with the TLS 1.2 and TLS 1.3 protocols. From the supported TLS 1.2 and TLS 1.3 ciphers, the ciphers that meet the following conditions might work with the existing certificates,

  • The public key of certificates and ciphers are compatible.
  • The signature and hash algorithms of certificates and ciphers are compatible.

The scenarios that require a change in the certificates:

  • To use ciphers with a different public key when compared to the public key in the existing certificate.
  • To use signature and hash algorithms that meet the NIST SP 800-131A guidelines.

If the existing certificates do not meet the SP 800-131A requirement, obtain certificates that meet the requirements.

For more information, see the Key database, Certificate, and Certificate request chapters in the GSKit tool gsk9certutil_64 user guide GSK9_CertUtil_User_Guide../v11/documents/GSK_CertUtil_UserGuide.pdf.

Note: When you configure a server with a key database file with certificates that meet NIST SP 800-131A guidelines, the server does more processing to secure connections with the TLS 1.2 and TLS 1.3 protocols. Therefore, the server might require more processing time to secure connections with the TLS 1.2 and TLS 1.3 protocol.

Directory server startup messages, log messages, and rootDSE result

If you do not set any protocols on a directory server, then the server uses the default protocols for secure communications. The following message shows the default protocols that are set when the server is configured for secure communications. 

GLPSSL039I Secure communication using the TLS12 protocol is enabled.
GLPSSL039I Secure communication using the TLS13 protocol is enabled.

The message is shown during the server startup. The messages are also recorded in the ibmslapd.log file of the directory server instance.

On AIX® and Linux™ systems
The default location of the ibmslapd.log file is instance_home/idsslapd-instance_name/logs directory.
On Windows™ systems
The default location of the ibmslapd.log file is drive\idsslapd-instance_name\logs directory.
When you set ibm-slapdSecurityProtocol with the SSLV3,TLS10,TLS11,TLS12 value in a directory server, the following messages are shown: 
GLPSSL039I Secure communication using the SSLV3 protocol is enabled.
GLPSSL039I Secure communication using the TLS10 protocol is enabled.
GLPSSL039I Secure communication using the TLS11 protocol is enabled.
GLPSSL039I Secure communication using the TLS12 protocol is enabled.
GLPSSL039I Secure communication using the TLS13 protocol is enabled.

For detailed messages on protocols and ciphers, you must check the server trace messages.

You can verify the secure communication protocols that are set on the server by querying for the ibm-slapdSecurityProtocol attribute in the rootDSE result.

Examples

Example 1:
To verify whether a directory server is configured for a secure communication, run the following command:
idsldapsearch -h server.com -p port -s base -b "" objectclass=* security

security=none
If the security attribute is none, the server is not configured for secure communications.
Example 2:
To configure a directory server in FIPS processing mode, run the ldapmodify command. For example,
idsldapmodify -h server.com -p port -D adminDN -w adminPWD
dn: cn=SSL,cn=Configuration
changetype: modify
replace: ibm-slapdSslFIPsProcessingMode
ibm-slapdSslFIPsProcessingMode: true
When you configure a secure server, do not set the ibm-slapdSslFIPsProcessingMode attribute to true unless you want to start the server in FIPS processing mode.
Note: You must restart the directory server and the administration server to apply the changes.
Example 3:
To verify whether a server is in FIPS processing mode, run the idsldapsearch command against the server for the root DSE results. For example,
idsldapsearch -h server.com -p port -s base -b "" objectclass=*\
 ibm-sslfipsprocessingmode

ibm-sslfipsprocessingmode=ON
The ibm-sslfipsprocessingmode attribute is listed when the ibm-slapdSecurity attribute is set to SSL, SSLOnly, or SSLTLS. If the ibm-slapdSecurity attribute is set to TLS, the ibm-sslfipsprocessingmode attribute is not listed in search results.
Example 4:
To verify the protocols that a server supports for secure communications, run the ldapsearch command for the root DSE results. In the search results, check the ibm-slapdSecurityProtocol attribute value. 
idsldapsearh -p port -s base -b "" objectclass=* ibm-slapdSecurityProtocol

ibm-slapdSecurityProtocol=TLS12,TLS13
To verify the secure communication protocols that an administration server supports, run the ldapsearch command for the root DSE result. In the search result, check the admindaemon-securityprotocol attribute value.
idsldapsearch -p admin_port -s base -b "" objectclass=* admindaemon-securityprotocol

admindaemon-securityprotocol=TLS12,TLS13
If the ibm-slapdSecurityProtocol attribute is not set on a directory server with the secure communications protocols, the default protocol values, TLS12,TLS13, are set.
Example 5:
You can also verify the ciphers that a server supports from the server trace. In the server trace file, check for the keyword cipher. To obtain the server trace, run the following commands:
#ldtrc on
#ibmslapd -h 65536 -I dsrdbm01 2>&1 | tee server_trace.txt
Example 6:
To verify the cipher that is used in a handshake, take the following actions for your operating system:
AIX and Linux
  1. Open a ksh or bash shell.
  2. Run the following commands: 
    export LDAP_DEBUG=65535
export LDAP_DEBUG_FILE=/tmp/ldapclient_trace.out

idsldapsearch -h server -p port -Z -K key.kdb \
-P kPWD -s base -b "" objectclass=*  security
Microsoft™ Windows
  1. Access the command prompt.
  2. Run the following commands: 
    set LDAP_DEBUG=65535
set LDAP_DEBUG_FILE=c:\ldapclient_trace.out

idsldapsearch -h server -p port -Z -K key.kdb -P kPWD 
-s base -b "" objectclass=* security