com.unboundid.util.ssl

Class SSLUtil

java.lang.Object

com.unboundid.util.ssl.SSLUtil

@ThreadSafety(level=COMPLETELY_THREADSAFE)
public final class SSLUtil
extends java.lang.Object

This class provides a relatively simple interface for helping to configure secure communication using TLS (formerly known as SSL) and StartTLS (which uses an LDAP extended operation to convert an already-established non-secure connection to one that uses TLS security). When establishing secure connections, there are five main concepts to be aware of:

• The allowed set of TLS protocol versions
• The allowed set of TLS cipher suites
• The key manager (if any) to use for obtaining local certificates
• The trust manager to use for determining whether to trust peer certificates
• The logic used to validate certificate hostnames

Each of these is covered in more detail below.

TLS Protocol Versions

The TLS protocol has evolved over time to improve both security and efficiency, and each update to the protocol has been assigned a version number. At present, only TLSv1.3 and TLSv1.2 are considered secure, and only those versions will be enabled by default, with TLSv1.3 preferred over TLSv1.2. Note that some older JVMs do not support TLSv1.3, and only TLSv1.2 will be enabled by default in that case. In the very unlikely event that the JVM does not support either TLSv1.3 or TLSv1.2, the LDAP SDK may fall back to enabling support for TLSv1.1 or TLSv1.

If you want or need to explicitly specify the TLS protocol versions to use for secure communication, then you may use the setEnabledSSLProtocols(java.util.Collection<java.lang.String>) method to indicate which protocol versions are allowed, and the setDefaultSSLProtocol(java.lang.String) method to indicate which is the preferred protocol version. You can use any TLS protocol version that the underlying JVM supports.

It is also possible to specify the set of enabled and default TLS protocol versions using Java system properties. The com.unboundid.util.SSLUtil.enabledSSLProtocols property may be set with a comma-delimited list of the TLS protocol versions that should be enabled by default, and the com.unboundid.util.SSLUtil.defaultSSLProtocol property may be set with the protocol version that should be preferred. If set, these properties will override the logic that the LDAP SDK automatically uses to select default values, but those defaults may be explicitly overridden by calls to the setEnabledSSLProtocols and setDefaultSSLProtocol methods.

TLS Cipher Suites

A cipher suite encapsulates a number of settings that will be used to actually secure TLS communication between two systems, including which algorithm to use for key exchange, which algorithm to use for bulk encryption, and which algorithm to use for integrity protection. The JVM supports a fixed set of TLS cipher suites, although it may only enable support for a subset of those by default, and the LDAP SDK may further disable support for some of those suites by default for security reasons. The logic that the LDAP SDK uses to select a good default set of TLS cipher suites is encapsulated in the TLSCipherSuiteSelector class, and the class-level documentation for that class describes the criteria that it uses to make its selection.

If you wish to override the LDAP SDK's default selection, you may use the setEnabledSSLCipherSuites(java.util.Collection<java.lang.String>) method to explicitly specify the set of cipher suites that should be enabled. Alternatively, the com.unboundid.util.SSLUtil.enabledSSLCipherSuites system property may be set with a comma-delimited list of the cipher suites that should be enabled.

Key Managers

A key manager is used to obtain access to a certificate chain and private key that should be presented to the peer during TLS negotiation. In the most common use cases, in which the LDAP SDK is used only to establish outbound connections and does not need to use a certificate to authenticate itself to the LDAP server, there won't be any need to present a certificate chain, and there won't be any need to configure a key manager. However, if you are using the LDAP SDK to accept TLS-secured connections from LDAP clients (for example, using the InMemoryDirectoryServer or another type of LDAPListener), if the server requires clients to present their own certificate for mutual TLS authentication, or if you want to use the SASL EXTERNAL mechanism to use a client certificate to authenticate to the server at the LDAP layer, then you will need to specify a key manager to provide access to that certificate chain. The key manager to use for that purpose should be provided in the SSLUtil constructor.

While any javax.net.ssl.KeyManager instance can be used, the LDAP SDK provides three options that will be sufficient for most use cases:

