Security Classification: EIDA Toolkit v Installation and Configuration Guide

Transcription

1 Security Classification: EIDA Toolkit v2.1.0 Installation and Configuration Guide

2 Document Details Organization Emirates Identity Authority (EIDA) Document Title Document Name Date Doc Name / Ref Toolkit Installation and configuration Classification Document Type Document History Date Version Author Comments 25/7/ Logica Draft 15/8/ Logica Addressing comments from EIDA 19/8/ Logica Final Version issued for Toolkit V1. 11/11/ Logica Updated version for Toolkit V.2 23/12/ Logica Updated version for Toolkit V.2 Document Approval Version 2.1 Name Signature Date Author Confirming Changes Author name Page 2 of 21

3 Contents 1 Introduction Toolkit components Core library Java API C# API Public Data web components RemoteSM Java API Samples System Requirements Software Requirements Hardware Requirements Operating Systems Installing EIDA Toolkit SDK Installation Prerequisites Installation Steps Post-Installation Test Uninstalling EIDA Toolkit SDK Configuration of Toolkit applications Configuration of Local Secure Messaging Modules Configuration of Remote Secure Messaging (RSM) Modules Configuring Local Secure Messaging modules Configuration of Remote Secure Messaging on Client/Server applications Configuration of Remote Secure Messaging on Web components Configuration of the Toolkit on the server side Page 3 of 21

4 Table of Figures Figure 1 Uninstall Confirmation... 8 Figure 2 Start uninstall... 9 Figure 3 Uninstallation Complete... 9 Figure 4: Setup welcome screen Figure 5: Component selection Figure 6: Choose Install Location Figure 7: Downloading Java Runtime Figure 8: Java Runtime Installation Figure 9: Java Runtime Installation Complete Figure 10: Downloading.Net Framework Figure 11: Installation Details Figure 12: Installation Complete Page 4 of 21

5 1 Introduction This document contains Installation Guide for the ID card toolkit where It describes the software requirements and installation steps of the toolkit, moreover the document also explains the configurations of the different components of the toolkit. The document is organized in this structure: - Section 2 : Provides an overview of the Toolkit components - Section 3 : Provides an overview of the toolkit installation, requirements and supported operating systems - Section 4: Describes in details the toolkit installation steps - Section 5: Describes the configuration details Page 5 of 21

6 2 Toolkit components EIDA toolkit SDK components contains the below components. 2.1 Core library This library is base of EIDA toolkit SDK where all the core functions are implemented. That library consists of the main native toolkit library UAE_IDCardLib.dll and helper core libraries. 2.2 Java API In order to use EIDA toolkit with java development platform, this components wraps the core functions in a simple, object-oriented and high level class library that provides EIDA card use cases functionality. 2.3 C# API It provides the same level of Java API functionality, but based on Microsoft.Net environment in order to suite.net developers. 2.4 Public Data web components The web components are actually acting as web browsers plug-ins providing an interfaces suitable for script languages used in web pages where it is working as middle layer between the web pages that reads the card public data and the low levels toolkit libraries. For wide interoperability, there are two kinds of plug-ins; ActiveX (most probably it will be preferable for Microsoft platform) and Applet (for java platforms) 2.5 RemoteSM Java API Provides the Remote Secure Messaging for the Java API. Provides also RemoteSM web service and a web service client 2.6 Samples Java desktop sample application that demonstrate the Java API functions Public Data ActiveX sample that demonstrates the usage of the ActiveX Public Data Applet sample that demonstrates the usage of the Public Data Applet RemoteSM web application, and web service that make use of the Remote SM API Page 6 of 21

7 3 System Requirements 3.1 Software Requirements.Net Framework 3.5: required only if the user of the SDK is using.net as a development environment, using EIDA.Net API, or using Public Data ActiveX. Java Runtime Environment 1.6: required only if the user of the SDK is using Java as a development environment, using EIDA Java API, or using Public Data Applet. Internet Explorer 6 or higher: required if the user is using any of the Public Data ActiveX or Applet. 3.2 Hardware Requirements Your computer must meet or exceed the following platform and operating system requirements: - 2GB RAM MB free disk space - PC\SC complied Card reader 3.3 Operating Systems The current version of the Toolkit is designed to work on the below Operating Systems / programming languages. - Windows XP - Windows Vista - Windows 2003 Server - Windows 2008 Server - Windows 7 Page 7 of 21

