iaik.security.ssl
Class ExtensionList

java.lang.Object
  extended by iaik.security.ssl.ExtensionList
All Implemented Interfaces:
java.lang.Cloneable

public class ExtensionList
extends java.lang.Object
implements java.lang.Cloneable

This class represents a TLS ExtensionList.

Extensions to the TLS protocol have been introduced by RFC 4366 (TLS extensions). and are incorporated into the upcoming TLS 1.2 protocol.

A TLS client that wishes to use some extensions creates an ExtensionList and sends it to the server within an extended ClientHello message:

 struct {
     ProtocolVersion client_version;
     Random random;
     SessionID session_id;
     CipherSuite cipher_suites<2..2^16-1>;
     CompressionMethod compression_methods<1..2^8-1>;
     Extension client_hello_extension_list<0..2^16-1>;
 } ClientHello;
 
 
The server parses the ExtensionList from the client and responds with an extended ServerHello message if he wants to enable any of the extensions suggested by the client:
 struct {
     ProtocolVersion server_version;
     Random random;
     SessionID session_id;
     CipherSuite cipher_suite;
     CompressionMethod compression_method;
     Extension server_hello_extension_list<0..2^16-1>;
 } ServerHello;
 
 struct {
    ExtensionType extension_type;
    opaque extension_data<0..2^16-1>;
 } Extension;
 
Each extension is identified by its extension type. The value of the extension is represented as opaque extension data. Currently the following extensions are implemented by iSaSiLk: If your iSaSiLk client/server shall use TLS extensions you must configure your SSLClientContext/SSLServerContext with an Extension list containing all Extensions that shall be enabled:
  // create new ExtensionList
  ExtensionList extensions = new ExtensionList();
  ...
  // add extensions as required
  extensions.addExtension(...);
  ...
  // pass the ExtensionList to the SSLClient/ServerContext
  SSLContext context = ...;
  context.setExtensions(extensions);
 
Extension configuration may differ on client and server side. When configuring, for instance, a server_name extension, the client-side ServerNameList has to contain the server names to be sent to the server. However, since the server only has to send back an empty ServerNameList, the server-side ExtensionList only has to contain an empty ServerNameList.

When setting an ExtensionList for an SSLClient/ServerContext the configuration of all of its extensions shall be already finished. Any extension configuration that is done after the ExtensionList has been set for the SSLContext is not recognized.

Each iSaSiLk Extension maybe classified as critical or not critical. The critical flag is not defined by the TLS specification, it is only used by iSaSiLk. On the client side it decides whether to abort (critical = true) the handshake if the client has sent some particular extension in his ClientHello, but the server does not include an extension of the same type in his ServerHello. On the server side critical decides whether to abort (critical = true) the handshake if the client did not sent an expected extension.
Default: true (client-side), false (server-side)
Depending on the particular Extension in use, the critical flag may have some additional, extension-specific meaning.

When parsing an ExtensionList received from the peer, iSaSiLk creates an UnknownExtension for any extension of unknown (i.e. unsupported) type.


*) The implementation of the renegotiation_info extension is not publicly accessible. All processing that is required for secure renegotiation is done automatically and internelly by the library. For more information see the iSaSiLk release documentation.

Version:
File Revision 41
See Also:
Extension, UnknownExtension

Constructor Summary
ExtensionList()
          Default Constructor.
ExtensionList(Extension[] extensions)
          Creates an ExtensionList for the given extensions.
 
