Manual Chapter : Setting Up the Network HSM

Applies To:

  • BIG-IP APM

    17.0.0

  • BIG-IP LTM

    17.0.0

  • BIG-IP AFM

    17.0.0

  • BIG-IP DNS

    17.0.0

  • BIG-IP ASM

    17.0.0

back-action BIG-IP System and Network HSM: Implementation

Updated Date: 06/08/2026

Setting Up the Network HSM

F5 BIG-IP supports the following Network HSM vendors:

  • Amazon CloudHSM
  • Equinix SmartKey HSM
  • SafeNet Data Protection on Demand (DPoD) HSM
  • Atos (Bull Trustway Proteccio) HSM
  • IBM HPCS HSM
  • SafeNet Luna SA HSM
  • nShield HSM

These 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™.

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

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

Important: You cannot run the BIG-IP system with both internal and external HSMs at the same time.

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

Note: For supported Network HSM versions with BIG-IP TMOS versions information, see each vendor’s respective Interoperability Matrix for BIG-IP TMOS with HSM supplemental document available on AskF5.

Network HSM supported versions:

  • Amazon CloudHSM: Version 2.0.4
  • Equinix SmartKey: Version 2.24.1051
  • Atos Proteccio: Version 1.08.18
  • DPoD: Version 1.1.0
  • IBM HPCS: Version 2.4.117

To setup a Network HSM, you must have network access to the HSM with the DNS configured to resolve it.

  • 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

Set up your Amazon CloudHSM by following the documentation in the Getting Started section of the CloudHSM guide.

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

Note: Follow the AWS topic directions up until following the task steps found in the Install and Client (Linux) section.

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.

Install the clients by logging into the AWS BIG-IP VE as root and run:

Note: 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/EL6/cloudhsm-client-3.2.1-1.el6.x86\_64.rpm ](https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL6/cloudhsm-client-3.2.1-1.el6.x86_64.rpm) 
curl -O [https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL6/cloudhsm-client-pkcs11-3.2.1-1.el6.x86\_64.rpm](https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL6/cloudhsm-client-pkcs11-3.2.1-1.el6.x86_64.rpm)

rpm -ivh ./cloudhsm-client-pkcs11-1.0-18.x86_64.rpm
rpm -ivh ./cloudhsm-client-1.0-18.x86_64.rpm

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.

Note: The link takes you to a resource outside of AskF5. It is possible the referred documents have been removed without our knowledge.

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.

To add your CloudHSM service to the BIG-IP startup scripts, run the following:

# systemctl enable cloudhsm-client.service

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_standard.so

  4. In the Partition List section, add the following details:

    1. In the Name field, type cavium (case sensitive).

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

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

  2. Configure the partition, by entering:

    # tmsh create sys crypto fips nethsm-partition <partition-name> password "<CU user name>:<password>"

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

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

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.

    Note: You can choose other partitions when you have multiple tokens or slots configured on your Network HSM that you use for keys.

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

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.

Create and set up your Equinix SmartKey HSM account by following the SmartKey Getting Started information.

Note: Create the group and application as noted in the SmartKey instructions.

Note: Make note of the API key after creating the application. The API key information can be useful later.

Install the clients by following the SmartKey developer’s guide instructions while logged into the BIG-IP as root.

Note: Use the 2.9.804 client instead of the client linked in the SmartKey instructions.

Note: After installing the RPM package, the installed RMP package name may change from rpm -i smartkey-pkcs11-2.9.804-0.x86_64.rpm to rpm -q -l fortanix-pkcs11-2.9.804-0.x86_64.rpm. If you are attempting to remove the package, search for it using the possible naming options noted here.

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

      Note: If you type auto in the Name field, the first available partition will be selected.

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

    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.

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

    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, set the environment variable FORTANIX_API_ENDPOINT (FORTANIX_API_ENDPOINT=<smartkey-server-url>).

