iaik.security.ssl
Class SSLClientContext

java.lang.Object
  extended by iaik.security.ssl.SSLContext
      extended by iaik.security.ssl.SSLClientContext
All Implemented Interfaces:
java.lang.Cloneable
Direct Known Subclasses:
SSLServerContext

public class SSLClientContext
extends SSLContext
implements java.lang.Cloneable

This class extends the SSLContext to add client related information to an SSL/TLS policy.

Note that there is a separate document about the iSaSiLk authentication framework, see your installation directory.

A SSLClientContext is used on the client side to tell iSaSiLk the TLS security parameters like cipher suites, key, certificates to be used.
After having created an SSLClientContext, you may set cipher suites, client credentials (if needed for authenticating against the server), trusted certificates and any other parameters you may require for your client configuration, e.g.:

  // create client context
  SSLClientContext context = new SSLClientContext();
  
  // key and certificate for client authentication
  PrivateKey clientKey = ...;
  X509Certificate[] clientCertChain = ...;
  context.addClientCredentials(clientCertChain, clientKey);
  
  // add some trust anchor(s)
  X509Certificate trustAnchor = ...;
  context.addTrustedCertificate(trustAnchor);
  
  // enable all default cipher suites  
  CipherSuiteList suites = new CipherSuiteList(CipherSuiteList.L_DEFAULT);
  context.setEnabledCipherSuiteList(suites);
  context.updateCipherSuites();
  
  ...
 
If you want to use TLS extensions you can set them as ExtensionList, e.g. (for using the server_name extension):
 ServerNameList serverNameList = new ServerNameList();
 // add to ExtensionList
 ExtensionList extensions = new ExtensionList();
 extensions.addExtension(serverNameList);
 // set extensions for the SSLClientContext configuration:
 // (extensions are only defined for TLS)
 context.setAllowedProtocolVersions(SSLContext.VERSION_TLS10, SSLContext.VERSION_TLS12); 
 context.setExtensions(extensions);
 
Finally, when having finished your configuration, set your SSLClientContext for the SSLTransport implementation you are using. Most commonly you will use an SSLSocket to connect to the server, e.g.:
 // the name of the server
 String serverName = ...;
 // the port on which the server is listening  
 int serverPort = 443; 
 SSLSocket socket = new SSLSocket(serverName, serverPort, context); 
 // print debug info to System.out 
 socket.setDebugStream(System.out); 
 // 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 
 System.out.println("Reading response..."); 
 while (true) { 
   String line = reader.readLine(); 
   if (line == null) { 
     break; 
   } 
   System.out.print(":"); 
   System.out.println(line); 
 } 
    
 // close streams and socket 
 writer.close(); 
 reader.close(); 
 socket.close(); 
 
 

See Also:
SSLContext, SSLClientContext

Field Summary
 
Fields inherited from class iaik.security.ssl.SSLContext
AVAIL_MODE_DECRYPTED, AVAIL_MODE_ENCRYPTED, AVAIL_MODE_ONE_BYTE, CERTTYPE_DSS_FIXED_DH, CERTTYPE_DSS_SIGN, CERTTYPE_ECDSA_EC, CERTTYPE_ECDSA_FIXED_ECDH, CERTTYPE_ECDSA_SIGN, CERTTYPE_RSA_ENCRYPT, CERTTYPE_RSA_FIXED_DH, CERTTYPE_RSA_FIXED_ECDH, CERTTYPE_RSA_SIGN, CERTTYPE_UNKNOWN, LIBRARY_VERSION, LIBRARY_VERSION_STRING, SEND_EMPTY_FRAGMENT, VERSION_NOT_CONNECTED, VERSION_SSL20, VERSION_SSL30, VERSION_TLS10, VERSION_TLS11, VERSION_TLS12
 
Constructor Summary
SSLClientContext()
          Create a default SSLContext.
SSLClientContext(CipherSuiteList cipherSuiteList)
          Create a SSLContext with the given cipher suite list.
SSLClientContext(java.security.SecureRandom random)
          Create a default SSLContext with a specific random number generator.
