iaik.smime

Class SMimeEncrypted

java.lang.Object

iaik.cms.EnvelopedDataStream

iaik.smime.SMimeEncrypted

All Implemented Interfaces:

ContentStream, EOFListener, java.util.EventListener

public class SMimeEncrypted
extends EnvelopedDataStream

This class represents the "CMS EnvelopedData object carrying" part of a S/MIME message.

S/MIME v3 (Secure/Multipurpose Internet Mail Extensions) specifies the application/pkcs7-mime (smime-type "enveloped-data") type for data enveloping.

The whole (prepared) MIME entity to be enveloped into a CMS 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 3 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"

 rfvbn...

 

This class extends the EnvelopedDataStream class of the iaik.cms or taking advantage of the stream architecture introduced there. Following this practice, the data is prepared according CMS (Cryptographic Message Syntax) by piping it through a cipher stream for performing the content encryption.

The steps for creating a SMimeEncrypted object and writing it to a stream may be summarized as follows (note that in this example we use Triple DES as content encryption algorithm and RSA key transport for encrypting the content-encryption key; however, an application may wish to use any other content encryption algorithm supported by a cryptographic provider installed, and any other key management technique allowed (e.g. ESDH key agreement):

1. Create a new SMimeEncrypted by specifying the data to be enveloped, the content encryption algorithm, and - when using RC2 - the key lengh, e.g.:

         InputStream data_stream = ...;
         AlgorithmID contentEA = AlgorithmID.des_CBC;
         SMimeEncrypted sme = new SMimeEncryoted(data_stream, contentEA, -1);
         

   This step also will create the symmetric content encryption key.
2. Add the intended recipients by calling the addRecipient method thereby specfying the particular recipient´s certificate and setting the RSA encryption method to be used for encrypting the symmetric content encryption key with the recipient´s public key obtained from the supplied certificate, e.g.:

         sme.addRecipient(recipientCert1, AlgorithmID.rsaEncryption);
         sme.addRecipient(recipientCert2, AlgorithmID.rsaEncryption);
         

3. Finally call the writeTo method for wrapping the EnvelopedData object into a ContentInfo and writing it BER encoded to an output stream thereby actually performing the content encryption by piping the data through a cipher stream:

         OutputStrem os = ...;
         sme.writeTo(os);
         

On the receiving side, the recipient first creates a new SMimeEncrypted object from an input stream supplying the BER encoded message, subsequently decrypts the encrypted symmetric content encryption key with its private key, and finally gets and reads the data holding input stream which is decrypted during the read operation, e.g.:

 InputStream enveloped_stream = ...;
 SMimeEncrypted sme = new SMimeEncrypted(encrypted_stream);
 //recipient has index 0
 sme.decryptSymmetricKey(privateKey, 0);
 //get and read the data
 InputStream data_stream = sme.getInputStream();
 byte[] buf = new byte[1024];
 int r;
 while ((r = data_is.read(buf)) > 0) {
   // do something useful
 }
 

Field Summary

Fields inherited from class iaik.cms.EnvelopedDataStream

blockSize_, encryptedContentInfo_, m_envelopedData, originatorInfo_, recipientInfos_, symmetricKey_, unprotectedAttrs_, version_

Constructor Summary

Constructors

Constructor and Description
SMimeEncrypted(java.io.InputStream is) Creates a new SMimeEncrypted object where the BER encoded message is read from the given input stream.
SMimeEncrypted(java.io.InputStream is, AlgorithmID contentEA, int keyLength) Creates a new SMimeEncrypted object where the data to be enveloped is read from the given InputStream.

Method Summary

Modifier and Type	Method and Description
void	addRecipient(X509Certificate recipientCertificate, AlgorithmID keyEA) Adds one recipient to this S/MIME EnvelopedData object.
void	decode(java.io.InputStream is) Reads and decodes the enveloped message from an input stream.
void	decryptSymmetricKey(KeyAndCertificateSource keyAndCertificateSource) Locates one of user's decryption keys that is appropriate for decrypting one of the content-encryption keys, decrypts the content-encryption key, and prepares the cipher for decrypting the encrypted content.
void	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 SMimeEncrypted object for the requesting recipient, specified by its recipientInfoIndex.
void	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 SMimeEncrypted object for the requesting recipient, specified by the given recipient identifier.
void	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 SMimeEncrypted object for the requesting recipient, specified by the given recipient certificate.
void	decryptSymmetricKey(SecureStringBuffer password, int recipientInfoIndex) Uses the specified password to derive a key for decrypting the content-encryption key to setup the cipher for decrypting the encrypted content of this SMimeEncrypted object for the requesting recipient, specified by its recipientInfoIndex.
int	decryptSymmetricKey(User user) Locates one of user's decryption keys that is appropriate for decrypting one of the content-encryption keys, decrypts the content-encryption key, and prepares the cipher for decrypting the encrypted content.
AlgorithmID	getEncryptionAlgorithm() Returns the content-encryption algorithm (including any associated parameters) of this SMimeEncrypted object.
int	getRecipientInfoIndex(X509Certificate recipientCertificate) Returns the recipient info index matching to the supplied recipient certificate.
ASN1Object	toASN1Object() Returns the S/MIME enveloped message as an ASN1Object.
void	writeTo(java.io.OutputStream os) Writes this SMimeEncrypted object to the supplied output stream.
void	writeTo(java.io.OutputStream os, int blockSize) Writes this SMimeEncrypted object to the supplied output stream.

Methods inherited from class iaik.cms.EnvelopedDataStream

addRecipientInfo, getBlockSize, getContentType, getEncryptedContentInfo, getInputStream, getOriginatorInfo, getRecipientInfo, getRecipientInfo, getRecipientInfos, getUnprotectedAttribute, getUnprotectedAttributes, getVersion, notifyEOF, setBlockSize, setOriginatorInfo, setRecipientInfos, setUnprotectedAttributes, setupCipher, setupCipher, setupCipher, setupCipher, setupCipher, setupCipher, toASN1Object, toString, toString

Methods inherited from class java.lang.Object

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

Constructor Detail

SMimeEncrypted

public SMimeEncrypted(java.io.InputStream is,
                      AlgorithmID contentEA,
                      int keyLength)
               throws java.security.NoSuchAlgorithmException

Creates a new SMimeEncrypted object where the data to be enveloped is read from the given InputStream.

This constructor automatically will create the symmetric content encryption key for the specified algorithm.

Parameters:

is - an InputStream holding the data to be enveloped

contentEA - the content encryption algorithm to be used

keyLength - the length of the key; undefined values set the default key length for the specified algorithm (e.g. 128 for RC2)

Throws:

java.security.NoSuchAlgorithmException - if there is no implementation for the specified algorithm

SMimeEncrypted

public SMimeEncrypted(java.io.InputStream is)
               throws java.io.IOException

Creates a new SMimeEncrypted object where the BER encoded message is read from the given input stream.

Do not use this constructor for supplying the content data to be enveloped. This constructor may be used by the recipient for parsing an already exisiting SMimeEncrypted object, supplied as BER encoding from an input stream, that may have been created by means of the writeTo method.

Use the SMimeEncrypted(InputStream is, AlgorithmID contentEA, int keyLength) constructor for supplying the content data to be enveloped when creating a SMimeEncrypted object.

Parameters:

is - the input stream where the BER encoded message shall be read from

Throws:

java.io.IOException - if an I/O error occurs

Method Detail

decode

public void decode(java.io.InputStream is)
            throws java.io.IOException

Reads and decodes the enveloped message from an input stream.

Specified by:

decode in interface ContentStream

Overrides:

decode in class EnvelopedDataStream

Parameters:

is - the InputStream holding a BER encoded SMimeEncrypted object

Throws:

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

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 quering 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 void 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 SMimeEncrypted 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 reading the data obtained by calling the getInputStream method. So don´t call getInputStream 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 decryptSymmetricKey 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.

recipientInfoIndex - the index into the recipientInfos field

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 recipient key is not valid

SMimeException

decryptSymmetricKey

public void decryptSymmetricKey(SecureStringBuffer password,
                                int recipientInfoIndex)
                         throws SMimeException,
                                java.security.InvalidKeyException

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

This method first uses the given password to derive a 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 reading the data obtained by calling the getInputStream method. So don´t call getInputStream 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.

Parameters:

password - the password used to derive the key to be used for decrypting the encrypted content-encryption key.

recipientInfoIndex - the index into the recipientInfos field

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 recipient key is not valid

SMimeException

decryptSymmetricKey

public void 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 SMimeEncrypted 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 reading the data obtained by calling the getInputStream method. So don´t call getInputStream 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.

recipientIdentifier - specifies which RecipientInfo the given key belongs to

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

SMimeException

decryptSymmetricKey

public void 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 SMimeEncrypted 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 reading the data obtained by calling the getInputStream method. So don´t call getInputStream 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.

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

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

decryptSymmetricKey

public int decryptSymmetricKey(User user)
                        throws UserNotLoggedInException,
                               NotARecipientException,
                               SMimeException

Locates one of user's decryption keys that is appropriate for decrypting one of the content-encryption keys, decrypts the content-encryption key, and prepares the cipher for decrypting the encrypted content.

The cipher will be only initialized for decrypting with this call; The encrypted-content decryption actually is done when the data is read by calling the getInputStream method. So don´t call this method before decrypting the encrypted content-encryption key!

Note:

This method is only capable of searching recipient information that is in 'key transport' (KeyTransRecipientInfo) format and contains the key identifier in 'issuerAndSerialNumber' (IssuerAndSerialNumber) format; all other formats of recipient information are ignored.

Parameters:

user - the user

Returns:

the index of the recipient information from which the symmetric content-encryption key was decrypted

Throws:

UserNotLoggedInException - if the user is not logged in

NotARecipientException - if the user is not listed as a recipient (unable to decrypt the content)

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

Since:

7.1

decryptSymmetricKey

public void decryptSymmetricKey(KeyAndCertificateSource keyAndCertificateSource)
                         throws NotARecipientException,
                                SMimeException

Locates one of user's decryption keys that is appropriate for decrypting one of the content-encryption keys, decrypts the content-encryption key, and prepares the cipher for decrypting the encrypted content.

The cipher will be only initialized for decrypting with this call; The encrypted-content decryption actually is done when the data is read by calling the getInputStream method. So don´t call this method before decrypting the encrypted content-encryption key!

Note:

This method is only capable of searching recipient information that is in 'key transport' (KeyTransRecipientInfo) format and contains the key identifier in 'issuerAndSerialNumber' (IssuerAndSerialNumber) format; all other formats of recipient information are ignored.

Parameters:

keyAndCertificateSource - a user's keys and certificates

Throws:

NotARecipientException - if the user is not listed as a recipient (unable to decrypt the content)

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

Since:

7.1

addRecipient

public void addRecipient(X509Certificate recipientCertificate,
                         AlgorithmID keyEA)
                  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 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

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

Throws:

SMimeException - if it was not possible to encrypt the symmetric key for this recipient

getEncryptionAlgorithm

public AlgorithmID getEncryptionAlgorithm()

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

Returns:

the content-encryption AlgorithmID

toASN1Object

public ASN1Object toASN1Object()
                        throws CMSException

Returns the S/MIME enveloped message as an ASN1Object. Automatically enforces block encoding with a block size of 2048.

Specified by:

toASN1Object in interface ContentStream

Overrides:

toASN1Object in class EnvelopedDataStream

Returns:

the S/MIME enveloped message as an ASN1Object

Throws:

CMSException - if an error occurs while building the ASN.1 object

writeTo

public void writeTo(java.io.OutputStream os)
             throws java.io.IOException

Writes this SMimeEncrypted object to the supplied output stream. Automatically enforces block encoding with a block size of 2048.

Overrides:

writeTo in class EnvelopedDataStream

Parameters:

os - the output stream to which this SMimeEncrypted shall be written

Throws:

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

writeTo

public void writeTo(java.io.OutputStream os,
                    int blockSize)
             throws java.io.IOException

Writes this SMimeEncrypted object to the supplied output stream. The blockSize parameter indicates the block size to be used for performimg block encoding.

Overrides:

writeTo in class EnvelopedDataStream

Parameters:

os - the output stream to which this SMimeEncrypted shall be written

blockSize - the block size for using block encoding

Throws:

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