Common arguments for TLS communication

The most useful TLS-related arguments our LDAP tools offer include the following.

Argument Description

Argument	Description
`--hostname <address>`	The address of the server to which the connection should be established.
`--port <port>`	The TCP port of the server to which the connection should be established. 389 is the standard port for non-secure LDAP (or LDAP to be secured with StartTLS) and 636 is the standard port for secure LDAPS, but many deployments use alternate ports (especially non-privileged ports above 1024).
`--useSSL`	Indicates that the tool should establish an LDAPS connection that is secured with TLS.
`--useStartTLS`	Indicates that the tool should establish an initially insecure LDAP connection that is then secured with the StartTLS extended operation.
`--trustStorePath <path>`	The path to a trust store that should be used in the course of determining whether to trust the certificate chain presented by the server during TLS negotiation. If neither this argument nor the `--trustAll` argument is provided, then the tool interactively prompts about whether to trust the server certificate if it is not signed by an issuer in the Java Virtual Machine (JVM’s) default trust store.
`--trustStoreFormat <format>`	The format for the trust store. This is typically be Java KeyStore (JKS) or PKCS12.
`--trustStorePassword <password>`	The password needed to access the contents of the trust store.
`--trustStorePasswordFile <path>`	The path to a file containing the password needed to access the contents of the trust store.
`--trustAll`	Indicates that the tool should blindly trust any TLS certificate chain that is presented to it. This is not recommended for general use, but it can be useful for troubleshooting purposes.
`--keyStorePath <path>`	The path to a key store that should be used if a client certificate chain should be presented to the server. This should typically be omitted unless the server has been configured to require clients to present a certificate or unless you want to use the certificate to authenticate using SASL EXTERNAL.
`--keyStoreFormat <format>`	The format for the key store. It is typically JKS or PKCS12.
`--keyStorePassword <password>`	The password needed to access the key store.
`--keyStorePasswordFile <path>`	The path to a file containing the password needed to access the key store.
`--certNickname <alias>`	The alias of the private key entry in the key store that should be used to obtain the certificate chain to present to the server.
`--useSASLExternal`	Indicates that the client should authenticate using the EXTERNAL SASL mechanism, which typically identifies the client using the certificate chain that was presented during TLS negotiation.
`--enableSSLDebugging`	Indicates that the tool should enable low-level TLS debugging provided by the JVM.

--hostname <address>

The address of the server to which the connection should be established.

--port <port>

The TCP port of the server to which the connection should be established. 389 is the standard port for non-secure LDAP (or LDAP to be secured with StartTLS) and 636 is the standard port for secure LDAPS, but many deployments use alternate ports (especially non-privileged ports above 1024).

--useSSL

Indicates that the tool should establish an LDAPS connection that is secured with TLS.

--useStartTLS

Indicates that the tool should establish an initially insecure LDAP connection that is then secured with the StartTLS extended operation.

--trustStorePath <path>

The path to a trust store that should be used in the course of determining whether to trust the certificate chain presented by the server during TLS negotiation. If neither this argument nor the --trustAll argument is provided, then the tool interactively prompts about whether to trust the server certificate if it is not signed by an issuer in the Java Virtual Machine (JVM’s) default trust store.

--trustStoreFormat <format>

The format for the trust store. This is typically be Java KeyStore (JKS) or PKCS12.

--trustStorePassword <password>

The password needed to access the contents of the trust store.

--trustStorePasswordFile <path>

The path to a file containing the password needed to access the contents of the trust store.

--trustAll

Indicates that the tool should blindly trust any TLS certificate chain that is presented to it. This is not recommended for general use, but it can be useful for troubleshooting purposes.

--keyStorePath <path>

The path to a key store that should be used if a client certificate chain should be presented to the server. This should typically be omitted unless the server has been configured to require clients to present a certificate or unless you want to use the certificate to authenticate using SASL EXTERNAL.

--keyStoreFormat <format>

The format for the key store. It is typically JKS or PKCS12.

--keyStorePassword <password>

The password needed to access the key store.

--keyStorePasswordFile <path>

The path to a file containing the password needed to access the key store.

--certNickname <alias>

The alias of the private key entry in the key store that should be used to obtain the certificate chain to present to the server.

--useSASLExternal

Indicates that the client should authenticate using the EXTERNAL SASL mechanism, which typically identifies the client using the certificate chain that was presented during TLS negotiation.

--enableSSLDebugging

Indicates that the tool should enable low-level TLS debugging provided by the JVM.

The easiest way to test TLS communication with the PingDirectory server is to use a command like ldapsearch.

$ bin/ldapsearch \
 	--hostname ds1.example.com \
 	--port 636 \
 	--useSSL \
        --trustStorePath config/truststore \
 	--baseDN "" \
 	--scope base \
 	"(objectClass=*)"
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 you don’t provide any trust-related arguments, then the tool automatically checks each of the following to determine whether it can trust the certificate chain that the server presented:

The config/truststore file for the local instance
The certificates defined in the local instance’s topology registry
The JVM’s default trust store

If the presented certificate chain can be trusted through one of those mechanisms, then the tool establishes the connection without the need for any further interaction. However, if the certificate chain is still not trusted after checking each of those locations, then the tool displays information about that certificate chain and interactively prompts to determine if it should be trusted.

If you want to ensure that the tool does not prompt about whether to trust the certificate chain, then provide trust-related arguments like --trustStorePath. If the certificate chain cannot be trusted using the information in the provided trust store, then the tool exits with an error.

If you want to present a client certificate chain to the server (for example, because the server’s connection handler has been configured with an ssl-client-auth-policy value of required, or because you want to use the certificate to authenticate using the SASL EXTERNAL mechanism), then you must provide at least the key store and its corresponding password. You can also specify the alias of the certificate chain to present, which you should probably do if your client key store contains multiple certificates.

$ 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 \
     --saslOption mech=EXTERNAL \
     --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 at any point you encounter a TLS-related problem that you can’t figure out by looking at the ldapsearch output or server logs, then you can try using the --enableSSLDebugging option. This enables the JVM’s support for low-level debugging of TLS processing, as described in the next section.