.png){kind=logo}
Security: Configuring a Luna Network HSM
You can configure a Hardware Security Module (HSM) to store and protect your cryptographic keys. Optionally, you can use the software-based SoftHSM implementation for demonstration or testing purposes.
The following describes how to configure a Luna HSM for the Software Appliance by registering the Software Appliance and connecting it to the HSM.
Choose between one of the following options:
Thales Luna HSM Client 10.4.0
Thales Luna HSM Client 10.5.1
Thales Luna HSM Client 10.7.2
Thales TCT Luna Client 7.12.1
Configuring an HSM for the Software Appliance is irrevocable. To change an HSM configuration, you must reset the Software Appliance.
The network-attached HSM stores, protects, and manages sensitive cryptographic keys in a centralized, high-assurance appliance, providing a root of trust for sensitive cryptographic data transactions. For more information, refer to the Thales docs on SafeNet Luna Hardware Security Modules.
To configure a Luna HSM for your Software 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 Software Appliance With the Luna Network HSM
To connect the Software Appliance with the HSM:
Log in to your Software Appliance and open the Security page or click Configure HSM in the Overview.
In the HSM Configuration section, select Luna Network HSM to access the Configuration fields.
HSM Client Version
Click on the HSM Client you want to use.
Click Add HSM Device to open the corresponding form for the certificate.
HSM IP Address / FQDN:
Enter the IP address or the Fully Qualified Domain Name (FQDN) of your Luna Network HSM.
Only IPv4 addresses are supported.The HSM Port is already set by default.
Upload the HSM Server Certificate. Drag and drop or select the file.
This step is optional if trusted CAs are uploaded as described.
Confirm with Add HSM Device.
A warning appears to inform you that after saving HSM configuration you can no longer switch to a different HSM.
To change the HSM configuration, you need to reset your EJBCA Software Appliance. Proceed by clicking Activate.
Proceed with Activate.
The HSM device is displayed in a table in the Luna Network HSM Configuration section.
Luna Network HSM Configuration
Network Trust Link Service Certificate Authorities
In this section the Luna Network HSM is configured.
With this function, it is possible to change the server certificate on the HSM at any time without affecting the services.
The server certificate can be changed as long as the new server certificate is signed by a trusted CA that is registered in the Luna driver.
The uploaded certificates must contain the complete chain or the uploaded certificates have a path to the root certification authority. If this is not the case, an error message appears and the process cannot be continued.
Upload the root certification authority certificate first or the root certification authority certificate and the certificate to be uploaded are contained in the same pem file.
Log in to your Software Appliance and open the Security page.
In the Luna Network HSM Configuration section go to Network Trust Link Service Certificate Authorities.
Click Upload Trusted CA.
Browse to the file and upload the CA certificate.
A warning is displayed indicating that changing the HSM configuration will result in a restart of all applications on the Software Appliance.
The trusted CA is now listed in the table for the Network Trust Link Service Certificate Authorities.
In the Action column you can Download or Remove the entity.
The sub CA is marked in the table and is therefore easy to identify.
Network Trust Link Service Client Certificate
In this section Luna Certificate Signing Request (CSR) are created.
By adding a certificate that is signed by a trusted CA, it is possible to easily replace the client certificate as long as it is signed by a trusted CA that is also registered on the Luna HSM.
There are Luna-specific limitations that depend on how the client was registered and which version it is using. Please refer to the Thales Luna documentation.
Log in to your Software Appliance and open the Security page.
In the Luna Network HSM Configuration section go to the Network Trust Link Client Certificate.
Click Create Luna CSR. The corresponding form opens.
The options are different depending on which Luna Thales client was selected!
These options are available for all driver versions.Enter the Common Name (CN) to be included in the CSR.
Enter the Validity period for the client certificate in days.
Key Algorithms:
These options are only available in Thales Luna Client 10.7.2.
From the drop down menu chose the Key type for the CSR.
RSA as key type, here a sub menu is available to enter the Key size. Chose from 2048, 3072 or 4096.
Elliptic Curve as key type, here a sub menu is available to enter the Elliptic Curve Name.
Chose from secp256k1, secp384r1, secp521r1 or prime256v1.
This entry selects the ECC algorithm for this CSR.
ED25519 as key type does not include a sub menu.
Click Create Luna CSR to continue.
The new created Luna CSR will than be listed in the Network Trust Link Service Client Certificate list.
Should the certificate be Active and Self-Signed the following options appear in the Actions column:
Renew Self Signed Client Certificate or Download Client Certificate.
Should the certificate only be Active but not Self-Signed (signed by a CA) the following options appear in the Actions column:
Replace with self-signed Certificate or Download Client Certificate.
The CA-signed certificate can now be replaced by a newly generated, self-signed certificate.
For self-signed Certificates:
If the HSM client certificate has expired or the Common Name (CN) field is incorrect
click Renew Client Certificate.
A modal dialog follows:
Current HSM Client Certificate Common Name is stated.
Enter the new HSM Client Certificate Common Name.
Note that renewing the client certificate will permanently remove the old client certificate and the private key.
This action must be confirmed.
Tick the corresponding box.
Click Renew Certificate to initiate the process.
For CA-signed certificates:
A new CSR must be created, signed and uploaded or:
if the HSM client certificate has expired or the Common Name (CN) field is incorrect
click Replace Client Certificate.
A modal dialog follows:
Current HSM Client Certificate Common Name is stated.
Enter the new HSM Client Certificate Common Name.
Note that replacing the client certificate will permanently remove the old client certificate and the private key.
This action must be confirmed.
Tick the corresponding box.
Click Replace Certificate to initiate the process.
Is the CSR Awaiting Issuance three options are available in the Actions column.
Upload Client Certificate
Download CSR
Remove CSR
Remove CSR will trigger a modal dialog which indicates that when the CSR is removed, the associated private key is also deleted. The corresponding CSR can then no longer be downloaded.
This action must be confirmed. Tick the corresponding box.
Click Submit to initiate the process.
Luna Network HSM Devices
In the table all configured HSM Devices are displayed.
Address/FQDN
Port
Number Partitions
Action: Edit/Remove
Click Edit to edit the HSM Device. The corresponding form opens.
HSM IP Address/FQDN: Enter the IP address or the FQDN of the Luna Network HSM.
HSM Port: Enter the service port of the Luna Network HSM. The default port is 1792.
HSM Server Certificate: Drop the file into the field or Select File.
Click Edit HSM Device to save the settings.
Remove will trigger a modal dialog which indicates that changing the configuration of the HSM will restart all applications on the Software Appliance.
Click Remove to initiate the process.
Register the Software Appliance at the Luna Network HSM
Next, proceed with registering the Software Appliance at the Luna Network HSM.
The following provides example configuration steps on how to create a connection, by uploading the client certificate to the HSM, registering the client, and assigning a partition of the HSM to the client. For detailed information, refer to Thales docs on Creating an NTLS Connection Using Self-Signed Certificates.
To register and connect to the HSM:
On the Security page, section HSM Configuration, click Download Client Certificate to download and save the certificate.
Upload the client certificate to the Luna Network HSM.
scp <appliance IP>.pem <luna IP>:<appliance IP>.pemLog into the Luna Network HSM.
ssh admin@<luna IP> Register the client with the HSM:
client register -client <appliance name> -ip <appliance IP> Assign a partition of the HSM to the client.
client assignPartition -client <appliance name> -partition <partition name>On the Security page of the application, 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 application, 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.
The HA Group for Luna HSM
All HA Group configurations are grayed out, until a second HSM device is configured and it is possible to create a group.
If you want to use High-Availability HA Groups, at least two HSM devices must be configured.
To add HSMs, follow the same procedure as when configuring the first HSM.
As soon as an additional HSM Device is added, a warning appears to inform you that changing the configuration of the HSM will restart all applications on the Software Appliance.
The grayed out HA Groups area is now active because at least two HSM devices have been configured.
Create HA Group
Log in to your Software Appliance and open the Security page.
In the Luna Network HSM Configuration section go to HA Groups.
To open the corresponding form click Create HA Group.
In the form enter HA Group Label.
Select the Partitions you want to use for creating the HA Group.
Partition Order: the top partition is the one that creates new keys and then forwards the keys to the other partitions. If this order is to be changed, this is done here.
Specify the password used by all partitions in this HA group.
To confirm the settings and to create the HA group click Create HA Group.
Ensure that all requirements described in the Thales Luna Network Documentation Archive under "Setting up an HA Group" are taken into account. For more information, see Set up an HA Group.
After the HA group has been created, it appears in a table with its partitions.
The last column offers various Actions to be performed.
Edit: To modify the HA Group click Edit. The form that opens corresponds to the form from the previous step: Create HA Group.
Remove: To clear the HA Group click Remove. A modal dialog is waiting for confirmation, as changing the configuration of the HSM will cause the applications to restart.
Recover: If a partition had lost the connection or was temporarily inaccessible, trigger Recover manually. A pop up window indicates the recovery result.
Synchronize: Click Synchronize to synchronize the key material of all partitions again. A modal dialog indicates the synchronization result.
More information: To display a pop-up window with all important data of the HA group click More information. This is an inactive overview. Only synchronization can be triggered manually in this window. If one of the members is not alive, the line is highlighted in red and the Status is set to down.
HA Groups Settings
Log in to your Software Appliance and open the Security page.
In the Luna Network HSM Configuration section go to HA Groups Settings.
Check Enable HA log if HA logs are to be added to the system logs.
To set the number of seconds between the Recovery attempts of a failed HA group member, use the arrow keys.
To set the number of attempts to restore a failed member use the arrow keys to:
Enter the value -1 to set unlimited recovery attempts
Enter the value 0 to deactivate automatic recovery.
Click Save HSM Configuration in the Miscellaneous Configurations to save the settings.
Miscellaneous Configurations
Enter the following Miscellaneous Configurations:
Protected Authentication Path: Select the desired authentication protection using the drop down function:
No Challenge Request:
There will be no further authentication protection.Check for Crypto Officer Challenge Request (black PED key):
You need to insert the black PED (PIN Entry Device) key for authentication.Check for Crypto User Challenge Request (grey PED key):
You need to insert the grey PED (PIN Entry Device) key for authentication.
Moreover select the additional options:
Use HA Only mode:
This option is only selectable if a Luna HA group is configured. It hides the physical slots and leaves only the HA group slots visible to applications.Allow Login on FM enabled HSMs:
Allow login to a partition on an HSM that uses FM (Functionality Modules).
Finish with Save HSM Configuration.
Luna HA Key Synchronization
The Software Appliance will check every 40 seconds if at least one slot is available.
If no slot is found, the driver will shut down and EJBCA will no longer be available.
A Key Synchronization recovery of lost HA group members only works for Luna v1 partitions.
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:
On the Overview page of the Software Appliance, click Admin Web for EJBCA in the Application Overview column.
The EJBCA Enterprise page opens.
Check whether the Create new CA checkbox is selected.Open the CA Functions drop-down menu in the top menu.
In the CA Functions section, select Crypto Tokens.
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.