Manual Chapter : Embedded HSM initialization and synchronization overview

Applies To:

Show Versions Show Versions

BIG-IP APM

  • 17.1.2

BIG-IP LTM

  • 17.1.2

BIG-IP DNS

  • 17.1.2

BIG-IP ASM

  • 17.1.2
Manual Chapter

Embedded HSM initialization and synchronization overview

After you have set up and configured your F5 FIPS platform, you create a FIPS security domain by initializing the embedded hardware security module (HSM) and then synchronizing all applicable HSMs.

HSM management on BIG-IP platforms

On BIG-IP platforms with an embedded hardware security module (HSM), you perform all HSM management tasks, such as HSM initialization and synchronization, from the TMOS Shell (
tmsh
).
By default, private keys can be created or imported into the onboard FIPS HSM. To disable key import, use the option "-k ... Disable PEM key import during INIT." in fipsutil during partition initialization. This prevents the import of PEM keys into the HSM. Once initialized with this option, the key import restriction remains in effect until the partition is re-initialized. This setting cannot be modified while the partition is in use.

Initialize the HSM in 5000/7000/10200 platforms

You must initialize the hardware security module (HSM) installed in each unit before you can use it. This is typically a one-time operation. When you are creating a device group using more than one FIPS platform, you initialize the HSM on one unit, and then initialize the HSM on a peer unit using the same security domain label that you used on the first unit.
You can initialize the HSM and create the security domain before you license the system and create a traffic management configuration.
  1. Log in to the command line of the system using an account with root access.
  2. Open the TMOS Shell (
    tmsh
    ).
    tmsh
  3. Initialize the HSM and set a security officer (SO) password.
    run util fips-util -f init
    Running this command deletes all keys in the HSM and makes any previously exported keys unusable.
    The initialization process takes a few minutes to complete.
    The initialization process begins. When prompted, type the Security Officer (SO) password.
    F5 recommends that you choose a strong value for the SO password. You cannot use the keyword
    default
    as the SO password.
    WARNING: This erases all keys from the FIPS 140 device. Any configuration objects dependent on FIPS keys will cause the configuration fail to load. ==================== WARNING ================================ The FIPS device will be reset to factory default state. All keys and user identities currently stored in the device will be erased. Any configuration objects dependent on FIPS keys will cause the configuration fail to load. Press <ENTER> to continue or Ctrl-C to cancel Resetting the device ... The FIPS device is now in factory default state. Enter new Security Officer password (min. 7, max. 14 characters): Re-enter Security Officer password:
  4. When this message displays, type a security domain label.
    NOTE: security domain label must be identical on peer FIPS devices in order to be able to synchronize with them. Enter security domain label (max. 50 chars, default: F5FIPS):
    Be sure to keep the security domain label and password in a secure location. You need the domain label and password when you initialize the HSM on a peer unit. You can use the same password or choose a new one. This information is also required when replacing a unit (for RMA or other reasons). Since keys are synchronized from the working unit to a new unit, the domain label and password are required.
    Initializing new security domain (F5FIPS)... Creating crypto user and crypto officer identities Waiting for the device to re-initialize ... Creating key encryption key (KEK) The FIPS device has been initialized.
  5. Enable the HSM device using one of these options:
    • Reboot the unit.
    • Restart all services:
      restart sys service all
      .
      Restarting services disrupts load-balanced traffic and might terminate remote login sessions to the system.
After you complete the initialization process on the first unit, you can initialize a peer system and add it to the security domain of the first unit. You must use the same security domain label that you used on the first unit.

Initialize the HSM in 10350v-F platforms

