Gemalto Ezio Web Connector

 

Secure PIN Entry

Use the Secure PIN Entry features provided by the reader

EWC provides a few functions to manage SPE mechanism as defined in the PC/SC specification.

You can verify or change the card holder's PIN or send command to the PCR with the API.

Note that an installed Gemalto driver is required to send SPE commands.

EWC API exposes a function for each case.

EWC provides functions to verify and change the card holder's PIN using the SPE mechanism (see the Overview page for more details).

Once EWC is initialized after a call to the "init" function, your page is able to react on smart card insertion to trigger an operation (see the "initialization" and "detection" pages for more details).

The SPE function is not exposed by the top level EWC API. When a smart card is inserted into the reader and validated as usuable, a "Connection" object is automatically created by the EWC library. The "Connection" object exposes all functions for SPE operations. The first step is to get the Connection object. A reference to this object is passed as argument to the connection callback provided in the "init" function. This reference can also be retrieve directly when the function getConnection is called.

The "Connection" object exposes the sendSPE function. Because the card holder have to operate directly with the PCR PAD, the function is asynchronous. The final result is reported to the web page by the callback provided as parameter of the function.

Note that you do not need the Gemalto driver for the PCR to operate SPE commands.

First you have to provide the feature you want to execute:

  • enex.FEATURE_VERIFY_PIN_DIRECT feature to verify the PIN
  • enex.FEATURE_MODIFY_PIN_DIRECT feature to modify the PIN
  • enex.FEATURE_CCID_ESC_COMMAND feature to send special commands to the PCR

Second you have to provide the template for the targeted feature. The template is described in the PC/SC part 10 specification. As parameter of the sendSPE function, you have to create an empty literal object and populate it with the required fields using the same defined types than for PPDU.

In your JavaScript file, first get the available "Connection" object reference.

Then prepare the verify PIN template and call the sendSPE function with enex.FEATURE_VERIFY_PIN_DIRECT feature argument to verify the PIN.

      var cnx = enex.getConnection( );
      if( !cnx ) {
        
        alert("no available connection to the smart card");
        
        return;
      }
    
      var parameters = { };
      parameters[ enex.FEATURE_PARAMETER_TIMEOUT ] = document.getElementById( "verify_timeOut" ).value;
      parameters[ enex.FEATURE_PARAMETER_TIMEOUT2 ] = document.getElementById( "verify_timeOut2" ).value;
      parameters[ enex.FEATURE_PARAMETER_FORMATSTRING ] = document.getElementById( "verify_formatingOptions" ).value;
      parameters[ enex.FEATURE_PARAMETER_PINBLOCKSTRING ] = document.getElementById( "verify_pinBlockString" ).value;
      parameters[ enex.FEATURE_PARAMETER_PINLENGTHFORMAT ] = document.getElementById( "verify_pinLengthFormat" ).value;
      parameters[ enex.FEATURE_PARAMETER_PINMAXEXTRADIGIT ] = document.getElementById( "verify_pinMaxExtraDigits" ).value;
      parameters[ enex.FEATURE_PARAMETER_ENTRYVALIDATIONCONDITION ] = document.getElementById( "verify_entryValidationCondition" ).value;
      parameters[ enex.FEATURE_PARAMETER_NUMBERMESSAGE ] = document.getElementById( "verify_numberMessage" ).value;
      parameters[ enex.FEATURE_PARAMETER_LANGID ] = document.getElementById( "verify_languageId" ).value;
      parameters[ enex.FEATURE_PARAMETER_MSGINDEX ] = document.getElementById( "verify_messageIndex" ).value;
      parameters[ enex.FEATURE_PARAMETER_TEOPROTOCOL ] = document.getElementById( "verify_teoProtocol" ).value;
      // If the data length field is not present in the template, EWC will compute the length itself from the data field
      //parameters[ enex.FEATURE_PARAMETER_DATALENGTH ] = document.getElementById( "verify_dataLength" ).value;
      parameters[ enex.FEATURE_PARAMETER_DATA ] = document.getElementById( "verify_data" ).value;
      

