iSaSiLk

iSaSiLk 6.0

The Secure Sockets Layer (SSL) protocol has been developed by Netscape Communications Corporation for providing a secure data transfer over the Internet in supporting peer authentication, data encryption and data integrity. The version 3 of the Secure Sockets Layer protocol and its IETF standardized successor TLS (Transport Layer Security) are the most important protocols for encrypted data transfer over the WWW, supported by all well-known browsers, such as Microsoft Internet Explorer, Mozilla Firefox, Google Chrome, and Opera.

Main Features

IAIK-iSaSiLk is a Java™ programming language implementation of the SSLv2 (client-side), SSLv3, TLS 1.0 ,TLS 1.1, TLS 1.2 and TLS 1.3 protocols. It supports all defined cipher suites (except for Fortezza), including all AES, GCM and PSK cipher suites. iSaSiLk implements the standard TLS extensions, comes with an easy to use API and operates on top of the IAIK-JCE Java™ Cryptography Extension. iSaSiLk is highly configurable and will work with any alternative JCE implementation supported by a proper provider for supplying the required cryptographic algorithms.

Please download the new iSaSiLk version and carefully read the included information about secure renegotiation support.

Pricing and Licensing

For current prices of iSaSiLk, please see our price list and license conditions. iSaSiLk is free for educational and research purposes, please see our educational/research license conditions.

See Prices

Webshop

You can order the product directly from our webshop. Please download the new iSaSiLk version and carefully read the included information about secure renegotiation support.

See Webshop

  • Implemented entirely in the Java™ language guaranteeing cross platform portability
  • Works on JDK versions 1.2, 1.3, 1.4, 1.5, 1.6, 1.7, 1.8, 1.9. 1.10, 1.11, 1.12 and compatible   (JDK 1.5, 1.6, 1.7, 1.8, 1.9, 1.10. 1.11, 1.12 are also called JDK 5, 6, 7, 8, 9, 10, 11, 12 respectively)
  • Mature product with a proven over fifteen year track record in the real world applications
  • Centralized security policy configuration
  • Uses Socket API to allow easy upgrading of existing network
  • Support for the HTTPS protocol via the standard JDK URL framework
  • Secures Java™ RMI calls
  • Supports client side SOCKS and HTTPS proxies
  • Multithreading safe
  • Special versions for Applets and Java™ WebStart

Protocol Standards Compliance

  • Client and server implementation of SSL 3.0, TLS 1.0, TLS 1.1, TLS 1.2 and TLS 1.3; client
    implementation of SSL 2.0
  • Ensures the most secure configured protocol version and encryption methods shared
    by client and server are used
  • Supports all standard defined cryptographic algorithms including ECC, RSA,
    DSA, Diffie-Hellman, AES, Triple DES, DES, IDEA, RC2, RC4, MD5, and SHA
  • Supports AES Galois Counter Mode (GCM) Cipher Suites for TLS according to RFC 5288
  • Supports Elliptic Curve cipher suites according to RFC 4492 (Named Curves)
  • Supports all TLS defined NIST (RFC 4492) and Brainpool (RFC 7027) curves
  • Supports x25519 and x448 ECDHE key exchange, and Ed25519 and Ed448 EdDSA signatures (RFC 8422; experimental)
  • Supports RSA-PSS signature algorithms (rsa_pss_rsae_sha256, rsa_pss_rsae_sha384, rsa_pss_rsae_sha512, rsa_pss_pss_sha256, rsa_pss_pss_sha384, rsa_pss_pss_sha512)
  • Supports ECC Cipher Suites with SHA-256/384 and AES Galois Counter Mode (GCM) according to RFC 5289
  • Supports Camellia cipher suites according to RFC 4132
  • Supports Camellia Cipher Suites with SHA-256/384 and AES Galois Counter Mode (GCM), including PSK suites, according to RFC 5932/6367
  • Public key server authentication, optional client authentication
    (ECC, RSA, DSA, and Diffie-Hellman) or fully anonymous connections
  • Supports all standard TLS extensions defined by RFC 4366
  • Supports Session Resumption without Server-Side State
    (SessionTicket extension according to RFC 4507, RFC 5077)
  • Supports the
    extended_master_secret extension as specified in RFC 7627 to calculate the master secret in a way that cryptographically binds it to important session parameters
  • Supports all Pre-Shared key (PSK) cipher suites defined by RFC 4279, RFC 4785
  • Supports Pre-Shared Key Cipher Suites with SHA-256/384 and AES Galois Counter Mode according to RFC 5487
  • Supports Pre-Shared Key ECDHE_PSK Cipher Suites according to RFC 5489
  • Session caching for high performance connection establishment
  • Security parameter renegotiation on demand

Application Extensible Design

  • Can perform SSL/TLS over any pair of streams and over
    an existing socket
  • Pluggable custom certification path verification
  • Pluggable custom session management
  • Allows private application defined encryption methods
  • Allows private application defined compression functions

Proven Interoperability

  • Interoperates with any SSL 2.0, SSL 3.0, TLS 1.0, TLS 1.1, TLS 1.2 and TLS 1.3 implementation
  • Interoperability tested among others with clients
    Mozilla, Firefox, SeaMonkey, Microsoft Internet Explorer, Opera, Google Chrome.
  • Interoperability tested with servers from Microsoft, Oracle, IBM, Apache (SSLeay, OpenSSL) and others.

Cryptographic Provider Independence

  • Can be used with any JCA/JCE compliant cryptography provider
  • Can use several different cryptography providers at the same time
  • Provisions for the integration of Smartcards and other secure
    hardware devices
  • Comes with the IAIK JCE provider by default (included in license)

With version TLS 1.3 (RFC 8446) the TLS protocol has been significantly redesigned. iSaSiLk 6.0 supports all core and some optional
features of the TLS 1.3 protocol, however some optional features like Zero Round-Trip 0-RRT Early Data are yet not supported.

This document explains how to use and configure iSaSiLk for TLS 1.3. If you are using the default settings of iSaSiLk you should not have to do anything. TLS 1.3 is enabled by default and can be used without special configurations settings. However, you should be aware about you are using TLS 1.3 and might want to configure it according to your requirements.

Version Interval

The new default version interval is form TLS 1.0 to TLS 1.3.

Cipher Suites

TLS 1.3 cipher suites do not follow the TLS_<KeyExchangeAlgorithm>_WITH_<SymmetricEncryptionAlgorithm>_<HashAlgorithm> scheme anymore. They specify the symmetric AEAD and the hash algorithm to be used; authentication and key exchange mechanisms are negotiated by extensions.

iSaSiLk supports all cipher suites specified by the TLS 1.3 specification but uses a separate class (TLS13CipherSuite) to implement them:

  • TLS_AES_256_GCM_SHA384
  • TLS_CHACHA20_POLY1305_SHA256
  • TLS_AES_128_GCM_SHA256
  • TLS_AES_128_CCM_SHA256
  • TLS_AES_128_CCM_8_SHA256

If TLS 1.3 is used the first four suites listed above are enabled by the default (depending on their cryptographic availability), only suite TLS_AES_128_CCM_8_SHA256 does not belong to the default cipher suite set (but to the set of implemented cipher suites).

Additionally the following pre-TLS 1.3 cipher suites are also enabled by default (if supported by the underlying cryptographic capabilities):

  • TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
  • TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
  • TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384
  • TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384
  • TLS_DHE_RSA_WITH_AES_256_GCM_SHA384
  • TLS_RSA_WITH_AES_256_GCM_SHA384
  • TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256
  • TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
  • TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256
  • TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256
  • TLS_DHE_RSA_WITH_AES_128_GCM_SHA256
  • TLS_DHE_RSA_WITH_AES_256_CBC_SHA256
  • TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA
  • TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA
  • TLS_RSA_WITH_AES_256_CBC_SHA256
  • TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA
  • TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA
  • TLS_RSA_WITH_AES_128_GCM_SHA256
  • TLS_RSA_WITH_AES_128_CBC_SHA256
  • TLS_RSA_WITH_AES_256_CBC_SHA
  • TLS_RSA_WITH_AES_128_CBC_SHA

Static RSA and CBC suites are enabled for backwards compatibility reasons.

If using the default version interval and the default cipher suite set — and the peer does support TLS 1.3 — a TLS 1.3 cipher suite will be selected for the handshake.
However, if you have enabled the default version interval and having explicitly set only some pre-TLS1.3 cipher suite(s) it is likely that you will run into a NullPointerException when SSLContext.updateCipherSuites() is called indicating that TLS 1.3 cipher suites are required for offering the TLS 1.3 protocol version. This because the new default maximum version SSLContext.VERSION_TLS13 needs at least one
enabled TLS 1.3 cipher suite. To get rid of this  exception class SSLContext
offers a static method telling iSaSiLk to automatically downgrade to TLS 1.2 if TLS 1.3 is enabled but no TLS 1.3 cipher suites are set:

  SSLContext.setDowngradeMaxVersionToTLS12IfNoTLS13CipherSuitesAvailable(true);

However, more appropriate you should update your configuration by either adding some TLS 1.3 cipher suite(s) or explicitly setting the maximum allowed protocol version to SSLContext.VERSION_TLS12.

Extensions

Extensions are a fundamental building block of the TLS 1.3 protocol. Both, authentication
and key exchange are managed by extensions. Since TLS 1.3 would not work without extensions
iSaSiLk automatically creates and sets any missing extension that has not been enabled
by the application.

The following extensions are set by default:

  • SupportedGroups: secp256r1, secp384r1, secp5213r, X25519 (if the IAIK ECCelerateTM SecurityProvider is installed)
    and ffdhe_2048 and ffdhe_3072
  • KeyShare: key share entries according to the supported groups
  • SignatureAlgorithms: ecdsa_secp256r1_sha256, ed25519, rsa_pss_rsae_sha256, rsa_pkcs1_sha256,
    ecdsa_secp384r1_sha384, rsa_pss_rsae_sha384, rsa_pkcs1_sha384,
    ecdsa_secp521r1_sha512, rsa_pss_rsae_sha512, rsa_pkcs1_sha512,
    ecdsa_sha1, rsa_pkcs1_sha1
    (ecdsa_ algorithms and ed25159 are only available if the IAIK ECCelerateTM
    SecurityProvider is installed)
  • ServerNameList

On the client side additionally the PskKeyExchangeModes extension (with mode psk_dhe_ke) is included in
the extension list to be offered to the server.

Special attention has been taken to the SignatureAlgorithms extension since the meaning of the ecdsa
signature algorithms has been changed with TLS 1.3. Prior to TLS 1.3 the curve name has not been
part of the ecdsa signature algorithms. Thus ecdsa could have been used with any curve (suggested by
the SupportedEllipticCurves/SupportedGroups extension), regardless of which of the hash algorithms
sha1, sha256, sha384 or sha512 has been used. With TLS 1.3 only the legacy ecdsa_sha1 algorithm
may be used with any curve, whereas ecdsa_secp256r1_sha256, ecdsa_secp384r1_sha384 and
ecdsa_secp521r1_sha512 are bound to the NIST curves secp256r1, secp384r1 and secp521r1,
respectively; the curves/groups of the SupportedGroups extension only apply to the curve/group
used for the key exchange.

In addition to the SignatureAlgorithms extension TLS 1.3 has introduced the SignatureAlgorithmsCert
extension which applies to certificate signatures rather than to (CertificateVerify) signatures
generated during the TLS handshake. If no SignatureAlgorithmsCert extension is sent the algorithms
specified within the SignatureAlgorithms extension shall be used to check the certificate signature
algorithms, too.
Since certificates typically maybe signed by using different signature algorithm(s) than used
for signatures generated during the handshake, the SignatureAlgorithms extension may have to
cover algorithms for both types of signatures; or an SignatureAlgorithmsCert extension may be
explicitly used.

For interoperability reasons iSaSiLk by default does not check if signatures that have
been used to sign certificates comply with the SignatureAlgorithmsCert (or SignatureAlgorithms)
extension. However, it checks if the (CertificateVerify) algorithms used during the handshake comply
with the SignatureAlgorithms extension. To change this behavior you may declare
your SignatureAlgorithmsCert extension as being a critical extension and/or your
SignatureAlgorithms extension as being a not critical extension; or change the
default critical value of these extension types by calling:

  ExtensionList.setDefaultCriticalValue(SignatureAlgorithmsCert.TYPE, true);

Of course, you do not need to stay with the default extensions used by iSaSiLk. You may
configure and use (some of) the extensions according to your requirements. A sample
extension configuration may look like (see the TLS13Server and TLS13Client samples):

  // the extension list
  ExtensionList extensions = new ExtensionList();
    
  // server_name
  ServerNameList serverNames = new ServerNameList();
  extensions.addExtension(serverNames);
   
  // supported_groups; enable some specific groups only
  NamedGroup[] namedGroups = { 
    SupportedGroups.NC_PRIME_SECP256R1,
    SupportedGroups.NC_X25519,
    SupportedGroups.FFDHE_2048
  };
  SupportedGroups supportedGroups = new SupportedGroups(namedGroups, true);
  extensions.addExtension(supportedGroups);

  // key_share; created from supported_groups
  KeyShare keyShare = KeyShare.createKeyShare(supportedGroups);
  extensions.addExtension(keyShare);
    
  // psk_key_exchange_modes
  PskKeyExchangeModes pskModes = new PskKeyExchangeModes(PskKeyExchangeModes.PSK_DHE_KE);
  extensions.addExtension(pskModes);
    
  // signature_algorithms
  SignatureScheme[] algorithms = {
     SignatureScheme.ecdsa_secp256r1_sha256,
     SignatureScheme.ed25519,
     SignatureScheme.rsa_pss_rsae_sha256,
     SignatureScheme.rsa_pkcs1_sha256,
   };
   SignatureAlgorithms signatureAlgorithms = 
      new SignatureAlgorithms(new SignatureSchemeList(algorithms));
   signatureAlgorithms.setCritical(true);   
   extensions.addExtension(signatureAlgorithms);
    
   // signature_algorithms_cert
   algorithms = {
     SignatureScheme.ecdsa_secp256r1_sha256,
     SignatureScheme.ed25519,
     SignatureScheme.rsa_pss_rsae_sha256,
     SignatureScheme.rsa_pkcs1_sha256,
   };
   SignatureAlgorithms signatureAlgorithmsCert = 
      new SignatureAlgorithmsCert(new SignatureSchemeList(algorithms));
   signatureAlgorithmsCert.setCritical(true);   
   extensions.addExtension(signatureAlgorithmsCert); 

When setting the extension list for the SSLContext in use take care to set it
before updating the cipher suites, but behind setting the protocol
version interval:

  // set the iSaSiLk SecurityProvider
  SecurityProvider.setSecurityProvider(new ECCelerateProvider());

  // create the SSLContext
  SSLContext context = ...;
  
  // add (client or server) credentials
  ...
  
  // set the protocol version interval
  context.setAllowedProtocolVersions(SSLContext.VERSION_TLS12, SSLContext.VERSION_TLS13);
  
  // set the cipher suites
  context.setEnabledCipherSuiteList(new CipherSuiteList(CipherSuiteList.L_DEFAULT));

  // set the extensions
  context.setExtensions(extensions);
  
  // update cipher suites
  context.updateCipherSuites();

Session Management

To maintain backwards compatibility the session management remains unchanged. However, for TLS 1.3 a psk identity of the pre_shared_key extension is used as session id for identifying a pre shared key of the initial session to be used for resuming the session.

Post Handshaking

At any time after the regular handshake TLS 1.3 allows to send/exchange post handshake
messages to update/change cryptographic parameters. There are three types of post handshake
types defined:

  • new_session_ticket allows a server to send a new session ticket to the client
  • post_handshake_auth allows a server to request post client authentication
  • key_update to perform a key update

Sending a new session ticket or requesting post client authentication may be only triggered on the server side, a key update may be done on both, client or server side.