You must initialize the hardware security module (HSM) installed in each unit before you can use it. This is typically a one-time operation. When you are creating a device group using more than one FIPS platform, you initialize the HSM on one unit, and then initialize the HSM on a peer unit using the same security domain label that you used on the first unit. You can choose to use a different password on the peer unit.
You can initialize the HSM and create the security domain, before you license the system and create a traffic management configuration.
  1. Log in to the command line of the system using an account with root access.
  2. Open the TMOS Shell (
    tmsh
    ).
    tmsh
  3. Initialize the HSM and set a security officer (SO) password.
    run util fips-util init
    Running this command deletes all keys in the HSM and makes any previously exported keys unusable.
    The initialization process takes a few minutes to complete.
    The initialization process begins. When prompted, type the Security Officer (SO) password. You cannot use the keyword
    default
    as the SO password.
    F5 recommends that you choose a strong value for the SO password.
    If this text displays in the message below, you need to first delete all keys from the device before running the command:
    There are keys stored in the FIPS device Delete all keys from the device before re-initializing it
    . You can use the
    -f
    option to force initialization, which deletes all user-generated keys (
    util fips-util -f init
    ).
    WARNING: This erases all keys from the FIPS 140 device. Any configuration objects dependent on FIPS keys will cause the configuration fail to load. ==================== WARNING ================================ The FIPS device will be reset to factory default state. All keys and user identities currently stored in the device will be erased. Any configuration objects dependent on FIPS keys will cause the configuration fail to load. Press <ENTER> to continue or Ctrl-C to cancel Resetting the device ... The FIPS device is now in factory default state. Enter new Security Officer password (min. 7, max. 14 characters): Re-enter Security Officer password:
  4. When this message displays, type a security domain label.
    NOTE: security domain label must be identical on peer FIPS devices in order to be able to synchronize with them. Enter security domain label (max. 50 chars, default: F5FIPS):
    Be sure to keep the security domain label and password in a secure location. You need the domain label and password when you initialize the HSM on a peer unit. You can use the same password or choose a new one. This information is also required when replacing a unit (for RMA or other reasons). Since keys are synchronized from the working unit to a new unit, the domain label and password are required.
    Initializing new security domain (F5FIPS)... Creating crypto user and crypto officer identities Waiting for the device to re-initialize ... Creating key encryption key (KEK) The FIPS device has been initialized.
  5. Enable the HSM device using one of these options:
    • Reboot the unit.
    • Restart all services:
      restart sys service all
      .
      Restarting services disrupts load-balanced traffic and might terminate remote login sessions to the system.
After you complete the initialization process on the first unit, you can initialize a peer system and add it to the security domain of the first unit. You can choose to use the same SO password that you used on the first unit.

Initialize the HSM in i5000F (i5820-DF)/i7000F (i7820-DF)/i15000-DF (i15820-DF) platforms

You must initialize the hardware security module (HSM) installed in each unit before you can use it. This is typically a one-time operation. When you are creating a device group using more than one FIPS platform, you initialize the HSM on one unit, and then initialize the HSM on a peer unit using the same security domain label that you used on the first unit. You can choose to use a different password on the peer unit.
You can initialize the HSM and create the security domain, before you license the system and create a traffic management configuration.
  1. Log in to the command line of the system using an account with root access.
  2. Open the TMOS Shell (
    tmsh
    ).
    tmsh
  3. Initialize the HSM and set a security officer (SO) password.
    run util fips-util init
    Running this command deletes all keys in the HSM and makes any previously exported keys unusable.
    The initialization process takes a few minutes to complete.
    The initialization process begins. When prompted, type the Security Officer (SO) password. You cannot use the keyword
    default
    as the SO password.
    F5 recommends that you choose a strong value for the SO password.
    If this text displays in the message below, you need to first delete all keys from the device before running the command:
    There are keys stored in the FIPS device Delete all keys from the device before re-initializing it
    . You can use the
    -f
    option to force initialization, which deletes all user-generated keys (
    util fips-util -f init
    ).
    WARNING: This erases all keys from the FIPS 140 device. Any configuration objects dependent on FIPS keys will cause the configuration fail to load. ==================== WARNING ================================ The FIPS device will be reset to factory default state. All keys and user identities currently stored in the device will be erased. Any configuration objects dependent on FIPS keys will cause the configuration fail to load. Press <ENTER> to continue or Ctrl-C to cancel Resetting the device ... The FIPS device is now in factory default state. Enter new Security Officer password (min. 7, max. 14 characters): Re-enter Security Officer password:
  4. When this message displays, type a security domain label.
    NOTE: security domain label must be identical on peer FIPS devices in order to be able to synchronize with them. Enter security domain label (max. 49 chars, default: F5FIPS):
    Be sure to keep the security domain label and password in a secure location. You need the domain label and password when you initialize the HSM on a peer unit. You can use the same password or choose a new one. This information is also required when replacing a unit (for RMA or other reasons). Since keys are synchronized from the working unit to a new unit, the domain label and password are required.
    Initializing new security domain (F5FIPS)... Creating crypto user and crypto officer identities Waiting for the device to re-initialize ... Creating key encryption key (KEK) The FIPS device has been initialized.
  5. Enable the HSM device using one of these options:
    • Reboot the unit.
    • Restart all services:
      restart sys service all
      .
      Restarting services disrupts load-balanced traffic and might terminate remote login sessions to the system.
