Manual Chapter : Setting Up the Network HSM

Applies To:

Show Versions

BIG-IP APM

17.0.0

BIG-IP LTM

17.0.0

BIG-IP AFM

17.0.0

BIG-IP DNS

17.0.0

BIG-IP ASM

17.0.0

Setting Up the Network HSM

Overview: Setting up the Network HSM

F5 BIG-IP supports the following Network HSM vendors:

Amazon CloudHSM

Equinix SmartKey HSM

SafeNet Data Protection on Demand (DPoD) HSM

Atos (Bull Trustway Proteccio) HSM

IBM HPCS HSM

These Network HSMs can be configured by installing the client software from the vendor and configuring it by adding the path to the PKCS #11 library to the BIG-IP configuration. This allows the addition of new Network HSM vendors to occur with greater efficiency. In addition, Network HSM adds support for multiple partitions on a configured HSM and the ability to configure the partitions and define the partition that a key belongs to. Now the configuration of the partition occurs during the install process.

In support of the Network HSM functionality, you can either utilize the new

System

Certificate Management

HSM Management

screen or use the new TMSH commands to configure the Network HSM. If you install the HSM using the existing F5 install script, the information is auto-filled when you open the HSM Management screen. You can also manually install the library by adding the library location to the configuration.

After you install the Network HSM client on the BIG-IP system, you may create and operate with the keys inside the HSM for use with Access Policy Manager and Application Security Manager™.

If you are installing Network HSM on a BIG-IP system that will be licensed for Appliance mode, you must install the Network HSM software prior to licensing the BIG-IP system for Appliance mode.

For specific instructions for HSM client installation and configuration, follow the HSM vendor specific workflows in this guide that link you to the vendor sites where the steps are provided based on the version you want to install.

Prerequisites for setting up Network HSM with BIG-IP system

Before you can use Network HSM with the BIG-IP system, you must make sure that these requirements are in place:

You have created the Network Security World (security architecture).

The BIG-IP system is licensed for "External Interface and Network HSM."

You cannot run the BIG-IP system with both internal and external HSMs at the same time.

BIG-IP TMOS with Network HSM only supports IPv4.

Other administrative information to keep in mind during setup:

Partition names must be unique.

Only one network HSM can be configured at a time.

You must identify a partition when installing a client (when using the F5 installer).

If you change the install path, client code, or any partition information, you must restart the pkcs11d daemon.

If you configure a cloud HSM from scratch, you must restart TMM daemon.

Run the test utility after making any changes to ensure that the HSM is configured correctly.

If you do not specify a partition when creating a key, the first listed partition will be used. The partition name will be automatically entered as "auto".

If you try to delete a partition when there are keys defined that use that partition, you will not be allowed to do so.

For supported Network HSM versions with BIG-IP TMOS versions information, see each vendor's respective Interoperability Matrix for BIG-IP TMOS with HSM supplemental document available on AskF5.

Supported Versions

Network HSM supported versions:

Amazon CloudHSM: Version 2.0.4

Equinix SmartKey: Version 2.24.1051

Atos Proteccio: Version 1.08.18

DPoD: Version 1.1.0

IBM HPCS: Version 2.4.117

Setting up Network HSM Client Installation and Configuration

To setup a Network HSM, you must have network access to the HSM with the DNS configured to resolve it.

Task Summary for Amazon CloudHSM and Equinix SmartKey HSM

Setup your Network HSM device

Install the client software and create a Cryptographic User (CU)

Configure and activate the software

Configure the BIG-IP

Add the HSM service (if any) to the BIG-IP startup scripts

Add the library path

Setup and configure partitions

Manage partitions

Setting up Amazon CloudHSM client installation and configuration

Set up your Amazon CloudHSM by following the documentation in the Getting Started section of the CloudHSM guide.

Amazon CloudHSM is only available for virtual machines running in the AWS cloud.

Your AWS BIG-IP VE is the EC2 client mentioned in the getting started guide and should be in the same VPC and availability zone as the CloudHSM. The getting started topics consist of information to assist creating, initializing, and activating AWS CloudHSM cluster.

Follow the AWS topic directions up until following the task steps found in the Install and Client (Linux) section.

Creating a cryptographic user

Manage your HSM cryptographic users (CU) or officers (CO) in your Amazon CloudHSM cluster by:

creating users

listing users

changing user passwords

deleting users

Follow the steps required at Managing HSM Users in AWS CloudHSM.

Installing the clients

Install the clients by logging into the AWS BIG-IP VE as root and run:

This client installation needs to be conducted after the BIG-IP upgrade process.

