SafeNet Authentication Service

Java Authentication API Developer Guide

All information herein is either public information or is the property of and owned solely by Gemalto and/or its
subsidiaries who shall have and keep the sole right to file patent applications or any other kind of intellectual
property protection in connection with such information.
Nothing herein shall be construed as implying or granting to you any rights, by license, grant or otherwise, under
any intellectual and/or industrial property rights of or concerning any of Gemalto’s information.
This document can be used for informational, non-commercial, internal and personal use only provided that:
• The copyright notice below, the confidentiality and proprietary legend and this full warning notice appear in
all copies.
• This document shall not be posted on any network computer or broadcast in any media and no modification
of any part of this document shall be made.
Use for any other purpose is expressly prohibited and may result in severe civil and criminal liabilities.
The information contained in this document is provided “AS IS” without any warranty of any kind. Unless
otherwise expressly agreed in writing, Gemalto makes no warranty as to the value or accuracy of information
contained herein.
The document could include technical inaccuracies or typographical errors. Changes are periodically added to
the information herein. Furthermore, Gemalto reserves the right to make any change or improvement in the
specifications data, information, and the like described herein, at any time.
Gemalto hereby disclaims all warranties and conditions with regard to the information contained herein,
including all implied warranties of merchantability, fitness for a particular purpose, title and non-infringement. In
no event shall Gemalto be liable, whether in contract, tort or otherwise, for any indirect, special or consequential
damages or any damages whatsoever including but not limited to damages resulting from loss of use, data,
profits, revenues, or customers, arising out of or in connection with the use or performance of information
contained in this document.
Gemalto does not and shall not warrant that this product will be resistant to all possible attacks and shall not
incur, and disclaims, any liability in this respect. Even if each product is compliant with current security
standards in force on the date of their design, security mechanisms' resistance necessarily evolves according to
the state of the art in security and notably under the emergence of new attacks. Under no circumstances, shall
Gemalto be held liable for any third party actions and in particular in case of any successful attack against
systems or equipment incorporating Gemalto products. Gemalto disclaims any liability with respect to security
for direct, indirect, incidental or consequential damages that result from any use of its products. It is further
stressed that independent testing and verification by the person using the product is particularly encouraged,
especially in any application in which defective, incorrect or insecure functioning could result in damage to
persons or property, denial of service or loss of privacy.
© 2018 Gemalto. All rights reserved. Gemalto and the Gemalto logo are trademarks and service marks of
Gemalto and/or its subsidiaries and are registered in certain countries. All other trademarks and service marks,
whether registered or not in specific countries, are the property of their respective owners.

Document Number: 007-012400-002, Rev. G

Release Date: January 2018

SafeNet Authentication Service: Java Authentication API Developer Guide 2

Document Number: 007-012400-002, Rev. G, © 2018 Gemalto
 Contents

Contents
Preface .................................................................................................................................. 4
Audience ......................................................................................................................................................... 4
Support Contacts ............................................................................................................................................ 4
Customer Support Portal .......................................................................................................................... 4
Telephone Support ................................................................................................................................... 5

1 SAS Authentication API ................................................................................................... 6

Constructors .................................................................................................................................................... 6
getInstance Method ........................................................................................................................................ 6
setINIPath Function ........................................................................................................................................ 6
LoadJNILibrary Method .................................................................................................................................. 7
Authenticate Method ....................................................................................................................................... 7
VerifySignature Method .................................................................................................................................. 9
getGridSureGrid Method ............................................................................................................................... 10
getGridSureLogo Method ............................................................................................................................. 10

2 Use Case Scenarios ...................................................................................................... 11

Basic Authentication ..................................................................................................................................... 11
Challenge-Response .................................................................................................................................... 11
Outer Window Authentication ....................................................................................................................... 11
PIN Styles ..................................................................................................................................................... 12
Static Password Authentication .................................................................................................................... 12
Agent Key Files ............................................................................................................................................. 13
Logging ......................................................................................................................................................... 13

