iaik.security.ssl
Class SSLContext

java.lang.Object
  |
  +--iaik.security.ssl.SSLContext

Direct Known Subclasses:

SSLClientContext

public abstract class SSLContext

extends java.lang.Object

implements java.lang.Cloneable

This class and its subclasses are used to define a SSL/TLS security policy for an SSLTransport. Also see SSLClientContext and SSLServerContext. The settings this class contains are:

• Peer trust verification preferences: A ChainVerifier containing trusted certificates and code to verify a chain according to some profile.
  default value: new ChainVerifier()

• enabled cipher suites: A CipherSuiteList containing the enabled ciphersuites in preference order.
  default value: new CipherSuiteList(CipherSuiteList.L_DEFAULT)

• enabled compression methods: An array of enabled compression methods, predered first.
  default value: NullCompression only

• session manager: The session manager is a class which implements the SessionManager interface. An application can use the DefaultSessionManager or implement its own session caching strategy.
  default value: SessionManager.getDefault()

• random number generator: The secure random number generator for generating all random numbers needed from the handshaker.
  default value: SecurityProvider.getProvider().getSecureRandom()

• cache terminated sessions: A boolean value determining whether or not to resume sessions that have not been properly shutdown. Per spec this should not be done, this exists only to improve performance when communicating with bad server implementations.
  default value: false

• allowed protocol version: The protocol minimum and maximum SSL protocol versions to allow for the handshake.
  default value: VERSION_SSL30, VERSION_TLS10

• Debug stream: Default stream for handshaking debugging data
  default value: null

See Also:

SSLClientContext, SSLServerContext, CipherSuite, CipherSuiteList, CompressionMethod, SessionManager, DefaultSessionManager, ChainVerifier

Field Summary

static int	CERTTYPE_DSS_FIXED_DH Certificate containing a Diffie-Hellman key.
static int	CERTTYPE_DSS_SIGN Certificate containing a DSA key.
static int	CERTTYPE_RSA_FIXED_DH Certificate containing a Diffie-Hellman key.
static int	CERTTYPE_RSA_SIGN Certificate containing an RSA key.
static int	CERTTYPE_UNKNOWN Certificate of unknown type.
static double	LIBRARY_VERSION iSaSiLk library version.
static java.lang.String	LIBRARY_VERSION_STRING iSaSiLk library version as a String.
static int	VERSION_NOT_CONNECTED Version number constant for not yet connected.
static int	VERSION_SSL20 Version number constant for SSL 2.0.
static int	VERSION_SSL30 Version number constant for SSL 3.0.
static int	VERSION_TLS10 Version number constant for TLS 1.0.

Method Summary

void	addTrustedCertificate(X509Certificate cert) Add a trusted certificate.
abstract java.lang.Object	clone()
static X509Certificate[]	convertCertificateChain(Certificate[] certificateChain) Deprecated. no replacement
int[]	getAllowedProtocolVersions() Get the protocol versions enabled for this context.
boolean	getCacheTerminatedSessions() Returns whether or not to cache improperly terminated sessions.
ChainVerifier	getChainVerifier() Get the ChainVerifier for this context.
java.io.PrintWriter	getDebugStream() Get the debug stream for this context.
CipherSuiteList	getEnabledCipherSuiteList() Returns the cipher suites which are enabled in this SSLContext.
CipherSuite[]	getEnabledCipherSuites() Deprecated. use getEnabledCipherSuiteList() instead
CompressionMethod[]	getEnabledCompressionMethods() Returns the compression methods which are enabled in this SSLContext.
SecureRandom	getRandomGenerator() Returns the random number generator currently used by this SSLContext.
SessionManager	getSessionManager() Returns the session manager defined by this SSLContext.
TrustDecider	getTrustDecider() Deprecated. TrustDeciders should no longer be used. See ChainVerifier
void	setAllowedProtocolVersions(int minimumVersion, int maximumVersion) Set the SSL/TLS protocol versions to be accepted during the handshake.
void	setCacheTerminatedSessions(boolean value) Sets whether or not to cache improperly terminated sessions.
void	setChainVerifier(ChainVerifier chainVerifier) Set the ChainVerifier for this context.
void	setDebugStream(java.io.OutputStream out) The default debug stream to use for all Transports created using this context.
void	setDebugStream(java.io.Writer out) The default debug stream to use for all Transports created using this context.
void	setEnabledCipherSuiteList(CipherSuiteList enabledCipherSuites) Sets the cipher suites which are enabled in this SSLContext.
void	setEnabledCipherSuites(CipherSuite[] enabledCipherSuites) Sets the cipher suites which are enabled in this SSLContext.
void	setEnabledCompressionMethods(CompressionMethod[] enabledCompressionMethods) Sets the compression methods which are enabled in this SSLContext.
void	setRandomGenerator(SecureRandom randomGenerator) Sets the random number generator of this SSLContext.
void	setSessionManager(SessionManager sessionManager) Sets the session manager defined by this SSLContext.
void	setTrustDecider(TrustDecider trustDecider) Deprecated. TrustDeciders should no longer be used. See ChainVerifier
java.lang.String	toString() Returns a string representation of this SSLContext.
void	updateCipherSuites() Update the list of enabled ciphersuites to remove all not available using the current SecurityProvider.

