using ssl relay

(1)

U

Us

si

i

ng

n

g

t

he

h

e

C

Ci

it

t

r

i

x

®

S

SS

SL

L

R

e

la

l

a

y

S

Se

er

rv

vi

i

c

e

™

By Jay Tomlin

(2)

! Using the Citrix® SSL Relay Service™ _ii Notice

The information in this publication is subject to change without notice.

THIS PUBLICATION IS PROVIDED “AS IS” WITHOUT WARRANTIES OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING ANY WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT. CITRIX SYSTEMS, INC. (“CITRIX”), SHALL NOT BE LIABLE FOR TECHNICAL OR EDITORIAL ERRORS OR OMISSIONS CONTAINED HEREIN, NOR FOR DIRECT, INCIDENTAL, CONSEQUENTIAL OR ANY OTHER DAMAGES RESULTING FROM THE FURNISHING, PERFORMANCE, OR USE OF THIS PUBLICATION, EVEN IF CITRIX HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES IN ADVANCE.

This publication contains information protected by copyright. Except for internal distribution, no part of this publication may be photocopied or reproduced in any form without prior written consent from Citrix.

The exclusive warranty for Citrix products, if any, is stated in the product documentation accompanying such products. Citrix does not warrant products other than its own.

Product names mentioned herein may be trademarks and/or registered trademarks of their respective companies. Copyright © 2001 Citrix Systems, Inc., 6400 NW 6th Way, Ft. Lauderdale, Florida 33309 U.S.A. All rights reserved.

Version History

October, 1991 Jay Tomlin Original

(3)

Overview

With the release of Feature Release 1 for MetaFrame XP and MetaFrame 1.1 for UNIX, Citrix has introduced Secure Sockets Layer (SSL) encryption capabilities into ICA Clients and servers. This document outlines the system

requirements for using SSL with ICA and includes troubleshooting tips for correcting problems related to SSL. Also included are a cursory introduction to SSL and suggestions for further reading.

Summary of Prerequisites

Before a client can make an ICA/SSL connection to a MetaFrame server, you must meet certain prerequisites. The prerequisites are summarized briefly below and discussed in more detail throughout this document.

Server Software and Licensing

" MetaFrame XP 1.0 for Windows with Service Pack 1 (SP1) and Feature Release 1 (FR1) or MetaFrame for UNIX 1.1 with Feature Release 1

" You must enable DNS name resolution for the farm

" Feature Release 1 connection licenses must be available for each SSL user in the farm

SSL Relay Service

" Each MetaFrame server must be running the Citrix SSL Relay Service

" Configure each server running the SSL Relay Service with an SSL Server certificate matching its Fully-Qualified Domain Name (FQDN)

" Make sure the SSL Relay Service is listening on a port number to which ICA Clients have direct access (default 443)

Client Device

" You must use the ICA Clients released with MetaFrame XP Service Pack 1 or later (Version 6.20 or later)

" Install a Root (CA) Certificate belonging to the Certifying Authority who issued the MetaFrame server certificates on the ICA Client device

(5)

NFuse Web Server (Optional)

" Use NFuse Version 1.6 or later

" Set AddressResolutionType=DNS or DNS-port in NFuse.conf

" If the SSL Relay is also used to protect XML traffic, install a Root (CA) certificate on the NFuse Web server If any of these prerequisites are not met, SSL Relay clients will fail to connect. Each of the requirements listed above is covered in more detail in the following sections, including troubleshooting tips to assist you when problems persist.

Introduction to Secure Sockets Layer

Note: The following is only a cursory introduction to SSL and Digital Certificates, but it suffices to assist newcomers in their understanding of how SSL operates. For a more thorough introduction, please see the Further Reading section at the end of this section.

Many IT professionals unfamiliar with SSL believe that it provides only data encryption services. SSL includes methods for encrypting data over public networks, but this is only one of its two primary roles. The other important role of SSL, not as widely understood, is authentication.

The cornerstone of SSL’s authentication technology is trust. The mechanism for creating and exercising this trust is provided by Digital Certificates.

A good analogy for the SSL trust mechanism exists in everyday life: your driver's license. Clear parallels exist when you compare the procedures for obtaining and using a driver's license with those for obtaining and using a digital server certificate:

Driver's License SSL Server Certificate

Issued by Department of Motor Vehicles

(DMV) Certifying Authority (CA)

Primary purpose Personal identification in society and vehicle operation on public roads

