iaik.cms

Class SignerInfo

java.lang.Object

iaik.cms.SignerInfo

All Implemented Interfaces:

ASN1Type, EncodeListener, java.util.EventListener

public class SignerInfo
extends java.lang.Object
implements ASN1Type, EncodeListener

This class implements the CMS SignerInfo type.

The CMS Cryptographic Message Syntax (RFC 2630) specifies the SignerInfo type for collecting all signer-related information about some particular signer intending to build a digital signature on the content of a CMS SignedData object. Content of any type may be signed by any number of signers in parallel. For each signer, a message digest is computed on the content (and any additional authenticating information) with a signer-specific message-digest algorithm. Subsequently, again for each signer, the corresponding message digest from the previous step is signed with the particular signer´s private key and - together with some signer-specific information - collected into a SignerInfo value. Finally all created SignerInfo values are collected together with the content for forming a SignedData structure (when.

The SignerInfo structure collecting all signer-related information is defined as ASN.1 SEQUENCE type containing the following components (see RFC 2630):

 SignerInfo ::= SEQUENCE {
   version                 CMSVersion,
   sid                     SignerIdentifier,
   digestAlgorithm         DigestAlgorithmIdentifier,
   signedAttrs         [0] IMPLICIT Attributes OPTIONAL,
   signatureAlgorithm      SignatureAlgorithmIdentifier,
   signature               SignatureValue,
   unsignedAttributes  [1] IMPLICIT Attributes OPTIONAL }
 

 SignerIdentifier ::= CHOICE {
    issuerAndSerialNumber IssuerAndSerialNumber,
    subjectKeyIdentifier [0] SubjectKeyIdentifier }
 

 SignatureValue ::= OCTET STRING
 

 SignedAttributes ::= SET SIZE (1..MAX) OF Attribute

 UnsignedAttributes ::= SET SIZE (1..MAX) OF Attribute

 

The digestAlgorithm and signatureAlgorithm fields identify the algorithms used for digesting the content and any signed attributes, respectively signing the message digest and associated information with the signer´s private key. The signerIdentifier field specifies the signer´s certificate by issuer distinguished name and issuer-specific serial number. SignedAttributes and unsignedAttributes are optional fields giving some attributes that are signed (respectively not signed) by the signer. Attributes that may be used here, are defined in PKCS #9: Selected Object Classes and Attribute Types Version 2.0 (RFC 2985). The signature field finally contains the result of the signature calculation process. It is derived by signing the message digest on the content and associated information with the signer´s private key.

For more information consult the RSA (see RFC 2630).

This class provides several constructors and methods for creating a SignerInfo object, setting some attributes, obtaining the component values, and signing (respectively verifying) the signature value.

Assuming that certificate represents the X509v3 certifcate of some signer, a SignerInfo object may be created by supplying the certificate´s issuer distinguished name and the issuer-specific serial number, the signer´s message digest algorithm ID, and the signer´s private key:

 IssuerAndSerialNumber issuerAndSerialNr = new IssuerAndSerialNumber(certificate);
 SignerInfo signerInfo = new SignerInfo(issuerAndSerialNr, AlgorithmID.sha, privateKey);
 

Instead of identifying the signer certificate by issuer distinguished name and issuer-specific serial number the SubjectKeyIdentifier extension my be used, if appropriate:

 SubjectKeyID subjectKeyId = new SubjectKeyID(certificate);
 SignerInfo signerInfo = new SignerInfo(subjectKeyId, AlgorithmID.sha, privateKey);
 

Attributes may be added using the setSignedAttributes respectively setUnsignedAttributes methods, e.g.:

 Attribute[] attributes = new Attribute[2];
 // PKCS#9 ContentType attribute specifying, e.g. the Data content type:
 attributes[0] = new Attribute(ObjectID.contentType, new ASN1Object[] {ObjectID.cms_data});
 // PKCS#9 SigningTime attribute specifying the signing time (e.g. current time):
 attributes[1] = new Attribute(ObjectID.signingTime, new ASN1Object[] {new ChoiceOfTime().toASN1Object()});
 // add the attributes to the SignerInfo:
 signerInfo.setSignedAttributes(attributes);
 

Add a SignerInfo to a SignedData object by calling the addSignerInfo method of the SignedData(Stream) class.

See Also:

SignedData, SignedDataStream, CertificateIdentifier, IssuerAndSerialNumber, SubjectKeyID

Constructor Summary

Constructors

Constructor and Description
SignerInfo() Default constructor.
SignerInfo(ASN1Object obj) Creates a CMS SignerInfo from an ASN1Object.
SignerInfo(CertificateIdentifier signerIdentifier, AlgorithmID digestAlgorithm, AlgorithmID signatureAlgorithm, java.security.PrivateKey privateKey) Creates a new SignerInfo from given signerIdentifier, and digestAlgorithm ID, signature algorithmID, and the signer´s private key.
SignerInfo(CertificateIdentifier signerIdentifier, AlgorithmID digestAlgorithm, java.security.PrivateKey privateKey) Creates a new SignerInfo from given SignerIdentifier, digestAlgorithm ID, and the signer´s private key.

Method Summary

Methods

Modifier and Type	Method and Description
void	decode(ASN1Object obj) Decodes the given ASN.1 SignerInfo object for parsing the internal structure.
void	encodeCalled(ASN1Object o, int id) This method implements the EncodeListener interface.
AlgorithmID	getDigestAlgorithm() Returns the AlgorithmID of the message-digest algorithm that has been used for digesting the content and any signed attributes.
AlgorithmID	getSignatureAlgorithm() Returns the signature algorithm used for calculating the signature and associated information with the signer's private key.
byte[]	getSignatureValue() Returns the signature value.
Attribute	getSignedAttribute(ObjectID oid) Returns the first signed attribute matching to the given ObjectID, if included in this SignerInfo object.
Attribute[]	getSignedAttributes() Returns a set of attributes that are signed by the signer.
byte[]	getSignedDigest() Returns the message digest included in the signed attributes.
CertificateIdentifier	getSignerIdentifier() Returns information about the signer's certificate.
SigningCertificate	getSigningCertificateAttribute() Gets the SigningCertificate attribute, if included.
Attribute	getUnsignedAttribute(ObjectID oid) Returns the first unsigned attribute matching to the given ObjectID, if included in this SignerInfo object.
Attribute[]	getUnsignedAttributes() Returns a set of attributes that are not signed by the signer.
int	getVersion() Returns the synatx version number (1 or 3).
boolean	isSignerCertificate(X509Certificate cert) Checks whether the supplied certificate actually is the certificate of the signer.
void	requestTimeStamp(TimeStampClient timeStampClient) Requests that the signature this SignerInfo structure represents be time-stamped.
void	setEncryptedDigest(byte[] signatureValue) Sets the signature value.
void	setSignedAttributes(Attribute[] attributes) Sets a set of attributes to be signed along with the content to be signed.
void	setUnsignedAttributes(Attribute[] attributes) Sets a set of attributes that are not signed by the signer.
ASN1Object	toASN1Object() Returns this SignerInfo as ASN1Object.
java.lang.String	toString() Returns a string giving some information about this SignerInfo object.
java.lang.String	toString(boolean detailed) Returns a string giving some - if requested - detailed information about this SignerInfo object.
boolean	verifySignature(java.security.PublicKey publicKey) Verifies the signature with the given public key.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

SignerInfo

public SignerInfo()

Default constructor. Creates an empty SignerInfo object and sets the version number to 1, and the signature algorithm ID to rsaEncryption.

SignerInfo

public SignerInfo(CertificateIdentifier signerIdentifier,
          AlgorithmID digestAlgorithm,
          java.security.PrivateKey privateKey)

Creates a new SignerInfo from given SignerIdentifier, digestAlgorithm ID, and the signer´s private key.

The signerIdentifier identifies the signer certificate either by issuer distinguished name and issuer-specific serial number or by SubjectKeyIdentifier. The digestAlgorithm ID specifies the message digest algorithm used for calculating the digest of the content and any signed information. The private key is used for calculating the signature.

Note: This method does not contain a parameter to set the signature algorithm. The key type of the passed in privatekey is checked and a best effort is made to match the keytype with the signature algorithm. The following key types are supported:

• "RSA" - sets the signature algorithm to AlgorithmID.rsaEncryption
• "DSA" - sets the signature algorithm to AlgorithmID.dsa
• "EC" or "ECDSA" - sets the signature algorithm to AlgorithmID.ecdsaWithSHA1 if no digestAlgorithm is supplied. If a digest algorithm is supplied it sets the Signature algorithm to the combination of the keytype with the digest algorithm. For example, AlgorithmID.ecdsaWithSha256

If a keytype other than one of the three above is encountered, an Invalid key algorithm is thrown. If another keytype is required, then the constructor SignerInfo(CertificateIdentifier, AlgorithmID, AlgorithmID, PrivateKey) should be used instead.

Parameters:

signerIdentifier - information about the signer's certificate.

digestAlgorithm - the AlgorithmID of the message-digest algorithm

privateKey - the signer´s private key to be used for signing

Throws:

java.lang.IllegalArgumentException - if the supplied signerIdentifier is not a SubjectKeyID or IssuerAndSerialNumber

SignerInfo

public SignerInfo(CertificateIdentifier signerIdentifier,
          AlgorithmID digestAlgorithm,
          AlgorithmID signatureAlgorithm,
          java.security.PrivateKey privateKey)

Creates a new SignerInfo from given signerIdentifier, and digestAlgorithm ID, signature algorithmID, and the signer´s private key.

The signerIdentifier identifies the signer certificate either by issuer distinguished name and issuer-specific serial number or by SubjectKeyIdentifier. The digestAlgorithm ID specifies the message digest algorithm used for calculating the digest of the content and any signed information. The private key is used for calculating the signature with the given signature algorithm.

Parameters:

signerIdentifier - information about the signer's certificate.

algorithmID - the AlgorithmID of the message-digest algorithm

signatureAlgorithm - the algorithm to be used for signature calculation

privateKey - the signer´s private key to be used for signing

Throws:

if - the supplied signerIdentifier is not a SubjectKeyID or IssuerAndSerialNumber

SignerInfo

public SignerInfo(ASN1Object obj)
           throws CodingException

Creates a CMS SignerInfo from an ASN1Object.

The ASN1Object supplied to this constructor represents an already exisiting SignerInfo object that may have been created by calling toASN1Object.

Parameters:

obj - the CMS SignerInfo as ASN1Object

Throws:

CodingException - if the object can not be parsed

Method Detail

decode

public void decode(ASN1Object obj)
            throws CodingException

Decodes the given ASN.1 SignerInfo object for parsing the internal structure.

This method internally is called when creating a CMS SignerInfo object from an already existing SignerInfo object, supplied as ASN1Object.

Specified by:

decode in interface ASN1Type

Parameters:

obj - the CMS SignerInfo as ASN1Object

Throws:

CodingException - if the object can not be parsed

toASN1Object

public ASN1Object toASN1Object()
                        throws CodingException

Returns this SignerInfo as ASN1Object.

Creates an ASN1 SEQUENCE object supplied with all the component values as defined for the CMS Cryptographic Message Syntax (RFC 2630) SignerInfo type. The ASN1Object returned by this method may be used as parameter value when creating a SignerInfo object using the SignerInfo(ASN1Object obj) constructor.

Specified by:

toASN1Object in interface ASN1Type

Returns:

this SignerInfo as ASN1Object.

Throws:

CodingException - if the ASN1Object could not be created

encodeCalled

public void encodeCalled(ASN1Object o,
                int id)
                  throws CodingException

This method implements the EncodeListener interface. During the encoding process the DerCoder calls this method when it actually is time for computing and signing the message digest to be encoded. In particular for the stream-supporting implementation of the SignedData content type, the message digest cannot be computed before the content stream entirely has been read. Since the content stream actually is read during the encoding procedure, this SignerInfo class has to be notified when the content stream has been read. This is done by means of the EncodeListener utility. The toASN1Object() method of this SignerInfo class instantiates an empty OCTET_STRING for the signature value field, and registers itself as EncodeListener for this empty OCTET_STRING. Now, during the encoding process, when the content stream entirely has been read, this encodeCalled method is called for performing digest computation and signature calculation. The supplied ASN1Object is the empty OCTET_STRING to be "filled" with the result of the digest-signature-computation.

Specified by:

encodeCalled in interface EncodeListener

Parameters:

o - an OCTET_STRING for being supplied with the signature value

id - the id identifying the particular octet string to be processed

Throws:

CodingException - if an error occurs when computing/signing the message digest

setSignedAttributes

public void setSignedAttributes(Attribute[] attributes)

Sets a set of attributes to be signed along with the content to be signed.

The signedAttributes field is optional, but must be present if the content type of the EncypsulatedContentInfo value being signed is not the Data type.

If the signedAttributes field is present, it must include the PKCS#9 content-type attribute and the PKCS#9 message-digest attribute. If the message-digest attribute is not included in the supplied signed attributes it is automatically calculated and set.

A further attribute type specified by PKCS#9 may be used for specifying the time at which the signer has performed the signing process, e.g.:

 Attribute[] attributes = new Attribute[2];
 // PKCS#9 ContentType attribute specifying, e.g. the Data content type:
 attributes[0] = new Attribute(ObjectID.contentType, new ASN1Object[] {ObjectID.cms_data});
 // PKCS#9 SigningTime attribute specifying the signing time (e.g. current time):
 attributes[1] = new Attribute(ObjectID.signingTime, new ASN1Object[] {new ChoiceOfTime().toASN1Object()});
 // add the attributes to the SignerInfo:
 signerInfo.setSignedAttributes(attributes);
 

Parameters:

attributes - a set of attributes to be signed along with the content to be signed.

getSigningCertificateAttribute

public SigningCertificate getSigningCertificateAttribute()
                                                  throws CMSException

Gets the SigningCertificate attribute, if included.

Returns:

the SigningCertificate attribute, or null if not included

Throws:

CMSException - if an error occurs while parsing for the SigningCertificate attribute

verifySignature

public boolean verifySignature(java.security.PublicKey publicKey)
                        throws java.security.SignatureException,
                               java.security.InvalidKeyException

Verifies the signature with the given public key.

Parameters:

digest - the digest independently calculated over the received content

the - public key of the signer

Throws:

java.security.SignatureException - signature verification process fails

java.security.InvalidKeyException - if the given key does not match to the signature algorithm

getSignedDigest

public byte[] getSignedDigest()
                       throws CMSException

Returns the message digest included in the signed attributes. If the signed content is not included in the SignedData ASN.1 object this method can be used to get to message digest of the signed content.

Returns:

the message digest included in the signed attributes, or null if not present

Throws:

CMSException

setUnsignedAttributes

public void setUnsignedAttributes(Attribute[] attributes)

Sets a set of attributes that are not signed by the signer. Attributes that might be useful are defined in PKCS #9: Selected Object Classes and Attribute Types Version 2.0 (RFC 2985).

Parameters:

attributes - a set of attributes that are not signed by the signer

getVersion

public int getVersion()

Returns the synatx version number (1 or 3).

Returns:

the version number

getSignerIdentifier

public CertificateIdentifier getSignerIdentifier()

Returns information about the signer's certificate.

The information is returned as CertificateIdentifier object specifying the signer´s certificate either by issuer distinguished name and issuer-specific serial number or by SubjectKeyIdentifier.

Returns:

information about the signer's certificate

isSignerCertificate

public boolean isSignerCertificate(X509Certificate cert)
                            throws CMSException

Checks whether the supplied certificate actually is the certificate of the signer.

This method first checks if the the signerIdentifier of this SignerInfo identifies the supplied certificate via IssuerAndSerialNumber or SubjectKeyIdentifier. If this check is successful, this method then looks if the SigningCertificate extension is present and identifies the given certificate as cert of the signer.

Parameters:

signerCert - the certificate to be checked of being the one of the signer

Returns:

true if the supplied certificate is the signer certificate, false if not

Throws:

CMSException - if the check cannot be completed because an error occurs when parsing the SigningCertificate attribute or the SHA-1 hash algorithm (required for calculating the cert hash) id not supported by the cryptographic providers installed

getDigestAlgorithm

public AlgorithmID getDigestAlgorithm()

Returns the AlgorithmID of the message-digest algorithm that has been used for digesting the content and any signed attributes.

Returns:

the AlgorithmID of the message-digest algorithm

getSignedAttributes

public Attribute[] getSignedAttributes()

Returns a set of attributes that are signed by the signer. The signedAttributes field is optional, but must be present if the content type of the EncypsulatedContentInfo value being signed is not the Data type.

Returns:

a set of attributes that are signed by the signer

See Also:

setSignedAttributes(iaik.asn1.structures.Attribute[])

getSignedAttribute

public Attribute getSignedAttribute(ObjectID oid)

Returns the first signed attribute matching to the given ObjectID, if included in this SignerInfo object.

Returns:

the first signed attribute belonging to the given ObjectID or null if there is no attribute for the given OID.

getSignatureAlgorithm

public AlgorithmID getSignatureAlgorithm()

Returns the signature algorithm used for calculating the signature and associated information with the signer's private key.

Returns:

the signature algorithm

getSignatureValue

public byte[] getSignatureValue()

Returns the signature value.

Returns:

the signature value, as byte array

setEncryptedDigest

public void setEncryptedDigest(byte[] signatureValue)

Sets the signature value. This method may be used for calculating the signature value outside and explicitly setting it.

Parameters:

signatureValue - the signature value, calculated from outside

getUnsignedAttributes

public Attribute[] getUnsignedAttributes()

Returns a set of attributes that are not signed by the signer. Attributes that might be useful are defined in PKCS#9.

Returns:

a set of attributes that are not signed by the signer

See Also:

setUnsignedAttributes(iaik.asn1.structures.Attribute[])

getUnsignedAttribute

public Attribute getUnsignedAttribute(ObjectID oid)

Returns the first unsigned attribute matching to the given ObjectID, if included in this SignerInfo object.

Returns:

the first unsigned attribute belonging to the given ObjectID or null if there is no attribute for the given OID.

toString

public java.lang.String toString()

Returns a string giving some information about this SignerInfo object.

Overrides:

toString in class java.lang.Object

Returns:

the string representation

toString

public java.lang.String toString(boolean detailed)

Returns a string giving some - if requested - detailed information about this SignerInfo object.

Parameters:

detailed - - whether or not to give detailed information

Returns:

the string representation

requestTimeStamp

public void requestTimeStamp(TimeStampClient timeStampClient)

Requests that the signature this SignerInfo structure represents be time-stamped.

When the SignerInfo structure is encoded to an ASN1 object, a time-stamp will automatically be requested from the TimeStamp Authority indicated, and added to the SignerInfo structure as an unsigned attribute.

A time-stamp will only be requested when timeStampClient is not set to null.

Note:

The time-stamp is not actually requested until the SignerInfo structure is encoded. Thus, if the time-stamp client that was used to request that the signature be time-stamped is modified (hash algorithm changed, TSA policy changed, ...) before the structure is encoded, these changes will apply to the time-stamp that is requested during the encoding.

Parameters:

timeStampClient - the time-stamp client that will be used to request a time-stamp for the signature value from a TimeStamp Authority

Since:

Entrust 7.0