var resultCallback = {
  
  success : function( a_oDataOut ) {
    
    alert("Operation succeeded - Data (" + a_oDataOut + ")" );
  },

  failure : function( a_oErrorObject ) {
  
    alert("Operation FAILED. Error code (" + a_oErrorObject.errorCode + "). Error message (" + a_oErrorObject.message + ")");
  }
  
};
  


  var cnx = enex.getConnection( );
  
  if( !cnx ) {
    
    alert("no available connection to the smart card");
    
    return;
  }
  
  try {
    
    cnx.sendSPE( resultCallback, enex.FEATURE_VERIFY_PIN_DIRECT, parameters );
  
  } catch( ex ) {

    // An exception has been thrown before the command was sent to the PCR.
    alert("Command transmission failed ! " + ex.message);
  }
                

Try it !


Click the button to verify the PIN

Insert a smart card and click the button.

            function sendModifyPIN( ) {
            
                var cnx = enex.getConnection( );
            
                if( !cnx ) {
                
                    alert("no available connection to the smart card");
                    
                    return;
                }
            
                // Build the modify PIN template
                var parameters = { };
                parameters[ enex.FEATURE_PARAMETER_TIMEOUT ] = document.getElementById( "modify_timeOut" ).value;
                parameters[ enex.FEATURE_PARAMETER_TIMEOUT2 ] = document.getElementById( "modify_timeOut2" ).value;
                parameters[ enex.FEATURE_PARAMETER_FORMATSTRING ] = document.getElementById( "modify_formatingOptions" ).value;
                parameters[ enex.FEATURE_PARAMETER_PINBLOCKSTRING ] = document.getElementById( "modify_pinBlockString" ).value;
                parameters[ enex.FEATURE_PARAMETER_PINLENGTHFORMAT ] = document.getElementById( "modify_pinLengthFormat" ).value;
                parameters[ enex.FEATURE_PARAMETER_INSERTIONOFFSETOLD ] = document.getElementById( "modify_insertionOffsetOld" ).value;
                parameters[ enex.FEATURE_PARAMETER_INSERTIONOFFSETNEW ] = document.getElementById( "modify_insertionOffsetNew" ).value;
                parameters[ enex.FEATURE_PARAMETER_PINMAXEXTRADIGIT ] = document.getElementById( "modify_pinMaxExtraDigits" ).value;
                parameters[ enex.FEATURE_PARAMETER_CONFIRMPIN ] = document.getElementById( "modify_confirmPin" ).value;
                parameters[ enex.FEATURE_PARAMETER_ENTRYVALIDATIONCONDITION ] = document.getElementById( "modify_entryValidationCondition" ).value;
                parameters[ enex.FEATURE_PARAMETER_NUMBERMESSAGE ] = document.getElementById( "modify_numberMessage" ).value;
                parameters[ enex.FEATURE_PARAMETER_LANGID ] = document.getElementById( "modify_languageId" ).value;
                parameters[ enex.FEATURE_PARAMETER_MSGINDEX1 ] = document.getElementById( "modify_messageIndex1" ).value;
                parameters[ enex.FEATURE_PARAMETER_MSGINDEX2 ] = document.getElementById( "modify_messageIndex2" ).value;
                parameters[ enex.FEATURE_PARAMETER_MSGINDEX3 ] = document.getElementById( "modify_messageIndex3" ).value;
                parameters[ enex.FEATURE_PARAMETER_TEOPROTOCOL ] = document.getElementById( "modify_teoProtocol" ).value;
                // If the data length field is not present in the template, EWC will compute the length itself from the data field
                //parameters[ enex.FEATURE_PARAMETER_DATALENGTH ] = document.getElementById( "modify_dataLength" ).value;
                parameters[ enex.FEATURE_PARAMETER_DATA ] = document.getElementById( "modify_data" ).value;
            
                try {
            
                    cnx.sendSPE( resultCallback, enex.FEATURE_MODIFY_PIN_DIRECT, parameters );
                
                } catch( ex ) {
                
                    // An exception has been thrown before the command was sent to the PCR.
                    alert("Command transmission failed ! " + ex.message);
                }
            }                
                        

Try it !


Click the button to modify the PIN