Manual Chapter : Setting Up the Network HSM

Applies To:

Show Versions Show Versions

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
Manual Chapter

Setting Up the Network HSM

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

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

Supported Versions

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

Setting up Network HSM Client Installation and Configuration

To setup a Network HSM, you must have network access to the HSM with 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/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 rpm -ivh ./cloudhsm-client-pkcs11-1.0-18.x86_64.rpm rpm -ivh ./cloudhsm-client-1.0-18.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_standard.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_standard.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

Install the clients by following the SmartKey developer’s guide instructions while logged into the BIG-IP as root.
Use the 2.9.804 client instead of the client linked in the SmartKey instructions.
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.

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

Setting up SafeNet Data Protection on Demand (DPoD) HSM client installation and configuration

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.

Prerequisites for setting up SafeNet DPoD HSM with BIG-IP system

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

Configuring the BIG-IP for SafeNet DPoD

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.

Installing the SafeNet DPoD.zip file

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

Setting up an external HSM and Network HSM partition on the BIG-IP

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.
    Some tests may take up to, or over, a minute to show results.
    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== }

Logging in to the LunaCM to initialize the cryptographic officers (CO) user

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

Initializing the crypto user role

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

Creating a Network HSM certificate and key

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

Creating a Network HSM client SSL profile

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.

Assigning the new client SSL profile to a virtual server

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.

Reviewing the new certificate

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.

Configuring the BIG-IP for SafeNet DPoD when using a High Availability pair

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.
    This object is not configuration synchronized. The nethsm-partition object does, however, get synchronized.

Setting up Atos (Bull Trustway Proteccio) HSM client installation and configuration

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.

Mounting the Atos Proteccio ISO

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

Installing the Atos clients

To install the Atos Proteccio client, enter the following command:
cd /mnt/atos/Linux/ sh install.sh

Creating a local directory on your system

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
Make sure to change the IP address with the one provided by Atos.
Make sure to change the SSL value to
1
.

Copying the certificate (CRT) files

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

Adding the library path and configuring partitions

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
    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
      >.
    If you type
    auto
    in the
    Name
    field, the first available partition will be selected.
    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
    .
    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"
    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>
    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

Setting up the external HSM and nethsm-partition on the BIG-IP system

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

Setting up IBM HPCS client installation and configuration

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.

Prerequisites for setting up IBM HPCS with 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.
    Always enable the
    CKA_MODIFIABLE
    attribute as
    TRUE
    while generating RSA and EC keys from the IBM portal.
    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.

Modifying the HPCS configuration file (grep11client.yaml)

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.

Adding the library path and configuring partitions

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).
      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>
    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
You must always restart the pkcs11d daemon on the BIG-IP system before importing a new RSA/EC key generated on the IBM portal.