In practice post handshaking may be used very carefully and may depend on the post handshake capabilities of the peer. For instance, it does not make sense to request post handshake authentication from a client that has not
sent a PostHandshakeAuth extension indicating that it is able to do post handshake authentication. Furthermore successful post handshaking may depend on the way the peer does handle it. For instance, a client may send its post handshake authentication messages immediately after having received the post
handshake authentication request from the server or may send some amount of application data before sending the post handshake authentication messages. iSaSiLk provides several configuration options that may be tried to handle post handshaking in a way most suitable for the intended peer. See the iSaSiLk Javadoc for more information.

We describe here how an iSaSiLk SSLv3/TLS client can use client authentication via an RSA smartcard or a similar device. Note that similar methods could be used to employ server side RSA, or (EC)DH and DSS via a smartcard but there is currently no document describing this step by step. However, note that there is another document  describing the iSaSiLk provider architecture in more detail.

The Steps in Detail

  1. Get yourself a smartcard that
    1. handles RSA signature creation operations.
    2. can create signatures in PKCS#1 version 1.5 format, padding blocktype 1 (padding with 0xff). If your device cannot do that it has to be able to do raw (unpadded) RSA operations and you have to do the padding yourself. See the PKCS#1 specification for details.
    3. Accepts the finished hash to sign and does NOT do the hashing itself.
  2. Get yourself a JCE compliant API to access the card. This means that the provider has to implement a subclass of  javax.crypto.CipherSpi (this is the standard way to do raw RSA operations as defined by the JCE™ API). For iSaSiLk client authentication there will only be one operation be performed on the cipher after getCipher():
    signature = rsa.doFinal(hash);
    The doFinal() call must return the PKCS#1 formatted signature.
  3. Write and activate your own SecurityProvider. To avoid limitations of the JCE provider model iSaSiLk does not directly use getInstance() calls. Instead it uses subclasses of iaik.security.ssl.SecurityProvider. You have to write your own SecurityProvider. If you only want to use your own implementation of RSA and not change anything about the other algorithms the easiest way to do this is to is to subclass iaik.security.ssl.IaikProvider and to override the getCipher() method.
    For example:

    protected Cipher getCipher(String algorithm, int mode, Key key, AlgorithmParameterSpec spec, SecureRandom random) throws Exception {
      if( algorithm.equals(ALG_CIPHER_RSA_SIGN) == false ) {
        return super.getCipher(algorithm, mode, key, spec, random);
       }
       Cipher rsaCipher = Cipher.getInstance("RSA/ECB/PKCS1Padding", myHardwareProvider);
       if( mode == CIPHER_ENCRYPT ) {
         rsaCipher.init(Cipher.ENCRYPT_MODE, key, spec, random);
       }
       return rsaCipher;
    }

    For more information about the iSaSiLk SecurityProvider model see the security provider site.

  4. Write your application. It is a standard iSaSiLk application, you only have to take care of two things. One, set your own SecurityProvider as the active cryptographic provider. Do this using, for example:
    SecurityProvider.setSecurityProvider(new mySecurityProvider());

    Two, add the respective credentials via clientContext.addClientCredentials(). The credentials consist of your certificate chain and a PrivateKey object.
    This of course cannot and will not be the actual private key as that is contained in the smartcard. Instead it can be an instance of an existing class containing dummy values or it can be your own subclass of PrivateKey containing information meaning e.g. use the second key on the first smartcard. For example, you might subclass the IaikProvider implementation to use the IAIK
    PCKS#11 provider for doing RSA
    based cipher operations only:

    package demo;
    public class MySecurityProvider extends IaikProvider {
      protected Cipher getCipher(String algorithm, int mode, Key key, AlgorithmParameterSpec param, SecureRandom random) throws Exception {
        if (key instanceof IAIKPKCS11Key) {
          if (algorithm.startsWith(ALG_CIPHER_RSA)) {
            algorithm = ALG_CIPHER_RSA;
          }
          cipherEngine = Cipher.getInstance(algorithm, ((IAIKPKCS11Key) key).getTokenManager().getProvider().getName());
          if (mode != CIPHER_NONE) {
            int cmode = (mode == CIPHER_ENCRYPT) ? Cipher.ENCRYPT_MODE : Cipher.DECRYPT_MODE;
            cipherEngine.init(cmode, key, param, random);
          }
        } else {
          cipherEngine = super.getCipher(algorithm, mode, key, param, random);
        }
      }
    }
  5. In this example above the key is an IAIKPKCS11Key instance that associates the Java™ key object with the actual PKCS#11 key object. In any case, that key object will only be used as a parameter to the cipher’s init() method, no methods will be invoked on it by the library at all.

Once you have done that you are ready to go. All that remains is standard programming for iSaSiLk and the Java™ platform, see the respective documentation for more information.

We will first explain how to get the demo working and then move on to some explanation, usage recommendations, and JDK version notes. It is recommended that you read this entire document even if some
sections may not seem to apply to you at the moment.

General

There are no special requirements RMI has about the socket layer that transports its calls. In other words, the core SSL library does not know or care about RMI, it is an add-on on top of it. All we do is provide a description and a demo of how we think our library should be used to secure RMI.
If you want to do something differently, just do it.

There are three players in RMI: the server, who offers services to remote programs; the client, who uses those services; and
the registry, which helps clients find servers. These player communicate using sockets and all this communication can be secured using SSL/TLS. This is what is done in the demo, where all communication between any of these players is encrypted using
strong cryptography and clients and servers are authenticated using certificates.

The RMI Demo

To run the demo follow these steps:

  1. Get yourself the required software. You of course need a JDK, either a 1.1 version (1.1.7 or later recommended) or 1.2 (1.2.2 or later recommended), 1.3 or later, which one you use is up to you. If you use a JDK version greater than 1.3 (1.4, 1.5, 1.6) you must have the signed version of
    iaik_jce_(full).jar in your classpath. Make sure that iaik_ssl.jar, iaik_ssl_demo.jar (demo classes), iaik_jce(_full).jar (most appropriate IAIK JCE 3.142 or later) and jdk11x_update.jar (from IAIK JCE, only for JDK 1.1) as well as the current
    directory are in your CLASSPATH. For example:set CLASSPATH=%CLASSPATH%;.;lib\iaik_ssl.jar;lib\iaik_ssl_demo.jar;lib\iaik_jce_full.jar;lib\jdk11x_update.jarUse this
    CLASSPATH for all the steps given below!
  2. Next executermic -d . demo.rmi.SSLHelloImplwith the rmi compiler of your JDK. This will generate the required RMI stub and skeleton classes. If you use JDK 1.2 or later you can also select RMI compatibility
    options, the demo works with all of them.
  3. Make sure the SSL keystore isasilk.keystore is in the
    current directory. If not runjava demo.SetupKeyStore
  4. Start the RMI registry. Because it is SSL secured you cannot use the standard registry, startjava demo.rmi.SSLRMIUtilinstead. It should print the success messageSSL rmiregistry started successfully...
  5. From another window start our RMI server using the same CLASSPATH:java demo.rmi.SSLHelloImplIt will register with the RMI registry and then printSSLHelloImpl created and bound in the registry to the name SSLHelloServer
  6. From yet another window start our client using the same CLASSPATH:java demo.rmi.SSLHelloClientIt will first contact the RMI registry to find out where to find the
    SSLHelloServer, then contact the server and execute its sayHello() method. That call is transparently made via RMI, which in turn
    transparently makes use of SSL. The program then printsMessage from RMI Server: Hello World over SSL!

As mentioned before, the entire communication was secured via SSL/TLS.
See below for more information.

Securing the RMI in an Existing Application

Actually using RMI over SSL is extremely simple. Done in the way explained in this document the only changes required are in the
setup code, and possibly in the use of a different RMI registry.

In short, all that is required is that at the beginning of each application that starts RMI clients, servers, or a registry the SSL policies are set via SSLContexts and a custom socket factory is activated. That’s all. As implemented in the demo this requires just three additional methods which could be used in almost exactly the same way in real world applications, only the certificates and private keys used should be parametrized there.

The assumptions the statements above are based on are:

  • You are using RMI over SSL in the way described in this document.
  • All code is available locally, no code download occurs.
  • You are using SSL for all calls and are using identical
    SSL security parameters for all calls.

For more information about the setup required please see the demo
source code, especially the class
SSLRMIUtil.

RMI Communication and the Demo Explained

RMI uses sockets for all network communication. As such it is well suited to be secured using SSL. Because the designers had that in mind and do not instantiate sockets directly and use a SocketFactory instead this is also fairly easy to do. Before we get into that, let us first explain how RMI uses sockets.

Who talks to whom in RMI?

This section describes who uses what type of sockets for what purpose. It assumes that no code downloading occurs, see also the note below.

  • RMI registry ServerSockets: it uses a ServerSocket, per default on port 1099. It waits for requests by servers binding,re-binding, un-binding, etc. implementations or clients who want to locate servers.
    client Sockets: the registry also uses
    client sockets to establish connectionsto servers right after they have registered.
  • ServerSockets: ServerSocket, per default a random local port. It is used
    to accept connections from the client and receive requests and send responses.
  • client Sockets: a client socket is used for communication
    with the RMI registry, in particular to register the server implementation.
  • ServerSockets: not used.
  • client Sockets: client sockets are used for the communication
    with the RMI registry (to find the server implementation it wants to talk
    to) and to make the actual RMI call to the server.

Types of Traffic

As can be seen from the explanation above, there are two types of
RMI traffic:

  1. Communication with the registry
  2. Communication with the actual RMI server

In principle both are worth protecting, the second obviously more than
the first, after all this is what we are here to do. The communication
with the RMI registry is not as critical as might appear at first.

Assume an attacker posing as the RMI registry to redirect calls to its own server. If the RMI registry traffic is not secured it can of course easily do so, but the client would detect the
tampering in the server authentication phase of the actual RMI call as that call is secured.
That means, all that can really be achieved is a denial of service attack that prevents the client from making some or any RMI calls, but the same effect can be achieved by preventing the client from connecting to the registry in the first place. The difference is
only when that tampering is detected.

Leaving RMI Traffic Unprotected

In environments where this is not a concern it is possible to leave RMI registry traffic unprotected. Although there is no immediate way in the RMI API for a SocketFactory to distinguish between sockets created for the RMI registry and sockets created for ordinary RMI calls this can be done by simply checking the port number, assuming the default port 1099 or another port number known in advance is used for the RMI registry. This is demonstrated in the SocketFactory implementation supplied with the demo, see its source.

In case you decide to leave RMI registry traffic unsecured there is actually no longer a need to use the customized registry supplied with the demo. Although the registry’s call to the server in reponse to its registration request will fail (talking plain instead of SSL/TLS) the registration is successful nevertheless. In other words, you can use the standard RMI registry or whatever other registry you want to use, which also allows you to use a common registry for secured and not secured RMI calls. However, remember that
using a secured RMI registry provides some additional security.

Setup Needed

As shown, all of the three partners involved in RMI all except the client, which uses client sockets only, use both client and server sockets. That means, assuming strong client and server authentication is always used, they all require the respective certificates. This is reflected in the setup code the demos use.

In the demo implementation this setup is achieved using a single call to
SSLRMIRegistry.setSSLSocketFactory() which performs three things:

  • If selected, sets up the client side SSL parameters. This includes loading the necessary private key and certificates for client authentication, setting the servers which to trust, and making all other settings to the SSLContext.
  • If selected, sets up the server side SSL parameters. The equivalent of the client side setup is performed.
  • Initializes and activates the custom RMI SocketFactory, which returns the SSL sockets.

Again, note that strictly speaking the SSL RMI registry does not need a client certificate, as noted before. Also note that if you decide to leave RMI traffic unprotected, the server certificates for the RMI registry and the client certificate for the RMI server are not required either. In other words, in that case you only need client certificates on clients
and server certificates on servers.

RMI in JDK 1.2 or later

Some improvements have been made to RMI 1.2. In particular, it is possible to use different SocketFactories for different remote objects. This also makes it possible to use secured and non-secured calls within a single VM.

However, the current demo does not make use of these improvements. As mentioned before this does preclude you from using them in your own applications.

Usage Recommendations and Notes

  • The demo uses certificates from the demo SSL keystore, the same server and client certificates for all programs. This is of course generally not advisable, you should use unique certificates for each communication
    partner.
  • RMI supports methods of tunneling RMI calls through firewalls. This feature will not work for RMI over SSL. The reason is that the JDK firewall tunneling mechanisms operate on top of the sockets and assume they can talk plain HTTP etc. over them. This of course cannot work for any type of custom sockets (like SSLSockets), as they perform additional encodings on the data. This could be considered a design flaw in the RMI implementation.
  • Using code downloading is generally not recommended. Any code in a security application should be obtained in a way compliant with the security policy used. In our case, for automatic code downloading this would mean that the code should be obtained in a way as secure as the RMI calls that are later made. This could be achieved by either also downloading the code using strong SSL with authentication or possibly using code signing (if appropriately configured). Unless that is done code downloading over e.g. plain HTTP introduces an
    obvious security hole.
  • The RMI SocketFactory setting is global and can only be made once. This means that it is not easily possible to use secured and non secured RMI calls at the same time. This limitation was lifted in
    JDK 1.2, see the section above.

General

iSaSiLk makes use of the JCA/JCE API for all cryptographic operations. However, it does not use the
getInstance() methods of those API classes directly, rather it uses a SecurityProvider class which centralizes all the various calls. Basically, there are two reasons for that. First, there is is no portable way to perform all required operations. For example, there is no provider indepedent way to construct a Principal object from its DER encoding. Also, some providers do not implement all required features defined in JCA/JCE. The second reason is that the SecurityProvider concept allows for more flexibility and makes it easier to use several providers at the same time.
The important class here is
iaik.security.ssl.SecurityProvider. It contains all the relevant API methods and provides a default SecurityProvider implementation that can be customized to accommodate your needs. Additionally it contains the static setting of the currently active SecurityProvider. It can be set and inspected using the methods
setSecurityProvider() and
getSecurityProvider(), respectively. Note that this is a global setting for the entire VM.

The SecurityProvider Class

The SecurityProvider class defines a number of constant strings as well
as methods.

Constant String

Constant strings are defined using the following variable names:
 ALG_DIGEST_MD5
ALG_DIGEST_SHA
ALG_DIGEST_SHA256
ALG_DIGEST_SHA384
ALG_HMAC_MD5
ALG_HMAC_SHA
ALG_HMAC_SHA256
ALG_HMAC_SHA384
ALG_SIGNATURE_SHADSA
ALG_SIGNATURE_SHAECDSA
ALG_SIGNATURE_SHA224ECDSA
ALG_SIGNATURE_SHA256ECDSA
ALG_SIGNATURE_SHA384ECDSA
ALG_SIGNATURE_SHA412ECDSA
ALG_SIGNATURE_RAWDSA
ALG_SIGNATURE_MD5RSA
ALG_SIGNATURE_SHA1RSA
ALG_SIGNATURE_SHA224RSA
ALG_SIGNATURE_SHA256RSA
ALG_SIGNATURE_SHA384RSA
ALG_SIGNATURE_SHA512RSA
ALG_KEYPAIR_RSA
ALG_KEYEX_RSA
ALG_KEYEX_DSA
ALG_KEYEX_DSA_CLIENT
ALG_KEYEX_DH
ALG_KEYEX_PSK
ALG_KEYEX_DHE_PSK
ALG_KEYEX_RSA_PSK
ALG_CIPHER_AES
ALG_CIPHER_AES_GCM
ALG_CIPHER_AES_PKCS5
ALG_CIPHER_CAMELLIA
ALG_CIPHER_CAMELLIA_GCM
ALG_CIPHER_RC4
ALG_CIPHER_RC2
ALG_CIPHER_DES
ALG_CIPHER_3DES
ALG_CIPHER_IDEA
ALG_CIPHER_AES
ALG_CIPHER_RSA
ALG_CIPHER_RSA_SIGN
ALG_CIPHER_RSA_VERIFY
ALG_CIPHER_RSA_ENCRYPT
ALG_CIPHER_RSA_DECRYPT
ALG_CIPHER_RSA_ENCRYPT_SSL2

