Added in API level 1

SSLContext

open class SSLContext

kotlin.Any
↳	javax.net.ssl.SSLContext

Instances of this class represent a secure socket protocol implementation which acts as a factory for secure socket factories or SSLEngines. 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+

This protocol is described in the SSLContext section of the Java Cryptography Architecture Standard Algorithm Name Documentation.

Summary

Protected constructors
SSLContext(contextSpi: SSLContextSpi!, provider: Provider!, protocol: String!) Creates an SSLContext object.

Public methods
SSLEngine!	createSSLEngine() Creates a new SSLEngine using this context.
SSLEngine!	createSSLEngine(peerHost: String!, peerPort: Int) Creates a new SSLEngine using this context using advisory peer information.
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.
open static SSLContext!	getDefault() Returns the default SSL context.
SSLParameters!	getDefaultSSLParameters() Returns a copy of the SSLParameters indicating the default settings for this SSL context.
open static SSLContext!	getInstance(protocol: String!) Returns a SSLContext object that implements the specified secure socket protocol.
open static SSLContext!	getInstance(protocol: String!, provider: String!) Returns a SSLContext object that implements the specified secure socket protocol.
open static SSLContext!	getInstance(protocol: String!, provider: Provider!) Returns a SSLContext object that implements the specified secure socket protocol.
String!	getProtocol() Returns the protocol name of this SSLContext object.
Provider!	getProvider() Returns the provider of this SSLContext object.
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.
SSLServerSocketFactory!	getServerSocketFactory() Returns a ServerSocketFactory object for this context.
SSLSocketFactory!	getSocketFactory() Returns a SocketFactory object for this context.
SSLParameters!	getSupportedSSLParameters() Returns a copy of the SSLParameters indicating the supported settings for this SSL context.
Unit	init(km: Array<KeyManager!>!, tm: Array<TrustManager!>!, random: SecureRandom!) Initializes this context.
open static Unit	setDefault(context: SSLContext!) Sets the default SSL context.

Protected constructors

SSLContext

Added in API level 1

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

Creates an SSLContext object.

Parameters
contextSpi	SSLContextSpi!: the delegate
provider	Provider!: the provider
protocol	String!: the protocol

Public methods

createSSLEngine

Added in API level 1

fun createSSLEngine(): SSLEngine!

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.

Return
SSLEngine!	the SSLEngine object

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

createSSLEngine

Added in API level 1

fun createSSLEngine(
    peerHost: String!, 
    peerPort: Int
): SSLEngine!

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

Return
SSLEngine!	the new SSLEngine object

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

getClientSessionContext

Added in API level 1

fun getClientSessionContext(): SSLSessionContext!

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.

Return
SSLSessionContext!	client session context bound to this SSL context

getDefault

Added in API level 9

open static fun getDefault(): SSLContext!

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.

Return
SSLContext!	the default SSL context

Exceptions
java.security.NoSuchAlgorithmException	if the javax.net.ssl.SSLContext#getInstance call fails

getDefaultSSLParameters

Added in API level 9

fun getDefaultSSLParameters(): SSLParameters!

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.

Return
SSLParameters!	a copy of the SSLParameters object with the default settings

Exceptions
java.lang.UnsupportedOperationException	if the default SSL parameters could not be obtained.

getInstance

Added in API level 1

open static fun getInstance(protocol: String!): SSLContext!

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.

Return
SSLContext!	the new SSLContext object.

Exceptions
java.security.NoSuchAlgorithmException	if no Provider supports a SSLContextSpi implementation for the specified protocol.
java.lang.NullPointerException	if protocol is null.

See Also

• java.security.Provider

getInstance

Added in API level 1

open static fun getInstance(
    protocol: String!, 
    provider: String!
): SSLContext!

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.

Return
SSLContext!	the new SSLContext object.

Exceptions
java.security.NoSuchAlgorithmException	if a SSLContextSpi implementation for the specified protocol is not available from the specified provider.
java.security.NoSuchProviderException	if the specified provider is not registered in the security provider list.
java.lang.IllegalArgumentException	if the provider name is null or empty.
java.lang.NullPointerException	if protocol is null.

See Also

• java.security.Provider

getInstance

Added in API level 1

open static fun getInstance(
    protocol: String!, 
    provider: Provider!
): SSLContext!

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.

Return
SSLContext!	the new SSLContext object.

Exceptions
java.security.NoSuchAlgorithmException	if a SSLContextSpi implementation for the specified protocol is not available from the specified Provider object.
java.lang.IllegalArgumentException	if the provider is null.
java.lang.NullPointerException	if protocol is null.

See Also

• java.security.Provider

getProtocol

Added in API level 1

fun getProtocol(): String!

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.

Return
String!	the protocol name of this SSLContext object.

getProvider

Added in API level 1

fun getProvider(): Provider!

Returns the provider of this SSLContext object.

Return
Provider!	the provider of this SSLContext object

getServerSessionContext

Added in API level 1

fun getServerSessionContext(): SSLSessionContext!

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.

Return
SSLSessionContext!	server session context bound to this SSL context

getServerSocketFactory

Added in API level 1

fun getServerSocketFactory(): SSLServerSocketFactory!

Returns a ServerSocketFactory object for this context.

Return
SSLServerSocketFactory!	the ServerSocketFactory object

Exceptions
java.lang.IllegalStateException	if the SSLContextImpl requires initialization and the init() has not been called

getSocketFactory

Added in API level 1

fun getSocketFactory(): SSLSocketFactory!

Returns a SocketFactory object for this context.

Return
SSLSocketFactory!	the SocketFactory object

Exceptions
java.lang.IllegalStateException	if the SSLContextImpl requires initialization and the init() has not been called

getSupportedSSLParameters

Added in API level 9

fun getSupportedSSLParameters(): SSLParameters!

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.

Return
SSLParameters!	a copy of the SSLParameters object with the supported settings

Exceptions
java.lang.UnsupportedOperationException	if the supported SSL parameters could not be obtained.

init

Added in API level 1

fun init(
    km: Array<KeyManager!>!, 
    tm: Array<TrustManager!>!, 
    random: SecureRandom!
): Unit

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

Exceptions
java.security.KeyManagementException	if this operation fails

setDefault

Added in API level 9

open static fun setDefault(context: SSLContext!): Unit

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

Exceptions
java.lang.NullPointerException	if context is null
java.lang.SecurityException	if a security manager exists and its checkPermission method does not allow SSLPermission("setDefaultSSLContext")