Improving Signature Workflows with the Datalogics PDF Java Toolkit

Improving Signature Workflows with the Datalogics PDF Java Toolkit

Sample of the Week:

Because PDF can be an exact representation of paper, it has long been an obvious choice for using digital signatures to create documents of record so there are many solutions available to sign PDF files. These solutions range from apps that simply insert a graphic image of a signature that you’ve drawn with your finger, to digital pens and small tablets, to smart cards, to the self-signed certificates that anyone can create using Acrobat or Reader. Without additional programming, Acrobat creates signature fields that can be signed by anyone, using any certificate, for any reason. But some governments and enterprises have standardized on particular signing solutions and need to impose those constraints on their users, restricting their choices, and controlling the document behavior when signing. Fortunately, the PDF specification allows these restrictions to be stored in the PDF so that the Acrobat and Reader UI can present and enforce them. These restrictions are called “Seed Values.”

Seed values allow document authors to “seed” a signature field with attributes that control the document behavior even after it’s been distributed and no longer within the confines of their controlled environment. Seed values are field-level properties that can be either optional or required; optional values are presented as defaults in Acrobat and override any application level defaults. For example, using the Datalogics PDF Java Toolkit, developers can add seed values to PDF files to allow only signing using a certificate issued by a particular Certificate Authority. When a user signs a “seeded” field, Acrobat and Reader automatically invoke and enforce the restrictions specified by the seed.

You can see the effect of seed values on the Acrobat UI in the screenshots below. The first one shows the signing dialog for a signature field with no seed values. You can see that the two certificates that I created myself using Acrobat are presented as well as the certificate issued by GlobalSign.

anyThe image below shows that the seed values have restricted the list of certificates I can use to the one issued by GlobalSign.

limitedThe seed values can also store a URL that can be used to enroll for a new credential if a credential matching the required issuer is not found by the PDF viewer. Acrobat and Reader will launch the user’s default browser and take them to the right location to get what they need.

To help understand how to go about adding seed values, I created the Gist referenced below. It  adds two unsigned digital signature fields to an existing PDF file. The first signature field is created using just the default values of the SignatureFieldFactory class and can be signed using any certificate including self-generated certificates. The second signature is also created by the SignatureFieldFactory class but is further modified to contain “Seed Values.” When a user attempts to sign a “seeded” field, the author-specified behaviors are automatically invoked and enforced by Adobe Acrobat and Reader. In this case the seed values limit the user’s choices when signing the field and only allowing them to sign using a certificate issued by a particular Certificate Authority (CA), GlobalSign in this case, and restricting the “Reasons” for signing to a list of three.

To modify this sample to support the CA of your choice, replace the GlobalSign root certificate (Root-R3.cer) with one of your choosing. If you need to target to a particular individual and make it so that only that person can sign the file, replace the root certificate with that individual’s public certificate.

The first few lines of the Gist simply read in the source PDF file and root certificate and create the first signature field. The interesting part starts after we’ve create the second signature field. To create the seed value that limits the number of certificate issuers the signer is permitted to use, we first need to read in the public root certificate of the CAs in question so we can store them in the seed. Though this sample uses only one, multiple CAs can be supported so they get stored in an array of byte arrays.

Once we have the array of certificate issuers, we can create the “certificate” seed value which is just one of several seed values. By setting the flag to 2 we are making the use of a certificate issued by GlobalSign a requirement rather than just a suggestion which appears as the default in the Acrobat or Reader UI. See SigCertificateSeedValue for other flag settings. Setting the URL will allow Acrobat to prompt the user to open a URL that can be used to enroll for a new credential.

At this point, we can create a new SigSeedValue object and add the SigCertificateSeedValue to it followed by the list of reasons, set the filter and the flags, and finally adding the SigSeedValue to the signature field (highlighted). Because we know that Acrobat’s default signature handler supports all the seed values defined by the PDF standard. We set the default handler to be a requirement by setting the filter and then using the flag to make that filter required rather than simply a default suggestion.

The power of digital signatures in PDF is that the file format is rich enough that the signing process can be as permissive or as strict as your business requires. The Datalogics PDF Java Toolkit is similarly flexible in that it can create a simple digital signature field with a single line of code but can then refine the properties of that field to match your business rules.

To run this Gist, you’ll need at least an evaluation version of the Datalogics PDF Java Toolkit. The input files are fetched from our server by the code so you won’t need to install those.

Leave a Reply

Your email address will not be published.