@ThreadSafety(level=COMPLETELY_THREADSAFE) public final class SSLUtil extends java.lang.Object
SSLContext
and
SSLSocketFactory
instances, which may be used to create SSL-based
connections, or secure existing connections with StartTLS. By default, only
the TLSv1.2 and TLSv1.3 (if supported by the JVM) will be enabled, with the
higher protocol version being the default and preferred for use. The TLSv1.1
or TLSv1 protocol will only be enabled if the JVM does not support either
TLSv1.2 or TLSv1.3.
TrustAllTrustManager
is only recommended
for testing purposes, since blindly trusting any certificate is not secure.
// Create an SSLUtil instance that is configured to trust any certificate, // and use it to create a socket factory. SSLUtil sslUtil = new SSLUtil(new TrustAllTrustManager()); SSLSocketFactory sslSocketFactory = sslUtil.createSSLSocketFactory(); // Establish a secure connection using the socket factory. LDAPConnection connection = new LDAPConnection(sslSocketFactory); connection.connect(serverAddress, serverSSLPort); // Process operations using the connection.... RootDSE rootDSE = connection.getRootDSE(); connection.close();
// Establish a non-secure connection to the server. LDAPConnection connection = new LDAPConnection(serverAddress, serverPort); // Create an SSLUtil instance that is configured to trust certificates in // a specified trust store file, and use it to create an SSLContext that // will be used for StartTLS processing. SSLUtil sslUtil = new SSLUtil(new TrustStoreTrustManager(trustStorePath)); SSLContext sslContext = sslUtil.createSSLContext(); // Use the StartTLS extended operation to secure the connection. StartTLSExtendedRequest startTLSRequest = new StartTLSExtendedRequest(sslContext); ExtendedResult startTLSResult; try { startTLSResult = connection.processExtendedOperation(startTLSRequest); } catch (LDAPException le) { startTLSResult = new ExtendedResult(le); } LDAPTestUtils.assertResultCodeEquals(startTLSResult, ResultCode.SUCCESS); // Process operations using the connection.... RootDSE rootDSE = connection.getRootDSE(); connection.close();
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 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.
|
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.
|
@NotNull public static final java.lang.String PROPERTY_DEFAULT_SSL_PROTOCOL
setDefaultSSLProtocol(String)
method.@NotNull public static final java.lang.String PROPERTY_ENABLED_SSL_PROTOCOLS
setEnabledSSLProtocols(Collection)
method.@NotNull public static final java.lang.String PROPERTY_ENABLED_SSL_CIPHER_SUITES
TLSCipherSuiteSelector
. This can be overridden via the
setEnabledSSLCipherSuites(Collection)
method.@NotNull public static final java.lang.String SSL_PROTOCOL_TLS_1_3
@NotNull public static final java.lang.String SSL_PROTOCOL_TLS_1_2
@NotNull public static final java.lang.String SSL_PROTOCOL_TLS_1_1
@NotNull public static final java.lang.String SSL_PROTOCOL_TLS_1
@NotNull public static final java.lang.String SSL_PROTOCOL_SSL_3
@NotNull public static final java.lang.String SSL_PROTOCOL_SSL_2_HELLO
public SSLUtil()
public SSLUtil(@Nullable javax.net.ssl.TrustManager trustManager)
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.public SSLUtil(@Nullable javax.net.ssl.TrustManager[] trustManagers)
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.public SSLUtil(@Nullable javax.net.ssl.KeyManager keyManager, @Nullable javax.net.ssl.TrustManager trustManager)
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.public SSLUtil(@Nullable javax.net.ssl.KeyManager[] keyManagers, @Nullable javax.net.ssl.TrustManager[] trustManagers)
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.@Nullable public javax.net.ssl.KeyManager[] getKeyManagers()
null
if none were provided.@Nullable public javax.net.ssl.TrustManager[] getTrustManagers()
null
if none were provided.@NotNull public javax.net.ssl.SSLContext createSSLContext() throws java.security.GeneralSecurityException
getDefaultSSLProtocol()
method and the JVM-default provider.java.security.GeneralSecurityException
- If a problem occurs while creating or
initializing the SSL context.@NotNull public javax.net.ssl.SSLContext createSSLContext(@NotNull java.lang.String protocol) throws java.security.GeneralSecurityException
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
.java.security.GeneralSecurityException
- If a problem occurs while creating or
initializing the SSL context.@NotNull public javax.net.ssl.SSLContext createSSLContext(@NotNull java.lang.String protocol, @NotNull java.lang.String provider) throws java.security.GeneralSecurityException
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
.java.security.GeneralSecurityException
- If a problem occurs while creating or
initializing the SSL context.@NotNull public javax.net.ssl.SSLSocketFactory createSSLSocketFactory() throws java.security.GeneralSecurityException
getDefaultSSLProtocol()
method and the JVM-default provider.java.security.GeneralSecurityException
- If a problem occurs while creating or
initializing the SSL socket factory.@NotNull public javax.net.ssl.SSLSocketFactory createSSLSocketFactory(@NotNull java.lang.String protocol) throws java.security.GeneralSecurityException
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
.java.security.GeneralSecurityException
- If a problem occurs while creating or
initializing the SSL socket factory.@NotNull public javax.net.ssl.SSLSocketFactory createSSLSocketFactory(@NotNull java.lang.String protocol, @NotNull java.lang.String provider) throws java.security.GeneralSecurityException
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
.java.security.GeneralSecurityException
- If a problem occurs while creating or
initializing the SSL socket factory.@NotNull public javax.net.ssl.SSLServerSocketFactory createSSLServerSocketFactory() throws java.security.GeneralSecurityException
getDefaultSSLProtocol()
method and the JVM-default provider.java.security.GeneralSecurityException
- If a problem occurs while creating or
initializing the SSL server socket
factory.@NotNull public javax.net.ssl.SSLServerSocketFactory createSSLServerSocketFactory(@NotNull java.lang.String protocol) throws java.security.GeneralSecurityException
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
.java.security.GeneralSecurityException
- If a problem occurs while creating or
initializing the SSL server socket
factory.@NotNull public javax.net.ssl.SSLServerSocketFactory createSSLServerSocketFactory(@NotNull java.lang.String protocol, @NotNull java.lang.String provider) throws java.security.GeneralSecurityException
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
.java.security.GeneralSecurityException
- If a problem occurs while creating or
initializing the SSL server socket
factory.@NotNull public static java.lang.String getDefaultSSLProtocol()
createSSLContext()
that do not explicitly specify which protocol
to use.public static void setDefaultSSLProtocol(@NotNull java.lang.String defaultSSLProtocol)
createSSLContext()
that do not explicitly specify which protocol
to use.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
.@NotNull public static java.util.Set<java.lang.String> getEnabledSSLProtocols()
public static void setEnabledSSLProtocols(@Nullable java.util.Collection<java.lang.String> enabledSSLProtocols)
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.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.public static void applyEnabledSSLProtocols(@NotNull java.net.Socket socket) throws LDAPException
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.socket
- The socket on which to apply the configured set of enabled
SSL protocols.LDAPException
- If getEnabledSSLProtocols()
returns a
non-empty set but none of the values in that set
are supported by the socket.@NotNull public static java.util.Set<java.lang.String> getEnabledSSLCipherSuites()
public static void setEnabledSSLCipherSuites(@Nullable java.util.Collection<java.lang.String> enabledSSLCipherSuites)
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.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.public static void applyEnabledSSLCipherSuites(@NotNull java.net.Socket socket) throws LDAPException
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.socket
- The socket on which to apply the configured set of enabled
SSL cipher suites.LDAPException
- If getEnabledSSLCipherSuites()
returns a
non-empty set but none of the values in that set
are supported by the socket.@NotNull public static java.lang.String certificateToString(@NotNull java.security.cert.X509Certificate certificate)
certificate
- The certificate for which to generate the string
representation. It must not be null
.public static void certificateToString(@NotNull java.security.cert.X509Certificate certificate, @NotNull java.lang.StringBuilder buffer)
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.