Using session keys provided by an HSM

You can integrate FortiWeb with SafeNet Network HSM 7 (hardware security module) to retrieve a per-connection, SSL session key instead of loading the private key and certificate stored on FortiWeb.

This release supports SafeNet Network HSM 5, 6, and 7 device, and device models older than SafeNet Network HSM 5 are not supported. Do confirm your device model before upgrading FortiWeb. Before the upgrade, you need to manually delete the original HSM configurations to avoid configuration residual. Otherwise, you need to manually delete the original HSM certificate, HSM partition, and HSM info configurations, and then reconfigure it.

Integration of SafeNet Network HSM 7 with FortiWeb requires specific configuration steps for both appliances, including the following tasks:

• On the HSM:
  • Create one or more HSM partitions for FortiWeb
  • Send the FortiWeb client certificate to the HSM
  • Register the FortiWeb HSM client to the partition
  • Retrieve the HSM server certificate
• On FortiWeb:
  • Configure communication with the HSM, including using the server and client certificates to register FortiWeb as a client of the HSM
  • Generate a certificate signing request (CSR) that includes the HSM configuration information
  • Upload the signed certificate to FortiWeb

When configuring your CSR to work with an HSM, the CSR generation process creates a private key on both the HSM and FortiWeb. The private key on the HSM is the "real" key that secures communication when FortiWeb uses the signed certificate. The key found on the FortiWeb is used when you upload the certificate to FortiWeb.

FortiWeb supports integrating a standalone HSM server, and also supports two HSM servers working as HA. The procedures are slightly different for standalone mode and HA mode.

To integrate FortiWeb with SafeNet Network HSM 7 - standalone mode

1. On HSM - Use the partition create command to create and initialize a new HSM partition that uses password authentication. This is the partition FortiWeb uses on the HSM. FortiWeb supports only one partition.

partition create -par <fortiweb> -pas <fortiweb> -do <fortinet.com>

For details, see the HSM documentation.

2. Use an SCP utility and the following command to retrieve the server certificate file from the HSM to local PC.

scp –c aes256-cbc <hsm_username>@<hsm_ip>:server.pem

<local_pc>/server_<hsm_IP>.pem

3. On FortiWeb - Log in to CLI, enable the HSM function and the high compatibility mode.

config server-policy setting

set hsm enable

set high-compatibility-mode enable

end

4. Register FortiWeb to HSM.
   Go to System > Config > HSM, select the HSM Server tab, and complete the following settings:

Server IP	Enter the IP address of the HSM.
Port	Enter the port where FortiWeb establishes an NTLS connection with the HSM. The default is 1792.
Timeout	Enter a timeout value for the connection between HSM and FortiWeb.
Upload Server Certificate File	Click Choose File and navigate to the server certificate file you retrieved in step 2.

5. After the creation is completed, go to the HSM server table, select the server, then click Download to download the client certificate file to local PC. Please note that client file is not available to download if the creation is not successful.
6. Use the SCP utility and the following command to send the downloaded FortiWeb client certificate to the HSM.

scp –c aes256-cbc <local_PC>/<fortiweb_ip>.pem admin@<hsm_ip>:


7. On HSM - Using SSH, connect to the HSM using the admin account, and then use the following command to register a client for FortiWeb on the HSM.

lunash:> client register -c <client_name> -i <fortiweb_ip>


where <client_name> is a name you choose that identifies the client.

8. Use the following command to assign the client you registered to the partition you created earlier:

lunash:> client assignPartition -client <client_name> -partition <partition_name>


You can verify the assignment using the following command:

lunash:> client show -client <client_name>


9. On FortiWeb - Add the partition and password created previously on HSM.
   Go to System > Config > HSM, select the HSM Partition tab, then click Create New and complete the following settings.
   

Partition Name	Enter the name of a partition that the FortiWeb HSM client is assigned to.
Label	Enter a label for the partition.
Server	Select the HSM server to which this partition belongs.
Password	Enter the partition password.

10. Go to Certificates > Local and click Generate to generate a certificate signing request that references the HSM connection and partition.

For details, see Using session keys provided by an HSM.

11. After the HSM-based certificate is signed by CA, go to Certificate > Local and click Import to import it.

For details, see Using session keys provided by an HSM.

12. To use a certificate, you select it in a policy or server pool configuration. For details, see Configuring a server policy or Creating an HTTP server pool.

To integrate FortiWeb with SafeNet Network HSM 7 - HA mode

FortiWeb supports two HSM servers working as HA. At most eight partitions on the two servers are allowed to be associated with FortiWeb.

1. On HSM - Use the partition create command to create and initialize a new HSM partition that uses password authentication. This is the partition FortiWeb uses on the HSM. FortiWeb supports only one partition.

partition create -par <fortiweb> -pas <fortiweb> -do <fortinet.com>

For details, see the HSM documentation.

2. Use an SCP utility and the following command to retrieve the server certificate file from the HSM to local PC.

scp –c aes256-cbc <hsm_username>@<hsm_ip>:server.pem

<local_pc>/server_<hsm_IP>.pem

3. On FortiWeb - Log in to CLI, and run the following commands to enable the HSM function, the high compatibility mode, and the HSM HA mode.

config server-policy setting

set hsm enable

set high-compatibility-mode enable

set hsm-ha enable

end

4. Register FortiWeb to HSM.
   Go to System > Config > HSM, select the HSM Server tab, and complete the following settings:

Server IP	Enter the IP address of the HSM.
Port	Enter the port where FortiWeb establishes a NTLS connection with the HSM. The default is 1792.
Timeout	Enter a timeout value for the connection between HSM and FortiWeb.
Upload Server Certificate File	Click Choose File and navigate to the server certificate file you retrieved in step 2.

5. After the creation is completed, go to the HSM server table, select the server, then click Download to download the client certificate file to local PC. Please note that client file is not available to download if the creation is not successful.
6. Use the SCP utility and the following command to send the downloaded FortiWeb client certificate to the HSM.

scp –c aes256-cbc <local_PC>/<fortiweb_ip>.pem admin@<hsm_ip>:


7. On HSM - Using SSH, connect to the HSM using the admin account, and then use the following command to register a client for FortiWeb on the HSM.

lunash:> client register -c <client_name> -i <fortiweb_ip>


where <client_name> is a name you choose that identifies the client.

8. Use the following command to assign the client you registered to the partition you created earlier:

lunash:> client assignPartition -client <client_name> -partition <partition_name>


You can verify the assignment using the following command:

lunash:> client show -client <client_name>


9. On FortiWeb - Add the partition and password created previously on HSM.
   Go to System > Config > HSM, select the HSM Partition tab, then click Create New and complete the following settings.
   

Partition Name	Enter the name of a partition that the FortiWeb HSM client is assigned to.
Label	Enter a label for the partition.
Server	Select the HSM server to which this partition belongs.
Password	Enter the partition password.

10. Go to Certificates > Local and click Generate to generate a certificate signing request that references the HSM connection and partition.

For details, see Using session keys provided by an HSM.

11. After the HSM-based certificate is signed by CA, go to Certificate > Local and click Import to import it.

For details, see Using session keys provided by an HSM.

12. To use a certificate, you select it in a policy or server pool configuration. For details, see Configuring a server policy or Creating an HTTP server pool.
13. Go to System > Config > HSM, then select the HSM Group tab.
    1. Click Create New. Enter a name for the server group. Click Save.
    2. Click Create New. Select the HSM partition you have created. Click OK. Repeat this step to add more partitions.

Perform the steps listed above to configure the other HSM server in HA mode. The first added server will be selected as the primary node.