The oracle.security.crypto.smime.SmimeObject interface represents an S/MIME object.

Classes that implement this interface include:

• SmimeSigned

• SmimeEnveloped

• SmimeMultipartSigned

• SmimeSignedReceipt

• SmimeCompressed

Methods in this interface include:

String generateContentType ()

returns the content type string for this S/MIME object. For example:

"application/pkcs7-mime; smime-type=signed-data"

String generateContentType (boolean useStandardContentTypes)

If the argument is true, returns the same as generateContentType(); if false, returns old-style (Netscape) content type string. For example: "application/x-pkcs7-mime; smime-type=signed-data"

void writeTo (java.io.OutputStream os, java.lang.String mimeType)

outputs this object to the specified output stream.

The oracle.security.crypto.smime.SmimeSignedObject interface extends SmimeObject, and specifies methods common to all S/MIME signed objects, including SmimeSigned and SmimeMultipartSigned.

Methods in this interface include:

Vector getCertificates ()

Returns the list of certificates included in this S/MIME object's signed content.

Vector getCRLs ()

Returns the list of certificate revocation lists in the S/MIME object's signed content.

javax.mail.internet.MimeBodyPart getEnclosedBodyPart ()

Returns the document which was signed.

oracle.security.crypto.smime.ess.EquivalentLabels getEquivalentLabels
(java.security.cert.X509Certificate signerCert)

Returns the EquivalentLabels if present or null.

oracle.security.crypto.smime.ess.ESSSecurityLabel getESSSecurityLabel
(java.security.cert.X509Certificate signerCert)

Returns the ESSSecurityLabel if present or null.

oracle.security.crypto.smime.ess.MLExpansionHistory getMLExpansionHistory(
 java.security.cert.X509Certificate signerCert)

Returns the MLExpansionHistory attribute if present or null.

oracle.security.crypto.smime.ess.ReceiptRequest getReceiptRequest(
 java.security.cert.X509Certificate signerCert)

Returns the ReceiptRequest attribute if present or null.

oracle.security.crypto.smime.ess.SigningCertificate getSigningCertificate(
 java.security.cert.X509Certificate signerCert)

Returns the SigningCertificate.

void verify (oracle.security.crypto.cert.CertificateTrustPolicy trustPolicy)

Returns normally if the signed contents include at least one valid signature according to the specified trust policy, otherwise throws an AuthenticationException.

void verifySignature (java.security.cert.X509Certificate signerCert)

Returns normally if the signed contents contain a signature which can be validated by the given certificate, otherwise throws an AuthenticationException.

The method can throw a SignatureException, if no signature exists corresponding to the given certificate.

The oracle.security.crypto.smime.SmimeSigned class represents an S/MIME signed message (.implements SmimeSignedObject). You may use this class to build a new message or parse an existing one.

Constructors and methods include:

SmimeSigned (javax.mail.internet.MimeBodyPart content)

Creates a new SmimeSigned object, using the specified MIME body part for the contents to be signed.

SmimeSigned ()

Creates a new empty SmimeSigned object, which is useful for building a "certificates-only" S/MIME message.

SmimeSigned (InputStream is)

Creates a new SmimeSigned object by reading its encoding from the specified input stream.

void addSignature (java.security.PrivateKey signerKey,
    java.security.cert.X509Certificate signerCert,
    oracle.security.crypto.core.AlgorithmIdentifier digestAlgID)

Adds a signature to the message, using the specified private key, certificate, and message digest algorithm.

void addSignature (java.security.PrivateKey signerKey,
 java.security.cert.X509Certificate signerCert,
 oracle.security.crypto.core.AlgorithmIdentifier digestAlgID,
      java.util.Date timeStamp)

Adds a signature to the message, including a time stamp.

void addSignature (java.security.PrivateKey signerKey,
    java.security.cert.X509Certificate signerCert,
    oracle.security.crypto.core.AlgorithmIdentifier digestAlgID,
    SmimeCapabilities smimeCaps)

Adds a signature to the message, including S/MIME capabilities.

javax.mail.internet.MimeBodyPart getEnclosedBodyPart ()

Returns the MIME body part that was signed.

To build a new message, use any of these three constructors:

