# Generate digital signatures from hashes

# Alias

`CscSignaturesSignHash`

# Description

Generates one or more digital signatures (i.e., an individual signature or a batch of signatures) from the hashes of the data to be signed, using the signing key corresponding to a given signature credential.

# Request

To generate one or more signatures from the hashes of the data to be signed, the client application must send the following request to the TRIDENT:

`POST /trustedx-resources/csc/v2/signatures/signHash`
Important

[CSC_STANDARD_V2] requires that the base path of all requests of the access API to a remote signature services provider be `/csc/v2/`. Thus, if the TRIDENT administrator decides to follow the standard strictly, they must deploy the system so that the base path of the request is `/csc/v2` instead of`/trustedx-resources/csc/v2`. To determine if this is the case in your situation, check the "`oauth2`" property of the JSON object provided by the Obtain information on the CSC signature service operation.

## Content-Type Header

`Content-Type: application/json`

## Request Parameters

Name | Type | Usage | Description
`credentialID` | String | Required | Identifier of the signature credential associated with the signing key with which the signatures will be generated.
`SAD` | String | Conditionally Required | The access token with which the application demonstrates the user granted authorization for signing the data corresponding to the hashes specified in the `hashes` parameter with the key referred to in the `credentialID` parameter. This access token must have `credential` scope and be obtained in an Authorization Code Grant OAuth 2.0 authorization flow. It is unnecessary if one access token like this is in the HTTP Authorization header.
`hashes` | String Array | Required | List of hashes (encoded in base64) of the data to be signed. The number of hashes in the list must be equal to or less than the value of the `numSignatures` parameter used to obtain the authorization demonstrated by the token contained in the `SAD` parameter or in the `Authorization` header.
`hashAlgorithmOID` | Boolean | Conditionally Required | Identifier (OID) of the algorithm with which the hashes were generated based on which the signatures will be generated. This parameter is only necessary when the algorithm is not implicit in the algorithm specified in the `signAlgo` parameter (i.e. when this algorithm is RSA encryption).
`signAlgo` | String | Required | Identifier (OID) of the algorithm that must be used to generate the signatures. It must be one of the following values, provided that the signature credential allows it (see the `keyAlgo` parameter of the response of the Obtain a signature credential of a user operation) "`1.2.840.113549.1.1.1`": RSA encryption "`1.2.840.113549.1.1.11`": sha256WithRSAEncryption "`1.2.840.113549.1.1.12`": sha384WithRSAEncryption "`1.2.840.113549.1.1.13`": sha512WithRSAEncryption "`1.2.840.10045.4.3.2`": sha 256WithECDSA " `1.2.840.10045.4.3.3`": sha384 WithECDSA " `1.2.840.10045.4.3.4`": sha512 WithECDSA

## Authorization

This operation can be authorized by including one or two access tokens in the request.

### Authorization with one access token

The request must contain a bearer access token with the `credential` scope in the Authorization header. This token can only be obtained via an OAuth 2.0 Authorization Code Grant flow and must be bound to the signing key to be used (through the `credentialID` parameter) and to the data to be signed (through the `hashes` parameter). In addition, the `SAD` parameter must not be used.

### Authorization with two access tokens

The request must contain two OAuth 2.0 access tokens:

- An access token with the `service` scope in the Authorization header. As a rule, this token can be obtained as much via an OAuth 2.0 Authorization Code Grant flow as an OAuth 2.0 Client Credentials Grant flow. Find out from the TRIDENT administrator if this is the case in your situation or if the access token can only be obtained via a particular type of OAuth 2.0 flow.

- An access token with the `credential` scope as the SAD parameter's value. This token can only be obtained via an OAuth 2.0 Authorization Code Grant flow and must be bound to the signing key to be used (through the `credentialID` parameter) and to the data to be signed (through the `hashes` parameter).

In both cases, the token in the header must be put as explained in RFC 6750. I.e., as follows:

`Authorization: Bearer <token>`

# Response

## Status-Line

If the digital signatures are successfully generated, the HTTP response contains the following `Status-Line`:

`HTTP/1.1 200 OK`

## Content-Type Header

`Content-Type: application/json;charset=UTF-8`

## Body

JSON object containing the digital signatures requested in the same order in which the hashes were provided in the request.

