Message Dispatch API Reference
The FM SDK has a number of host libraries that must be linked into the host application in order to be able to communicate with an FM. The following functions labelled by the MD_ prefix form the Message Dispatch (MD) API. The function prototypes are defined in the header file md.h. The libraries etpso (for local HSMs) and etnetclient (for remote HSMs) implement the PCIe bus and NetServer driver respectively. The driver is accessible via the MD API.
Functions included in this Reference are:
Function Descriptions:
This section contains the following function descriptions:
MD_Initialize
This function is used to initialize the message dispatch library. Until this function is called, all other functions will return error code MDR_NOT_INITIALIZED.
The message dispatch library is designed to operate on a stable HSM system (either local or remote to the Host computer). During the initialization of the message dispatch library, the number of accessible HSMs is determined and HSM indices are allocated to accessible HSMs. These variables are utilized in other functions; if the HSM system should change, the message dispatch library should be re-initialized.
Synopsis
#include <md.h>
MD_RV MD_Initialize(void)
Return Value
The function returns either MDR_OK or MDR_UNSUCCESSFUL.
MD_Finalize
This function is used to finalize the message dispatch library. After this function returns, only the MD_Initialize() function should be called. All other functions will return error code MDR_NOT_INITIALIZED.
Synopsis
#include <md.h>
void MD_Finalize(void)
Input Requirements
The message dispatch library has been initialized via the MD_Initialize() function.
Return Value
None
MD_GetHsmCount
This function retrieves the number of accessible HSMs at the time the message dispatch library was initialized (when the MD_Initialize() function was called).
Synopsis
#include <md.h>
MD_RV MD_GetHsmCount(uint32* pHsmCount)
| Parameter | Description |
|---|---|
pHsmCount
|
Pointer to the variable which will hold the number of visible HSMs when the function returns. The pointer must not be NULL. |
Input Requirements
The message dispatch library has been initialized via the MD_Initialize() function.
Return Value
The HSM Count is returned in pHsmCount.
The function returns the following codes:
| Function Code | Qualification |
|---|---|
| MDR_OK | N/A |
| MDR_INVALID_PARAMETER | If pHsmCount was NULL. |
| MDR_NOT_INITIALIZE | If the message dispatch library was not previously initialized successfully. |
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);
| 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. For more information about this configuration item, see Specifying the Network Server(s). 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. The only error code that is returned is SCFS_SEE_LOG. The pointer may be NULL. |
Input Requirements
The message dispatch library has been initialized via the MD_Initialize() function.
Return Value
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. |
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. |
MD_ResetHsm
This function is used to reset the specified HSM.
Synopsis
#include <md.h>
MD_RV MD_ResetHsm(uint32 hsmIndex);
| Parameter | Description |
|---|---|
hsmIndex
|
Zero-based index of the HSM to query. For remote HSMs, the HSM indices are numbered according to the order that the HSMs’ IP addresses were entered in the ET_HSM_NETCLIENT_SERVERLIST registry key. For more information about this configuration item, see Specifying the Network Server(s). When MD_Initialize () is invoked the message dispatch library assigns an index to each available HSM. |
Input Requirements
The message dispatch library has been initialized via the MD_Initialize() function.
The remote server may disable or limit the use of this function via the ET_HSM_NETSERVER_ALLOW_RESET environment variable. For more information about this configuration item, see Network Mode Server Configuration Items. If this limitation has been set, then this function may only be called when the HSM stat is not S_NORMAL_OPERATION. See MD_GetHsmState for further details.
Return Value
The HSM is reset.
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. |
MD_SendReceive
This function is used to send a request and receive the response.
Synopsis
#include <md.h>
MD_RV MD_SendReceive(uint32 hsmIndex,
uint32 originatorId,
uint16 fmNumber,
MD_Buffer_t* pReq,
uint32 timeout,
MD_Buffer_t* pResp,
uint32* pReceivedLen,
uint32* pFmStatus);
| 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. For more information about this configuration item, see Specifying the Network Server(s). When MD_Initialize() is invoked, the message dispatch library assigns an index to each available HSM. |
fmNumber
|
Identifies whether the request is intended for an FM or not. This value must be set to the FMID of the FM that will handle the message (#include csa8fm.h). |
originatorId
|
ID of the request originator. This value is typically 0. The value should only be non-zero when the calling application is acting as a proxy. |
pReq
|
Array of request buffers to send to the FM module. For user-defined functions, the structure and content of the array of buffers is user-defined. Refer to javahsmreset and javahsmstate for an example of how to construct the response and request buffers for a user-defined function in Java. Each buffer in the array is an MD_Buffer_t struct, which contains a pointer to the data and the number of bytes of data, as detailed below. typedef struct In the final MD_Buffer_t struct the pData field must contain a NULL pointer and the length field should be set to 0. This indicates the end of the array of buffers. This scheme allows arrays with variable number of buffers to be passed into the function. The following diagram illustrates an array of buffers containing two buffers. The first buffer contains 6 bytes of data and the second buffer contains 4 bytes of data. The last array element contains an array with the pData field set to NULL and the length field set to 0 to indicate the end of the array. Figure 1: An example of a request buffers data type for function MD_SendReceive
|
timeout
|
The message timeout in ms. If set to 0, an internal default of 10 minutes is used. |
pResp
|
Response buffers. When the function returns, the response from the FM is contained in these buffers. Refer to the description of the pReq buffers above for details on how these buffers must be constructed. The memory for the pResp buffers must be allocated in the context of the application which calls the function. The pData field and length fields must be assigned appropriately to conform to the anticipated response packet. The buffers are filled in order until either the entire response is copied or the buffers overflow (this condition determined by pReceivedLen, described below). The value of this parameter can be NULL if the FM function will not return a response. |
pReceivedLen
|
Address of variable to hold the total number of bytes placed in the response buffers. The memory for this variable must be allocated in the context of the application which calls the function. The value of this parameter can be NULL if the FM function will not return a response. |
pFmStatus
|
Address of variable to hold the status/return code of the Functionality Module which processed the request. The meaning of the value is defined by the FM. The value of this parameter can be NULL. |
Input Requirements
The message dispatch library has been initialized via the MD_Initialize() function.
Return Value
The request is sent to the appropriate FM module. Where applicable the response is returned in the response buffers.
The function returns the following codes:
| Function Code | Qualification |
|---|---|
| MDR_OK | N/A |
| MDR_UNSUCCESSFUL | N/A |
| MDR_INVALID_PARAMETER | If the pointer supplied for pReq is NULL, if the request requires a response and the pointer supplied for pResp is NULL or if pReserved is not zero. |
| 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. |
| MDR_INSUFFICIENT_RESOURCE | If there is insufficient memory on either the host or adapter |
| MDR_OPERATION_CANCELLED | The operation was cancelled in the HSM. This code will not be returned. |
| MDR_INTERNAL_ERROR | The HSM has detected an internal error. This code will be returned if there is a fault in the firmware or device driver. |
| MDR_ADAPTER_RESET | The HSM was reset during the operation. This could be possibly due to the MD_ResetHsm command being issued during the operation. |
| MDR_FM_NOT_AVAILABLE | An invalid FM number was used. |
MD_GetParameter
This function obtains the value of a system parameter.
Synopsis
#include <md.h>
MD_RV MD_GetParameter(MD_Parameter_t parameter,
void*pValue,
unsigned int valueLen);
| Parameter | Description |
|---|---|
parameter
|
The following parameter, defined in md.h, may be queried: MDP_MAX_BUFFER_LENGTH Value: 1 The recommended maximum buffer size (in bytes) for messages that can be sent using the MD library. While messages larger than this buffer size may be accepted by the library, exceeding it is not recommended. Different HSM access providers have different values for this parameter. When this parameter returns 0 via pValue, there is no limit to the amount of data that can be sent using this library. |
pValue
|
The address of the buffer to hold the parameter value, which has the following buffer requirements: MDP_MAX_BUFFER_LENGTH, unsigned integer Size: 4 bytes The memory for the buffer must be allocated in the context of the application which calls the function. The size of the buffer is determined by the parameter that is being obtained. |
valueLen
|
The length of the buffer, pValue, in bytes. If the buffer length is not correct, MDR_INVALID_PARAMETER is returned. |
Input Requirements
The message dispatch library has been initialized via the MD_Initialize() function.
Return Value
The function returns the following codes:
| Function Code | Qualification |
|---|---|
| MDR_OK | N/A |
| MDR_INVALID_PARAMETER | If the pointer supplied for pReq is NULL, if the request requires a response and the pointer supplied for pResp is NULL or if pReserved is not zero. |
FM Host Legacy Functions API
Host legacy functions are no longer supported. If you have an existing host application that uses host legacy functions, it will continue to work. It is recommended, however, that you do not use any host legacy functions in new or migrated host applications.
The functions listed in the following table have been superseded as shown.
| Legacy Function | Superceded by |
|---|---|
| FM_Initialize | MD_Initialize |
| FM_Finalize | MD_Finalize |
| FM_DispatchRequest | MD_SendReceive |
