iaik.smime
Class EncryptedContent

java.lang.Object
  iaik.smime.SMimeContent
      iaik.smime.EncryptedContent

All Implemented Interfaces:

CryptoContent

Direct Known Subclasses:

AuthEncryptedContent

public class EncryptedContent
extends SMimeContent

This class can be used to create and parse encrypted S/MIME messages in combination with the JavaMail^TM API (javax.mail).

S/MIME (Secure/Multipurpose Internet Mail Extensions, RFC 8551) enhances the MIME standard(s) about the following cryptographic security services for electronic messaging applications: authentication, message integrity, and non-repudiation of origin (using digital signatures), and data confidentiality (using encryption). This class supports the creation, handling and parsing of encrypted S/MIME messages in combination with the javax.mail architecture. For creating, parsing and working with signed S/MIME messages, use the SignedContent class of the iaik.smime package.

S/MIME (Secure/Multipurpose Internet Mail Extensions) specifies the application/pkcs7-mime (smime-type "enveloped-data") type for data enveloping (encrypting). The whole (prepared) MIME entity to be enveloped is encrypted and packed into a CMS (RFC 5652) object of type EnvelopedData which subsequently is inserted into an application/pkcs7-mime MIME entity. The smime-type parameter for enveloped messages is "enveloped-data", the file extension is ".p7m" (see S/MIME Version 4 Message Specification). The "Content-" headers of a sample message would look like:

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

 MIIBHgYJKoZI...

 

For creating a new EncryptedContent to be sent, first use a proper constructor, and subsequently supply the content by means of a setContent, setText, or setDataHandler method. Recipients are added by calling a proper addRecipient method, depending on which CMS key management technique to be used. When setting the content encryption algorithm by means of the setEncryptionAlgorithm method, optionally the key length fo the temporary symmetric content encryption key to be generated may be specified. The S/MIME Version 4 Message Specification recommends AES-128 CBC to be used as content encryption algorithm.

Before actually sending the message with the encrypted content, the setHeaders method shall be called for properly updating some message headers (Content-Transfer-Encoding, Content-Disposition). When not calling method setHeaders JavaMail may run method writeTo twice to itself determine the content transfer encoding to be used.

Typical usage (when using RSA key transport):

 // create a MimeMessage for the current mail session
 MimeMessage msg = new MimeMessage(session);
 ...
 // create an EncryptedContent object
 EncryptedContent ec = new EncryptedContent();
 // set the content to be encrypted
 ec.setContent(...);
 // the encryption certificate of the recipient:
 X509Certificate recipientCertificate = ...;
 ec.addRecipient(recipientCertificate, AlgorithmID.rsaEncryption);
 // the sender also wants to be able to decrypt the message
 X509Certificate senderCertificate = ...;
 ec.addRecipient(senderCertificate, AlgorithmID.rsaEncryption);
 // we use the AES algorithm
 AlgorithmID contentEncryptionAlg = (AlgorithmID)AlgorithmID.aes128_CBC.clone();
 int keyLength = 128;
 ec.setEncryptionAlgorithm(contentEncryptionAlg, keyLength);
 // set the EncryptedContent as message content
 msg.setContent(ec, ec.getContentType());
 // update message headers
 ec.setHeaders(msg);
 // send message
 Transport.send(msg);
 

A recipient uses a proper decryptSymmetricKey method for decrypting the encrypted content encryption key with her/his (private) key encryption key, and subsequently reads the content, e.g.:

 // the message to be parsed
 MimeMessage msg = ...;
 // get the EncryptedContent
 EncryptedContent ec = (EncryptedContent)msg.getContent();
 //recipient at index 0 decrypts the content encryption key:
 ec.decryptSymmetricKey(privateKey, 0);
 // get the (decrypted, original) content
 Object content = ec.getContent();
 ...
 

The decryptSymmetricKey method used in the sample above requires that the recipient knows the index of the RecipientInfo that belongs to her/his key. Alternatively you may use the certificate of the recipient or her/his KeyIdentifier to find the right RecipientInfo and decrypt the symmetric content encryption key.