SSLClientContext(java.security.SecureRandom random, CipherSuiteList cipherSuiteList)
          Create a SSLContext with a specific random number generator and given cipher suite list.
SSLClientContext(SSLClientContext other)
          Create a SSLClientContext cloning another context.
 
Method Summary
 void addClientCredentials(KeyAndCert keyAndCert)
          Add some client credentials.
 int addClientCredentials(java.security.KeyStore keyStore, char[] password)
          Add some client credentials from a KeyStore.
 int addClientCredentials(java.security.KeyStore keyStore, char[] password, java.lang.String[] aliases)
          Add some client credentials from a KeyStore.
 int addClientCredentials(java.lang.String keyStoreFile, char[] keyStorePassword, java.lang.String keyStoreType, java.lang.String keyStoreProvider)
          Add some client credentials from a KeyStore.
 void addClientCredentials(java.security.cert.X509Certificate[] chain, java.security.PrivateKey key)
          Add some client credentials.
 void clearClientCredentials()
          Clear the database of client credentials.
 java.lang.Object clone()
          Implements the Cloneable interface.
protected  KeyAndCert[] getClientCredentials(java.security.Principal[] issuers, byte[] certificateTypes)
          Deprecated. use getClientCredentials(issuers, certificateTypes, null) instead
protected  KeyAndCert[] getClientCredentials(java.security.Principal[] issuers, byte[] certificateTypes, java.security.PublicKey publicKey)
          Gets all matching client credentials.
 boolean getIgnorePSKIdentityHint()
          Gets whether a PSK identity hint sent by the server shall be ignored by the client or not.
 void setCheckExportRestrictions(boolean check)
          Set the export restriction check.
 void setIgnorePSKIdentityHint(boolean ignore)
          Sets whether a PSK identity hint sent by the server shall be ignored by the client or not.
 void setUseMaxVersionForRSAPremasterSecret(boolean useMaxVersion)
          Decides whether to include the max client version into the RSA premaster secret.
 java.lang.String toString()
          Returns a string representation of this SSLClientContext.
 
Methods inherited from class iaik.security.ssl.SSLContext
addPSKCredential, addTrustedCertificate, addTrustedCertificates, addTrustedCertificates, addTrustedCertificates, clearPSKCredentials, convertCertificateChain, getAllowedProtocolVersionNames, getAllowedProtocolVersions, getAllowIdentityChangeDuringRenegotiation, getAllowLegacyRenegotiation, getAllSupportedProtocolVersionNames, getAllSupportedProtocolVersions, getCacheTerminatedSessions, getChainVerifier, getDebugStream, getDisableRenegotiation, getDoNotSendServerCloseNotify, getEnabledCipherSuiteList, getEnabledCipherSuites, getEnabledCompressionMethods, getPSKCredential, getPSKManager, getRandomGenerator, getSendEmptyFragment, getSessionManager, getTrustDecider, getUseNoRenegotiationWarnings, setAllowedProtocolVersions, setAllowedProtocolVersions, setAllowIdentityChangeDuringRenegotiation, setAllowLegacyRenegotiation, setCacheTerminatedSessions, setChainVerifier, setDebugStream, setDebugStream, setDisableRenegotiation, setDoNotPackHandshakeMessages, setDoNotSendServerCloseNotify, setEnabledCipherSuiteList, setEnabledCipherSuites, setEnabledCompressionMethods, setExtensions, setInputStreamAvailableMode, setPSKCredential, setPSKManager, setRandomGenerator, setRecordOverheadSize, setSendEmptyFragment, setSendRecordOverflowAlert, setSessionManager, setTrustDecider, setUseNoRenegotiationWarnings, setUseRecordSplitting, updateCipherSuites
 
Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

SSLClientContext

public SSLClientContext()
Create a default SSLContext.


SSLClientContext

public SSLClientContext(java.security.SecureRandom random)
Create a default SSLContext with a specific random number generator.

Parameters:
random - the random number generator to be used or null for the default SecureRandom

