iaik.security.ssl

Class SSLContext

java.lang.Object

iaik.security.ssl.SSLContext

All Implemented Interfaces:

java.lang.Cloneable

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 main settings of this class contains are (see method documentation for a detailed description):

• 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_TLS10, VERSION_TLS13
• Debug stream: Default stream for handshaking debugging data
  default value: null
• TLS extensions: Any TLS extensions to be supported (and negotiated with the peer)
  default value: null (ignored)
• Renegotiation configuration: Decides whether to allow legacy renegotiation, use no_renegotiation warnings, allow identity change during renegotiation, or disable renegotiation at all
  default value: See method documentation

See Also:

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

Field Summary

Fields

Modifier and Type	Field and Description
static java.lang.String	AVAIL_MODE_DECRYPTED SSLInputInputStream.available mode "decrypted".
static java.lang.String	AVAIL_MODE_ENCRYPTED SSLInputInputStream.available mode "encrypted".
static java.lang.String	AVAIL_MODE_ONE_BYTE SSLInputInputStream.available mode "onebyte".
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_ECDSA_EC Certificate containing an ECC key that maybe used for signing or encryption (key agreement).
static int	CERTTYPE_ECDSA_FIXED_ECDH Certificate containing an ECDH key.
static int	CERTTYPE_ECDSA_SIGN Certificate containing an ECDSA key.
static int	CERTTYPE_RSA_ENCRYPT Certificate containing an RSA key that can be used for encryption.
static int	CERTTYPE_RSA_FIXED_DH Certificate containing a Diffie-Hellman key.
static int	CERTTYPE_RSA_FIXED_ECDH Certificate containing an ECDH key.
static int	CERTTYPE_RSA_SIGN Certificate containing an RSA key that can be used for signatures.
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 java.lang.String	SEND_EMPTY_FRAGMENT Name of the system property, which controls the default empty fragement behaviour.
static int	VERSION_NOT_CONNECTED Version number constant for not yet connected.
static int	VERSION_SSL20 Deprecated. shall not be used anymore
static int	VERSION_SSL30 Deprecated. shall not be used anymore
static int	VERSION_TLS10 Deprecated. (for backwards compatibility still min default version but should not be used anymore)
static int	VERSION_TLS11 Deprecated. shall not be used anymore
static int	VERSION_TLS12 Version number constant for TLS 1.2.
static int	VERSION_TLS13 Version number constant for TLS 1.3.

Method Summary

Modifier and Type	Method and Description
void	addPSKCredential(PSKCredential pskCredential) Adds the given PSKCredential.
void	addTrustedCertificate(java.security.cert.X509Certificate cert) Add a trusted certificate.
int	addTrustedCertificates(java.security.KeyStore trustStore) Add some trusted certificates.
int	addTrustedCertificates(java.security.KeyStore trustStore, java.lang.String[] aliases) Add some trusted certificates.
int	addTrustedCertificates(java.lang.String trustStoreFile, char[] trustStorePassword, java.lang.String trustStoreType, java.lang.String trustStoreProvider) Add some trusted certificates.
void	clearPSKCredentials() Clears the database of pre-shared keys.
java.lang.Object	clone()
static java.security.cert.X509Certificate[]	convertCertificateChain(java.security.cert.Certificate[] certificateChain) Deprecated. no replacement
java.lang.String[]	getAllowedProtocolVersionNames() Get the protocol versions enabled for this context.
int[]	getAllowedProtocolVersions() Get the protocol versions enabled for this context.
boolean	getAllowIdentityChangeDuringRenegotiation() Gets whether to allow peer identity change during renegotiation.
boolean	getAllowLegacyRenegotiation() Gets whether to allow legacy renegotiation.
static java.lang.String[]	getAllSupportedProtocolVersionNames() Gets an array with all supported protocol version names supported by iSaSiLk (except for "SSL20" which is not listed in the array but -- client side -- supported by iSaSiLk).
static int[]	getAllSupportedProtocolVersions() Gets an array with all available protocol version numbers supported by iSaSiLk (except for SSL20 which is not listed in the array but -- client side -- supported by iSaSiLk).
boolean	getCacheTerminatedSessions() Returns whether to cache incorrectly terminated sessions.
ChainVerifier	getChainVerifier() Get the ChainVerifier for this context.
ChannelBindings	getChannelBindings() Gets any ChannelBindings the application may be interested in.
java.io.PrintWriter	getDebugStream() Get the debug stream for this context.
boolean	getDisableRenegotiation() Gets whether renegotiation is disabled at all.
boolean	getDoNotSendServerCloseNotify() Returns whether a close_notify alert shall be sent by the server at shutdown or not.
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.
PSKCredential	getPSKCredential(byte[] identity, SSLTransport transport) Gets the PSKCredential identified by the given identity and/or information provided by the given SSLTransport object.
PSKManager	getPSKManager() Returns the PSK manager used by this SSLContext.
java.security.SecureRandom	getRandomGenerator() Returns the random number generator currently used by this SSLContext.
boolean	getSendEmptyFragment() Returns the actual empty fragment settings.
SessionManager	getSessionManager() Returns the session manager defined by this SSLContext.
TrustDecider	getTrustDecider() Deprecated. TrustDeciders should no longer be used. See ChainVerifier
boolean	getUseNoRenegotiationWarnings() Gets whether to allow old renegotiation.
void	setAllowedProtocolVersions(int minimumVersion, int maximumVersion) Set the SSL/TLS protocol versions to be accepted during the handshake.
void	setAllowedProtocolVersions(java.lang.String minVersion, java.lang.String maxVersion) Set the SSL/TLS protocol versions to be accepted during the handshake.
void	setAllowIdentityChangeDuringRenegotiation(boolean allowIdentityChange) Sets whether to allow that the peer identity may be changed during renegotiation.
void	setAllowLegacyRenegotiation(boolean allowLegacyRenegotation) Sets whether to allow legacy renegotiation.
void	setCacheTerminatedSessions(boolean value) Sets whether to cache incorrectly terminated sessions.
void	setChainVerifier(ChainVerifier chainVerifier) Set the ChainVerifier for this context.
void	setChannelBindings(ChannelBindings channelBindings) Sets any ChannelBindings the application may be interested in.
static void	setCheckTypeOfNextHandshakeMessage(boolean check) Sets whether to check the type of a received handshake message if being allowed/expected at the current handshake state.
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	setDisableRenegotiation(boolean disableRenegotation) Sets whether to disable renegotiation at all.
void	setDoNotPackHandshakeMessages(boolean doNotPackMessages) Sets whether not to pack handshake messages together where possible and send them within one SSL/TLS fragment.
void	setDoNotSendServerCloseNotify(boolean doNotSendServerCloseNotify) Sets whether a close_notify alert shall be sent by the server at shutdown or not.
static void	setDowngradeMaxVersionToTLS12IfNoTLS13CipherSuitesAvailable(boolean downgrade) Sets whether updateCipherSuites shall automatically downgrade the maximum protocol version number to TLS 1.2 if no TLS 1.3 cipher suites are enabled (and TLS 1.3 is configured as maximum protocol version number).
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	setExtensions(ExtensionList extensions) Sets any TLS extensions that shall be used by this context.
void	setInputStreamAvailableMode(java.lang.String availableMode) Sets the SSLInputInputStream.available mode.
void	setPSKCredential(PSKCredential pskCredential) Sets the exclusive PSKCredential to be used by this SSLContext.
void	setPSKManager(PSKManager pskManager) Sets the PSK manager to be used by this SSLContext.
void	setRandomGenerator(java.security.SecureRandom randomGenerator) Sets the random number generator of this SSLContext.
void	setRecordOverheadSize(int size) Sets the TLS record overhead size.
void	setSendEmptyFragment(boolean sendEmptyFragment) To enable IV randomization in CBC mode, an empty fragment will be sent before the encrypted plaintext fragment.
void	setSendRecordOverflowAlert(boolean send) Sets whether a record_overflow alert shall be sent if a record is received that exceeds the max record size.
void	setSessionManager(SessionManager sessionManager) Sets the session manager defined by this SSLContext.
static void	setTls13MiddleboxCompatibilityMode(boolean mode) Sets whether to send change_cipher_spec messages when TLS 1.3 is used.
void	setTLS13WaitOnPeerCloseNotify(int size) Sets whether to wait until the peer has sent its close_notify alert when closing the transport.
void	setTrustDecider(TrustDecider trustDecider) Deprecated. TrustDeciders should no longer be used. See ChainVerifier
void	setUseNoRenegotiationWarnings(boolean useNoRenegotiationWarnings) Sets whether to use (send) no_renegotiation warnings as response to unsupported renegotiation requests.
void	setUseRecordSplitting(boolean splitRecords) Sets whether to use 1/n-1 record splitting in CBC mode as a countermeasure against the Rizzo/Duong BEAST (Browser Exploit Against SSL/TLS) attack against the SSL 3.0 / TLS 1.0 protocol.
java.lang.String	toString() Returns a string representation of this SSLContext.
void	updateCipherSuites() Update the list of enabled cipher suites to remove all cipher suites that cannot be used with the enabled protocol version interval and/or are not supported by 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 6.1

