iaik.smime

Class SignedContent

java.lang.Object

jakarta.mail.Multipart

jakarta.mail.internet.MimeMultipart

iaik.smime.SMimeMultipart

iaik.smime.SignedContent

All Implemented Interfaces:

SMimeContentType

public class SignedContent
extends SMimeMultipart
implements SMimeContentType

This class can be used to create S/MIME signed emails in combination with the jakarta.mail package.

S/MIME (Secure/Multipurpose Internet Mail Extensions) provides a consistent way to send and receive secure MIME data. Based on the popular Internet MIME standard, S/MIME provides the following cryptographic security services for electronic messaging applications: authentication, message integrity and non-repudiation of origin (using digital signatures) and privacy and data security (using encryption) (see S/MIME Version 3 Message Specification).

This class supports the creation and handling of S/MIME signed messages in combination with the jakarta.mail architecture. For creating and working with encrypted S/MIME messages, use the EncryptedContent class of the iaik.smime package.

S/MIME provides two formats for signed messages:

• application/pkcs7-mime and SignedData (or application/x-pkcs7-mime for early implementations)
• multipart/signed

The first format (application/pkcs7-mime and SignedData) processes the whole (prepared) MIME entity to be signed into a CMS object of type SignedData which subsequently is inserted into an application/pkcs7-mime MIME entity. The smime-type parameter for messages signed using this format is "signed-data", the file extension is ".p7m" (see S/MIME Version 3 Message Specification). The "Content-" headers of a sample message would look like:

 Content-Type: application/pkcs7-mime; smime-type="signed-data";
     name="smime.p7m"
 Content-Transfer-Encoding: base64
 Content-Disposition: attachment;
     filename="smime.p7m"

 fgwehds...

 

For viewing a message that is signed using this format, a recipient must take care for an S/MIME aware mail client.

The second format (multipart/signed) makes use of the multipart/signed MIME type, consisting of two parts. The first part contains the MIME entity to be signed, and the second part contains the signature, which is a CMS (Cryptographic Message Syntax) detached signature, inserted into a MIME entity of type application/pkcs7-signature (or application/x-pkcs7-signature for early implementations) leaving the ContentInfo (content) field of the SignedData} object empty. The multipart/signed Content type requires two parameters (see S/MIME Version 3 Message Specification):

• protocol (value = "application/pkcs7-signature" - or "application/x-pkcs7-signature" for early implementations)
• micalg (value = name of the message digest algorithm used for computing the message integrity check (MIC) over the body part; possible values: md5, sha1, or any other (i.e. unknown))

The "Content-" headers of a sample message would look like:

 Content-Type: multipart/signed;
     protocol="application/pkcs7-signature";
     micalg=sha1;
     boundary="----=_NextPart_000_00AA_01BD7FE8.1CD08610"

 ------_NextPart_000_00AA_01BD7FE8.1CD08610
 Content-Type: text/plain  ;
     charset="iso-8859-1"
 Content-Transfer-Encoding: 8bit

 This is a clear-signed message.

 ------_NextPart_000_00AA_01BD7FE8.1CD08610
 Content-Type: application/pkcs7-signature;
     name=smime.p7s
 Content-Transfer-Encoding: base64
 Content-Disposition: attachment;
     filename=smime.p7s

 sdefqj...

 ------_NextPart_000_00AA_01BD7FE8.1CD08610--
 

Messages signed using this format can be viewed by the recipient, regardless of being equipped with S/MIME aware software.

This class supports both formats, application/x-pkcs7-mime and multipart/signed. For distinguishing between the two formats when creating a new SignedContent object using the SignedContent(boolean implicit) constructor, the implicit parameter has to be set either to true or to false, depending on whether to use the application/x-pkcs7-mime format or the multipart/signed format:

 SignedContent sc = new SignedContent(true);
   respectively
 SignedContent sc = new SignedContent(false);
 

In the first case, a jakarta.mail.internet.ContentType (representing a MIME content type) object is created setting the primary (media) type to "application", and the sub type to "x-pkcs7-mime". The signature will be "carried" by a SMimeSigned object including the signed message in the inherent SignedData structure.

In the second case, the primary (media) type of the new created jakarta.mail.internet.ContentType object is set to "multipart", and the sub type is set to "signed". The required multipart/signed parameters protocol and micalg specify the "application/x-pkcs7-signature" type for leaving the ContentInfo field of the signature carrying SMimeSigned --> SignedData object empty, and the "SHA-1" (FIPS PUB 180-1) message digest algorithm to be used for MIC computation.

When creating an implicit message you also may wish to set the smime-type parameter to signed-data or certs-only, depending what kind of message to be sent:

 SignedContent sc = new SignedContent(true, SignedContent.SIGNED_DATA);
 

respectively

 SignedContent sc = new SignedContent(true, SignedContent.CERTS_ONLY);
 

For signing some message to be sent using the features of the MIME implementing jakarta.mail.internet package, first create an (either implicit or explicit) SignedContent object, supply the content and sign it with your private key. Subsequently incorporate this SignedContent object into a jakarta.mail.internet.MimeMessage by calling a proper setContent method. As usually, finally the message is sent by calling Transport.send(msg):

 SignedContent sc = new SignedContent(false);
 sc.setContent(...);
 sc.setCertificates(certificates);
 sc.addSigner(privateKey, signerCertificate);
 ...
 MimeMessage msg = new MimeMessage(session);
 ...
 set sender, recipient(s), subject, ...
 ...
 msg.setContent(sc, sc.getContentType());
 Transport.send(msg);
 

