F5 Logo MyF5
Search
  1. MyF5 Home
  2. Knowledge Centers
  3. BIG-IP LTM
  4. BIG-IP System and SafeNet Luna SA HSM: Implementations
  5. Manually Setting Up the SafeNet Luna HSM with BIG-IP Systems
Manual Chapter : Manually Setting Up the SafeNet Luna HSM with BIG-IP Systems

Applies To:

Show Versions Show Versions

BIG-IP AAM

  • 11.6.5, 11.6.4, 11.6.3, 11.6.2, 11.6.1

BIG-IP APM

  • 11.6.5, 11.6.4, 11.6.3, 11.6.2, 11.6.1

BIG-IP GTM

  • 11.6.5, 11.6.4, 11.6.3, 11.6.2, 11.6.1

BIG-IP LTM

  • 11.6.5, 11.6.4, 11.6.3, 11.6.2, 11.6.1

BIG-IP AFM

  • 11.6.5, 11.6.4, 11.6.3, 11.6.2, 11.6.1

BIG-IP ASM

  • 11.6.5, 11.6.4, 11.6.3, 11.6.2, 11.6.1
Manual Chapter
Table of Contents | << Previous Chapter | Next Chapter >>

Overview: Manually setting up the SafeNet Luna SA HSM with BIG-IP systems

The SafeNet Luna SA HSM is an external hardware security module that is available for use with BIG-IP® systems. Because it is network-based, you can use the SafeNet solution with all BIG-IP platforms, including VIPRION® Series chassis and appliances and BIG-IP Virtual Edition (VE). You can also configure multiple HSMs as an HA (high availability) group to use with BIG-IP systems. Typically, you would use the script to set up the SafeNet Luna SA HSM. However, in cases where the installation script does not support your network configuration, you can install one or more HSMs manually. For a VIPRION Series chassis, this procedure would require manual setup on the additional blades.

Note: The BIG-IP system does not support the SafeNet Luna SA HSM in Appliance mode.

Only RSA-based cipher suites use the network HSM. After installation on the BIG-IP system, the SafeNet Luna SA HSM is compatible with Access Policy Manager® and Application Security Manager™, without additional configuration steps.

