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 can be applied to other deployments.

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

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

  4. A Security World ISO file is required to install the nShield Security World software.

Install the Security World software

The following steps describe 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
% mount -o loop SecWorld_Lin64-13.6.8.iso SecWorld

  2. Untar the Security World files:

    % cd /shared
% sudo tar -zxvf /shared/SecWorld/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:

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

  6. Run the installation:

    % /opt/nfast/sbin/install

  7. Run the enquiry utility to verify that 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
    Whenever you change the cknfastrc file, you must restart the pkcs11d service for the changes to take effect.

  5. Append * to 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 to 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. Under General Properties:

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

  5. Under Certificate Properties:

    1. For Issuer, select Self.

    2. For Common Name, enter a name. This is typically the name of a website, such as www.siterequest.com.

    3. Enter the other certificate details.

  6. Under Key Properties:

    1. For Security Type, select NetHSM.

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

    3. For Key Type, leave RSA selected as the default.

    4. For Size, select a size in bits.

  7. Under Certificate Order Properties:

    1. For Provider, select the certificate provider.

    2. For Certificate Manager Order, select the Manager.

  8. 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. Under General Properties:

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

  5. Under Certificate Properties:

    1. For Issuer, select Certificate Authority.

    2. Enter the other certificate details as appropriate.

  6. Under Certificate Signing Request Attributes:

    1. For Administrator E-mail Address, enter the administrator’s email address.

    2. For Challenge Password, type a password.

    3. Confirm the password.

  7. Under Key Properties:

    1. For Security Type, select NetHSM.

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

    3. For Key Type, leave RSA selected as the default.

    4. For Size, select a size in bits.

  8. Under Certificate Order Properties:

    1. For Provider, select the certificate provider.

    2. For Certificate Manager Order, select the Manager.

  9. Select Finished.

    The Certificate Signing Request page appears.

  10. Do one of the following to download the request as a file on your system:

    1. For Request Text, copy the certificate.

    2. For Request File, select Download.

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

  12. Select Finished.

    An option appears to import the signed certificate.

  13. 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 delete it, find the key file in /opt/nfast/kmdata/local and remove 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 also be performed in 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 pair.

    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 using the rfs-sync feature for this. Other file transfer methods can also be used. Without this step, SSL traffic that uses this key fails when BIG-IP fails over to the peer machine that does not have the key file.

    For instructions on setting up two F5 BIG-IP machines in an HA pair, 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.