The recipient verifies a S/MIME signed message by calling a proper verify method, depending on whether the signer´s certificate list is included in the received message or not, or if there more than only one signers on the content. If not, the signer´s public key explicitly has to be supplied. When certificates are included, the verify() method returns the signer´s certificate if the verification process turns out that the signature is correct. If the verification process fails, a SignatureException is thrown, e.g.:

 SignedContent sc = (SignedContent)msg.getContent();
 try {
    X509Certificate signer = sc.verify();
    System.out.println("This message is signed from: "+signer.getSubjectDN());
 } catch (java.security.SignatureException ex) {
    ...
 }
 // get the content:
 Object content = sc.getContent();
 ...
 

For more information about the JakartaMail architecture, consult Jakarta Mail specification. Note, that JakartaMail uses the Jakarta Activation Framework (JAF) for encapsulating the message data. To confirm with the JAF, this class also supports a setDataHandler method for supplying the content to be signed, wrapped by a jakarta.activation.DataHandler, e.g.:

 MimeBodyPart mbp1 = new SMimeBodyPart();
 mbp1.setText("The message!\n\n");
 MimeBodyPart mbp2 = new SMimeBodyPart();
 mbp2.setDataHandler(new DataHandler(new FileDataSource("C:/users/idea.key")));
 mbp2.setFileName("pop3.jar");
 Multipart mp = new SMimeMultipart();
 mp.addBodyPart(mbp1);
 mp.addBodyPart(mbp2);
 DataHandler dataHandler = new DataHandler(mp, mp.getContentType());
 SignedContent sc = new SignedContent(false);
 sc.setDataHandler(dataHandler);
 sc.setCertificates(certificates);
 sc.addSigner(privateKey, signerCertificate);
 ...
 MimeMessage msg = new MimeMessage(session);
 ...
 set sender, recipient(s), subject, ...
 ...
 msg.setContent(sc, sc.getContentType());
 Transport.send(msg);
 

Notice, that when creating a multipart/signed message as above, body parts and multiparts have to be supplied as instances of SMimeBodyPart and SMimeMultipart for ensuring a proper canonicalization.

Additional setContent (or setText) methods provide alternative ways for supplying the content, which then internally is wrapped by a data handler, e.g.:

 SignedContent sc = new SignedContent(true);
 sc.setText("Immediately supplied text/plain data which internally will be wrapped by a data handler");
 

When creating a certs-only message for sending certificates/crls no content has to be supplied at all:

  SignedContent sc = new SignedContent(true, SignedContent.CERTS_ONLY);
  sc.setCertificates(certificates);
  msg.setContent(sc, sc.getContentType());
  //set filename and attachment parameters
  sc.setHeaders(msg);
 ...
 

For using the IAIK-JCE S/MIME classes, an application also will need the packages:

• jakarta.mail-api.jar: Get it from Eclipse Foundation.
• jakarta.activation-api.jar: Get it from Eclipse Foundation.
• OPTIONAL: pop3.jar: If you need POP3 access. Get it from org.eclipseangus.mail.pop3.

