iaik.security.ssl
Class MaxFragmentLength

java.lang.Object
  iaik.security.ssl.Extension
      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:

• MaxFragmentLength.L_512 (1) for 512 (2^09 bytes)
• MaxFragmentLength.L_1024 (2) for 1024 (2^10 bytes)
• MaxFragmentLength.L_2048 (3) for 2048 (2^11 bytes)
• MaxFragmentLength.L_4096 (4) for 4096 (2^12 bytes)

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 34

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.
int	hashCode() Gets a hash code of this MaxFragmentLength.
java.lang.String	toString() Gets a String representation of this MaxFragmentLength.

Methods inherited from class iaik.security.ssl.Extension

getAllowedProtocolVersions, getExtensionType, getName, getType, setCritical

Methods inherited from class java.lang.Object

finalize, getClass, 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:

• MaxFragmentLength.L_512 (1) for 512 (2^09 bytes)
• MaxFragmentLength.L_1024 (2) for 1024 (2^10 bytes)
• MaxFragmentLength.L_2048 (3) for 2048 (2^11 bytes)
• MaxFragmentLength.L_4096 (4) for 4096 (2^12 bytes)

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

hashCode

public int hashCode()

Gets a hash code of this MaxFragmentLength.

Overrides:

hashCode in class java.lang.Object

Returns:

a hash code of this SupportedVersions

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