Product Documentation

Transport Layer Security (TLS)

Jan 04, 2018
XenApp and XenDesktop support the Transport Layer Security (TLS) protocol for TCP-based connections between components. XenApp and XenDesktop also support the Datagram Transport Layer Security (DTLS) protocol for UDP-based ICA/HDX connections, using adaptive transport.
 
TLS and DTLS are similar, and support the same digital certificates. Configuring a XenApp or XenDesktop Site to use TLS also configures it to use DTLS. Use the following procedures; the steps are common to both TLS and DTLS except where noted:
  • Obtain, install, and register a server certificate on all Delivery Controllers, and configure a port with the TLS certificate. For details, see Install TLS server certificates on Controllers.

    Optionally, you can change the ports the Controller uses to listen for HTTP and HTTPS traffic.

  • Enable TLS connections between Citrix Receivers and Virtual Delivery Agents (VDAs) by completing the following tasks:
Requirements and considerations:
  • Enabling TLS connections between users and VDAs is valid only for XenApp 7.6 and XenDesktop 7.6 Sites, plus later supported releases.
  • Configure TLS in the Delivery Groups and on the VDAs after you install components, create a Site, create machine catalogs, and create Delivery Groups.
  • To configure TLS in the Delivery Groups, you must have permission to change Controller access rules. A Full Administrator has this permission.
  • To configure TLS on the VDAs, you must be a Windows administrator on the machine where the VDA is installed.
  • On pooled VDAs that are provisioned by Machine Creation Services or Provisioning Services, the VDA machine image is reset on restart, causing previous TLS settings to be lost. Run the PowerShell script each time the VDA is restarted to reconfigure the TLS settings.

Warning

For tasks that include working in the Windows registry—editing the registry incorrectly can cause serious problems that may require you to reinstall your operating system. Citrix cannot guarantee that problems resulting from the incorrect use of Registry Editor can be solved. Use Registry Editor at your own risk. Be sure to back up the registry before you edit it.

For information about enabling TLS to the Site database, see CTX137556

Install TLS server certificates on Controllers

For HTTPS, the XML Service supports TLS features by using server certificates, not client certificates. To obtain, install, and register a certificate on a Controller, and to configure a port with the TLS certificate:

If the Controller has IIS installed, follow the guidance in https://technet.microsoft.com/en-us/library/cc771438%28v=ws.10%29.aspx.

If the Controller does not have IIS installed, one method of configuring the certificate is:

  1. Obtain a TLS server certificate and install it on the Controller using the guidance in http://blogs.technet.com/b/pki/archive/2009/08/05/how-to-create-a-web-server-ssl-certificate-manually.aspx. For information on the certreq tool, see http://technet.microsoft.com/en-us/library/cc736326(WS.10).aspx.
  2. Configure a port with the certificate; see http://msdn.microsoft.com/en-us/library/ms733791%28v=vs.110%29.aspx.

If the Controller is installed on Windows Server 2016, and StoreFront is installed on Windows Server 2012, a configuration change is needed at the Controller, to change the order of TLS cipher suites.

Note

This configuration change is not needed for Controller and StoreFront with other combinations of Windows Server versions.

The cipher suite order list must include the TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384, or TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256 cipher suites (or both); and these cipher suites must precede any TLS_DHE_ cipher suites.

Note

Windows Server 2012 does not support the GCM cipher suites TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 or TLS_ECDHE_RSA_WITH_AES_128_GCM _SHA256.

  1. Using the Microsoft Group Policy Editor, browse to Computer Configuration > Administrative Templates > Network > SSL Configuration Settings.
  2. Edit the policy “SSL Cipher Suite Order”. By default, this policy is set to “Not Configured”. Set this policy to Enabled.
  3. Arrange suites in the correct order; remove any cipher suites suites you do not want to use.

Ensure that either TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384, or TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256 precedes any TLS_DHE_ cipher suites.

On Microsoft MSDN, see also Prioritizing Schannel Cipher Suites.

Change HTTP or HTTPS ports

By default, the XML Service on the Controller listens on port 80 for HTTP traffic and port 443 for HTTPS traffic. Although you can use non-default ports, be aware of the security risks of exposing a Controller to untrusted networks. Deploying a standalone StoreFront server is preferable to changing the defaults.

To change the default HTTP or HTTPS ports used by the Controller, run the following command from Studio:

BrokerService.exe -WIPORT <http-port> -WISSLPORT <https-port>

where <http-port> is the port number for HTTP traffic and <https-port> is the port number for HTTPS traffic.

