iaik.smime.ess.utils
Class SignedReceipt

java.lang.Object
  iaik.smime.ess.utils.SignedReceipt

public class SignedReceipt
extends java.lang.Object

Utility for parsing a message for an included ReceiptRequest attribute and in return creating a signed Receipt message.

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):

 1. If an mlExpansionHistory attribute is present in the outermost
    signedData block, do one of the following two steps, based on the
    absence or presence of mlReceiptPolicy:

     1.1. If an mlReceiptPolicy value is absent from the last MLData
          element, a Mail List receipt policy has not been specified
          and the processing software SHOULD examine the
          receiptRequest attribute value to determine if a receipt
          should be created and returned.

     1.2. If an mlReceiptPolicy value is present in the last MLData
          element, do one of the following two steps, based on the
          value of mlReceiptPolicy:

         1.2.1. If the mlReceiptPolicy value is none, then the receipt
                policy of the Mail List supersedes the originator
                request for a signed receipt and a signed receipt MUST
                NOT be created.

         1.2.2. If the mlReceiptPolicy value is insteadOf or
                inAdditionTo, the processing software SHOULD examine
                the receiptsFrom value from the receiptRequest
                attribute to determine if a receipt should be created
                and returned. If a receipt is created, the insteadOf
                and inAdditionTo fields identify entities that SHOULD
                be sent the receipt instead of or in addition to the
                originator.

 2. If the receiptsFrom value of the receiptRequest attribute
    allOrFirstTier, do one of the following two steps based on the
    value of allOrFirstTier.

     2.1. If the value of allOrFirstTier is allReceipts, then a signed
          receipt SHOULD be created.

     2.2. If the value of allOrFirstTier is firstTierRecipients, do
          one of the following two steps based on the presence of an
          mlExpansionHistory attribute in an outer signedData block:

         2.2.1. If an mlExpansionHistory attribute is present, then
                this recipient is not a first tier recipient and a
                signed receipt MUST NOT be created.

         2.2.2. If an mlExpansionHistory attribute is not present,
                then a signed receipt SHOULD be created.

 3. If the receiptsFrom value of the receiptRequest attribute is a
    receiptList:
   3.1. If receiptList contains one of the GeneralNames of the
        recipient, then a signed receipt SHOULD be created.

  3.2. If receiptList does not contain one of the GeneralNames of
       the recipient, then a signed receipt MUST NOT be created.
 

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.

    1.1. The content of the original signedData object is digested as
         described in [CMS]. 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.

     1.2. 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]. 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.

     2.1. The value of the Receipt version field is set to 1.

     2.2. The object identifier from the contentType attribute
          included in the original signedData signerInfo that
          includes the receiptRequest attribute is copied into
          the Receipt contentType.

     2.3. The original signedData signerInfo receiptRequest
          signedContentIdentifier is copied into the Receipt
          signedContentIdentifier.

     2.4. 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]. 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]. 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 creating a new SignedReceipt object an application may immediately provide signed inner layer (containing a ReceiptRequest attribute) and (optional) signed outer layer (possibly containing a MLExpansionHistory attribute), or may provide message layers or message Part. In the latter case the layers or part, respectively, are parsed for any inlcuded signed innner or signed outer layer. If the signed inner layer contains a ReceiptRequest attribute, the proceeding above is used to see if a receipt is requested from the ReceiptRequest recipient and to whom a signed receipt shall be sent, if requested. If an outer layer is present and is parsed if it contains a MLExpansionHistory that may supersede the original receipt request or list of intended receipt recipients.
After having successfully created a SignedReceipt any of the following methods may be used for Receipt building:

• createReceipt: creates a Receipt from the information parsed from the received message. This method may be used when needing the raw Receipt only:

   
       // email address of the receipt creator (the one who has received the receipt request)
       String receiptEmailAddress = ...;
       // message containing the receipt request:
       MimeMessage msg = ...;
       SignedReceipt signedReceipt = new SignedReceipt(msg, receiptEmailAddress);
       Receipt receipt = signedReceipt.createReceipt();
       

