Receipt (6.1 API Documentation)

java.lang.Object
- iaik.smime.ess.Receipt

All Implemented Interfaces:

Content, ContentStream
```
public class Receipt
extends java.lang.Object
implements Content
```
The S/MIMEv3 ESS Receipt content type.
The Enhanced Security Services for S/MIMEv3 (ESS) (RFC 2634) specifies the Receipt content type to be set as content of a SignedData which shall be sent in response to a ReceiptRequest received:
```
 Receipt ::= SEQUENCE {
   version ESSVersion,
   contentType ContentType,
   signedContentIdentifier ContentIdentifier,
   originatorSignatureValue OCTET STRING }
 
 id-ct-receipt OBJECT IDENTIFIER ::= { iso(1) member-body(2) us(840)
   rsadsi(113549) pkcs(1) pkcs-9(9) smime(16) id-ct(1) 1}

 ESSVersion ::= INTEGER  { v1(1) }
 
```
When receiving a SignedData having any SignerInfo holding a ReceiptRequest the recipient first has to check if all ReceiptRequests contained in any of the SignerInfos are identical. According to the rules given in RFC 2634, section 2.3, the recipient then checks if it is requested to create signed receipt(s) to be sent to dedicated user(s). If a signed receipt has to be sent, the recipient performs the following steps for creating the signed receipt and setting it as content of a SignedData object ("signedData/Receipt", see RFC 2634, section 2.4):
1. The signature of the original signedData signerInfo that includes the receiptRequest signed attribute MUST be successfully verified before creating the signedData/Receipt.
  - The content of the original signedData object is digested as described in CMS (RFC 5652). The resulting digest value is then compared with the value of the messageDigest attribute included in the signedAttributes of the original signedData signerInfo. If these digest values are different, then the signature verification process fails and the signedData/Receipt MUST NOT be created.
  - The ASN.1 DER encoded signedAttributes (including messageDigest, receiptRequest and, possibly, other signed attributes) in the original signedData signerInfo are digested as described in CMS (RFC 5652). The resulting digest value, called msgSigDigest, is then used to verify the signature of the original signedData signerInfo. If the signature verification fails, then the signedData/Receipt MUST NOT be created.
2. A Receipt structure is created.
  - The value of the Receipt version field is set to 1.
  - The object identifier from the contentType attribute included in the original signedData signerInfo that includes the receiptRequest attribute is copied into the Receipt contentType.
  - The original signedData signerInfo receiptRequest signedContentIdentifier is copied into the Receipt signedContentIdentifier.
  - The signature value from the original signedData signerInfo that includes the receiptRequest attribute is copied into the Receipt originatorSignatureValue.
