F5 Big-IP Systems

Set up Luna HSM

Set up F5 Big-IP

Ensure that the HSM is set up, initialized, provisioned, and ready for deployment. For more information, refer to Luna HSM documentation.

Create a partition that will be later on used by Red Hat Certificate System.

Create and exchange certificate between the Luna Network HSM and client system. Register client and assign partition to create an NTLS connection.

Initialize Crypto Officer and Crypto User roles for the registered partition.

Run the following command to verify that the partition has been successfully registered and configured:

/usr/safenet/lunaclient/bin/lunacm

Upon successful execution, you should observe an output similar to the example provided below:

lunacm.exe (64-bit) v10.7.0-255. Copyright (c) 2023 Thales Group. All rights reserved. 

Available HSMs:

Slot Id ->                           0
Label ->                             bigip
Serial Number ->                     1280780175877
Model ->                             LunaSA 7.3.0
Firmware Version ->                  7.3.0
Configuration Cloning Mode ->        Luna User Partition With SO (PW) Key Export With Cloning Mode
Slot Description ->                  Net Token Slot
FM HW Status ->                      FM Ready

Refer to Luna HSM documentation for detailed steps on creating NTLS connection, initializing the partitions, and assigning various user roles.

To ensure the correct configuration of a PED-based Luna HSM, make sure that the ProtectedAuthenticationPathFlagStatus is set to 1 within the Misc section of the Chrystoki.conf file.

Transfer the downloaded .zip file to your client workstation using pscp, scp, or other secure means

This integration has been certified on the RHEL platform.

Extract the .zip file into a directory on your client workstation.

Extract or untar the appropriate client package for your operating system. Do not extract to a new subdirectory; place the files in the client install directory.

tar -xvf cvclient-min.tar

Run the setenv script to create a new configuration file containing information required by the Luna Cloud HSM service.

source ./setenv

To add the configuration to an already installed UC client, use the –addcloudhsm option when running the setenv script.

Run the LunaCM utility and verify that the Cloud HSM service is listed.

If your organization requires non-FIPS algorithms for your operations, ensure that the Allow non-FIPS approved algorithms check box is checked. For more information, refer to Supported Mechanisms.

Obtain Luna Client Software: Obtain the Luna Client software tarball from Thales Support.

This process is only supported with Luna Client 7.1.

Access the Command-Line Interface (CLI): Log in to the command-line interface of the BIG-IP system using an account with administrator privileges.

Create Directory for Installation: Create a directory named safenet_install under the /shared directory.

mkdir /shared/safenet_install

Copy Luna Client Software: Copy the Luna Client software tarball to the /shared/safenet_install directory.

Install and Register Luna Client:

• Log in to the command-line interface of the BIG-IP system using an account with administrator privileges.

• If not installing on a VIPRION system or using a self IP address to communicate with the HSM, disable the IP check on the HSM using Luna Shell (LunaSH).

ntls ipcheck disable
service restart ntls

• Install and register the Luna client on the BIG-IP system using the provided parameters.

nethsm-safenet-install.sh --hsm_ip_addr=[luna_sa_device_IP_address] --image=[Luna_x.x_Client_Software.tar]

Replace [luna_sa_device_IP_address] with the IP address of your Luna Network HSM and [Luna_x.x_Client_Software.tar] with the actual software filename.

• During installation, the system will prompt for Luna SA admin password and partition password. Initialize the partition and CO/CU user roles using root before entering the password. After initialization, enter the CO password and press Enter.

• If setting up an HA group, use the same password for all HA members.

• If using multiple HSMs as an HA group, specify the parameters accordingly.

Complete Additional Configurations:

• Install all components when prompted during the installation process.

• Register your client IP address with the Luna Network HSM and assign the Luna Client to a previously defined HSM partition.

• To customize the number of threads used by the Luna Client software, run the following command before restarting the pkcs11d service:

tmsh sys crypto fips external-hsm num-threads [integer]

Changing the number of threads can impact performance.