They are used with the respective
getInstance() methods. A special case are the
ALG_CIPHER_RSA_xxx strings. They are used to simplify differentiation between the various types of RSA operations, which is useful particularly for Smartcards (see also iSaSiLk and Smartcards). Usually the same RSA implementation is used in all cases though.

SecurityProvider Constructor

The SecurityProvider class has two constructors. A no-argument constructor, which will create a security provider that searches all JCA installed providers, and a constructor that takes as string argument the name of the only provider to be searched. This is usefull when you want to avoid that implementations from some other provider is used.

Methods

The security provider defines the following methods, all of which
have been implemented to work in a provider independent way using
only the JCA/JCE APIs. Note that does not necessarily mean that
they will work with any provider as some providers do not implement
the necessary KeyFactories, etc.
protected boolean isImplemented(String algorithm);
protected DHPublicKey getDHPublicKey(BigInteger y, BigInteger p, BigInteger g) throws Exception;
protected DHPrivateKey getDHPrivateKey(BigInteger x, BigInteger p, BigInteger g) throws Exception;
protected RSAPublicKey getRSAPublicKey(BigInteger modulus, BigInteger publicExponent) throws Exception;
protected X509Certificate getX509Certificate(byte[] array) throws Exception;
protected X509Certificate getX509Certificate(InputStream is) throws Exception;
protected MessageDigest getMessageDigest(String algorithm) throws Exception;
protected Mac getMac(String algorithm, Key key) throws Exception;
protected Signature getSignature(String algorithm, int mode, Key key, SecureRandom random) throws Exception;
protected byte[] calculateRawSignature(String algorithmName, byte[] dataToBeSigned, PrivateKey key, SecureRandom random) throws Exception;
protected boolean verifyRawSignature(String algorithmName, byte[] dataToBeSigned, byte[] signature, PublicKey key);
protected Cipher getCipher(String algorithm, int mode, Key key, AlgorithmParameterSpec spec, SecureRandom random) throws Exception;
protected KeyPairGenerator getKeyPairGenerator(String algorithm) throws Exception;
protected SecureRandom getSecureRandom();
public String decodeURL(byte[] encodedCertificateURL) throws Exception;
public byte[] encodeURL(String certificateURL) throws Exception;
public ServerName getTLSServerName(int nameType, byte[] encodedServerName);
public ServerName[] getTLSServerName(int nameType, X509Certificate serverCert);
public ServerName getTLSServerName(int nameType, String name) throws Exception;

Note that the
getCipher(),
getSignature(), and

getMac() must initialize the respective
object before returning it if requested (i.e. mode is not SIGNATURE_NONE,
CIPHER_NONE, key is not null, respectively). This structure was chosen to
allow you to convert keys if your provider can only handle its own keys objects, etc.
For example, for symmetric keys the
SecretKeySpec class is used,
which may not be supported by all providers.
The following two methods could not be implemented in a provider independent way and only
return
null when called. For this particular case the library has been
designed to work without them as well, but note that this disables the more
precise client authentication certificate selection. Therefore, it is recommended
to provide concrete implementations for your provider if possible.
protected Principal getPrincipal(byte[] array) throws Exception;
protected byte[] getEncodedPrincipal(Principal principal);

The following method could not be implemented in a provider independent way and only
return
null when called. For this particular case the library has been
designed to work without them as well, but note that this disables the more
precise server name verification. Therefore, it is recommended
to provide concrete implementations for your provider if possible.
protected String[] getTLSServerName(X509Certificate serverCert);

The following methods could not be implemented in a provider independent way.
They are required when using iSaSiLk with TLS extensions:
 protected String[] getTLSServerName(X509Certificate serverCert);
public byte[] createCertStatusRequest(int statusType) throws Exception;
public byte[] createPkiPath(X509Certificate[] certificates) throws Exception;
public SecretKey deriveKey(String algorithm, char[] password, byte[] salt, int iterationCount, int keyLen, String keyName, SecureRandom random) throws Exception;
public byte[] calculateTrustedAuthorityIdentifier(int type, X509Certificate certificate) throws Exception;

The SecurityProvider Default Implementation

Below we provide the source code for the SecurityProvider class.
It is the code from iSaSiLk slightly modified
(comments and constant strings removed, etc.).
public class SecurityProvider {

protected String providerName;

public SecurityProvider() {
this(null);
}

public SecurityProvider(String providerName) {
this.providerName = providerName;
}

protected DHPublicKey getDHPublicKey(BigInteger y, BigInteger p, BigInteger g) throws Exception {
DHPublicKeySpec spec = new DHPublicKeySpec(y, p, g);
KeyFactory factory = (providerName == null) ? KeyFactory.getInstance(“DH”) :
KeyFactory.getInstance(“DH”, providerName);
DHPublicKey key = (DHPublicKey)factory.generatePublic(spec);
return key;
}

protected DHPrivateKey getDHPrivateKey(BigInteger x, BigInteger p, BigInteger g) throws Exception {
DHPrivateKeySpec spec = new DHPrivateKeySpec(x, p, g);
KeyFactory factory = (providerName == null) ? KeyFactory.getInstance(“DH”) :
KeyFactory.getInstance(“DH”, providerName);
DHPrivateKey key = (DHPrivateKey)factory.generatePrivate(spec);
return key;
}

protected RSAPublicKey getRSAPublicKey(BigInteger modulus, BigInteger publicExponent) throws Exception {
RSAPublicKeySpec spec = new RSAPublicKeySpec(modulus, publicExponent);
KeyFactory factory = (providerName == null) ? KeyFactory.getInstance(“RSA”) :
KeyFactory.getInstance(“RSA”, providerName);
RSAPublicKey key = (RSAPublicKey)factory.generatePublic(spec);
return key;
}

protected X509Certificate getX509Certificate(byte[] array) throws Exception {
CertificateFactory factory = (providerName == null) ?
CertificateFactory.getInstance(“X.509”) :
CertificateFactory.getInstance(“X.509”, providerName);
InputStream in = new ByteArrayInputStream(array);
X509Certificate cert = (X509Certificate)factory.generateCertificate(in);
return cert;
}

protected Principal getPrincipal(byte[] array) throws Exception {
return null;
}

protected byte[] getEncodedPrincipal(Principal principal) {
return null;
}

protected MessageDigest getMessageDigest(String algorithm) throws Exception {
return (providerName == null) ? MessageDigest.getInstance(algorithm) :
MessageDigest.getInstance(algorithm, providerName);
}

protected Mac getMac(String algorithm, Key key) throws Exception {
Mac mac = (providerName == null) ?  Mac.getInstance(algorithm) :
Mac.getInstance(algorithm, providerName);
if( key != null ) {
mac.init(key);
}
return mac;
}

protected Signature getSignature(String algorithm, int mode, Key key, SecureRandom random) throws Exception {
Signature sig = (providerName == null) ? Signature.getInstance(algorithm) :
Signature.getInstance(algorithm, providerName);
if( mode == SIGNATURE_SIGN ) {
sig.initSign((PrivateKey)key);
} else if( mode == SIGNATURE_VERIFY ) {
sig.initVerify((PublicKey)key);
} // do nothing for SIGNATURE_NONE
return sig;
}

protected byte[] calculateRawSignature(String algorithmName, byte[] dataToBeSigned, PrivateKey key, SecureRandom random) throws Exception {
Cipher cipher = getCipher(algorithmName, CIPHER_ENCRYPT, key, null, random);
byte[] signature = cipher.doFinal(dataToBeSigned);
return signature ;
}

protected boolean verifyRawSignature(String algorithmName, byte[] dataToBeSigned, byte[] signature, PublicKey key) throws Exception {
Cipher cipher = getCipher(algorithmName, CIPHER_DECRYPT, key, null, null);
byte[] received_hash = cipher.doFinal(signature);
return Utils.equalsBlock(dataToBeSigned, received_hash);
}

protected Cipher getCipher(String algorithm, int mode, Key key, AlgorithmParameterSpec spec, SecureRandom random) throws Exception {
if( algorithm.startsWith(ALG_CIPHER_RSA) ) {
algorithm = ALG_CIPHER_RSA;
}
Cipher cipher = (providerName == null) ? Cipher.getInstance(algorithm) :
Cipher.getInstance(algorithm, providerName);
if( mode != CIPHER_NONE ) {
int cmode = (mode == CIPHER_ENCRYPT) ? Cipher.ENCRYPT_MODE : Cipher.DECRYPT_MODE;
cipher.init(cmode, key, spec, random);
}
return cipher;
}

protected KeyPairGenerator getKeyPairGenerator(String algorithm) throws Exception {
return (providerName == null) ? KeyPairGenerator.getInstance(algorithm) :
KeyPairGenerator.getInstance(algorithm, providerName);
}

protected SecureRandom getSecureRandom() {
return new SecureRandom();
}

protected String[] getTLSServerName(X509Certificate serverCert) {
return null;
}

}

Writing Your Own SecurityProvider

Step One: Writing the Provider

Basically there are two scenarios:

  1.  You want to mainly use the IAIK JCE as a provider and use another
    provider just for a few algorithms. For instance, you might want to use
    the IAIK PCKS#11 provider for doing RSA based cipher operations only.
  2.  You do not want to use the IAIK JCE at all and use only some other
    provider.

In the first case the easiest thing to do is to subclass the
IaikProvider class. For example,
package demo;

public class MySecurityProvider extends IaikProvider {

protected Cipher getCipher(String algorithm, int mode, Key key, AlgorithmParameterSpec param, SecureRandom random) throws Exception {

if (key instanceof IAIKPKCS11Key) {
if (algorithm.startsWith(ALG_CIPHER_RSA)) {
algorithm = ALG_CIPHER_RSA;
}
cipherEngine = Cipher.getInstance(algorithm, ((IAIKPKCS11Key) key).getTokenManager().getProvider().getName());
if (mode != CIPHER_NONE) {
int cmode = (mode == CIPHER_ENCRYPT) ? Cipher.ENCRYPT_MODE : Cipher.DECRYPT_MODE;
cipherEngine.init(cmode, key, param, random);
}
} else {
cipherEngine = super.getCipher(algorithm, mode, key, param, random);
}

}
}