3. The Receipt structure is ASN.1 DER encoded to produce a data stream, D1.
4. D1 is digested. The resulting digest value is included as the messageDigest attribute in the signedAttributes of the signerInfo which will eventually contain the signedData/Receipt signature value.
5. The digest value (msgSigDigest) calculated in Step 1 to verify the signature of the original signedData signerInfo is included as the msgSigDigest attribute in the signedAttributes of the signerInfo which will eventually contain the signedData/Receipt signature value.
6. A contentType attribute including the id-ct-receipt object identifier MUST be created and added to the signed attributes of the signerInfo which will eventually contain the signedData/Receipt signature value.
7. A signingTime attribute indicating the time that the signedData/Receipt is signed SHOULD be created and added to the signed attributes of the signerInfo which will eventually contain the signedData/Receipt signature value. Other attributes (except receiptRequest) may be added to the signedAttributes of the signerInfo.
8. The signedAttributes (messageDigest, msgSigDigest, contentType and, possibly, others) of the signerInfo are ASN.1 DER encoded and digested as described in CMS (RFC 5652). The resulting digest value is used to calculate the signature value which is then included in the signedData/Receipt signerInfo.
9. The ASN.1 DER encoded Receipt content MUST be directly encoded within the signedData encapContentInfo eContent OCTET STRING defined in CMS (RFC 5652). The id-ct-receipt object identifier MUST be included in the signedData encapContentInfo eContentType. This results in a single ASN.1 encoded object composed of a signedData including the Receipt content. The Data content type MUST NOT be used. The Receipt content MUST NOT be encapsulated in a MIME header or any other header prior to being encoded as part of the signedData object.
10. The signedData/Receipt is then put in an application/pkcs7-mime MIME wrapper with the smime-type parameter set to "signed-receipt". This will allow for identification of signed receipts without having to crack the ASN.1 body. The smime-type parameter would still be set as normal in any layer wrapped around this message.
11. If the signedData/Receipt is to be encrypted within an envelopedData object, then an outer signedData object MUST be created that encapsulates the envelopedData object, and a contentHints attribute with contentType set to the id-ct-receipt object identifier MUST be included in the outer signedData SignerInfo signedAttributes. When a receiving agent processes the outer signedData object, the presence of the id-ct-receipt OID in the contentHints contentType indicates that a signedData/Receipt is encrypted within the envelopedData object encapsulated by the outer signedData.
When receiving a signed receipt the following steps have to be performed for validating the signed receipt (see RFC 2634, section 2.6):
1. ASN.1 decode the signedData object including the Receipt content.
2. Extract the contentType, signedContentIdentifier, and originatorSignatureValue from the decoded Receipt structure to identify the original signedData signerInfo that requested the signedData/Receipt.
3. Acquire the message signature digest value calculated by the sender to generate the signature value included in the original signedData signerInfo that requested the signedData/Receipt.
  - If the sender-calculated message signature digest value has been saved locally by the sender, it must be located and retrieved.
  - If it has not been saved, then it must be re-calculated based on the original signedData content and signedAttributes as described in CMS (RFC 5652).
4. The message signature digest value calculated by the sender is then compared with the value of the msgSigDigest signedAttribute included in the signedData/Receipt signerInfo. If these digest values are identical, then that proves that the message signature digest value calculated by the recipient based on the received original signedData object is the same as that calculated by the sender. This proves that the recipient received exactly the same original signedData content and signedAttributes as sent by the sender because that is the only way that the recipient could have calculated the same message signature digest value as calculated by the sender. If the digest values are different, then the signedData/Receipt signature verification process fails.
5. Acquire the digest value calculated by the sender for the Receipt content constructed by the sender (including the contentType, signedContentIdentifier, and signature value that were included in the original signedData signerInfo that requested the signedData/Receipt).
  - If the sender-calculated Receipt content digest value has been saved locally by the sender, it must be located and retrieved.
  - If it has not been saved, then it must be re-calculated. As described in section above, step 2, create a Receipt structure including the contentType, signedContentIdentifier and signature value that were included in the original signedData signerInfo that requested the signed receipt. The Receipt structure is then ASN.1 DER encoded to produce a data stream which is then digested to produce the Receipt content digest value.
6. The Receipt content digest value calculated by the sender is then compared with the value of the messageDigest signedAttribute included in the signedData/Receipt signerInfo. If these digest values are identical, then that proves that the values included in the Receipt content by the recipient are identical to those that were included in the original signedData signerInfo that requested the signedData/Receipt. This proves that the recipient received the original signedData signed by the sender, because that is the only way that the recipient could have obtained the original signedData signerInfo signature value for inclusion in the Receipt content. If the digest values are different, then the signedData/Receipt signature verification process fails.
7. The ASN.1 DER encoded signedAttributes of the signedData/Receipt signerInfo are digested as described in CMS (RFC 5652).
8. The resulting digest value is then used to verify the signature value included in the signedData/Receipt signerInfo. If the signature verification is successful, then that proves the integrity of the signedData/receipt signerInfo signedAttributes and authenticates the identity of the signer of the signedData/Receipt signerInfo. Note that the signedAttributes include the recipient-calculated Receipt content digest value (messageDigest attribute) and recipient-calculated message signature digest value (msgSigDigest attribute). Therefore, the aforementioned comparison of the sender-generated and recipient-generated digest values combined with the successful signedData/Receipt signature verification proves that the recipient received the exact original signedData content and signedAttributes (proven by msgSigDigest attribute) that were signed by the sender of the original signedData object (proven by messageDigest attribute). If the signature verification fails, then the signedData/Receipt signature verification process fails.
When creating a new Receipt you may specify the content type, signed content identifier and originator signature value immediately:
```
 ObjectID contentType = ...;
 ContentIdentifier contentIdentifier = ...;
 byte[] originatorSignatureValue = ...;
 Receipt Receipt = 
   new Receipt(contentType, contentIdentifier, originatorSignatureValue);
 
```
Or you may create a Receipt from a SignerInfo letting the constructor get the required information from the SignerInfo to set the fields of the Receipt as required:
```
 SignerInfo signerInfo = ...;
 Receipt receipt = new Receipt(signerInfo);
 
```
See Also:

ReceiptRequest, ContentIdentifier, SignerInfo, SignedData

Field Summary

Fields
Modifier and Type Field and Description

static iaik.asn1.ObjectID oid
The content type object identifier of the Receipt structure.

Fields
Modifier and Type	Field and Description
`static iaik.asn1.ObjectID`	`oid` The content type object identifier of the `Receipt` structure.

Constructor Summary

Constructors
Constructor and Description
`Receipt()` Empty default constructor.
`Receipt(iaik.asn1.ASN1Object obj)` Creates an Receipt from its ASN.1 representation.
`Receipt(java.io.InputStream is)` Creates a Receipt from an input stream supplying the DER encoded Receipt.
`Receipt(iaik.asn1.ObjectID contentType, ContentIdentifier signedContentIdentifier, byte[] originatorSignatureValue)` Creates an Receipt from given content type, content identifier and originator signature value.
`Receipt(SignerInfo signerInfo)` Creates an Receipt from the given SignerInfo.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`void`	`decode(iaik.asn1.ASN1Object obj)` Decodes the given ASN.1 `Receipt` object for parsing the internal structure.
`void`	`decode(java.io.InputStream is)` Reads and decodes a DER encoded Receipt from the given input stream.
`boolean`	`equals(java.lang.Object obj)` Compares this `Receipt` to the specified object.
`int`	`getBlockSize()` Returns -1.
`iaik.asn1.ObjectID`	`getContentType()` Returns the ESS Receipt (id-cd-receipt) content type object identifier.
`byte[]`	`getEncoded()` DER encodes this ESS `Receipt` object.
`byte[]`	`getOriginatorSignatureValue()` Returns the originator signature value.
`iaik.asn1.ObjectID`	`getReceiptContentType()` Returns the content type.
`SecurityProvider`	`getSecurityProvider()` Returns null since no SecurityProvider is required by this class.
`ContentIdentifier`	`getSignedContentIdentifier()` Returns the signed content identifier.
`int`	`getVersion()` Gets the ESSVersion number.
`int`	`hashCode()` Returns a hashcode for this `Receipt`.
`void`	`setBlockSize(int blockSize)` Does nothing.
`void`	`setSecurityProvider(SecurityProvider securityProvider)` Does nothing since no SecurityProvider is required by this class.
`iaik.asn1.ASN1Object`	`toASN1Object()` Returns this Receipt as ASN1Object.
`java.lang.String`	`toString()` Returns a string representation of this Receipt.
`java.lang.String`	`toString(boolean detailed)` Returns a string representation of this Receipt.
`void`	`writeTo(java.io.OutputStream os)` Writes this ESS `Receipt` object DER encoded to the given output stream.

Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

- Field Detail
  - oid
```
public static final iaik.asn1.ObjectID oid
```
    The content type object identifier of the Receipt structure. The corresponding OID string is "1.2.840.113549.1.9.16.1.1".
- Constructor Detail
  - Receipt
```
public Receipt()
```
    Empty default constructor. Required for dynamic object creation. Shall NOT be used by an application.
  - Receipt