For more information about the JavaMail architecture, and how to handling MIME messages, consult the JavaMail specification.

For using the IAIK-CMS S/MIME library, you also will need the following packages:

• iaik_jce(_full).jar (IAIK-JCE Core Crypto Library).
• iaik_eccelerate.jar (IAIK ECC Library; if you want to use Elliptic Curve Cryptography).
• mail.jar (JavaMail API).
• activation.jar (Java Activation Framework; required for JDK versions < 1.6).

The JAF assignment between MIME-types and content handlers is done by means of a RFC 1524 mailcap file which is included in the IAIK-CMS distribution. It defines the following classes as content handlers for the corresponding MIME types:

 #
 # IAIK 'mailcap' file entries
 #
 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
 

The content handlers are registered by copying the mailcap file into the lib directory of your JDK (/lib). Alternatively you may register the IAIK-S/MIME mailcap file dynamically by using the default command map:

 String mailcapFileName = ...;
 MailcapCommandMap mc = new MailcapCommandMap(mailcapFileName);
 CommandMap.setDefaultCommandMap(mc);
 

Or you may add the IAIK mailcap entries to the default mailcap command map, e.g.:

 MailcapCommandMap mc = (MailcapCommandMap)CommandMap.getDefaultCommandMap();
 mc.addMailcap("multipart/signed;; x-java-content-handler=iaik.smime.signed_content");
 mc.addMailcap("application/x-pkcs7-signature;; x-java-content-handler=iaik.smime.signed_content");
 mc.addMailcap("application/x-pkcs7-mime;; x-java-content-handler=iaik.smime.encrypted_content");
 mc.addMailcap("application/pkcs7-signature;; x-java-content-handler=iaik.smime.signed_content");
 mc.addMailcap("application/pkcs7-mime;; x-java-content-handler=iaik.smime.encrypted_content");
 mc.addMailcap("application/x-pkcs10;; x-java-content-handler=iaik.smime.pkcs10_content");
 mc.addMailcap("application/pkcs10;; x-java-content-handler=iaik.smime.pkcs10_content");
 CommandMap.setDefaultCommandMap(mc);
 

For a more detailed description of mailcap handling consult the Javadoc of the Activation Framework.

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

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

See Also:

SMimeEncrypted

Constructor Summary

EncryptedContent()
Creates a new EncryptedContent object.

EncryptedContent(CryptoContent cryptoContent)
Creates a new S/MIME encrypted and signed content.

EncryptedContent(javax.activation.DataSource dataSource)
Constructs an EncryptedContent object from the given data source.

EncryptedContent(java.io.InputStream in)
Constructs an EncryptedContent object from the given input stream.

Method Summary

