com.ibm.security.pkcs7
Class EnvelopedData

java.lang.Object
  |
  +--com.ibm.security.pkcsutil.PKCSDerObject
        |
        +--com.ibm.security.pkcs7.Content
              |
              +--com.ibm.security.pkcs7.EnvelopedData

public final class EnvelopedData
extends Content
implements Cloneable

Implements the ASN.1 EnvelopedData type.

This class in mainly used as a container for encrypted data. It encapsulates the encrypted content and information specific to the recipients of the content. The combination of the encrypted content and the content encryption key -- which was encrypted in the recipient's public key -- is a "digital envelope" for that recipient.

A recipient opens the enveloped data by first opening its digital envelope using its private key, thus extracting the content-encryption key. The content-encryption key is then used to decrypt the encrypted content.

EnvelopedData ::= SEQUENCE { version CMSVersion, originatorInfo [0] IMPLICIT OriginatorInfo OPTIONAL, recipientInfos RecipientInfos, encryptedContentInfo EncryptedContentInfo, unprotectedAttrs [1] IMPLICIT UnprotectedAttributes OPTIONAL }

This definition reflects PKCS #7 version 1.5 specifications with selected enhancements from the Cryptographic Message Syntax (CMS) RFC 2630 specifications.

Only X509Certificate objects are supported for recipient certificates.

See Also:
OriginatorInfo, RecipientInfo, EncryptedContentInfo

Fields inherited from class com.ibm.security.pkcsutil.PKCSDerObject
provider
 
Constructor Summary
EnvelopedData(byte[] der)
          Create an EnvelopedData object with a DER-encoded byte array.
EnvelopedData(byte[] der, String provider)
          Create an EnvelopedData object with a DER-encoded byte array.
EnvelopedData(Certificate[] certs, ContentInfo contentInfo, String encryptionAlgorithm, int keySize, PKCSAttributes unprotectedAttrs)
          Create an EnvelopedData object with the specified values.
EnvelopedData(Certificate[] certs, ContentInfo contentInfo, String encryptionAlgorithm, int keySize, PKCSAttributes unprotectedAttrs, String provider)
          Create an EnvelopedData object with the specified values.
EnvelopedData(OriginatorInfo originatorInfo, RecipientInfo[] recipientInfos, EncryptedContentInfo encryptedContentInfo, PKCSAttributes unprotectedAttrs)
          Create an EnvelopedData object with the specified values.
EnvelopedData(OriginatorInfo originatorInfo, RecipientInfo[] recipientInfos, EncryptedContentInfo encryptedContentInfo, PKCSAttributes unprotectedAttrs, String provider)
          Create an EnvelopedData object with the specified values.
EnvelopedData(String filename, boolean base64)
          Create an EnvelopedData with the filename of the DER-encoded or BASE64-encoded object.
EnvelopedData(String filename, boolean base64, String provider)
          Create an EnvelopedData with the filename of the DER-encoded or BASE64-encoded object.
 
Method Summary
 void addRecipient(Certificate[] certs)
          Adds a group of recipients, as identified by their certificates, to the EnvelopedData object.
 Object clone()
          Creates a clone of this EnvelopedData object.
protected  void decode(com.ibm.security.pkcs7.DerValue encoding)
          Initializes an EnvelopedData object from a DerValue.
 ContentInfo decrypt(PrivateKey key, Certificate cert)
          Decrypts the object's encrypted content.
 void encode(OutputStream os)
          Encodes this object to an OutputStream.
 boolean equals(Object other)
          Determines if this EnvelopedData object is equivalent to the input object.
protected  void finalize()
          Ensure that the contentEncryptionKey bytes are nulled out when there are no more references to this object.
 EncryptedContentInfo getEncryptedContentInfo()
          Returns a copy of the encryptedContentInfo for this object, or null if the encryptedContentInfo has not been set.
 ObjectIdentifier getObjectIdentifier()
          Returns a reference to the Object Identifier for this object.
 OriginatorInfo getOriginator()
          Returns a copy of the OriginatorInfo for this object, or null if the OriginatorInfo has not been set.
 RecipientInfo getRecipientInfo(Certificate cert)
          Returns a copy of the matching recipientInfo contained in this object for the specified certificate, or null if the recipientInfo objects have not been set.
 RecipientInfo[] getRecipientInfos()
          Returns a copy of the recipientInfo objects for this object, or null if the matching recipientInfo object could not be found.
 PKCSAttribute getUnprotectedAttribute(ObjectIdentifier oid)
          Returns a reference to an unprotected attribute from the unprotected attribute set based on an ObjectIdentifier.
 PKCSAttributes getUnprotectedAttributes()
          Returns a reference to the set unprotected attributes.
 BigInteger getVersion()
          Returns a reference to the version for this object.
 boolean hasRecipientInfo(Certificate cert)
          Checks if a matching recipientInfo contained in this object exists for the specified certificate.
 String toString()
          Returns a string representation of this EnvelopedData object.
 
