HSM Integration

A hardware security module (HSM) is a dedicated device for managing digital keys and performing cryptographic operations. An HSM can be a plug-in card or an external device directly connected to a computer or network server. Purposefully designed to protect the crypto-key life cycle, HSMs have been used by some of the world's most security-conscious entities to protect their cryptographic infrastructure by securely managing, processing, and storing cryptographic keys inside a hardened, tamper-resistant device.

Because of their strengths in securing cryptographic keys and provisioning encryption, decryption, authentication, and digital signing services for a wide range of applications, HSMs have been used by enterprises worldwide to safeguard their online transactions, identities, and applications.

Integrating FortiADC with SafeNet Network HSM

Starting from Version 4.7.2, FortiADC has integrated with SafeNet Network HSM. It enables you to retrieve a per-connection, SSL session key from the HSM server instead of loading the private key and certificate stored on FortiADC.

The integration requires specific configuration steps on both the FortiADC and the HSM appliances, as outlined below:

On the HSM appliance:

• Create one or more HSM partitions for FortiADC
• Send the FortiADC client certificate to the HSM server
• Register the FortiADC HSM client to the partition(s)
• Retrieve the HSM server certificate

On the FortiADC appliance:

• Configure communication with the HSM server, including using the server and client certificates to register FortiADC as a client of the HSM server
• Generate a certificate-signing request (CSR) that includes the HSM's configuration information
• Upload the signed certificate to FortiADC

It must be noted that

• Currently, FortiADC supports the SafeNet Network HSM only.
• HSM support is disabled on FortiADC by default. You must enable it via the CLI for the feature to become available on the FortiADC GUI. To enable HSM support from the CLI, execute the following commands:

  config system global

  set hsm enable

• You must have the HSM server certificate available on your local PC or a network drive.
• HSM integration supports all HA modes, i.e., active-active, active-passive, and VRRP.
• HSM partition is a global configuration that can be used from individual VDOMs.
• HSM integration does not support configuration synchronization (config-sync), but local certificate using HSM can be synchronized to peer FortiADC appliances. Keep in mind that this local certificate may NOT function properly on peer FortiADC appliances.
• Network Trust Links (NTLs) IP check (ntls ipcheck) must be disabled on the HSM server for HA configuration.

The following instructions assume that you have (1) HSM support enabled on FortiADC and (2) access to the HSM server certificate from your PC.

Preparing the HSM appliance

Before starting to configure FortiADC-HSM integration, you must configure the SafeNet Network HSM first using the following steps:

1. On the SafeNet Network HSM, use the partition create command to create and initialize a new HSM partition that uses password authentication.
   Note: This is the partition FortiADC uses on the HSM server. You can create more than one partition, but all the partitions are assigned to the same client. For more information, see HSM-related documentation.
2. Use the SCP utility and the following command to send the FortiADC client certificate to the HSM:
   scp <fortiadc_ip>.pem admin@<hsm_ip>:
3. Using SSH, connect to the HSM server using the admin account. Then, use the following command to register a client for FortiADC on the HSM server:
   lunash:> client register -c <client_name> -ip <fortiadc_ip>, where <client_name> is the name you specify that identifies the client.
4. Use the following command to assign the client you registered to the partition you've created in Step 1 above:lunash:> client assignPartition -client <client_name> -partition <partition_name>
   You can verify the assignment using the following command:
   lunash:> client show -client <client_name>
5. Repeat the client assignment process for any additional partitions you've created for FortiADC.
6. Use the SCP utility and the following command to retrieve the server certificate file from the HSM server:
   scp <hsm_username>@<hsm_ip>:server.pem /usr/lunasa/bin/server_<hsm_ip>.pem
7. On the FortiADC GUI, navigate to System>HSM to bring up the HSM configuration page.
8. Complete the HSM configuration as described in HSM Configuration Parameters. Then move on to Generating a certificate-signing request on FortiADC.

HSM Configuration Parameters