In the second case, i.e. you want to use a different provider altogether
and not use the IAIK JCE at all (for whatever reason 😉 it will be easiest
to start with the
SecurityProvider class and override those
methods where you cannot use the default implementation. It might we
wise to have the IAIK JCE in your
CLASSPATH at first so that
you can use its implementations for those parts you have not changed
to use your provider yet.

Step Two: Using it in Your Program

To use your own SecurityProvider in your application you only have
to make sure you have all required classes in your
CLASSPATH
and that you activate it at the beginning of your program. This
can be done using, for example:
SecurityProvider.setSecurityProvider(new demo.MySecurityProvider());

Alternatively you may set your security provider via property file. iSaSiLk
first looks if there is a property file with name “SecurityProvider.properties”
located in package iaik.security.ssl. You may set the value of the only “class”
entry to the full name of your provider, e.g.:
class = demo.MySecurityProvider

Of course you also have to make sure your provider is initialized
in whatever way(s) it requires, e.g. add it as a JCE security provider.

This document explains how to secure HTTPS traffic with SSL/TLS using iSaSiLk. We give a quick rundown of the demo and explain how the API can be used.

Basically what the code allows you to do is to use HTTPS URLs with the java.net.URL   class, open connections to perform requests and read responses, just like standard HTTP URLs are supported in the JDK.

Note: This document does not give a complete description of all features of Java™ URLs and HttpURLConnections, please refer to the iSaSiLk and JDK JavaDoc files or additional information.

General

HTTPS is nothing more than the HTTP protocol over SSL/TLS rather than over plain TCP. As such it would be quite easy to add HTTPS to any HTTP implementation given the necessary hooks for the transport are
provided or the source is available.

Unfortunately this is not the case for the HTTP code that comes with the JDK. As developing a stable and fairly complete implementation of HTTP/1.1 would be a serious undertaking and reinventing the wheel is something we prefer to avoid, we decided not to do yet another HTTP implementation and to use the W3C’s HTTP code that comes with their Jigsaw Web server instead (see license
notice).

Essentially what we did was to take the Jigsaw source (current version 2.2.6), remove a lot of classes which are not required for HTTP URL support, and modify a few classes to allow for HTTPS. We provide the result as the JAR file w3c_http.jar which has to be used in addition to
the iSaSiLk iaik_ssl.jar file for HTTPS support.

As a sidenote we would also like to point at that there is at least one third party HTTP implementation that can be used with iSaSiLk to provide HTTPS support. It is called HTTPClient, is free under a LGPL license and available online. Please note that this is a pointer to a possible alternate solution only and not an endorsement of this software. As a matter of fact we have
never evaluated it and of course cannot answer any support questions about it.

Using HTTPS

This section explains how to actually use HTTPS by describing the demo supplied with the iSaSiLk distribution. Its source is located in HttpsDemo.java example and it is available in
compiled form in the iaik_ssl_demo.jar file.

Running the Demo

To try out the demo do the following (assuming you are using the IAIK JCE
as your cryptographic provider and a JDK version on a Windows platform):

set CLASSPATH=%CLASSPATH%;.;lib\iaik_ssl.jar;lib\w3c_http.jar;lib\iaik_jce_full.jar
java demo.https.HttpsDemo https://jce.iaik.tugraz.at/

Note that the HTTPS code requires w3c_http.jar in addition to
iaik_ssl.jar. The demo then will open a HTTPS connection to https://jce.iaik.tugraz.at/, display some status information and then print the downloaded HTML page. You can select a different server by passing its URL as argument to the demo.

The Demo Code

As shown in the demo using HTTPS is very simple. Summarized, the steps to
follow are:

  1. Setup your environment for HTTPS. Make sure you have w3c_http.jar in your CLASSPATH in addition to iaik_ssl.jar and your cryptographic code. In your program register HTTPS URLs so that they can be used,
    for more information see the next section.
  2. Setup the SSL code so that it is ready to go, i.e. add your cryptographic provider and set your SecurityProvider if necessary. Then set the SSL parameters you want to use in an SSLContext. Either set it as the default SSL context using the static method HttpsURLConnection.setDefaultSSLContext() or set it
    dynamically on your URLConnection using setSSLContext()
  3. Create HTTPS URLs and calls openConnection() on them. A HttpsURLConnection object is returned. You can perform all standard java.net.HttpURLConnection operations on it and additionally call getSSLSocket() to get SSL parameters directly from the socket. Note:  do not forget to set
    your SSLContext on this object unless you set a static default.

Registering HTTPS URLs

The HTTPS protocol has to be registered with the java.net
APIs before it can be used. There are several options:

  • Set the system property java.protocol.handler.pkgs.
    Use for example/nbsp;System.getProperties().put("java.protocol.handler.pkgs", "iaik.protocol");This property can contain a list of packages used to search for protocol handlers. For more information see the JDK documentation for the java.net.URL class. Note that this will not work if a factory is installed,
  • Set the factor for URLStreamHandler. Use code like/nbsp;java.net.URL.setURLStreamHandlerFactory(new iaik.protocol.https.HttpsURLStreamHandlerFactory());For some reason the JDK code allows the factory to be set only once. That means if you environment already has a factory installed for some reason (as usually the case with Applets or Servlets) this code cannot be used either. In that case you can only check the installed factory if it allows other protocols to be added in some way.
  • If you are using JDK 1.2 or later you can specify the handler dynamically
    when creating an URL object./nbsp;URL u = new URL(null, "https://...", new iaik.protocol.https.Handler());Note that all your HTTPS URLs have to be created in this way. Also note that you need not create a new Handler object each time, you can use the same for all URLs.

HTTPS Without Registering URLs

For cases where the above approaches cannot be used we provide a limited workaround. Because HTTPS URLs cannot even be created if no appropriate protocol handler is installed they cannot be used in this case but it is still possible to speak HTTPS via the provided implementation. To do this
create a HTTP (!) URL specifying the target host and port and pass it directly to the constructor of the class iaik.protocol.https.HttpsURLConnection. For example, use code like this:

URL u = new URL("https://jce.iaik.tugraz.at:443/");
URLConnection connection = new HttpsURLConnection(u);
InputStream in = connection.getInputStream();

Note that you must specify a destination port in this case, you cannot use the default port (80 would be used as for HTTP). Also note that this is a limited workaround only, we recommend using it only if the other options are not available. This problem is due to a limitation in the JDK software and not in ours.

Using the POST Method

HTTP defines a number of request methods. Most often used is the GET method, which is appropriate to retrieve data from the server. Another request method is POST, which is most usefull to send large amounts of data to the server. iSaSiLk supports both.

However, in difference to the original JDK HTTP implementation the POST method is not automatically chosen if you enable both input and output
for the connection. To use the POST method use code like this:

HttpsURLConnection con = (HttpsURLConnection)url.openConnection();

// setup SSL-configuration
con.setSSLContext(context);

con.setRequestMethod(“POST”);
con.setDoInput(true);
con.setDoOutput(true);

OutputStream out = con.getOutputStream();
out.write(“foobar”.getBytes());
out.flush();

InputStream in = con.getInputStream();

Important: Please note the order in which the methods are executed and also that
all data must be written before calling
getInputStream().

Connecting via a Proxy

For connecting via a proxy the host name and port number of the proxy have to be set as System properties using “https.proxyHost” and
“https.proxyPort” as key words, e.g.:

String proxyHost = ...;
int proxyPort = ...;
System.setProperty("https.proxyHost", proxyHost);
System.setProperty("https.proxyPort", proxyPort);
...

If the proxy requires a user to authenticate him/herself by username and password, this either may be done in the common way by setting a request property on the HttpsURLConnection object or by specifying user name and password via System properties. When setting proxy user name and password via request property you have to use “Https-Proxy-Authorization” as key. The value consists of authentication scheme (“Basic”) and username/password encoding (base64) as
accustomed from normal (proxy) authentication, e.g.:

String authString = "userid:password";
String authMsg = "Basic " + base64encode(authString.getBytes());
URL url = new URL("https://...");
HttpsURLConnection con = (HttpsURLConnection)url.openConnection();
...
con.setRequestProperty("Https-Proxy-Authorization", authMsg);

Please ensure to use “Https-Proxy-Authorization” as key only when connecting through a authentication requesting HTTPS proxy! Do not use another key like “Proxy-Authorization” or “Authorization”. It would not be recognized and so may travel to the target server. You may test the behaviour of your proxy by connecting through it to an iSaSiLk server to see what is actually send to the server.

When setting HTTPS proxy user and password via System properties (may not be the recommended way except you are sure that no one else may have access to your client machine), use “https.proxyUser” and
“https.proxyPassword” as keys:

String httpsProxyUser = ...;
String httpsProxyPassword =...;
System.setProperty("https.proxyUser", httpsProxyUser);
System.setProperty("https.proxyPassword", httpsProxyPassword);

Moreover, it is possible to specify a list of hosts for which the library should
not use a proxy. This can be done using the https.nonProxyHosts property. The use is similar to the http.nonProxyHosts property. The value of this property is a ‘|’ separated list of host names. The ‘*’ as wildcard character
is allowed as first character of a name in the list. For example:

System.setProperty("https.nonProxyHosts", "*.tugraz.at|www.iaik.at");

For a host that matches any of the names in this list, the library will establish the connection directly without using the proxy.

Notes

  • The HTTP implementation is not ours but the W3C’s. We can only
    provide limited support for not SSL specific problems.
  • The W3C library provides a whole set of additional features and an entire alternate API. However, those have not been tested AT ALL and should NOT be used. The only functionality we support is the one described above, i.e. creation of HTTPS URLs and calling openConnection() on them.
  • No operations other than SSL status query calls should be executed on the socket returned by
    getSSLSocket(). For example, you can use it to determine the active SSL ciphersuite or to obtain the server certificates, but do not access its
    streams, etc.
  • Because the HTTP library employs persistent connections that are possibly used for multiple HTTPS requests, changes to an SSLContext may not be immediately reflected in successive connections if they are to a server with which a HTTPS connection was already previously established! It is assumed that this will generally not be a problem because the SSL preferences only rarely ever
    need to be changed in the middle of a connection.
  • HTTPS connections are automatically established through a HTTP proxy if the respective settings have been made in the Java™ environment. SOCKS proxies are supported by the original java.net.Socket class anyway.See iaik.security.ssl.Utils.proxyConnect() for details.

This document describes how the TLS protocol uses certificates for authentication and the role of the iSaSiLk library and the application.

General

The TLS protocol uses public key cryptography for authentication. In all ciphersuites except DH_anon the server is authenticated, client authentication is optional for all ciphersuites except DH_anon. Peer authentication in this case means verification that the peer has access to the private key corresponding to the public key contained in the certificate he provided.

This is part of the TLS protocol and as such performed by the library automatically as configured. What remains for the application is to input its certificates and private keys, specify its algorithm preferences, and, very importantly, verify that the certificate provided by the remote peer is actually trusted.

Note that this document only describes the new framework and not the old model using TrustDeciders. It is still supported for compatibility though,  please see the documentation from earlier releases for information about how to use it.

Certificates Types

In TLS the types of certificates used are determined by the ciphersuite. For all standard ciphersuites X.509 certificates are used and the following types of certificates are distinguished

  • RSA. Certificates containing an RSA public key. The algorithm used to
    sign the certificate should also be RSA.
  • DSS. Certificates containing a DSA public key. The algorithm used to
    sign the certificate should also be DSA.
  • DH_RSA. Certificates containing a Diffie-Hellman public key. The algorithm
    used to sign the certificate should be RSA.
  • DH_DSS. Certificates containing a Diffie-Hellman public key. The algorithm
    used to sign the certificate should be DSA.
  • ECDH_RSA. Certificates containing an EC Diffie-Hellman public key. The algorithm
    used to sign the certificate should be RSA.
  • ECDH_ECDSA. Certificates containing an EC Diffie-Hellman public key. The algorithm
    used to sign the certificate should be ECDSA.
  • ECDSA. Certificates containing an ECDSA public key. The algorithm used to
    sign the certificate should also be ECDSA.

Note that we refer to the algorithm
DSA digital signature of an SHA-1hash as DSA while the TLS specification uses the name DSS. Both terms
describe the same algorithm and we use them interchangeably.
DH_RSA and DH_DSS certificates both contain a Diffie-Hellman public key and as such are functionally identical. The distinction based on the certificate signature algorithm is only made to allow a peer to advertise that does or does not implement the RSA or DSA algorithm. In the same way ECDH_RSA and ECDH_ECDSA are functionally identical but the algorithm used to sign the certificate is different.

The Server Side

The server requires certificates if a non-anonymous ciphersuite is used. In iSaSiLk you can set the server certificates using the

addServerCredentials() method of the
SSLServerContext class. You can pass either a PrivateKey object and an array of X509Certificates or a KeyAndCert object (KeyAndCert is a simple class that stores a private key and the corresponding certificate chain), or a KeyStore object (which may
contain multiple server credentials, i.e. private key entries and corresponding certificate chains).. The
addServerCredentials() method automatically determines the type of certificate used and stores it replacing existing credentials of the same type.

Certificates

Below is a table of the certificate types and the ciphersuites that require its presence to function. Ciphersuites are identified via their TLS keyexchange algorithm.

 Certificate type  Key exchange algorithm requiring this type of certificate
RSA RSA, RSA_EXPORT, RSA_EXPORT1024, DHE_RSA, DHE_RSA_EXPORT, ECDHE_RSA
DSS DHE_DSS, DHE_DSS_EXPORT, DHE_DSS_EXPORT1024
DH_RSA DH_RSA, DH_RSA_EXPORT
DH_DSS DH_DSS, DH_DSS_EXPORT
ECDH_RSA ECDH_RSA
ECDH_ECDSA ECDH_ECDSA
ECDSA ECDHE_ECDSA
No certificate DH_anon, DH_anon_EXPORT, ECDH_anon

 

Unless the required certificate is available that ciphersuite cannot be used. Calling
updateCipherSuites() on the SSLServerContext object will
automatically disable all those ciphersuites that cannot be used.

Temporary Parameters

In addition to certificates and a private key some ciphersuites require additional parameters. In particular, DHE ciphersuites require temporary Diffie-Hellman parameters (prime modulus and a generator), and ECDHE ciphersuites require temporary EC parameters (elliptic curve domain parameters, i.e. named_curve). Also exportable RSA ciphersuites require a temporary RSA keypair if the public key in the certificate is longer than the limit for that ciphersuite (i.e. 512 bit for EXPORT, 1024 bit for EXPORT1024).

For DHE and RSA those parameters can be set using the
addTemporaryParameter() method of SSLServerContext. If a temporary parameter is not set but a ciphersuite is chosen in the handshake that requires it defaults are used. For DHE this means pre-generated Diffie-Hellman parameters of 512 or 1024 are used, for
RSA a new 512 or 1024 bit RSA keypair is generated on the fly. For ECDHE the curve is negotiated by means of the SupportedEllipticCurves extension.
RSA keypair generator may take a few seconds, especially for 1024 bit keys. If this is a concern you should not use the defaults and set a temporary keypair manually, but note that the keypair generation will only be performed once per JVM invocation anyway. For additional information about temporary parameters please see the JavaDoc.

The Client Side

The client does not require certificates per se, but as noted above the server may request client authentication and choose not to accept clients with an appropriate certificate.

In TLS client authentication works as follows: during the handshake the server may request a client certificate. While doing that he also specifies which types of client certificates he wants to accept (and same four basic types described above) and optionally which certificate authorities he trusts (he lists their subject distinguished names). Both of this is done to make it easier for the client to choose the correct certificate. The server may also choose not to tell which CAs he trusts and send an empty list instead.

Note that client authentication with RSA, ECDSA and DSS certificates is available for all ciphersuites, DH_RSA and DH_DSS is only available for DH_ ciphersuites, and ECDH_RSA and ECDH_ECDSA is only available for ECDH_ ciphersuites, i.e. those where the server uses (EC)DH certificates as well. These are a special case because the EC(DH) keys cannot be used for signatures and authentication has to be performed differently. For this and other reasons we generally recommend ECDHE, DHE, ECDSA and RSA over (EC)DH.

Requesting Client Authentication

In iSaSiLk the server can request client authentication by calling
serverContext.setRequestClientCertificate(true). The valid certificate types and trusted CAs are determined automatically. You can also restrict the types of client certificates you wish to accept, e.g. not allow DSS certificates. Use the method

serverContext.setAllowedCertificateTypes(). The trusted certificate authorities are determined using the ChainVerifier’s
getTrustedPrincipalsArray() method, see below for more information about the ChainVerifier class.

Adding Credentials

For client authentication with iSaSiLk the client only needs to add this private keys and certificates, the library will automatically select the appropriate ones. To add credentials use the
clientContext.addCredentials() method. You can add as many as you want, they will automatically be stored in a database. You can pass either a PrivateKey object and an array of X509Certificates or a KeyAndCert object (KeyAndCert is a simple class that stores a private key and the corresponding certificate chain), or a KeyStore object (which may contain multiple client credentials, i.e. private key entries and corresponding certificate chains).

During the handshake the library code calls the
clientContext.getClientCredentials() method to retrieve client certificates. If you want to implement your own storage mechanism you only need to override this method.

Trust Settings and Verification

There are two basic parts to verifying trust: (a) specifying which certificates (and CA trees) to trust and (b) a profile to follow when verifying certificate chains.

In iSaSiLk this is handled by the ChainVerifier class. It also you to specify trusted certificates and its code implements a basic X.509v1 style profile to verify certificate chains. It can be replaced by a more advanced implementation if desired, for example it would be possible to use the IAIK Trust Manager. For information about custom ChainVerifier please see the JavaDoc API documentation.

You can specify trusted certificates by calling e.g.
context.addTrustedCertificate(), which is a shorthand for
context.getChainVerifier().addTrustedCertificate(). The library code will call the ChainVerifier during the handshake as described below.

Client Side Trust Verification

The client verifiers that the server has an acceptable certificate. The following cases arise (assuming the default ChainVerifier implementation is used):

  • ChainVerifier is null: If the ChainVerifier for the current SSLContext is null all certificates are accepted. Note that the ChainVerifier is only null when explicitly set to null by the application.
  •  CipherSuite is (EC)DH_anon: If the active ciphersuite is anonymous the ChainVerifier is not called and the connection is accepted. The reasoning is that (EC)DH_anon is only used when explicitly enabled by the user making an additional check of the always server certificate redundant (for (EC)DH_anon the server certificate is of course actually null).
  •   No trusted certificates set: If no trusted certificates have been specified all valid certificate chains are accepted. Valid in this case means that all signature verify, no certificates are expired, etc.
  •   One or more trusted certificates set: If trusted certificate have been specified only chains that are valid and contain a trusted certificate are accepted.

For more information please the the JavaDoc for the ChainVerifier class.

Server Side Trust Verification

The client verifiers that the server has an acceptable certificate. The following cases arise (assuming the default ChainVerifier implementation is used):

  •   Client authentication disabled: If client authentication is disabled the client is always accepted. The ChainVerifier is not callled.
  •  ChainVerifier is null: If client authentication is enabled but the current ChainVerifier is null, all client certificates and clients which do not send a certificate are accepted.
  •   Client does not send a certificate: If client authentication is enabled, the ChainVerifier is not null, but the client does not send a certificate, the connection is only accepted if
    null was specified as a trusted certificate (via
    context.addTrustedCertificate(null)).
  •   No trusted certificates specified: If the client sends a certificate but no trusted certificates have been specified in the ChainVerifier (except for possibly null), all valid certificate chains are accepted. Valid in this case means that all signature verify, no certificates are expired, etc.
  •   One or more trusted certificates specified: If the client sends a certificate and some trusted certificates have been specified in the
    ChainVerifier only chains that are valid and contain a trusted certificate are accepted.

For more information please the the JavaDoc for the ChainVerifier class.

Key and Certificate Handling for TLS extensions

Some TLS extensions may require an additional/alternative key or certificate handling. If, for instance, the client sends an OCSP certificate
status_request extension to the server, it may have to validate the OCSP status response sent back by the server. In this case the alternative
OCSPCertStatusChainVerifier maybe enabled to check the OCSP response got from the server:

SSLClientContext clientContext = new SSLClientContext();
OCSPCertStatusChainVerifier ocspChainVerifier = new OCSPCertStatusChainVerifier();
clientContext.setChainVerifier(ocspChainVerifier);

See the iSaSiLk

TLS extensions (143.81 kB)

This document gives information about interoperability with other SSL/TLS implementations and notes to SSL 2.0.

Protocol Version Selection

iSaSiLk supports several versions of the SSL/TLS protocol (SSL 2.0 on the client, SSL 3.0, TLS 1.0 and TLS 1.1 on both client
and server side). SSL 2.0 is disabled by default for security reasons and should only be enabled if it is actually needed.
The SSL/TLS protocol ensures that always the highest protocol version supported by both the client and the server is used.
Therefore, most applications should never need to care about version selection. However, this may not work correctly
with certain very few buggy implementations. In this case you might want to disable a protocol version. This is done using
the
setAllowedProtocolVersion() method in the
SSLContext.
Per default SSL 3.0, TLS 1.0 and TLS 1.1 are enabled for both clients and server, SSL 2.0 is not enabled, see the section on SSL 2.0
for more information
Once the handshake has been completed you can call the
getActiveProtocolVersion() method of
your SSLSocket to retrieve the selected SSL version.

SSL 2.0 Notes

iSaSiLk also supports SSL 2.0 on the client side, server side SSL 2.0 is NOT supported. It was implemented to allow communication
with a few remaining old server implementations that do not support SSLv3. Server side support for SSLv2 should never be needed
as virtually all clients long support SSLv3.
SSLv2 is a very mediocre security protocol and has several known flaws and design limitations. Therefore, it is disabled by default. It should
only be enabled if you want to communicate with a server that does not support SSLv3.
A few of the limitations of SSL 2.0 are:

  • Very limited selection of ciphersuites. SSLv2 only supports RSA for key exchange and MD5 for the MAC.
  • No support for certificate chains. SSLv2 certificate messages can only contain a single certificate, hierarchies are not properly possible.
  •  No proper error signalling. Once the handshake has been completed it is no longer possible to signal errors like a MAC error to the peer.
    Neither are there closure alerts like in SSLv3. This means that it is not possible to detect if the remote peer closed the connection normally,
    because of an error, or if the connection was closed on the TCP level by an attacker.
  • No renegotiation. Ciphersuite renegotiation is not supported in SSL 2.0.
  • No compression. Compression is not possible in SSLv2 but this is only a minor limitation as it is never used in SSLv3 either.

Setting SSL 2.0 Enabled Ciphersuites

In iSaSiLk SSLv2 enabled ciphersuites are not manually set. Rather they are computed automatically from the enabled v3 suites. That means that
if v2 is enabled the list of enabled v3 suites is checked and if a given enabled v3 ciphersuite has an equivalent in v2 that is automatically enabled.
These equivalents are:

SSLv3 Ciphersuite SSLv2 Equivalent Ciphersuite
SSL_RSA_WITH_3DES_EDE_CBC_SHA SSL2_RSA_WITH_DES_192_EDE3_CBC_MD5
SSL_RSA_WITH_IDEA_CBC_SHA SSL2_RSA_WITH_IDEA_128_CBC_MD5
SSL_RSA_WITH_RC4_MD5 SSL2_RSA_WITH_RC4_128_MD5
PRIVATE_RSA_WITH_RC2_CBC_MD5 SSL2_RSA_WITH_RC2_128_CBC_MD5
SSL_RSA_WITH_DES_CBC_SHA SSL2_RSA_WITH_DES_64_CBC_MD5
SSL_RSA_EXPORT_WITH_RC4_40_MD5 SSL2_RSA_WITH_RC4_128_EXPORT40_MD5
SSL_RSA_EXPORT_WITH_RC2_CBC_40_MD5 SSL2_RSA_WITH_RC2_128_CBC_EXPORT40_MD5

 

As you can see there is an equivalent v3 ciphersuite for each v2 ciphersuite (SHA is used instead of MD5 several times) except for
SSL2_RSA_WITH_RC2_128_CBC_MD5. In this case a private ciphersuite with the v3 id 0xFF5B was defined as an equivalent. This ciphersuite
PRIVATE_RSA_WITH_RC2_CBC_MD5 can also be used in v3 mode but this is not recommended.

Interoperability

Fairly extensive interoperability testing has been performed between iSaSiLk and other SSL/TLS compliant implementations. Some minor problems
have been fixed and there are no known interoperability problems except for those listed below. Note that because iSaSiLk fully supports all aspects
of SSL3.0/TLS1.0/TLS1.1 iSaSiLk is interoperable with any other standard compliant implementation no matter which algorithms it supports and has enabled.
No problems were detected in tests with the following implementations:

  • Netscape Navigator and Communicator, versions 3.x, 4.0x, 4.5 and later
  • Mozilla and Firefox browsers, various versions
  • Netscape Servers (Enterprise, etc.), various versions
  • Microsoft Internet Explorer, versions 4.x, 5.x, 6.x, 7.x
  • Microsoft IIS, versions 4.x, 5.x, 7.x (but see see note below)
  • SSLeay and OpenSSL based software (Apache + mod_ssl), various versions
  • Oracle Server (Web Listener)
  • Opera browsers, various versions (but see note below)

Some notes apply to the following implementations:

  •  iSaSiLk versions prior to 3.0: these versions has minor errors in the
    rarely used DH_anon and fixed DH ciphersuites which may prevent them from interoperating
    with compliant implementations including iSaSiLk 3.0 or later. This does not affect
    the RSA and DHE ciphers.
  • Stronghold server. A version selection problem may occur, see note below.
  •  IBM servers. Some versions also have problems with protocol version
    selection, see note below.

Protocol Version Selection Problems

Some servers do not recognize the SSL 3.0 and TLS 1.0 combined client hello format correctly (although they should).

In those cases it may be necessary to either disable TLS 1.0 or to enable

SSL 2.0 in addition (they seem to better cope with the different SSLv2 hello messages).
That means try
context.setAllowedProtocolVersions(SSLContext.VERSION_SSL30, SSLContext.VERSION_SSL30);

or possibly
context.setAllowedProtocolVersions(SSLContext.VERSION_SSL20, SSLContext.VERSION_TLS10);

 

Connection Closure and EOFExceptions

Unfortunately a number of servers, seemingly including most or all versions of the Microsoft IIS server, do not correctly shutdown
the SSL/TLS layer before closing the connection on the TCP level. This will cause EOFExceptions to be thrown and also 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 server implementations and not in iSaSiLk! Anyway, as a workaround we offer an SSLContext setting
that allows you to ignore this (i.e. no EOFException will be thrown and the session is cached as usually). To active this workaround
use code like
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
the
setCacheTerminatedSessions method if you want to enforce the
same behaviour for all protocol versions.

TLS Extensions

Extensions for the TLS protocol have been introduced by RFC 3546, 4366. iSaSiLk supports all standard extensions
specified by RFC 3546 (and additionally the
session_ticket extension defined in RFC 4507)
and has been successfully tested against the following extension supporting browsers :

  •  Microsoft Internet Explorer MSIE 7.0: when running on Vista operating
    system, MSIE sends the following standard extensions within the ClientHello
    message:
    server_name,
    status_request (type OCSP); MSIE
    correctly handles the extensions and the OCSP status response sent back
    by iSaSiLk
  •  Mozilla Firefox 2.0: if TLS is enabled only, Firefox sends the following
    standard extension within the ClientHello message:
    server_name;
    Firefox correctly handles the
    server_name extension sent back
    by iSaSiLk
  •  Opera 9.10: if TLS is enabled only, Opera sends the following standard
    extensions within the ClientHello message:
    server_name,status_request (type OCSP), however, there seems to be an OCSP
    encoding problem. Thus the usage of the
    status_request extension
    should be disabled when talking with Opera versions containing this
    issue. This problem has been fixed by newer versions of Opera (e.g. 9.62)

SessionTicket extension

The SessionTicket extension has been introduced by RFC 4507  (“TLS Session Resumption without Server-Side State”). However,  the SessionTicket encoding has been changed from RFC 4507 to its  successor draft RFC 4507bis which simply puts the ticket into the extension_data field since done so by most applications.  iSaSiLk 4.1 now also uses the 4507bis format when sending a SessionTicket  extension, but is able to parse both, the 4507 and 4507bis format.  According to RFC 4507bis iSaSiLk now also uses SHA-256 as hash algorithm
for HMAC-protecting the ticket instead of SHA-1 as has been used by RFC 4507.

RenegotiationInfo extension

The RenegotiationInfo extension has been introduced by RFC 5746 as countermeasure against renegotiation attacks. Depending on the deploymaent of RenegotiationInfo supporting TLS applications, interoperability problems may occur during a certain transition period. See here for further information about use and configuration options
of the RenegotiationInfo extension.

ECC Cipher Suites

The most recent versions of Mozilla Firefox and Microsoft Internet Explorer on Windows Vista both support elliptic curve cipher suites. Both browsers make use of the SupportedEllipticCurves and SupportedPointFormat extensions with named curves secp256r1, secp384r1 and secp521r1 and uncompressed point format, all supported and by default used by iSaSiLk.

This document describes how to use the iSaSiLk library to perform secure renegotiation.

The SSL/TLS Renegotiation vulnerability

In November 2009 Marsh Ray and Martin Rex independently discovered a serious vulnerability in the SSL/TLS renegotiation protocol which does not provide any cryptographic binding of the renegotiation handshake to the corresponding TLS channel. An attacker may exploit this vulnerability and establish a regular TLS connection with a server, exchange some data with it, and then splice in a connection with an innocent client who starts a new handshake with the server. The server, however, interprets this initial handshake as renegotiation and thinks that any data received so far has come from the client (and not from the attacker).

There may be variants of the attack possible where an initial handshake of the server is interpreted as renegotiation handshake by the client.

As a countermeasure against this attack (and its possible derivatives) the IETF TLS working group has developed a new TLS extension,
RenegotiationInfo (RFC 5746), to establish a cryptographic binding of the renegotiation handshake to the corresponding TLS channel. When successfully exchanging and verifying the
RenegotiationInfo extension, client and server know whether they perform an initial or renegotiating handshake and if they actually renegotiate the cryptographic parameters of the corresponding TLS connection.

For further information see http://extendedsubset.com/?p=8,
http://www.ietf.org/mail-archive/web/tls/current/msg03928.html , and RFC 5746.

The RenegotiationInfo extension

RFC 5746  defines the RenegotiationInfo extension as an opaque structure that may be empty (initial handshake) or (renegotiating handshake) may carry verification data for checking the cryptographic binding to the enclosing TLS connection:

struct {
opaque renegotiated_connection<0..255>;
} RenegotiationInfo;

On the beginning of an initial handshake the client sends a ClientHello message containing a RenegotiationInfo extension with an empty renegotiated_connection field. The server, when parsing the ClientHello message, knows that the client is able to perform secure renegotiation (because the ClientHello message contains the RenegotiationInfo extension) and that the ClientHello message belongs to an initial handshake (because the renegotiated_connection field of the RenegotiationInfo extension is empty). The server now also includes an RenegotiationInfo extension with an empty
renegotiated_connection field into its ServerHello message to let the client know that it also is able to perform secure renegotiation.

Later, when client or server decide to perform a renegotiation, they exchange ClientHello and ServerHello messages containing RenegotiationInfo extensions with a non-empty renegotiated_connection field that carries verification data from the Finished messages of the immediately previous handshake. Successfully verification of this data ensures that the renegotiation corresponds to the enclosing TLS connection and the handshake can be securely continued. Otherwise, if the verification fails, the renegotiation handshake may be under attack and has to be aborted immediately by sending a fatal handshake failure alert.

A TLS handshake may be also aborted by any of the following reasons:

  • Initial handshake: The client sends a
    RenegotiationInfo extension with an
    empty
    renegotiated_connection field, but the server does not respondwith a RenegotiationInfo  extension. The client now knows that the server
    does not support secure renegotiation and may prefer to abort the handshake
    with a fatal handshake failure alert because it may be already under attack.
  • Initial handshake: If the client does not send a
    RenegotiationInfo extension, the server knows that the client does not support secure renegotiation and may abort the handshake with a fatal handshake failure alert or may continue it to later deny any renegotiation request of the client by sending a
    no_renegotiation alert message.
  • Initial handshake or renegotiating handshake: Any incorrect usage of the
    RenegotiationInfo extension (non-empty renegotiated_connection field at an initial handshake, empty renegotiated_connection field at a renegotiating handshake)
    immediately causes a fatal handshake failure alert.
  • Renegotiating handshake: When both client and server have announced to be able to support secure renegotiation (by exchanging RenegotiationInfo extensions within the initial handshake), but any party does not send the RenegotiationInfo extension within the renegotiating handshake, the renegotiation has to be aborted with fatal handshake failure alert.

For interoperability with SSLv3- and TLS-Servers that do not support extensions yet, RFC 5746 provides an alternative way for the client to signal its ability to perform secure renegotiation. Instead of including an empty RenegotiationInfo extension into the
ClientHello message of an initial handshake, the client may add the special signalling cipher suite value (SCSV) “TLS_EMPTY_RENEGOTIATION_INFO_SCSV” withID {0x00, 0xFF} to the list of its cipher suites. When parsing this special cipher suite value, the server knows that the client supports the
RenegotiationInfoextension and safely can include it into its
ServerHello message to tell the client that it is also able to perform secure renegotiation. The SCSV cipher suite has no other meaning or purpose than announcing the ability to perform secure renegotiation. It can only be sent within an initial handshake and is simply ignored by (and does not break) servers that do not support TLS extension.

iSaSiLk and the RenegotiationInfo extension

By default iSaSiLk uses the RenegotiationInfo extension as described above. At the beginning of a handshake an iSaSiLk client announces its ability for secure renegotiation by either sending an empty RenegotiationInfo extension or including the special SCSV cipher suite value into its cipher suite list. The RenegotiationInfo extension is only sent if the client application has
configured iSaSiLk to use any further extensions (like, for instance,
ServerName). If the client application does not want to use extensions, iSaSiLk does not send the

RenegotiationInfo extension, but includes the SCSV cipher suite value. This ensures that the server will not break if it does not support extensions. However, if the server does not respond with a RenegotiationInfo extension, the client cannot know if an attacker already has launched a renegotiation attack and therefore iSaSiLk will abort the handshake immediately by sending a fatal
handshake failure alert to the server. In the same way, an iSaSiLk server by default will immediately abort an initial handshake with a fatal handshake failure alert if the ClientHello message neither contains the RenegotiationInfo  extension nor the SCSV cipher suite value. Both, iSaSiLk clients and iSaSiLk servers will not continue an (initial or renegotiating) handshake if they notice that the peer does not use the RenegotiationInfo extension correctly (for instance non-empty extension at initial handshake, empty extension at renegotiating handshake) or that the RenegotiationInfo extension of a renegotiating handshake contains an invalid or wrong
renegotiated_connection value. In all these situations the handshake will be aborted immediately by sending a fatal handshake failure alert.

All
RenegotiationInfo extension and the SCSV cipher suite value handling is done transparently to the user. iSaSiLk manages the RenegotiationInfo extension as “hidden” extension. It must not be set by the application and cannot be accessed by the application. All required secure renegotiation processing is done automatically. You only will recognize something about it if you turn on and watch
the debug output or if you get an exception because the handshake fails because of missing or incorrect use of the RenegotiationInfo extension.

A typical initial and renegotiation client-server handshake course may look like:

Client:

Starting handshake...
ssl_debug(1): Starting handshake (iSaSiLk 4.4)...
ssl_debug(1): Sending v3 client_hello message to localhost:443, requesting version 3.2...
ssl_debug(1): Received v3 server_hello handshake message.
ssl_debug(1): Server selected SSL version 3.2.
ssl_debug(1): Server created new session 4A:B7:09:06:F3:35:BA:5E...
ssl_debug(1): CipherSuite selected by server: SSL_RSA_WITH_3DES_EDE_CBC_SHA
ssl_debug(1): CompressionMethod selected by server: NULL
ssl_debug(1): TLS extensions sent by the server: renegotiation_info (65281)
ssl_debug(1): Server supports secure renegotiation.
ssl_debug(1): Received certificate handshake message with server certificate.
ssl_debug(1): Server sent a 1024 bit RSA certificate, chain has 3 elements.
ssl_debug(1): Received server_hello_done handshake message.
ssl_debug(1): Sending client_key_exchange handshake...
ssl_debug(1): Sending change_cipher_spec message...
ssl_debug(1): Sending finished message...
ssl_debug(1): Received change_cipher_spec message.
ssl_debug(1): Received finished message.
ssl_debug(1): Session added to session cache.
ssl_debug(1): Handshake completed, statistics:
ssl_debug(1): Read 2538 bytes in 3 records, wrote 254 bytes in 4 records.
ssl_debug(1): Acquiring locks for renegotiation...
ssl_debug(1): Starting renegotiation...
ssl_debug(1): Sending v3 client_hello message to localhost:443, requesting version 3.2...
ssl_debug(1): Sending extensions: renegotiation_info (65281)
ssl_debug(1): Received v3 server_hello handshake message.
ssl_debug(1): Server selected SSL version 3.2.
ssl_debug(1): Server created new session FD:15:DD:D5:11:1E:6A:B6...
ssl_debug(1): CipherSuite selected by server: SSL_RSA_WITH_3DES_EDE_CBC_SHA
ssl_debug(1): CompressionMethod selected by server: NULL
ssl_debug(1): TLS extensions sent by the server: renegotiation_info (65281)
ssl_debug(1): Received certificate handshake message with server certificate.
ssl_debug(1): Server sent a 1024 bit RSA certificate, chain has 3 elements.
ssl_debug(1): Received server_hello_done handshake message.
ssl_debug(1): Sending client_key_exchange handshake...
ssl_debug(1): Sending change_cipher_spec message...
ssl_debug(1): Sending finished message...
ssl_debug(1): Received change_cipher_spec message.
ssl_debug(1): Received finished message.
ssl_debug(1): Session added to session cache.
ssl_debug(1): Renegotiation completed, statistics:
ssl_debug(1): Read 2623 bytes in 3 records, wrote 372 bytes in 4 records.
ssl_debug(1): Shutting down SSL layer...
ssl_debug(1): Sending alert: Alert Warning: close notify
ssl_debug(1): Read 501 bytes in 1 records, 466 bytes net, 466 average.
ssl_debug(1): Wrote 53 bytes in 1 records, 18 bytes net, 18 average.
ssl_debug(1): Closing transport...

Server:

ssl_debug(1): Starting handshake (iSaSiLk 4.4)...
ssl_debug(1): Received v3 client_hello handshake message from localhost/127.0.0.1.
ssl_debug(1): Client supports secure renegotiation.
ssl_debug(1): Client requested SSL version 3.2, selecting version 3.2.
ssl_debug(1): Creating new session 4A:B7:09:06:F3:35:BA:5E...
ssl_debug(1): CipherSuites supported by the client:
ssl_debug(1): SSL_RSA_WITH_3DES_EDE_CBC_SHA
ssl_debug(1): SSL_RSA_WITH_IDEA_CBC_SHA
ssl_debug(1): SSL_RSA_WITH_RC4_128_SHA
ssl_debug(1): CompressionMethods supported by the client:
ssl_debug(1): NULL
ssl_debug(1): Sending server_hello handshake message.
ssl_debug(1): Selecting CipherSuite: SSL_RSA_WITH_3DES_EDE_CBC_SHA
ssl_debug(1): Selecting CompressionMethod: NULL
ssl_debug(1): Selecting extensions: renegotiation_info (65281)
ssl_debug(1): Sending certificate handshake message with 1024 bit RSA server certificate...
ssl_debug(1): Sending server_hello_done handshake message...
ssl_debug(1): Received client_key_exchange handshake message.
ssl_debug(1): Received change_cipher_spec message.
ssl_debug(1): Received finished message.
ssl_debug(1): Sending change_cipher_spec message...
ssl_debug(1): Sending finished message...
ssl_debug(1): Session added to session cache.
ssl_debug(1): Handshake completed, statistics:
ssl_debug(1): Read 254 bytes in 4 records, wrote 2538 bytes in 3 records.
ssl_debug(1): Acquiring locks for renegotiation...
ssl_debug(1): Starting renegotiation...
ssl_debug(1): Received v3 client_hello handshake message from localhost/127.0.0.1.
ssl_debug(1): Client requested SSL version 3.2, selecting version 3.2.
ssl_debug(1): Creating new session FD:15:DD:D5:11:1E:6A:B6...
ssl_debug(1): CipherSuites supported by the client:
ssl_debug(1): SSL_RSA_WITH_3DES_EDE_CBC_SHA
ssl_debug(1): SSL_RSA_WITH_IDEA_CBC_SHA
ssl_debug(1): SSL_RSA_WITH_RC4_128_SHA
ssl_debug(1): CompressionMethods supported by the client:
ssl_debug(1): NULL
ssl_debug(1): TLS extensions sent by the client: renegotiation_info (65281)
ssl_debug(1): Sending server_hello handshake message.
ssl_debug(1): Selecting CipherSuite: SSL_RSA_WITH_3DES_EDE_CBC_SHA
ssl_debug(1): Selecting CompressionMethod: NULL
ssl_debug(1): Selecting extensions: renegotiation_info (65281)
ssl_debug(1): Sending certificate handshake message with 1024 bit RSA server certificate...
ssl_debug(1): Sending server_hello_done handshake message...
ssl_debug(1): Received client_key_exchange handshake message.
ssl_debug(1): Received change_cipher_spec message.
ssl_debug(1): Received finished message.
ssl_debug(1): Sending change_cipher_spec message...
ssl_debug(1): Sending finished message...
ssl_debug(1): Session added to session cache.
ssl_debug(1): Renegotiation completed, statistics:
ssl_debug(1): Read 372 bytes in 4 records, wrote 2623 bytes in 3 records.
ssl_debug(1): Shutting down SSL layer...
ssl_debug(1): Sending alert: Alert Warning: close notify
ssl_debug(1): Read 53 bytes in 1 records, 18 bytes net, 18 average.
ssl_debug(1): Wrote 501 bytes in 1 records, 466 bytes net, 466 average.
ssl_debug(1): Closing transport...

Configuration Options

As discussed above, a TLS client – for being sure to be not vulnerable to renegotiation
attacks – has to abort a handshake with a fatal handshake failure alert if a server does
not send the RenegotiationInfo extension within its initial
ServerHello  message. In the same way, a TLS server has to abort an initial handshake with a fatal handshake failure alert if the ClientHello message neither contains the
RenegotiationInfo
extension nor the SCSV cipher suite value.

This means that by default no SSL/TLS communication is possible if the peer does not support secure
renegotiation. Although this is the recommended behaviour from the security point of view, it might
cause interoperability problems with servers/clients that do not support the
RenegotiationInfo extension yet. Since deployment of patched TLS implementations cannot start before the final release of RFC 5746, it will take a certain transition period until the majority of available TLS applications will be able to understand the secure renegotiation protocol. Especially
during this transmission period there may be a certain (for instance, economic) requirement for being still able to talk with unpatched TLS client or servers.

This section describes the configuration options allowing an application to control the
renegotiation handling of the iSaSiLk library. Each option can be dynamically set (or unset)
by calling a particular method of the SSLContext class, or can be statically configured by editing a SSLContext.properties file and packing it with iaik_ssl.jar file (or putting it elsewhere in the classpath). Any static configuration via SSLContext.properties file is globally valid for the entire application scope. Dynamical configuration settings are only valid for the particular SSLContext to which they have been applied. The SSLContext.properties file has to be located in the package iaik.security.ssl. A sample property and iSaSiLk jar file allowing to communicate with unpatched TLS applications is contained in the lib/legacy-renegotiation folder of your iSaSiLk distribution.

  • Allow legacy renegotiation: An iSaSiLk client or server that allows legacy  renegotiation will be able to talk (and renegotiate) with unpatched TLS applications  that do not support the RenegotiationInfo extension yet. 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.   Configuration via
    SSLContext method.            sslContext.setAllowLegacyRenegotiation(true);
    Configuration via
    SSLContext.properties file:            allowLegacyRenegotiation=true
    Default value:
    false
  • Use of no_renegotiation warnings: A
    no_renegotiation
    warning maybe sent if a renegotiation request (
    ClientHello message from the client;HelloRequest message from the server, respectively) from the peer is refused by
    the local TLS server/client. The local TLS server/client does not abort the current TLS session,  it only tells the peer that it will not go into a renegotiation handshake. It then is the  decision of the peer if it wants to continue the current session or if it prefers to close
    the session because the renegotiation request has been refused.  By default iSaSiLk does not use no_renegotiation warnings. Rather the handshake is  aborted by sending a fatal handshake failure alert if it gets a renegotiation request  you cannot be fulfilled. You may configure your SSLContext to not send a fatal  handshake failure alert, but continue and send a  no_renegotiation warning in response  to an unsupported renegotiation request. In this case an iSaSiLk server will  not abort an initial handshake if it receives a
    ClientHello that  does not contain the SCSV cipher suite value or
    RenegotiationInfo  extension. It will continue and then send a
    no_renegotiation warning if  it receives a renegotiating
    ClientHello. Please note that this behaviour may  make your server vulnerable to attacks where only the client notices that a renegotiation  takes place.    Note also, that
    no_renegotiation warnings are only  defined for TLS, not for SSLv3; SSLv3 in any case will abort the handshake  with a fatal handshake failure alert when refusing a renegotiation request of the  peer.
    Configuration via
    SSLContext method:            sslContext.setUseNoRenegotiationWarnings(true) ;
    Configuration via
    SSLContext.properties file:            useNoRenegotiationWarnings=true
    Default value:
    false
  • Allow identity change during renegotiation: If 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.
    Configuration via SSLContext method:            sslContext.setAllowIdentityChangeDuringRenegotiation(false);
    Configuration via
    SSLContext.properties file:            allowIdentityChangeDuringRenegotiation=false
    Default value:
    true
  • Disable renegotiation: Use this flag if you want to disable renegotiation at all.  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.   Configuration via
    SSLContext method:            sslContext.setDisableRenegotiation(true);
    Configuration via
    SSLContext.properties file:            disableRenegotiation=true
    Default value:
    false

SecurityProvider

A more finely granulated configuration option is provided by the iSaSiLk SecurityProvider method continueIfPeerDoesNotSupportSecureRenegotiation. iSaSiLk calls this method during an (initial or renegotiation) handshake to check if legacy renegotiation is allowed or not when the peer does not support secure renegotiation according to RFC 5746.

By default this method will check the SSLContext configuration (as described
above) and throw an SSLException if legacy renegotiation is not allowed. This means
that — if the default configuration is used — at the client side an intial handshake
with a server that does not send the RenegotiationInfo extension will be aborted immediately with a fatal handshake failure alert. On the server side an initial handshake will also be aborted immediately if the client does not send the RenegotiationInfo extension or SCSV cipher
suite value.

You may override the SecurityProvider method continueIfPeerDoesNotSupportSecureRenegotiation if you do not want to use the default behaviour/configuration or, for instance, want to decide on case-by-case basis whether to continue or not. For instance, a client application may pop-up a warning dialag to inform the user that the server has not send the
RenegotiationInfoextension (may be only appropriate for expierenced users), or may maintain a
white list with server names for which legacy renegotiation is allowed, e.g.:


/**
* Simple demo SecurityProvider implementation for a client}
* that generally enforces secure renegotiation according
* RFC 5746 but allows legacy renegotiation with some
* specific, explcitily listed sites.
*/
public class RISecurityProvider extends IaikProvider {

/**
* Repository of sites to which legacy renegotiation
* shall be allowed.
*/
Hashtable legacyRenegotiationSites_;
/**
* Default constructor.
*/
public RISecurityProvider() {
super();
legacyRenegotiationSites_ = new Hashtable();
}

/**
* Adds a site (server) name with which legacy
* renegotiation shall be allowed.
*
* @param severName the site (server) name
*/
public void addSite(String serverName) {
if (serverName != null) {
legacyRenegotiationSites_.put(serverName, serverName);
}
}

/**
* Removes a site (server) name with which legacy
* renegotiation shall be not allowed.
*
* @param severName the site (server) name
*/
public void removeSite(String serverName) {
if (serverName != null) {
legacyRenegotiationSites_.remove(serverName);
}
}

/**
* Throws a SSLException if a server that does not support
* secure renegotiation (or tries a legacy renegotiation),
* but the server name is not contained in the list of sites
* with which legacy renegotiation is allowed.
*
*
* @param transport the SSLTransport to maybe used for getting
*                  information about the remote peer
* @param renegotiation whether this method is called during an
*                      initial or during a renegotiation handshake
*
* @exception SSLException if a server that does not support secure
*                         renegotiation (or tries a legacy renegotiation),
*                         but is not contained in the list of sites with
*                         which legacy renegotiation is allowed
*/
public void continueIfPeerDoesNotSupportSecureRenegotiation(SSLTransport transport,
boolean renegotiation)
throws SSLException {

String serverName = transport.getRemotePeerName();
if ((serverName != null) && (legacyRenegotiationSites_.get(serverName) != null)) {
transport.debug(“Server ” + serverName + ” did not send RenegotiationInfo extension. Continue anyway.”);
} else {
throw new SSLException(“Server did not send RenegotiationInfo extension.”);
}

}
}

For a more detailed description of the several configuraton options see the Javadoc documentation of the SSLContext class. Please note that full protection can only be achieved when not allowing any communication with clients/servers that do not support the
RenegotiationInfo extension. For that reason the default configuration of iSaSiLk does not allow to communicate with unpatched peers that are not able to perform secure renegotiation.

You want to know what SSL/TLS-capabilites you browser has? Want to find out about the SSL/TLS-features of some Web-Server? We provide two demos, that do that job for you!

The demos are included in our IAIK iSaSiLk Toolkit, one for testing the SSL/TLS capcabilities of your browser, the other for testing the capabilities of your server. Both demos can be run as servlets or as stand alone applications.

After downloading and unpacking the iSaSiLk distribution file you simply have to browse to the
demo/cmd or
demo/sh sub-directory and follow the steps described below.

Browser Test:

  • Go to the
    sslclientinfo sub-directory and start the
    runSSLClientInfo.bat/sh file. When the demo is running it informs you that is ready for inputs on port 4433:

Waiting for HTTPS requests on port 4433…

If everything works well the SSL/TLS browser capabilities will be dumped in your browser window.

Server Test:

  • Go to the
    sslserverinfo sub-directory
     and start the
    runSSLServerInfo.bat/sh file. When the demo is running it informs you that is ready for inputs on port 80:

Waiting for HTTP requests on port 80…

A form field will be shown in your browser window where you can enter the https address of the server for which you want to know its SSL/TLS capabilities.

IAIK-SSL 6.0 – 1. July 2020
Class or Package Bug / Change / New Feature Description and Examples
NF

Implementation of the TLS 1.3 protocol according to RFC 8446 added. All core and some optional features of the protocol are implemented. Some optional features like Zero Round-Trip 0-RTT Early Data are yet not supported.

CipherSuite C

Changed state of 3DES-EDE and RC4 cipher suites from default to implemented.

ExtensionList NF, C

New method setDefaultCriticalValue allowing to set the default critical value of (some) TLS extensions.

ServerNameList C

For interoperability reasons a client-side critical ServerNameList extension does not cause the handshake to be aborted anymore.

SignatureAlgorithms C

Now marked as critical by default meaning that the handshake is aborted if the peer uses a signature algorithm that has not been suggested.

SignatureAndHashAlgorithmList, SignatureSchemeList C

Removed DSA signature algorithms from the default set. Added ED25519 in default set. Moved ED25519 to second position in all algorithms set.

SSLServerContext C

Default domestic DH parameters set to ffdhe2048 from RFC 7919.

IAIK-SSL 6.0 Beta 1 – 23. December 2019
Class or Package Bug / Change / New Feature Description and Examples
* NF

Implementation of the TLS 1.3 protocol according to RFC 8446 added. All core and some optional features of the protocol are implemented. Some optional features like Zero Round-Trip 0-RTT Early Data are yet not supported.

IAIK-SSL 6.0 Alpha 3 – 21. October 2019
Class or Package Bug / Change / New Feature Description and Examples
* NF
Implementation of the TLS 1.3 protocol according to RFC 8446 added. All core and some optional features of the protocol are implemented. Some optional features like Post-Handshake Client Authentication or Zero Round-Trip 0-RTT Early Data are yet not supported.
IAIK-SSL 6.0 Alpha 2 – 23. September 2019
Class or Package Bug / Change / New Feature Description and Examples
* NF

Implementation of the TLS 1.3 protocol according to RFC 8446 added. All core and some optional features of the protocol are implemented. Some optional features like Post-Handshake Client Authentication or Zero Round-Trip 0-RTT Early Data are yet not supported.

IAIK-SSL 6.0 Alpha 1 – 30. August 2019
Class or Package Bug / Change / New Feature Description and Examples
* NF

Implementation of the TLS 1.3 protocol according to RFC 8446 added. All core and some optional features of the protocol are implemented. Some optional features like Post-Handshake Client Authentication, CCM cipher suites or Zero Round-Trip 0-RTT Early Data are yet not supported.

IAIK-SSL 5.2 – 20. August 2018
Class or Package Bug / Change / New Feature Description and Examples
* NF

Support for x25519 and x448 ECDHE key exchange, and Ed25519 and Ed448 EdDSA signatures (RFC 8422; experimental).

* NF

Support for RSA-PSS signature algorithm for client/server authentication.

iaik.security.ssl.ClientHandshaker C

Tries to better recognize the curve preference order when selecting the client credentials to be used.

iaik.security.ssl.ChainVerifier C

Check EC server/client keys for compliance with SupportedEllipticCurves/SupportedPointFormats extension.

iaik.security.ssl.CipherSuite C

Disabled the following cipher suites according to RFC 8422:
TLS_ECDH_ECDSA_WITH_NULL_SHA,
TLS_ECDH_ECDSA_WITH_RC4_128_SHA,
TLS_ECDH_ECDSA_WITH_3DES_EDE_CBC_SHA,
TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA,
TLS_ECDH_ECDSA_WITH_AES_256_CBC_SHA,
TLS_ECDH_RSA_WITH_NULL_SHA,
TLS_ECDH_RSA_WITH_RC4_128_SHA,
TLS_ECDH_RSA_WITH_3DES_EDE_CBC_SHA,
TLS_ECDH_RSA_WITH_AES_128_CBC_SHA,
TLS_ECDH_RSA_WITH_AES_256_CBC_SHA

Further/all ECDH_RSA/ECDH_ECDSA cipher suites may be disabled in next iSaSiLk version.

iaik.security.ssl.SSLContext, iaik.security.ssl.SSLServerContext C

updateCipherSuites now also ensures that the enabled SignatureAlgorithms are
supported by the installed SecurityProvider.

iaik.security.ssl.SSLServerContext C

getServerCredentials now also looks at the SignatureAlgorithms extension for selecting the server credentials.

iaik.security.ssl.ServerHandshaker B

Fixed possible NullpointerException in ExtendedMasterSecret check.

iaik.security.ssl.SupportedEllipticCurves C

Constructor SupportedEllipticCurves(NamedCurve[] ellipticCurveList) does not allow to use specify explicit curves anymore (explicit curves are deprecated by RFC 8422)

iaik.security.ssl.chb.* NF

Support for tls-unique and tls-server-end-point channel bindings added (RFC 5929).

IAIK-SSL 5.107 – 22. November 2017
Class or Package Bug / Change / New Feature Description and Examples
iaik.security.ssl.ALPNProtocolNameList, iaik.security.ssl.ALPNProtocolName NF

Support for application_layer_protocol_negotiation(ALPN) extension added (RFC 7301).

iaik.security.ssl.ClientRSAKeyExchange C

Improved counter measure against variants of the PKCS#1 attack (Bleichenbacher).

IAIK-SSL 5.106 – 18. September 2017
Class or Package Bug / Change / New Feature Description and Examples
iaik.security.ssl.ClientHandShaker, iaik.security.ssl.SSLClientContext, iaik.security.ssl.SSLTransport, iaik.security.ssl.SSLSocketTransport C

Changed peer host name management to avoid (reverse) DNS lookups where possible.

iaik.security.ssl.IaikProvider, iaik.security.ssl.SecurityProvider C

Constructors added allowing to use iSaSiLk without the necessity to
install the JCA Provider within the JCA Security framework.

iaik.security.ssl.SSLContext, iaik.security.ssl.CipherSuite B

SSLContext.updateCipherSuites() now also ensures that no AEAD ECC cipher suites are offered if TLS 1.2 is not enabled.

iaik.security.ssl.* C

Changed System property calls to use System.getProperty() to avoid NPE
problems on Android Systems.

IAIK-JSSE Provider NF

KeyManager and KeyManagerFactory for pre-shared keys added to provide support for PSK cipher suites

IAIK-SSL 5.105 – 1. February 2017
Class or Package Bug / Change / New Feature Description and Examples
demo.DemoUtil C

getEccSecurityProvider(): explicitly set point encoding to “uncompressed” for ECCelerate (since ECCelerate has changed default point encoding to “compressed” with version 3.0)

iaik.security.ssl.SignatureAlgorithms, iaik.security.ssl..SignatureAndHashAlgorithmList C

Changed default signature algorithms list to also contain SHA384withRSA, SHA384withECDSA, SHA384withDSA.

iaik.security.ssl.SSLContext B

Fixed ids for ECC certificate types CERTTYPE_ECDSA_SIGN, CERTTYPE_RSA_FIXED_ECDH and CERTTYPE_ECDSA_FIXED_ECDH.

iaik.security.ssl.SupportedEllipticCurves B

Fixed oid for curve sect409r1 (1.3.132.0.37).

iaik.security.ssl.SupportedEllipticCurves B

Fixed static method getRegisteredCurveByOID (returnednull anytime).

iaik.security.ssl.SupportedEllipticCurves B

Added static method getRegisteredCurveByID.

iaik.security.ssl.SupportedEllipticCurves NF, C

It is now also possible to specify a curve list on the server side to be merged with the curve list sent by the client. This allows the server to enforce the usage of specific curves only.
The curves may be negotiated in client preference (default) or server preference order. A server-side SupportedEllipticCurves extension maybe set to critical to not negotiate ECC suites if the explicitly configured server curve list has no common curve with the curve list sent by the client.

iaik.protocol.https.Handler, org.w3c.www.protocol.http.Handler NF, B

Method openConnection(URL u, Proxy p) now also handles direct connections ( Proxy.NO_PROXY).

w3c_http B

Fixed possible NullPointerException in HttpManager property copying.

IAIK-SSL 5.104 – 18. April 2016
Class or Package Bug / Change / New Feature Description and Examples
iaik.security.ssl.ExtendedMasterSecret NF

Support for the extended master secret extension as specified in RFC 7627 to calculate the master secret in a way that cryptographically binds it to important session parameters.

iaik.security.ssl.ChainVerifier C

Method verifyServer: if checkServerName is true and theserver_name extension has been negotiated the server certificate name is checked against the server names of the server_nameextension, regardless if server_name extension has been specified as critical or not

iaik.security.ssl.IaikProvider C

Method getTLSServerName(X509Certificate cert) also checks the SubjectAltName extension for GeneralName elements of type iPAddress.
Method getTLSServerName(int nameType, X509Certificate serverCert) is now implemented to not check for iPAddress if the given ServerName nameType is HOST_NAME

iaik.security.ssl.SecurityProvider C

Method isImplemented() now calls method aeadEncrypt() for GCM Ciphers to check enable AEAD CipherSuites only if they are supported by the enabled JCA provider(s) and if methodaeadEncrypt() is implemented.

iaik.security.ssl.ServerName C

Constructor now throws an IllegalArgumentException if a ServerName of type HOST_NAME shall be created for an ipAddress. If theserver_name extension shall be automatically created (by using the default constructor) no server_name extension is sent if the server name is specified as ipAddress when creating the SSLSocket.

iaik.security.ssl.SSLContext NF

New methods setAllowedProtocolVersions(String minVersion, String maxVersion) andgetAllowedProtocolVersionNames() allowing to set/get the allowed protocol version as Strings.

iaik.security.ssl.SSLContext NF

New static methods getAllSupportedProtocolVersions() andgetAllSupportedProtocolVersionNames() returning all SSL/TLS protocol
versions supported by iSaSiLk (except for SSL20 which is not included in the list but client-side supported).

iaik.security.ssl.SSLServerContext NF

New method setSendEmptySessionID to decide whether the server shall create and send an empty session id if no SessionManager is set. By default a non-empty session is created when no SessionManager is set, too. An empty session id may be used to tell the client that the session will no be cached and therefore cannot be resumed.

iaik.security.ssl.SSLSocketTransport C

Method engineGetRemotePeerName returns remoteHost_ if it is not null (also when no proxy is set)

w3c_http NF, C

HttpURLConnection implements methodgetRequestProperties(), allows to specify a zero (0) content length for method setFixedLengthStreamingMode(0), allows to use an empty content-type header, and throws an exception if output streaming
shall be used without having called con.setDoOutput(true). Flushing of output stream between header- and body emit is done
again to avoid timeout problems in some environments. FixedgetRead/connetTimeout()).  Fixed HttpManager properties management.

