CryptoServer Class Reference

This class implements an interface to Utimaco's Hardware Security Module "CryptoServer". More...

Inheritance diagram for CryptoServer:

Public Member Functions
Constructors
	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
Authentication & Secure Messaging
void	logonPassword (String user, byte[] password) throws IOException, CryptoServerException
	Authenticates a user and establishs a secure messaging session with the CryptoServer. More...
void	logonPassword (String user, String password) throws IOException, CryptoServerException
	Authenticates a user and establishs a secure messaging session with the CryptoServer. More...
void	logonSign (String user, String keySpec, String pin) throws IOException, CryptoServerException
	Authenticates a user and establishes a secure messaging session with the CryptoServer. More...
void	logoff () throws IOException, CryptoServerException
	Terminates a secure messaging session and invalidates authentication. More...
int	getAuthState () throws IOException, CryptoServerException
	Returns resulting authentication state. More...
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...
synchronized void	setKeepSessionAlive (boolean flag) throws CryptoServerException
	Starts or stops an additional thread that keeps the current session alive and prevents it from expiring after 15 minutes idle time. 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	logonSC (String user, String pin) throws IOException, CryptoServerException
Deprecated
void	getSessionKeyDH (int size) throws IOException, CryptoServerException
void	keepSessionAlive () throws CryptoServerException
void	setTrace (PrintStream out)
void	setTrace (boolean flag)

Static Public Member Functions
static String	getName ()
	Returns the name of the CryptoServerAPI. More...
static double	getVersion ()
	Returns the version of the CryptoServerAPI (x.xx) More...

Basic Functions
synchronized void	close ()
	Terminates the current session, invalidates authentication and closes the connection to the CryptoServer. More...
String	getDevice ()
	Returns the device specifier of the connected CryptoServer.
synchronized void	setTimeout (int readTimeout) throws IOException, CryptoServerException
	Set the (read) timeout for all communication with the CryptoServer. More...
int	getTimeout ()
	Returns the current (read) timeout for all communication with the CryptoServer. More...
void	setTrace (PrintStream out, boolean flag)
	Enables or disables the trace function. More...
byte[]	exec (int fc, int sfc, byte[] cmd) throws IOException, CryptoServerException
	Executes a command of the CryptoServer. More...

Detailed Description

This class implements an interface to Utimaco's Hardware Security Module "CryptoServer".

Each instance of this class handles a connection to one dedicated CryptoServer.

See also

CryptoServerAPI.CryptoServerCluster on how to create an instance to a cluster of CryptoServer.

Example:

The following code illustrates the usage of the class CryptoServer:

// open connection to CryptoServer with a connection timeout of 3 seconds
CryptoServer cs = new CryptoServer("192.168.4.1", 3000);
 
// set command (read) timeout to 60 seconds
cs.setTimeout(60000);
 
// logon first user 'paul' with password 'utimaco'
cs.logonPassword("paul", "utimaco");
 
// logon second user 'kate' with encrypted keyfile 'rsa.key' and password '123456'
cs.logonSign("kate", "rsa.key", "123456");
 
// logon third user 'bill' with smartcard / USB connected reader
cs.logonSign("bill", ":cs2:cyb:USB0", null);
 
// get resulting authentication status (permission sum of paul, kate and bill)
int auth_state = cs.getAuthState();
System.out.println("AuthState: " + Integer.toHexString(auth_state));
 
// execute echo command
byte [] answ = cs.exec(0x83, 1, "Hello Echo".getBytes());
CryptoServerUtil.xtrace("answ", answ);
 
// end session
cs.logoff();
 
// close connection
cs.close();

Constructor & Destructor Documentation

CryptoServer() [1/3]

CryptoServer	(	String	device,
		int	timeout
	)		throws IOException, NumberFormatException, CryptoServerException

Creates a new connection to a 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.

CryptoServer() [2/3]

CryptoServer

(

String

device

)

throws IOException, NumberFormatException, CryptoServerException

Creates a new connection to a 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"

CryptoServer() [3/3]

CryptoServer

(

CryptoServerConfig

config

)

throws IOException, NumberFormatException, CryptoServerException

