# Confirming a Transaction with a Mobile Device

# Description

In this example, TRIDENT's digital signature API is used to confirm a transaction with a mobile device. This operation is requested by an e-bank portal (`yourbank.safelayer.com`) on behalf of a user (`john.doe`) who ordered the transfer of funds. The user logged in to the portal after authenticating in TRIDENT with their password and is accessing the website with a desktop.

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

It is assumed that portal users have a mobile device (iOS or Android) with the BlueCard Mobile version of the Mobile ID application installed. We also assume that the editor of this application (BlueCard) is a certification services provider that provides a signature certificate to each user and that both this certificate and the associated signature key are stored on the user's mobile device. Lastly, we also assume that the TRIDENT platform to which `yourbank` accesses was provisioned with the signing identities of the users. Thus, each user has a signing identity registered in TRIDENT corresponding to the signature key they have in their device and that has the following attributes:

- The `yourbank`, `mobile` and `sign` labels.

- The X.509 certificate issued by BlueCard for the signature key.

- The identifier of the mobile device where the signature key is found.

The transaction is confirmed as follows:

1. User Is Authorized

2. Transaction signature request made

3. Wait for signature to be available

4. Transaction signature obtained

5. Signature process deleted

# User Is Authorized

For the transaction to be signed, the user must give authorization for the portal to request the signature on their behalf. In this example, user authorization directly follows their reauthentication (i.e., it is an implicit authorization). This is established by configuration and is owing to the fact that the user will have to enter their PIN in their mobile device for the signature to be generated, which, in itself, constitutes an explicit authorization making the first one unnecessary. Furthermore, user re-authentication does not require the user's intervention as it is performed with the same authentication flow used to create the session in the portal and this flow establishes SSO for the password factor.

In any case, when the user clicks on the button for performing the transaction (Continue), the website 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=yourbank`
`&redirect_uri=https://yourbank.safelayer.com/oauth/callback`
`&scope=urn:safelayer:eidas:sign:identity:use:device`
`&acr_values=urn:safelayer:tws:policies:authentication:flow:basic:password`
`&state=87ea40e838067c99c7635390152f2bee7bfc5630775b811787412108d5d3cae1`

This causes the browser to send to TRIDENT the following HTTP request specifying `urn:safelayer:eidas:sign:identity:use:device` as the scope of the requested authorization:

`GET /trustedx-authserver/oauth/main?response_type=code`
`&client_id=yourbank`
`&redirect_uri=https://yourbank.safelayer.com/oauth/callback`
`&scope=urn:safelayer:eidas:sign:identity:use:device`
`&acr_values=urn:safelayer:tws:policies:authentication:flow:basic:password`
`&state=87ea40e838067c99c7635390152f2bee7bfc5630775b811787412108d5d3cae1 HTTP/1.1`
`Host: txeidas.safelayer.com:443`

On receiving this request, TRIDENT re-authenticates the user transparently (SSO is applied) and, based on this reauthentication, it deduces that the user authorizes the website to request a signature on their behalf. Lastly, TRIDENT provides the website with the code that accredits this authorization and redirects the browser to the URL specified in the authorization request (`https://yourbank.safelayer.com/oauth/callback`). This redirect causes the browser to send the following HTTP request to the website:

`GET /oauth/callback?code=2e448c42af62bdfe2f455c64a2e98f53b5ff512d9b93dd77eaea1a4b3a239390`
`&state=87ea40e838067c99c7635390152f2bee7bfc5630775b811787412108d5d3cae1 HTTP/1.1`
`Host: yourbank.safelayer.com:443`

Next, the website uses the code it receives from the browser to request the corresponding access token (see the Obtain a Token operation):

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

The token finally obtained in the following HTTP request:

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

# Transaction Signature Request Made

The website builds an HTML document with the data of the transaction performed and requests that the TRIDENT prompts the user to sign the document with their mobile device. To do this, it sends the following HTTP message to the TRIDENT's signature generation service (see the Create a Transaction Signature Process with a Device operation). (For the sake of readability, an ellipsis replaces the HTML document.)

`POST /trustedx-resources/esigp/v1/signatures/device/commitment/transaction`
`Host: txeidas.safelayer.com:443`
`Authorization: Bearer ed15d124c0433486949eb1a7894aec7f921ca7a3d010344532844e9a6f1c836d`
`Content-Type: application/json`
`{`
`"input" : {`
`"data" : <html>...</html>`
`},`
`"sign_identities" : [{"labels": ["mobileid"]}],`
`"notify" : true`
`}`