To set up your SafeNet DPoD HSM, you must first Install the software to the BIG-IP and complete the configuration steps. For additional SafeNet/Gemalto set up information, follow the documentation from their site listed below.

  • You have obtained a SafeNet DPoD account with the HSM on Demand setup-<servicename>.zip file and password for the NetHSM partition.
  • You have received your new registration keys.
  • You have obtained a license for BIG-IP 15.1.0.
  • You have properly licensed the BIG-IP with the NetHSM add-on.

HSM client installation and configuration](/en-us/bigip-17-0-0/big-ip-system-and-net-hsm-implementation/setting-up-the-network-hsm.html)

To configure the BIG-IP for SafeNet DPoD, perform the following steps:

  1. On the Main tab, select System > License .

  2. Review the Summary information and locate the External Interface and Network HSM in the Active Modules field (for example, under Local Traffic Manager) for conformation

You are now ready to create a SafeNet DPoD account and install the zip file.

HSM client installation and configuration](/en-us/bigip-17-0-0/big-ip-system-and-net-hsm-implementation/setting-up-the-network-hsm.html)

To install the SafeNet DPoD.zip file, perform the following steps:

  1. To unzip the SafeNet DPoD.zip files after creating a directory (/shared/safenet/) and copying the setup files to the new directory, enter the following commands:

    [root@bigip:Active:Standalone] safenet # unzip setup-f5_dpod_test2.zip
     Archive:  setup-f5_dpod_test2.zip
     inflating: server-certificate.pem
     inflating: partition-ca-certificate.pem
     inflating: partition-certificate.pem
     inflating: Chrystoki.conf
     inflating: crystoki-template.ini
     inflating: cvclient-min.tar
     inflating: cvclient-min.zip
     inflating: EULA.zip

[root@bigip:Active:Standalone] safenet # tar -xvf cvclient-min.tar
    bin/
    bin/64/
    bin/64/lunacm
    bin/64/ckdemo
    bin/64/multitoken
    bin/64/cmu
    etc/
    jsp/
    jsp/64/
    jsp/64/libLunaAPI.so
    jsp/LunaProvider.jar
    libs/
    libs/64/
    libs/64/libCryptoki2.so
    setenv

  2. To create a lunasa directory and copy the DPoD client files into that directory, enter the following command:

    # mkdir -p /shared/safenet/lunasa
# [root@bigip:Active:Standalone] safenet # cp -rf * /shared/safenet/lunasa/

  3. To set the environment and generate the Chrystoki.conf configuration file, enter the following command:

    # source ./setenv

  4. To create a lib directory and move the crypto libraries into the created directory, enter the following commands:

    # mkdir /shared/safenet/lunasa/lib
# mv /shared/safenet/lunasa/libs/64/libCryptoki2.so /shared/safenet/lunasa/lib

[root@bigip:Active:Standalone] safenet # mv libs/64/libCryptoki2.so /shared/safenet/lunasa/lib/.

  5. To create a password file to store the partition password, enter the following command:

    # touch /shared/safenet/lunasa/passfile
# pOiu12zx > passfile

    Note: This file is used for the password when GemEngine is called. For example, we are using pOiu12zx as the partition password.

  6. Open and modify the Chrystoki.conf file.

    1. To modify the Chrystoki2 and Misc sections, enter the following commands:

      Chrystoki2 = {
LibUNIX64 = /shared/safenet/lunasa/lib/libCryptoki2.so; 
}
Misc = {
  Apache = 0;
  PE1746Enabled = 1;
  ToolsDir = /usr/bin;                          
  RSAKeyGenMechRemap = 1;
}

    2. To create a new GemEngine section, use the following values:

      GemEngine = {
   EnableDsaGenKeyPair = 1;
   EnableRsaGenKeyPair = 1;
   DisablePublicCrypto = 1;
   EnableRsaSignVerify = 1;
   EnableLoadPubKey = 1;
   EnableLoadPrivKey = 1;
   DisableCheckFinalize = 1;
   DisableEcdsa = 1;
   DisableDsa = 0;
   DisableRand = 0;
   EngineInit = "f5dpod":0:0:passfile=/shared/safenet/lunasa/passfile;
   EnableLoginInit = 1;
   LibPath64 = /shared/safenet/lunasa/lib/libCryptoki2.so;
   LibPath = /shared/safenet/lunasa/lib/libCryptoki2.so;
}

  7. To check if the paths are correctly set and the partition is accessible, run LunaCM by entering the following comand:

    # /shared/safenet/lunasa/bin/64/lunacm

  8. To create the soft links, enter the following commands:

    # ln -sf /shared/safenet/lunasa /usr/lunasa
