This class implements an interface to a cluster of Utimaco's Hardware Security Modules "CryptoServer". More...

Inheritance diagram for CryptoServerCluster:

Classes
enum	DeviceState
	Device states as reported by CryptoServerCluster.EventHandler.stateChanged. More...

class	Error
	Defines an additional error code/mask that causes the cluster to switch to another device instead of returning to the caller. More...

interface	EventHandler
	The EventHandler interface provides callback functions, which are called if the state of the current CryptoServer within a cluster changes or an error occurs. More...

Public Member Functions
Constructors
	CryptoServerCluster (String[] devices, int timeout) throws IOException, CryptoServerException
	Creates a new connection to a CryptoServer cluster. More...

	CryptoServerCluster (CryptoServerConfig config) throws IOException, CryptoServerException
	Creates a new connection to a CryptoServer or CryptoServer cluster. More...

	CryptoServerCluster (String device, int timeout) throws IOException, CryptoServerException
	Creates a new connection to a CryptoServer (a cluster of one only one CryptoServer). More...

	CryptoServerCluster (String device) throws IOException, CryptoServerException
	Creates a new connection to a CryptoServer (a cluster of one only one CryptoServer). More...

synchronized void	open (String[] devices, int connTimeout) throws CryptoServerException

Basic Functions
synchronized void	close ()
	Closes the connection to the CryptoServer cluster. More...

byte[]	exec (int fc, int sfc, byte[] cmd, CryptoServerAPI.CryptoServerCluster.Error[] errList) throws IOException, CryptoServerException
	Executes a command on the current CryptoServer. More...

byte[]	exec (int fc, int sfc, byte[] cmd) throws IOException, CryptoServerException
	Executes a command on the current CryptoServer. More...

String	getDevice ()
	Returns the device specifier of the current CryptoServer.

int	getTimeout ()
	Returns the current read timeout for all communication with the current CryptoServer. More...

synchronized void	setTimeout (int timeout) throws IOException, CryptoServerException
	Sets the read timeout. More...

synchronized void	setFallbackInterval (int seconds) throws CryptoServerException
	Sets the fallback interval time. More...

synchronized void	setKeepSessionAlive (boolean flag) throws CryptoServerException
	Starts an additional thread that keeps the current session alive and prevents it from expiring after 15 minutes of idle time. More...

synchronized void	setEventHandler (EventHandler eventHandler) throws CryptoServerException
	Registers an event (callback) handler, that receives notification messages if the state of a CryptoServer changes or an error occurs. More...

Authentication & Secure Messaging
synchronized void	logon (String user, String keyFile, byte[] password) throws IOException, CryptoServerException
	Authenticates a user and establishes a secure messaging session with the current CryptoServer. More...

synchronized void	logoff () throws IOException, CryptoServerException
	Terminates a secure messaging session and invalidates authentication. More...

int	getAuthState () throws IOException, CryptoServerException
	Returns resulting authentication state. More...

Deprecated
void	setFallbackInterval (long seconds) throws CryptoServerException

void	logonPassword (String user, byte[] password) throws IOException, CryptoServerException

void	logonPassword (String user, String password) throws IOException, CryptoServerException

void	logonSign (String user, String keyFile, String password) throws IOException, CryptoServerException

void	keepSessionAlive () throws CryptoServerException

void	logonSC (String user, String pin) throws IOException, CryptoServerException

Public Member Functions inherited from CryptoServer
	CryptoServer (String device, int timeout) throws IOException, NumberFormatException, CryptoServerException
	Creates a new connection to a CryptoServer. More...

	CryptoServer (String device) throws IOException, NumberFormatException, CryptoServerException
	Creates a new connection to a CryptoServer. More...

	CryptoServer (CryptoServerConfig config) throws IOException, NumberFormatException, CryptoServerException
	Creates a new connection to a CryptoServer. More...

synchronized void	open (String device, int connTimeout) throws CryptoServerException

void	open (String device) throws CryptoServerException

void	prepareAuthenticationHMAC (String user, byte[] password) throws CryptoServerException
	Prepares to authenticate the subsequent commands with "HMAC Password" mechanism. More...

void	prepareAuthenticationHMAC (String user, String password) throws CryptoServerException, UnsupportedEncodingException
	Prepares to authenticate the subsequent commands with "HMAC Password" mechanism. More...

