org.faceless.pdf2
Class PKCS7SignatureHandler

java.lang.Object
  org.faceless.pdf2.SignatureHandler
      org.faceless.pdf2.PKCS7SignatureHandler

public abstract class PKCS7SignatureHandler
extends SignatureHandler

This class represents the subclass of digital signatures that rely on Public/Private key pairs and that meet the requirements laid down in the document "PDF Public-Key Digital Signature and Encryption Specification", published by Adobe. Currently we know of three handlers that meet this requirement - the general purpose PKCS#7 handler supplied with Acrobat 6.0 and later, or (for earlier versions) the Adobe "Self-Sign" handler and the plugin supplied by VeriSign.

See Also:

AcrobatSignatureHandlerFactory

Constructor Summary

protected

PKCS7SignatureHandler()

Method Summary

X509Certificate[]	getCertificates() Return the list of certificates included in this signature.
protected abstract String	getHashAlgorithm() Return the Hash algorithm used by the PKCS#7 object when signing.
PDFCanvas	getLayerAppearance(String layername, PDFStyle textstyle) Return a PDFCanvas for the specified layer.
String[]	getLayerNames() Return the list of appearance layer names used by this Signature Handler to create a visible appearance on the page, in the order they should be drawn.
MessageDigest	getMessageDigest() Return a MessageDigest that will be used to calculate the digest of the PDF for signing.
protected abstract String	getSubFilter() Return the SubFilter field, which determines how the PKCS#7 object is encoded.
X509Certificate[]	getTimeStampCertificates() If the PKCS#7 object was digitally time-stamped using an RFC3161 time-stamp server, this method verifies and returns the list of X.509 certificates that verify the timestamp, with the actual signing certificate first and the rest in no particular order.
protected void	prepareToSign(KeyStore keystore, String alias, char[] password) This method initialized the handler using the specified values into a state where it's ready to sign.
void	setCustomAppearance(PDFCanvas canvas, float x1, float y1, float x2, float y2) Set a custom appearance for this signature.
byte[]	sign() Finish the digest calculation on the digest returned from SignatureHandler.getMessageDigest() and return a signature token the signs it.
boolean	verify(InputStream in) Return a boolean indicating whether or not the signature handler can verify the specified InputStream.

Methods inherited from class org.faceless.pdf2.SignatureHandler

containsKey, getArrayValueSize, getBooleanValue, getDictionaryValueKeys, getFilter, getNameValue, getNumericValue, getStreamValue, getStringValue, getTextStringValue, getVariable, getVariables, isVariableEncrypted, putArrayValue, putBooleanValue, putDictionaryValue, putNameValue, putNumericValue, putStreamValue, putStringValue, putTextStringValue

Methods inherited from class java.lang.Object

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

Constructor Detail

PKCS7SignatureHandler

protected PKCS7SignatureHandler()

Method Detail

getHashAlgorithm

protected abstract String getHashAlgorithm()

Return the Hash algorithm used by the PKCS#7 object when signing. Valid values are currently "MD5", "SHA1" or "SHA256".

getSubFilter

protected abstract String getSubFilter()

Return the SubFilter field, which determines how the PKCS#7 object is encoded. Valid values are "adbe.pkcs7.detached", "adbe.pkcs7.sha1" or "adbe.x509.rsa_sha1"

prepareToSign

protected void prepareToSign(KeyStore keystore,
                             String alias,
                             char[] password)
                      throws GeneralSecurityException

Description copied from class: SignatureHandler

This method initialized the handler using the specified values into a state where it's ready to sign. This method should be used to set any additional fields in the Signature dictionary, for example "Certs" for the Self-Sign handler.

Those overriding this method must call super.prepareToSign() before doing anything else.

Overrides:

prepareToSign in class SignatureHandler

Parameters:

keystore - the KeyStore holding the signing key

alias - which key in the KeyStore to use

password - the password to use to decode the key from the keystore

Throws:

GeneralSecurityException

getMessageDigest

public MessageDigest getMessageDigest()

Description copied from class: SignatureHandler

Return a MessageDigest that will be used to calculate the digest of the PDF for signing.

Specified by:

getMessageDigest in class SignatureHandler

sign

public byte[] sign()
            throws GeneralSecurityException,
                   IOException

Description copied from class: SignatureHandler