cd /shared/
mkdir nethsm
cd nethsm
curl -O https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL6/cloudhsm-client-3.2.1-1.el6.x86_64.rpm  
curl -O https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL6/cloudhsm-client-pkcs11-3.2.1-1.el6.x86_64.rpm

rpm -ivh ./cloudhsm-client-pkcs11-1.0-18.x86_64.rpm
rpm -ivh ./cloudhsm-client-1.0-18.x86_64.rpm

Configuring and activating the software

To configure and activate the software you must edit the client configuration before you can use the CloudHSM client to connect to your cluster.

Follow the steps required at Edit the Client Configuration.

The link takes you to a resource outside of AskF5. It is possible the referred documents have been removed without our knowledge.

Configure the BIG-IP

To configure your BIG-IP with your newly configured and activated HSM, you can:

Add your HSM service to the BIG-IP startup scripts.

Add the library path and configure partitions.

Adding the HSM service to the BIG-IP startup scripts

To add your CloudHSM service to the BIG-IP startup scripts, run the following:

# systemctl enable cloudhsm-client.service

Adding the library path and configuring partitions

To add your CloudHSM library to the BIG-IP and configure the partitions, perform either the UI screen or CLI to accomplish the task.

On the Main tab, click

System

Certificate Management

External HSM

. The External HSM screen opens.

From the

Vendor

list, select

Auto

In the

PKCS11 Library Path

field, type the following:

/opt/cloudhsm/lib/libcloudhsm_pkcs11_standard.so

In the

Partition List

section, add the following details:

In the

Name

field, type

cavium

(case sensitive).

If you type

auto

in the

Name

field, the first available partition will be selected.

In the Password field, type the <

CU user name

>:<

password

Click

Add

to add as many partitions as necessary.

To edit any existing partition, select the partition and click

Edit

To delete any existing partition, select the partition and click

Delete

To test any existing partition, select a partition and click

Test

If you selected

Test

, review the Test Output to make sure your details are accurate.

If the test does not pass, attempt to locate the problem and enable debug logging and run the test again for further details. The logs are writing to

/var/log/ltm

Make sure to reset debug logging to the prior setting before continuing.

Click

Update

If you are using the CLI, do the following:

Add your CloudHSM library to the BIG-IP by entering:

# tmsh create sys crypto fips external-hsm vendor auto pkcs11-lib-path /opt/cloudhsm/lib/libcloudhsm_pkcs11_standard.so

Configure the partition, by entering:

# tmsh create sys crypto fips nethsm-partition <partition-name> password "<CU user name>:<password>"

For <partition-name>, use "cavium" as it is the default partition name for AWS CloudHSM. You can also use "auto" to point to the first partition (which is normally the only partition for AWS CloudHSM).

Reboot the appliance to start the service and create the links.

Test your output by using the Network HSM testing tool and entering:

# tmsh run sys crypto nethsm-test --hsm_partition_name=<partition-name>

If you do not specify hsm_partition_name then the first partition (which is normally the only partition for AWS CloudHSM) will be chosen.

Creating a key in a partition

To create a key in a partition, do the following:

On the Main tab, click

System

Certificate Management

Traffic Certificate Management

SSL Certificate List

. The New SSL Certificate screen opens.

Click

Create

. The New SSL Certificate screen opens.

In the

Name

field, type the name of the new SSL certificate.

In the

Common Name

field, type the common name of the certificate. For example,

nethsm_ecdsa

From the

NetHSM Partition

list, select

Default Partition

Click

Finished

You can choose other partitions when you have multiple tokens or slots configured on your Network HSM that you use for keys.

Checking the partition for the key

To check the partition for the new key, do the following:

On the Main tab, click

System

Certificate Management

Traffic Certificate Management

SSL Certificate List

. The New SSL Certificate screen opens.

Select the newly created SSL certificate name.

Select the

Key

tab (if necessary) to check the partition for the key properties (such as name, key type, key ID, ect.).

Checking the service status

To check the service status, do the following:

On the Main tab, click

System

Services

Services List

. The Service List screen opens.

Locate the

Service

name (for example, pkcs11d) and view the History information.

Click

Start

Stop

, or

Restart

as necessary.

Setting up Equinix SmartKey HSM client installation and configuration

Create and set up your Equinix SmartKey HSM account by following the SmartKey Getting Started information.

Create the group and application as noted in the SmartKey instructions.

Make note of the API key after creating the application. The API key information can be useful later.

Installing the clients

Install the clients by following the SmartKey developer’s guide instructions while logged into the BIG-IP as root.

