com.ibm.security.pkcs7
Class SignedData

java.lang.Object
  |
  +--com.ibm.security.pkcsutil.PKCSDerObject
        |
        +--com.ibm.security.pkcs7.Content
              |
              +--com.ibm.security.pkcs7.SignedData

public final class SignedData
extends Content
implements Cloneable

Implements the ASN.1 SignedData type. It encapsulates signed data and related methods. Each signer's information is included in the signerInfos field. The sign and verify methods can be used to sign the ContentInfo and verify the ContentInfo against a signature (encrypted message digest) in a SignerInfo object.

Currently, SignedData only supports X509Certificates for certificates and X509CRLs for crls.

SignedData ::= SEQUENCE { version CMSVersion, digestAlgorithms DigestAlgorithmIdentifiers, encapsulatedContentInfo EncapsulatedContentInfo, certificates [0] IMPLICIT CertificateSet OPTIONAL, crls [1] IMPLICIT CertificateRevocationLists OPTIONAL, signerInfos SignerInfos }

This definition reflects PKCS #7 version 1.5 specifications with selected enhancements from the Cryptographic Message Syntax (CMS) RFC 2630 specifications.

Only X509Certificate objects are supported for recipient certificates.

SignedData objects are not immutable; they can be changed once created. After construction of the SignedData object, users can add additional recipients of the object, add certificates and CRLs, as well as remove the contents of this object.


Field Summary
protected static String BEGIN_CERTIFICATE
          BEGIN_CERTIFICATE = "-----BEGIN CERTIFICATE-----"
protected static String END_CERTIFICATE
          END_CERTIFICATE = "-----END CERTIFICATE-----"
 
Fields inherited from class com.ibm.security.pkcsutil.PKCSDerObject
provider
 
Constructor Summary
SignedData(AlgorithmId[] digestAlgorithms, EncapsulatedContentInfo eci, Certificate[] certsIn, CRL[] crlsIn, SignerInfo[] signersIn)
          Create a SignedData object with specified values.
SignedData(AlgorithmId[] digestAlgorithms, EncapsulatedContentInfo eci, Certificate[] certsIn, CRL[] crlsIn, SignerInfo[] signersIn, String provider)
          Create a SignedData object with specified values.
SignedData(byte[] der)
          Create a SignedData object with a DER-encoded byte array.
SignedData(byte[] der, String provider)
          Create a SignedData object with a DER-encoded byte array.
SignedData(Certificate[] certs, CRL[] crls)
          Create a SignedData object with the specified certificate and CRL arrays.
SignedData(Certificate[] certs, CRL[] crls, ContentInfo contentInfo, String digestSignatureAlgorithm, PrivateKey[] privateKeys, PKCSAttributes signedAttribs, PKCSAttributes unsignedAttribs, boolean signatureOnly)
          Create a SignedData object with the specified certificate array, contentInfo, message digest and signature algorithm, and private key array and derive a signature for each certificate in the signing certificate array.
SignedData(Certificate[] certs, CRL[] crls, ContentInfo contentInfo, String digestSignatureAlgorithm, PrivateKey[] privateKeys, PKCSAttributes signedAttribs, PKCSAttributes unsignedAttribs, boolean signatureOnly, String provider)
          Create a SignedData object with the specified certificate array, contentInfo, message digest and signature algorithm, and private key array and derive a signature for each certificate in the signing certificate array.
SignedData(Certificate[] certs, CRL[] crls, String provider)
          Create a SignedData object with the specified certificate and CRL arrays.
SignedData(Certificate cert, ContentInfo contentInfo, String digestSignatureAlgorithm, PrivateKey privateKey, boolean signatureOnly)
          Create a SignedData object with the specified certificate, contentInfo, message digest and signature algorithm, and private key and derive a signature for the specified signing certificate.
SignedData(Certificate cert, ContentInfo contentInfo, String digestSignatureAlgorithm, PrivateKey privateKey, boolean signatureOnly, String provider)
          Create a SignedData object with the specified certificate, contentInfo, message digest and signature algorithm, and private key and derive a signature for the specified signing certificate.
