F5 Logo MyF5
Search
  1. MyF5 Home
  2. BIG-IP System and nShield HSM: Implementation
  3. Managing External HSM Keys for LTM
Manual Chapter : Managing External HSM Keys for LTM

Applies To:

Show Versions Show Versions

BIG-IP APM

  • 17.1.1, 17.1.0, 17.0.0, 16.1.5, 16.1.4, 16.1.3, 16.1.2, 16.1.1, 16.1.0, 16.0.1, 16.0.0

BIG-IP LTM

  • 17.1.1, 17.1.0, 17.0.0, 16.1.5, 16.1.4, 16.1.3, 16.1.2, 16.1.1, 16.1.0, 16.0.1, 16.0.0

BIG-IP AFM

  • 17.1.1, 17.1.0, 17.0.0, 16.1.5, 16.1.4, 16.1.3, 16.1.2, 16.1.1, 16.1.0, 16.0.1, 16.0.0

BIG-IP DNS

  • 17.1.1, 17.1.0, 17.0.0, 16.1.5, 16.1.4, 16.1.3, 16.1.2, 16.1.1, 16.1.0, 16.0.1, 16.0.0

BIG-IP ASM

  • 17.1.1, 17.1.0, 17.0.0, 16.1.5, 16.1.4, 16.1.3, 16.1.2, 16.1.1, 16.1.0, 16.0.1, 16.0.0
Manual Chapter

Managing External HSM Keys for LTM

Overview: Managing external HSM keys for LTM

You can use the nShield to store and manage token-, module-, and softcard-protected keys.
For additional information about using nShield, refer to the nShield website: (hsm).

About key protection

There are three types of key protection available for use with the BIG-IP system and nShield:
  • 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 module protection. nShield prefers the use of physical tokens for authorization. In the case of Operator Cards, nShield recommends making a 1/N card set, where N is greater than the total number of nShields. For more information about card sets, refer to the nShield user guides.

Configuring the key protection type

On the BIG-IP system, you can choose among the nShield-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:
    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 softcard key protection by moving any previously created
      softcard*
       files from the
      /opt/nfast/kmdata/local
       directory to the
      /opt/nfast/kmdata/
       directory.
    2. Enable OCS key protection by creating the OCS cardset using the nShield-provided
      createocs
       utility.
    softcard
    1. Disable OCS key protection by moving any previously created
      cards*
       files from the
      /opt/nfast/kmdata/local
       directory to the
      /opt/nfast/kmdata
       directory.
    2. Enable softcard key protection by creating the softcard cardset using the nShield-provided
      ppmk
       utility.
    The softcard passphrase used in the
    ppmk
     command must match the passphrase used for setting up the nShield client on the BIG-IP system (used in the command
    tmsh create/modify sys crypto fips external-hsm password <
    password
    >
    ).
    If OCS is configured with a passphrase for nShield HSM, the user must enter it when prompted for
    nShield HSM slot password
    , even if the user only wants to use module keys.
    To revert back to module protection, change
    CKNFAST_NO_ACCELERATOR_SLOTS=1
    to
    CKNFAST_NO_ACCELERATOR_SLOTS=0
    and remove any softcard or OCS files out of
    /opt/nfast/kmdata/local
    .
  3. After you make any configuration changes, you must restart the
    pkcs11
     and
    tmm
     services.
     
    
                    tmsh restart sys service pkcs11d
                    tmsh restart sys service tmm

Generating a key/certificate using tmsh

You can use the Traffic Management Shell (
tmsh
) to generate a key and certificate.
  1. Log in to the command-line interface of the system using an account with administrator privileges.
  2. Open the TMOS Shell (
    tmsh
    ).
    tmsh
  3. Generate the key.
    create sys crypto key
    <key_name>
     gen-certificate common-name
    <cert_name>
     security-type nethsm
    This example generates an external HSM key named
    test_key
     and a certificate named
    test_nshield.com
     with the security type of
    nethsm
    :
    create sys crypto key test_key gen-certificate common-name test_nshield.com security-type nethsm
  4. Verify that the key was created.
    list sys crypto key test_key.key
    Information about the key displays:
    sys crypto key test_key.key {
key-id <
    32-digit string
    >
key-size 2048
key-type rsa-private
security-type nethsm
}
When you generate a key/certificate using
tmsh
, the system creates a HSM private key. It also creates a local key, which points to the HSM key, residing in the HSM.

