Transaction Signing

View this page for | |

Once the keys are provisioned, the device is ready to perform a Transaction Signing operation (that is, to approve or decline a transaction based on details sent by the HID authentication platform). How the application is notified that a transaction is to be signed depends on its deployment. One option is to get a push notification from the server.

Transaction Signing Workflow

The mobile application signs a transaction as follows:

1. Create an instance of the Device (DeviceFactory.getDevice).

2. Retrieve the transaction identifier (transactionId) for the transaction that will be processed. This identifier can be retrieved from the:

   • Push notification payload received by the application. This is the tds member of the payload

   • List of pending transactions for a specific container retrieved from the server (Container.retrieveTransactionsIds)

3. Get public information (TransactionInfo) from the transaction identifier (transactionId) (Device.retrieveTransactionInfo). There is no communication with the server at this point.

   The returned TransactionInfo instance provides the:

   • TransactionInfo.getContainer - the container associated with this transaction

   • TransactionInfo.getUniqueIdentifier - the transaction Unique Identifier

     This unique identifier corresponds to the server challenge identifier (cid) and can be used to correlate transactions between the client and server.

   • TransactionInfo.getTransactionProtectionKey - the session transport key, which can be used to determine the corresponding key protection policy (such as if the password is required)

2. Check if the Session Transport Key is protected by a password and prompt the user as required.
3. Get transaction details from the server (TransactionInfo.getTransaction).
4. Get the Transaction details (Transaction.toString) and the list of allowed statuses (Transaction.getAllowedStatuses) that will be displayed to the end user so that they can decide which action to take (“approve” or “decline” the Transaction).
5. Display the transaction to the end user and retrieve the end user’s selection among the available statuses.
6. Then request the end user to provide their Transaction Signing Protecting password and send the final status to the HID authentication platform (Transaction.setStatus).

Sample Transaction Signing on Android

Device device = DeviceFactory.getDevice(ctx, null); 
// Get public information from the transaction identifier
TransactionInfo txInfo = device.retrieveTransactionInfo(txId);
 
// Here we can check whether the transaction protection key is protected by a password 
ProtectionPolicy policy = txInfo.getTransactionProtectionKey().getProtectionPolicy();
if (PolicyType.PASSWORD.toString().equals(policy.getType())) {
    // Prompt the end-user for the transaction protection key password
    ...
}
...
// Get the Transaction details
Transaction tx = txInfo.getTransaction(sessionPassword, new Parameter[0]);
 
// Display the transaction details to the end user and get the end user’s selection among the available statuses
// tx.toString()
// tx.getAllowedStatuses()
 
...
 
// Here we can check whether the signing key is protected by a password
ProtectionPolicy signingKeyPolicy = tx.getSigningKey().getProtectionPolicy();
if (PolicyType.PASSWORD.toString().equals(signingKeyPolicy.getType())) {
    // Prompt the end-user for the signing key password
    ...
}
 
// Sign the transaction
boolean result = tx.setStatus(selectedStatus, sessionPassword, signingKeyPassword, new Parameter[0]);