IAIK-SSL 5.103 – 20. January 2016
Class or Package Bug / Change / New Feature Description and Examples
iaik.security.ssl.SignatureAndHashAlgorithmList, iaik.security.ssl.SignatureAlgorithms C

Added SHA512withRSA, SHA512withECDSA, SHA512withDSA to default algorithm list.

iaik.security.ssl.SupportedEllipticCurves C

Default constructor again does not check (does NOT throw an IllegalArgumentException) if default curves are not supported (to avoid elliptic_curves extension parsing problems in non ECC supporting environments).

iaik.security.ssl.SupportedPointFormats C

Default constructor again does not check (does NOT throw an IllegalArgumentException) if the default point format is not supported (to avoid ec_point_formats extension parsing problems in non ECC supporting environments).

IAIK-SSL 5.102 – 23. December 2015
Class or Package Bug / Change / New Feature Description and Examples
iaik.security.ssl.ChainVerifier NF

(Extended)KeyUsage check moved to ChainVerifier.

iaik.security.ssl.ChainVerifier C

ServerNameList – certificate server check also recognize wildcards in server
certificates.

iaik.security.ssl.CipherSuite C

Tighter check if EC is supported by the installed SecurityProvider to ensure that ECDH(E) suites are not enabled if ECDH is supported by a JCA provider but
no SecurityProvider implementation is available for it.