Finish the digest calculation on the digest returned from SignatureHandler.getMessageDigest() and return a signature token the signs it. This method will be called more than once - the first time with a zero-length stream, to calculate the length of the token, the second time with the actual data to sign. The returned byte array will be stored as the "Contents" value of the Signature dictionary.

Specified by:

sign in class SignatureHandler

Returns:

a byte array representing the signature token

Throws:

GeneralSecurityException - if the signature cannot be applied for some cryptographic reason

IOException - if the InputStream cannot be read

verify

public final boolean verify(InputStream in)
                     throws GeneralSecurityException,
                            IOException

Description copied from class: SignatureHandler

Return a boolean indicating whether or not the signature handler can verify the specified InputStream.

Specified by:

verify in class SignatureHandler

Returns:

true if the signature matches the specified InputStream

Throws:

GeneralSecurityException - if the signature cannot be verified for some cryptographic reason

IOException - if the InputStream cannot be read

getCertificates

public final X509Certificate[] getCertificates()
                                        throws CertificateException

Return the list of certificates included in this signature. The first certificate is the X.509 certificate used to sign the PDF, and the optional additional certificates are those used to validate the earlier certificates, in no particular order.

Returns:

a list of one or more X.509 Certificates

Throws:

CertificateException

getLayerNames

public String[] getLayerNames()

Description copied from class: SignatureHandler

Return the list of appearance layer names used by this Signature Handler to create a visible appearance on the page, in the order they should be drawn. This method is called internally by the FormSignature class when drawing the signature annotations on the page. For more information see the document "Digital Signature Appearances for Public-Key Interoperability", from Adobes website.

As an example, both the Verisign and the SelfSign handlers return the array [ "n0", "n1", "n2", "n3" ].

Specified by:

getLayerNames in class SignatureHandler

Returns:

the ordered list of layer names that should to used to create a visible representation of this signature on a page.

See Also:

SignatureHandler.getLayerAppearance(java.lang.String, org.faceless.pdf2.PDFStyle)

getLayerAppearance

public PDFCanvas getLayerAppearance(String layername,
                                    PDFStyle textstyle)

Description copied from class: SignatureHandler

Return a PDFCanvas for the specified layer. This method is called internally by the FormSignature class when drawing the signature annotations on the page. For more information see the document "Digital Signature Appearances for Public-Key Interoperability", from Adobes website.

Specified by:

getLayerAppearance in class SignatureHandler

Parameters:

layername - the layer to create (from the list returned by SignatureHandler.getLayerNames())

textstyle - the style in which to draw the text, if any

Returns:

a new PDFCanvas of any size containing the specified layer.

See Also:

SignatureHandler.getLayerNames()

setCustomAppearance

public void setCustomAppearance(PDFCanvas canvas,
                                float x1,
                                float y1,
                                float x2,
                                float y2)

Set a custom appearance for this signature. See the AcrobatSignatureHandlerFactory.setCustomAppearance(org.faceless.pdf2.PDFCanvas, float, float, float, float) method for more details - unless you're manually overriding this class, that's the method you should be calling.

Parameters:

canvas - the canvas to display as the "n2" layer of the signature appearance.

x1 - the left-most X co-ordinate to place the (optional) certificate text

y1 - the bottom-most Y co-ordinate to place the (optional) certificate text

x2 - the right-most X co-ordinate to place the (optional) certificate text

y2 - the top-most Y co-ordinate to place the (optional) certificate text

Since:

2.0

getTimeStampCertificates

public X509Certificate[] getTimeStampCertificates()
                                           throws GeneralSecurityException,
                                                  IOException

If the PKCS#7 object was digitally time-stamped using an RFC3161 time-stamp server, this method verifies and returns the list of X.509 certificates that verify the timestamp, with the actual signing certificate first and the rest in no particular order. If this method succeeds, then the date returned by FormSignature.getSignDate() is the date guaranteed by the time-stamp.

If the signature was time-stamped but the timestamp is corrupt or invalid, thie method will throw either a GeneralSecurityException or a IOException detailing why.

If the signature was not timestamped, this method returns null.

Returns:

an array of X509Certificate objects that authorized the timestamp, or null if there isn't a timestamp.

Throws:

GeneralSecurityException - if the TimeStamp is invalid

IOException - if the TimeStamp is corrupt or can't be parsed

Since:

2.7.1