8 4 Installing EIDA Toolkit SDK 4.1 Installation Prerequisites In order to save time downloading the prerequisites during EIDA toolkit SDK setup, install the following prerequisites if you already have them Java Runtime Environment 1.6 (or JRE 6) Microsoft.Net Framework v Installation Steps EIDA toolkit SDK is packaged in an easy to use setup wizard, which is self described and well guided. Follow the instructions as below. Run EIDA_SDKSetup.exe If a previous version or the same version of the toolkit SDK is already installed, the following screen will appear asking to remove the previous version of the toolkit Figure 1 Uninstall Confirmation If you click OK an uninstall dialog will appear to remove the previous toolkit version Page 8 of 21

9 Figure 2 Start uninstall Click Uninstall, the installer will automatically remove all toolkit components from your system Figure 3 Uninstallation Complete Page 9 of 21

10 Click Close to start Toolkit SDK installation wizard the setup wizard starts showing the welcome(figure 4) Figure 4: Setup welcome screen Click Next to see a screen which let you choose the components to install ( Figure 5: Component selection ). Components are described in section 2 of this document. Select the components you want to install and click Next. Page 10 of 21

11 Figure 5: Component selection Setup wizard then requests a destination folder for the components to be installed. Choose the desired location and the click Install. Figure 6: Choose Install Location The setup wizard then checks if the Java Runtime 1.6 installed, if it s not installed the wizard will start downloading it. Page 11 of 21

12 If the Java Runtime 1.6 is already installed, the setup wizard will skip this step, cancel the download and continue installation to install it later. Figure 7: Downloading Java Runtime After downloading the Java Runtime, the setup wizard will automatically launch the java runtime installation wizard. Figure 8: Java Runtime Installation Page 12 of 21

13 Follow the Java Runtime installation wizard until it s completed successfully and then click Close to get back to EIDA toolkit SDK setup wizard ( Figure 9). Figure 9: Java Runtime Installation Complete Setup wizard then checks if the.net framework v3.5 is installed, if it s not installed the wizard will start downloading it ( Page 13 of 21

14 Figure 10). If the.net framework is already installed, the setup wizard will skip this step, or cancel the download and continue installation to install it later. After downloading the.net framework the setup wizard will silently install it, and continue the toolkit installation. Page 14 of 21

15 Figure 10: Downloading.Net Framework 3.5 Figure 11: Installation Details The setup wizard will install the selected toolkit components and register components if needed displaying the installation details( Page 15 of 21

16 Figure 11). Click Next to finish, the setup wizard will display its Finish screen ( Figure 12). Page 16 of 21

17 4.3 Post-Installation Test Figure 12: Installation Complete To test if the installation has been done correctly, below tests can be run only if Samples component was selected while installation. - Go to the installation directory (e.g., C:\Program Files\EIDA Toolkit) - Navigate to Sample\Desktop - Run the file Launch.bat - EIDA Java Sample Application will start asking to select a card reader - If card reader select dialog box appears, then the installation has been done successfully 4.4 Uninstalling EIDA Toolkit SDK EIDA toolkit SDK can be uninstalled from Add/Remove programs in control panel Find the EIDA toolkit SDK then right click and select uninstall from the drip down menu, another wizard will start guiding you through the removal operation. Page 17 of 21

18 5 Configuration of Toolkit applications This section describes various configurations required to run the Test applications. 5.1 Configuration of Local Secure Messaging Modules Desktop applications use Secure Messaging modules (sm) in local mode. All sm modules will be described in the sm.cfg file as described below. The file sm.cfg contains the list of configured secure messaging modules parameters. Sm.cfg [SM_Modules] ########### SAGEM_SAM 1, SAFENET_LUNA_HSM 2, LOGICA_SOFTWARE_HSM 3 ID_SM_Name=1 PKI_SM_Name=4 MOC_SM_Name=3 4=Another_SM.dll [SAM] PIN=1234 The SM_Modules: this section contains the secure messaging modules. - The ID_SM_Name attribute refers to the secure messaging module used with the ID Applet. - The PKI_SM_Name attribute refers to the secure messaging module used with the PKI Applet. - The MOC_SM_Name attribute refers to the secure messaging module used with the MOC Applet. The value of these three attributes can be: - 1: this means that the SAGEM_SAM is used. - 2: the SAFENET_LUNA_HSM is used. - 3: the LOGICA_SOFTWARE_HSM is used. - 4,5,6,7 : another secure messaging module is used. This extra sm module is implemented on a separate DLL. For example, if the SM module used with the PKI applet is implemented on the Another_SM.dll. the PKI_SM_Name will be set to 4. Then another attribute is added under SM_Modules to reference the new sm module which means 4=Another_SM.dll. Note that the Another_SM.dll library must be located on the same directory as the UAE_IDCardLib.dll. NOTE: the section Another_SM in the DLL name Another_SM.dll could be any name for the DLL The second section [SAM] contains only the SAM PIN attribute. It is used only when a one of the three attributes XXX_SM_Name points to the SAGEM_SAM. The PIN attributes are provided by EIDA. Page 18 of 21

