public class SSLContext extends Object
SSLEngine
s. This class is initialized
with an optional set of key and trust managers and source of
secure random bytes.
Every implementation of the Java platform is required to support the
following standard SSLContext
protocol:
TLSv1.2
- Since:
- 1.4
-
Constructor Summary
ModifierConstructorDescriptionprotected
SSLContext(SSLContextSpi contextSpi, Provider provider, String protocol)
Creates an SSLContext object. -
Method Summary
Modifier and TypeMethodDescriptionCreates a newSSLEngine
using this context.createSSLEngine(String peerHost, int peerPort)
Creates a newSSLEngine
using this context using advisory peer information.Returns the client session context, which represents the set of SSL sessions available for use during the handshake phase of client-side SSL sockets.static SSLContext
Returns the default SSL context.Returns a copy of the SSLParameters indicating the default settings for this SSL context.static SSLContext
getInstance(String protocol)
Returns aSSLContext
object that implements the specified secure socket protocol.static SSLContext
getInstance(String protocol, String provider)
Returns aSSLContext
object that implements the specified secure socket protocol.static SSLContext
getInstance(String protocol, Provider provider)
Returns aSSLContext
object that implements the specified secure socket protocol.Returns the protocol name of thisSSLContext
object.Returns the provider of thisSSLContext
object.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 aServerSocketFactory
object for this context.Returns aSocketFactory
object for this context.Returns a copy of the SSLParameters indicating the supported settings for this SSL context.void
init(KeyManager[] km, TrustManager[] tm, SecureRandom random)
Initializes this context.static void
setDefault(SSLContext context)
Sets the default SSL context.
-
Constructor Details
-
SSLContext
Creates an SSLContext object.- Parameters:
contextSpi
- the delegateprovider
- the providerprotocol
- the protocol
-
-
Method Details
-
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 callSSLContext.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:
- the default SSL context
- Throws:
NoSuchAlgorithmException
- if theSSLContext.getInstance()
call fails- Since:
- 1.6
-
setDefault
Sets the default SSL context. It will be returned by subsequent calls togetDefault()
. The default context must be immediately usable and not require initialization.- Parameters:
context
- the SSLContext- Throws:
NullPointerException
- if context is nullSecurityException
- if a security manager exists and itscheckPermission
method does not allowSSLPermission("setDefaultSSLContext")
- Since:
- 1.6
-
getInstance
Returns aSSLContext
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 than the order of providers returned bySecurity.getProviders()
. - Parameters:
protocol
- 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:
- the new
SSLContext
object - Throws:
NoSuchAlgorithmException
- if noProvider
supports aSSLContextSpi
implementation for the specified protocolNullPointerException
- ifprotocol
isnull
- See Also:
Provider
-
getInstance
public static SSLContext getInstance(String protocol, String provider) throws NoSuchAlgorithmException, NoSuchProviderExceptionReturns aSSLContext
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 Security Standard Algorithm Names Specification for information about standard protocol names.provider
- the name of the provider.- Returns:
- the new
SSLContext
object - Throws:
IllegalArgumentException
- if the provider name isnull
or emptyNoSuchAlgorithmException
- if aSSLContextSpi
implementation for the specified protocol is not available from the specified providerNoSuchProviderException
- if the specified provider is not registered in the security provider listNullPointerException
- ifprotocol
isnull
- See Also:
Provider
-
getInstance
public static SSLContext getInstance(String protocol, Provider provider) throws NoSuchAlgorithmExceptionReturns aSSLContext
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 Security Standard Algorithm Names Specification for information about standard protocol names.provider
- an instance of the provider.- Returns:
- the new
SSLContext
object - Throws:
IllegalArgumentException
- if the provider isnull
NoSuchAlgorithmException
- if aSSLContextSpi
implementation for the specified protocol is not available from the specifiedProvider
objectNullPointerException
- ifprotocol
isnull
- See Also:
Provider
-
getProtocol
Returns the protocol name of thisSSLContext
object.This is the same name that was specified in one of the
getInstance
calls that created thisSSLContext
object.- Returns:
- the protocol name of this
SSLContext
object.
-
getProvider
Returns the provider of thisSSLContext
object.- Returns:
- the provider of this
SSLContext
object
-
init
public final void init(KeyManager[] km, TrustManager[] tm, SecureRandom random) throws KeyManagementExceptionInitializes 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 nulltm
- the sources of peer authentication trust decisions or nullrandom
- the source of randomness for this generator or null- Throws:
KeyManagementException
- if this operation fails
-
getSocketFactory
Returns aSocketFactory
object for this context.- Returns:
- the
SocketFactory
object - Throws:
UnsupportedOperationException
- if the underlying provider does not implement the operation.IllegalStateException
- if the SSLContextImpl requires initialization and theinit()
has not been called
-
getServerSocketFactory
Returns aServerSocketFactory
object for this context.- Returns:
- the
ServerSocketFactory
object - Throws:
UnsupportedOperationException
- if the underlying provider does not implement the operation.IllegalStateException
- if the SSLContextImpl requires initialization and theinit()
has not been called
-
createSSLEngine
Creates a newSSLEngine
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:
- the
SSLEngine
object - Throws:
UnsupportedOperationException
- if the underlying provider does not implement the operation.IllegalStateException
- if the SSLContextImpl requires initialization and theinit()
has not been called- Since:
- 1.5
-
createSSLEngine
Creates a newSSLEngine
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
- the non-authoritative name of the hostpeerPort
- 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 theinit()
has not been called- Since:
- 1.5
-
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
-
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
-
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.- Since:
- 1.6
-
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.- Since:
- 1.6
-