After you complete the initialization process on the first unit, you can initialize a peer system and add it to the security domain of the first unit. You can choose to use the same SO password that you used on the first unit.

View HSM information using tmsh

You can use the TMOS Shell (
tmsh
) to view information about the hardware security module (HSM) on BIG-IP systems. If you have a 10350v-FIPS platform provisioned for Virtual Clustered Multiprocessing (vCMP), you can also view information about any FIPS partitions on the HSM.
  1. Log in to the command line of the system using an account with root access.
  2. Open the TMOS Shell (
    tmsh
    ).
    tmsh
  3. View information about the HSM.
    run util fips-util info
    Depending on the HSM installed in your system, a summary similar to this example (from a 10350 platform) displays.
    Label: F5FIPS Model: NITROX-III CNN35XX-NFBE Serial Number: 3.0G1501-ICM000059 FIPS state: 2 MaxSessionCount: 2048 SessionCount: 13 MaxPinLen: 14 MinPinLen: 7 TotalPublicMemory: 557540 FreePublicMemory: 234552 TotalUserKeys: 10075 AvailableUserKeys: 10075 Logging failures: user: 0 officer: 0 Temperature: 72 C HW version: 0.0 Firmware version: CNN35XX-NFBE-FW-1.0-27
  4. View information about FIPS partitions on the HSM.
    run util fips-util ptninfo

Before you synchronize the HSMs

Before you can synchronize the FIPS hardware security modules (HSMs), you must ensure that the target HSM:
  • Is already initialized
  • Has an identical security domain name
  • Does not contain existing keys
  • Is the same hardware model
  • Contains the same firmware version
Before you run the
fips-card-sync
command, ensure that you have this information:
  • The Security Officer (SO) password for the source F5 device
  • The SO password for the target F5 device
  • The root password for the target F5 device
The target device must also be reachable using SSH from the source device.

Synchronize the HSMs using tmsh

Be sure that you meet all prerequisites before synchronizing the hardware security modules (HSMs) in your devices.
Synchronizing the HSMs enables you to copy keys from one HSM to another. This is also required to synchronize the software configuration in a device group.
You only need to perform the synchronization process during the initial configuration of a pair of devices. After the two devices are in sync, they remain in sync.
  1. Log on to the command line of the source F5 device using an account with root access.
  2. Open the TMOS Shell (
    tmsh
    ).
    tmsh
  3. Synchronize the masking from the HSM on the source F5 device to the HSM on the target F5 device, where <
    hostname
    > is the IP address or hostname of the target F5 device.
    run util fips-card-sync
    <hostname>
    Be sure to run this command on a device that contains a valid masking key. Otherwise, you might invalidate all keys loaded in the HSM.
    A masking key is shared between the HSMs on each F5 device. This shared masking key is used to encrypt the SSL private keys when the keys leave the cryptographic boundary of the HSM.
    1. When prompted, type the security officer (SO) password for the local device.
    2. When prompted, type the SO password for the remote device or press Enter if the password is the same as for the local device.
      A message similar to this example displays:
      Connecting to 192.0.2.255 as user root ...
    3. When prompted, type the root password.
      When the synchronization operation completes, a message similar to this example displays:
      FIPS devices have been synchronized.
  4. Synchronize the software configuration in the device group.
    You must run
    fips-card-sync
    before running
    config-sync
    . Otherwise, the FIPS keys will not load on the remote device.
    run cm config-sync [
    to-group
    |
    from-group
    ] <
    device-group-name
    >

HSM management on F5 rSeries platforms

