iaik.smime.ess
Class MLExpansionHistory

java.lang.Object
  iaik.asn1.structures.AttributeValue
      iaik.smime.ess.ESSAttributeValue
          iaik.smime.ess.MLExpansionHistory

All Implemented Interfaces:

ASN1Type

public class MLExpansionHistory
extends ESSAttributeValue

The S/MIMEv3 ESS MLExpansionHistory attribute.

The Enhanced Security Services for S/MIMEv3 (ESS) (RFC 2634) specifies the MLExpansionHistory attribute to may be included as signed attribute in a SignerInfo for recording the mailing list agents (MLA) that have processed a message. As an MLA distributes a message to members of an ML, the MLA records its unique identifier, date and time of expansion, and receipt policy in an MLData structure and adds it to the MLData list of an MLExpansionHistory attribute. If yet no MLData has been added to the list the particular MLA MLData will become the first entry in the list:

 
 MLExpansionHistory ::= SEQUENCE
      SIZE (1..ub-ml-expansion-history) OF MLData
        
 MLData ::= SEQUENCE {  
   mailListIdentifier EntityIdentifier,
   expansionTime GeneralizedTime,  
   mlReceiptPolicy MLReceiptPolicy OPTIONAL }
 

Each MLA processing a message checks if its MLData already is included in the MLExpansionHistory list. If it detects its own identification information, then the MLA must discontinue expansion processing and should provide warning of an expansion loop to a human mail list administrator. The mail list administrator is responsible for correcting the loop condition. Please refer to (RFC 2634) (Section 4) for a more detailed discussion about mail list expansion and MLA processing.

Since at least one MLData entry has to be present the MLA creating an MLExpansionHistory attribute, supplies an MLData object carrying its identification information, time of expansion and optional MLReceiptPolicy superseding the originator request for signed receipts, if present:

 // the MLA is identified by an IssuerAndSerialNumber:
 IssuerAndSerialNumber issuerAndSerialNumber = ...;
 EntityIdentifier mailListID = new EntityIdentifier(issuerAndSerialNumber);
 // the time the MLA processed the message
 Date expansionTime = ...;
 // create the MLData:
 MLData mlData = new MLData(mailListID, expansionTime);
 // a list of recipients to which receipts should be returned in addition to the originator:
 GeneralNames recipientList = ...;
 // create a MLReceiptPolicy of appropriate type:
 MLReceiptPolicy mlReceiptPolicy = new MLReceiptPolicy(MLReceiptPolicy.IN_ADDITION_TO, recipientList);
 // set the MLReceiptPolicy of the MLData:
 mlData.setMLReceiptPolicy(mlReceiptPolicy);
 // Create an MLExpansionHistory attribute and set the MLData as first list entry:
 MLExpansionHistory mlExpansionHistory = new MLExpansionHistory(mlData);
 

Any further MLA may add its MLData to the list by calling method addMLData. However, for preventing from causing an expansion loop the MLA first may check if it already has added an MLData to the list. When adding its MLData to an MLExpansionHistory that already has reached its allowed limit of 64 entries, an MLExpansionHistoryOverflowException will be thrown indicating to notify the ML administrator to correct the overflow condition:

 // the mail list identifier of the MLA going to add an MLData entry:
 EntityIdentifier myMLId = ...;
 // the MLData to be added:
 MLData myMLData = ...;
 // check for expansion loop
 if (mlExpansionHistory.getMLData(myMLId) == null) {
   try {
     mlExpansionHistory.addMLData(myMLData);
   } catch (MLExpansionHistoryOverflowException ex) {
     System.err.println("MLExpansionHistory overflow!");
     MLData[] mlDataList = ex.getMLDataList();
     ...
   }
 }
 

The array of MLData objects returned when calling method getMLDataList will already include the MLData object just added and causing the overflow. An MLExpansionHistoryOverflowException also will be thrown when reading in and attempting to parse an overflowed MLExpansionHistory attribute from its ASN.1 representation. For that reason MLExpansionHistoryOverflowException is a RuntimeException because method decode inherited from class AttributeValue allows a CodingException only.

See Also:

EntityIdentifier, MLReceiptPolicy, MLData, MLExpansionHistoryOverflowException

