How to set up secure access to your X display

There are several ways to have X11 applications running on remote machines to display on your local desktop. These methods are described below in order from most secure to least secure. The methods described in this HOWTO are:

SSH tunneling
Direct display using XAuth
Direct display without access control

Any or all of these methods can be used simultaneously. In fact, we recommend using the most secure method (SSH tunnelling) by default, and using the less secure methods for particular applications only if display performance is a problem.

A note on terminology: In X land, the X "client" is the application, and the X "server" is the software managing your local display, even though in context of running applications remotely, we tend to call our local machine a "client" and the remote machine a "server". This document will use this accepted terminology because it is precise (the X server is providing access to the local display as a service, the remote machine is providing a platform to run applications as a service), but additional descriptive info will be provided throughout to minimize confusion.

In this document, the remote machine is assumed to be a UNIX/Linux-based system.

SSH tunnelling (most secure).

This method works by tunnelling all X traffic through your SSH connection. As far as the X server (your display) is concerned, X traffic will appear on the local side of the SSH connection, looking like it is coming from the local (desktop) machine, even though the X traffic originated from an X application running on the remote machine. Moreover, this traffic will be encrypted, thereby protecting private info you might potentially send through the X interface (by typing passwords, for example). This has the further benefit of working through firewalls that are set up to allow only "trusted" ports through (ssh, for example). Windows systems running X display software may encounter a significant performance penalty when using the SSH tunnelling/encryption method. However, the penalty is minimal when your display machine is a Linux/UNIX system. If you encounter major performance degradation, consider the XAuth method below.

Do the following to set up SSH tunnelling:

On Windows using F-Secure SSH/X-Win32:
Assuming you have enabled X11 tunneling in your F-Secure SSH profile and added "localhost" to your XHost list in X-Win32 (as described in HOWTO: Display Graphics from Golgi using X-Win32 on Windows), just starting X-Win32 will suffice. Now any graphical application run on the remote machine through the secure shell should display on your local machine.
On Linux/UNIX:
On your desktop machine, the following line:
```
  ForwardX11 yes
```
should occur either in the system-wide ssh_config file (/etc/ssh/ssh_config) or your per-user config file (${HOME}/.ssh/ssh_config) before you connect. Then connect as usual. ssh will automatically take care of providing access to your desktop X display (assuming you own your X display). Alternatively, you can add the "-X" option to ssh when connecting:
```
  ssh -X golgi.biac.duke.edu
```
Now any graphical application run on the remote machine through the secure shell should display on your local machine.

Direct display using XAuth (partially secure)

The XAuth method of access control ensures that X applications have authorization before allowing them to connect to an X server. Authorization credentials take the form of a display-specific "magic cookie" that the X application must present to the X server. If the cookie matches with the one that the server has, then it will allow access to that application. By using this access method, X traffic can be sent without tunneling, directly to the X display. Though X traffic is not encrypted, this is an acceptable solution if your network itself is reasonably secure (i.e. the switched network within BIAC), and if your "cookie" files are protected (not readable by anyone else).

Do the following to set up XAuth:

Set up a display key on the remote machine
- If you are connecting to golgi:
  
  Connect to golgi using your favorite SSH program. Run the following command:
```
  addxauthkey my.display.machine.edu:0
```
  (replace "my.display.machine.edu" with the name of your desktop machine). Note the colon-zero (:0) immediately following the display machine's host name. This will add a randomly generated 128-bit cookie to your personal ${HOME}/.Xauthority file on golgi, and also will merge this new key into your BIAC personal .Xauthority file in \\gall\users\USERNAME\Profile\.Xauthority. This step needs to be performed once on golgi for each machine on which you wish to display.
- If you are connecting to another UNIX/Linux system:
  
  Run the following command:
```
  xauth add my.display.machine.edu:0 . XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
```
  (replace "my.display.machine.edu" with the name of your desktop machine, and replace "XXX..." with a random 32-character hexadecimal string of characters taken from the following set: "0123456789abcdef"). Note the colon-zero (:0) immediately following the display machine's host name, and the single dot (.) [representing the MIT-MAGIC-COOKIE-1 protocol] as the third argument to xauth. This will add the 32-character (128-bit) cookie to your personal ${HOME}/.Xauthority file on the remote machine. This step needs to be performed once on the remote system for each local machine on which you wish to display.
Set up your display to recognize the new key
- If you are connecting from a BIAC Windows machine:
  
  Your system is already set up to recognize the new key in your Profile's .Xauthority file (if not, check the registry with regedit as described below).
- If you are connecting from a non-BIAC Windows machine:
  
  Because your display machine does not necessarily have access to your BIAC Windows profile, you need to copy that file to your local display machine using the Secure copy functionality of your SSH program. Copy the .Xauthority file either from the remote machine (typically /home/USERNAME/.Xauthority), or if the remote machine is golgi and you used
```
addxauthkey
```
  , you can also copy it from gall (\\gall\users\USERNAME\Profile\.Xauthority) to a secure, private folder on your local machine.
  
  You need to tell X-Win32 to use this file to authorize access (you only need to do this once). Go to Start::Run, type "regedit" in the box, and click OK. In the registry editor, navigate to HKEY_CURRENT_USER::Software::StarNet::X-Win32, right-click on the X-Win32 folder, and add a New String Value called "XAuthFile". Once this new value is created, right-click on XAuthFile, and "Modify" the value to be the full pathname to your .Xauthority file (such as u:\MYNAME\Profile\.Xauthority). Here is what it should look like when you're done:
  
  Exit regedit and restart X-Win32. Verify that you can display on your machine by running
```
  xclock -display my.display.machine.edu:0 &
```
  on the remote machine.
- If you are connecting from a Linux machine:
  
  Merge the new keys from the remote machine to your local machine using the following command from your local machine:
```
  ssh their.remote.machine.edu xauth extract - my.display.machine.edu:0 | xauth merge -
```
  Verify that you can display on your machine by running
```
  xclock -display my.display.machine.edu:0 &
```
  on golgi.

Direct display without access control (not secure, not recommended)

This method bypasses the authorization mechanisms provided by the X server. This method is not documented because it is highly insecure.