Citrix ADC
This document offers detailed guidance on integrating Citrix ADC with Luna HSM devices or Luna Cloud HSM services. To effectively utilize this guide, a basic understanding of Citrix ADC and Luna HSM concepts is assumed.
Citrix ADC (formerly known as NetScaler ADC) is an application delivery controller and load balancing solution developed by Citrix Systems. It is used to optimize the delivery of applications and web services, ensuring high availability, security, and performance. Citrix ADC functions as an intermediary between clients and servers, managing traffic flow, optimizing application performance, and enhancing security through features such as SSL encryption and authentication. In the context of SSL communication, Citrix ADC requires private keys to encrypt and decrypt data transmitted over HTTPS connections. Private keys are used to establish secure communication channels between clients and servers. To enhance security, organizations often use Hardware Security Modules like the Thales Luna HSM to generate and securely store these private keys.
The integration between Citrix ADC and Thales Luna HSM allows organizations to leverage the security features of HSMs for SSL communication. Thales Luna HSM generates and securely stores the private keys used by Citrix ADC, ensuring that they are protected from unauthorized access and tampering. By offloading cryptographic operations to the HSM, organizations can enhance the security of their SSL communication while maintaining high performance and scalability. The benefits of integrating Luna HSMs with Citrix ADC include:
-
Secure generation, storage, and protection of the identity signing private keys using either FIPS 140-2 or FIPS 140-3 Level 3 validated hardware.
-
Full life cycle management of the keys to ensure their integrity and reliability throughout their usage.
-
Maintenance of a comprehensive HSM audit trail for transparency and accountability in key operations. It's important to note that Luna Cloud HSM service does not have access to this secure audit trail.
-
Significant performance enhancements by offloading cryptographic operations from application servers.
Supported Platforms
This integration has been tested and verified on the following platforms:
| Third Party Details | Luna HSM Version | Luna Firmware Version |
|---|---|---|
| Citrix ADC Virtual Appliance (NS13.0 83.29.nc) | Appliance Version-7.7.1 | 7.7.2 |
| Citrix ADC Virtual Appliance (13.1-12.51_nc) | Appliance Version-7.7.1 | 7.7.1 |
| Citrix ADC Virtual Appliance (13.0-47.24_nc) | Appliance Version-7.3.0 | 7.3.3 |
| Citrix ADC Virtual Appliance (13.0-41.20_nc) | Appliance Version-7.3.0 | 7.3.0 |
| Citrix ADC Virtual Appliance (12.1-51.19_nc) | Appliance Version-6.3.0 | 6.27.0 |
| Citrix NetScaler Virtual Appliance(11.1-47.14_nc) | Appliance Version-5.4.7 | 6.10.9 |
This integration has been tested in both HA and FIPS modes.
Prerequisites
Before integrating, ensure that the following prerequisites are met:
Configure Luna HSM
Before initiating the integration process, it's crucial to ensure that the Luna HSM is properly configured, and a partition is initialized. Follow these steps to configure the Luna HSM:
This integration guide specifically outlines the steps for establishing a Network Trust Link (NTL) between the Citrix ADC host environment and the Luna HSM appliance. For detailed instructions on additional configuration tasks such as creating High Availability (HA), initializing partitions, and setting up user roles, please refer to the Luna HSM documentation.
Set up Citrix ADC virtual appliance
To set up your Citrix ADC virtual appliance, follow these steps:
Download the Virtual Image File: Visit the Citrix Product Portal to download the appropriate virtual image file for your deployment environment (VMware). Detailed instructions can be found in the Citrix Product Documentation.
Deploy the Virtual Appliance on VMware: Utilize the downloaded virtual image file to deploy the Citrix ADC virtual appliance on your VMware environment. Refer to the deployment guide provided in the Citrix Product Documentation for step-by-step instructions.
Access the Citrix ADC Web Console: Once the virtual appliance is deployed and running, access the Citrix ADC Web console using the IP address configured during deployment. Simply enter the following URL in your web browser: http://CitrixADCApplianceIP-Address. Replace CitrixADCApplianceIP-Address with the actual IP address assigned to your Citrix ADC appliance.
The freemium version of Citrix ADC does not support the load balancing functionality. To fully utilize the features and capabilities of Citrix ADC, including load balancing, you must ensure that you have the appropriate license in place. Failing to have the correct license may result in limited functionality or the inability to use the load balancing capabilities. It is important to review your current license to confirm that it includes the necessary permissions for load balancing, and if not, you will need to upgrade or acquire the appropriate license to enable this functionality.
Integrating Citrix ADC with Luna HSM
The following steps are involved in integrating Citrix ADC with Luna HSM, enabling you to generate and store the Citrix ADC SSL communication private keys:
Create a Network Trust Link between Citrix ADC and Luna HSM
Generate a key pair and certificate on Luna HSM
Create a Network Trust Link between Citrix ADC and Luna HSM
To establish a secure connection between Luna HSM and Citrix ADC for managing SSL communication private keys, follow these detailed steps:
Access the Citrix Appliance and switch to the BSD Shell by running the following command:
shell
Copy the required Citrix ADC build with Luna libraries to the /var directory on the Citrix ADC Virtual Appliance:
cp build-12.1-51.19_nc_64.tgz /var
For Citrix ADC 13.x.x onwards, skip this step.
Untar the build in the /var directory and run the installns script:
tar -zxvf build-12.1-51.19_nc_64.tgz cd /var/nsinstall ./installns
For Citrix ADC 13.x.x onwards, skip this step.
Navigate to the /var/safenet directory and run the installation script to install the Luna Client corresponding to your appliance version:
cd /var/safenet ./install_client.sh -v 722
or
./install_client.sh -v 1030
The numbers 722 and 1030 correspond to the Luna client versions for v7.2.2 and v10.3.0, respectively. Ensure to adjust the version number based on the specific version provided in your Citrix ADC Appliance for compatibility.
The Luna Client 6.0.0 included with the Citrix build is not compatible with HA mode in Citrix Virtual Appliance setups. Be mindful of this limitation when configuring your environment to avoid potential issues with HA functionality.
Execute the safenet_config script in the /var/safenet/config directory to set up the necessary configurations:
cd /var/safenet/config sh safenet_config
The script safenet_config serves a dual purpose: it copies the Chrystoki.conf file into the /etc directory, ensuring proper configuration, and generates a symbolic link, libCryptoki2_64.so, in the /usr/lib directory. This streamlined approach simplifies access to essential files and components, facilitating the integration of Luna HSM with Citrix ADC by establishing necessary configurations and symbolic links for seamless operation.
Create Network Trust Link (NTL):
a. Navigate to /var/safenet/safenet/lunaclient/bin and generate a certificate for Citrix ADC using:
./vtl createCert -n
b. Import the Citrix ADC certificate to Luna HSM by executing:
scp /var/safenet/safenet/lunaclient/cert/client/[IP address of Citrix ADC].pem [HSM account]@[HSM IP]:
c. Export the Luna HSM certificate to Citrix ADC with:
scp@ :server.pem /var/safenet/safenet/lunaclient/cert/server/[HSM IP].pem
d. Register the Luna HSM certificate on the Citrix ADC appliance using:
./vtl addserver -n [HSM IP] -c /var/safenet/safenet/lunaclient/cert/server/[HSM IP].pem
e. Access Luna Shell and register Citrix ADC as a client on Luna HSM:
lunash:> client register -client [client name] -ip [Citrix ADC IP]
f. Once the client is registered, assign the created partition for Citrix ADC to the client:
lunash:> client assignPartition -client [Client Name] -partition [Partition Name]
g. Verify the NTL connectivity between Citrix ADC and HSM by running:
./vtl verify
Exit the shell and log back into the Citrix ADC CLI. Save the configuration to ensure the settings are retained:
save ns config
In the BSD shell, copy the /etc/Chrystoki.conf file to the /var/safenet/config directory to enable automatic startup of SafeNet Client processes on ADC reboot:
cp /etc/Chrystoki.conf /var/safenet/config/
Start the SafeNet Gateway client process by executing the following command:
sh /var/safenet/gateway/start_safenet_gw
Create the /var/safenet/safenet_is_enrolled file to signal the ADC appliance to automatically start the SafeNet client processes after reboot:
touch /var/safenet/safenet_is_enrolled
Reboot the ADC appliance to verify that the processes are started automatically at boot time:
reboot
After the reboot, confirm that the SafeNet Gateway client process is running:
ps -aux | grep safenet_gw
Generate a key pair and certificate on Luna HSM
To generate a key pair and certificate on Luna HSM, follow these steps:
Navigate to the /var/safenet/safenet/lunaclient/bin directory and generate a key pair using the cmu utility:
./cmu generatekeypair -modulusBits=2048 -publicExponent=65537 -sign=T -verify=T -encrypt=1 -decrypt=1 -wrap=1 -unwrap=1 -label=Citrix_Keys
Enter the partition password when prompted.
List the generated key pair:
./cmu list
Enter the partition password when prompted.
Generate a certificate request:
./cmu requestcertificate
Provide the partition password when prompted.
The certificate request file is saved in the /var/safenet/safenet/lunaclient/bin directory by default.
Obtain the signed certificate from the trusted Certificate Authority and transfer the certificate to the /var/safenet/safenet/lunaclient/bin directory.
Import the signed certificate to Luna HSM:
./cmu import
Provide the partition password and certificate file when prompted.
Export the certificate in .pem format from Luna HSM:
./cmu export
Enter the partition password and specify the certificate PEM file name when prompted.
Copy the exported certificate to the /nsconfig/ssl directory on the Citrix ADC:
cp/nsconfig/ssl/
Add the key pair and certificate to Citrix ADC
To add the key pair and certificate generated on Luna HSM to Citrix ADC, follow these steps:
Add the HSM key on the Citrix ADC CLI using the following command:
add ssl hsmKey [KeyName] -hsmType SAFENET -serialNum [serial number of partition] -password [Partition_password]
You may encounter an error message while adding the key to Citrix ADC: ERROR: Internal error while adding HSM key. You can safely ignore this message.
Verify that the HSM key was added successfully by running:
show run | grep -i hsm
Add the HSM certificate-key pair to Citrix ADC using the following command:
add ssl certKey [CertkeyName] -cert [cert name] -hsmkey [KeyName]
Verify that the certificate key-pair was added successfully by running:
show run | grep -i hsm
Create and test a load balancing virtual server
After adding the keys and certificate to Citrix ADC, ensure their functionality by setting up a test load balancing virtual server. For this demonstration, Microsoft IIS is utilized as the backend server. To create a load balancing virtual server, access http:/CitrixADCWebIP-Address and proceed with the following steps:
Add servers
To add servers for virtual load balancing on Citrix ADC, follow these steps:
Go to Traffic Management > Load Balancing > Servers in the Citrix ADC interface.
Click on the Add button to input the necessary information for the application server.
Click on Create to finalize adding the server. The newly added server will now be visible in the server list.
Add services
To create a service on the server and finalize the load balancing configuration, follow these steps:
Go to Traffic Management > Load Balancing > Services in the Citrix ADC interface.
Click on the Add button to create a new service.
In the Server field, enter the IP address of the machine where your application is already running. Select the appropriate protocol and port for your application.
Click on OK to save the service configuration. This will take you back to the Services page.
Ensure that the State column in the Services table displays UP for the newly added service. Click on Done to complete the service addition process.
Add virtual servers
To set up and configure a virtual server as the load balancer for the backend server and connect it to the shared service, follow these user-friendly steps:
Access Traffic Management > Load Balancing > Virtual Servers in the Citrix ADC interface.
Click on the Add button to create a new virtual server.
Enter the name and IP address for the virtual server. Select the protocol as SSL and then click OK.
The State column may initially show as Down in the basic settings. Proceed to bind the service and certificate to bring it UP.
Click on No Load Balancing Virtual Server Service Binding to access the Service Binding page. Select the service you created earlier and click the Bind button.
After binding the service, click on Continue.
Click on No Server Certificate to proceed with the configuration.
