codec.pkcs7
Class EnvelopedData

java.lang.Object
  |
  +--java.util.AbstractCollection
        |
        +--java.util.AbstractList
              |
              +--java.util.ArrayList
                    |
                    +--codec.asn1.ASN1AbstractCollection
                          |
                          +--codec.asn1.ASN1Sequence
                                |
                                +--codec.pkcs7.EnvelopedData

All Implemented Interfaces:

ASN1Collection, ASN1RegisteredType, ASN1Type, Cloneable, Collection, Externalizable, List, Serializable

public class EnvelopedData

extends ASN1Sequence

implements ASN1RegisteredType

This class represents the PKCS#7 EnvelopedData type, which is defined as follows:

 EnvelopedData ::= SEQUENCE {
   version Version,
   recipientInfos RecipientInfos,
   encryptedContentInfo EncryptedContentInfo
 }
 RecipientInfos ::= SET OF RecipientInfo
 

See class RecipientInfo for a description of the RecipientInfo structure.

Version:

"$Id: EnvelopedData.java,v 1.6 2004/08/12 12:16:19 pebinger Exp $"

Author:

Volker Roth

See Also:

Serialized Form

Field Summary

static int	BUFFER_SIZE The size of the buffer allocated for reading and verifying data in case this is a detached signature file.
protected ContentInfo	content_ The ContentInfo.
protected EncryptedContentInfo	info_ The EncryptedContentInfo.
protected ASN1SetOf	recipients_ The RecipientInfos.
protected ASN1Integer	version_ The version of this structure.

Fields inherited from class java.util.AbstractList

modCount

Constructor Summary

EnvelopedData()
This method calls builds the tree of ASN.1 objects used for decoding this structure.

EnvelopedData(SecretKey bek, String bea, AlgorithmParameters params)
Creates an instance that is initialized with the given secret key and algorithm parameters.

Method Summary