Digital identification on the Internet and encryption of data on public networks

Document contains My name, address, and

photograph My server name (FQDN) and company name

Proof required during

(6)

! Using the Citrix® SSL Relay Service™ ₃ Driver's License SSL Server Certificate

Document authenticity

verified by DMV hologram or other formatting features imprinted on the license that would be very difficult to forge

Digital signature imprinted on the certificate using a lengthy private key string that would be very difficult to reproduce

Third parties honor the

document based on A common license format and hologram known to all as published by the DMV

A common root certificate made publicly available from the CA

Proof of identity during

usage Photo must match my appearance FQDN must match the server I connect to

Validity controlled by Expiration date Expiration date

Cost to the user Taxes and fees paid to the DMV Fees paid to the CA

When you see a person’s driver's license, you trust that this person is capable of driving a car on public roads. This feeling of trust is based on the notions that:

" You recognize the format of the driver's license and believe it was issued by the DMV

" You trust the DMV to scrutinize applicants and not to issue a license to someone who is incapable of driving a car In other words, you trust that the license is genuine because you trust the DMV.

Digital Certificates operate on this same model of trust-by-proxy. By signaling your trust in certain Certifying Authorities (CA), you implicitly trust any organization that is verified by that CA.

Suppose you are a client who wants to make an SSL-protected connection into an organization. The CA expresses its verification of the organization (and makes its money) by issuing to that organization a certificate that is “signed” by the CA. End-users express their trust in the CA by installing the CA’s Root certificate on their server or Web browser. During the client's connection request, an SSL handshake takes place in which the server sends its signed certificate to the client. Because the certificate contains the signature of a trusted CA, the connection continues.

The Windows operating system and many Web browsers are preconfigured with a set of Root certificates from reputable Certifying Authorities. The list of CA’s trusted by default include, but are not limited to:

(7)

These companies operate as public Certifying Authorities, not unlike public DMV offices. To save money, companies can choose to act as their own Certifying Authority. To do so, they must install and use their own certificate-generating service. Microsoft provides such a service with Microsoft Certificate Server, an optional component of Windows 2000 or the Windows NT 4.0 Option Pack.

When you use your own certificate server, the onus for distributing your CA Root certificate to clients falls upon you. In practical terms, this means you must install your own Root certificate on the NFuse Web server (if SSL Relay is used to protect XML traffic) and on each ICA Client device.

Server Software and Licensing

MetaFrame XP 1.0 Service Pack 1 and Feature Release 1 licenses must be installed on all servers in the farm where SSL client connectivity will be required. As a best practice, do not maintain a mixture of service pack or feature release levels among the MetaFrame servers in your farm. Upgrade all servers to Service Pack 1 and assign Feature Release 1 licenses to all servers.

Troubleshooting Licensing Issues

1. In the Citrix Management Console, inspect the installed license numbers and view the License tab for each MetaFrame server. Server licenses are drawn from the license pool automatically; if not, you can assign licenses to particular servers.

2. Ensure that the feature release level is set for each MetaFrame server; right-click the server name and select Set Feature Release Level.

3. At a command prompt, type clicense strings and ensure that the output matches what you observe in the CMC.

DNS Name Resolution

For SSL connections to take place, clients must initiate a connection to the MetaFrame server using a Fully-Qualified Domain Name (FQDN), such as metaframe.company.com. To enable DNS name resolution in your server farm after installing SP1/FR1:

1. Open and log on to the Citrix Management Console (CMC).

2. In the left-hand pane, right-click the farm name and select Properties. 3. View the MetaFrame Settings tab.

(8)

! Using the Citrix® SSL Relay Service™ ₅

Troubleshooting DNS Name Resolution

1. On the MetaFrame server, view the properties of the server or type ipconfig /all at a command prompt to ascertain the DNS domain suffix.

2. From a client device, try to ping the FQDN of the MetaFrame server. Even if ICMP traffic is blocked, preventing you from getting a ping reply, you can confirm that the client is able to resolve the server’s FQDN to an appropriate IP address.

3. DNS name resolution in an NFuse environment requires the SP1 version of the XML service on all MetaFrame servers. To ensure that your XML service is up-to-date, check the timestamp of the Wpnbr.dll file on each server and verify that it was modified on August 9, 2001 or later. If you are running the standalone Citrix XML Service, check the Wpnbr.dll file beneath %SystemRoot%\system32; if you are using IIS Port Sharing, check the Wpnbr.dll file beneath \Inetpub\Scripts.

