Android DVS


Table of Contents:

The DVS methods
| ---- The startRegistrationDVS method
| ---- The finishRegistrationDVS method
| ---- The verifyDocument method
| ---- The sign method


Introduction

The MIRACL Trust Android SDK (https://github.com/miracl/incubator-milagro-mfa-sdk-android) contains methods which can be used to configure a 'Designated Verifier Signature' app whereby the MIRACL Trust authentication server can issue secret signing keys to users and allow them to verify their transactions with multi-factor signatures.

The DVS scheme enables a client to sign a transaction which can only be verified by a designated verifier. Three components are required:

  1. The mobile client application controlled by the customer (making use of the MIRACL Trust Android SDK)
  2. The Relying Party server controlled by the customer. This makes use of one of the MIRACL Trust backend SDKs (such as the .NET SDK. Note that the DVS functionality is not yet available in all SDKs)
  3. The MIRACL Trust DVS server

The scheme has the following flow:

  1. The mobile client app generates and sends the message to be signed, to the RP server
  2. The RP server calls the DvsCreateDocumentHash backend SDK method to create a SHA256 hash. The hash together with a timestamp is then sent back to the mobile client app.
  3. Then the mobile client app creates its signature and passes it to the RP server
  4. The RP server creates a Signature object with the received signature data, and passes it to the DvsVerifySignature method of the backend SDK.
  5. The backend SDK makes the necessary requests to the DVS Server to verify the signature validity.

A typical user flow for a mobile DVS application would be:

  1. Perform initial registration, email confirmation, primary authentication PIN creation and login (at this stage the user is issued with a user ID and an access token)
  2. Register with the DVS service and create a second PIN for signing transactions (the access token from stage one means that email registration and confirmation does not need to be carried out a second time)
  3. They can then create a transaction and sign it by entering their second PIN
  4. The transaction will then appear as confirmed in the mobile application

 

The DVS methods

In the Android SDK, there are methods which can be used to manage the basic setup and primary registration and authentication process such as SetBackend, StartRegistration and StartAuthentication. An illustration of these methods in use (in a simple demo app) can be found here

For the purposes of this guide, the following DVS-specific methods are available:

The startRegistrationDvs method

public Status startRegistrationDvs(User user, String token)

The above token is the access token issued for the user during the primary Open ID Connect authentication process. This token has to be passed from the RP server backend to the mobile application.

It is this token which ensures that the user does not have to re-register and confirm their ID. They only need to create a new second PIN for DVS signing:

The finishRegistrationDvs method

public Status finishRegistrationDvs(User user, String[] multiFactor)

finishRegistrationDvs finalizes the user registration process. Before it is called, the PIN must be obtained from the end user (it is possible to introduce other authentication factors besides a PIN, hence the String[] multiFactor array above)

The verifyDocumentHash method

public boolean verifyDocumentHash(String document, byte[] hash)

Once the RP server backend has returned the hash of the document to the mobile client app, this method verifies that the hash value is correct for the given document. It returns true or false.

The sign method

public Status sign(User user, byte[] documentHash, String secret, int epochTime, String authzToken, Signature signature)

This method signs the documentHash for the given user. The user's authentication factor (i.e. their secondary DVS PIN) has to be provided.

epochTime is the timestamp, in Epoch format, for the document/transaction signature. This will have been created by the RP server backend, using the backend SDK CreateDocumentHash method.

authzToken is a token that the Android SDK needs in order to be able to generate the signature and verify against the platform the correctness of the provided authentication factors. This token should also be generated by the application back-end, using one of the MFA Backend SDK variants.

Generally, the token has the format "MAAS-HMAC-SHA256 <token>" as <token> is Base64-encoded <client-id>:<hmac-sha256-signature>.

<hmac-sha256-signature> is an HMAC-SHA256 signature of the hex-encoded document hash, using the Client Secret as a key

Top