Tunneling with SSH2

Last updated 2005-02

Contents

Back to Main Help Index

About This Guide

The purpose of this guide is to enable users to tunnel (connect) to OpenOffice.org using SSH2 (Secure Shell 2). This guide helps you create the certificate (also called the public key) used by SSH2 servers, and send that certificate to the OpenOffice.org administrator. Next it explains how to create a secure "tunnel" (or connection) between your machine and OpenOffice.org using this certificate. This guide only seems long. Much of the material is repeated and tailored to suit the needs of particular clients.

Tunneling is not hard. But it is more difficult using Windows than, say, Linux or Solaris or Mac OS X. If you don't get it the first time, don't hesitate to ask for enlightenment on the support@website.openoffice.org list or on the issue that holds your public key. Also, if you want to improve this guide, please do so by submitting your ideas to support@website.openoffice.org.

This guide also gives the basics on how to use CVS after set up of the SSH tunnel.

About SSH2

SSH2 is a flexible and more secure replacement for telnet and rlogin, and SSH1. It is widely used in development projects to provide access control and data-transport security. SSH2 can be used to create an unobtrusive, transparent "port tunnel" to the CVS (concurrent versions system) server. SSH2 uses encrypted certificates (a public/private key pair) to verify the user's identity and to transmit data. Data sent through the tunnel is encrypted, but the process is invisible to you and to the client software you are using to access the CVS repository.

Step 1. Previewing the Process

This is what you have to do:

  1. Depending upon your operating system, find or install a terminal with port forwarding (or tunneling) capabilities. OpenOffice.org uses the OpenSSH protocol.
  2. Generate a public/private key pair (the certificate).
  3. File an issue, attach the public key to the issue, then wait for email that says the key has been uploaded.
  4. Be sure you are a member of the project (you can see your role in the project members list), then ask the project owner for the content developer or developer role.
  5. If all the above is done, you are ready to commit updated or new files to your project's web space!

Step 2. Setting Up the Client

Linux, Unix, Solaris | Cygwin for Windows | Putty for Windows | MacCVSPro for Macs

Linux (or some other Unix variant): Go to Tunneling, where you will learn the key elements of establishing an SSH2 tunnel in a Unix-like environment.

Windows clients: Find a client that places a terminal on your desktop to generate a public/private key file set and establish a tunnel. Use either Cygwin or PuTTY. Of the two, we recommend Cygwin, as it works well; although setup can sometimes be difficult. For PuTTY, there are reported security risks in earlier versions, so use PuTTY version 0.57 or later.

Mac clients: Find a client that places a terminal on your desktop to generate a public/private key file set and establish a tunnel. MacCVSPro is the recommended GUI client for using CVS on Mac OS X; it is easy to use and robust.

Linux, Unix, Solaris | Cygwin for Windows | Putty for Windows | MacCVSPro for Macs

Using Cygwin

Cygwin, from Cygnus Solutions, provides a nearly full Unix environment on your Windows desktop. Cygwin can be found at http://www.cygwin.com/. To install and configure Cygwin, read our instructions. (These instructions also detail how to create a set of keys.)

Using PuTTY

PuTTY is easy to use, but the keys generated need some adjustment. You can download PuTTY from http://www.chiark.greenend.org.uk/~sgtatham/putty/. Instructions on setting it up, generating keys, and forming a tunnel with port forwarding can be found in the PuTTY User Manual. See also the very good, "How to make a tunnel from PuTTY." The key values are the same as for the Cygwin tunnel, so no repetition is needed. Willy Sudiarto Raharjo has succeeded in creating tunnels to OpenOffice.org using PuTTY plus Pageant (PuTTY Authentication Agent), downloaded from the same website as PuTTY. He also writes Guide about Creating Tunnel with PuTTY.

Configuring the Mac OS X CVS Client

MacCVSPro is the recommended GUI client for using CVS on Mac OS X; it is easy to use, robust, and allows for port forwarding, which is crucial. A hint: you must create a folder for the CVS files. This can be done within the client or outside. I suggest you do it first, and that you clearly identify your folder.

The above information should be all you need. If you receive error messages, you may not have correctly set up your tunnel or have a bad password. As well, be sure to put the preceding slash "/" before the cvs (lowercase) root. If it's not there, you won't be able to checkout material.

Step 3. Tunneling

