ldapsearch
The ldapsearch
command-line utility is a 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 table details arguments that are the most useful for TLS-related communication.
Argument | Description | ||
---|---|---|---|
|
Address of the server to which the connection is established |
||
|
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 |
||
|
The tool establishes an initially insecure LDAP connection, which is secured later with the StartTLS extended operation. |
||
|
Path to the trust store that is used when determining whether to trust the certificate chain that the server presents during TLS negotiation. If neither this argument nor the |
||
|
Format for the trust store, which is typically |
||
|
Password that is required to access the contents of the trust store. |
||
|
Path to the file that contains the password that is required to access the contents of the trust store. |
||
|
The tool blindly trusts all TLS certificate chains that are presented to it. Although this argument can prove useful for troubleshooting purposes, it is not recommended for general use. |
||
|
Path to the key store to use if a client certificate chain is presented to the server.
|
||
|
Format for the key store, which is typically |
||
|
Password to access the key store. |
||
|
Path to the file that contains the password necessary to access the key store. |
||
|
Alias of the private key entry in the key store. Use when obtaining the certificate chain to present to the server. |
||
|
The client authenticates with the EXTERNAL SASL mechanism, which typically identifies the client using the certificate chain that is presented during TLS negotiation. |
||
|
The tool activates the low-level TLS-debugging feature that the JVM provides. |
The following command provides an example of the simplest method for testing TLS communication with the PingDirectory server.
Example
$ 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
Trust stores and trust-related arguments
If no trust-related arguments are provided, the tool uses the JVM’s default trust store 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 trust store, 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 trust store instead of being prompted interactively, use the --trustStorePath
argument that points to the appropriate trust store. If you are using a Java Keystore (JKS) trust store, you might not need to provide the trust store password. If you are using a PKCS #12 trust store, you need to provide the trust store password. The following code provides an example.
Example
$ 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
Client certificate chains and key stores
To present a client certificate chain to the server, either 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 key store and its corresponding password. You can also specify the alias of the certificate chain to present, which is recommended if your client key store contains multiple certificates. The following code provides an example.
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 need to further troubleshoot a TLS-related issue
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 Using low-level TLS debugging.