# Signing a PDF document with external generation of the PKCS #1

# Description

In this example, the TRIDENT's document signature API is used to sign a PDF document using a digital signature (PKCS #1) generated by a system other than the TRIDENT platform that performs the signature. This situation occurs in all deployments in which, for reasons of confidentiality, the digital signature provider cannot access the documents that it signs (e.g., because it is located in another organization).

The PDF signature is requested by an application registered in the TRIDENT (`txeidas.safelayer.com`) as an OAuth 2.0 client application, which means it has an identifier (`docsign_orchestrator`) and shares a secret with the platform (`demodemo`). Furthermore, this application is associated to an authorization server (`esignsp`) capable of issuing access tokens that will allow the application to perform the document signature operations. I.e., the application is associated to an authorization server that recognizes the `urn:safelayer:eidas:sign:process:document` scope and supports client credentials grant flows. The PDF document is signed in six steps:

1. Obtaining the token for accessing the signature operations

2. Creating the document and signature definitions resource

3. Obtaining the hash of the document

4. Obtaining the digital signature of the document

5. Inserting the digital signature in the document.

6. Obtaining the signed document

Lastly, after the signature is performed, the document and signature definitions resource used is deleted.

# Obtaining the Token for Accessing the Signature Operations

Firstly, the `docsign_orchestrator` application sends the following message to the TRIDENT to obtain the access token for accessing the PDF document signing operations (see the Obtain a Token operation):

`POST /trustedx-authserver/oauth/main/token HTTP/1.1`
`Host: txeidas.safelayer.com:443`
`Authorization: Basic ZG9jc2lnbl9vcmNoZXN0cmF0b3I6ZGVtb2RlbW8=`
`Content-Type: application/x-www-form-urlencoded`
``
`grant_type=client_credentials&scope=urn%3Asafelayer%3Aeidas%3Asign%3Aprocess%3Adocument`

Note that the application must use its identifier and the secret it shares with the TRIDENT to authenticate in accordance with the HTTP basic authentication scheme (RFC 2617). Also note that the application specifies that its authentication also demonstrates having the right to obtain the access token requested (`grant_type=client_credentials`).

The access token is finally obtained in the following HTTP response:

`HTTP/1.1 200 OK`
`Content-Type: application/json;charset=utf-8`
`Cache-Control: no-store, no-cache, must-revalidate`
`Pragma: no-cache`
``
`{`
`"access_token" : "da19ef9bf6da15ddae5ce16e60074456559066d69e8b984c0e01b6562673f9fd"`
`"token_type" : "bearer",`
`"expires_in" : 300`
`}`

This token must be included in the `Authorization` header of all request messages subsequently sent to the TRIDENT for signing the PDF document in accordance with RFC 6750.

# Creating the Document and Signature Definitions Resource

The `docsign_orchestrator` application requests the creation of a document and signature definitions resource by sending the following message to the TRIDENT's signature services provider (see the create a document and signature definitions resource operation and note that, for the sake of readability, the binary content of the PDF document has been replaced with `{pdfToBeSigned}`).

`POST /trustedx-resources/esignsp/v2/documents HTTP/1.1`
`Authorization: Bearer da19ef9bf6da15ddae5ce16e60074456559066d69e8b984c0e01b6562673f9fd`
`Host: txeidas.safelayer.com:443`
`Content-Type: multipart/form-data; boundary=docsign9f4ed55adae18f76`
``
`--docsign9f4ed55adae18f76`
`Content-Disposition: form-data; name="signers"`
`Content-Type: application/json`
``
`[{`
`"signature_policy_id": "urn:safelayer:eidas:policies:sign:document:pdf",`
`"parameters": {`
`"type": "pades-bes",`
`"default_digest_algorithm": "sha256",`
`"location": "Madrid, Spain",`
`"signature_field": {`
`"location": {`
`"page": {`
`"number": "last"`
`},`
`"rectangle": {`
`"x": 100,`
`"y": 100,`
`"height": 150,`
`"width": 200`
`}`
`},`
`"appearance": {`
`"background_image": {`
`"binary": "/9j/4AAQ...iigD/2Q=="`
`},`
`"signature_details": {`
`"details": [{`
`"type": "subject",`
`"title": "Signer: "`
`}, {`
`"type": "date",`
`"title": "Date: "`
`}]`
`}`
`}`
`}`
`}`
`}]`
`--docsign9f4ed55adae18f76`
`Content-Disposition: form-data; name="document";`
`Content-Type: application/pdf`
`Content-Transfer-Encoding: binary`
``
`{pdfToBeSigned}`
`--docsign9f4ed55adae18f76--`

In the above message you can see that:

- Only one signature definition is provided (i.e., the document is to be signed only once).

- A PAdES-BES (`parameters.type = "pades-bes"`) signature is to be performed, and the SHA-256 hash algorithm (`parameters.default_digest_algorithm = "sha256"`) is to be used for calculating the digital signature.

- The signature has an appearance (`parameters.signature_field.``appearance`) and is located on the last page of the document (`parameters.signature_field.location.page.number = "last"`).

- The signature appearance comprises an image with text to the right: the distinguished name of the signer and the date and time the signature was made `(parameters.signature_field.appearance.signature_details.details[0].type = "subject"`, `parameters.signature_field.appearance.signature_details.details[1].type = "location"` and `parameters.signature_field.appearance.signature_details.details[2].type = "date"`).