See Also:

Constant Field Values

LIBRARY_VERSION_STRING

public static final java.lang.String LIBRARY_VERSION_STRING

iSaSiLk library version as a String. Currently "6.1"

See Also:

Constant Field Values

VERSION_NOT_CONNECTED

public static final int VERSION_NOT_CONNECTED

Version number constant for not yet connected.

See Also:

Constant Field Values

VERSION_SSL20

public static final int VERSION_SSL20

Deprecated. shall not be used anymore

Version number constant for SSL 2.0.

See Also:

Constant Field Values

VERSION_SSL30

public static final int VERSION_SSL30

Deprecated. shall not be used anymore

Version number constant for SSL 3.0.

See Also:

Constant Field Values

VERSION_TLS10

public static final int VERSION_TLS10

Deprecated. (for backwards compatibility still min default version but should not be used anymore)

Version number constant for TLS 1.0.

See Also:

Constant Field Values

VERSION_TLS11

public static final int VERSION_TLS11

Deprecated. shall not be used anymore

Version number constant for TLS 1.1.

See Also:

Constant Field Values

VERSION_TLS12

public static final int VERSION_TLS12

Version number constant for TLS 1.2.

See Also:

Constant Field Values

VERSION_TLS13

public static final int VERSION_TLS13

Version number constant for TLS 1.3.

See Also:

Constant Field Values

SEND_EMPTY_FRAGMENT

public static final java.lang.String SEND_EMPTY_FRAGMENT

Name of the system property, which controls the default empty fragement behaviour. If this system property is set, in CBC mode an empty fragment will be sent before every data fragment.

See Also:

setSendEmptyFragment(boolean), getSendEmptyFragment(), Constant Field Values

AVAIL_MODE_ONE_BYTE

public static final java.lang.String AVAIL_MODE_ONE_BYTE

SSLInputInputStream.available mode "onebyte". Configures the SSLInputStream.available behaviour to return 1 (byte) if available is called before the data has been already decrypted by a preceding read() call. A subsequent read() call will decrypt the next SSL message to return the exact number of (unencrypted) bytes.

See Also:

Constant Field Values

AVAIL_MODE_ENCRYPTED

public static final java.lang.String AVAIL_MODE_ENCRYPTED

SSLInputInputStream.available mode "encrypted". Configures the SSLInputStream.available behaviour to return the number of encrypted bytes if available is called before the data has been already decrypted by a preceding read() call. This is the default behaviour. Note that the number of (encrypted) bytes maybe greater than the number of (decrypted) bytes that are actually available. You may change the default behaviour by calling method setInputStreamAvailableMode.

See Also:

Constant Field Values

AVAIL_MODE_DECRYPTED

public static final java.lang.String AVAIL_MODE_DECRYPTED

SSLInputInputStream.available mode "decrypted". Configures the SSLInputStream.available behaviour to return the number of decrypted bytes if available is called before the data has been already decrypted by a preceding read() call. If this option is selected a read() call may be necessary within method available to read (and decrypt) the next SSL record. This may cause method available to block if not enough bytes are available from the underlying stream to read a full SSL record. You may enable this behaviour by calling method setInputStreamAvailableMode.

See Also:

Constant Field Values

CERTTYPE_UNKNOWN

public static final int CERTTYPE_UNKNOWN

Certificate of unknown type. Such certificate cannot be used.

See Also:

Constant Field Values

CERTTYPE_RSA_SIGN

