Applies To:

Show Versions Show Versions

Manual Chapter: Managing External HSM Keys for LTM
Manual Chapter
Table of Contents   |   << Previous Chapter   |   Next Chapter >>

Overview: Managing external HSM keys for LTM

You can use the Thales nShield Connect to store and manage token- module-, and softcard-protected keys.

For additional information about using Thales nShield Connect, refer to the Thales website:

https://www.thales-esecurity.com/products-and-services/products-and-services /hardware-security-modules/general-purpose-hsms/nshield-connect

About key protection

There are three types of key protection available for use with the BIG-IP® system and Thales Connect:

  • Module-protected keys are directly protected by the external HSM through the security world and can be used at any time without further authorization.
  • Softcard-protected keys are protected by a softcard and can be used by only an operator who possesses the assigned passphrases.
  • Token-protected keys are protected by a cardset and can be used by only an operator who possesses the Operator Card Set (OCS) token and any assigned passphrases.

All options are equally secure, and the main difference is the authorization requirement. As a general rule, if you have no particular security or regulatory requirement, you can default to softcard protection. Thales prefers the use of physical tokens for authorization. In the case of Operator Cards, Thales recommends making a 1/N card set, where N is greater than the total number of nShield Connects. For more information about card sets, refer to the Thales user guides.

Task summary

The implementation process involves configuring a key protection type, and then creating and loading a token-, module-, or softcard-protected key and certificate, and creating a client SSL profile to use the key and certificate.

Task list

Configuring the key protection type

On the BIG-IP® system, you can choose among the Thales-supported types of key protection: module, softcard, and OCS. By default, the installation script sets up the appliance to create and use module-protected keys. F5 recommends that you keep only one set of cardset files (cards* or softcard*) in the $NFAST_KMDATA/local directory.