Use the 2.9.804 client instead of the client linked in the SmartKey instructions.

After installing the RPM package, the installed RMP package name may change from

rpm -i smartkey-pkcs11-2.9.804-0.x86_64.rpm

rpm -q -l fortanix-pkcs11-2.9.804-0.x86_64.rpm

. If you are attempting to remove the package, search for it using the possible naming options noted here.

Adding the library path and configuring partitions

To add your SmartKey HSM library to the BIG-IP and configure the partitions, perform either the UI screen or CLI to accomplish the task.

On the Main tab, click

System

Certificate Management

External HSM

. The External HSM screen opens.

From the

Vendor

list, select

Auto

In the

PKCS11 Library Path

field, type the following:

/opt/fortanix/pkcs11/fortanix_pkcs11.so

In the

Partition List

section, add the following details:

In the

Name

field, type

fortanix

(case sensitive).

If you type

auto

in the

Name

field, the first available partition will be selected.

In the Password field, type the <

API Key

The user name and password are based on the Cryptographic user created earlier.

Click

Add

to add as many partitions as necessary.

To edit any existing partition, select the partition and click

Edit

To delete any existing partition, select the partition and click

Delete

To test any existing partition, select a partition and click

Test

If you clicked

Test

, review the Test Output to make sure your details are accurate.

If the test does not pass, attempt to locate the problem and enable debug logging and run the test again for further details. The logs are writing to

/var/log/ltm

Make sure to reset debug logging to the prior setting before continuing.

Click

Update

If you are using the CLI, do the following:

Add your SmartKey HSM library to the BIG-IP by entering:

# tmsh create sys crypto fips external-hsm vendor auto pkcs11-lib-path /opt/fortanix/pkcs11/fortanix_pkcs11.so

Configure the partition, by entering:

# tmsh create sys crypto fips nethsm-partition <partition-name> password "<API Key>"

For <partition-name>, use "fortanix" as it is the default partition name for Equinix SmartKey.

Reboot the appliance to start the service and create the links.

Test your output by using the Network HSM testing tool and entering:

# tmsh run sys crypto nethsm-test --hsm_partition_name=<partition-name>

If you do not specify hsm_partition_name, then the first partition (which is normally the only partition for Equinix SmartKey) will be chosen.

By default, smartkey-client makes REST API calls to the SmartKey server at https://www.smartkey.io. To make calls to a different SmartKey server, set the environment variable FORTANIX_API_ENDPOINT (FORTANIX_API_ENDPOINT=<smartkey-server-url>).

Setting up SafeNet Data Protection on Demand (DPoD) HSM client installation and configuration

To set up your SafeNet DPoD HSM, you must first Install the software to the BIG-IP and complete the configuration steps. For additional SafeNet/Gemalto set up information, follow the documentation from their site listed below.

Prerequisites for setting up SafeNet DPoD HSM with BIG-IP system

You have obtained a SafeNet DPoD account with the HSM on Demand setup-<servicename>.zip file and password for the NetHSM partition.

You have received your new registration keys.

You have obtained a license for BIG-IP 15.1.0.

You have properly licensed the BIG-IP with the NetHSM add-on.

Configuring the BIG-IP for SafeNet DPoD

To configure the BIG-IP for SafeNet DPoD, perform the following steps:

On the Main tab, select

System

License

Review the

Summary

information and locate the

External Interface and Network HSM

in the

Active Modules

field (for example, under Local Traffic Manager) for conformation

You are now ready to create a SafeNet DPoD account and install the zip file.

Installing the SafeNet DPoD.zip file

To install the SafeNet DPoD.zip file, perform the following steps:

To unzip the SafeNet DPoD.zip files after creating a directory (/shared/safenet/) and copying the setup files to the new directory, enter the following commands:

[root@bigip:Active:Standalone] safenet # unzip setup-f5_dpod_test2.zip
     Archive:  setup-f5_dpod_test2.zip
     inflating: server-certificate.pem
     inflating: partition-ca-certificate.pem
     inflating: partition-certificate.pem
     inflating: Chrystoki.conf
     inflating: crystoki-template.ini
     inflating: cvclient-min.tar
     inflating: cvclient-min.zip
     inflating: EULA.zip
    
[root@bigip:Active:Standalone] safenet # tar -xvf cvclient-min.tar
    bin/
    bin/64/
    bin/64/lunacm
    bin/64/ckdemo
    bin/64/multitoken
    bin/64/cmu
    etc/
    jsp/
    jsp/64/
    jsp/64/libLunaAPI.so
    jsp/LunaProvider.jar
    libs/
    libs/64/
    libs/64/libCryptoki2.so
    setenv