SSL Relay Service

The Citrix SSL Relay Service is a MetaFrame server component that provides encryption, authentication, and forwarding capabilities. This service can be installed on any MetaFrame server; it must be installed on all MetaFrame servers to which clients will attempt SSL connections. Typically, the Citrix SSL Relay Service listens for encrypted SSL traffic on TCP port 443 and decrypts and forwards information to other services on the MetaFrame server, such as the XML service or the ICA listener.

Using the SSL Relay with NFuse and the Citrix XML Service

(9)

Under normal circumstances, the NFuse Web server sends XML data in plain text across the network to the Citrix XML Service running on port 80 at the MetaFrame server. This XML data stream can include usernames, weakly-scrambled passwords, and application lists. When configured for use with SSL Relay, this XML data is first subjected to strong encryption by the NFuse Web extensions and sent to the SSL Relay Service on port 443 of the MetaFrame server. The SSL Relay decrypts and relays the XML data internally to the XML service so that clear-text XML is never visible on the network.

Using the SSL Relay with ICA Clients

The Citrix SSL Relay has been available for encrypting XML traffic since the introduction of NFuse 1.5. The same model can now also be applied to ICA traffic between end users and the MetaFrame server:

The ICA Version 6.20 Client encrypts all ICA traffic using SSL before releasing packets onto the network. When the traffic reaches the MetaFrame server, the SSL Relay Service decrypts the ICA traffic and forwards it to the ICA listener on port 1494. Version 6.20 ICA Clients are available for the following platforms:

" 32-bit Windows

" Java

" Windows CE (WBT and HPC)

" Linux

" Macintosh

Installing and Configuring the SSL Relay Service

Versions of the SSL Relay Service are included with the following Citrix deliverables: MetaFrame 1.8 for Windows, Service Pack 2

" MetaFrame XP 1.0 for Windows

" MetaFrame XP 1.0 for Windows, Service Pack 1

(10)

! Using the Citrix® SSL Relay Service™ ₇ Specific instructions for installing and configuring the SSL Relay Service are included in the respective Administrative Guides for these products. But a general outline of installation in all cases involves the following steps:

Obtain a server certificate matching the Fully-Qualified Domain Name (FQDN) of your MetaFrame server. 1. Copy the certificate to the SSL Relay’s keystore\certs folder.

2. Configure a listening port and authorized forwarding addresses. 3. Start the SSL Relay Service process.

(11)

On the Connection tab, you can control to what addresses and ports the relay is permitted to forward decrypted traffic. By default, the SSL Relay protects XML traffic only, which is typically sent to the server on port 80. To enable ICA over SSL, edit the server address entry and add port 1494 to the list of allowed ports:

(12)

! Using the Citrix® SSL Relay Service™ ₉ Unless you are a government organization with strict encryption regulations, you do not need to disable any ciphersuites. You can either run the Citrix SSL Relay as a Windows NT service or run it from a command prompt by typing

SSLServerRelay.exe in the SSLRelay directory beneath %SystemRoot%. Running SSLServerRelay.exe from a command prompt offers the advantage of visible connection and error messages as the relay is used. Sample output is shown below:

D:\WINNT\SSLRelay>sslserverrelay ******************************************** Citrix SSL Relay

1.1.1.1.1.1 Version 1.01

10/12/2001 12:42:42 PM: Negotiating with Service Control Manager, please wait... 10/12/2001 12:42:57 PM: Using SSL provider Citrix SSL interface v1.04

10/12/2001 12:42:58 PM: Waiting for incoming connections. 10/12/2001 12:43:22 PM: Accepting connection from 10.3.7.69

10/12/2001 12:43:22 PM: Client requested connection to server.company.com:80 10/12/2001 12:44:12 PM: Accepting connection from 10.3.7.69

10/12/2001 12:44:12 PM: Client requested connection to server.company.com:1494

Configuring ICA Clients to use SSL

SSL capabilities were introduced into the line of Citrix ICA Clients beginning with Version 6.20. Earlier versions of ICA Clients do not support ICA over SSL. The examples that follow focus on the configuration of the 32-bit Windows Client, but the same concepts apply to Version 6.20 ICA Clients for Linux, Macintosh, and Java.

(13)

With this preference in place, the client attempts to communicate with both the XML service and the ICA listener using SSL encryption on port 443. This corresponds to the following INI settings that can be used in Appsrv.ini or ICA files: SSLEnable=On

(14)

