org.faceless.pdf2
Class PKCS7SignatureHandler

java.lang.Object
  extended by org.faceless.pdf2.SignatureHandler
      extended by 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

Nested Class Summary
 
Nested classes/interfaces inherited from class org.faceless.pdf2.SignatureHandler
SignatureHandler.Placeholder
 
Field Summary
protected  org.faceless.pdf2.PKCS7 pkcs7
           
 
Constructor Summary
protected PKCS7SignatureHandler()
           
 
Method Summary
 X509Certificate[] getCertificates()
          Return the list of certificates included in this signature.
 String getDefaultName()
          Returns an optional default value that can be used to initialize FormSignature.setName(java.lang.String), or null if no such name is available.
 int getEstimatedContentSize(int additional)
          Return the estimated size of the signature object to be embedded, or <= 0 if this cannot be determined.
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.
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, getFormSignature, getNameValue, getNumericValue, getStreamValue, getStringValue, getTextStringValue, getVariables, postDigest, preDigest, 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
 

Field Detail

pkcs7

protected org.faceless.pdf2.PKCS7 pkcs7
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 SHA1, SHA256, SHA384, SHA512 or MD5


getSubFilter

public 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" "adbe.x509.rsa_sha1" or "ETSI.CAdES.detached"


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
alias - which key to use
password - the password to use to decode the key
Throws:
GeneralSecurityException

getEstimatedContentSize

public int getEstimatedContentSize(int additional)
Description copied from class: SignatureHandler
Return the estimated size of the signature object to be embedded, or <= 0 if this cannot be determined. The default implementation returns 0.

Overrides:
getEstimatedContentSize in class SignatureHandler
Parameters:
additional - the negation of any value previously passed into SignatureHandler.setContentSize(int)

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. This message will be called before SignatureHandler.sign() - see the API docs for that method for more details.

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. The returned byte array will be stored as the "Contents" value of the Signature dictionary.

As well as being called to perform the actual signing, the default behaviour of the SignatureHandler.getVariables() method is also to call this method with an empty digest, to determine the size of the token to store in the PDF (the SignatureHandler.getMessageDigest() method is called twice as well). This can be overridden, by calling AcrobatSignatureHandlerFactory.setContentSize(int) for handlers created by that factory or, if you're implementing a custom signature handler, by writing your own SignatureHandler.getVariables() method.

Overrides:
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 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

getDefaultName

public String getDefaultName()
Description copied from class: SignatureHandler
Returns an optional default value that can be used to initialize FormSignature.setName(java.lang.String), or null if no such name is available.

Overrides:
getDefaultName in class SignatureHandler


Copyright © 2001-2012 Big Faceless Organization