# ln -sf /shared/safenet/lunasa /usr/safenet/lunaclient
# ln -sf /shared/safenet/lunasa/Chrystoki.conf /etc/Chrystoki.conf
# ln -sf /shared/safenet/lunasa/lib/libCryptoki2.so /usr/lib/libCryptoki2_64.so
# ln -sf /shared/safenet/lunasa/lib/libCryptoki2.so /usr/lib/libCryptoki2.so

    Note: You may need to remount /usr prior to mount -o remount,rw /usr.

  9. Restart the services to apply the changes by entering the following command:

    # bigstart start pkcs11d
# bigstart restart tmm

You have now installed the SafeNet DPoD.zip file and are ready to set up an external HSM and netHSM partition on the BIG-IP.

HSM client installation and configuration](/en-us/bigip-17-0-0/big-ip-system-and-net-hsm-implementation/setting-up-the-network-hsm.html)

To create an external HSM and Network HSM partition on the BIG-IP, do the following:

  1. On the Main tab, select System > Certificate Management > HSM Management.

  2. In the PKCS11 Library Path field, select the /shared/safenet/lunasa/libs/64/libCryptoki2.so library path.

  3. In the Partition List field, do the following:

    1. In the Name field, type a name (for example, f5dpod).

    2. In the Password field, type the crypto officer password.

  4. Click Add.

  5. To test the partition list Name and Password, click Test. Results from the test will appear in the Test Output field.

    Note: Some tests may take up to, or over, a minute to show results.

    Note: If your test results show issues, you can turn on debug logging of PKCS11 with the following command: tmsh modify sys db log.pkcs11d.level value Debug. The log information will appear in /var/log/ltm.

  6. Click Update.

    You have now created an external HSM and Network HSM partition on the BIG-IP.

You can also set up an external HSM and nethsm-partition on the BIG-IP using the CLI:

tmsh create sys crypto fips external-hsm vendor auto pkcs11-lib-path /shared/safenet/lunasa/lib/libCryptoki2.so password pOiu12zx
create sys crypto fips nethsm-partition f5dpodTEST password pOiu12zx
 
[root@bigip:Active:Standalone] config # tmsh list sys crypto fips
sys crypto fips external-hsm {
    num-threads 20
    password $M$39$2g2pWUdT0f6INYhHJ1lZfQ==
    pkcs11-lib-path /shared/safenet/lunasa/lib/libCryptoki2.so
    vendor auto
}
sys crypto fips nethsm-partition f5dpodTEST {
    password $M$Pk$b099uPx3zSycJWdEBrazhw==
}

HSM client installation and configuration](/en-us/bigip-17-0-0/big-ip-system-and-net-hsm-implementation/setting-up-the-network-hsm.html)

To login to LunaCM and initialize the CO user, enter the following commands:

[root@bigip19:Active:Standalone] f5_dpod # /shared/safenet/lunasa/bin/64/lunacm
LunaCM v1.1.0-1044. Copyright (c) 2006-2017 SafeNet.
slot s
    Available HSMs:
 
e   Slot Id ->              3
    Label ->                                               
    Serial Number ->        1334047160562  
    Model ->                Cryptovisor7  
    Firmware Version ->     7.1.3
    CV Firmware Version ->  1.1.0
t   Configuration ->        Luna User Partition With SO (PW) Signing With Cloning Mode
    Slot Description ->     User Token Slot

    Current Slot Id: 3

