# Signing Data on the Server

# Description

An accounting Web application (`youraccounting.safelayer.com`) lets the user sign accounting entries made during a given period of time (e.g., a month) so that the period remains closed and cannot be modified. To do this, the Web application calculates the hash (SHA-256) of the entries made during this period after ordering them chronologically and using the TRIDENT's digital signature API to obtain the digital signature (PKCS #1) of these entries based on the hash. The application saves the signature obtained in a repository of evidences that contains the signatures of all the closed accounting periods.

The Web application was registered in the TRIDENT as an OAuth 2.0 client application, which means it has been associated to an authorization server (`main`), has an identifier (`youraccounting`) and shares a secret with the platform (`secret`). The `https://youraccounting.safelayer.com/oauth/callback` was registered as the portal's only redirect URL.

The digital signature is requested by a Web application on behalf of a user (`john.doe`) who accesses the application from any browser and who has logged in after authenticating in a TRIDENT's identity provider via password. We are assuming that the signature keys of the user are in one of a TRIDENT’s signature provider, i.e., that the signing identity used to sign the accounting entries is a signing identity on server. We also assume that the signing identity has the `accounting` and `sign` labels.

The signature on the data is performed as follows:

1. User is authorized

2. Identity signature is obtained

3. Hash of the data is obtained

4. Signature generated from the data hash

# User Is Authorized

For the accounting entries to be signed, the user must give authorization for the portal to obtain their signing identities and request the signature on their behalf. For the first task, the scope required (`urn:safelayer:eidas:sign:identity:profile`) must be configured in the authorization server so that it does not require any authentication requirement and that the user's authorization is considered implicit. For the second task, the scope required (`urn:safelayer:eidas:sign:identity:use:server`) must be configured in the authorization server so that it requires the user to be reauthenticated by executing a flow that prompts the user for a signature PIN (which is always requested as the flow disables the SSO for this factor) and so that it considers that the user's authorization is implicit in this new authentication.

In all cases, when the user clicks on the button for requesting the signature (e.g., Close period), the Web application responds with the following HTTP redirect response (see the Obtain Authorization operation):

`HTTP/1.1 302 Found`
`Location: https://txeidas.safelayer.com/trustedx-authserver/oauth/main?response_type=code`
`&client_id=youraccounting`
`&redirect_uri=https://youraccounting.safelayer.com/oauth/callback`
`&scope=urn:safelayer:eidas:sign:identity:profile urn:safelayer:eidas:sign:identity:use:server`
`&state=ad6ef6cb500ac218b6560228c5e10515933f166605abe0a90e56de1f0178a6e4`

This causes the browser to send to the TRIDENT the following HTTP request:

`GET /trustedx-authserver/oauth/main?response_type=code`
`&client_id=youraccounting`
`&redirect_uri=https://yourbank.safelayer.com/oauth/callback`
`&scope=urn:safelayer:eidas:sign:identity:profile urn:safelayer:eidas:sign:identity:use:server`
`&state=ad6ef6cb500ac218b6560228c5e10515933f166605abe0a90e56de1f0178a6e4 HTTP/1.1`
`Host: txeidas.safelayer.com:443`

On receiving this request, the TRIDENT authenticates the user by prompting for the signature PIN and, based on this authentication, if successful, it deduces that the user authorizes the website to access their signing identities and request the signature on their behalf. Lastly, the TRIDENT provides the Web application with the code that accredits this authorization and redirects the browser to the URL specified in the authorization request (`https://youraccounting.safelayer.com/oauth/callback`). This redirect causes the browser to send the following HTTP request to the application:

`GET /oauth/callback?code=556a7d490bef05587e390f033b2253a787f0527ca5c27a0de6f037d51c692dcc`
`&state=ad6ef6cb500ac218b6560228c5e10515933f166605abe0a90e56de1f0178a6e4 HTTP/1.1`
`Host: youraccounting.safelayer.com:443`

