SSLContext (Java Platform SE 6) (original) (raw)

javax.net.ssl

Class SSLContext

java.lang.Object javax.net.ssl.SSLContext

public class SSLContext

extends Object

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.

Since:

1.4

SSLContext

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

Creates an SSLContext object.

Parameters:

contextSpi - the delegate

provider - the provider

protocol - the protocol

getDefault

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 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](../../../javax/net/ssl/SSLContext.html#init%28javax.net.ssl.KeyManager[], javax.net.ssl.TrustManager[], java.security.SecureRandom%29).

Returns:

the default SSL context

Throws:

[NoSuchAlgorithmException](../../../java/security/NoSuchAlgorithmException.html "class in java.security") - if theSSLContext.getInstance() call fails

Since:

1.6

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](../../../javax/net/ssl/SSLContext.html#init%28javax.net.ssl.KeyManager[], javax.net.ssl.TrustManager[], java.security.SecureRandom%29).

Parameters:

context - the SSLContext

Throws:

[NullPointerException](../../../java/lang/NullPointerException.html "class in java.lang") - if context is null

[SecurityException](../../../java/lang/SecurityException.html "class in java.lang") - if a security manager exists and itscheckPermission method does not allowSSLPermission("setDefaultSSLContext")

Since:

1.6

getInstance

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.

Parameters:

protocol - the standard name of the requested protocol. See Appendix A in the Java Secure Socket Extension Reference Guide for information about standard protocol names.

Returns:

the new SSLContext object.

Throws:

[NoSuchAlgorithmException](../../../java/security/NoSuchAlgorithmException.html "class in java.security") - if no Provider supports a TrustManagerFactorySpi implementation for the specified protocol.

See Also:

Provider

getInstance

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 - the standard name of the requested protocol. See Appendix A in the Java Secure Socket Extension Reference Guide for information about standard protocol names.

provider - the name of the provider.

Returns:

the new SSLContext object.

Throws:

[NoSuchAlgorithmException](../../../java/security/NoSuchAlgorithmException.html "class in java.security") - if a SSLContextSpi implementation for the specified protocol is not available from the specified provider.

[NoSuchProviderException](../../../java/security/NoSuchProviderException.html "class in java.security") - if the specified provider is not registered in the security provider list.

[IllegalArgumentException](../../../java/lang/IllegalArgumentException.html "class in java.lang") - if the provider name is null or empty.

See Also:

Provider

getInstance

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 - the standard name of the requested protocol. See Appendix A in the Java Secure Socket Extension Reference Guide for information about standard protocol names.

provider - an instance of the provider.

Returns:

the new SSLContext object.

Throws:

[NoSuchAlgorithmException](../../../java/security/NoSuchAlgorithmException.html "class in java.security") - if a KeyManagerFactorySpi implementation for the specified protocol is not available from the specified Provider object.

[IllegalArgumentException](../../../java/lang/IllegalArgumentException.html "class in java.lang") - if the provider name is null.

See Also:

Provider

getProtocol

public final String getProtocol()

Returns the protocol name of this SSLContext object.

This is the same name that was specified in one of thegetInstance calls that created thisSSLContext object.

Returns:

the protocol name of this SSLContext object.

getProvider

public final Provider getProvider()

Returns the provider of this SSLContext object.

Returns:

the provider of this SSLContext object

init

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 - the sources of authentication keys or null

tm - the sources of peer authentication trust decisions or null

random - the source of randomness for this generator or null

Throws:

[KeyManagementException](../../../java/security/KeyManagementException.html "class in java.security") - if this operation fails

getSocketFactory

public final SSLSocketFactory getSocketFactory()

Returns a SocketFactory object for this context.

Returns:

the SocketFactory object

Throws:

[IllegalStateException](../../../java/lang/IllegalStateException.html "class in java.lang") - if the SSLContextImpl requires initialization and the init() has not been called

getServerSocketFactory

public final SSLServerSocketFactory getServerSocketFactory()

Returns a ServerSocketFactory object for this context.

Returns:

the ServerSocketFactory object

Throws:

[IllegalStateException](../../../java/lang/IllegalStateException.html "class in java.lang") - if the SSLContextImpl requires initialization and the init() has not been called

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(String, int)](../../../javax/net/ssl/SSLContext.html#createSSLEngine%28java.lang.String, int%29) 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:

the SSLEngine object

Throws:

[UnsupportedOperationException](../../../java/lang/UnsupportedOperationException.html "class in java.lang") - if the underlying provider does not implement the operation.

[IllegalStateException](../../../java/lang/IllegalStateException.html "class in java.lang") - if the SSLContextImpl requires initialization and the init() has not been called

Since:

1.5

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 - the non-authoritative name of the host

peerPort - the non-authoritative port

Returns:

the new SSLEngine object

Throws:

[UnsupportedOperationException](../../../java/lang/UnsupportedOperationException.html "class in java.lang") - if the underlying provider does not implement the operation.

[IllegalStateException](../../../java/lang/IllegalStateException.html "class in java.lang") - if the SSLContextImpl requires initialization and the init() has not been called

Since:

1.5

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:

server session context bound to this SSL context

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:

client session context bound to this SSL context

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:

a copy of the SSLParameters object with the default settings

Throws:

[UnsupportedOperationException](../../../java/lang/UnsupportedOperationException.html "class in java.lang") - if the default SSL parameters could not be obtained.

Since:

1.6

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:

a copy of the SSLParameters object with the supported settings

Throws:

[UnsupportedOperationException](../../../java/lang/UnsupportedOperationException.html "class in java.lang") - if the supported SSL parameters could not be obtained.

Since:

1.6

Submit a bug or feature
For further API reference and developer documentation, see Java SE Developer Documentation. That documentation contains more detailed, developer-targeted descriptions, with conceptual overviews, definitions of terms, workarounds, and working code examples.

Copyright © 1993, 2015, Oracle and/or its affiliates. All rights reserved. Use is subject to license terms. Also see the documentation redistribution policy.

Scripting on this page tracks web page traffic, but does not change the content in any way.