Method Summary
 boolean addExtension(Extension e)
          Adds an extension to this ExtensionList.
 java.lang.Object clone()
          Gets a clone of this Extension.
 int countExtensions()
          Gets the number of extensions included in this ExtensionList.
 Extension getExtension(ExtensionType type)
          Gets a particular extension, specified by its type.
 java.util.Enumeration getExtensionTypes()
          Gets an Enumeration containing the types of the Extensions contained in this ExtensionList.
 boolean hasExtensions()
          Checks, if there are any extensions included in this ExtensionList.
 boolean hasUnsupportedExtensions()
          Asks whether unsupported extensions are included in this ExtensionList.
 java.util.Enumeration listExtensions()
          Returns an enumeration of all extensions included in this ExtensionList.
 java.util.Enumeration listUnsupportedExtensions()
          Gets an enumeration of all unsupported extensions contained in this ExtensionList.
 void removeAllExtensions()
          Removes all extensions currently included in this ExtensionList.
 boolean removeExtension(ExtensionType type)
          Removes an extension, identified by its type.
 void setAllCritical(boolean critical)
          Sets the critical state of all included extensions to true or false.
 java.lang.String toString()
          Gets a string that represents the contents of the ExtensionList.
 java.lang.String toString(boolean detailed)
          Gets a string that represents the contents of the ExtensionList.
 
Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

ExtensionList

public ExtensionList()
Default Constructor. Creates a new ExtensionList object to be supplied with TLS Extensions. Use method addExtension to add extensions to the list.


ExtensionList

public ExtensionList(Extension[] extensions)
Creates an ExtensionList for the given extensions.

Parameters:
extensions - the extensions for this ExtensionList
Method Detail

addExtension

public boolean addExtension(Extension e)
Adds an extension to this ExtensionList.
If there already exists an extension with the same type it is replaced by the new extension.

Parameters:
e - the extension to to be added
Returns:
true, if an extension with the same type has been replaced, or false if there has yet not been included any extension with the same type
Throws:
java.lang.NullPointerException - if the given extension is null

removeExtension

public boolean removeExtension(ExtensionType type)
Removes an extension, identified by its type.

Parameters:
type - the type of the extension to be removed
Returns:
true if the extension successfully has been removed, false otherwise

removeAllExtensions

public void removeAllExtensions()
Removes all extensions currently included in this ExtensionList.


listExtensions

public java.util.Enumeration listExtensions()
Returns an enumeration of all extensions included in this ExtensionList.

The enumeration returned by this method will contain an UnknownExtension for any included unknown extension.

Returns:
an enumeration of the included extensions; the enumeration maybe empty if no extensions are included in this ExtensionList

hasExtensions

public boolean hasExtensions()
Checks, if there are any extensions included in this ExtensionList.

Returns:
true if there are extensions included, false if not

countExtensions

public int countExtensions()
Gets the number of extensions included in this ExtensionList.

Returns:
the number of extensions

listUnsupportedExtensions

public java.util.Enumeration listUnsupportedExtensions()
Gets an enumeration of all unsupported extensions contained in this ExtensionList.

Returns:
an enumeration of all unsupported extensions (as instances of UnknownExtension) contained in this ExtensionList; the enumeration maybe empty if no unsupported extensions are included

hasUnsupportedExtensions

public boolean hasUnsupportedExtensions()
Asks whether unsupported extensions are included in this ExtensionList.

Returns:
true if unsupported extensions are included false if no unsupported extensions are included

setAllCritical

public void setAllCritical(boolean critical)
Sets the critical state of all included extensions to true or false.

Parameters:
critical - true if all extensions shall be set to critical; false if they shall be set to not critical;

getExtension

public Extension getExtension(ExtensionType type)
Gets a particular extension, specified by its type.

If the extension type is unknown, an UnknownExtension is returned.

Parameters:
type - the type of the extension
Returns:
the extension, or null if no extension with the given type is included in this ExtensionList

getExtensionTypes

public java.util.Enumeration getExtensionTypes()
Gets an Enumeration containing the types of the Extensions contained in this ExtensionList.

Returns:
an Enumeration containing the types of the extensions contained in this ExtensionList; the enumeration maybe empty if no extensions are included in this ExtensionList

clone

public java.lang.Object clone()
Gets a clone of this Extension.

Overrides:
clone in class java.lang.Object
Returns:
a clone of this Extension

toString

public java.lang.String toString()
Gets a string that represents the contents of the ExtensionList.

Overrides:
toString in class java.lang.Object
Returns:
the string representation

toString

public java.lang.String toString(boolean detailed)
Gets a string that represents the contents of the ExtensionList.

Parameters:
detailed - true to include the contents of the extensions false to only dump the extension types
Returns:
the string representation

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

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