To create a

lunasa

directory and copy the DPoD client files into that directory, enter the following command:

# mkdir -p /shared/safenet/lunasa
# [root@bigip:Active:Standalone] safenet # cp -rf * /shared/safenet/lunasa/

To set the environment and generate the

Chrystoki.conf

configuration file, enter the following command:

# source ./setenv

To create a

lib

directory and move the crypto libraries into the created directory, enter the following commands:

# mkdir /shared/safenet/lunasa/lib
# mv /shared/safenet/lunasa/libs/64/libCryptoki2.so /shared/safenet/lunasa/lib
 
[root@bigip:Active:Standalone] safenet # mv libs/64/libCryptoki2.so /shared/safenet/lunasa/lib/.

To create a password file to store the partition password, enter the following command:

# touch /shared/safenet/lunasa/passfile
# pOiu12zx > passfile

This file is used for the password when GemEngine is called. For example, we are using

pOiu12zx

as the partition password.

Open and modify the

Chrystoki.conf

file.

To modify the

Chrystoki2

and

Misc

sections, enter the following commands:

Chrystoki2 = {
LibUNIX64 = /shared/safenet/lunasa/lib/libCryptoki2.so; 
}
Misc = {
  Apache = 0;
  PE1746Enabled = 1;
  ToolsDir = /usr/bin;                          
  RSAKeyGenMechRemap = 1;
}

To create a new

GemEngine

section, use the following values:

GemEngine = {
   EnableDsaGenKeyPair = 1;
   EnableRsaGenKeyPair = 1;
   DisablePublicCrypto = 1;
   EnableRsaSignVerify = 1;
   EnableLoadPubKey = 1;
   EnableLoadPrivKey = 1;
   DisableCheckFinalize = 1;
   DisableEcdsa = 1;
   DisableDsa = 0;
   DisableRand = 0;
   EngineInit = "f5dpod":0:0:passfile=/shared/safenet/lunasa/passfile;
   EnableLoginInit = 1;
   LibPath64 = /shared/safenet/lunasa/lib/libCryptoki2.so;
   LibPath = /shared/safenet/lunasa/lib/libCryptoki2.so;
}

To check if the paths are correctly set and the partition is accessible, run LunaCM by entering the following comand:

# /shared/safenet/lunasa/bin/64/lunacm

To create the soft links, enter the following commands:

# ln -sf /shared/safenet/lunasa /usr/lunasa
# ln -sf /shared/safenet/lunasa /usr/safenet/lunaclient
# ln -sf /shared/safenet/lunasa/Chrystoki.conf /etc/Chrystoki.conf
# ln -sf /shared/safenet/lunasa/lib/libCryptoki2.so /usr/lib/libCryptoki2_64.so
# ln -sf /shared/safenet/lunasa/lib/libCryptoki2.so /usr/lib/libCryptoki2.so

You may need to remount

/usr prior to mount -o remount,rw /usr

Restart the services to apply the changes by entering the following command:

# bigstart start pkcs11d
# bigstart restart tmm

You have now installed the SafeNet DPoD.zip file and are ready to set up an external HSM and netHSM partition on the BIG-IP.

Setting up an external HSM and Network HSM partition on the BIG-IP

To create an external HSM and Network HSM partition on the BIG-IP, do the following:

On the Main tab, select

System

Certificate Management

HSM Management

In the

PKCS11 Library Path

field, select the

/shared/safenet/lunasa/libs/64/libCryptoki2.so

library path.

In the

Partition List

field, do the following:

In the

Name

