Gemalto Ezio Server

ClientAPI User Guide

2

Revision history
Version Author Date Change history
Number
Added logic diagram.
Updated contents for ClientAPI version 2.9.2.
2.0 Added section 4.3, 4.4 and 4.5.
Modified Logs section.
Modified section 5.2.
3

Table of contents
1 Important ................................................................................................................................... 4
1.1 Scope......................................................................................................................................... 4
1.2 Purpose ..................................................................................................................................... 4
1.3 The icons and acronyms used in this document........................................................................ 4
1.4 What is included in the standard Client API package ............................................................... 5
1.5 References ................................................................................................................................ 5
1.6 Feedback Information ............................................................................................................... 5

2 Overview .................................................................................................................................... 6
2.1 Components .............................................................................................................................. 7

3 Before you start ......................................................................................................................... 8

3.1 Set up the client machine.......................................................................................................... 8
3.2 Set up the Certificate Authority in Ezio Server .......................................................................... 8
3.2.3 Get the CA to sign the Server Certificate Request .......................................................... 10
3.3 Create a new client in Ezio Server ........................................................................................... 11
3.4 Download the keystore from the Ezio Server .......................................................................... 12
3.5 Check connectivity .................................................................................................................. 13

4 Basic configuration ................................................................................................................... 15

4.1 Instantiate a client .................................................................................................................. 15
4.2 Set up the logs ........................................................................................................................ 19
4.3 Set up the High Availability mode ........................................................................................... 20

5 Advanced configuration ........................................................................................................... 33

5.1 Customize Client API ............................................................................................................... 33
5.2 Multiple SSL set up .................................................................................................................. 34
5.3 RSA Block for certain APIs ...................................................................................................... 41

6 Usage ....................................................................................................................................... 44
6.1 Basic usage ............................................................................................................................. 44
6.2 Sample scenario ...................................................................................................................... 45

7 Frequently asked questions ...................................................................................................... 49

Appendix A – Sample Code .............................................................................................................. 51

Appendix B – Help and support ........................................................................................................ 53

4

1 Important
1.1 Scope

This document is intended for software developers and JAVA programmers who will use
Client Application Programming Interfaces (Client APIs) to develop applications to
communicate with the Gemalto Ezio Server.

The document provides an overview of the basic concepts, programming constructs and
sample code to help programmers understand how to use the JAVA Client APIs included in
the standard Client API package for Ezio Server.

For information about the Ezio Server or related concepts, refer to the Administration Guide.

1.2 Purpose

The purpose of the document is to help software developers understand how to use the Client
API to perform various functions, and to help them get started with relative ease. Thus, the
document explains all the technical details required to set up and use Client API such as how
to create an instance, which ports to use, how to use and customize the ‘properties’ files,
configure High Availability, and how to construct a Client API program.

For the ease of understanding, the document also includes a fully-commented sample code
that demonstrates the use of Client APIs in a typical scenario - verify the OTP generated by a
token of Media Type 61.

1.3 The icons and acronyms used in this document

Acronyms Description
2FA Two-Factor Authentication
DR Disaster Recovery
E2E End to End Encryption
Gemalto Ezio A token-agnostic Authentication Server that provides multi-factor
Server/ authentication and end-to-end encryption of user credentials for
Ezio Server/ complete protection of online transactions and sensitive data.
HA High Availability
Hybrid Active-Active-Passive mode
Java Oracle Java Software (Freeware)
JDK Java Development Kit
JS JavaScript
LB Load Balance cluster, also refer to Active-Active mode.
Note Note or a tip
OTP One Time Password
RFU Reserved for future use
RMI Remote Method Invocation
SMS Short Message Service
SSL Secure Socket Layer
WAS WebSphere Application Server
5

1.4 What is included in the standard Client API package

The standard Client API package for Ezio Server includes the following:

 ClientAPI jar file

 ClientAPI release notes
 ClientAPI Javadoc

1.5 References

For additional information, refer to the resources given below:

 For better understanding about the Ezio Server, how to use it, troubleshooting and
error codes, read the Administration Guide version 1.3.
 For details about the semantics and descriptions of the Client API method calls, refer
to the Client API Javadoc.

1.6 Feedback Information

At Gemalto, we try our best to release high-quality documents. If you have any comments
about the document, or suggestions for improvement, you can contact us through email at
support.aspac.ebanking@gemalto.com. We greatly appreciate your assistance!
6

2 Overview
The Client API is a singleton Java Application Programming Interface (API) that allows your
client applications to interface with the Gemalto Ezio Server using Remote Method Invocation
(RMI) over two-way Secure Sockets Layer (SSL).

A client keystore is used to establish connection between a client application and the Ezio
Server. The client keystore is a file that stores the private key and certificates associated with
the aliases ‘user’ and ‘cacert’, respectively. The client keystore is certified by the Ezio Server,
and is downloaded from the Ezio Server.

Note:
Retain the same referencing alias even if you modify the client keystore. For example, if you consolidate
the keystores to a centralized keystore and truststore, retain the original referencing alias: user and
cacert.

The Client API library enables you to perform a variety of functions such as the following:

 Two-Factor Authentication (2FA): Client APIs such as verifyClearOTIP and

verifyClearOTIPToken can be used for 2FA. For some tokens, there are token-
specific APIs too which can be used for 2FA, for example, verifyOCRAResponse for
OCRA OTP verification.

 End-to-End (E2E) encryption: Client API can be used for E2E of passwords and
One-Time Passwords (OTPs). The passwords and OTPs are protected by RSA
encryption.

 Cryptographic operations: Client API can be used to create, import, get key value,
set default key and delete both symmetric and asymmetric keys.

 User provisioning and de-provisioning: ClientAPI can be used to create user,

update user, list user, query user, set user status, and delete user.

 Token provisioning and de-provisioning: Client API can be used to create a

variety of different tokens, list tokens, delete a token and generate OTP.

For a complete list of APIs, refer to the Client API Javadoc.

7

2.1 Components

The Client API components are shown below:

Application Ezio Server

RMI SSL Ezio Server

Client API (Two-way)
Ezio Server

client keystore

ha.properties

socket.properties

log.properties

Table 2-1: Description of Client API components

Component Description
Application A Client application.
Ezio Server Gemalto Ezio Server.
Client API A Java API for interfacing with the Ezio Server.
This is the keystore used for 2-way SSL connection. It is downloaded
Client keystore
from the Ezio Server.
Defines the HA mode: Active-Passive, Load Balancing (Active-Active), or
ha.properties Hybrid.

Unless you use the Ezio Server in a standalone mode, this file is
required to set up the Ezio Server in a High Availability mode.
socket.properties Customize properties such as ‘authentication timeout’ value and ‘retry
interval’ as per your needs.
Define Client API log level and location.
log.properties
This file is used to customize log setting.