SignedData(String filename, boolean base64)
          Create a SignedData with the filename of the DER-encoded or BASE64-encoded object.
SignedData(String filename, boolean base64, String provider)
          Create a SignedData with the filename of the DER-encoded or BASE64-encoded object.
 
Method Summary
 void addCertificate(Certificate[] certs)
          Add a certificate array to the certificate array for this SignedData object.
 void addCRL(CRL[] crls)
          Add a CRL array to the CRL array for this SignedData object.
 void addSigner(Certificate cert, PrivateKey privateKey, String digestSignatureAlgorithm, PKCSAttributes signedAttribs, PKCSAttributes unsignedAttribs)
          Add a SignerInfo entry to this SignedData object.
 void addSignerSignatureOnly(Certificate cert, PrivateKey privateKey, String digestSignatureAlgorithm)
          Add a SignerInfo entry to this SignedData object without any default or specified signed attributes.
 Object clone()
          Creates a clone of this SignedData object.
protected  void decode(com.ibm.security.pkcs7.DerValue encoding)
          Initializes a SignedData object from a DerValue.
 void encode(OutputStream os)
          DER encode this object to an OutputStream.
 boolean equals(Object other)
          Determines if this SignedData object is equivalent to the input object.
 Certificate getCertificate(IssuerAndSerialNumber issuer)
          Retrieve a copy of the Certificate object that matches the specified IssuerAndSerialNumber.
 Certificate[] getCertificates()
          Returns a copy of the set of signing certificates in an array of certificates.
 CRL[] getCRLs()
          Returns a copy of the set of CRLs in an array of CRLs.
 AlgorithmId[] getDigestAlgorithms()
          Returns a copy of the array of message digest algorithms.
 EncapsulatedContentInfo getEncapsulatedContentInfo()
          Returns a copy of the EncapsulatedContentInfo.
 ObjectIdentifier getObjectIdentifier()
          Returns a reference to the ObjectIdentifer for the SignedData object.
 SignerInfo getSignerInfo(Certificate cert)
          Retrieve a copy of the SignerInfo object that matches the specified certificate.
 SignerInfo[] getSignerInfos()
          Returns a copy of the array of SignerInfo objects.
 BigInteger getVersion()
          Returns a reference to the version for this object.
 boolean hasCertificate(Certificate cert)
          Determine if this SignedData object has the specified certificate.
 boolean hasCertificates()
          Determines whether or not this SignedData object has Certificate objects.
 boolean hasCertificatesOnly()
          Determine if this SignedData object contains certificate objects and does not contain SignerInfo objects.
 boolean hasContent()
          Returns whether or not this SignedData object contains content in its EncapsulatedContentInfo object.
 boolean hasCRL(CRL crl)
          Determine if this SignedData object has the specified CRL.
 boolean hasCRLs()
          Determines whether or not this SignedData object has CRL objects.
 boolean hasSignerInfos()
          Returns whether or not this SignedData object has SignerInfo objects.
 void removeContent()
          Removes the content from the EncapsulatedContentInfo contained within this SignedData object.
 String toString()
          Returns a string representation of this SignedData object.
 boolean verify(Certificate cert)
          Verify the message digest stored in the SignerInfo object within this SignedData object with the public key contained in the specified certificate.
 boolean verify(Certificate cert, byte[] msg)
          Verify the message digest stored in the SignerInfo object within this SignedData object with the public key contained in the specified certificate.
 void writeBASE64(String filename)
          DER-encode the object and write the encoded bytes to the output file in BASE64 format.
 
Methods inherited from class com.ibm.security.pkcsutil.PKCSDerObject
decode, decode, encode, hashCode, read, readBASE64, write, write
 
Methods inherited from class java.lang.Object
finalize, getClass, notify, notifyAll, wait, wait, wait
 

Field Detail

BEGIN_CERTIFICATE

protected static final String BEGIN_CERTIFICATE
BEGIN_CERTIFICATE = "-----BEGIN CERTIFICATE-----"

