F5 Logo MyF5
Search
  1. MyF5 Home
  2. BIG-IP System and Network HSM: Implementation
  3. Setting Up the Network HSM
Manual Chapter : Setting Up the Network HSM

Applies To:

Show Versions Show Versions

BIG-IP AAM

  • 14.1.5, 14.1.4, 14.1.3, 14.1.2, 14.1.0

BIG-IP APM

  • 14.1.5, 14.1.4, 14.1.3, 14.1.2, 14.1.0

BIG-IP LTM

  • 14.1.5, 14.1.4, 14.1.3, 14.1.2, 14.1.0

BIG-IP AFM

  • 14.1.5, 14.1.4, 14.1.3, 14.1.2, 14.1.0

BIG-IP DNS

  • 14.1.5, 14.1.4, 14.1.3, 14.1.2, 14.1.0

BIG-IP ASM

  • 14.1.5, 14.1.4, 14.1.3, 14.1.2, 14.1.0
Manual Chapter

Setting Up the Network HSM

Overview: Setting up the Network HSM

F5 BIG-IP LTM 14.1.0 supports two new Network HSM vendors: Amazon CloudHSM and Equinix SmartKey HSM. Both of the two new Network HSMs can be configured by installing the client software from the vendor and configuring it by adding the path to the PKCS #11 library to the BIG-IP configuration. This allows the addition of new Network HSM vendors to occur with greater efficiency. In addition, Network HSM adds support for multiple partitions on a configured HSM and the ability to configure the partitions and define the partition that a key belongs to. Now the configuration of the partition occurs during the install process.
In support of the Network HSM functionality, you can either utilize the new
System > Certificate Management > HSM Management
screen or use the new TMSH commands to configure the Network HSM. If you install the HSM using the existing F5 install script, the information is auto-filled when you open the HSM Management screen. You can also manually install the library by adding the library location to the configuration.
After you install the Network HSM client on the BIG-IP system, you may create and operate with the keys inside the HSM for use with Access Policy Manager and Application Security Manager™.
If you are installing Network HSM on a BIG-IP system that will be licensed for Appliance mode, you must install the Network HSM software prior to licensing the BIG-IP system for Appliance mode.
For specific instructions for HSM client installation and configuration, follow the HSM vendor specific workflows in this guide that link you to the vendor sites where the steps are provided based on the version you want to install.
To view details for Thales HSM and SafeNet Luna SA HSM, see their supporting documentation on AskF5.

Prerequisites for setting up Network HSM with BIG-IP system

Before you can use Network HSM with the BIG-IP® system, you must make sure that these requirements are in place:
  • You have created the Network Security World (security architecture).
  • The BIG-IP system is licensed for "External Interface and Network HSM."
You cannot run the BIG-IP system with both internal and external HSMs at the same time.
BIG-IP TMOS with Network HSM only supports IPv4.
Other administrative information to keep in mind during setup:
  • Partition names must be unique.
  • Only one network HSM can be configured at a time.
  • You must identify a partition when installing a client (when using the F5 installer).
  • If you change the install path, client code, or any partition information, you must restart the pkcs11d daemon.
  • If you configure a cloud HSM from scratch (such as AWS CloudHSM and Equinix Smartkey), you must restart TMM daemon.
  • Run the test utility after making any changes to ensure that the HSM is configured correctly.
  • If you do not specify a partition when creating a key, the first listed partition will be used. The partition name will be automatically entered as "auto".
  • If you try to delete a partition when there are keys defined that use that partition, you will not be allowed to do so.
For supported Amazon CloudHSM and Equinix SmartKey HSM versions with BIG-IP TMOS versions information, see each of their respective Interoperability Matrix for BIG-IP TMOS with HSM supplemental document available on AskF5.

Supported Versions

Network HSM supported versions:
  • Amazon CloudHSM: Version 1.0.18 and 1.1.0
  • Equinix SmartKey: Version 2.9.804

Setting up Network HSM Client Installation and Configuration

To setup a network HSM for Amazon CloudHSM or Equinix SmartKey HSM you must have network access to the network HSM, as well as the DNS configured to resolve it.

Task Summary for Amazon CloudHSM and Equinix SmartKey HSM

  • Setup your Network HSM device
  • Install the client software and create a Cryptographic User (CU)
  • Configure and activate the software
  • Configure the BIG-IP
    • Add the HSM service (if any) to the BIG-IP startup scripts
    • Add the library path
    • Setup and configure partitions
  • Manage partitions

Setting up Amazon CloudHSM client installation and configuration

Set up your Amazon CloudHSM by following the documentation in the Getting Started section of the CloudHSM guide.
Amazon CloudHSM is only available for virtual machines running in the AWS cloud.
Your AWS BIG-IP VE is the EC2 client mentioned in the getting started guide and should be in the same VPC and availability zone as the CloudHSM. The getting started topics consist of information to assist creating, initializing, and activating AWS CloudHSM cluster.
Follow the AWS topic directions up until following the task steps found in the Install and Client (Linux) section.