void	addRecipient(RecipientInfo recipientInfo) Adds one recipient.
java.security.KeyPair	addRecipient(X509Certificate[] originatorCertificates, java.security.PrivateKey originatorPrivateKey, X509Certificate recipientCertificate, AlgorithmID keyEA, AlgorithmID keyWrapAlg, int kekLength) Adds one recipient to this S/MIME EnvelopedData object.
void	addRecipient(X509Certificate recipientCertificate, AlgorithmID keyEncAlg) Adds one recipient.
java.security.KeyPair	addRecipient(X509Certificate recipientCertificate, AlgorithmID keyEA, AlgorithmID keyWrapAlg, int kekLength) Adds one recipient.
javax.crypto.SecretKey	decryptSymmetricKey(java.security.Key recipientKey, int recipientInfoIndex) Uses the specified key for decrypting the content-encryption key to setup the cipher for decrypting the encrypted content of this EncryptedContent object for the requesting recipient, specified by its recipientInfoIndex.
javax.crypto.SecretKey	decryptSymmetricKey(java.security.Key recipientKey, KeyIdentifier recipientIdentifier) Uses the specified key for decrypting the content-encryption key to setup the cipher for decrypting the encrypted content of this EncryptedContent object for the requesting recipient, specified by the given recipient identifier.
javax.crypto.SecretKey	decryptSymmetricKey(java.security.Key recipientKey, X509Certificate recipientCertificate) Uses the specified key for decrypting the content-encryption key to setup the cipher for decrypting the encrypted content of this EncryptedContent object for the requesting recipient, specified by the given recipient certificate.
java.io.InputStream	getContentInputStream() Returns an InputStream with the unparsed (decrypted) content.
javax.activation.DataHandler	getDataHandler() Return a DataHandler holding the content.
AlgorithmID	getEncryptionAlgorithm() Returns the content-encryption algorithm (including any associated parameters) of this EncryptedContent.
OriginatorInfo	getOriginatorInfo() Gets the OriginatorInfo, if included.
int	getRecipientInfoIndex(X509Certificate recipientCertificate) Returns the recipient info index matching to the supplied recipient certificate.
RecipientInfo[]	getRecipientInfos() Returns information about all recipients of this message.
java.lang.String	getSMimeType() Returns the smime-type parameter ("enveloped-data").
void	setEncryptionAlgorithm(AlgorithmID contentEncAlg, int keyLength) Sets the symmetric algorithm for encrypting the message.
void	setEncryptionAlgorithm(AlgorithmID contentEncAlg, javax.crypto.SecretKey cek) Sets the symmetric algorithm for encrypting the message.
void	setHeaders(javax.mail.Part part) Sets additional headers of the part (message) containing this CompressedContent.
void	setOriginatorInfo(OriginatorInfo originatorInfo) Sets the optional OriginatorInfo.
void	setRecipients(RecipientInfo[] recipientInfos) Sets the recipients.
void	setSMimeType() Sets the smime-type parameter to "enveloped-data".
void	setupCipher(java.security.Key key) Uses the given symmetric key to setup the cipher for decrypting the content.
void	writeTo(java.io.OutputStream os) Writes this EncryptedContent BER encoded to the given output stream.

Methods inherited from class iaik.smime.SMimeContent

getContent, getContentType, getInputStream, setBlockSize, setContent, setContent, setContentContentHeaders, setContentContentTransferEncoding, setDataHandler, setText

Methods inherited from class java.lang.Object

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

Constructor Detail

EncryptedContent

public EncryptedContent()

Creates a new EncryptedContent object.

Use a proper setContent, setText, or setDataHandler method for supplying the content to be enveloped. Recipients are added by calling a proper addRecipient method thereby specifying the recipient certificate, and the key management algorithm to be used. When setting the content encryption algorithm by means of the setEncryptionAlgorithm method, optionally the key length may be specified. The S/MIME Version 4 Message Specification recommends AES-128 CBC to be used as content encryption algorithm. Before actually sending the Message with the encrypted content, the setHeaders method shall be called for properly updating the message headers. Typical usage (for RSA key transport):

 MimeMessage msg = new MimeMessage(session);
 ...
 EncryptedContent ec = new EncryptedContent();
 ec.setContent(...);
 ec.addRecipient(recipientCertificate, AlgorithmID.rsaEncryption);
 ec.setEncryptionAlgorithm(algorithm, keyLength);
 ec.setHeaders(msg);

 msg.setContent(ec, ec.getContentType());
 Transport.send(msg);
 

When using this constructor the smime-type parameter will be set to "enveloped-data".

EncryptedContent

public EncryptedContent(CryptoContent cryptoContent)
                 throws javax.mail.MessagingException

Creates a new S/MIME encrypted and signed content. When using this constructor the smime-type parameter will be set to "enveloped-data".

Parameters:

cryptoContent - the (signed or encrypted or compressed) content to be encrypted

Throws:

if - an error occurs when setting the content

javax.mail.MessagingException

EncryptedContent

public EncryptedContent(javax.activation.DataSource dataSource)
                 throws java.io.IOException