Note that the website demonstrates its authorization for requesting the signing of the transaction by including the access token (`ed15...836d`) in the `Authorization` header. Note also that the portal specifies the signing identity with which the signature must be created by including the `yourbank`, `mobile` and `sign` labels in the request. Therefore, as well as belonging to the `john.doe` user, the signing identity must correspond to a signature key on a mobile device (the `mobile` label), be for signing data (`sign` label) and have been provisioned for use in YourBank (`yourbank` label).

When it receives the above request, TRIDENT creates a signature process and informs the portal of the data on this process via the following HTTP response (for the sake of readability, an ellipsis replaces the JSON object containing the data on the process created):

`HTTP/1.1 201 Created`
`Content-Type: application/json;charset=UTF-8`
`Location: https://txeidas.safelayer.com/trustedx-resources/esigp/v1/signatures/9u0bdhl7679h99glqtun1je0u1`
``
`{`
`"signature" : {...}`
`}`

Note that the `Location` header of the response contains the URL of the signature generation process created. This URL is used later for polling to detect when the signature is available.

The signature creation process starts by notifying the BlueCard Mobile application of the need to generate the signature on the transaction and to display the transaction's data to the user. If after seeing this data the user confirms the transaction, the BlueCard Mobile application prompts them to enter the PIN for the transaction signature to be generated. Lastly, the user enters their PIN and the BlueCard Mobile application generates the XAdES-EPES signature on the HTML document containing the data on the transaction and sends this signature to TRIDENT.

## HTML Document Containing the Transaction Data

The HTML document containing the transaction data that has to be signed is displayed below. As you can see, it is a €200 bank transfer to Entrust without commission fees.

`<html>`
`<head>`
`<meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no" />`
`<style>`
`#title-container {`
`display: table;`
`width: 100%;`
`background-color: #283850;`
`height: 50px;`
`}`
`#title {`
`padding-left: 30px;`
`display: table-cell;`
`vertical-align: middle;`
`color: white;`
`font-size: 150%;`
`font-family: 'Lucida Sans Unicode','Lucida Grande',sans-serif;`
`}`
`#logo {height: auto; width: 100px; }`
`#data-table {padding: 30px; text-align: center;}`
`#table-row {`
`padding: 10px;`
`align: left;`
`color:#283850;`
`font-family: 'Lucida Sans Unicode','Lucida Grande',sans-serif;`
`}`
`#info {`
`font-size: 90%;`
`color: #283850;`
`font-family: 'Lucida Sans Unicode','Lucida Grande',sans-serif;`
`}`
`@media screen and (max-width: 400px) {`
`#title {font-size: 90%;}`
`}`
`@media screen and (max-height: 360px) {`
`#data-table {padding: 10px;}`
`#table-row {font-size: 80%;}`
`#info { font-size: 60%;}`
`#title-container { height: 40px; }`
`}`
`@media screen and (max-height: 290px){`
`#logo{width: 70px;}`
`}`
`@media screen and (max-height: 270px){`
`#title-container {height: 30px;}`
`#logo { width: 70px;}`
`#data-table {padding: 0px;padding-top: 10px;}`
`#table-row {font-size: 69%; padding: 5;}`
`#info { font-size: 53%;}`
`</style>`
`<title></title>`
`</head>`
`<body>`
`<div id="title-container">`
`<p id="title">Confirm the transaction</p>`
`<div style="position: absolute; right: 0px; padding: 10">`
`</div>`
`</div>`
`<div id="data-table">`
`<table border="1" frame="void" rules="rows" style="margin: auto;"width="75%">`
`<tr><th align="left" id="table-row">Pay to</th><th align="left" id="table-row">Amount</th></tr>`
`<tr><td align="left" id="table-row">Entrust</td><td align="left" id="table-row">200 EUR</td></tr>`
`<tr><td align="right" id="table-row" style="font-weight: bold">Fees:</td><td align="left" id="table-row">0 EUR</td></tr>`
`</table>`
`</div>`
`<div>`
`<p id="info">If you authorize this transaction, it will be signed with your private key and sent to the other parties for final approval.</p>`
`</div>`
`</body>`
`</html>`

# Wait for Signature to Be Available

Once the process for generating the transaction signature is created, the website can poll the `result` resource of this process. This is done by repeatedly executing the Obtain Result of the Signature Process operation until a HTTP response with the 200 status code is obtained. In this case, the transaction signature is found in the body of the response received.

The following request is repeated:

`GET /trustedx-resources/esigp/v1/signatures/9u0bdhl7679h99glqtun1je0u1/result HTTP/1.1`
`Host: txeidas.safelayer.com:443`
`Authorization: Bearer ed15d124c0433486949eb1a7894aec7f921ca7a3d010344532844e9a6f1c836d`