Below, the application uses the code it receives from the browser to request the corresponding access token (see the Obtain Access Token operation):

`POST /trustedx-authserver/oauth/main/token HTTP/1.1`
`Host: txeidas.safelayer.com:443`
`Authorization: Basic eW91cmFjY291bnRpbmc6c2VjcmV0`
`Content-Type: application/x-www-form-urlencoded; charset=UTF-8`
``
`grant_type=authorization_code&code=556a7d490bef05587e390f033b2253a787f0527ca5c27a0de6f037d51c692dcc`

Token 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" : "3ee106df8096ab0893aaec66366d7774b1c87a33ddbd12d81335fa5386ef4e33"`
`"token_type" : "bearer",`
`"expires_in" : 120`
`}`

# Identity Signature Is Obtained

To determine which signing identity must be used to sign the accounting period, the Web application asks TRIDENT to provide it with all the signing identities of the `john.doe` user that have the `accounting` and `sign` labels. To do this it performs the following HTTP request (see the Obtain User Signing Identities operation):

`GET /trustedx-resources/esigp/v1/sign_identities?labels=accounting,sign`
`Host: txeidas.safelayer.com:443 HTTP/1.1`
`Authorization: Bearer 3ee106df8096ab0893aaec66366d7774b1c87a33ddbd12d81335fa5386ef4e33`

Note that the application does not have to specify in the request that the signing identities must belong to the `john.doe` user because the TRIDENT deduces this from the authorization token included in the request (i.e., the system knows which user granted the associated authorization token).

We also assume there is only one such signing identity, and the Web application receives the following response:

`HTTP/1.1 200 OK`
`Content-Type: application/json;charset=UTF-8`
`{`
`"sign_identities" : [ {`
`"id" : "12345678",`
`"self" : "https://txeidas.safelayer.com:443/sign_identities/12345678",`
`"description" : "Accounting Signing Identity"`
`"labels" : [`
`"accounting", "sign"`
`],`
`"type" : "pki:x509",`
`"domain: "main",`
`"access" : [ {`
`"user_id" : "john.doe"`
`}],`
`}]`
`}`

Where you can see that 12345678 is the identifier of the only signing identity that the `john.doe` user has access to and that it also has the `accounting` and `sign` labels. In general, the Web application must manage both the case where no signing identity can be found that meets the query criteria and also when more than one meets the criteria.

# Hash of the Data Is Obtained

Because the signature operation on server is done using the hash of the data to be signed, the Web application must obtain the hash (SHA-256) of the accounting records to be signed. The TRIDENT system establishes no restriction on how this hash must be obtained. It is normally calculated using the library or framework functions for this purpose.

Let's assume that the base64 encoding of the hash of the accounting entries to be signed is `BzfaFfN6dxMHRNZDc78NCTzOfn8Fge2R1pzZJeVrytQ=.`

# Signature Generated from the Data Hash

Once the Web application has obtained the hash of the accounting entries to be signed and knows the signing identity to be used, it requests that the signature be generated by sending the following HTTP message (see the Create a Digital Signature on the Server operation):

`POST /trustedx-resources/esigp/v1/signatures/server/raw HTTP/1.1`
`Host: txeidas.safelayer.com:443`
`Authorization: Bearer 3ee106df8096ab0893aaec66366d7774b1c87a33ddbd12d81335fa5386ef4e33`
`Content-Type: application/json`
`{`
`"digest_value" : "BzfaFfN6dxMHRNZDc78NCTzOfn8Fge2R1pzZJeVrytQ=",`
`"signature_algorithm" : "rsa-sha256",`
`"sign_identity_id" : "12345678"`
`}`

Lastly, the TRIDENT system responds to the above request with an HTTP response message whose body contains the binary value of the requested signature (for the sake of readability, this value is represented as `{pkcs#1}`):

`HTTP/1.1 200 OK`
`Content-Type: application/octet-string`
`{pkcs#1}`