com.unboundid.util.ssl
Class SSLUtil

java.lang.Object
  extended by com.unboundid.util.ssl.SSLUtil

public final class SSLUtil
extends java.lang.Object

This class provides a simple interface for creating SSLContext and SSLSocketFactory instances, which may be used to create SSL-based connections, or secure existing connections with StartTLS.

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 the 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();
 

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
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 Summary
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
static void applyEnabledSSLProtocols(java.net.Socket socket)
          Updates the provided socket to apply the appropriate set of enabled SSL protocols.
 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.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

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 the setDefaultSSLProtocol(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 the setEnabledSSLProtocols(java.util.Collection) method.

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 be null 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 be null 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 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(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 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

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 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

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 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.
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 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.
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 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

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 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.
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 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.
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 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

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 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.
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 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.
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 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(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

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, 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(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, as

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.