iaik.security.ssl
Class MaxFragmentLength

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

public class MaxFragmentLength
extends Extension
implements java.lang.Cloneable

This class implements the MaxFragmentLength structure as used by the max_fragment_length TLS extension.

In constrained environments it may be preferable to use a smaller maximum data fragment length than the TLS default maximum plaintext fragment length of 2^14 (16384) bytes. For negotiating a smaller fragment length a TLS client may send a max_fragment_length extension within an extended ClientHello message indicating the max fragment length value he wants to use (see RFC 4366):

 enum{
    2^9(1), 2^10(2), 2^11(3), 2^12(4), (255)
 } MaxFragmentLength;
 

If the server agrees to use a smaller maximum fragment length, he sends back a max_fragment_length extension which has to contain the same value as received from the client.

If any of the two parties detects that the max_fragment_length extension received from the peer does contain an invalid value (not 1, 2, 3 or 4 for max fragment lengths 2^9, 2^10, 2^11, 2^12, respectively) it has to abort the handshake with an illegal_parameter alert.

On the client side, when you create a MaxFragmentLength object to be sent within an extended ClientHello message, you have identify the maximum fragment length you want to use, e.g.:

 // we want use a max fragment length of 2^10 (1024)
 int maxLen = MaxFragmentLength.L_1024;
 // create MaxFragmentLength
 MaxFragmentLength maxFragmentLength = new MaxFragmentLength(maxLen);
 // add to ExtensionList
 ExtensionList extensions = new ExtensionList();
 ...
 extensions.addExtension(maxFragmentLength);
 ...
 // set extensions for the SSLClientContext configuration:
 SSLClientContext clientContext = new SSLClientContext();
 // extensions are only defined for TLS
 clientContext.setAllowedProtocolVersions(SSLContext.VERSION_TLS10, SSLContext.VERSION_TLS12); 
 ...
 clientContext.setExtensions(extensions);
 ...
 
Allowed values for the MaxFragmentLength extensions are: If you set the critical flag of a client-side MaxFragmentLength to true (client-side) default), the handshake will be aborted if the server does not respond with a max_fragment_length extension. Or the handshake may already be aborted (before reading the server extension) with a "Invalid SSL message, too long" alert because the client has already switched to a smaller fragment length. Therefore critical MaxFragmentLength extensions shall be only used in environments where both client and server are known to support this extensions.

On the server side you only have to tell the SSLServerContext configuration whether to support the max_fragment_length extension or not. Since the max_fragment_length extension sent back by the server has to contain the same value as the max_fragment_length extension received from the client, you do not know the max fragment value when configuring the iSaSiLk server. Thus use the empty default constructor when configuring the SSLServerContext to support the max_fragment_length extension:

 // create MaxFragmentLength
 MaxFragmentLength maxFragmentLength = new MaxFragmentLength();
 // add to ExtensionList
 ExtensionList extensions = new ExtensionList();
 ...
 extensions.addExtension(maxFragmentLength);
 ...
 // set extensions for the SSLServerContext configuration:
 SSLServerContext serverContext = new SSLServerContext();
 ...
 serverContext.setExtensions(extensions);
 ...
 
If you set the critical flag of a server-side max_fragment_length extension to true, the handshake will be aborted if the client does not send a max_fragment_length extension within the extended ClientHello message.

Version:
File Revision 20
See Also:
Extension, ExtensionList

Field Summary
static int L_1024
          Identifies the pre-defined maximum fragment length 1024 (2^10).
static int L_2048
          Identifies the pre-defined maximum fragment length 2048 (2^11).
static int L_4096
          Identifies the pre-defined maximum fragment length 4096 (2^12).
static int L_512
          Identifies the pre-defined maximum fragment length 512 (2^9).
static ExtensionType TYPE
          The type (1) of the max_fragment_length extension.
 
Constructor Summary
MaxFragmentLength()
          Creates a new MaxFragmentLength extension object.
MaxFragmentLength(int mflId)
          Creates a new MaxFragmentLength extension object with the given length id.
 
Method Summary
 java.lang.Object clone()
          Returns a clone of this MaxFragmentLength extension object.
 boolean equals(java.lang.Object obj)
          Checks if this MaxFragmentLength is equal to the given object.
 int getLength()
          Gets maximum fragment length value of this MaxFragmentLength extension object.
 int getMflId()
          Gets maximum fragment length id of this MaxFragmentLength extension object.
 java.lang.String toString()
          Gets a String representation of this MaxFragmentLength.
 
Methods inherited from class iaik.security.ssl.Extension
getExtensionType, getName, getType, setCritical
 
Methods inherited from class java.lang.Object
finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

TYPE

public static final ExtensionType TYPE
The type (1) of the max_fragment_length extension.


L_512

public static final int L_512
Identifies the pre-defined maximum fragment length 512 (2^9).
Use it when creating a client-side MaxFragmentLength extension object for suggesting a maximum fragment length of 512 (2^9) bytes:
 MaxFragmentLength maxFragmentLength = 
   new MaxFragmentLength(MaxFragmentLength.L_512);
 

See Also:
Constant Field Values

L_1024