Field Summary

static ObjectID	oid The attributeType object identifier of this MLExpansionHistory attribute.
static int	UB_ML_EXPANSION_HISTORY The maximum number (64) of MLData objects allowed to be in the list.

Constructor Summary

MLExpansionHistory()
Empty default constructor.

MLExpansionHistory(ASN1Object obj)
Creates an MLExpansionHistory from the given ASN1Object.

MLExpansionHistory(MLData mlData)
Creates an MLExpansionHistory attribute for the given MLData.

MLExpansionHistory(MLData[] mlDataList)
Creates an MLExpansionHistory for the given MLData list.

Method Summary

void	addMLData(MLData mlData) Adds the given MLData to this MLExpansionHistory.
int	countMLDataEntries() Counts the number of MLData entries included in the list.
void	decode(ASN1Object obj) Decodes the MLExpansionHistory from the given ASN1Object.
boolean	equals(java.lang.Object obj) Compares this MLExpansionHistory to the specified object.
ObjectID	getAttributeType() Returns the OID identifying the MLExpansionHistory attribute type.
MLData	getLastMLData() Returns the last MLData object in the list.
MLData	getMLData(EntityIdentifier mailListIdentifier) Looks for the MLData belonging to the MLA identified by the given mail list identifier.
MLData[]	getMLDataList() Gets the MLData list contained in this MLExpansionHistory.
int	hashCode() Returns a hashcode for this object.
void	setMLDataList(MLData[] mlDataList) Sets the MLData list of this MLExpansionHistory.
ASN1Object	toASN1Object() Returns this MLExpansionHistory as ASN1Object.
java.lang.String	toString() Returns a string giving some information about this MLExpansionHistory.
java.lang.String	toString(boolean detailed) Returns a string giving some information about this MLExpansionHistory.

Methods inherited from class iaik.smime.ess.ESSAttributeValue

multipleAllowed

Methods inherited from class iaik.asn1.structures.AttributeValue

getName

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

oid

public static final ObjectID oid

The attributeType object identifier of this MLExpansionHistory attribute. The corresponding OID string is "1.2.840.113549.1.9.16.2.3".

UB_ML_EXPANSION_HISTORY

public static final int UB_ML_EXPANSION_HISTORY

The maximum number (64) of MLData objects allowed to be in the list.

If the number of MLData objects contained in an MLExpansionHistory exceeds an allowed upper bound of 64 entries an MLExpansionHistoryOverflowException is thrown to indicate the list overflow. Nevertheless an application might whish to query for the MLData objects included by calling method getMLDataList of class MLExpansionHistoryOverflowException:

 try {
   ...
 } catch (MLExpansionHistoryOverflowException ex) {
   System.err.println("MLExpansionHistory overflow!");
   MLData[] mlDataList = ex.getMLDataList();
   ...
 }
 

See Also:

Constant Field Values

Constructor Detail

MLExpansionHistory

public MLExpansionHistory()

Empty default constructor. Initializes the MLData list with an empty Vector. Only required for dynamic object creation. Shall NOT be used by an application.

MLExpansionHistory

public MLExpansionHistory(MLData mlData)

Creates an MLExpansionHistory attribute for the given MLData.

Parameters:

mlData - the mlData being the first (and maybe only) entry in the list

MLExpansionHistory

public MLExpansionHistory(MLData[] mlDataList)
                   throws MLExpansionHistoryOverflowException

Creates an MLExpansionHistory for the given MLData list.

Parameters:

mlDataList - the MLData list to be set

Throws:

MLExpansionHistoryOverflowException - if the number of MLData objects included in the list exceeds the allowed maximum (64 entries)

MLExpansionHistory

public MLExpansionHistory(ASN1Object obj)
                   throws CodingException,
                          MLExpansionHistoryOverflowException

Creates an MLExpansionHistory from the given ASN1Object.

Parameters:

obj - the MLExpansionHistory as ASN1Object

Throws:

CodingException - if the ASN1Object cannot be decoded or is invalid structured

MLExpansionHistoryOverflowException - if the number of MLData objects included in the list exceeds the allowed maximum (64 entries)

Method Detail

getAttributeType

public ObjectID getAttributeType()

