iaik.smime.ess
Class ReceiptRequest

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

• receipts from all recipients are requested
• receipts from first tier (recipients that did not receive the message as members of a mailing list) recipients are requested
• receipts from a specific list of recipients are requested

 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