Methods inherited from class com.ibm.security.pkcsutil.PKCSDerObject
decode, decode, encode, hashCode, read, readBASE64, write, write, writeBASE64
 
Methods inherited from class java.lang.Object
getClass, notify, notifyAll, wait, wait, wait
 

Constructor Detail

EnvelopedData

public EnvelopedData(byte[] der)
              throws IOException
Create an EnvelopedData object with a DER-encoded byte array.
Parameters:
der - a DER-encoded byte array of an EnvelopedData object.
Throws:
IOException - on decoding errors.

EnvelopedData

public EnvelopedData(byte[] der,
                     String provider)
              throws IOException
Create an EnvelopedData object with a DER-encoded byte array.
Parameters:
der - a DER-encoded byte array of an EnvelopedData object.
provider - the name of the java security provider to use
Throws:
IOException - on decoding errors.

EnvelopedData

public EnvelopedData(OriginatorInfo originatorInfo,
                     RecipientInfo[] recipientInfos,
                     EncryptedContentInfo encryptedContentInfo,
                     PKCSAttributes unprotectedAttrs)
Create an EnvelopedData object with the specified values. Each RecipientInfo contained in the input RecipientInfo array must contain an encrypted version of the secret key used to encrypt the content of the input EncryptedContentInfo.
Parameters:
orignatorInfo - the originator of this enveloped data. This argument may be null.
recipientInfos - an array of all the recipients of this enveloped data.
encryptedContentInfo - the encrypted content contained in an EncryptedContentInfo object.
unprotectedAttrs - PKCSAttributes collection of unprotected attributes. This argument may be null.

EnvelopedData

public EnvelopedData(OriginatorInfo originatorInfo,
                     RecipientInfo[] recipientInfos,
                     EncryptedContentInfo encryptedContentInfo,
                     PKCSAttributes unprotectedAttrs,
                     String provider)
Create an EnvelopedData object with the specified values. Each RecipientInfo contained in the input RecipientInfo array must contain an encrypted version of the secret key used to encrypt the content of the input EncryptedContentInfo.
Parameters:
orignatorInfo - the originator of this enveloped data. This argument may be null.
recipientInfos - an array of all the recipients of this enveloped data.
encryptedContentInfo - the encrypted content contained in an EncryptedContentInfo object.
unprotectedAttrs - PKCSAttributes collection of unprotected

EnvelopedData

public EnvelopedData(Certificate[] certs,
                     ContentInfo contentInfo,
                     String encryptionAlgorithm,
                     int keySize,
                     PKCSAttributes unprotectedAttrs)
              throws PKCSException,
                     IOException
Create an EnvelopedData object with the specified values. This constructor will encrypt the specified contentInfo with the indicated encryption algorithm and keysize. The secret key will be encrypted for each of the specified recipient certificates.
Parameters:
certs - Recipient certificate array
contentInfo - ContentInfo to encrypt
encryptionAlgorithm - Encryption algorithm string
keysize - Size of the secret key
unprotectedAttrs - PKCSAttributes collection of unprotected attributes. This argument may be null.

EnvelopedData

public EnvelopedData(Certificate[] certs,
                     ContentInfo contentInfo,
                     String encryptionAlgorithm,
                     int keySize,
                     PKCSAttributes unprotectedAttrs,
                     String provider)
              throws PKCSException,
                     IOException
Create an EnvelopedData object with the specified values. This constructor will encrypt the specified contentInfo with the indicated encryption algorithm and keysize. The secret key will be encrypted for each of the specified recipient certificates.
Parameters:
certs - Recipient certificate array
contentInfo - ContentInfo to encrypt
encryptionAlgorithm - Encryption algorithm string
keysize - Size of the secret key
unprotectedAttrs - PKCSAttributes collection of unprotected

EnvelopedData

public EnvelopedData(String filename,
                     boolean base64)
              throws IOException
Create an EnvelopedData with the filename of the DER-encoded or BASE64-encoded object.
Parameters:
filename - name of the DER-encoded or base64-encoded object
base64 - true if BASE64-encoded, false if DER-encoded
Throws:
IOException - on decoding errors.

EnvelopedData

public EnvelopedData(String filename,
                     boolean base64,
                     String provider)
              throws IOException
Create an EnvelopedData with the filename of the DER-encoded or BASE64-encoded object.
Parameters:
filename - name of the DER-encoded or base64-encoded object
base64 - true if BASE64-encoded, false if DER-encoded
Throws:
IOException - on decoding errors.
Method Detail