// Create a new S/MIME Signed Message
SmimeSigned sig = new SmimeSigned();

//         -OR-
// Create a new S/MIME Signed Message with a specified MIME body part
MimeBodyPart bp = new MimeBodyPart();
bp.setText("Hello from SendSignedMsg!");
SmimeSigned sig1 = new SmimeSigned(bp);

//         -OR-
// Create a new S/MIME Signed Message with a specified MIME body part 
// and a flag switching compression on or off
MimeBodyPart bp = new MimeBodyPart();
bp.setText("Hello from SendSignedMsg!");
boolean useCompression = true;
SmimeSigned sig2 = new SmimeSigned(bp, useCompression);

To parse a message, use the constructor that takes a java.io.InputStream:

InputStream is = Input stream containing message to be parsed
SmimeSigned sig = new SmimeSigned(is);

The oracle.security.crypto.smime.SmimeEnveloped class represents an S/MIME enveloped message (implements SmimeObject), and may be used to build a new message or parse an existing one.

Constructors and methods include:

SmimeEnveloped (javax.mail.internet.MimeBodyPart content,
    oracle.security.crypto.core.AlgorithmIdentifier contentEncryptionAlgID)

Creates a new SmimeEnveloped object from the specified MIME body part, using the specified content encryption algorithm.

SmimeEnveloped (InputStream is)

Creates a new SmimeEnveloped object by reading its encoding from the specified input stream.

void addRecipient (java.security.cert.X509Certificate cert)

Encrypts the message for the recipient using the given public key certificate.

byte[] getEncryptedContent ()

Returns the contents without decrypting.

javax.mail.internet.MimeBodyPart getEnclosedBodyPart (
 java.security.PrivateKey recipientKey,
 java.security.cert.X509Certificate recipientCert)

Returns the MIME body part for the recipient specified by recipientCert, after decryption using the given recipient private key.

Use the following code to build a new message:

// Create a new S/MIME Enveloped Message with a specified MIME body part and a specified content
// encryption algorithm
MimeBodyPart bp = new MimeBodyPart();
bp.setText("Hello from SendSignedMsg!");
AlgorithmIdentifier algId = AlgID.aes256_CBC;
SmimeEnveloped env = new SmimeEnveloped(bp, algId);

To parse a message, use the constructor that takes a java.io.InputStream:

InputStream is = Input stream containing message to be parsed
    SmimeEnveloped env = new SmimeEnveloped(is);

The oracle.security.crypto.smime.SmimeMultipartSigned class represents an S/MIME multi-part signed message. A multipart signed message is intended for email clients that are not MIME-aware. This class can be used to build a new message or parse an existing one.

Constructors and methods include:

SmimeMultipartSigned (javax.mail.internet.MimeBodyPart bodyPart,
    oracle.security.crypto.core.AlgorithmIdentifier digestAlgID)

Creates a new SmimeMultipartSigned message, with the specified MIME body part and message digest algorithm.

void addBodyPart (javax.mail.BodyPart part)