In this release, only one type of key protection (PKCS#11 slot) can be configured for active use. You need to configure the key protection type for a slot by enabling the type you want, and disabling the others.

  1. Log in to the command-line interface of the BIG-IP system using an account with administrator privileges.
  2. Complete one of these steps, depending on your preferred key protection option:
    Option Description
    module The module-protected key option is enabled by default. To enable this protection type, no further action is required, and you can proceed to the next section.
    OCS
    1. Disable module key protection by opening the configuration file /opt/nfast/cknfastrc and changing the value of the following parameter to 1, as shown.

      CKNFAST_NO_ACCELERATOR_SLOTS=1

    2. Disable softcard key protection by moving any previously created softcard* files from the /opt/nfast/kmdata/local directory to the /opt/nfast/kmdata/ directory.
    3. Enable OCS key protection by creating the OCS cardset using the Thales-provided createocs utility.
    softcard
    1. Disable module protection by opening the configuration file /opt/nfast/cknfastrc and changing the value of the following parameter to 1, as shown.

      CKNFAST_NO_ACCELERATOR_SLOTS=1

    2. Disable OCS key protection by moving any previously created cards* files from the /opt/nfast/kmdata/ directory to the /opt/nfast/kmdata/local directory.
    3. Enable softcard key protection by creating the softcard cardset using the Thales-provided ppmk utility.
    Note: The softcard passphrase used in the ppmk command must match the passphrase used for setting up the Thales nShield Connect client on the BIG-IP system (used in the command tmsh create/modify sys crypto fips external-hsm password <password>).
    Note: If OCS is configured with a passphrase for Thales HSM, the user must enter it when prompted for Thales HSM slot password, even if the user only wants to use module keys.
  3. After you make any configuration changes, you must restart the pkcsd11 and tmm services. tmsh restart sys service pkcs11d tmsh restart sys service tmm

Generating a token-, module-, or softcard-protected key/certificate using Thales nShield Connect

Before you generate a token-, module-, or softcard-protected key/certificate, make sure that the Thales nShield Connect client is running on the BIG-IP® system.
You can use the fipskey.nethsm utility to generate token-, module-, or softcard-protected private keys and self-signed certificates on the BIG-IP system. You can use the generated .csr file to request a signed certificate from a certificate authority (CA).
  1. Log in to the command-line interface of the system using an account with administrator privileges.
  2. Generate a key, using one of these options:
    • Generate a token-protected key (the default method):

      fipskey.nethsm --genkey -o <output_file> -c token

    • Generate a module-protected key:

      fipskey.nethsm --genkey -o <output_file> -c module

    • Generate a softcard-protected key:

      fipskey.nethsm --genkey -o <output_file> -c softcard

    This example generates the four files that follow, using the default protection type (token):
    fipskey.nethsm --genkey -o my_key -c token
    • /config/ssl/ssl.key/my_key.key (local key)
    • /config/ssl/ssl.csr/my_key.csr (CSR file)
    • /config/ssl/ssl.crt/my_key.crt (self-signed certificate)
    • /opt/nfast/kmdata/local/<filename> (protected key)
    The local key points to the protected key, which is encrypted.
After you generate a key and certificates, you need to load the local key into the BIG-IP configuration using tmsh.

Configuring hardware-protected HSM keys using tmsh

You can use the Traffic Management Shell (tmsh) to load the corresponding local HSM (FIPS) keys into the BIG-IP® system.
Note: This procedure loads the local key, not the actual hardware key, which never leaves the HSM.
  1. Log in to the command-line interface of the BIG-IP system using an account with administrator privileges.
  2. Open the Traffic Management Shell (tmsh). tmsh
  3. Configure the local key. install sys crypto key <key_object_name> from-local-file <keyname>

    This example loads the external HSM key named my_key.key from a local key file stored in the /config/ssl/ssl.key/ directory:

    install sys crypto key my_key.key from-local-file /config/ssl/ssl.key/my_key.key The Thales client software maps the local key to the appropriate protected key.

Adding certificates using tmsh

You can use the Traffic Management Shell (tmsh) to add existing certificates to the BIG-IP® system configuration.
  1. Log in to the command-line interface of the BIG-IP system using an account with administrator privileges.
  2. Open the Traffic Management Shell (tmsh). tmsh
  3. Add the certificate. install sys crypto cert <cert_object_name> from-local-file <path_to_cert_file>

    This example loads the certificate named my_key.crt from a local certificate file stored in the /config/ssl/ssl.crt/ directory:

    install sys crypto cert my_key.crt from-local-file /config/ssl/ssl.crt/my_key.crt

Importing existing SSL keys into Thales nShield device for use by the BIG-IP system

You import existing SSL keys when you have pre-existing keys you want the BIG-IP® system to use. You need to perform these steps for each key you want to import into the Thales system.
  1. Log in to the command-line interface of the system using an account with administrator privileges.
  2. Copy certificate(s) and key(s) you want to import onto the BIG-IP system and place them in the /var/tmp directory on the BIG-IP system. /var/tmp/user.key /var/tmp/user.crt
  3. Ensure adequate permissions are set so that other users on the system are not able to view the .key files copied. chmod 600 /var/tmp/user.key
  4. Import the key into Thales nShield Connect external HSM using the generatekey utility. /opt/nfast/bin/generatekey --import pkcs11 certreq=yes The system interactively prompts you for information.
  5. When prompted to enter the name of the PEM file that contains the RSA key, enter the full path to the key copied to the BIG-IP system (pemreadfile). For example, /var/tmp/user.key.
  6. When prompted to enter the file name where the key will be written, enter the full path to the pseudo key (embedsavefile). This is the pseudo key required by BIG-IP system. For example, /var/tmp/imported_user.key.
  7. When prompted to enter the key name, type a name for the key (plainname). This is the name with which the key is associated in the nShield RFS. No path is required, as plainname is not written to a file on disk. For example, userkey. When the key import is complete, the generatekey utility will generate two files.
    • imported_user.key
    • imported_user_req
  8. Modify the ownership and permissions of the key you created. After successful import, take note of the path to key to modify ownership. chown nfast:nfast /opt/nfast/kmdata/local/key_pkcs11_uced028e5251b7b6891e7e59dec5428d871f92241b-c70e6451e8d793ca80a497267ccb9bc73bd55edb chmod 755 /opt/nfast/kmdata/local/key_pkcs11_uced028e5251b7b6891e7e59dec5428d871f92241b-c70e6451e8d793ca80a497267ccb9bc73bd55edb
    Important: If this step is omitted, you might see permission errors when running rfs-sync.
  9. Sync the nShield generated pseudo-key (embedsavefile) to the RFS. [root@LBHAS64:Active:Standalone] tmp # rfs-sync --update [root@LBHAS64:Active:Standalone] tmp # rfs-sync --commit If the BIG-IP system this procedure is performed on is also the RFS, the rfs-sync commands above will report 0 committed. This is expected behavior, as the keys imported are automatically stored in the RFS directory.
  10. Import the pseudo key and SSL certificate using tmsh for use by BIG-IP client SSL profile using this syntax: tmsh install sys crypto key [name] from-local-file [/path/to/pseudo_key.key] tmsh install sys crypto cert [name] from-local-file [/path/to/real_certificate.crt] For example: tmsh install sys crypto key import.key from-local-file /var/tmp/imported_user.key tmsh install sys crypto cert import.crt from-local-file /var/tmp/user.crt
  11. Save the configuration. tmsh save sys config If you need to import more SSL certificates and keys, repeat all preceding steps for each certificate and key pair.
  12. Create an SSL profile that references the above key and certificate.
  13. Create a virtual server that uses the above SSL profile (or assign to an existing virtual server).
  14. Verify that the virtual server passes traffic correctly.
  15. You can safely remove the certificates and keys from /var/tmp directory used in this procedure as they are no longer required by the BIG-IP system.
    Note: Once the pseudo key has been installed with tmsh, the copy in /var/tmp is no longer used.
    Note: Unless the SSL key file is deleted in a secure manner, it might be possible for someone to recover the file from the disk. Consider using the shred utility (type: man shred at the command line for details) to delete any key files copied to the BIG-IP system once they have been successfully imported into the Thales nShield device.

Creating a client SSL profile to use an external HSM key and certificate

After you have installed the external HSM key and certificate to the BIG-IP® system, you can use the key and certificate as part of a client SSL profile.
  1. On the Main tab, click Local Traffic > Profiles > SSL > Client. The Client screen opens.
  2. Click Create. The New Client SSL Profile screen opens.
  3. In the Name field, type a name for the profile.
  4. Select clientssl in the Parent Profile list.
  5. From the Configuration list, select Advanced. This selection makes it possible for you to modify additional default settings.
  6. Select the Custom check box for Configuration. The settings in the Configuration area become available for configuring.
  7. Using the Certificate Key Chain setting, specify one or more certificate key chains:
    1. From the Certificate list, select the name of a certificate that you imported.
    2. From the Key list, select the name of the key that you imported.
    3. From the Chain list, select the chain that you want to include in the certificate key chain.
    4. Click Add.
  8. Click Finished.
After you have created the client SSL profile, you must assign the profile to a virtual server, so that the virtual server can process SSL traffic according to the specified profile settings.
Table of Contents   |   << Previous Chapter   |   Next Chapter >>

Was this resource helpful in solving your issue?




NOTE: Please do not provide personal information.



Incorrect answer. Please try again: Please enter the words to the right: Please enter the numbers you hear:

Additional Comments (optional)