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 Standard 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 specification):

 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#1v1.5. 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. 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 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.sha256,
     privateKey);
 

Attributes may be added using the setAuthenticatedAttributes respectively setUnauthenticatedAttributes methods, e.g.:

 Attribute[] attributes = new Attribute[2];
 // PKCS#9 <code>ContentType</code> attribute specifying, e.g. the Data content
 // type:
 attributes[0] = new Attribute(ObjectID.contentType,
     new ASN1Object[] { ObjectID.pkcs7_data });
 // PKCS#9 <code>SigningTime</code> 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.

Version:

File Revision 39

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

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.
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) 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.
RSACipherProvider	getRSACipherProvider() Gets the RSA cipher provider for this ReceipientInfo.
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 synatx version number.
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	setRSACipherProvider(RSACipherProvider provider) Sets the RSA cipher provider for this SignerInfo.
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 (encrypting the digest with the PKCS#1 rsaEncryption method).

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 Standard 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 <code>ContentType</code> attribute specifying, e.g. the Data content
 // type:
 attributes[0] = new Attribute(ObjectID.contentType,
     new ASN1Object[] { ObjectID.pkcs7_data });
 // PKCS#9 <code>SigningTime</code> 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)
                 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 resulting DigestInfo object is parsed for the inherent digest value, which subsequently is returned by this method.

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 defined in PKCS#9.

Parameters:

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

getVersion

public int getVersion()

Returns the synatx 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.

setRSACipherProvider

public void setRSACipherProvider(RSACipherProvider provider)

Sets the RSA cipher provider for this SignerInfo. The RSACipherProvider allows an application to control the RSA cipher encryption/decryption (private key based encryption part of signature creation / public key based decryption part of signature verification operations). To, for instance, use the IAIK PKCS#11 provider for RSA cipher private key based encryption during signature creation only, but the first installed provider for RSA cipher public key based decryption during signature verification you may set the PKCS#11 provider as RSA encryption provider:

 IAIKPkcs11 pkcs11Provider = new IAIKPkcs11();
 Security.addProvider(pkcs11Provider);
 ...
 RSACipherProvider rsaProv = new RSACipherProvider(pkcs11Provider.getName(), null);
 ...
 SignerInfo signerInfo = ...;
 ...
 signerInfo.setRSACipherProvider(rsaProv, null);
 

In overriding method cipher of the RSACipherProvider you even can take more influence on the ciphering process.

If no RSACipherProvider is set for this RecipientInfo the first installed RSA capable crypto provider is used for RSA en/deciphering.

Parameters:

provider - the RSACipherProvider to be used for private/public key RSA cipher operations

getRSACipherProvider

public RSACipherProvider getRSACipherProvider()

Gets the RSA cipher provider for this ReceipientInfo. The RSACipherProvider allows an application to control the RSA cipher encryption/decryption (signature creation/verification operations). It may be set by calling method setRSACipherProvider.

Returns:

the RSACipherProvider to be used for private/public key RSA cipher operations

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