TUTORIALS

 How to use Signer:
Using a custom signer to integrate with hardware devices

As easy as 1, 2, 3...

Introduction to PDF signatures and hardware signer

Let's start from the beginning and see how PDF signatures are different from standard digital signatures.

Starting with Acrobat 4.0, Adobe changed the PDF specification to allow the inclusion of a digital stamp directly in the PDF structure. The signature not only gives information about the signer's identity, but it also seals the document content and allows the detection of any modification within the PDF content.

A PDF signature has the following features (on top of traditional signatures):

• The signature is embedded inside the PDF document.
• Transparent management of different signature types: A signature can be encoded using a PKCS1 or PKCS7 object, while the algorithm used to compute the signature value might differ (typically a byte range interval or a digest, as introduced by the latest PDF Specs).
• Flexible signature management that allows a signature to be left BLANK or LOCKED.
• Graphical integration: Signatures can be set to be invisible or displayed on a page via a dialog box appearing when the PDF is opened.

Creating the PDF structure that holds a digital signature is not an easy task and it requires strong PDF knowledge. The process is even more complex when you have to integrate it with a hardware device.

There are many different kinds of hardware devices. Some have a Java Card API. Some are mounted like a file system, while others will work with streams or byte arrays. In fact, the only thing they have in common is that the private key is hidden and cannot be disclosed at anytime.

Typically a hardware signer will have interfaces to:

• Receive input data (either via a file, stream or byte array)
• Produce signature data (as a set of files, pkcs7 object,...)

In the next chapter we will discuss the CustomPKCS7Signer which allows corporations to easily integrate their hardware with jPDF Signer.

Introducing the jPDF CustomPKCS7Signer

CustomPKCS7Signer is an abstract class that allows application authors to hook the jPDF Signer processing to custom code. It is the perfect place to integrate a hardware device. As hardware devices hold the private key, the standard jPDF methods have been updated to accept this custom signing approach to sign a document.

Class SignerModule

public Signature createSignature(String name, CustomPKCS7Signer signer) throws PdfException, IOException

Class Signature

public void sign(CustomPKCS7Signer signer) throws PdfException, IOException

But let's have a closer look at the CustomPKCS7Signer class:

The class exposes five methods, called by jPDF Signer, as follows:

Step Name	Methods	Comments
Initialization	reset()	Resets the hardware signer.
Calculation	update(byte)	Calculates the signature value. The bytes part of the signature calculation are passed one by one.
Signature Generation	getSignatureDigest() getCertificateChain() getHashAlgoName()	These methods are used to build a PKCS7 signature object compatible with Acrobat.

Note that there are no methods to get/set the private key. That's because the private key is part of the hardware.
For more information regarding each method, please refer to the javadoc.

Algorithm

The process of generating a PDF signature is broken down into two main steps:

1. PREPARATION

This takes place when the code creates and/or signs the document.
jPDF Signer populates the PDF structure which will hold the PKCS7 signature. Among other things, the structure is filled with information about the signer certificate (name, location, contact #, etc.,...).
jPDF Signer also tries to figure out the size of the PKCS7 signature by running a dummy signature calculation.

2. GENERATION

The generation is performed when the document is saved to the file system.
The final signature calculation is processed at this time. jPDF Signer calculates the file ranges element of the signature calculation (typically the whole file minus the range for the PKCS7 signature). It then processes all the bytes that are part of the signature calculation, next creates a valid PKCS7 that Acrobat can understand and, finally, writes it in the PDF file.

Details of the calls to customPKCS7Signer:

PREPARATION

1. In order to determine the size necessary to hold the signature in the PDF, jPDF Signer performs the following steps:
   
   reset();
   update(0);
2. A dummy PKCS7 signature is generated using the methods getHashAlgoName(), getSignatureDigest() and getCertificateChain().
3. The signing certificate, getCertificateChain()[0], is used to fill the PDF signature structure with data (name, location, etc.,...)

GENERATION

1. jPDF Signer calculates the correct signature byte ranges in order to skip the dummy signature allocated in the previous step.
2. The final signature calculation takes place. The methods are called in this order:
   
   reset()
   // For each of the bytes part of the signature calculation:
   update(b)
3. Finally, getHashAlgoName(), getSignatureDigest() and getCertificateChain() are called to create the final PKCS7 signature.

Samples

The jPDF distribution comes with two sample programs; one for the generation and the other for the validation.
For the purpose of the demo, we simulated the hardware device with a singleton class. It is recommended that you read the sample code to better understand how to implement a custom signer.