Methods inherited from class java.lang.Object

equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

LIBRARY_VERSION

public static final double LIBRARY_VERSION

iSaSiLk library version. Currently 3.0

LIBRARY_VERSION_STRING

public static java.lang.String LIBRARY_VERSION_STRING

iSaSiLk library version as a String. Currently "3.0"

VERSION_NOT_CONNECTED

public static final int VERSION_NOT_CONNECTED

Version number constant for not yet connected.

VERSION_SSL20

public static final int VERSION_SSL20

Version number constant for SSL 2.0.

VERSION_SSL30

public static final int VERSION_SSL30

Version number constant for SSL 3.0.

VERSION_TLS10

public static final int VERSION_TLS10

Version number constant for TLS 1.0.

CERTTYPE_UNKNOWN

public static final int CERTTYPE_UNKNOWN

Certificate of unknown type. Such certificate cannot be used.

CERTTYPE_RSA_SIGN

public static final int CERTTYPE_RSA_SIGN

Certificate containing an RSA key. It should be signed using RSA as well.

CERTTYPE_DSS_SIGN

public static final int CERTTYPE_DSS_SIGN

Certificate containing a DSA key. It should be signed using DSA as well.

CERTTYPE_RSA_FIXED_DH

public static final int CERTTYPE_RSA_FIXED_DH

Certificate containing a Diffie-Hellman key. It should be signed using RSA.

CERTTYPE_DSS_FIXED_DH

public static final int CERTTYPE_DSS_FIXED_DH

Certificate containing a Diffie-Hellman key. It should be signed using DSA.

Method Detail

updateCipherSuites

public void updateCipherSuites()

Update the list of enabled ciphersuites to remove all not available using the current SecurityProvider.

getChainVerifier

public ChainVerifier getChainVerifier()

Get the ChainVerifier for this context. @see ChainVerifier

setChainVerifier

public void setChainVerifier(ChainVerifier chainVerifier)

Set the ChainVerifier for this context. @see ChainVerifier

addTrustedCertificate

public void addTrustedCertificate(X509Certificate cert)

Add a trusted certificate. Shorthand for getChainVerifier().addTrustedCertificate(). If the ChainVerifier is null this call is ignored.

getRandomGenerator

public SecureRandom getRandomGenerator()

Returns the random number generator currently used by this SSLContext.

Returns:

the random number generator currently used by this SSLContext

setRandomGenerator

public void setRandomGenerator(SecureRandom randomGenerator)

Sets the random number generator of this SSLContext.

Parameters:

randomGenerator - the random number generator to use

getSessionManager

public SessionManager getSessionManager()

Returns the session manager defined by this SSLContext.

Returns:

the session manager defined by this SSLContext

setSessionManager

public void setSessionManager(SessionManager sessionManager)

Sets the session manager defined by this SSLContext.

Parameters:

sessionManager - the session manager defined by this SSLContext

getEnabledCipherSuiteList

public CipherSuiteList getEnabledCipherSuiteList()