public static final int CERTTYPE_RSA_SIGN

Certificate containing an RSA key that can be used for signatures. It should be signed using RSA as well.

See Also:

Constant Field Values

CERTTYPE_RSA_ENCRYPT

public static final int CERTTYPE_RSA_ENCRYPT

Certificate containing an RSA key that can be used for encryption. It should be signed using RSA as well. In difference to the other RSA certificate types this is not a valid client authentication type and is used only with SSLServerContext.addServerCredentials().

See Also:

Constant Field Values

CERTTYPE_DSS_SIGN

public static final int CERTTYPE_DSS_SIGN

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

See Also:

Constant Field Values

CERTTYPE_RSA_FIXED_DH

public static final int CERTTYPE_RSA_FIXED_DH

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

See Also:

Constant Field Values

CERTTYPE_DSS_FIXED_DH

public static final int CERTTYPE_DSS_FIXED_DH

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

See Also:

Constant Field Values

CERTTYPE_ECDSA_SIGN

public static final int CERTTYPE_ECDSA_SIGN

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

See Also:

Constant Field Values

CERTTYPE_RSA_FIXED_ECDH

public static final int CERTTYPE_RSA_FIXED_ECDH

Certificate containing an ECDH key. It should be signed using RSA.

See Also:

Constant Field Values

CERTTYPE_ECDSA_FIXED_ECDH

public static final int CERTTYPE_ECDSA_FIXED_ECDH

Certificate containing an ECDH key. It should be signed using ECDSA.

See Also:

Constant Field Values

CERTTYPE_ECDSA_EC

public static final int CERTTYPE_ECDSA_EC

Certificate containing an ECC key that maybe used for signing or encryption (key agreement). It should be signed using ECDSA. In difference to the other EC certificate types this is not a valid client authentication type. It is used to identify EC certificates that may be used for ECDSA signing or ECDH key agreement (for instance, EC certificates that do not have a KeyUsage extension or have both digitalSignature and keyAgreement bits set).

See Also:

Constant Field Values

Method Detail

setCheckTypeOfNextHandshakeMessage

public static void setCheckTypeOfNextHandshakeMessage(boolean check)

Sets whether to check the type of a received handshake message if being allowed/expected at the current handshake state.

By default iSaSiLk checks for any received handshake message if its type is allowed/expected at the current handshake state. Although iSaSiLk performs a handshake state check in any case, disabling the handshake message type check is not recommended any maybe only done for error detecting purposes.

Parameters:

check - whether to check the type of an handshake message (default: true)

setTls13MiddleboxCompatibilityMode

public static void setTls13MiddleboxCompatibilityMode(boolean mode)

Sets whether to send change_cipher_spec messages when TLS 1.3 is used.

TLS 1.3 does not require to use change_cipher_spec messages in TLS 1.3 handshakes. However, for middlebox compatibility it may be preferable to send (dummy) change_cipher_spec messages.
Note that the spec requires that a TLS 1.3 server must send send (dummy) change_cipher_spec messages in a TLS 1.3 handshake if the client uses a non-empty session id. iSaSiLk clients use non-empty session ids and iSaSiLk clienst and servers send (dummy) change_chipher_spec messages in TLS 1.3 handshakes, too.
When switching off the middle box compatibility mode by calling setTls13MiddleboxCompatibilityMode(false) iSaSiLk does not send change_chipher_spec messages. This means that in this case an iSaSiLk server does not send a change_cipher_spec message even if the client uses a non-empty sessio id.

Parameters:

mode - whether to send chenge_cipher_spec messages when TLS 1.3 is used (default: true; change_cipher_spec messages are sent)

setDowngradeMaxVersionToTLS12IfNoTLS13CipherSuitesAvailable

public static void setDowngradeMaxVersionToTLS12IfNoTLS13CipherSuitesAvailable(boolean downgrade)

Sets whether updateCipherSuites shall automatically downgrade the maximum protocol version number to TLS 1.2 if no TLS 1.3 cipher suites are enabled (and TLS 1.3 is configured as maximum protocol version number). By default updateCipherSuites() will throw an exception in this case indicating that the SSLContext is no properly configured and TLS 1.3 cannot be enabled without any TLS 1.2 cipher suites.

Deciding whether setting downgrade to true should be done with special care only. Having TLS 1.3 but not any TLS 1.3 cipher suites enabled is a clear indication of some mis-configuration which might not be detected when automatically downgrading to TLS 1.2. Thus considering to set downgrade to true might be done only if required for backwards compatibility.

Parameters:

downgrade - whether to automatically downgrade to TLS 1.3 if no TLS 1.3 cipher suites are enabled (default: false; updateCipherSuites() will throw an exception)

getAllSupportedProtocolVersionNames

public static java.lang.String[] getAllSupportedProtocolVersionNames()

Gets an array with all supported protocol version names supported by iSaSiLk (except for "SSL20" which is not listed in the array but -- client side -- supported by iSaSiLk).

Note the difference to method getAllowedProtocolVersionNames() which returns the protocol versions enabled for some specific SSLContext object.

Returns:

an array with all protocol version names supported by iSaSiLk ("SSL30", "TLS10", "TLS11", "TLS12").

getAllSupportedProtocolVersions

public static int[] getAllSupportedProtocolVersions()

Gets an array with all available protocol version numbers supported by iSaSiLk (except for SSL20 which is not listed in the array but -- client side -- supported by iSaSiLk).

Note the difference to method getAllowedProtocolVersions() which returns the protocol versions enabled for some specific SSLContext object.

Returns:

an array with all protocol version numbers supported by iSaSiLk -- 768 (0x0300), 769 (0x0301), 770 (0x0302), 771 (0x0303) for SSL30, TLS10, TLS11, TLS12

updateCipherSuites

public void updateCipherSuites()

Update the list of enabled cipher suites to remove all cipher suites that cannot be used with the enabled protocol version interval and/or are not supported by the current SecurityProvider.

Since cipher suite availability also depends on the enabled protocol version interval method setAllowedProtocolVersions shall be called before calling method updateCipherSuites

Also cipher suite availability may depend on the extension list (TLS 1.2 SignatureAlgorithms), thus -- if you want to explicitly set an SignatureAlgorithms extension -- you may call method setExtensions before method updateCipherSuites. This is not necessary if you rely on the default SignatureAlgorithms selection.

