SSL
May 28, 2016
Configuring a XenApp or XenDesktop Site to use the Secure Sockets Layer (SSL) security protocol includes the following procedures:
-
Obtain, install, and register a server certificate on all Delivery Controllers, and configure a port with the SSL certificate. For details, see Install SSL server certificates on Controllers.
Optionally, you can change the ports the Controller uses to listen for HTTP and HTTPS traffic.
-
Enable SSL connections between users and Virtual Delivery Agents (VDAs) by completing the following tasks:
- Configure SSL on the machines where the VDAs are installed. (For convenience, further references to machines where VDAs are installed are simply called “VDAs.”) You can use a PowerShell script supplied by Citrix, or configure it manually. For general information, see About SSL settings on VDAs. For details, see Configure SSL on a VDA using the PowerShell script and Manually configure SSL on a VDA.
- Configure SSL in the Delivery Groups containing the VDAs by running a set of PowerShell cmdlets in Studio. For details, see Configure SSL on Delivery Groups.
Requirements and considerations:
- Enabling SSL connections between users and VDAs is valid only for XenApp 7.6 and XenDesktop 7.6 Sites, plus later supported releases.
- Configure SSL in the Delivery Groups and on the VDAs after you install components, create a Site, create Machine Catalogs, and create Delivery Groups.
- To configure SSL in the Delivery Groups, you must have permission to change Controller access rules; a Full Administrator has this permission.
- To configure SSL on the VDAs, you must be a Windows administrator on the machine where the VDA is installed.
- If you intend to configure SSL on VDAs that have been upgraded from earlier versions, uninstall any SSL relay software on those machines before upgrading them.
- The PowerShell script configures SSL on static VDAs; it does not configure SSL on pooled VDAs that are provisioned by Machine Creation Services or Provisioning Services, where the machine image resets on each restart.
For tasks that include working in the Windows registry:
Caution: 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 SSL to the Site database, see CTX137556.
Install SSL server certificates on Controllers
For HTTPS, the XML Service supports SSL features through the use of server certificates, not client certificates. To obtain, install, and register a certificate on a Controller, and to configure a port with the SSL 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:
-
Obtain an SSL 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.
If you intend to use the PowerShell script to configure SSL on VDAs, and unless you intend on specifying the SSL certificate’s thumbprint, make sure the certificate is located in the Local Computer > Personal > Certificates area of the certificate store. If more than one certificate resides in that location, the first one found will be used.
-
Configure a port with the certificate; see http://msdn.microsoft.com/en-us/library/ms733791%28v=vs.110%29.aspx.
-
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:
``` pre codeblock 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, set the following registry value in HKLM\\Software\\Citrix\\DesktopServer\\ on the Controller and then restart the Broker Service.
To ignore HTTP traffic, set XmlServicesEnableNonSsl to 0.
There is a corresponding registry value to ignore HTTPS traffic: XmlServicesEnableSsl. Ensure that this is not set to 0.
## <span id="about"></span>About SSL settings on VDAs
When you configure SSL on VDAs, it changes permissions on the installed SSL certificate, 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 SSL**.
- **Which TCP port number to use for SSL connections**.
The Windows Firewall (if it is 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 SSL protocol to allow**.
The supported SSL protocol versions follow a hierarchy (lowest to highest): SSL 3.0, TLS 1.0, TLS 1.1, and TLS 1.2. You 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.
- **Which SSL ciphers to allow**.
A cipher suite is a list of common SSL ciphers. When a client connects and sends a list of supported SSL ciphers, the VDA matches one of the client’s ciphers with one of the ciphers in its configured cipher suite and accepts the connection. If the client sends a cipher that is not in the VDA’s cipher suite, the VDA rejects the connection.
Three cipher suites are supported: GOV(ernment), COM(mercial), and ALL. The ciphers in those cipher suites depend on the Windows FIPS mode; see
<http://support.microsoft.com/kb/811833> for information about Windows FIPS mode. The following table lists the ciphers in each supported cipher suite.
| | | | | | | |
| -------------------- | :-: | :-: | :-: | :-: | :-: | :-: |
| **SSL cipher suite** | GOV | COM | ALL | GOV | COM | ALL |
| **FIPS Mode** | Off | Off | Off | On | On | On |
| **RSA\_KEYX** | x | x | x | x | x | x |
| **RSA\_SIGN** | x | x | x | x | x | x |
| **3DES** | x | | x | x | | x |
| **RC4** | | x | x | | | |
| **MD5** | x | x | x | | | |
| **SHA** | x | x | x | x | x | x |
| **SHA\_256** | x | x | x | x | x | x |
| **SHA\_384** | x | x | x | x | x | x |
| **SHA\_512** | x | x | x | x | x | x |
| **AES** | x | x | x | x | x | x |
A Delivery Group cannot have a mixture of some VDAs with SSL configured and some VDAs without SSL configured. When you configure SSL for a Delivery Group, you should have already configured SSL for all of the VDAs in that Delivery Group.
## <span id="config-ps"></span>Configure SSL on a VDA using the PowerShell script
The Enable-VdaSSL.ps1 script enables or disables the SSL listener on a VDA. This script is available in the Support \>Tools \> SslSupport folder on the installation media.
When you enable SSL, the script disables all existing Windows Firewall rules for the specified TCP port before adding a new rule that allows the ICA Service to accept incoming connections only on the SSL TCP port. It also disables the Windows Firewall rules for:
- Citrix ICA (default: 1494)
- Citrix CGP (default: 2598)
- Citrix WebSocket (default: 8008)
The result is that users can connect only over SSL; they cannot use raw ICA, CGP, or WebSocket to connect.
The script contains the following syntax descriptions, plus additional examples; you can use a tool such as Notepad++ to review this information.
You must specify either the –Enable or –Disable parameter; all other parameters are optional.
**Syntax**
Enable-VdaSSL {-Enable | -Disable} \[–SSLPort \<port\>\] \[-SSLMinVersion “\<min-ssl-version\>”\] \[-SSLCipherSuite “\<suite\>”\] \[-CertificateThumbPrint “\<thumbprint\>”\]
| Parameter | Description |
| ---------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| \-Enable | Installs and enables the SSL listener on the VDA. Either this parameter or the –Disable parameter is required. |
| \-Disable | Disables the SSL listener on the VDA. Either this parameter or the –Enable parameter is required. If you specify this parameter, no other parameters are valid. |
| –SSLPort \<port\> | SSL port. Default: 443 |
| \-SSLMinVersion “\<min-ssl-version\>” | Minimum SSL protocol version, enclosed in quotation marks. Valid values: "SSL\_3.0", "TLS\_1.0", "TLS\_1.1", and "TLS\_1.2". Default: "TLS\_1.0" |
| \-SSLCipherSuite “\<suite\>” | SSL cipher suite, enclosed in quotation marks. Valid values: "GOV", "COM", and "ALL". Default: "ALL" |
| \-CertificateThumbPrint “\<thumbprint\>” | Thumbprint of the SSL certificate in the certificate store, enclosed in quotation marks. This parameter is generally used when the certificate store has multiple certificates; the script uses the thumbprint to select the certificate you want to use. Default: the first available certificate found in the Local Computer \> Personal \> Certificates area of the certificate store. |
**Examples**
The following script installs and enables the SSL listener, using default values for all optional parameters.
``` pre codeblock
Enable-VdaSSL –Enable
The following script installs and enables the SSL listener, and specifies SSL port 400, the GOV cipher suite, and a minimum TLS 1.2 SSL protocol value.
``` pre codeblock Enable-VdaSSL – Enable –SSLPort 400 ‘SSLMinVersion “TLS_1.2” –SSLCipherSuite “GOV”
The following script disables the SSL listener on the VDA.
``` pre codeblock
Enable-VdaSSL –Disable
``` pre codeblock
``` pre codeblock
Manually configure SSL on a VDA
When configuring SSL on a VDA manually, you grant generic read access to the SSL certificate’s private key 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:
- Launch the Microsoft Management Console (MMC): Start > Run > mmc.exe.
- Add the Certificates snap-in to the MMC:
- Select File > Add/Remove Snap-in.
- Select Certificates and then click Add.
- When prompted with “This snap-in will always manage certificates for:” choose “Computer account” and then click Next.
- When prompted with “Select the computer you want this snap-in to manage” choose “Local computer” and then click Finish.
- Under Certificates (Local Computer) > Personal > Certificates, right–click the certificate and then select All Tasks > Manage Private Keys.
- The Access Control List Editor displays “Permissions for (FriendlyName) private keys” where (FriendlyName) is the name of your SSL 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”
- Double-click the installed SSL certificate. In the certificate dialog, select the Details tab and then scroll to the bottom. Click Thumbprint.
- Run regedit and go to HKLM\SYSTEM\CurrentControlSet\Control\Terminal Server\Wds\icawd.
- Edit the SSL Thumbprint key and copy the value of the SSL 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).
- Edit the SSLEnabled key and change the DWORD value to 1. (To disable SSL later, change the DWORD value to 0.)
- 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).
- Ensure the SSL TCP port is open in the Windows Firewall if it is not the default 443. (When you create the inbound rule in Windows Firewall, make sure its properties have the “Allow the connection” and “Enabled” entries selected.)
- Ensure that no other applications or services (such as IIS) are using the SSL TCP port.
- 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.)
Configure SSL on Delivery Groups
Complete this procedure for each Delivery Group that contains VDAs you have configured for SSL connections.
-
From Studio, open the PowerShell console.
-
Run asnp Citrix.* to load the Citrix product cmdlets.
-
Run Get-BrokerAccessPolicyRule –DesktopGroupName ‘<delivery-group-name>’ Set-BrokerAccessPolicyRule –HdxSslEnabled $true. where <delivery-group-name> is the name of the Delivery Group containing VDAs.
- Run Set-BrokerSite –DnsResolutionEnabled $true.
Troubleshooting
If a connection error occurs, check the VDA’s system event log.
When using Receiver for Windows, if you receive a connection error (such as 1030) that indicates an SSL error, disable Desktop Viewer and then try connecting again; although the connection will still fail, an explanation of the underlying SSL issue might be provided (for example, you specified an incorrect template when requesting a certificate from the certificate authority).