Creating a cryptographic user

Manage your HSM cryptographic users (CU) or officers (CO) in your Amazon CloudHSM cluster by:
  • creating users
  • listing users
  • changing user passwords
  • deleting users
Follow the steps required at Managing HSM Users in AWS CloudHSM.

Installing the clients

Install the clients by logging into the AWS BIG-IP VE as root and run:
This client installation needs to be conducted after the BIG-IP upgrade process.
cd /shared/
mkdir nethsm
cd nethsm
 
curl -O https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL7/cloudhsm-client-pkcs11-3.2.1-1.el7.x86_64.rpm
curl -O https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL7/cloudhsm-client-3.2.1-1.el7.x86_64.rpm

rpm -ivh cloudhsm-client-pkcs11-3.2.1-1.el7.x86_64.rpm
rpm -ivh cloudhsm-client-3.2.1-1.el7.x86_64.rpm

Configuring and activating the software

To configure and activate the software you must edit the client configuration before you can use the CloudHSM client to connect to your cluster.
Follow the steps required at Edit the Client Configuration.
The link takes you to a resource outside of AskF5. It is possible the referred documents have been removed without our knowledge.

Configure the BIG-IP

To configure your BIG-IP with your newly configured and activated HSM, you can:
  • Add your HSM service to the BIG-IP startup scripts.
  • Add the library path and configure partitions.

Adding the HSM service to the BIG-IP startup scripts

To add your CloudHSM service to the BIG-IP startup scripts, run the following:
# systemctl enable cloudhsm-client.service

Adding the library path and configuring partitions

To add your CloudHSM library to the BIG-IP and configure the partitions, perform either the UI screen or CLI to accomplish the task.
  1. On the Main tab, click
    System
    Certificate Management
    External HSM
    . The External HSM screen opens.
  2. From the
    Vendor
     list, select
    Auto
    .
  3. In the
    PKCS11 Library Path
     field, type the following:
     
    /opt/cloudhsm/lib/libcloudhsm_pkcs11.so
  4. In the
    Partition List
     section, add the following details:
    1. In the
      Name
       field, type
      cavium
       (case sensitive).
      If you type
      auto
       in the
      Name
       field, the first available partition will be selected.
    2. In the Password field, type the <
      CU user name
      >:<
      password
      >
  5. Click
    Add
     to add as many partitions as necessary.
  6. To edit any existing partition, select the partition and click
    Edit
    .
  7. To delete any existing partition, select the partition and click
    Delete
    .
  8. To test any existing partition, select a partition and click
    Test
    .
  9. If you selected
    Test
    , review the Test Output to make sure your details are accurate.
    1. If the test does not pass, attempt to locate the problem and enable debug logging and run the test again for further details. The logs are writing to
      /var/log/ltm
      .
    Make sure to reset debug logging to the prior setting before continuing.
  10. Click
    Update
    .
If you are using the CLI, do the following:
  1. Add your CloudHSM library to the BIG-IP by entering:
    # tmsh create sys crypto fips external-hsm vendor auto pkcs11-lib-path /opt/cloudhsm/lib/libcloudhsm_pkcs11.so
  2. Configure the partition, by entering:
    # tmsh create sys crypto fips nethsm-partition <partition-name> password "<CU user name>:<password>"
    For <partition-name>, use "cavium" as it is the default partition name for AWS CloudHSM. You can also use "auto" to point to the first partition (which is normally the only partition for AWS CloudHSM).
  3. Reboot the appliance to start the service and create the links.
  4. Test your output by using the Network HSM testing tool and entering:
    # tmsh run sys crypto nethsm-test --hsm_partition_name=<partition-name>
    If you do not specify hsm_partition_name then the first partition (which is normally the only partition for AWS CloudHSM) will be chosen.

Creating a key in a partition

To create a key in a partition, do the following:
  1. On the Main tab, click
    System
    Certificate Management
    Traffic Certificate Management
    SSL Certificate List
    . The New SSL Certificate screen opens.
  2. Click
    Create
    . The New SSL Certificate screen opens.
  3. In the
    Name
     field, type the name of the new SSL certificate.
  4. In the
    Common Name
     field, type the common name of the certificate. For example,
    nethsm_ecdsa
    .
  5. From the
    NetHSM Partition
     list, select
    Default Partition
    .
  6. Click
    Finished
    .
    You can choose other partitions when you have multiple tokens or slots configured on your Network HSM that you use for keys.

Checking the partition for the key