• createReceiptContent: creates a ReceiptContent from the information parsed from the received message. After having created the ReceiptContent ReceiptContent} an application may set signer information and certificates to finally sent the signed receipt to the intended rscipients, e.g.:

        // email address of the receipt creator (the one who has received the receipt request)
        String receiptEmailAddress = ...;
        // message containing the receipt request:
        MimeMessage msg = ...;
        SignedReceipt signedReceipt = new SignedReceipt(msg, receiptEmailAddress);
        // sendTo is the one to which the receipt should be send
        String sendTo = signedReceipt.getReceiptsToAddressList();
        MimeMessage msg = new MimeMessage(...);
        msg.setFrom(new InternetAddress(receiptEmailAddress));
        msg.setRecipients(Message.RecipientType.TO, InternetAddress.parse(sendTo));
        msg.setSubject(...);
        ...
        ReceiptContent receiptContent = signedReceipt.createReceiptContent();
        // for this simple demo signer = recipient
        receiptContent.setCertificates(...);
        receiptContent.setSigner(...);
        msg.setContent(receiptContent, receiptContent.getContentType());
        receiptContent.setHeaders(msg);
        Transport.send(msg);
        

• createReceiptMessage: creates a receipt message from the information parsed from the received message. The receipt signer information has to be supplied as CMS SignerInfo object, e.g.:

        // email address of the receipt creator (the one who has received the receipt request)
        String receiptEmailAddress = ...;
        // message containing the receipt request:
        MimeMessage msg = ...;
        SignedReceipt signedReceipt = new SignedReceipt(msg, receiptEmailAddress);
        String subject = "...";
        SignerInfo receiptSigner = ...;
        Message msg = signedReceipt.createReceiptMessage(receiptSigner, 
                                                         signerCertificates,
                                                         session,
                                                         subject);
        Transport.send(msg);
        

• createReceiptMessage: creates a receipt message from the information parsed from the received message. The receipt is signed with the given key using the supplied signature algorithm, e.g.:

        // email address of the receipt creator (the one who has received the receipt request)
        String receiptEmailAddress = ...;
        // message containing the receipt request:
        MimeMessage msg = ...;
        SignedReceipt signedReceipt = new SignedReceipt(msg, receiptEmailAddress);
        String subject = "...";
        Message msg = signedReceipt.createReceiptMessage(signerPrivateKey, 
                                                         certificates,
                                                         signerCertificate,
                                                         AlgorithmID.sha256,
                                                         AlgorithmID.rsaEncryption,
                                                         encryptionCertOfSigner,
                                                         true,
                                                         session,
                                                         subject);
        Transport.send(msg);
        

See Also:

Receipt, ReceiptContent, MLExpansionHistory, ESSLayers, ESSLayer, SignedESSLayer

Field Summary

protected java.io.PrintWriter

debugWriter_ Writer to which debug information may be written.

Constructor Summary

SignedReceipt(ESSLayers layers, iaik.asn1.structures.GeneralNames myName)
Creates a SignedReceipt from the given ESS layers.

SignedReceipt(ESSLayers layers, iaik.asn1.structures.GeneralNames myName, java.io.OutputStream debugStream)
Creates a SignedReceipt from the given ESS layers.

SignedReceipt(ESSLayers layers, java.lang.String myEmailAddress)
Creates a SignedReceipt from the given ESS layers.

SignedReceipt(ESSLayers layers, java.lang.String myEmailAddress, java.io.OutputStream debugStream)
Creates a SignedReceipt from the given ESS layers.

SignedReceipt(javax.mail.Part part, iaik.asn1.structures.GeneralNames myName)
Creates a SignedReceipt from the given mail part.

SignedReceipt(javax.mail.Part part, iaik.asn1.structures.GeneralNames myName, java.io.OutputStream debugStream)
Creates a SignedReceipt from the given mail part.

SignedReceipt(javax.mail.Part part, java.lang.String myEmailAddress)
Creates a SignedReceipt from the given mail part.

SignedReceipt(javax.mail.Part part, java.lang.String myEmailAddress, java.io.OutputStream debugStream)
Creates a SignedReceipt from the given mail part.