iaik.security.ssl.ClientHandshaker C

Turned of OpenSSL 0.9.4 compatibility workaround (needed max version as record
version if SSL 3.0 was enabled).

iaik.security.ssl.IaikEccProvider C

decodeECPublicKey: ensure to check that the EC point actually lies on the curve as countermeasure against Practical Invalid Curve Attacks on TLS-ECDH; only applies to the old IAIK_ECC library; the new ECC library ECCelerate includes this check by default

iaik.security.ssl.MaxFragmentLength B

Fixed length – length id conversion.

iaik.security.ssl.SecurityProvider NF

Method checkCreatedRSAServerKeyExchangeSignature added to decide whether to verify an RSA-CRT key ServerKeyExchange signature immediately after signature creation as countermesaure against RSA-CRT key leaks.

iaik.security.ssl.ServerKeyExchange C

If IAIK provider <= 5.25 is used verify signature when calculated with RSA-CRT key immediately after signature creation as countermesaure against
RSA-CRT key leaks.

iaik.security.ssl.SSLContext NF

Extensions can be set and (when applicable) configured via properties file.

iaik.security.ssl.SSLContext, iaik.security.ssl.SSLServerContext C

Method updateCipherSuites allows SignatureAlgorithms extension with empty algorithm list for TLS 1.2 if only anonymous suites are enabled.

