Environment setup

As described in the Proprietary authentication scheme chapter, the relationship between the in-browser JavaScript code and the SCWS service must be established using a specific Web Application Certificate provided by Idopte, and a challenge-response authentication scheme. The functions decribed below must be called before any other API methods to achieve this.

Client-side

SCWS.findService(webAppCert)

Attempts to contact the local SCWS service.

The ports on which the service can potentially be listening are scanned, and the first from which a consistent answer can be obtained is selected. When successful, the SCWS returns a challenge that must be used to compute the remote server signature, prior to calling SCWS.createEnvironment().

Arguments
  • webAppCert – A character string identifying the web application server allowed to connect to the SCWS. The string is provided by idopte and embeds the allowed origin URL and the public key used to check the server signature.

Returns

A Promise resolving to an hexadecimal string containing the random challenge.

SCWS.createEnvironment(signature)

Creates the working environment on the SCWS side. Required before any operation.

Internally calls SCWS.updateReaderList() (thus intializing the SCWS.readers array), and starts monitoring smart card reader events.

Arguments
  • signature – Hexadecimal string containing the signature of the challenge returned from SCWS.findService().

Returns

A Promise resolved when the environment is ready (the resolution value is undefined).

Below is an example usage of these functions, with the call to a specific server-side signchallenge.php script to produce the required signature:

var webappcert = "4HfLHzMS05>]T+PeNPw<X/qE2d+7^Fi4*tXK5XUSpj-5F?v220vO$U&V?<[}t1$T{SgWs]g1wFx0t^wKX88E=tBG:>Q=?r-f-mJ4nre!!s7cqOJ0/Os@Kw?HHaS>ewC+WPnDEbhxh:6MUtZIt0+D^Wa2eO?(&l.>A0MDw!JF2K0[8TM{W^[FLaq?oRb{WDRmEmo#oEoV3e<fhfH[+Cl7y)FJF0fMO28[.s=0JC@3ymR*]Zxq!{^$KgsBYg/7Ad.EHJiiea.!K@G&:H=1&T{K</+P7k]^-6GnEr*GM=?6{8Sk&w.VduRhSE!kr)QHYv$yi";
return SCWS.findService(webbappcert).then(function(challenge) {
        return new Promise(function(resolve, reject) {
                var req = new XMLHttpRequest();
                req.onreadystatechange = function () {
                if (this.readyState === 4) {
                                if (this.status === 200)
                                        resolve(req.responseText);
                                else
                                        reject(new Error("Challenge signature failed"));
                        }
                };
                req.open("GET", "signchallenge.php?rnd=" + challenge, true);
                req.send();
        }).then(function(signature) {
                return SCWS.createEnvironment(signature);
        })
});

This will return a Promise resolved once the entire environment setup operation is done.

Environments can be explicitly destroyed using the following function:

SCWS.destroyEnvironment()

Destroys the environment created by SCWS.createEnvironment().

All readers, tokens, objects obtained through this environment are invalidated, and any subsequent method call or property access on these objects may trigger undefined behavior. After the environment is destroyed, a new environment may be created again using SCWS.findService() and SCWS.createEnvironment().

Note that web applications are not mandated to destroy the environments. Environments are maintained alive within the underlying service through the event mechanism. If the web application is closed for some reason, this will be seen by the underlying service within a few minutes, and all the resources used by the environment will be automatically released.

The status of the underlying service can optionally be monitored by providing the following callback function:

SCWS.onserviceunresponsive

Callback (can be assigned to a user function) used to receive notifications when the underlying service becomes unresponsive.

This may happen when the Smart Card Manager application is closed by the user (through the menu from the system tray icon).

The web application can eventually use this event to notify the user and ask him to restart the Smart Card Manager manually. The web application can attemp reconnecting to the service by calling SCWS.findService() and SCWS.createEnvironment() again.

Server-side

The web application server must be able to produce the signature from the challenge generated by the SCWS. This can be achieved with a script on the server side. Below is an example PHP implementation of the signchallenge.php script as required by the above client-side code:

<?php
        $k = <<<EOT
-----BEGIN RSA PRIVATE KEY-----
MIIBOgIBAAJBAMPMNNpbZZddeT/GTjU0PWuuN9VEGpxXJTAkmZY02o8238fQ2ynt
N40FVl08YksWBO/74XEjU30mAjuaz/FB2kkCAwEAAQJBALoMlsROSLCWD5q8EqCX
rS1e9IrgFfEtFZczkAWc33lo3FnFeFTXSMVCloNCBWU35od4zTOhdRPAWpQ1Mzxi
aCkCIQD9qjKjNvbDXjUcCNqdiJxPDlPGpa78yzyCCUA/+TNwVwIhAMWZoqZO3eWq
SCBTLelVQsg6CwJh9W7vlezvWxUni+ZfAiAopBAg3jmC66EOsMx12OFSOTVq6jiy
/8zd+KV2mnKHWQIgVpZiLZo1piQeAvwwDCUuZGr61Ap08C3QdsjUEssHhOUCIBee
72JZuJeABcv7lHhAWzsiCddVAkdnZKUo6ubaxw3u
-----END RSA PRIVATE KEY-----
EOT;
        $output = "";
        openssl_private_encrypt(hex2bin($_GET["rnd"]), $output, openssl_pkey_get_private($k));
        echo bin2hex($output);
?>

The key included in this script represents the Proprietary authentication scheme key generated on the customer’s side, whose public key is provided to Idopte when requesting the Web Application Certificate.

Caution

Note that the above script does not check the origin of the request. This is volontary, as ensuring that the request effectively comes from a valid client is the responsibility of the web application developer, and depends on the architecture of the entire application. However, not checking the origin of the request before producing the signature is a security weakness and should be avoided. Standard methods such as cookies, or session mechanisms, can be used to solve this requirement.