SignedReceipt(SignedContent innerLayer, SignedContent outerLayer, iaik.asn1.structures.GeneralNames myName)
Creates a SignedReceipt from given inner and outer layer.

SignedReceipt(SignedContent innerLayer, SignedContent outerLayer, iaik.asn1.structures.GeneralNames myName, java.io.OutputStream debugStream)
Creates a SignedReceipt from given inner and outer layer.

SignedReceipt(SignedContent innerLayer, SignedContent outerLayer, java.lang.String myEmailAddress)
Creates a SignedReceipt from given inner and outer layer.

SignedReceipt(SignedContent innerLayer, SignedContent outerLayer, java.lang.String myEmailAddress, java.io.OutputStream debugStream)
Creates a SignedReceipt from given inner and outer layer.

Method Summary

Receipt	createReceipt() Creates a Receipt attribute based on the information parsed from the originator SignerInfo.
ReceiptContent	createReceiptContent() Creates a ReceiptContent based on the information parsed from the originator SignerInfo (got from the inner signed layer of the receipt request conatining message).
javax.mail.internet.MimeMessage	createReceiptMessage(java.security.PrivateKey privateKey, iaik.x509.X509Certificate[] certificates, iaik.x509.X509Certificate signerCertificate, iaik.asn1.structures.AlgorithmID digestAlgorithm, iaik.asn1.structures.AlgorithmID signatureAlgorithm, iaik.x509.X509Certificate encryptionCertificate, boolean includeEncryptionCertIDForMSOE, javax.mail.Session session, java.lang.String subject) Creates a SignedReceipt message based on the information parsed from the originator SignerInfo (got from the inner signed layer of the receipt request containing message).
javax.mail.internet.MimeMessage	createReceiptMessage(SignerInfo receiptSigner, iaik.x509.X509Certificate[] signerCertificates, javax.mail.Session session, java.lang.String subject) Creates a SignedReceipt message based on the information parsed from the originator SignerInfo (got from the inner signed layer of the receipt request conatining message).
MLExpansionHistory	getMLExpansionHistory() Return the MLExpansionHistory attribute of the outer layer.
SignerInfo[]	getOriginatorSignerInfos() Returns all SignerInfos of the original inner SignedData layer that contain a valid ReceiptRequest attribute.
ReceiptRequest	getReceiptRequest() Returns the ReceiptRequest attribute from the originator SignerInfo.
iaik.asn1.structures.GeneralNames[]	getReceiptsTo() Returns the general names this SignedReceipt should be sent to.
java.lang.String[]	getReceiptsToAddresses() Returns the email addresses this SignedReceipt should be sent to.
java.lang.String	getReceiptsToAddressList() Returns the email addresses this SignedReceipt should be sent to.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

debugWriter_

protected java.io.PrintWriter debugWriter_

Writer to which debug information may be written.

Constructor Detail

SignedReceipt

public SignedReceipt(SignedContent innerLayer,
                     SignedContent outerLayer,
                     java.lang.String myEmailAddress)
              throws SignedReceiptException

Creates a SignedReceipt from given inner and outer layer. A ReceiptRequest attribute in the inner layer may indicate that a SignedReceipt has to be sent. A MLExpansionHistory attribute in the outer layer may supersede the receipt request of the sender.

Parameters:

innerLayer - the inner signed layer of a possible multi layer message

outerLayer - the outer signed layer of a possible multi layer message; may be null

myEmailAddress - the email address of the SignedReceipt creator (the one who sends the signed receipt)

Throws:

SignedReceiptException - if the signed receipt creation fails for any reason (e.g. no receipt is requested from the holder of myEmailAddress)

SignedReceipt

public SignedReceipt(SignedContent innerLayer,
                     SignedContent outerLayer,
                     java.lang.String myEmailAddress,
                     java.io.OutputStream debugStream)
              throws SignedReceiptException

Creates a SignedReceipt from given inner and outer layer. A ReceiptRequest attribute in the inner layer may indicate that a SignedReceipt has to be sent. A MLExpansionHistory attribute in the outer layer may supersede the receipt request of the sender.

