SignerInfo ("Entrust Authority Security Toolkit for the Java Platform")

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 andunsignedAttributes 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, AlgorithmID signatureAlgorithm, java.security.PrivateKey privateKey, java.security.Provider overrideProvider)` 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

All Methods Instance Methods Concrete 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.
    
    digestAlgorithm - 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(CertificateIdentifier signerIdentifier,
                  AlgorithmID digestAlgorithm,
                  AlgorithmID signatureAlgorithm,
                  java.security.PrivateKey privateKey,
                  java.security.Provider overrideProvider)
```
    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.
    
    digestAlgorithm - 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
    
    overrideProvider - the provider to used instead of a default softward provider
    
    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 SignerInfoobject 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 aSignerInfo 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:
    
    publicKey - the public key
    
    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:
    
    cert - 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

Class SignerInfo

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

SignerInfo

SignerInfo

SignerInfo

SignerInfo

SignerInfo

Method Detail

decode

toASN1Object

encodeCalled

setSignedAttributes

getSigningCertificateAttribute

verifySignature

getSignedDigest

setUnsignedAttributes

getVersion

getSignerIdentifier

isSignerCertificate

getDigestAlgorithm

getSignedAttributes

getSignedAttribute

getSignatureAlgorithm

getSignatureValue

setEncryptedDigest

getUnsignedAttributes

getUnsignedAttribute

toString

toString

requestTimeStamp