Note

After changing a port, Studio might display a message about license compatibility and upgrading. To resolve the issue, re-register service instances using the following PowerShell cmdlet sequence:

Get-ConfigRegisteredServiceInstance -ServiceType Broker -Binding XML_HTTPS |

Unregister-ConfigRegisteredServiceInstance 

Get-BrokerServiceInstance | where Binding -eq "XML_HTTPS" |  
Register-ConfigServiceInstance

Enforce HTTPS traffic only

If you want the XML Service to ignore HTTP traffic, create the following registry setting in HKLM\Software\Citrix\DesktopServer\ on the Controller and then restart the Broker Service.

To ignore HTTP traffic, create DWORD XmlServicesEnableNonSsl and set it to 0.

There is a corresponding registry DWORD value you can create to ignore HTTPS traffic: DWORD XmlServicesEnableSsl. Ensure that it is not set to 0.

TLS settings on VDAs

A Delivery Group cannot have a mixture of some VDAs with TLS configured and some VDAs without TLS configured. Before you configure TLS for a Delivery Group, ensure that you have already configured TLS for all the VDAs in that Delivery Group

When you configure TLS on VDAs, permissions on the installed TLS certificate are changed, giving the ICA Service read access to the certificate’s private key, and informing the ICA Service of the following:

  • Which certificate in the certificate store to use for TLS.
  • Which TCP port number to use for TLS connections.

The Windows Firewall (if enabled) must be configured to allow incoming connection on this TCP port. This configuration is done for you when you use the PowerShell script.

  • Which versions of the TLS protocol to allow.

Important

Citrix recommends that you review your use of SSLv3, and reconfigure those deployments to remove support for SSLv3 where appropriate. See CTX200238.

The supported TLS protocol versions follow a hierarchy (lowest to highest): SSL 3.0, TLS 1.0, TLS 1.1, and TLS 1.2. Specify the minimum allowed version; all protocol connections using that version or a higher version are allowed.

For example, if you specify TLS 1.1 as the minimum version, then TLS 1.1 and TLS 1.2 protocol connections are allowed. If you specify SSL 3.0 as the minimum version, then connections for all the supported versions are allowed. If you specify TLS 1.2 as the minimum version, only TLS 1.2 connections are allowed.

DTLS 1.0 corresponds to TLS 1.1, and DTLS 1.2 corresponds to TLS 1.2.

  • Which TLS cipher suites to allow.

A cipher suite selects the encryption that is used for a connection.  Clients and VDAs can support different sets of cipher suites. When a client (Citrix Receiver or StoreFront) connects and sends a list of supported TLS cipher suites, the VDA matches one of the client’s cipher suites with one of the cipher suites in its own list of configured cipher suites, and accepts the connection. If there is no matching cipher suite, the VDA rejects the connection.

The VDA supports three sets of cipher suites (also known as compliance modes): GOV(ernment), COM(mercial), and ALL. The acceptable cipher suites also depend on the Windows FIPS mode; see http://support.microsoft.com/kb/811833 for information about Windows FIPS mode. The following table lists the cipher suites in each set:

TLS/DTLS cipher suite ALL COM GOV ALL COM GOV

FIPS Mode

Off

Off

Off

On

On

On

TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384**

X

X

X

X

TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256**

X

X

X

X

X

X

TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384

X

X

X

X

TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256

X

X

X

X

X

X

TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA

X

X

X

X

TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA

X

X

X

X

X

X

TLS_RSA_WITH_AES_256_GCM_SHA384

X

X

X

X

TLS_RSA_WITH_AES_128_GCM_SHA256

X

X

X

X

X

X

TLS_RSA_WITH_AES_256_CBC_SHA256

X

X

X

X

TLS_RSA_WITH_AES_128_CBC_SHA256

X

X

X

X

X

X

TLS_RSA_WITH_AES_256_CBC_SHA

X

X

X

X

TLS_RSA_WITH_AES_128_CBC_SHA

X

X

X

X

X

X

TLS_RSA_WITH_3DES_EDE_CBC_SHA

X

X***

X

X***

TLS_RSA_WITH_RC4_128_SHA*

X****

X****

TLS_RSA_WITH_RC4_128_MD5*

X****

X****

* These cipher suites are not supported by DTLS.
** These cipher suites are not supported in Windows Server 2012 R2.
*** 3DES is disabled by default in GOV cipher set.
**** RC4-MD5 is disabled by default.

Note