Parameters:

innerLayer - the inner signed layer of a possible multi layer message

outerLayer - the outer signed layer of a possible multi layer message; may be null

myEmailAddress - the email address of the SignedReceipt creator (the one who sends the signed receipt)

debugStream - the stream to which debug information shall be written; maybe null for disabling debug output

Throws:

SignedReceiptException - if the signed receipt creation fails for any reason (e.g. no receipt is requested from the holder of myEmailAddress)

SignedReceipt

public SignedReceipt(SignedContent innerLayer,
                     SignedContent outerLayer,
                     iaik.asn1.structures.GeneralNames myName)
              throws SignedReceiptException

Creates a SignedReceipt from given inner and outer layer. A ReceiptRequest attribute in the inner layer may indicate that a SignedReceipt has to be sent. A MLExpansionHistory attribute in the outer layer may supersede the receipt request of the sender.

Parameters:

innerLayer - the inner signed layer of a possible multi layer message

outerLayer - the outer signed layer of a possible multi layer message; may be null

myName - the name of the SignedReceipt creator (the one who sends the signed receipt)

Throws:

SignedReceiptException - if the signed receipt creation fails for any reason (e.g. no receipt is requested from the holder of myName)

SignedReceipt

public SignedReceipt(SignedContent innerLayer,
                     SignedContent outerLayer,
                     iaik.asn1.structures.GeneralNames myName,
                     java.io.OutputStream debugStream)
              throws SignedReceiptException

Creates a SignedReceipt from given inner and outer layer. A ReceiptRequest attribute in the inner layer may indicate that a SignedReceipt has to be sent. A MLExpansionHistory attribute in the outer layer may supersede the receipt request of the sender.

Parameters:

innerLayer - the inner signed layer of a possible multi layer message

outerLayer - the outer signed layer of a possible multi layer message; may be null

myName - the name of the SignedReceipt creator (the one who sends the signed receipt)

debugStream - the stream to which debug information shall be written; maybe null for disabling debug output

Throws:

SignedReceiptException - if the signed receipt creation fails for any reason (e.g. no receipt is requested from the holder of myName)

SignedReceipt

public SignedReceipt(ESSLayers layers,
                     java.lang.String myEmailAddress)
              throws SignedReceiptException,
                     ESSLayerException

Creates a SignedReceipt from the given ESS layers. If the given layers contain a signed inner layer, its ReceiptRequest attribute (if included) may indicate that a SignedReceipt has to be sent. If the given layers contain a signed outer layer, its MLExpansionHistory attribute (if included) may supersede the receipt request of the sender.

Parameters:

layers - the ESS layers possibly containing a signed inner and a signed outer layer

myEmailAddress - the email address of the SignedReceipt creator (the one who sends the signed receipt)

Throws:

SignedReceiptException - if the signed receipt creation fails for any reason (e.g. no receipt is requested from the holder of myName, or there is no signed inner layer at all)

ESSLayerException - if the parsing of the layers fails for some reason

SignedReceipt

public SignedReceipt(ESSLayers layers,
                     java.lang.String myEmailAddress,
                     java.io.OutputStream debugStream)
              throws SignedReceiptException,
                     ESSLayerException

Creates a SignedReceipt from the given ESS layers. If the given layers contain a signed inner layer, its ReceiptRequest attribute (if included) may indicate that a SignedReceipt has to be sent. If the given layers contain a signed outer layer, its MLExpansionHistory attribute (if included) may supersede the receipt request of the sender.

Parameters:

layers - the ESS layers possibly containing a signed inner and a signed outer layer

myEmailAddress - the email address of the SignedReceipt creator (the one who sends the signed receipt)

debugStream - the stream to which debug information shall be written; maybe null for disabling debug output

Throws:

SignedReceiptException - if the signed receipt creation fails for any reason (e.g. no receipt is requested from the holder of myName, or there is no signed inner layer at all)

ESSLayerException - if the parsing of the layers fails for some reason

SignedReceipt

