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

   SSLUtil sslUtil = new SSLUtil(new TrustAllTrustManager());

   LDAPConnection connection =
        new LDAPConnection(sslUtil.createSSLSocketFactory());
   connection.connect("server.example.com", 636);
 

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.

   LDAPConnection connection = new LDAPConnection();
   connection.connect("server.example.com", 389);

   String trustStoreFile  = "/path/to/trust/store/file";
   SSLUtil sslUtil = new SSLUtil(new TrustStoreTrustManager(trustStoreFile));

   ExtendedResult extendedResult = connection.processExtendedOperation(
        new StartTLSExtendedRequest(sslUtil.createSSLContext()));
 

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

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

Methods inherited from class java.lang.Object

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

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.