SSLContext

public class SSLContext extends Object

Instances of this class represent a secure socket protocol implementation which acts as a factory for secure socket factories or SSLEngines. This class is initialized with an optional set of key and trust managers and source of secure random bytes.

Android provides the following SSLContext protocols:

Name	Supported (API Levels)
Default	10+
SSL	10+
SSLv3	10+
TLS	1+
TLSv1	10+
TLSv1.1	16+
TLSv1.2	16+

This protocol is described in the SSLContext section of the Java Cryptography Architecture Standard Algorithm Name Documentation.

Protected Constructor Summary

SSLContext(SSLContextSpi contextSpi, Provider provider, String protocol) Creates an SSLContext object.

Public Method Summary

final SSLEngine	createSSLEngine() Creates a new SSLEngine using this context.
final SSLEngine	createSSLEngine(String peerHost, int peerPort) Creates a new SSLEngine using this context using advisory peer information.
final SSLSessionContext	getClientSessionContext() Returns the client session context, which represents the set of SSL sessions available for use during the handshake phase of client-side SSL sockets.
synchronized static SSLContext	getDefault() Returns the default SSL context.
final SSLParameters	getDefaultSSLParameters() Returns a copy of the SSLParameters indicating the default settings for this SSL context.
static SSLContext	getInstance(String protocol) Returns a SSLContext object that implements the specified secure socket protocol.
static SSLContext	getInstance(String protocol, String provider) Returns a SSLContext object that implements the specified secure socket protocol.
static SSLContext	getInstance(String protocol, Provider provider) Returns a SSLContext object that implements the specified secure socket protocol.
final String	getProtocol() Returns the protocol name of this SSLContext object.
final Provider	getProvider() Returns the provider of this SSLContext object.
final SSLSessionContext	getServerSessionContext() Returns the server session context, which represents the set of SSL sessions available for use during the handshake phase of server-side SSL sockets.
final SSLServerSocketFactory	getServerSocketFactory() Returns a ServerSocketFactory object for this context.
final SSLSocketFactory	getSocketFactory() Returns a SocketFactory object for this context.
final SSLParameters	getSupportedSSLParameters() Returns a copy of the SSLParameters indicating the supported settings for this SSL context.
final void	init(KeyManager[] km, TrustManager[] tm, SecureRandom random) Initializes this context.
synchronized static void	setDefault(SSLContext context) Sets the default SSL context.

Inherited Method Summary

From class java.lang.Object

Object	clone() Creates and returns a copy of this Object.
boolean	equals(Object obj) Compares this instance with the specified object and indicates if they are equal.
void	finalize() Invoked when the garbage collector has detected that this instance is no longer reachable.
final Class<?>	getClass() Returns the unique instance of Class that represents this object's class.
int	hashCode() Returns an integer hash code for this object.
final void	notify() Causes a thread which is waiting on this object's monitor (by means of calling one of the wait() methods) to be woken up.
final void	notifyAll() Causes all threads which are waiting on this object's monitor (by means of calling one of the wait() methods) to be woken up.
String	toString() Returns a string containing a concise, human-readable description of this object.
final void	wait(long timeout, int nanos) Causes the calling thread to wait until another thread calls the notify() or notifyAll() method of this object or until the specified timeout expires.
final void	wait(long timeout) Causes the calling thread to wait until another thread calls the notify() or notifyAll() method of this object or until the specified timeout expires.
final void	wait() Causes the calling thread to wait until another thread calls the notify() or notifyAll() method of this object.

Protected Constructors

protected SSLContext (SSLContextSpi contextSpi, Provider provider, String protocol)

Creates an SSLContext object.

Parameters

contextSpi	the delegate
provider	the provider
protocol	the protocol

Public Methods

public final SSLEngine createSSLEngine ()

Creates a new SSLEngine using this context.

Applications using this factory method are providing no hints for an internal session reuse strategy. If hints are desired, createSSLEngine(String, int) should be used instead.

Some cipher suites (such as Kerberos) require remote hostname information, in which case this factory method should not be used.

Returns

• the SSLEngine object

Throws

UnsupportedOperationException	if the underlying provider does not implement the operation.
IllegalStateException	if the SSLContextImpl requires initialization and the init() has not been called

public final SSLEngine createSSLEngine (String peerHost, int peerPort)

Creates a new SSLEngine using this context using advisory peer information.

Applications using this factory method are providing hints for an internal session reuse strategy.

Some cipher suites (such as Kerberos) require remote hostname information, in which case peerHost needs to be specified.

Parameters

peerHost	the non-authoritative name of the host
peerPort	the non-authoritative port

Returns

• the new SSLEngine object

Throws

UnsupportedOperationException	if the underlying provider does not implement the operation.
IllegalStateException	if the SSLContextImpl requires initialization and the init() has not been called

public final SSLSessionContext getClientSessionContext ()

Returns the client session context, which represents the set of SSL sessions available for use during the handshake phase of client-side SSL sockets.

This context may be unavailable in some environments, in which case this method returns null. For example, when the underlying SSL provider does not provide an implementation of SSLSessionContext interface, this method returns null. A non-null session context is returned otherwise.

Returns

• client session context bound to this SSL context

public static synchronized SSLContext getDefault ()

Returns the default SSL context.

If a default context was set using the SSLContext.setDefault() method, it is returned. Otherwise, the first call of this method triggers the call SSLContext.getInstance("Default"). If successful, that object is made the default SSL context and returned.