public SignedReceipt(ESSLayers layers,
                     iaik.asn1.structures.GeneralNames myName)
              throws SignedReceiptException,
                     ESSLayerException

Creates a SignedReceipt from the given ESS layers. If the given layers contain a signed inner layer, its ReceiptRequest attribute (if included) may indicate that a SignedReceipt has to be sent. If the given layers contain a signed outer layer, its MLExpansionHistory attribute (if included) may supersede the receipt request of the sender.

Parameters:

layers - the ESS layers possibly containing a signed inner and a signed outer layer

myName - the name of the SignedReceipt creator (the one who sends the signed receipt)

Throws:

SignedReceiptException - if the signed receipt creation fails for any reason (e.g. no receipt is requested from the holder of myName, or there is no signed inner layer at all)

ESSLayerException - if the parsing of the layers fails for some reason

SignedReceipt

public SignedReceipt(ESSLayers layers,
                     iaik.asn1.structures.GeneralNames myName,
                     java.io.OutputStream debugStream)
              throws SignedReceiptException,
                     ESSLayerException

Creates a SignedReceipt from the given ESS layers. If the given layers contain a signed inner layer, its ReceiptRequest attribute (if included) may indicate that a SignedReceipt has to be sent. If the given layers contain a signed outer layer, its MLExpansionHistory attribute (if included) may supersede the receipt request of the sender.

Parameters:

layers - the ESS layers possibly containing a signed inner and a signed outer layer

myName - the name of the SignedReceipt creator (the one who sends the signed receipt)

debugStream - the stream to which debug information shall be written; maybe null for disabling debug output

Throws:

SignedReceiptException - if the signed receipt creation fails for any reason (e.g. no receipt is requested from the holder of myName, or there is no signed inner layer at all)

ESSLayerException

SignedReceipt

public SignedReceipt(javax.mail.Part part,
                     java.lang.String myEmailAddress)
              throws SignedReceiptException,
                     ESSLayerException

Creates a SignedReceipt from the given mail part. The part is parsed for its layers. If the layers contain a signed inner layer, its ReceiptRequest attribute (if included) may indicate that a SignedReceipt has to be sent. If the given layers contain a signed outer layer, its MLExpansionHistory attribute (if included) may supersede the receipt request of the sender.

Parameters:

part - the MIME part possibly containing a signed inner and a signed outer layer

myEmailAddress - the email address of the SignedReceipt creator (the one who sends the signed receipt)

Throws:

SignedReceiptException - if the signed receipt creation fails for any reason (e.g. no receipt is requested from the holder of myName, or there is no signed inner layer at all)

ESSLayerException - if an error occurs when parsing/decomposing the part or any of the signatures of a signed layer is invalid

SignedReceipt

public SignedReceipt(javax.mail.Part part,
                     java.lang.String myEmailAddress,
                     java.io.OutputStream debugStream)
              throws SignedReceiptException,
                     ESSLayerException

Creates a SignedReceipt from the given mail part. The part is parsed for its layers. If the layers contain a signed inner layer, its ReceiptRequest attribute (if included) may indicate that a SignedReceipt has to be sent. If the given layers contain a signed outer layer, its MLExpansionHistory attribute (if included) may supersede the receipt request of the sender.

Parameters:

part - the MIME part possibly containing a signed inner and a signed outer layer

myEmailAddress - the email address of the SignedReceipt creator (the one who sends the signed receipt)

debugStream - the stream to which debug information shall be written; maybe null for disabling debug output

Throws:

SignedReceiptException - if the signed receipt creation fails for any reason (e.g. no receipt is requested from the holder of myName, or there is no signed inner layer at all)

ESSLayerException - if an error occurs when parsing/decomposing the part or any of the signatures of a signed layer is invalid

SignedReceipt

public SignedReceipt(javax.mail.Part part,
                     iaik.asn1.structures.GeneralNames myName)
              throws SignedReceiptException,
                     ESSLayerException

Creates a SignedReceipt from the given mail part. The part is parsed for its layers. If the layers contain a signed inner layer, its ReceiptRequest attribute (if included) may indicate that a SignedReceipt has to be sent. If the given layers contain a signed outer layer, its MLExpansionHistory attribute (if included) may supersede the receipt request of the sender.

