codec.pkcs7
Class SignedData

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

All Implemented Interfaces:

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

public class SignedData

extends ASN1Sequence

implements ASN1RegisteredType, CertificateSource, Signable

The signatures generated by this class are compatible to Sun's jarsigner. The actual bytes being signed are denoted payload in this documenatation, in order to differentiate between the signing of arbitrary (opaque) data and the DER encoding of registered ASN.1 structures such as EnvelopedData.

Presently, only content of type Data is supported. Either detached signatures may be generated (in which case the content consists of a Data type with no content) or the payload may be embedded into the content info of this structure (automatically wrapped into a Data type.

Use SignerInfo instances for signing and verifying instances of this class such as illustrated in the code example below. This example shows how to verify a detached signature on a file. One PKCS#7 structure may contain multiple signatures. In the example given below, all of them are verified.

 public void verifyFile(SignedData sd, File file) {
     boolean ok;
     Iterator i;
     Verifier verifier;
     SignerInfo info;
     FileInputStream in;
     for (i = sd.getSignerInfos().iterator(); i.hasNext();) {
 	info = (SignerInfo) i.next();
 	System.out.println("\nVerifying:\n" + info.toString());
 	verifier = new Verifier(sd, info, null);
 	in = new FileInputStream(file);
 	verifier.update(in);
 	in.close();
 	ok = (verifier.verify() != null);
 
 	System.out.println(ok ? "Signature OK" : "BAD SIGNATURE!");
     }
 }
 

If the data embedded in a SignedData instance shall be verified then this data must be retrieved by means of the getData method first and must be passed to one of the update methods just as the detached data in the example above.

Likewise, if data shall be signed and attached to a SignedData instance then the signing process of that data must be completed as for detached data. The signed data then can be attached to the SignedData instance by means of the setData method. The definition of this structure is:

 SignedData ::= SEQUENCE {
   version Version,
   digestAlgorithms DigestAlgorithmIdentifiers,
   contentInfo ContentInfo,
   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(..).

Version:

"$Id: SignedData.java,v 1.8 2004/08/12 12:25:19 pebinger Exp $"

Author:

Volker Roth

See Also:

Serialized Form

Field Summary

protected ASN1Set	cache_ The cache encoded X.509 certificates.
protected Certificates	certs_ The X.509 certificates.
protected ContentInfo	content_ The ContentInfo.
protected ASN1Set	crls_ The revocation lists.
protected ASN1Set	digestID_ The DigestAlgorithmIdentifiers.
protected CertificateFactory	factory_ The certificate factory that is used for decoding certificates.
protected ASN1SetOf	infos_ 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

SignedData()
Creates an instance ready for decoding.

SignedData(int _version)
Creates an instance ready for decoding, allows the setting of the Version. needed for instance for TSP Structures.

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	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.
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.
Data	getData() This method retrieves the content from this structure's ContentInfo structure.
ASN1ObjectIdentifier	getOID() Returns the OID of this structure.
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	hasData() This method returns true if this structure has content of type Data and the content contained in it is not null.
void	setCertificateFactory(CertificateFactory factory) Sets the certificate factory to use for decoding certificates.
void	setContent(ASN1ObjectIdentifier oid, ASN1Type t) Sets the content to be embedded into this instance's ContentInfo.
void	setContent(ASN1RegisteredType t) Sets the content to be embedded into this instance's ContentInfo.
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	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.

infos_

protected ASN1SetOf infos_

The SignerInfos.

crls_

protected ASN1Set crls_

The revocation lists.

content_

protected ContentInfo content_

The ContentInfo.

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

SignedData

public SignedData()

Creates an instance ready for decoding.

SignedData

public SignedData(int _version)

Creates an instance ready for decoding, allows the setting of the Version. needed for instance for TSP Structures.

Method Detail

getContent

public ASN1Type getContent()

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.

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)) .

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.

setContent

public void setContent(ASN1RegisteredType t)

Sets the content to be embedded into this instance's ContentInfo.

Parameters:

t - The actual content.

setContent

public void setContent(ASN1ObjectIdentifier oid,
                       ASN1Type t)

Sets the content to be embedded into this instance's ContentInfo.

Parameters:

oid - The object identifier of the content.

t - The actual content.

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.

setData

public void setData(byte[] b)

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.

getData

public Data getData()
             throws NoSuchElementException

This method retrieves the content from this structure's ContentInfo structure. In general, this will be of type Data. The actual content type can be retrieved by calling getContentType. If the type is Data, then getData might be called. If the content type is Data then the easiest way to retrieve the actual payload bytes is to call:

signedData.getData().getByteArray()

Throws:

NoSuchElementException - if the content type is not Data.

hasData

public boolean hasData()

This method returns true if this structure has content of type Data and the content contained in it is not null.

Returns:

true if there is a payload.

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.

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.

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.

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.

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.

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

getSignerInfos

public List getSignerInfos()

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

Returns:

The unmodifiable view of the list of SignerInfos.

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.

toString

public String toString()

Returns a string representation of this object.

Overrides:

toString in class ASN1AbstractCollection

Returns:

The string representation.

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.