ExtensionList (iSaSiLk 6.1 API Documentation)

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 59

See Also:

Extension, UnknownExtension

Constructor Summary

Constructors
Constructor and Description

ExtensionList()
Default Constructor.

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

Constructors
Constructor and Description
`ExtensionList()` Default Constructor.
`ExtensionList(Extension[] extensions)` Creates an ExtensionList for the given extensions.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`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

Class ExtensionList

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

ExtensionList

ExtensionList

Method Detail

setDefaultCriticalValue

setDefaultCriticalValue

addExtension

removeExtension

removeAllExtensions

listExtensions

hasExtensions

countExtensions

listUnsupportedExtensions

hasUnsupportedExtensions

setAllCritical

getExtension

getExtensionTypes

clone

toString

toString