void	prepareAuthenticationRSASign (String user, String keySpec, String pin) throws IOException, CryptoServerException
	Prepares to authenticate the subsequent commands with "RSA Signature" mechanism. More...

void	prepareAuthenticationRSASC (String user, String pin) throws IOException, CryptoServerException
	Prepares to authenticate the subsequent commands with "RSA Smartcard" mechanism. More...

synchronized void	endAuthentication ()
	Stops authentication. More...

void	getSessionKeyDH () throws IOException, CryptoServerException
	Establishes a secure messaging session with the CryptoServer using 2048 bit Diffie-Hellman key agreement. More...

void	setEndSessionOnShutdown (boolean flag)
	Enables or disables a ShutdownHook for terminating active sessions. More...

synchronized void	endSession ()
	Terminates a secure messaging session. More...

void	getSessionKeyDH (int size) throws IOException, CryptoServerException

void	setTrace (PrintStream out)

void	setTrace (boolean flag)

void	setTrace (PrintStream out, boolean flag)
	Enables or disables the trace function. More...

Additional Inherited Members
Static Public Member Functions inherited from CryptoServer
static String	getName ()
	Returns the name of the CryptoServerAPI. More...

static double	getVersion ()
	Returns the version of the CryptoServerAPI (x.xx) More...

Detailed Description

This class implements an interface to a cluster of Utimaco's Hardware Security Modules "CryptoServer".

Only one CryptoServer is connected at a time but in case of a communication error the API automatically switches to another device and tries to execute the command on that device (failover).

The API tries to execute the command on every device and returns to the caller if the command could either be executed successfully or if it wasn't able to execute the command on any device.

The API begins with the first (primary) device in the given device list and switches to other devices in the given order. Once switched to another device the API basically stays at this device. Optionally a fallback interval can be given that causes the API to try to reconnect to the primary device after the interval time has expired (see setFallbackInterval).

Note: The cluster API stores the authentication credential (password) of the user in order to automatically restore a lost session.
Therefore the cluster API does not support smart card authentication.

In case of communication errors the API silently switches to another device and does not report the error to the calling application. If the calling application wants to get noticed about errors or state changes it can implement an event handler interface, see CryptoServerCluster.EventHandler

Note: Use the class CryptoServer instead of CryptoServerCluster if a dedicated CryptoServer should be adressed!

Example:

The following code illustrates the usage of the class CryptoServerCluster:

// create a configuration object
CryptoServerConfig config = new CryptoServerConfig("./CryptoServer.cfg");
 
// open connection to cluster.
CryptoServerCluster cs = new CryptoServerCluster(config);
 
System.out.println("current device: " + cs.getDevice());
 
// set event handler for error and state change messages
cs.setEventHandler(new EventHandler());
 
// logon user 'paul'
cs.logonPassword("paul", "utimaco");
 
// ... execute commands
 
// end session
cs.logoff();
 
// close connection
cs.close();

A sample configuration file looks as follows:

LogFile = d:/temp/CryptoServer.log
LogLevel = 3
LogSize = 1000000
 
Device = 192.168.4.183 \
         192.168.4.185 \
         192.168.4.186
 
ConnectionTimeout = 3000
Timeout = 60000
 
EndSessionOnShutdown = true
KeepSessionAlive = true

Constructor & Destructor Documentation

◆ CryptoServerCluster() [1/4]

CryptoServerCluster	(	String[]	devices,
		int	timeout
	)		throws IOException, CryptoServerException

Creates a new connection to a CryptoServer cluster.

Internally only one CryptoServer is connected at a time. The API provides a failover mechanism that switches to another device in case of connection failures and returns as soon as a device has been successfully connected. If none of the devices in the cluster can be connected an exception will be thrown.

Parameters

devices	Array of CryptoServer device addresses. Each address may contain the prefix "TCP:" followed by the IP address or port number and IP address (seperated by a '@'), or the prefix "PCI:" followed by the device name of a PCI device. Examples: "TCP:192.168.4.99", "TCP:288@192.168.4.201", "PCI:0", "PCI:/dev/cs2.0". The array may contain one or more devices.
timeout	Timeout in milliseconds to establish the connection to a CryptoServer.

