iaik.pkcs.pkcs7

Class SignerInfo

java.lang.Object

iaik.pkcs.pkcs7.SignerInfo

All Implemented Interfaces:

ASN1Type, EncodeListener, java.util.EventListener

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

This class implements the PKCS#7 SignerInfo type.

The PKCS #7: Cryptographic Message Syntax Version 1.5 (RFC 2315) 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 PKCS#7 SignedData, or the content of a PKCS#7 SignedAndEnvelopedData 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 (when building a SignedAndEnvelopedData, this message digest again is encrypted with a content-encryption key). Subsequently, again for each signer, the corresponding message digest from the previous step is encrypted 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 PKCS #7: Cryptographic Message Syntax Version 1.5 (RFC 2315)):

 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
 

The digestAlgorithm and digestEncryptionAlgorithm fields identify the algorithms used for digesting the content and any authenticated attributes, respectively encrypting the message digest and associated information with the signer´s private key. This SignerInfo implementation uses the rsaEncryption digest-encryption method as specified by PKCS #1: RSA Encryption Version 1.5 (RFC 2313). The issuerAndSerialNumber field specifies the signer´s certificate by issuer distinguished name and issuer-specific serial number. AuthenticatedAttributes and unauthenticatedAttributes 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 encryptedDigest field finally contains the result of the message digest encryption process. It is derived by encrypting the message digest and associated information (supplied as BER encoded PKCS#7 DigestInfo object) with the signer´s private key.

For more information consult the RSA PKCS #7: Cryptographic Message Syntax Version 1.5 (RFC 2315) specification.

This class provides several constructors and methods for creating a SignerInfo object, setting some attributes, obtaining the component values, and encrypting (respectively decrypting) the (encrypted) message digest.

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

 IssuerAndSerialNumber issuer_and_serialNr = new IssuerAndSerialNumber(certificate);
 SignerInfo signer_info = new SignerInfo(issuer_and_serialNr, AlgorithmID.sha, privateKey);
 

Attributes may be added using the setAuthenticatedAttributes respectively setUnauthenticatedAttributes 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.pkcs7_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:
 signer_info.setAuthenticatedAttributes(attributes);
 

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

See Also:

ContentInfo, SignedData, SignedAndEnvelopedData, SignedDataStream, SignedAndEnvelopedDataStream, IssuerAndSerialNumber, DigestInfo

Constructor Summary

Constructors

Constructor and Description
SignerInfo() Default constructor.
SignerInfo(ASN1Object obj) Creates a PKCS#7 SignerInfo from an ASN1Object.
SignerInfo(IssuerAndSerialNumber issuerAndSerialNumber, AlgorithmID digestAlgorithm, AlgorithmID digestEncryptionAlgorithm, java.security.PrivateKey privateKey) Creates a new SignerInfo from given issuerAndSerialNumber, and digestAlgorithm ID, digest-encryption algorithmID, and the signer´s private key.
SignerInfo(IssuerAndSerialNumber issuerAndSerialNumber, AlgorithmID digestAlgorithm, java.security.PrivateKey privateKey) Creates a new SignerInfo from given IssuerAndSerialNumber, digestAlgorithm ID, and the signer´s private key.

