Sign documents with DVS

DVS (Designated Verifier Signature) scheme allows a client entity to sign a message/document which could be verified only by the designated verifier. The signatures are produces on the user’s side either by the JS Client Library as described in this article or the mobile applications using the Android and iOS SDKs.

You can read more about DVS in the concepts section.

What Can Be Signed

We will be using the term ‘document’ in this article to represent the data that will be cryptographically signed. This however does not mean there are restrictions on the type of data that you want to sign. DVS can be used on any blob of data as the signature will be produced for the hash digest of the data rather than the raw value itself. On top of what you will traditionally consider a document, you can also sign any type of transaction, like a transfer of financial funds or a representation of a write operation to be stored in an audit log.

It is important to note that the usage of a hash digests instead of the raw data also means that the actual value of what is being signed will never be transmitted to the MIRACL Trust platform. This holds true for all parts of the process - both signing and verification.

Implementation

In order to create and verify signatures you need to:

  1. Integrate the DVS JS Client library in your web frontend and/or integrate the Android/iOS SDK in your mobile application.
  2. Alter the endpoint that you have in your backend for creation of the document to return a SHA256 hash digest of the document and timestamp of creation and return those in the response.
  3. Invoke the sign method of the library/SDK to produce the signature.
  4. Create an endpoint in your backend, which will accept the signature data and verify it against the MIRACL Trust platform as described in Signature Verification.

JS Client Library

Installation

In order to sign documents in the browser, you need to include the MIRACL Trust DVS client library and related CSS served from our CDN.

<link rel="stylesheet" type="text/css" href="https://cdn.mpin.io/dvs/css/dvs.css" media="screen"/>
<script type="text/javascript" src="https://cdn.mpin.io/dvs/dvs.client.min.js"></script>

Usage

Before using the DVS client library, you need to configure and initialize it.

var dvs = new DVS({
    userId: "test@example.com",
    clientId: "{{ ClientID }}",
    redirectURI: "http://127.0.0.1/login",
    pinPolicy: "same"
});

dvs.init(function () {
    // You can call the sign method here.
});

Specifying the value same for pinPolicy means that the user will use the same PIN for signing documents and for authentication. This means that there is no need to manually manage the identity used for signing with the hasIdentity, createIdentity and deleteIdentity methods of the library. If not set to same you will have to additionaly create the signing identity:

dvs.hasIdentity(function success() {
    // User already has an identity.
}, function fail() {
    dvs.createIdentity(function success(data) {
        // The user now has an identity and can sign documents.
    }, function fail(error) {
        // Creation was not successful.
        console.error(error);
    });
});

After you have ensured that user has a signing identity either by using pinPolicy: "same" or creating one by invoking createIdentity, you can call the sign method. This will produce a cryptographic signature of the provided document, which you will be able to store and verify:

dvs.sign({
    doc: "This is a test document for signing",
    hash: "a85675951451ebbcccb4c4d1a41dfe6cbf0f037ef505ffccd3d314930b3d7316",
    timestamp: 1608300866
}, function success(signature) {
    // The signature was created successfully.
    // You can now send it to your backend for verification.
    console.log(signature);
}, function fail(error){
    // The signing was not successful.
    // This can happen if the user entered a wrong PIN or
    // there was a malicious attempt to temper with the signing.
});

You can see a full list of configuration options in the MIRACL Trust DVS JS Reference.

Examples

<!DOCTYPE html>
<html>
<head>
<title>DVS Same PIN</title>
<link rel="stylesheet" type="text/css" href="https://cdn.mpin.io/dvs/css/dvs.css" media="screen"/>
<script type="text/javascript" src="https://cdn.mpin.io/dvs/dvs.client.min.js"></script>
</head>
<body>

<script type="text/javascript">
    var dvs = new DVS({
        userId: "test@example.com",
        clientId: "{{ ClientID }}",
        redirectURI: "http://127.0.0.1/login",
        pinPolicy: "same"
    });

    dvs.init(function () {
        dvs.sign({
            doc: "This is a test document for signing",
            hash: "a85675951451ebbcccb4c4d1a41dfe6cbf0f037ef505ffccd3d314930b3d7316",
            timestamp: 1608300866
        }, function success(signature) {
            console.log(signature);
        }, function fail(error){
            console.error(error);
        });
    });
</script>

</body>
</html>

<!DOCTYPE html>
<html>
<head>
<title>DVS Different PINs</title>
<link rel="stylesheet" type="text/css" href="https://cdn.mpin.io/dvs/css/dvs.css" media="screen"/>
<script type="text/javascript" src="https://cdn.mpin.io/dvs/dvs.client.min.js"></script>
</head>
<body>

<script type="text/javascript">
    var dvs = new DVS({
        userId: "test@example.com",
        clientId: "{{ ClientID }}",
        redirectURI: "http://127.0.0.1/login",
        pinPolicy: "different"
    });

    function signExample() {
        console.info("Start signing");

        dvs.sign({
            doc: "This is a test document for signing",
            hash: "a85675951451ebbcccb4c4d1a41dfe6cbf0f037ef505ffccd3d314930b3d7316",
            timestamp: 1608300866
        }, function success(signature) {
            console.info("Successful signature:");
            console.log(signature);
        }, function fail(error){
            console.error(error);
        });
    }

    dvs.init(function () {
        dvs.hasIdentity(function success() {
            signExample();
        }, function fail() {
            console.info("Start registration");

            dvs.createIdentity(function success(data) {
                console.info("Successful registration:");
                console.log(data);

                signExample();
            }, function fail(error) {
                console.error(error);
            });
        });
    });
</script>

</body>
</html>

Signature Verification

Signature verification is done by making a request to the /dvs/verify endpoint of the MIRACL Trust platform from your backend. If the verification is successful you will receive a certificate digest in the response.

API Reference

  • POST https://api.mpin.io/dvs/verify
Authorization: "Basic <base64(clientId:clientSecret)>"

Payload:
{
    signature: {
        hash: string,
        mpinId: string,
        publicKey: string,
        dtas: string,
        u: string,
        v: string
    },
    timestamp: string,
    type: string
}

Response:
{
    certificate: string
}