• KeyStoreKeyManager -- Allows the certificate chain and private key to be obtained from a key store file, which will typically be in the JKS or PKCS #12 format (or in the Bouncy Castle BCFKS format when using the LDAP SDK in FIPS 140-2-compliant mode).
• PEMFileKeyManager -- Allows the certificate chain and private key to be obtained from text files that contain the PEM-encoded representation of X.509 certificates and a PKCS #8 private key.
• PKCS11KeyManager -- Allows the certificate chain and private key to be accessed from a PKCS #11 token, like a hardware security module (HSM).

Trust Managers

A trust manager is used to determine whether to trust a certificate chain presented by a peer during TLS negotiation. Trust is a very important aspect of TLS because it's important to make sure that the peer you're communicating with is actually who you intend it to be and not someone else who has managed to hijack the negotiation process.

You will generally always want to provide a trust manager, regardless of whether you're using the LDAP SDK to act as a client or a server, and this trust manager should be provided in the SSLUtil constructor. The LDAP SDK offers several trust manager implementations, including:

• JVMDefaultTrustManager -- Uses the JVM's default cacerts trust store to obtain access to a set of trusted, well-known issuer certificates, including those from commercial certification authorities like Verisign or DigiCert, and from trusted free providers like Let's Encrypt. This trust manager will only accept valid certificates that have been signed by one of those trusted authorities.
• TrustStoreTrustManager -- Uses the information in a trust store file (typically in a format like JKS, PKCS #12 or BCFKS) as a set of trusted certificates and issuers.
• PEMFileTrustManager -- Uses the information one or more files containing the PEM representations of X.509 certificates as a set of trusted certificates and issuers.
• TopologyRegistryTrustManager -- Uses the topology registry information in the configuration of a Ping Identity Directory Server (or related server product) to obtain a set of trusted certificates and issuers.
• PromptTrustManager -- Interactively prompts the user (via the terminal) to determine whether the presented certificate chain should be trusted.
• TrustAllTrustManager -- Blindly trusts all certificate chains that are presented to it. This may be convenient in some cases for testing purposes, but it is strongly discouraged for production use because it does not actually perform any real trust processing and will allow connecting to unintended or malicious peers.
• AggregateTrustManager -- Allows you to combine multiple other trust managers in the course of determining whether to trust a presented certificate chain. For example, you may use this to automatically trust certificates signed by an issuer in the JVM's cacerts file or in an explicitly specified alternative trust store file, but to fall back to interactively prompting the user for certificates not trusted by one of the previous two methods.

Certificate Hostname Validation

Trust managers can be used to ensure that a certificate chain presented by a peer originally came from a trusted source, but that doesn't necessarily mean that the peer system is the one you intend it to be. It's not at all difficult for malicious users and applications to obtain a certificate that is signed by a CA in the JVM's default set of trusted issuers. However, any certificate signed by one of those trusted issuers will include information in a subject alternative name extension that specifies the hostnames (or at least domain names) and IP addresses for systems with which that certificate is allowed to be used, and those issues are careful to verify that they only issue certificates to systems that are legitimately associated with those systems. So while a malicious user may be able to easily get a certificate from a trusted issuer, it should not be possible for them to get a certificate with a subject alternative name extension containing addresses they don't legitimately have the right to use.

Because of this, it's very important that clients not only verify that the server's certificate comes from a trusted source, but also that it's allowed to be used by that server system. This additional level of validation can help thwart attacks that rely on DNS hijacking or other methods of diverting communication away from the intended recipient to one that an attacker controls instead. The LDAP SDK does not perform this validation by default because there are unfortunately too many cases in which clients (especially those used in testing and development environments) might need to interact with a server whose certificate may not have an appropriate subject alternative name extension. However, in production environments with a properly configured TLS certificate, hostname verification can be enabled by calling the LDAPConnectionOptions.setSSLSocketVerifier(com.unboundid.util.ssl.SSLSocketVerifier) method with an instance of the HostNameSSLSocketVerifier. Alternatively, you can set the com.unboundid.ldap.sdk. LDAPConnectionOptions.defaultVerifyCertificateHostnames system property with a value of "true" to enable this validation by default.

Examples

The following example demonstrates the process for establish a secure client connection. It relies on the LDAP SDK's default configuration for selecting TLS protocols and cipher suites, and does not use a key manager. It uses an aggregate trust manager to automatically trust any certificates signed by one of the JVM's default trusted issuers or an issuer in an explicitly specified key store file, and it enables host name validation.

   AggregateTrustManager trustManager = new AggregateTrustManager(false,
        JVMDefaultTrustManager.getInstance(),
        new TrustStoreTrustManager(trustStorePath, trustStorePIN,
             "PKCS12", true));
   SSLUtil sslUtil = new SSLUtil(trustManager);

   LDAPConnectionOptions connectionOptions = new LDAPConnectionOptions();
   connectionOptions.setSSLSocketVerifier(
        new HostNameSSLSocketVerifier(true));

   try (LDAPConnection connection = new LDAPConnection(
             sslUtil.createSSLSocketFactory(), connectionOptions,
             serverAddress, serverLDAPSPort))
   {
     // Use the connection here.
     RootDSE rootDSE = connection.getRootDSE();
   }
 

The above example establishes an LDAPS connection that is secured by TLS as soon as it is created. The following example shows the process needed to use the StartTLS extended operation to secure an already-established non-secure connection:

   AggregateTrustManager trustManager = new AggregateTrustManager(false,
        JVMDefaultTrustManager.getInstance(),
        new TrustStoreTrustManager(trustStorePath, trustStorePIN,
             "PKCS12", true));
   SSLUtil sslUtil = new SSLUtil(trustManager);

   LDAPConnectionOptions connectionOptions = new LDAPConnectionOptions();
   connectionOptions.setSSLSocketVerifier(
        new HostNameSSLSocketVerifier(true));

   try (LDAPConnection connection = new LDAPConnection(
             connectionOptions, serverAddress, serverLDAPPort))
   {
     // Use the StartTLS extended operation to secure the connection.
     ExtendedResult startTLSResult;
     try
     {
       startTLSResult = connection.processExtendedOperation(
            new StartTLSExtendedRequest(
                 sslUtil.createSSLSocketFactory()));
     }
     catch (LDAPException e)
     {
       Debug.debugException(e);
       startTLSResult = new ExtendedResult(e);
     }
     LDAPTestUtils.assertResultCodeEquals(startTLSResult,
          ResultCode.SUCCESS);

     // Use the connection here.
     RootDSE rootDSE = connection.getRootDSE();
   }
 

Field Summary

Fields

Modifier and Type	Field and Description
static java.lang.String	PROPERTY_DEFAULT_SSL_PROTOCOL The name of a system property (com.unboundid.util.SSLUtil.defaultSSLProtocol) that can be used to specify the initial value for the default SSL protocol that should be used.
static java.lang.String	PROPERTY_ENABLED_SSL_CIPHER_SUITES The name of a system property (com.unboundid.util.SSLUtil.enabledSSLCipherSuites) that can be used to provide the initial set of enabled SSL cipher suites that should be used, as a comma-delimited list.
static java.lang.String	PROPERTY_ENABLED_SSL_PROTOCOLS The name of a system property (com.unboundid.util.SSLUtil.enabledSSLProtocols) that can be used to provide the initial set of enabled SSL protocols that should be used, as a comma-delimited list.
static java.lang.String	SSL_PROTOCOL_SSL_2_HELLO The name of the SSL protocol that can be used to request SSLv2Hello.
static java.lang.String	SSL_PROTOCOL_SSL_3 The name of the SSL protocol that can be used to request SSLv3.
static java.lang.String	SSL_PROTOCOL_TLS_1 The name of the SSL protocol that can be used to request TLSv1.
static java.lang.String	SSL_PROTOCOL_TLS_1_1 The name of the SSL protocol that can be used to request TLSv1.1.
static java.lang.String	SSL_PROTOCOL_TLS_1_2 The name of the SSL protocol that can be used to request TLSv1.2.
static java.lang.String	SSL_PROTOCOL_TLS_1_3 The name of the SSL protocol that can be used to request TLSv1.3.

Constructor Summary

Constructors

Constructor and Description
SSLUtil() Creates a new SSLUtil instance that will not have a custom key manager or trust manager.
SSLUtil(javax.net.ssl.KeyManager[] keyManagers, javax.net.ssl.TrustManager[] trustManagers) Creates a new SSLUtil instance that will use the provided key managers to obtain certificates to present to the server, and the provided trust managers to determine whether to trust server certificates presented to the client.
SSLUtil(javax.net.ssl.KeyManager keyManager, javax.net.ssl.TrustManager trustManager) Creates a new SSLUtil instance that will use the provided key manager to obtain certificates to present to the server, and the provided trust manager to determine whether to trust server certificates presented to the client.
SSLUtil(javax.net.ssl.TrustManager trustManager) Creates a new SSLUtil instance that will use the provided trust manager to determine whether to trust server certificates presented to the client.
SSLUtil(javax.net.ssl.TrustManager[] trustManagers) Creates a new SSLUtil instance that will use the provided trust managers to determine whether to trust server certificates presented to the client.

Method Summary

Modifier and Type	Method and Description
static void	applyEnabledSSLCipherSuites(java.net.Socket socket) Updates the provided socket to apply the appropriate set of enabled SSL cipher suites.
static void	applyEnabledSSLProtocols(java.net.Socket socket) Updates the provided socket to apply the appropriate set of enabled SSL protocols.
static java.lang.String	certificateToString(java.security.cert.X509Certificate certificate) Creates a string representation of the provided certificate.
static void	certificateToString(java.security.cert.X509Certificate certificate, java.lang.StringBuilder buffer) Appends a string representation of the provided certificate to the given buffer.
javax.net.ssl.SSLContext	createSSLContext() Creates an initialized SSL context created with the configured key and trust managers.
javax.net.ssl.SSLContext	createSSLContext(java.lang.String protocol) Creates an initialized SSL context created with the configured key and trust managers.
javax.net.ssl.SSLContext	createSSLContext(java.lang.String protocol, java.lang.String provider) Creates an initialized SSL context created with the configured key and trust managers.
javax.net.ssl.SSLServerSocketFactory	createSSLServerSocketFactory() Creates an SSL server socket factory using the configured key and trust manager providers.
javax.net.ssl.SSLServerSocketFactory	createSSLServerSocketFactory(java.lang.String protocol) Creates an SSL server socket factory using the configured key and trust manager providers.
javax.net.ssl.SSLServerSocketFactory	createSSLServerSocketFactory(java.lang.String protocol, java.lang.String provider) Creates an SSL server socket factory using the configured key and trust manager providers.
javax.net.ssl.SSLSocketFactory	createSSLSocketFactory() Creates an SSL socket factory using the configured key and trust manager providers.
javax.net.ssl.SSLSocketFactory	createSSLSocketFactory(java.lang.String protocol) Creates an SSL socket factory with the configured key and trust managers.
javax.net.ssl.SSLSocketFactory	createSSLSocketFactory(java.lang.String protocol, java.lang.String provider) Creates an SSL socket factory with the configured key and trust managers.
static java.lang.String	getDefaultSSLProtocol() Retrieves the SSL protocol string that will be used by calls to createSSLContext() that do not explicitly specify which protocol to use.
static java.util.Set<java.lang.String>	getEnabledSSLCipherSuites() Retrieves the set of SSL cipher suites that will be enabled for use, if available, for SSL sockets created within the LDAP SDK.
static java.util.Set<java.lang.String>	getEnabledSSLProtocols() Retrieves the set of SSL protocols that will be enabled for use, if available, for SSL sockets created within the LDAP SDK.
javax.net.ssl.KeyManager[]	getKeyManagers() Retrieves the set of key managers configured for use by this class, if any.
javax.net.ssl.TrustManager[]	getTrustManagers() Retrieves the set of trust managers configured for use by this class, if any.
static void	setDefaultSSLProtocol(java.lang.String defaultSSLProtocol) Specifies the SSL protocol string that will be used by calls to createSSLContext() that do not explicitly specify which protocol to use.
static void	setEnabledSSLCipherSuites(java.util.Collection<java.lang.String> enabledSSLCipherSuites) Specifies the set of SSL cipher suites that will be enabled for SSL sockets created within the LDAP SDK.
static void	setEnabledSSLProtocols(java.util.Collection<java.lang.String> enabledSSLProtocols) Specifies the set of SSL protocols that will be enabled for use for SSL sockets created within the LDAP SDK.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

PROPERTY_DEFAULT_SSL_PROTOCOL

@NotNull
public static final java.lang.String PROPERTY_DEFAULT_SSL_PROTOCOL

The name of a system property (com.unboundid.util.SSLUtil.defaultSSLProtocol) that can be used to specify the initial value for the default SSL protocol that should be used. If this is not set, then the default SSL protocol will be dynamically determined. This can be overridden via the setDefaultSSLProtocol(String) method.

See Also:

Constant Field Values

PROPERTY_ENABLED_SSL_PROTOCOLS

@NotNull
public static final java.lang.String PROPERTY_ENABLED_SSL_PROTOCOLS

The name of a system property (com.unboundid.util.SSLUtil.enabledSSLProtocols) that can be used to provide the initial set of enabled SSL protocols that should be used, as a comma-delimited list. If this is not set, then the enabled SSL protocols will be dynamically determined. This can be overridden via the setEnabledSSLProtocols(Collection) method.

See Also:

Constant Field Values

PROPERTY_ENABLED_SSL_CIPHER_SUITES

@NotNull
public static final java.lang.String PROPERTY_ENABLED_SSL_CIPHER_SUITES

The name of a system property (com.unboundid.util.SSLUtil.enabledSSLCipherSuites) that can be used to provide the initial set of enabled SSL cipher suites that should be used, as a comma-delimited list. If this is not set, then the enabled SSL cipher suites will be dynamically determined using the TLSCipherSuiteSelector. This can be overridden via the setEnabledSSLCipherSuites(Collection) method.

See Also:

Constant Field Values

SSL_PROTOCOL_TLS_1_3

@NotNull
public static final java.lang.String SSL_PROTOCOL_TLS_1_3

The name of the SSL protocol that can be used to request TLSv1.3.

See Also:

Constant Field Values

SSL_PROTOCOL_TLS_1_2

@NotNull
public static final java.lang.String SSL_PROTOCOL_TLS_1_2

The name of the SSL protocol that can be used to request TLSv1.2.

See Also:

Constant Field Values

SSL_PROTOCOL_TLS_1_1

@NotNull
public static final java.lang.String SSL_PROTOCOL_TLS_1_1

The name of the SSL protocol that can be used to request TLSv1.1.

See Also:

Constant Field Values

SSL_PROTOCOL_TLS_1

@NotNull
public static final java.lang.String SSL_PROTOCOL_TLS_1

The name of the SSL protocol that can be used to request TLSv1.

See Also:

Constant Field Values

SSL_PROTOCOL_SSL_3

@NotNull
public static final java.lang.String SSL_PROTOCOL_SSL_3

The name of the SSL protocol that can be used to request SSLv3.

See Also:

Constant Field Values

SSL_PROTOCOL_SSL_2_HELLO

@NotNull
public static final java.lang.String SSL_PROTOCOL_SSL_2_HELLO

The name of the SSL protocol that can be used to request SSLv2Hello.

See Also:

Constant Field Values

Constructor Detail

SSLUtil

public SSLUtil()

Creates a new SSLUtil instance that will not have a custom key manager or trust manager. It will not be able to provide a certificate to the server if one is requested, and it will only trust certificates signed by a predefined set of authorities.

SSLUtil

public SSLUtil(@Nullable
               javax.net.ssl.TrustManager trustManager)

Creates a new SSLUtil instance that will use the provided trust manager to determine whether to trust server certificates presented to the client. It will not be able to provide a certificate to the server if one is requested.

Parameters:

trustManager - The trust manager to use to determine whether to trust server certificates presented to the client. It may be null if the default set of trust managers should be used.

SSLUtil

public SSLUtil(@Nullable
               javax.net.ssl.TrustManager[] trustManagers)

Creates a new SSLUtil instance that will use the provided trust managers to determine whether to trust server certificates presented to the client. It will not be able to provide a certificate to the server if one is requested.

Parameters:

trustManagers - The set of trust managers to use to determine whether to trust server certificates presented to the client. It may be null or empty if the default set of trust managers should be used.

SSLUtil

public SSLUtil(@Nullable
               javax.net.ssl.KeyManager keyManager,
               @Nullable
               javax.net.ssl.TrustManager trustManager)

Creates a new SSLUtil instance that will use the provided key manager to obtain certificates to present to the server, and the provided trust manager to determine whether to trust server certificates presented to the client.

Parameters:

keyManager - The key manager to use to obtain certificates to present to the server if requested. It may be null if no client certificates will be required or should be provided.

trustManager - The trust manager to use to determine whether to trust server certificates presented to the client. It may be null if the default set of trust managers should be used.

SSLUtil

public SSLUtil(@Nullable
               javax.net.ssl.KeyManager[] keyManagers,
               @Nullable
               javax.net.ssl.TrustManager[] trustManagers)

Creates a new SSLUtil instance that will use the provided key managers to obtain certificates to present to the server, and the provided trust managers to determine whether to trust server certificates presented to the client.

Parameters:

keyManagers - The set of key managers to use to obtain certificates to present to the server if requested. It may be null or empty if no client certificates will be required or should be provided.

trustManagers - The set of trust managers to use to determine whether to trust server certificates presented to the client. It may be null or empty if the default set of trust managers should be used.

Method Detail

getKeyManagers

@Nullable
public javax.net.ssl.KeyManager[] getKeyManagers()

Retrieves the set of key managers configured for use by this class, if any.

Returns:

The set of key managers configured for use by this class, or null if none were provided.

getTrustManagers

@Nullable
public javax.net.ssl.TrustManager[] getTrustManagers()

Retrieves the set of trust managers configured for use by this class, if any.

Returns:

The set of trust managers configured for use by this class, or null if none were provided.

createSSLContext

@NotNull
public javax.net.ssl.SSLContext createSSLContext()
                                                   throws java.security.GeneralSecurityException

Creates an initialized SSL context created with the configured key and trust managers. It will use the protocol returned by the getDefaultSSLProtocol() method and the JVM-default provider.

Returns:

The created SSL context.

Throws:

java.security.GeneralSecurityException - If a problem occurs while creating or initializing the SSL context.

createSSLContext

@NotNull
public javax.net.ssl.SSLContext createSSLContext(@NotNull
                                                          java.lang.String protocol)
                                                   throws java.security.GeneralSecurityException

Creates an initialized SSL context created with the configured key and trust managers. It will use a default provider.

Parameters:

protocol - The SSL protocol to use. The Java Secure Socket Extension (JSSE) Reference Guide provides a list of the supported protocols, but commonly used values are "TLSv1.3", "TLSv1.2", "TLSv1.1", and "TLSv1". This must not be null.

Returns:

The created SSL context.

Throws:

java.security.GeneralSecurityException - If a problem occurs while creating or initializing the SSL context.

createSSLContext

@NotNull
public javax.net.ssl.SSLContext createSSLContext(@NotNull
                                                          java.lang.String protocol,
                                                          @NotNull
                                                          java.lang.String provider)
                                                   throws java.security.GeneralSecurityException

Creates an initialized SSL context created with the configured key and trust managers.

Parameters:

protocol - The SSL protocol to use. The Java Secure Socket Extension (JSSE) Reference Guide provides a list of the supported protocols, but commonly used values are "TLSv1.3", "TLSv1.2", "TLSv1.1", and "TLSv1". This must not be null.

provider - The name of the provider to use for cryptographic operations. It must not be null.

Returns:

The created SSL context.

Throws:

java.security.GeneralSecurityException - If a problem occurs while creating or initializing the SSL context.

createSSLSocketFactory

@NotNull
public javax.net.ssl.SSLSocketFactory createSSLSocketFactory()
                                                               throws java.security.GeneralSecurityException

Creates an SSL socket factory using the configured key and trust manager providers. It will use the protocol returned by the getDefaultSSLProtocol() method and the JVM-default provider.

Returns:

The created SSL socket factory.

Throws:

java.security.GeneralSecurityException - If a problem occurs while creating or initializing the SSL socket factory.

createSSLSocketFactory

@NotNull
public javax.net.ssl.SSLSocketFactory createSSLSocketFactory(@NotNull
                                                                      java.lang.String protocol)
                                                               throws java.security.GeneralSecurityException

Creates an SSL socket factory with the configured key and trust managers. It will use the default provider.

Parameters:

protocol - The SSL protocol to use. The Java Secure Socket Extension (JSSE) Reference Guide provides a list of the supported protocols, but commonly used values are "TLSv1.3", "TLSv1.2", "TLSv1.1", and "TLSv1". This must not be null.

Returns:

The created SSL socket factory.

Throws:

java.security.GeneralSecurityException - If a problem occurs while creating or initializing the SSL socket factory.

createSSLSocketFactory

@NotNull
public javax.net.ssl.SSLSocketFactory createSSLSocketFactory(@NotNull
                                                                      java.lang.String protocol,
                                                                      @NotNull
                                                                      java.lang.String provider)
                                                               throws java.security.GeneralSecurityException

Creates an SSL socket factory with the configured key and trust managers.

Parameters:

protocol - The SSL protocol to use. The Java Secure Socket Extension (JSSE) Reference Guide provides a list of the supported protocols, but commonly used values are "TLSv1.3", "TLSv1.2", "TLSv1.1", and "TLSv1". This must not be null.

provider - The name of the provider to use for cryptographic operations. It must not be null.

Returns:

The created SSL socket factory.

Throws:

java.security.GeneralSecurityException - If a problem occurs while creating or initializing the SSL socket factory.

createSSLServerSocketFactory

@NotNull
public javax.net.ssl.SSLServerSocketFactory createSSLServerSocketFactory()
                                                                           throws java.security.GeneralSecurityException

Creates an SSL server socket factory using the configured key and trust manager providers. It will use the protocol returned by the getDefaultSSLProtocol() method and the JVM-default provider.

Returns:

The created SSL server socket factory.

Throws:

java.security.GeneralSecurityException - If a problem occurs while creating or initializing the SSL server socket factory.

createSSLServerSocketFactory

@NotNull
public javax.net.ssl.SSLServerSocketFactory createSSLServerSocketFactory(@NotNull
                                                                                  java.lang.String protocol)
                                                                           throws java.security.GeneralSecurityException

Creates an SSL server socket factory using the configured key and trust manager providers. It will use the JVM-default provider.

Parameters:

protocol - The SSL protocol to use. The Java Secure Socket Extension (JSSE) Reference Guide provides a list of the supported protocols, but commonly used values are "TLSv1.3", "TLSv1.2", "TLSv1.1", and "TLSv1". This must not be null.

Returns:

The created SSL server socket factory.

Throws:

java.security.GeneralSecurityException - If a problem occurs while creating or initializing the SSL server socket factory.

createSSLServerSocketFactory

@NotNull
public javax.net.ssl.SSLServerSocketFactory createSSLServerSocketFactory(@NotNull
                                                                                  java.lang.String protocol,
                                                                                  @NotNull
                                                                                  java.lang.String provider)
                                                                           throws java.security.GeneralSecurityException

Creates an SSL server socket factory using the configured key and trust manager providers.

Parameters:

protocol - The SSL protocol to use. The Java Secure Socket Extension (JSSE) Reference Guide provides a list of the supported protocols, but commonly used values are "TLSv1.3", "TLSv1.2", "TLSv1.1", and "TLSv1". This must not be null.

provider - The name of the provider to use for cryptographic operations. It must not be null.

Returns:

The created SSL server socket factory.

Throws:

java.security.GeneralSecurityException - If a problem occurs while creating or initializing the SSL server socket factory.

getDefaultSSLProtocol

@NotNull
public static java.lang.String getDefaultSSLProtocol()

Retrieves the SSL protocol string that will be used by calls to createSSLContext() that do not explicitly specify which protocol to use.

Returns:

The SSL protocol string that will be used by calls to create an SSL context that do not explicitly specify which protocol to use.

setDefaultSSLProtocol

public static void setDefaultSSLProtocol(@NotNull
                                         java.lang.String defaultSSLProtocol)

Specifies the SSL protocol string that will be used by calls to createSSLContext() that do not explicitly specify which protocol to use.

Parameters:

defaultSSLProtocol - The SSL protocol string that will be used by calls to create an SSL context that do not explicitly specify which protocol to use. It must not be null.

getEnabledSSLProtocols

@NotNull
public static java.util.Set<java.lang.String> getEnabledSSLProtocols()

Retrieves the set of SSL protocols that will be enabled for use, if available, for SSL sockets created within the LDAP SDK.

Returns:

The set of SSL protocols that will be enabled for use, if available, for SSL sockets created within the LDAP SDK.

setEnabledSSLProtocols

public static void setEnabledSSLProtocols(@Nullable
                                          java.util.Collection<java.lang.String> enabledSSLProtocols)

Specifies the set of SSL protocols that will be enabled for use for SSL sockets created within the LDAP SDK. When creating an SSL socket, the SSLSocket.getSupportedProtocols method will be used to determine which protocols are supported for that socket, and then the SSLSocket.setEnabledProtocols method will be used to enable those protocols which are listed as both supported by the socket and included in this set. If the provided set is null or empty, then the default set of enabled protocols will be used.

Parameters:

enabledSSLProtocols - The set of SSL protocols that will be enabled for use for SSL sockets created within the LDAP SDK. It may be null or empty to indicate that the JDK-default set of enabled protocols should be used for the socket.

applyEnabledSSLProtocols

public static void applyEnabledSSLProtocols(@NotNull
                                            java.net.Socket socket)
                                     throws LDAPException

Updates the provided socket to apply the appropriate set of enabled SSL protocols. This will only have any effect for sockets that are instances of javax.net.ssl.SSLSocket, but it is safe to call for any kind of java.net.Socket. This should be called before attempting any communication over the socket.

Parameters:

socket - The socket on which to apply the configured set of enabled SSL protocols.

Throws:

LDAPException - If getEnabledSSLProtocols() returns a non-empty set but none of the values in that set are supported by the socket.

getEnabledSSLCipherSuites

@NotNull
public static java.util.Set<java.lang.String> getEnabledSSLCipherSuites()

Retrieves the set of SSL cipher suites that will be enabled for use, if available, for SSL sockets created within the LDAP SDK.

Returns:

The set of SSL cipher suites that will be enabled for use, if available, for SSL sockets created within the LDAP SDK.

setEnabledSSLCipherSuites

public static void setEnabledSSLCipherSuites(@Nullable
                                             java.util.Collection<java.lang.String> enabledSSLCipherSuites)

Specifies the set of SSL cipher suites that will be enabled for SSL sockets created within the LDAP SDK. When creating an SSL socket, the SSLSocket.getSupportedCipherSuites method will be used to determine which cipher suites are supported for that socket, and then the SSLSocket.setEnabledCipherSuites method will be used to enable those suites which are listed as both supported by the socket and included in this set. If the provided set is null or empty, then the default set of enabled cipher suites will be used.

Parameters:

enabledSSLCipherSuites - The set of SSL cipher suites that will be enabled for use for SSL sockets created within the LDAP SDK. It may be null or empty to indicate that the JDK-default set of enabled cipher suites should be used for the socket.

applyEnabledSSLCipherSuites

public static void applyEnabledSSLCipherSuites(@NotNull
                                               java.net.Socket socket)
                                        throws LDAPException

Updates the provided socket to apply the appropriate set of enabled SSL cipher suites. This will only have any effect for sockets that are instances of javax.net.ssl.SSLSocket, but it is safe to call for any kind of java.net.Socket. This should be called before attempting any communication over the socket.

Parameters:

socket - The socket on which to apply the configured set of enabled SSL cipher suites.

Throws:

LDAPException - If getEnabledSSLCipherSuites() returns a non-empty set but none of the values in that set are supported by the socket.

certificateToString

@NotNull
public static java.lang.String certificateToString(@NotNull
                                                            java.security.cert.X509Certificate certificate)

Creates a string representation of the provided certificate.

Parameters:

certificate - The certificate for which to generate the string representation. It must not be null.

Returns:

A string representation of the provided certificate.

certificateToString

public static void certificateToString(@NotNull
                                       java.security.cert.X509Certificate certificate,
                                       @NotNull
                                       java.lang.StringBuilder buffer)

Appends a string representation of the provided certificate to the given buffer.

Parameters:

certificate - The certificate for which to generate the string representation. It must not be null.

buffer - The buffer to which to append the string representation.