On F5 rSeries platforms with an embedded HSM, you manage the hardware security module (HSM) from the system CLI. This includes initializing the HSM and managing FIPS partitions. You can also view HSM information and manage FIPS partitions from the F5OS webUI.
You perform key management tasks at the tenant level from the TMOS Shell (
tmsh
) using utilities that are also available on BIG-IP platforms with an embedded HSM. For more information, see Key management on embedded FIPS systems
By default, private keys can be created or imported into the onboard FIPS HSM. To disable key import, use the option "-k ... Disable PEM key import during INIT." in fipsutil during partition initialization. This prevents the import of PEM keys into the HSM. Once initialized with this option, the key import restriction remains in effect until the partition is re-initialized. This setting cannot be modified while the partition is in use.
For more information on FIPS card synchronization at the tenant level, see
Before you synchronize the HSMs
and
Synchronize the HSMs using tmsh
in the above section.

HSM management from the CLI

You can manage the hardware security module (HSM) and FIPS partitions from the CLI.

Initialize the HSM in F5 r5000/r10000 platforms

The hardware security module (HSM) installed in your F5 r5000/r10000 FIPS platform is uninitialized by default. You must initialize the HSM before you can use it. This is typically a one-time operation.
  1. Initialize the HSM and set a security officer (SO) password.
    Forcing the initialization deletes all keys in the HSM and makes any previously-exported keys unusable.
    fips hsm force-init
    When prompted, type an SO password. You cannot use the keyword
    default
    as the SO password.
    F5 recommends that you choose a strong value for the SO password and keep it in a secure location.
    Value for 'new-so-password' (<string, min: 7 chars, max: 30 chars>): ******** Value for 'confirm-new-so-password' (<string, min: 7 chars, max: 30 chars>): ********
    The initialization process begins and might take a few minutes to complete..
    Initialization is complete, when this message displays:
    result The FIPS device has been initialized.
After you complete the initialization, you create a FIPS partition.

Create a FIPS partition from the CLI

After initializing the HSM, these resources are assigned to a single default FIPS partition called PARTITION_1 (also called a virtual HSM):
  • Number of keys that the FIPS partition can hold. The range is from 1 to 1000000.
  • Number of acceleration devices (or acceleration cores) for the FIPS partition. The range is from 1 to 63. F5 r5000-DF platforms support up to 32 acceleration devices, and F5 r10000-DF platforms support up to 63 acceleration devices.
Before you can create a new FIPS partition from the CLI, you must first deallocate resources from the default partition so that they can be assigned to any new partitions.
F5 r5000-DF platforms support up to 24 FIPS partitions, and F5 r10000-DF platforms support up to 32 FIPS partitions.
  1. View information about the default FIPS partition.
    show fips partitions
    A summary similar to this example displays:
    appliance-1# show fips partitions OCCUPIED ACCEL FIPS SESSION SESSION PCI NAME NAME KEYS DEVS BACKUP ID STATE KEYS COUNT ADDRESS ----------------------------------------------------------------------------------------- PARTITION_1 PARTITION_1 10075 63 disabled - 255 0 10 ca:10.0
  2. Resize the default partition.
    fips set-partition name <
    fips-partition
    > accel-devs <
    quantity
    > keys <
    quantity
    > backup {
    false
    |
    true
    }
    This example changes PARTITION_1 to use one acceleration device and hold 10 keys:
    appliance-1(config)# fips set-partition name PARTITION_1 accel-devs 1 keys 10 Value for 'so-password' (<string, min 7 chars, max 30 chars>): *********** result fips partition PARTITION_1 has been resized
  3. Create a new FIPS partition.
    fips set-partition name <
    fips-partition
    > accel-devs <
    quantity
    > keys <
    quantity
    > backup {
    false
    |
    true
    }
    If you plan to migrate keys from an iSeries FIPS platform and restore to this FIPS partition on your rSeries FIPS platform, be sure to set the
    backup
    option to
    true
    .
    This example creates PARTITION_2:
    appliance-1(config)# fips set-partition name PARTITION_2 accel-devs 12 keys 128 backup true Value for 'so-password' (<string, min 7 chars, max 30 chars>): *********** result fips partition PARTITION_2 has been created
  4. Verify the FIPS partition information.
    show fips partitions
    A summary similar to this example displays:
    appliance-1# show fips partitions OCCUPIED ACCEL FIPS SESSION SESSION PCI NAME NAME KEYS DEVS BACKUP ID STATE KEYS COUNT ADDRESS ----------------------------------------------------------------------------------------- PARTITION_1 PARTITION_1 20 1 disabled - 255 0 10 ca:10.0 PARTITION_2 PARTITION_2 128 12 disabled - - - - ca:10.2
