Manage communication with the HSM

The Authentication Suite Server SDK for Entrust nShield HSM host-side library does not manage the communication with the HSM. Communication with the Entrust nShield HSMs (connection opening, published SEE machine retrieval, HSM key loading, AS command transactions, HSM key removal, SEE World KeyID destroying , connection closing) needs to be implemented in the integrator applications:

• Connection opening. A connection to the Entrust nShield hardserver has to be established to possibly communicate with the HSM modules.

  From the nCore HSM host API, use the NFastApp_Connect() method in C or the new NFConnection object in Java.

• Published SEE machine retrieval. An application that must use the SEE machine (e.g. for HSM keys loading, or to execute Authentication Suite Server SDK command transactions) will have to retrieve a SEE World KeyID of the published SEE machine if this one has been uploaded, started and published by a client machine (see Automatically upload and start the Authentication Suite Server SDK SEE machine).

  In this case, the SEE World KeyID of the published SEE machine can be retrieved using the nCore command Cmd_GetPublishedObject.

  From the nCore HSM host API, use the NFastApp_Transact() method in C or the transact() method of an NFConnection in Java to execute the nCore command.

• HSM key loading. An HSM key located on the host computer can be loaded into the started SEE machine, using the nCore command Cmd_LoadBLOB to load the key BLOB into the HSM, nCore command Cmd_GetTicket to obtain the ticket from the previously loaded key BLOB, and nCore command Cmd_SEEJob with the SEE job see_VC_loadkey to send the ticket to the SEE machine.

  From the nCore HSM host API, use the NFastApp_Transact() method in C or the transact() method of an NFConnection in Java to execute the nCore commands.

• VC command transaction. An Authentication Suite Server SDK command generated with the Authentication Suite Server SDK host API can be executed by the SEE machine, using the nCore command Cmd_SEEJob with the SEE job see_VC_cmd.

  From the nCore HSM host API, use the NFastApp_Transact() method in C or the transact() method of an NFConnection in Java to execute the nCore command.

• HSM keys removal. All HSM keys previously loaded in the SEE machine can be unloaded using the nCore command Cmd_SEEJob with the SEE job see_VC_removekeys.

  From the nCore HSM host API, use the NFastApp_Transact() method in C or the transact() method of an NFConnection in Java to execute the nCore command.

• SEE World KeyID destroying. An application that no longer needs to use the SEE machine can destroy the SEE World KeyID handle previously retrieved using the nCore command Cmd_Destroy.

  From the nCore HSM host API, use the NFastApp_Transact() method in C or the transact() method of an NFConnection in Java to execute the nCore command.

• Connection closing. An application that no longer needs to use a connection previously established with the Entrust nShield hardserver can close the connection.

  From the nCore HSM host API, use the NFastApp_Disconnect() method in C, or the close() method of an open NFConnection in Java.

Authentication Suite Server SDK for Entrust nShield HSM for Entrust nShield contains C and Java samples that demonstrate the communication between a host application and the HSM to perform HSM key loading or Authentication Suite Server SDK command transactions with the Authentication Suite Server SDK SEE machine.

In these samples, to use the SEE machine, the SEE World KeyID handle of the published SEE machine is retrieved (using the nCore command Cmd_GetPublishedObject, the expected published name is ‘OneSpan’ in the samples). It is necessary to have configured the hardserver of a client machine (preferably the remote file system that manages the HSMs) to publish the SEE machine (see Automatically upload and start the Authentication Suite Server SDK SEE machine).

For production purposes, it is recommended to configure the hardserver of a client machine (preferably the remote file system that manages the HSMs) for this client machine to automatically upload, start and publish the SEE machine, and for the applications to retrieve an SEE World KeyID handle on the published SEE machine.

For more information about the nCore APIs, refer to the Entrust nShield API documentation.