iaik.security.ssl
Class ExtensionList

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

• Server Name Indication (server_name) (0)
• Maximum Fragment Length Negotiation ( max_fragment_length) (1)
• Client Certificate URLs ( client_certificate_url) (2)
• Trusted CA Indication ( trusted_ca_keys) (3)
• Truncated HMAC (truncated_hmac) (4)
• Certificate Status Request ( status_request) (5)
• Supported Elliptic Curves ( elliptic_curves) (10)
  Supported Groups (supported_groups) (10)
• Supported Point Formats ( ec_point formats) (11)
• Session Ticket (session_ticket) (35)
• Signature Algorithm ( signature_algorithms) (13)
• Extended Master Secret ( extended_master_secret) (23)
• Application-Layer Protocol Negotiation Extension (application_layer_protocol_negotiation) (16)
• Signature Algorithms Cert ( signature_algorithms_cert) (50)
• Supported Versions (TLS 1.3) ( supported_versions) (43)
• KeyShare (TLS 1.3) (key_share) (51)
• Certificate Authorities (TLS 1.3) ( certificate_authorities) (47)
• Psk KeyExchange Modes(TLS 1.3) ( psk_key_exchange_modes) (45)
• Post Handshake Auth (TLS 1.3) ( post_handshake_auth) (49)
• renegotiation_info (65281)^*
• cookie (TLS 1.3) (43)^*
• pre_shared_key (TLS 1.3) (41)^*

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, cookie and pre_shared_key extensions is not publicly accessible. All processing is done automatically and internally by the library.

Version:

File Revision 54

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.
static void	setDefaultCriticalValue(ExtensionType type, boolean critical) Sets the default critical value for the extension of the given type.
static void	setDefaultCriticalValue(ExtensionType type, boolean isClient, boolean critical) Sets the server- or client-specific default critical value for the extension of the given type.
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

setDefaultCriticalValue

public static final void setDefaultCriticalValue(ExtensionType type,
                                                 boolean critical)

Sets the default critical value for the extension of the given type.

Parameters:

type - the type of the extension.

critical - whether the extension of the given type shall be marked as critical by default or as non critical

Throws:

java.lang.IllegalArgumentException - if the default critical value of the specified extension cannot be set (either because the extension of the given type is not supported or it is not allowed to set the default critical value)

setDefaultCriticalValue

public static final void setDefaultCriticalValue(ExtensionType type,
                                                 boolean isClient,
                                                 boolean critical)

Sets the server- or client-specific default critical value for the extension of the given type.

Parameters:

type - the type of the extension.

isClient - whether the critical value shall be applied to a client side extension of the given type, or to the server side extension of this type

critical - whether the extension of the given type shall be marked as critical by default or as non critical

Throws:

java.lang.IllegalArgumentException - if the default critical value of the specified extension cannot be set (either because the extension of the given type is not supported or it is not allowed to set the default critical value

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