SSLContext
public
class
SSLContext
extends Object
java.lang.Object | |
↳ | javax.net.ssl.SSLContext |
Instances of this class represent a secure socket protocol
implementation which acts as a factory for secure socket
factories or SSLEngine
s. 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:
Algorithm | Supported API Levels |
---|---|
Default | 10+ |
SSL | 10+ |
SSLv3 | 10-25 |
TLS | 1+ |
TLSv1 | 10+ |
TLSv1.1 | 16+ |
TLSv1.2 | 16+ |
TLSv1.3 | 29+ |
Summary
Protected constructors | |
---|---|
SSLContext(SSLContextSpi contextSpi, Provider provider, String protocol)
Creates an SSLContext object. |
Public methods | |
---|---|
final
SSLEngine
|
createSSLEngine()
Creates a new |
final
SSLEngine
|
createSSLEngine(String peerHost, int peerPort)
Creates a new |
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. |
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 |
static
SSLContext
|
getInstance(String protocol, String provider)
Returns a |
static
SSLContext
|
getInstance(String protocol, Provider provider)
Returns a |
final
String
|
getProtocol()
Returns the protocol name of this |
final
Provider
|
getProvider()
Returns the provider of this |
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 |
final
SSLSocketFactory
|
getSocketFactory()
Returns a |
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. |
static
void
|
setDefault(SSLContext context)
Sets the default SSL context. |
Inherited methods | |
---|---|
Protected constructors
SSLContext
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 |
Public methods
createSSLEngine
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(java.lang.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 | |
---|---|
SSLEngine |
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 |
createSSLEngine
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 |
String : the non-authoritative name of the host |
peerPort |
int : the non-authoritative port |
Returns | |
---|---|
SSLEngine |
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 |
getClientSessionContext
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
public static 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 initialization.
Returns | |
---|---|
SSLContext |
the default SSL context |
Throws | |
---|---|
NoSuchAlgorithmException |
if the
SSLContext.getInstance() call fails |
getDefaultSSLParameters
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 |
Throws | |
---|---|
UnsupportedOperationException |
if the default SSL parameters could not be obtained. |
getInstance
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 |
String : 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 | |
---|---|
SSLContext |
the new SSLContext object. |
Throws | |
---|---|
NoSuchAlgorithmException |
if no Provider supports a SSLContextSpi implementation for the specified protocol. |
NullPointerException |
if protocol is null. |
See also:
getInstance
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 |
String : 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 |
String : the name of the provider. |
Returns | |
---|---|
SSLContext |
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:
getInstance
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 |
String : 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 |
Provider : an instance of the provider. |
Returns | |
---|---|
SSLContext |
the new SSLContext object. |
Throws | |
---|---|
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. |
See also:
getProtocol
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
public final Provider getProvider ()
Returns the provider of this SSLContext
object.
Returns | |
---|---|
Provider |
the provider of this SSLContext object |
getServerSessionContext
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 |
getServerSocketFactory
public final SSLServerSocketFactory getServerSocketFactory ()
Returns a ServerSocketFactory
object for
this context.
Returns | |
---|---|
SSLServerSocketFactory |
the ServerSocketFactory object |
Throws | |
---|---|
IllegalStateException |
if the SSLContextImpl requires
initialization and the init() has not been called |
getSocketFactory
public final SSLSocketFactory getSocketFactory ()
Returns a SocketFactory
object for this
context.
Returns | |
---|---|
SSLSocketFactory |
the SocketFactory object |
Throws | |
---|---|
IllegalStateException |
if the SSLContextImpl requires
initialization and the init() has not been called |
getSupportedSSLParameters
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 |
Throws | |
---|---|
UnsupportedOperationException |
if the supported SSL parameters could not be obtained. |
init
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 |
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 |
Throws | |
---|---|
KeyManagementException |
if this operation fails |
setDefault
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.
Developers are strongly discouraged from changing the default SSLContext
as
it is used as the Android default for secure communication by APIs like
SSLSocketFactory#getDefault()
, SSLServerSocketFactory#getDefault()
and
HttpsURLConnection
.
Parameters | |
---|---|
context |
SSLContext : the SSLContext |
Throws | |
---|---|
NullPointerException |
if context is null |
SecurityException |
if a security manager exists and its
checkPermission method does not allow
SSLPermission("setDefaultSSLContext") |