@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.
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 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_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.
|
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 |
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> |
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 |
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.
|
public static final java.lang.String PROPERTY_DEFAULT_SSL_PROTOCOL
setDefaultSSLProtocol(String)
method.public static final java.lang.String PROPERTY_ENABLED_SSL_PROTOCOLS
setEnabledSSLProtocols(java.util.Collection)
method.public SSLUtil()
public SSLUtil(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(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(javax.net.ssl.KeyManager keyManager, 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(javax.net.ssl.KeyManager[] keyManagers, 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.public javax.net.ssl.KeyManager[] getKeyManagers()
null
if none were provided.public javax.net.ssl.TrustManager[] getTrustManagers()
null
if none were provided.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.public javax.net.ssl.SSLContext createSSLContext(java.lang.String protocol) throws java.security.GeneralSecurityException
protocol
- The protocol to use. As per the Java SE 6 Cryptography
Architecture document, the set of supported protocols
should include at least "SSLv3", "TLSv1", "TLSv1.1", and
"SSLv2Hello". It must not be null
.java.security.GeneralSecurityException
- If a problem occurs while creating or
initializing the SSL context.public javax.net.ssl.SSLContext createSSLContext(java.lang.String protocol, java.lang.String provider) throws java.security.GeneralSecurityException
protocol
- The protocol to use. As per the Java SE 6 Cryptography
Architecture document, the set of supported protocols
should include at least "SSLv3", "TLSv1", "TLSv1.1", and
"SSLv2Hello". It 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.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.public javax.net.ssl.SSLSocketFactory createSSLSocketFactory(java.lang.String protocol) throws java.security.GeneralSecurityException
protocol
- The protocol to use. As per the Java SE 6 Cryptography
Architecture document, the set of supported protocols
should include at least "SSLv3", "TLSv1", "TLSv1.1", and
"SSLv2Hello". It must not be null
.java.security.GeneralSecurityException
- If a problem occurs while creating or
initializing the SSL socket factory.public javax.net.ssl.SSLSocketFactory createSSLSocketFactory(java.lang.String protocol, java.lang.String provider) throws java.security.GeneralSecurityException
protocol
- The protocol to use. As per the Java SE 6 Cryptography
Architecture document, the set of supported protocols
should include at least "SSLv3", "TLSv1", "TLSv1.1", and
"SSLv2Hello". It 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.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.public javax.net.ssl.SSLServerSocketFactory createSSLServerSocketFactory(java.lang.String protocol) throws java.security.GeneralSecurityException
protocol
- The protocol to use. As per the Java SE 6 Cryptography
Architecture document, the set of supported protocols
should include at least "SSLv3", "TLSv1", "TLSv1.1", and
"SSLv2Hello". It must not be null
.java.security.GeneralSecurityException
- If a problem occurs while creating or
initializing the SSL server socket
factory.public javax.net.ssl.SSLServerSocketFactory createSSLServerSocketFactory(java.lang.String protocol, java.lang.String provider) throws java.security.GeneralSecurityException
protocol
- The protocol to use. As per the Java SE 6 Cryptography
Architecture document, the set of supported protocols
should include at least "SSLv3", "TLSv1", "TLSv1.1", and
"SSLv2Hello". It 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.public static java.lang.String getDefaultSSLProtocol()
createSSLContext()
that do not explicitly specify which protocol
to use.public static void setDefaultSSLProtocol(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
.public static java.util.Set<java.lang.String> getEnabledSSLProtocols()
public static void setEnabledSSLProtocols(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(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, assocket
- 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.public static java.lang.String certificateToString(java.security.cert.X509Certificate certificate)
certificate
- The certificate for which to generate the string
representation. It must not be null
.public static void certificateToString(java.security.cert.X509Certificate certificate, 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.