iaik.smime.ess
Class ReceiptRequest

java.lang.Object
  extended by iaik.asn1.structures.AttributeValue
      extended by iaik.smime.ess.ESSAttributeValue
          extended by iaik.smime.ess.ReceiptRequest
All Implemented Interfaces:
ASN1Type

public class ReceiptRequest
extends ESSAttributeValue

The S/MIMEv3 ESS ReceiptRequest attribute.

The Enhanced Security Services for S/MIMEv3 (ESS) (RFC 2634) specifies the ReceiptRequest attribute to may be included as an signed attribute in a SignerInfo to request signed receipts from a specific list of recipients:

 ReceiptRequest ::= SEQUENCE {
   signedContentIdentifier ContentIdentifier,
   receiptsFrom ReceiptsFrom,
   receiptsTo SEQUENCE SIZE (1..ub-receiptsTo)) OF GeneralNames }

 ub-receiptsTo INTEGER ::= 16

 id-aa-receiptRequest OBJECT IDENTIFIER ::= { iso(1) member-body(2)
   us(840) rsadsi(113549) pkcs(1) pkcs-9(9) smime(16) id-aa(2) 1}

 ContentIdentifier ::= OCTET STRING

 id-aa-contentIdentifier OBJECT IDENTIFIER ::= { iso(1) member-body(2)
    us(840) rsadsi(113549) pkcs(1) pkcs-9(9) smime(16) id-aa(2) 7}
 
A signedContentIdentifier must be created by the message originator when creating a receipt request. To ensure global uniqueness, the minimal signedContentIdentifier should contain a concatenation of user-specific identification information (such as a user name or public keying material identification information), a GeneralizedTime string, and a random number.
The receiptsFrom field is used by the originator to specify the recipients requested to return a signed receipt. A CHOICE is provided to allow specification of:
 ReceiptsFrom ::= CHOICE {
   allOrFirstTier [0] AllOrFirstTier,
   -- formerly "allOrNone [0]AllOrNone"
   receiptList [1] SEQUENCE OF GeneralNames }

 AllOrFirstTier ::= INTEGER { -- Formerly AllOrNone
   allReceipts (0),
   firstTierRecipients (1) }
 
The receiptsTo field is used by the originator to identify the user(s) to whom the identified recipient should send signed receipts. The message originator MUST populate the receiptsTo field with a GeneralNames for each entity to whom the recipient should send the signed receipt. If the message originator wants the recipient to send the signed receipt to the originator, then the originator must include a GeneralNames for itself in the receiptsTo field.

An entity requsting a signed receipt performs the folowing steps for creating the ReceiptRequest and including it as signed attribute into a SignerInfo object (see RFC 2634, section 2.2):

  1. A receiptRequest data structure is created.
  2. A signed content identifier for the message is created and assigned to the signedContentIdentifier field. The signedContentIdentifier is used to associate the signed receipt with the message requesting the signed receipt.
  3. The entities requested to return a signed receipt are noted in the receiptsFrom field.
  4. The message originator MUST populate the receiptsTo field with a GeneralNames for each entity to whom the recipient should send the signed receipt. If the message originator wants the recipient to send the signed receipt to the originator, then the originator MUST include a GeneralNames for itself in the receiptsTo field. GeneralNames is a SEQUENCE OF GeneralName. receiptsTo is a SEQUENCE OF GeneralNames in which each GeneralNames represents an entity. There may be multiple GeneralName instances in each GeneralNames. At a minimum, the message originator MUST populate each entity's GeneralNames with the address to which the signed receipt should be sent. Optionally, the message originator MAY also populate each entity's GeneralNames with other GeneralName instances (such as directoryName).
  5. The completed receiptRequest attribute is placed in the signedAttributes field of the SignerInfo object.

When creating a new ReceiptRequest the signedContentIdentifier, receiptsFrom and the receiptsTo list have to be specified, e.g.:

 // the public key of the user
 PublicKey publicKey = ...;
 // the date from which to create the GeneralizedTime
 Date date = ...;
 // a random number
 byte[] rand = ...;
 // create a signed content identifier from user keying material, date and random number:
 ContentIdentifier contentIdentifier = new ContentIdentifier(publicKey, date, rand);
 // request receipts from all recipients:
 int allOrFirstTier = ReceiptsFrom.ALL_RECIPIENTS;
 ReceiptsFrom receiptsFrom = new ReceiptsFrom(allOrFirstTier);
 // the list of useres to which identified recipients should send signed receipts:
 GeneralNames receiptsTo = ...;
 // create the ReceiptRequest:
 ReceiptRequest receiptRequest =
   new ReceiptRequest(contentIdentifier, receiptsFrom, receiptsTo);
 

See Also:
ContentIdentifier, ReceiptsFrom

Field Summary
static ObjectID oid
          The attributeType object identifier of this ReceiptRequest attribute.
static int UP_RECEIPTS_TO
          Upper bound (16) for the number of user(s) that may be listed in the receiptsTo field to identify the user(s) to whom the identified recipients should send signed receipts.
 
Constructor Summary
ReceiptRequest()
          Empty default constructor.
ReceiptRequest(ASN1Object obj)
          Creates an ReceiptRequest from its ASN.1 representation.
ReceiptRequest(ContentIdentifier signedContentIdentifier, ReceiptsFrom receiptsFrom, GeneralNames[] receiptsTo)
          Creates an ReceiptRequest from given content identifier, receiptsFrom and receiptsTo values.