19 The sm.cfg file must be located on the same working directory of the desktop application or under the config folder of the working directory. Checking ID Card Genuine will be done through the function IsCardGenuine() member of the PublicDataFacade class. 5.2 Configuration of Remote Secure Messaging (RSM) Modules For using the Toolkit in remote secure messaging mode, it is mandatory to install the Toolkit on the client and server side. The client side will ensure the communication with the card and the server side will ensure the communication with the secure messaging module which can be HSM software, Safenet Luna HSM or any other sm module (except the SAM which is used in local mode only). The sm modules are configured on the server side using the sm.cfg file. Client Application Server Application EIDA Toolkit SDK EIDA Toolkit SDK The server application can be a webservice, web application based on servlets, JSPs, Struts, JSF, ASP, ASPX It is not mandatory that the client side and the server side are developed in the same programming language. For example, the client side can be developed in C# or VB.Net using the Toolkit C# API while the server side is developed in Java based on Toolkit Java API. Checking ID Card Genuine will be done through the function IsCardGenuine(SecureMessagingInterface Object) member of the PublicDataFacade class. 5.3 Configuring Local Secure Messaging modules Desktop applications can use the Toolkit in local secure messaging mode; secure messaging modules shall be configured in the file sm.cfg as described above. The sm.cfg file must be located on the same working directory of the desktop application or under the config folder of the working directory. Checking ID Card Genuine will be done through the function IsCardGenuine() member of the PublicDataFacade class. Page 19 of 21

20 5.4 Configuration of Remote Secure Messaging on Client/Server applications Enabling secure messaging modules with a server side component needs an implementation of the RemoteSecureMessaging interface. The Toolkit API contains a simple implementation of this interface which is the LogicaRemoteSMImpl class. The LogicaRemoteSMImpl class takes the IP of the server as parameter and allows performing client/server communication to enable secure messaging using HTTP protocol. Note that the toolkit allows developers to build new remote sm modules easily based on other communication protocols by implementing LogicaRemoteSMImpl. 5.5 Configuration of Remote Secure Messaging on Web components The web-components uses only remote secure messaging. The ActiveX and the Applet uses the LogicaRemoteSMImpl class that inherits from RemoteSecureMessaging. The configuration of the web-components is done on the javascipt file eida_webcomponents.js. var RemoteSM_Address = " The RemoteSM_Address defines the address of the server side application that represents the remote secure messaging module. For the Applet, the RemoteSM_Address must refer to a and not a webservice. For the ActiveX, it is possible to use the webapplication or the webservice. So, the JS parameter can be Or any other server side components address. 5.6 Configuration of the Toolkit on the server side The toolkit allows extending the SDK with new secure messaging modules. This is done by implementing the RemoteSecureMessagingInterface and wrapping it with a server side component. The Webapplication RemoteSM_WebApp and the Webservice RemoteSM_Webservice has been implemented just as sample applications to illustrate the remote secure messaging feature of the toolkit. They can be found at the <Toolkit SDK>\Samples\Webservice folder, where the <Toolkit SDK> is the installation folder of the toolkit SDK. The RemoteSM_WebApp contains 3 JSP pages, each one is dedicated to expose a specific function of the toolkit. The configuration of the webservice RemoteSM_Webservice is as follows: Page 20 of 21

21 1- Install the Toolkit SDK on the server. 2- Ensure that the Path environment variable contains the <Toolkit SDK>/Libs folder. 3- Download Tomcat and install it. 4- Ensure that the CATALINA_HOME environment variable is correctly set and point to the Tomcat folder. 5- Put the sm.config on the bin folder of Tomcat. 6- Put the UAE_IDCardJavaAPI.jar on CATALINA_HOME/shared/lib 7- Deploy the RemoteSM_WebService.war and the RemoteSM_WebApp.war to Tomcat (put them on webapps). 8- Start Tomcat from services.msc or by launching startup.bat. Page 21 of 21