```
public Receipt(iaik.asn1.ObjectID contentType,
               ContentIdentifier signedContentIdentifier,
               byte[] originatorSignatureValue)
```
    Creates an Receipt from given content type, content identifier and originator signature value.
    
    Parameters:
    
    contentType - the content type of the of the SignedData to be linked to
    
    signedContentIdentifier - the signed content identifier of the SignedData to be linked to
    
    originatorSignatureValue - the signature value of the SignedData to be linked to
  - Receipt
```
public Receipt(SignerInfo signerInfo)
        throws ESSException
```
    Creates an Receipt from the given SignerInfo.
    This constructor follows the instructions given in RFC 2634, section 2.4, 2:
    - The value of the Receipt version field is set to 1.
    - The object identifier from the contentType attribute included in the original signedData signerInfo that includes the receiptRequest attribute is copied into the Receipt contentType.
    - The original signedData signerInfo receiptRequest signedContentIdentifier is copied into the Receipt signedContentIdentifier.
    - The signature value from the original signedData signerInfo that includes the receiptRequest attribute is copied into the Receipt originatorSignatureValue.
    This constructor just creates a Receipt as described above, but does not perform any signature or ReceiptRequest validation.
    Parameters:
    
    signerInfo - the signerInfo from which to create a Receipt
    
    Throws:
    
    ESSException - if the Receipt cannot be created for some reason, e.g. no ReceiptRequest is included in the supplied SignerInfo
  - Receipt
```
public Receipt(java.io.InputStream is)
        throws java.io.IOException,
               CMSParsingException
```
    Creates a Receipt from an input stream supplying the DER encoded Receipt.
    
    Parameters:
    
    is - the input stream from where to read the encoded Receipt
    
    Throws:
    
    CMSParsingException - if the object cannot be paresd
    
    java.io.IOException - if an error occurs while reading from the stream
  - Receipt
```
public Receipt(iaik.asn1.ASN1Object obj)
        throws CMSParsingException
```
    Creates an Receipt from its ASN.1 representation.
    
    Parameters:
    
    obj - the Receipt as ASN1Object
    
    Throws:
    
    CMSParsingException - if the object cannot be paresd
- Method Detail
  - setSecurityProvider
```
public void setSecurityProvider(SecurityProvider securityProvider)
```
    Does nothing since no SecurityProvider is required by this class. Only required to implement the ContentStream interface.
    
    Parameters:
    
    securityProvider - the SecurityProvider to be set; ignored
  - getSecurityProvider
```
public SecurityProvider getSecurityProvider()
```
    Returns null since no SecurityProvider is required by this class. Only required to implement the ContentStream interface.
    
    Returns:
    
    null
  - getVersion
```
public int getVersion()
```
    Gets the ESSVersion number.
    
    Returns:
    
    the ESSVersion number (1) this Receipt conforms to
  - getBlockSize
```
public int getBlockSize()
```
    Returns -1. Only implements the same name method of the Content interface, but has no meaning here.
    
    Specified by:
    
    getBlockSize in interface ContentStream
    
    Returns:
    
    -1
  - setBlockSize
```
public void setBlockSize(int blockSize)
```
    Does nothing. Only implements the same name method of the Content interface., but has no meaning here.
    
    Specified by:
    
    setBlockSize in interface ContentStream
    
    Parameters:
    
    blockSize - the block size; ignored here
  - getReceiptContentType
```
public iaik.asn1.ObjectID getReceiptContentType()
```
    Returns the content type.
    Attention! The OID returned by this method is the content type as given in the second component of an Receipt object and represents the value of the contentType attribute included in the original signedData signerInfo that includes the receiptRequest:
```
 Receipt ::= SEQUENCE {
   version ESSVersion,
   contentType ContentType,
   signedContentIdentifier ContentIdentifier,
   originatorSignatureValue OCTET STRING }
 
```
    It has to be distinguished from the content type returned by method getContentType which always returns the id-cd-receipt oid.
    Returns:
    
    the receipt content type
  - getSignedContentIdentifier
```
public ContentIdentifier getSignedContentIdentifier()
```
    Returns the signed content identifier.
    
    Returns:
    
    the signed content identifier
  - getOriginatorSignatureValue
