MaxFragmentLength (iSaSiLk 6.1 API Documentation)

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 35

See Also:

Extension, ExtensionList

Field Summary

Fields
Modifier and Type	Field and Description
`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

Constructors
Constructor and Description
`MaxFragmentLength()` Creates a new MaxFragmentLength extension object.
`MaxFragmentLength(int mflId)` Creates a new MaxFragmentLength extension object with the given length id.

Method Summary

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

Class MaxFragmentLength

Field Summary

Constructor Summary

Method Summary

Methods inherited from class iaik.security.ssl.Extension

Methods inherited from class java.lang.Object

Field Detail

TYPE

L_512

L_1024

L_2048

L_4096

Constructor Detail

MaxFragmentLength

MaxFragmentLength

Method Detail

getMflId

getLength

clone

toString

hashCode

equals