OpenJDK 27 · javax.net.ssl.SSLContext · APIdia, the JavaDoc alternative

Modifier and Type	Field and Description
private final SSLContextSpi	contextSpi
private static volatile SSLContext	defaultContext
private final String	protocol
private final Provider	provider
private static final VarHandle	VH_DEFAULT_CONTEXT

Access	Constructor and Description
protected	SSLContext(SSLContextSpi the delegate contextSpi, Provider the provider provider, String the protocol protocol) Creates an SSLContext object.

Method Summary

Modifier and Type	Method and Description
public final SSLEngine	Returns: the `SSLEngine` object createSSLEngine() Creates a new `SSLEngine` using this context.
public final SSLEngine	Returns: the new `SSLEngine` object createSSLEngine(String the non-authoritative name of the host peerHost, int the non-authoritative port peerPort) Creates a new `SSLEngine` using this context using advisory peer information.
public final SSLSessionContext	Returns: client session context bound to this SSL context 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.
public static SSLContext	Returns: the default SSL context getDefault() Returns the default SSL context.
public final SSLParameters	Returns: a copy of the SSLParameters object with the default settings getDefaultSSLParameters() Returns a copy of the SSLParameters indicating the default settings for this SSL context.
public static SSLContext	Returns: the new `SSLContext` object getInstance(String the standard name of the requested protocol. See the SSLContext section in the Java Security Standard Algorithm Names Specification for information about standard protocol names. protocol) Returns a `SSLContext` object that implements the specified secure socket protocol.
public static SSLContext	Returns: the new `SSLContext` object getInstance(String the standard name of the requested protocol. See the SSLContext section in the Java Security Standard Algorithm Names Specification for information about standard protocol names. protocol, String the name of the provider. provider) Returns a `SSLContext` object that implements the specified secure socket protocol.
public static SSLContext	Returns: the new `SSLContext` object getInstance(String the standard name of the requested protocol. See the SSLContext section in the Java Security Standard Algorithm Names Specification for information about standard protocol names. protocol, Provider an instance of the provider. provider) Returns a `SSLContext` object that implements the specified secure socket protocol.
public final String	Returns: the protocol name of this `SSLContext` object. getProtocol() Returns the protocol name of this `SSLContext` object.
public final Provider	Returns: the provider of this `SSLContext` object getProvider() Returns the provider of this `SSLContext` object.
public final SSLSessionContext	Returns: server session context bound to this SSL context 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.
public final SSLServerSocketFactory	Returns: the `ServerSocketFactory` object getServerSocketFactory() Returns a `ServerSocketFactory` object for this context.
public final SSLSocketFactory	Returns: the `SocketFactory` object getSocketFactory() Returns a `SocketFactory` object for this context.
public final SSLParameters	Returns: a copy of the SSLParameters object with the supported settings getSupportedSSLParameters() Returns a copy of the SSLParameters indicating the supported settings for this SSL context.
public final void	init(KeyManager[] the sources of authentication keys or null km, TrustManager[] the sources of peer authentication trust decisions or null tm, SecureRandom the source of randomness for this generator or null random) Initializes this context.
public static void	setDefault(SSLContext the SSLContext context) Sets the default SSL context.

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll toString wait wait wait

contextSpi	back to summary
private final SSLContextSpi contextSpi

defaultContext	back to summary
private static volatile SSLContext defaultContext

protocol	back to summary
private final String protocol

provider	back to summary
private final Provider provider

VH_DEFAULT_CONTEXT	back to summary
private static final VarHandle VH_DEFAULT_CONTEXT

SSLContext	back to summary
protected SSLContext(SSLContextSpi contextSpi, Provider provider, String protocol) Creates an SSLContext object. Parameters contextSpi:SSLContextSpi the delegate provider:Provider the provider protocol:String the protocol

Method Detail

createSSLEngine back to summary

createSSLEngine	back to summary
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. Implementation Note It is provider-specific if the returned SSLEngine uses client or server mode by default for the (D)TLS connection. The JDK SunJSSE provider implementation uses server mode by default. However, it is recommended to always set the desired mode explicitly by calling `SSLEngine.setUseClientMode()` before invoking other methods of the SSLEngine. Returns:SSLEngine the `SSLEngine` object Exceptions UnsupportedOperationException: if the underlying provider does not implement the operation. IllegalStateException: if the SSLContextImpl requires initialization and the `init()` has not been called Since 1.5

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.

