HSM Management

Detailed description

Administrative management of HSM.

See HSM technical documentation.

Administrative management of HSM. More...

Functions
TacAccessToken	issueAToken (long lExpiration) throws TacException
	Issues an Access Token for the user's session in the HSM.
void	revokeAToken(TacAccessToken accessToken) throws TacException
	Revoke a user's Access Token session in the HSM.
TacAccessToken[]	listAToken () throws TacException
	Lists the user's Access Tokens in the HSM.
int	getATokenCounter () throws TacException
	Recovers the Access Token counter for the entire HSM.
void	runATokenGC () throws TacException
	Runs the Garbage Collector for HSM session tokens.
HSMStatInfo	getStatInfo () throws TacException
	Retrieves HSM statistics information, such as session, CPU and memory usage figures.
HSMAllInfo	getHSMInfo () throws TacException
	Retrieves HSM status information.
String	getHSMStringInfo () throws TacException
	Retrieves HSM status information.
String	getFirmwareVersion () throws TacException
	Retrieves the HSM firmware version.
String	getModel () throws TacException
	Recover the HSM model.
String	getSerialNumber () throws TacException
	Retrieves the HSM's serial number.
void	backup (String file, String password) throws TacException
	Creates a backup of the objects (keys, certificates, etc.) stored internally in the Dinamo.
void	restoreWithoutNetConfig (String file, String password) throws TacException
	Restores the backup of objects (keys, certificates, etc.) saved internally in the Dinamo.
void	restoreWithNetConfig (String file, String password) throws TacException
	Restores the backup of objects (keys, certificates, etc.) saved internally in the Dinamo.
void	backupData (String file, String password, int direction) throws TacException
	Creates or restores the backup of objects (keys, certificates, etc.) stored internally in the Dinamo.

Functions

issueAToken()

TacAccessToken issueAToken

(

long

lExpiration

)

throws TacException

Issues an Access Token for the user's session in the HSM.

This feature is suitable for granular control of application authentication, where token issuance is managed by the security officer.
The cleaning of expired Access Tokens takes place in 2 stages:
When a user who has expired Access Tokens logs in using Access Tokens. Clearing only the expired Access Tokens themselves.
Using the revokeAToken() function. Clears all expired Access Tok ens from the HSM.

The maximum limit of Access Tokens issued per HSM can be seen in the table below.

Model	Maximum limit
Pocket	1024
XP	1 Million
ST	1 Million

Notes: Access Tokens are kept in a volatile form, and are thus deleted when the HSM is restarted. Despite being volatile, Access Tokens are replicated between HSMs.

This operation is available starting with HSM firmware version 3.17. Implementation of Access Tokens prior to firmware version 3.17 is legacy. Applications using this functionality must update the HSM client to version 3.2.18 or higher, along with the HSM firmware to version 3.17 or higher. There is no compatibility between new and old versions of HSM client and firmware.

Parameters

lExpiration

Token expiration. Equivalent to time_t. Measured in seconds from EPOCH(00:00, Jan 1 1970 UTC). Use TacNDJavaLib.DN_A_TOKEN_INFINITE for token without expiration.

Return

AToken for use in openSession.

Exceptions

TacException

Launched when an error occurs in the Access Token generation.

revokeAToken()

void revokeAToken

(

TacAccessToken

accessToken

)

throws TacException

Revoke a user's Access Token session in the HSM.

Parameters

accessToken

Access Token to be revoked.

Exceptions

TacException

Triggered when an error occurs when revoking the Access Token.

listAToken()

TacAccessToken[] listAToken

(

)

throws TacException

Lists the user's Access Tokens in the HSM.

Return

List of user ATokens.

Exceptions

TacException

Triggered when an error occurs when revoking the Access Token.

getATokenCounter()

int getATokenCounter

(

)

throws TacException

Recovers the Access Token counter for the entire HSM.

Return

Total Access tokens for the entire HSM.

Exceptions

TacException

Posted in the event of an error.

runATokenGC()

void runATokenGC

(

)

throws TacException

Runs the Garbage Collector for HSM session tokens.

This method cleans up any Access Tokens in the HSM that are no longer valid.
The GC must be called periodically by the application to keep the Access Token cache levels under control. The GC's execution schedule should be programmed taking into account the times when the HSM is most heavily loaded.

Exceptions

TacException

Posted in the event of an error.

getStatInfo()

HSMStatInfo getStatInfo

(

)

throws TacException

Retrieves HSM statistics information, such as session, CPU and memory usage figures.

Return

Statistical information.

Exceptions

TacException

Posted when an error occurs when retrieving information.

getHSMInfo()

HSMAllInfo getHSMInfo

(

)

throws TacException

Retrieves HSM status information.

Return

Statistical information.

Exceptions

TacException

Posted when an error occurs when retrieving information.

getHSMStringInfo()

String getHSMStringInfo

(

)

throws TacException

Retrieves HSM status information.

Return

Information on the state of HSM.

Exceptions

TacException

Posted when an error occurs when retrieving information.

getFirmwareVersion()

String getFirmwareVersion

(

)

throws TacException

Retrieves the HSM firmware version.

Return

HSM firmware version or null if this information is not available.

Exceptions

TacException

Posted when an error occurs when retrieving information.

getModel()

String getModel

(

)

throws TacException

Recover the HSM model.

Return

HSM model or null if this information is not available.

Exceptions

TacException

Posted when an error occurs when retrieving information.

getSerialNumber()

String getSerialNumber

(

)

throws TacException

Retrieves the HSM's serial number.

Return

HSM serial number or null if there is no such information.

Exceptions

TacException

Posted when an error occurs when retrieving information.

backup()

void backup	(	String	file,
		String	password ) throws TacException

Creates a backup of the objects (keys, certificates, etc.) stored internally in the Dinamo.

The backup file will be created, if it exists, it will be overwritten.

Parameters

file	Path of the backup file.
password	Backup password.

Exceptions

TacException

Launched when an error occurs while creating the backup.

restoreWithoutNetConfig()

void restoreWithoutNetConfig	(	String	file,
		String	password ) throws TacException

Restores the backup of objects (keys, certificates, etc.) stored internally in the Dinamo.

Without network settings.

Parameters

file	Path of the backup file.
password	Backup password.

Exceptions

TacException

Launched when an error occurs while restoring the backup.

restoreWithNetConfig()

void restoreWithNetConfig	(	String	file,
		String	password ) throws TacException

Restores the backup of objects (keys, certificates, etc.) stored internally in the Dinamo.

With the network settings.

Parameters

file	Path of the backup file.
password	Backup password.

Exceptions

TacException

Launched when an error occurs while restoring the backup.

backupData()

void backupData	(	String	file,
		String	password,
		int	direction ) throws TacException

Creates or restores the backup of objects (keys, certificates, etc.) stored internally in the Dinamo.

Parameters

file	Path of the backup or restore file.
password	Backup or restore password.
direction	Specifies the action to be performed. Value Meaning TacNDJavaLib.MAKE_BACKUP The backup file will be created, if it exists, it will be overwritten. TacNDJavaLib.MAKE_RESTORE_WITHOUT_NET_CONFIG The existing backup data, not including network parameters, in the file indicated by file will be restored. TacNDJavaLib.MAKE_RESTORE_WITH_NET_CONFIG The existing backup data, including network parameters, in the file indicated by file will be restored. TacNDJavaLib.MAKE_USE_WIN_CREDENTIAL Uses Windows credentials for authentication. This option must be used with one of the other options. Enter the credential target in the password field.

Exceptions

TacException

Launched when an error occurs while creating or restoring the backup.