F5 Big-IP Systems

1Set up Luna HSM

2Set up F5 Big-IP

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

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

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

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

5Run 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

Note

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

Note

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.

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

Note

This integration has been certified on the RHEL platform.

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

3Extract 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

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

source ./setenv

Note

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

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

Note

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.

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

Note

This process is only supported with Luna Client 7.1.

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

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

mkdir /shared/safenet_install

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

5Install 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]

Note

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.

6Complete 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]

Note

Changing the number of threads can impact performance.

7Set 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

1Apply 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

2Configure 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

3Configure 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

4Add 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

Note

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.

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

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

3Generate the key:

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

Note

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

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

list sys crypto key [key_name].key

Note

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

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

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

2Click on Create to begin the certificate creation process.

3Fill 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.

4Click on Finished to complete the process.

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

2Click 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.

3Click Finished to generate the certificate signing request.

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

5Follow CA instructions for submission.

6After submission, click Finished to complete the process.

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

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

3Enter a Name for the profile.

4Choose clientssl from the Parent Profile list.

5Select Advanced from the Configuration list to access additional settings.

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

7Under 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.

8Click Finished to complete the profile setup.

Note

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.

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

2Under Import Type, choose Key.

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

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

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

6Click Import to finalize the import process.

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

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

3Click Delete.