The VDA does not support DHE ciphersuites (for example, TLS_DHE_RSA_WITH_AES_256_GCM_SHA384, TLS_DHE_RSA_WITH_AES_256_CBC_SHA, TLS_DHE_RSA_WITH_AES_128_GCM_SHA256, and TLS_DHE_RSA_WITH_AES_128_CBC_SHA.)  If selected by Windows, they may not be used by Receiver.

Configure TLS on a VDA using the PowerShell script

Install the TLS Certificate in the Local Computer > Personal > Certificates area of the certificate store. If more than one certificate resides in that location, supply the thumbprint of the certificate to the PowerShell script.

Note

Starting with XenApp and XenDesktop 7.16 LTSR, the PowerShell script finds the correct certificate based on the FQDN of the VDA. You do not need to supply the thumbprint when only a single certificate is present for the VDA FQDN.

The Enable-VdaSSL.ps1 script enables or disables the TLS listener on a VDA. This script is available in the Support >Tools > SslSupport folder on the installation media.

When you enable TLS, DHE cipher suites are disabled.  ECDHE cipher suites are not affected.

When you enable TLS, the script disables all existing Windows Firewall rules for the specified TCP port. It then adds a new rule that allows the ICA Service to accept incoming connections only on the TLS TCP and UDP ports. It also disables the Windows Firewall rules for:

  • Citrix ICA (default: 1494)
  • Citrix CGP (default: 2598)
  • Citrix WebSocket (default: 8008)

The effect is that users can only connect using TLS or DTLS. They cannot use ICA/HDX, ICA/HDX with Session Reliability, or HDX over WebSocket, without TLS or DTLS.

Note

DTLS is not supported with ICA/HDX Audio over UDP Real-time Transport, or with ICA/HDX Framehawk.

See Network ports.

The script contains the following syntax descriptions, plus extra examples; you can use a tool such as Notepad++ to review this information.

Important

Specify either the Enable or Disable parameter, and the CertificateThumbPrint parameter. The other parameters are optional.

Syntax

Enable-VdaSSL {-Enable | -Disable} -CertificateThumbPrint "<thumbprint>"
[–SSLPort <port>] [-SSLMinVersion "<min-ssl-version>"] [-SSLCipherSuite"<suite>"] 

Parameter Description

Enable

Installs and enables the TLS listener on the VDA. Either this parameter or the Disable parameter is required.

Disable

Disables the TLS listener on the VDA. Either this parameter or the Enable parameter is required. If you specify this parameter, no other parameters are valid.

CertificateThumbPrint
"<thumbprint>"

Thumbprint of the TLS certificate in the certificate store, enclosed in quotation marks. The script uses the specified thumbprint to select the certificate you want to use. If this parameter is omitted, an incorrect certificate is selected.

SSLPort <port>

TLS port. Default: 443

SSLMinVersion
"<version>"

Minimum TLS protocol version, enclosed in quotation marks. Valid values:

  • "SSL_3.0"
  • "TLS_1.0"
  • "TLS_1.1"
  • "TLS_1.2"

Default: "TLS_1.0"

Important: Citrix recommends that customers review their usage of SSLv3 and take steps to reconfigure their deployments to remove support for SSLv3 where appropriate. See CTX200238.

SSLCipherSuite
"<suite>"

TLS cipher suite, enclosed in quotation marks. Valid values:

  • "GOV"
  • "COM"
  • "ALL"

Default: "ALL"

Examples

The following script installs and enables the TLS protocol version value. The thumbprint (represented as "12345678987654321" in this example) is used to select the certificate to use.

Enable-VdaSSL –Enable -CertificateThumbPrint "12345678987654321"

The following script installs and enables the TLS listener, and specifies TLS port 400, the GOV cipher suite, and a minimum TLS 1.2 protocol value. The thumbprint (represented as "12345678987654321" in this example) is used to select the certificate to use.

Enable-VdaSSL – Enable
-CertificateThumbPrint "12345678987654321"
–SSLPort 400 'SSLMinVersion "TLS_1.2"
–SSLCipherSuite "GOV"

The following script disables the TLS listener on the VDA.

Enable-VdaSSL –Disable

Manually configure TLS on a VDA

When configuring TLS on a VDA manually, you grant generic read access to the private key of the TLS certificate for the appropriate service on each VDA: NT SERVICE\PorticaService for a VDA for Windows Desktop OS, or NT SERVICE\TermService for a VDA for Windows Server OS. On the machine where the VDA is installed:

STEP 1. Launch the Microsoft management console (MMC): Start > Run > mmc.exe.