Parameters:

part - the MIME part possibly containing a signed inner and a signed outer layer

myName - the name of the SignedReceipt creator (the one who sends the signed receipt)

Throws:

SignedReceiptException - if the signed receipt creation fails for any reason (e.g. no receipt is requested from the holder of myName, or there is no signed inner layer at all)

ESSLayerException - if an error occurs when parsing/decomposing the part or any of the signatures of a signed layer is invalid

SignedReceipt

public SignedReceipt(javax.mail.Part part,
                     iaik.asn1.structures.GeneralNames myName,
                     java.io.OutputStream debugStream)
              throws SignedReceiptException,
                     ESSLayerException

Creates a SignedReceipt from the given mail part. The part is parsed for its layers. If the layers contain a signed inner layer, its ReceiptRequest attribute (if included) may indicate that a SignedReceipt has to be sent. If the given layers contain a signed outer layer, its MLExpansionHistory attribute (if included) may supersede the receipt request of the sender.

Parameters:

part - the MIME part possibly containing a signed inner and a signed outer layer

myName - the name of the SignedReceipt creator (the one who sends the signed receipt)

debugStream - the stream to which debug information shall be written; maybe null for disabling debug output

Throws:

SignedReceiptException - if the signed receipt creation fails for any reason (e.g. no receipt is requested from the holder of myName, or there is no signed inner layer at all)

ESSLayerException - if an error occurs when parsing/decomposing the part or any of the signatures of a signed layer is invalid

Method Detail

getReceiptRequest

public ReceiptRequest getReceiptRequest()

Returns the ReceiptRequest attribute from the originator SignerInfo. Based on the information from this request, the signed receipt will be built.

Returns:

the ReceiptRequest attribute from the originator SignerInfo

getMLExpansionHistory

public MLExpansionHistory getMLExpansionHistory()

Return the MLExpansionHistory attribute of the outer layer. Maybe null if there is no outer layer or if the outer layer does not contain a MLExpansionHistory attribute. If present, the MLExpansionHistory may have influence on the receipt content creation procedure (e.g. if it supersedes the original receipt request).

getReceiptsTo

public iaik.asn1.structures.GeneralNames[] getReceiptsTo()

Returns the general names this SignedReceipt should be sent to. The GeneralNames array returned by this method must not necessarily be the same as contained in the receiptsTo field of the ReceiptRequest attribute to which this signed receipt corresponds. Depending on the presence of an outer SignedLayer layer which may contain an MLExpansionHistory attribute an MLReceiptPolicy of IN_ADDITION_TO or INSTEAD_OF may affect the receiptsTo entries.

Returns:

the general names this SignedReceipt should be sent to.

getReceiptsToAddresses

public java.lang.String[] getReceiptsToAddresses()

Returns the email addresses this SignedReceipt should be sent to. The email String array returned by this method must not necessarily be the same as contained in the receiptsTo field of the ReceiptRequest attribute to which this signed receipt corresponds. Depending on the presence of an outer SignedLayer layer which may contain an MLExpansionHistory attribute an MLReceiptPolicy of IN_ADDITION_TO or INSTEAD_OF may affect the receiptsTo entries. This method steps to all receiptsTo GeneralNames and picks any included rfc822name.

Returns:

the email addresses this SignedReceipt should be sent to.

getReceiptsToAddressList

public java.lang.String getReceiptsToAddressList()

Returns the email addresses this SignedReceipt should be sent to. The email address list (as comma separeted String of addresses) returned by this method must not necessarily be the same as contained in the receiptsTo field of the ReceiptRequest attribute to which this signed receipt corresponds. Depending on the presence of an outer SignedLayer layer which may contain an MLExpansionHistory attribute an MLReceiptPolicy of IN_ADDITION_TO or INSTEAD_OF may affect the receiptsTo entries. This method steps to all receiptsTo GeneralNames and picks any included rfc822name.

Returns:

the email addresses this SignedReceipt should be sent to (as comma separeted String of addresses).