ReceiptRequest(ContentIdentifier signedContentIdentifier, ReceiptsFrom receiptsFrom, java.lang.String[] receiptsToAddresses)
          Creates an ReceiptRequest from given content identifier, receiptsFrom and receiptsTo addresses.
 
Method Summary
 void decode(ASN1Object obj)
          Decodes the given ASN.1 ReceiptRequest object for parsing the internal structure.
 boolean equals(java.lang.Object obj)
          Compares this ReceiptRequest to the specified object.
 ObjectID getAttributeType()
          Returns the OID identifying the ReceiptRequest attribute type.
 ReceiptsFrom getReceiptsFrom()
          Returns the receiptsFrom.
 GeneralNames[] getReceiptsTo()
          Returns the receiptsTo.
 java.lang.String[] getReceiptsToAddresses()
          Returns all receiptsTo email addresses included in this ReceiptRequest.
 ContentIdentifier getSignedContentIdentifier()
          Returns the signed content identifier.
 int hashCode()
          Returns a hashcode for this object.
 ASN1Object toASN1Object()
          Returns this ReceiptRequest as ASN1Object.
 java.lang.String toString()
          Returns a string representation of this ReceiptRequest.
 java.lang.String toString(boolean detailed)
          Returns a string representation of this ReceiptRequest.
 
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 ReceiptRequest attribute. The corresponding OID string is "1.2.840.113549.1.9.16.2.1".


UP_RECEIPTS_TO

public static final int UP_RECEIPTS_TO
Upper bound (16) for the number of user(s) that may be listed in the receiptsTo field to identify the user(s) to whom the identified recipients should send signed receipts.

See Also:
Constant Field Values
Constructor Detail

ReceiptRequest

public ReceiptRequest()
Empty default constructor. Required for dynamic object creation. Shall NOT be used by an application.


ReceiptRequest

public ReceiptRequest(ContentIdentifier signedContentIdentifier,
                      ReceiptsFrom receiptsFrom,
                      GeneralNames[] receiptsTo)
Creates an ReceiptRequest from given content identifier, receiptsFrom and receiptsTo values.

Parameters:
signedContentIdentifier - the signed content identifier identifying the message
receiptsFrom - from whom to request receipts
receiptsTo - to whom identified recipients should send signed receipts

ReceiptRequest

public ReceiptRequest(ContentIdentifier signedContentIdentifier,
                      ReceiptsFrom receiptsFrom,
                      java.lang.String[] receiptsToAddresses)
Creates an ReceiptRequest from given content identifier, receiptsFrom and receiptsTo addresses. This constructor may be used to immediately supply the email addresses of the signed receipt recipients. The required GeneralNames structures are internally created (for each email address one GeneralNames with only one GeneralName entry of type rfc822Name).

Parameters:
signedContentIdentifier - the signed content identifier identifying the message
receiptsFrom - from whom to request receipts
receiptsToAddresses - to whom identified recipients should send signed receipts

ReceiptRequest

public ReceiptRequest(ASN1Object obj)
               throws CodingException
Creates an ReceiptRequest from its ASN.1 representation.

Parameters:
obj - the ReceiptRequest as ASN1Object
Throws:
CodingException
Method Detail

getSignedContentIdentifier

public ContentIdentifier getSignedContentIdentifier()
Returns the signed content identifier.

Returns:
the signed content identifier identifying the message

getReceiptsFrom

public ReceiptsFrom getReceiptsFrom()
Returns the receiptsFrom.

Returns:
from whom to request a signed receipt

getReceiptsTo

public GeneralNames[] getReceiptsTo()
Returns the receiptsTo.

Returns:
to whom identified recipients should send a signed receipt

getReceiptsToAddresses

public java.lang.String[] getReceiptsToAddresses()
Returns all receiptsTo email addresses included in this ReceiptRequest.

This method searches the receiptsTo GeneralNames for all GeneralName objects of type rfc822Name. Any GeneralName of type rfc822Name contributes to the String array of email addresses returned by this method.

Returns:
the email addresses of the receiptsTo members

equals

public boolean equals(java.lang.Object obj)
Compares this ReceiptRequest to the specified object.

Specified by:
equals in class ESSAttributeValue
Parameters:
obj - the object to compare this ReceiptRequest against.
Returns:
true, if the given object is equal to this ReceiptRequest, 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
Decodes the given ASN.1 ReceiptRequest object for parsing the internal structure.

Parameters:
obj - the ReceiptRequest as ASN1Object
Throws:
CodingException - if the encoding is invalid

toASN1Object

public ASN1Object toASN1Object()
                        throws CodingException
Returns this ReceiptRequest as ASN1Object.

Returns:
this ReceiptRequest as ASN1Object
Throws:
CodingException

getAttributeType

public ObjectID getAttributeType()
Returns the OID identifying the ReceiptRequest attribute type.

Specified by:
getAttributeType in class AttributeValue
Returns:
the OID identifying the ReceiptRequest attribute type.

toString

public java.lang.String toString()
Returns a string representation of this ReceiptRequest.

Specified by:
toString in class AttributeValue
Returns:
a string representation of this ReceiptRequest

toString

public java.lang.String toString(boolean detailed)
Returns a string representation of this ReceiptRequest.

Parameters:
detailed - whether to give detailed information
Returns:
a string representation of this ReceiptRequest

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