.NET DVS


Table of Contents:

Create a new standard app in the portal
Run the demo DVS app
DVS Demo app analysis
| ---- Initial login
| ---- DVS Registration
| ---- DVS Signing
| ---- DVS Verify Signature


Introduction

With the .NET SDK (https://github.com/miracl/maas-sdk-dotnet-v2) it is possible to configure a 'Designated Verifier Signature' client/server setup whereby MIRACL Trust 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. Based on 3 components (the client application, the Relying Party server, the MIRACL Trust authentication 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 .NET 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 .NET SDK.
  5. The backend SDK makes the necessary requests to the DVS Server to verify the signature validity.

The .NET SDK contains a demo application which is a simple JS browser app and RP server MVC application setup. Here, the JS code sends the document to the RP server to be hashed. The RP server creates the document hash and returns it to the browser app. After that the browser app generates a signature using the 'mfa.js' library and sends that signature to the RP server to be verified. The RP server uses the .NET SDK which makes the necessary calls to the MIRACL Trust authentication platform to verify the signature received from the JS app.

 

The user flow for this demo is:

  1. Perform initial registration, email confirmation, primary 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 authenticating transactions (the access token from stage one means that email registration and confirmation does not need to be carried out a second time)
  3. Enter some sample text for the document and sign the transaction by entering their second PIN
  4. Click to Verify the signature and see the result which will be True for a correct PIN

Dependencies


Note that the SDK has the following dependencies:

  1. .NET framework 4.5.2 and above
  2. MS Visual Studio 2013 and above
  3. IdentityModel (NuGet package)

Note on hosting


Please note that, for demo purposes, this documentation shows the use of IIS Express. This is for local testing purposes, and you should use your own chosen method to host a publicly-available web app.


Create a new standard app in the portal


Before working with the SDK, a new app must be created in the MIRACL Trust admin portal. Creating an app involves two basic steps:

  1. Register/create an app in the portal and obtain credentials (by going to Apps > Create new app)
  2. Configure your app using an SDK, making use of these credentials

You should first create a demo/test app with a redirect uri of http://127.0.0.1:5000/login in the portal, to enable you to run the SDK demo app and test the SDK functionality.

In the portal, when you create a new app, you will be issued with the client ID and client secret credentials that you need to specify when building your app with the SDK. These are found in the app settings screen:

app settings page

Note that you can control the Login Methods available (QR Code requires customer usage of the mobile app. While Browser Login enables logging in within the desktop browser, without the mobile app)

When creating your app in the portal, you also must specify a redirect_uri endpoint which comes from the url where you are hosting your app. When testing you can just enter a dummy address for Domain (in production this can be used to identify internal and external users):

add app

 


Run the demo DVS app


In order to make use of the DVS demo app you should download version 2 of the .NET SDK repo from https://github.com/miracl/maas-sdk-dotnet-v2.git

Then take the following steps:

  1. Open the root folder 'Authentication.sln' file in Visual Studio

  2. Minimise Visual Studio and navigate back to the root maas-sdk-dotnet-v2 folder. You will see that a '.vs' folder has appeared. Open the file .vs/config/applicationhost.config. In here you should edit the MiraclAuthenticationApp block:

    <site name="MiraclAuthenticationApp" id="2">
        <application path="/" applicationPool="Clr4IntegratedAppPool">
            <virtualDirectory path="/" physicalPath="C:\Users\user1\sdks\maas-sdk-dotnet-v2\MiraclDvsSigningApp" />
        </application>
        <bindings>
            <binding protocol="http" bindingInformation="*:5000:127.0.0.1" />
        </bindings>
    </site>

    Make sure that bindingInformation is changed from :5000:localhost to :5000:127.0.0.1

    Note that these instructions may differ for versions of Visual Studio older than 2015. You may have to edit the config file found in Documents\IISExpress\config\applicationhost.config and create the site name block above.

  3. Right-click on the top-level 'Authentication' solution and choose 'Build Solution'.

  4. Right-click on '/Samples/MiraclDvsSigningApp' and choose 'Set as Startup Project'

    Before running the app, you need to edit the web.config file to add the Client ID and Client Secret for your app, as well as your Customer ID:

    <appSettings>
    <add key="webpages:Version" value="3.0.0.0" />
    <add key="webpages:Enabled" value="false" />
    <add key="ClientValidationEnabled" value="true" />
    <add key="UnobtrusiveJavaScriptEnabled" value="true" />
    <add key="ClientId" value="" />
    <add key="ClientSecret" value="" />
    <add key="CustomerId" value=""/>
    </appSettings>

    Your Customer ID is visible as a tooltip in the top right corner of your company dashboard in the portal:

    view cid

    To activate the initial login button, it is necessary to open Views/Home/Index.cshtml and, towards the end of the file, make sure the mpad script has the correct url in order to communicate with the authentication server (note that it begins with 'mcl.cdn.mpin.io'):

    @section scripts{
    <script src="https://mcl.cdn.mpin.io/mpad/mpad.js"  data-authurl="@ViewBag.AuthorizationUri" data-element="btmpin"></script>
    }
  5. Run the app in Visual Studio (ctrl + f5) and visit http://127.0.0.1:5000 in your browser.

DVS Demo app analysis


Initial login

You will be presented with the initial login page:

dvs login

The registration and login is handled by the https://mcl.cdn.mpin.io/mpad/mpad.js script on the Views/Home/Index.cshtml page.

Once logged in the Viewbag created by Controllers/loginController.cs allows the Client UserId and access token to be displayed:

 

<div>
    @using (Html.BeginForm("Index", "Home", FormMethod.Post))
    {
        <span>You have been authenticated with identity <b id="userId">@ViewBag.Client.UserId</b> which has the following data.</span>
        <br/>
        <span>If you want to logout, press the button.</span>
        <button id="LogoutId" class="btn" name="Logout" value="Logout" type="submit">Logout</button>
    }
</div>
<br />
<p>
    <strong>Access token:</strong>
    <pre>@ViewBag.AccessTokenParsed</pre>
</p>

DVS Registration

After logging in you can click on the 'Register' button to register with the DVS service:

dvs login 2

In MiraclDvsSigningApp/Views/login/Index.cshtml the 'DVS Register' button is presented with:

<div id="dvsRegister">
    <a class="btn btn-primary" onclick="dvsRegister()">DVS register</a>
</div>

 

This calls the dvsRegister function:

function dvsRegister() {
    if (!isRegistered(userId)) {
        var pinValue;
        var isPinValid = false;
        while (!isPinValid) {
            pinValue = prompt("Please, set up PIN (accepts only 4 digits)");
            if (pinValue === null) {
                return;
            }

            isPinValid = /^\d{4}$/.test(pinValue);
        }

        var successCb = function () {
            var element = $("#dvsRegisterResponse > span");
            element.removeClass("text-danger");
            element.html("An identity <b>@ViewBag.Client.UserId</b> has been registered for DVS. Now you can sign documents with it.");

            $("#dvsRegister").addClass("hidden");
            $("#dvsSign").removeClass("hidden");
        };

        var errorCb = function (error) {
            var element = $("#dvsRegisterResponse > span");
            element.addClass("text-danger");
            element.html(error.message);
            console.log(error);
        };

        var pinCb = function (passPin) {
            passPin(pinValue);
        };

        mfa.registerDvs(userId, accessToken, pinCb, successCb, errorCb)
    } else {
        $("#dvsRegister").addClass("hidden");
        $("#dvsSign").removeClass("hidden");
    }
}    

This prompts the user to set up a PIN and mfa.registerDvs(userId, accessToken, pinCb, successCb, errorCb) uses the mfa object to call the registerDvs method from http://cdn.miracl.net/mfa-client-js/latest/mfa.js

At this point it should be noted that, in the scripts section of Views/login/Index.html, the mpad.js library is called:

@section scripts{
<script src="http://cdn.miracl.net/mfa-client-js/latest/mfa.js"></script>

Variables are created for the userId and accessToken:

var userId = "@ViewBag.Client.UserId";
var accessToken = "@Model.AccessToken";

And an Mfa object is created:

var mfa = new Mfa({
    server: "@ViewBag.Client.Options.PlatformAPIAddress",
    customerId: "@ViewBag.Client.Options.CustomerId",
    seed: getLocalEntropy(),
    clientId: "@ViewBag.Client.Options.ClientId"
});

The prompt to create a separate DVS PIN:

dvs create pin

Note that the access token which was granted when you first registered and confirmed with your email address has meant that you did not need to register and confirm again. You only need to create your second PIN for the DVS service.

DVS Signing

Once registered you can enter some sample text in the box and click 'Sign':

dvs login 3

You will be prompted to enter your DVS PIN to sign the transaction:

dvs enter pin

In MiraclDvsSigningApp/Views/login/Index.cshtml the 'Sign' button is presented with:

<a class="btn btn-primary" onclick="dvsSign($('#doc').val())">Sign</a>

This calls the dvsSign function:

function dvsSign(doc) {
    var pinValue;
    var isPinValid = false;
    while (!isPinValid) {
        pinValue = prompt("Please, enter PIN (accepts only 4 digits)");
        if (pinValue === null) {
            return;
        }

        isPinValid = /^\d{4}$/.test(pinValue);
    }

    $("#verificationResult").addClass("hidden");

    if (isRegistered(userId)) {
        $.ajax({
            url: "@Url.Action("CreateDocumentHash", "login")",
            type: "POST",
            data: { document: doc },
            dataType: "json",
            cache: false,
            success: function (documentData) {
                try {
                    var s = mfa.signMessage(userId, pinValue, documentData.hash, documentData.timestamp);

                    var signature = {
                        mpinId: mfa.users.get(userId, "mpinId"),
                        publicKey: mfa.users.get(userId, "publicKey"),
                        u: s.U,
                        v: s.V,
                        hash: documentData.hash,
                        timestamp: documentData.timestamp
                    };

                    $("#signatureData").html(JSON.stringify(signature, null, 4));
                    $("#signature").removeClass("hidden");
                } catch (err) {
                    alert(err);
                }
            }
        })
    }
}

This makes a POST action to the /login/CreateDocumentHash endpoint. The CreateDocumentHash endpoint is configured in Controllers/loginController.cs:

[HttpPost]
public JsonResult CreateDocumentHash(string document)
{
    var docHash = HomeController.Client.DvsCreateDocumentHash(document);
    var timeStamp = (int)(DateTime.UtcNow - new DateTime(1970, 1, 1, 0, 0, 0, 0, DateTimeKind.Utc)).TotalSeconds;
    var documentData = new { hash = docHash, timestamp = timeStamp };

    return Json(documentData);
}

DVS Verify signature

Finally you will see the Signature output and can click 'Verify Signature' to see the verification result:

dvs login 4

In MiraclDvsSigningApp/Views/login/Index.cshtml the 'Verify Signature' button is presented with:

<a class="btn btn-primary" onclick="dvsVerifySignature($('#signatureData').html())">Verify signature</a>

This calls the dvsVerifySignature function:

 

function dvsVerifySignature(signature) {
    $.ajax({
            url: "@Url.Action("VerifySignature", "login")",
            type: "POST",
            data: { verificationData: signature },
            dataType: "json",
            cache: false,
            success: function (res) {
                $("#verificationResult").removeClass("hidden");
                $("#verificationResult > pre").html(JSON.stringify(res, null, 4));
            }
        })
}

Which POSTs to the /login/VerifySignature endpoint. This endpoint is configured in Controllers/loginController.cs:

[HttpPost]
public async Task<JsonResult> VerifySignature(string verificationData)
{
    var data = JObject.Parse(verificationData);

    var mPinId = data.TryGetString("mpinId");
    var publicKey = data.TryGetString("publicKey");
    var u = data.TryGetString("u");
    var v = data.TryGetString("v");
    var docHash = data.TryGetString("hash");
    var ts = data.TryGetInt("timestamp");

    var signature = new Signature(docHash, mPinId, u, v, publicKey);
    var timeStamp = ts.HasValue ? ts.Value : 0;
    var verificationResult = await HomeController.Client.DvsVerifySignatureAsync(signature, timeStamp);

    return Json(new { verified = verificationResult.IsSignatureValid, status = verificationResult.Status.ToString() });
}      

Top