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 an operation 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.

For more information about creating a transaction from the Web App/backend integration, refer to the bcauthorize endpoint.

The mobile application signs a transaction as follows:

  1. Create an instance of the IDevice (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 (IContainer.RetrieveTransactionsIds)

  3. Get public information (ServerActionInfo) from the transaction identifier (transactionId) (IDevice.RetrieveTransactionInfo). There is no communication with the server at this point.

    The returned ServerActionInfo instance provides the:

    • ServerActionInfo.Container - the container associated with this transaction

    • ServerActionInfo.UniqueIdentifier - 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.

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

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

Sample Transaction Signing on Windows (C#)

Copy 
// Retrieve pending trnasaction for this container. The ID can also be recevied through a push message.
var txIds = await container.RetrieveTransactionsIds(null, null);

// Get the public information of the transaction
var info = await device.RetrieveActionInfo(txIds[0]);

// Retrieve the transaction details
var transaction = (ITransaction)await info.GetServerAction(null, null);

// Here we can check whether the transaction protection key is protected by a password 
var signKey = await transaction.GetSigningKey();
var policy =  await signKey.GetProtectionPolicy();
if (ProtectionPolicyType.Password.Equals(policy.Type))
{
    // Prompt the end-user for the transaction protection key password
    Debug.WriteLine("This is a password policy");
}

// We can now sign the transaction with a selected status
var status = transaction.AllowedStatuses.First();
var succeeded = await transaction.SetStatus(status, mypassword, null, null);