Parameter	Description
Client Certificate
Client IP	Enter the IP address of the interface (i.e., port) which FortiADC uses to generate the client certificate. Note: This IP address is the common name of client certificate. FortiADC is the client of the HSM server. The client and server certificates are used in SSL connection between FortiADC and the HSM server.
Generate	Click this button to generate the client certificate that you've specified above. Note: Use this option only if you do not have an existing client certificate on FortiADC.
Download	Click this button retrieve the client certificate that you have just generated or stored on FortiADC. Note: You must generate a client certificate if you do not have one already residing on FortiADC. See above.
Configuration	Complete the following entries or selections to configure the FortiADC-HSM integration.
Server IP	Enter the IP address of the HSM server.
Port	Specify the port via which FortiADC establishes an NTLS connection with the HSM server. The default value is 1792.
Timeout	Specify a timeout value for the connection between FortiADC and the HSM server. The default is 20000. Valid values range from 5000 to 20000 milliseconds.
Upload Server Certificate File	Click Browse to browse for the server certificate file that you retrieved earlier.
Register	Click this button to register FortiADC as a client of the HSM sever using the specified server and client certificates. Note: This action generates a config file, e.g., /example.conf
Unregister	Click this button to clear all HSM-related configurations on the back-end.
Partition	Click Create New to create partition or Delete to remove a selected partition. Note: FortiADC can accept only one partition. Once a partition is added, the Register and Unregister buttons become dimmed out, meaning you cannot make any change to the HSM configuration. To edit the HSM configuration, you must delete the partition first.
Partition Name	Specify the name of a partition to which the FortiADC HSM client is assigned.
Password	Specify the password for the partition.

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

Generating a certificate-signing request on FortiADC

Once you have completed configuring the HSM server, you must generate a certificate-signing request which references the HSM connection and partition from inside FortiADC.

To generate a certificate-signing request:

1. On the FortiADC GUI, navigate to System > Manage Certificates > Local Certificate.
2. Click Generate to bring up the Local Certificate configuration page.
3. Configure the certificate-signing request as described in Generating a certificate-signing request. Then move on to Downloading and uploading the certificate request (.csr) file.

Generating a certificate-signing request

