Detailed description

Client session management with HSM.

Client session management with HSM. More...

Functions
void	openSession (String strAddr, String strUsrId, String strPwd) throws TacException
	Establishes an encrypted connection with the HSM.

void	openSession (String strAddr, String strUsrId, String strPwd, boolean bLoadBalance) throws TacException
	Establishes an encrypted connection with the HSM.

void	openSession (String strAddr, String strUsrId, String strPwd, String strOtp, boolean bLoadBalance) throws TacException
	Establishes an encrypted connection with the HSM using OTP.

void	openSession (String strAddr, String strUsrId, String strPwd, String strOtp) throws TacException
	Establishes an encrypted connection with the HSM using OTP.

void	openSession (String strAddr, String strUsrId, String strPwd, int nPort, int nFlags) throws TacException
	Establishes an encrypted connection to the HSM using the load balance settings.

void	openSession (String strAddr, String strUsrId, String strPwd, String strOtp, int nPort, int nFlags) throws TacException
	Establishes an encrypted connection with the HSM using the load balance and OTP configurations.

void	setOpenSession (byte[] session)
	Defines a previously opened session handle to be used in this instance.

void	openSession (String strAddr, TacAccessToken stAToken, int nPort, int nFlags) throws TacException
	Establishes an encrypted connection with the HSM using AToken.

void	openSession (String strAddr, byte[] jbaAToken, int nPort, int nFlags) throws TacException
	Establishes an encrypted connection with the HSM using AToken.

void	openSession (String strAddr, TacAccessToken stAToken, int nPort, boolean bLoadBalance, boolean bSessionCache, boolean bEncrypted) throws TacException
	Establishes a connection with the HSM using AToken.

void	openSession (String strAddr, byte[] jbaAToken, int nPort, boolean bLoadBalance, boolean bSessionCache, boolean bEncrypted) throws TacException
	Establishes a connection with the HSM using AToken.

void	openSession (String strAddr, String strUsrId, String strPwd, int nPort, boolean bLoadBalance, boolean bSessionCache, boolean bEncrypted) throws TacException
	Establishes an encrypted connection with the HSM.

void	openSession (String strAddr, String strUsrId, String strPwd, String strOtp, int nPort, boolean bLoadBalance, boolean bSessionCache, boolean bEncrypted) throws TacException
	Establishes an encrypted connection with the HSM using OTP.

static byte[]	getHSMTLSCert (String strAddr, int nPort, int nOutFormat) throws TacException
	Retrieves the TLS certificate from the HSM without logging in.

void	openSessionCert (String strAddr, String strUsrId, String strPwd, byte[] baPrivKey, String strPrivKeyPwd, byte[] baPrivKeyCert, byte[] baHSMCert, int nPort, int nFlags) throws TacException
	Establishes a connection to the HSM authenticated by username, password, and certificate (mutual TLS authentication).

void	openSessionHsmCert (String strAddr, String strUsrId, String strPwd, byte[] baHSMCert, int nPort, int nFlags) throws TacException
	Establishes a connection to the HSM authenticated by username, password, and HSM certificate verification.

void	closeSession (int nFlags) throws TacException
	Terminates the connection to the HSM.

void	closeSession (boolean bPhysicallyClose) throws TacException
	Terminates the connection to the HSM.

void	closeSession () throws TacException
	Ends the session by handing back the open connection to the management pool.

long	getCID () throws TacException
	Retrieves the CID (Correlation ID) of the current session.

Functions

◆ openSession() [1/12]

void openSession	(	String	strAddr,
		String	strUsrId,
		String	strPwd ) throws TacException

Establishes an encrypted connection with the HSM.

Parameters

strAddr	IP address of the HSM. If left blank, the system uses load balancing
strUsrId	HSM user.
strPwd	HSM user password.

Exceptions

TacException Posted when a user access or validation error occurs.

◆ openSession() [2/12]

void openSession	(	String	strAddr,
		String	strUsrId,
		String	strPwd,
		boolean	bLoadBalance ) throws TacException

Establishes an encrypted connection with the HSM.

Parameters

strAddr	IP address of the HSM. If left blank, the system uses load balancing
strUsrId	HSM user.
strPwd	HSM user password.
bLoadBalance	If true, use load balance

Exceptions

TacException Posted when a user access or validation error occurs.

◆ openSession() [3/12]

void openSession	(	String	strAddr,
		String	strUsrId,
		String	strPwd,
		String	strOtp,
		boolean	bLoadBalance ) throws TacException

Establishes an encrypted connection with the HSM using OTP.

Parameters

strAddr	IP address of the HSM. If left blank, the system uses load balancing
strUsrId	HSM user.
strPwd	HSM user password.
strOtp	HSM user OTP.
bLoadBalance	If true, use load balance

Exceptions

TacException Posted when a user access or validation error occurs.

◆ openSession() [4/12]

void openSession	(	String	strAddr,
		String	strUsrId,
		String	strPwd,
		String	strOtp ) throws TacException

