How can we help?

Using vSEC:CMS User Application with Browser and Scripts

Anders Adolfsson - Versasec
Anders Adolfsson - Versasec
  • Updated

Introduction

From version 6.10 it will be possible to trigger self-service workflows from a browser or a script. It will be possible to trigger the following flows:

  • Issuance
  • Reissue of certificate(s)
  • Change PIN
  • Unblock
  • Update credential.

Using Windows support for URL protocols, the vSEC:CMS Application will register the protocol as part of the installation process. Then it will be possible to trigger these flows using the registered protocol. 

This article will provide very simple examples of how you can implement these flows. For more advanced flows please contact Versasec support.

How to Implement

vSEC:CMS User application needs to be installed on the client where you wish to trigger the flows from. vSEC:CMS User application registers a custom URI handler named cmsuss:// that the application will listen for. For each of the possible flows available, a JSON object needs to be constructed and passed into the URI handler. The JSON object will need to be base64URL encoded.

Issuance

For triggering issuance flow the following parameters can be used to construct a JSON object:

Parameter Name Description
URL cmsuss://issue/v1
Options This is a bit mask value that can be used for debugging purposes when the flow is not working for some reason. Default value is 0 which means the error dialog will not be shown. Set the value to 1 if you want to see error dialog with more details shown if errors occur.
MsgOptions Decimal value to always show popup dialog that is always on top. The value should be 1281. 
TemplateId Predefined template ID in decimal that is to be used for issuance. This value can be retrieved from Templates - Card Templates and selecting the template you want to use and click View. Then take the Template ID and convert the hexadecimal value to decimal. 
UserId Predefined user ID for issuance. This needs to be the user's DN.

For example, the JSON object could look like below:

{
"Options": 0,
"MsgOptions": 1281,
"TemplateId": 131081,
"UserId": "CN=Joe Bloggs 2,CN=Users,DC=vs,DC=local"
}

You should then base64URL encode the JSON object and pass this into the URL. For example, the URL would look similar to below. Just copy and paste the URL into a browser to try.

cmsuss://issue/v1/ew0KIk9wdGlvbnMiOiAwLA0KIk1zZ09wdGlvbnMiOiAxMjgxLA0KIlRlbXBsYXRlSWQiOiAxMzEwODEsDQoiVXNlcklkIjogIkNOPUpvZSBCbG9nZ3MgMixDTj1Vc2VycyxEQz12cyxEQz1sb2NhbCINCn0
Untitled.png

Reissuance of Certificate(s)

For triggering reissuance flow the following parameters can be used to construct a JSON object:

Parameter Name Description
URL cmsuss://reissue/v1
MsgOptions Decimal value to always show popup dialog that is always on top. The value should be 1281. 
Flags

Integer value which should be set to 1 to reissue all certificates issued to the credential. Enter 2 if you want to issue a specific certificate on the credential.

Params If 2 is set as the Flags parameter then enter the decimal value of the certificate template that you want to issue. You can get the certificate template ID from Repository - Smart Cards and select an entry that you want to do this flow with. Click the Details button. In the Certificate(s) section you will see the decimal and hexadecimal value. Enter the decimal value for the Params.

For example the JSON object could look like below:

{
"MsgOptions": 1281,
"Flags": 1
}

You should then base64 encode the JSON object and pass this into the URL. For example, the URL would look similar to below. Just copy and paste the URL into a browser to try.

cmsuss://reissue/v1/ew0KIk1zZ09wdGlvbnMiOiAxMjgxLA0KIkZsYWdzIjogMQ0KfQ

Change PIN

For triggering change PIN flow the following parameters can be used to construct a JSON object:

Parameter Name Description
URL cmsuss://changepin/v1
MsgOptions Decimal value to always show popup dialog that is always on top. The value should be 1281. 
ReaderName

Optionally you can enter the name of the specific reader that the credential is expected to be inserted into. For example, you can get the reader name using the Windows command: 

certutil -scinfo

For example, the JSON object could look like below:

{
"MsgOptions": 1281
}

You should then base64URL encode the JSON object and pass this into the URL. For example, the URL would look similar to below. Just copy and paste the URL into a browser to try.

cmsuss://changepin/v1/ew0KIk1zZ09wdGlvbnMiOiAxMjgxDQp9

Unblock PIN

For triggering unblock PIN flow the following parameters can be used to construct a JSON object:

Parameter Name Description
URL cmsuss://unblockpin/v1
MsgOptions Decimal value to always show popup dialog that is always on top. The value should be 1281. 
ReaderName

Optionally you can enter the name of the specific reader that the credential is expected to be inserted into. For example, you can get the reader name using the Windows command: 

certutil -scinfo

For example, the JSON object could look like below:

{
"MsgOptions": 1281
}

You should then base64URL encode the JSON object and pass this into the URL. For example, the URL would look similar to below. Just copy and paste the URL into a browser to try.

cmsuss://unblockpin/v1/ew0KIk1zZ09wdGlvbnMiOiAxMjgxDQp9

Update Credential

For triggering credential update flow the following parameters can be used to construct a JSON object:

Parameter Name Description
URL cmsuss://updatecard/v1
MsgOptions Decimal value to always show popup dialog that is always on top. The value should be 1281. 
ReaderName

Optionally you can enter the name of the specific reader that the credential is expected to be inserted into. For example, you can get the reader name using the Windows command: 

certutil -scinfo

For example, the JSON object could look like below:

{
"MsgOptions": 1281
}

You should then base64URL encode the JSON object and pass this into the URL. For example, the URL would look similar to below. Just copy and paste the URL into a browser to try.

cmsuss://updatecard/v1/ew0KIk1zZ09wdGlvbnMiOiAxMjgxDQp9

Simple HTML Example

In this section we will provide a very simple example of how you could construct a HTML page to be used to trigger an issuance flow from a browser. We used the sample JSON object from Issuance section above for this example. Copy and paste the code below and save as a .html file and launch it from a browser. 

<!doctype html>
<html>
<head>
<title>vSEC:CMS User Application URL Launcher Simple Example</title>
</head>
<body>
<center>
<h1>vSEC:CMS User Application URL Launcher Simple Example</h1>
<table>
<tr>
<td></td>
<td>
<input type="button" name="bt" id="btProcess" value="Issuance"
onclick="process_it()" style="height:50px;width:200px">
</td>
</tr>
</table>
</center><pre><div id="content"></div></pre>
</body>
</html>

<script>
function process_url(msg, url)
{
document.getElementById("content").innerHTML = msg;
if(!confirm(msg))
{
return;
}
window.location.href=url;
document.getElementById("btProcess").disabled = true;
document.getElementById("btCardTemplate").disabled = true;

var seconds = 10;
var countdown = setInterval(function() {

seconds--;
document.getElementById("btProcess").value = "Wait "+seconds+"...";
document.getElementById("btCardTemplate").value = "Wait "+seconds+"...";

if (seconds <= 0)
{
clearInterval(countdown);
process_reset_ui();
}
}, 1000);
}

function process_it()
{
var url="cmsuss://issue/v1/" + "ew0KIk9wdGlvbnMiOiAwLA0KIk1zZ09wdGlvbnMiOiAxMjgxLA0KIlRlbXBsYXRlSWQiOiAxMzEwODEsDQoiVXNlcklkIjogIkNOPUpvZSBCbG9nZ3MgMixDTj1Vc2VycyxEQz12cyxEQz1sb2NhbCINCn0";
var msg = "Launch URL Param\r\n--------------------\r\n";
process_url(msg, url);
}
</script>

For more advanced examples and queries please contact Versasec Support.