◆ CryptoServerCluster() [2/4]

CryptoServerCluster ( CryptoServerConfig config ) throws IOException, CryptoServerException

Creates a new connection to a CryptoServer or CryptoServer cluster.

Parameters

config

Configuration object. The following key names will be recognized:

Key	Mandatory	Default Value	Description
Device	Yes	-	Device specifier of CryptoServer to be connected. Optionally multiple device specifiers can be assigned in order to establish a fault-tolerant connection to a CryptoServer cluster (failover). The values have to be separated either by a space or tab character or have to be spread over multiple lines each ended by a backslash character, see CryptoServerConfig.
Timeout	No	60000	Timeout in milliseconds the API waits for an answer on command execution
ConnectionTimeout	No	3000	Timeout in milliseconds the API waits on attempt to connect to a CryptoServer
EndSessionOnShutdown	No	false	Enables or disables a ShutdownHook for terminating active sessions
KeepSessionAlive	No	false	Prevents a secure messaging session from expiring after having been idle for more than 15 minutes
FallbackInterval	No	0	Time in seconds the API waits before it tries to reconnect to the primary device (first device in list) after having switched to another device due to a communication error

See also: CryptoServerCluster(String [] devices, int timeout)

◆ CryptoServerCluster() [3/4]

CryptoServerCluster	(	String	device,
		int	timeout
	)		throws IOException, CryptoServerException

Creates a new connection to a CryptoServer (a cluster of one only one CryptoServer).

Parameters

device	Address of the CryptoServer. May contain the prefix "TCP:" followed by the IP address or port number and IP address (seperated by a '@'), or the prefix "PCI:" followed by the device name of a PCI device. Examples: "TCP:192.168.4.99", "TCP:288@192.168.4.201", "PCI:0", "PCI:/dev/cs2.0".
timeout	Timeout in milliseconds to establish the connection.

See also: CryptoServer(String device, int timeout)

◆ CryptoServerCluster() [4/4]

CryptoServerCluster ( String device ) throws IOException, CryptoServerException

Creates a new connection to a CryptoServer (a cluster of one only one CryptoServer).

Parameters

device Address of the CryptoServer. May contain the prefix "TCP:" followed by the IP address or port number and IP address (seperated by a '@'), or the prefix "PCI:" followed by the device name of a PCI device. Examples: "TCP:192.168.4.99", "TCP:288@192.168.4.201", "PCI:0", "PCI:/dev/cs2.0".

See also: CryptoServer(String device, int timeout)

Member Function Documentation

◆ close()

synchronized void close ( )

Closes the connection to the CryptoServer cluster.

See also: CryptoServer.close()

Reimplemented from CryptoServer.

◆ exec() [1/2]

byte[] exec	(	int	fc,
		int	sfc,
		byte[]	cmd,
		CryptoServerAPI.CryptoServerCluster.Error[]	errList
	)		throws IOException, CryptoServerException

Executes a command on the current CryptoServer.

In case of failure the method automatically switches to the next device and tries to execute the command on that device. If the command could not be executed on any device an exception will be thrown.

Parameters

fc	Function code of the function called.
sfc	Sub-Function code of the function called.
cmd	Command data sent to the CryptoServer.
errList	Optional list of additional error codes the cluster should not report to the caller but switch to another device. Set to 'null' if only communication errors should cause the API to switch to another device.

Returns: Answer data received from the CryptoServer.

◆ exec() [2/2]

byte[] exec	(	int	fc,
		int	sfc,
		byte[]	cmd
	)		throws IOException, CryptoServerException

Executes a command on the current CryptoServer.

In case of failure the method automatically switches to the next device and tries to execute the command on that device. If the command could not be executed on any device an exception will be thrown.

Parameters

fc	Function code of the function called.
sfc	Sub-Function code of the function called.
cmd	Command data sent to the CryptoServer.

Returns: Answer data received from the CryptoServer.

Reimplemented from CryptoServer.

◆ getTimeout()

int getTimeout ( )

Returns the current read timeout for all communication with the current CryptoServer.

Returns: Timeout in milliseconds.

Reimplemented from CryptoServer.

◆ setTimeout()

synchronized void setTimeout ( int timeout ) throws IOException, CryptoServerException

Sets the read timeout.

