API Java Class

The SafeNet Java Authentication SDK is represented by a single Java class CRYPTOCardAPI. The Java class is a singleton class with no public constructor. Class instance can be acquired using the getInstance public method.

Method

public static CRYPTOCardAPI getInstance()

This public method returns a singleton instance of the CRYPTOCardAPI class. This method also performs some internal initializations.

Note

We recommend calling the getInstance() method and setting INIPath once, and using the same for the life of the application.

Functions

public synchronized void setINIPath(String path)

This function is used 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 one of the following locations:

• Default deployment location.
• If the INI file is not present at the default location, the current execution path will be explored.

public synchronized void LoadJNILibrary() throws UnsatisfiedLinkError, Exception

This function performs initialization for the API settings by reading the INI file.

public void Authenticate(String[] arrData)

This function provides SafeNet server authentication and challenge generation functionality. It must be called only after initialization and loading are successfully completed.

String[] arrData Details

• 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 element may also be set to an empty string or to a single character to indicate if a challenge is required. If a challenge generation is required, send an empty state in arrData[4] as well. This may take the 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.
  • [OTP+PIN] – If it is configured this way in the SafeNet server.
  • [StaticPassword] – User has a static password enabled or is responding to a static password change.
• 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 must be passed back to the server, which was returned by the challenge generation call.
• 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 a 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 the requirements. Please provide a new PIN.
  • 9 - Authentication Expired
• BothServersDown – If both SafeNet servers (primary and secondary) are down, value is 1, otherwise 0.
• ErrorMessage – The error message (for logging or the client), if any.
• InIPAddress – A string representing the IP address from which the authentication request came. If this parameter is an empty string, the SafeNet server will attempt to detect the IP from which the authentication request came. Under normal circumstances, this should be left empty.

Note

Passing NULL as a parameter(s) should be avoided. Instead, the array must be initialized with empty strings.

• ResourceName – [Optional] The resource name from which the PUSH is triggered. The value will be displayed on the mobile notification in the following format: Login Request From <ResourceName>

Public void checkServerStatus(String[] arrData)

This function checks the status of the primary and secondary SafeNet server. It must be called only after initialization and loading get successfully completed.

• ReturnedResult – A string return value.
  • 0 - If failure.
• Servers’ status – Represents the status of the servers.
  • 0 – If either primary or secondary or both servers are up and running.
  • 1 – If both servers are down.
• ErrorMessage –The error message (for logging or the client), if any.

public void VerifySignature(String[] arrData)

This function verifies the token's signature for a given hash. The system-returned value could be:

• 0 – Signature is incorrect for the provided hash.
• 1 – Signature is correct for the provided hash.

• SerialNumber – A string representing the token’s serial number.
• Hash – A string representing the hash value to verify.
• Signature – A string representing the signature (OTP) to verify the provided hash.
• ReturnedResult – A string return value.
  • 1 - Success
  • 0 - Failure

Note

Passing NULL as a parameter(s) should be avoided. Instead, array must be initialized with empty strings.

public BufferedImage getGridSureGrid(String BSIDChallenge) throws Exception

This function creates and returns a GrIDsure grid from the received SafeNet server challenge.

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

public String getSoapPayload(String[] arrData) throws Exception

This function gives the API user, an ability to use their own SOAP transport layer. The API itself uses the following java packages for SOAP calls:

java.net.Authenticator;
java.net.HttpURLConnection;
java.net.InetSocketAddress;
java.net.MalformedURLException;
java.net.Proxy;
java.net.Socket;
java.net.SocketAddress;
java.net.URL;

The API fully handles HTTP, HTTPS, and HTTP/ HTTPS via HTTP Proxy with basic authentication. If, for any reason, it is desired not to use the built-in functionality, this function can be used to get the input parameter required to make a SOAP-based authentication call. Call to this procedure will return an encrypted SOAP payload accepted by the SafeNet server. This payload should be enclosed inside a SOAP envelope to be sent to the SafeNet server.

Example: SOAP Request With Headers and Soap Envelope

The following is a sample SOAP 1.2 request and response. The place holders shown needs to be replaced with actual values.

If the SOAP call is successful you should receive the following response:

The following is an example of the call for older SafeNet server versions.

If the SOAP call is successful you should receive the following response:

public String[] getResultFromAuthenticateResult(String encryptedAuthenticateResult) throws Exception

To get the result back, pass the ENCRYPTED AUTHENTICATION RESULT to the getResultFromAuthenticateResult function. This function throws an exception if the input(s) is invalid:

• Array Length is less than 12 characters
• No User Name
• Encryption Failure

All input and output values must follow the details provided in the Authenticate function.

This function is called after obtaining an encrypted result from a SOAP call to the SafeNet server. This function throws an exception if the input is null, empty or it fails to decrypt.

It returns the following array:

Example: SOAP Request With Headers and Soap Envelop

If SOAP call is successful, you should receive the following response:

encryptedAuthenticateResult is the value of AuthenticateTokenResult returned by the SafeNet server.

The following is an example of the call for older SafeNet server versions.

encryptedAuthenticateResult is the value of AuthenticateTokenResult returned by the SafeNet server.