Procedures

Prerequisites

  1. A Big-IP system must be deployed before following the steps in this guide.

    Big-IP Virtual Edition was used for this guide, but the procedures in this guide can be applied to other deployments.

  2. The BIG-IP system must be licensed for External Interface and Network HSM.

  3. Access is required to the command-line interface of the Big-IP machine and the Configuration utility web interface.

  4. A Security World ISO file is required for installing the nShield Security World software.

Install the Security World software

The following steps will be a manual installation of Security World on the BIG-IP machine. Automatic installation steps exist for older versions of Security World software. See the F5 documentation for more information.

  1. Mount the Security World ISO file:

    % cd /shared
% mkdir SecWorld-12.60.11
% mount -o loop SecWorld_Lin64-12.60.11.iso SecWorld-12.60.11

  2. Untar the Security World files:

    % cd /shared
% sudo tar -zxvf /shared/SecWorld-12.60.11/linux/amd64/ctd.tar.gz

  3. Repeat for all tar.gz files in the amd64 directory.

  4. Fix installation directory paths:

    % mv /shared/opt/nfast/ /shared
% rmdir /shared/opt

  5. Create a symbolic link from /shared/nfast to /opt/nfast:

    % mv /share/opt/nfast /shared
% ln -s /shared/nfast /opt/nfast

  6. Run the installation:

    % /opt/nfast/sbin/install

  7. Run the enquiry utility to see if the hardserver is up and running:

    % /opt/nfast/bin/enquiry

Configure the Security World

To configure the Security World:

  1. Enroll the HSM onto the Big-IP machine. The machine must be a client of the HSM. For more information, see the User Guide for the HSM.

    % /opt/nfast/bin/nethsmenroll -p <HSM_IP_Address>
% /opt/nfast/bin/enquiry

  2. Create or import the Security World. For more information, see the User Guide for the HSM.

  3. Edit cknfastrc in /opt/nfast and update it to contain one of the following configurations:

    1. For Module-Only protection:

      CKNFAST_OVERRIDE_SECURITY_ASSURANCES=wrapping_crypt
CKNFAST_FAKE_ACCELERATOR_LOGIN=1

    2. For OCS or Softcard protection:

      CKNFAST_OVERRIDE_SECURITY_ASSURANCES=wrapping_crypt
CKNFAST_LOADSHARING=1
CKNFAST_NO_ACCELERATOR_SLOTS=1

  4. Restart the pkcs11d service to apply the new settings to the system:

    % tmsh restart sys service pkcs11d
% tmsh restart sys service tmm
    Anytime you change the cknfastrc file you must restart the pkcs11d service for changes to take effect.

  5. Add * to the end of the /shared/opt/nfast/kmdata/config/cardlist file.

Configure HSM connectivity to Big-IP

To configure HSM connectivity to Big-IP:

  1. Use the following F5 commands to verify the setup and check the name of the partition to be used. For OCS or Softcard protection, this is typically the name of the card set.

    % pkcs11d_test_suite
% pkcs11d_test_one

  2. Take note of the partition name. This integration uses Module-Only protection, so the partition name was accelerator.

  3. Log in to the Configuration utility using an account with the administrator role.

  4. Add the following information under System > Certificate Management > HSM Management > External HSM.

    1. For Vendor, select Auto.

    2. For PKCS11 Library Path, enter /opt/nfast/toolkits/pkcs11/libcknfast.so.

    3. For Partition, enter the partition name.

    4. For Password, enter the card set passphrase.

    big ip external hsm

  5. Select Add to add the partition.

  6. Select Update.

  7. Restart the pkcs11d service to apply the new settings to the system:

    % bigstart restart pkcs11d

  8. Confirm that pkcs11d is running:

    % bigstart status pkcs11d

Manage HSM keys for LTM

Generate an HSM key

The Traffic Management Shell tmsh can be used to generate a key or certificate on the HSM.

  1. Generate the key:

    % tmsh create sys crypto key <key_name> gen-certificate common-name <cert_name> security-type nethsm

  2. Verify that the key was created:

    % tmsh list sys crypto key test_key

Generate a self-signed digital certificate

To generate a self-signed digital certificate:

  1. Log in to the Configuration utility using an account with the administrator role.

  2. On the main page, select System > Certificate Management > Traffic Certificate Management.

    The Traffic Certificate Management page appears.

  3. Select Create.

  4. For Name, enter a unique name for the SSL certificate.

  5. For Issuer, select Self.

  6. For Common Name, enter a name. This is typically the name of a web site, such as www.siterequest.com.

  7. Enter the other certificate details.

  8. For Security Type, select NetHSM.

  9. For NetHSM Partition, select a partition to use.

  10. For Key Type, RSA is selected as the default key type.

  11. For Size, select a size, in bits.

  12. Select Finished.

Request a certificate from a Certificate Authority

To request a certificate from a Certificate Authority, you must generate a certificate signing request (CSR) and then submit the CSR to a third-party trusted certificate authority (CA):

  1. Log in to the Configuration utility using an account with the administrator role.

  2. On the main page, select System > Certificate Management > Traffic Certificate Management.

    The Traffic Certificate Management page appears.

  3. Select Create.

  4. For Name, enter a unique name for the SSL certificate.

  5. For Issuer list, select Certificate Authority.

  6. Enter the other certificate details.

  7. Select Finished.

  8. The Certificate Signing Request page appears.

  9. Do one of the following to download the request into a file on your system.

    1. For Request Text, copy the certificate.

    2. For Request File, select the Download button.

  10. Submit the request to a certificate authority to be signed.

  11. Select Finished.

    An option appears to import the signed certificate.

  12. Import the certificate.

Delete a key from the BIG-IP system

To delete a key from the BIG-IP system:

  1. Log in to the Configuration utility using an account with the administrator role.

  2. On the main page, select System > Certificate Management > Traffic Certificate Management.

    The Traffic Certificate Management page appears.

  3. For SSL Certificate List, select the key to delete.

  4. Select Delete.

    The key you selected is deleted from BIG-IP.

    The key stored in NetHSM is not deleted. To do this, find the key file in /opt/nfast/kmdata/local and delete it.

Import a pre-existing NetHSM key to the BIG-IP system

To import a pre-existing NetHSM key to the BIG-IP system:

  1. Log in to the command-line interface of the system using an account with administrator privileges.

  2. Import the NetHSM key:

    % tmsh install sys crypto key <nethsm_key_label> from-nethsm security-type nethsm

This step can be completed on the Configuration utility. See the F5 documentation for more information.

Configure BIG-IP High Availability (HA) Failover

SSL traffic failover can work with HSM keys and certificates.

  1. Attach the HSM key and certificate to a client SSL profile.

  2. Assign the profile to a virtual server, so that the virtual server can process SSL traffic according to the specified profile settings.

  3. Verify that the virtual server passes traffic correctly.

  4. Perform a manual failover of the HA pairing.

    The virtual server should still pass traffic correctly.

    When a new HSM key for F5 BIG-IP HA is created or imported on an HA machine, you must copy the key_pkcs11 file from /opt/nfast/kmdata/local to the other machine in the HA setup. Entrust recommends the rfs-sync feature to accomplish this. Other file transfer methods can also be used. Without this action, SSL traffic using this key will fail when BIG-IP fails over to the machine without the file.

    For setting up two F5 BIG-IP machines in an HA pairing, see https://techdocs.f5.com/en-us/bigip-14-0-0/big-ip-service-provider-sip-administration-14-0-0/high-availability-ha-failover.html.

    For instructions on manual failover, see https://my.f5.com/manage/s/article/K42061352.