STEP 2. Add the Certificates snap-in to the MMC:

  1. Select File > Add/Remove Snap-in.
  2. Select Certificates and then click Add.
  3. When prompted with "This snap-in will always manage certificates for:" choose "Computer account" and then click Next.
  4. When prompted with "Select the computer you want this snap-in to manage" choose "Local computer" and then click Finish.

STEP 3. Under Certificates (Local Computer) > Personal > Certificates, right–click the certificate and then select All Tasks > Manage Private Keys.

STEP 4. The Access Control List Editor displays "Permissions for (FriendlyName) private keys" where (FriendlyName) is the name of your TLS certificate. Add one of the following services and give it Read access:

  • For a VDA for Windows Desktop OS, "PORTICASERVICE"
  • For a VDA for Windows Server OS, "TERMSERVICE"

STEP 5. Double-click the installed TLS certificate. In the certificate dialog, select the Details tab and then scroll to the bottom. Click Thumbprint.

STEP 6. Run regedit and go to HKLM\SYSTEM\CurrentControlSet\Control\Terminal Server\Wds\icawd.

  1. Edit the SSL Thumbprint key and copy the value of the TLS certificate’s thumbprint into this binary value. You can safely ignore unknown items in the Edit Binary Value dialog box (such as '0000' and special characters).
  2. Edit the SSLEnabled key and change the DWORD value to 1. (To disable SSL later, change the DWORD value to 0.)
  3. If you want to change the default settings (optional), use the following in the same registry path:

SSLPort DWORD – SSL port number. Default: 443.

SSLMinVersion DWORD – 1 = SSL 3.0, 2 = TLS 1.0, 3 = TLS 1.1, 4 = TLS 1.2. Default: 2 (TLS 1.0).

SSLCipherSuite DWORD – 1 = GOV, 2 = COM, 3 = ALL. Default: 3 (ALL).

STEP 7. Ensure that the TLS TCP and UDP ports are that open in the Windows Firewall if they are not the default 443. (When you create the inbound rule in Windows Firewall, ensure its properties have the "Allow the connection" and "Enabled" entries selected.)

STEP 8. Ensure that no other applications or services (such as IIS) are using the TLS TCP port.

STEP 9. For VDAs for Windows Server OS, restart the machine for the changes to take effect. (You do not need to restart machines containing VDAs for Windows Desktop OS.)

Important

An extra step is necessary when the VDA is on Windows Server 2012 R2, Windows Server 2016, or Windows 10 Anniversary Edition or later supported release. This affects connections from Citrix Receiver for Windows (version 4.6 through 4.9), Citrix Receiver for HTML5, and Citrix Receiver for Chrome. This also includes connections using NetScaler Gateway.

This step is also required for all connections using NetScaler Gateway, for all VDA versions, if TLS between the NetScaler Gateway and the VDA is configured. This affects all Citrix Receiver versions.

On the VDA (Windows Server 2012 R2, Windows Server 2016, or Windows 10 Anniversary Edition or later), using the Group Policy Editor, go to Computer Configuration > Administrative Templates > Network > SSL Configuration Settings > SSL Cipher Suite Order. Select the following order:

TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384_P384
TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384_P256
TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384_P384
TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384_P256
TLS_RSA_WITH_AES_256_GCM_SHA384
TLS_RSA_WITH_AES_128_GCM_SHA256
TLS_RSA_WITH_AES_256_CBC_SHA256
TLS_RSA_WITH_AES_256_CBC_SHA
TLS_RSA_WITH_AES_128_CBC_SHA
TLS_RSA_WITH_RC4_128_SHA
TLS_RSA_WITH_3DES_EDE_CBC_SHA

Note

The first four items also specify the elliptic curve, P384 or P256. Ensure that "curve25519" is not selected.  FIPS Mode does not prevent the use of "curve25519".

When this Group Policy setting is configured, the VDA selects a cipher suite only if appears in both lists: the Group Policy list and the list for the selected compliance mode (COM, GOV, or ALL). The cipher suite must also appear in the list sent by the client (Citrix Receiver or StoreFront).

This Group Policy configuration also affects other TLS applications and services on the VDA. If your applications require specific cipher suites, you may need to add them to this Group Policy list.

Important

Even though Group Policy changes are shown when they are applied, Group Policy changes for TLS configuration only take effect after an operating system restart. Therefore, for pooled desktops, apply the Group Policy changes for TLS configuration to the base image.

Configure TLS on Delivery Groups