iaik.security.ssl.SSLClientContext C

Method addClientCredentials(KeyStore keyStore) now does throw an exception if a KeyStore entry cannot be added; rather the entry is skipped. If debugStream is enabled, debug info is dumped during adding client credentials; methodaddClientCredentials(KeyAndCert) also checks the ExtendedKeyUsage extension
and certificate type

iaik.security.ssl.SSLServerContext C

Method addServerCredentials(KeyStore keyStore) now does throw an exception if a KeyStore entry cannot be added; rather the entry is skipped. If debugStream is enabled, debug info is dumped during adding server credentials; methodaddServerCredentials(KeyAndCert) also checks the ExtendedKeyUsage extension

iaik.security.ssl.ServerNameList C

By default now ServerNameLists with more than one server name of same type are rejected according RFC 6066. MethodsetAllowMoreThanOneServerNamesOfSameTypecode>
added allowing to decide if more than one server name of the same type shall be allowed (since it was allowed by RFC 4366).

iaik.security.ssl.SupportedEllipticCurves C

Default constructor now throws an IllegalArgumentException if default curves are
not supported.

iaik.security.ssl.SupportedPointFormats C

Default constructor now throws an IllegalArgumentException if default point format is
not supported.

IAIK-SSL 5.101 – 23. August 2015
Class or Package Bug / Change / New Feature Description and Examples
iaik.security.ssl.CipherSuite C

Changed state of ECDH cipher suites from default to implemented.

iaik.security.ssl.SecurityProvider NF

Method checkExtendedKeyUsage added.

iaik.security.ssl.SSLClientHandshaker, iaik.security.ssl.SSLServerHandshaker C

Tighter peer certificate key usage / extended key usage check.

IAIK-SSL 5.1 – 20. July 2015
Class or Package Bug / Change / New Feature Description and Examples
demo.sslserverinfo.SSLServerInfo B

Fixed check for TLS 1.1 support.

iaik.security.ssl.CipherSuite C

Changed state of DH(E) cipher suites from default to implemented.

iaik.security.ssl.SecurityProvider NF

Method checkKeyLength added to check the key length of peer certificates and server RSA/DH(E)/ECDH(E) key exchange messages. By default peer certificates and server key exchange messages are rejected for RSA, DSA, DH keys < 1024 bit and EC keys < 192 bit. The method can be overridden to enforce other key size constraints. The key size check can also be controlled by the “disabledAlgorithms” property in the SSLContext.properties file following the same syntax as used by
the JDK java.security file.

iaik.security.ssl.SessionID C

Changed default SessionID length to 32 (bytes).

iaik.security.ssl.SSLServerContext NF

New method setTemporaryParameterScheduling to optionally enable periodic generation of temporary domestic DH parameters.

iaik.security.ssl.TicketKeysManager, iaik.security.ssl.DefaultTicketKeysManager, NF

New class that manages the server cipher and mac keys for session ticket protection. Allowing an application to plug in its own TicketKeysManager implementation.

iaik.protocol.https.Handler, org.w3c.www.protocol.http.Handler NF

Added support for JDK 1.5 method openConnection(URL u, Proxy p).

w3c_http C

Removed flushing of output stream between header- and body emit.

IAIK-SSL 5.0 – 3. November 2014
Class or Package Bug / Change / New Feature Description and Examples
* NF

TLS 1.2 support according to RFC 5246.

* NF

Support for AES Galois Counter Mode (GCM) Cipher Suites for TLS according to RFC 5288.

* NF

Support for TLS Elliptic Curve Cipher Suites with SHA-256/384 and AES Galois Counter Mode (GCM) according to RFC 5289.

* NF

Support for Pre-Shared Key Cipher Suites for TLS with SHA-256/384 and AES Galois Counter Mode according to RFC 5487.

* NF

Support for ECDHE_PSK Cipher Suites for TLS according to RFC 5489.

* NF

Support for Camellia Cipher Suites with SHA-256/384 and AES Galois Counter Mode (GCM), including PSK suites,
according to RFC 5932/6367.

CipherSuite NF

TLS 1.2 cipher suites added.

CipherSuite C

Method isAvaiable first checks if the suite is allowed for
the enabled protocol versions.

CipherSuite, ServerHandshaker NF