Until the following response is obtained:

`HTTP/1.1 200 OK`
`Content-Type: application/json;charset=UTF-8`
`{`
`"status" : "finished",`
`"value" : {...},`
`...`
`}`

# Transaction Signature Obtained

Once via polling it is detected that the transaction signature has been generated, the signature is extracted from the response in which its availability was detected. Specifically, it is extracted from the `value` element of the JSON object in the response body (see Obtain the Result of a Signature Process). This is an XAdES-EPES signature on the HTML document containing the data on the transaction.

## XML Document Containing the Transaction Signature

The XML document containing the transaction signature is shown below. Note that it is a detached XAdES-EPES signature inside an element that also contains the transaction data encoded in base64:

`<?xml version="1.0" encoding="UTF-8"?>`
`<Transaction>`
`<Content Encoding="http://www.w3.org/2000/09/xmldsig#base64" Id="Message" MimeType="text/html">`
`PGh0...h0bWw+`
`</Content>`
`<Content Id="Service" MimeType="text/xml">`
`<Service Domain="urn:safelayer:eidas:domain:oauth:client" Id="yourbank" Name="YourBank"></Service>`
`</Content>`
`<Content Id="SignatureProcess" MimeType="text/xml">`
`<SignatureProcess Domain="blueCardDomain" Id="9u0bdhl7679h99glqtun1je0u1" OperationType="sign:commitment:transaction">`
`</SignatureProcess>`
`</Content>`
`<ds:Signature xmlns:ds="http://www.w3.org/2000/09/xmldsig#" Id="Signature">`
`<ds:SignedInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#">`
`<ds:CanonicalizationMethod Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"></ds:CanonicalizationMethod>`
`<ds:SignatureMethod Algorithm="http://www.w3.org/2001/04/xmldsig-more#rsa-sha256"></ds:SignatureMethod>`
`<ds:Reference Id="Reference-Message" URI="#Message">`
`<ds:Transforms>`
`<ds:Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"></ds:Transform>`
`</ds:Transforms>`
`<ds:DigestMethod Algorithm="http://www.w3.org/2001/04/xmlenc#sha256"></ds:DigestMethod>`
`<ds:DigestValue>jU9PJFAx0x5TBLhxHEvuRBcEY5iV8BLMkSXfggEIccM=</ds:DigestValue>`
`</ds:Reference>`
`<ds:Reference Id="Reference-Service" URI="#Service">`
`<ds:Transforms>`
`<ds:Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"></ds:Transform>`
`</ds:Transforms>`
`<ds:DigestMethod Algorithm="http://www.w3.org/2001/04/xmlenc#sha256"></ds:DigestMethod>`
`<ds:DigestValue>5ZKVXeZAyGnV5HDYU0qghRgquXf9XxKLm4QTrvZmqRQ=</ds:DigestValue>`
`</ds:Reference>`
`<ds:Reference Id="Reference-SignatureProcess" URI="#SignatureProcess">`
`<ds:Transforms>`
`<ds:Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"></ds:Transform>`
`</ds:Transforms>`
`<ds:DigestMethod Algorithm="http://www.w3.org/2001/04/xmlenc#sha256"></ds:DigestMethod>`
`<ds:DigestValue>WdIrVPfYIUSjyDUANxrAysk6nBpFmv7B0TOfAYaM8Q8=</ds:DigestValue>`
`</ds:Reference>`
`<ds:Reference Type="http://uri.etsi.org/01903#SignedProperties" URI="#Xades">`
`<ds:Transforms>`
`<ds:Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"></ds:Transform>`
`</ds:Transforms>`
`<ds:DigestMethod Algorithm="http://www.w3.org/2001/04/xmlenc#sha256"></ds:DigestMethod>`
`<ds:DigestValue>zpDxDm8i78mdqzJUyilojHtQMdNqPV9LzQo3ikjwcaE=</ds:DigestValue>`
`</ds:Reference>`
`</ds:SignedInfo>`
`<ds:SignatureValue>kP7Bs....MlQ9Bc=</ds:SignatureValue>`
`<ds:KeyInfo>`
`<ds:X509Data>`
`<ds:X509Certificate>MIIDb...1dvZ/Q==</ds:X509Certificate>`
`</ds:X509Data>`
`</ds:KeyInfo>`
`<ds:Object>`
`<xades:QualifyingProperties xmlns:xades="http://uri.etsi.org/01903/v1.3.2#" Target="#Signature">`
`<xades:SignedProperties xmlns:xades="http://uri.etsi.org/01903/v1.3.2#" Id="Xades">`
`<xades:SignedSignatureProperties>`
`<xades:SigningTime>2015-02-07T18:00:21Z</xades:SigningTime>`
`<xades:SigningCertificate>`
`<xades:Cert>`
`<xades:CertDigest>`
`<ds:DigestMethod xmlns:ds="http://www.w3.org/2000/09/xmldsig#" Algorithm="http://www.w3.org/2001/04/xmlenc#sha256">`
`</ds:DigestMethod>`
`<ds:DigestValue xmlns:ds="http://www.w3.org/2000/09/xmldsig#">`
`YsUWbMcdqSza/JD8EVuSDQmYs0QR/osN3+svxy84Rao=`
`</ds:DigestValue>`
`</xades:CertDigest>`
`<xades:IssuerSerial>`
`<ds:X509IssuerName xmlns:ds="http://www.w3.org/2000/09/xmldsig#">`
`CN=Safelayer - Class 1 Root CA Demo, O=Safelayer Secure Communications\, S.A. [C.I.F. A61930046]`
`</ds:X509IssuerName>`
`<ds:X509SerialNumber xmlns:ds="http://www.w3.org/2000/09/xmldsig#">`
`53059670224754696327523756992274048772`
`</ds:X509SerialNumber>`
`</xades:IssuerSerial>`
`</xades:Cert>`
`</xades:SigningCertificate>`
`<xades:SignaturePolicyIdentifier>`
`<xades:SignaturePolicyId>`
`<xades:SigPolicyId>`
`<xades:Identifier Qualifier="OIDAsURI">`
`http://www.facturae.es/politica_de_firma_formato_facturae/politica_de_firma_formato_facturae_v3_1.pdf`
`</xades:Identifier>`
`<xades:Description>Spanish Facturae Signature Policy 3.1</xades:Description>`
`<xades:DocumentationReferences>`
`<xades:DocumentationReference>`
`http://www.safelayer.com/TWS`
`</xades:DocumentationReference>`
`</xades:DocumentationReferences>`
`</xades:SigPolicyId>`
`<xades:SigPolicyHash>`
`<ds:DigestMethod xmlns:ds="http://www.w3.org/2000/09/xmldsig#" Algorithm="http://www.w3.org/2000/09/xmldsig#sha1">`
`</ds:DigestMethod>`
`<ds:DigestValue xmlns:ds="http://www.w3.org/2000/09/xmldsig#">`
`Ohixl6upD6av8N7pEvDABhEL6hM=`
`</ds:DigestValue>`
`</xades:SigPolicyHash>`
`<xades:SigPolicyQualifiers>`
`<xades:SigPolicyQualifier>`
`<xades:SPURI>http://www.safelayer.com/TWS</xades:SPURI>`
`</xades:SigPolicyQualifier>`
`</xades:SigPolicyQualifiers>`
`</xades:SignaturePolicyId>`
`</xades:SignaturePolicyIdentifier>`
`</xades:SignedSignatureProperties>`
`<xades:SignedDataObjectProperties>`
`<xades:DataObjectFormat ObjectReference="#Reference-Message">`
`<xades:MimeType>text/html</xades:MimeType>`
`<xades:Encoding>http://www.w3.org/2000/09/xmldsig#base64</xades:Encoding>`
`</xades:DataObjectFormat>`
`<xades:DataObjectFormat ObjectReference="#Reference-Service">`
`<xades:MimeType>text/xml</xades:MimeType>`
`</xades:DataObjectFormat>`
`<xades:DataObjectFormat ObjectReference="#Reference-SignatureProcess">`
`<xades:MimeType>text/xml</xades:MimeType>`
`</xades:DataObjectFormat>`
`</xades:SignedDataObjectProperties>`
`</xades:SignedProperties>`
`</xades:QualifyingProperties>`
`</ds:Object>`
`</ds:Signature>`
`</Transaction>`

# Signature Process Deleted

Once the transaction signature is obtained, the signature creation process used to generate the signature must be deleted. Only then can new signatures be generated with the same mobile device (i.e., with the same BlueCard Mobile instance), because until the process is deleted, all requests for generating a signature with the same device are rejected.

The signature creation process is deleted by sending the following HTTP message to the TRIDENT signature generation service (see the Delete a Signature Process operation).

`DELETE /trustedx-resources/esigp/v1/signatures/9u0bdhl7679h99glqtun1je0u1`
`Host: txeidas.safelayer.com:443`
`Authorization: Bearer ed15d124c0433486949eb1a7894aec7f921ca7a3d010344532844e9a6f1c836d`