- Madrid, Spain is indicated as the place where the signature was generated (`parameters.location =` `"Madrid, Spain"`).

If the request is successfully processed, the TRIDENT creates the document and signature definitions resource requested and responds to the application with the following HTTP message:

`HTTP/1.1 201 Created`
`Location: https://txeidas.safelayer.com/trustedx-resources/esignsp/v2/documents/dc_11dbed1a0e9f0cc1`
`Content-Type: application/json`
``
`{`
`"id" : "dc_11dbed1a0e9f0cc1",`
`"self" : "https://txeidas.safelayer.com/trustedx-resources/esignsp/v2/documents/dc_11dbed1a0e9f0cc1",`
`"signers": [`
`{`
`"id" : "sd_f9c2d467a2bf72c7",`
`"self" : "https://txeidas.safelayer.com/trustedx-resources/esignsp/v2/documents/dc_11dbed1a0e9f0cc1/signers/sd_f9c2d467a2bf72c7"`
`}`
`]`
`}`

Where the document and signature definitions resource created has the identifier `dc_11dbed1a0e9f0cc` and contains, in addition to the document to be signed, the signature definition with the identifier `sd_f9c2d467a2bf72c7`.

# Obtaining the Hash of the Document

The `docsign_orchestrator` obtains the hash of the document to be signed prior to the obtaining of the digital signature to be applied to it. To do this, it sends the following message to the TRIDENT's signature services provider that includes the signer's certificate (see the obtain the hash of the document in accordance with a signature definition operation). This is because a PAdES-BES signature is to be performed, which requires including the signer's certificate among the attributes signed along with the content of the PDF document itself.

`PUT /trustedx-resources/esignsp/v2/documents/dc_11dbed1a0e9f0cc1/signers/sd_f9c2d467a2bf72c7/to_be_signed HTTP/1.1`
`Authorization: Bearer da19ef9bf6da15ddae5ce16e60074456559066d69e8b984c0e01b6562673f9fd`
`Host: txeidas.safelayer.com:443`
`Content-Type: application/json`
``
`{`
`"parameters" : {`
`"type": "x509",`
`"certificate" : "MIIF...hP2A"`
`}`
`}`

TRIDENT calculates the SHA-256 hash of the PDF document (and of the attributes to be signed with it) and responds with the following message:

`HTTP/1.1 200 OK`
`Content-Type: application/json`
``
`{`
`"type" : "x509",`
`"digest_algorithm" : "sha256",`
`"digest_value" : "NDky...cwNQ=="`
`}`

# Obtaining the Digital Signature of the Document

Once the hash of the document has been obtained, the `signdoc_orchestrator` requests that a digital signature provider separate from the TRIDENT platform generate the digital signature on the document to be signed. To do this, the `signdoc_orchestrator` application must provide to the digital signature provider the hash of the document obtained in the previous step ( `NDky...cwNQ==` ) and also indicate to it which signature key must be used for generating the signature. This last step is certain to require the intervention of the user, not only for selecting the key but also for authorizing its use for generating the digital signature. In all cases, both this interaction with the user and the interaction with the digital signature provider for obtaining the PKCS #1 signature takes place outside of the TRIDENT.

# Inserting the Digital Signature in the Document

After obtaining the digital signature of the PDF document, the application inserts it in the document by sending the following message to the TRIDENT's signature services provider (see the updating a signature definition operation):

`PATCH /trustedx-resources/esignsp/v2/documents/dc_11dbed1a0e9f0cc1/signers/sd_f9c2d467a2bf72c7 HTTP/1.1`
`Authorization: Bearer da19ef9bf6da15ddae5ce16e60074456559066d69e8b984c0e01b6562673f9fd`
`Host: txeidas.safelayer.com:443`
`Content-Type: application/json`
``
`{`
`"signature" : "NGVm...AyMQ=="`
`}`

To which TRIDENT responds with the following message:

`HTTP/1.1 204 No content`

# Obtaining the Signed Document

After receiving the above message, the application sends the following message to the TRIDENT's signature services provider to obtain the signed PDF document (see the obtain a document operation):

`GET /trustedx-resources/esignsp/v2/documents/dc_11dbed1a0e9f0cc1/content HTTP/1.1`
`Authorization: Bearer da19ef9bf6da15ddae5ce16e60074456559066d69e8b984c0e01b6562673f9fd`
`Host: txeidas.safelayer.com:443`

Note that the URL of the document requested is created by adding `/content` to the URL specified in the response received when the document and signature definitions resource was created (the `Location` header of the response, the `self` property of the JSON object contained in the response).

Lastly, the application receives the signed document in the following HTTP response message (note that, for the sake of readability, `{pdfSigned}` replaces the binary content of the signed PDF).

`HTTP/1.1 200 OK`
`Content-Type: application/pdf`
``
`{pdfSigned}`

# Deleting the Document and Signature Definitions Resource

After receiving the signed PDF document, the application sends the following message to the TRIDENT's signature services provider to delete the document and signature definitions resource used (see the delete a document and signature definitions resource operation):

`DELETE /trustedx-resources/esignsp/v2/documents/dc_11dbed1a0e9f0cc1 HTTP/1.1`
`Authorization: Bearer da19ef9bf6da15ddae5ce16e60074456559066d69e8b984c0e01b6562673f9fd`
`Host: txeidas.safelayer.com:443`

TRIDENT deletes the resource specified in the request and responds with the following message:

`HTTP/1.1 204 No content`