Package 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 simple interface for creatingSSLContext
andSSLSocketFactory
instances, which may be used to create SSL-based connections, or secure existing connections with StartTLS. Support for the TLSv1, TLSv1.1, TLSv1.2, and TLSv1.3 protocols will be enabled by default (if the JVM supports them), with TLSv1.3 being the preferred protocol.
Example 1
The following example demonstrates the use of the SSL helper to create an SSL-based LDAP connection that will blindly trust any certificate that the server presents. Using theTrustAllTrustManager
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();
Example 2
The following example demonstrates the use of the SSL helper to create a non-secure LDAP connection and then use the StartTLS extended operation to secure it. It will use a trust store to determine whether to trust the server certificate.// 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();
-
-
Field Summary
Fields Modifier and Type Field Description static java.lang.String
PROPERTY_DEFAULT_SSL_PROTOCOL
The name of the system property 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 the system property 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 the system property 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 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
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method 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 tocreateSSLContext()
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 tocreateSSLContext()
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.
-
-
-
Field Detail
-
PROPERTY_DEFAULT_SSL_PROTOCOL
public static final java.lang.String PROPERTY_DEFAULT_SSL_PROTOCOL
The name of the system property 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 thesetDefaultSSLProtocol(String)
method.- See Also:
- Constant Field Values
-
PROPERTY_ENABLED_SSL_PROTOCOLS
public static final java.lang.String PROPERTY_ENABLED_SSL_PROTOCOLS
The name of the system property 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 thesetEnabledSSLProtocols(Collection)
method.- See Also:
- Constant Field Values
-
PROPERTY_ENABLED_SSL_CIPHER_SUITES
public static final java.lang.String PROPERTY_ENABLED_SSL_CIPHER_SUITES
The name of the system property 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. This can be overridden via thesetEnabledSSLCipherSuites(Collection)
method.- See Also:
- Constant Field Values
-
SSL_PROTOCOL_TLS_1_3
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
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
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
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
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
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(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 benull
if the default set of trust managers should be used.
-
SSLUtil
public 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. 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 benull
or empty if the default set of trust managers should be used.
-
SSLUtil
public 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.- Parameters:
keyManager
- The key manager to use to obtain certificates to present to the server if requested. It may benull
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 benull
if the default set of trust managers should be used.
-
SSLUtil
public 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.- Parameters:
keyManagers
- The set of key managers to use to obtain certificates to present to the server if requested. It may benull
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 benull
or empty if the default set of trust managers should be used.
-
-
Method Detail
-
getKeyManagers
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
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
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 thegetDefaultSSLProtocol()
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
public javax.net.ssl.SSLContext createSSLContext(java.lang.String protocol) throws java.security.GeneralSecurityException
Creates an initialized SSL context created 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 benull
.- Returns:
- The created SSL context.
- Throws:
java.security.GeneralSecurityException
- If a problem occurs while creating or initializing the SSL context.
-
createSSLContext
public javax.net.ssl.SSLContext createSSLContext(java.lang.String protocol, 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 benull
.provider
- The name of the provider to use for cryptographic operations. It must not benull
.- Returns:
- The created SSL context.
- Throws:
java.security.GeneralSecurityException
- If a problem occurs while creating or initializing the SSL context.
-
createSSLSocketFactory
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 thegetDefaultSSLProtocol()
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
public javax.net.ssl.SSLSocketFactory createSSLSocketFactory(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 benull
.- Returns:
- The created SSL socket factory.
- Throws:
java.security.GeneralSecurityException
- If a problem occurs while creating or initializing the SSL socket factory.
-
createSSLSocketFactory
public javax.net.ssl.SSLSocketFactory createSSLSocketFactory(java.lang.String protocol, 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 benull
.provider
- The name of the provider to use for cryptographic operations. It must not benull
.- Returns:
- The created SSL socket factory.
- Throws:
java.security.GeneralSecurityException
- If a problem occurs while creating or initializing the SSL socket factory.
-
createSSLServerSocketFactory
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 thegetDefaultSSLProtocol()
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
public javax.net.ssl.SSLServerSocketFactory createSSLServerSocketFactory(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 benull
.- 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
public javax.net.ssl.SSLServerSocketFactory createSSLServerSocketFactory(java.lang.String protocol, 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 benull
.provider
- The name of the provider to use for cryptographic operations. It must not benull
.- 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
public static java.lang.String getDefaultSSLProtocol()
Retrieves the SSL protocol string that will be used by calls tocreateSSLContext()
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(java.lang.String defaultSSLProtocol)
Specifies the SSL protocol string that will be used by calls tocreateSSLContext()
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 benull
.
-
getEnabledSSLProtocols
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(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, theSSLSocket.getSupportedProtocols
method will be used to determine which protocols are supported for that socket, and then theSSLSocket.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 isnull
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 benull
or empty to indicate that the JDK-default set of enabled protocols should be used for the socket.
-
applyEnabledSSLProtocols
public static void applyEnabledSSLProtocols(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 ofjavax.net.ssl.SSLSocket
, but it is safe to call for any kind ofjava.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
- IfgetEnabledSSLProtocols()
returns a non-empty set but none of the values in that set are supported by the socket.
-
getEnabledSSLCipherSuites
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(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, theSSLSocket.getSupportedCipherSuites
method will be used to determine which cipher suites are supported for that socket, and then theSSLSocket.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 isnull
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 benull
or empty to indicate that the JDK-default set of enabled cipher suites should be used for the socket.
-
applyEnabledSSLCipherSuites
public static void applyEnabledSSLCipherSuites(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 ofjavax.net.ssl.SSLSocket
, but it is safe to call for any kind ofjava.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 suties.- Throws:
LDAPException
- IfgetEnabledSSLCipherSuites()
returns a non-empty set but none of the values in that set are supported by the socket.
-
certificateToString
public static java.lang.String certificateToString(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 benull
.- Returns:
- A string representation of the provided certificate.
-
certificateToString
public static void certificateToString(java.security.cert.X509Certificate certificate, 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 benull
.buffer
- The buffer to which to append the string representation.
-
-