After you complete the initialization, you create a tenant that uses the FIPS partition.

Create a tenant with a FIPS partition from the CLI

After you create a FIPS partition, you can create a tenant and assign the FIPS partition to it from the CLI.
F5 rSeries FIPS platforms support only tenants running BIG-IP software version 17.1.0.1 or later.
  1. Create and deploy a tenant that uses a FIPS partition.
    tenants tenant <
    name
    > config type BIG-IP image <
    filename
    >.bundle fips-partition <
    partition-name
    > cryptos enabled vcpu-cores-per-node <
    cores
    > nodes <
    node
    > mgmt-ip <
    ip-address
    > prefix-length <
    prefix
    > gateway <
    ip-address
    > memory <
    memory
    > running-state deployed vlans <
    vlan-ids
    >
    This example creates a BIG-IP tenant called
    big-ip
    that uses a FIPS partition named PARTITION_2:
    appliance-1(config)# tenants tenant big-ip config type BIG-IP image BIGIP-17.1.0.1-0.0.0.ALL-F5OS.qcow2.zip.bundle fips-partition PARTITION_2 cryptos enabled vcpu-cores-per-node 6 nodes 1 mgmt-ip 192.0.2.42 prefix-length 24 gateway 192.0.2.254 memory 22016 running-state deployed vlans 11
After you complete the initialization, you initialize the FIPS partition from the tenant CLI.

Initialize the HSM partition in F5OS tenants from the CLI

You must initialize the hardware security module (HSM) partition assigned to a tenant before you can use it.
You can initialize the HSM and create the security domain before you license the system and create a traffic management configuration.
  1. Log in to the command line interface (CLI) of the tenant using an account with admin access.
  2. Open the TMOS Shell (
    tmsh
    ).
    tmsh
  3. Initialize the HSM and set a security officer (SO) password.
    run util fips-util init
    Running this command deletes all keys in the HSM and makes any previously exported keys unusable.
    The initialization process takes a few minutes to complete.
    The initialization process begins. When prompted, type the Security Officer (SO) password. You cannot use the keyword
    default
    as the SO password.
    F5 recommends that you choose a strong value for the SO password.
    If this text displays in the message below, you need to first delete all keys from the device before running the command:
    There are keys stored in the FIPS device Delete all keys from the device before re-initializing it
    . You can use the
    -f
    option to force initialization, which deletes all user-generated keys (
    util fips-util -f init
    ).
    WARNING: This erases all keys from the FIPS 140 device. Any configuration objects dependent on FIPS keys will cause the configuration fail to load. ==================== WARNING ================================ The FIPS device will be reset to factory default state. All keys and user identities currently stored in the device will be erased. Any configuration objects dependent on FIPS keys will cause the configuration fail to load. Press <ENTER> to continue or Ctrl-C to cancel Resetting the device ... The FIPS device is now in factory default state. Enter new Security Officer password (min. 7, max. 14 characters): Re-enter Security Officer password:
  4. When this message displays, type a security domain label.
    NOTE: security domain label must be identical on peer FIPS devices in order to be able to synchronize with them. Enter security domain label (max. 49 chars, default: F5FIPS):
    Be sure to keep the security domain label and password in a secure location. You need the domain label and password when you initialize the HSM on a peer unit. You can use the same password or choose a new one. This information is also required when replacing a unit (for RMA or other reasons). Since keys are synchronized from the working unit to a new unit, the domain label and password are required.
    Initializing new security domain (F5FIPS)... Creating crypto user and crypto officer identities Waiting for the device to re-initialize ... Creating key encryption key (KEK) The FIPS device has been initialized.
  5. Enable the HSM device using one of these options:
    • Reboot the unit.
    • Restart all services:
      restart sys service all
      .
      Restarting services disrupts load-balanced traffic and might terminate remote login sessions to the system.

View HSM information in the CLI

