TUTORIALS

 How to use Signer: Signing a document

As easy as 1, 2, 3...

This document assumes that you have read the previous introductory tutorials and especially the one about key store management.

Introduction

In the 17th century, members of the European nobility sealed documents and letters with melted wax which they then imprinted with a carved signet. The resulting wax seal not only made sure that the content would be read only by the intended recipient, its embossed coat of arms also revealed the identity of the author.
Four centuries later, digital signatures - in a more sophisticated way - provide the same kind of security and information. When a signature is applied to a PDF document, the document content is sealed (using a complex unbreakable formula) and information about the signer is added to the document.

We will see in this tutorial how jPDF can assist you in applying digital signatures to PDF documents.

Signature category

Signatures are identified by a unique name and are basically part of two signature categories. These are:

Visible signatures

These show a graphical representation on a page - typically something that looks like the figure below. Their appearance, which is the way they "look," can be customized (see tutorial). They are typically used for workflow processes in which you need users to input/approve information and apply their signature.

The method to create this kind of signature is:
SignatureField createInstance(PdfDocument document, String name, int pageIndex, Rectangle rect)

Invisible signatures

These are not directly visible on the document, but they will show in a summary popup when the document is opened. They also show as a small icon in the left bottom corner of the viewer's window. This category is typically used to seal a document.

The method to create this kind of signature is:
SignatureField SignatureField.createInstance(PdfDocument document, String name)

Signing or re-signing a document

We saw in the previous tutorial how we could retrieve the private key and the certification chain from a key store. All the following examples assume that you have:

// The private key:
PrivateKey key;

// The associated certification chain:
Certificate[] certs;

Now, let's use this information to create a digital signature on a PDF document. There are two ways to sign a document:

1. Adding a new signature to a document.
2. Re-sign an existing signature (if it isn't locked).

// Open the document:
PdfDocument doc=new PdfDocument("myunsigneddoc.pdf");

// Get the signer module:
SignerModule sm = doc.getSignerModule();

// Sign the document by creating a new invisible signature:
SignatureField signature = SignatureField.createInstance(doc,"myNewSignatureName");
signature.sign(key, chain);

// Save and close:
doc.save();
doc.close();

That's it! Easy, isn't it?
Well, if you compare jPDF with its competitors you will certainly notice a difference in the complexity of the code. Indeed, jPDF abstracts all the complexity of the PDF internals and cryptography to its bare minimum - allowing nonspecialists to achieve their goals easily.

Signing an existing signature is just as easy. Take a look:

// Open the document:
PdfDocument doc=new PdfDocument("mysigneddoc.pdf");

// Get the signer module:
SignerModule sm = doc.getSignerModule();

// Now, we need to get the signature by its name:
SignatureField signature = sm.getSignature("mySignature");

// Then, we just sign it!
signature.sign(key, certs);

// Save and close:
doc.save();
doc.close();

Convinced? Let's see how to validate a signature - check the next tutorial...