-
WebIdentity Developer Guide v5.
-
© Copyright 2007 Eutronsec Spa - Via Gandhi, 12 - 24048 Treviolo (BG) – Italy. All rights reserved: The trade names of the products mentioned herein are brand-names belonging to the rightful owners.
-
-
Table of contents 1 PREFACE ................................................................................................................................................................. 7 1.1 ABOUT THIS MANUAL .......................................................................................................................................... 7 1.2 ENVIRONMENTS SUPPORTED BY VERSION 5.0 ...................................................................................................... 7 1.
-
SERVER ......................................................................................................................................................................... 27 RESPONSE COMPUTATION ............................................................................................................................................. 27 READPIN ..............................................................................................................................................................
-
COMMAND EXECUTION CONTROL .................................................................................................................................. 37 CMDRESULT .................................................................................................................................................................... 37 IT ENABLES CONTROLLING AND EXTRACTING THE STATUS AND THE RETURN VALUES OF THE REMOTE COMMAND. ...... 37 SERVER ...............................................................
-
1 Preface This chapter describes the contents and the lay-out of this manual and of WebIdentity distribution. 1.1 About this manual This manual describes the WebIdentity product, its operation, its integration into web services and client/server applications.
-
• Names of classes and objects • File names The font is used for: • • • 1.6 Product names Company names Registered Trademarks Interrelated Documents Here follows the list of further documentation relating to WebIdentity: EUTRON, “WebIdentity API Reference”, 2007 Reference for the programmer of WebIdentity-related applications. EUTRON, “WebIdentity Java Developer Documentation”, 1998 Electronic guide for the Java developer of WebIdentity in JAVADOC format.
-
1.6.2 Documentation The following documentation is enclosed with WebIdentity: EUTRON, “WebIdentity Developer Guide”, 2007 Manual for the WebIdentity programmer. EUTRON, “WebIdentity API Reference”, 2007 Reference for the programmer of WebIdentity-related applications. EUTRON, “WebIdentity Java Developer Documentation”, 1998 Electronic guide for the Java developer of WebIdentity in JAVADOC format.
-
1.6.3 Distribution The CD-ROM that is supplied with the WebIdentity SDK contains all necessary software for using and developing web-based and client/server applications with WebIdentity use. 1.7 Feedback The quickest way for getting in touch with EUTRON as regards WebIdentity is sending an email message to the helpdesk: helpdesk@eutronsec.it For any commercial contact it is possible to send an email message to the following address: info@eutronsec.it.
-
2 INTRODUCTION WebIdentity is a USB device which enables the remote identification of a user in a secure way. The software components that are available with WebIdentity enable integrating the token features into web-based applications. Eutron WebIdentity originated with the intention of making an Internet service user identifiable univocally and guaranteeing access to information contained in the website only and exclusively to the user in possession of a personal hardware device.
-
WebIdentity represents the ideal hardware & software solution: • for Strong Authentication of web-based service users • for managing protected transactions over the Internet network 2.4 Fields of application The typical WebIdentity user is anybody interested in the protection of web services, that is in protecting access to reserved information and services that are available via a web server.
-
2.8 Remote control This feature enables carrying out the reading and writing operation on the WebIdentity remote device. To this end a protocol based on challenge/response has been developed which enables exchanging data (reading and writing of the remote Token) from the client ActiveX to the server ActiveX securely, that is, ensuring confidentiality, integrity and non-replicability of data. This function enables storing on the token any kind of information which might concern the user or the service.
-
3 Requirements To work properly the WebIdentity product requires the processing environment to meet some minimum requisites in terms of installed hardware and software. The requisites are divided into two distinct parts concerning the client and the server. 3.1 Client With Microsoft Windows the client component is realized with an ActiveX for Windows Explorer and with a Plug-In for Mozilla Firefox. This is the list of environments supported by the software 5.
-
3.3 Compatibility between 5.0 and 4.0 versions The following table sums up the availability or non availability of the support between different software versions on the client and servers side and tokens in use. Server 5.0 Server 4.0 WebIdentityDL with Client 5.0 Supported NOT supported WebIdentityDL with Client 4.0 NOT supported NOT supported WebIdentity3P with Client 5.0 Supported Supported WebIdentity3P with Client 4.
-
4 Installation and Configuration Using WebIdentity requires installing and configuring two different modules: the client and the server. For each system specific software components to install and configure are provided. 4.1 Client WebIdentityDL operation on the client requires the installation of a software component: in Windows environment for the Explorer browser it will be an activex, in all other cases it will be a plug-in.
-
4.1.3 EXPLORER USERS IN POSSESSION OF A WEBIDENTITY3P DEVICE For being able to use WebIdentity3P the user needs to install the driver (had it not been previously installed) by using the WIDriverInstaller.exe setup. The setup must be carried out by administrator-level users. The driver is not signed, therefore the user will have to answer affirmatively to the request for installation of a non-signed driver. After installing the driver the user can use the device as a WebIdentityDL user. 4.1.
-
it and run it by double-clicking the packet file wicli.pkg in order to start the installation; then follow the wizard's instructions for completing it. 4.1.9 ADMINISTRATOR’S PERMITS FOR INSTALLATION With Microsoft Windows NT/W2K/XP, Linux and Mac OS X it is necessary to have administrator’s privileges for carrying out the installation of the client component.
-
5 Features This chapter describes the content and the features provided by WebIdentity for integrating with web-based and clientserver applications. 5.1 Integrated features The WebIdentityDL device is a secure, portable and user-friendly hardware key with USB interface. The device is characterized by the following technical specifications: • compliant with the USB specifications (Universal Serial Bus) v2.0 low speed devices and HID 1.11.
-
On this key a good part of data is assigned to an eeprom memory which, even if external to the processor, is encrypted with a key contained in the processor internal memory space. This makes reading the eeprom memory useless as the cryptography key is not revealed. It is also impossible to clone it because each WebIdentity3P device has a cryptography key which resides on the processor-internal memory partition and is different for each device. 5.
-
HASH+AES - SERVER SECRET - USER-ID Label - User Data - Token Serial Number AES KEY USER-ID Figure 5.
-
5.2.1 Server Secret The protection model offered by WebIdentity includes the use of one unique secret termed Server Secret (inside the WebIdentity SDK it is termed Server Password). The Server Secret is used during WebIdentity’s processing for authentication, cryptography and remote control on the server side; it is also used during the initialization phase relating the WebIdentity hardware devices.
-
5.3 Operation For operating properly it is necessary to structure a website in such a manner as to be able to manage the following. When a user is connecting to a protected web area, the WebIdentity Server requires the insertion of the device in the client machine in order to verify the information contained therein. The operation is carried out with a Challenge/Response protocol which enables authenticating the client without the information contained in the token being transferred through the network.
-
(1) Request for Challenge (2) Return Challenge Get Response Computer (5) (3) Server R se on p es + s ma ke d e Us r-I D ) (4 Response = AES( challenge, AES-key ) Figure 5.3 – Sequence Challenge/Response for authentication operation 1. In the first phase the client (browser) sends an http request to the web server (get, post). 2. The web server responds to the request by generating a challenge which is sent to the client. 3.
-
Client AES-Key Server User-Id Challenge Hashing Server Secret AES AES Client Response Server Response Figure 5.4 – Procedure for client authentication The challenge is generated by the ActiveX of the server and is termed Random Session String. The Random Session String can depend on the time, on an id-session which typically all application servers make available for identifying the session, and on a string which, if present, contributes to the generation of the Random Session String.
-
1 function SendPIN() { document.WIDrvCli.RndSessionString = 2 "<%= Session("SessionString") %>" 3 document.WIDrvCli.Label = "<%= Application("wi_Label") %>" 4 document.WebIdData.PIN.value = document.WIDrvCli.ReadPin(); // Send PIN to server document.WebIdData.submit(); 5 } • 1. Client-side JavaScript function used for the generation and forwarding of the response that is called for by the login page following an authentication attempt.
-
3. Call of DecryptPIN method of the server ActiveX for decrypting the response sent by the client and returned by the call to Request.Form("PIN"). As illustrated in figure 5.4 the server computes the response with the User-Id and the Server Secret again. If the verification is successful the User-Id is stored in the PIN variable of the server ActiveX. 4.
-
5.5 Cryptography With WebIdentity it is possible to execute web page encryption; in particular it is possible to encrypt single items of information both from the server towards the client and vice versa.
-
Figure 5.
-
5.5.1 Example – cryptography from server to client The following example illustrated the essential steps to take for integrating the WebIdentity cryptography into a webbased application with ASP; the following example shows the passage of an encrypted data from the server to the client; only the parts that are strictly necessary for describing the operation are reported hereunder; a complete example is provided at section Errore. L'origine riferimento non è stata trovata..
-
Function Method Description Component Server side encryption Crypt Encryption with the use of Random Session String, of Server Secret and User-Id which the confidential data is to be sent. Server Server side decryption Decrypt Decryption with the use of Random Session String, of Server Secret and User-Id which the confidential data has been received from. Server Client side encryption Crypt Encryption with use of Random Session String.
-
5.6 Remote control The remote control feature and in the case in point the possibility to read from and write on the WebIdentity token memory is carried out with simple calls to the server ActiveX methods for creating the desired command and with the call of a client ActiveX method for the actual execution of the requested command. The command and all the necessary information for execution are encapsulated inside an encrypted string by the server ActiveX and decrypted and executed by the client ActiveX.
-
The following layout illustrates the operating sequence for the remote control: WI Client WI Server Request (1) (2) (3) Execute Command Computer A) Synchronize Read Require B) C) Write + Data Re sp Command er mb u n ize ata data n o d d en hr t nc Rea writ y S r e A) mb u ) N B e C) s on Server ) (4 Figure 5.6 –Challenge/Response Sequence for remote control 1. In the first phase the client sends a request to the server. 2.
-
5.6.4 Example – writing on the remote token The following example sums up the essential steps to take for using the writing features on the remote token. Hereunder reported are the parts that are strictly necessary for the description of the operations.
-
1. Initialization of the WebIdentity client object with the Random Session String generated and sent by the server; the entry RndSessionString is a variable of the client ActiveX inside the HTML document; the Session("SessionString") entry is interpreted by the sever side and then replaced with a Random Session String. 2.
-
-
Table 5.6 – Association of software functions / methods for remote control. Function Method Description Component Read command CommitRead It enables generating the read command by stating the start position and the readable data length. Server Write command CommitWrite It enables generating the write command by stating the start position, the data length and the writable data.
-
6 Integration The integration of WebIdentity into an existing project or its adoption into a new project includes a sequence of operations to carry out for identifying the necessary points on which work is to be focused. First of all it is necessary to identify the positions inside the application where a control of the connected user identity is required and of how such a user can interact with the application.
-
• Server Secret1 – Secret of the server for security control • User Data – Identifying data of the user; for instance name, surname, etc. As described by figure 5.2 the Label, the Server Secret and the User Data are used for computing and initializing the WebIdentity token.
-
Label
User Data
User-Id