END_CERTIFICATE

protected static final String END_CERTIFICATE
END_CERTIFICATE = "-----END CERTIFICATE-----"
Constructor Detail

SignedData

public SignedData(byte[] der)
           throws IOException
Create a SignedData object with a DER-encoded byte array.
Parameters:
der - a DER-encoded byte array of a SignedData object.
Throws:
IOException - on decoding errors.

SignedData

public SignedData(byte[] der,
                  String provider)
           throws IOException
Create a SignedData object with a DER-encoded byte array.
Parameters:
der - a DER-encoded byte array of a SignedData object.
provider - the name of the java security provider to use
Throws:
IOException - on decoding errors.

SignedData

public SignedData(Certificate[] certs,
                  CRL[] crls)
           throws IOException
Create a SignedData object with the specified certificate and CRL arrays. The version is calculated after the values are assigned. This method is useful for creating a certificate only SignedData object.
Parameters:
certs - Certificate array
crls - Certificate Revocation List array

SignedData

public SignedData(Certificate[] certs,
                  CRL[] crls,
                  String provider)
           throws IOException
Create a SignedData object with the specified certificate and CRL arrays. The version is calculated after the values are assigned. This method is useful for creating a certificate only SignedData object.
Parameters:
certs - Certificate array
crls - Certificate Revocation List array
provider - the name of the java security provider to use

SignedData

public SignedData(AlgorithmId[] digestAlgorithms,
                  EncapsulatedContentInfo eci,
                  Certificate[] certsIn,
                  CRL[] crlsIn,
                  SignerInfo[] signersIn)
Create a SignedData object with specified values. The version is calculated after the values are assigned.
Parameters:
digestAlgorithms - message digest algorithm array
eci - EncapsulatedContentInfo object
certsIn - Certificate array
crlsIn - Certificate Revocation List array
signersIn - SignerInfo array

SignedData

public SignedData(AlgorithmId[] digestAlgorithms,
                  EncapsulatedContentInfo eci,
                  Certificate[] certsIn,
                  CRL[] crlsIn,
                  SignerInfo[] signersIn,
                  String provider)
Create a SignedData object with specified values. The version is calculated after the values are assigned.
Parameters:
digestAlgorithms - message digest algorithm array
eci - EncapsulatedContentInfo object
certsIn - Certificate array
crlsIn - Certificate Revocation List array
signersIn - SignerInfo array
provider - the name of the java security provider to use

SignedData

public SignedData(Certificate cert,
                  ContentInfo contentInfo,
                  String digestSignatureAlgorithm,
                  PrivateKey privateKey,
                  boolean signatureOnly)
           throws PKCSException,
                  IOException,
                  NoSuchAlgorithmException
Create a SignedData object with the specified certificate, contentInfo, message digest and signature algorithm, and private key and derive a signature for the specified signing certificate.
Parameters:
cert - signing certificate
contentInfo - ContentInfo object to sign
digestSignatureAlgorithm - message digest and signature algorithm, such as "SHA1withDSA"
privateKey - signer's private key
signatureOnly - indicate if the default signed attributes should be included.
Throws:
PKCSException - on signing errors.
IOException - on signing errors.
NoSuchAlgorithmException - on invalid algorithm errors.

SignedData

public SignedData(Certificate cert,
                  ContentInfo contentInfo,
                  String digestSignatureAlgorithm,
                  PrivateKey privateKey,
                  boolean signatureOnly,
                  String provider)
           throws PKCSException,
                  IOException,
                  NoSuchAlgorithmException
Create a SignedData object with the specified certificate, contentInfo, message digest and signature algorithm, and private key and derive a signature for the specified signing certificate.
Parameters:
cert - signing certificate
contentInfo - ContentInfo object to sign
digestSignatureAlgorithm - message digest and signature algorithm, such as "SHA1withDSA"
privateKey - signer's private key
signatureOnly - indicate if the default signed attributes should be included.
Throws:
PKCSException - on signing errors.
IOException - on signing errors.
NoSuchAlgorithmException - on invalid algorithm errors.

