codec.pkcs7
Class SignedAndEnvelopedData

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

All Implemented Interfaces:

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

public class SignedAndEnvelopedData

extends ASN1Sequence

implements ASN1RegisteredType, CertificateSource, Signable, Serializable

The definition of this structure is:

 SignedAndEnvelopedData ::= SEQUENCE {
   version Version,
   recipientInfos RecipientInfos,
   digestAlgorithms DigestAlgorithmIdentifiers,
   encryptedContentInfo EncryptedContentInfo,
   certificates
     [0] IMPLICIT ExtendedCertificatesAndCertificates OPTIONAL,
   crls
     [1] IMPLICIT CertificateRevocationLists OPTIONAL,
   signerInfos SignerInfos
 }
 DigestAlgorithmIdentifiers ::= SET OF DigestAlgorithmIdentifier
 SignerInfos ::= SET OF SignerInfo
 

Please note that SignerInfo structures only store the issuer and serial number of the signing certificate but not the certificate itself. Neither are certificates added automatically by this class when signing is done. If a certificate shall be included with an instance of this class then it must be added explicitly by calling addCertificate(..).

The encryption and decryption methods of this class do not work like update(...) of a Cipher class but encrypt and decrypt data with a freshly initialized cipher instance.

Version:

"$Id: SignedAndEnvelopedData.java,v 1.6 2002/08/28 21:40:35 jpeters Exp $"

Author:

Volker Roth, Markus Tak

See Also:

Serialized Form

Field Summary

protected ASN1Set	cache_ The cache encoded X.509 certificates.
protected Certificates	certs_ The X.509 certificates.
protected ASN1Set	crls_ The revocation lists.
protected ASN1Set	digestID_ The DigestAlgorithmIdentifiers.
protected CertificateFactory	factory_ The certificate factory that is used for decoding certificates.
protected EncryptedContentInfo	info_ The EncryptedContentInfo.
protected ASN1SetOf	recipients_ The RecipientInfos.
protected ASN1SetOf	sInfos_ The SignerInfos.

Fields inherited from class java.util.AbstractList

modCount

Fields inherited from interface codec.util.CertificateSource

ALL, DATA_ENCIPHERMENT, KEY_AGREEMENT, KEY_CERT_SIGN, KEY_ENCIPHERMENT, NON_REPUDIATION

Constructor Summary

SignedAndEnvelopedData()
Creates an instance ready for decoding.

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

Method Summary

void	addCertificate(X509Certificate cert) Adds the given certificate to this structure if none with the same issuer and serial number already exists.
void	addRecipient(X509Certificate cert) This method adds a recipient to the list of recipients.
void	addSignerInfo(SignerInfo info) Adds the given SignerInfo to this instance.
Iterator	certificates(Principal subject) Retrieves certificates based on the distinguished name of the certificate's subject.
Iterator	certificates(Principal subject, int keyUsage) Retrieves certificates based on the distinguished name of the certificate's subject and a number of key usage bits.
byte[]	decryptBulkData(byte[] b)
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.
byte[]	encryptBulkData(byte[] b)
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.
X509Certificate	getCertificate(Principal issuer, BigInteger serial) This method retrieves a certificate based on the distinguished name of the certificate's issuer as well as its serial number, as assigned by the issuer.
List	getCertificates() This method returns the certificates stored in this structure.
ASN1Type	getContent() This method retrieves the content of this structure, consisting of the ASN.1 type embedded in the ContentInfo structure.
ASN1ObjectIdentifier	getContentType() Returns the content type of the content embedded in this structure.
byte[]	getData() This method decrypts and returns the decrypted data contained in this instance or null if there is no contained data.
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).
SignerInfo	getSignerInfo(X509Certificate cert) Returns the SignerInfo that matches the given certificate.
List	getSignerInfos() This method returns the SignerInfos of the signers of this structure.
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	setCertificateFactory(CertificateFactory factory) Sets the certificate factory to use for decoding certificates.
void	setContentType(ASN1ObjectIdentifier oid) Sets the content type to the given OID.
void	setData(byte[] b) This method wraps the given bytes into a Data type and sets it as the content.
void	setData(InputStream in) Encrypts the given data and inserts it as Data content.
void	setDataContentType() Sets the content type to Data and clears the actual content.
String	toString() Returns a string representation of this object.

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, 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

digestID_

protected ASN1Set digestID_

The DigestAlgorithmIdentifiers.

certs_

protected Certificates certs_

The X.509 certificates.

sInfos_

protected ASN1SetOf sInfos_

The SignerInfos.

crls_

protected ASN1Set crls_

The revocation lists.

recipients_

protected ASN1SetOf recipients_

The RecipientInfos.

info_

protected EncryptedContentInfo info_

The EncryptedContentInfo.

cache_

protected ASN1Set cache_

The cache encoded X.509 certificates. This cache is filled with opaque versions on encoding this instance.

factory_

protected CertificateFactory factory_

The certificate factory that is used for decoding certificates.

Constructor Detail

SignedAndEnvelopedData

public SignedAndEnvelopedData()

Creates an instance ready for decoding.

SignedAndEnvelopedData

