Table of Contents:

The DVS methods
| ---- The StartRegistrationDVS method
| ---- The FinishRegistrationDVS method
| ---- The VerifyDocument method
| ---- The Sign method


The MIRACL Trust iOS SDK ( 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 iOS 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 iOS 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

+ (MpinStatus*) StartRegistrationDVS:(const id<IUser>)user
                               token:(NSString *) 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

+ (MpinStatus*) FinishRegistrationDVS:(const id<IUser>)user
                               pinDVS:(NSString *) pinDVS
                                  nfc:(NSString *) nfc;

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, as per the use of nfc above)

The VerifyDocument method

+ ( BOOL ) VerifyDocument:(NSString *) strDoc hash:(NSData *) 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

+ (MpinStatus*) Sign: (id<IUser>)user documentHash:(NSData *)hash pin0: (NSString *) pin0 pin1: (NSString *) nfc epochTime: (double) epochTime authZToken: (NSString *) authZToken result:(BridgeSignature **)result;

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

Note that, when pin0 and pin1 are expected and there is no additional factor besides the signing PIN, the second parameter should be nil.

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 iOS 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