Constructs an EncryptedContent object from the given data source. The given data source is expected to supply a BER encoded CMS ContentInfo object holding the enveloped data. During a mail session this constructor may not be called directly. Rather it is called by a proper data content handler encrypted_content supplying the data source.

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

Parameters:

dataSource - the DataSource supplying the enveloped data

Throws:

java.io.IOException - if an I/O error occurs during reading the object

EncryptedContent

public EncryptedContent(java.io.InputStream in)
                 throws java.io.IOException

Constructs an EncryptedContent object from the given input stream. The given input stream is expected to supply a BER encoded CMS ContentInfo object holding the enveloped data.

Parameters:

in - the input stream supplying the enveloped data

Throws:

java.io.IOException - if an I/O error occurs during parsing the stream

Method Detail

setSMimeType

public void setSMimeType()

Sets the smime-type parameter to "enveloped-data".

getSMimeType

public java.lang.String getSMimeType()

Returns the smime-type parameter ("enveloped-data").

Returns:

the smime-type parameter ("enveloped-data")

getRecipientInfos

public RecipientInfo[] getRecipientInfos()

Returns information about all recipients of this message. You will need at least the private key of one recipinet specified in this array to decrypt the message.

Returns:

all recipients who can decrypt this message

getRecipientInfoIndex

public int getRecipientInfoIndex(X509Certificate recipientCertificate)

Returns the recipient info index matching to the supplied recipient certificate. This method may be used by a recipient for querying for the recipient info that holds the content encryption key encrypted with the public key of the given certificate.

Parameters:

recipientCertificate - the certificate of the recipient

Returns:

the recipient info index matching to the supplied recipient certificate, or -1 if no recipient info belonging to the given certificate can be found

decryptSymmetricKey

public javax.crypto.SecretKey decryptSymmetricKey(java.security.Key recipientKey,
                                                  int recipientInfoIndex)
                                           throws SMimeException,
                                                  java.security.InvalidKeyException

Uses the specified key for decrypting the content-encryption key to setup the cipher for decrypting the encrypted content of this EncryptedContent object for the requesting recipient, specified by its recipientInfoIndex.

This method first uses the given key for decrypting the encrypted temporary symmetric key obtained from the corresponding RecipientInfo structure, and subsequently uses this key to initialize a CipherInputStream for decrypting the inherent encrypted content.

Note that the cipher will be only initialized for decrypting in this class. The encrypted-content decryption actually is done during during reading the data obtained by calling the getInputStream, getContent, getContentInputStream or getDataHandler method. So do not call any of these methods before decrypting the encrypted content-encryption key!

Note that you have to know the right index into the recipientInfos field when using this method for decrypting the encrypted content-encryption key and setting up the cipher for decryption. You may search for the index by using the getRecipientInfoIndex method.
However, when having some recipient using a key agreement protocol the corresponding RecipientInfo is of type KeyAgreeRecipientInfo which may hold encrypted content-encryption keys for more than only one recipients using the same key agreement algorithm with same domain parameters. Since this decryptSymmetricKey method only can get the KeyAgreeRecipientInfo with the given index (but not search for the right recipient in the KeyAgreeRecipientInfo), it will step through any recipient included in the KeyAgreeRecipientInfo trying to decrypt the encrypted content-encryption key with the supplied key. This may give some overhead so it might be appropriate to use another decryptSymmetric method allowing to immediately identify the particular recipient in mind by its #decryptSymmetricKey(Key, KeyIdentifier) keyIdentifier} or certificate.

Parameters:

recipientKey - the key of the recipient to be used for decrypting the encrypted content-encryption key for setting up the cipher for decrypting the encrypted content-encryption key.

recipientInfoIndex - the index into the recipientInfos field

Returns:

the (decrypted) secret content encryption key

Throws:

SMIMEException - if there occurs an error while decrypting the content-encryption key or setting up the cipher for decrypting the content

java.security.InvalidKeyException - if the specified key is not valid

SMimeException

decryptSymmetricKey