Note:
For the default values for all properties in socket.properties and log.properties, refer to Section 4 - Basic
configuration.
8

3 Before you start

Before you start using the Client API functions, make sure you set up the client machine to
run the Client APIs, set up the Ezio Server for Client API, and check the SSL connection.

3.1 Set up the client machine

Set up the client machine to make sure that it can run the Client APIs and perform various
functions.

On the client machine,

1. Install Java Development Kit (JDK) version 5.0 or above to create and compile
programs. JDK includes JRE for running Java programs, browser pugins for applet
execution, and the compilers and tools such as JavaDoc and Java debugger.
2. Have ports available for Two-way SSL connection.
o Port 1099 for registry.
o Port 32771 for RMI server.
3. Download the Client API. jar (Client API library) provided by Gemalto.
4. Add the Client API.jar to your application library path. Some of the ways are:
o Using java command in command prompt
Java –cp .;ClientAPI.jar
o Using IDE (For instance, Eclipse)
Right click project, Properties-Java Build Path-click on Libraries
tab-Add External JARS...

3.2 Set up the Certificate Authority in Ezio Server

Set up the internal Certificate Authority (CA) in the Ezio Server to get a signed digital
certificate. The CA-signed digital certificate is used to secure connection between the client
and Ezio Server.

For details about CA, refer to the section ’Configure Certificate Authority’ in the
Administration Guide.

3.2.1 Generate the CA keypair

Generate a CA keypair for communicating with devices that rely on its certificate:

1. Log on to the Ezio Server, and then click [ADMINISTRATION > SSL Manager >
Manage CA] to access the CA management portal.
 The hyperlinks used to generate and sign the certificate request are displayed.
9

2. Click Generate CA KeyPair to generate a pair of keys at the root CA.

 The Generate CA page is displayed.

3. Enter valid values as shown above, and click Generate CA.

 Upon successful creation of CA keypair, an operation success message is displayed.

3.2.2 Generate the Ezio Server keypair and the Server Certificate Request.

Generate the Ezio Server keypair for mutual authentication.

1. Click [ADMINISTRATION > SSL Manager > Manage Server] to access the Ezio
Server management portal.
 The hyperlinks used to generate and import certificates are displayed.
10

2. Click Generate Server KeyPair to generate the server keypair.

 A Generate Server button is displayed.
3. Click Generate Server button to create the server keypair.
 Upon successful creation, an operation success message is displayed. Click OK.
4. Click [ADMINISTRATION > SSL Manager > Manage Server] to access the Ezio
Server management portal again.
5. Click Generate Cert Request to generate a server certificate request.
 A Generate Server Cert Request button is displayed.
6. Click Generate Server Cert Request button.
 Upon successful creation, an operation success message is displayed. Click OK.
7. Click Download Server Cert Request to download the certificate request file on your
PC.

3.2.3 Get the CA to sign the Server Certificate Request

Get the server certificate request signed by the CA.

1. Click [ADMINISTRATION > SSL Manager > Manage CA] to access the CA
management portal.
 The hyperlinks used to generate and sign the certificate request are displayed.

2. Click Sign Cert Request to sign the server cert request.

 You are prompted to locate the server cert request file on your PC.
3. Browse and locate the server certificate request file, and then open it.
 You are prompted to enter additional information.
11

4. Enter the validity of the server certificate (in days) and the CA key password, and
then click Sign Cert Request.
5. Click the Download Signed Certificate to download the signed server certificate on
your PC.

3.2.4 Import the CA-signed Server Certificate Request into the Ezio Server

Import the CA-signed certificate into the Ezio Server.

1. Click [ADMINISTRATION > SSL Manager > Manage Server] to access the Ezio
Server management portal.
 The hyperlinks used to generate and import certificates are displayed.

2. Click Import Signed Cert to import the signed certificate into the Ezio Server.
 You are prompted to locate the signed server certificate file.
3. Browse and locate the signed server certificate file, and then click Import Signed
Server Cert.
 Upon successful import, an operation success message is displayed. Click OK.
4. Restart the Ezio Server for the changes to take effect.

Note:
It is very important to restart the server. If you do not restart the server, you will not see the changes
in the Ezio Server.

3.3 Create a new client in Ezio Server

Any application that needs to integrate with the Ezio Server is added as a client. To use the
Client APIs, create a new client in the Ezio Server.

1. Log in to the Ezio Server, and then click [ADMINISTRATION > SSL Manager >
Manage Client > Add New Client].
 You are prompted to enter information.
12

2. Enter valid information for the new client, and then click Add.
 Upon successful creation of the new client, an operation success message is
displayed.

3.4 Download the keystore from the Ezio Server

The keystore is used to establish Two-way SSL connection between the client application and
the Ezio Server. To use Client APIs, download the keystore for the newly created client from
the Ezio Server, and then store it in your application directory.

1. Click [ADMINISTRATION > SSL Manager > Manage Client] to access the client-
related information.
13

2. Locate the newly created client, and then click [Retrieve Cert > Download] for the
client to download the keystore.
3. Save the keystore in the same location on your PC as the ClientAPI.jar program, or at
a different location.

3.5 Check connectivity

Test connectivity between the client and Ezio Server using a Java program, clientAPI.jar.
Make sure that you have JRE version 1.4 or above on the client machine to run the program.

1. Enter the following command to test the configuration:

java -classpath clientapi.jar com.client.ClientAPI <AS keystore
location> <keystore password> <IPaddress of AS server> <domain>

The parameters are described as follows:

Parameters Description
AS keystore This is the location of the file where the keystore is saved.
location
This is the password you entered when you created a new
keystore password client using ‘Add a Client’. If you didn’t enter a password while
creating the new client, use the default value, ‘123456’.
IPaddress of AS This is the IP Address of the AS Server where the client is
saved.
Server
By default, this value is set to ‘0’. To test the configuration for a
domain
different domain, enter the domain number.

 If the CA is configured properly, the output is displayed as shown below:

14

 If something is not set up properly, the output window displays the issues. For
example, if there is a connectivity issue, the output is displayed as shown below:

Note:
If you face any exceptions when connecting to the Ezio Server, refer to the clientapi.log file. The
clientapi.log is created in the same directory as the client keystore, or other location as specified in
the log.properties file.
15

4 Basic configuration
4.1 Instantiate a client

Before you invoke a method to perform a function, you must instantiate a client.

There are four types of constructors that can be used to instantiate a client. You can use any
of these constructors depending on your needs. A constructor establishes an RMI/SSL
connection between the client and Ezio Server.

To implement singleton pattern and make sure that the constructor is not accessible publicly,
getInstance(…) method is used to create an instance of Client API. For more details about the
methods, parameters and return values, refer to the Client API Javadoc included with the Ezio
server Client API package.