SSLClientContext

public SSLClientContext(CipherSuiteList cipherSuiteList)
Create a SSLContext with the given cipher suite list.

Parameters:
cipherSuiteList - the cipher suite list to be used or null for the default cipher suite list

SSLClientContext

public SSLClientContext(java.security.SecureRandom random,
                        CipherSuiteList cipherSuiteList)
Create a SSLContext with a specific random number generator and given cipher suite list.

Parameters:
random - the random number generator to be used or null for the default SecureRandom
cipherSuiteList - the cipher suite list to be used or null for the default cipher suite list

SSLClientContext

public SSLClientContext(SSLClientContext other)
Create a SSLClientContext cloning another context.

Method Detail

clone

public java.lang.Object clone()
Implements the Cloneable interface.

Overrides:
clone in class SSLContext
Returns:
a clone of this SSLClientContext

setCheckExportRestrictions

public void setCheckExportRestrictions(boolean check)
Set the export restriction check. If activated the handshake will check that no keys longer than the keysize limit for exportable ciphersuites are used for key exchange. Disabled by default.


addClientCredentials

public void addClientCredentials(java.security.cert.X509Certificate[] chain,
                                 java.security.PrivateKey key)
Add some client credentials. The certificate chain must contain the client certificate at index 0. The credentials are added to a database and automatically retrieved via getClientCredentials() if requested by the server.


addClientCredentials

public void addClientCredentials(KeyAndCert keyAndCert)
                          throws java.lang.IllegalArgumentException
Add some client credentials. The credentials are added to a database and automatically retrieved via getClientCredentials() if requested by the server.

Throws:
java.lang.IllegalArgumentException

addClientCredentials

public int addClientCredentials(java.lang.String keyStoreFile,
                                char[] keyStorePassword,
                                java.lang.String keyStoreType,
                                java.lang.String keyStoreProvider)
                         throws java.security.KeyStoreException
Add some client credentials from a KeyStore.

Note that this method does not allow the same fine granularity as when adding some particular key and certificate. Any key entry (and its corresponding certificate) chain) contained in the KeyStore is added to the key/cert database.
If the KeyStore contains SecretKeys, they are added as PSKCredentials.

All key entries must have the same password.

Parameters:
keyStoreFile - the name of the KeyStore file
keyStorePassword - the KeyStore password
keyStoreType - the KeyStore type; default: IAIKKeyStore
keyStoreProvider - the KeyStore provider; default: IAIK
Returns:
the number of credentials added from the KeyStore
Throws:
java.security.KeyStoreException - if an error occurs while getting keys/certificates from the KeyStore

addClientCredentials

public int addClientCredentials(java.security.KeyStore keyStore,
                                char[] password)
                         throws java.security.KeyStoreException
Add some client credentials from a KeyStore.

Note that this method does not allow the same fine granularity as when adding some particular key and certificate. Any key entry (and its corresponding certificate) chain) contained in the KeyStore is added to the key/cert database.
If the KeyStore contains SecretKeys, they are added as PSKCredentials.

The KeyStore must have been already loaded when calling this method. All key entries must have the same password.

Parameters:
keyStore - the KeyStore from which to read the client credentials
password - the password for the private/secret key entries
Returns:
the number of credentials added from the KeyStore
Throws:
java.security.KeyStoreException - if an error occurs while getting keys/certificates from the KeyStore

addClientCredentials

public int addClientCredentials(java.security.KeyStore keyStore,
                                char[] password,
                                java.lang.String[] aliases)
                         throws java.security.KeyStoreException
Add some client credentials from a KeyStore.

This method is similar to method addClientCredentials(KeyStore, char[]) except that are only those key entries are added that are specified by their aliases. If no aliases are specified, all key entries are added (in this case this method does the same as method addClientCredentials(KeyStore, char[])).
If any of the referenced key entries represents a SecretKeys, it is added as PSKCredential.

The KeyStore must have been already loaded when calling this method. All key entries must have the same password.