Furthermore, for telling JAF the data content handlers for the surppoted S/MIME types, a RFC1524 mailcap file with the following contents has to be put in the lib directory of your JDK (/lib):

 # Default mailcap file for the JakartaMail System
 #
 # for our content-handlers
 #
 text/plain;;   x-java-content-handler=com.sun.mail.handlers.text_plain
 multipart/*;;  x-java-content-handler=com.sun.mail.handlers.multipart_mixed
 message/*;;    x-java-content-handler=com.sun.mail.handlers.message_rfc822
 #
 # IAIK 'mailcap' file
 #
 multipart/signed;;               x-java-content-handler=iaik.smime.signed_content
 application/x-pkcs7-signature;;  x-java-content-handler=iaik.smime.signed_content
 application/x-pkcs7-mime;;       x-java-content-handler=iaik.smime.encrypted_content
 application/x-pkcs10;;           x-java-content-handler=iaik.smime.pkcs10_content
 application/pkcs7-signature;;    x-java-content-handler=iaik.smime.signed_content
 application/pkcs7-mime;;         x-java-content-handler=iaik.smime.encrypted_content
 application/pkcs10;;             x-java-content-handler=iaik.smime.pkcs10_content
 

When creating a new SignedContent to be sent per default the new S/MIME content type (application/x-pkcs7-mime, application/x-pkcs7-signature) are used. For using the old types call the static useNewContentTypes method of the SMimeParameters class before creating a new SignedContent object, e.g.:

 //switch to old content types
 SMimeParameters.useNewContentTypes(false);
 //create a SignedContent
 boolean implicit = ...;
 SignedContent sc = new SignedContent(implicit);
 ...
 

See Also:

SMimeSigned, JMailSMimeSigned, EncryptedContent, SignedContent

Field Summary

Fields

Modifier and Type	Field and Description
static java.lang.String	CERTS_ONLY SMime-type "certs-only".
static java.lang.String	SIGNED_DATA SMime-type "signed-data".

Fields inherited from class jakarta.mail.internet.MimeMultipart

allowEmpty, complete, ds, ignoreExistingBoundaryParameter, ignoreMissingBoundaryParameter, ignoreMissingEndBoundary, parsed, preamble

Fields inherited from class jakarta.mail.Multipart

contentType, parent, parts

Fields inherited from interface iaik.smime.SMimeContentType

LOG

Constructor Summary

Constructors

Constructor and Description
SignedContent(boolean implicit) Creates a new S/MIME signed content.
SignedContent(boolean implicit, java.lang.String smimeType) Creates a new S/MIME signed content.
SignedContent(jakarta.activation.DataSource dataSource) Creates a SignedContent object from the given DataSource.
SignedContent(SMimeContentType smimeCT, boolean implicit)

Method Summary

Modifier and Type	Method and Description
void	addBodyPart(jakarta.mail.BodyPart part) Throws a Messaging Exception.
void	addBodyPart(jakarta.mail.BodyPart part, int index) Throws a Messaging Exception.
void	addSigner(java.security.PrivateKey privateKey, X509Certificate signerCertificate) Uses the given private key to sign the content.
void	addSigner(java.security.PrivateKey privateKey, X509Certificate signerCertificate, AlgorithmID digestAlgorithm, AlgorithmID signatureAlgorithm) Uses the given private key to sign the content with the given signature algorithm.
void	addSigner(java.security.PrivateKey privateKey, X509Certificate signerCertificate, AlgorithmID digestAlgorithm, AlgorithmID signatureAlgorithm, Attribute[] signedAttributes) Signs this content using the supplied signer´s private key with the given signature algorithm.
void	addSigner(java.security.PrivateKey privateKey, X509Certificate signerCertificate, AlgorithmID digestAlgorithm, AlgorithmID signatureAlgorithm, X509Certificate encryptionCertificate, boolean includeEncryptionCertIDForMSOE) Uses the given private key to sign the content with the given signature algorithm.
void	addSigner(java.security.PrivateKey privateKey, X509Certificate signerCertificate, X509Certificate encryptionCertificate, boolean includeEncryptionCertIDForMSOE) Uses the given private key to sign the content.
java.security.cert.Certificate[]	getCertificates() Returns the certificates included in this S/MIME messages.
java.lang.Object	getContent() Returns the content as a Java object.
java.io.InputStream	getContentInputStream() Returns an InputStream for this part's unparsed content.
X509CRL[]	getCRLs() Returns the CRLs included in this S/MIME messages.
jakarta.activation.DataHandler	getDataHandler() Returns a DataHandler holding the content of this SignedContent object.
java.io.InputStream	getInputStream() Returns an input stream holding the content of this SignedContent object.
SignerInfo[]	getSignerInfos() Returns all the signer infos included in the underlying SignedData object.
java.lang.String	getSMimeType() Returns the S/MIME type of this SignedContent.
void	requestTimeStamp(TimeStampClient timeStampClient) Requests that the last signature that exists in this SignedContent structure be time-stamped.
void	requestTimeStamp(TimeStampClient timeStampClient, int signerInfoIndex) Requests that the signature at the indicated index in this SignedContent structure be time-stamped.
void	setBlockSize(int blockSize) Sets the block size to use when encoding the content.
void	setCertificates(java.security.cert.Certificate[] certificates) Sets the certificates to be included in the S/MIME message.
void	setContent(jakarta.mail.Multipart multipart) This method sets the given Multipart object as this SignedContent's content.
void	setContent(java.lang.Object content, java.lang.String type) A convenience method for setting this SignedContent's content.
void	setContentContentHeaders(jakarta.mail.Header[] headers) Set some headers for the entity to be signed.
void	setContentContentTransferEncoding(java.lang.String cte) Sets the content transfer encoding of the entity to be signed.
void	setCRLs(X509CRL[] crls) Sets the crls to be included in the S/MIME message.
void	setDataHandler(jakarta.activation.DataHandler dataHandler) Sets the content wrapped by a jakarta.activation.DataHandler.
void	setHeaders(jakarta.mail.Part part) Sets additional headers of the message containing this SignedContent.
void	setSession(jakarta.mail.Session session) Set the mail session to use when sending this message.
void	setText(java.lang.String text) A convenience method that sets the given String as this SignedContent's content.
X509Certificate	verify() Verifies this S/MIME signed content and returns the certificate of the signer (i.e.
X509Certificate	verify(int signerInfoIndex) Verifies this S/MIME signed content for the signerInfoIndex´th signer.
void	verify(java.security.PublicKey publicKey) Uses the given PublicKey to verify the signature of the signer (i.e.
void	verify(java.security.PublicKey publicKey, int signerInfoIndex) Uses the given PublicKey to verify the signature of the signerInfoIndex´th signer.
SignerInfo	verify(X509Certificate signerCertificate) Uses the provided signer certificate for verifying the signature that has been created by the signer being owner of the certificate.
X509Certificate	verifyAndValidate(int signerInfoIndex, CertVerifier certVerifier) Verifies and validates the SignerInfo structure that exists in this SignedContent object at the indicated index.
SignerInfo	verifyAndValidate(X509Certificate signerCert, CertVerifier certVerifier) Verifies and validates the SignerInfo structure that exists in this SignedContent object and corresponds to the indicated signer certificate.
void	writeTo(java.io.OutputStream os) Writes this SignedContent to the given output stream.

Methods inherited from class iaik.smime.SMimeMultipart

updateHeaders

Methods inherited from class jakarta.mail.internet.MimeMultipart

createInternetHeaders, createMimeBodyPart, createMimeBodyPart, getBodyPart, getBodyPart, getCount, getPreamble, initializeProperties, isComplete, parse, removeBodyPart, removeBodyPart, setPreamble, setSubType

Methods inherited from class jakarta.mail.Multipart

getContentType, getParent, setMultipartDataSource, setParent

Methods inherited from class java.lang.Object

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

Methods inherited from interface iaik.smime.SMimeContentType

getContentType

Field Detail

SIGNED_DATA

public static final java.lang.String SIGNED_DATA

SMime-type "signed-data".

See Also:

Constant Field Values

CERTS_ONLY

public static final java.lang.String CERTS_ONLY

SMime-type "certs-only".

See Also:

Constant Field Values

Constructor Detail

SignedContent

public SignedContent(boolean implicit,
                     java.lang.String smimeType)

Creates a new S/MIME signed content. It is possible to create implicitly (application/pkcs7-mime) and explicitly (multipart/signed) signed S/MIME messages. Implicitly signed messages can only be read with a mail client which supports S/MIME because the content is included in the S/MIME signature (DER encoded ASN.1).

Explicitly signed messages consist of a multipart/signed content where the first part contains the human readable content and the second part contains the signature.

When creating an implicit message the smime-type may be set to either SignedContent.SIGNED_DATA ("signed-data") or SignedContent.CERTS_ONLY ("certs-only"). Per default (smimeType = null) the smime-type parameter is not set.

Parameters:

implicit - true if the message shall be included in the signature, false otherwise

smimeType - the smime-type (SignedContent.SIGNED_DATA or SignedContent.CERTS_ONLY)

SignedContent

public SignedContent(SMimeContentType smimeCT,
                     boolean implicit)
              throws jakarta.mail.MessagingException

Throws:

jakarta.mail.MessagingException

SignedContent

public SignedContent(boolean implicit)

Creates a new S/MIME signed content. It is possible to create implicitly (application/pkcs7-mime) and explicitly (multipart/signed) signed S/MIME messages. Implicitly signed messages can only be read with a mail client which supports S/MIME because the content is included in the S/MIME signature (DER encoded ASN.1).

Explicitly signed messages consist of a multipart/signed content where the first part contains the human readable content and the second part contains the signature.

When using this constructor for creating an implicit message the smime-type parameter will not be set.

Parameters:

implicit - true if the message shall be included in the signature, false otherwise

SignedContent

public SignedContent(jakarta.activation.DataSource dataSource)
              throws java.io.IOException

Creates a SignedContent object from the given DataSource.

From the given data source the content type of the inherent message is parsed to determine if it represents an application/pkcs7-mime (implicit), or an multipart/sigend (explicit) message. If an application/pkcs7-mime message is encapsulated by the data source, the message is included in the signature, and a SMimeSigned object is created from the whole data to be parsed for the message. Otherwise, if an multipart/signed message is encapsulated by the data source, an jakarta.mail.internet.MimeMultipart is created from the data source containing the message in its first (0th) body part and the "non-message-including" signature in its second (1st) body part. In this case, the signature is parsed from the second body part to create a SMimeSigned.

During a mail session an application usually won´t call this constructor directly. Rather it will be called by a proper data content handler signed_content supplying the data source.

For more information on data handling using the jakarta.activation.DataSource for "MIME type based" data access, see Jakarta Activation Framework (JAF) sepecification.

Parameters:

dataSource - the DataSource

Throws:

java.io.IOException - if an error occurs when parsing the message, e.g. an unknown MIME type is requested or the message content cannot be read

Method Detail

setDataHandler

public void setDataHandler(jakarta.activation.DataHandler dataHandler)

Sets the content wrapped by a jakarta.activation.DataHandler. This method provides the mechanism to set this SignedContent's content, e.g:

 DataHandler dataHandler = new DataHandler(...);
 SignedContent sc = new SignedContent(false);
 sc.setDataHandler(dataHandler);
 

The DataHandler wraps around the actual content. It allows clients to discover the operations available on the content, and to instantiate the appropriate component to perform those operations. For more information consult Jakarta Activation Framework (JAF) sepecification.

Parameters:

dataHandler - the DataHandler for the content

setContent

public void setContent(java.lang.Object content,
                       java.lang.String type)

A convenience method for setting this SignedContent's content. The content internally is wrapped in a jakarta.activation.DataHandler.

Note that a DataContentHandler class for the specified type should be available to the JakartaMail implementation for this to work right. i.e., to do setContent(foobar, "application/x-foobar"), a DataContentHandler for "application/x-foobar" should be installed. Refer to the Jakarta Activation Framework for more information.

Parameters:

content - a java object

type - MIME type of this object

setText

public void setText(java.lang.String text)

A convenience method that sets the given String as this SignedContent's content. The content internally is wrapped in a jakarta.activation.DataHandler thereby specifying "text/plain" as MIME type.

Parameters:

text - the text that is the SignedObject's content

setContent

public void setContent(jakarta.mail.Multipart multipart)

This method sets the given Multipart object as this SignedContent's content. The content is internally wrapped in a jakarta.activation.DataHandler. Refer to the Jakarta Activation Framework for more information.

Parameters:

multipart - the multipart object that is the SignedObject's content

addBodyPart

public void addBodyPart(jakarta.mail.BodyPart part)
                 throws jakarta.mail.MessagingException

Throws a Messaging Exception. This method only overrides the same named method of super class MimeMultipart for prohibiting explicit usage of this method.

Overrides:

addBodyPart in class jakarta.mail.internet.MimeMultipart

Parameters:

part - the body part to be added; not used

Throws:

jakarta.mail.MessagingException - since not supported for this class

addBodyPart

public void addBodyPart(jakarta.mail.BodyPart part,
                        int index)
                 throws jakarta.mail.MessagingException

Throws a Messaging Exception. This method only overrides the same named method of super class MimeMultipart for prohibiting explicit usage of this method.

Overrides:

addBodyPart in class jakarta.mail.internet.MimeMultipart

Parameters:

part - the body part to be added; not used

index - the index; not used

Throws:

jakarta.mail.MessagingException - since not supported for this class

setContentContentTransferEncoding

public void setContentContentTransferEncoding(java.lang.String cte)

Sets the content transfer encoding of the entity to be signed. This method allows to set the content transfer encoding for the inner entity when method setText or setDataHandler is used for supplying the content. However, the supplied content transfer encoding will be ignored when the inner entity is a structured entity.

Parameters:

cte - the content transfer encoding to be applied to the inner entity to be signed

setContentContentHeaders

public void setContentContentHeaders(jakarta.mail.Header[] headers)

Set some headers for the entity to be signed. This method allows to set some headers for the inner entity when method setText or setDataHandler is used for supplying the content. However, the supplied header will be ignored when the inner entity is a structured entity. The supplied headers are not cloned!

Parameters:

headers - the headers to be applied to the inner entity to be signed

verify

public X509Certificate verify()
                       throws java.security.SignatureException

Verifies this S/MIME signed content and returns the certificate of the signer (i.e. the signer with the SignerInfo at index 0).

This method may be used for verifying the signature when only one signer is included.

To use this method the certificate of the signer must be included in the signature. Use verify(PublicKey) for verification when the signer certificate is not included in the signature.

To validate the certificates received when calling getCertificates(), use the method validate(X509Certificate certificate) from the class com.entrust.toolkit.User.java.

Returns:

the certificate of the signer

Throws:

java.security.SignatureException - if this message does not verify, the signer certificate is not included in the message or if this is a certs-only message

setSession

public void setSession(jakarta.mail.Session session)

Set the mail session to use when sending this message. This session can provide additional control over the message sending when sending an implicitly signed message.

Parameters:

session -

verify

public X509Certificate verify(int signerInfoIndex)
                       throws java.security.SignatureException

Verifies this S/MIME signed content for the signerInfoIndex´th signer.

The signature is verified by using the specified signer´s public key, which is get from the signer´s certificate, derived from the certificates field.

To use this method the certificate of the signer must be included in the signature. Use verify(PublicKey, int) for verification when the signer certificate is not included in the signature.

To validate the certificates received when calling getCertificates(), use the method validate(X509Certificate certificate) from the class com.entrust.toolkit.User.java.

Returns:

the certificate of the signer

Throws:

java.security.SignatureException - if this message does not verify, the signer certificate is not included in the message or if this is a certs-only message

verify

public void verify(java.security.PublicKey publicKey)
            throws java.security.SignatureException

Uses the given PublicKey to verify the signature of the signer (i.e. the signer with the SignerInfo at index 0).

This method may be used for verifying the signature when only one signer is included and the certificate of the signer is not included.

Throws:

java.security.SignatureException - if this message does not verify or if this is a certs-only message

verify

public void verify(java.security.PublicKey publicKey,
                   int signerInfoIndex)
            throws java.security.SignatureException

Uses the given PublicKey to verify the signature of the signerInfoIndex´th signer.

This method may be used for verifying the signature when the certificate of the signer in mind is not included.

Throws:

java.security.SignatureException - if this message does not verify or if this is a certs-only message

verify

public SignerInfo verify(X509Certificate signerCertificate)
                  throws java.security.SignatureException

Uses the provided signer certificate for verifying the signature that has been created by the signer being owner of the certificate.

This method may be used for verifying the signature of a signer in situations where there are no certificates sent with the SignedData object. Of course, it also may be used when the certificate is not empty. However, take in mind that you should not step through the entries of the certificates field for calling verify(cert) for any certificate presented there since there also may (shall) be included issuer certificates and certificate chains leading to some trusted root.

Parameters:

signerCertificate - the certificate of the signer whose signature should be verified

Returns:

the signerInfo belonging to the signer being owner of the given certificate

Throws:

java.security.SignatureException - if the signature turns out to be incorrect or there is no signer with the given certificate

verifyAndValidate

public X509Certificate verifyAndValidate(int signerInfoIndex,
                                         CertVerifier certVerifier)
                                  throws java.security.SignatureException,
                                         CertificationException,
                                         TimeStampException,
                                         RevocationWarningException

Verifies and validates the SignerInfo structure that exists in this SignedContent object at the indicated index.

First the signature is verified to ensure that the data has not been tampered since it was signed. Then, if the signature does not contain a time-stamp, the signer's certificate is validated at the present time. However, if the signature does contain a time-stamp, the time-stamp token is decoded, verified and validated, and then the signer's certificate is validated at the time specified in the time-stamp.

In order to verify a signature contained in a SignerInfo structure, the corresponding signer certificate must be located. Using the signer identifier from the SignerInfo structure, the signer certificate is located by searching the 'certificates' included in the SignedContent and then searching the trusted certificates contained in the certificate validation mechanism.

When validating the signer's certificate at the time specified by the time-stamp, a revocation warning can occur. This happens when the signer's certificate has been revoked, but was revoked after the time specified in the time-stamp. When this occurs, the signer's certificate can still be considered valid, depending on the policy surrounding time-stamping and the reason it was revoked. In this case, a RevocationWarningException exception will be thrown; it is then up to the caller to decide whether the warning should be ignored, or acted upon.

Parameters:

signerInfoIndex - the index of the SignerInfo structure to be verified/validated

certVerifier - the certificate validation mechanism; used to validate the signer's certificate

Returns:

the certificate that was used to validate the signature (the signer's certificate)

Throws:

java.security.SignatureException - thrown if the signature has been tampered, or a SignerInfo structure with the specified index does not exist, or the corresponding signer certificate could not be found

CertificateException - thrown if the signature cannot be trusted

TimeStampException - thrown if the signature is time-stamped, but the time-stamp is invalid or cannot be trusted

RevocationWarningException - thrown if the signer's certificate was revoked, but was revoked after the time specified in the time-stamp; the caller must then decided if the signature can be trusted

CertificationException

Since:

Entrust 7.0

verifyAndValidate

public SignerInfo verifyAndValidate(X509Certificate signerCert,
                                    CertVerifier certVerifier)
                             throws java.security.SignatureException,
                                    CertificationException,
                                    TimeStampException,
                                    RevocationWarningException

Verifies and validates the SignerInfo structure that exists in this SignedContent object and corresponds to the indicated signer certificate.

First the signature is verified to ensure that the data has not been tampered since it was signed. Then, if the signature does not contain a time-stamp, the signer's certificate is validated at the present time. However, if the signature does contain a time-stamp, the time-stamp token is decoded, verified and validated, and then the signer's certificate is validated at the time specified in the time-stamp.

When validating the signer's certificate at the time specified by the time-stamp, a revocation warning can occur. This happens when the signer's certificate has been revoked, but was revoked after the the time specified in the time-stamp. When this occurs, the signer's certificate can still be considered valid, depending on the policy surrounding time-stamping and the reason it was revoked. In this case, a RevocationWarningException exception will be thrown; it is then up to the caller to decide whether the warning should be ignored, or acted upon.

Parameters:

signerCert - the certificate that corresponds the SignerInfo structure to be verified/validated; used to verify the signature

certVerifier - the certificate validation mechanism; used to validate the signer's certificate

Returns:

the SignerInfo structure that was verifier/validated

Throws:

java.security.SignatureException - thrown if the signature has been tampered or the SignerInfo structure that corresponds to the signer's certificate could not be found

CertificateException - thrown if the signature cannot be trusted

TimeStampException - thrown if the signature is time-stamped, but the time-stamp is invalid or cannot be trusted

RevocationWarningException - thrown if the signer's certificate was revoked, but was revoked after the time specified in the time-stamp; the caller must then decided if the signature can be trusted

CertificationException

Since:

Entrust 7.0

getContent

public java.lang.Object getContent()
                            throws java.io.IOException,
                                   jakarta.mail.MessagingException

Returns the content as a Java object. The type of the returned object depends on the content itself. For example, the object returned for "text/plain" content is usually a String object. For content-types that are unknown to the DataHandler system, an input stream is returned as the content. This is a convenience method that just invokes the inherent DataHandler's getContent() method. Refer to the Jakarta Activation Framework for more information.

Returns:

an object representing the content

Throws:

java.io.IOException - if an I/O error occurs when getting the content from the inherent data handler

jakarta.mail.MessagingException - if an error occurs when fetching the inherent data handler

getDataHandler

public jakarta.activation.DataHandler getDataHandler()
                                              throws jakarta.mail.MessagingException

Returns a DataHandler holding the content of this SignedContent object.

The DataHandler allows clients to operate on as well as retrieve the content. Refer to the Jakarta Activation Framework for more information.

Returns:

a DataHandler for the content

Throws:

jakarta.mail.MessagingException - if an error occurs when fetching the data handler

getInputStream

public java.io.InputStream getInputStream()
                                   throws java.io.IOException,
                                          jakarta.mail.MessagingException

Returns an input stream holding the content of this SignedContent object. Any mail-specific transfer encodings will be decoded before the input stream is provided. This is typically a convenience method that just invokes the inherent DataHandler's getInputStream() method.

Returns:

an InputStream carrying the inherent content

Throws:

java.io.IOException - if an I/O error occurs when getting the content from the inherent data handler

jakarta.mail.MessagingException - if an error occurs when fetching the inherent data handler

getContentInputStream

public java.io.InputStream getContentInputStream()
                                          throws java.io.IOException

Returns an InputStream for this part's unparsed content. No mail-specific transfer encodings will be decoded before the input stream is provided. This is typically a convenience method that just invokes the SMimeEncrypted's getInputStream() method.

This method can be used to get the content of large messages.

Returns:

an InputStream holding the content of the message

Throws:

java.io.IOException

setCertificates

public void setCertificates(java.security.cert.Certificate[] certificates)

Sets the certificates to be included in the S/MIME message. The supplied certificate list is an array of X509Certificates representing the certifcate chain of the signer. It is intended that the certificate list is sufficient to contain chains from a recognized 'top level CA' to the signer.

Note: Setting the signer´s certificates is an optional task. If no signer certificates are included, the recipient explicitly has to supply the signer´s public key when verifying the message: verify(PublicKey). Otherwise - if the signer´s certificate chain is included in the S/MIME message - the verify() method obtains the signer´s public key from the inherent certificate and the recipient must not extra take care for explicitly supplying the public key.

Parameters:

certificates - an array of certificates

setCRLs

public void setCRLs(X509CRL[] crls)

Sets the crls to be included in the S/MIME message.

Parameters:

crls - an array of crls

setHeaders

public void setHeaders(jakarta.mail.Part part)

Sets additional headers of the message containing this SignedContent. Till now I found no way how to set the required header for the message which contains this SignedContent. This method adds one header with one parameter to the specified message:

 Content-Disposition: attachment";
     filename="smime.p7m"
     or
     filename="smime.p7c"
 

Specified by:

setHeaders in interface SMimeContentType

Parameters:

part - message to add the headers

setBlockSize

public void setBlockSize(int blockSize)

Sets the block size to use when encoding the content. Setting to 0 causes definite length ASN.1 encoding to be used, setting to a positive number causes indefinite length encoding to be used, with blocks split up to the given size.

The default block size is 2048.

Note

Setting the block size to 0 causes all data to be buffered internally before being written, and is only suitable when signing small messages.

Parameters:

blockSize - the block size to use when encoding the content.

Since:

Entrust 7.0

getCertificates

public java.security.cert.Certificate[] getCertificates()

Returns the certificates included in this S/MIME messages.

Returns:

the certificates of this S/MIME message

getCRLs

public X509CRL[] getCRLs()

Returns the CRLs included in this S/MIME messages.

Returns:

the crls of this S/MIME message

getSMimeType

public java.lang.String getSMimeType()

Returns the S/MIME type of this SignedContent. Possible values are certs-only and signed-data.

Specified by:

getSMimeType in interface SMimeContentType

Returns:

the S/MIME type or null if not set

getSignerInfos

public SignerInfo[] getSignerInfos()

Returns all the signer infos included in the underlying SignedData object.

Returns:

an array containing all the SignerInfo objects

addSigner

public void addSigner(java.security.PrivateKey privateKey,
                      X509Certificate signerCertificate)
               throws java.security.NoSuchAlgorithmException,
                      java.security.InvalidKeyException

Uses the given private key to sign the content.

This method uses the rsaEncryption digest-encryption algorithm as specified by PKCS#1 for encrypting the message digest, which is computed over the message with the SHA algorithm as specified in FIPS PUB 180-2.

Since rsaEncryption is used, the supplied "signing" key has to be a RSAPrivateKey. The signer certificate is used to add information about the signer by issuer distinguished name and issuer-specific serial number.The recipient uses this information to find the signer certificate from the list of certificates or from anywhere else.

When creating the SignerInfo object for the signer, the following attributes are set for the SignerInfo structure:

• Content-Type (PKCS#7 Data)
• Signing-Time
• S/MIME Capabilities specifying the follwing symmetric ciphers:
  • des_CBC (DES in CBC mode)
  • des_EDE3_CBC (TripleDes in CBC mode)
  • rc2_CBC (RC2 in CBC mode with 128, 64 or 40 bit key)

The PKCS#9 message digest attribute automatically will be added later, during the data is written to a stream, and after SHA hash calculation is completed. Digest encryption will be done by using the rsaEncryption method as specified by PKCS#1.

Parameters:

privateKey - the private key to sign the content

signerCertificate - the certificate of the signer

Throws:

java.security.NoSuchAlgorithmException - if SHA-1 is not supported

java.security.InvalidKeyException - if the key cannot be used for signing

addSigner

public void addSigner(java.security.PrivateKey privateKey,
                      X509Certificate signerCertificate,
                      X509Certificate encryptionCertificate,
                      boolean includeEncryptionCertIDForMSOE)
               throws java.security.NoSuchAlgorithmException,
                      java.security.InvalidKeyException

Uses the given private key to sign the content.

This method uses the rsaEncryption digest-encryption algorithm as specified by PKCS#1 for encrypting the message digest, which is computed over the message with the SHA algorithm as specified in FIPS PUB 180-2.

Since rsaEncryption is used, the supplied "signing" key has to be a RSAPrivateKey. The signer certificate is used to add information about the signer by issuer distinguished name and issuer-specific serial number. The recipient uses this information to find the signer certificate from the list of certificates or from anywhere else.

When creating the SignerInfo object for the signer, the following attributes are set for the SignerInfo structure:

• Content-Type (PKCS#7 Data)
• Signing-Time
• S/MIME Capabilities specifying the follwing symmetric ciphers:
  • des_CBC (DES in CBC mode)
  • des_EDE3_CBC (TripleDes 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

The PKCS#9 message digest attribute automatically will be added later, during the data is written to a stream, and after SHA hash calculation is completed. Digest encryption will be done by using the rsaEncryption method as specified by PKCS#1.

Inclusion of a special private Microsoft signed attribute (type: 1.3.6.1.4.1.311.16.4) for identifying the sender´s encryption certificate 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 (RSA) private key to sign the content

signerCertificate - the certificate of the signer

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

Throws:

java.security.NoSuchAlgorithmException - if SHA-1 is not supported

java.security.InvalidKeyException - if the key cannot be used for signing

addSigner

public void addSigner(java.security.PrivateKey privateKey,
                      X509Certificate signerCertificate,
                      AlgorithmID digestAlgorithm,
                      AlgorithmID signatureAlgorithm)
               throws java.security.NoSuchAlgorithmException,
                      java.security.InvalidKeyException

Uses the given private key to sign the content with the given signature algorithm.

The signer certificate is used to add information about the signer by issuer distinguished name and issuer-specific serial number. The recipient uses this information to find the signer certificate from the list of certificates or from anywhere else.

When creating the SignerInfo object for the signer, the following attributes are set for the SignerInfo structure:

• Content-Type (PKCS#7 Data)
• Signing-Time
• S/MIME Capabilities specifying the follwing symmetric ciphers:
  • des_CBC (DES in CBC mode)
  • des_EDE3_CBC (TripleDes in CBC mode)
  • rc2_CBC (RC2 in CBC mode with 128, 64 or 40 bit key)

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

Inclusion of a special private Microsoft signed attribute (type: 1.3.6.1.4.1.311.16.4) for identifying the sender´s encryption certificate 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

signerCertificate - the certificate of the signer

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

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

Throws:

java.security.NoSuchAlgorithmException - if no implementation of the requested message digest algorithm is available

java.security.InvalidKeyException - if the key cannot be used for signing

addSigner

public void addSigner(java.security.PrivateKey privateKey,
                      X509Certificate signerCertificate,
                      AlgorithmID digestAlgorithm,
                      AlgorithmID signatureAlgorithm,
                      X509Certificate encryptionCertificate,
                      boolean includeEncryptionCertIDForMSOE)
               throws java.security.NoSuchAlgorithmException,
                      java.security.InvalidKeyException

Uses the given private key to sign the content with the given signature algorithm.

The signer certificate is used to add information about the signer by issuer distinguished name and issuer-specific serial number. The recipient uses this information to find the signer certificate from the list of certificates or from anywhere else.

When creating the SignerInfo object for the signer, the following attributes are set for the SignerInfo structure:

• Content-Type (PKCS#7 Data)
• Signing-Time
• S/MIME Capabilities specifying the following symmetric ciphers:
  • des_CBC (DES in CBC mode)
  • des_EDE3_CBC (TripleDes 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

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

Inclusion of a special private Microsoft signed attribute (type: 1.3.6.1.4.1.311.16.4) for identifying the sender´s encryption certificate 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

signerCertificate - the certificate of the signer

digestAlgorithm - the digest algorithm; default: SHA-1 (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

Throws:

java.security.NoSuchAlgorithmException - if no implementation of the requested message digest algorithm is available

java.security.InvalidKeyException - if the key cannot be used for signing

addSigner

public void addSigner(java.security.PrivateKey privateKey,
                      X509Certificate signerCertificate,
                      AlgorithmID digestAlgorithm,
                      AlgorithmID signatureAlgorithm,
                      Attribute[] signedAttributes)
               throws java.security.NoSuchAlgorithmException,
                      java.security.InvalidKeyException

Signs this content using the supplied signer´s private key with the given signature algorithm.

Please note that no signed attributes are created by this method (as done by the other addSigner methods. This method sets the supplied attributes for the SignerInfo to be created for the signer.

Parameters:

privateKey - the private key which shall be used for signing

signerCertificate - the certificate of the signer which must be used for verifying the signature

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

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

Throws:

java.security.NoSuchAlgorithmException - if no implementation of the requested message digest algorithm is available

java.security.InvalidKeyException - if the key cannot be used for signing

writeTo

public void writeTo(java.io.OutputStream os)
             throws java.io.IOException,
                    jakarta.mail.MessagingException

Writes this SignedContent to the given output stream. If this SignedContent is IMPLICIT a DER encoded byte array is written. If this SignedContent is EXPLICIT a MimeMultipart object is written.

Overrides:

writeTo in class jakarta.mail.internet.MimeMultipart

Throws:

java.io.IOException - if an error occurs while writing to the stream

jakarta.mail.MessagingException - if an error occurs when fetching the data to be written

requestTimeStamp

public void requestTimeStamp(TimeStampClient timeStampClient)

Requests that the last signature that exists in this SignedContent structure be time-stamped.

This API can be used following any of the addSigner() APIs to ensure that the signature that was just added is time-stamped.

When this SignedContent structure is encoded to an ASN1 object, a time-stamp will automatically be requested for the signature from the TimeStamp Authority. It will then be added to the SignerInfo structure that represents the signature, causing the signature to be time-stamped.

A time-stamp will NOT be requested under the following circumstances:

• the timeStampClient parameter is null
• the SignedContent structure does not contain any signatures
• the last signature the SMimeSigned structure contains is null

Note:

The time-stamp is not actually requested until the SignedContent encoding is done, which occurs during a close operation. Thus, if the time-stamp client that was used to request that the signature be time-stamped is modified (hash algorithm changed, TSA policy changed, ...) before the write operation, these changes will apply to the time-stamp that is requested during the encoding.

Parameters:

timeStampClient - the time-stamp client that will be used to request a time-stamp for the signature value from a TimeStamp Authority

Since:

Entrust 7.0

requestTimeStamp

public void requestTimeStamp(TimeStampClient timeStampClient,
                             int signerInfoIndex)

Requests that the signature at the indicated index in this SignedContent structure be time-stamped.

When this SignedContent structure is encoded to an ASN1 object, a time-stamp will automatically be requested for the signature from the TimeStamp Authority. It will then be added to the SignerInfo structure that represents the signature, causing the signature to be time-stamped.

A time-stamp will NOT be requested under the following circumstances:

• the timeStampClient parameter is null
• the SignedContent structure does not contain any signatures
• the signature at the indicated index does not exist
• the signature at the indicated index is null

Note:

The time-stamp is not actually requested until the SignedContent encoding is done, which occurs during a close operation. Thus, if the time-stamp client that was used to request that the signature be time-stamped is modified (hash algorithm changed, TSA policy changed, ...) before the write operation, these changes will apply to the time-stamp that is requested during the encoding.

Parameters:

timeStampClient - the time-stamp client that will be used to request a time-stamp for the signature value from a TimeStamp Authority

signerInfoIndex - the index of the signature that is to be time-stamped

Since:

Entrust 7.0