Creates a new connection to a CryptoServer.

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 specifier can be assigned in order to establish a fault-tolerant connection to a cluster of CryptoServer (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

Member Function Documentation

getName()

static String getName ( )

static

Returns the name of the CryptoServerAPI.

Returns

name string

getVersion()

static double getVersion ( )

static

Returns the version of the CryptoServerAPI (x.xx)

Returns

version string

Reimplemented in CryptoServerCXI.

close()

synchronized void close

(

)

Terminates the current session, invalidates authentication and closes the connection to the CryptoServer.

See also

endSession()

endAuthentication()

Reimplemented in CryptoServerCluster.

setTimeout()

synchronized void setTimeout

(

int

readTimeout

)

throws IOException, CryptoServerException

Set the (read) timeout for all communication with the CryptoServer.

Parameters

readTimeout

Timeout in milliseconds.

Reimplemented in CryptoServerCluster.

getTimeout()

int getTimeout

(

)

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

Returns

Timeout in milliseconds.

Reimplemented in CryptoServerCluster.

setTrace() [1/3]

void setTrace	(	PrintStream	out,
		boolean	flag
	)

Enables or disables the trace function.

If enabled all data sent to and received from the CryptoServer is printed to the output stream. This is for debugging purpose only. Don't use the trace function in a real life application to avoid disclosure of secret information.

Parameters

flag	trace function switched on if true, switched off if false.
out	OutputStream to which the trace output is sent (e.g. System.out).

exec()

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

Executes a command of the CryptoServer.

First the command data is sent to the CryptoServer. Then the answer from the CryptoServer is received and returned. This method blocks until an answer was received from the CryptoSever or an error occurs. If authentication was requested by calling one of the prepareAuthentication...() methods, the command data sent to the CryptoServer is authenticated. If secure messaging is established for this connection, then the data sent to and received from the CryptoServer is encrypted.

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 in CryptoServerCluster.

logonPassword() [1/2]

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

Authenticates a user and establishs a secure messaging session with the CryptoServer.

Parameters

user	Name of the user who wants to autenticate to the CryptoServer.
password	Password of the user. May contain binary data.

See also

prepareAuthenticationHMAC

getSessionKeyDH

Reimplemented in CryptoServerCluster.

logonPassword() [2/2]

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

Authenticates a user and establishs a secure messaging session with the CryptoServer.

Parameters

user	Name of the user who wants to autenticate to the CryptoServer.
password	Password of the user. Should contain ISO8859-15 characters only..

See also

prepareAuthenticationHMAC

getSessionKeyDH

Reimplemented in CryptoServerCluster.

logonSign()

void logonSign	(	String	user,
		String	keySpec,
		String	pin
	)		throws IOException, CryptoServerException

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

Note

The authentication mechanism of the user may be any of the following:

• RSA Signature / ECDSA Signature:
  The user authenticates with an RSA resp. ECDSA signature.
  The key source may be either a key file or a smartcard.
  In the latter case the PinPad reader has to be connected to the host.
• RSA Smartcard:
  The user authenticates with a RSA signature.
  The key source has to be a smartcard.
  The PinPad reader has to be connected directly to the CryptoServer (and not to the host).

Parameters

user	Name of the user who wants to autenticate to the CryptoServer.
keySpec	Specifies either the name of a - optionally encrypted - key file that contains the private key of the user or the combination of smartcard and PinPad reader (e.g. ':cs2:cyb:COM3', ':cs2:auto:USB0').
pin	Keyfile: Password, if the key file is encrypted, or null. Smartcard: Pin of smartcard or null to enter pin at PinPad reader.

See also

prepareAuthenticationRSASign

prepareAuthenticationRSASC

getSessionKeyDH

Reimplemented in CryptoServerCluster.

logoff()

void logoff

(

)

throws IOException, CryptoServerException

Terminates a secure messaging session and invalidates authentication.

See also

endSession()

Reimplemented in CryptoServerCluster.

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 in CryptoServerCluster.

prepareAuthenticationHMAC() [1/2]

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

Prepares to authenticate the subsequent commands with "HMAC Password" mechanism.

The next commands executed via the exec() method or the getSessionKeyDH() method are authenticated.

Parameters

user	Name of the user who wants to autenticate to the CryptoServer.
password	Password of the user. May contain binary data.

prepareAuthenticationHMAC() [2/2]

void prepareAuthenticationHMAC	(	String	user,
		String	password
	)		throws CryptoServerException, UnsupportedEncodingException

Prepares to authenticate the subsequent commands with "HMAC Password" mechanism.

The next commands executed via the exec() method or the getSessionKeyDH() method are authenticated.

Parameters

user	Name of the user who wants to autenticate to the CryptoServer.
password	Password of the user. Should contain ISO8859-15 characters only.

prepareAuthenticationRSASign()

void prepareAuthenticationRSASign	(	String	user,
		String	keySpec,
		String	pin
	)		throws IOException, CryptoServerException

Prepares to authenticate the subsequent commands with "RSA Signature" mechanism.

The next commands executed via the exec() method or the getSessionKeyDH() method are authenticated.

Note

The PinPad reader has to be connected to the host.

Parameters

user	Name of the user who wants to autenticate to the CryptoServer.
keySpec	Specifies either the name of a - optionally encrypted - key file that contains the private key of the user or smartcard and PinPad reader (e.g. ':cs2:cyb:COM3', ':cs2:auto:USB0')
pin	Keyfile: Password, if the key file is encrypted, or null. Smartcard: Pin of smartcard or null to enter pin at PinPad reader.

prepareAuthenticationRSASC()

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

Prepares to authenticate the subsequent commands with "RSA Smartcard" mechanism.

The next commands executed via the exec() method or the getSessionKeyDH() method are authenticated.

Note

The PinPad reader has to be connected directly to the CryptoServer (and not to the host).

Parameters

user	Name of the user who wants to autenticate to the CryptoServer.
pin	PIN of the smartcard (optional), or null

endAuthentication()

synchronized void endAuthentication

(

)

Stops authentication.

All pending authentication requests issued with one of the prepareAuthentication...() methods are cancelled.

getSessionKeyDH() [1/2]

void getSessionKeyDH

(

)

throws IOException, CryptoServerException

Establishes a secure messaging session with the CryptoServer using 2048 bit Diffie-Hellman key agreement.

An AES session key is negotiated with the CryptoServer and used to encrypt all commands send to and all answers received from the CryptoServer. The session is valid for all subsequent communication until a new session key is generated or the session is terminated with the endSession() method.

setKeepSessionAlive()

synchronized void setKeepSessionAlive

(

boolean

flag

)

throws CryptoServerException

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

If a session remains idle (no command was sent) for more than 15 minutes, the session expires and is automatically invalidated by the CryptoServer.

Parameters

flag	true: starts the thread (if not already started) false: stops the thread (if already started)

Reimplemented in CryptoServerCluster.

setEndSessionOnShutdown()

void setEndSessionOnShutdown

(

boolean

flag

)

Enables or disables a ShutdownHook for terminating active sessions.

If enabled a session is automatically ended on shutdown without endSession() having been called explicitly.

Parameters

flag	ShutdownHook is enables if TRUE, disabled if FALSE.

See also

endSession()

endSession()

synchronized void endSession

(

)

Terminates a secure messaging session.

The session key will be invalidated and all subsequent communication with the CryptoServer will no longer be encrypted.

getSessionKeyDH() [2/2]

void getSessionKeyDH

(

int

size

)

throws IOException, CryptoServerException

Deprecated:

As of CryptoServerAPI version 2.00, replaced by CryptoServerAPI.CryptoServer.getSessionKeyDH().
Ignores its parameter and always uses 2048 bit Diffie-Hellman.

keepSessionAlive()

void keepSessionAlive

(

)

throws CryptoServerException

Deprecated:

As of CryptoServerAPI version 1.41, replaced by CryptoServerAPI.CryptoServer.setKeepSessionAlive(boolean flag)

Reimplemented in CryptoServerCluster.

setTrace() [2/3]

void setTrace

(

PrintStream

out

)

Deprecated:

As of CryptoServerAPI version 1.41, replaced by CryptoServerAPI.CryptoServer.setTrace(PrintStream, boolean)

setTrace() [3/3]

void setTrace

(

boolean

flag

)

Deprecated:

As of CryptoServerAPI version 1.41, replaced by CryptoServerAPI.CryptoServer.setTrace(PrintStream, boolean)