! Using the Citrix® SSL Relay Service™ ₁₁ A primary requirement for the use of SSL from the Citrix Program Neighborhood client is that users must connect using the DNS name of the MetaFrame server. This DNS name must exactly match the name on the MetaFrame server’s SSL certificate. If clients attempt to connect to a server by IP address, the following error message appears:

If clients attempt to connect using a DNS name that does not match the server’s certificate, the following error message appears:

These restrictions are in place to ensure that your server farm is not vulnerable to a man-in-the-middle attack, whereby a malicious attacker would attempt to route your users to a duplicate MetaFrame server and steal their passwords.

Configuring an NFuse Web Server to Use SSL

When users connect to published applications through an NFuse 1.6 Web site, some special considerations need to be in place to ensure that applications published with SSL encryption enabled will launch successfully.

Not HTTPS

Bear in mind that Citrix SSL Relay communications do not affect HTTP traffic between an end user’s Web browser and the NFuse Web server. To protect this data, follow your Web server’s documentation for enabling SSL. When SSL is enabled for published Web pages, users need to access your Web site using an https:// URL.

Enabling HTTPS traffic to the Web pages published by your Web server requires a server certificate matching the FQDN of your Web server. This is often confused with the CA Root certificate required if NFuse is to act as a client to the Citrix SSL Relay and encrypt XML traffic between the Web server and a MetaFrame server. In a completely secured

(15)

Enabling ICA Over SSL With NFuse Version 1.6

Follow the steps below to take advantage of the SSL capabilities built into the Version 6.20 clients: 1. Using notepad, edit the %SystemRoot%\java\trustlib\NFuse.conf file.

2. Change the AddressResolutionType value from IPv4-port to DNS or DNS-port. 3. Save your changes.

4. At a command prompt, type IISRESET to restart Web services.

Unless you are using an ICA port other than 1494, all you need to do is set AddressResolutionType=DNS. Note that DNS name resolution requires a Feature Release 1 license on all MetaFrame XP or MetaFrame 1.1 for UNIX servers that host published applications.

Enabling XML Over SSL With NFuse Version 1.6

While it is not necessary to allow ICA over SSL connectivity in your server farm, you may want to use the Citrix SSL Relay to encrypt the XML data that passes between your NFuse Web server and the MetaFrame server hosting the XML service for NFuse. Because the NFuse Java objects on your Web server act as an SSL client to the MetaFrame server’s XML and SSL Relay services, install the CA Root certificate on the NFuse Web server.

The process for installing the root certificate for use with NFuse is not the same as for an ICA Client. Because NFuse is written in Java and may run on a non-Windows Web server, an independent method was developed for locating the appropriate root certificate.

The following instructions pertain to NFuse 1.6 running on a Microsoft IIS server. For instructions that pertain to other Web servers, see the NFuse 1.6 Administrator’s Guide.

To install the root certificate and enable SSL Relay on your NFuse 1.6 Web server, follow these steps: 1. Copy your root certificate (not a server certificate!) to your Web server’s hard drive in the

%SystemRoot%\keystore\cacerts directory.

2. Add or modify the following entries in %SystemRoot%\java\trustlib\NFuse.conf, changing the italicized portions to match your environment:

SessionField.NFuse_RelayServer=metaframe-server.company.com

SessionField.NFuse_RelayServerPort=443

SessionField.NFuse_Transport=SSL SslKeystore=D:\\WinNT\\keystore\\cacerts

(16)

! Using the Citrix® SSL Relay Service™ ₁₃

Appendix A: Creating Certificates with

Microsoft

®

Certificate Services

™

The following is a step-by-step guide for creating and using your own SSL certificates using Microsoft Certificate Services. In this scenario, you will act as your own Certifying Authority. This saves you money because you do not have to purchase certificates from public certifying authorities like Verisign or Baltimore, but at the same time adds the burden of distributing and installing your CA Root certificate on all client devices.

Before you begin, install IIS and Certificate Services on a domain controller. You can then reach your Certificate Server by pointing a Web browser to http://servername.company.com/certsrv/. When this is completed, there are two main steps to complete:

" Generate and install server certificates for each MetaFrame server running the Citrix SSL Relay Service

" Distribute and install your CA Root certificate on all client devices

Generating and Installing a Server Certificate

Your certificate server is capable of generating SSL server certificates that uniquely identify a MetaFrame server by its Fully-Qualified DNS Name (FQDN). In this example, the FQDN of the MetaFrame server is

