Introduction

Citrix Federated Authentication Servers (FAS) are security-critical and should be treated like Domain Controllers. Protecting the FAS server’s Authorization / Registration Authority (RA) key is one of the measures that help protect FAS server integrity.

We published an official eDocs page on FAS private key protection: Citrix Documentation - Federated Authentication Service private key protection.

This document is intentionally generic. We do not go into details on how to configure private key protection with FAS for specific HSM (Hardware Security Module) vendors. FAS is built on top of Microsoft cryptographic technology (CAPI / CNG). It should therefore be possible to use third party cryptographic solutions such as HSMs, provided the third party products are supported with Microsoft cryptographic technologies.

There is no standard for HSM configuration. Setup varies from vendor to vendor. Even within a single vendor’s range, different models use different configuration procedures. For example, one vendor might have a networked as well as a PCI version of the same product line with very different setup procedures. These products could come with either a secure PED (Pin Entry Device) or without, or even a remote PED. When a PED is utilised, certain setup steps will be different than when a PED is not utilised. For example, a Security Officer or Partition Owner password might be required for certain cryptographic operations instead of manually being present with a smart card and PIN when certain cryptographic or configuration operations are performed on the HSM.

Customers who would like to know if their HSM will work with FAS should ask their HSM vendor whether the vendor is enrolled in the Citrix Ready programme and specifically if the HSM they use is certified to be compatible with FAS.

FAS has proven to be a very popular Citrix technology. As third party documentation is not ready at this time and customers require guidance, we are providing this blog on how to configure FAS with one popular model, the SafeNet Network HSM (formerly known as a SafeNet Luna SA):
 
https://safenet.gemalto.com/data-encryption/hardware-security-modules-hsms/safenet-network-hsm/

This is not a comprehensive step-by-step guide and does not replace the information in eDocs.

---

Instructions

HSM initial setup, initialization and partitioning

Follow the vendor’s instructions to initialize your HSM and create a partition to be used by the FAS server.

Install SafeNet Luna Client

Install the SafeNet Luna Client on the FAS server using the vendor-provided installer:

Perform a Custom Setup and ensure that the Luna CSP (CAPI) / Luna KSP (CNG) components are installed:

Note: Screenshot shows PCI model. When writing this blog we did not have access to a device to re-test every step and re-purposed screenshots that were saved earlier.

Ensure that the SafeNet software is shown as installed:

Warning: Do not use KSP v6.2 to protect FAS user's (non-Authorization / RA) keys. The HSM will run out of space. Contact the vendor for an updated KSP for use with user keys with FAS.

Follow the vendor’s instructions to configure a secure connection between the FAS server and the Network HSM.

Get to the point where the command vtl.exe -verify succeeds from the FAS server to the Network HSM:

SafeNet KSP configuration, slot registration and network service. Register the Safenet KSP on the FAS server by running kspconfig.exe

The SafeNet KSP Config Wizard is spawned:

Click on Register Or View Security Library and register cryptoki.dll in the LunaClient directory:

Register HSM slots / Run as Network service

Click on Register HSM Slots and select the following:

• Register For User NETWORK SERVICE.
• Domain NT AUTHORITY
• Available Slots choose the partition created in earlier step according to vendor instructions. In this example the slot was named fasluna1
• Slot Password Enter slot password that was created in an earlier step according to vendor instructions.

Get FAS Authorization (RA) key and revert for user keys

Close FAS GUI.

Put FAS server in maintenance mode. (Instructions to put FAS server in maintenance mode at end of post)

Edit the Citrix.Authentication.FederatedAuthenticationService.exe config file located in the /Program Files/Citrix/Federated Authentication Service directory on the FAS server by adding the following line:
<add key="Citrix.TrustFabric.ClientSDK.TrustAreaJoinParameters.ProviderName" value="SafeNet Key Storage Provider"/>

The complete file should now look like this:

Save the file.

Restart the FAS service.

Start the FAS GUI

Perform Step 3 in FAS GUI to generate an Authorization (RA) key and certificate request

When all steps in the FAS GUI goes green, revert the Citrix.Authentication.FederatedAuthenticationService.exe config file setting back to Microsoft Software Key Storage Provider. This will prevent user keys from being generated in the HSM once the FAS server goes out of maintenance mode and requests start coming in. The complete file should look like this:

<!-- add key="Citrix.TrustFabric.ClientSDK.TrustAreaJoinParameters.ProviderName" value="Microsoft Software Key Storage Provider"/ -->
is commented out by default. Microsoft Software Key Storage Provider is the default cryptographic provider used by FAS out-of-the box. When no cryptographic provider is specified, the default provider is used. If no other cryptographic provider is specified in the config file, having a commented
<!-- add key="Citrix.TrustFabric.ClientSDK.TrustAreaJoinParameters.ProviderName" value="Microsoft Software Key Storage Provider"/ -->
or uncommented
<add key="Citrix.TrustFabric.ClientSDK.TrustAreaJoinParameters.ProviderName" value="Microsoft Software Key Storage Provider"/>
will both result in the Microsoft Software Key Storage Provider being used.

Save the file

Restart the FAS service

Take the FAS server out of maintenance mode.

Footnote 1 - Putting a FAS server into Maintenance mode

• Use the PowerShell command on the FAS server:

• Set-FasServer [-MaintenanceMode <Boolean>] [-Address <String>] [-UserName <String>] [-Password <String>] [<CommonParameters>]
  

• If FAS is in maintenance mode StoreFront wont pick that FAS server.

• Storefront will know that FAS is in maintenance mode because SF will contact FAS server and FAS server will report that it is in maintenance mode.

• If users already logged into VDA they are unaffected. They can still use their in-session certificates. Even if FAS server is in maintenance mode.

Footnote 2 - Renewing the Authorization (RA) key

When Authorization (RA) certificate expires (after 2 years by default) renew as follows:

• Place FAS server in maintenance mode using PowerShell command
• Run FAS GUI > Initial Setup > Deauthorize this Service > Click Deauthorize.
• Edit the configuration file to use the HSM for RA key:
• <add key="Citrix.TrustFabric.ClientSDK.TrustAreaJoinParameters.ProviderName" value="SafeNet Key Storage Provider"/>
• Restart the FAS Service
• Click “Authorize this Service”
• Manually “allow” the certificate to be issued on the CA
• Edit the configuration file back so user certificate keys will not be generated in the HSM:
• <add key="Citrix.TrustFabric.ClientSDK.TrustAreaJoinParameters.ProviderName" value="Microsoft Software Key Storage Provider"/>
• Restart the FAS Service
• Take FAS Server out of maintenance mode using PowerShell command

Warning: When Deauthorizing a FAS server, all the user certificates/keys on that FAS server gets deleted. Ensure that no users with existing sessions are relying on use of in-session certificates from the FAS server that is being Deauthorized.

Citrix is not responsible for and does not endorse or accept any responsibility for the contents or your use of these third party Web sites. Citrix is providing these links to you only as a convenience, and the inclusion of any link does not imply endorsement by Citrix of the linked Web site. It is your responsibility to take precautions to ensure that whatever Web site you use is free of viruses or other harmful items.

Using a SafeNet Network HSM to protect the Citrix Federated Authentication Server (FAS) Authorization (RA) key.