codec.pkcs7
Class SignerInfo

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

All Implemented Interfaces:

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

public class SignerInfo

extends ASN1Sequence

ATTENTION : if this object shall use the strict DER encoding rules, the function setStrict(true) must be called right after instantiating the object. This class represents a PKCS#7 SignerInfo structure. It is defined as follows:

 SignerInfo ::= SEQUENCE {
   version Version,
   issuerAndSerialNumber IssuerAndSerialNumber,
   digestAlgorithm DigestAlgorithmIdentifier,
   authenticatedAttributes [0] IMPLICIT Attributes OPTIONAL,
   digestEncryptionAlgorithm DigestEncryptionAlgorithmIdentifier,
   encryptedDigest EncryptedDigest,
   unauthenticatedAttributes [1] IMPLICIT Attributes OPTIONAL
 }
 EncryptedDigest ::= OCTET STRING
 DigestAlgorithmIdentifier ::= AlgorithmIdentifier
 DigestEncryptionAlgorithmIdentifier ::= AlgorithmIdentifier
 

For completeness, we also present the structures referenced in the SignerInfo structure.

 IssuerAndSerialNumber ::= SEQUENCE {
   issuer Name,
   serialNumber CertificateSerialNumber
 }
 CertificateSerialNumber ::= INTEGER
 Attributes ::= SET OF Attribute -- from X.501
 

Version:

"$Id: SignerInfo.java,v 1.3 2004/08/12 12:31:42 pebinger Exp $"

Author:

Volker Roth

See Also:

Serialized Form

Field Summary

protected String	algorithm_ The algorithm to use when a SignedData instance is used for signing or verifying.
protected Attributes	attr_ The unauthenticated attributes.
protected Attributes	auth_ The authenticated attributes.
protected AlgorithmIdentifier	cAlg_ The DigestEncryptionAlgorithmIdentifier.
protected AlgorithmIdentifier	dAlg_ The DigestAlgorithmIdentifier.
protected ASN1OctetString	edig_ The encrypted digest.
protected Name	issuer_ The issuer name.
protected ASN1Integer	serial_ The serial number.
protected AlgorithmParameterSpec	spec_ The signature algorithm parameters spec to use when verifying or signing SignedData instances.
protected ASN1Integer	version_ The version number of this SignerInfo.

Fields inherited from class java.util.AbstractList

modCount

Constructor Summary

SignerInfo()
Creates an instance ready for decoding.

SignerInfo(OIDRegistry registry)
Creates an instance ready for decoding.

SignerInfo(X509Certificate cert, String algorithm)
This method calls initializes this structure with the given arguments.

SignerInfo(X509Certificate cert, String algorithm, AlgorithmParameters params)
This method calls initializes this structure with the given arguments.

SignerInfo(X509Certificate cert, String algorithm, AlgorithmParameters params, int nameEncoding)
same as above but with an explicit nameEncoding.

SignerInfo(X509Certificate cert, String algorithm, int nameEncoding)
method as above, but with an explicit encoding type

Method Summary