metaframe-server.company.com. The type of certificate each MetaFrame server needs is referred to as a Web Server certificate; it is

the same type of certificate that can be used to protect HTTPS traffic in IIS.

To create a server certificate for your MetaFrame server that can be used by the Citrix SSL Relay Service, follow these steps:

(18)

! Using the Citrix® SSL Relay Service™ ₁₅ 2. Select Request a certificate and click Next. The following screen appears:

(19)

4. Select Submit a certificate request to this CA using a form and click Next. The Advanced Certificate Request dialog box appears:

5. Change the certificate template to Web Server and complete the information for your company. Be sure to enter the MetaFrame server’s FQDN in the Name field:

(20)

! Using the Citrix® SSL Relay Service™ ₁₇ 7. Leave the Additional Options section as it is and click Submit. The following confirmation message appears.

However, this Microsoft-specific certificate is not usable by the Citrix SSL Relay Service in this form. The

certificate must be extracted to a file and converted to a standard certificate format. The following steps explain how to do this.

(21)

9. Click the Certificates button; your server certificate appears on the Personal tab:

(22)

! Using the Citrix® SSL Relay Service™ ₁₉ 11. Click Next to move to the second portion of the Certificate Export Wizard.

12. Select Yes, export the private key.

(23)

14. Select Enable strong protection and click Next. The Password dialog box appears:

15. Choose a password to protect the private key that will be added to this file. Remember this password. 16. Click Next. The File to Export dialog box appears:

(24)

! Using the Citrix® SSL Relay Service™ ₂₁ 18. From a command prompt, change into the %SystemRoot%\SSLRelay\keystore\certs directory. Convert the PFX file

to a PEM-formatted certificate using the keytopem.exe utility included in the SSLRelay folder. (Because the program is not in your command path, call the executable by typing ..\..\keytopem.exe) The syntax for keytopem is: keytopem pfx-filepem-certificate-file

You will be prompted for the private key password that you created in Step 15:

This creates a file named Mfserver.pem that can be used by the Citrix SSL Relay Service.

19. Launch and configure the SSL Relay Configuration Tool (SSLRelayConfig.exe) as described in the Installing and Configuring the SSL Relay Service section.

20. Click OK to complete the SSL Relay configuration. If this is the first time you have configured the SSL Relay Service, you will be prompted to register the Citrix SSL Relay as a service. Click Yes to do so.

Important: In some cases, your certificate will not work properly until the day after it is created. If you experience trouble making SSL connections on the day that the server certificate is created, try waiting one day or temporarily set your computer’s clock forward by one day.

(25)

Installing your Root Certificate on ICA Client Devices

Because you created your own Certifying Authority, Windows clients will not implicitly trust your MetaFrame server certificates. To establish the trust required to make an SSL connection to the relay service, all SSL clients must install the Root certificate from your Certificate Server. SSL clients include ICA Clients (for ICA/SSL traffic) and any NFuse Web server (for ICA/XML traffic).

To obtain your root certificate, follow these steps:

(26)

! Using the Citrix® SSL Relay Service™ ₂₃ 2. Check the radio button next to Retrieve the CA certificate or certificate revocation list. Click Next. The Retrieve

the CA Certificate or Certificate Revocation List dialog box appears:

(27)

5. Distribute this file to all end-users and instruct them to install the certificate on their servers. To install the certificate, double-click the Rootcert.cer file:

6. Click Install Certificate… and accept all defaults as the Certificate Import Wizard runs.

(28)

using ssl relay

By Jay Tomlin

Table of Contents

Overview...1

SSL Relay Service...5

Not HTTPS...11

Overview

Server Software and Licensing

Client Device

Introduction to Secure Sockets Layer

Server Software and Licensing

DNS Name Resolution

Troubleshooting DNS Name Resolution

SSL Relay Service

Installing and Configuring the SSL Relay Service

D:\WINNT\SSLRelay>sslserverrelay ******************************************** Citrix SSL Relay

10/12/2001 12:44:12 PM: Client requested connection to server.company.com:1494

Configuring ICA Clients to use SSL

Configuring an NFuse Web Server to Use SSL

Enabling ICA Over SSL With NFuse Version 1.6

Enabling XML Over SSL With NFuse Version 1.6

Further Reading

Appendix A: Creating Certificates with

Generating and Installing a Server Certificate

Installing your Root Certificate on ICA Client Devices

the CA Certificate or Certificate Revocation List dialog box appears: