SetaPDF-Signer Manual

Asynchronous Signature Workflow

Introduction

As of version 2.2 the SetaPDF-Signer component introduced a asynchronous signature workflow. This allows more flexibility in view to individual signature modules for e.g. batch processing.

The asynchronous workflow makes use of a new class instance which represents a temporary version of the document that should be signed: The SetaPDF_Signer_TmpDocument class.  

This instance is bound to a document instance of the original PDF document and is created automatically by specific methods of the signer instance. The asynchronous workflow is done by passing this instance and the signature module (if it implements the SetaPDF_Signer_Signature_DictionaryInterface interface) to several public methods of the signer instance.

The Workflow

preSign() / preTimestamp()

To start an asynchronous workflow the required temporary document instance has to be created by one of the following methods.

To start a "normal" signature workflow the preSign() method has to be used, while a document level timestamp signature requires the preTimestamp() method to be called: 

preSign()

Prepares a temporary document instance to be used further in an asynchronous signature workflow.

preTimestamp()

Prepares a temporary document instance to be used further in an asynchronous timestamp workflow.

createSignature() / createTimestampSignature()

To create a signature or timestamp siignature the next methods are: 

createSignature()

Creates a signature based on a temporary document instance and a signature module.

createTimestampSignature()

Creates a timestamp signature based on a temporary document instance.

optional: addTimeStamp()

If you need to add a digital timestamp to the document signature the signature container can be updated by the following method: 

addTimeStamp()

Forwards the signature to a timestamp module and merges the result into the signature container.

saveSignature()

To finally save the signature or document level timestamp signature the saveSignature() method has to be used: 

saveSignature()

Add a signature result to the temporary document instance and saves it to the main documents writer instance.

Example

This example shows you the asynchronous workflow in a single script: 

<?php
require_once('library/SetaPDF/Autoload.php');

// create a writer
$writer = new \SetaPDF_Core_Writer_Http('simple.pdf', true);
// create a new document instance
$document = \SetaPDF_Core_Document::loadByFilename(
    'files/pdfs/tektown/Laboratory-Report.pdf', $writer
);

// ----- STEP 1 --------
// create a signer instance
$signer = new \SetaPDF_Signer($document);

// set some signature properties
$signer->setReason('Async Testing');
$signer->setLocation('SetaPDF-Signer Manual');

// let's create the temporary document instance
$tmpDocument = $signer->preSign(new \SetaPDF_Core_Writer_TempFile());

// ----- STEP 2 --------
// create a signature module
$module = new \SetaPDF_Signer_Signature_Module_Cms();
// load the certificate
$certificate = 'file://files/certificates/setapdf-no-pw.pem';
$module->setCertificate($certificate);
$module->setPrivateKey(array($certificate, '' /* no password */));

// create the signature
$signature = $signer->createSignature($tmpDocument, $module);

// ----- STEP 3 --------
// save the signature
$signer->saveSignature($tmpDocument, $signature);