To check the partition for the new key, do the following:
  1. On the Main tab, click
    System
    Certificate Management
    Traffic Certificate Management
    SSL Certificate List
    . The New SSL Certificate screen opens.
  2. Select the newly created SSL certificate name.
  3. Select the
    Key
     tab (if necessary) to check the partition for the key properties (such as name, key type, key ID, ect.).

Checking the service status

To check the service status, do the following:
  1. On the Main tab, click
    System
    Services
    Services List
    . The Service List screen opens.
  2. Locate the
    Service
     name (for example, pkcs11d) and view the History information.
  3. Click
    Start
    ,
    Stop
    , or
    Restart
     as necessary.

Setting up Equinix SmartKey HSM client installation and configuration

Create and set up your Equinix SmartKey HSM account by following the SmartKey Getting Started information.
Create the group and application as noted in the SmartKey instructions.
Make note of the API key after creating the application. The API key information can be useful later.

Installing the clients

Download the Smartkey PKCS#11 RPM package version 2.9.804 from http://support.smartkey.io/downloads/smartkey-pkcs11-2.9.804-0.x86_64.rpm.
The downloaded file
smartkey-pkcs11-2.9.804-0.x86_64.rpm
 contains the RPM package name
fortanix-pkcs11-2.9.804-0
. Attempting to delete the package using
smartkey-pkcs11-2.9.804-0
 as the package name will fail. We recommend you rename the file from
smartkey-pkcs11-2.9.804-0.x86_64.rpm
 to
fortanix-pkcs11-2.9.804-0.x86_64.rpm
 before proceeding. This is especially relevant when doing automated/declarative package installations.
Use the following command to install the RPM package upload to the /shared/tmp folder and install it as root:
rpm -ivh /shared/tmp/<RPM package file name>

Adding the library path and configuring partitions

To add your SmartKey HSM library to the BIG-IP and configure the partitions, perform either the UI screen or CLI to accomplish the task.
  1. On the Main tab, click
    System
    Certificate Management
    HSM Management
    External HSM
    . The External HSM screen opens.
  2. From the
    Vendor
     list, select
    Auto
    .
  3. In the
    PKCS11 Library Path
     field, type the following:
     
    /opt/fortanix/pkcs11/fortanix_pkcs11.so
  4. In the
    Partition List
     section, add the following details:
    1. In the
      Name
       field, type
      fortanix
       (case sensitive).
      If you type
      auto
       in the
      Name
       field, the first available partition will be selected.
    2. In the Password field, type the <
      API Key
      >
      The user name and password are based on the Cryptographic user created earlier.
  5. Click
    Add
     to add as many partitions as necessary.
  6. To edit any existing partition, select the partition and click
    Edit
    .
  7. To delete any existing partition, select the partition and click
    Delete
    .
  8. To test any existing partition, select a partition and click
    Test
    .
  9. If you clicked
    Test
    , review the Test Output to make sure your details are accurate.
    1. If the test does not pass, attempt to locate the problem and enable debug logging and run the test again for further details. The logs are writing to
      /var/log/ltm
      .
    Make sure to reset debug logging to the prior setting before continuing.
  10. Click
    Update
    .
If you are using the CLI, do the following:
  1. Add your SmartKey HSM library to the BIG-IP by entering:
    # tmsh create sys crypto fips external-hsm vendor auto pkcs11-lib-path /opt/fortanix/pkcs11/fortanix_pkcs11.so
  2. Configure the partition, by entering:
    # tmsh create sys crypto fips nethsm-partition <partition-name> password "<API Key>"
    For <partition-name>, use "fortanix" as it is the default partition name for Equinix SmartKey.
  3. Reboot the appliance to start the service and create the links.
  4. Test your output by using the Network HSM testing tool and entering:
    # tmsh run sys crypto nethsm-test --hsm_partition_name=<partition-name>
If you do not specify hsm_partition_name, then the first partition (which is normally the only partition for Equinix SmartKey) will be chosen.
By default, smartkey-client makes REST API calls to the SmartKey server at https://www.smartkey.io. To make calls to a different SmartKey server, create a file named
/config/smartkey.cfg
 with the SmartKey server of your choice and the API key. The format of the
/config/smartkey.cfg
 file is defined in the “Configuration file format” section at http://support.smartkey.io/smartkey/developers-guide-pkcs11.html. To make use of this SmartKey configuration file, when configuring the partition (Step 2), use the following command line instead:
tmsh create sys crypto fips nethsm-partition <partition-name> password "file:///config/smartkey.cfg"
A sample configuration file is shown next:
# cat /config/smartkey.cfg
api_key="<API Key>"
api_endpoint=https://eu.smartkey.io
Contact Support Contact Support

Have a Question?

Support and Sales >

About F5

Education

F5 Sites

Support Tasks




©2023 F5, Inc. All rights reserved.


Trademarks Policies Privacy California Privacy Do Not Sell My Personal Information