Implementation Note

It is provider-specific if the returned SSLEngine uses client or server mode by default for the (D)TLS connection. The JDK SunJSSE provider implementation uses server mode by default. However, it is recommended to always set the desired mode explicitly by calling SSLEngine.setUseClientMode() before invoking other methods of the SSLEngine.

Returns:SSLEngine

the SSLEngine object

Exceptions

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

Since

1.5

createSSLEngine back to summary

createSSLEngine	back to summary
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. Implementation Note It is provider-specific if the returned SSLEngine uses client or server mode by default for the (D)TLS connection. The JDK SunJSSE provider implementation uses server mode by default. However, it is recommended to always set the desired mode explicitly by calling `SSLEngine.setUseClientMode()` before invoking other methods of the SSLEngine. Parameters peerHost:String the non-authoritative name of the host peerPort:int the non-authoritative port Returns:SSLEngine the new `SSLEngine` object Exceptions UnsupportedOperationException: if the underlying provider does not implement the operation. IllegalStateException: if the SSLContextImpl requires initialization and the `init()` has not been called Since 1.5

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.

Implementation Note

Parameters

peerHost:String: the non-authoritative name of the host
peerPort:int: the non-authoritative port

Returns:SSLEngine

the new SSLEngine object

Exceptions

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

Since

1.5

getClientSessionContext	back to summary
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:SSLSessionContext client session context bound to this SSL context

getClientSessionContext

back to summary

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:SSLSessionContext: client session context bound to this SSL context

getDefault back to summary

getDefault	back to summary
public static SSLContext getDefault() throws NoSuchAlgorithmException 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 initialization. Returns:SSLContext the default SSL context Exceptions NoSuchAlgorithmException: if the `SSLContext.getInstance()` call fails Since 1.6

public static SSLContext getDefault() throws NoSuchAlgorithmException

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

Returns:SSLContext

the default SSL context

Exceptions

NoSuchAlgorithmException:: if the SSLContext.getInstance() call fails

Since

1.6

getDefaultSSLParameters	back to summary
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:SSLParameters a copy of the SSLParameters object with the default settings Exceptions UnsupportedOperationException: if the default SSL parameters could not be obtained. Since 1.6

getDefaultSSLParameters

back to summary

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

a copy of the SSLParameters object with the default settings

Exceptions

UnsupportedOperationException:: if the default SSL parameters could not be obtained.

Since

1.6

getInstance back to summary

getInstance	back to summary
public static SSLContext getInstance(String protocol) throws NoSuchAlgorithmException 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. Implementation Note The JDK Reference Implementation additionally uses the `jdk.security.provider.preferred` `Security` property to determine the preferred provider order for the specified algorithm. This may be different from the order of providers returned by `Security.getProviders()`. Parameters protocol:String the standard name of the requested protocol. See the SSLContext section in the Java Security Standard Algorithm Names Specification for information about standard protocol names. Returns:SSLContext the new `SSLContext` object Exceptions NoSuchAlgorithmException: if no `Provider` supports a `SSLContextSpi` implementation for the specified protocol NullPointerException: if `protocol` is `null` External Specification Java Security Standard Algorithm Names See Also `java.security.Provider`

public static SSLContext getInstance(String protocol) throws NoSuchAlgorithmException

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.

Implementation Note

The JDK Reference Implementation additionally uses the jdk.security.provider.preferred Security property to determine the preferred provider order for the specified algorithm. This may be different from the order of providers returned by Security.getProviders().

Parameters

protocol:String: the standard name of the requested protocol. See the SSLContext section in the Java Security Standard Algorithm Names Specification for information about standard protocol names.

Returns:SSLContext

the new SSLContext object

Exceptions

NoSuchAlgorithmException:: if no Provider supports a SSLContextSpi implementation for the specified protocol
NullPointerException:: if protocol is null

External Specification

Java Security Standard Algorithm Names

See Also

java.security.Provider

getInstance back to summary