SignedData

public SignedData(Certificate[] certs,
                  CRL[] crls,
                  ContentInfo contentInfo,
                  String digestSignatureAlgorithm,
                  PrivateKey[] privateKeys,
                  PKCSAttributes signedAttribs,
                  PKCSAttributes unsignedAttribs,
                  boolean signatureOnly)
           throws PKCSException,
                  IOException,
                  NoSuchAlgorithmException
Create a SignedData object with the specified certificate array, contentInfo, message digest and signature algorithm, and private key array and derive a signature for each certificate in the signing certificate array. The index into the certificate array must correspond to the matching index in the private key array.
Parameters:
certs[] - array of signing certificates
crls[] - array of CRLs
contentInfo - ContentInfo object to sign
digestSignatureAlgorithm - message digest and signature algorithm, such as "SHA1withRSA"
privateKeys[] - array of private keys corresponding to each signing certificate.
signatureOnly - indicate if the default signed attributes should be included.
Throws:
PKCSException - on signing errors.
IOException - on signing errors.
NoSuchAlgorithmException - on invalid algorithm errors.

SignedData

public SignedData(Certificate[] certs,
                  CRL[] crls,
                  ContentInfo contentInfo,
                  String digestSignatureAlgorithm,
                  PrivateKey[] privateKeys,
                  PKCSAttributes signedAttribs,
                  PKCSAttributes unsignedAttribs,
                  boolean signatureOnly,
                  String provider)
           throws PKCSException,
                  IOException,
                  NoSuchAlgorithmException
Create a SignedData object with the specified certificate array, contentInfo, message digest and signature algorithm, and private key array and derive a signature for each certificate in the signing certificate array. The index into the certificate array must correspond to the matching index in the private key array.
Parameters:
certs[] - array of signing certificates
crls[] - array of CRLs
contentInfo - ContentInfo object to sign
digestSignatureAlgorithm - message digest and signature algorithm, such as "SHA1withRSA"
privateKeys[] - array of private keys corresponding to each signing certificate.
signatureOnly - indicate if the default signed attributes should be included.
Throws:
PKCSException - on signing errors.
IOException - on signing errors.
NoSuchAlgorithmException - on invalid algorithm errors.

SignedData

public SignedData(String filename,
                  boolean base64)
           throws IOException
Create a SignedData with the filename of the DER-encoded or BASE64-encoded object.
Parameters:
filename - name of the DER-encoded or base64-encoded object
base64 - true if BASE64-encoded, false if DER-encoded
Throws:
IOException - on decoding errors.

SignedData

public SignedData(String filename,
                  boolean base64,
                  String provider)
           throws IOException
Create a SignedData with the filename of the DER-encoded or BASE64-encoded object.
Parameters:
filename - name of the DER-encoded or base64-encoded object
base64 - true if BASE64-encoded, false if DER-encoded
provider - the name of the java security provider to use
Throws:
IOException - on decoding errors.
Method Detail

clone

public Object clone()
Creates a clone of this SignedData object.
Overrides:
clone in class Object
Returns:
clone of this SignedData object.

getObjectIdentifier

public ObjectIdentifier getObjectIdentifier()
Returns a reference to the ObjectIdentifer for the SignedData object.
Overrides:
getObjectIdentifier in class PKCSDerObject
Returns:
an ObjectIdentifer for the SignedData object.

getVersion

public BigInteger getVersion()
Returns a reference to the version for this object. BigInteger is an immutable object.
Returns:
the version for this object.

getDigestAlgorithms

public AlgorithmId[] getDigestAlgorithms()
Returns a copy of the array of message digest algorithms.
Returns:
the array of message digest algorithms.

getEncapsulatedContentInfo

public EncapsulatedContentInfo getEncapsulatedContentInfo()
Returns a copy of the EncapsulatedContentInfo.
Returns:
the EncapsulatedContentInfo.

removeContent

public void removeContent()
                   throws IOException