field, type a name (for example,

f5dpod

In the

Password

field, type the crypto officer password.

Click

Add

To test the partition list

Name

and

Password

, click

Test

. Results from the test will appear in the

Test Output

field.

Some tests may take up to, or over, a minute to show results.

If your test results show issues, you can turn on debug logging of PKCS11 with the following command:

tmsh modify sys db log.pkcs11d.level value Debug

. The log information will appear in

/var/log/ltm

Click

Update

You have now created an external HSM and Network HSM partition on the BIG-IP.

You can also set up an external HSM and nethsm-partition on the BIG-IP using the CLI:

tmsh create sys crypto fips external-hsm vendor auto pkcs11-lib-path /shared/safenet/lunasa/lib/libCryptoki2.so password pOiu12zx
create sys crypto fips nethsm-partition f5dpodTEST password pOiu12zx
 
[root@bigip:Active:Standalone] config # tmsh list sys crypto fips
sys crypto fips external-hsm {
    num-threads 20
    password $M$39$2g2pWUdT0f6INYhHJ1lZfQ==
    pkcs11-lib-path /shared/safenet/lunasa/lib/libCryptoki2.so
    vendor auto
}
sys crypto fips nethsm-partition f5dpodTEST {
    password $M$Pk$b099uPx3zSycJWdEBrazhw==
}

Logging in to the LunaCM to initialize the cryptographic officers (CO) user

To login to LunaCM and initialize the CO user, enter the following commands:

[root@bigip19:Active:Standalone] f5_dpod # /shared/safenet/lunasa/bin/64/lunacm
LunaCM v1.1.0-1044. Copyright (c) 2006-2017 SafeNet.
slot s
    Available HSMs:
 
e   Slot Id ->              3
    Label ->                                               
    Serial Number ->        1334047160562  
    Model ->                Cryptovisor7  
    Firmware Version ->     7.1.3
    CV Firmware Version ->  1.1.0
t   Configuration ->        Luna User Partition With SO (PW) Signing With Cloning Mode
    Slot Description ->     User Token Slot
 
 
    Current Slot Id: 3

Initializing the crypto user role

To initialize the crypto user role, perform the following steps.

To enter the slot ID, enter the following command:

lunacm:>slot set -slot 3

The

Current Slot ID

: 3 (Luna User Slot 7.1.3 (PW) Signing With Cloning Mode).

The

Command Result

: No Error.

To enter the partition information, enter the following command:

lunacm:>partition init -label f5dpodTEST

Type, and then re-type, the password for

Partition SO

You are now about to initialize the partition. All contents of the partition will be destroyed.

Type

proceed

to continue or type

quit

to stop the action.

If you proceed, type, and then re-type, the domain name.

If neither option

-domain

nor

-defaultdomain

was specified, enter one.

The

Command Result

: No Error.

Enter the following

Partition SO

command and then type the password:

lunacm:>role login -name

The

Command Result

: No Error.

Enter the following command and then type, and then re-type, the new password:

lunacm:>role init -name co

The

Command Result

: No Error.

Enter the following command and then type the existing and new passwords:

lunacm:>role changePW -name co

Type the existing password: ********

Type the new password: ********

Re-type the new password: ********

You have now initialized the partition.

Creating a Network HSM certificate and key

To create a Network HSM certificate and key to assign to the virtual server, follow the steps below.

Assumptions:

You have an HTTPS server available.

On the Main tab, select

System

Certificate Management

Traffic Certificate Management

and click

Create

In the

Name

field, type a name (for example,

my-fips

From the

Issuer

list, select

Self

for a self-signed certificate.

In the

Common Name

field, type a name.

In the

Key Properties

section, from the

Security Type

list, select

NetHSM

is only visible when NetHSM is licensed.

From the

NetHSM Partition

list, select the partition name you created earlier (for example,

f5dpod

Click

Finished

You can also check the key at the partition by entering the following commands:

lunacm:>ro login -n co
 
    enter password: ********
 
Command Result : No Error
 
lunacm:>par con
 
The 'Crypto Officer' is currently logged in.  Looking for objects accessible to the 'Crypto Officer'.
 
    Object list:
 
    Label:         rsa_19574___15ba2050
    Handle:        2156006992
    Object Type:   Private Key
    Object UID:    842b00000a0000012cbe0800
 
    Label:         ec_secp384r1_20117___28804c3f
    Handle:        746860604
    Object Type:   Private Key
    Object UID:    822b00000a0000012cbe0800
 
    Label:         ec_secp384r1_20117___28804c3f
    Handle:        408279569
    Object Type:   Public Key
    Object UID:    812b00000a0000012cbe0800
 
 
    Number of objects:  3
 
 
Command Result : No Error
 
lunacm:>

You have now created a Network HSM certificate and key.

Creating a Network HSM client SSL profile

To create a Network HSM client SSL profile that will use the newly created certificate and key, do the following:

On the Main tab, select

Local Traffic

Profiles

SSL

Client

and click

Create

In the

Name

field, type a name (for example,

my-fips-clientssl

From the

Parent Profile

list, select

clientssl

In the

Certificate Key Chain

field, select the

Custom

checkbox and click

Add

. The Add SSL Certificate Key Chain screen appears.

From the

Certificate

Key

, and

Chain

lists, select

my-fips

to set the values to your FIPS certificate.

Click

Add

Click

Finished

to create the new profile.

You have now created a Network HSM client SSL profile.

Assigning the new client SSL profile to a virtual server

To assign your new client SSL profile to your virtual server, do the following:

On the Main tab, select

Local Traffic

Virtual Servers

Virtual Server List

and click

Create

In the

Name

field, type a name.

In the

Destination Address/Mask

field, select

and type the address.

Specifies destination IP address information to which the virtual server sends traffic. Specify the IP address in CIDR format: address/prefix, where the prefix length is in bits: for example, for IPv4: 10.0.0.1/32 or 10.0.0.0/24, and for IPv6: ffe1::0020/64 or 2001:ed8:77b5:2:10:10:100:42/64. The defaults for DHCP are 255.255.255.255 (IPv4 Default) and ff02::1:2 (IPv6 Default). You can also select Other to specify another Destination Address.

In the

Service Port

field, select

and type the port information before selecting a port designation from the list.

Type a service port or select a type from the list. When you select a type from the list, the value in the

Service Port

box changes to reflect the associated default, which you can change.

In the

SSL Profile (Client)

field, select

my-fips-clientssl

from the

Available

list and move it to the

Selected

list.

Specifies the SSL profile for managing client-side SSL traffic. Use the Move buttons (<<) and (>>) to adjust profile use.

Click

Finished

You have now assigned your new client SSL profile to your virtual server.

Reviewing the new certificate

To review the new certificate when passing traffic via a browser, do the following:

Open a browser of your choice and pass traffic through your BIG-IP device.

View the certificate details for the name of your certificate’s common name.

Configuring the BIG-IP for SafeNet DPoD when using a High Availability pair

To configure your BIG-IP for SafeNet DPoD when using High Availability (HA) device pair, do the following:

Follow the manual installation process for the .zip file on both HA devices.

Create the external HSM on both devices.

This object is not configuration synchronized. The nethsm-partition object does, however, get synchronized.

Setting up Atos (Bull Trustway Proteccio) HSM client installation and configuration

The BIG-IP system can be configured to use the Bull Trustway Proteccio network HSM service, by Atos. Proteccio is a third-party network HSM service not sold by F5. Customers of Atos that own a license to Proteccio can configure the network HSM to work on the BIG-IP system.

To set up your Atos Proteccio HSM, refer to the support material provided by Bull Trustway Proteccio HSM at the Bull Atos Technologies Support On Line site.

Use the following information to install and configure your Atos Proteccio HSM.

Mounting the Atos Proteccio ISO

To mount the Atos Proteccio ISO to your local file system using the BIG-IP CLI, enter the following command:

mount -o loop /shared/rpms/Proteccio1.08.18_dec2017.iso /mnt/atos

Installing the Atos clients

To install the Atos Proteccio client, enter the following command:

cd /mnt/atos/Linux/
sh install.sh

Creating a local directory on your system

To create a local directory on your system for a configuration check, enter the following commands:

cd /shared/
mkdir proteccio
cd protecccio
cp /etc/proteccio/proteccio.rc ./
cat /shared/proteccio/proteccio.rc
chmod +w proteccio.rc
vi /shared/proteccio/proteccio.rc
[PROTECCIO]
IPaddr=193.251.82.208   
SSL=1                   
SrvCert=proteccio.crt
 
[CLIENT]
Mode=0
LoggingLevel=7
LogFile=my_log_file1.log
ClntKey=proteccio_client.key
ClntCert=proteccio_client.crt

Make sure to change the IP address with the one provided by Atos.

Make sure to change the SSL value to

Copying the certificate (CRT) files

To add the library path and configure the partitions, copy the CRT files to

/shared/proteccio/

and enter the following command:

[root@localhost:Active:Standalone] proteccio # ls
client19.crt  client19.p12  client19.pem  my_log_file1.log  my_log_file.log  proteccio_client.crt  proteccio_client.key  proteccio.crt  proteccio.rc

Adding the library path and configuring partitions

To add your Atos HSM library to the BIG-IP and configure the partitions, perform the steps provided in the UI screen or the CLI.

On the Main tab, click

System

Certificate Management

HSM Management

External HSM

. The External HSM screen opens.

From the

Vendor

list, select

Auto

In the

PKCS11 Library Path

field, type the following:

/usr/lib64/libnethsm.so

See the ATOS Virtual HSM installation and user guide for the NetHSM library path.

In the Partition List section, add the following details:

In the

Name

field, type

proteccio

(case sensitive).

In the

Password

field, type the <

API Key

If you type

auto

in the

Name

field, the first available partition will be selected.

The user name and password are based on the Cryptographic user created earlier.

Click

Add

to add as many partitions as necessary.

To edit any existing partition, select the partition and click

Edit

To delete any existing partition, select the partition and click

Delete

To test any existing partition, select a partition and click

Test

If you clicked Test, review the Test Output to make sure your details are accurate.

If the test does not pass, attempt to locate the problem and enable debug logging and run the test again for further details. The logs are writing to

/var/log/ltm

Make sure to reset debug logging to the prior setting before continuing.

Click

Update

If you are using the CLI, do the following:

To add your CloudHSM library to the BIG-IP, enter the following command:

# tmsh create sys crypto fips external-hsm vendor auto pkcs11-lib-path/usr/lib64/libnethsm.so.

To configure the partition, enter the following command:

# tmsh create sys crypto fips nethsm-partition <partition-name> password "<partition-password"

For

<partition-name>

, use the partition name given by ATOS (for example,

HSMV_6

). F5 recommends not using the name "auto" since the first partition may not always be available.

Reboot the appliance to restart the service and create the links.

To test your output, use the Network HSM testing tool at

/shared/proteccio/

, enter the following command:

# tmsh run sys crypto nethsm-test --hsm_partition_name=<partition-name>

If you do not specify hsm_partition_name, then the first partition (which is normally the only partition for Atos) will be chosen.

Copy all of the files under

cp /shared/proteccio/*

/etc/proteccio/

To restart pkcs11d and check its health, enter the following command:

bigstart restart pkcs11d
bigstart status pkcs11d

To run a full validation test, enter the following command:

tmsh run sys crypto nethsm-test

To create a key from pkcs11d for review, enter the following command:

tmsh create sys crypto key test_key security-type nethsm
tmsh list sys crypto key

Setting up the external HSM and nethsm-partition on the BIG-IP system

To set up the external HSM and nethsm-partition on the BIG-IP system, enter the following commands after obtaining the new partition from the vendor:

tmsh create sys crypto fips external-hsm vendor auto pkcs11-lib-path "/usr/lib64/libnethsm.so" password kLG7j9p4
tmsh create sys crypto fips nethsm-partition 'HSMV1' password kLG7j9p4
 
[root@bigip:Active:Standalone] tmp # tmsh list sys crypto fips
sys crypto fips external-hsm {
    num-threads 20
    password $M$Zc$Mjpis3OHylCBsOReoHgMPQ==
    pkcs11-lib-path /usr/lib64/libnethsm.so
    vendor auto
}
sys crypto fips nethsm-partition HSMV1 {
    password $M$1v$5T68lhIsqTPZNa0I36/OEQ==
}

Setting up IBM HPCS client installation and configuration

The BIG-IP system can be configured to use the IBM Cloud Hyper Protect Crypto Services (HPCS). HPCS is a third-party key management service and cloud HSM based on IBM cloud not sold by F5. Customers of IBM that own a license to HPCS can configure the cloud HSM to manage encryption keys and perform cryptographic operations that work with the BIG-IP system.

Prerequisites for setting up IBM HPCS with BIG-IP system

This section details the pre-requisites required before setting up IBM HPCS with the BIG-IP system:

Get the following information from the IBM portal before proceeding with the configuration:

You have an enterprise PKCS #11 endpoint URL starting from

ep11

and the port number.

You have the ID of your Hyper Protect Crypto Services instance.

You have tokenspaceID for the private and public keystore.

You have generated the anonymous user API key.

You have generated the normal user API key.

For setting up your HPCS service, follow the Getting started with IBM Cloud Hyper Protect Crypto Services instructions.

For setting up PKCS #11 API users, follow the Setting up PKCS #11 API user types instructions.

Always enable the

CKA_MODIFIABLE

attribute as

TRUE

while generating RSA and EC keys from the IBM portal.

The link takes you to a resource outside of AskF5. The referred documents may have been removed without our knowledge.

Download the latest PKCS #11 library and the sample YAML file from https://github.com/IBM-Cloud/hpcs-pkcs11/releases. You may have downloaded the library file (

pkcs11-grep11.so

) in the directory

/shared/tmp/IBM-HPCS/

Move the downloaded configuration file (

grep11client.yaml

) in the

/etc/ep11client

directory (for example, /etc/ep11client/grep11client.yaml). Create the

/etc/ep11client

directory if it does not exist.

Modifying the HPCS configuration file (grep11client.yaml)

Modify the configuration file

grep11client.yaml

by editing the grep11connection attributes with the following values gathered in the pre-requisites:

Address

: Replace

hpcs_ep11_server_address

address

with the Enterprise PKCS #11 endpoint URL.

Port

: Update

port

with the Enterprise PKCS #11 endpoint port number.

tokenspaceID

: Update

tokenspaceID

for both normal and anonymous users. Under the normal user, the

tokenspaceID

identifies the private keystore, and under the anonymous user, it identifies the public keystore.

apikey

: Update

apikey

with the anonymous user API key you created previously.

Adding the library path and configuring partitions

To configure your BIG-IP with your newly configured and activated IBM HSM, add the library path and configure partitions. You can either use the BIG-IP UI screen or CLI to accomplish the task.

Using BIG-IP UI

On the Main tab, click

System

Certificate Management

External HSM

. The External HSM screen opens.

From the

Vendor

list, select

Auto

In the

PKCS11 Library Path

field, type the following:

/opt/ibmhsm/lib/pkcs11-grep11.so

In the

Partition List

section, add the following details:

In the

Name

field, type

auto

(case sensitive).

If you type

auto

in the

Name

field, the first available partition will be selected.

In the Password field, type the <

CU user name

>:<

password

Click

Add

to add as many partitions as necessary.

To edit any existing partition, select the partition and click

Edit

To delete any existing partition, select the partition and click

Delete

To test any existing partition, select a partition and click

Test

If you selected

Test

, review the test output to ensure your details are accurate.

If the test does not pass, attempt to locate the problem and enable debug logging and rerun the test for further details.

To enable debug logging and capture trace data, use the following command:

export EP11CLIENT_LOGGING_LOGLEVEL=trace

The log information will appear in

/var/log/grep11-pkcs11.log

Make sure to reset debug logging to the prior setting before continuing.

Click

Update

Using Command Line Interface

If you are using the CLI, do the following:

Add your IBM HPCS library to the BIG-IP by using the following command:

# tmsh create sys crypto fips external-hsm vendor auto pkcs11-lib-path /opt/ibmhsm/lib/pkcs11-grep11.so

Configure the partition by using the following command:

# tmsh create sys crypto fips nethsm-partition auto password <Normal user API key>

Here, we used "auto" to point to the first partition.

Reboot the appliance to start the service and create the links.

Test your output by using the Network HSM testing tool and entering:

# tmsh run sys crypto nethsm-test --hsm_partition_name=auto

You must always restart the pkcs11d daemon on the BIG-IP system before importing a new RSA/EC key generated on the IBM portal.

Subscriptions

Product Usage

Trials

Registration Keys

Downloads

Applies To:

BIG-IP APM

BIG-IP LTM

BIG-IP AFM

BIG-IP DNS

BIG-IP ASM

Setting Up the Network HSM

Overview: Setting up the Network HSM

Prerequisites for setting up Network HSM with BIG-IP system

Supported Versions

Setting up Network HSM Client Installation and Configuration

Task Summary for Amazon CloudHSM and Equinix SmartKey HSM

Setting up Amazon CloudHSM client installation and configuration

Creating a cryptographic user

Installing the clients

Configuring and activating the software

Configure the BIG-IP

Adding the HSM service to the BIG-IP startup scripts

Adding the library path and configuring partitions

Creating a key in a partition

Checking the partition for the key

Checking the service status

Setting up Equinix SmartKey HSM client installation and configuration

Installing the clients

Adding the library path and configuring partitions

Setting up SafeNet Data Protection on Demand (DPoD) HSM client installation and configuration

Prerequisites for setting up SafeNet DPoD HSM with BIG-IP system

Configuring the BIG-IP for SafeNet DPoD

Installing the SafeNet DPoD.zip file

Setting up an external HSM and Network HSM partition on the BIG-IP

Logging in to the LunaCM to initialize the cryptographic officers (CO) user

Initializing the crypto user role

Creating a Network HSM certificate and key

Creating a Network HSM client SSL profile

Assigning the new client SSL profile to a virtual server

Reviewing the new certificate

Configuring the BIG-IP for SafeNet DPoD when using a High Availability pair

Setting up Atos (Bull Trustway Proteccio) HSM client installation and configuration

Mounting the Atos Proteccio ISO

Installing the Atos clients

Creating a local directory on your system

Copying the certificate (CRT) files

Adding the library path and configuring partitions

Setting up the external HSM and nethsm-partition on the BIG-IP system

Setting up IBM HPCS client installation and configuration

Prerequisites for setting up IBM HPCS with BIG-IP system

Modifying the HPCS configuration file (grep11client.yaml)

Adding the library path and configuring partitions

Have a Question?

Follow Us

About F5

Education

F5 Sites

Support Tasks