EWC must be set up and released according your configuration
EWC has to be initialized first before its API functions use. This first step is required to start the smart card/reader event notifications, read the specific configuration and initialize the low level components.
The function init in the EWC API must be called to reach that goal.
When no more calls to the API are required, EWC must be disposed to released all resources handled by EWC and the low level components.
The function dispose in the EWC API must be called to reach that goal.
In your JavaScript file, you have to define two functions to be called for initialization and disposal:
function initialize( ) {
enex.init( null, null, null, onHardwareChange );
}
function finalize( ) {
enex.dispose( );
}
// Initialize the EWC library when the web page loading is over
window.onload = function( ) { initialize( ); }
// Finalize the EWC library when the web page is closed
window.onunload = function( ) { finalize( ); }
The init function is very rich. Here is an overview of the parameters of this function.
The reader configuration is mainly used for Sign-What-You-See operation. This JSON structure describes the primitives, currencies and templates used during the SWYS operations. If you do not provide a reader configuration the following configuration is used.
Here is a generic example of a reader configuration that you can use.
var readerConfiguration = ({
"currencies" : { "EUR" : "978", "USD" : "840",
"GBP" : "826", "BRL" : "986",
"ARS" : "032", "SEK" : "752",
"Other" : "999" },
"primitives" :
{
"INPUT_FURTHER_INPUTS" : { "type" : "ID", "tag" : "DF43",
"min_length" : 3, "max_length" : 11 },
"INPUT_CHALLENGE" : { "type" : "IDG", "tag" : "9F37",
"min_length" : 0, "max_length" : 8 },
"INPUT_AMOUNT" : { "type" : "DID", "tag" : "9F03",
"min_length" : 1, "max_length" : 12 },
"INPUT_ACCOUNT_NUMBER" : { "type" : "ID", "tag" : "DF03",
"min_length" : 1, "max_length" : 17 },
"INPUT_TO_ACCOUNT" : { "type" : "ID", "tag" : "DF04",
"min_length" : 1, "max_length" : 17 },
"INPUT_FROM_ACCOUNT" : { "type" : "ID", "tag" : "5A",
"min_length" : 1, "max_length" : 17 },
"INPUT_PG_BG" : { "type" : "SD", "tag" : "DF06",
"allowed_values" : {"PG" : "1", "BG" : "2"} },
"INPUT_REF_ORDER_NUMBER" : { "type" : "ID", "tag" : "DF07",
"min_length" : 1, "max_length" : 28 },
"INPUT_REFERENCE_NUMBER" : { "type" : "ID", "tag" : "DF08",
"min_length" : 0, "max_length" : 28 },
"INPUT_NUMBER_OF_PAYMENTS" : { "type" : "NID", "tag" : "C3",
"min_length" : 0, "max_length" : 12 },
"INPUT_DATE" : { "type" : "ID", "tag" : "9A",
"min_length" : 6, "max_length" : 8 },
"INPUT_CHECKSUM" : { "type" : "ID", "tag" : "DF64",
"min_length" : 0, "max_length" : 17 },
"INPUT_TIME" : { "type" : "ID", "tag" : "DF14",
"min_length" : 4, "max_length" : 4 },
"INPUT_NOT_BEFORE" : { "type" : "ID", "tag" : "DF15",
"min_length" : 6, "max_length" : 8 },
"INPUT_CURRENCY" : { "type" : "SD", "tag" : "5F2A",
"allowed_values" : "currencies" },
"INPUT_AMOUNT_WITH_CURRENCY" : { "type" : "DID", "tag" : "9F02",
"min_length" : 1, "max_length" : 12 },
"INPUT_BUY_SELL" : { "type" : "SD", "tag" : "DF17",
"allowed_values" : { "BUY" : "1", "SELL" : "2" }
},
"INPUT_IBAN" : { "type" : "ID", "tag" : "DF18",
"min_length" : 6, "max_length" : 28 },
"INPUT_LIMIT" : { "type" : "DID", "tag" : "DF19",
"min_length" : 1, "max_length" : 12 },
"INPUT_USER_ID" : { "type" : "ID", "tag" : "DF20",
"min_length" : 0, "max_length" : 17 },
"INPUT_UNITS" : { "type" : "DID", "tag" : "DF21",
"min_length" : 1, "max_length" : 12 },
"INPUT_IDENTITY_NUMBER" : { "type" : "ID", "tag" : "DF23",
"min_length" : 6, "max_length" : 17 },
"INPUT_EXTRA_CODE" : { "type" : "IDG", "tag" : "DF24",
"min_length" : 2, "max_length" : 12 },
"INPUT_QUANTITY" : { "type" : "NID", "tag" : "DF25",
"min_length" : 1, "max_length" : 11 },
"INPUT_PHONE_NUMBER" : { "type" : "ID", "tag" : "DF26",
"min_length" : 5, "max_length" : 17 },
"INPUT_DATA" : { "type" : "ID", "tag" : "DF71",
"min_length" : 1, "max_length" : 17 },
"INPUT_DATA_2" : { "type" : "ID", "tag" : "DF72",
"min_length" : 1, "max_length" : 17 },
"INPUT_DATA_3" : { "type" : "ID", "tag" : "DF73",
"min_length" : 1, "max_length" : 17 },
"INPUT_DATA_4" : { "type" : "ID", "tag" : "DF74",
"min_length" : 1, "max_length" : 17 },
"INPUT_DATA_5" : { "type" : "ID", "tag" : "DF75",
"min_length" : 1, "max_length" : 17 },
"INPUT_DATA_6" : { "type" : "ID", "tag" : "DF76",
"min_length" : 1, "max_length" : 17 },
"INPUT_DATA_7" : { "type" : "ID", "tag" : "DF77",
"min_length" : 1, "max_length" : 17 },
"INPUT_DATA_8" : { "type" : "ID", "tag" : "DF78",
"min_length" : 1, "max_length" : 17 },
"INPUT_DATA_9" : { "type" : "ID", "tag" : "DF79",
"min_length" : 1, "max_length" : 17 },
"INPUT_DATA_10" : { "type" : "ID", "tag" : "DF7A",
"min_length" : 1, "max_length" : 17 },
"INPUT_Passcode" : { "type" : "ID", "tag" : "DF1C",
"min_length" : 0, "max_length" : 17 },
"INPUT_DUE_DATE" : { "type" : "ID", "tag" : "DF37",
"min_length" : 6, "max_length" : 8 },
"INPUT_LOGIN_CODE" : { "type" : "ID", "tag" : "DF38",
"min_length" : 0, "max_length" : 17 },
"INPUT_TOTAL_AMOUNT" : { "type" : "DID", "tag" : "DF39",
"min_length" : 1, "max_length" : 12 },
"INPUT_VALID_UNTIL" : { "type" : "ID", "tag" : "DF40",
"min_length" : 6, "max_length" : 8 },
"INPUT_TO_DATE" : { "type" : "ID", "tag" : "DF41",
"min_length" : 6, "max_length" : 8 },
"INPUT_FROM_DATE" : { "type" : "ID", "tag" : "DF42",
"min_length" : 6, "max_length" : 8 },
"MESSAGE_INTERNATIONAL_PAYMENT" : { "type" : "MD", "tag" : "BF11" },
"MESSAGE_BUY_SELL_SHARES" : { "type" : "MD", "tag" : "BF12" },
"MESSAGE_NEW_PHONE_NUMBER" : { "type" : "MD", "tag" : "BF13" },
"MESSAGE_NEW_PG_BG" : { "type" : "MD", "tag" : "BF14" },
"MESSAGE_CONFIRM_PROTECT_FILE" : { "type" : "MD", "tag" : "BF15" },
"MESSAGE_CONFIRM_AGREEMENT" : { "type" : "MD", "tag" : "BF16" },
"MESSAGE_PG_BG_PAYMENT" : { "type" : "MD", "tag" : "BF17" },
"MESSAGE_NEW_BENEFICIARY" : { "type" : "MD", "tag" : "BF18" },
"MESSAGE_LOGIN" : { "type" : "MD", "tag" : "BF19" },
"MESSAGE_PAYMENT" : { "type" : "MD", "tag" : "BF1A" },
"MESSAGE_TRANSFER" : { "type" : "MD", "tag" : "BF1B" },
"MESSAGE_SIGNING" : { "type" : "MD", "tag" : "BF1C" },
"MESSAGE_AUTHENTICATE" : { "type" : "MD", "tag" : "BF1D" },
"MESSAGE_CONFIRM_ASSIGNMENT" : { "type" : "MD", "tag" : "BF1E" },
"MESSAGE_CONFIRM_ADDRESS_CHANGE" : { "type" : "MD", "tag" : "BF1F" },
"FREE_TEXT" : { "type" : "E0", "tag" : "E0" },
"HIDDEN_TEXT" : { "type" : "E1", "tag" : "E1",
"min_length" : 1, "max_length" : 127 }
},
"templates" :
{
"0" : [
[ "INPUT_FURTHER_INPUTS" ],
[ "SIGN", "BUY", "LOGIN" ] ],
"1" : [
[ "INPUT_USER_ID" ],
[ "LOGIN" ] ],
"2" : [
[ "INPUT_Passcode" ],
[ "LOGIN" ] ],
"3" : [
[ "INPUT_IDENTITY_NUMBER" ],
[ "LOGIN", "SIGN" ] ],
"4" : [
[ "INPUT_EXTRA_CODE" ],
[ "LOGIN", "SIGN", "BUY" ] ],
"5" : [
[ "INPUT_REFERENCE_NUMBER" ],
[ "LOGIN", "SIGN", "BUY" ] ],
"6" : [
[ "INPUT_DATA" ],
[ "LOGIN", "SIGN", "BUY" ] ],
"7" : [
[ "MESSAGE_NEW_BENEFICIARY", "INPUT_ACCOUNT_NUMBER" ],
[ "SIGN" ] ],
"8" : [
[ "MESSAGE_NEW_PHONE_NUMBER" , "INPUT_PHONE_NUMBER" ],
[ "SIGN" , "BUY" ] ],
"9" : [
[ "INPUT_AMOUNT" ],
[ "SIGN" , "BUY" ] ],
"10" : [
[ "INPUT_TO_ACCOUNT" , "INPUT_AMOUNT" ],
[ "SIGN" ] ],
"11" : [
[ "MESSAGE_NEW_BENEFICIARY" ],
[ "SIGN" ] ],
"12" : [
[ "MESSAGE_CONFIRM_ADDRESS_CHANGE" ],
[ "SIGN" ] ],
"13" : [
[ "INPUT_CURRENCY", "INPUT_AMOUNT_WITH_CURRENCY" ],
[ "SIGN" , "BUY" ] ],
"14" : [
[ "INPUT_NUMBER_OF_PAYMENTS", "INPUT_TOTAL_AMOUNT" ],
[ "SIGN" ] ],
"15" : [
[ "MESSAGE_INTERNATIONAL_PAYMENT", "INPUT_IBAN", "INPUT_CURRENCY", "INPUT_AMOUNT_WITH_CURRENCY" ],
[ "SIGN" ] ],
"16" : [
[ "MESSAGE_CONFIRM_AGREEMENT", "INPUT_REFERENCE_NUMBER", "INPUT_DATE" ],
[ "SIGN" , "BUY" ] ],
"17" : [
[ "MESSAGE_CONFIRM_PROTECT_FILE", "INPUT_CHECKSUM" ],
[ "SIGN" ] ],
"18" : [
[ "MESSAGE_CONFIRM_PROTECT_FILE", "INPUT_CHECKSUM", "INPUT_TOTAL_AMOUNT" ],
[ "SIGN" ] ],
"19" : [
[ "MESSAGE_BUY_SELL_SHARES", "INPUT_BUY_SELL", "INPUT_AMOUNT" ],
[ "SIGN" ] ],
"20" : [
[ "MESSAGE_BUY_SELL_SHARES", "INPUT_BUY_SELL", "INPUT_QUANTITY" ],
[ "SIGN" ] ],
"21" : [
[ "MESSAGE_BUY_SELL_SHARES", "INPUT_BUY_SELL", "INPUT_QUANTITY", "INPUT_LIMIT", "INPUT_TO_DATE" ],
[ "SIGN" ] ],
"22" : [
[ "INPUT_ACCOUNT_NUMBER" ],
[ "SIGN" ] ],
"23" : [
[ "MESSAGE_PG_BG_PAYMENT", "INPUT_ACCOUNT_NUMBER", "INPUT_REFERENCE_NUMBER", "INPUT_AMOUNT" ],
[ "SIGN" ] ]
}
}
);
The purpose of this callback is accept or reject a reader or a smart card. If you accept the hardware then EWC will employ it. If you reject the hardware, EWC just ignore it.
The principle is simple. As incoming argument, the reader name and the smart cart Answer To Reset (ATR) information are provided. The callback function have to analyse the information and decide if the hardware is compatible or not with the future operations. The callback returns "true" to accept or "false" to reject the hardware.
function card_filter( reader_name, atr ) {
if( ( reader_name == "MySpecificReader ) && ( atr == "1234567890" ) ) {
// Accept to use this reader with this smart card
return true;
}
// And reject any other
return false;
}
This callback can be provided to perform an action each time a smart card is inserted and accepted. When the callback is invoked a "Connection" object is provided as argument. From this object the callback is able to operate.
This callback is not invoked if your reader/smart does not respect the filter provided by the 'hardware filter callback'.
This callback is not invoked if the connection to the smart card is not possible.
function connection_callback( connection ) {
// Perform a CAP operation each time the smart card is inserted
connection.cap_mode1(cap_callback, "11223344", "10000", "SEK");
}
This callback can be provided to be notified each time a hardware event occurs.
The following events are used:
function onHardwareChange( a_Event, a_ReaderName, a_SmartCardATR ) {
var sMsg = "";
switch( a_Event ) {
case "CARD_IN":
sMsg += "A smart card with the ATR ";
sMsg += a_SmartCardATR;
sMsg += " is inserted in the reader ";
sMsg += a_ReaderName;
break;
case "CARD_OUT":
sMsg += "The smart card is withdrew from the reader ";
sMsg += a_ReaderName;
break;
case "CARD_MUTE":
sMsg += "The smart card inserted into the ";
sMsg += a_ReaderName;
sMsg += " reader is MUTE !!!";
break;
case "READER_IN":
sMsg += "The reader ";
sMsg += a_ReaderName;
sMsg += " is inserted on your system";
break;
case "READER_OUT":
sMsg += "The reader ";
sMsg += a_ReaderName;
sMsg += " is withdrew from your system";
break;
default:
sMsg += "UNKNOWN EVENT ";
sMsg += a_Event;
break;
}
alert( sMsg );
}
This callback can be provided to be notified when the SConnect licence verification fails. Because EWC is based on SConnect, you will not be able to operate without a valid licence.
function onLicenceVerificationFailed( ) {
alert( "SConnect licence verification failed" );
}
The SConnect browser extension must be installed on the card holder's browser to provide to EWC the access to the PCR. The installation is driven directly by SConnect from the on-line banking server. You have to provide the URLs to access the images, EULA, FAQ, extensions and web pages to guide the card holder during the installation.
All paths must be absolute URL (for example "https://127.0.0.1/addons" and not relative as "/addons") but the license path which is relative.
The server configuration is composed of different URLs:
var serverConfiguration = {
extPath : "https://127.0.0.1/sconnect/extensions/",
addonPath : "https://127.0.0.1/sconnect/addons/",
imgPath : "https://127.0.0.1/sconnect/images/",
eulaPath : "https://127.0.0.1/sconnect/eula/",
faqPath : "https://127.0.0.1/sconnect/faqs/",
licensePath : "/sconnect.lic",
};
During the licence verification, SConnect displays a dialog box showing the verification progress.
You show or hide this dialog box using the "showValidationMessage" flag.
EWC provides a GUI to warm the card holder when PCR or smart card are required or an error occurs.
You show or hide the EWC GUI using the "enableGUI" flag.
You can provide a custom dialog box to replace the EWC default one when the library needs to interact with the card holder.
To overwrite the default GUI, you have to provide an object with two properties:
var callbackDialog = {
open : function displayMessage( a_Message ) {
var title = document.getElementById( "ModalTitle" );
title.innerHTML = "Warning";
var message = document.getElementById( "ModalMessage" );
message.innerHTML = a_Message;
$( '#myModal' ).modal( );
},
close : function( ) {
$('#myModal').modal( 'hide' );
}
You can provide a callback to be noticed and react when the installation is required.
var installationStatusCallback = {
success: function () {
// The SConnect and PCSC add-ons has been successfully installed. EWC is ready to be used
},
failure: function (code, info) {
// The SConnect and PCSC add-ons has not been installed or an update is available.
//
}
};
This the last parameter of the "init" function.
When EWC is not more needed, you have to dispose it to release all resources allocated.
In your JavaScript file, you have to call the dispose function.
function finalize( ) {
enex.dispose( );
}