Skip to content
Branch: master
Find file History
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
..
Failed to load latest commit information.
DVSSample.xcodeproj
DVSSample
Docs
Podfile
README.md

README.md

DVSSample

Description

This sample demonstrates how to use the MIRACL iOS SDK in order to sign a transaction which can only be verified by a designated verifier using the MIRACL MFA Platform via an iOS device. These are the so-called DVS Registration and DVS Signing flows and here is the methods sequence user needs to follow in order to achieve it:

Requirements

  • MacOS Mojave or newer
  • iOS 12 or newer

Setup

  1. Checkout the sample projects https://github.com/miracl/sample-mobile-app-ios
  2. Run a backend application
  3. Configure the app with the issued credentials
  4. Build the project:
    1. From command line open the root dir from the checked out project. Navigate to folder DVSSample.
    2. Execute the following command:

    pod install

    1. Open the .xcworkspace file which is located in the current directory.

Create a demo web app to act as a backend service

In order to be able to test the demo DVS sample app, you need to run a backend service as a relying party demo web app (RPA). The demo app should authenticate to the MIRACL Trust authentication portal, called also MFA, using OpenIDConnect protocol. More information could be found here. This means you need to login and create an application in the portal and use its credentials (client id and client secret) in the demo web app for the communication.

This sample uses the mobile app login in order to register and authenticate an identity so it can make DVS operations with it. This means that the web app should implements the following endpoints as it is done at this sample RPA project:

  • POST /authzurl This should return the following json formatted data on success as it's done here:
{
    "authorizeURL": "<- The authorization url to the MFA ->"
}
  • POST /authtoken This endpoint should authenticate by a specified Authorization Code and User ID, passed in the following format:
{
    "code":"<- the authorization code to validate with ->",
    "userID":"<- the authorized email to be verified ->"
}

The http status code of the response could correspond to the status of the authentication. A sample could be found here.

Two more endpoints are necessary for the DVS operations:

  • POST /document The user signs a hash of the document, not the document itself. The web demo needs to have an endpoint to create this hash. It should accept the document to be signed and return its hash and a time stamp of its creation. By default SHA256 algorithm is used to compute the hash. You could review a sample handler for this here.

  • POST /verify-signature An additional call to the web demo should verify if the document hash is properly signed. There should be an endpoint which accepts a json formatted signature data with the following structure:

{
    "hash" : "<- the hash of the signed document ->",
    "mpinId" : "<- the M-Pin ID used to generate the signature ->",
    "u" : "<- the random commitment generated by the user ->",
    "v" : "<- the proof of the signature ->",
    "publicKey" : "<- the user public key used in the key-escrow less scheme (if supported) ->",
    "dtas" : "<- the DTAs used for signing ->"
}

and returns true/false if the signature is valid or not. Here is a sample handler you could review for a reference.

Once you have run the demo web app you need to host it on a visible URI for the mobile app. Just reassure that the proper redirect URI (demoAppUri/login) is added as a redirect URI to the authentication portal application settings you're running the web app with:

Configure the app with the issued credentials

Before starting the iOS application, you need to configure it through the Config.m file:

+ (NSString *)companyId
{
  return <# Replace with your company id #>;
}

+ (NSString *)accessCodeServiceBaseUrl
{
  return  <# Replace with backend ip/domain hostname #> ;
}

+ (NSNumber *)accessCodeServicePort
{
  return [NSNumber numberWithInteger: <# Replace with backend ip/domain port number #>];
}

+ (NSString *)httpScheme
{
  return <# Replace with http scheme value #>;
}

+ (NSString *)authBackend
{
  return @"https://api.mpin.io";
}

As the owner of the MFA web app, your Company ID is visible as a tooltip in the top right corner of your company dashboard in the MFA portal:

Note that authBackend method should always return https://api.mpin.io URL in order to authenticate against MIRACL Trust authentication portal.

DVS Sample implementation by MIRACL iOS SDK

Тhis sample uses Registration and Mobile App Login flows, which are explained in detail here, in order to login into the mobile app itself. In this documentation, we focus only on the DVS implementation flows, so we assume that the user has already been issued with a user ID and an access token.

Also since most of the Miracl iOS SDK methods are long-term operations, it is recommended to be called on background queue with NSOperationQueue or Grand Central Dispatch. You could see this pattern through the sample application.

SDK initialization

First step of SDK initialization is done at AppDelegate.m in application: didFinishLaunchingWithOptions: method, where [MPinMFA initSDK] and [MPinMFA SetClientId:] methods are called:

[MPinMFA initSDK];
[MPinMFA SetClientId: [Config companyId]];

DVS Registration

The user needs to have a DVS identity (different than their authentication identity with the same user id) in order to sign documents, which is implemented at DVSRegistrationViewController.m. If a user has a DVS identity could be checked by self.currentUser canSign method. If it returns true, this identity could be used to sign transactions. If it returns false, you need to create a signing identity for it. They need to authenticate first. That's why when DVS REGISTER button is clicked user first needs to enter their authentication identity PIN and after that [MPinMFA StartRegistrationDVS: pin0: pin1:] method is called:

MpinStatus *status = [MPinMFA StartRegistrationDVS:self.appDelegate.currentUser pin0:pin pin1:nil];

If the authentication succeeded, the user is asked for their DVS Signing PIN. Then [MPinMFA FinishRegistrationDVS: pinDVS: nfc:] method is called to complete their DVS Identity registration. Then the user could sign documents using the SignMessageViewController.m logic.

MpinStatus *status = [MPinMFA FinishRegistrationDVS:self.appDelegate.currentUser pinDVS:pin nfc:nil];

DVS Signing

For simplicity signing in SignMessageViewController.m is done for a simple string, but could be done for different resources like files or pictures, that could be represented as a string. Keep in mind, that better usage of DVS is to sign the document hash, not the whole file instead.

The user needs to enter some text and click SIGN button. The DVS Identity signing PIN is required to sign the text. Method createDocumentHash of AccessCodeServiceApi is executed to create a transaction of type DocumentDvsInfo from the document text by making a POST request to the RPA backend service.

This transaction needs to be verified by [MPinMFA VerifyDocument: hash:] method so the user is sure that the hash is correct.

BOOL verifiedDocument = [MPinMFA VerifyDocument:message hash:documentHash];
if (!verifiedDocument) {
    // ...
}

To sign the transaction [MPinMFA Sign: documentHash: pin0: pin1: epochTime: result:] method is used:

id<IUser> user = self.appDelegate.currentUser;
double time = (double)info.timestamp;
BridgeSignature *bridgeSignature = nil;
MpinStatus *status = [MPinMFA Sign:user documentHash:[info.hashValue dataUsingEncoding:NSUTF8StringEncoding] pin0:pin pin1:nil epochTime:time result:&bridgeSignature];

If status result is OK, the user can verify the validity of the provided PIN with verifySignature method of AccessCodeServiceApi. The result is displayed to the screen:

See also:

  1. MobileLoginSample
  2. WebsiteLoginSample
  3. BootstrapSample
You can’t perform that action at this time.