# Signature Creation Process

# URI

`/trustedx-resources/esigp/v1/signatures/{signature_id}`

# Description

Resource containing information on a signature creation process performed with a mobile device.

# Representation

A signature creation process is represented in JSON as follows:

`{`
`"id" : {string},`
`"self" : {string},`
`"input" : {InputData},`
`"operation_type" : {string},`
`"creation_time" : {string},`
`"sign_identity_selectors" : [ {`
`"labels" : [ {string} ],`
`"device_id" : {string},`
`"type" : {string},`
`"details" : {SignIdentitySelectorDetails}`
`} ],`
`"device_configuration_url" : {string},`
`"domain" : {string},`
`"service" : {`
`"id" : {string},`
`"name" : {string},`
`"domain" : {string}`
`},`
`"result" : {`
`"status" : {string},`
`"value" : {string},`
`"signature_algorithm" : {string},`
`"sign_identity" : {SignIdentity},`
`"device_type" : {DeviceType}`
`},`
`"links" : {`
`"finish" : {string},`
`"fail" : {string},`
`"cancel" : {string}`
`}`
`}`

Property | Description
`id` | Identifier of the signature creation process.
`self` | Access URL for the resource.
`input` | Information on the data being signed. See `input` Property.
`operation_type` | Type of signature created by the process: Raw signature: `sign:raw` Signature on a transaction: `sign:commitment:transaction` Signature on a document: `sign:commitment:document` Authentication signature on a user: `authentication`
`creation_time` | Time the process started expressed in the `date-time` format of RFC 3339.
`domain` | Domain of the signing user.
`sign_identity_selectors[]` | Signing identity selectors. The signing identity used to create the signature must meet the conditions of one of the specified selectors.
`sign_identity_selectors[].labels[]` | Labels that the signing identity must have according to a selector.
`sign_identity_selectors[].details` | This property is optional and contains conditions that the signing identity must meet for a given selector and that are only applicable to the signing identities of a given type. See the `sign_identity_selectors[].details` property.
`sign_identity_selectors[].type` | This property is optional (required if the `sign_identity_selectors[].details` property is present) and contains the type that the signing identity must be according to a selector.
`sign_identity_selectors[].device_id` | This property is optional (required if the `sign_identity_selectors[].details` property is present) and contains the identifier of the device in which, according to the selector, the private part of the keys associated to the signing identity must be.
`device_configuration_url` | Template of the URL at which the device can access configuration data specific to creating signatures (e.g., the signature policy).
`service` | Service that requests the creation of a signature.
`service.id` | Identifier of the service.
`service.name` | Name of the service.
`service.domain` | Domain of the service.
`result` | Result of the signature creation process. This property only exists in finalized signature creation processes.
`result.status` | Status of the finalized signature creation process (`finished`, `failed` or `canceled`): `finished`: The process has finalized after having successfully created the signature. `failed`: The process has terminated without being able to create the signature because an error occurred. `canceled`: The process terminated without a signature having been created because it was canceled.
`result.value` | Value returned by the signature creation process. This value depends on the final status of the process: If the process ended with the `finished` status: the signature created encoded in base64. If the process ended with the `failed` status: information on the error that occurred (there may not be any information). If the process ended with the `canceled` status: information on the cancellation that occurred (there may not be any information).
`result.signature_algorithm` | Signature algorithm used in the process (`rsa-sha1`, `rsa-sha256`, `rsa-sha384`, `rsa-sha512`,`ecdsa-sha1`,`ecdsa-sha256`,`ecdsa-sha384` and `ecdsa-sha512`).
`result.sign_identity` | Signing Identity used (applied) in the process.
`result.device_type` | Information on the type of device used in the process. This property only exists in signature creation processes that end successfully (`finished`). See the `result.device_type` property.
`links` | URLs for ending the signature process. Only devices containing the signing identities selected by the selectors can access these URLs.
`links.finish` | URL for finalizing the signature process and putting the value of the signature generated in `result.value` and the value `finished` in `result.status`.
`links.fail` | URL for ending the signature process and putting the error information in `result.value` and the value `failed` in `result.status`.
`links.cancel` | URL for ending the signature process and putting the cancellation information in `result.value` and the value `canceled` in `result.status`. URL for ending the process in the `failed` status. URL that responds to the `PUT` verb. The body will optionally contain error information.

## input Property

The representation of the `input` property depends on the type of signature being created.

### Document Signature

When a signature is created on a document, the `input` property is represented as follows:

`{`
`"service" : {`
`"id" : {string},`
`"name" : {string},`
`"domain" : {string}`
`},`
`"digest_url" : {string},`
`"digest_value" : {string},`
`"digest_algorithm" : {string},`
`"document_url" : {string},`
`"document_alias" : {string},`
`"root_certs" : [ {string} ],`
`"document_info" : {`
`"html" : {string}`
`}`
`}`