public javax.crypto.SecretKey decryptSymmetricKey(java.security.Key recipientKey,
                                                  KeyIdentifier recipientIdentifier)
                                           throws SMimeException,
                                                  java.security.InvalidKeyException

Uses the specified key for decrypting the content-encryption key to setup the cipher for decrypting the encrypted content of this EncryptedContent object for the requesting recipient, specified by the given recipient identifier.

This method first uses the given key for decrypting the encrypted temporary symmetric key obtained from the corresponding RecipientInfo structure, and subsequently uses this key to initialize a CipherInputStream for decrypting the inherent encrypted content.

Note that the cipher will be only initialized for decrypting in this class. The encrypted-content decryption actually is done during during reading the data obtained by calling the getInputStream, getContent, getContentInputStream or getDataHandler method. So do not call any of these methods before decrypting the encrypted content-encryption key!

This decryptSymmetricKey method can be used to decrypt the encrypted content-encryption key and setup the cipher for decryption for any type of RecipientInfo. The supplied recipient identifier will be used for searching for the right RecipientInfo in the recipientInfos field.

Parameters:

recipientKey - the key of the recipient to be used for decrypting the encrypted content-encryption key for setting up the cipher for decrypting the encrypted content-encryption key.

recipientIdentifier - specifies which RecipientInfo the given key belongs to

Returns:

the (decrypted) secret content encryption key

Throws:

SMIMEException - if there occurs an error while decrypting the content-encryption key or setting up the cipher for decrypting the content, or no RecipientInfo for the requested recipient is included

java.security.InvalidKeyException - if the specified key is not valid

SMimeException

decryptSymmetricKey

public javax.crypto.SecretKey decryptSymmetricKey(java.security.Key recipientKey,
                                                  X509Certificate recipientCertificate)
                                           throws SMimeException,
                                                  java.security.InvalidKeyException

Uses the specified key for decrypting the content-encryption key to setup the cipher for decrypting the encrypted content of this EncryptedContent object for the requesting recipient, specified by the given recipient certificate.

This method first uses the given key for decrypting the encrypted temporary symmetric key obtained from the corresponding RecipientInfo structure, and subsequently uses this key to initialize a CipherInputStream for decrypting the inherent encrypted content.

Note that the cipher will be only initialized for decrypting in this class. The encrypted-content decryption actually is done during during reading the data obtained by calling the getInputStream, getContent, getContentInputStream or getDataHandler method. So do not call any of these methods before decrypting the encrypted content-encryption key!

Note that this method only can be used for decrypting the encrypted content encyrption key and setting up the cipher for content decryption if the recipient in mind has a RecipientInfo of type KeyTransRecipientInfo or KeyAgreeRecipientInfo using a public key from a certificate for its key management protocol. However, this should be no problem since S/MIME generally only uses certificate based RecipientInfos.

Parameters:

recipientKey - the key of the recipient to be used for decrypting the encrypted content-encryption key for setting up the cipher for decrypting the encrypted content-encryption key.

recipientCertificate - the certificate of the recipient specifying which RecipientInfo the recipient private key belongs to

Returns:

the (decrypted) secret content encryption key

Throws:

SMimeException - if there occurs an error while decrypting the content-encryption key or setting up the cipher for decrypting the content, or no RecipientInfo for the requested recipient is included

java.security.InvalidKeyException - if the specified recipient key is not valid

setupCipher

public void setupCipher(java.security.Key key)
                 throws SMimeException,
                        java.security.NoSuchAlgorithmException,
                        java.security.InvalidKeyException

Uses the given symmetric key to setup the cipher for decrypting the content.

The secret key supplied to this method has to be the already decrypted content encryption key.

Note that the cipher will be only initialized for decrypting in this class. The encrypted-content decryption actually is done during during reading the data obtained by calling the getInputStream, getContent, getContentInputStream or getDataHandler method. So do not call any of these methods before decrypting the encrypted content-encryption key!

Parameters:

key - the temporary symmetric key that has been used to encrypt the content, and now is used for decrypting it again

Throws:

SMimeException - if there occurs an error while setting up the cipher for decrypting the content

