Detailed description

HSM Management.

Enumerations
enum	TOKEN_TYPE : int { TIME = 1 , EVENT = 2 , CHAP = 3 , NTP = 4 }

Functions
string	GetErrorString (Int32 _errorCode)
	Returns the message with the error description.

DateTime	GetHSMDate ()
	Returns the date/time of the HSM.

void	SetHSMDateTime (DateTime stDateTime)
	Sets the date/time of the HSM.

DinamoApi.SYS_COUNTER_INFO	GetHSMCounterInfo ()
	Retrieves information from HSM system counters.

void	GetHSMHardwareInfo ()
	Retrieves hardware information from the HSM.

void	Backup (string DestFile, string Pin)
	Recover an HSM backup.

void	Restore (string SourceFile, string Pin, bool IncludeNetworkParameters)
	Restore a backup in HSM.

int	GetLogSize ()
	Retrieves the size of the HSM logs.

byte[]	DGetStatLog ()
	Recover the HSM logs.

byte[]	DGetStatLog (int StartPos, int BytesToRead)
	Recover the HSM logs.

int	IPFilterOperationStatus ()
	Retrieves the status of the HSM IP filter.

int	IPFilterOperationAdd (string szUser, string szIP)
	Adds an IP/user set to the HSM IP whitelist.

int	IPFilterOperationRemove (string szUser, string szIP)
	Removes an IP/user set from the HSM IP whitelist.

int	IPFilterSetStatus (bool bStatus)
	Sets the status of the HSM IP filter.

int	IPFilterOptList (DinamoApi.ListIpFilterCallback filterIpCallBack, IntPtr param)
	Retrieves the list from the HSM IP filter.

void	SaveLog (string fileName)
	Saves HSM logs to a file.

void	ClearLog ()
	Clears HSM logs.

string	EmitAuthenticationToken (DateTime expirationDate)

string	IssueAToken (ulong expiration)
	This functionality is suitable for granular control of application authentication, where the issuing oftokens is managed by the security officer. Expired Access Tok ens are cleared in 2 stages: When a user who has expired Access Tokens logs in using Access Tokens. It cleans only the expired Access Tokens themselves. Using the RunATokenGC() function. Clears all expired Access Tok ens from the HSM.

string	IssueAToken (long expiration)
	/overload void IssueAToken(ulong expiration)

string	IssueAToken (DateTime expiration)
	/overload void IssueAToken(ulong expiration)

void	RevokeAToken (string aToken)
	Revoke an HSM authentication token.

void	RevokeAuthenticationToken (string strToken)

DinamoApi.DN_A_TOKEN_FULL[]	ListATokenFull ()
	Lists the user's Access Tokens in the HSM.

void	RunATokenGC ()
	Runs the Garbage Collector for HSM session tokens. This method cleans up any HSM Access Tokens that are no longer valid. The GC should be called periodically by the application to keep the Access Token cache levels under control. The GC's execution schedule should be programmed to take into account the times of the HSM's greatest workloads.

uint	GetATokenCounter ()
	Recovers the Access Token counter for the entire HSM.

Enumerations

◆ TOKEN_TYPE

enum TOKEN_TYPE : int

Enumerators
TIME
EVENT
CHAP
NTP

Functions

◆ GetErrorString()

string GetErrorString ( Int32 _errorCode )

inline

Returns the message with the error description.

Parameters

_errorCode Error code.

Return: Error description.

◆ GetHSMDate()

DateTime GetHSMDate ( )

inline

Returns the date/time of the HSM.

Return: Date in DateTime format

Exceptions

DinamoException Throws exception in case of error.

Examples: get_date.cs.

◆ SetHSMDateTime()

void SetHSMDateTime ( DateTime stDateTime )

inline

Sets the date/time of the HSM.

Parameters

stDateTime Date in DateTime format

Exceptions

DinamoException Throws exception in case of error.

◆ GetHSMCounterInfo()

DinamoApi.SYS_COUNTER_INFO GetHSMCounterInfo ( )

inline

Retrieves information from HSM system counters.

Return: HSM system counter information.

Exceptions

DinamoException Throws exception in case of error.

Examples: get_counter_info.cs.

◆ GetHSMHardwareInfo()

void GetHSMHardwareInfo ( )

inline

Retrieves hardware information from the HSM.

Exceptions

DinamoException Throws exception in case of error.

◆ Backup()

void Backup	(	string	DestFile,
		string	Pin )

inline

Recover an HSM backup.

Parameters

DestFile	Name of the backup destination file.
Pin	Password for protecting the backup file. Must be ASCII characters. The length must be between DinamoApi.MIN_BACKUP_PIN_LEN and DinamoApi.MAX_BACKUP_PIN_LEN.

Exceptions

DinamoException Throws exception in case of error.

◆ Restore()

void Restore	(	string	SourceFile,
		string	Pin,
		bool	IncludeNetworkParameters )

inline

Restore a backup in HSM.

Parameters

SourceFile	Name of the backup file.
Pin	Password for protecting the backup file. Must be ASCII characters. The length must be between DinamoApi.MIN_BACKUP_PIN_LEN and DinamoApi.MAX_BACKUP_PIN_LEN.
IncludeNetworkParameters	If true, it includes the network settings in the HSM restore.

Exceptions

DinamoException Throws exception in case of error.

◆ GetLogSize()

int GetLogSize ( )

