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:
*
| Name | *Supported (API Levels) | *
|---|---|
| Default | *10+ | *
| SSL | *10+ | *
| SSLv3 | *10+ | *
| TLS | *1+ | *
| TLSv1 | *10+ | *
| TLSv1.1 | *16+ | *
| TLSv1.2 | *16+ | *
If a default context was set using the {@link #setDefault
* 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 {@linkplain #init initialization}.
*
* @return the default SSL context
* @throws NoSuchAlgorithmException if the
* {@link SSLContext#getInstance SSLContext.getInstance()} call fails
* @since 1.6
*/
public static synchronized SSLContext getDefault()
throws NoSuchAlgorithmException {
if (defaultContext == null) {
defaultContext = SSLContext.getInstance("Default");
}
return defaultContext;
}
/**
* Sets the default SSL context. It will be returned by subsequent calls
* to {@link #getDefault}. The default context must be immediately usable
* and not require {@linkplain #init initialization}.
*
* @param context the SSLContext
* @throws NullPointerException if context is null
* @throws SecurityException if a security manager exists and its
* checkPermission method does not allow
* SSLPermission("setDefaultSSLContext")
* @since 1.6
*/
public static synchronized void setDefault(SSLContext context) {
if (context == null) {
throw new NullPointerException();
}
SecurityManager sm = System.getSecurityManager();
if (sm != null) {
sm.checkPermission(new SSLPermission("setDefaultSSLContext"));
}
defaultContext = context;
}
/**
* 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 {@link Security#getProviders() Security.getProviders()} method.
*
* @param protocol 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 the new SSLContext object.
*
* @exception NoSuchAlgorithmException if no Provider supports a
* TrustManagerFactorySpi implementation for the
* specified protocol.
* @exception NullPointerException if protocol is null.
*
* @see java.security.Provider
*/
public static SSLContext getInstance(String protocol)
throws NoSuchAlgorithmException {
GetInstance.Instance instance = GetInstance.getInstance
("SSLContext", SSLContextSpi.class, protocol);
return new SSLContext((SSLContextSpi)instance.impl, instance.provider,
protocol);
}
/**
* 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 {@link Security#getProviders() Security.getProviders()} method.
*
* @param protocol 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.
*
* @param provider the name of the provider.
*
* @return the new SSLContext object.
*
* @throws NoSuchAlgorithmException if a SSLContextSpi
* implementation for the specified protocol is not
* available from the specified provider.
*
* @throws NoSuchProviderException if the specified provider is not
* registered in the security provider list.
*
* @throws IllegalArgumentException if the provider name is null or empty.
* @throws NullPointerException if protocol is null.
*
* @see java.security.Provider
*/
public static SSLContext getInstance(String protocol, String provider)
throws NoSuchAlgorithmException, NoSuchProviderException {
GetInstance.Instance instance = GetInstance.getInstance
("SSLContext", SSLContextSpi.class, protocol, provider);
return new SSLContext((SSLContextSpi)instance.impl, instance.provider,
protocol);
}
/**
* 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.
*
* @param protocol 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.
*
* @param provider an instance of the provider.
*
* @return the new SSLContext object.
*
* @throws NoSuchAlgorithmException if a KeyManagerFactorySpi
* implementation for the specified protocol is not available
* from the specified Provider object.
*
* @throws IllegalArgumentException if the provider name is null.
* @throws NullPointerException if protocol is null.
*
* @see java.security.Provider
*/
public static SSLContext getInstance(String protocol, Provider provider)
throws NoSuchAlgorithmException {
GetInstance.Instance instance = GetInstance.getInstance
("SSLContext", SSLContextSpi.class, protocol, provider);
return new SSLContext((SSLContextSpi)instance.impl, instance.provider,
protocol);
}
/**
* 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 the protocol name of this SSLContext object.
*/
public final String getProtocol() {
return this.protocol;
}
/**
* Returns the provider of this SSLContext object.
*
* @return the provider of this SSLContext object
*/
public final Provider getProvider() {
return this.provider;
}
/**
* 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.)
*
* @param km the sources of authentication keys or null
* @param tm the sources of peer authentication trust decisions or null
* @param random the source of randomness for this generator or null
* @throws KeyManagementException if this operation fails
*/
public final void init(KeyManager[] km, TrustManager[] tm,
SecureRandom random)
throws KeyManagementException {
contextSpi.engineInit(km, tm, random);
}
/**
* Returns a SocketFactory object for this
* context.
*
* @return the SocketFactory object
* @throws IllegalStateException if the SSLContextImpl requires
* initialization and the init() has not been called
*/
public final SSLSocketFactory getSocketFactory() {
return contextSpi.engineGetSocketFactory();
}
/**
* Returns a ServerSocketFactory object for
* this context.
*
* @return the ServerSocketFactory object
* @throws IllegalStateException if the SSLContextImpl requires
* initialization and the init() has not been called
*/
public final SSLServerSocketFactory getServerSocketFactory() {
return contextSpi.engineGetServerSocketFactory();
}
/**
* 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, * {@link #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.
*
* @return the SSLEngine object
* @throws UnsupportedOperationException if the underlying provider
* does not implement the operation.
* @throws IllegalStateException if the SSLContextImpl requires
* initialization and the init() has not been called
* @since 1.5
*/
public final SSLEngine createSSLEngine() {
try {
return contextSpi.engineCreateSSLEngine();
} catch (AbstractMethodError e) {
UnsupportedOperationException unsup =
new UnsupportedOperationException(
"Provider: " + getProvider() +
" doesn't support this operation");
unsup.initCause(e);
throw unsup;
}
}
/**
* 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.
*
* @param peerHost the non-authoritative name of the host
* @param peerPort the non-authoritative port
* @return the new SSLEngine object
* @throws UnsupportedOperationException if the underlying provider
* does not implement the operation.
* @throws IllegalStateException if the SSLContextImpl requires
* initialization and the init() has not been called
* @since 1.5
*/
public final SSLEngine createSSLEngine(String peerHost, int peerPort) {
try {
return contextSpi.engineCreateSSLEngine(peerHost, peerPort);
} catch (AbstractMethodError e) {
UnsupportedOperationException unsup =
new UnsupportedOperationException(
"Provider: " + getProvider() +
" does not support this operation");
unsup.initCause(e);
throw unsup;
}
}
/**
* 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 server session context bound to this SSL context */ public final SSLSessionContext getServerSessionContext() { return contextSpi.engineGetServerSessionContext(); } /** * 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 client session context bound to this SSL context */ public final SSLSessionContext getClientSessionContext() { return contextSpi.engineGetClientSessionContext(); } /** * 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 a copy of the SSLParameters object with the default settings * @throws UnsupportedOperationException if the default SSL parameters * could not be obtained. * @since 1.6 */ public final SSLParameters getDefaultSSLParameters() { return contextSpi.engineGetDefaultSSLParameters(); } /** * 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 a copy of the SSLParameters object with the supported * settings * @throws UnsupportedOperationException if the supported SSL parameters * could not be obtained. * @since 1.6 */ public final SSLParameters getSupportedSSLParameters() { return contextSpi.engineGetSupportedSSLParameters(); } }