Removes the content from the EncapsulatedContentInfo contained within this SignedData object. This method can be called on a completed SignedData object to create a SignedData object with detached signature(s). To verify a SignedData with a detached signature, call the verify method, passing in the public key and contents.

hasContent

public boolean hasContent()
Returns whether or not this SignedData object contains content in its EncapsulatedContentInfo object.
Returns:
true if there is contents in the SignedData object, else false.

hasCertificates

public boolean hasCertificates()
Determines whether or not this SignedData object has Certificate objects.
Returns:
true if there are Certificate objects, else false.

hasCRLs

public boolean hasCRLs()
Determines whether or not this SignedData object has CRL objects.
Returns:
true if there are CRL objects, else false.

getCertificates

public Certificate[] getCertificates()
Returns a copy of the set of signing certificates in an array of certificates. Since the certificates are stored in a set, they may not be returned in the same order as they were added.
Returns:
the array of signing certificates.

getCRLs

public CRL[] getCRLs()
Returns a copy of the set of CRLs in an array of CRLs. Since the CRLs are stored in a set, they may not be returned in the same order as they were added.
Returns:
the array of CRLs.

getSignerInfos

public SignerInfo[] getSignerInfos()
Returns a copy of the array of SignerInfo objects.
Returns:
the array of SignerInfo objects.

hasSignerInfos

public boolean hasSignerInfos()
Returns whether or not this SignedData object has SignerInfo objects.
Returns:
true if there are SignerInfo objects, else false.

getSignerInfo

public SignerInfo getSignerInfo(Certificate cert)
                         throws IOException
Retrieve a copy of the SignerInfo object that matches the specified certificate.
Parameters:
cert - signer certificate to match
Returns:
SignerInfo object matching the certificate, otherwise null.
Throws:
IOException - on search errors.

getCertificate

public Certificate getCertificate(IssuerAndSerialNumber issuer)
                           throws IOException
Retrieve a copy of the Certificate object that matches the specified IssuerAndSerialNumber.
Parameters:
issuer - IssuerAndSerialNumber to match
Returns:
Certificate object matching the IssuerAndSerialNumber, otherwise null.
Throws:
IOException - on search errors.

hasCertificate

public boolean hasCertificate(Certificate cert)
Determine if this SignedData object has the specified certificate.
Parameters:
cert - signer certificate for which to search
Returns:
true if certificate exists in the certificate array, otherwise false.

hasCRL

public boolean hasCRL(CRL crl)
Determine if this SignedData object has the specified CRL.
Parameters:
crl - CRL for which to search
Returns:
true if CRL exists in the CRL array, otherwise false.

hasCertificatesOnly

public boolean hasCertificatesOnly()
Determine if this SignedData object contains certificate objects and does not contain SignerInfo objects.
Returns:
true if certificate exists and SignerInfo do not, otherwise false.

verify

public boolean verify(Certificate cert)
               throws PKCSException,
                      IOException,
                      NoSuchAlgorithmException
Verify the message digest stored in the SignerInfo object within this SignedData object with the public key contained in the specified certificate. The specified certificate must match a certificate stored in a SignerInfo object contained in this SignedData object. As part of the verification process, this method will use the content stored in the EncapsulatedContentInfo to independently compute the message digest.
Parameters:
cert - signer certificate for which to verify
Returns:
true if message digest verified, otherwise false.
Throws:
PKCSException - on verification errors.
IOException - on verification errors.
NoSuchAlgorithmException - on invalid algorithm errors.

verify

public boolean verify(Certificate cert,
                      byte[] msg)
               throws PKCSException,
                      IOException,
                      NoSuchAlgorithmException
Verify the message digest stored in the SignerInfo object within this SignedData object with the public key contained in the specified certificate. The msg byte array parameter allows this SignedData object to compute a message digest and compare it against the message digest that is part of the contained SignerInfo object.

This method allows callers to verify a detached signature, where the contents is not part of the SignedData object.