Inherited from javax.mail.Multipart, adds the specified body part to this SmimeMultipartSigned object. (See the javax.mail API documentation at http://www.oracle.com/technetwork/java/index-138643.html for more details.)

void addSignature (java.security.PrivateKey signerKey,
    java.security.cert.X509Certificate signerCert)

Adds a signature to the message, using the specified private key and certificate.

void addSignature (java.security.PrivateKey signerKey,
    java.security.cert.X509Certificate signerCert, java.util.Date timeStamp)

Adds a signature to the message, using the specified private key and certificate plus a time stamp.

void addSignature (java.security.PrivateKey signerKey,
    java.security.cert.X509Certificate signerCert, java.util.Date timeStamp,
    SmimeCapabilities smimeCaps)

Adds a signature to the message, using the specified private key and certificate, plus S/MIME capabilities.

javax.mail.internet.MimeBodyPart getEnclosedBodyPart ()

Returns the MIME body part that was signed.

Use the following code to build a new message:

// Create a new S/MIME Multipart Signed Message with a specified 
// MIME body part and a specified digest algorithm
MimeBodyPart bp = new MimeBodyPart();
bp.setText("Hello from SendSignedMsg!");
AlgorithmIdentifier algId = AlgID.sha1;
SmimeMutlipartSigned sig = new SmimeMultipartSigned(bp, algId);

To parse a message, use the constructor that takes a javax.activation.DataSource:

DataSource ds = Data source containing message to be parsed
SmimeMultipartSigned sig = new SmimeMultipartSigned(ds);

The oracle.security.crypto.smime.SmimeSignedReceipt class represents an S/MIME wrapped and signed receipt. You may use this class to build a new message or parse an existing one.

To build a new message, use any of these four constructors:

// Create a new S/MIME wrapped and signed receipt with the specified receipt,
// the specified digest of the message's signed attributes
// and the addresses of the receipt recipients
ESSReceipt receipt = ESS receipt to include in message
byte [] msgSigDigest = Digest of signed attributes to be included in message
Address [] addresses = Addresses of receipt recipients
SmimeSignedReceipt sig = new SmimeSigned(receipt, msgSigDigest, addresses);

 //         -OR-
// Create a new S/MIME wrapped and signed receipt 
// with a specified S/MIME Signed Message containing the receipt 
SmimeSignedObject sso = S/MIME signed message containing receipt
SmimeSignedReceipt sig1 = new SmimeSignedReceipt(sso);

//         -OR-
// Create a new S/MIME wrapped and signed receipt with a 
// specified S/MIME Signed Message containing the receipt,
// the signer's certificate and the addresses of the receipt recipients
SmimeSignedObject sso1 = S/MIME signed message containing receipt
X509Certificate signerCert = The message signer's certificate
Address [] addresses1 = Addresses of receipt recipients
SmimeSignedReceipt sig2 = new SmimeSignedReceipt(sso1, signerCert, addresses1); 

//         -OR-

// Create a new S/MIME wrapped and signed receipt with a 
// specified S/MIME Signed Message containing the receipt,
// the signer's certificate, the addresses of the receipt recipients and
// a specified MLExpansionHistory attribute.
SmimeSignedObject sso1 = S/MIME signed message containing receipt
X509Certificate signerCert = The message signer's certificate
Address [] addresses1 = Addresses of receipt recipients
MLExpansionHistory mlExpansionHistory = The MLExpansionHistory attribute
SmimeSignedReceipt sig2 = 
    new SmimeSignedReceipt(sso1, signerCert, addresses1, mlExpansionHistory);

To parse a message, use the constructor that takes a java.io.InputStream:

InputStream is = Input stream containing message to be parsed
SmimeSignedReceipt sig = new SmimeSignedReceipt(is);

The oracle.security.crypto.smime.SmimeCompressed class represents an S/MIME compressed message as defined in RFC 3274. You can use this class to build a new message or parse an existing one.

Use the following code to build a new message:

// Create a new S/MIME Compressed Message with a specified MIME body part
MimeBodyPart bp = new MimeBodyPart();
bp.setText("Hello from SendSignedMsg!");
SmimeCompressed comp = new SmimeCompressed(bp);

//           -OR-
// Create a new S/MIME Compressed Message with a specified MIME body part
// and a specified compression algorithm
MimeBodyPart bp = new MimeBodyPart();
bp.setText("Hello from SendSignedMsg!");
AlgorithmIdentifier algId = Smime.id_alg_zlibCompress;
SmimeCompressed comp = new SmimeCompressed(bp, algId);

To parse a message, use the constructor that takes a java.io.InputStream:

InputStream is = Input stream containing message to be parsed
SmimeCompressed comp1 = new SmimeCompressed(is);

The oracle.security.crypto.smime.Smime interface defines constants such as algorithm identifiers, content type identifiers, and attribute identifiers.

The oracle.security.crypto.smime.SmimeUtils class contains static utility methods.

Methods of this class include:

public static FileDataSource createFileDataSource (File file,
    String contentTypeHeader)
public static FileDataSource createFileDataSource (String name,
    String contentTypeHeader)

For transparent handling of multipart or multipart/signed S/MIME types, use these methods instead of directly instantiating a javax.activation.FileDataSource.

The oracle.security.crypto.smime.MailTrustPolicy class implements a certificate trust policy (oracle.security.crypto.cert.CertificateTrustPolicy) used to verify signatures on signed S/MIME objects.

The oracle.security.crypto.smime.SmimeCapabilities class encapsulates a set of capabilities for an S/MIME object including, for example, the supported encryption algorithms.

A useful method of this class is:

void addCapability(oracle.security.crypto.asn1.ASN1ObjectID capabilityID)

which adds the capability with the specified object ID to this set of S/MIME capabilities.

The oracle.security.crypto.smime.SmimeDataContentHandler class provides the DataContentHandler for S/MIME content types. It implements javax.activation.DataContentHandler.

The oracle.security.crypto.smime.ess package contains the following classes:

SmimeObject is an abstract class representing a fundamental S/MIME message content entity. Subclasses of SmimeObject include :

• SmimeSigned

• SmimeEnveloped

• SmimeMultipartSigned

• SmimeSignedReceipt, and

• SmimeCompressed

One of the characteristics of SmimeObject implementations is that they "know their own MIME type" -- that is, they implement the generateContentType method. Thus, to place such an object inside a MIME message or body part, follow the same outline that was used in the SmimeSigned example:

The SmimeObject class provides another version of the generateContentType method, which takes a boolean parameter. When given true as a parameter, generateContentType behaves exactly as in the case of no argument. When given false as a parameter, generateContentType returns the older MIME types required by certain mail clients, including Netscape Communicator 4.0.4. Specifically:

• "application/pkcs7-mime" becomes "application/x-pkcs7-mime"

• "application/pkcs7-signature" becomes "application/x-pkcs7-signature"

Create a signed message, or signed MIME body part, using these steps:

The generateContentType method used in these examples returns a string identifying the appropriate MIME type for the object, which in this case is:

application/pkcs7-mime; smime-type=signed-data

With these simple steps, you can now transport the MIME message, place the body part containing S/MIME content into a MIME multipart object, or perform any other operation appropriate for these objects. See the JavaMail API for details.

The SmimeMultipartSigned class provides an alternative way to create signed messages. These messages use the "multipart/signed" mime type instead of "application/pkcs7-mime". The advantage is that the content of the resulting message is readable with non-MIME enabled mail clients, although such clients will not, of course, be able to verify the signature.

Creating a multi-part/signed message is slightly different from creating a signed message. For example, to send a multi-part/signed text message:

// create the content text as a MIME body part
MimeBodyPart bp = new MimeBodyPart();
bp.setText("Example multipart/signed message.");
// the constructor takes the signature algorithm
SmimeMultipartSigned sig = new SmimeMultipartSigned(bp, AlgID.sha1);
// sign the content
sig.addSignature(signerKey, signerCert); 
// place the content in a MIME message
MimeMessage msg = new MimeMessage();
msg.setContent(sig, sig.generateContentType());

The reason for identifying the message digest in the SmimeMultipartSigned constructor is that, unlike the case of application/pkcs7-mime signed data objects, multipart/signed messages require that all signatures use the same message digest algorithm.

The generateContentType method returns the following string:

multipart/signed; protocol="application/pkcs7-signature"

An S/MIME digital envelope (encrypted message) is represented by the SmimeEnveloped class. This is a MIME entity which is formed by encrypting a MIME body part with some symmetric encryption algorithm (eg, Triple-Des or RC2) and a randomly generated session key, then encrypting the session key with the RSA public key for each intended message recipient.

In the following example, doc is an instance of MimeBodyPart, which is to be wrapped in an instance of SmimeEnveloped, and recipientCert is the recipient's certificate.

SmimeEnveloped env = new SmimeEnveloped(doc, Smime.dES_EDE3_CBC);
env.addRecipient (recipientCert);

You may add any number of envelope recipients by making repeated calls to addRecipient.

It is possible to create an S/MIME signed-data object that contains neither content nor signatures; rather, it contains just certificates, or CRLs, or both. Such entities can be used as a certificate transport mechanism. They have the special content type:

application/pkcs7-mime; smime-type=certs-only

This example shows how to create a signed-data object:

X509Certificate cert1, cert2;
SmimeSigned certBag = new SmimeSigned();
certBag.addCertificate(cert1);
certBag.addCertificate(cert2);

Now you can pass certBag to an appropriate setContent method. When generateContentType is invoked on certBag, it will automatically return a content type with the correct "certs-only" value for the smime-type parameter.

The basic JavaMail API technique for extracting Java objects from MIME entities is to invoke the getContent() method on an instance of MimePart, an interface which models MIME entities and is implemented by the MimeMesage and MimeBodyPart classes.

The getContent method consults the currently installed default command map - which is part of the JavaBeans Activities Framework - to find a data content handler for the given MIME type, which is responsible for converting the content of the MIME entity into a Java object of the appropriate class.

The mailcap file provided with your distribution can be used to install the SmimeDataContentHandler class, which serves as a data content handler for the following types:

Once you obtain an instance of SmimeSigned or SmimeMutlipartSigned from getContent(), you will naturally want to verify the attached signatures. To explain the available options for signature verification, it is neccessary to discuss the structure of an S/MIME signed message.

The content of a signed S/MIME message is a CMS object of type SignedData. Such an object itself has a content - the document to which the signatures are applied - which is the text encoding of a MIME entity. It also contains from zero to any number of signatures, and, optionally, a set of certificates, CRLs, or both, which the receiving party may use to validate the signatures.

The SmimeSigned and SmimeMultipartSigned classes encapsulate all of this information. They provide two authentication methods: verifyingSignature and verify.

To verify a particular signature with a certificate already in possession, ignoring any certificate and CRLs attached by the signer, use verifySignature. For example:

SmimeSignedObject sig =
    (SmimeSignedObject)msg.getContent(); // msg is a Message
sig.verifySignature(cert, msg.getFrom()); // cert is an X509Certificate object

If verification fails, the verifySignature method throws either a SignatureException or an AuthenticationException ; otherwise, it returns normally.

Use verify to verify that the content contains at least one valid signature; that is, there exists a valid certificate chain, starting from a trusted root CA, and terminating in a certificate for the private key which generated the signature. This method makes use of the attached certificate and CRLs in order to follow certificate chains.

For example, given a trusted certificate authority (CA) certificate already in hand:

TrustedCAPolicy trusts = new TrustedCAPolicy();
// if true, need CRL for each cert in chain
trusts.setRequireCRLs(false); 
// caCert is an X509Certificate object with CA cert
trusts.addTrustedCA(caCert); 
SmimeSignedObject sig = (SmimeSignedObject)msg.getContent();
sig.verify(trusts, msg.getFrom());

Like verifySignature, verify throws an AuthenticationException if the signature cannot be verified; otherwise it returns normally. In either case you can recover the document that was signed, which is itself a MIME entity, by invoking getEnclosedBodyPart():

MimeBodyPart doc = sig.getEnclosedBodyPart();

An S/MIME digital envelope consists of:

• A protected MIME body part, which has been encrypted with a symmetric key algorithm (for example, DES or RC2)

• A randomly generated content encryption key

• Information that allows one or more intended recipients to decrypt the content

For each recipient, this information consists of the content encryption key, itself encrypted with the recipient's public key.

To obtain the encrypted content from an SmimeEnveloped object, you need the recipient's private key and the corresponding certificate; the certificate is used as an index into the recipient information table contained in the envelope's data structure.

For example:

SmimeEnveloped env = (SmimeEnveloped)msg.getContent();
MimeBodyPart mbp = env.getEnclosedBodyPart(privKey, cert)
// privKey is a PrivateKey object
// cert is an X509Certificate object

Passing the private key and the certificate to the getEnclosedBodyPart method returns the decrypted content as an instance of MimeBodyPart.

The getContent method can now be invoked on the MimeBodyPart object to retrieve the (now decrypted) content. This content may be a String (in the case of an encrypted text message), or any other object such as an SmimeSigned.

You can add the ESS services ReceiptRequests, SecurityLabels, and SigningCertificates to an S/MIME signed message by adding them to the signedAttributes of a signature.

// Create a Signed Message
SmimeSigned sig = new SmimeSigned(); 
    AttributeSet signedAttributes = new AttributeSet();

An S/MIME signed receipt must have correctly set content type parameters for the data content handlers to recognize it. If the content type parameters are missing, the signed receipt is treated as a signed message.