Signature électronique de PDFs/en

<languages/>
==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<br>
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. <br>

<u>To be done</u>
#Check if the certificate is visible on Acrobat when issued by a CA
#Validate the PFX
#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 :

{| class="wikitable"
|-
! 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.

<u>private.pem file</u>
 -----BEGIN PRIVATE KEY-----
 MIIEvgIBADANBgkqhkiG9w0BAQEFA
 ...
 HRgFVVNXS8jTjAo2LL7U6rZK8gwsXWzqaXNLsvwj9HoF89+reRosTfIIk
 -----END PRIVATE KEY-----
<br>
<u>Fichier certificate.cer</u>
 -----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'''

<u>certifcle.pem file</u>
<br>
<br>
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.<br>
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.<br>
<br>
(Example : /apps/mapping/certificate)

===Different parameters===

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

{| class="wikitable"
|-
! Parameter name !! value !! Signification
|-
| '''signclass''' || 0 || Electronic signature activated |-
|-
|'''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


[[File:OX_S_SIGNPDF1.jpg|1300px|center|sans_cadre]]

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

<u>Remark</u> : 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'''

<u>Example</u> : 

 "/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 :

[[File:OX_S_SIGNPDF2.jpg|800px|center|sans_cadre]]

Details of the toPDF box (Standard tab) :

[[File:OX_S_SIGNPDF3.jpg|800px|center|sans_cadre]]

Detail of the toPDF box (Signature tab)

[[File:OX_S_SIGNPDF4.jpg|800px|center|sans_cadre]]

====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=====

<u>Convertion profile used</u> : 

 <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 :

[[File:OX_S_SIGNPDF2.jpg|800px|center|sans_cadre]]


Detail of the toPDF box (Standard tab) :

[[File:OX_S_SIGNPDF3.jpg|800px|center|sans_cadre]]


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.


[[File:OX_S_SIGNPDF5.jpg|800px|center|sans_cadre]]


====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"

====Ligne de commande avec profil de conversion====


<u>Profil de conversion utilisé</u> : 

 <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>


Exécuter la commande suivante :

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