Parameters:
cert - signer certificate for which to verify
msg - byte array to compute the message digest comparision. If not specified, this method will use the content stored in the EncapsulatedContentInfo to independently compute the message digest.
Returns:
true if message digest verified, otherwise false.
Throws:
PKCSException - on verification errors.
IOException - on verification errors.
NoSuchAlgorithmException - on invalid algorithm errors.

addSigner

public void addSigner(Certificate cert,
                      PrivateKey privateKey,
                      String digestSignatureAlgorithm,
                      PKCSAttributes signedAttribs,
                      PKCSAttributes unsignedAttribs)
               throws PKCSException,
                      IOException,
                      NoSuchAlgorithmException
Add a SignerInfo entry to this SignedData object. With the specified certificate, private key, message digest algorithm, signature algorithm, and optional list of signed and unsigned attributes, sign the ContentInfo object within the EncapsulatedContentInfo object that is contained by this SignedData object.
Parameters:
cert - signer certificate
privateKey - signer private key
digestAlgorithm - message digest algorithm
signatureAlgorithm - signature algorithm
signedAttribs - signed PKCSAttributes
unsignedAttribs - unsigned PKCSAttributes
Throws:
PKCSException - on adding errors.
IOException - on adding errors.
NoSuchAlgorithmException - on invalid algorithms.

addSignerSignatureOnly

public void addSignerSignatureOnly(Certificate cert,
                                   PrivateKey privateKey,
                                   String digestSignatureAlgorithm)
                            throws PKCSException,
                                   IOException,
                                   NoSuchAlgorithmException
Add a SignerInfo entry to this SignedData object without any default or specified signed attributes. With the specified certificate, private key, message digest algorithm, signature algorithm, sign the data contained by the Content of the ContentInfo object within the EncapsulatedContentInfo object that is contained by this SignedData object. The SignedData ContentInfo must be of the Data type.
Parameters:
cert - signer certificate
privateKey - signer private key
digestAlgorithm - message digest algorithm
signatureAlgorithm - signature algorithm
Throws:
PKCSException - on adding errors.
IOException - on adding errors.
NoSuchAlgorithmException - on invalid algorithms.

addCertificate

public void addCertificate(Certificate[] certs)
Add a certificate array to the certificate array for this SignedData object. Duplicate certificate objects will not be added. This method allows callers to create a certificate chain within the SignedData object by adding certificates that do not need to have a corresponding SignerInfo object.
Parameters:
certs - Certificate array to add

addCRL

public void addCRL(CRL[] crls)
Add a CRL array to the CRL array for this SignedData object. Duplicate CRL objects will not be added. This method allows callers to add CRLs to an existing SignedData object.
Parameters:
crls - CRL array to add

encode

public void encode(OutputStream os)
            throws IOException
DER encode this object to an OutputStream.
Overrides:
encode in class PKCSDerObject
Parameters:
os - the OutputStream to write the encoded data to.
Throws:
IOException - on encoding errors.

decode

protected void decode(com.ibm.security.pkcs7.DerValue encoding)
               throws IOException
Initializes a SignedData object from a DerValue. The DER encoding must be in the format specified by the SignedData ASN.1 notation.
Parameters:
encoding - a DER-encoded SignedData object.
Throws:
IOException - on parsing error.

equals

public boolean equals(Object other)
Determines if this SignedData object is equivalent to the input object.
Overrides:
equals in class PKCSDerObject
Parameters:
other - the object to compare this one to.
Returns:
true, if the two objects are equivalent, false otherwise.

writeBASE64

public void writeBASE64(String filename)
                 throws IOException
DER-encode the object and write the encoded bytes to the output file in BASE64 format. If the SignedData object has only certificates, the file will begin with the following header: -----BEGIN CERTIFICATE----- contain the BASE64 DER-encoded SignedData object and end with the following footer: -----END CERTIFICATE-----
Overrides:
writeBASE64 in class PKCSDerObject
Parameters:
filename - the file to write the BASE64 DER-encoded object to.
Throws:
IOException - if the file cannot be created or written to.

toString

public String toString()
Returns a string representation of this SignedData object.
Overrides:
toString in class Content
Returns:
a string representation of this object.