java.security.InvalidKeyException - if the specified key is not valid

java.security.NoSuchAlgorithmException

setHeaders

public void setHeaders(javax.mail.Part part)

Sets additional headers of the part (message) containing this CompressedContent. This method sets the Content-Disposition and Content-Transfer-Encoding headers:

 Content-Disposition: attachment";
     filename="smime.p7m"
 Content-Transfer-Encoding: base64
 

It is highly recommended to call this method to set the headers above for the part containing this EncryptedContent to avoid processing overhead :

 MimeMessage msg = ...;
 EncryptedContent ec = ...;
 ec.setHeaders(msg);
 

If this method is not called, JavaMail may run method writeTo twice to determine the content transfer encoding to be used.

Parameters:

part - the part for which the Content-Disposition and Content-Transfer-Encoding headers should be set

getDataHandler

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

Return a DataHandler holding the content.

Specified by:

getDataHandler in class SMimeContent

Returns:

a DataHandler with the content

Throws:

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

getContentInputStream

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

Returns an InputStream with the unparsed (decrypted) content. No mail-specific transfer encodings will be decoded before the input stream is provided.

Attention!This method may be called only once since a stream only can be read once. However, if any of the content accessing methods like getContent, getDataHandler or getDataHandler is called before calling getContentInputStream, getContentInputStream may be called repeadetly since in this case the content is internally kept by means of a DataHandler.
Before calling this method the internal Cipher already must have been setup by calling a proper decryptSymmetricKey or setupCipher method.

Returns:

an InputStream holding the unparsed content

Throws:

java.io.IOException - if an error occurs when reading the data

addRecipient

public void addRecipient(X509Certificate recipientCertificate,
                         AlgorithmID keyEncAlg)

Adds one recipient.

When using this method for adding a Recipient, the corresponding RecipientInfo will be the KeyTransRecipientInfo choice and the recipient certificate will be identified by IssuerAndSerialNumber. So use this method with rsaEncyrption as key transport algorithm to be compatible to S/MIMEv2.

Parameters:

recipientCertificate - the certificate of the recipient

keyEncAlg - the algorithm to use for encrypting the symmetric key (e.g. AlgorithmID.rsaEncryption)

addRecipient

public java.security.KeyPair addRecipient(X509Certificate recipientCertificate,
                                          AlgorithmID keyEA,
                                          AlgorithmID keyWrapAlg,
                                          int kekLength)
                                   throws SMimeException

Adds one recipient.

When using this method for adding a Recipient, the corresponding RecipientInfo will be the KeyAgreeRecipientInfo choice and the recipient certificate will be identified by IssuerAndSerialNumber. The KeyAgreeRecipientInfo originator field will be the OriginatorPublicKey choice for using an ephemeral originator key.

This method may be called repeatedly for adding information for each recipient using key agreement as key management protocol. When calling this method the first time (for adding the first "KeyAgree" recipient) and the originator key yet has not been set, this method itself creates a OriginatorPublicKey with domain parameters matching to those of the supplied recipient key. Any further call of this method might add a recipient to an already existing KeyAgreeRecipientInfo (if the recipient to be added has a public key with domain parameters matching to those of an already existing KeyAgreeRecipientInfo originator key) or create a new KeyAgreeRecipientInfo for this recipient.

Parameters:

recipientCertificate - the certificate of the recipient

keyEA - the (key agreement) algorithm to use for creating a shared secret key encryption key for encrypting the symmetric key (e.g. AlgorithmID.esdhKeyAgreement)

keyWrapAlg - the key wrap algorithm to be used for encrypting (wrapping) the content-encryption key with the shared key-encryption created according to the requested key agreement protocol

kekLength - the length of the shared key encryption key to be generated

Returns:

the originator key pair matching to the domain parameters of the recipient key

Throws:

SMimeException - if it was not possible to create a RecipientInfo for adding the recipient

addRecipient

