iaik.security.ssl
Class SSLContext

java.lang.Object
  extended by 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):

See Also:
SSLClientContext, SSLServerContext, CipherSuite, CipherSuiteList, CompressionMethod, SessionManager, DefaultSessionManager, ChainVerifier

Field Summary
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
          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.
static int VERSION_TLS11
          Version number constant for TLS 1.1.
static int VERSION_TLS12
          Version number constant for TLS 1.2.
 
Method Summary
 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.
 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 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.
 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.
 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 5.104

See Also:
Constant Field Values

LIBRARY_VERSION_STRING

public static final java.lang.String LIBRARY_VERSION_STRING
iSaSiLk library version as a String. Currently "5.104"

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

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
Version number constant for SSL 2.0.

See Also:
Constant Field Values

VERSION_SSL30

public static final int VERSION_SSL30
Version number constant for SSL 3.0.

See Also:
Constant Field Values

VERSION_TLS10

public static final int VERSION_TLS10
Version number constant for TLS 1.0.

See Also:
Constant Field Values

VERSION_TLS11

public static final int VERSION_TLS11
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

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() 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

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):

    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, 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)
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);.


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
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

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

This Javadoc may contain text parts from text parts from IETF Internet Standard specifications (see copyright note).

iSaSiLk 5.104, (c) 2002 IAIK, (c) 2003 - 2015 SIC