Any changes to the parameters (in terms of Objects/Parameters to the getInstance methods
or the properties files) will need a restart to the application that consumes ClientAPI for the
changes to take effect.

4.1.1 Default constructor

To use the default constructor, every component should be stored in the default directory - the
same directory where the client keystore is stored.

 ClientAPI.getInstance(String keyStoreLocation, String keyStoreP

assword, String ip)
 ClientAPI.getInstance(String keyStoreLocation, String keyStoreP
assword, String ip, boolean haFlag)

Table 4-1: Description of parameters for default instantiation

Parameter Description
keyStoreLocation The file location (absolute path) of the clients’ keystore.
keyStorePassword The password for client’s keystore.
ip The IP address of the Ezio Server.
The flag that indicates whether an HA mode is required.
haFlag If it is in standalone mode, set it to false
else set it to true.

4.1.2 File-based property constructor

This is a new constructor introduced since Client API version 2.8.11. It allows you to configure
the paths for each of the three properties files - ha.properties, socket.properties and
log.properties. This means that you can store the three properties files in separate locations,
and away from the keystore.
16

 ClientAPI.getInstance(String keyStoreLocation, String keyStoreP

assword, String ip,boolean haFlag, String haFilePath, String so
cketPath,String logPath)

Table 4-2: Description of additional parameters for file-based property instantiation

Parameter Description
keyStoreLocation The file location (absolute path) of the clients’ private keystore.
keyStorePassword The password for client’s private keystore.
ip The IP address of the Ezio Server.
The flag that indicates whether an HA mode is required.
haFlag If it is in standalone mode, set it to false
else set it to true.
haFilePath The customized path of ha.properties.
socketPath The customized path of socket.properties.
logPath The customized path of log.properties.

4.1.3 WAS constructor

This constructor is used for IBM WebSphere Application Server (WAS). If you are using the
IBM WAS as a client, set ‘wasFlag’ to true.

 ClientAPI.getInstance(String keyStoreLocation, String keyStoreP

assword, String ip, boolean haFlag, boolean wasFlag)
 ClientAPI.getInstance(String keyStoreLocation, String keyStoreP
assword, String ip,boolean haFlag, String haFilePath, String so
cketPath,String logPath, boolean wasFlag)

Table 4-3: Description for WAS instantiation

Parameter Description
keyStoreLocation The file location (absolute path) of the clients’ private keystore.
keyStorePassword The password for client’s private keystore.
ip The IP address of the Ezio Server.
The flag that indicates whether an HA mode is required.
haFlag If it is in standalone mode, set it to false
else set it to true.
haFilePath The customized path of ha.properties.
socketPath The customized path of socket.properties.
logPath The customized path of log.properties.
The flag that indicates whether it is a IBM WebSphere version.
wasFlag If your application server is IBM WebSphere, set it to true
else set it to false.

4.1.4 Object-oriented property instantiation

Introduced in ClientAPI version 2.9.2, this type of instantiation allows you to use the property
object instead of a property file. This is especially useful when you prefer the programming
method for the configuration of properties.

 ClientAPI.getInstance(String keyStoreLocation, String keyStoreP

assword, String ip, Properties clientProp)
17

 ClientAPI.getInstance(String keyStoreLocation, String keyStoreP

assword, String ip, Properties clientProp, boolean haFlag)
 ClientAPI.getInstance(String keyStoreLocation, String keyStoreP
assword, String ip, Properties clientProp, boolean haFlag,
boolean wasFlag)

Table 4-4: Description of client property for object-oriented instantiation

Parameter Description
keyStoreLocation The file location (absolute path) of the clients’ private keystore.
keyStorePassword The password for client’s private keystore.
ip The IP address of the Ezio Server.
The properties object from client. This contains ha.properties,
clientProp
log.properties and socket.properties.
haFilePath The customized path of ha.properties.
The flag that indicates whether it is a WebSphere version.
wasFlag If your application server is WebSphere, set it to true
else set it to false.

4.1.5 Example – How to construct a Properties object

Here is an example of code that shows how to construct a Properties object.

Table 4-5: Example of code to construct Properties object

Properties prop = new Properties ();

 Native Logging

prop.setProperty("log.level", "2");

prop.setProperty("log.location", "C:/Users/ZH/Desktop");

 Log4j Logging

prop.setProperty("log4jFlag", "true");

prop.setProperty("log4j.rootLogger", "info, FILE");

