iaik.smime.ess
Class MLExpansionHistory

java.lang.Object
  extended by iaik.asn1.structures.AttributeValue
      extended by iaik.smime.ess.ESSAttributeValue
          extended by 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

This Javadoc may contain text parts from text parts from IETF Internet Standard specifications (see copyright note).

IAIK-CMS 5.1, (c) 2002 IAIK, (c) 2003 - 2010 SIC