Parameters:
keyStore - the KeyStore from which to read the client credentials
password - the password for the private/secret key entries
aliases - the alias names of the key entries to be added
Returns:
the number of credentials added from the KeyStore
Throws:
java.security.KeyStoreException - if an error occurs while getting keys/certificates from the KeyStore, or no key entry is available for any of the specified alias names

clearClientCredentials

public void clearClientCredentials()
Clear the database of client credentials.


setUseMaxVersionForRSAPremasterSecret

public void setUseMaxVersionForRSAPremasterSecret(boolean useMaxVersion)
Decides whether to include the max client version into the RSA premaster secret.

SSL/TLS requires that the max version (sent within the ClientHello message) is included in the RSA premaster secret, however, many implementations send the negotiated version. By default iSaSiLk uses the max client version as required by SSL/TLS; you can call this method if you want to use the negotiated version:

 ...
 sslClientContext.setUseMaxVersionForRSAPremasterSecret(false);
 

Parameters:
useMaxVersion - whether to include the max ClientHello version into the RSA premaster secret

getIgnorePSKIdentityHint

public boolean getIgnorePSKIdentityHint()
Gets whether a PSK identity hint sent by the server shall be ignored by the client or not. This method is only meaningful if PSK (pre-shared key) based cipher suites are used. In this case the server may sent a PSK identity hint to help the client in selecting the pre-shared key to be used. However, the TLS-PSK specification recommends that an identity hint should not be sent by the server and that it must be ignored by the client (except for a special profile makes some other recommendation).

Returns:
whether to ignore a psk identity hint sent by the server (default: true)

setIgnorePSKIdentityHint

public void setIgnorePSKIdentityHint(boolean ignore)
Sets whether a PSK identity hint sent by the server shall be ignored by the client or not. This method is only meaningful if PSK (pre-shared key) based cipher suites are used. In this case the server may sent a PSK identity hint to help the client in selecting the pre-shared key to be used. However, the TLS-PSK specification recommends that an identity hint should not be sent by the server and that it must be ignored by the client (except for a special profile makes some other recommendation).

Parameters:
ignore - whether to ignore a psk identity hint sent by the server

getClientCredentials

protected KeyAndCert[] getClientCredentials(java.security.Principal[] issuers,
                                            byte[] certificateTypes,
                                            java.security.PublicKey publicKey)
Gets all matching client credentials. This method is called during the handshake if a server has requested client authentication. The default implementation will search through the database of available client credentials and return all that match the server request. If the server does not specify particular CAs he trusts all credentials of correct type are returned. Note that credentials that cannot be used because the necessary algorithms are not implemented by the current SecurityProvider are ignored (e.g. DSA credentials if no implementation for RawDSA is available).

The publicKey parameter, if not null, is the server's public key for the key exchange. For client authentication with a Diffie-Hellman certificate the parameters from that public key must match the client parameters for the key exchange to work. This method verifies this as well.

This method returns all appropriate credentials or the empty array if no are available. An application may override this method to display a dialog window etc. to the user to allow him select the credentials to use if multiple are available. The library will always use the credentials at index 0 in the returned array. An overridden method may look like this:

 protected KeyAndCert[] getClientCredentials(Principal[] issuers, byte[] certificateTypes, PublicKey publicKey) {
   KeyAndCert[] certs = super.getClientCredentials(issuers, certificateType, publicKey);
   // allow user to select a certificate or cancel
   if( selected == -1 ) {
     return new KeyAndCert[0];
   } else {
     return new KeyAndCert[] { certs[selected] };
   }
 }
 

Parameters:
issuers - a list of CA names trusted by the server
certificateTypes - the certificate types accepted by the server
publicKey - the public key of the server

getClientCredentials

protected KeyAndCert[] getClientCredentials(java.security.Principal[] issuers,
                                            byte[] certificateTypes)
Deprecated. use getClientCredentials(issuers, certificateTypes, null) instead


toString

public java.lang.String toString()
Returns a string representation of this SSLClientContext.

Overrides:
toString in class SSLContext
Returns:
a string representation

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