public java.security.KeyPair addRecipient(X509Certificate[] originatorCertificates,
                                          java.security.PrivateKey originatorPrivateKey,
                                          X509Certificate recipientCertificate,
                                          AlgorithmID keyEA,
                                          AlgorithmID keyWrapAlg,
                                          int kekLength)
                                   throws SMimeException

Adds one recipient to this S/MIME EnvelopedData object.

When using this method for adding a Recipient, the corresponding RecipientInfo will be the KeyAgreeRecipientInfo choice and the recipient certificate will be identified by IssuerAndSerialNumber. The KeyAgreeRecipientInfo originator field will be the OriginatorPublicKey choice for using an ephemeral originator key.

This method may be called repeatedly for adding information for each recipient using key agreement as key management protocol. When calling this method the first time (for adding the first "KeyAgree" recipient) and the originator key yet has not been set, this method itself creates a OriginatorPublicKey with domain parameters matching to those of the supplied recipient key. Any further call of this method might add a recipient to an already existing KeyAgreeRecipientInfo (if the recipient to be added has a public key with domain parameters matching to those of an already existing KeyAgreeRecipientInfo originator key) or create a new KeyAgreeRecipientInfo for this recipient.

Parameters:

recipientCertificate - the certificate of the recipient

keyEA - the (key agreement) algorithm to use for creating a shared secret key encryption key for encrypting the symmetric key (e.g. AlgorithmID.esdhKeyAgreement)

keyWrapAlg - the key wrap algorithm to be used for encrypting (wrapping) the content-encryption key with the shared key-encryption created according to the requested key agreement protocol

kekLength - the length of the shared key encryption key to be generated

Returns:

the originator key pair matching to the domain parameters of the recipient key

Throws:

SMimeException - if it was not possible to create a RecipientInfo or encrypt the symmetric key for this recipient

addRecipient

public void addRecipient(RecipientInfo recipientInfo)

Adds one recipient.

Parameters:

recipientInfo - the recipientInfo for the recipient to be added

setRecipients

public void setRecipients(RecipientInfo[] recipientInfos)

Sets the recipients.

Parameters:

recipientInfos - the RecipientInfos for the recipients for which to encrypt the mail

setOriginatorInfo

public void setOriginatorInfo(OriginatorInfo originatorInfo)

Sets the optional OriginatorInfo.

The originatorInfo may be set for including certificates and/or certificate revocation lists for the originator if required by the key management algorithm used.

Parameters:

originatorInfo - the OriginatorInfo to be set

getOriginatorInfo

public OriginatorInfo getOriginatorInfo()

Gets the OriginatorInfo, if included.

The originatorInfo may be set for including certificates and/or certificate revocation lists if required by the key management algorithm used.

Returns:

the originatorInfo, if included; otherwise null

setEncryptionAlgorithm

public void setEncryptionAlgorithm(AlgorithmID contentEncAlg,
                                   int keyLength)
                            throws java.security.NoSuchAlgorithmException

Sets the symmetric algorithm for encrypting the message.

Parameters:

contentEncAlg - the algorithm for encrypting the content

keyLength - the key length of the temporary symmetric key to be generated (maybe -1 if the algorithm uses a default key length)

Throws:

java.security.NoSuchAlgorithmException - if the requested content encryption algorithm is not supported

setEncryptionAlgorithm

public void setEncryptionAlgorithm(AlgorithmID contentEncAlg,
                                   javax.crypto.SecretKey cek)
                            throws java.security.NoSuchAlgorithmException

Sets the symmetric algorithm for encrypting the message.

Parameters:

contentEncAlg - the algorithm for encrypting the content

cek - the content encryption key to be used

Throws:

java.security.NoSuchAlgorithmException - if the requested content encryption algorithm is not supported

getEncryptionAlgorithm

public AlgorithmID getEncryptionAlgorithm()

Returns the content-encryption algorithm (including any associated parameters) of this EncryptedContent.

Returns:

the content encryption algorithm

writeTo

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

Writes this EncryptedContent BER encoded to the given output stream.

Throws:

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

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