prop.setProperty("log4j.appender.FILE","org.apache.log4j.Dai
lyRollingFileAppender");

prop.setProperty("log4j.appender.FILE.DatePattern","'.'yyyy-
MM-dd");

prop.setProperty("log4j.appender.FILE.file",
"clientapi.log");

prop.setProperty("log4j.appender.FILE.layout",
"org.apache.log4j.PatternLayout");

prop.setProperty("log4j.appender.FILE.layout.ConversionPatte
rn", "[%d{MMM dd HH:mm:ss}] %-5p - %m%n");

 Active-Passive mode
18

prop.setProperty("ha.1", "192.168.168.173");

prop.setProperty("ha.2", "192.168.168.174");

 Active-Active mode

prop.setProperty("ha.1", "lbcluster1");

prop.setProperty("lb.lbcluster1.1", "192.168.168.183");

prop.setProperty("lb.lbcluster1.1.ratio", "1");

prop.setProperty("lb.lbcluster1.2", "192.168.168.184");

prop.setProperty("lb.lbcluster1.2.ratio", "1");

 Hybrid mode

prop.setProperty("ha.1", "hybrid");

prop.setProperty("lb.lbcluster1.1", "192.168.168.184");

prop.setProperty("lb.lbcluster1.1.ratio", "1");

prop.setProperty("lb.lbcluster1.2", "192.168.168.184");

prop.setProperty("lb.lbcluster1.2.ratio", "1");

prop.setProperty("ha.passive.1", "192.168.168.184");

 Socket.properties

prop.setProperty("auth.timeout", "15");

prop.setProperty("reconnect.retrytime", "120");

prop.setProperty("nolbserver.interval", "15");

prop.setProperty("getInst.retrynum", "4");

prop.setProperty("auth.multiplier", "900");

prop.setProperty("inst.multiplier", "35");

prop.setProperty("auth.sleep", "10");

prop.setProperty("method.sleep", "7");

prop.setProperty("ha.ipmonitor.interval", "15");
19

4.2 Set up the logs

By default, the ClientAPI generates a log file named clientapi.log in the same location as the
client keystore. Depending on the log level, the clientapi.log includes information about the
error logs, debug log and other critical information about the Ezio Server.

To modify the location of the clientapi.log file and other log-related information, update the
‘log.properties’ file in Client API.

There are two types of logging methods:

 Native method
 Log4j

4.2.1 Native logging

Native logging is the default method of logging. In native logging, the clientapi.log is written by
a simple Java method based on the default log level and log location. This method doesn’t
support housekeeping such as log rotation or log backup.

To configure the log level or log location for native logging, set up the ‘log.properties’ file as
follows:

Table 4-6: log.properties file

# log.properties

# Log file directory

log.location=<log path>

# Log Level
log.level=1

The log levels are described below:

 Log level ‘0’: OFF

 Log level ‘1’: ERROR. This log level displays the ClientAPI version number, property
value (if any), and other critical info related to High Availability.
 Log level ‘2’: INFO. This is the default log level. This displays the method name and
return code for each method call.
 Log level ‘3’: DEBUG. This is the most commonly displayed log. This displays each
parameter value in HEX.

Note:
For transaction related logs, please download the audit and error logs from the Gemalto Ezio Server.

Table 4-7: Log output

# Log format
Date, Message

#Sample:
Thu Jun 16 13:51:08 SGT 2011, ClientAPI Version: 2.7-production-sun-
20

static, Thread[main,5,main]
Thu Jun 16 13:51:08 SGT 2011, HA flag passed in ClientAPI: true

4.2.2 Log4j

For more flexibility and configuration options, use log4j. Log4j library offers a comprehensive
set of logging utilities for customized logging.

The syntax for log.properties is as follows:

Table 4-8: log.properties file

# log.properties

log4jFlag=true
log4jPath=<log4j properties path>

In this case, the log format depends on the log4j properties. The configuration is compatible to
Log4J configurations:

Table 4-9: Log4j configuration sample

#Log format
#DEBUG; INFO; ERROR; OFF

log4j.logger.com.client=INFO, FILE

#uncomment the below 2 lines to rollover at midnight,

#log4j.appender.FILE=org.apache.log4j.DailyRollingFileAppender
#log4j.appender.FILE.DatePattern='.'yyyy-MM-dd
#END of rollover at midnight

#Added for size-based rollover, if you do not want to rollover based on size, just #uncomment
3 lines below
log4j.appender.FILE=org.apache.log4j.RollingFileAppender
log4j.appender.FILE.MaxFileSize=10MB
log4j.appender.FILE.MaxBackupIndex=10
#END of size-based rollover

log4j.appender.FILE.file=C:/BenchMark/NAF_Ben/clientapi.log
log4j.appender.FILE.layout=org.apache.log4j.PatternLayout
log4j.appender.FILE.layout.ConversionPattern=[%d{MMM dd HH:mm:ss}] - %p - %m%n

For more configurations, refer to the web page at:

http://logging.apache.org/log4j/1.2/manual.html.

4.3 Set up the High Availability mode

The Ezio Server can be configured for High Availability (HA) and Disaster Recovery (DR)
modes. The HA mode can support up to a maximum of six Ezio Servers per site – one
primary server, one secondary server and four Horizontal Scale servers.
21

Based on the HA requirements in your system, configure the Client API through ha.properties
file in one of the following HA modes:

 Standalone mode
 Active-Passive mode
 Load Balancing or Active-Active mode
 Hybrid mode

The ha.properties file contains the Ezio Server IP address, and the load balancing ratio of the
Ezio Servers included in the RMI connection pool. To configure the Client API in an HA mode,
adjust the values in the ha.properties file. For even load distribution, we recommend that you
set the load balancing ratio to one. For Standalone mode, the Client API can be configured
without a ‘ha.properties’ file.

Note:
Make sure you use the same client keystore in all the clusters.

By default, all the three ‘properties’ files are stored in the same directory as the client keystore. But,
since Client API version 2.8.11, you can store these ‘properties’ files in different locations and customize
the path.

4.3.1 Standalone mode

This is the simplest working mode, and is usually used for User Acceptance Testing (UAT).
The Standalone mode does not require a ‘ha.properties’ file.

To set up the Ezio Server in Standalone mode, set the parameter ‘haFlag’ for method
‘ClientAPI.getInstance()’ to ‘False’ when instantiating a Client API.

Figure 4-1: Client API in standalone mode

Application
RMI SSL (Two-way)

Client API Ezio Server (Standalone)

client keystore

log.properties

4.3.2 Active-Passive mode

Active-Passive mode has a primary server and a DR server for High Availability. In some
case, multiple DRs, up to a maximum of five, may also be used for High Availability.
22

Figure 4-2: Client API in Active-Passive mode

Application Ezio Server

RMI
Client API

SSL (Two-way)
client keystore DR stream

ha.properties

socket.properties
Ezio Server
(DR)
log.properties

To set up the Ezio Servers in Active-Passive mode, follow the instructions given below.

4.3.2.1 Set up the ha.properties file

For Active-Passive mode, the ’ha.properties’ file is set up as follows:

Table 4-10: ha.properties file for Active-Passive mode

ha.1 = < Ezio Server>

ha.2 = < DR1 Ezio Server>

4.3.2.2 Get a Client API instance

Use any of the constructors described earlier to instantiate your Client API. Set the ’haFlag’ to
’true’ when instantiating a Client API.

4.3.2.3 Set up the failure and recovery processes

In Active-Passive mode, when the primary Ezio server is unavailable, traffic automatically
failovers to a DR server, which acts as a secondary server. If you have multiple DR servers in
your setup, the failover mechanism selects a single server as the DR server. The Client API
function searches for an IP address in the ha.properties file that it can connect to, and then
connects to that server. If there are multiple IP addresses in the ha.properties file, the Client
API functions connects to the first IP address in the list.

Once the primary Ezio server is connected and restored, the traffic swings back to the original
server again. The seamless failover and recovery, called Disaster Recovery, is a key feature
of the Ezio Server.

The failover process for the Active-Passive is shown in the following figure.
23

Figure 4-3: Active-Passive connections

24

Figure 4-4: Active-Passive method invocation

25

4.3.3 Load Balancing (LB) or Active-Active mode

In LB mode, you can deploy up to six Ezio Servers in one cluster. The traffic is distributed
evenly between the servers.

Figure 4-5: Client API in LB mode

Application Ezio Server AS1 (lbcluster)

RMI SSL (Two-way)

ClientAPI

client keystore

ha.properties
Ezio Server AS2 (lbcluster)

socket.properties

log.properties

To set up the Ezio Servers in the LB mode, follow the instructions given below.

4.3.3.1 Set up the ha.properties file

Set up the ’ha.properties’ file in the following way:

Table 4-11: ha.properties file for LB mode

ha.1=lbcluster1

lb.lbcluster1.1=<AS1 IP address>
lb.lbcluster1.2=<AS2 IP address>
lb.lbcluster1.1.ratio=1
lb.lbcluster1.2.ratio=1

Note:
The load balancing ratio decides the size of RMI connection pool. For LB mode, the size of RMI
Connection Pool is < 2 x load balancing ratio>. For example, as per the above mentioned ha.properties
file, the RMI Connection Pool size is < 1 x 2 (for AS1) > + < 1 x 2 (for AS2) > = 4.

4.3.3.2 Get a Client API instance

Use any of the constructors described earlier to instantiate your Client API. Make sure you set
the ’haFlag’ to ’true’ when instatiating a Client API.
26

4.3.3.3 Set up the failure and recovery processes

In LB mode, when a primary server fails, the Client API re-tries to connect to the primary
server. If the Client API is unsuccessful in connecting to the crashed primary server, it
removes the crashed server from the RMI Pool.

For example, if AS1 is down, Client API re-tries to connect to AS1, and if unsuccessful,
removes the AS1 from the RMI Pool so that the current RMI Pool contains only AS2.

The failover process for the LB mode is shown in the following figure:
27

Figure 4-6: Load balancing or Active-Active connection

28

Figure 4-6: LB method invocation

29

4.3.4 Hybrid mode

In hybrid mode, you can support only one LB cluster with multiple DR servers. The traffic is
distributed evenly between the active servers.

Figure 4-7: Client API in hybrid mode

Application Ezio Server AS 1 (lbcluster)

RMI SSL (Two-way)

Client API
Active-Active

client keystore Ezio Server AS 1 (lbcluster)

ha.properties
DR stream
socket.properties
DR AS1
DR AS2 (DR cluster)
log.properties

To set up the Ezio Servers in hybrid mode, follow the instructions given below.

4.3.4.1 Set up the ha.properties file

Set up the ’ha.properties’ file in the following way:

Table 4-12: ha.properties file for hybrid mode

ha.1=hybrid

lb.lbcluster1.1=<Ezio server 1 IP address>

lb.lbcluster1.2=<Ezio server 2 IP address>
lb.lbcluster1.1.ratio=1
lb.lbcluster1.2.ratio=1
ha.passive.1=<DR1 Ezio server IP address>
ha.passive.2=<DR2 Ezio server IP address>

Note:
In Hybrid mode, the DR Site is not in a load balancing cluster. Thus, when both AS1 and AS2 fail, all
traffic is diverted to only one DR server, DR1. If all the servers, i.e., AS1, AS2 and DR1 fail, then traffic
is diverted to DR2.

4.3.4.2 Get a Client API instance

Use any of the constructors described earlier to instantiate your Client API. Set the ’haFlag’ to
’true’ when instantiating a Client API.
30

4.3.4.3 Set up the failure and recovery processes

In a hybrid mode, when the primary server fails, the failover mechanism is the same as in LB
mode. But, if both Ezio server 1 and Ezio server 2 servers fail, the Client API mechanism
selects only one DR server, as in Active-Passive mode.

The failover process for the hybrid mode is shown in the following figure:
31
32
33

5 Advanced configuration
5.1 Customize Client API

Customize the behavior of Client API through modifications in the socket.properties file.

Properties Default Applied Usage

value Mode
This is used for both RMI
auth.timeout 0 (s) All modes connections and method
calls. If no return value is
received before this value
expires, the Client API throws
an AuthTimeoutException,
which acts as a trigger for
failover process.
This property applies when
reconnect.retrytime 180 (s) LB, Hybrid there is at least one live Ezio
server.
This represents the time
period during which the Ezio
Server attempts to reconnect
to the crashed server in LB
cluster. It is used for recovery
purposes.
The increment time period
inst.multiplier 15 (millisec) ALL used while establishing the
RMI connection.
The sleep time used while
auth.sleep 15 (millisec) ALL establishing the RMI
connection.
The sleep time used when
method.sleep 15 (millisec) ALL calling a method.
This is used in Hybrid
nolbserver.interval 15 (s) Hybrid recovery scenario, when both
the active servers in lbcluster
are down, and only the DR
server is active. In this case,
ClientAPI uses this interval to
recover the active Ezio
Server.
The retry number is used by
getInst.retrynum 5 ALL the getInstance method while
connecting to the Ezio
Server.
By default, the Client API
retries for five times while
connecting to the Ezio
Server.
multiple.rmi.support.registry.port N/A ALL When you use this property,
the value is 1100 (the registry
port).
For the RMI server, port
32772 is used.
The registry and RMI server
ports are used as a pair.
ha.ipmonitor.interval 10(s) Active-Passive, The interval to check if the
Hybrid passive server is alive, it is
used by both active-passive
and hybrid modes.
34

Note:
The properties - inst.multiplier, auth.sleep and method.sleep are dependent on auth.timeout value. They
take effect only when auth.timeout value is not equal to 0. We recommend that you set auth.timeout to
’20 seconds’ in the socket.properties file.

5.2 Multiple SSL set up

When an application uses multiple SSL connections, all the keystores are merged into a
centralized keystore, and every component uses the combined keystore.

The keystores can be merged in two different ways:

 For GlassFish or other server which specify a centralized keystore, use a script as
given below.
 For Websphere application server, use the tool iKeyman.

5.2.1 Script

To merge the keystores into a centralized keystore, download and use the attached batch
scripts.

importKeysCerts.zip

1. Before you execute the script, configure the values of the following variables:

 SET CLIENT_KEYSTORE=<Ezio server client keystore absolute path>

 SET CLIENT_KEYSTORE_PASS=<password of above client keystore>
 SET CACERT_ALIAS=cacert
 SET TRUSTSTORE=<absolute path of destinaton keystore>
 SET TRUSTSTORE_PASS=<keystore password of destination keystore>
 SET KEY_ALIAS=user
 SET KEYSTORE=< absolute path of destinaton keystore >
 SET KEYSTORE_PASS= <keystore password of destination keystore>

2. Execute the script to merge the keystores. Modify the scripts, if required.
 For Windows OS, run ExportTwoWaySSLCAKey(Win).bat script.
 For Linux OS, run ExportTwoWaySSLCAKey.sh script.

For example, to import ’cacert’ and ’user’ from test148.keystore to testkeys, first modify the
batch file as shown below:
35

Then, double click on the ExportTwoWaySSLCAKey(Win).bat to run the script on Windows

OS.

5.2.2 iKeyman

If you are using IBM WebSphere as you application server, use iKeyman to merge the
keystore. The key.p12 default keystore and the trust.p12 truststore are stored in the configuration
repository within the node directory of the web server.

The section below illustrates the steps to add the certificate into a Web Sphere web server.

5.2.2.1 Start iKeyman

3. Log on to WebSphere Application Server.
4. Stop all services running on ‘IBM WebSphere Application Server V6.1 Network
Deployment’ in Windows.

5. Run ‘ikeyman’ from the command prompt. The IBM IkeyMan utility could be found in
the folder of <IBM JRE>/bin/
36

5.2.2.2 Import user cert from the Gemalto keystore into key.p12

To import client cert with Alias of ‘user’ into Websphere key.p12, perform the following steps:

6. From Ikeyman, open key.p12 centralize keystore that is used by Websphere

Application Server node.

On a base application server, default key and truststores are stored in the node directory of the
configuration repository.

7. Enter the password of key.p12 (the default password of Websphere key.p12 is

‘WebAS’)

 The following window is displayed.

8. Click Export/Import...to extract the personal certificates with ‘user’ alias from the
Gemalto client keystore into key.p12 keystore.
37

9. Browse and locate the Gemalto client keystore, choose import key and click OK.

 The following window is displayed.

10. Enter the password of the keystore, and click OK.

11. Select only user and click OK.

12. Click OK. Do not change the label.

38

 The personal certificates with alias “user” is imported into the key.p12 keystore.

13. Repeat steps 1-7 for others key.p12 of the WebSphere nodes that are required.

5.2.2.3 Import cacert from the Gemalto keystore into trust.p12

To import ca cert with Alias of ‘cacert’ into WebSphere key.p12, perform the following steps:

14. From Ikeyman, open trust .p12 centralize keystore that is used by WebSphere
Application Server node.

On a base application server, default key and truststores are stored in the node
directory of the configuration repository.

15. Under Personal Certificates, click Import... to import the cacert.

39

16. Browse and locate the Gemalto client keystore, choose import key and click OK.

17. Enter password of the Gemalto client keystore.

18. Select only cacert and click OK.

40

19. Click "OK". Do not change the label name.

20. Cacert is displayed under Signer Certificates.

21. Repeat steps 1-7 for others trust.p12 of the WebSphere nodes that are required.

5.2.2.4 Some more extra steps required for WAS 6.1.0.13 and higher versions
22. Enable the User alias at the cell or the Node or the server level.
41

23. Select the User alias and apply.

24. Repeat step 1 for outbound communication also. Synchronize and Restart the
Application Servers and the other affected components in the cluster.

For more information of IBM WebSphere secure communication using SSL please refer to
http://pic.dhe.ibm.com/infocenter/wasinfo/v8r0/topic/com.ibm.websphere.express.doc/info/exp
/ae/csec_sslsecurecom.html

5.3 RSA Block for certain APIs

We provide additional javaScript and java libary to generate RSA block required for certain
APIs.

 DSSSCryptography.js:

function encryptChangePwdNoVerifyRSABlock(
UserIdValue,Pin1Value,Pin2Value,ServerRND1,ServerRND2)

public int changeRSAStatic_noVerify(byte[] sessionHandle, String

userID, int domain,byte[] random1, byte[] random2, byte[]
rsaEncBlock, int rsaEncBlockLen)

function encryptChangePwdRSABlock(
UserIdValue,Pin1Value,Pin2Value,OtipValue,ServerRND1,ServerRND2)

public int changeRSAStatic(byte[] sessionHandle, String userID,

int domain,byte[] random1, byte[] random2,

byte[] rsaEncBlock,intrsaEncBlockLen)

function encryptSetPwdNoVerifyRSABlock(
UserIdValue,PinValue,ServerRND )

public int setRSAStatic_noVerify(byte[] sessionHandle, String

userID, int domain, byte[] random, byte[] rsaEncBlock,

int rsaEncBlockLen)
42

function encryptSetPwdRSABlock(
UserIdValue,PinValue,OtipValue,ServerRND )

public int setRSAStatic(byte[] sessionHandle, String userID, int

domain, byte[] random, byte[] rsaEncBlock, int rsaEncBlockLen)

function encryptVerifyRSABlock(UserIdValue, PinValue, OtipValue,

ServerRND)

public int verify2Factor(byte[] sessionHandle, String userID, int

domain,byte[] random, byte[] rsaEncBlock, int rsaEncBlockLen)

function encryptVerifyStaticRSABlock( UserIdValue, PinValue,

ServerRND)

public int verifyRSAStatic(byte[] sessionHandle, String userID,

int domain,byte[] random, byte[] rsaEncBlock, int rsaEncBlockLen)

 Applet.jar: same as above DSSS javaScript, alternative way for RSA block
generation

 e2eejslib2048_b1.5.jar:

public static String EncryptPassword(String publicKey, String

password, String random)

public static String EncryptPasswordChange(String publicKey,

String oldPassword, String newPassword, String random)

public HSMPasswordStore hsmPasswordEncrypt(byte[] sessionHandle,

String userID, int domain, byte[] random, byte[] rsaEncBlock, int
rsaEncBlockLen, int rsaKeyIndex, int rsaKeyType,int hashAlgoType,
int symKeyIndex, int symKeyType, int mdoe),

public HSMPasswordStore hsmPasswordVerify(byte[] sessionHandle,

String userID, int domain, byte[] random, byte[] rsaEncBlock, int
rsaEncBlockLen, int rsaKeyIndex, int rsaKeyType, int hashAlgoType,
int symKeyIndex, int symKeyType, byte[] hashPasswordBlock,byte[]
salt ,int mdoe )

public HSMPasswordStore hsmPasswordEncrypt(byte[] sessionHandle,

String userID, int domain,byte[] random,byte[] encPINBlock,int
encPINBlockLen, int encKeyIndex,int encKeyType,int
hashAlgoType,int symKeyIndex, int symKeyType,byte[] newSalt,int
mode )

public HSMPasswordStore hsmPasswordVerify(byte[] sessionHandle,

String userID, int domain, byte[] random,byte[] encPINBlock,int
encPINBlockLen, int encKeyIndex,int encKeyType,int hashAlgoType,
int symKeyIndex,int symKeyType,byte[] hashPasswordBlock,byte[]
salt,byte[] newSalt, int mode)

registration-lib-1.0.jar: for Oath, OCRA token registration.

Instantiated OathRSABlockGenerator first, then call the method

accordingly.

OathRSABlockGenerator generator = new

OathRSABlockGenerator(String publicKeyMod, String publicKeyExp,
byte[] seedValue)
43

public byte[] generateRsaBlockForTOTPWithOTPValue(String

otpValueInString, long timestep)

public byte[] generateRsaBlockForTOTP(int otpLength, long

timestep)

public byte[] generateRsaBlockForHOTPWithOTP(String

otpValueInString)

public byte[] generateRsaBlockForHOTP(int otpLength)

public byte[] generateRsaBlockForOCRAWithOTP(String ocraSuite,

String otpValueInString)

public byte[] generateRsaBlockForOCRA(String ocraSuite)

public AutoSerial autoTokenSelfRegistrationEx(byte[]

sessionHandle, String userID, int domain, String serialNo, int
mediaType,byte[] random, byte[] authBlock, int authBlockLen, int
regOpType)
44

6 Usage
6.1 Basic usage

The basic use of ClientAPI involves three steps as follows:

1. Get a ClientAPI instance.

2. Call a method.
3. Check the return code to make sure that the function call is successful (it returns 0).

Note:
For a sample code, refer to the Appendix A in this document.

6.1.1 Get Client API instance

The Client API can be instantiated in many ways. For example,

ClientAPI api = null;

try {
api = ClientAPI.getInstance(keyStore, Pwd, ip,
false/true);
} catch (Exception ex) {
ex.printStackTrace();
return;
}

6.1.2 API call

The API method can be invoked to perform a variety of functions. For example,

int returncode = api.createUser(byte[] sessionHandle, String userID,

String userName, int domain, String group1, String group2,
String group3) ;

QueryKeyValue returnObject = api.keyGetValue(byte[] sessionHandle,

int domain, int keyIndex, int keyType) ;

6.1.3 Check return code/object

Check the return code to make sure that the function call is successful.

if (returncode == 0)
successful;
else
failed ;
if (returnObject.getReturnCode()== 0)
successful;
else
failed ;
45

6.2 Sample scenario

This section demostrates a sample scenario where:

1. First, a new user is created.

2. Then, the user is assigned the media destination and token.
3. Then, the user-entered OTP is verified for authentication.

Full sample code for the scenario is available in Appendix A.

6.2.1 ClientAPI instantiation

The Client API is a Singleton API, and can be instantiated through many instantiation
methods. The simplest method, without any HA mode configuration, is as follows:

// instantiate ClientAPI via Singleton method

ClientAPI clientapi = ClientAPI.getInstance(keyStore_AbsolutePath,

keyStore_Password, ezioServer_IPAddress);

Order Parameter Value Type Description

1 keyStore_AbsolutePath String Absolute path of the client keystore downloaded
from Ezio Server.
2 keyStore_Password String Keystore password of corresponding client
keystore.

3 ezioServer_IPAddress String Ezio Server IP address, for example,

192.168.168.220

6.2.2 Create user

Users are segregated into Admin domain (Domain 0) and User domains (Domains 1 - 1023).
ClientAPI allows you to manage the users – create, edit or delete.

Sample code to create a user is given below:

// Create a user

int rv = clientapi.createUser(sessionHandle, userId, userName,

domain, affiliatedGroup1Name, affiliatedGroup2Name,
affiliatedGroup3Name);

if(rv == 0) System.out.println("Test user created successfully");

else throw new Exception(rv +":Failed to create user");

Order Parameter Value Description

Type
1 sessionHandle Byte Array Deprecated API session management function
parameter to specify session Id in byte arrays.
Empty byte array to be specified.
2 userId String Unique user identifier under the domain.
3 userName String Name of user.
46

4 domain Int Specify domain where user is to be located.

Admin domain: 0
User domain: 1 - 1023.
5 affiliatedGroup1Name String Name of group 1 affiliated with user.
6 affiliatedGroup2Name String Name of group 2 affiliated with user. If there is no
group 2 associated with user, empty string can be
specified.
7 affiliatedGroup3Name String Name of group 3 affiliated with user. If there is no
group 3 associated with user, empty string can be
specified.

6.2.3 Activate user

For every new user created, there is a ’user status’ flag that is set to ’Pending’. The ’Pending”
user status means that the user’s password has not been set, or the user is still inactive. To
activate the user, set the ’user status’ flag to ’Active’.

A sample code to activate the user is given below.

public enum UserStatus{

ACTIVE(1), PENDING(0), SUSPEND(8), REVOKE(9),

FORCE_CHANGE(2);

int intVal;
UserStatus(int intVal){ this.intVal = intVal; }
public int getIntVal(){ return this.intVal;}
}
….
….
// Activate new user

rv = clientapi.setUserStatus(sessionHandle, userId, domain,

UserStatus.ACTIVE.intVal);

if(rv == 0) System.out.println("Activate user successful");

else throw new Exception(rv +":Failed to activate user");

Order Parameters ValueType Description

1 sessionHandle Byte Array Deprecated API session management function
parameter to specify session Id in byte arrays.
Specify an empty byte array.
2 userId String Unique user identifier under the domain.
3 domain Int Specify domain where user is to be located.
Admin domain: 0
User domain: 1 - S1023.
4 User status Int Specify user status:
Pending
Active
Force change
Suspend
Revoked

6.2.4 Create media destination

Ezio server is a token-agnostic server that supports almost all kinds of tokens. Media
Destination is a container that includes additional information about those medias that require
out-of-band channel to send SMS PIN or email OTP to users. To use a media for
47

authentication, the Media must be updated with the Media Destination field, even if it is
empty, as in the case of hardware tokens.

The sample code to create a media destination for a user is given below. The return code -
0x314 means that the user already has an existing media destination of similar media type.

// Create Media Destination

rv = clientapi.createMediaDest(sessionHandle, userId, domain,

mediaType, serialNo, mediaDest);

if(rv == 0) System.out.println("Media destination created for user

successfully");
else if(rv == 0x314)
// Only a single media destination of each media type is
allowed to be created for each user
System.out.println("Media destination already created for
user");
else throw new Exception(rv +":Failed to create media destination for
user");

Order Parameters ValueType Description

1 sessionHandle Byte Array Deprecated API session management function
parameter to specify session Id in byte arrays.
Specify an empty byte array.
2 userId String Unique user identifier under the domain.
3 domain Int Specify domain where user is to be located.
Admin domain: 0
User domain: 1 -1023.
4 mediaType Int To differentiate media characteristics, for example,
manufacturer, implementation and usage.
5 serialNo String Media serial number.
6 mediaDest String Media destination, for example, phone number or email
address.
If media does not require an Out-of-Band channel,
specify an empty string or as advised.

6.2.5 Create token

Ezio server supports many configuration of user token, for example, one user with multiple
tokens, or multiple users sharing a single media. The token is a virtual extension of a Media
assigned to a user. It stores information that defines the relationship between the Media and
user, for example, expiry date, authentication counters, token status and token size.

Sample code to assign a media to a user for authentication is given below.

// Create Token

rv = clientapi.createToken(sessionHandle, userId, domain, serialNo,

mediaType, otipBuffer);

if(rv == 0) System.out.println("Token created for user

successfully");
else throw new Exception(rv +":Failed to create token for user");
48

Order Parameters ValueType Description

1 sessionHandle Byte Array Deprecated API session management function
parameter to specify session Id in byte arrays.
Specify an empty byte array.
2 userId String Unique user identifier under the domain.
3 domain Int Specify domain where user is to be located.
Admin domain: 0
User domain: 1 - 1023.
4 serialNo String Media serial number.
5 mediaType Media Type.
6 otipBuffer Byte array Depending on media type, this is used to specify token
information for each user
E.g., Preassigned Media (Type 61) - specify One-time
password in byte array.

6.2.6 Verify One-Time Password

The sample code below shows how to authenticate an OTP generated by a token assigned to
a user. There are token-specific OTP verification methods too that verify OTPs generated by
a specific tokens through media type and serial number. A return code – 0x704 indicates a
failed 2nd factor authentication, most likely caused by a wrong or invalid OTP.

In the sample, a failed 2nd factor authentication is indicated by return code(0x704) likely due
to wrong or invalid OTP specified.

// Verification of Token

rv = clientapi.verifyClearOTIP(sessionHandle, userId, domain,

oneTimePassword.getBytes(), oneTimePassword.length());

if(rv == 0) System.out.println("Successfully verified One-time

password");
else if(rv == 0x704) System.out.println("Failed to verify One-time
password");
else throw new Exception(rv +":Failed to verify Token");

Order Parameters ValueType Description

1 sessionHandle Byte Array Deprecated API session management function
parameter to specify session Id in byte arrays.
Specify an empty byte array.
2 userId String Unique user identifier under the domain.
3 domain Int Specify domain where user is to be located.
Admin domain: 0
User domain: 1 -1023.
4 oneTimePassword Byte array Specify One-time password in byte array.
5 oneTimePassword length Int Length of One-time password.
49

7 Frequently asked questions

 How does Client API detect HA mode?

The ClientAPI detects the HA mode according to the following logic.

If HA flag in ClientAPI.getInstance(…) is set to:

o False: ‘ha.properties’ file is ignored.

o True: ClientAPI searches for ha.properties in the directory where the keystore
is stored, or the location specified while calling ClientAPI.getInstance(...). If
the ‘ha.properties’ file is

o Not found: Client API operates in standalone mode.

o Found: Client API reads the ‘ha.properties file to define the mode of
operation.

 How can I check for Client API connectivity?

On the command prompt of your client machine, enter the following java command to
validate the client keystore and RMI connection.

java –cp .;<path of ClientAPI.jar> com.client.ClientAPI

<keystore> <keypassword> <IP>

If everything is fine, public key value is displayed on the screen as shown below:

 What does ‘connection refused exception’ in clientapi.log mean?

Most probably, the RMI service is down in Ezio server. Please telnet to ports 1099
and 32771, or customized ports 1100 and 32772.

 What does ‘JRMP SSLHandshakeException’ mean?

This means that you have an invalid keystore. Please verify your keystore through the
connectivity test command.

 What happens if I see ‘keystore is tampered’?

This means that you have supplied a wrong keystore password. Please provide the
corresponding password.

 Do I need to do anything if there is another RMI service in the same environment?

If there is another RMI service in the same enviroment, you need to customize the
use of ClientAPI as per following logic:
50

If the other RMI is Non-SSL{

If the ClientAPI is using port 1099, make sure that the ClientAPI is the last
one to instantiate because when we customize the RMI factory by calling
RMISocketFactory.setSocketFactory(...) for port 1099, it doesn’t allow other
RMI services to exist after itself in the same JVM enviroment.
However, if ClientAPI is working on 1100, the sequence does’t matter.
}else{
Refer to Multiple SSL setup (Section 5.2)
}
51

Appendix A – Sample Code

package com.ds3global;

import com.client.ClientAPI;

/**
* Sample code to illustrate ClientAPI usages for;
*
* i. Instantiate ClientAPI
* ii. Creation of a new user
* iii. User account activation
* iv. Creation of media destination for user
* v. Creation of One-time password token for user
* vi. Verification of One-time password token
*
* The test token is of media type 61 ( pre-assigned media ) whereby
* the OTP is specified during creation of the media on Server Admin.
*
*/
public class ClientAPISampleUsage {

public enum UserStatus{

ACTIVE(1), PENDING(0), SUSPEND(8), REVOKE(9), FORCE_CHANGE(2);

int intVal;
UserStatus(int intVal){ this.intVal = intVal; }
public int getIntVal(){ return this.intVal;}
}

public static void main(String[] args) throws Exception{

// ClientAPI instantiation parameters

String keyStore_AbsolutePath = "dsssAdmin.keystore";
String keyStore_Password = "123456";
String ezioServer_IPAddress = "192.168.168.220";

// instantiate ClientAPI via Singleton method

ClientAPI clientapi = ClientAPI.getInstance(keyStore_AbsolutePath,
keyStore_Password, ezioServer_IPAddress);

// New User parameters

byte[] sessionHandle = new byte[16];
String userId = "bob";
String userName = "bob ross";
int domain = 1;
String affiliatedGroup1Name = "BasicGroup";
String affiliatedGroup2Name = "";
String affiliatedGroup3Name = "";

// Create user
int rv = clientapi.createUser(sessionHandle, userId, userName, domain, affiliatedGroup1Name,
affiliatedGroup2Name, affiliatedGroup3Name);
if(rv == 0) System.out.println("Test user created successfully");
else throw new Exception(rv +":Failed to create user");

// Activate new user for use

rv = clientapi.setUserStatus(sessionHandle, userId, domain, UserStatus.ACTIVE.intVal);
if(rv == 0) System.out.println("Activate user successful");
else throw new Exception(rv +":Failed to activate user");

// Test media for OTP verification

int mediaType = 61; // Pre-assigned One-time password Media
String serialNo = "GAPA00000001"; // Media destination
String mediaDest = ""; // No destination information
as no need for distribution of OTP
52

String oneTimePassword = "123456"; // Pre-assigned One-time password

// Create Media Destination

rv = clientapi.createMediaDest(sessionHandle, userId, domain, mediaType, serialNo, mediaDest);
if(rv == 0) System.out.println("Media destination created for user successfully");
else if(rv == 0x314)
// Only a single media destination of each media type is allowed to be created for each user
System.out.println("Media destination already created for user");
else throw new Exception(rv +":Failed to create media destination for user");

// Token information required for token creation of media type 61

byte[] otipBuffer = oneTimePassword.getBytes();

// Create Token
rv = clientapi.createToken(sessionHandle, userId, domain, serialNo, mediaType, otipBuffer);
if(rv == 0) System.out.println("Token created for user successfully");
else throw new Exception(rv +":Failed to create token for user");

// Verification of Token
rv = clientapi.verifyClearOTIP(sessionHandle, userId, domain,
oneTimePassword.getBytes(), oneTimePassword.length());
if(rv == 0) System.out.println("Successfully verified One-time password");
else if(rv == 0x704) System.out.println("Failed to verify One-time password");
else throw new Exception(rv +":Failed to verify Token");

}
53

Appendix B – Help and support

Gemalto provides extensive support for installation and use of the Ezio Server.

For any help or support, additional information, or product upgrade, contact Gemalto Support
personnel at the following email or phone number:

Asia Pacific, Europe, and Japan:

 Email: support.aspac.ebanking@gemalto.com
 Phone support: +65 6317 3744
 Escalations: +65 9173 5075

North America (The USA and Canada):

 Email: NIS.support@gemalto.com
 Toll-free phone support: 1 888 455 0496
54