```
public byte[] getOriginatorSignatureValue()
```
    Returns the originator signature value.
    
    Returns:
    
    the originator signature value
  - equals
```
public boolean equals(java.lang.Object obj)
```
    Compares this Receipt to the specified object.
    
    Overrides:
    
    equals in class java.lang.Object
    
    Parameters:
    
    obj - the object to compare this Receipt against.
    
    Returns:
    
    true, if the given object is equal to this Receipt, false otherwise
  - hashCode
```
public int hashCode()
```
    Returns a hashcode for this Receipt.
    
    Overrides:
    
    hashCode in class java.lang.Object
    
    Returns:
    
    a hashcode for this Receipt
  - decode
```
public void decode(java.io.InputStream is)
            throws java.io.IOException,
                   CMSParsingException
```
    Reads and decodes a DER encoded Receipt from the given input stream.
    
    Specified by:
    
    decode in interface ContentStream
    
    Parameters:
    
    is - the input stream from where to read the encoded Receipt
    
    Throws:
    
    CMSParsingException - if the object cannot be paresd
    
    java.io.IOException - if an error occurs while reading from the stream
  - decode
```
public void decode(iaik.asn1.ASN1Object obj)
            throws CMSParsingException
```
    Decodes the given ASN.1 Receipt object for parsing the internal structure.
    
    Specified by:
    
    decode in interface Content
    
    Parameters:
    
    obj - the Receipt as ASN1Object
    
    Throws:
    
    CMSParsingException - if the object cannot be paresd
  - toASN1Object
```
public iaik.asn1.ASN1Object toASN1Object()
```
    Returns this Receipt as ASN1Object.
    
    Specified by:
    
    toASN1Object in interface ContentStream
    
    Returns:
    
    this Receipt as ASN1Object
  - getContentType
```
public iaik.asn1.ObjectID getContentType()
```
    Returns the ESS Receipt (id-cd-receipt) content type object identifier.
    Attention! This method implements the smae name method of the Content interface to always return the id-ct-receipt oid. The content type returned by this method has to be distinguished from the content type returned by method getReceiptContentType() which returns the content type as given in the second component of an Receipt object:
```
 Receipt ::= SEQUENCE {
   version ESSVersion,
   contentType ContentType,
   signedContentIdentifier ContentIdentifier,
   originatorSignatureValue OCTET STRING }
 
```
    Specified by:
    
    getContentType in interface ContentStream
    
    Returns:
    
    the ESS Receipt (id-cd-receipt) content type object identifier
  - toString
```
public java.lang.String toString()
```
    Returns a string representation of this Receipt.
    
    Overrides:
    
    toString in class java.lang.Object
    
    Returns:
    
    this Receipt as string
  - toString
```
public java.lang.String toString(boolean detailed)
```
    Returns a string representation of this Receipt.
    
    Specified by:
    
    toString in interface ContentStream
    
    Parameters:
    
    detailed - whether to give detailed information
    
    Returns:
    
    this Receipt as string
  - getEncoded
```
public byte[] getEncoded()
                  throws CMSException
```
    DER encodes this ESS Receipt object.
    
    Returns:
    
    the DER encoded Receipt object
    
    Throws:
    
    CMSException - if an encoding error occurs
  - writeTo
```
public void writeTo(java.io.OutputStream os)
             throws java.io.IOException
```
    Writes this ESS Receipt object DER encoded to the given output stream.
    
    Parameters:
    
    os - the output stream to which to encode the Receipt
    
    Throws:
    
    java.io.IOException - if an error occurs during encoding to the stream

Class Receipt

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

oid

Constructor Detail

Receipt

Receipt

Receipt

Receipt

Receipt

Method Detail

setSecurityProvider

getSecurityProvider

getVersion

getBlockSize

setBlockSize

getReceiptContentType

getSignedContentIdentifier

getOriginatorSignatureValue

equals

hashCode

decode

decode

toASN1Object

getContentType

toString

toString

getEncoded

writeTo