void	addRecipient(X509Certificate cert) This method adds a recipient to the list of recipients.
void	addRecipient(X509Certificate cert, int encType) same as above but with an explicit encodingType
void	decryptBulkData(InputStream in, OutputStream out) This method reads encrypted bulk data from the input stream, decrypts and writes the decrypted data to the given output stream.
void	encryptBulkData(InputStream in, OutputStream out) This method reads plaintext bulk data from the input stream, encrypts it and writes the encrypted data to the given output stream.
ASN1ObjectIdentifier	getContentType() Retrieves and returns the content type of the content stored in the encryptedContentInfo of this structure.
byte[]	getData() This method decrypts and returns the decrypted data contained in this instance or null if there is no contained data.
EncryptedContentInfo	getEncryptedContentInfo() This method returns the EncryptedContentInfo embedded in this instance.
ASN1ObjectIdentifier	getOID() Returns the OID of this structure.
RecipientInfo	getRecipientInfo(X509Certificate cert) This method retrieves the RecipientInfo macthing the given certificate or null if there is no such recipient.
List	getRecipientInfos() This method returns an unmodifiable list view on the RecipientInfos of this structure.
SecretKey	getSecretKey() This method returns the secret bulk encryption key if the underlying EncryptedContentInfo structure is already initialized properly (by calling one of this object's init methods).
boolean	hasRecipient(X509Certificate cert) This method checks if the given certificate is listed as a recipient by comparing the issuer and serial number of the given certificate with those listed in the recipient infos of this instance.
void	init(X509Certificate cert, PrivateKey kdk) Initializes this instance for encryption/decryption.
boolean	isReady() This method returns true if this instance is ready for encryption/decryption without further initialization.
void	setData(InputStream in) Encrypts the given data and inserts it as Data content.

Methods inherited from class codec.asn1.ASN1Sequence

getTag

Methods inherited from class codec.asn1.ASN1AbstractCollection

checkConstraints, decode, encode, getCollection, getConstraint, getTagClass, getValue, isExplicit, isOptional, isType, readExternal, setConstraint, setExplicit, setOptional, toString, writeExternal

Methods inherited from class java.util.ArrayList

add, add, addAll, addAll, clear, clone, contains, ensureCapacity, get, indexOf, isEmpty, lastIndexOf, remove, removeRange, set, size, toArray, toArray, trimToSize

Methods inherited from class java.util.AbstractList

equals, hashCode, iterator, listIterator, listIterator, subList

Methods inherited from class java.util.AbstractCollection

containsAll, remove, removeAll, retainAll

Methods inherited from class java.lang.Object

finalize, getClass, notify, notifyAll, wait, wait, wait

Methods inherited from interface codec.asn1.ASN1Type

checkConstraints, decode, encode, getConstraint, getTag, getTagClass, getValue, isExplicit, isOptional, isType, setConstraint, setExplicit, setOptional

Methods inherited from interface java.util.Collection

add, addAll, clear, contains, containsAll, equals, hashCode, isEmpty, iterator, remove, removeAll, retainAll, size, toArray, toArray

Methods inherited from interface java.util.List

containsAll, equals, hashCode, iterator, listIterator, listIterator, remove, removeAll, retainAll, subList

Field Detail

BUFFER_SIZE

public static final int BUFFER_SIZE

The size of the buffer allocated for reading and verifying data in case this is a detached signature file.

version_

protected ASN1Integer version_

The version of this structure.

recipients_

protected ASN1SetOf recipients_

The RecipientInfos.

info_

protected EncryptedContentInfo info_

The EncryptedContentInfo.

content_

protected ContentInfo content_

The ContentInfo.

Constructor Detail

EnvelopedData

public EnvelopedData()

This method calls builds the tree of ASN.1 objects used for decoding this structure.

EnvelopedData

public EnvelopedData(SecretKey bek,
                     String bea,
                     AlgorithmParameters params)
              throws InvalidAlgorithmParameterException

Creates an instance that is initialized with the given secret key and algorithm parameters. If this constructor is used then this instance need not be initialized anymore with the init method for adding recipients.

Parameters:

bek - The secret key to use for bulk encryption.

bea - The name of the bulk encryption algorithm.

params - The AlgorithmParameters of the bulk encryption algorithm.

Throws:

InvalidAlgorithmParameterException - just what is says...

Method Detail

getOID

public ASN1ObjectIdentifier getOID()

Returns the OID of this structure.

Specified by:

getOID in interface ASN1RegisteredType

Returns:

The OID.

getContentType

public ASN1ObjectIdentifier getContentType()

Retrieves and returns the content type of the content stored in the encryptedContentInfo of this structure. This value is meaningful only if this instance was decoded or initialized properly.

getEncryptedContentInfo

public EncryptedContentInfo getEncryptedContentInfo()

This method returns the EncryptedContentInfo embedded in this instance. This method is hardly ever used. Its primary purpose is to allow customized decryption of bulk encryption keys e.g., via SmartCards. This would work as follows: The application

• retrieves a matching RecipientInfo from this instance and extracts the encrypted bulk encryption key and the (asymmetric) key encryption algorithm identifier (with parameters and algorithm identifier).
• retrieves the EncryptedContentInfo and from that the bulk encryption algorithm and the bulk encryption algorithm parameters.
• decrypts and generates the secret bulk encryption key by customized means (e.g., via SmartCard).
• initializes the EncryptedContentInfo directly with the freshly decrypted bulk encryption key.
• decrypts the bulk data either via this class or directly via the embedded EncryptedContentInfo instance.

Returns:

The EncryptedContentInfo

getRecipientInfos

public List getRecipientInfos()

This method returns an unmodifiable list view on the RecipientInfos of this structure.

Returns:

The list of recipient infos.

hasRecipient

public boolean hasRecipient(X509Certificate cert)

This method checks if the given certificate is listed as a recipient by comparing the issuer and serial number of the given certificate with those listed in the recipient infos of this instance.

Parameters:

cert - The certificate that identifies the recipient.

Returns:

true if a recipient who matches the given certificate is included in this structure.

getRecipientInfo

public RecipientInfo getRecipientInfo(X509Certificate cert)

This method retrieves the RecipientInfo macthing the given certificate or null if there is no such recipient.

Parameters:

cert - The certificate that identifies the recipient.

Returns:

The RecipientInfo of the recipient or null if no matching recipient was found.

addRecipient

public void addRecipient(X509Certificate cert)
                  throws GeneralSecurityException,
                         BadNameException

This method adds a recipient to the list of recipients. Please note that this works only if the underlying EncryptedContentInfo is initialized properly. This is done by either of two means:

• creating an instance of this class with the non-default constructor that takes as arguments a secret key and algorithm parameters, or
• by calling init with a certificate that is listed as recipient and appropriate private key.

This ensures that the bulk encryption key is available. This key is then encrypted for the recipient specified in the given certificate (by encrypting with the public key enclosed in it) and an appropriate RecipientInfo instance is created and added to the list of recipient infos in this instance.

Parameters:

cert - The certificate of the recipient.

Throws:

GeneralSecurityException - if some cipher operation fails. The reason can bedetermined from the actual subclass that is thrown.

BadNameException - if the issuer name in the certificate cannot be parsed.

addRecipient

public void addRecipient(X509Certificate cert,
                         int encType)
                  throws GeneralSecurityException,
                         BadNameException

same as above but with an explicit encodingType

Parameters:

cert -

encType -

Throws:

GeneralSecurityException -

BadNameException -

init

public void init(X509Certificate cert,
                 PrivateKey kdk)
          throws GeneralSecurityException,
                 NoSuchElementException

Initializes this instance for encryption/decryption. The given certificate must be registered as recipient and the private key must match the certificate. This method actually looks for a RecipientInfo matching the given certificate and calls init of the EncryptedContentInfo contained in this structure.

This method need to be called only if this instance was not initialized with a secret key for bulk encryption, but was initialized through parsing it from a DER stream. In other words, this method is probably used only when reading EnvelopedData sent by someone else but hardly ever if it is generated.

Please note that, once this instance is properly initialized, additional recipients might be added to it unless this structure is protected by integrity measures (such as wrapping it in a SignedData structure.

Parameters:

kdk - The private Key Decryption Key required to decrypt the DEK.

cert - The certificate matching the private key.

Throws:

GeneralSecurityException - if some cipher operation fails.

NoSuchElementException - if no matching RecipientInfo is found in this instance.

isReady

public boolean isReady()

This method returns true if this instance is ready for encryption/decryption without further initialization.

Returns:

true if it is ready.

setData

public void setData(InputStream in)
             throws GeneralSecurityException,
                    IOException

Encrypts the given data and inserts it as Data content.

Throws:

IllegalStateException - if the DEK is not initialized.

GeneralSecurityException - if something nasty happens while encrypting such as algorithms not found, bad paddings et cetera.

getData

public byte[] getData()
               throws GeneralSecurityException,
                      NoSuchElementException

This method decrypts and returns the decrypted data contained in this instance or null if there is no contained data.

Throws:

IllegalStateException - if the DEK is not initialized.

NoSuchElementException - if the content type is not Data.

GeneralSecurityException - if a cipher operation fails.

getSecretKey

public SecretKey getSecretKey()

This method returns the secret bulk encryption key if the underlying EncryptedContentInfo structure is already initialized properly (by calling one of this object's init methods). If the key is not available (yet) then null is returned.

Returns:

The BEK or null.

Throws:

IllegalStateException - if this instance is not yet initialized.

decryptBulkData

public void decryptBulkData(InputStream in,
                            OutputStream out)
                     throws IOException,
                            GeneralSecurityException

This method reads encrypted bulk data from the input stream, decrypts and writes the decrypted data to the given output stream. This instance must be properly initialized for this operation to work.

Parameters:

in - The input stream from which the data is read.

out - The output stream to which the data is written.

encryptBulkData

public void encryptBulkData(InputStream in,
                            OutputStream out)
                     throws IOException,
                            GeneralSecurityException

This method reads plaintext bulk data from the input stream, encrypts it and writes the encrypted data to the given output stream. This instance must be properly initialized for this operation to work.

Parameters:

in - The input stream from which the data is read.

out - The output stream to which the data is written.