Implementation of the TLS_FALLBACK_SCSV Signaling Cipher Suite Value according to draft-bmoeller-tls-downgrade-scsv-00 as countermeasure against protocol downgrade attacks on the Transport Layer Security (TLS) protocol trying to enforce a fall back to SSL 3.0, which is vulnerable to a padding-oracle attack if CBC is used (“POODLE” — Padding Oracle On Downgraded Legacy Encryption attack).

SSLContext C

Default protocol version interval changed to TLS 1.0 – TLS 1.2.

SSLContext C

Method updateCipherSuites now throws a NullPointerException if no suites cannot be enabled.

SSLServerContext C

Use 2048-bit MODP Group by default for domestic DHE parameters (if not got from certificate).

w3c_http.jar B, C

Tries to prevent “Socket already closed” exceptions if neither chunked encoding has been used nor the server has sent a Content-Length header.

IAIK-SSL 4.6 – 17. March 2014
Class or Package Bug / Change / New Feature Description and Examples
CipherSuite C

Removed exportable cipher suites from the default cipher suite set.

CipherSuite, KeyExchange... NF

Added support for TLS 1.0, TLS 1.1 ECDHE_PSK cipher suites according to RFC 5489.

CipherSuite, CipherSuiteList NF, C

CipherSuite now implements the Comparable interface; refactored sorting algorithm.

ClientHandshaker C

Aborts the handshake if server has selected an exportable cipher suite for a protocol version of TLS 1.1 or later.

ServerHandshaker C

Does not select an exportable cipher suite for a protocol version of TLS 1.1 or later.

SecurityProvider, IaikEccProvider B

Method getSignature() uses the provided random for initializing the Signature engine for signing.

SSLContext C

get/setAllowIdentityChangeDuringRenegotiation: default value set to false.

SSLContext C

New method setDHModpID to use prime modulus and base generator from a Modular Exponential (MODP) group (RFC 3526) by default for domestic temporary DH parameters.

SupportedEllipticCurves NF

Added support for Brainpool curves brainpoolP256r1, brainpoolP384r1, brainpoolP512r1
according to RFC 7027.

JSSE-Wrapper: IAIKSSLSocketFactory, IAIKSSLSocketFactory C

getSupportedCipherSuites returns plugable suites only when JDK 1.5 is used, otherwise all implemented suites are returned; key type fix

JSSE-Wrapper: IAIKSSLSocketWrapper C

changed getNeed/WantClientAuth to work with HttpsURLConnection of JDK 7

JSSE-Wrapper: IAIKSSLSocketWrapper C

JSSE compliant autohandshake behaviour: getInputStream(), getOutputStream() now use special wrapper streams to start the auto handshake not before a write or read call, respectively

JSSE-Wrapper: JSSEClient/JSSEServerConext C

use KeyManager mainly to set client/server credentials; getClient/ServerCredentials first try to get credentials from the underlying iSaSiLk SSLClient/ServerContext (to support ellitpic curve extensions, parameter and key usage checks…) and then — if no credentials are available from the underlying context — ask the key manager

JSSE-Wrapper: IAIKSSLSocketWrapper, IAIKSSLServerSocketWrapper C

if peer authentication is required deny missing peer certificate regardless of trust manager configuration

IAIK-SSL 4.5 – 28. March 2013
Class or Package Bug / Change / New Feature Description and Examples
* C

JDK 1.1.x is no longer supported. Supported Java(TM) versions are
1.2, 1.3, 1.4, 1.5 (5.0), 1.6 (6.0), 1.7 (7.0) and compatible.

ChainVerifier C

If server name check has been disabled by calling

chainVerifier.setCheckServerName(false); the server certificate
name(s) is/are checked anyway if a critical ServerNameList
extension has been set for the SSLClientContext.

ClientHello, ClientHandshaker C

According TLS spec always suggest maximum supported version in ClientHello (also during a renegotiation when already have negotiated a lower version in the first handshake) to avoid problems with imlementations (e.g. IIS) which checks the RSA premaster
secret against the suggested version of the initial handshake

demo.ecc.* C

Adjusted to support the new IAIK ECCelerate(TM) library.

DefaultNoTrustChainVerifier NF

Alternative ChainVerifier implementation that rejects any certificate
if no trust anchor is set.

HandShaker C

If the server has sent an an “unrecognized_name” warning alert the
handshake will be continued if an un-critical ServerNameList extension has been set for the SSLClientContext.

InputRecord NF, C

Constant-time unpadding and MAC calculation as countermeasure against the Lucky Thirteen timing attack on cipher suites using block ciphers in CBC mode.

KeyAndCert C

No more serializable.

OutputRecord C

Some performance improvements in TLS 1.1 explicit IV handling.

SecurityProvider NF

Method generateMasterSecret() added.

SecurityProvider NF

Method validateDHPublicKey() added.

SecurityProvider C

Method getTLSServerName(X509Certificate) now does not return null, but tries to parse the server name from the commonName (cn) attribute — if included — of the subjectDN of the certificate; the SubjectAltName extension is not considered in the general (not provider specific) implementation.

SSLContext, SSLInputStream NF

New method setInputStreamAvailableMode to allow to configure
the behaviour of the SSLInputStream.available method for the
case when the data has not been already decrypted by a precedingread() call.

SSLContext NF

Now can be also configured via SSLContext.properties file.

SSLContext NF

New method setUseRecordSplitting to en/disable 1/n-1 record splitting as countermeasure against the Duong/Rizzo BEAST (Browser Exploit Against SSL/TLS) CBC attack on SSL3.0, TLS1.0.

SSLContext NF

New method addTrustedCertificates(KeyStore keyStore) to add trusted certificates from a KeyStore

SSLClientContext NF

New method addClientCredentials(KeyStore keyStore, char[] password) to add client credentials from a KeyStore

SSLServerContext NF

New method addServerCredentials(KeyStore keyStore, char[] password) to add server credentials from a KeyStore

SSLServerContext NF

New method setIgnoreClientCipherSuitePreferenceOrder
allowing to select the active cipher suite by server preference order

w3c_http.jar NF, B, C

check if client/server have sent “connection:close” for keep-alive behaviour; try to close the socket on stream closure for non keep-alive connections, too; reuse connections for POST requests, too; implementation of JDK 1.5 methodssetFixedLengthStreamingMode, setChunkedStreamingMode added; parsing of timeout parameter of http Keep-Alive response header added

IAIK-SSL 4.4 – 22. February 2010
Class or Package Bug / Change / New Feature Description and Examples
* NF, C

Implementation of the RenegotiationInfo extension according to RFC 5746 to provide secure renegotiation handling (see here)

ClientHandshaker C

When resuming a session check if session version is compliant to SSLClientContext.allowedVersions (if they have changed)

ClienHello, ServerHello C

Extensions (if set) are also send and parsed when SSLv3 is used (and not only for TLS as done so far)

Handshaker C

Refresh SSLContext settings at the beginning of a renegotiation

SecurityProvider NF

New methodcontinueIfPeerDoesNotSupportSecureRenegotiation to decide whether to continue a handshake if the peer does not support secure renegotiation according to RFC 5746

SSLContext NF

New methods setAllowLegacyRenegotiation,setUseNoRenegotiationWarnings,

setAllowIdentityChangeDuringRenegotiation to configure the iSaSiLk renegotiation handling

SSLContext C

Method addPSKCredentials: if already set, do not replace default PSK credentials

SSLContext C

setExtensions: if extensions are set, they are also sent when SSLv3 is used; extensions are also parsed now when SSLv3 is used (not only for TLS as done do far)

SSLTransport C

Session is no more closed when sending an alert with warning level (peer may decide whether it want to continue or close the session)

IAIK-SSL 4.31 – 6. November 2009
Class or Package Bug / Change / New Feature Description and Examples
ClientHandshaker C

Final handshake messages are not packed together with first application data also when resuming a session (to avoid possible problems when using another transport protocol than TCP)

SSLContext NF

New method setDisableRenegoation allowing to disable renegotiation at all to prevent renegotiation attacks (coumtermeasure until RenegotionInfo extension becomes approved). Before actually disabling renegotiation make sure that it is not required by your application!

IAIK-SSL 4.3 – 28. September 2009
Class or Package Bug / Change / New Feature Description and Examples
* NF

Support for Camellia cipher suites according to RFC 4132 added.

* C

Where possible Hashtables are replaced by HashMaps to increase
access performance in multithreaded environments; for
JDK 1.1.x a new jdk11x_update.jar version must be used

ClientHandshaker C

ClientHello debugging contains remote peer name and port.

ChainVerifier NF

verifyChain: check that different consecutive certificates do not have the same signature value (countermeasure against preimage attacks on the signature hash algorithm)

IAIK-SSL 4.2 – 23. December 2008
Class or Package Bug / Change / New Feature Description and Examples
* NF

Support for elliptic curve cipher suites according to RFC 4492 (Named Curves) added.

* NF

Handshalke performance improvements by packaging handshake
messages and send them together, if possible; configurable via
SSLContext

* C

Reorganized debugging to improve performance in non-debug mode.
Client/ServerHello debugging contains remote peer address.
KeyExchange debugging contains information about the key, if included.

demo.ecc.* NF

ECC cipher suite demos

ClientHandshaker C

Fixed DH client authentication only allowed for DH_ cipher suites

ClientHandshaker B

Resume, rnegotiate: set max version to active version from previous session

IaikProvider NF

If used with the unltd version of IAIK-JCE 3.17 or later, iSaSiLk can be used with unlimited
strength cryptography even if only the default jurisdiction policy files are
installed

IaikEccProvider NF

iSaSiLk SecurityProvider for supporting ECC cipher suites according to RFC 4492:

SecurityProvider.setSecurityProvider(new IaikEccProvider());

SecurityProvider NF, C

New methods for ECC cipher suite support; implemented by IaikEccProvider

ServerHandshaker C

Fixed DH client authentication only allowed for DH_ cipher suites

SSLContext NF

New methods setDoNotPackHandshakeMessages,
getDoNotPackHandshakeMessages allowing to switch
packaging of handshake messages on/off (by default handshake messages
are packaged together if possible)

SupportedEllipticCurves NF

Implementation of the elliptic_curves TLS extension as specified by RFC 4492:
// create extension list
ExtensionList extensions = new ExtensionList();
// add SupportedEllipticCurves extension
SupportedEllipticCurves supportedEllipticCurves = new SupportedEllipticCurves();
extensions.addExtension(supportedEllipticCurves);
// enable exensions
sslContext.setExtensions(extensions);

SupportedPointFormats NF

Implementation of the ec_point_formats TLS extension as specified by RFC 4492:

// create extension list
ExtensionList extensions = new ExtensionList();
// add SupportedPointFormats extension
SupportedPointFormats supportedPointFormats = new SupportedPointFormats();
extensions.addExtension(supportedPointFormats);
// enable exensions
sslContext.setExtensions(extensions);

IAIK-SSL 4.1 – 21. December 2007
Class or Package Bug / Change / New Feature Description and Examples
* NF, C

Support for TLS 1.1 added; by default SSL 3.0, TLS 1.0 and TLS 1.1 are
enabled; TLS 1.1 can be selected viaSSLContext.VERSION_TLS11

CipherSuite NF

Support for PSK cipher suites with NULL encryption according to RFC 4785

SessionTicket C

Adapted to RFC 4507 successor draft-salowey-tls-rfc4507bis-01.txt which
simply puts the ticket into the extension_data field since done so by
most applications; SHA-256 used for HMAC ticket protection.

SessionTicket B

Server only sends SessionTicket extension if client has presented
one; server-sent SessionTicket empty in any case

SSLClientContext NF, C

New method setUseMaxVersionForRSAPremasterSecret to
decide whether to send the maximum client version (from the ClientHello)
within the RSA premaster secret or do send the active negotiated version. The
protocol requires to send the maximum client version, but many applications
send the active version. iSaSiLk 4.1 by default sends the maximum client
version (versions prior 4.1 have sent the active version).

SSLContext C

TLS 1.1: set/getCacheTerminatedSessions different
default behaviour between TLS 1.1 and versions prior TLS 1.1.
Since TLS 1.1 does no more require to invalidate incorrectly
terminated sessions they are cached by default when TLS 1.1
is used.

SSLContext NF

New method setSendRecordOverflowAlert to decide
if the handshake shall be aborted and a record_overflow
shall be sent if a record is received with exceeds the maximum
allowed fragment length, or if the internal buffer shall be
automatically enlarged and the handshake shall be continued

SSLContext NF

TLS 1.1: Method updateCipherSuites disables exportable
cipher suites if the SSLContext has been configured to
support TLS 1.1 only (TLS 1.1 disallows the use of
exportable cipher suites)

SSLServeContext NF

New method setCheckVersionInRSAPremasterSecret to
decide whether to check version number sent within the RSA
premaster secret. The protocol requires to send the maximum client
version, but many applications send the active negotiated version,
thus iSaSiLk by default does not check the version.

SSLServeContext C

Method clone clones server credential
repository

w3c_http.jar C

Adapted to most recent Jigsaw version, 2.2.6.

IAIK-SSL 4.0 – 6. March 2007
Class or Package Bug / Change / New Feature Description and Examples
ChainVerifier NF

New method setCacheSize allowing to
limit the size of the cert cache

CipherSuite NF

Method isAvailable now also
inlcudes policy key size limitations checks

CipherSuite NF

Added static TLS_ variables
for AES cipher suites (synonymical to their
SSL_ equivalents

ClientHandShaker C

Local session is invalidated if server has refused a resume request

ExtendedPrintWriter NF

Extended PrintWriter implementation allowing application to explicitly specify the
line break to be used (CRLF or LF)

Extension, ExtensionList, CertificateStatusRequest, ClientCertificateURL, MaximumFragmentLength, ServerNameList, TruncatedHMAC, TrustedAuthorities NF

Support for TLS extensions according to RFC 3546;
Implementations for all standard extensions
status_requestclient_certificate_url,
max_fragment_lengthserver_name,
truncated_hmactrusted_authorities

KeyAndCertURL NF

Client credentials to be used with the
client_certificate_url extension

OCSPCertStatusChainVerifier NF

Client-side ChainVerifier to validate OCSP responses
sent by the server in return to a status_request
extension

OutputRecord C

Record fragmentation also supported during handshake

PreSharedKey, PCSKCredential, PSKManager,... NF

Support for all pre-shared key (PSK) cipher suites
defined by RFC 4279

SessionManager NF

New method setCacheSizeLimit allowing
to limit the size of the session cache

SessionTicket NF

Implementation of the session_ticket extension
according to RFC 4507 (Session Resumption without Server-Side
State)

SSLContext, SSLClientContext, SSLServerContext NF

Additional constructors to allow to supply the cipher suites
already when creating the SSLContext; may be used for applets
to avoid reloading attemps of missing classes (e.g. IDEA)
when checking if enabled cipher suite algorithms are supported

SSLContext NF

New method setDoNotSendServerCloseNotify allowing to tell
the server not to send a close_notify alert message on shutdown.
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.

SSLException NF

New methods getAlertCode and getAlertDescription
allowing to query for alert codes and alert descriptions

SSLCertificateException, SSLCertificateRuntimeException NF

New exceptions extended from SSLException;ChainVerifier.verifyChain
may throw a SSLRuntimeException which may wrap a certificate related
problem that is propageted through an CertificateException

Utils B

fixed getASCIIWriter to always write a CRLF instead of platfrom
dependent linefeed

Utils B

Method proxyConnext supports proxy authentication and
does not use a proxy for host that have been classified as
“https.nonProxyHosts”

JSSEWrapper NF

Adapted to work with JDK versions >= 1.5 where it is allowed
to plug-in JSSE providers again

w3c_http.jar C

HTTPS library adapted to most recent Jigsaw version (2.2.5);
several fixes and improvements

Any questions?

Don‘t hestitate to ask us about our products.

Contact us