Generating the Keys with Cygwin and Linux

  1. Open Cygwin or a Linux terminal. If properly configured, the working directory should start in your home directory. To check that it does, type in pwd at the prompt. (The command requests bash to respond with the working directory.) If the answer does not correspond to your home directory, type cd at the prompt. This relocates the working directory to your home directory.
  2. Enter ssh-keygen -d at the command prompt. This commands the system to generate an SSH2 key (the -d extension specifies a DSA or SSH2 key). Depending on the speed of your processor, it could take anywhere from several seconds to several minutes. When finished, it will prompt you for a file in which to save the key. You should accept the default; or, you can specify a file and directory in which to save the key, but doing so can be a pain, unless you are familiar (or wish to be become familiar) with Unix file structures.
  3. You will then be asked to enter a passphrase. You must enter a passphrase. Your key will not work unless you enter one. Remember this passphrase: you will be asked for it every time you log into the SSH2 server to which you have connected using this public key.
  4. If you have entered a passphrase correctly (and you will be asked twice to be sure you aren't typo-ing your way into a mistake), you will then be told that the "identification" has been saved in the file you stipulated, and that the "public key" has been saved in a file bearing that same name but with a .pub suffix. The .pub signifies that it is the public key.
  5. For details on submitting the key, see the section below, "Submitting Your Certificate (Public Key).
  6. Note: you are going to use CVS via the tunnel. Your CVSROOT needs therefore to point to your localhost to use the tunnel.

General commands for tunneling

Pointing CVSROOT to Your Localhost

Step 4. Submitting Your (Certificate) Public Key

Regardless of the way the public key has been created, it needs to be sent to OpenOffice.org and accepted by OpenOffice.org administrators.

  1. To submit the key, attach the .pub file as an attachment to an Issue Tracker issue. (To use Issue Tracker you must be registered; but, then, to actually use the key you have to be a registered user.) Assign it to "ssh2key" in the "www" component, ""openoffice.org website general issues"" subcomponent. Explain in the issue what modules you wish access to. (The key takes up one very long line; it cannot be broken into more than one line, and anything that does that violates the integrity of the key. That's why you need to attach the file to the issue.)
  2. CC the lead of the project for which you need the key. We will only accept keys that are authorized by the lead of the project.
  3. Once the issue has been resolved, you should be able to tunnel. If you still cannot, don't hesitate to discuss the problem with the support in the issue used for the key submission.

Step 5. Obtaining Project Roles

What to do after you have established a tunnel

Okay, you've come this far. If you've done everything right, you will have a tunnel on your desktop to the server housing the CVS repository. This tunnel is not a shell, i.e., you will not see any of the more or less familiar Unix elements, just a screen with the message, "Tunnel established. Type ctrl-c to exit".

What you must do now: Access the CVS repository. As mentioned before, this document does not focus on CVS but does give the elements. For more extensive documentation on how to use CVS, please see the Help on CVS or Miljenko Williams' excellent How-To. Both the documents discuss excellent and easy-to-use clients for Windows. The below is merely the basics plus a brief account on how to use SSH2/CVS with a Mac OS X client.

What to do if there are tunneling problems

Problems with tunneling are distinct from those having to do with CVS. Most problems occur because the key submitted does not work with OpenSSH, which is what the OpenOffice.org server uses.

The easiest way to resolve your problem is to contact us. Reopen, if needed, the issue used to file the original key. Then, ask support for assistance, explaining the problems you are encountering.

How to use CVS with a tunnel: Basics

The tunnel is a conduit for cvs data. When you initiate a tunnel following the instructions above, you are connecting to the CVS server. The tunnel, which is more a window into the server, becomes your designated CVS host. You need only supply the correct password for the CVS server; it is the same as your OpenOffice.org user password. Thus, the process is:

  1. Establish a tunnel. If it works, you will be asked for your passphrase (not password, a sign of failure)
  2. Initiate the CVS connection. You use :pserver; the server is "localhost" (the tunnel), and you use your regular OpenOffice.org username.
    • E.g., cvs -d :pserver:[username]@localhost:/cvs login
  3. The regular set of CVS commands obtains. Just keep in mind you are going through the localhost tunnel, that you are not connecting to the CVS server outside of the tunnel.

Terminating the tunnel

The easiest way to terminate the tunnel is to Ctrl-C (^C) it out of existence. In both the Mac OS and Windows environment, you can also close the client window, thereby shutting the tunnel down.

Useful links

Top | Help index