3 Additional Information .................................................................................................... 14

API Example ................................................................................................................................................. 14
Deployment Requirements for Windows ...................................................................................................... 14
Deployment Requirements for Linux ............................................................................................................ 15
Configuration................................................................................................................................................. 16

SafeNet Authentication Service: Java Authentication API Developer Guide 3

Document Number: 007-012400-002, Rev. G, © 2018 Gemalto
 Preface

Preface
The SafeNet Authentication Service (SAS) Authentication API enables agents to support all functionality
required to interact with the SAS authentication server. SAS agents are third-party applications with embedded
plug-in code that enables the collection of user names and one-time passwords (OTPs) to be passed to the SAS
server for verification.

Audience
This document is intended for personnel responsible for maintaining your organization's security infrastructure. It
is assumed that the users of this document are proficient with security concepts.
All products manufactured and distributed by Gemalto are designed to be installed, operated, and maintained by
personnel who have the knowledge, training, and qualifications required to safely perform the tasks assigned to
them. The information, processes, and procedures contained in this document are intended for use by trained
and qualified personnel only.

Support Contacts
If you encounter a problem while installing, registering, or operating this product, refer to the documentation. If
you cannot resolve the issue, contact your supplier or Gemalto Customer Support.
Gemalto Customer Support operates 24 hours a day, 7 days a week. Your level of access to this service is
governed by the support plan arrangements made between Gemalto and your organization. Please consult this
support plan for further information about your entitlements, including the hours when telephone support is
available to you.

Customer Support Portal

The Customer Support Portal, at https://supportportal.gemalto.com, is a where you can find solutions for most
common problems. The Customer Support Portal is a comprehensive, fully searchable database of support
resources, including software and firmware downloads, release notes listing known problems and workarounds,
a knowledge base, FAQs, product documentation, technical notes, and more. You can also use the portal to
create and manage support cases.

NOTE: You require an account to access the Customer Support Portal. To create
a new account, go to the portal and click on the REGISTER link.

SafeNet Authentication Service: Java Authentication API Developer Guide 4

Document Number: 007-012400-002, Rev. G, © 2018 Gemalto
 Preface

Telephone Support
If you have an urgent problem, or cannot access the Customer Support Portal, you can contact Customer
Support by telephone. Calls to Customer Support are handled on a priority basis.

Region Telephone number

(Subject to change. An up-to-date list is maintained on the Customer Support Portal)

Global +1-410-931-7520

Australia 1800.020.183

China North: 10800-713-1971

South: 10800-1301-932

France 0800-912-857

Germany 0800-181-6374

India 000.800.100.4290

Israel 180-931-5798

Italy 800-786-421

Japan 0066 3382 1699

Korea +82 2 3429 1055

Netherlands 0800.022.2996

New Zealand 0800.440.359

Portugal 800.863.499

Singapore 800.1302.029

Spain 900.938.717

Sweden 020.791.028

Switzerland 0800.564.849

United Kingdom 0800.056.3158

United States (800) 545-6608

SafeNet Authentication Service: Java Authentication API Developer Guide 5

Document Number: 007-012400-002, Rev. G, © 2018 Gemalto
 1 – SAS Authentication API

1
SAS Authentication API

The SAS Authentication API is represented by a single Java class, CRYPTOCardAPI. This class is a singleton.

Constructors
CRYPTOCardAPI()
{
// empty constructor
}

getInstance Method
getInstance
(
)
returns a singleton instance of the CRYPTOCardAPI class.

setINIPath Function
setINIPath
(
String path
);

This function may be called to set the location from where the API should load the INI file. If this function is not
called before calling LoadJNILibrary, the INI file will be loaded from:
• Default Deployment Location
• If not persent at default location, the current execution path will be explored.
LoadJNILibrary must be called to initialize this instance.