getOriginatorSignerInfos

public SignerInfo[] getOriginatorSignerInfos()

Returns all SignerInfos of the original inner SignedData layer that contain a valid ReceiptRequest attribute.

Returns:

all SignerInfos of the original inner SignedData layer that contain a valid ReceiptRequest attribute

createReceipt

public Receipt createReceipt()
                      throws ESSException

Creates a Receipt attribute based on the information parsed from the originator SignerInfo. This method may be used when needing the raw Receipt only:

 
 // email address of the receipt creator (the one who has received the receipt request)
 String receiptEmailAddress = ...;
 // message containing the receipt request:
 MimeMessage msg = ...;
 SignedReceipt signedReceipt = new SignedReceipt(msg, receiptEmailAddress);
 Receipt receipt = signedReceipt.createReceipt();
 

Returns:

the newly created Receipt attribute.

Throws:

ESSException - if an error occurs when creating the Receipt attribute (e.g. no originator SignerInfo has been obtained from the signed inner layer, or no ReceiptRequest is included in the originator SignerInfo)

createReceiptContent

public ReceiptContent createReceiptContent()
                                    throws ESSException

Creates a ReceiptContent based on the information parsed from the originator SignerInfo (got from the inner signed layer of the receipt request conatining message). After having created the ReceiptContent an application may set signer information and certificates to finally sent the SignedReceipt to the intended rscipients, e.g.:

 // email address of the receipt creator (the one who has received the receipt request)
 String receiptEmailAddress = ...;
 // message containing the receipt request:
 MimeMessage msg = ...;
 SignedReceipt signedReceipt = new SignedReceipt(msg, receiptEmailAddress);
 // sendTo is the one to which the receipt should be send
 String sendTo = signedReceipt.getReceiptsToAddressList();
 MimeMessage msg = new MimeMessage(...);
 msg.setFrom(new InternetAddress(receiptEmailAddress));
 msg.setRecipients(Message.RecipientType.TO, InternetAddress.parse(sendTo));
 msg.setSubject(...);
 ...
 ReceiptContent receiptContent = signedReceipt.createReceiptContent();
 // for this simple demo signer = recipient
 receiptContent.setCertificates(...);
 receiptContent.setSigner(...);
 msg.setContent(receiptContent, receiptContent.getContentType());
 receiptContent.setHeaders(msg);
 Transport.send(msg);
 

Returns:

the newly created ReceiptContent

Throws:

ESSException - if an error occurs when creating the ReceiptContent (e.g. no originator SignerInfo has been obtained from the signed inner layer, or no ReceiptRequest is included in the originator SignerInfo)

createReceiptMessage

public javax.mail.internet.MimeMessage createReceiptMessage(SignerInfo receiptSigner,
                                                            iaik.x509.X509Certificate[] signerCertificates,
                                                            javax.mail.Session session,
                                                            java.lang.String subject)
                                                     throws javax.mail.MessagingException,
                                                            ESSException

Creates a SignedReceipt message based on the information parsed from the originator SignerInfo (got from the inner signed layer of the receipt request conatining message). The receipt signer information has to be supplied as CMS SignerInfo object, e.g.:

 // email address of the receipt creator (the one who has received the receipt request)
 String receiptEmailAddress = ...;
 // message containing the receipt request:
 MimeMessage msg = ...;
 SignedReceipt signedReceipt = new SignedReceipt(msg, receiptEmailAddress);
 String subject = "...";
 SignerInfo receiptSigner = ...;
 Message msg = signedReceipt.createReceiptMessage(receiptSigner, 
                                                  signerCertificates,
                                                  session,
                                                  subject);
 Transport.send(msg);
 

Parameters:

receiptSigner - information about the signer of the receipt

signerCertificates - the certificates of the receipt signer

session - the current mail session

subject - the subject header of the receipt message

Returns:

the newly created SignedReceipt message

Throws:

javax.mail.MessagingException - if an error occurs when creating the message

ESSException - if an error occurs when creating the Receipt message (e.g. no originator SignerInfo has been obtained from the signed inner layer, or no ReceiptRequest is included in the originator SignerInfo)