Establishes an encrypted connection with the HSM using OTP.

Parameters

strAddr	IP address of the HSM. If left blank, the system uses load balancing
strUsrId	HSM user.
strPwd	HSM user password.
strOtp	HSM user OTP.

Exceptions

TacException Posted when a user access or validation error occurs.

◆ openSession() [5/12]

void openSession	(	String	strAddr,
		String	strUsrId,
		String	strPwd,
		int	nPort,
		int	nFlags ) throws TacException

Establishes an encrypted connection to the HSM using the load balance settings.

Parameters

strAddr	IP address of the HSM. If left blank, the system uses load balancing
strUsrId	HSM user.
strPwd	HSM User Password.
nPort	HSM port. Please note: only 4433 can be used.
nFlags	Always equal to zero.

Exceptions

TacException Posted when there is an error in accessing or validating the User.

◆ openSession() [6/12]

void openSession	(	String	strAddr,
		String	strUsrId,
		String	strPwd,
		String	strOtp,
		int	nPort,
		int	nFlags ) throws TacException

Establishes an encrypted connection with the HSM using the load balance and OTP configurations.

Parameters

strAddr	IP address of the HSM. If left blank, the system uses load balancing
strUsrId	HSM user.
strPwd	HSM User Password.
strOtp	HSM User Otp.
nPort	HSM port. Please note: only 4433 can be used.
nFlags	Always equal to zero.

Exceptions

TacException Posted when there is an error in accessing or validating the User.

◆ setOpenSession()

void setOpenSession ( byte[] session )

Defines a previously opened session handle to be used in this instance.

Parameters

session Previously opened session handle

◆ openSession() [7/12]

void openSession	(	String	strAddr,
		TacAccessToken	stAToken,
		int	nPort,
		int	nFlags ) throws TacException

Establishes an encrypted connection with the HSM using AToken.

Parameters

strAddr	IP address of the HSM. If left blank, the system uses load balancing
stAToken	HSM access token.
nPort	HSM port. Please note: only 4433 can be used.
nFlags	Always equal to zero.

Exceptions

TacException Posted when there is an error in accessing or validating the User.

◆ openSession() [8/12]

void openSession	(	String	strAddr,
		byte[]	jbaAToken,
		int	nPort,
		int	nFlags ) throws TacException

Establishes an encrypted connection with the HSM using AToken.

Parameters

strAddr	IP address of the HSM. If left blank, the system uses load balancing
jbaAToken	HSM access token.
nPort	HSM port. Please note: only 4433 can be used.
nFlags	Always equal to zero.

Exceptions

TacException Posted when there is an error in accessing or validating the User.

◆ openSession() [9/12]

void openSession	(	String	strAddr,
		TacAccessToken	stAToken,
		int	nPort,
		boolean	bLoadBalance,
		boolean	bSessionCache,
		boolean	bEncrypted ) throws TacException

Establishes a connection with the HSM using AToken.

Parameters

strAddr	IP address of the HSM.
stAToken	HSM access token.
nPort	HSM port. Please note: only 4433 can be used.
bLoadBalance	If true, use load balance
bSessionCache	If true, it uses the session cache manager.
bEncrypted	If true, use an encrypted connection. Some operations, such as generating keys or changing a user's password, can only be used with encrypted connections.

Exceptions

TacException Posted when there is an error in accessing or validating the User.

◆ openSession() [10/12]

void openSession	(	String	strAddr,
		byte[]	jbaAToken,
		int	nPort,
		boolean	bLoadBalance,
		boolean	bSessionCache,
		boolean	bEncrypted ) throws TacException

Establishes a connection with the HSM using AToken.

Parameters

strAddr	IP address of the HSM.
jbaAToken	HSM access token.
nPort	HSM port. Please note: only 4433 can be used.
bLoadBalance	If true, use load balance
bSessionCache	If true, it uses the session cache manager.
bEncrypted	If true, use an encrypted connection. Some operations, such as generating keys or changing a user's password, can only be used with encrypted connections.

Exceptions

TacException Posted when there is an error in accessing or validating the User.

◆ openSession() [11/12]

void openSession	(	String	strAddr,
		String	strUsrId,
		String	strPwd,
		int	nPort,
		boolean	bLoadBalance,
		boolean	bSessionCache,
		boolean	bEncrypted ) throws TacException

Establishes an encrypted connection with the HSM.

Parameters

strAddr	IP address of the HSM.
strUsrId	HSM user.
strPwd	HSM User Password.
nPort	HSM port. Please note: only 4433 can be used.
bLoadBalance	If true, use load balance
bSessionCache	If true, it uses the session cache manager.
bEncrypted	If true, use an encrypted connection. Some operations, such as generating keys or changing a user's password, can only be used with encrypted connections.

Exceptions

TacException Posted when there is an error in accessing or validating the User.

◆ openSession() [12/12]

void openSession	(	String	strAddr,
		String	strUsrId,
		String	strPwd,
		String	strOtp,
		int	nPort,
		boolean	bLoadBalance,
		boolean	bSessionCache,
		boolean	bEncrypted ) throws TacException

Establishes an encrypted connection with the HSM using OTP.

Parameters

strAddr	IP address of the HSM.
strUsrId	HSM user.
strPwd	HSM User Password.
strOtp	HSM User OTP.
nPort	HSM port. Please note: only 4433 can be used.
bLoadBalance	If true, use load balance
bSessionCache	If true, it uses the session cache manager.
bEncrypted	If true, use an encrypted connection. Some operations, such as generating keys or changing a user's password, can only be used with encrypted connections.

Exceptions

TacException Posted when there is an error in accessing or validating the User.

◆ getHSMTLSCert()

static byte[] getHSMTLSCert	(	String	strAddr,
		int	nPort,
		int	nOutFormat ) throws TacException

static

Retrieves the TLS certificate from the HSM without logging in.

This method is static and does not require an open session. It is typically called before openSessionCert to obtain the server certificate that will be verified during TLS mutual authentication.

Parameters

strAddr	HSM IP address or name.
nPort	HSM TCP port (usually `TacNDJavaLib#DEFAULT_PORT`).
nOutFormat	Format of the exit certificate. `TacNDJavaLib#CERT_OUT_DER` — X.509 DER `TacNDJavaLib#CERT_OUT_PEM` — X.509 PEM

Return: HSM certificate in the format specified in nOutFormat.

Exceptions

TacException Thrown when an error occurs while retrieving the certificate.

◆ openSessionCert()

void openSessionCert	(	String	strAddr,
		String	strUsrId,
		String	strPwd,
		byte[]	baPrivKey,
		String	strPrivKeyPwd,
		byte[]	baPrivKeyCert,
		byte[]	baHSMCert,
		int	nPort,
		int	nFlags ) throws TacException

Establishes a connection to the HSM authenticated by username, password, and certificate (mutual TLS authentication).

The HSM authenticates the client using its private key and certificate at the TLS level, and the client verifies the HSM’s identity using the server certificate (baHSMCert). Both sides authenticate each other.

Parameters

strAddr	HSM IP address or name.
strUsrId	User authentication on the HSM.
strPwd	User password.
baPrivKey	Client's private key in PEM format.
strPrivKeyPwd	The password for the private key specified in `baPrivKey`. Pass `null` or an empty string if there is no password.
baPrivKeyCert	Client certificate (private key pair) in PEM or DER format. Used for mutual TLS authentication at the channel level.
baHSMCert	HSM certificate in PEM or DER format. Obtained using `getHSMTLSCert()`.
nPort	HSM TCP port (usually `TacNDJavaLib#DEFAULT_PORT`).
nFlags	Combination of session flags, for example `TacNDJavaLib#ENCRYPTED_CONN`.

Exceptions

TacException Thrown when an error occurs during login.

◆ openSessionHsmCert()

void openSessionHsmCert	(	String	strAddr,
		String	strUsrId,
		String	strPwd,
		byte[]	baHSMCert,
		int	nPort,
		int	nFlags ) throws TacException

Establishes a connection to the HSM authenticated by username, password, and HSM certificate verification.

The HSM's TLS certificate is verified against baHSMCert before proceeding with username and password authentication. The client does not present its own certificate—use openSessionCert for mutual TLS authentication.

Parameters

strAddr	HSM IP address or name.
strUsrId	User authentication on the HSM.
strPwd	User password.
baHSMCert	HSM certificate in PEM or DER format. Obtained using `getHSMTLSCert(String, int, int)`.
nPort	HSM TCP port (usually `TacNDJavaLib#DEFAULT_PORT`).
nFlags	Combination of session flags, for example `TacNDJavaLib#ENCRYPTED_CONN`.

Exceptions

TacException Thrown when an error occurs during login.

◆ closeSession() [1/3]

void closeSession ( int nFlags ) throws TacException

Terminates the connection to the HSM.

Parameters

nFlags Always equal to zero.

Exceptions

TacException Posted in the event of failure to close the session.

◆ closeSession() [2/3]

void closeSession ( boolean bPhysicallyClose ) throws TacException

Terminates the connection to the HSM.

Parameters

bPhysicallyClose Determines whether the session will be physically closed, or only released in the local cache.

Exceptions

TacException Posted in the event of failure to close the session.

◆ closeSession() [3/3]

void closeSession ( ) throws TacException

Ends the session by handing back the open connection to the management pool.

Exceptions

TacException Posted in the event of failure to close the session.

◆ getCID()

long getCID ( ) throws TacException

Retrieves the CID (Correlation ID) of the current session.

The CID makes it possible to relate the operation on the HSM client to the HSM logs. The CID is only available when there is an established session with the HSM, otherwise the value will be 0 (zero). This number is usually represented in hexadecimal.

Return: CID

Exceptions

TacException Throws exception in case of error