HSM client installation and configuration](/en-us/bigip-17-0-0/big-ip-system-and-net-hsm-implementation/setting-up-the-network-hsm.html)

To initialize the crypto user role, perform the following steps.

  1. To enter the slot ID, enter the following command:

    lunacm:>slot set -slot 3

    The Current Slot ID: 3 (Luna User Slot 7.1.3 (PW) Signing With Cloning Mode).

    The Command Result: No Error.

  2. To enter the partition information, enter the following command:

    lunacm:>partition init -label f5dpodTEST

  3. Type, and then re-type, the password for Partition SO.

    You are now about to initialize the partition. All contents of the partition will be destroyed.

  4. Type proceed to continue or type quit to stop the action.

  5. If you proceed, type, and then re-type, the domain name.

    Note: If neither option -domain nor -defaultdomain was specified, enter one.

    The Command Result: No Error.

  6. Enter the following Partition SO command and then type the password:

    lunacm:>role login -name

    The Command Result: No Error.

  7. Enter the following command and then type, and then re-type, the new password:

    lunacm:>role init -name co

    The Command Result : No Error.

  8. Enter the following command and then type the existing and new passwords:

    lunacm:>role changePW -name co
    1. Type the existing password: ********
    2. Type the new password: ********
    3. Re-type the new password: ********

You have now initialized the partition.

HSM client installation and configuration](/en-us/bigip-17-0-0/big-ip-system-and-net-hsm-implementation/setting-up-the-network-hsm.html)

To create a Network HSM certificate and key to assign to the virtual server, follow the steps below.

Assumptions:

  • You have an HTTPS server available.

  1. On the Main tab, select System > Certificate Management > Traffic Certificate Management and click Create.

  2. In the Name field, type a name (for example, my-fips).

  3. From the Issuer list, select Self for a self-signed certificate.

  4. In the Common Name field, type a name.

  5. In the Key Properties section, from the Security Type list, select NetHSM.

    Note: NetHSM is only visible when NetHSM is licensed.

  6. From the NetHSM Partition list, select the partition name you created earlier (for example, f5dpod).

  7. Click Finished.

    You can also check the key at the partition by entering the following commands:

    lunacm:>ro login -n co

    enter password: ********

Command Result : No Error

lunacm:>par con

The 'Crypto Officer' is currently logged in.  Looking for objects accessible to the 'Crypto Officer'.

    Object list:

    Label:         rsa_19574___15ba2050
    Handle:        2156006992
    Object Type:   Private Key
    Object UID:    842b00000a0000012cbe0800

    Label:         ec_secp384r1_20117___28804c3f
    Handle:        746860604
    Object Type:   Private Key
    Object UID:    822b00000a0000012cbe0800

    Label:         ec_secp384r1_20117___28804c3f
    Handle:        408279569
    Object Type:   Public Key
    Object UID:    812b00000a0000012cbe0800

    Number of objects:  3

Command Result : No Error

lunacm:>

    You have now created a Network HSM certificate and key.

HSM client installation and configuration](/en-us/bigip-17-0-0/big-ip-system-and-net-hsm-implementation/setting-up-the-network-hsm.html)

To create a Network HSM client SSL profile that will use the newly created certificate and key, do the following:

  1. On the Main tab, select Local Traffic > Profiles > SSL > Client and click Create.

  2. In the Name field, type a name (for example, my-fips-clientssl).

  3. From the Parent Profile list, select clientssl.

  4. In the Certificate Key Chain field, select the Custom checkbox and click Add. The Add SSL Certificate Key Chain screen appears.

  5. From the Certificate, Key, and Chain lists, select my-fips to set the values to your FIPS certificate.

  6. Click Add.

  7. Click Finished to create the new profile.

    You have now created a Network HSM client SSL profile.

HSM client installation and configuration](/en-us/bigip-17-0-0/big-ip-system-and-net-hsm-implementation/setting-up-the-network-hsm.html)

