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 section 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 section 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.

The samples also provide sample snippets to illustrate an alternative process starting directly the SEE machine from the sample application (using the  userdata.sar and the 3 nCore commands Cmd_CreateBuffer, Cmd_LoadBuffer and Cmd_CreateSEEWorld), for an SEE machine that would not have been published, but that would have been anyway uploaded on the HSM module (e.g. using the loadmache command line tool).

This approach of directly starting the SEE machine in the application may be convenient for development and testing purposes, but is not recommended for production.

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