javax.net.ssl

Class SSLContext

java.lang.Object

javax.net.ssl.SSLContext

public class SSLContext
extends Object

The public API for secure socket protocol implementations. It acts as factory for SSLSocketFactory's and SSLEngines.

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	SSLContext(SSLContextSpi contextSpi, Provider provider, String protocol) Creates a new SSLContext.

Method Summary

Modifier and Type	Method and Description
SSLEngine	createSSLEngine() Creates an SSLEngine instance from this context.
SSLEngine	createSSLEngine(String peerHost, int peerPort) Creates an SSLEngine instance from this context with the specified hostname and port.
SSLSessionContext	getClientSessionContext() Returns the SSL session context that encapsulates the set of SSL sessions that can be used for handshake of client-side SSL sockets.
static SSLContext	getDefault() Returns the default SSLContext.
SSLParameters	getDefaultSSLParameters() Returns the default SSL handshake parameters for SSLSockets created by this SSLContext.
static SSLContext	getInstance(String protocol) Creates a new SSLContext instance for the specified protocol.
static SSLContext	getInstance(String protocol, Provider provider) Creates a new SSLContext instance for the specified protocol from the specified provider.
static SSLContext	getInstance(String protocol, String provider) Creates a new SSLContext instance for the specified protocol from the specified provider.
String	getProtocol() Returns the name of the secure socket protocol of this instance.
Provider	getProvider() Returns the provider of this SSLContext instance.
SSLSessionContext	getServerSessionContext() Returns the SSL session context that encapsulates the set of SSL sessions that can be used for handshake of server-side SSL sockets.
SSLServerSocketFactory	getServerSocketFactory() Returns a server socket factory for this instance.
SSLSocketFactory	getSocketFactory() Returns a socket factory for this instance.
SSLParameters	getSupportedSSLParameters() Returns SSL handshake parameters for SSLSockets that includes all supported cipher suites and protocols.
void	init(KeyManager[] km, TrustManager[] tm, SecureRandom sr) Initializes this SSLContext instance.
static void	setDefault(SSLContext sslContext) Sets the default SSLContext instance as returned by getDefault() to a non-null initialized value.

Methods inherited from class java.lang.Object

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

Constructor Detail

SSLContext

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

Creates a new SSLContext.

Parameters:

contextSpi - the implementation delegate.

provider - the provider.

protocol - the protocol name.

Method Detail

getDefault

public static SSLContext getDefault()
                             throws NoSuchAlgorithmException

Returns the default SSLContext. The default SSL context can be set with setDefault(javax.net.ssl.SSLContext). If not, one will be created with SSLContext.getInstance("Default"), which will already be initialized.

Throws:

NoSuchAlgorithmException - if there is a problem creating the default instance.

Since:

1.6

setDefault

public static void setDefault(SSLContext sslContext)

Sets the default SSLContext instance as returned by getDefault() to a non-null initialized value.

Throws:

NullPointerException - on a null argument

Since:

1.6

getInstance

public static SSLContext getInstance(String protocol)
                              throws NoSuchAlgorithmException

Creates a new SSLContext instance for the specified protocol.

The following protocols are supported:

Protocol	API Levels
Default	9+
SSL	9+
SSLv3	9+
TLS	1+
TLSv1	1+
TLSv1.1	16+
TLSv1.2	16+

Parameters:

protocol - the requested protocol to create a context for.

Returns:

the created SSLContext instance.

Throws:

NoSuchAlgorithmException - if no installed provider can provide the requested protocol

NullPointerException - if protocol is null (instead of NoSuchAlgorithmException as in 1.4 release)

getInstance

public static SSLContext getInstance(String protocol,
                                     String provider)
                              throws NoSuchAlgorithmException,
                                     NoSuchProviderException

Creates a new SSLContext instance for the specified protocol from the specified provider.

The following combinations are supported:

Protocol	Provider	API Levels
Default	AndroidOpenSSL	9+
SSL	AndroidOpenSSL	9+
SSL	HarmonyJSSE	9-19
SSLv3	AndroidOpenSSL	9+
SSLv3	HarmonyJSSE	9-19
TLS	AndroidOpenSSL	9+
TLS	HarmonyJSSE	1-19
TLSv1	AndroidOpenSSL	9+
TLSv1	HarmonyJSSE	1-19
TLSv1.1	AndroidOpenSSL	16+
TLSv1.2	AndroidOpenSSL	16+