To assign your new client SSL profile to your virtual server, do the following:

  1. On the Main tab, select Local Traffic > Virtual Servers > Virtual Server List and click Create.

  2. In the Name field, type a name.

  3. In the Destination Address/Mask field, select <Host or Address List?> and type the address.

    1. Specifies destination IP address information to which the virtual server sends traffic. Specify the IP address in CIDR format: address/prefix, where the prefix length is in bits: for example, for IPv4: 10.0.0.1/32 or 10.0.0.0/24, and for IPv6: ffe1::0020/64 or 2001:ed8:77b5:2:10:10:100:42/64. The defaults for DHCP are 255.255.255.255 (IPv4 Default) and ff02::1:2 (IPv6 Default). You can also select Other to specify another Destination Address.

  4. In the Service Port field, select <Port or Port List?> and type the port information before selecting a port designation from the list.

    1. Type a service port or select a type from the list. When you select a type from the list, the value in the Service Port box changes to reflect the associated default, which you can change.

  5. In the SSL Profile (Client) field, select my-fips-clientssl from the Available list and move it to the Selected list.

    1. Specifies the SSL profile for managing client-side SSL traffic. Use the Move buttons (<<) and (>>) to adjust profile use.

  6. Click Finished.

    You have now assigned your new client SSL profile to your virtual server.

HSM client installation and configuration](/en-us/bigip-17-0-0/big-ip-system-and-net-hsm-implementation/setting-up-the-network-hsm.html)

To review the new certificate when passing traffic via a browser, do the following:

  1. Open a browser of your choice and pass traffic through your BIG-IP device.

  2. View the certificate details for the name of your certificate’s common name.

HSM client installation and configuration](/en-us/bigip-17-0-0/big-ip-system-and-net-hsm-implementation/setting-up-the-network-hsm.html)

To configure your BIG-IP for SafeNet DPoD when using High Availability (HA) device pair, do the following:

  1. Follow the manual installation process for the .zip file on both HA devices.

  2. Create the external HSM on both devices.

    Note: This object is not configuration synchronized. The nethsm-partition object does, however, get synchronized.

HSM client installation and configuration](/en-us/bigip-17-0-0/big-ip-system-and-net-hsm-implementation/setting-up-the-network-hsm.html)

The BIG-IP system can be configured to use the Bull Trustway Proteccio network HSM service, by Atos. Proteccio is a third-party network HSM service not sold by F5. Customers of Atos that own a license to Proteccio can configure the network HSM to work on the BIG-IP system.

To set up your Atos Proteccio HSM, refer to the support material provided by Bull Trustway Proteccio HSM at the Bull Atos Technologies Support On Line site.

Use the following information to install and configure your Atos Proteccio HSM.

To mount the Atos Proteccio ISO to your local file system using the BIG-IP CLI, enter the following command:

mount -o loop /shared/rpms/Proteccio1.08.18_dec2017.iso /mnt/atos

HSM client installation and configuration](/en-us/bigip-17-0-0/big-ip-system-and-net-hsm-implementation/setting-up-the-network-hsm.html)

To install the Atos Proteccio client, enter the following command:

cd /mnt/atos/Linux/
sh install.sh

HSM client installation and configuration](/en-us/bigip-17-0-0/big-ip-system-and-net-hsm-implementation/setting-up-the-network-hsm.html)

To create a local directory on your system for a configuration check, enter the following commands:

cd /shared/
mkdir proteccio
cd protecccio
cp /etc/proteccio/proteccio.rc ./
cat /shared/proteccio/proteccio.rc
chmod +w proteccio.rc
vi /shared/proteccio/proteccio.rc
[PROTECCIO]
IPaddr=193.251.82.208   
SSL=1                   
SrvCert=proteccio.crt
 
[CLIENT]
Mode=0
LoggingLevel=7
LogFile=my_log_file1.log
ClntKey=proteccio_client.key
ClntCert=proteccio_client.crt

Note: Make sure to change the IP address with the one provided by Atos.

