SSLContext Class

The is an engine class for an implementation of a secure socket protocol. An instance of this class acts as a factory for SSL socket factories and SSL engines. An SSLContext holds all of the state information shared across all objects created under that context. For example, session state is associated with the SSLContext when it is negotiated through the handshake protocol by sockets created by socket factories provided by the context. These cached sessions can be reused and shared by other sockets created under the same context.

Each instance is configured through its init method with the keys, certificate chains, and trusted root CA certificates that it needs to perform authentication. This configuration is provided in the form of key and trust managers. These managers provide support for the authentication and key agreement aspects of the cipher suites supported by the context.

Currently, only X.509-based managers are supported.

Creating an SSLContext Object

Like other JCA provider-based engine classes, SSLContext objects are created by using the getInstance factory methods of the SSLContext class. These static methods each return an instance that implements the requested secure socket protocol. The returned instance can implement other protocols too.

For example, getInstance("SSL_TLS") returns an instance that implements SSLv3 and TLSv1.

The getSupportedProtocols method returns a list of supported protocols when an SSLSocket, SSLServerSocket or SSLEngine is created from this context. You can also control which protocols are enabled for an SSL connection by using the method setEnabledProtocols(String[] protocols).

Note: An SSLContext object is automatically created, initialized, and statically assigned to the SSLSocketFactory class when you call SSLSocketFactory.getDefault. Therefore, you don't have to directly create and initialize an SSLContext object (unless you want to override the default behavior).
To create an SSLContext object by calling a getInstance factory method, you must specify the protocol name. You can also specify which provider you want to supply the implementation of the requested protocol:
public static SSLContext getInstance(String protocol);

public static SSLContext getInstance(String protocol, String provider);

public static SSLContext getInstance(String protocol, Provider provider);

If only a protocol name is specified, the system determines whether there is an implementation of the requested protocol available in the environment. If there is more than one, it determines the preferred one.

If both a protocol name and a provider are specified, the system determines whether there is an implementation of the requested protocol in the provider that is requested, and throws an exception if there is not.

A protocol is a string (such as SSL_TLS) that describes the secure socket protocol that you require. Common protocol names for SSLContext objects are defined in Appendix A.

The following example shows how to obtain an SSLContext:
SSLContext sc = SSLContext.getInstance("SSL_TLS");
A newly created SSLContext should be initialized by calling the init method:
public void init(KeyManager[] km, TrustManager[] tm, SecureRandom random);

If the KeyManager[] parameter is null, the installed security providers are searched for the highest-priority implementation of the KeyManagerFactory, from which an appropriate KeyManager is obtained. If the TrustManager[] parameter is null, the installed security providers are searched for the highest-priority implementation of the TrustManagerFactory, from which an appropriate TrustManager is obtained. Likewise, the SecureRandom parameter can be null, in which case a default implementation is used.

If the internal default context is used (for example, a SSLContext is created by SSLSocketFactory.getDefault() or SSLServerSocketFactory.getDefault()), a default KeyManager and a TrustManager are created. The default SecureRandom implementation is also chosen.

The IBM implementation of SSLContext.getInstance("TLS") is different from the Oracle implementation. Start of changes for service refresh 3 fix pack 10A system property is available to match the behavior of the IBM implementation to Oracle's implementation. For more information, see Matching the behavior of SSLContext.getInstance("TLS") to Oracle.End of changes for service refresh 3 fix pack 10