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:
- Integrate the DVS JS Client library in your web frontend and/or integrate the Android/iOS SDK in your mobile application.
- 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.
- Invoke the sign method of the library/SDK to produce the signature.
- 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
}