`{`
`"signatures": [{string}]`
`}`

Property | Type | Description
`signatures` | String Array | List (batch) of digital signatures that were generated. The signatures are provided in the same order in which the hashes used for the generation were given in the request. Each signature is a PKCS #1 encoded in base64.

# Error Management

If the request does not contain the `Authorization: Bearer` header, the TRIDENT returns an HTTP response with the 401 Unauthorized `Status Code`.

If the request is not successfully processed, the TRIDENT returns an HTTP error response with the `Content-Type: application/json;charset=utf-8` header and a JSON object in the body with the following properties:

- `error`: Error code.

- `error_description`: Additional description of the error. Not required.

Error case | Status Code (HTTP) | error | error_description
The `SAD` parameter was not included in the request or its value is not a string | 400 Bad Request | `invalid_request` | `invalidParameter`
The `SAD` parameter of the request is invalid | 400 Bad Request | `invalid_request` | `invalidSAD`
The `credentialID` parameter was not included in the request, or its value is not a string. | 400 Bad Request | `invalid_request` | `invalidParameter`
The `credentialID` parameter of the request is invalid | 400 Bad Request | `invalid_request` | `invalidCredentialID`
The `hashes` parameter was not included in the request, or its value is not a string array. | 400 Bad Request | `invalid_request` | `invalidParameter`
The value of the `hashes` parameter is an empty array (it does not contain any element). | 400 Bad Request | `invalid_request` | `invalidParameter`
The base64 encoding of one of the hashes in the list of hashes of the `hashes` parameter of the request is invalid. | 400 Bad Request | `JsonMappingException` |
One or more of the hashes in the list of hashes of the `hashes` parameter is not authorized by the SAD token included in the `SAD` parameter of the request. | 400 Bad Request | `invalid_request` | `invalidSAD`
The `signAlgo` parameter was not included in the request, or its value is not a string. | 400 Bad Request | `invalid_request` | `invalidParameter`
The `hashAlgorithmOID` parameter was not included in the request, or its value is not a string, and the value of the `signAlgo` parameter of the request is “`1.2.840.113549.1.1.1`” (RSA encryption). | 400 Bad Request | `invalid_request` | `invalidDigestAlgorithm`
The `hashAlgorithmOID` parameter of the request is invalid. | 400 Bad Request | `invalid_request` | `invalidDigestAlgorithm`
The `signAlgo` parameter of the request is invalid. | 400 Bad Request | `invalid_request` | `invalidSignatureAlgorithm`
The length of one of the hashes in the list of hashes of the `hashes` parameter is wrong. | 400 Bad Request | `invalid_request` | `invalidHashLength`
The SAD token included in the `SAD` parameter of the request is expired. | 400 Bad Request | `invalid_request` | `invalidSAD`
The `credentialID` parameter of the request corresponds to an expired signature credential. | 400 Bad Request | `invalid_request` | `expiredCredential`
The `credentialID` parameter of the request corresponds to a disabled signature credential | 403 Forbidden | `DisabledSignIdentityException` |

# Example

## Request

The signature application requests the generation of the digital signature of the data corresponding to the "TMkLHG9F5EE1X3YxkimehiuRDV9RcepZnKZ1dUAlHiQ=" hash (encoded in base64) with the signing key that corresponds to the credential identified by "GX0112348". To do this, it sends the following request to the TRIDENT:

`POST /trustedx-resources/csc/v2/signatures/signHash HTTP/1.1`
`Host: rse.corporation.com`
`Authorization: Bearer 9ade1210b7ac648b49defc577aa258eb2701b2064a14de13842524c2fd59c597`
`Content-Type: application/json`
`{`
`"credentialID": "GX0112348",`
`"hashes": ["TMkLHG9F5EE1X3YxkimehiuRDV9RcepZnKZ1dUAlHiQ="],`
`"signAlgo": "1.2.840.113549.1.1.11"`
`}`

## Response

The TRIDENT generates the digital signature requested and responds to the signature application with the following message:

`HTTP/1.1 200 OK`
`Content-Type: application/json;charset=UTF-8`
`{`
`"signatures":["KegbGQAqNXDR3cTjQ8...EGo7zY8DrCFI="]`
`}`