Using SmartKey with F5 BIG-IP

Updated: 10 Dec 2019

Overview

F5’s BIG-IP uses SmartKey to store RSA or EC keys used in the key exchange and authentication of TLS sessions. When using SmartKey, BIG-IP no longer stores these keys locally. Instead, it calls SmartKey’s APIs to perform Sign operations during the server authentication phase of the TLS handshake. The private key never leaves the SmartKey HSM and the asymmetric encryption of the TLS sessions is off-loaded to SmartKey. SmartKey can be used for both client-side and/or server-side connections.

By decrypting the traffic between the client and the back-end server, BIG-IP is able to perform advanced functionalities such as:

  • Advanced Web Application Firewall including Anti-Bot and Anti-L7 DoS.
  • Dynamic Service Chaining, supporting all traffic inspection devices.
  • Intelligent application traffic management and performance optimization.
  • Single Sign-On and desktop virtualization delivery.
  • By combining with Equinix Cloud Exchange, F5 can perform service discovery dynamically.

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.

Note:

  • You will need to create a group and application as noted in the SmartKey instructions. The application needs to be assigned to the created group.
  • Make note of the API key after creating the application. The API key will be used later. Click on the icon for “Copy UUID” to copy it to clipboard.

img

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.

Note: 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.

Using UI

  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:
    a. In the Name field, type fortanix (case sensitive). Note: If you type auto in the Name field, the first available partition will be selected.
    b. In the Password field, type the <API Key> Note: 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. a. 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. Note: Make sure to reset debug logging to the prior setting before continuing.
  10. Click Update.

Using CLI

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/libpkcs11_lib.so
    
  2. Configure the partition, by entering:

     # tmsh create sys crypto fips nethsm-partition <partition-name> password "<API Key>"
    

    Note: 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>
    

Note: If you do not specify hsm_partition_name, then the first partition (which is normally the only partition for Equinix SmartKey) will be chosen.

Note: 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"

Note: A sample configuration file is shown next:

# cat /config/smartkey.cfg
api_key="<API Key>"
api_endpoint=https://api.amer.smartkey.io