MD_GetHsmState

This function retrieves the current state of the specified HSM.

Synopsis

#include <md.h>
MD_RV MD_GetHsmState(uint32 hsmIndex,
                     HsmState_t* pState,
                     uint32* pErrorCode);

Input Requirements

The message dispatch library has been initialized via the MD_Initialize() function.

Input Parameters

Parameter	Description
`hsmIndex`	Zero-based index of the HSM to query. For remote HSMs, HSMs are numbered according to the order that the HSMs IP addresses were entered in the ET_HSM_NETCLIENT_SERVERLIST registry key. Refer to the SafeNet HSM Access Provider Installation Guide for further details. When MD_Initialize() is invoked, the message dispatch library assigns an index to each available HSM.
`pState`	Pointer to a variable to hold the HSM state. The pointer must not be NULL.
`pErrorCode`	Pointer to a variable which will hold the HSM error code when the function returns. If the HSM is halted, this variable contains an error code indicating the conditions which caused the halt. The pointer may be NULL.

Output Requirements

pState: When the function returns, pState points to a variable containing one of the following values. These values are defined in hsmstate.h :

Label	Value	Meaning
S_WAIT_ON_TAMPER	1	The HSM is waiting for the tamper cause to be removed.
S_HALT	6	The HSM is halted due to a failure.
S_POST	7	The HSM is initializing, and performing POST (Power On Self Test).
S_TAMPER_RESPOND	8	The HSM is responding to tamper.
S_NORMAL_OPERATION	0x8000	The HSM is in one of the following three states: S_NONFIPS_MODE, S_WAIT_FOR_INIT, or S_FIPS_MODE.

pErrorCode: When the function returns, pErrorCode points to a variable containing one of the following values. These values are defined in inc_scfs.h:

Label	Value	Meaning
SCFS_BAD_SDRAM	0x00000001	The HSM has come out of reset but has crashed whilst checking the SDRAM.
SCFS_BAD_SRAM	0x00000004	Failure in Secure Memory.
SCFS_BAD_SMFS	0x0000000A	Failure in the Secure Memory File System.
SCFS_BAD_CRYPT	0x00000021	Failure whilst testing cryptographic algorithms.
SCFS_BAD_RBG	0x00000023	Failure whilst testing the random number generator.
SCFS_UART_COM	0x00000026	Failure to detect the Real Time Clock.
SCFS_FLASH_FM	0x00000040	Failure in the Flash ROM – section containing the functionality module.
SCFS_FLASH_SA0	0x00000041	Failure in the Flash ROM – section containing the hardware info.
SCFS_TAMP_ACTIVE	0x00000083	The HSM has been tampered and the tamper is active

The function returns the following codes:

Function Code	Qualification
MDR_OK	N/A
MDR_UNSUCCESSFUL	N/A
MDR_NOT_INITIALIZE	If the message dispatch library was not previously initialized successfully.
MDR_INVALID_HSM_INDEX	If HSM index was not in the range of accessible HSMs.