Net-attached HSM: Configuring a Securosys Primus HSM or a Securosys CloudHSM

A Hardware Security Module (HSM) can be configured to store and protect cryptographic keys in a centralized, high-assurance appliance, providing a root of trust for sensitive cryptographic data transactions.

The following describes how to configure a Securosys Primus HSM or Securosys CloudHSM for the Next Generation Hardware Appliance by registering the appliance and connecting it to the HSM.

For more information on the Securosys HSM, refer to the Securosys product documentation that you received with your purchase of the HSM.

To configure a Securosys Primus HSM or a Securosys CloudHSM for your Next Generation Hardware Appliance, follow the steps below.

If you run into issues after the configuration, you can get HSM specific log messages from a HSM Support Package.
For further information please refer to Create an HSM Log.

Connect the Next Generation Hardware Appliance with the Securosys Primus HSM or Securosys CloudHSM

To connect the Next Generation Hardware Appliance with the HSM:

1. Log in to your Next Generation Hardware Appliance.

2. Open the Security page or click Configure HSM in the Overview.

3. In the HSM Configuration section, click + Add External HSM in the HSM Selection field. 

4. The Add an external HSM window opens.
   Select Securosys Primus HSM tile to access the Configuration fields.

5. Click Select HSM Type to continue. 

Securosys Primus HSM or Securosys CloudHSM Configuration

There are 3 different tables that are currently empty. 

1. one is for the HSM Devices,

2. one is for the Slots,

3. and one is for Permanent Secrets.

4. Further down there is a Miscellaneous section where you can provide details.
   The individual sections are: Wait Delay, Wait Retries, Trace Level or set the Trace PKCS#11 function inputs.

5. Adjust the settings if applicable.

6. Confirm your entries with Save HSM Configuration.

In the Overview you can now see that the Securosys Primus HSM is listed, but Not Connected and no device is configured yet.

Go back to the Security page and proceed with Add HSM Device.

Add HSM Device

1. To add a HSM Device click Add HSM Device in the Primus HSM Devices table.

2. Start with entering the HSM IP Address / FQDN (Fully Qualified Domain Name) to add a device.

3. Enter the HSM Port.

4. If applicable specify the Priority in selecting a redundant HSM. If you configure the first HSM leave the value 0.

For more information on how to set the priority, please refer to the Securosys Primus HSM or Securosys CloudHSM product documentation that you received when you purchased the HSM.

• Click Add HSM Device.

  • The corresponding form for the certificate opens.

    • HSM IP Address / FQDN:
      Enter the IP address or the Fully Qualified Domain Name (FQDN) of the HSM.
      Only IPv4 addresses are supported.

    • The HSM Port is already set by default.

    • Priority:
      Specify the priority when selecting a redundant HSM.
      The smaller the value, the higher the priority.
      The value can be between 0 and 127.

• Confirm your entries with Add HSM Device.

• A modal dialog requests to confirm your configuration.
  Save HSM Configuration

• Proceed with Activate.

The device will now be listed in the table Primus HSM Devices.
Here you can now preform actions such as Edit Device or Remove Device.

You can of course add multiple devices. Just repeat the process as described before.

Managed HSM Slots

There are no slots configured for this HSM at this time.

Add HSM Slot

1. To add a slot click Add HSM Slot.

2. At the first line: HSM Device, select the HSM for which the slot is to be defined. If several HSM Devices are configured, you can open the corresponding list using the drop-down menu.

3. Continue to specify the Slot ID.

4. Next you must specify a Username.

5. You can configure an optional Client ID to identify the client or the application.
   

Slot Setup

1. Enter the slot Setup Password.

2. Provide the PKCS#11 Password of the slot (PIN/Password).
   
   If there is a proxy in front of the HSM, the proxy settings have to be added first. If this is not the case, you can click Add HSM Slot to confirm the HSM slot configuration.

Proxy Settings

1. Add the Proxy User.

2. Enter the Proxy Password.

3. Click Add HSM Slot to confirm the HSM slot configuration.

4. Finalize with Save.

Permanent Secrets

After the configuration of the HSM Slots, the user name (partition) will be displayed under Permanent Secrets.

Should the password for the partition change you can Re-Initialize the Permanent Secret for a user or proxy.

Re-Initialize Permanent Secrets

It is possible to Re-Initialize Permanent Secrets for the User or for the Proxy.

1. From the list Permanent Secrets select the line of the Username you want to edit.

2. In the column Actions click Re-Initialize to open the form.

3. Enter the New Credentials.

4. To confirm your settings click Re-Initialize.

5. Finalize with Save.

On the Security page of the appliance, the status of the HSM Driver will change from Not Connected to Connected as soon as the configuration is completed.

On the Overview page of the appliance, the status in the HSM Overview also changes to Connected as soon as the configuration is completed. During configuration, the appliance is in the Restarting status. During this time, it is not available.

Usage Information

CryptoToken Configuration
The following note can be found in the info box:

In order to use this HSM in EJBCA, you need to select the following
PKCS#11 library in the P11NG CryptoToken configuration:
Reference: PKCS#1 Proxy - Securosys Primus HSM

The last line in Usage Information displays the options:

Remove HSM Configuration
To remove the HSM configuration you need to type REMOVE HSM CONFIGURATION into the Confirm Action field.
Click Cancel/Remove.
If remove is chosen the application will restart.

If changes have been made to the sections:
HSM Client Authentication Configuration
Secure Channel Client Configuration
Miscellaneous Configurations

these can be made with undone with Cancel or saved with Save HSM Configuration.

Abort
Click Abort to terminate the process of configuring a HSM.

Save HSM Configuration
Click Save HSM Configuration to save changes made on the HSM configuration.

Once EJBCA is running again, you can proceed with adding a crypto token.

Add a Crypto Token in EJBCA Enterprise

To create a crypto token:

1. On the Overview page of the Next Generation Hardware Appliance, click Admin Web for EJBCA in the Application Overview column.

2. The EJBCA Enterprise page opens.
   Check whether the Create new CA checkbox is selected.

3. Open the CA Functions drop-down menu in the top menu.

4. In the CA Functions section, select Crypto Tokens.

5. On the Manage Crypto Tokens page, click Create New...

The individual configuration of the Crypto Token depends on the configuration of the HSM!
For detailed Information please see managing crypto tokens.

HSM Troubleshooting

In the section HSM Driver Controls the current HSM Driver Status is displayed.
In case of HSM problems, the HSM driver can be restarted via the Restart button.