NOTE: The best practice is to rely on platform defaults rather than explicitly specify a provider. getDefault() and getInstance(String) are normally preferred over this method.

Parameters:

protocol - the requested protocol to create a context for.

provider - the name of the provider that provides the requested protocol.

Returns:

an SSLContext for the requested protocol.

Throws:

NoSuchAlgorithmException - if the specified provider cannot provider the requested protocol.

NoSuchProviderException - if the specified provider does not exits.

NullPointerException - if protocol is null (instead of NoSuchAlgorithmException as in 1.4 release)

getInstance

public static SSLContext getInstance(String protocol,
                                     Provider provider)
                              throws NoSuchAlgorithmException

Creates a new SSLContext instance for the specified protocol from the specified provider.

Parameters:

protocol - the requested protocol to create a context for

provider - the provider that provides the requested protocol.

Returns:

an SSLContext for the requested protocol.

Throws:

NoSuchAlgorithmException - if the specified provider cannot provide the requested protocol.

NullPointerException - if protocol is null (instead of NoSuchAlgorithmException as in 1.4 release)

getProtocol

public final String getProtocol()

Returns the name of the secure socket protocol of this instance.

Returns:

the name of the secure socket protocol of this instance.

getProvider

public final Provider getProvider()

Returns the provider of this SSLContext instance.

Returns:

the provider of this SSLContext instance.

init

public final void init(KeyManager[] km,
                       TrustManager[] tm,
                       SecureRandom sr)
                throws KeyManagementException

Initializes this SSLContext instance. Three aspects of the context can be configured during initialization:

• Providers of key material for key exchange and peer authentication (KeyManager instances),
• Providers of trust decisions about peers (TrustManager instances),
• Provider of randomness (SecureRandom instance).

For each type of KeyManager or TrustManager used by this context, only the first matching instance from km or tm will be used. For example, only the first instance of X509TrustManager from tm will be used.

For any parameter set to null defaults will be used. In that case, the installed security providers will be searched for the highest priority implementation of the required primitives. For km and tm, the highest priority implementation of KeyManagerFactory and TrustManagerFactory will be used to obtain the required types of KeyManager and TrustManager. For sr, the default SecureRandom implementation will be used.

Parameters:

km - the key sources or null for default.

tm - the trust decision sources or null for default.

sr - the randomness source or null for default.

Throws:

KeyManagementException - if initializing this instance fails.

getSocketFactory

public final SSLSocketFactory getSocketFactory()

Returns a socket factory for this instance.

Returns:

a socket factory for this instance.

getServerSocketFactory

public final SSLServerSocketFactory getServerSocketFactory()

Returns a server socket factory for this instance.

Returns:

a server socket factory for this instance.

createSSLEngine

public final SSLEngine createSSLEngine()

Creates an SSLEngine instance from this context.

Returns:

an SSLEngine instance from this context.

Throws:

UnsupportedOperationException - if the provider does not support the operation.

createSSLEngine

public final SSLEngine createSSLEngine(String peerHost,
                                       int peerPort)

Creates an SSLEngine instance from this context with the specified hostname and port.

Parameters:

peerHost - the name of the host

peerPort - the port

Returns:

an SSLEngine instance from this context.

Throws:

UnsupportedOperationException - if the provider does not support the operation.

getServerSessionContext

public final SSLSessionContext getServerSessionContext()

Returns the SSL session context that encapsulates the set of SSL sessions that can be used for handshake of server-side SSL sockets.

Returns:

the SSL server session context for this context or null if the underlying provider does not provide an implementation of the SSLSessionContext interface.

getClientSessionContext

public final SSLSessionContext getClientSessionContext()

Returns the SSL session context that encapsulates the set of SSL sessions that can be used for handshake of client-side SSL sockets.

Returns:

the SSL client session context for this context or null if the underlying provider does not provide an implementation of the SSLSessionContext interface.

getDefaultSSLParameters

public final SSLParameters getDefaultSSLParameters()

Returns the default SSL handshake parameters for SSLSockets created by this SSLContext.

Throws:

UnsupportedOperationException

Since:

1.6

getSupportedSSLParameters

public final SSLParameters getSupportedSSLParameters()

Returns SSL handshake parameters for SSLSockets that includes all supported cipher suites and protocols.

Throws:

UnsupportedOperationException

Since:

1.6