Creating a self-signed digital certificate

If you are configuring the BIG-IP system to manage client-side HTTP traffic, you perform this task to create a self-signed certificate to authenticate and secure the client-side HTTP traffic. If you are also configuring the system to manage server-side HTTP traffic, you must repeat this task to create a second self-signed certificate to authenticate and secure the server-side HTTP traffic.
  1. On the Main tab, click
    System
    Certificate Management
    Traffic Certificate Management
    .
    The Traffic Certificate Management screen opens.
  2. Click
    Create
    .
  3. In the
    Name
     field, type a unique name for the SSL certificate.
  4. From the
    Issuer
     list, select
    Self
    .
  5. In the
    Common Name
     field, type a name.
    This is typically the name of a web site, such as
    www.siterequest.com
    .
  6. In the
    Division
     field, type your department name.
  7. In the
    Organization
     field, type your company name.
  8. In the
    Locality
     field, type your city name.
  9. In the or
    State or Province
     field, type your state or province name.
  10. From the
    Country
     list, select the name of your country.
  11. In the
    E-mail Address
     field, type your email address.
  12. In the
    Lifetime
     field, type a number of days, or retain the default,
    365
    .
  13. In the
    Subject Alternative Name
     field, type a name.
    This name is embedded in the certificate for X509 extension purposes.
    By assigning this name, you can protect multiple host names with a single SSL certificate.
  14. From the
    Security Type
     list, select
    NetHSM
    .
  15. From the
    Key Type
     list,
    RSA
     is selected as the default key type.
  16. From the
    Size
     list, select a size, in bits.
  17. Click
    Finished
    .

Requesting a certificate from a certificate authority

You perform this task to generate a certificate signing request (CSR) that can then be submitted to a third-party trusted certificate authority (CA).
F5 Networks recommends that you consult the CA to determine the specific information required for each step in this task.
  1. On the Main tab, click
    System
    Certificate Management
    Traffic Certificate Management
    .
    The Traffic Certificate Management screen opens.
  2. Click
    Create
    .
  3. In the
    Name
     field, type a unique name for the SSL certificate.
  4. From the
    Issuer
     list, select
    Certificate Authority
    .
  5. In the
    Common Name
     field, type a name.
    This is typically the name of a web site, such as
    www.siterequest.com
    .
  6. In the
    Division
     field, type your department name.
  7. In the
    Organization
     field, type your company name.
  8. In the
    Locality
     field, type your city name.
  9. In the or
    State or Province
     field, type your state or province name.
  10. From the
    Country
     list, select the name of your country.
  11. In the
    E-mail Address
     field, type your email address.
  12. In the
    Lifetime
     field, type a number of days, or retain the default,
    365
    .
  13. In the
    Subject Alternative Name
     field, type a name.
    This name is embedded in the certificate for X509 extension purposes.
    By assigning this name, you can protect multiple host names with a single SSL certificate.
  14. In the
    Challenge Password
     field, type a password.
  15. In the
    Confirm Password
     field, re-type the password you typed in the
    Challenge Password
     field.
  16. From the
    Security Type
     list, select
    NetHSM
    .
  17. From the
    Key Type
     list,
    RSA
     is selected as the default key type.
  18. From the
    Size
     list, select a size, in bits.
  19. Click
    Finished
    .
    The Certificate Signing Request screen displays.
  20. Do one of the following to download the request into a file on your system.
    • In the
      Request Text
       field, copy the certificate.
    • For
      Request File
      , click the button.
  21. Follow the instructions on the relevant certificate authority web site for either pasting the copied request or attaching the generated request file.
  22. Click
    Finished
    .
    The Certificate Signing Request screen displays.
The generated certificate signing request is submitted to a trusted certificate authority for signature.

Deleting a key from the BIG-IP

You perform this task to delete an existing key from the BIG-IP.
  1. On the Main tab, click
    System
    Certificate Management
    Traffic Certificate Management
    .
    The Traffic Certificate Management screen opens.
  2. From the
    SSL Certificate List
    , select the check box next to the key you wish to delete.
  3. Click
    Delete
    .
The key you selected is deleted from BIG-IP.
The key stored in NetHSM is not deleted.

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