public static final int L_1024
Identifies the pre-defined maximum fragment length 1024 (2^10).
Use it when creating a client-side MaxFragmentLength extension object for suggesting a maximum fragment length of 1024 (2^10) bytes:
 MaxFragmentLength maxFragmentLength = 
   new MaxFragmentLength(MaxFragmentLength.L_1024);
 

See Also:
Constant Field Values

L_2048

public static final int L_2048
Identifies the pre-defined maximum fragment length 2048 (2^11).
Use it when creating a client-side MaxFragmentLength extension object for suggesting a maximum fragment length of 2048 (2^11) bytes:
 MaxFragmentLength maxFragmentLength = 
   new MaxFragmentLength(MaxFragmentLength.L_2048);
 

See Also:
Constant Field Values

L_4096

public static final int L_4096
Identifies the pre-defined maximum fragment length 4096 (2^12).
Use it when creating a client-side MaxFragmentLength extension object for suggesting a maximum fragment length of 4096 (2^12) bytes:
 MaxFragmentLength maxFragmentLength = 
   new MaxFragmentLength(MaxFragmentLength.L_4096);
 

See Also:
Constant Field Values
Constructor Detail

MaxFragmentLength

public MaxFragmentLength()
Creates a new MaxFragmentLength extension object.
This constructor shall be used on the server side to enable max_fragment_length extension support for the SSLServerContext configuration:
 // create MaxFragmentLength
 MaxFragmentLength maxFragmentLength = new MaxFragmentLength();
 // add to ExtensionList
 ExtensionList extensions = new ExtensionList();
 ...
 extensions.addExtension(maxFragmentLength);
 ...
 // set extensions for the SSLServerContext configuration:
 SSLServerContext serverContext = new SSLServerContext();
 ...
 serverContext.setExtensions(extensions);
 ...
 
If you set the critical flag of this extension to true, the handshake will be aborted if the client does not send a max_fragment_length extension within the extended ClientHello message.

If the client has sent a max_fragment_length extension, the server will respond with an max_fragment_length extension containing the same value as included in the max_fragment_length extension received from the client.


MaxFragmentLength

public MaxFragmentLength(int mflId)
                  throws java.lang.IllegalArgumentException
Creates a new MaxFragmentLength extension object with the given length id.
This constructor shall be used on the client side to specify the maximum fragment length id that shall be sent to the server within an extended ClientHello message, e.g.:
 // we want use a max fragment length of 2^10 (1024)
 int maxLen = MaxFragmentLength.L_1024;
 // create MaxFragmentLength
 MaxFragmentLength maxFragmentLength = new MaxFragmentLength(maxLen);
 // add to ExtensionList
 ExtensionList extensions = new ExtensionList();
 ...
 extensions.addExtension(maxFragmentLength);
 ...
 // set extensions for the SSLClientContext configuration:
 SSLClientContext clientContext = new SSLClientContext();
 ...
 clientContext.setExtensions(extensions);
 ...
 
Allowed values for the MaxFragmentLength extensions are: If you set the critical flag of this extension to true (client-side default), the handshake will be aborted if the server does not respond with a max_fragment_length extension.

On the server side, when creating a MaxFragmentLength extension object, you generally will use the default constructor to indicate that the max_fragment_length extension shall be supported. If you want to limit the server to accept only one specific max fragment length value from the set of allowed values, you may use this constructor and specify the desired max fragment value when creating the MaxFragmentLength object, e.g.:

 int maxLen = MaxFragmentLength.L_1024;
 MaxFragmentLength maxFragmentLength = new MaxFragmentLength(maxLen);
 

Parameters:
mflId - the maximum fragment length id, either 1, 2, 3 or 4
Throws:
java.lang.IllegalArgumentException - if the given maximum fragment length id is out of range (not 1, 2, 3 or 4 for actual length values 512 (2^9), 1024 (2^10), 2048 (2^11), 4096 (2^12), respectively)
Method Detail

getMflId

public int getMflId()
Gets maximum fragment length id of this MaxFragmentLength extension object.

Returns:
the maximum fragment length id; 1, 2, 3 or 4 for actual length values 512 (2^9), 1024 (2^10), 2048 (2^11), 4096 (2^12), respectively

getLength

public int getLength()
Gets maximum fragment length value of this MaxFragmentLength extension object.

Returns:
the maximum fragment length value; 512 (2^9), 1024 (2^10), 2048 (2^11), 4096 (2^12) for ids 1, 2, 3, 3, respectively

clone

public java.lang.Object clone()
Returns a clone of this MaxFragmentLength extension object.

Overrides:
clone in class Extension
Returns:
a clone of this MaxFragmentLength

toString

public java.lang.String toString()
Gets a String representation of this MaxFragmentLength.

Specified by:
toString in class Extension
Returns:
a String representation of the MaxFragmentLength

equals

public boolean equals(java.lang.Object obj)
Checks if this MaxFragmentLength is equal to the given object.

Two MaxFragmentLengths are treated as equal if they have the same length (ID) values.

Overrides:
equals in class java.lang.Object
Returns:
true if this MaxFragmentLength is equal to the given object, false if it is not equal to it

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