getInstance	back to summary
public static SSLContext getInstance(String protocol, String provider) throws NoSuchAlgorithmException, NoSuchProviderException 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:String the standard name of the requested protocol. See the SSLContext section in the Java Security Standard Algorithm Names Specification for information about standard protocol names. provider:String the name of the provider. Returns:SSLContext the new `SSLContext` object Exceptions 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` External Specification Java Security Standard Algorithm Names See Also `java.security.Provider`

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

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:String: the standard name of the requested protocol. See the SSLContext section in the Java Security Standard Algorithm Names Specification for information about standard protocol names.
provider:String: the name of the provider.

Returns:SSLContext

the new SSLContext object

Exceptions

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

External Specification

Java Security Standard Algorithm Names

See Also

java.security.Provider

getInstance back to summary

getInstance	back to summary
public static SSLContext getInstance(String protocol, Provider provider) throws NoSuchAlgorithmException 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:String the standard name of the requested protocol. See the SSLContext section in the Java Security Standard Algorithm Names Specification for information about standard protocol names. provider:Provider an instance of the provider. Returns:SSLContext the new `SSLContext` object Exceptions NoSuchAlgorithmException: if a `SSLContextSpi` implementation for the specified protocol is not available from the specified `Provider` object IllegalArgumentException: if the provider is `null` NullPointerException: if `protocol` is `null` External Specification Java Security Standard Algorithm Names See Also `java.security.Provider`

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

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:String: the standard name of the requested protocol. See the SSLContext section in the Java Security Standard Algorithm Names Specification for information about standard protocol names.
provider:Provider: an instance of the provider.

Returns:SSLContext

the new SSLContext object

Exceptions

NoSuchAlgorithmException:: if a SSLContextSpi implementation for the specified protocol is not available from the specified Provider object
IllegalArgumentException:: if the provider is null
NullPointerException:: if protocol is null

External Specification

Java Security Standard Algorithm Names

See Also

java.security.Provider

getProtocol back to summary

getProtocol	back to summary
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:String the protocol name of this `SSLContext` object.

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:String: the protocol name of this SSLContext object.

getProvider back to summary

getProvider	back to summary
public final Provider getProvider() Returns the provider of this `SSLContext` object. Returns:Provider the provider of this `SSLContext` object

public final Provider getProvider()

Returns the provider of this SSLContext object.

Returns:Provider: the provider of this SSLContext object

getServerSessionContext	back to summary
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:SSLSessionContext server session context bound to this SSL context

getServerSessionContext

back to summary

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.

Returns:SSLSessionContext: server session context bound to this SSL context

getServerSocketFactory back to summary

getServerSocketFactory	back to summary
public final SSLServerSocketFactory getServerSocketFactory() Returns a `ServerSocketFactory` object for this context. Returns:SSLServerSocketFactory the `ServerSocketFactory` object Exceptions 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 SSLServerSocketFactory getServerSocketFactory()

Returns a ServerSocketFactory object for this context.

Returns:SSLServerSocketFactory

the ServerSocketFactory object

Exceptions

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

getSocketFactory back to summary

getSocketFactory	back to summary
public final SSLSocketFactory getSocketFactory() Returns a `SocketFactory` object for this context. Returns:SSLSocketFactory the `SocketFactory` object Exceptions 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 SSLSocketFactory getSocketFactory()

Returns a SocketFactory object for this context.

Returns:SSLSocketFactory

the SocketFactory object

Exceptions

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

getSupportedSSLParameters	back to summary
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:SSLParameters a copy of the SSLParameters object with the supported settings Exceptions UnsupportedOperationException: if the supported SSL parameters could not be obtained. Since 1.6

getSupportedSSLParameters

back to summary

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

a copy of the SSLParameters object with the supported settings

Exceptions

UnsupportedOperationException:: if the supported SSL parameters could not be obtained.

Since

1.6

init	back to summary
public final void init(KeyManager[] km, TrustManager[] tm, SecureRandom random) throws KeyManagementException 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:KeyManager[] the sources of authentication keys or null tm:TrustManager[] the sources of peer authentication trust decisions or null random:SecureRandom the source of randomness for this generator or null Exceptions KeyManagementException: if this operation fails

init

back to summary

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

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:KeyManager[]: the sources of authentication keys or null
tm:TrustManager[]: the sources of peer authentication trust decisions or null
random:SecureRandom: the source of randomness for this generator or null

Exceptions

KeyManagementException:: if this operation fails

setDefault back to summary

setDefault	back to summary
public static 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 initialization. Parameters context:SSLContext the SSLContext Exceptions NullPointerException: if context is null Since 1.6

public static 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 initialization.

Parameters

context:SSLContext: the SSLContext

Exceptions

NullPointerException:: if context is null

Since

1.6

public Class SSLContext

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail