Detailed description

Administrative management of HSM.

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.

void	setTlsBundle (String szKey, String szCert) throws TacException
	Specifies the key and certificate that the HSM will use to establish the TLS tunnel.

void	nsAuthSetState (int acl, int state, SvmkShadow[] shadows) throws TacException
	Sets the partition's M-of-N authorization state (NSAuth).

SvmkShadow	scReadShadow (String pin) throws TacException
	Reads the M shadow of N from the smart card inserted into the reader.

ScInfo	scGetInfo () throws TacException
	Retrieves the information from the smart card inserted into the reader.

boolean	scIsLibLoaded ()
	Check to see if the Smart-card reader library is loaded.

void	scChangePIN (String currentPin, String newPin) throws TacException
	Change the PIN for the M-to-N Smart Card Dinamo inserted into the reader.

void	scWriteShadow (SvmkShadow shadow, String pin, boolean overwrite) throws TacException
	Write a shadow M of N to the smart card inserted in the reader.

void	scErase (String pin) throws TacException
	Erase the data from an M-of-N smart card Dinamo inserted into the reader.

void	scSetLabel (String pin, String label) throws TacException
	Sets the label for the M-of-N smart card Dinamo inserted into the reader.

String	scGetLabel (String pin) throws TacException
	Retrieves the label of the M-type smart card Dinamo inserted into the reader.

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.

◆ setTlsBundle()

void setTlsBundle	(	String	szKey,
		String	szCert ) throws TacException

Specifies the key and certificate that the HSM will use to establish the TLS tunnel.

Passing empty strings to szKey and szCert restores the HSM's default key and certificate.

Parameters

szKey	Key identifier ( `user/key` format) to be used in the HSM's TLS. Pass an empty string to use the default key.
szCert	Certificate identifier ( `user/cert` format) to be used in the HSM's TLS. Pass an empty string to use the default certificate.

Exceptions

TacException Thrown when an error occurs during the operation.

◆ nsAuthSetState()

void nsAuthSetState	(	int	acl,
		int	state,
		SvmkShadow[]	shadows ) throws TacException

Sets the partition's M-of-N authorization state (NSAuth).

Used to associate the HSM with an M-of-N partition and define the access level for objects using smart card shadows Dinamo. The session must be authenticated.

Available states (@iliteral{code} state @endiliteral )
State	Meaning	`acl`
`TacNDJavaLib#DN_S_NSAUTH_ASSOC`	Sets the associated state. Specify the desired ACL in `acl`.	combination of `NSAUTH_ACL_*`
`TacNDJavaLib#DN_S_NSAUTH_RESET`	Resets the NSAuth state (not associated and not authorized).	`TacNDJavaLib#NSAUTH_ACL_NOP`
`TacNDJavaLib#DN_S_NSAUTH_AUTH`	Sets the authorized status. Not yet available.	`TacNDJavaLib#NSAUTH_ACL_NOP`
`TacNDJavaLib#DN_S_NSAUTH_and_AUTH`	Sets the session as authorized. The ACL must have been defined previously via `TacNDJavaLib#DN_S_NSAUTH_ASSOC`.	`TacNDJavaLib#NSAUTH_ACL_NOP`
`TacNDJavaLib#DN_S_NSAUTH_CHECK`	Checks the set of shadows. Does not change the NSAuth state.	`TacNDJavaLib#NSAUTH_ACL_NOP`

Parameters

acl	Object access permissions (combination of `NSAUTH_ACL_*` flags). Relevant only for `TacNDJavaLib#DN_S_NSAUTH_ASSOC`; pass `TacNDJavaLib#NSAUTH_ACL_NOP` in all other states.
state	Status to be determined. See table above.
shadows	Shadows of the smart cards in partition M of N. May be `null` or empty for states that do not require shadows (e.g., `TacNDJavaLib#DN_S_NSAUTH_RESET`, `TacNDJavaLib#DN_S_NSAUTH_eAUTH`).

Exceptions

TacException

◆ scReadShadow()

SvmkShadow scReadShadow ( String pin ) throws TacException

Reads the M shadow of N from the smart card inserted into the reader.

This operation accesses the card directly via a USB/CCID reader and does not require an HSM session. Check the availability of the library using scIsLibLoaded().

Parameters

pin	Card PIN. Maximum length `TacNDJavaLib#DN_SC_MAX_PIN_LEN`.

Return: Shadow handles the card.

Exceptions

TacException

◆ scGetInfo()

ScInfo scGetInfo ( ) throws TacException

Retrieves the information from the smart card inserted into the reader.

This operation accesses the card directly via a USB/CCID reader and does not require an HSM session.

Return: Structure containing the card data.

Exceptions

TacException

◆ scIsLibLoaded()

boolean scIsLibLoaded ( )

Check to see if the Smart-card reader library is loaded.

Return: true if the library is available, false otherwise.

◆ scChangePIN()

void scChangePIN	(	String	currentPin,
		String	newPin ) throws TacException

Change the PIN for the M-to-N Smart Card Dinamo inserted into the reader.

This operation accesses the card directly via a USB/CCID reader and does not require an HSM session.

Parameters

currentPin	Current card PIN. Maximum length `TacNDJavaLib#DN_SC_MAX_PIN_LEN`.
newPin	New card PIN. Maximum length `TacNDJavaLib#DN_SC_MAX_PIN_LEN`.

Exceptions

TacException

◆ scWriteShadow()

void scWriteShadow	(	SvmkShadow	shadow,
		String	pin,
		boolean	overwrite ) throws TacException

Write a shadow M of N to the smart card inserted in the reader.

This operation accesses the card directly via a USB/CCID reader and does not require an HSM session.

Parameters

shadow	Shadow is being saved to the card.
pin	Card PIN. Maximum length `TacNDJavaLib#DN_SC_MAX_PIN_LEN`.
overwrite	`true` to overwrite an existing shadow.

Exceptions

TacException

◆ scErase()

void scErase ( String pin ) throws TacException

Erase the data from an M-of-N smart card Dinamo inserted into the reader.

This operation accesses the card directly via a USB/CCID reader and does not require an HSM session.

Parameters

pin	Card PIN. Maximum length `TacNDJavaLib#DN_SC_MAX_PIN_LEN`.

Exceptions

TacException

◆ scSetLabel()

void scSetLabel	(	String	pin,
		String	label ) throws TacException

Sets the label for the M-of-N smart card Dinamo inserted into the reader.

This operation accesses the card directly via a USB/CCID reader and does not require an HSM session.

Parameters

pin	Card PIN. Maximum length `TacNDJavaLib#DN_SC_MAX_PIN_LEN`.
label	ASCII label. Maximum size `TacNDJavaLib#DN_SC_MAX_LABEL_LEN`.

Exceptions

TacException

◆ scGetLabel()

String scGetLabel ( String pin ) throws TacException

Retrieves the label from the M-type smart card Dinamo inserted into the reader.

This operation accesses the card directly via a USB/CCID reader and does not require an HSM session.

Parameters

pin	Card PIN. Maximum length `TacNDJavaLib#DN_SC_MAX_PIN_LEN`.

Return: Card label in ASCII format.

Exceptions

TacException