After you have added the external HSM key and certificate to the BIG-IP system configuration, you can use the key and certificate as part of a client SSL profile. This task describes using the browser interface. Alternatively, you can use the Traffic Management Shell (
tmsh
) command-line utility.
  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. From the
    Parent Profile
     list, select
    clientssl
    .
  5. From the
    Configuration
     list, select
    Advanced
    .
    This selection makes it possible for you to modify additional default settings.
  6. For the Configuration area, select the
    Custom
     check box.
    The settings in the Configuration area become available for modification.
  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.

Migrating existing software-protected or unprotected keys to the nShield HSM

Before you begin this task, make sure that the nShield client is installed and configured on the BIG-IP system.
If you already have regular RSA keys, you can migrate them to the nShield HSM.
A nShield HSM device that is configured with the
Strict FIPS 140-2 Level 3
 compliance flag prevents importation of extraneous private keys.
  1. Log in to the command-line interface of the system using an account with administrator privileges.
  2. Migrate the key.
    fipskey.nethsm --export -i <
    input_key_full_path_filename
    > -o output_key_filename
    This example generates the four files that follow:
    fipskey.nethsm --export -i regular_key -o hsm_key
    • /config/ssl/ssl.key/hsm_key.key
       (local key)
    • /config/ssl/ssl.csr/hsm_key.csr
      (CSR file)
    • /config/ssl/ssl.crt/hsm_key.crt
       (self-signed certificate)
    • /opt/nfast/kmdata/local/
      protected_key_filename
      (protected key)
If you migrated a key that has a certificate that is already issued by a reputable issuing CA, you should migrate the key, but continue using the old certificate. After you migrate the existing key to the nShield HSM, you must load the key into the BIG-IP system using
tmsh
, and then modify the client SSL profile, or create a new client SSL profile that uses the new key and the existing certificate.

Importing existing SSL keys into 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 nShield 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 nShield 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_uced028e5251b7b​6891e7e59dec5428d871f92241b-c70e6451e8d793ca80a497267ccb9bc73bd55edb
    

    chmod 755 /opt/nfast/kmdata/local/key_pkcs11_uced028e5251b7b​6891e7e59dec5428d871f92241b-c70e6451e8d793ca80a497267ccb9bc73bd55edb
    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@hostname:Active:Standalone] tmp # rfs-sync --update
          

    [root@hostname: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.
    Once the pseudo key has been installed with
    tmsh
    , the copy in
    /var/tmp
     is no longer used.
    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 nShield device.
    When you create a new nShield key for BIG-IP HA, you must run the command
    rfs-sync --update
     on all standby BIG-IP devices to update the local nShield encrypted file object cache. Without this action, SSL traffic using this key will fail when BIG-IP fails over to one of the unsynced standby devices.

Importing a pre-existing NetHSM key to the BIG-IP

  1. On the Main tab, click
    System
    Certificate Management
    Traffic Certificate Managment
    SSL Certificate List
    Import
    .
    The SSL Certificate/Key Source page opens.
  2. Within
    Import Type
    , select
    Key
    .
    The key name should be the same as the NetHSM key label.
  3. Within
    Key Name
    , select
    Overwrite Existing
     and from the drop-down menu, select the key you would like to overwrite.
  4. Within Key Source, select
    From NetHSM
    .
    For this option to be available, the system must have External HSM licensed, and either SafeNet/nShield External HSM configured.
  5. Click
    Import
    .
You can also import an existing key by using tmsh commands
tmsh install sys crypto key nethsm_key_label from-nethsm security-type
 or
tmsh install sys crypto key nethsm_key_label from-nethsm
. Use the NetHSM key label as the key name. For example:
root@(hostname)(Standalone)(Active)(/Common)(tmos)# install sys crypto key nethsm_key_label (tab)
Options:
  from-editor       from-nethsm 
Properties:
  from-local-file   from-url    
root@(ssl8519)(cfg-sync Standalone)(Active)(/Common)(tmos)# install sys crypto key nethsm_key_label from-nethsm security-type nethsm
Contact Support Contact Support

Have a Question?

Support and Sales >

About F5

Education

F5 Sites

Support Tasks




©2023 F5, Inc. All rights reserved.


Trademarks Policies Privacy California Privacy Do Not Sell My Personal Information