Property | Description
`service` | Client application requesting the creation of a signature.
`service.id` | Identifier of the client application.
`service.name` | Name of the client application.
`service.domain` | Domain of the client application.
`digest_url` | URL for obtaining the hash to be signed encoded in base64 and the hash algorithm used.
`digest_value` | Hash of the document to be signed encoded in base64.
`digest_algorithm` | Algorithm used to calculate the hash of the document (`sha1`, `sha256`, `sha384` and `sha512)`.
`document_url` | URL of the document to be signed.
`document_alias` | Alias of the document to be signed.
`root_certs` | Certificates encoded in base64 of the certification paths of the `digest_url` and `document_url` TLS servers.
`document_info` | Additional information on the document to be signed.
`document_info.html` | HTML encoded in base64 with the information displayed to the user on the document to be signed.

### Transaction Signature

When a signature is to be created on a transaction, the `input` property is represented as follows:

`{`
`"service" : {`
`"id" : {string},`
`"name" : {string},`
`"domain" : {string}`
`},`
`"data" : {string},`
`"digest_algorithm" : {string}`
`}`

Property | Description
`service` | Client application requesting the confirmation of the transaction.
`service.id` | Identifier of the client application.
`service.name` | Name of the client application.
`service.domain` | Domain of the client application.
`data` | HTML displayed to the user to prompt them to confirm the transaction that contains data on the transaction.
`digest_algorithm` | This property is optional and contains the hash algorithm for creating the signature (`sha1`, `sha256`, `sha384` and `sha512)`. If it is not present, the algorithm used will depend on the type of device with which the signature is created.

### Basic Signature

When a basic signature is to be created on data, the `input` property is represented as follows:

`{`
`"service" : {`
`"id" : {string},`
`"name" : {string},`
`"domain" : {string}`
`},`
`"digest_url" : {string},`
`"digest_value" : {string},`
`"digest_algorithm" : {string},`
`"data_info" : {`
`"html" : {string}`
`},`
`"root_certs" : [ {string} ]`
`}`

Property | Description
`service` | Client application requesting the creation of a signature.
`service.id` | Identifier of the client application.
`service.name` | Name of the client application.
`service.domain` | Domain of the client application.
`digest_url` | URL for obtaining the hash to be signed encoded in base64 and the hash algorithm used.
`digest_value` | Hash of the data to be signed encoded in base64.
`digest_algorithm` | Algorithm used to calculate the hash of the data (sha1, sha256, sha384 and sha512).
`data_info` | Information on the data to be signed.
`data_info.html` | HTML encoded in base64 with the information displayed to the user on the data to be signed.
`root_certs` | Certificates encoded in base64 of the certification paths of the digest_url TLS server.

## sign_identity_selectors[].details Property

The `sign_identity_selectors[].details` property contains criteria for selecting signing identities that are only applicable to the signing identities of a given type. Therefore, its representation depends on the signing identity type on which the selection is to be made.

### pki:x509 type signing identity.

When a `pki_x509` type signing identity is selected, the `sign_identity_selectors[].details` property is represented as follows:

`{`
`"certificate" : "<certificate base64 encoded>"`
`}`

Property | Description
`certificate` | Certificate associated to a signing identity encoded in base64.

## result.device_type Property

The `result.device_type` property contains information on the type of device used in the process and is represented as follows:

`{`
`"id" : {string},`
`"notifications_service_id" : {string},`
`"wakeup_uri_scheme" : {string},`
`"verification_policy" : {string},`
`"application" : {`
`"id" : {string},`
`"version" : {string}`
`},`
`"server_configuration" : {...}`
`}`

Property | Description
`id` | Identifier of the device type.
`notifications_service_id` | Identifier of the notification service used by this type of device.
`wakeup_uri_scheme` | URL scheme that opens the signature application (Mobile ID) in this type of device.
`verification_policy` | Identifier of the verification policy used to validate the authentication signatures and transactions created with this type of device.
`application` | Information on the signature application (Mobile ID) installed in this type of device.
`application.id` | Identifier on the signature application (Mobile ID) installed in this type of device.
`version` | Version on the signature application (Mobile ID) installed in this type of device.
`server_configuration` | Additional configuration of this type of device registered in the server.

# Operations

- Create a Process for Generating a Digital Signature on a Document with a Device

- Create a Process for Signing a Transaction with a Device

- Create a Process for Generating a Digital Signature on Data with a Device

- Obtain the Result of a Signature Creation Process

- Delete a Signature Creation Process