Throws:

java.lang.NullPointerException - if no cipher suite cannot be enabled because none of the configured suites is supported

getChainVerifier

public ChainVerifier getChainVerifier()

Get the ChainVerifier for this context.

See Also:

ChainVerifier

setChainVerifier

public void setChainVerifier(ChainVerifier chainVerifier)

Set the ChainVerifier for this context.

See Also:

ChainVerifier

addTrustedCertificate

public void addTrustedCertificate(java.security.cert.X509Certificate cert)

Add a trusted certificate. Shorthand for getChainVerifier().addTrustedCertificate(). If the ChainVerifier is null this call is ignored.
Add null if want to accept if the peer does not send a certificate (i.e. you want to trust an anonymous peer).

addTrustedCertificates

public int addTrustedCertificates(java.lang.String trustStoreFile,
                                  char[] trustStorePassword,
                                  java.lang.String trustStoreType,
                                  java.lang.String trustStoreProvider)
                           throws java.security.KeyStoreException

Add some trusted certificates. The trusted certificates are read from a KeyStore.

Any trusted certificate entry contained in the KeyStore is added as trusted certificate.

Parameters:

trustStoreFile - the name of the KeyStore file from which to read trusted certificates

trustStorePassword - the password of the trusted KeyStore

trustStoreType - the type of the trusted KeyStore; default: IAIKKeyStore

trustStoreProvider - the provider of the trusted KeyStore; default: IAIK

Returns:

the number of trusted certificates added from the KeyStore

Throws:

java.security.KeyStoreException - if an error occurs while getting certificates from the KeyStore

addTrustedCertificates

public int addTrustedCertificates(java.security.KeyStore trustStore)
                           throws java.security.KeyStoreException

Add some trusted certificates. The trusted certificates are read from a KeyStore.

The KeyStore must have been already loaded when calling this method. Any trusted certificate entry contained in the KeyStore is added as trusted certificate.

Parameters:

trustStore - the KeyStore from which to read the trusted certificates

Returns:

the number of trusted certificates added from the trust store

Throws:

java.security.KeyStoreException - if an error occurs while getting certificates from the KeyStore

addTrustedCertificates

public int addTrustedCertificates(java.security.KeyStore trustStore,
                                  java.lang.String[] aliases)
                           throws java.security.KeyStoreException

Add some trusted certificates. The trusted certificates are read from a KeyStore.

This method is similar to method addTrustedCertificates(KeyStore) except that only those certificate entries are added that are specified by their aliases. If no aliases are specified, all trusted certificate entry contained in the KeyStore is added as trusted certificate (in this case this method does the same as method addTrustedCertificates(KeyStore)).

Parameters:

trustStore - the KeyStore from which to read the trusted certificates

aliases - the alias names of the certificate entries to be added as trusted certificates

Returns:

the number of trusted certificates added from the trust store

Throws:

java.security.KeyStoreException - if an error occurs while getting certificates from the KeyStore, or no certificate entry is available for any of the specified alias names

getRandomGenerator