The default context is immediately usable and does not require {@linkplain #init initialization}.

Returns

• the default SSL context

Throws

NoSuchAlgorithmException	if the SSLContext.getInstance() call fails

public final SSLParameters getDefaultSSLParameters ()

Returns a copy of the SSLParameters indicating the default settings for this SSL context.

The parameters will always have the ciphersuites and protocols arrays set to non-null values.

Returns

• a copy of the SSLParameters object with the default settings

Throws

UnsupportedOperationException	if the default SSL parameters could not be obtained.

public static SSLContext getInstance (String protocol)

Returns a SSLContext object that implements the specified secure socket protocol.

This method traverses the list of registered security Providers, starting with the most preferred Provider. A new SSLContext object encapsulating the SSLContextSpi implementation from the first Provider that supports the specified protocol is returned.

Note that the list of registered providers may be retrieved via the Security.getProviders() method.

Parameters

protocol	the standard name of the requested protocol. See the SSLContext section in the Java Cryptography Architecture Standard Algorithm Name Documentation for information about standard protocol names.

Returns

• the new SSLContext object.

Throws

NoSuchAlgorithmException	if no Provider supports a TrustManagerFactorySpi implementation for the specified protocol.
NullPointerException	if protocol is null.

See Also

• Provider

public static SSLContext getInstance (String protocol, String provider)

Returns a SSLContext object that implements the specified secure socket protocol.

A new SSLContext object encapsulating the SSLContextSpi implementation from the specified provider is returned. The specified provider must be registered in the security provider list.

Note that the list of registered providers may be retrieved via the Security.getProviders() method.

Parameters

protocol	the standard name of the requested protocol. See the SSLContext section in the Java Cryptography Architecture Standard Algorithm Name Documentation for information about standard protocol names.
provider	the name of the provider.

Returns

• the new SSLContext object.

Throws

NoSuchAlgorithmException	if a SSLContextSpi implementation for the specified protocol is not available from the specified provider.
NoSuchProviderException	if the specified provider is not registered in the security provider list.
IllegalArgumentException	if the provider name is null or empty.
NullPointerException	if protocol is null.

See Also

• Provider

public static SSLContext getInstance (String protocol, Provider provider)

Returns a SSLContext object that implements the specified secure socket protocol.

A new SSLContext object encapsulating the SSLContextSpi implementation from the specified Provider object is returned. Note that the specified Provider object does not have to be registered in the provider list.

Parameters

protocol	the standard name of the requested protocol. See the SSLContext section in the Java Cryptography Architecture Standard Algorithm Name Documentation for information about standard protocol names.
provider	an instance of the provider.

Returns

• the new SSLContext object.

Throws

NoSuchAlgorithmException	if a KeyManagerFactorySpi implementation for the specified protocol is not available from the specified Provider object.
IllegalArgumentException	if the provider name is null.
NullPointerException	if protocol is null.

See Also

• Provider

public final String getProtocol ()

Returns the protocol name of this SSLContext object.

This is the same name that was specified in one of the getInstance calls that created this SSLContext object.

Returns

• the protocol name of this SSLContext object.

public final Provider getProvider ()

Returns the provider of this SSLContext object.

Returns

• the provider of this SSLContext object

public final SSLSessionContext getServerSessionContext ()

Returns the server session context, which represents the set of SSL sessions available for use during the handshake phase of server-side SSL sockets.

This context may be unavailable in some environments, in which case this method returns null. For example, when the underlying SSL provider does not provide an implementation of SSLSessionContext interface, this method returns null. A non-null session context is returned otherwise.

Returns

• server session context bound to this SSL context

public final SSLServerSocketFactory getServerSocketFactory ()

Returns a ServerSocketFactory object for this context.

Returns

• the ServerSocketFactory object

Throws

IllegalStateException	if the SSLContextImpl requires initialization and the init() has not been called

public final SSLSocketFactory getSocketFactory ()

Returns a SocketFactory object for this context.

Returns

• the SocketFactory object

Throws

IllegalStateException	if the SSLContextImpl requires initialization and the init() has not been called

public final SSLParameters getSupportedSSLParameters ()

Returns a copy of the SSLParameters indicating the supported settings for this SSL context.

The parameters will always have the ciphersuites and protocols arrays set to non-null values.

Returns

• a copy of the SSLParameters object with the supported settings

Throws

UnsupportedOperationException	if the supported SSL parameters could not be obtained.

public final void init (KeyManager[] km, TrustManager[] tm, SecureRandom random)

Initializes this context. Either of the first two parameters may be null in which case the installed security providers will be searched for the highest priority implementation of the appropriate factory. Likewise, the secure random parameter may be null in which case the default implementation will be used.

Only the first instance of a particular key and/or trust manager implementation type in the array is used. (For example, only the first javax.net.ssl.X509KeyManager in the array will be used.)

Parameters

km	the sources of authentication keys or null
tm	the sources of peer authentication trust decisions or null
random	the source of randomness for this generator or null

Throws

KeyManagementException	if this operation fails

public static synchronized void setDefault (SSLContext context)

Sets the default SSL context. It will be returned by subsequent calls to getDefault(). The default context must be immediately usable and not require {@linkplain #init initialization}.

Parameters

context	the SSLContext

Throws

NullPointerException	if context is null
SecurityException	if a security manager exists and its checkPermission method does not allow SSLPermission("setDefaultSSLContext")