createReceiptMessage

public javax.mail.internet.MimeMessage createReceiptMessage(java.security.PrivateKey privateKey,
                                                            iaik.x509.X509Certificate[] certificates,
                                                            iaik.x509.X509Certificate signerCertificate,
                                                            iaik.asn1.structures.AlgorithmID digestAlgorithm,
                                                            iaik.asn1.structures.AlgorithmID signatureAlgorithm,
                                                            iaik.x509.X509Certificate encryptionCertificate,
                                                            boolean includeEncryptionCertIDForMSOE,
                                                            javax.mail.Session session,
                                                            java.lang.String subject)
                                                     throws javax.mail.MessagingException,
                                                            ESSException

Creates a SignedReceipt message based on the information parsed from the originator SignerInfo (got from the inner signed layer of the receipt request containing message). The receipt is signed with the given key using the supplied signature algorithm, e.g.:

 // email address of the receipt creator (the one who has received the receipt request)
 String receiptEmailAddress = ...;
 // message containing the receipt request:
 MimeMessage msg = ...;
 SignedReceipt signedReceipt = new SignedReceipt(msg, receiptEmailAddress);
 String subject = "...";
 Message msg = signedReceipt.createReceiptMessage(signerPrivateKey, 
                                                  signerCertificates,
                                                  AlgorithmID.sha256,
                                                  AlgorithmID.rsaEncryption,
                                                  encryptionCertOfSigner,
                                                  true,
                                                  session,
                                                  subject);
 Transport.send(msg);
 

When using this method to create a SignedRecipt message, the following attributes are set for the receipt SignerInfo:

• Content-Type (ESS receipt)
• Signing-Time
• S/MIME Capabilities specifying the follwing symmetric ciphers:
  • aes256_CBC (AES-256 in CBC mode)
  • aes128_CBC (AES-128 in CBS mode)
  • des_EDE3_CBC (TripleDes in CBC mode)
  • des_CBC (DES in CBC mode)
  • rc2_CBC (RC2 in CBC mode with 128, 64 or 40 bit key)
• SMIMEEncryptionKeyPreference, if encryptionCertificate is not null
• a private MS attribute ("1.3.6.1.4.1.311.16.4") identifying the encryption cert if if encryptionCertificate is not null and includeEncryptionCertIDForMSOE allowing MSOE to recognize the encryption certificate is different certs are used for signing and encryption
• ESS MsgSigDigest representing the digest value on the original content

The PKCS#9 message digest attribute automatically will be added later, during the data is written to a stream, and after hash calculation is completed.

Inclusion of a special private Microsoft signed attribute (type: 1.3.6.1.4.1.311.16.4) for identifying encryption certificate of the sender by IssuerAndSerialNumber might be useful to tell Outlook Express the encryption certificate to be used if separate certificates are used for signing and encryption. If you want to include this attribute, set includeEncryptionCertIDForMSOE to true and supply the IssuerAndSerialNumber of the encryption certificate ("encrypter").

Parameters:

privateKey - the private key to sign the content

certificates - the (signing and possibly encryption) certificates of the signer;

signerCertificate - the certificate of the signer

digestAlgorithm - the digest algorithm; default: SHA-256 (used, if null)

signatureAlgorithm - the signature algorithm; default: rsaEncryption (used, if null); Attention! use AlgorithmID.rsaEncryption for RSA signing!

encryptionCertificate - the encryption certificate of the sender (or null if signing and encryption cert are the same or no encryption certificate shall be indicated)

includeEncryptionCertIDForMSOE - if true, a private MS attribute will be included allowing MSOE to recognize the encryption cert of the signer if using different certs for signing/encryption

session - the current mail session

subject - the subject header of the receipt message

Returns:

the newly created SignedReceipt message

Throws:

javax.mail.MessagingException - if an error occurs when creating the message

ESSException - if an error occurs when creating the Receipt message (e.g. no originator SignerInfo has been obtained from the signed inner layer, or no ReceiptRequest is included in the originator SignerInfo)