public SignedAndEnvelopedData(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

addCertificate

public void addCertificate(X509Certificate cert)

Adds the given certificate to this structure if none with the same issuer and serial number already exists.

Parameters:

cert - The certificate to add.

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.

addSignerInfo

public void addSignerInfo(SignerInfo info)

Adds the given SignerInfo to this instance. This method should be used rarely. In general, the signing methods take care of adding SignerInfo instances. Explicit adding of a SignerInfo is provided only in those cases where fine control of the creation of signatures is required.

Specified by:

addSignerInfo in interface Signable

Parameters:

info - The SignerInfo to add.

Throws:

NullPointerException - if the info is null.

certificates

public Iterator certificates(Principal subject)

Description copied from interface: CertificateSource

Retrieves certificates based on the distinguished name of the certificate's subject.

Specified by:

certificates in interface CertificateSource

Following copied from interface: codec.util.CertificateSource

Parameters:

subject - The subject DN of the certificate that should be retrieved.

Returns:

An Iterator of all known certificates with the given subject DN.

See Also:

CertificateIterator

certificates

public Iterator certificates(Principal subject,
                             int keyUsage)

Description copied from interface: CertificateSource

Retrieves certificates based on the distinguished name of the certificate's subject and a number of key usage bits.

Specified by:

certificates in interface CertificateSource

Following copied from interface: codec.util.CertificateSource

Parameters:

subject - The subject DN of the certificate that should be retrieved. A value of null matches every subject DN.

keyUsage - The mask of key usage bits; at least one of these bits must be set in the key usage extension of matching certificates. A value of 0 disables key usage checking.

Returns:

An Iterator of all known certificates with the given subject DN that match at least one of the given key usage bits.

See Also:

CertificateIterator

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.

decryptBulkData

public byte[] decryptBulkData(byte[] b)
                       throws GeneralSecurityException

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.

encryptBulkData

public byte[] encryptBulkData(byte[] b)
                       throws GeneralSecurityException

getCertificate

public X509Certificate getCertificate(Principal issuer,
                                      BigInteger serial)

Description copied from interface: CertificateSource

This method retrieves a certificate based on the distinguished name of the certificate's issuer as well as its serial number, as assigned by the issuer.

Specified by:

getCertificate in interface CertificateSource

Following copied from interface: codec.util.CertificateSource

Parameters:

issuer - The issuer distinguished name.

serial - The serial number.

Returns:

The certificate or null if it is not found.

getCertificates

public List getCertificates()

This method returns the certificates stored in this structure. Each certificate can be casted to a X509Certificate.

Returns:

An unmodifiable list view of the certificates.

getContent

public ASN1Type getContent()
                    throws GeneralSecurityException

This method retrieves the content of this structure, consisting of the ASN.1 type embedded in the ContentInfo structure. Beware, the content type might be faked by adversaries, if it is not of type Data. If it is not data then the authenticated content type must be given as an authenticated attribute in all the SignerInfo structures.

Specified by:

getContent in interface Signable

Returns:

The contents octets.

getContentType

public ASN1ObjectIdentifier getContentType()

Returns the content type of the content embedded in this structure. The returned OID is a copy, no side effects are caused by modifying it.

Specified by:

getContentType in interface Signable

Returns:

The content type of this structure's payload.

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.

getOID

public ASN1ObjectIdentifier getOID()

Returns the OID of this structure. The returned OID is a copy, no side effects are caused by modifying it.

Specified by:

getOID in interface ASN1RegisteredType

Returns:

The OID.

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.

getRecipientInfos

public List getRecipientInfos()

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

Returns:

The list of recipient infos.

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.

getSignerInfo

public SignerInfo getSignerInfo(X509Certificate cert)

Returns the SignerInfo that matches the given certificate.

Specified by:

getSignerInfo in interface Signable

Parameters:

cert - The certificate matching the SignerInfo to be retrieved.

Returns:

The SignerInfo or null if no matching one is found.

getSignerInfos

public List getSignerInfos()

This method returns the SignerInfos of the signers of this structure.

Returns:

The unmodifiable view of the list of SignerInfos.

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.

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.

setCertificateFactory

public void setCertificateFactory(CertificateFactory factory)

Sets the certificate factory to use for decoding certificates.

Parameters:

factory - The certificate factory or null if the default X.509 factory shall be used.

setContentType

public void setContentType(ASN1ObjectIdentifier oid)

Sets the content type to the given OID. The content itself is set to null. This method should be called if the content to be signed is external (not inserted into this structure).

If this structure is signed with the Signer then the SignerInfo that is passed to it must have either:

• no authenticated content type attribute, or
• the authenticated content type attribute must match oid.

In the first case, a new authenticated content type attribute with oid as its value will be added to the SignerInfo automatically (if the content type is not Data or at least one other authenticated attribute is already in that SignerInfo.

Parameters:

oid - The OID that identifies the content type of the signed data.

Throws:

NullPointerException - if oid is null.

setData

public void setData(byte[] b)
             throws IOException,
                    GeneralSecurityException

This method wraps the given bytes into a Data type and sets it as the content.

Please note that the signing process implemented in this class does not care about the content. Setting a content before signing does not sign the content. The data to be signed must always be passed to one of the update methods.

Parameters:

b - The opaque contents to embed in this structure.

Throws:

IllegalStateException - if the DEK is not initialized.

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

setData

public void setData(InputStream in)
             throws GeneralSecurityException,
                    IOException

Encrypts the given data and inserts it as Data content. The stream is not closed.

Throws:

IllegalStateException - if the DEK is not initialized.

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

setDataContentType

public void setDataContentType()

Sets the content type to Data and clears the actual content. Call this method when external data is signed, and no particular content type shall be used. This method calls setContentType(new ASN1ObjectIdentifier(DATA_OID)) .

toString

public String toString()

Returns a string representation of this object.

Overrides:

toString in class ASN1AbstractCollection

Returns:

The string representation.