Set up Luna Client on New Blades: After setting up the Luna Client on the primary blade of a VIPRION system, the system propagates the configuration to additional active blades. However, if you subsequently add a secondary blade, activate a disabled blade, or power on a powered-off blade, follow these steps to set up the Luna Client:

• Log in to the command-line interface of the system using an account with administrator privileges.

• Execute the following command on any new or re-activated secondary blade:

safenet-sync.sh [HSM partition password] -v 

• If you make the new blade a primary blade before running the synchronization script, you only need to run the regular client installation and registration procedure on the new primary blade:

nethsm-safenet-install.sh

Apply Patch for Luna Cloud HSM: If you're using Luna Cloud HSM, a patch must be installed to integrate it with F5 BIG-IP. Download the pkcs11d fix patch from the support portal (Doc ID: DOW0003489). Follow these steps to apply the patch:

• Before applying the patch, create a backup of the current pkcs11d configuration file by running the following command:

cp /usr/bin/pkcs11d /shared/pkcs11d_bk

• Download the pkcs11d fix patch and copy it to the /shared directory.

• Install the patch by running:

rpm -Uvh /shared/pkcs11d-14.1.0-0.0.118.x86_64.rpm --force

• Restart the pkcs11 service to apply the changes:

bigstart restart pkcs11d

Configure Luna Client with BIG-IP: Follow these steps to manually configure Luna Client with your BIG-IP system:

(i) Mount the /usr directory in read-write mode:

mount -o remount,rw /usr

(ii) Copy the gemengine library to /usr/lib64/openssl/engines:

cp ./builds/linux/rhel/64/1.0.2/libgem.so /usr/lib64/openssl/engines/

(iii) Create a lunasa directory /shared/safenet/lunasa:

mkdir -p /shared/safenet/lunasa

(iv) Create a symbolic link for the Luna Client to /shared/safenet/lunasa:

ln –sf /* /shared/safenet/lunasa

(v) Open and modify the Chrystoki.conf file located at /etc/Chrystoki.conffor the full client package or /shared/safenet/lunasa/Chrystoki.conf for the minimal client package.

(vi) Copy the modified Chrystoki.conf file if necessary:

cp /etc/Chrystoki.conf /shared/safenet/lunasa/

(vii) Adjust the permissions of the Chrystoki.conf file:

restorecon -R /shared/safenet
chmod 644 /shared/safenet/lunasa/Chrystoki.conf

(viii) If using the minimal client package, create a lib directory and copy the crypto libraries:

mkdir /shared/safenet/lunasa/lib
# cp /shared/safenet/lunasa/libs/64/libCryptoki2.so /shared/safenet/lunasa/lib/libCryptoki2_64.so

(ix) Create symbolic links for the Luna Crypto Library:

ln -sf /shared/safenet/lunasa/lib/libCryptoki2_64.so /usr/lib/libCryptoki2_64.so
ln -sf /shared/safenet/lunasa/lib/libCryptoki2_64.so /usr/lib/libCryptoki2.so

(x) Create a password file to store the partition password:

echo userpin1 > passfile

(xi) Install pkcs11d to the BIG-IP system:

bigstart add pkcs11d
bigstart stop pkcs11d
bigstart add --default pkcs11d

(xii) Remount the /usr directory in read-only mode:

mount -o remount,ro /usr

Configure SafeNet as External-HSM: Add SafeNet as an external-hsm vendor to the BIG-IP System. Follow these steps:

(i) Set the vendor name to SafeNet:

fipskey.nethsm --hsm=Safenet

(ii) Configure the vendor name and partition password in tmsh:

tmsh create sys crypto fips external-hsm vendor safenet password [partition_password]

(iii) Restart the services to apply the changes:

bigstart start pkcs11d
bigstart restart tmm

Add Partition Information to BIG-IP System: To add partition information to your BIG-IP system for key management, you have two options:

• Option 1: On the terminal, run:

tmsh -a create sys crypto fips nethsm-partition [partition_name] password [partition_password]

• Option 2: Add partition information using web console:

   (i) Open the web console https://[big-ip_address].

   (ii) Navigate to Main tab > System > Certificate Management > HSM Management > External HSM.

   (iii) Select Safenet from Vendor.

   (iv) Enter the partition name and password.

   (v) Click Add to add the partition.

   (vi) Click Update to save the changes.

• Restart the services: After completing Option 1 or Option 2, as appropriate, follow these steps to ensure that the changes take effect:

bigstart restart pkcs11d
bigstart restart tmm

After restarting the services, you can verify that the partition has been successfully added by running the following command: tmsh -a list sys crypto fips nethsm-partition.

Log in to your system's command-line interface using an account with administrator privileges.

Open the Traffic Management Shell by entering tmsh in the command line.

Generate the key:

create sys crypto key [key_name] gen-certificate common-name [cert_name] security-type nethsm nethsm-partition-name [partition_name]

Replace [key_name], [cert_name], and [partition_name] with your preferred names. Example: create sys crypto key test_key gen-certificate common-name test_safenet.com security-type nethsm nethsm-partition-name HA

Check that the key was successfully created by using the command:

list sys crypto key [key_name].key

Replace [key_name] with the name of your key. Example: list sys crypto key test_key.key

Confirm the key's details, including its ID, size, type, and security type.

Go to System > Certificate Management > Traffic Certificate Management on the main tab.

Click on Create to begin the certificate creation process.

Fill in certificate details:

• Name: Provide a unique name for the SSL certificate.

• Issuer: Choose Self from the dropdown list.

• Common Name: Enter the website's name (e.g., www.example.com).

• Division: Input your department name.

• Organization: Type your company name.

• Locality: Enter your city name.

• State or Province: Input your state or province name.

• Country: Select your country from the list.

• E-mail Address: Provide your email address.

• Lifetime: Specify the number of days for the certificate's validity (default is 365).

• Subject Alternative Name: Optionally, enter additional names for X509 extension purposes to protect multiple host names with a single SSL certificate.

• Security Type: Choose NetHSM from the dropdown list.

• Key Type: RSA is selected by default.

• Size: Select the desired size, in bits, for the key.

Click on Finished to complete the process.

Navigate to System > Certificate Management > Traffic Certificate Management on the main tab.

Click Create and fill in the following details:

• Name: Unique SSL certificate name.

• Issuer: Select Certificate Authority from the list.

• Common Name: Website name (e.g., www.example.com).

• Division, Organization, Locality, State or Province, Country, E-mail Address: Organization and contact details.

• Lifetime: Set validity period (default: 365 days).

• Subject Alternative Name: Optional additional host names.

• Challenge Password: Create a password and confirm it.

• Security Type: Choose NetHSM.

• Key Type and Size: Defaults to RSA, adjust as needed.

Click Finished to generate the certificate signing request.

Download the request: Copy the request text from the field, or download the request file.

Follow CA instructions for submission.

After submission, click Finished to complete the process.

Navigate to Local Traffic > Profiles > SSL > Client on the Main tab.

Click Create to begin setting up a new client SSL profile.

Enter a Name for the profile.

Choose clientssl from the Parent Profile list.

Select Advanced from the Configuration list to access additional settings.

Check the Custom box in the Configuration area to enable modification of default settings.

Under Certificate Key Chain, specify the certificate, key, and chain:

• Choose the appropriate certificate from the list.

• Select the corresponding key.

• Pick the desired chain.

• Click Add.

Click Finished to complete the profile setup.

After creating the client SSL profile, it's essential to assign it to a virtual server. This enables the virtual server to handle SSL traffic based on the specified profile settings.

Go to System > Certificate Management > Traffic Certificate Management > SSL Certificate List > Import on the Main tab to access the SSL Certificate/Key Source page.

Under Import Type, choose Key.

Select the Luna HSM key you wish to import, ensuring the key name matches the Luna HSM key label.

Choose Overwrite Existing from the Key Name dropdown menu to replace any existing key with the imported one.

Under Key Source, select From NetHSM (This option requires the External HSM license and SafeNet External HSM configuration).

Click Import to finalize the import process.

Navigate to System > Certificate Management > Traffic Certificate Management on the main tab.

Select the key you wish to delete from the SSL Certificate List.

Click Delete.