Parameters

timeout Timeout in milliseconds to receive the answer from a CryptoServer.

Reimplemented from CryptoServer.

◆ setFallbackInterval() [1/2]

synchronized void setFallbackInterval ( int seconds ) throws CryptoServerException

Sets the fallback interval time.

If the API has switched to another device due to a communication error, this value specifies the time the API waits before it tries to reconnect to the primary device (first device in the list).

Parameters

seconds interval time in seconds. A value of 0 (default) specifies that the API should never fall back.

◆ setKeepSessionAlive()

synchronized void setKeepSessionAlive ( boolean flag ) throws CryptoServerException

Starts an additional thread that keeps the current session alive and prevents it from expiring after 15 minutes of idle time.

See also: setKeepSessionAlive()

Reimplemented from CryptoServer.

◆ setEventHandler()

synchronized void setEventHandler ( EventHandler eventHandler ) throws CryptoServerException

Registers an event (callback) handler, that receives notification messages if the state of a CryptoServer changes or an error occurs.

Parameters

eventHandler EventHandler class

See also: EventHandler

◆ logon()

synchronized void logon	(	String	user,
		String	keyFile,
		byte[]	password
	)		throws IOException, CryptoServerException

Authenticates a user and establishes a secure messaging session with the current CryptoServer.

The API provides a failover mechanism that switches to another device in case of failure and returns as soon as a secure messaging session to a device could be established. Therefore user credentials will be stored internally in order to reestablish a session in case of a failure. If logon fails on all devices an exception will be thrown.

Parameters

user	Name of the user who wants to autenticate to the CryptoServer.
keyFile	Key file user: Path to key file containing user's private key. Password user: null.
password	Key file user: Password of the key file if using an encrypted file, null otherwise. Password user: Password of the user.

Note: Smartcard users are not supported on a cluster.

◆ logoff()

synchronized void logoff ( ) throws IOException, CryptoServerException

Terminates a secure messaging session and invalidates authentication.

See also: endSession(); endAuthentication()

Reimplemented from CryptoServer.

◆ getAuthState()

int getAuthState ( ) throws IOException, CryptoServerException

Returns resulting authentication state.

Returns: resulting authentication state (== sum of permissions of all users currently logged on to the session).

Reimplemented from CryptoServer.

◆ setFallbackInterval() [2/2]

void setFallbackInterval ( long seconds ) throws CryptoServerException

Deprecated:: As of CryptoServerAPI version 2.00 replaced by setFallbackInterval(int seconds)

◆ logonPassword() [1/2]

void logonPassword	(	String	user,
		byte[]	password
	)		throws IOException, CryptoServerException

Deprecated:: As of CryptoServerAPI version 2.00 replaced by logon(String user, String keyFile, byte [] password)

Reimplemented from CryptoServer.

◆ logonPassword() [2/2]

void logonPassword	(	String	user,
		String	password
	)		throws IOException, CryptoServerException

Deprecated:: As of CryptoServerAPI version 2.00 replaced by logon(String user, String keyFile, byte [] password)

Reimplemented from CryptoServer.

◆ logonSign()

void logonSign	(	String	user,
		String	keyFile,
		String	password
	)		throws IOException, CryptoServerException

Deprecated:: As of CryptoServerAPI version 2.00 replaced by logon(String user, String keyFile, byte [] password)

Reimplemented from CryptoServer.

◆ keepSessionAlive()

void keepSessionAlive ( ) throws CryptoServerException

Deprecated:: Use setKeepSessionAlive() instead

Reimplemented from CryptoServer.

Classes

Public Member Functions

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ CryptoServerCluster() [1/4]

◆ CryptoServerCluster() [2/4]

◆ CryptoServerCluster() [3/4]

◆ CryptoServerCluster() [4/4]

Member Function Documentation

◆ close()

◆ exec() [1/2]

◆ exec() [2/2]

◆ getTimeout()

◆ setTimeout()

◆ setFallbackInterval() [1/2]

◆ setKeepSessionAlive()

◆ setEventHandler()

◆ logon()

◆ logoff()

◆ getAuthState()

◆ setFallbackInterval() [2/2]

◆ logonPassword() [1/2]

◆ logonPassword() [2/2]

◆ logonSign()

◆ keepSessionAlive()