README

This package offers a module for the SetaPDF-Signer component that allows you to use the OVHcloud Key Management Service to digital sign PDF documents in pure PHP.

At the moment of writing the OVHcloud KMS only supports keys which are stored and secured on a software level. This level doesn't allows you to use the keys with e.g. AATL conforming certificates.

BUT, actually OVH is working on a new OVHcloud Shared HSM service which will fill this gap. More details can be found in the related GitHub issue.

Requirements

The current version of the module is developed and tested on PHP >= 8.1 up to PHP 8.5. Requirements of the SetaPDF-Signer component can be found in the manual.

For sure you will need to have an active OVHcloud KMS-Domain with an related access certificate and at least one managed service key. Simply read and follow the "Getting started" guide for this.

For PDF signing you will also need a X509 certificate with the corresponding public key. To create a self-signed test certificate or a CSR (Certificate Signing Request), OVH provides a great CLI tool for this.

You can e.g. create a simple self-signed testing certificate with the following command:

okms x509 create cert <your-key-id> --cn "<our-common-name>"

Installation

Add following to your composer.json:

{
    "require": {
        "setasign/setapdf-signer-addon-ovhcloud-kms": "^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).

The Setasign repository requires authentication data: You can use your credentials of your account at setasign.com to which your licenses are assigned or use an access token which you can create in your personal composer settings on setasign.com. See here for more options for authentication with composer.

Usage

All classes in this package are located in the namespace setasign\SetaPDF\Signer\Module\OVHcloudKMS.

The Client class

The client class is some kind of wrapper to the REST API of the OVHcloud KMS. It comes with a simple call() method that allows you to call individual endpoints, but also implements the sign() method which is used by the Module class.

Its constructor requires the following arguments:

• string $apiUri - Your Rest API endpoint
• string $oKmsId - Your OVHcloud KMS ID
• ClientInterface $httpClient - A PSR-18 HTTP Client implementation.
• RequestFactoryInterface $requestFactory - PSR-17 HTTP Factory implementation.
• StreamFactoryInterface $streamFactory - PSR-17 HTTP Factory implementation.

The PSR-18 HTTP Client implementation needs to support mTLS authentication. We use and suggest e.g. Guzzle for this.

So creating a Client instance could look like this:

use setasign\SetaPDF\Signer\Module\OVHcloudKMS\Client;

$httpClient = new GuzzleHttp\Client([
    'cert' => '/path/to/your/mtls/certficate.pem',
    'ssl_key' => '/path/to/your/mtls/privatekey.pem',
]);

$requestFactory = new Http\Factory\Guzzle\RequestFactory();
$streamFactory = new Http\Factory\Guzzle\StreamFactory();

$client = new Client(
    '<your-api-url>',
    '<your-okms-id>',
    $httpClient,
    $requestFactory,
    $streamFactory
);

The Module class

This is the main signature module which can be used with the SetaPDF-Signer component. Its constructor requires only an instance of the Client class:

use setasign\SetaPDF\Signer\Module\OVHcloudKMS\Module;

$module = new Module($client);

Then you have to configure the instance through various methods:

Module::setKeyId(string $keyId)

Set the id of the service key. E.g.:

$module->setKeyId('dbbd1a34-9f69-4aef-8600-0627da52a4cb');

Module::setDigest(string $digest)

A proxy method to the setDigest() method of internally used Pades instance.

Module::setSignatureAlgorithm(string $signatureAlgorithm)

Set the signature algorithm. You have to make sure that the algorithm matches your key. Possible values are Digest::RSA_PSS_ALGORITHM, Digest::RSA_ALGORITHM or Digest::ECDSA_ALGORITHM.

A simple complete signature process would look like this:

use setasign\SetaPDF\Signer\Module\OVHcloudKMS\Client;
use setasign\SetaPDF\Signer\Module\OVHcloudKMS\Module;
use setasign\SetaPDF2\Core\Document;
use setasign\SetaPDF2\Core\Writer\FileWriter;
use setasign\SetaPDF2\Signer\Digest;
use setasign\SetaPDF2\Signer\Signer;
use setasign\SetaPDF2\Signer\ValidationRelatedInfo\IntegrityResult;
use setasign\SetaPDF2\Signer\X509\Certificate;

require_once __DIR__ . '/../vendor/autoload.php';

$httpClient = new GuzzleHttp\Client([
    'cert' => '/path/to/your/mtls/certficate.pem',
    'ssl_key' => '/path/to/your/mtls/privatekey.pem',
]);

$requestFactory = new Http\Factory\Guzzle\RequestFactory();
$streamFactory = new Http\Factory\Guzzle\StreamFactory();

$client = new Client(
    '<your-api-url>',
    '<your-okms-id>',
    $httpClient,
    $requestFactory,
    $streamFactory
);

$writer = new FileWriter('result.pdf');
$document = Document::loadByFilename(__DIR__ . '/assets/Laboratory-Report.pdf', $writer);

$signer = new Signer($document);
$field = $signer->addSignatureField();
$signer->setSignatureFieldName($field->getQualifiedName());

$module = new Module($client);
$module->setDigest(Digest::SHA_512);
$module->setKeyId('<your-key-id>');
$module->setSignatureAlgorithm(Digest::RSA_PSS_ALGORITHM);
$module->setCertificate(Certificate::fromFile('/path/to/your/certificate.pem'));

$signer->sign($module);

$newDocument = Document::loadByFilename('result.pdf');

License

This package is open-source software licensed under the MIT license.