clone

public Object clone()
Creates a clone of this EnvelopedData object.
Overrides:
clone in class Object
Returns:
clone of this EnvelopedData object.

encode

public void encode(OutputStream os)
            throws IOException
Encodes this object to an OutputStream.
Overrides:
encode in class PKCSDerObject
Parameters:
os - the OutputStream to write the encoded data to.
Throws:
IOException - on encoding errors.

decode

protected void decode(com.ibm.security.pkcs7.DerValue encoding)
               throws IOException
Initializes an EnvelopedData object from a DerValue. The DER encoding must be in the format specified by the EnvelopedData ASN.1 notation.
Parameters:
encoding - a DER-encoded EnvelopedData object.
Throws:
IOException - on parsing error.

equals

public boolean equals(Object other)
Determines if this EnvelopedData object is equivalent to the input object.
Overrides:
equals in class PKCSDerObject
Parameters:
other - the object to compare this one to.
Returns:
true, if the two objects are equivalent, false otherwise.

addRecipient

public void addRecipient(Certificate[] certs)
                  throws PKCSException,
                         IOException
Adds a group of recipients, as identified by their certificates, to the EnvelopedData object.
Parameters:
certs - the X509Certificates representing the recipients to add.
Throws:
IOException - if extraction of a recipient identifier from an input certificate fails.
PKCSException - key encryption error.

getOriginator

public OriginatorInfo getOriginator()
Returns a copy of the OriginatorInfo for this object, or null if the OriginatorInfo has not been set.
Returns:
the OriginatorInfo for this object, or null if it has not been set.

getVersion

public BigInteger getVersion()
Returns a reference to the version for this object. BigInteger is an immutable object.
Returns:
the version for this object.

getRecipientInfos

public RecipientInfo[] getRecipientInfos()
Returns a copy of the recipientInfo objects for this object, or null if the matching recipientInfo object could not be found.
Returns:
the recipientInfos for this object, or null if the matching recipientInfo object could not be found.

getEncryptedContentInfo

public EncryptedContentInfo getEncryptedContentInfo()
Returns a copy of the encryptedContentInfo for this object, or null if the encryptedContentInfo has not been set.
Returns:
the encryptedContentInfo for this object, or null if the encryptedContentInfo has not been set.

getRecipientInfo

public RecipientInfo getRecipientInfo(Certificate cert)
                               throws IOException
Returns a copy of the matching recipientInfo contained in this object for the specified certificate, or null if the recipientInfo objects have not been set.
Returns:
the recipientInfo that matches the certificate, or null if the recipientInfos have not been set.

hasRecipientInfo

public boolean hasRecipientInfo(Certificate cert)
Checks if a matching recipientInfo contained in this object exists for the specified certificate.
Returns:
true if a matching recipientInfo contained in this object exists for the specified certificate, false otherwise.

getUnprotectedAttribute

public PKCSAttribute getUnprotectedAttribute(ObjectIdentifier oid)
Returns a reference to an unprotected attribute from the unprotected attribute set based on an ObjectIdentifier.
Parameters:
oid - ObjectIdentifier to match
Returns:
unprotected attribute matching the oid, null otherwise.

getUnprotectedAttributes

public PKCSAttributes getUnprotectedAttributes()
Returns a reference to the set unprotected attributes.
Returns:
unprotected PKCSAttribute set or null if none were set.

decrypt

public ContentInfo decrypt(PrivateKey key,
                           Certificate cert)
                    throws PKCSException,
                           IOException
Decrypts the object's encrypted content. A recipient identified by the input certificate is located in the object's set of RecipientInfo objects. Then the input private key is used to decrypt the encrypted content encryption key stored in the recipient info. This secret key is then used to decrypt the encrypted content. The decrypted content is returned as the content octets of a ContentInfo object.

The private key must be part of a matching key pair with the public key within the certificate.

Parameters:
key - a recipient's private key used for decryption.
cert - a certificate containing a recipient's identity.
Returns:
a ContentInfo object containing the decrypted content.
Throws:
IOException - if wrapping of the decrypted content into a ContentInfo object fails.
PKCSException - key or content decryption error.

getObjectIdentifier

public ObjectIdentifier getObjectIdentifier()
Returns a reference to the Object Identifier for this object.
Overrides:
getObjectIdentifier in class PKCSDerObject
Returns:
the Object Identifier for this object.

toString

public String toString()
Returns a string representation of this EnvelopedData object.
Overrides:
toString in class Content
Returns:
a string representation of this object.

finalize

protected void finalize()
Ensure that the contentEncryptionKey bytes are nulled out when there are no more references to this object.
Overrides:
finalize in class Object