ONYX:Utilisation:Signature électronique de PDFs/en

Introduction

Mapping gives you the possibility to numerically sign the PDF files generated. To do so, electronic signatures associated with private keys are used.

prerequisite

Prior to this, we need to have in possession a certificate and a private key.

Generation of a certifiate and a private key. (For our example, via openssl)

openssl req -x509 -sha256 -nodes -days 365 -newkey rsa:2048 -keyout private.pem -out certificate.cer

Private key : private.pem
Certificate : certificate.cer

This command will generate a certificate and a private key named "autogenerated" without having to use an Certification authority. This makes sens only for testing purposes. For a real usage, we will need to obtain a certificate from the Certification Authority (CA)

Limits

The certificate is easily visible on Foxit Reader but not on Acrobat Reader.

To be done

1. Check if the certificate is visible on Acrobat when issued by a CA
2. Validate the PFX
3. Documenting the timestampurl (Probably a bug on it)

Remarks on certificates

Different types of certificates

MAPPING handles different types of certificates

PFX

A PFX file (or PKCS#12) is a file containing at the same time a private key and a certificate X.509. The generation of the request of the certificate signature (CSR, Certificate Signing Request) remains a recurrent problem for the customers. With a PFX file, the customer is no longuer required to create its own CSR. A Certification authority will do it in a totally secured way during the Request for Certificate process.

CSR

The Certification Authority (AC) uses the data of the request of the certificate signature to create your SSL certificate. Here is a list of the jey information :

Information about your company and the website that you want to secure via the SSL certificate. This one contains :

Label	Description
Common Name (CN)(ex : *.example.fr www.example.fr mail.example.fr)	The fully domain name qualified of your server. (FQDN)
Organization (O)	The social denomisation of your company. Make sure not to use abbreviation and include the company structure (Such as SA or other). For the EV and OV SSL, those information will be verified by the AC and be included in the certificate.
Organizational Unit (OU)	Organization department in charge of certificates management
City/Locality (L)	Town where your company is located.Please enter the full name.
State/County/Region (S)	Region where your company is located.Please enter the full name.
Country (C)	2 letter code of the country where your company is located.
Email Address	Contact person email address of your company.

2. Public key included in the certificate. The SSL uses the public key cryptography or asymetric to encode the exchanged data during a SSL connection. The public key is used for the encoding and the its private key used to decode the data.

3. Information on the type and length of the key. The length of the most common key is RSA 2048 but some Autority of Certification (AC) accept longeur keys (Ex : RSA 4096+) and the ECC keys.

The CSR are in general created in the PEM format encoded in Base64. You can open it in a simple text editor.

It is also possible to have the certificate and the private key in separate files or within the same file.

In separate files

Here is an example of a certificate and a private key in two separate files.

private.pem file

-----BEGIN PRIVATE KEY-----
MIIEvgIBADANBgkqhkiG9w0BAQEFA
...
HRgFVVNXS8jTjAo2LL7U6rZK8gwsXWzqaXNLsvwj9HoF89+reRosTfIIk
-----END PRIVATE KEY-----

Fichier certificate.cer

-----BEGIN CERTIFICATE-----
MIID2TCCAsGgAwIBAgIJAKcd3Qk2E
...
bJVSEN4kV0mdg5jrFhCCZjrlumzs+MQ=
-----END CERTIFICATE-----

In the same file

Here is an example of certificate and private key defined within the same file certifcle.pem

certifcle.pem file

Its content is a simple concatenation of the content of the private key and certificate files.

-----BEGIN PRIVATE KEY-----
MIIEvgIBADANBgkqhkiG9w0BAQEFA
...
HRgFVVNXS8jTjAo2LL7U6rZK8gwsXWzqaXNLsvwj9HoF89+reRosTfIIk
-----END PRIVATE KEY-----
-----BEGIN CERTIFICATE-----
MIID2TCCAsGgAwIBAgIJAKcd3Qk2E
...
bJVSEN4kV0mdg5jrFhCCZjrlumzs+MQ=
-----END CERTIFICATE-----

Settings

The usage of electronic signature within MAPPING requires the copy of the private key and certificate on the server.
Its usage is then possible in the MAPPING workflows or with command line using the map_xps command.

Copy of the file on the server

We need to place the private key file and the certificate file in the file system of the server.

(Example : /apps/mapping/certificate)

Different parameters

The electronic signature requires the usage of many parameters. You can find the list in the bellow table :

Parameter name	value	Signification
signclass	0	-
signdriver	blank	Electronic signature deactivated (Other parameter will not have any effect)
signdriver	OPENSSL	The OPENSSL mode is compatible with all platforms supported by MAPPING. it uses one or two file containing the certificate and private key. Those file must reside on the serveur (Network path not supported).
signdriver	FIRSTSIGNATURE	The FIRSTSIGNATURE mode is only available on Windows because it uses a certificate installed on the workstation. The certificate used is the one on the top of the list of certificates displayed in Internet Explorer.
signdriver	WINDOWS	Activation of SHA1 mode. Only available on Windows because it uses the certicate installed on the workstation. The certifacate used is defined by its hash key.(digital fingerprint).
signmode	FILENAME	To be used for the signature using the OPENSSL signdriver
signpassword	Passphrase valeur of the certifiate	Used in the case of security passphrase in the certificate
signsha1hash	SHA1 value	Used if the parameter "signdriver" is set to "WINDOWS"
signpemfile	Path and name of the private key file	Private key file alone or private key + certificate in the case both are in the same file
signcerfile	Path and name of the certificate file	Used only in the case of CSR file
signpfxfile	Path and name of the PFX file	Used only in the case of PFX file(PKCS#12)
timestampurl	??	To be documented

Utilization

Workflow

The MAPPING workflow box to be used is the toPDF box (XPS to web format / toPDF) By défaukt, this box allows to create a PDF file out of a XPS file. However, it is possible to set an electronic signature

Signature tab

This tab allows to set the parameters listed in the list of parameters table.

Remark : Note that the workflow initialize the parameter signclass to the value 0.

map_xps

It is also possible to use the MAPPING command map_xps

We will then need to set the electronic parameters via parameters -param:KEY=VALUE

Example :

"/apps/mapping/bin/map_xps" "-infile:/apps/mapping/infile/infile.xps" "-param:signmode=FILENAME" "-param:signclass=0"
-param:signdriver=OPENSSL" "-param:signpemfile=/apps/mapping/certificate/private.pem"
"-param:signcerfile=/apps/mapping/certificate/certificate.cer" "-toPDF" "-outfile:/apps/mapping/out/out.pdf"

Exemples

Exemple 1

In this example, we will see how to convert the input file (XPS file) into a sign PDF. We will see how to do this in using the MAPPING workflow and in command line using map_xps

Workflows

Create the following workflow :

Details of the toPDF box (Standard tab) :

Detail of the toPDF box (Signature tab)

Command line without convertion profile

Executes the following command :

"/apps/mapping/bin/map_xps" "-infile:/apps/mapping/infile/infile.xps" "-param:signclass=0" "-param:signmode=FILENAME" 
"-param:signdriver=OPENSSL" "-param:signpemfile=/apps/mapping/infile/private.pem" 
"-param:signcerfile=/apps/mapping/infile/certificate.cer" "-toPDF" "-outfile:/apps/mapping/output/out.pdf"

Command line with a convertion profile=

Convertion profile used :

<pdf_signature>
   <label>for Adobe Reader</label>
   <language>PDF</language>
   <signclass>0</signclass>
   <signmode>FILENAME</signmode>
   <signpassword></signpassword>
   <signdriver>OPENSSL</signdriver>
   <signpfxfile></signpfxfile>
   <signpemfile>apps/mapping/infile/private.pem</signpemfile>
   <signcerfile>apps/mapping/infile/certificate.cer</signcerfile>
 </pdf_signature>

Execute the following command :

"/apps/mapping/bin/map_xps" "-infile:/apps/mapping/infile/infile.xps" "-toPDF" "-outfile:/apps/mapping/output/out.pdf"
"-profile:pdf_signature"

Example 2

In this example, we will see how to use a file containing the private key and the certificate.

Workflows

Create the following workflow :

Detail of the toPDF box (Standard tab) :

Detail of the toPDF box (Signature tab) :

The file having the private key and the certificate must be entered in the pem parameter. Therefore we leave blank the cer parameter.

Command line without profil convertion

Execute the following command :

"/apps/mapping/bin/map_xps" "-infile:/apps/mapping/infile/infile.xps" "-param:signclass=0" "-param:signmode=FILENAME" 
"-param:signdriver=OPENSSL" "-param:signpemfile=/apps/mapping/infile/privatekey_certificate.pem" "-toPDF"
"-outfile:/apps/mapping/output/out.pdf"

Command line with a profil convertion

Used conversion profile :

<pdf_signature>
   <label>for Adobe Reader</label>
   <language>PDF</language>
   <signclass>0</signclass>
   <signmode>FILENAME</signmode>
   <signpassword></signpassword>
   <signdriver>OPENSSL</signdriver>
   <signpfxfile></signpfxfile>
   <signpemfile>apps/mapping/infile/privatekey_certificate.pem</signpemfile>
   <signcerfile></signcerfile>
 </pdf_signature>

Execute the following command :

"/apps/mapping/bin/map_xps" "-infile:/apps/mapping/infile/infile.xps" "-toPDF" "-outfile:/apps/mapping/output/out.pdf"
"-profile:pdf_signature"