# Obtain the Hash of the Document in Accordance with a Signature Definition

# Alias

`DocumentSignerToBeSignedCalculation`

# Description

Obtains the hash of a document according to a signature definition and modifies it with the information on the hash (the `to_be_signed` property). Optionally, the parameters in the signature definition can be modified before obtaining the hash. Currently, only the following modifications can be performed:

- Provide (or substitute) the signer's certificate, leaving all the other parameters that the signature already has, i.e., provide the value of the `parameters.certificate` property of the signature definition.

- Provide the parameters of the signature definition, completely replacing (where appropriate) the already defined parameters, i.e., provide the value of the `parameters` property of the signature definition.

Important

After obtaining the hash of a document from a signature definition, this definition can only be updated to provide it the digital signature that corresponds to the hash obtained. If a document and signature definitions resource contains several signature definitions, between the obtaining of the hash and the update that provides the digital signature to signature definition, the obtaining of the hash and the update that provides the digital signature cannot be performed for a different signature definition.

## Behavior for When Parameters Are Missing from the Signature Definition

Although it is possible to create a signature definition without the `parameters` property, this property is required for calculating the hash of the data to be signed. Thus, if the signature definition lacks the `parameters` property when this operation is executed, it should be provided in the request body.

We distinguish between when the signature definition is for a PAdES signature from when it is for an XMLDSig/XAdES signature.

### Missing Parameters in the Definition of a PAdES Signature

When this operation is executed on a signature definition applied to a PDF document, the data structures required for containing the information on this signature (principally, the signature dictionary) is created in the PDF document (and are initialized). If at this time the signature definition is missing any `parameters` properties, the structures are informed as set out for an ETSI PAdES-Basic signature (ETSI TS 102 778-2) that has no appearance and for which the SHA-256 algorithm is used to obtain it. These structures are also informed that the signature is an ordinary one (not a certification signature), and 12,228 bytes is reserved (in the signature dictionary) for inserting the electronic signature itself.

If, however, the signature definition contains parameters (i.e., it has the `parameters` property), the data structures of the PDF are informed without taking into account the optional parameters not present, except in the following cases:

- If the `estimated_signature_size` property is not present, the value 12,288 is taken by default.

- If the `certification_level` property is not present, the value 0 is taken by default. As a result, the signature is ordinary (not a certification signature).

- If the `appearance.signature_details` property is present but the `appearance.signature_details.font.style` property is not, the value `"normal"` is taken by default. As a result, the font style used in the signature appearance will be normal.

- If the `appearance.signature_details` property is present but the `appearance.signature_details.font.color` property is not, the value `{r=0; g=0; b=0}` is taken by default. As a result, the color of the font used in the signature appearance will be black.

- If the `appearance.signature_details` property is present but the `appearance.signature_details.font.encoding` property is not, the value `"latin1"` is taken by default. As a result, the code of the characters used in the signature appearance will be ISO-8859-1 (Latin 1).

- If the `appearance.signature_details` property is present but the `appearance.signature_details.font.embed` property is not, the value `true` is taken by default. As a result, the font used in the signature appearance will be included in the PDF document.

- If the `appearance.signature_details` is present, one of the elements of the `appearance.signature_details.details[]` array is of the `date` type and the signature definition does not specify the `timezone` property for this element, the timezone of the TRIDENT platform is taken by default.

- If the `appearance.signature_details` is present, one of the elements of the `appearance.signature_details.details[]` array is of the `date` type and the signature definition does not specify the `format` property for this element, the `"yyyy.MM.dd hh:mm:ss XXX"` value is taken by default.

### Missing Parameters in the Definition of an XMLDSig/XAdES Signature

When this operation is executed on a signature definition for an XMLDSig/XAdES signature, whether certain `parameters` properties are required and the default values any optional properties take depend on the position of the signature with respect to the signed data specified by the required `signature_target.signature_packaging` property.

- If the signature definition is for a detached signature and only the `type` property (which is required) is present, an externally detached signature is generated on the document (of any type) to which the signature definition is applied. The signature is applied to a different document and will reference the signed document with a URL with the `"file:///<docname>"` format, where `<docname>` is the name of the document in question.

- If the signature definition corresponds to an enveloped signature and only the `type` property (which is required) is present, a signature is generated on the XML document to which the signature definition is applied, and the signature is added to this document as the last child node of the root node.

- If the signature definition is for a enveloping signature, an enveloping XML signature is generated that contains the signed document encoded in base64.

# Request

`PUT /trustedx-resources/esignsp/v2/documents/{doc_and_sigdefs_id}/signers/{signature_definition_id}/to_be_signed`

## Parameters

Name | Type | Usage | Description
`doc_and_sigdefs_id` | path | Required | Identifier of the document and signature definitions resource that contains the signature definition applied to obtain the hash.
`signature_definition_id` | path | Required | Identifier of the signature definition applied to obtain the hash.

## Authorization

The request must contain a bearer access token generated by an authorization server of the platform. This token must have a scope that includes the `urn:safelayer:eidas:sign:process:document` value and must be used as explained in RFC 6750. Basically, the access token must be included in an `Authorization` header as follows:

`Authorization: Bearer <token>`

The client application must obtain the required access token via a client credentials grant OAuth 2.0 interaction with the platform.

## Content-Type Header

For the case of modifying the signature definition to be applied (e.g., to send the signer's certificate) before the hash is obtained, the request must include the following `Content-Type` header:

`Content-Type: application/json`

## Body

For the case of modifying the signature definition to be applied (e.g., to send the signer's certificate), the body of the request must include the following JSON object:

`{`
`"parameters" : {Parameters}`
`}`

Property | Usage | Description
`parameters` | Required if the request has a body. | Characteristics for extending or changing what is established by the signature policy of the signature definition.

# Response

## Status-Line

Value | Description
`HTTP/1.1 200 OK` | The calculation of the hash was performed correctly and its data is in the body of the response.
`HTTP/1.1 409 Conflict` | An attempt was made to obtain the hash using a signature definition that had already been used for obtaining the hash of the document to which it will be applied. I.e., an attempt was made to obtain the same hash a second time.
Others | See HTTP Response Status for all the possible cases.

## Content-Type Header

`Content-Type: application/json`

## Body

If the hash is successfully calculated, the body contains the following JSON object:

`{`
`"type" : "x509",`
`"digest_algorithm" : {string},`
`"digest_value" : {string}`
`}`

Property | Description
`type` | Always has the `"x509"` value.
`digest_algorithm` | Hash algorithm. The value of this property can be `sha1`, `sha256`, `sha384` or `sha512.`
`digest_value` | Hash of the document and the attributes signed according to the signature definition.