For information about using the iControl® interface to configure the Luna SA HSM with BIG-IP systems, consult the F5 DevCentral site (https://devcentral.f5.com/icontrol/).

For additional information about using the Luna SA HSM, contact SafeNet Technical Support (http://www.safenet-inc.com/technical-support/).

Prerequisites for setting up SafeNet Luna SA HSM with BIG-IP systems

Before you can use SafeNet Luna SA HSM with the BIG-IP® system, you must make sure that:

  • The SafeNet device is installed on your network.
  • The SafeNet device and the BIG-IP system can communicate with each other.
  • The SafeNet device has a virtual HSM (HSM Partition) defined before you install the client software on the BIG-IP system.
  • The BIG-IP system is licensed for external interface and network HSM.

Additionally, before you begin the installation process, make sure that you have access to:

  • The Luna SA Client software (Version 5.1 or 5.2). For VIPRION® system support or configuring multiple HSMs as an HA group, you must use Version 5.2.
  • The Luna SA Customer Documentation
Note: If you install the Luna SA HSM (external HSM) on a system with a FIPS card (internal HSM) installed, the Luna SA HSM takes precedence. You cannot use the SafeNet Luna SA HSM on a BIG-IP system that is running another external HSM.

Task summary

The implementation process for a manual installation involves preparation of the SafeNet device and the BIG-IP® system, followed by key/certificate management and creation of a client SSL profile to use the key and certificate. If you are setting up multiple HSMs configured as an HA group, you repeat a subset of the manual installation steps for each additional HSM, and then create an HA group. You can generate SafeNet HSM protected keys and corresponding CSR and certificate using either tmsh (recommended) or the fipskey.nethsm utility.

Task list

Preparing to manually install the Luna SA client on the BIG-IP system

Before you can set up the SafeNet Luna SA client software on a BIG-IP® system, you must obtain a valid SafeNet Luna SA client license.

To use the Luna SA HSM, you need to obtain the software tarball from SafeNet, and install the Luna SA client software onto the BIG-IP system.
  1. Log in to the SafeNet Support portal.
    https://serviceportal.safenet-inc.com
  2. Download the appropriate document, using the download password F5Clientdownload!.
    • LunaSA Client v5.1 for F5, Document Id:DOW3519
    • LunaSA Client v5.2.1-6 for F5, Document Id:DOW3520
    Note: For supporting the VIPRION® system or configuring multiple HSMs as an HA group, you must use version 5.2.x with this release.
  3. Log in to the command-line interface of the BIG-IP system using an account with administrator privileges.
  4. Create a directory under /shared named safenet_install.
    mkdir /shared/safenet_install
  5. Copy the software tarball to /shared/safenet_install.

Manually installing and registering the Luna SA client

You install and register the Luna SA client so that you can use the Luna SA device with the BIG-IP® system. You provide the passwords for your Luna SA device during the installation process. You can use this procedure to install and register the Luna SA client on the BIG-IP system, either for a single HSM or multiple HSMs configured as an HA group.
  1. If you are installing the Luna SA client on a VIPRION system, and you are using the management network to connect to the HSM, disable ip check on the HSM. If you are not installing on a VIPRION system, or you are using a self IP address to communicate with the HSM, skip this step.
    tls ipcheck disable
    service restart ntls
    This step allows the same certificate to be used from multiple IP addresses, identifying multiple blades.
  2. Untar the image, and place the extracted files into appropriate directories, moving the extracted toolkit to the safenet path. 
                                  
tar -C /shared/safenet_install -xvr /shared/safenet_install/<lunasa tar file>
                    
mkdir -p /shared/safenet/toolkit
mv /shared/safenet_install/toolkit/* /shared/safenet/toolkit
chmod 755 /shared/safenet/toolkit/*
  3. Set the write permission and create softlinks for the /usr path. 
                                  
mount -o remount,rw /usr   mkdir -p /shared/safenet/lunasa
rm -rf /usr/lunasa              
ln -sf /shared/safenet/lunasa /usr/lunasa
 
rm -rf /usr/safenet/    
mkdir -p /usr/safenet/
ln -sf /shared/safenet/lunasa /usr/safenet/lunaclient
  4. Install the SafeNet Luna SA package.
    sh /shared/safenet_install/linux/x86/64/install.sh
  5. Adjust the location and permission of the Chrystoki.conf file 
                                  
mv /etc/Chrystoki.conf /shared/safenet/lunasa/Chrystoki.conf
restorecon /shared/safenet/lunasa/Chrystoki.conf
chmod 644 /shared/safenet/lunasa/Chrystoki.conf
  6. Add these entries to the file /shared/safenet/lunasa/Chrystoki.conf, if the entries do not already exist: 
                                  
Misc = {
    Apache = 0;
    PE1746Enabled=1;
}  
 
EngineLunaCA3 = {
    DisableCheckFinalize = 1;
    DisableEcdsa = 0;
    DisableDsa = 0;
    DisableRand = 0;
    EngineInit = 1:10:11;
    LibPath64 = /usr/lunasa/lib/libCryptoki2_64.so;
    LibPath = /usr/lunasa/lib/libCryptoki2.so;
}
  7. Set these softlinks: 
                                  
ln -sf /shared/safenet/lunasa/Chrystoki.conf /etc/Chrystoki.conf     
ln -sf /shared/safenet/lunasa/lib/libCryptoki2_64.so /usr/lib/libCryptoki2_64.so
  8. Fetch the server certificate from the SafeNet Luna SA HSM. 
                                  
scp <hsm_username>@<hsm_ip_addr>:server.pem /usr/lunasa/bin/server_<hsm_ip_addr>.pem
  9. Create the client certificate.
    /usr/lunasa/bin/vtl createCert -n <BIG-IP IP address>
  10. Send the client certificate to the SafeNet Luna SA HSM. 
                                  
scp /usr/lunasa/cert/client/<BIG-IP IP address>.pem <hsm_username>@<hsm_ip_addr>:
  11. Clean up the old server information (if any), and add the server information to the client. 
                                  
/usr/lunasa/bin/vtl deleteServer -n <hsm_ip_addr>
rm -f /usr/lunasa/cert/server/CAFile.pem
rm -f /usr/lunasa/cert/server/<hsm_ip_addr>Cert.pem
  12. Add the server to the list of servers. 
                                  
/usr/lunasa/bin/vtl addServer -n <hsm_ip_addr> -c /usr/lunasa/bin/server_<hsm_ip_addr>.pem
  13. On the SafeNet Luna SA HSM device, register a client name that has the IP address of the BIG-IP system, and assign a partition for the client. 
                                  
lunash:> client register -client <clientname> [-hostname <resolvable hostname>] [-ip <client IP address>]
lunash:> client assignPartition -client <clientname> -partition <partitionname>
    For additional details, refer to the SafeNet documentation.
  14. (HA only) If you are setting up multiple HSMs configured as an HA group, repeat these steps for each SafeNet Luna SA HSM device.
    1. Fetch the server certificate from the Safenet Luna SA HSM. 
                                          
scp <hsm_username>@<hsm_ip_addr>:server.pem /usr/lunasa/bin/server_<hsm_ip_addr>.pem
    2. Send the client certificate to the SafeNet Luna SA HSM. 
                                          
scp /usr/lunasa/cert/client/<BIG-IP IP address>.pem <hsm_username>@<hsm_ip_addr>:
    3. Clean up the old server information (if any), and add the server information to the client. 
                                          
/usr/lunasa/bin/vtl deleteServer -n <hsm_ip_addr>
rm -f /usr/lunasa/cert/server/<hsm_ip_addr>Cert.pem
    4. Add the server to the list of servers. 
                                          
/usr/lunasa/bin/vtl addServer -n <hsm_ip_addr> -c /usr/lunasa/bin/server_<hsm_ip_addr>.pem
    5. On the SafeNet Luna SA HSM device, register a client name that has the IP address of the BIG-IP system, and assign a partition for the client. 
                                          
lunash:> client register -client <clientname> [-hostname <resolvable hostname>] [-ip <client IP address>]
lunash:> client assignPartition -client <clientname> -partition <partitionname>
      For additional details, refer to the SafeNet documentation.
      This example shows the list of slots after the BIG-IP system is securely connected to two SafeNet Luna SA HSMs.
                                          
[root@test:Active:Standalone] shared # vtl listSlots
Number of slots: 5                                   

The following slots were found:

Slot #    Description          Label                           Serial #   Status
========= ==================== =============================== ========== ============
slot #1   LunaNet Slot         test1                           153124004  Present     
slot #2   LunaNet Slot         test1                           153560010  Present     
slot #3    -                    -                                -        Not present 
slot #4    -                    -                                -        Not present
slot #5    -                    -                                -        Not present
  15. (HA only) If you are setting up multiple HSMs configured as an HA group, after you have securely connected all the SafeNet Luna SA HSMs, create an HA group, and add all the HSMs into the group.
    These commands use serial numbers from the previous example.
                                  
/usr/lunasa/bin/vtl haAdmin newGroup -serialNum 153124004 -label ha1
                  
/usr/lunasa/bin/vtl haAdmin addMember -group ha1 -serialNum 153560010
                  
/usr/lunasa/bin/vtl haAdmin HAOnly –enable
  16. (HA only) Verify that the HA group configuration was successful.
    /usr/lunasa/bin/vtl listSlots
  17. Close and open the session for the SafeNet Luna SA HSM in slot #1. 
                                  
/shared/safenet/toolkit/sautil -v -s 1 -i 10:11 -c
/shared/safenet/toolkit/sautil -v -s 1 -i 10:11 -o -p <hsm_partition_password>
  18. Install the pkcs11d service on the BIG-IP system. 
                                  
bigstart add pkcs11d    
bigstart stop pkcs11d   
bigstart add --default pkcs11d
  19. Revert the read-write permission.
    mount -o remount,ro /usr
  20. Set the vendor name to SafeNet.
    fipskey.nethsm --hsm=Safenet
  21. Configure the vendor name and partition password in tmsh. 
                                  
tmsh create sys crypto fips external-hsm vendor safenet password <Safenet partition password>
  22. To adjust the number of threads, you can modify the configuration, as shown.
    tmsh modify sys crypto fips external-hsm num-threads <integer>
    The default value for the number of threads is 20.
  23. Restart the daemons.
    1. Restart the pkcs11d service.
      bigstart restart pkcs11d
    2. Restart tmm.
      bigstart restart tmm

Generating a key/certificate using tmsh

You can use the Traffic Management Shell (tmsh) to generate a key and certificate.
  1. Log in to the command-line interface of the system using an account with administrator privileges.
  2. Open the Traffic Management Shell (tmsh).
    tmsh
  3. Generate the key.
    create sys crypto key <key_name> gen-certificate common-name <cert_name> security-type nethsm

    This example generates an external HSM key named test_key and a certificate named test_safenet.com with the security type of nethsm:

    create sys crypto key test_key gen-certificate common-name test_safenet.com security-type nethsm
  4. Verify that the key was created.
    list sys crypto key siterequest.key
    Information about the key displays:
                                  
sys crypto key siterequest.key {
key-size 2048
key-type rsa-private
security-type nethsm
}
When you generate a key/certificate using tmsh, the system also creates a local key, which points to the HSM key, residing in the HSM.

Generating a key/certificate using the fipskey.nethsm utility

Before you generate a key/certificate, make sure that the SafeNet Luna SA client is running on the BIG-IP® system.
You can use the fipskey.nethsm utility to generate private keys and self-signed certificates on the BIG-IP system.
  1. Display the available options.
    fipskey.nethsm --help
  2. Generate the key, using any options you need.
    fipskey.nethsm --genkey -o <output_file>
    This example generates the three files that follow:
    fipskey.nethsm --genkey -o siterequest
    • /config/ssl/ssl.key/siterequest.key
    • /config/ssl/ssl.csr/siterequest.csr
    • /config/ssl/ssl.crt/siterequest.crt
    The key is saved in /config/ssl/ssl.key/<output_file>.key. The certificate request is saved in /config/ssl/ssl.csr/<output_file>.csr. The self-signed certificate is saved in /config/ssl/ssl.crt/<output_file>.crt.
After you generate keys and certificates, you need to add the local key to the BIG-IP configuration using tmsh. The local key points to the HSM key, which resides in the HSM.

Adding the SafeNet local key to the BIG-IP system configuration

You can use the Traffic Management Shell (tmsh) to add the SafeNet local key, which was created on the BIG-IP® system when you generated a key/certificate using the fipskey.nethsm utility. The local key points to the HSM key.
  1. Log in to the command-line interface of the system using an account with administrator privileges.
  2. Open the Traffic Management Shell (tmsh).
    tmsh
  3. Add the key.
    install sys crypto key key_object_name>< from-local-file <keyname>
    This example adds a local key named my_key.key from a local key file stored in the /config/ssl/ssl.key/ directory: install sys crypto key my_key.key from-local-file /config/ssl/ssl.key/my_key.key

Adding certificates using tmsh

You can use the Traffic Management Shell (tmsh) to add existing certificates to the BIG-IP® system configuration.
  1. Log in to the command-line interface of the system using an account with administrator privileges.
  2. Open the Traffic Management Shell (tmsh).
    tmsh
  3. Add the certificate.
    install sys crypto cert <cert_object_name> from-local-file <path_to_cert_file>

    This example loads the certificate named my_key.crt from a local certificate file stored in the /config/ssl/ssl.crt/ directory:

    install sys crypto cert my_key.crt from-local-file /config/ssl/ssl.crt/my_key.crt

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

After you have added the external HSM key and certificate to the BIG-IP® system configuration, you can use the key and certificate as part of a client SSL profile. This task describes using the browser interface. Alternatively, you can use the Traffic Management Shell (tmsh) command-line utility.
  1. On the Main tab, click Local Traffic > Profiles > SSL > Client .
    The Client screen opens.
  2. Click Create.
    The New Client SSL Profile screen opens.
  3. In the Name field, type a name for the profile.
  4. From the Parent Profile list, select clientssl.
  5. From the Configuration list, select Advanced.
    This selection makes it possible for you to modify additional default settings.
  6. For the Configuration area, select the Custom check box.
    The settings in the Configuration area become available for modification.
  7. Using the Certificate Key Chain setting, specify one or more certificate key chains:
    1. From the Certificate list, select the name of a certificate that you imported.
    2. From the Key list, select the name of the key that you imported.
    3. From the Chain list, select the chain that you want to include in the certificate key chain.
    4. Click Add.
  8. Click Finished.
After you have created the client SSL profile, you must assign the profile to a virtual server, so that the virtual server can process SSL traffic according to the specified profile settings.
Table of Contents | << Previous Chapter | Next Chapter >>
Contact Support Contact Support

Have a Question?

Support and Sales >

About F5

Education

F5 Sites

Support Tasks




©2023 F5 Networks, Inc. All rights reserved.


Trademarks Policies Privacy California Privacy Do Not Sell My Personal Information