SafeNet Authentication Service: Java Authentication API Developer Guide 6

Document Number: 007-012400-002, Rev. G, © 2018 Gemalto
 1 – SAS Authentication API

LoadJNILibrary Method
LoadJNILibrary
(
)

This functions loads and initializes the SafeNet encryption, communication, and logging library from the system-
exported LD_LIBRARY_PATH (on Linux) environment path or the system PATH (on Windows).
This function requires that, on Linux-like systems, the LD_LIBRARY_PATH environment variable be exported,
pointing to the location of all the binaries like libJCryptoWrapper.so. On Linux-like systemd, run ldd
./libJCryptoWrapper.so to confirm that all the dependencies can be resolved.
On Windows Systems, the management tool adds this path to the system’s PATH environment variable, making
it visible to the Java application. But if it is desired to load binaries from a different location (such as multiple
applications using their own binaries), this function should be called with the full path to JCryptoWrapper.dll or
libJCryptoWrapper.so.
On a Linux system, you must add the LD_LIBRARY_PATH export directive in your application`s launch script.
In the case of a web application, this must be declared in the web server launch script.
Read and write permissions must be set on the defined paths before attempting to load the binaries.
LoadJNILibrary
(
String LoadFromLocation
);

This functions loads and initializes the SafeNet encryption, communication, and logging library from the required
location. Call the setINIPath function before calling this function if it is desired to load the INI file from any other
location than the default. Comments for the LoadJNILibrary function without any argument are also valid for
this function call.

Authenticate Method
All authentications related actions make use of a single API call:
Authenticate
(
String[] arrData
);

Where the arrData details are:

arrData[0] UserName In Value

arrData[1] Organization In Value

arrData[2] OTP In Value

arrData[3] Challenge Return Value

SafeNet Authentication Service: Java Authentication API Developer Guide 7

Document Number: 007-012400-002, Rev. G, © 2018 Gemalto
 1 – SAS Authentication API

arrData[4] State In and Out

arrData[5] ChallengeData Return Value

arrData[6] ChallengeMessage Return Value

arrData[7] ReturnedResult Return Value

arrData[8] BothServersDown Return Value -> 1 or 0 (1 if down)

arrData[9] ErrorMessage Return Value -> Error Message for Logging or client

arrData[10] InIPAddress In Value Value -> Incoming client IP address - Service

Provider IP address
Where:
• Passing NULL as parameters should be avoided. Instead, array must be initialized with empty strings.
• UserName – A string representing the user name of the individual who is authenticating.
• Organization – A string representing the organization to which the individual who is authenticating belongs.
This currently should be passed as an empty string to represent the default organization.
• OTP – A string representing the user’s passcode. This may take form of either:
• [PIN+OTP] – Server-side PIN authentication.
• [OTP] – Token-side PINs or no PIN.
• [PIN] – When responding to a server-side user changeable PIN change request.
• [StaticPassword] – User has a static password enabled or is responding to a static password change.
This parameter may also be set to null to indicate a challenge is required.
• Challenge – A string that may be populated with a challenge/PIN change/outer window authentication
message.
• State – A string that may be populated with a state attribute. When returning a challenge, the same state
should passed back to the server.
• ChallengeData – Data returned as the response to the challenge.
• ChallengeMessage – Returned user message appended with the challenge.
• ReturnedResult – Returned result (String):
• 0 – Authentication Failed
• 1 – Authentication Succeeded
• 2 – Challenge
• 3 – Server provided PIN
• 4 – User needs to provide PIN
• 5 – Authentication in outer window; Re-authenticate
• 6 – User must change their static password
• 7 – Static password change does not satisfy policies
• 8 – PIN provided doesn’t meet requirements. Please provide a new PIN

SafeNet Authentication Service: Java Authentication API Developer Guide 8

Document Number: 007-012400-002, Rev. G, © 2018 Gemalto
 1 – SAS Authentication API

• BothServersDown – TokenValidator servers are down. If both servers (primary and secondary) are down,
value is 1, otherwise 0.
• InIPAddress – A string representing the IP address from which the authentication request came. If this
parameter is an empty string, the SAS server will attempt to detect the IP from which the authentication
request came from.

VerifySignature Method
Verifies the token's signature for a given hash.

VerifySignature
(
String[] arrData
);

where arrData details are:

arrData[0] SerialNumber In Value
arrData[1] Hash In Value
arrData[2] Signature In Value
arrData[3] ReturndResult Return Value

Return Value could be:

• 0 – Signature is incorrect for hash provided.
• 1 – Signature is correct for hash provided.
where:
• Passing NULL as a parameter should be avoided. Instead, an array must be initialized with empty strings.
• SerialNumber – A string representing the token’s serial number.
• Hash – A string representing the hash value to verify.
• Signature – A string representing the signature to verify for the provided hash.
• ReturndResult – A string return value: 1 = Success, 0 = Failure.

SafeNet Authentication Service: Java Authentication API Developer Guide 9

Document Number: 007-012400-002, Rev. G, © 2018 Gemalto
 1 – SAS Authentication API

getGridSureGrid Method
The getGridSureGrid method creates and returns a GrIDsure grid from the received SAS challenge.
getGridSureGrid
(
String BSIDChallenge
);

The getGridSureGrid method returns an instance of the BufferedImage class (bitmap).

getGridSureLogo Method
getGridSureLogo
(
);

The getGridSureLogo method returns the GrIDsure logo (an instance of the BufferedImage class) from a
string saved in this function.
If the getGridSureLogo method fails, it returns NULL BufferedImage or throws an exception.

SafeNet Authentication Service: Java Authentication API Developer Guide 10

Document Number: 007-012400-002, Rev. G, © 2018 Gemalto
 2 – Use Case Scenarios

2
Use Case Scenarios

SAS architecture supports the concept of a token-side and server-side PIN used in either QuickLog or
challenge/response mode. In addition, agents must support challenges, inner/outer window authentication, and
static password authentication. The following sections discuss these features in more detail.

Basic Authentication
The communication between an SAS agent and server is similar to that used in the RADIUS protocol, in that the
concepts of challenge messages and states are used.
The following scenario shows the most basic interaction between the agent and server:
1. Authenticating agent issues an authentication request with username, organization name, and a passcode.
2. Server responds with one of nine possible return codes as outlined in Returned Result.

Challenge-Response
Central to the concept of challenge/response authentication, outer window authentication, and server-side PIN
changes is a challenge message and state attribute issued from the authenticating server. This mechanism is
employed to authenticate tokens in challenge/response mode in the following manner:
1. Authenticating agent issues an authentication request with username, organization name, and a blank
passcode.
2. Server responds with a challenge message containing a challenge string (for example, challenge:
19863257) and a state attribute.
3. The authenticating agent responds to the challenge by issuing another authentication request with their
username, organization name, a response, and the state attribute.
To support localization, the SAS server returns necessary data only in its challenge messages, and the agent is
required to construct a localized version of it to display to the client. For example, the SAS server would return
only 19863257, and the SAS agent would display “Please respond to the challenge: 19863257”.

Outer Window Authentication

The concept of challenge messages and maintaining state is also used when authenticating a user through
inner/outer window authentication. Outer window authentication allows a user to authenticate by providing a
match in a large look-ahead window; however, they must also be able to respond to a follow-up challenge that
asks them to provide the exact next OTP from their token. The following sequence illustrates this functionality:
1. The authenticating agent issues an authentication request with username, organization name, and a
passcode.

SafeNet Authentication Service: Java Authentication API Developer Guide 11

Document Number: 007-012400-002, Rev. G, © 2018 Gemalto
 2 – Use Case Scenarios

2. The server finds a match for the provided OTP in the outer window and issues a challenge to the client
containing an outer window authentication string (“Please re-authenticate using the next OTP from your
token”) and a state attribute.
3. The authenticating agent responds to the challenge by issuing another authentication request with their
username, organization name, a response, and the state attribute.
See the localization note in the section “Challenge-Response” page 11.

PIN Styles
A number of PIN styles in SAS are supported:
• No PIN
• Fixed PIN (token-side PIN validation)
• User-changeable PINs (token-side PIN validation)
• Stored on server, fixed PIN
• Stored on server, user-changeable PIN
• Stored on server, server-changeable PIN
The authentication mechanism in SAS supports incoming passcodes in the following format [PIN+OTP], [OTP],
[NEWPIN], [STATICPASSWORD] and an empty passcode to request a challenge.

Stored on server, user or server changeable

In the case of PINs stored on the server that are user or server changeable, the challenge framework needs to
be leveraged again, as follows:
1. The authenticating agent issues an authentication request with username, organization name, and a
passcode.
2. The server finds a match for the provided OTP; however, it determines that it is necessary for the user to
change their PIN, therefore it issues a challenge to the client containing a PIN change string (“Your PIN has
expired. Please enter a new PIN:”) and a state attribute.
3. The authenticating agent responds to the challenge by returning the new PIN and the state attribute.
See the localization note in the section “Challenge-Response” page 11.

Static Password Authentication

SAS offers also the option of static password authentication, and enables the user to change their password.
The challenge response architecture can be used to facilitate this functionality, in the following manner:
1. Authenticating agent issues an authentication request with username, organization name, and a static
passcode.
2. If the user is not required to change the static password and it is correct, the server returns access-accept.
If the user is required to change the static password, a challenge message will be issued to client (“Your
password has expired. Please enter a new password:”) and a state attribute.
3. The authenticating agent responds to the challenge by issuing an access request message with their
username, organization, the new static password, and the state attribute.
See the localization note in the section “Challenge-Response” page 11.

SafeNet Authentication Service: Java Authentication API Developer Guide 12

Document Number: 007-012400-002, Rev. G, © 2018 Gemalto
 2 – Use Case Scenarios

Agent Key Files

The SAS API uses an encrypted key file to secure communication with the server. To accomplish this, a key file
is loaded and registered with agents, and then a matching key is registered with the authentication server.

Logging
The Java Authentication API will log messages to the log file C:/log/JCcryptoWrapper-{date}.log. This location
is configurable through the JavaAPIManager Logging tab. The logging level can be adjusted through this tab to
warning, info, debug, error, or critical.

SafeNet Authentication Service: Java Authentication API Developer Guide 13

Document Number: 007-012400-002, Rev. G, © 2018 Gemalto
 3 – Additional Information

3
Additional Information

API Example
Refer to the sample code in Main.java for an example of how to call the Authenticate and VerifySignature
methods.
To use the API example, the following are required:
• BSIDJavaAPI.jar (needed for Windows and Linux)
• NetBeans IDE or Eclipse, or any other Java development tool

Deployment Requirements for Windows

To deploy your completed application to another computer, the following are required to support the
SAS API:
• Your own .jar file and JCryptoWrapper.ini file should be in the same directory.
• The following files are required:
Program Files\CRYPTOCard\BlackShield ID\JavaAPI\bsidkey\ Agent.bsidkey
Program Files\CRYPTOCard\BlackShield ID\JavaAPI\ini\ JCryptoWrapperWin.ini
Program Files\CRYPTOCard\BlackShield ID\JavaAPI\jar\ BSIDJavaAPI.jar

For 32-bit operating systems the following files are required:

Program Files\CRYPTOCard\BlackShield ID\JavaAPI\bin\x86\ CryptoCOM.dll
Program Files\CRYPTOCard\BlackShield ID\JavaAPI\bin\x86\ JCryptoWrapperWin.dll

For 64-bit operating systems the following files are required:

Program Files\CRYPTOCard\BlackShield ID\JavaAPI\bin\x64\ CryptoCOM.dll
Program Files\CRYPTOCard\BlackShield ID\JavaAPI\bin\x64\ JCryptoWrapperWin.dll

SafeNet Authentication Service: Java Authentication API Developer Guide 14

Document Number: 007-012400-002, Rev. G, © 2018 Gemalto
 3 – Additional Information

Deployment Requirements for Linux

To deploy your completed application to another computer, the following are required to support the SAS API:
• Your own .jar file and JCryptoWrapper.ini file should be in the same directory.
• Mono framework installation is required only if you wish to run the JavaAPIManager.
• The following files are required:
• /usr/local/cryptocard/javaapi/bsidkey/Agent.bsidkey
• /usr/local/cryptocard/javaapi/ini/JCryptoWrapper.ini
• /usr/local/cryptocard/javaapi/jar/BSIDJavaAPI.jar

For 32-bit operating systems the following files are required:

• /usr/local/cryptocard/javaapi/bin/x86/libcrypto.so -> libcrypto.so.1.0.0
• /usr/local/cryptocard/javaapi/bin/x86/libcrypto.so.1.0.0
• /usr/local/cryptocard/javaapi/bin/x86/libJCryptoWrapper.so
• /usr/local/cryptocard/javaapi/bin/x86/libLinuxSOAP.so
• /usr/local/cryptocard/javaapi/bin/x86/libssl.so -> libssl.so.1.0.0
• /usr/local/cryptocard/javaapi/bin/x86/libssl.so.1.0.0
For 64-bit operating systems the following files are required:
• /usr/local/cryptocard/javaapi/bin/x64/libcrypto.so -> libcrypto.so.1.0.0
• /usr/local/cryptocard/javaapi/bin/x64/libcrypto.so.1.0.0
• /usr/local/cryptocard/javaapi/bin/x64/libJCryptoWrapper.so
• /usr/local/cryptocard/javaapi/bin/x64/libLinuxSOAP.so
• /usr/local/cryptocard/javaapi/bin/x64/libssl.so -> libssl.so.1.0.0
• /usr/local/cryptocard/javaapi/bin/x64/libssl.so.1.0.0

SafeNet Authentication Service: Java Authentication API Developer Guide 15

Document Number: 007-012400-002, Rev. G, © 2018 Gemalto
 3 – Additional Information

Configuration
Configuration of the Java Authentication API is done through the JavaAPIManager.
For configuration on Windows the following files are required:
• Program Files\CRYPTOCard\BlackShield ID\JavaAPI\ JavaAPIManager.exe
• Program Files\CRYPTOCard\BlackShield ID\JavaAPI\Nini.dll

For configuration on Linux the following files are required:

• /usr/local/cryptocard/javaapi/JavaAPIManager.exe
• /usr/local/cryptocard/javaapi/Nini.dll.

JavaAPIManager.exe uses Nini.dll to write configuration settings to JCryptoWrapper.ini file on Linux or

JCryptoWrapperWin.ini on Windows.
On the Communications tab, for Primary Server (IP and Port) field, enter the IP address of the SAS server.
For the Agent Encryption Key File field, browse to the Agent.bsidkey file, located at Program
Files\CRYPTOCard\BlackShield ID\JavaAPI\bsidkey\Agent.bsidkey on Windows, and
/usr/local/cryptocard/javaapi/bsidkey/Agent.bsidkey on Linux.
On the Policy tab, Enable Agent option should be selected. The Send Remote Client IP Address to SAS
Server option toggles whether or not the API sends the client’s IP address to SAS, overriding the SAS
automatic detection of the IP address.

SafeNet Authentication Service: Java Authentication API Developer Guide 16

Document Number: 007-012400-002, Rev. G, © 2018 Gemalto