void	addAuthenticatedAttribute(Attribute attr) Adds the given attribute to the list of authenticated attributes.
void	addUnauthenticatedAttribute(Attribute attr) Adds the given attribute to the list of unauthenticated attributes.
Attributes	authenticatedAttributes() Returns the authenticated attributes.
void	encode(Encoder encoder) Encodes this SignerInfo.
boolean	equivIssuerAndSerialNumber(X509Certificate cert) Checks if this SignerInfo has an issuer distinguished name and a serial number that are equivalent to those in the given certificate.
String	getAlgorithm() Returns the name of the signature algorithm.
AlgorithmIdentifier	getDigestAlgorithmIdentifier() This method returns the DigestAlgorithmIdentifier.
byte[]	getEncryptedDigest() This method returns the encrypted digest stored in this structure.
Principal	getIssuerDN() Returns the name of the issuer of the certificate of this signer.
AlgorithmParameterSpec	getParameterSpec() Returns the algorithm parameter spec for the parameters of the signature algorithm (PKCS#1 Version 2.1 Draft 1) or null if there are none.
BigInteger	getSerialNumber()
protected void	init() This method determines the signature algorithm and appropriate parameters for initializing the signature algorithm from the algorithm identifiers in this structure.
void	setEncryptedDigest(byte[] edig) This method sets the encrypted digest.
void	setStrict(boolean strictness) sets the strict parameter with the given value.
String	toString() Returns a string representation of this object.
Attributes	unauthenticatedAttributes() Returns the unauthenticated attributes.
void	update(Signature sig) This method updates the given Signature instance with the DER encoding of the authenticatedAttributes file of the SignerInfo structure if such attributes are given.

Methods inherited from class codec.asn1.ASN1Sequence

getTag

Methods inherited from class codec.asn1.ASN1AbstractCollection

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

version_

protected ASN1Integer version_

The version number of this SignerInfo.

issuer_

protected Name issuer_

The issuer name. Still of type ANY but being replaced by RDName soon.

serial_

protected ASN1Integer serial_

The serial number.

dAlg_

protected AlgorithmIdentifier dAlg_

The DigestAlgorithmIdentifier.

cAlg_

protected AlgorithmIdentifier cAlg_

The DigestEncryptionAlgorithmIdentifier.

auth_

protected Attributes auth_

The authenticated attributes.

attr_

protected Attributes attr_

The unauthenticated attributes.

edig_

protected ASN1OctetString edig_

The encrypted digest.

algorithm_

protected String algorithm_

The algorithm to use when a SignedData instance is used for signing or verifying.

spec_

protected AlgorithmParameterSpec spec_

The signature algorithm parameters spec to use when verifying or signing SignedData instances.

Constructor Detail

SignerInfo

public SignerInfo()

Creates an instance ready for decoding.

SignerInfo

public SignerInfo(OIDRegistry registry)

Creates an instance ready for decoding. The given registry is used to resolve attributes.

Parameters:

registry - The OIDRegistry to use for resolving attributes, or null if the default PKCS registry shall be used.

SignerInfo

public SignerInfo(X509Certificate cert,
                  String algorithm)
           throws BadNameException,
                  NoSuchAlgorithmException

This method calls initializes this structure with the given arguments. This constructore creates Version 1 SignerInfos. The given algorithm must be a PKCS#1 Version 1.5 conformant signature algorithm. In other words, the signature algorithm MUST NOT have algorithm parameters beyond those embedded in the SubjectPublicKeyInfo of the public key, and aliases for a slashed name form MUST be defined by JSPs (Java Security Providers). JSPs also MUST define OID aliases for the signature's raw cipher and the message digest.

If PKCS#1 version 2.1 Draft 1 signatures (RSASSA-PSS) shall be used then the constructor taking algorithm parameters must be called instead of this one.

Parameters:

cert - The signer's certificate.

algorithm - The JCA standard name of the PKCS#1 version 1.5 compliant signature algorithm.

Throws:

NoSuchAlgorithmException - if the signature algorithm name cannot be resolved to the OIDs of the names of its raw cipher algorithm and its digest algorithm.

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

IllegalArgumentException - if the OID to which the given algorithm name is mapped by means of the aliases of the installed providers is not a valid OID string.

SignerInfo

public SignerInfo(X509Certificate cert,
                  String algorithm,
                  int nameEncoding)
           throws BadNameException,
                  NoSuchAlgorithmException

method as above, but with an explicit encoding type

Parameters:

cert -

algorithm -

nameEncoding -

Throws:

BadNameException -

NoSuchAlgorithmException -

SignerInfo

public SignerInfo(X509Certificate cert,
                  String algorithm,
                  AlgorithmParameters params)
           throws BadNameException,
                  NoSuchAlgorithmException,
                  InvalidAlgorithmParameterException

This method calls initializes this structure with the given arguments. This constructore creates Version 1 SignerInfos. The given algorithm must be a PKCS#1 Version 2.1 Draft 1 conformant signature algorithm. The signature algorithm identifier is put into the place of the digest algorithm identifier. The given parameters are those of the signature algorithm (e. g. RSASSA-PSS). If the parameters are null then they are encoded as ASN1Null. The signature algorithm identifier is also put into the place of the digest encryption algorithm identifier (without parameters). PKCS#1 Version 2.1 Draft 1 does not specify how this case should be handled so we picked our choice.

Parameters:

cert - The signer's certificate.

algorithm - The JCA standard name of the PKCS#1 Version 2.1 Draft 1 compliant signature algorithm.

Throws:

NoSuchAlgorithmException - if the signature algorithm name cannot be resolved to the OIDs of the names of its raw cipher algorithm and its digest algorithm.

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

SignerInfo

public SignerInfo(X509Certificate cert,
                  String algorithm,
                  AlgorithmParameters params,
                  int nameEncoding)
           throws BadNameException,
                  NoSuchAlgorithmException,
                  InvalidAlgorithmParameterException

same as above but with an explicit nameEncoding.

Parameters:

cert -

algorithm -

params -

nameEncoding -

Throws:

BadNameException -

NoSuchAlgorithmException -

InvalidAlgorithmParameterException -

Method Detail

setStrict

public void setStrict(boolean strictness)

sets the strict parameter with the given value.

update

public void update(Signature sig)
            throws SignatureException

This method updates the given Signature instance with the DER encoding of the authenticatedAttributes file of the SignerInfo structure if such attributes are given.

Parameters:

sig - The Signature instance to be updated.

Throws:

SignatureException - if the signature instance is not properly initialized.

InconsistentStateException - in case of an internal error -- this should never happen.

setEncryptedDigest

public void setEncryptedDigest(byte[] edig)

This method sets the encrypted digest.

Parameters:

edig - The encrypted digest.

getEncryptedDigest

public byte[] getEncryptedDigest()

This method returns the encrypted digest stored in this structure. The EncryptedDigest is defined as

 EncryptedDigest ::= OCTET STRING
 

This octet string contains the encrypted digest info structure, which is reproduced below for completeness:

 DigestInfo ::= SEQUENCE {
   digestAlgorithm DigestAlgorithmIdentifier,
   digest Digest
 }
 Digest ::= OCTET STRING
 DigestAlgorithmIdentifier ::= AlgorithmIdentifier
 

Returns:

The encrypted digest.

authenticatedAttributes

public Attributes authenticatedAttributes()

Returns the authenticated attributes.

Returns:

The unmodifiable list of authenticated attributes.

addAuthenticatedAttribute

public void addAuthenticatedAttribute(Attribute attr)

Adds the given attribute to the list of authenticated attributes. This method should be used to add attributes because it clears the attributes instance's OPTIONAL flag. Alternatively, this can be done manually.

Parameters:

attr - The attribute.

unauthenticatedAttributes

public Attributes unauthenticatedAttributes()

Returns the unauthenticated attributes.

Returns:

The unmodifiable list of unauthenticated attributes.

addUnauthenticatedAttribute

public void addUnauthenticatedAttribute(Attribute attr)

Adds the given attribute to the list of unauthenticated attributes. This method should be used to add attributes because it clears the attributes instance's OPTIONAL flag. Alternatively, this can be done manually.

Parameters:

attr - The attribute.

getIssuerDN

public Principal getIssuerDN()

Returns the name of the issuer of the certificate of this signer.

Returns:

The issuer name.

getSerialNumber

public BigInteger getSerialNumber()

Returns:

The serial number.

getDigestAlgorithmIdentifier

public AlgorithmIdentifier getDigestAlgorithmIdentifier()

This method returns the DigestAlgorithmIdentifier.

Returns:

The DigestAlgorithmIdentifier.

getAlgorithm

public String getAlgorithm()
                    throws NoSuchAlgorithmException,
                           InvalidAlgorithmParameterException

Returns the name of the signature algorithm. This method calls init() if the name is not yet known in order to determine it by means of the JCA and the algorithm identifiers embedded in this structure.

Returns:

The algorithm name.

Throws:

NoSuchAlgorithmException - if the OIDs in this structure cannot be mapped onto an algorithm name by means of the alias definitions of the installed providers.

InvalidAlgorithmParameterException - if the signature algorithm identifier contains parameters but the parameters cannot be decoded.

getParameterSpec

public AlgorithmParameterSpec getParameterSpec()
                                        throws NoSuchAlgorithmException,
                                               InvalidAlgorithmParameterException

Returns the algorithm parameter spec for the parameters of the signature algorithm (PKCS#1 Version 2.1 Draft 1) or null if there are none.

Returns:

The AlgorithmParameterSpec to use when initializing the signature engine.

Throws:

NoSuchAlgorithmException - if the OIDs in this structure cannot be mapped onto an algorithm name by means of the alias definitions of the installed providers.

InvalidAlgorithmParameterException - if the signature algorithm identifier contains parameters but the parameters cannot be decoded.

init

protected void init()
             throws NoSuchAlgorithmException,
                    InvalidAlgorithmParameterException

This method determines the signature algorithm and appropriate parameters for initializing the signature algorithm from the algorithm identifiers in this structure. PKCS#1 versions 1.5 and 2.1 Draft 1 are supported.

We start by resolving the digest and cipher OIDs against a signature algorithm name by means of the JCA class. This requires JSPs (Java Security Providers) to support appropriate alias mappings. Both OID mappings and slashed forms are required.

If this fails then we try to interpret the digest algorithm identifier as the signature algorithm identifier. If this still does not give us a valid signature engine then we try the digest encryption algorithm identifier as the signature algorithm identifier.

If the combined form led to the signature engine then no parameters are set (apart from those in the public key's SubjectPublicKeyInfo. If either the digest algorithm identifier or the digest encryption algorithm identifier led to the signature engine then the respective parameters are set for the signature engine.

Parameters are set before the signature engine is initialized with the public key. No hint is given in the JDK documentation on which is to be done first. So we picked our choice.

Parameter initialization works only if the parameters engine supports proper conversion of opaque parameter representations into transparent representations (AlgorithmParameterSpecs) by means of the getAlgorithmParameterSpec() method. Hardly any provider gets it right, at the time of writing not even the Sun JSP does it correctly.

equivIssuerAndSerialNumber

public boolean equivIssuerAndSerialNumber(X509Certificate cert)

Checks if this SignerInfo has an issuer distinguished name and a serial number that are equivalent to those in the given certificate.

Parameters:

cert - The certificate to compare to.

Returns:

true if this SignerInfo matches the given certificate.

toString

public String toString()

Returns a string representation of this object.

Overrides:

toString in class ASN1AbstractCollection

Returns:

The string representation.

encode

public void encode(Encoder encoder)
            throws IOException,
                   ASN1Exception

Encodes this SignerInfo.

Overrides:

encode in class ASN1AbstractCollection

Parameters:

encoder - The encoder to use.