org.faceless.pdf2
Class DSE200Handler

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

public class DSE200Handler
extends SignatureHandler

Note. Acrobat 7 now supports RFC3161, the industry standard method of embedding a certified timestamp in a digital signature. This requires no additional plugins for Acrobat, and since 2.7.1 is supported with our PDF library via the AcrobatSignatureHandlerFactory.setTimeStampServer(java.net.URL) method. Unless you're specifically targeting Acrobat 6.0, we'd encourage you to use that approach instead of this class

This class is an implementation of SignatureHandler that can be used to time-stamp documents using an nCipher DSE200. These documents can then be verified using nCiphers pdfProof plugin for Acrobat.

Using this class is fairly simple. First, you will need the asn1rt.jar and tti.jar files supplied with the DSE200 Development Kit in your CLASSPATH (if you don't have a copy of the DSE200 SDK, get in touch with nCipher through their website). Additionally, if signing (rather than verifying) you will need the hostname of the DSE you're using to sign. Then, it's as simple as:

  SignatureHandlerFactory factory = new DSE200HandlerFactory(hostname, DSE200HandlerFactory.TSP);
  FormSignature sig = new FormSignature(null, null, null, factory);
  sig.addAnnotation(page, 100, 500, 300, 700);
  form.getElements().put("TestSignature", sig);
 

To verify documents, as with all public key signatures you must first verify the signature matches the document, then verify that the certificates that signed it are trusted. To do this, first you must register the factory class like so:

  FormSignature.registerHandlerForVerification(new DSE200HandlerFactory(null,0));
 

and then call FormSignature.verify() as normal to confirm the signature matches the document. For further verification you can retrieve the Certificate used to sign the TimeStamp with getSignerCertificate(), or the getTimeStampToken() method can be called to retrieve the DER encoded TimeStampToken object, which can be parsed and verified seperately if required.

Note: If running these classes with Java 1.2, an external security provider must also be installed or signature validation functions will throw NoSuchAlgorithmException.

Since:

2.3

Method Summary

String	getFilter() Return the name of the filter, eg "Adobe.PPKLite".
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.
Calendar	getSignatureDate()
X509Certificate	getSignerCertificate() Return the Signer Certificate used to sign this timestamp
String	getSubFilter()
byte[]	getTimeStampToken() Return the encoded TimeStampToken object used to sign the document.
byte[]	getVariable(String name) This method returns the contents of the variable specified by name.
Map	getVariables() Return the list of "variables" which will be set by the handler after the PDF is rendered.
boolean	isVariableEncrypted(String name) When signing an encrypted document, whether to encrypt the specified variable or not.
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 true if the hash of the signed document is the same as the hash included in the PKCS#7 object, the time in the signature dictionary is the same as the time in the time-stamp, and if the signature of the time-stamp matches the signer certificate stored in the time-stamp.

Methods inherited from class java.lang.Object

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

Method Detail

getFilter

public String getFilter()

Description copied from class: SignatureHandler

Return the name of the filter, eg "Adobe.PPKLite".

Specified by:

getFilter in class SignatureHandler

getSubFilter

public String getSubFilter()

getVariables

public Map getVariables()
                 throws GeneralSecurityException

Description copied from class: SignatureHandler

Return the list of "variables" which will be set by the handler after the PDF is rendered. Entries in the returned map should have a String as a key and a byte[] as a value. The byte array should be empty (ie all zeros), and should be long enough to hold the token that will eventually be substituted into it from the SignatureHandler.getVariable(java.lang.String) method.

Remember that the token may be encrypted if it is a string (or contains a string) and an EncryptionHandler is present. For that reason it's recommended to encode enough spaces after any string to cater for expansion due to character escaping. For example, the variable value (Test) may be converted to (r^$\n) after encryption - which requires an extra byte.

For most SignatureHandlers, the only variable is the "Contents" array containing the signature token, which is what this method returns (it may be overridden if more variables are required).

This method and SignatureHandler.getVariable(java.lang.String) replace the isPDFObjectSignature method which was added in 2.2.4 but has been removed in favour of this considerably more flexible approach.

Overrides:

getVariables in class SignatureHandler

Returns:

a Map containing the name and size of variables to be substituted into the "V" dictionary.

Throws:

GeneralSecurityException

See Also:

AcrobatSignatureHandlerFactory.setContentSize(int)

isVariableEncrypted

public boolean isVariableEncrypted(String name)

Description copied from class: SignatureHandler

When signing an encrypted document, whether to encrypt the specified variable or not. The PDF specification is silent on this, and different handlers have different approaches. For instance, the standard Adobe handlers encrypt every variable except the "Contents" field. The nCipher TimeSeal handler encrypts all variables including Contents. This method should return true if the variable is to be stored encrypted in an encrypted PDF.

The default implementation of this method returns true for every variable except "Contents"

Overrides:

isVariableEncrypted in class SignatureHandler

Parameters:

name - the name of a variable - guaranteed to be one of the keys returned from SignatureHandler.getVariables()

Returns:

true if, when signing an encrypted document, this variable is to be stored encrypted

getVariable

public byte[] getVariable(String name)
                   throws GeneralSecurityException

Description copied from class: SignatureHandler

This method returns the contents of the variable specified by name. It is called after the SignatureHandler.sign() method. The returned byte array should not be longer than the array returned by SignatureHandler.getVariables(), and as it will be substituted straight into the PDF should contain any PDF formatting that's required - for example, if returning a string, you need to make sure the "(" and ")" characters are added around the String and that any nested "(" characters are escaped. This method will be called once for each item returned from the SignatureHandler.getVariables() method, except for "Contents" (which is handled seperately).

Overrides:

getVariable in class SignatureHandler

Parameters:

name - the name of a variable - guaranteed to be one of the keys returned from SignatureHandler.getVariables() (although not "Contents")

Returns:

a byte array which will be substituted into the "V" dictionary of the Signature Handler.

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

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

verify

public boolean verify(InputStream in)
               throws GeneralSecurityException

Return true if the hash of the signed document is the same as the hash included in the PKCS#7 object, the time in the signature dictionary is the same as the time in the time-stamp, and if the signature of the time-stamp matches the signer certificate stored in the time-stamp.

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

getSignerCertificate

public X509Certificate getSignerCertificate()

Return the Signer Certificate used to sign this timestamp

getSignatureDate

public Calendar getSignatureDate()

getTimeStampToken

public byte[] getTimeStampToken()

Return the encoded TimeStampToken object used to sign the document. This can be used to perform further, independent validation of the time-stamp if required.

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()