You can view information about the embedded hardware security module (HSM) on F5 r5000-DF/r10000-DF FIPS systems from the CLI.
If the State is 2, the HSM is initialized. If the State is -1, the HSM is not initialized.
  1. View information about the HSM.
    show fips status
    A summary similar to this example displays.
    appliance-1# show fips status fips status last-updated "Tue Nov 15 18:50:02 2022\n" fips status state 2 fips status desc "FIPS mode with single factor authentication" fips status label cavium fips status model "NITROX-III CNN35XX-NFBE" fips status part-number CNN3560-NFBE-3.0-G fips status serial-number 6.0G2139-VPM006082 fips status firmware-major-version 8 fips status firmware-minor-version 2 fips status hw-major-version 54 fips status hw-minor-version 48 fips status build-number 11-25 fips status firmware-id CNN35XX-NFBE-FW-2.08-11-25 fips status temperature "53 C" fips status wear-leveling DEVICE_STATUS_OK

HSM management from the webUI

You can manage the hardware security module (HSM) and FIPS partitions from the F5OS webUI.

Display HSM information from the webUI

The HSM Details screen lists read-only information about the embedded hardware security module (HSM) on F5 r5000-DF/r10000-DF FIPS systems. This screen shows information, such as state, part/serial numbers, firmware/hardware versions, build number, temperature, and wear leveling.
If the State is 2, the HSM is initialized. If the State is -1, the HSM is not initialized.

Configure the default FIPS partition from the webUI

The FIPS Partitions screen lists FIPS partitions on the embedded hardware security module (HSM). If the HSM is newly initialized, the FIPS Partitions screen lists only the default partition (PARTITION_1). If the HSM needs to be initialized, no FIPS partitions are listed. For more information on initializing the HSM, see Initialize the HSM in F5 r5000/r10000 platforms.
After initializing the HSM, all resources (keys and acceleration devices) are assigned to a single default FIPS partition (PARTITION_1). Before you can create a new FIPS partition from the webUI, you must first deallocate resources from the default partition so they can be assigned to a new partition.
  1. Click the default partition name (PARTITION_1).
    The Edit FIPS Partition screen displays.
  2. For
    Keys
    , enter the maximum number of keys the FIPS partition can hold.
    The range is from 1 to 1000000.
  3. For
    Accel Devs
    , enter the maximum number of acceleration devices used for the FIPS partition.
    The range is from 1 to 63. F5 r5000-DF platforms support up to 32 acceleration devices, and F5 r10000-DF platforms support up to 63 acceleration devices.
  4. For
    Backup
    , select whether to enable or disable backup for the FIPS partition.
    If you plan to migrate keys from an iSeries FIPS platform and restore to this FIPS partition on your rSeries FIPS platform, be sure to select
    Enabled
    .
Next, you can create a new custom FIPS partition.

Add FIPS partitions from the webUI

Before you can add a new FIPS partition from the webUI, you must have already deallocated resources from the default partition so they can be assigned to any new partitions.
The FIPS Partitions screen enables you to manage FIPS partitions on the embedded hardware security module (HSM). If the HSM is newly initialized, the FIPS Partitions screen lists only the default partition (PARTITION_1). You can add a new FIPS partition from the webUI.
F5 r5000-DF platforms support up to 24 FIPS partitions, and F5 r10000-DF platforms support up to 32 FIPS partitions.
  1. For
    Name
    , enter a name for the FIPS partition.
    The minimum length is 1 character, and the maximum length is 15 characters.
  2. For
    Keys
    , enter the maximum number of keys the FIPS partition can hold.
    The range is from 1 to 1000000.
  3. For
    Accel Devs
    , enter the maximum number of acceleration devices used for the FIPS partition.
    The range is from 1 to 63. F5 r5000-DF platforms support up to 32 acceleration devices, and F5 r10000-DF platforms support up to 63 acceleration devices.
  4. For
    Backup
    , select whether to enable or disable backup for the FIPS partition.
    If you plan to migrate keys from an iSeries FIPS platform and restore to this FIPS partition on your rSeries FIPS platform, be sure to select
    Enabled
    .
Next, you can create a tenant that uses the new FIPS partition and initialize the HSM partition in the tenant. For more information, see Create a tenant with a FIPS partition from the CLI and Initialize the HSM partition in F5OS tenants from the CLI.
F5 rSeries FIPS platforms support only tenants running BIG-IP software version 17.1.0.1 or later.