public java.security.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(java.security.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

getPSKManager

public PSKManager getPSKManager()

Returns the PSK manager used by this SSLContext. A PSK manager may have been set for managing pre shared keys for psk based cipher suites. If no PSK manager has been explicitly set by the application, the DefaultPSKManager is used.

Returns:

the PSK manager used by this SSLContext

setPSKManager

public void setPSKManager(PSKManager pskManager)

Sets the PSK manager to be used by this SSLContext. If no PSK manager is explicitly set by the application, the DefaultPSKManager is used for managing pre shared keys for psk based cipher suites.

Parameters:

pskManager - the PSK manager to be used by this SSLContext

addPSKCredential

public void addPSKCredential(PSKCredential pskCredential)

Adds the given PSKCredential. The given PSKCredential identifies a pre shared key to be used with psk cipher suites. If an exclusive PSKCredential has been set (or will be set) by calling method setPSKCredential any PSKCredential added by this method will be ignored by any further call to method getPSKCredential.

Parameters:

pskCredential - the PSKCredential to be added

setPSKCredential

public void setPSKCredential(PSKCredential pskCredential)

Sets the exclusive PSKCredential to be used by this SSLContext. The given PSKCredential identifies a pre-shared key to be used with psk cipher suites. If this method is used for exclusively setting a PSKCredential, any other PSKCredential that may have been added so far (or may be added later) is ignored. If a PSKManager is installed, it is ignored too.

Be careful to use setPSKCredential on the server side. In this case your server will only have one single pre-shared key to be used with any client that requests a PSK based TLS communication.
However, on the client side you already will know the server when creating the SSLClientContext, thus you also will know the pre-shared key to be used for establishing a TLS-PSK session with this server. For that reason you may not need a PSKManager and may explicitly set the corresponding PSKCredential to be used with this specific SSLClientContext, e.g.:

 
  // psk identity
 String identity = ...;
 // server name (remote peer id)
 String serverName = ...;
 // the pre-shared key
 PreSharedKey psk = ...;
 // create PSKCredential
 PSKCredential pskCredential = new PSKCredential(identity, psk);
 // set remote peer id
 pskCredential.setRemotePeerId(serverName);
 // create client context
 SSLClientContext context = new SSLClientContext();
 // set pre-shared key
 context.setPSKCredential(pskCredential);
 // enable PSK cipher suites
 CipherSuiteList suites = new CipherSuiteList();
 suites.add(CipherSuite.CS_ALL_PSK);
 context.setEnabledCipherSuiteList(suites);
 context.updateCipherSuites();
 ...
 

Of course you can use a PSKManager on the client side, too (for maintaining several pre-shared key and let the PSKManager search for the right psk when connecting to some server). In this case you may add PSKCredentials by calls of method addPSKCredential.

Parameters:

pskCredential - the PSKCredential to be used by this SSLContext with psk cipher suites

Throws:

java.lang.IllegalArgumentException - when trying to set an exclusive PSK credential on the server side

getPSKCredential

public PSKCredential getPSKCredential(byte[] identity,
                                      SSLTransport transport)
                               throws SSLException

Gets the PSKCredential identified by the given identity and/or information provided by the given SSLTransport object.

This method maybe called by iSaSiLk in two different situations, depending on if the identity argument is null or not. If not null iSaSiLk asks for a PSKCredential with the specific psk identity (see 1. below). If null iSaSiLK searches based on identification information provided by the second (SSLTransport) argument (see 2. below).

1. If the identity argument is not null this method is called by iSaSiLk to search for a pre-shared key for the given identity. On the client side, the given identity represents the psk identity hint that may have been sent by the server within the ServerKeyExchange message. Note that the TLS-PSK specification (RFC 4279) does NOT recommend to use a psk identity hint. Unless not explicitly required by the application environment, the server SHOULD NOT send a psk identity hint, and the client MUST ignore a psk identity hint if sent by the server.
   By default pre-shared keys are maintained by the iSaSiLk PSKManager. The default PSKManager implementation requires that each identity is unique for the whole application environment. Thus, if the identity argument is not null the second argument (SSLTransport) of this method is not used by the DefaultPSKManager except for on the client side when having received a psk identity hint but not found a proper PSKCredential. In this case the DefaultPSKManager looks if he has a PSKCredential with the peer id of the server (got from the SSLTransport argument).
   However, an application-specific PSKManager implementation may need information provided by the SSLTransport object in any case (for instance, to support a psk management policy allowing to use same identities for different remote peer ids).

2. If the identity argument is null this method is called by iSaSiLk to search for a pre-shared key based on peer information provided by the given SSLTransport object. The default PSKManager implementation asks the given SSLTransport for peer identification information by calling the following methods (in that order):
   • transport.getRemotePeerName()
   • transport.getRemoteIndetAddress().getHostAddress()
   • transport.getRemotePeerId()

   If you are, for instance, on the client side and want to go into a psk based TLS session with a server "pskserver.iaik.tugraz.at" with ip address "129.27.142.47" listening on port 4433, the SSL(Socket)Transport methods above will return the following values (in that order):

   • pskserver.iaik.tugraz.at
   • 129.27.142.47
   • 129.27.142.47:4433

   Thus, when registering a PSKCredential to be used for a TLS communication with the "pskserver.iaik.tugraz.at" server, it must have one of the three identification information values from above as remote peer id, e.g.:

    // the psk identity
    String identity = ...;
    // the pre-shared key
    PreSharedKey psk = ...;
    // create PSKCredential
    PSKCredential pskCredential = new PSKCredential(identity, psk);
    // set remote peer id
    int serverPort = 4433;
    
    String serverName = "pskserver.iaik.tugraz.at";
    pskCredential.setRemotePeerId(serverName);
    
    // create SSLClientContext and add the credential
    SSLClientContext context = new SSLClientContext();
    // calling this method forwards the PSKCredential to the internal PSKManager
    context.addPSKCredential(pskCredential);
    

   When now connecting to server "pskserver.iaik.tugraz.at", iSaSiLk asks the PSK manager for a PSKCredential with remote peer id "pskserver.iaik.tugraz.at" and the connection can succeed if both parties support the negotiated cipher suite and have a corresponding pre-shared key:

    //  enable PSK cipher suites
    CipherSuiteList suites = new CipherSuiteList();
    suites.add(CipherSuite.CS_ALL_PSK);
    SSLSocket socket = new SSLSocket(serverName, serverPort, context);
    // start handshake
    socket.startHandshake();
    // psk identity
    String pskIdentity = socket.getPSKIdentity();
    if (pskIdentity != null) {
      System.out.println("PSK Identity: " + pskIdentity);
    }
    // send GET-request
    System.out.println("Sending HTTPS request to " + serverName);
    PrintWriter writer = Utils.getASCIIWriter(socket.getOutputStream());
    BufferedReader reader = Utils.getASCIIReader(socket.getInputStream());
    writer.println("GET / HTTP/1.0");
    writer.println();
    writer.flush();
    // read response
    while( true ) {
      String line = reader.readLine();
      if( line == null ) {
        break;
      }
      System.out.print(":");
      System.out.println(line);
    }
    socket.close();
    

   Note, that if the psk identity already represents any of the remote peer ids, it may be not necessary to explicitly set it as remote peer id for the psk credential (the DefaultPSKManager implementation looks for the id in this case, too), e.g.:

    String serverName = "pskserver.iaik.tugraz.at";
    // the psk identity
    String identity = serverName;
    // the pre-shared key
    PreSharedKey psk = ...;
    // create PSKCredential
    PSKCredential pskCredential = new PSKCredential(identity, psk);
    

   In similar way, if the remote peer id is equal to the psk identity hint, it may be sufficient to only set the psk identity hint.

By default pre-shared keys are maintained by the iSaSiLk PSKManager. However, you can disable the PSKManager at all by using method setPSKCredential for specifying an exclusive PSKCredential to be used only with some specific SSLContext. This may be suitable on the client side: since you already know the server when creating the SSLClientContext you also will know the pre-shared key to be used for establishing a TLS-PSK session with this server. Thus you may not neet a PSKManager and may explicitly set the corresponding PSKCredential to be used with this specific SSLClientContext. However, be careful to use setPSKCredential on the server side. In this case your server will only have one single pre-shared key to be used with any client that requests a PSK based TLS communication. An application also may bypass the default iSaSiLk PSK management by extending class SSLClientContext and overriding this getPSKCredential method to follow some different strategy (for instance poping up some dialog window etc. to ask the user for entering a pre-shared key...).

Parameters:

identity - the (UTF-8 encoded) identity, if not null identifying the PSK for which to search

transport - the SSLTransport to maybe used for getting information about the remote peer (if identity is null or if required by the psk management implementation)

Returns:

the PSKCredential fulfilling the given search requirements; or null if no such PSKCredential is included

Throws:

SSLException - if the given identity is invalid encoded (not UTF-8)

clearPSKCredentials

public void clearPSKCredentials()

Clears the database of pre-shared keys.

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 (the returned array is not cloned or copied by this method)

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 (the enabledCompressionMethods array is not cloned or copied by this method)

getCacheTerminatedSessions

public boolean getCacheTerminatedSessions()

Returns whether to cache incorrectly terminated sessions.

Unfortunately a number of SSL/TLS applications, seemingly including most or all versions of the Microsoft IIS server and IE explorer, do not correctly shutdown the SSL/TLS layer before closing the connection on the TCP level. Depending on the protocol version this may cause EOFExceptions to be thrown and also may cause iSaSiLk to invalidate the session resulting in a full handshake for each connection and consequently lower performance.
Note that this is a bug in those client/server implementations and not in iSaSiLk! Anyway, you can tell iSaSiLk to ignore this (i.e. no EOFException will be thrown and the session is cached as usually) by using method setCacheTerminatedSessions:

 context.setCacheTerminatedSessions(true);
 

Note that when activated you may be vulnerable to truncation attacks. Note also that TLS 1.0 (RFC 2246) does not allow to resume incorrectly terminated sessions. However, since closing TLS sessions without correct shutdown is a common practice, TLS 1.1 (RFC 4346) does no longer require to invalidate incorrectly terminated sessions. For that reason, the default behaviour of iSaSiLk is different for TLS 1.1 (incorrectly terminated sessions are cached) and protocol versions prior TLS 1.1 where incorrectly terminated sessions cause an EOF exception and are not cached by default. You may explicitly call method setCacheTerminatedSessions if you want to enforce the same behaviour for all protocol versions.

Returns:

whether or not to cache incorrectly terminated sessions,

• true if explicitly set by the application by calling setCacheTerminatedSessions(true) or this context has been configured to support TLS 1.1 only
• false if explicitly set by the application by calling setCacheTerminatedSessions(false) or this context has NOT been explicitly configured to support TLS 1.1 only

Note that if this context does support different protocol versions (including TLS 1.1) and setCacheTerminatedSessions has not been called explictly, the value returned by this method may differ from the actual behaviour which depends on the version that actually has been negotiated between client and server during the handshake. For instance, if you have decided to use the default settings and this SSLContext supports versions SSL 3.0, TLS 1.0, TLS 1.1 this method will return false, however, an incorrectly terminated session will be cached by default if TLS 1.1 is negotiated as active version between client and server

setCacheTerminatedSessions

public void setCacheTerminatedSessions(boolean value)

Sets whether to cache incorrectly terminated sessions.

Unfortunately a number of SSL/TLS applications, seemingly including most or all versions of the Microsoft IIS server and IE explorer, do not correctly shutdown the SSL/TLS layer before closing the connection on the TCP level. Depending on the protocol version this may cause EOFExceptions to be thrown and also may cause iSaSiLk to invalidate the session resulting in a full handshake for each connection and consequently lower performance.
Note that this is a bug in those client/server implementations and not in iSaSiLk! Anyway, you can tell iSaSiLk to ignore this (i.e. no EOFException will be thrown and the session is cached as usually) by calling:

 context.setCacheTerminatedSessions(true);
 

Note that when activated you may be vulnerable to truncation attacks. Note also that TLS 1.0 (RFC 2246) does not allow to resume incorrectly terminated sessions. However, since closing TLS sessions without correct shutdown is a common practice, TLS 1.1 (RFC 4346) does no longer require to invalidate incorrectly terminated sessions. For that reason, the default behaviour of iSaSiLk is different for TLS 1.1 (incorrectly terminated sessions are cached) and protocol versions prior TLS 1.1 where incorrectly terminated sessions cause an EOF exception and are not cached by default. You may explicitly call this setCacheTerminatedSessions method if you want to enforce the same behaviour for all protocol versions.

Parameters:

value - true if you want to cache incorrectly terminated sessions, false if you do not want to cache them

setAllowedProtocolVersions

public void setAllowedProtocolVersions(int minimumVersion,
                                       int maximumVersion)
                                throws java.lang.IllegalArgumentException

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, TLS 1.1, or TLS 1.2.

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. SSLv3 and TLS use setAllowedProtocolVersions(SSLContext.VERSION_SSL30, SSLContext.VERSION_TLS12);.

Throws:

throws - IllegalArgumentException if the given protocol version String is not supported or the context configuration does not comply with the versions

java.lang.IllegalArgumentException

setAllowedProtocolVersions

public void setAllowedProtocolVersions(java.lang.String minVersion,
                                       java.lang.String maxVersion)
                                throws java.lang.IllegalArgumentException

Set the SSL/TLS protocol versions to be accepted during the handshake.

Parameters:

minVersion - the minimum protocol version as String

maxVersion - the maximum protocol version as String

Throws:

throws - IllegalArgumentException if the given protocol version String is not supported or the context configuration does not comply with the versions

java.lang.IllegalArgumentException

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.

Returns:

an array containing the protocol versions enabled for this session

getAllowedProtocolVersionNames

public java.lang.String[] getAllowedProtocolVersionNames()

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

Returns:

a String array containing the protocol versions enabled for this session

setExtensions

public final void setExtensions(ExtensionList extensions)
                         throws java.lang.IllegalArgumentException

Sets any TLS extensions that shall be used by this context.

The extensions have to be specified as ExtensionList. The ExtensionList configuration shall already be finsihed when calling this setExtensions method to set the ExtensionList for an SSLContext. Any modifications an application may apply to an ExtensionList after having set it for an SSLContext are not recognized by the SSLContext.

Parameters:

extensions - the TLS ExtensionList to be used by this SSLContext, or null if no extensions shall be supported by this SSLContext

Throws:

IllegalArgumetException - if something is wrong with any of the extensions to be added

java.lang.IllegalArgumentException

setTLS13WaitOnPeerCloseNotify

public void setTLS13WaitOnPeerCloseNotify(int size)

Sets whether to wait until the peer has sent its close_notify alert when closing the transport.
TLS 1.3 (RFC 8446) requires that each side of the connection sends a close_notify alert before closing the write side of the connection, unless it has already sent some error alert. Although a TLS endpoint also may immediately close its read side, too, it may wait doing so until having received the close_notify alert from the peer.

This method allows to configure the behaviour when closing the SSL transport. By default the close method waits for the peer close_notify alert by reading up to 4096 bytes from the input stream. If the close_notify has not been received so far, the connection is shut down and closed without further waiting. By de/increasing the amount of bytes to be read the wait interval can be de/increased. By setting the number of bytes to <=0, the connection is immediately shut down and closed without waiting on the close_notify from the peer.

Note that closing will block until data is received from peer.

Parameters:

size - the amount of bytes to read until closing the connection without further waiting on the close_notify alert from the peer (default: 4096); or -1 for immediately shutting down / closing the connection

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 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 java.security.cert.X509Certificate[] convertCertificateChain(java.security.cert.Certificate[] certificateChain)
                                                                    throws java.security.cert.CertificateException

Deprecated. no replacement

Throws:

java.security.cert.CertificateException

setSendEmptyFragment

public void setSendEmptyFragment(boolean sendEmptyFragment)

To enable IV randomization in CBC mode, an empty fragment will be sent before the encrypted plaintext fragment. This might cause interop. issues. The default behavior is controlled by the SSLContext.SEND_EMPTY_FRAGMENT system property. If this system property is set (whatever value) the empty fragments feature is enabled. This method overrules the system property settings.

If sending of empty fragments is enabled and SSL 3.0 / TLS 1.0 is used, 1/n-1 record splitting is automatically disabled. Thus, if you call this method with sendEmptyFragment set to true after calling method setUseRecordSplitting 1/n-1 record splitting will not be used because empty fragments will be sent.

Parameters:

sendEmptyFragment - if true an empty fragment will be sent.

getSendEmptyFragment

public boolean getSendEmptyFragment()

Returns the actual empty fragment settings.

Returns:

true an empty fragment will be sent.

See Also:

setSendEmptyFragment(boolean)

setUseRecordSplitting

public void setUseRecordSplitting(boolean splitRecords)

Sets whether to use 1/n-1 record splitting in CBC mode as a countermeasure against the Rizzo/Duong BEAST (Browser Exploit Against SSL/TLS) attack against the SSL 3.0 / TLS 1.0 protocol. Protocol versions > 1.0 are not vulnerable.

If 1/n-1 record splitting is enabled and SSL 3.0 / TLS 1.0 is used, sending of empty fragments is automatically disabled. Thus, if you call this method with splitRecords set to true after calling method setSendEmptyFragment no empty fragments will be sent because 1/n-1 record splitting is used.

Parameters:

splitRecords - true (default) to use 1/n-1 record splitting, false to not use it

setDoNotSendServerCloseNotify

public void setDoNotSendServerCloseNotify(boolean doNotSendServerCloseNotify)

Sets whether a close_notify alert shall be sent by the server at shutdown or not. If this variable is set, a close_notify alert will not be sent during shutdown on the server side. Some versions of MSIE may not be able to properly deal with close_notify alert messages; to avoid such problems a server application may decide to not send a close_notify at shutdown. However, please be aware that not sending a close_notify may make the client vulnerable for truncation attacks.

Parameters:

doNotSendServerCloseNotify - if true the server will not send a close_notify alert at shutdown

getDoNotSendServerCloseNotify

public boolean getDoNotSendServerCloseNotify()

Returns whether a close_notify alert shall be sent by the server at shutdown or not. If this variable is set, a close_notify alert will not be sent during shutdown on the server side. Some versions of MSIE may not be able to properly deal with close_notify alert messages; to avoid such problems a server application may decide to not send a close_notify at shutdown. However, please be aware that not sending a close_notify may make the client vulnerable for truncation attacks.

Returns:

if the server will not send a close_notify alert at shutdown

setRecordOverheadSize

public void setRecordOverheadSize(int size)

Sets the TLS record overhead size. The maximum plaintext fragment length used by the SSL/TLS protocol is 2^14 (16384) bytes. Calculating some overhead (header length, mac length, padding length,...) the internal data buffer may have to be somewhat larger than the maximum fragment length. By default iSaSiLk adds a overhead size of 5 (header length) + 1024 (compression size increase) + 20 (mac length) + 256 (max padding length) + 16 (max explict IV size, TLS 1.1) + 1024 (reverse) = 2345 bytes to give the actual buffer size. When the max_fragment_length extension is used iSaSiLk adds an overhead size of 297 bytes only (header length + mac length + max padding length + max explicit IV size) to the negotiated fragment length.
This method may be used to set greater (or smaller) record overhead size. Usually it should be NOT necessary for an application to use this method at all. The record size is defined by the SSL/TLS protocol and a record_overflow alert has to be triggered when receiving records that exceed the allowed limit. However, some TLS protocol implementations may not take care about record size limitations. In such situations you may want to enlarge the buffer to be able to finish the TLS session without sending a record_overflow alert. Alternatively you may use method setSendRecordOverflowAlert to tell iSaSiLk to automatically enlarge the buffer (and not break the handshake with a record_overflow alert) when the peer sends a record that exceeds the maximum fragment length.

Parameters:

size - the record overhead size to be used

setSendRecordOverflowAlert

public void setSendRecordOverflowAlert(boolean send)

Sets whether a record_overflow alert shall be sent if a record is received that exceeds the max record size.

The maximum plaintext fragment length used by the SSL/TLS protocol is 2^14 (16384) bytes. Usually a record_overflow alert has to be triggered when receiving records that exceed the allowed limit. However, some TLS protocol implementations may not take care about record size limitations. You may want to tell iSaSiLk to automatically enlarge the buffer (and not break the handshake with a record_overflow alert) when the peer sends a record that exceeds the maximum fragment length:

 context.setSendRecordOverflowAlert(false);
 

Parameters:

send - whether to send a record_overflow alert (default: true) if a record is received that exceeds the max record size or to automatically resize the internal buffer and do not send a record_overflow alert

setDoNotPackHandshakeMessages

public void setDoNotPackHandshakeMessages(boolean doNotPackMessages)

Sets whether not to pack handshake messages together where possible and send them within one SSL/TLS fragment. Packing may be useful when running SSL/TLS over TCP/IP on systems using a rather big delayed ACK (e.g. some versions of Windows).

Parameters:

doNotPackMessages - whether to pack handshake messages or not (default: false; messages are packed)

setDisableRenegotiation

public void setDisableRenegotiation(boolean disableRenegotation)

Sets whether to disable renegotiation at all. If renegotation is disbaled a no_renegotatioan warning or fatal handshake failure alert will be triggered if the peers tries to renegotiate a session.
However, note that disabling renegotiation only might provide a conditional protection against renegotiation attacks. Without using the RenegotiationInfo extension, your initial (attacked) handshake may look like a renegotiation handshake for the peer. Disabling renegotiation would only help you if you are aware about the renegotiation.

Parameters:

disableRenegotation - whether to disable renegotation or not (default: false; renegotiation is allowed)

getDisableRenegotiation

public boolean getDisableRenegotiation()

Gets whether renegotiation is disabled at all. If renegotation is disbaled a no_renegotatioan alert will be triggered if the peers tries to renegotiate a session.

Returns:

whether to renegotation is disabled or not (default: false; renegotiation is allowed)

See Also:

setDisableRenegotiation(boolean)

setAllowLegacyRenegotiation

public void setAllowLegacyRenegotiation(boolean allowLegacyRenegotation)

Sets whether to allow legacy renegotiation.
If this flag is set to true, renegotiation without using the RenegotiationInfo extension (RFC 5746) is allowed. Please note that your application may be vulnerable to renegotiation attacks if you allow legacy renegotiation without using the RenegotiationInfo extension to cryptographically bind the renegotiation handshake to the enclosing SSL/TLS connection (see RFC 5746).

Parameters:

allowLegacyRenegotation - whether to allow legacy renegotation or not (default: false; legacy renegotiation is not allowed)

getAllowLegacyRenegotiation

public boolean getAllowLegacyRenegotiation()

Gets whether to allow legacy renegotiation.
If the allow_legacy_renegotiation flag is set to true, renegotiation without using the RenegotiationInfo extension is allowed.

Returns:

true if legacy renegotation is allowed; false (default) if legacy renegotiation is not allowed

See Also:

setAllowLegacyRenegotiation(boolean)

setUseNoRenegotiationWarnings

public void setUseNoRenegotiationWarnings(boolean useNoRenegotiationWarnings)

Sets whether to use (send) no_renegotiation warnings as response to unsupported renegotiation requests.
A no_renegotiation warning alert may be sent in any of the following situations:

• A client may send a no_renegotiation warning if renegotiation has been disbaled at all, but a server sends a hello_request message to ask the client for initiating a renegotiation handshake.
• A client may send a no_renegotiation warning if legacy renegotiation is not allowed, but a server that only supports legacy renegotiation sends a hello_request message to ask the client for initiating a renegotiation handshake.
• A server may send a no_renegotiation warning if renegotiation has been disbaled at all, but a client sends a client_hello message to initiate a renegotiation handshake.
• A server may send a no_renegotiation warning if legacy renegotiation is not allowed, but a client that only supports legacy renegotiation sends a client_hello message to start a renegotiation handshake.

In any of these situations a no_renegotiation warning alert may be send to refuse the renegotiation request of the peer. Since no_renegotiation alerts are not defined for SSLv3, SSLv3 client/servers immediately abort the SSL session by sending a fatal handshake_failure alert. Since no_renegotiation alerts are not fatal, but only warning alerts, TLS clients/servers keep the TLS connection opened and only send the no_renegotiation warning to refuse the renegotation request of the peer. It is then up to the peer to decide whether to continue with the current session or to abort the TLS connection.
By default iSaSiLk does not send no_renegotiation warnings. If a client does not announce its ability to secure renegotiation within its initial ClientHello message (by including the TLS_EMPTY_RENEGOTIATION_INFO_SCSV cipher suite value or the RenegotiationInfo extension), an iSaSiLk server will immediately abort the handshake by sending a fatal handshake failure alert as recommended by RFC 5746.
If you want to use (send) a no_renegotiation warning in any of the situations described obove, configure your SSLContext to use no_renegotiation warnings (please note that in this case your server maybe vulnerable to attacks where only the client notices that a renegotiation takes place):

 sslContext.setUseNoRenegotiationWarnings(true);
 

Parameters:

useNoRenegotiationWarnings - whether to use (send) no_renegotiation warnings on unsupported TLS renegotiation requests (default: false; no_renegotiation warnings are not used)

getUseNoRenegotiationWarnings

public boolean getUseNoRenegotiationWarnings()

Gets whether to allow old renegotiation.
If the use_no_renegotiation_warning flag is set to true, TLS clients/servers send a no_renegotiation warning to refuse a not supported renegoation request.

Returns:

true if no_renegotiation warnings shall be used; false (default) if no_renegotiation warnings shall not be used

See Also:

setUseNoRenegotiationWarnings(boolean)

setAllowIdentityChangeDuringRenegotiation

public void setAllowIdentityChangeDuringRenegotiation(boolean allowIdentityChange)

Sets whether to allow that the peer identity may be changed during renegotiation.
When identity change is allowed an already authenticated peer may change its certificate, psk identity or ServerName extension during renegotiation. If peer identity change is not allowed, a renegotiation handshake will be aborted with a fatal handshake_failure alert if the peer tries to authenticate with a different certificate or psk identiy, or tries to use a different ServerName extension than used for the preceding session.

Parameters:

allowIdentityChange - whether to allow that the peer identity may be changed during renegotiation (default: false; peer identity change is not allowed)

getAllowIdentityChangeDuringRenegotiation

public boolean getAllowIdentityChangeDuringRenegotiation()

Gets whether to allow peer identity change during renegotiation.
If the allowIdentityChange flag is set to true, identity change is allowed during renegotiation.

Returns:

false (default) to not allow peer identity change during renegotiation true to allow peer identity change during renegotiation;

See Also:

setAllowIdentityChangeDuringRenegotiation(boolean)

setInputStreamAvailableMode

public void setInputStreamAvailableMode(java.lang.String availableMode)

Sets the SSLInputInputStream.available mode.

This method may be used to configure the SSLInputInputStream.available behaviour for the case when the data has not been already decrypted by a preceding read() call. The mode may be set to

• "onebyte" to indicate that 1 (byte) shall be returned
• "encrypted" to return the number of encrypted bytes (which maybe greater than the number of actually available bytes after decryption) (this is the default behaviour)
• "decrypted" to return the number of decrypted bytes. If this option is selected a read() call may be necessary within method available to read (and decrypt) the next SSL record. This may cause method available to block if not enough bytes are available from the underlying stream to read a full SSL record.

Parameters:

availableMode - "onebyte" to return 1 if the data has not been decrypted yet, "encrypted" to return the number of encrypted bytes, "decrypted" to read and decrypt the next message to return the number of decrypted data bytes

setChannelBindings

public void setChannelBindings(ChannelBindings channelBindings)

Sets any ChannelBindings the application may be interested in.

Parameters:

channelBindings - the ChannelBindings

Throws:

java.lang.IllegalArgumentException - if any of the given ChannelBindings does contain data

getChannelBindings

public ChannelBindings getChannelBindings()

Gets any ChannelBindings the application may be interested in.

Returns:

the ChannelBindings