Complete this procedure for each Delivery Group that contains VDAs you have configured for TLS connections.

  1. From Studio, open the PowerShell console.
  2. Run asnp Citrix.* to load the Citrix product cmdlets.
  3. Run Get-BrokerAccessPolicyRule -DesktopGroupName '<delivery-group-name>' | Set-BrokerAccessPolicyRule -HdxSslEnabled $true.
  4. Run Set-BrokerSite -DnsResolutionEnabled $true.

Troubleshooting

If a connection error occurs, check the system event log on the VDA.

When using Citrix Receiver for Windows, if you receive a connection error that indicates a TLS error, disable Desktop Viewer and then try connecting again. Although the connection still fails an explanation of the underlying TLS issue might be provided. For example, you specified an incorrect template when requesting a certificate from the certificate authority.)

Most configurations that use HDX Adaptive Transport work successfully with DTLS, including those using the latest versions of Citrix Receiver, NetScaler Gateway, and the VDA.  Some configurations which use DTLS between Citrix Receiver and NetScaler Gateway, and which use DTLS between NetScaler Gateway and the VDA, require additional action.

Additional action is needed if:

  • the Citrix Receiver version supports HDX Adaptive Transport and DTLS: Receiver for Windows (4.7, 4.8, 4.9), Receiver for Mac (12.5, 12.6, 12.7), Receiver for iOS (7.2, 7.3.x) or Receiver for Linux (13.7)

and either of the following also applies:

  • the NetScaler Gateway version supports DTLS to the VDA, but the VDA version does not support DTLS (version 7.15 or earlier),
  • the VDA version supports DTLS (version 7.16 or later), but the NetScaler Gateway version does not support DTLS to the VDA.

To avoid connections from Citrix Receiver failing, do one of the following:

  • update Citrix Receiver, to Receiver for Windows version 4.10 or later, Receiver for Mac 12.8 or later, or Receiver for iOS version 7.5 or later; or,
  • update the NetScaler Gateway to a version that supports DTLS to the VDA; or,
  • update the VDA, to version 7.16 or later; or,
  • disable DTLS at the VDA; or,
  • disable HDX Adaptive Transport.

Note

A suitable update for Receiver for Linux is not yet available. Receiver for Android (version 3.12.3) does not support HDX Adaptive Transport and DTLS via NetScaler Gateway, and is therefore not affected.

To disable DTLS at the VDA, modify the VDA firewall configuration to disable UDP port 443.  See Network ports.

Communication between Controller and VDA

Windows Communication Framework (WCF) message-level protection secures communication between the Controller and the VDA. Extra transport-level protection using TLS is not required. The WCF configuration uses Kerberos for mutual authentication between the Controller and VDA. Encryption uses AES in CBC mode with a 256-bit key. Message integrity uses SHA-1.

According to Microsoft, the Security protocols used by WCF conform to standards from OASIS (Organization for the Advancement of Structured Information Standards), including WS-SecurityPolicy 1.2.  Additionally, Microsoft states that WCF supports all algorithm suites listed in Security Policy 1.2.

Communication between the Controller and VDA uses the basic256 algorithm suite, whose algorithms are as stated above.

TLS and HTML5 video redirection, and browser content redirection

You can use HTML5 video redirection and browser content redirection to redirect HTTPS websites. The JavaScript injected into those websites must establish a TLS connection to the Citrix HDX HTML5 Video Redirection Service running on the VDA. To achieve this, two custom certificates are generated in the certificate store on the VDA.

The HTML5 video redirection policy is disabled by default.

The browser content redirection is enabled by default.

Note

If  you do not intend to use HTML5 video redirection or browser content redirection, we recommend that you delete the two certificates from the local computer certificate store.

These certificates are:

  • For the CA (root): Citrix XenApp/XenDesktop HDX In-Product CA (C = US; S = Florida; L = Fort Lauderdale; O = Citrix Systems, Inc.; OU = XenApp/XenDesktop Engineering; CN = Citrix XenApp/XenDesktop HDX In-Product CA)
    Location: Certificates (Local Computer) >Trusted Root Certification Authorities >Certificates.
  • For the end-entity (leaf): Citrix XenApp/XenDesktop HDX Service (C = US; S = Florida; L = Fort Lauderdale; O = Citrix Systems, Inc.; OU = XenApp/XenDesktop Engineering; CN = Citrix XenApp/XenDesktop HDX Service)
    Location: Certificates (Local Computer) > Personal > Certificates.

We recommend setting the Citrix HDX HTML5 Video Redirection Service so that it doesn't automatically start.
Stopping this service also removes the certificates.

For more information on HTML5 video redirection, see Multimedia policy settings.