DVS Web Plugin

The MIRACL Trust DVS Web Plugin provides a secure way to digitally sign documents or data directly within a web environment. It is the standard signing method for applications that use an OIDC integration, and is particularly useful when end-user devices are registered on the MIRACL Trust domain rather than your domain. For instance, if your application runs on example.com, users attempting to log in will be redirected to example.miracl.io, where they register their device and authenticate. After successful authentication, they are seamlessly redirected back to example.com, ready to complete actions such as signing documents or transactions.

When a signature is required, the web application invokes the DVS Web Plugin’s sign method. This action launches a secure pop-up window hosted on example.miracl.io, where the end user is prompted to enter their PIN. Once entered, the system generates a cryptographic signature and the user is returned to example.com. In this way, all sensitive operations, including device registration, authentication, and signing, are managed securely on the MIRACL Trust domain, while the user experience remains anchored within your own application’s domain.

sequenceDiagram actor User Agent participant DVS_Web_Plugin as DVS Web Plugin participant RPA as Relying Party Application participant MIRACL_Trust as MIRACL Trust User Agent->>RPA: Request to sign a document/transaction RPA-->>User Agent: Return a document/transaction to be signed User Agent->>DVS_Web_Plugin: Call `sign` method DVS_Web_Plugin->>MIRACL_Trust: Open pop-up MIRACL_Trust->>MIRACL_Trust: Prompt for PIN
End user enters PIN MIRACL_Trust-->>DVS_Web_Plugin: Generate signature DVS_Web_Plugin-->>User Agent: Return signature User Agent->>RPA: Send signature RPA->>MIRACL_Trust: Request signature verification MIRACL_Trust-->>RPA: Verify signature RPA-->>User Agent: Signing complete

Relying Party Application is your application’s back end.

# Install

In order to sign documents in the browser, you must include the MIRACL Trust DVS client library served from the MIRACL Trust CDN.

<script
  type="text/javascript"
  src="https://cdn.mpin.io/dvs/1.0.0/dvs.client.min.js"></script>

# Configure

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

const dvs = new DVS({
  userId: "test@example.com", // ID of the currently logged-in user
  clientId: "<CLIENT_ID>", // Client ID for the registered platform application
  redirectURI: "http://127.0.0.1/login", // Redirect URI for the registered platform application
  allowBrowser: true, // Allow signing in browser if set to true. Default is true
  allowMobile: true, // Allow signing with mobile app if set to true. Default is true
});

# Generate Signature

After configuration, you can call the sign method. This produces a cryptographic signature of the provided document, which you can store and verify:

dvs.sign(
  {
    doc: "This is a test document for signing",
    hash: "a85675951451ebbcccb4c4d1a41dfe6cbf0f037ef505ffccd3d314930b3d7316",
    description: "A description of the document that will be signed",
    timestamp: 1608300866,
  },
  function callback(error, signature) {
    if (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.
    }

    // The signature was created successfully.
    // You can now send it to your back end for verification.
    console.log(signature);
  },
);

# Verify Signature

The signature must be verified on the back end. For more information, see Digital Signatures .