A.2. Using SSL/TLS and Start TLS with LDAP Client Tools

There are three things that must be configured for SSL/TLS connections with LDAP command-line tools:
  • The appropriate environment variables must be set before running the command.
  • The appropriate arguments must be passed with the command to identify the server to which to connect. This requires either -H to specify an LDAP or LDAPI URL or -h and -p to give the fully-qualified domain name and port of the server.

    Note

    The fully-qualified domain name is always required with the -h option. This prevents man-in-the-middle attacks.
  • SSL/TLS must be specified. This can be done by invoking Start TLS with the -Z or -ZZ (force Start TLS) options. Start TLS is described in Section 7.5, “Command-Line Functions for Start TLS”. For example: 
    ldapsearch -D "cn=directory manager" -W -p 389 -h server.example.com -b "dc=example,dc=com" -s sub -x -ZZ "(objectclass=*)"
    Alternatively, this can be done using the LDAPS protocol with -H or using the secure LDAPS port with the -p option. Although using the ldaps protocol is supported, it is deprecated. The recommended method is to use Start TLS.
When using SSL/TLS with LDAP command-line tools for client connections, the appropriate TLS environment variables (Section A.1, “Environment Variables Used with LDAP Client Tools”) must be set in order to access the required security databases and certificates.
To set up system-wide SSL/TLS configuration for LDAP tools, edit the ldap.conf file. To edit per-user SSL/TLS configuration for LDAP tools, edit the $HOME/.ldaprc profile for the specific user. Whichever file is edited, the same configuration parameters need to be set.
  1. Open the ldap.conf file or $HOME/.ldaprc profile. For example: 
    vim /etc/openldap/ldap.conf

    Note

    These parameters can also be set as environment variables. See Table A.1, “LDAP Tools Environment Variables” for the variable names.
  2. Add a line to define the security databases directory location. This is required. 
    TLS_CACERTDIR /etc/dirsrv/slapd-instance_name
  3. Optionally, add lines for the client certificate name and token database password for the Directory Server's NSS security databases. This allows certificate-based client authentication. 
    TLS_CERT Server-Cert
TLS_KEY internal:secret
Once the security databases parameters are set, then SSL connections can be invoked with the LDAP command-line tools. For example, using -ZZ opens a Start TLS connection and forces the use of TLS or the operation fails: 
ldapsearch -D "cn=directory manager" -W -p 389 -h server.example.com -b "dc=example,dc=com" -s sub -x -ZZ "(objectclass=*)"
The -x allows simple (user name/password) binds. Alternatively, use the -Y EXTERNAL option to indicate that an authentication method other than SASL is being used. The -Y EXTERNAL argument can be used with client authentication: 
ldapsearch -H ldaps://server.example.com:636 -b "dc=example,dc=com" -Y EXTERNAL "givenname=Richard"