Method Summary

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.
Attribute	getAuthenticatedAttribute(ObjectID oid) Returns the first authenticated attribute matching to the given ObjectID, if included in this SignerInfo object.
Attribute[]	getAuthenticatedAttributes() Returns a set of attributes that are signed by the signer.
byte[]	getDigest(java.security.PublicKey publicKey, byte[] digest_in) Decrypts the encrypted digest using the publicKey and returns the resulting digest value in a byte array.
AlgorithmID	getDigestAlgorithm() Returns the AlgorithmID of the message-digest algorithm that has been used for digesting the content and any authenticated attributes.
AlgorithmID	getDigestEncryptionAlgorithm() Returns the digest-encryption algorithm used for encrypting the message digest and associated information with the signer's private key.
byte[]	getEncryptedDigest() Returns the encrypted digest.
IssuerAndSerialNumber	getIssuerAndSerialNumber() Returns information about the signer's certificate.
Attribute	getUnauthenticatedAttribute(ObjectID oid) Returns the first unauthenticated attribute matching to the given ObjectID, if included in this SignerInfo object.
Attribute[]	getUnauthenticatedAttributes() Returns a set of attributes that are not signed by the signer.
int	getVersion() Returns the syntax version number.
void	requestTimeStamp(TimeStampClient timeStampClient) Requests that the signature this SignerInfo structure represents be time-stamped.
void	setAuthenticatedAttributes(Attribute[] attributes) Sets a set of attributes to be authenticated along with the content to be signed.
void	setEncryptedDigest(byte[] encryptedDigest) Sets the encrypted digest value.
void	setUnauthenticatedAttributes(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.

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 digest-encryption algorithm ID to rsaEncryption.

SignerInfo

public SignerInfo(IssuerAndSerialNumber issuerAndSerialNumber,
                  AlgorithmID digestAlgorithm,
                  java.security.PrivateKey privateKey)

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

The issuerAndSerialNumber specifies issuer distinguished name and serial number of the signer´s certificate, and the digestAlgorithm ID specifies the message digest algorithm used for calculating the digest of the content and any authenticated information. The private key is used for calculating the signature.

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

• "RSA" - sets the digest encryption algorithm to AlgorithmID.rsaEncryption
• "DSA" - sets the digest encryption algorithm to AlgorithmID.dsa
• "EC" or "ECDSA" - sets the digest encryption algorithm to AlgorithmID.ecdsaWithSHA1

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(IssuerAndSerialNumber, AlgorithmID, AlgorithmID, PrivateKey) should be used instead.

Parameters:

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

SignerInfo

public SignerInfo(IssuerAndSerialNumber issuerAndSerialNumber,
                  AlgorithmID digestAlgorithm,
                  AlgorithmID digestEncryptionAlgorithm,
                  java.security.PrivateKey privateKey)

Creates a new SignerInfo from given issuerAndSerialNumber, and digestAlgorithm ID, digest-encryption algorithmID, and the signer´s private key.

The issuerAndSerialNumber specifies issuer distinguished name and serial number of the signer´s certificate, and the the digestAlgorithm ID specifies the message digest algorithm used for calculating the digest of the content and any authenticated information. The private key is used for calculating the signature (encrypting the digest with the with the given digest-encryption method). Currently only PKCS#1 rsaEncryption is supported for digest encryption.

Parameters:

issuerAndSerialNumber - information about the signer's certificate.

digestAlgorithm - the AlgorithmID of the message-digest algorithm

digestEncryptionAlgorithm - the algorithm to be used for encrypting the digest; default: PKCS#1 rsaEncryption

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

SignerInfo

public SignerInfo(ASN1Object obj)
           throws CodingException

Creates a PKCS#7 SignerInfo from an ASN1Object.

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

Parameters:

obj - the PKCS#7 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 PKCS#7 SignerInfo object from an already existing SignerInfo object, supplied as ASN1Object.

Specified by:

decode in interface ASN1Type

Parameters:

obj - the PKCS#7 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 in the PKCS #7: Cryptographic Message Syntax Version 1.5 (RFC 2315) specification. 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 encrypting 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 encrypted message digest 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 encryption. The supplied ASN1Object is the empty OCTET_STRING to be "filled" with the result of the digest-computation-encryption.

Specified by:

encodeCalled in interface EncodeListener

Parameters:

o - an OCTET_STRING for being supplied with the encrypted message digest

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

Throws:

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

setAuthenticatedAttributes

public void setAuthenticatedAttributes(Attribute[] attributes)

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

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

If the authenticatedAttributes 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 authenticated 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.pkcs7_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:
 signer_info.setAuthenticatedAttributes(attributes);
 

Parameters:

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

getDigest

public byte[] getDigest(java.security.PublicKey publicKey,
                        byte[] digest_in)
                 throws java.security.SignatureException,
                        java.security.InvalidKeyException

Decrypts the encrypted digest using the publicKey and returns the resulting digest value in a byte array.

This method decrypts the encrypted message digest using the PKCS#1 rsaEncryption method in decryption mode with the signer´s public key (usually derived from the signer´s certificate). The resultingDigestInfo object is parsed for the inherent digest value, which subsequently is returned by this method.

It should be noted that the encrypted digest is not necessarily the digest of the content that was signed. When originally signed, the digest was computed on either the content being signed or the content together with the signer's authenticated attributes. The result of the message digest process depends on whether the authenticatedAttributes field is present. When the field is absent, the result is just the digest of the content. When the field is present, however, the result is the digest of the complete DER encoding of the Attributes contained in the authenticateAttributes field. Since the Attributes value, when the field is present, must contain as attributes the content type and the message digest of the content, those values are indirectly included in the result.

Returns:

the decrypted message digest value as byte array

Throws:

java.security.SignatureException - if the digest decryption process fails

java.security.InvalidKeyException - if the given key does not match to the digest-encryption algorithm (rsaEncryption)

See Also:

DigestInfo

setUnauthenticatedAttributes

public void setUnauthenticatedAttributes(Attribute[] attributes)

Sets a set of attributes that are not signed by the signer. Attributes that might be useful are de fined 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 syntax version number. At this time version 1 is implemented.

Returns:

the version number

getIssuerAndSerialNumber

public IssuerAndSerialNumber getIssuerAndSerialNumber()

Returns information about the signer's certificate.

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

Returns:

information about the signer's certificate

See Also:

IssuerAndSerialNumber

getDigestAlgorithm

public AlgorithmID getDigestAlgorithm()

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

Returns:

the AlgorithmID of the message-digest algorithm

getAuthenticatedAttributes

public Attribute[] getAuthenticatedAttributes()

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

Returns:

a set of attributes that are signed by the signer

See Also:

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

getAuthenticatedAttribute

public Attribute getAuthenticatedAttribute(ObjectID oid)

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

Returns:

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

getDigestEncryptionAlgorithm

public AlgorithmID getDigestEncryptionAlgorithm()

Returns the digest-encryption algorithm used for encrypting the message digest and associated information with the signer's private key.

Returns:

the digest-encryption algorithm

getEncryptedDigest

public byte[] getEncryptedDigest()

Returns the encrypted digest.

Returns:

the encrypted digest, as byte array

setEncryptedDigest

public void setEncryptedDigest(byte[] encryptedDigest)

Sets the encrypted digest value. This method may be used for encrypting the digest outside and explicitly setting it.

Parameters:

encryptedDigest - the encrypted digest value, calculated from outside

getUnauthenticatedAttributes

public Attribute[] getUnauthenticatedAttributes()

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:

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

getUnauthenticatedAttribute

public Attribute getUnauthenticatedAttribute(ObjectID oid)

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

Returns:

the first unauthenticated 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