Transaction data signing
- 23 Oct 2024
- 8 Minutes to read
- DarkLight
- PDF
Transaction data signing
- Updated on 23 Oct 2024
- 8 Minutes to read
- DarkLight
- PDF
Article summary
Did you find this summary helpful?
Thank you for your feedback
For more information about the transaction data signing mechanism, refer to the Mobile Authenticator Studio Product Guide.
Listing transactions to sign
With transaction data signing enabled, Mobile Authenticator Studio is able to retrieve a list of transactions on user demand, and sign each transaction locally. The signature is then sent back to a server for validation.
.png?sv=2022-11-02&spr=https&st=2024-11-19T16%3A22%3A22Z&se=2024-11-19T16%3A32%3A22Z&sr=c&sp=r&sig=DLQyC1dS3tDt2DYRal1ueM9TpJsjEl%2BpZW15UecaX5Q%3D "image(121).png")
Listing pending transactions (overview)
Integrating transaction data signing involves the following steps:
The app submits an HTTP(S) request to the integrator back-end system. The request contains a one-time password (OTP) to authenticate the issuer.
The integrator validates the OTP.
On successful authentication, the list of pending transactions can be retrieved from the database.
The response that contains the transaction list is sent back to the app.
Transaction list request
The request sent by Mobile Authenticator Studio is configured in the TransactionList section of the configuration file:
<TransactionDataSigningAction authenticationCryptoAppIndex="1"signatureCryptoAppIndex="2"displayPopup="true">
<!-- Transactions list URL -->
<TransactionList>
<URL method="GET"value="http://MY_DOMAIN_NAME/MY_WEB_SERVICE?serial=%_SerialNumber_%&otp=%_OTP_%&version=%_Version_%" />
</TransactionList>
...
</TransactionDataSigningAction>
The URL can use the HTTP POST or GET methods. For more information about URL customization, refer to the Mobile Authenticator Studio Customization Guide.
Parameter name | Description |
|---|---|
SerialNumber | The authenticator serial number. Format: Alphanumeric string, 10 characters |
RegistrationIdentifier | The identifier provided by the user via the online activation screen of the Mobile Authenticator Studio app. Format: Alphanumeric string, limited to 40 characters |
UserIdentifier | The extra user identifier that has been set during activation. Format: Alphanumeric string, limited to 40 characters |
OTP | The OTP generated by the cryptographic application defined by the authenticationCryptoAppIndex attribute of the TransactionDataSigningAction element. Format: Hexadecimal string, limited to 16 characters |
Version | The version of the application binary as defined when configuring the app. |
DeviceIdentifier | The device-unique identifier. Format: String of 64 hexadecimal characters |
RootingStatus | The status indicating whether the device is rooted, either true or false according to the device state. |
Transaction list response
The response expected by Mobile Authenticator Studio must be formatted as described in the DTD:
<!ELEMENT DP4Mobile (Activation?,PendingTransactions?)>
<!ATTLIST DP4Mobile retCode CDATA #REQUIRED>
<!ATTLIST DP4Mobile message CDATA #REQUIRED>
<!ATTLIST DP4Mobile serverTime CDATA #IMPLIED>
<!ELEMENT PendingTransactions (Transaction*)>
<!ELEMENT Transaction (Item*)>
<!ATTLIST Transaction identifier CDATA #REQUIRED>
<!ATTLIST Transaction name CDATA #REQUIRED>
<!ELEMENT Item EMPTY>
<!ATTLIST Item value CDATA #REQUIRED>
<!ATTLIST Item dtfIndex (1|2|3|4|5|6|7|8) #IMPLIED>
<!ATTLIST Item hidden (true|false) #IMPLIED>
<!ATTLIST Item align (left|right|center) #IMPLIED>
<!ATTLIST Item bold (true|false) #IMPLIED>
<!ATTLIST Item italic (true|false) #IMPLIED>
Example
<?xml version="1.0"encoding="UTF-8"?>
<DP4MobileretCode="0"message="Operation Successful" >
<PendingTransactions>
<Transaction identifier="795ba1121281608b84a8000"
name="Transaction 1">
<Item value="Amount"bold="true"align="center" />
<Item value="123"dtfIndex="1" />
<Item value="" />
<Item value="Destination"italic="true" />
<Item value="456"dtfIndex="2" />
<Item value="789"hidden="true"dtfIndex="3" />
</Transaction>
<Transaction identifier="3456426341316aec21ef0190"name="Transaction 2" >
<Item value="Amount"bold="true"align="center" />
<Item value="111"dtfIndex="1" />
<Item value="Destination"italic="true" />
<Item value="222"dtfIndex="2" />
<Item value="333"hidden="true"dtfIndex="3" />
</Transaction>
</PendingTransactions>
</DP4Mobile>
Attribute name | Description |
|---|---|
//DP4Mobile/@retCode | Required. The return code associated with the transaction list request. 0 means success, any other value will cause the message attribute value to be displayed and the list transaction to stop. |
//DP4Mobile/@message | Required. The return message associated with the transaction list request. This value will be displayed by the app if not 0. |
//DP4Mobile/@serverTime | Optional. This is the current server GMT time. This value will be used by the app to silently set the drift between device and server time to keep the app synchronized. |
//Transaction/@identifier | The unique identifier of a transaction. It is not displayed, but only used to uniquely trace a transaction during the signing process. Format: Alphanumeric string |
//Transaction/@name | The name of the transaction as displayed on the device. Format: Alphanumeric string |
Each transaction contains a list of items that will be displayed in the app. Each item has a number of attributes.
Attribute name | Description |
|---|---|
//Item/@value | The text as displayed on the device. Format: Alphanumeric string |
//Item/@bold | Indicates whether the text is in bold. |
//Item/@align | Indicates whether the text is in left-, center-, or right-aligned. |
//Item/@italic | Indicates whether the text is in italics. |
//Item/@dtfIndex | Indicates whether the item value is signed as a data field. If omitted, the text is not signed. |
//Item/@hidden | Indicates whether the text is visible. |
Validating transactions
Depending on the Mobile Authenticator Studio configuration, transactions can be validated either internally or externally.
Internal transaction validation
.png?sv=2022-11-02&spr=https&st=2024-11-19T16%3A22%3A22Z&se=2024-11-19T16%3A32%3A22Z&sr=c&sp=r&sig=DLQyC1dS3tDt2DYRal1ueM9TpJsjEl%2BpZW15UecaX5Q%3D "image(122).png")
Internal transaction validation (overview)
Once Mobile Authenticator Studio has signed the content of a transaction, it can manage the validation of the transaction inside the app by connecting to a web service. The web service must be able to validate the signature of a transaction identified by its unique transaction identifier.
The request sent by Mobile Authenticator Studio is configured in the TransactionValidation section of the configuration file:
<TransactionDataSigningAction authenticationCryptoAppIndex="1"signatureCryptoAppIndex="2" displayPopup="true">
<TransactionValidation>
<OutputDatadisplayed="false"internalValidation="true">
<URL method="POST"value="http://MY_DOMAIN_NAME/MY_WEB_SERVICE">
<PayloadParameter key="serial"value="%_SerialNumber_%" />
<PayloadParameter key="signature"value="%_OTP_%" />
<PayloadParameter key="transactionId"value="%_TransactionIdentifier_%" />
</URL>
</OutputData>
</TransactionValidation>
...
</TransactionDataSigningAction>
The URL can use the HTTP POST or GET methods. For more information about URL customization, refer to the Mobile Authenticator Studio Customization Guide.
Parameter name | Description |
|---|---|
SerialNumber | The authenticator serial number. Format: Alphanumeric string, 10 characters |
RegistrationIdentifier | The identifier provided by the user via the online activation screen of the Mobile Authenticator Studio app. Format: Alphanumeric string, limited to 40 characters |
UserIdentifier | The extra user identifier that has been set during activation. Format: Alphanumeric string, limited to 40 characters |
OTP | The signature generated by the cryptographic application defined by the signatureCryptoAppIndex attribute of the TransactionDataSigningAction element. |
TransactionIdentifier | The unique identifier of a transaction. Format: Alphanumeric string |
Version | The version of the application binary as defined when configuring the app. |
DeviceIdentifier | The device-unique identifier. Format: String of 64 hexadecimal characters |
RootingStatus | The status indicating whether the device is rooted, either true or false according to the device state. |
If a score-based authentication mechanism is used to generate the OTP, the score evaluated by Mobile Authenticator Studio will be returned by OneSpan Authentication Server Framework. This is done through the return code of the OTP verification API.
Score-based authentication requires OneSpan Authentication Server Framework 3.14 or later.
For more information about retrieving the client score from Authentication Server Framework, refer to the OneSpan Authentication Server Framework Programmer's Guide.
The response expected by Mobile Authenticator Studio must be formatted as described in the DTD:
<!ELEMENT DP4Mobile (Activation?,PendingTransactions?)>
<!ATTLIST DP4Mobile retCode CDATA #REQUIRED>
<!ATTLIST DP4Mobile message CDATA #REQUIRED>
<!ATTLIST DP4Mobile serverTime CDATA #IMPLIED>
<!ATTLIST DP4Mobile confirmationCode CDATA #IMPLIED>
Example
<?xml version="1.0"encoding="UTF-8"?>
<DP4MobileretCode="0"message="Operation Successful"confirmationCode="123456" >
<PendingTransactions/>
</DP4Mobile>
A confirmation code attribute can be added to the response. It will be displayed by the app together with the message.
Attribute name | Description |
|---|---|
//DP4Mobile/@retCode | Required. The return code associated with the transaction validation request. 0 means success, any other value will cause the message attribute value to be displayed and the transaction data signing process to stop. |
//DP4Mobile/@message | Required. The return message associated with the transaction validation request. This value will be displayed by the app if not empty. |
//DP4Mobile/@serverTime | Optional. This is the current server GMT time. This value will be used by the app to silently set the drift between device and server time to keep the app synchronized. |
//DP4Mobile/@confirmationCode | Optional. The server return host code. If provided, it will be displayed along with the message. |
External transaction validation
.png?sv=2022-11-02&spr=https&st=2024-11-19T16%3A22%3A22Z&se=2024-11-19T16%3A32%3A22Z&sr=c&sp=r&sig=DLQyC1dS3tDt2DYRal1ueM9TpJsjEl%2BpZW15UecaX5Q%3D "image(123).png")
External transaction validation (overview)
Once Mobile Authenticator Studio has signed the content of a transaction, it can open a URL in the device web browser. This URL contains the information that identifies the authenticator application and the transaction, as well as the transaction signature. The Mobile Authenticator Studio app is closed as soon as the browser is opened.
The URL opened by Mobile Authenticator Studio is configured in the TransactionValidation section of the configuration file:
<TransactionDataSigningAction authenticationCryptoAppIndex="1"signatureCryptoAppIndex="2"displayPopup="true">
<TransactionValidation>
<OutputDatadisplayed="false"internalValidation="false">
<URL method="POST"value="http://MY_DOMAIN_NAME/MY_WEB_SERVICE">
<PayloadParameter key="serial"value="%_SerialNumber_%" />
<PayloadParameter key="signature"value="%_OTP_%" />
<PayloadParameter key="transactionId"value="%_TransactionIdentifier_%" />
</URL>
</OutputData>
</TransactionValidation>
...
</TransactionDataSigningAction>
The URL can use the HTTP POST or GET methods. For more information about URL customization, refer to the Mobile Authenticator Studio Customization Guide.
Parameter name | Description |
|---|---|
SerialNumber | The authenticator serial number. Format: Alphanumeric string, 10 characters |
RegistrationIdentifier | The identifier provided by the user via the online activation screen of the Mobile Authenticator Studio app. Format: Alphanumeric string, limited to 40 characters |
UserIdentifier | The extra user identifier that has been set during activation. Format: Alphanumeric string, limited to 40 characters |
OTP | The signature generated by the cryptographic application defined by the signatureCryptoAppIndex attribute of the TransactionDataSigningAction element. Format: Hexadecimal string, limited to 16 characters |
TransactionIdentifier | The unique identifier of a transaction. Format: Alphanumeric string |
Version | The version of the application binary as defined when configuring the app. |
DeviceIdentifier | The device-unique identifier. Format: String of 64 hexadecimal characters |
RootingStatus | The status indicating whether the device is rooted, either true or false according to the device state. |
Rejecting transactions
.png?sv=2022-11-02&spr=https&st=2024-11-19T16%3A22%3A22Z&se=2024-11-19T16%3A32%3A22Z&sr=c&sp=r&sig=DLQyC1dS3tDt2DYRal1ueM9TpJsjEl%2BpZW15UecaX5Q%3D "image(124).png")
Transaction rejection (overview)
The user can reject a transaction. When a transaction is rejected, no signature will be generated and the transaction will be removed from the list of pending transactions. Transaction rejection is managed by connecting to a web service.
The request sent by Mobile Authenticator Studio is configured for every TransactionDataSigningAction element of the configuration file:
<TransactionDataSigningAction authenticationCryptoAppIndex="1"signatureCryptoAppIndex="2"displayPopup="true">
<TransactionRejection>
<URL method="POST"value="http://MY_DOMAIN_NAME/MY_WEB_SERVICE">
<PayloadParameter key="serialNumber"value="%_SerialNumber_%" />
<PayloadParameter key="transactionId"value="%_TransactionIdentifier_%" />
</URL>
</TransactionRejection>
</TransactionDataSigningAction>
The URL can use the HTTP POST or GET methods. For more information about URL customization, refer to the Mobile Authenticator Studio Customization Guide.
Parameter name | Description |
|---|---|
SerialNumber | The authenticator serial number. Format: Alphanumeric string, 10 characters |
RegistrationIdentifier | The identifier provided by the user via the online activation screen of the Mobile Authenticator Studio app. Format: Alphanumeric string, limited to 40 characters |
UserIdentifier | The extra user identifier that has been set during activation. Format: Alphanumeric string, limited to 40 characters |
TransactionIdentifier | The unique identifier of a transaction. Format: Alphanumeric string |
Version | The version of the application binary as defined when configuring the app. |
DeviceIdentifier | The device-unique identifier. Format: String of 64 hexadecimal characters |
RootingStatus | The status indicating whether the device is rooted, either true or false according to the device state. |
The response expected by Mobile Authenticator Studio must be formatted as described in the DTD:
<!ELEMENT DP4Mobile (Activation?,PendingTransactions?)>
<!ATTLIST DP4Mobile retCode CDATA #REQUIRED>
<!ATTLIST DP4Mobile message CDATA #REQUIRED>
<!ATTLIST DP4Mobile serverTime CDATA #IMPLIED>
Example
<?xml version="1.0"encoding="UTF-8"?>
<DP4MobileretCode="0"message="Operation Successful" >
<PendingTransactions />
</DP4Mobile>
A confirmation code attribute can be added to the response. It will be displayed by the application along with the message.
Attribute name | Description |
|---|---|
//DP4Mobile/@retCode | Required. The return code associated with the transaction rejection request. 0 means success, any other value will cause the message attribute value to be displayed and the transaction data signing process to stop. |
//DP4Mobile/@message | Required. The return message associated with the transaction rejection request. This value will be displayed by the app if not empty. |
//DP4Mobile/@serverTime | Optional. This is the current server GMT time. This value will be used by the app to silently set the drift between device and server time to keep the app synchronized. |
Was this article helpful?