inline

Retrieves the size of the HSM logs.

Exceptions

DinamoException Throws exception in case of error.

◆ DGetStatLog() [1/2]

byte[] DGetStatLog ( )

inline

Recover the HSM logs.

Return: Complete HSM logs.

Exceptions

DinamoException Throws exception in case of error.

◆ DGetStatLog() [2/2]

byte[] DGetStatLog	(	int	StartPos,
		int	BytesToRead )

inline

Recover the HSM logs.

Parameters

StartPos	Starting position, in bytes, of the log to be retrieved. To receive the entire contents of the log, enter DinamoApi.GET_LOG_START_FULL.
BytesToRead	Amount, in bytes, to be retrieved from the starting position indicated by `dwStart`. To receive the entire contents of the log, indicate DinamoApi.GET_LOG_END_FULL.

Return: HSM logs.

Exceptions

DinamoException Throws exception in case of error.

◆ IPFilterOperationStatus()

int IPFilterOperationStatus ( )

inline

Retrieves the status of the HSM IP filter.

Return: Status of the IP filter.

Exceptions

DinamoException Throws exception in case of error.

◆ IPFilterOperationAdd()

int IPFilterOperationAdd	(	string	szUser,
		string	szIP )

inline

Adds an IP/user set to the HSM IP whitelist.

Parameters

szUser	User name.
szIP	IP

Return: Status of the IP filter.

Exceptions

DinamoException Throws exception in case of error.

◆ IPFilterOperationRemove()

int IPFilterOperationRemove	(	string	szUser,
		string	szIP )

inline

Removes an IP/user set from the HSM IP whitelist.

Parameters

szUser	User name.
szIP	IP

Return: Status of the IP filter.

Exceptions

DinamoException Throws exception in case of error.

◆ IPFilterSetStatus()

int IPFilterSetStatus ( bool bStatus )

inline

Sets the status of the HSM IP filter.

Parameters

bStatus true for enabled and false for disabled.

Return: Status of the IP filter.

Exceptions

DinamoException Throws exception in case of error.

◆ IPFilterOptList()

int IPFilterOptList	(	DinamoApi.ListIpFilterCallback	filterIpCallBack,
		IntPtr	param )

inline

Retrieves the list from the HSM IP filter.

Parameters

filterIpCallBack	IP listing callback.
param	Callback parameter.

Return: Status of the IP filter.

Exceptions

DinamoException Throws exception in case of error.

◆ SaveLog()

void SaveLog ( string fileName )

inline

Saves HSM logs to a file.

Parameters

fileName Name of the file to save the logs to.

Exceptions

DinamoException Throws exception in case of error.

◆ ClearLog()

void ClearLog ( )

inline

Clears HSM logs.

Exceptions

DinamoException Throws exception in case of error.

◆ EmitAuthenticationToken()

string EmitAuthenticationToken ( DateTime expirationDate )

inline

Obsolete: Use IssueAToken().

◆ IssueAToken() [1/3]

string IssueAToken ( ulong expiration )

inline

This functionality is suitable for granular control of application authentication, where the issuing oftokens is managed by the security officer.
Expired Access Tok ens are cleared in 2 stages:
When a user who has expired Access Tokens logs in using Access Tokens. It only clears the expired Access Tokens themselves.
Using the RunATokenGC() 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 from version 3.17 of the HSM firmware. The implementation of Access Tokens prior to version 3.17 of the firmware is legacy. Applications that use 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 the HSM client and firmware.

Parameters

expiration Token expiration. Equivalent to time_t. Measured in seconds from EPOCH(00:00, Jan 1 1970 UTC). Use DinamoApi.DN_A_TOKEN_INFINITE for tokens with no expiry.

Return: AToken for use in Connect().

Exceptions

DinamoException Throws exception in case of error.

Examples: atoken.cs.

◆ IssueAToken() [2/3]

string IssueAToken ( long expiration )

inline

/overload void IssueAToken(ulong expiration)

◆ IssueAToken() [3/3]

string IssueAToken ( DateTime expiration )

inline

/overload void IssueAToken(ulong expiration)

◆ RevokeAToken()

void RevokeAToken ( string aToken )

inline

Revoke an HSM authentication token.

Parameters

aToken Authentication token to be revoked.

Exceptions

DinamoException Throws exception in case of error.

Examples: atoken.cs.

◆ RevokeAuthenticationToken()

void RevokeAuthenticationToken ( string strToken )

inline

Obsolete: Use RevokeAToken().

◆ ListATokenFull()

DinamoApi.DN_A_TOKEN_FULL[] ListATokenFull ( )

inline

Lists the user's Access Tokens in the HSM.

Return: List of user ATokens.

Exceptions

DinamoException

Examples: atoken.cs.

◆ RunATokenGC()

void RunATokenGC ( )

inline

Runs the Garbage Collector for HSM session tokens. This method cleans up any HSM Access Tokens that are no longer valid.
The GC should be called periodically by the application to keep the Access Token cache levels under control. The GC's execution schedule should be programmed to take into account the times of the HSM's greatest workloads.

Exceptions

DinamoException

Examples: atoken.cs.

◆ GetATokenCounter()

uint GetATokenCounter ( )

inline

Recovers the Access Token counter for the entire HSM.

Return: Total Access tokens for the entire HSM.

Exceptions

DinamoException

Examples: atoken.cs.