Note: Make sure to change the SSL value to 1.

HSM client installation and configuration](/en-us/bigip-17-0-0/big-ip-system-and-net-hsm-implementation/setting-up-the-network-hsm.html)

To add the library path and configure the partitions, copy the CRT files to /shared/proteccio/ and enter the following command:

[root@localhost:Active:Standalone] proteccio # ls
client19.crt  client19.p12  client19.pem  my_log_file1.log  my_log_file.log  proteccio_client.crt  proteccio_client.key  proteccio.crt  proteccio.rc

HSM client installation and configuration](/en-us/bigip-17-0-0/big-ip-system-and-net-hsm-implementation/setting-up-the-network-hsm.html)

To add your Atos HSM library to the BIG-IP and configure the partitions, perform the steps provided in the UI screen or the CLI.

  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:

    /usr/lib64/libnethsm.so

    Note: See the ATOS Virtual HSM installation and user guide for the NetHSM library path.

  4. In the Partition List section, add the following details:

    1. In the Name field, type proteccio (case sensitive).

    2. In the Password field, type the <API Key>.

    Note: If you type auto in the Name field, the first available partition will be selected.

    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.

    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.

If you are using the CLI, do the following:

  1. To add your CloudHSM library to the BIG-IP, enter the following command:

    # tmsh create sys crypto fips external-hsm vendor auto pkcs11-lib-path/usr/lib64/libnethsm.so.

  2. To configure the partition, enter the following command:

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

    Note: For <partition-name>, use the partition name given by ATOS (for example, HSMV_6). F5 recommends not using the name “auto” since the first partition may not always be available.

  3. Reboot the appliance to restart the service and create the links.

  4. To test your output, use the Network HSM testing tool at /shared/proteccio/, enter the following command:

    # 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 Atos) will be chosen.

  5. Copy all of the files under cp /shared/proteccio/* to /etc/proteccio/.

  6. To restart pkcs11d and check its health, enter the following command:

    bigstart restart pkcs11d
bigstart status pkcs11d

  7. To run a full validation test, enter the following command:

    tmsh run sys crypto nethsm-test

  8. To create a key from pkcs11d for review, enter the following command:

    tmsh create sys crypto key test_key security-type nethsm
tmsh list sys crypto key

HSM client installation and configuration](/en-us/bigip-17-0-0/big-ip-system-and-net-hsm-implementation/setting-up-the-network-hsm.html)

To set up the external HSM and nethsm-partition on the BIG-IP system, enter the following commands after obtaining the new partition from the vendor:

tmsh create sys crypto fips external-hsm vendor auto pkcs11-lib-path "/usr/lib64/libnethsm.so" password kLG7j9p4
tmsh create sys crypto fips nethsm-partition 'HSMV1' password kLG7j9p4
 
[root@bigip:Active:Standalone] tmp # tmsh list sys crypto fips
sys crypto fips external-hsm {
    num-threads 20
    password $M$Zc$Mjpis3OHylCBsOReoHgMPQ==
    pkcs11-lib-path /usr/lib64/libnethsm.so
    vendor auto
}
sys crypto fips nethsm-partition HSMV1 {
    password $M$1v$5T68lhIsqTPZNa0I36/OEQ==
}

HSM client installation and configuration](/en-us/bigip-17-0-0/big-ip-system-and-net-hsm-implementation/setting-up-the-network-hsm.html)

The BIG-IP system can be configured to use the IBM Cloud Hyper Protect Crypto Services (HPCS). HPCS is a third-party key management service and cloud HSM based on IBM cloud not sold by F5. Customers of IBM that own a license to HPCS can configure the cloud HSM to manage encryption keys and perform cryptographic operations that work with the BIG-IP system.

This section details the pre-requisites required before setting up IBM HPCS with the BIG-IP system:

  1. Get the following information from the IBM portal before proceeding with the configuration:

    • You have an enterprise PKCS #11 endpoint URL starting from ep11 and the port number.
    • You have the ID of your Hyper Protect Crypto Services instance.
    • You have tokenspaceID for the private and public keystore.
    • You have generated the anonymous user API key.
    • You have generated the normal user API key. For setting up your HPCS service, follow the Getting started with IBM Cloud Hyper Protect Crypto Services instructions.

    For setting up PKCS #11 API users, follow the Setting up PKCS #11 API user types instructions.

    Note: Always enable the CKA_MODIFIABLE attribute as TRUE while generating RSA and EC keys from the IBM portal.

    Note: The link takes you to a resource outside of AskF5. The referred documents may have been removed without our knowledge.

  2. Download the latest PKCS #11 library and the sample YAML file from https://github.com/IBM-Cloud/hpcs-pkcs11/releases. You may have downloaded the library file (pkcs11-grep11.so) in the directory /shared/tmp/IBM-HPCS/.

  3. Move the downloaded configuration file (grep11client.yaml) in the /etc/ep11client directory (for example, /etc/ep11client/grep11client.yaml). Create the /etc/ep11client directory if it does not exist.

Modify the configuration file grep11client.yaml by editing the grep11connection attributes with the following values gathered in the pre-requisites:

  1. Address: Replace hpcs_ep11_server_address in address with the Enterprise PKCS #11 endpoint URL.

  2. Port: Update port with the Enterprise PKCS #11 endpoint port number.

  3. tokenspaceID: Update tokenspaceID for both normal and anonymous users. Under the normal user, the tokenspaceID identifies the private keystore, and under the anonymous user, it identifies the public keystore.

  4. apikey: Update apikey with the anonymous user API key you created previously.

To configure your BIG-IP with your newly configured and activated IBM HSM, add the library path and configure partitions. You can either use the BIG-IP UI screen or CLI to accomplish the task.

  1. Using BIG-IP UI

  2. On the Main tab, click System > Certificate Management > External HSM. The External HSM screen opens.

  3. From the Vendor list, select Auto.

  4. In the PKCS11 Library Path field, type the following:

    /opt/ibmhsm/lib/pkcs11-grep11.so

  5. In the Partition List section, add the following details:

    1. In the Name field, type auto (case sensitive).

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

  6. Click Add to add as many partitions as necessary.

  7. To edit any existing partition, select the partition and click Edit.

  8. To delete any existing partition, select the partition and click Delete.

  9. To test any existing partition, select a partition and click Test.

  10. If you selected Test, review the test output to ensure your details are accurate.

    1. If the test does not pass, attempt to locate the problem and enable debug logging and rerun the test for further details.

    2. To enable debug logging and capture trace data, use the following command:

      export EP11CLIENT_LOGGING_LOGLEVEL=trace

    The log information will appear in /var/log/grep11-pkcs11.log.

    Make sure to reset debug logging to the prior setting before continuing.

  11. Click Update.

Using Command Line Interface

If you are using the CLI, do the following:

  1. Add your IBM HPCS library to the BIG-IP by using the following command:

    # tmsh create sys crypto fips external-hsm vendor auto pkcs11-lib-path /opt/ibmhsm/lib/pkcs11-grep11.so

  2. Configure the partition by using the following command:

    # tmsh create sys crypto fips nethsm-partition auto password <Normal user API key>

    Note: Here, we used “auto” to point to the first partition.

  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=auto

Note: You must always restart the pkcs11d daemon on the BIG-IP system before importing a new RSA/EC key generated on the IBM portal.

Set up your SafeNet Luna SA HSM by following the documentation in the BIG-IP System and SafeNet Luna SA HSM: Implementation guide.

Set up your SafeNet Luna SA HSM by following the documentation in the BIG-IP System and nShield HSM: Implementation guide.

To ensure seamless integration and compatibility, please refer to the interoperability matrix for SafeNet Luna SA HSM and Entrust nShield HSM below:

  1. Interoperability Matrix for BIG-IP TMOS with SafeNet Clients and HSM

  2. Interoperability Matrix for BIG-IP TMOS with nShield Clients and HSM