Returns the OID identifying the MLExpansionHistory attribute type.

Specified by:

getAttributeType in class AttributeValue

Returns:

the OID identifying the MLExpansionHistory attribute type.

addMLData

public void addMLData(MLData mlData)
               throws MLExpansionHistoryOverflowException

Adds the given MLData to this MLExpansionHistory.

If the MLData to be added exceeds an allowed upper bound of 64 entries an MLExpansionHistoryOverflowException is thrown to indicate the list overflow. Nevertheless an application might whish to query for the MLData objects included by calling method getMLDataList of class MLExpansionHistoryOverflowException:

 try {
   mlExpansionHistory.addMLData(mlData);
 } catch (MLExpansionHistoryOverflowException ex) {
   System.err.println("MLExpansionHistory overflow!");
   MLData[] mlDataList = ex.getMLDataList();
   ...
 }
 

The array of MLData objects returned when calling method getMLDataList will already include the MLData object just added and causing the overflow.

Parameters:

mlData - the MLData to be added

Throws:

MLExpansionHistoryOverflowException - if the number of MLData objects included in the list exceeds the allowed maximum (64 entries) when adding the new MLData

setMLDataList

public void setMLDataList(MLData[] mlDataList)
                   throws MLExpansionHistoryOverflowException

Sets the MLData list of this MLExpansionHistory.

Any entry included is cleared before setting the list.

Parameters:

mlDataList - the MLData list to be set

Throws:

MLExpansionHistoryOverflowException - if the number of MLData objects included in the list exceeds the allowed maximum (64 entries)

getMLData

public MLData getMLData(EntityIdentifier mailListIdentifier)

Looks for the MLData belonging to the MLA identified by the given mail list identifier.

This method may be used by an MLA to check its own unique identifier already is in the list. If yes the MLA knows that a mail list loop has been formed, and does not send the message to the list again.

Parameters:

mailListIdentifier - the EntityIdentifier of the MLA in mind

Returns:

the MLData belonging to the MLA (loop!), or null if no MLData for this MLA is in the list (no loop)

getMLDataList

public MLData[] getMLDataList()

Gets the MLData list contained in this MLExpansionHistory.

Returns:

the MLData list contained in this MLExpansionHistory

getLastMLData

public MLData getLastMLData()

Returns the last MLData object in the list.

Returns:

the last MLData object in the list or null if the MLData list is empty

countMLDataEntries

public int countMLDataEntries()

Counts the number of MLData entries included in the list.

This method may be useful for checking if the list would exeed its maximum allowed number (64) of entries when adding a new MLData.

Returns:

the number of MLData object entries included in the list

equals

public boolean equals(java.lang.Object obj)

Compares this MLExpansionHistory to the specified object.

Specified by:

equals in class ESSAttributeValue

Parameters:

obj - the object to compare this MLExpansionHistory against.

Returns:

true, if the given object is equal to this MLExpansionHistory, false otherwise

hashCode

public int hashCode()

Returns a hashcode for this object.

Overrides:

hashCode in class ESSAttributeValue

Returns:

a hashcode for this object

decode

public void decode(ASN1Object obj)
            throws CodingException,
                   MLExpansionHistoryOverflowException

Decodes the MLExpansionHistory from the given ASN1Object.

Parameters:

obj - the MLExpansionHistory as ASN1Object

Throws:

CodingException - if the ASN1Object cannot be decoded or is invalid structured

MLExpansionHistoryOverflowException - if the number of MLData objects included in the list exceeds the allowed maximum (64 entries)

toASN1Object

public ASN1Object toASN1Object()
                        throws CodingException

Returns this MLExpansionHistory as ASN1Object.

Returns:

this MLExpansionHistory as ASN1Object

Throws:

CodingException - if an error occurs while creating the ASN.1 SEQUENCE

toString

public java.lang.String toString(boolean detailed)

Returns a string giving some information about this MLExpansionHistory.

Parameters:

detailed - whether to print detailed information about the MLData objects included

Returns:

a string representation of this MLExpansionHistory

toString

public java.lang.String toString()

Returns a string giving some information about this MLExpansionHistory.

Specified by:

toString in class AttributeValue

Returns:

a string representation of this MLExpansionHistory