Fortinet black logo

Administration Guide

Using session keys provided by an HSM

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.

caution icon This release only supports SafeNet Network HSM 7 device. 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.
To integrate FortiWeb with SafeNet Network HSM 7
  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.
  2. partition create -par <fortiweb> -pas <fortiweb> -do <fortinet.com>

    For details, see the HSM documentation.

  3. Use an SCP utility and the following command to retrieve the server certificate file from the HSM to local PC.
  4. scp –c aes256-cbc <hsm_username>@<hsm_ip>:server.pem

    <local_pc>/server_<hsm_IP>.pem

  5. On FortiWeb - Log in to CLI, enable the HSM function and the high compatibility mode.
  6. config server-policy setting

    set hsm enable

    set high-compatibility-mode enable

    end

  7. Register FortiWeb to HSM.
    Go to System > Config > HSM and complete the following settings:
  8. 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.
    Create Client Click Create Client to create FortiWeb as a client of the HSM using the specified server and client certificates. You will be prompted to return when creation is successful.
    Destroy Client Click Destroy Client to cancel FortiWeb as a client of the HSM.
    Download Client Certificate File Click Download to download the client certificate file to local PC.
    Available only when Create Client is successful.
  9. After the creation is completed, 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.
  10. Use the SCP utility and the following command to send the downloaded FortiWeb client certificate to the HSM.
  11. scp –c aes256-cbc <local_PC>/<fortiweb_ip>.pem admin@<hsm_ip>:

  12. 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.
  13. lunash:> client register -c <client_name> -i <fortiweb_ip>

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

  14. Use the following command to assign the client you registered to the partition you created earlier:
  15. lunash:> client assignPartition -client <client_name> -partition <partition_name>

    You can verify the assignment using the following command:

    lunash:> client show -client <client_name>

  16. On FortiWeb - Add the partition and password created previously on HSM.
    Go to System > Config > HSM. Click Create New and complete the following settings.
  17. Partition Name Enter the name of a partition that the FortiWeb HSM client is assigned to.
    Password
    Enter the partition password.
  18. Go to Certificates > Local and click Generate to generate a certificate signing request that references the HSM connection and partition.
  19. For details, see Using session keys provided by an HSM.

  20. After the HSM-based certificate is signed by CA, go to Certificate > Local and click Import to import it.
  21. For details, see Using session keys provided by an HSM.

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

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.

caution icon This release only supports SafeNet Network HSM 7 device. 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.
To integrate FortiWeb with SafeNet Network HSM 7
  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.
  2. partition create -par <fortiweb> -pas <fortiweb> -do <fortinet.com>

    For details, see the HSM documentation.

  3. Use an SCP utility and the following command to retrieve the server certificate file from the HSM to local PC.
  4. scp –c aes256-cbc <hsm_username>@<hsm_ip>:server.pem

    <local_pc>/server_<hsm_IP>.pem

  5. On FortiWeb - Log in to CLI, enable the HSM function and the high compatibility mode.
  6. config server-policy setting

    set hsm enable

    set high-compatibility-mode enable

    end

  7. Register FortiWeb to HSM.
    Go to System > Config > HSM and complete the following settings:
  8. 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.
    Create Client Click Create Client to create FortiWeb as a client of the HSM using the specified server and client certificates. You will be prompted to return when creation is successful.
    Destroy Client Click Destroy Client to cancel FortiWeb as a client of the HSM.
    Download Client Certificate File Click Download to download the client certificate file to local PC.
    Available only when Create Client is successful.
  9. After the creation is completed, 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.
  10. Use the SCP utility and the following command to send the downloaded FortiWeb client certificate to the HSM.
  11. scp –c aes256-cbc <local_PC>/<fortiweb_ip>.pem admin@<hsm_ip>:

  12. 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.
  13. lunash:> client register -c <client_name> -i <fortiweb_ip>

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

  14. Use the following command to assign the client you registered to the partition you created earlier:
  15. lunash:> client assignPartition -client <client_name> -partition <partition_name>

    You can verify the assignment using the following command:

    lunash:> client show -client <client_name>

  16. On FortiWeb - Add the partition and password created previously on HSM.
    Go to System > Config > HSM. Click Create New and complete the following settings.
  17. Partition Name Enter the name of a partition that the FortiWeb HSM client is assigned to.
    Password
    Enter the partition password.
  18. Go to Certificates > Local and click Generate to generate a certificate signing request that references the HSM connection and partition.
  19. For details, see Using session keys provided by an HSM.

  20. After the HSM-based certificate is signed by CA, go to Certificate > Local and click Import to import it.
  21. For details, see Using session keys provided by an HSM.

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