Automatically upload and start the Authentication Suite Server SDK SEE machine

Entrust nShield provides the capability to automatically upload and start the SEE machine in the HSMs as needed (e.g. when the HSMs are restarted). It is possible to configure the hardserver of a client machine (preferably on the remote file system that manages the HSMs) to automatically perform this operation, where the SEE World KeyID of the started SEE machine will be published to allow further client applications (on this client machine or on other client machines) to access and use the SEE machine.

Configuring the hardserver of the RFS to automatically upload, start and publish the SEE machine is the recommended method for integrating the Authentication Suite Server SDK SEE machine with the HSMs.

In any case, to avoid conflicts, it is important to configure only one hardserver to perform this automatic upload/start/publich operation.

Configure the client machine to automatically upload, start, and publish the SEE machine

Follow these steps to configure the client machine from which the SEE machine is uploaded to the HSM.

To configure the client machine

1. Configure the HSM to authorize the client machine to issue privileged commands on the HSM. This can be done by setting the connection type between the HSM and the client to Priv. on any port.

   For instructions to configure the HSM to authorize a client machine to issue privileged commands, refer to the Entrust nShield product documentation.

2. Configure the hardserver on the client machine to allow privileged connections to the HSM. This can be done by editing the privileged setting with value 1 for each module declared in the [nethsm-imports] section of the client machine hardserver config file. The config file is located in the ${NFAST_HOME}/kmdata/config directory (in case of Unix) or %NFAST_KMDATA%\config directory (in case of Windows), e.g.:

   [nethsm_imports]
   local_module=1
   ...
   privileged=1
   ...
   -----------
   local_module=2
   ...
   privileged=1
   ...

   For instructions to configure the client machine hardserver to allow a client machine to issue privileged commands to an HSM, refer to the Entrust nShield product documentation.

3. Configure the hardserver of the client machine to automatically load, start and publish the SEE machine each time it is required. This can be done by editing the [load_seemachine] section of the client machine hardserver config file, e.g.:

   Windows:

   [load_seemachine]
   # Example of first module being a former nShield HSM (PowerPCSXF type)
   # seemach_ppc.sar SEE machine must be used
   module=1
   machine_file=C:\ProgramData\nCipher\Key Management Data\seemach_ppc.sar
   userdata=C:\ProgramData\nCipher\Key Management Data\userdata.sar
   worldid_pubname=vasco
   -----------
   # Example of second module being a former nShield HSM (PowerPCSXF type)
   # seemach_ppc.sar SEE machine must be used
   module=2
   machine_file=C:\ProgramData\nCipher\Key Management Data\seemach_ppc.sar
   userdata=C:\ProgramData\nCipher\Key Management Data\userdata.sar
   worldid_pubname=vasco
   -----------
   # Example of third module being a new nShield XC HSM (PowerPCELF type)
   # seemach_ppc-xc.sar SEE machine must be used
   module=3
   machine_file=C:\ProgramData\nCipher\Key Management Data\seemach_ppc-xc.sar
   
   userdata=C:\ProgramData\nCipher\Key Management Data\userdata.sar
   
   worldid_pubname=vasco

   Unix

   [load_seemachine]
   # Example of first module being a former nShield HSM (PowerPCSXF type)
   # seemach_ppc.sar SEE machine must be used
   module=1
   machine_file=/opt/nfast/kmdata/seemach_ppc.sar
   userdata=/opt/nfast/kmdata/userdata.sar
   worldid_pubname=vasco
   -----------
   # Example of second module being a former nShield HSM (PowerPCSXF type)
   # seemach_ppc.sar SEE machine must be used
   module=2
   
   machine_file=/opt/nfast/kmdata/seemach_ppc.sar
   
   userdata=/opt/nfast/kmdata/userdata.sar
   
   worldid_pubname=vasco
   
   -----------
   
   # Example of third module being a new nShield XC HSM (PowerPCELF type)
   
   # seemach_ppc-xc.sar SEE machine must be used
   
   module=3
   
   machine_file=/opt/nfast/kmdata/seemach_ppc-xc.sar
   
   userdata=/opt/nfast/kmdata/userdata.sar
   
   worldid_pubname=vasco

   The machine_file parameter specifies the SEE machine to be uploaded, and must be the absolute path to the SEE machine file seemach_ppc.sar in case of former Entrust nShield HSMs, or seemach_ppc-xc.sar in case of new Entrust nShield XC HSMs.

   The userdata parameter specifies the userdata file corresponding to the SEE machine to start, and must be the absolute path to the user data file userdata.sar generated and signed during the process described in Before using the Authentication Suite Server SDK SEE machine

   The worldid_pubname parameter specifies the PublishedObject name to use for publishing the SEE World KeyID of the started SEE machine. This published SEE machine will allow the client applications (on this client machine or on other client machines) to access and use this SEE machine (the published name is ‘vasco’ in this example).

   For more instructions to configure the client machine hardserver configuration file to automatically load, start and publish a SEE machine on an HSM, refer to the Entrust nShield product documentation.

4. After manually editing the config file of the client machine hardserver, the command line tool cfg-reread must be executed to reload the client machine hardserver’s configuration and take the changes in account.