setasign / seta-pdf-signer-addon-global-sign-dss
A SetaPDF-Signer component signature module for the GlobalSign Digital Signing Service.
Requires
- php: ^7.1 || ^8.0
- guzzlehttp/guzzle: ^6.0
- setasign/setapdf-signer: ^2.31
Requires (Dev)
- phpunit/phpunit: ^7.0
This package is auto-updated.
Last update: 2021-01-07 09:21:11 UTC
README
This package offers modules for the SetaPDF-Signer component that allow you to use the Cloud-based Digital Signing Service by GlobalSign to digital sign and timestamp PDF documents in pure PHP.
Requirements
To use this package you need credentials for the GlobalSign Digital Signing Service which are:
- Your private key
- Client certificate for mTLS connection to the API
- Your API key and password
See "GlobalSign-Digital-Signing-Service-Guide 1.3.pdf" (or newer) for details. Ask a GlobalSign contact for this document.
This package is developed and tested on PHP >= 7.1. Requirements of the SetaPDF-Signer component can be found here.
Installation
Add following to your composer.json:
{
"require": {
"setasign/seta-pdf-signer-addon-global-sign-dss": "^1.0"
},
"repositories": [
{
"type": "composer",
"url": "https://www.setasign.com/downloads/"
}
]
}
and execute composer update
. You need to define the repository
to evaluate the dependency to the SetaPDF-Signer component (see here for more details).
Evaluation version
By default this packages depends on a licensed version of the SetaPDF-Signer component. If you want to use it with an evaluation version please use following in your composer.json:
{
"require": {
"setasign/seta-pdf-signer-addon-global-sign-dss": "dev-evaluation"
},
"repositories": [
{
"type": "composer",
"url": "https://www.setasign.com/downloads/"
}
]
}
Without Composer
Make sure, that the SetaPDF-Signer component is installed and its autoloader is registered correctly.
Then simply require the src/autoload.php
file or register this package in your own PSR-4 compatible autoload implementation:
$loader = new \Example\Psr4AutoloaderClass;
$loader->register();
$loader->addNamespace('setasign\SetaPDF\Signer\Module\GlobalSign\Dss', 'path/to/src/');
Usage
All classes in this package are located in the namespace setasign\SetaPDF\Signer\Module\GlobalSign\Dss
.
The Client
class
There's a simple Client
class which wraps the REST API into simple PHP methods. It handles the authentication, requests and responses internally. For the communication with the API it uses Guzzle.
The constructor of this class requires 3 arguments:
$options
which are the request options for Guzzle. To authenticate to the API endpoint it requires the cert
(the client certificated issued by GlobalSign) and ssl_key
(your private key) options. The headers
and body
options are set/overwritten internally.
$apiKey
is your API key received from GlobalSign.
$apiSecret
is the secret to your API key received from GlobalSign.
A common creation could look like:
$options = [
'cert' => 'path/to/tls-cert.pem',
'ssl_key' => 'path/to/private/key.pem'
];
$apiKey = 'xxxxxxxxxxxxxxxx';
$apiSecret = 'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx';
$client = new Dss\Client($options, $apiKey, $apiSecret);
You can use this instance to e.g. query general information:
$remainingSignatures = $client->getQuota(Dss\Client::TYPE_SIGNATURES);
// or
$signaturesCount = $client->getCount(Dss\Client::TYPE_SIGNATURES);
To create a digital signature you need to create a signing certificate first which can be done with the getIdentity()
method. The argument to this method can be an associative array as defined here. The method will return an Identity
instance which is nothing more than a data wrapper of the returned id, signing certificate and OCSP response.
$identity = $client->getIdentity();
This Identity
needs to be forward to the signature module which internally passes it back to the Dss\Client\sign()
method to get the final signature. It is also possible to use this method individually (just for completion):
$signature = $client->sign($identity, hash('sha256', $data));
The SignatureModule
class
This is the main signature module which can be used with the SetaPDF-Signer component. Its constructor requires 4 arguments:
$signer
is the instance of the \SetaPDF_Signer
class to which the module is passed afterwards. Internally $signer->setAllowSignatureContentLengthChange(false)
is called to prohibit redundant signature requests.
$client
needs to be the Dss\Client
instance.
$identity
a Dss\Identity
instance.
$module
needs to be a CMS or PAdES signature module instance. It is used internally to create the CMS container.
A simple complete signature process would look like this:
// setup the client and identity
$options = [
'cert' => 'path/to/tls-cert.pem',
'ssl_key' => 'path/to/private/key.pem'
];
$apiKey = 'xxxxxxxxxxxxxxxx';
$apiSecret = 'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx';
$client = new Dss\Client($options, $apiKey, $apiSecret);
$identity = $client->getIdentity();
// now start the signature process
$writer = new \SetaPDF_Core_Writer_File('signed.pdf');
$document = \SetaPDF_Core_Document::loadByFilename('invoice.pdf', $writer);
$signer = new \SetaPDF_Signer($document);
$signer->setSignatureContentLength(15000);
$pades = new \SetaPDF_Signer_Signature_Module_Pades();
$module = new Dss\SignatureModule($signer, $client, $identity, $pades);
$signer->sign($module);
The TimestampModule
class
This module can be used to add timestamps to the digital signature or to create document level timestamps. It's constructor simply requires a Dss\Client
instance:
$tsmodule = new Dss\TimestampModule($client);
It doesn't requires an identity as the signature module but can be passed as it is to the \SetaPDF_Signer
instance:
$signer->setTimestampModule($tsmodule);
// ...
$signer->sign($module);
or you can create a document level timestamp with it:
$signer->setTimestampModule($tsmodule);
// ...
$signer->timestamp();
Information about Tests
The test suite currently only comes with functional tests, which invoke real service calls! Keep in mind that these calls are deducted from your signature contingent and you should not execute these tests in an automated environment!
To execute the tests, you need to create a folder in the root of this package with the following file:
/private/
credentials.php
The credentials.php
file needs to return your credentials, certificate and private key:
<?php
return [
'apiKey' => '<YOUR API KEY>',
'apiSecret' => '<YOUR API SECRET>',
'cert' => '/path/to/your/mTLS/certificate.pem',
'privateKey' => '/path/to/your/private/key.pem'
];
License
This package is open-sourced software licensed under the MIT license.