SetaPDF-Signer Manual

Trust Settings

Introduction

A digital signature guarantees the document's integrity and it allows the recipient to identify the signer of a document. The integrity is proved by mathematic solutions but how do you know that the signer is really the signer you expect?

And how should the reader application know that the signers identity is the expected one? Well, at the end all of this is based on trust and entities that sign other certificates to confirm their identity - a certificate authority (CA). 

Trust Settings in Adobe Acrobat or Reader

By default Adobe Acrobat and Reader trust signers whose digital certificates can trace its lineage back to a certificate on the Adobe Approve Trust List (AATL), by the Certified Document Services (CDS) or on the European Union Trusted Lists (EUTL).

Nearly all certificates of these programs require the certificate to be stored on a secure hardware device, such as an USB token, which makes them not useable through PHP in common situations. To overcome this we had built several modules which allow you to communicate with key management systems (e.g. AWS KMS, Google KMS, Azure Key Vault) which store the keys as a service on a secure hardware device for you. You can find more details about the modules here.

Software certificates for companies (so called advanced seals) are also available as software certificates and validate through the EUTL.

Other certificate authorities offers software certificates but they are not automatically trusted by Acrobat or the Reader. Because of this a blue ribbon will be telling the user that "At least one signature has problems.".

To validate the signature you need to add the signators certificate or its root certificate to your "Trusted Certificates" as describe here.

Trust Settings in Collector Instance

To gather validation related information the SetaPDF-Signer also do some certificate chain building and verification. This process also needs to end in trusted root certificates.

The SetaPDF-Signer component doesn't come with any predefined trusted certificates. It is up to you what certificates you trust. Mostly the certifcate issuing certificate authority sends you a package of certificates which can be used to validate your own certificate. This package can be of different formats.

Create a Collection by Separated Certificate Files

If they send you individual certificate files you can build your trusted certificates collection that way:

$trustedCertificates = new \SetaPDF_Signer_X509_Collection();

$trustedCertificates->addFromFile('path/to/root.crt');
$trustedCertificates->addFromFile('path/to/other/root.pem');

$certificateContent = \file_get_contents('path/to/root2.pem');
$trustedCertificates->add($certificateContent);

// or

$certificate = new \SetaPDF_Signer_X509_Certificate($certificateContent);
$trustedCertificates->add($certificate);

Create a Collection by a CA-Bundle (PEM or p7b)

Sometimes a CA will send you a single file that holds all of their root certificates. This can be a PEM or p7b file.

You can load PEM bundles as follows:

$trustedCertificates = new \SetaPDF_Signer_X509_Collection();

$certificates = \SetaPDF_Signer_Pem::extractFromFile('path/to/root-bundle.pem');
$trustedCertificates->add($certificates);

$pemContent = \file_get_contents('path/to/root-bundle2.pem');
$certificates = \SetaPDF_Signer_Pem::extract($pemContent);
$trustedCertificates->add($certificates);

If you receive a p7b file, you can access the certifcates of it that way:

$certs = new \SetaPDF_Signer_Cms_CertsOnly(\file_get_contents('path/to/bundle.p7b'));
// this getAll() method returns a SetaPDF_Signer_X509_Collection instance
$trustedCertificates = $certs->getAll(); 

// or

$trustedCertificates = new \SetaPDF_Signer_X509_Collection();
$trustedCertificates->add($certs->getAll());