Returns the cipher suites which are enabled in this SSLContext.

Returns:

the cipher suites which are enabled in this SSLContext

setEnabledCipherSuiteList

public void setEnabledCipherSuiteList(CipherSuiteList enabledCipherSuites)

Sets the cipher suites which are enabled in this SSLContext. Note that you can only enable SSLv3/TLS ciphersuite here. If SSLv2 is enabled the v2 ciphersuites to use are automatically computed as those equivalent to the enabled v3 suites. For more information see the companion iSaSiLk 3.0 use document.

Parameters:

enabledCipherSuites - the cipher suites which are enabled in this SSLContext

setEnabledCipherSuites

public void setEnabledCipherSuites(CipherSuite[] enabledCipherSuites)

Sets the cipher suites which are enabled in this SSLContext. This is done by converting the array to a CipherSuiteList.

Parameters:

enabledCipherSuites - the cipher suites which are enabled in this SSLContext

getEnabledCompressionMethods

public CompressionMethod[] getEnabledCompressionMethods()

Returns the compression methods which are enabled in this SSLContext.

Returns:

the compression methods which are enabled in this SSLContext

setEnabledCompressionMethods

public void setEnabledCompressionMethods(CompressionMethod[] enabledCompressionMethods)

Sets the compression methods which are enabled in this SSLContext.

Parameters:

enabledCompressionMethods - the compression methods which are enabled in this SSLContext

getCacheTerminatedSessions

public boolean getCacheTerminatedSessions()

Returns whether or not to cache improperly terminated sessions.

Returns:

whether or not to cache improperly terminated sessions

setCacheTerminatedSessions

public void setCacheTerminatedSessions(boolean value)

Sets whether or not to cache improperly terminated sessions.

setAllowedProtocolVersions

public void setAllowedProtocolVersions(int minimumVersion,
                                       int maximumVersion)

Set the SSL/TLS protocol versions to be accepted during the handshake. You normally will not need this method as the SSL handshake makes sure that always the highest protocol version supported by both the client and the server is selected. However, you may want to use this method if

• You want to communicate with a buggy server that fails if a certain protocol version is enabled.
• You want to enable SSL 2.0, which is disabled by default.
• You want to disable less secure protocol versions, e.g. use only TLS 1.0.

The parameters passed should be from the VERSION_xxx list defined in this class. Per default both SSLv3 and TLS are enabled, SSLv2 is disabled.

If you want to enable e.g. SSLv2, SSLv3, and TLS use setAllowedProtocolVersions(SSLContext.VERSION_SSL20, SSLContext.VERSION_TLS10);.

getAllowedProtocolVersions

public int[] getAllowedProtocolVersions()

Get the protocol versions enabled for this context. The returned array has two elements, [0] contains the minimumVersion, [1] the maximumVersion.

setDebugStream

public void setDebugStream(java.io.OutputStream out)

The default debug stream to use for all Transports created using this context. Set to null to disable. The settings made here can be overridden using the SSLTransport.setDebugStream() method.

setDebugStream

public void setDebugStream(java.io.Writer out)

The default debug stream to use for all Transports created using this context. Set to null to disable. The settings made here can be overridden using the SSLTransport.setDebugStream() method.

getDebugStream

public java.io.PrintWriter getDebugStream()

Get the debug stream for this context.

toString

public java.lang.String toString()

Returns a string representation of this SSLContext.

Overrides:

toString in class java.lang.Object

Returns:

a string representation

clone

public abstract java.lang.Object clone()

Overrides:

clone in class java.lang.Object

getEnabledCipherSuites

public CipherSuite[] getEnabledCipherSuites()

Deprecated. use getEnabledCipherSuiteList() instead

getTrustDecider

public TrustDecider getTrustDecider()

Deprecated. TrustDeciders should no longer be used. See ChainVerifier

setTrustDecider

public void setTrustDecider(TrustDecider trustDecider)

Deprecated. TrustDeciders should no longer be used. See ChainVerifier

convertCertificateChain

public static X509Certificate[] convertCertificateChain(Certificate[] certificateChain)
                                                 throws CertificateException

Deprecated. no replacement