SetaPDF-Signer Manual

Timestamp Modules

Introduction

The SetaPDF-Signer component allows you to add a timestamp to the final digital signature or to add a document level timestamp (PDF 2.0). Such a timestamp is created by a third party that acts as a Time Stamp Authority (TSA). The component will create a hash of the hash value of the signature which will be send to this entity. It will create a digital signature including a timestamp.

If the timestamp is created in a sign() process the result will be re-assembled into the main signature, so that it is part of it. If it is created in a timestamp() process the resulting timestamp token becomes the contents of the signature itself.

Beside the document integrity a timestamp signature will prove that the signed data exists before a certain point if the TSA is trusted.

A timestamp module implements the SetaPDF_Signer_Timestamp_Module_ModuleInterface interface. 

RFC 3161

The component comes with an abstract class for handling timestamps as described in RFC 3161.

CURL

An implementing class that uses CURL for the communication to the time stampserver is available: SetaPDF_Signer_Timestamp_Module_Rfc3161_Curl

Basically it requies the URL of the timestamp server. You can pass additional (or all) parameter, e.g. for authentication, to curl with the setCurlOption() method. All options will be passed to the curl_setopt_array() function.

<?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
);

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

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

// We need more space, if the signature will include a timestamp signature
$signer->setSignatureContentLength(17000);

// create the timestamp module
$tsModule = new \SetaPDF_Signer_Timestamp_Module_Rfc3161_Curl();
$tsModule->setUrl('http://zeitstempel.dfn.de');
$signer->setTimestampModule($tsModule);

// 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 */));

// sign the document and send the final document to the initial writer
$signer->sign($module);

Authenticate With Username and Password

You can authenticate by username and password by passing them to the setCurlOption() method: 

$username = 'yourUserName';
$password = 'yourSecretPassword';

$tsModule->setCurlOption(CURLOPT_USERPWD, $username . ':' . $password);

Authenticate With a Client Certificate

You also can authenticate with a client certificate by passing the desired options to the setCurlOption() method:

$certFile = 'client-certificate.pem';
$certPassword = 'password';

$tsModule->setCurlOption([
    CURLOPT_SSLCERT => $certFile,
    CURLOPT_SSLCERTPASSWD => $certPassword
]);

Authenticate With Individual HTTP Header

If the timestamp server uses an individual authentication method through an HTTP header, you can define this header through curl options, too (possible as of v2.45):

$tsModule->setCurlOption(CURLOPT_HTTPHEADER, ['X-API-Key: your-api-key']);