The ldapsearch command-line utility is a simple but powerful tool for issuing searches against an LDAP directory server. It also provides a convenient method for troubleshooting a variety of issues, including problems that are relevant to TLS communication.

The following arguments for TLS-related communication are the most useful:

  • --hostname {address} – Address of the server to which the connection is established.
  • --port {port} – TCP port of the server to which the connection is established. The standard port for non-secure LDAP (or LDAP to be secured with StartTLS) is 389, and the standard port for secure LDAPS is 636. However, many deployments use alternate ports, especially non-privileged ports above 1024.
  • --useSSL – Indicates that the tool establishes an initially insecure LDAP connection, which is secured later with the StartTLS extended operation.
  • --trustStorePath {path} – Path to the truststore that is used during the course of determining whether to trust the certificate chain that the server presents during TLS negotiation. If neither this argument nor the --trustAll argument is provided, the tool prompts you interactively about whether to trust server certificated that are not signed by an issuer in the JVM's default truststore.
  • --trustStoreFormat {format} – Format for the truststore, which is typically JKS or PKCS12.
  • --trustStorePassword {password} – Password that is needed to access the contents of the truststore.
  • --trustStorePasswordFile {path} – Path to the file that contains the password that is needed to access the contents of the truststore.
  • --trustAll – Indicates that the tool blindly trusts all TLS certificate chains that are presented to it. Although this argument can prove useful for troubleshooting purposes, we do not recommended it for general use.
  • --keyStorePath {path} – Path to the keystore to use if a client certificate chain is presented to the server. Use this argument only when one of the following conditions is satisfied:

    • The server is configured to require clients to present a certificate.
    • You intend to use the certificate to authenticate through SASL EXTERNAL.
  • --keyStoreFormat {format} – Format for the keystore, which is typically JKS or PKCS12.
  • --keyStorePassword {password} – Password that is needed to access the keystore.
  • --keyStorePasswordFile {path} – Path to the file that contains the password necessary to access the keystore.
  • --certNickname {alias} – Alias of the private key entry in the keystore to use when obtaining the certificate chain to present to the server.
  • --useSASLExternal – Indicates that the client authenticates with the EXTERNAL SASL mechanism, which typically identifies the client using the certificate chain that is presented during TLS negotiation.
  • --enableSSLDebugging – Indicates that the tool is expected to enable the low-level TLS-debugging feature that the JVM provides.

The following command represents the simplest method for testing TLS communication with PingDirectory Server:

$ bin/ldapsearch \
     --hostname ds1.example.com \
     --port 636 \
     --useSSL \
     --baseDN "" \
     --scope base \
     "(objectClass=*)"
The server presented the following certificate chain:
 
     Subject: CN=ds1.example.com,O=Example Corp,C=US
     Valid From: Tuesday, November 12, 2019 at 08:28:08 PM CST
     Valid Until: Wednesday, November 11, 2020 at 08:28:08 PM CST
     SHA-1 Fingerprint: 
        6a:22:2a:bd:0b:1b:09:35:63:bc:12:3e:2c:9e:e7:70:bc:a4:73:de
     256-bit SHA-2 Fingerprint: 
        7a:8c:e4:76:d4:47:15:fd:65:f5:26:0e:d2:55:77:d7:03:7a:e6:79:9f:bc:
        ae:93:2c:76:9c:01:fc:ef:15:38
     -
     Issuer 1 Subject: CN=Example Intermediate CA,O=Example Corp,C=US
     Valid From: Tuesday, November 12, 2019 at 08:28:06 PM CST
     Valid Until: Monday, November 7, 2039 at 08:28:06 PM CST
     SHA-1 Fingerprint: 01:b3:70:8b:6c:11:43:87:3b:e9:bb:73:27:99:ea:fd:08:c4:db:ec
     256-bit SHA-2 Fingerprint: 49:60:69:df:33:9d:26:d0:66:c9:6d:7b:0b:cb:3b:96:
                                40:22:dc:6d:11:32:b7:c0:30:47:d6:7c:6a:19:cd:60
     -
     Issuer 2 Subject: CN=Example Root CA,O=Example Corp,C=US
     Valid From: Tuesday, November 12, 2019 at 08:28:03 PM CST
     Valid Until: Monday, November 7, 2039 at 08:28:03 PM CST
     SHA-1 Fingerprint: b4:83:55:db:82:e4:63:5c:3a:44:13:8f:88:44:e3:60:f2:53:80:48
     256-bit SHA-2 Fingerprint: 
        e8:af:6f:ed:b9:0e:df:94:9c:20:29:53:a9:74:44:a9:17:b4:08:65:c8:19:c1:fb:
        34:34:a1:90:83:8a:d5:12
 
Do you wish to trust this certificate?  Enter 'y' or 'n': y
dn:
objectClass: top
objectClass: ds-root-dse
startupUUID: 8d574122-4584-4522-96d9-0cdcb9d2e339
startTime: 20191113061149Z
 
# Result Code:  0 (success)
# Number of Entries Returned:  1

If no trust-related arguments are provided, the tool uses the JVM's default truststore to verify whether to trust the certificate chain, based on the information that it contains. If a trusted authority has signed the server certificate, the negotiation process continues without further interaction.

If the chain cannot be trusted, based on the information in the JVM-default truststore, ldapsearch prompts you interactively about whether to trust the certificate. If you accept the chain, the client and server complete the negotiation process, and the client sends the search request to the server. If the search succeeds, the server can communicate over TLS.

To test with a truststore instead of being prompted interactively, use the --trustStorePath argument that points to the appropriate truststore. If you are using a JKS truststore, you probably do not need to provide the truststore password. If you are using a PKCS #12 truststore, though, you most likely need to provide the truststore password, as the following example shows:

$ bin/ldapsearch \
     --hostname ds1.example.com \
     --port 636 \
     --useSSL \
     --trustStorePath config/truststore.p12 \
     --trustStorePasswordFile config/truststore.pin \
     --trustStoreFormat PKCS12 \
     --baseDN "" \
     --scope base \
     "(objectClass=*)"
dn:
objectClass: top
objectClass: ds-root-dse
startupUUID: c8724159-8c37-45eb-b210-879bfcf74ad6
startTime: 20191113154023Z
 
# Result Code:  0 (success)
# Number of Entries Returned:  1

To present a client certificate chain to the server – for example, because the server's connection handler is configured with an ssl-client-auth-policy value of required, or because you plan to use the certificate to authenticate by way of the SASL EXTERNAL mechanism – provide at least the keystore and its corresponding password. You can also specify the alias of the certificate chain to present, which is recommended if your client keystore contains multiple certificates.

The following code provides an example:

$ bin/ldapsearch \
     --hostname ds1.example.com \
     --port 636 \
     --useSSL \
     --trustStorePath config/truststore.p12 \
     --trustStorePasswordFile config/truststore.pin \
     --trustStoreFormat PKCS12 \
     --keyStorePath client-keystore \
     --keyStorePasswordFile client-keystore.pin \
     --certNickname client-cert \
     --useSASLExternal \
     --baseDN "" \
     --scope base \
     "(objectClass=*)"
dn:
objectClass: top
objectClass: ds-root-dse
startupUUID: c8724159-8c37-45eb-b210-879bfcf74ad6
startTime: 20191113154023Z
 
# Result Code:  0 (success)
# Number of Entries Returned:  1

If you encounter a TLS-related issue that you cannot resolve by examining the ldapsearch output or the server logs, use the --enableSSLDebugging option to enable the JVM's support for low-level debugging of TLS processing. For more information, see Low-Level TLS Debugging.