Parameter	Description
Generate Certificate Signing Request	Complete the following entries or selections to configure the FortiADC-HSM integration.
Certificate Name	Specify a name for the certificate request, e.g., www.example.com. This can be the name of your web site.
Subject Information	Specify the information that the certificate is required to contain in order to uniquely identify the FortiADC appliance. This area varies depending on the ID Type you select.
ID Type	Select the type of identifier to use in the certificate to identify the FortiADC appliance: Host IP — Select this option if the FortiADC appliance has a static IP address, and then enter the public IP address of the FortiADC appliance in the IP field. If the FortiADC appliance does not have a public IP address, use Domain Name or Email instead. See below. Domain Name — Select this option if the FortiADC appliance has a static IP address and subscribes to a dynamic DNS service. Enter the FQDN of the FortiADC appliance, such as www.example.com, in the Domain Name field, but do NOT include the protocol specification (http://) or any port number or path names. Email — Select this option if the FortiADC appliance does not require either a static IP address or a domain name. Enter the email address of the owner of the FortiADC appliance in the Email field. The ID type you can select varies by whether or not your FortiADC appliance has a static IP address, a fully-qualified domain name (FQDN), and by the primarily intended use of the certificate. For example, if your FortiADC appliance has both a static IP address and a domain name, but you will primarily use the local certificate for HTTPS connections to the web UI by the domain name of the FortiADC appliance, you might prefer to generate a certificate based upon the domain name of the FortiADC appliance rather than its IP address. Depending on your choice for ID Type, the other options may vary.
IP	Note: This option appears only if the ID Type is Host IP. Enter the static IP address of the FortiADC appliance, such as 10.0.0.1. The IP address must be the one visible to clients. Usually, this should be its public IP address on the Internet, or a virtual IP that you use NAT to map to the appliance’s IP address on your private network.
Domain Name	Note: This option appears only if the ID Type is Domain Name. Enter the fully qualified domain name (FQDN) of the FortiADC appliance, such as www.example.com. The domain name must resolve to the static IP address of the FortiADC appliance or a protected server.
Email	Note: This option appears only if the ID Type is Email. Enter the email address of the owner/user of the FortiADC appliance, such as admin@example.com.
Distinguished Information	The following information is OPTIONAL in the certificate; it is NOT required.
Organization unit	Enter the name of your organizational unit (OU), such as the name of your department. To enter more than one OU name, click the + icon, and enter each OU in each separate field.
Organization	Enter the legal name of your organization.
Locality(City)	Enter the name of the city or town where the FortiADC appliance is deployed.
State/Province	Enter the name of the state or province where the FortiADC appliance is deployed.
Country/Region	Select the name of the country where the FortiADC appliance is deployed.
Email	Enter an email address that may be used for contact purposes, such as admin@example.com.
Key Information	Enter the information pertinent to the key.
Key Type	This field shows the type of algorithm used to generate the key. Note: It's read-only and cannot be changed. FortiADC 4.7.2 supports RSA key type only.
Key Size	Select one of the following key sizes: 512 bit 1024 bit 1536 bit 2048 bit 4096 bit Note: Larger keys may take longer to generate, but provide better security.
HSM	Select this option if the private key for the connections is provided by an HSM appliance instead of FortiADC. Note: This option is available only if you have enabled HSM via the CLI using the config system global command. For more information, see Integrating FortiADC with SafeNet Network HSM.
Partition Name	Enter the name of the partition where the private key for this certificate is located on the HSM server. Note: This option becomes available only when HSM is selected. See above.
Enrollment Information
Enrollment Method	Select either of the following: File Based —If selected, you must manually download and submit the resulting certificate signing request (.csr) file to a certificate authority (CA) for signing. Once signed, you need to upload the local certificate. This is the only enrollment method if HSM is selected. Online SCEP — If selected, the FortiADC appliance will automatically use HTTP to submit the certificate-signing request to the simple certificate enrollment protocol (SCEP) server of a CA, which will validate and sign the certificate. Note: For this selection, two more options appear: CA Server URL and Challenge Password. This option is not available if HSM is selected.

Downloading and uploading the certificate request (.csr) file

Normally, when generating a certificate-signing request, the FortiADC appliance creates a private and public key pair. The generated request includes the public key of the FortiADC appliance and information such as the FortiADC appliance’s IP address, domain name, or email address. The FortiADC appliance’s private key remains confidential on the FortiADC appliance. The Status column of the entry is PENDING.

If you configured your CSR to work with the FortiADC-HSM integration, the CSR generation process creates a private key both on the HSM and on FortiADC appliances. The private key on the HSM is used to secure communication when FortiADC uses the certificate. The FortiADC private key is used when you upload the certificate to FortiADC.

After you have submitted a certificate-signing request from inside FortiADC as discussed above, you must go back to the System > Management Certificates > Local Certificate page to download the certificate request (.csr) file, and then upload that file to your certificate authority (CA) by taking the following steps:

1. On the System > Manage Certificates > Local Certificate page, locate the entry of the certificate request.
2. Click the Download icon.
   Note: The time it takes to download the certificate request (.csr) file varies, depending on the size of the file and the speed of your network connection. After the file is downloaded, save it at a location on your machine.
3. Upload the certificate request (.csr) file to your CA.
   Note: Upon receiving the certificate request file, the CA will verify the information in the certificate, give it a serial number and an expiration date, and sign it with the public key of the CA.
4. If you are not using a commercial CA whose root certificate is already installed by default on web browsers, download your CA’s root certificate, and then install it on all computers that will be connecting to your FortiADC appliance.
   Note: You must have the certificate installed on the computers. Otherwise, they may not trust your new certificate. After you have received the signed certificate from the CA, upload it to FortiADC, as discussed below.

Uploading the server certificate to FortiADC

You must have the Read and Write permission to upload server certificates to the FortiADC appliance.

To upload the server certificate to FortiADC:

1. On the FortiADC GUI, navigate to the System > Manage Certificates > Local Certificate page.
2. Click Import.
3. Make the selections as described in Uploading a server certificate, and click Save.

Uploading a server certificate

Parameter	Description
Type	Click the down arrow and select one of the following options from the drop-down menu: Local Certificate—Use this option only if you have a CA-signed certificate that was originated from a CSR generated in FortiADC . See HSM Integration. Note: It is important to make sure that the load-balancer (FortiADC appliance) you use to import a local certificate is the same appliance where the CSR was generated because it is where the key matching the certificate resides. The import operation will fail without the matching key on the same hardware system. PKCS12 Certificate—Use this option only if you have a PKCS #12 password-encrypted certificate with its key in the same file. Certificate—Use this option only if you have a certificate and its key in separate files. Note: Additional fields are displayed depending on your selection.
Certificate File	Click Browse to locate the certificate file that you want to upload.
Certificate Name	The name of the certificate. Note: This field applies when Type is Certificate or PKCS12.
Key File	Click Browse to locate the key file that you want to upload with the certificate. Note: This option is available only if Type is Certificate.
Password	Enter the password used to encrypt the server certificate file. Note: This enables FortiADC to decrypt and install the certificate. This option is available only if Type is Certificate or PKCS12 Certificate.

Once a certificate is uploaded to FortiADC, you can use it in a policy or server pool configuration.