iaik.security.ssl

Class SSLClientContext

java.lang.Object

iaik.security.ssl.SSLContext

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:
 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, VERSION_TLS13

Constructor Summary

Constructors

Constructor and Description
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

Modifier and Type	Method and Description
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	setReadPostHandshakeMessageAfterFinsished(boolean readMessage) TLS 1.3: Whether to try to immediately read a post handshake message after having sent the Finished message.
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, getChannelBindings, getDebugStream, getDisableRenegotiation, getDoNotSendServerCloseNotify, getEnabledCipherSuiteList, getEnabledCipherSuites, getEnabledCompressionMethods, getPSKCredential, getPSKManager, getRandomGenerator, getSendEmptyFragment, getSessionManager, getTrustDecider, getUseNoRenegotiationWarnings, setAllowedProtocolVersions, setAllowedProtocolVersions, setAllowIdentityChangeDuringRenegotiation, setAllowLegacyRenegotiation, setCacheTerminatedSessions, setChainVerifier, setChannelBindings, setCheckTypeOfNextHandshakeMessage, setDebugStream, setDebugStream, setDisableRenegotiation, setDoNotPackHandshakeMessages, setDoNotSendServerCloseNotify, setDowngradeMaxVersionToTLS12IfNoTLS13CipherSuitesAvailable, setEnabledCipherSuiteList, setEnabledCipherSuites, setEnabledCompressionMethods, setExtensions, setInputStreamAvailableMode, setPSKCredential, setPSKManager, setRandomGenerator, setRecordOverheadSize, setSendEmptyFragment, setSendRecordOverflowAlert, setSessionManager, setTls13MiddleboxCompatibilityMode, setTLS13WaitOnPeerCloseNotify, 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

setReadPostHandshakeMessageAfterFinsished

public void setReadPostHandshakeMessageAfterFinsished(boolean readMessage)

TLS 1.3: Whether to try to immediately read a post handshake message after having sent the Finished message. In TLS 1.3 after having received the Finished message from the server the client -- if requested to do so -- sends its authentication (Certificate, CertificateVerify) and Finished messages. If the server does not accept the client Certificate message (because it is empty or the server does not trust the client certificate) the server will send a bad_certificate alert and close the connection. The client, however, may not read the alert message before it has sent its application request to the server and starts reading the application response from the server. If the server immediately closes the connection after having sent the alert message the socket may be closed already before the client sends its application request. In this case the client will never see the bad_certificate alert because it already gets a socket write error indicating that the connection is closed.

Usually -- if session resumption is enabled -- a TLS 1.3 server may send a NewSessionTicket post handshake message before exchanging application data. When setting read_post_handshake_message_after_finsish to true the client will try to read a post handshake message immediately after having sent its Finished message and before sending application data. Usually this should work without any problems, however, when the server does not send a NewSessionTicket message before exchanging application data, the client may block for the time of the configured read time out before continuing with sending its application data request. For that reason by default an iSaSiLk client does not try to read a post handshake message immediately after having sent the Finished message (and before sending its application request). However, it might be useful to enable this feature for debugging purposes (to, for instance, check if the server has denied the client certificate when having got a socket write error before being able to exchange any application data.

Parameters:

readMessage - whether to try to read a post handshake message after having sent the Finished message (default: false) (only meaningful for TLS 1.3)

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