---

About this Guide

What this guide discusses. The purpose of this guide is to enable users to tunnel to OpenOffice.org using SSH2 (Secure Shell 2). This guide provides instructions for the creating the certificate (also called the public key) used by SSH2 servers and for sending that certificate to the OpenOffice.org administrator. It will also then explain how to create a secure "tunnel" between your machine and OpenOffice.org using this certificate. (Throughout this discussion, the term "public key" and "certificate" will be used interchangeably.) This guide only seems long. Much of the material is repeated and tailored to suit the needs of particular clients.

What this guide does not discuss. This guide does not explain in detail how to use CVS, only how to set up the tunnel so that you can use CVS. See the brief account of using CVS with a tunnel below.

Note: In order to tunnel to OpenOffice.org, you must first submit a public key (certificate); it must then be accepted; it will only be accepted if you have the authorization of your project lead and have submitted either a Joint Copyright Assignment or Public Document License and your name is on the "Copyright Approved" list. For more information, see the Contributing page.

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 or to the client software you are using to access the CVS repository.

Because it is easy to use and very secure, OpenOffice.org uses SSH2 for developers accessing the CVS repository.

Concepts

1. Using the right software
2. Creating the certificate
3. Establishing the SSH2 tunnel

Before you can establish an SSH2 connection, you have to find the right software, i.e., a client that places a terminal on your desktop, if you are using Windows or Mac OS 9 (Mac OS X has SSH2 capability built in). Fortunately, there are excellent clients that offer Windows and Mac OS users desktop terminals. The section below discusses them in detail. Of course, if you are using Linux (or some other Unix variant), then you can skip that section and go right to the section, "Tunneling" that describes the key elements in establishing an SSH2 tunnel in a Unix-like environment. And if you already are familiar with the these clients, then you can skip ahead to "Using the Desktop Terminal."

Once you have obtained and configured a client terminal, you must

1. Generate a public/private key pair (the certificate); and
2. File an issue and attach the public key to the issue. Assign it to ssh2key@openoffice.org in the "www" component

Generating the key is simple, and there are both commercially available and free clients that do the job for you. Sending the key then is only a matter of attaching it to an issue in which you explain which module you wish to access and assigning it to ssh2key@openoffice.org in the www.component.

The SSH2 Client

Platforms

Command Line: Linux, Mac OS X, Unix, Solaris. Linux supports SSH. To connect using SSH, see the "Tunneling" section below. As well, Mac OS X, via the "Terminal" application, allows you to generate a key pair, and establish a tunnel. This is no surprise, as it is using tried-and-true software. To establish the tunnel, follow the instructions as for Linux, with the exception being that the command for generating the DSA key in BSD is different: ssh-keygen -t dsa (though I have found that ssh-keygen -d also works).

MacOS 9.x. Hardly surprising, isn't it, that tunneling using Mac OS 9 is trivially easy? The concepts are the same as for Windows, Linux, or Mac OS X, as are the numbers, etc. But, in a nutshell, here's what you do. It's a two-step process. First, you must configure MacSSH, then configure the CVS client.

Configuring MacSSH

1. Download the latest version of MacSSH, which is characteristically easy to use, is free, Open Source, and offers superior performance.
2. Configure it by clicking on the "Favorites" pull-down menu in the top-navbar.
3. Click on the "New" button.
4. Enter a name for this favorite. If it is going to be your default, don't bother.
5. Host Name: openoffice.org
6. Port: 22
7. Terminal: default
8. Go now to "SSH2" tab.
9. Encryption: 3DES
10. Authentication: MD5
11. Compression: zlib
12. Method: Local TCP port forward
13. Local port: 2401
14. Remote host: localhost
15. Remote port: 2401
16. You now must initialize (create) your SSH2 key pair. Click on the "Initialize SSH" button. Follow instructions.
17. Export your key (that is, put it elsewhere) by clicking on the "Export" button.
18. Once your key has been loaded by the helpful and friendly staff at OpenOffice.org, you will be notified; and then you will be able to establish a tunnel.
19. And, as is the case with tunnels: once established, there is no shell. At most you will receive a message in a window saying that you are connected. That is all. Leave this open, though you may minimize the window.

Configuring Mac CVS Clients

There are several free and easy-to-use CVS clients for the Mac. Each has its shortcoming (among them being the inane similarity of names) but I prefer two: MacCVSPro, and MacCVSClient. Both allow port forwarding (so you can use the tunnel) and both are easily configured. The data is the same for both. As well, for both you must create a folder for he CVS files. This can be done within the client or outside. I suggest you do it first, and that you clearly identify your folder.

Note: I am providing all the information you may need. Not all this information is required by the clients.

• Remote Host information: localhost
• CVS Root: /cvs
• CVs User Name: The same as your OpenOffice.org login user name
• CVs Password: The same as your OpenOffice.org login password
• CVs command: CVS
• Port: 2401
• Method: Pserver
• Default Module: The module to which you have access.
• Do not allow "Auto Merge."

The above information should be all you need. If you receive error messages (a "1" in CVS), 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.

Windows. If you are using Windows (NT or 9x or 2K), then please use Cygwin. Cygwin, from Cygnus Solutions, provides a nearly full Unix environment on your desktop. Cygwin has been updated to load quickly and easily. It also generates the keys in the proper format for OpenOffice.org. We recommend Cygwin and do not recommend any other client.

Using Cygwin: Free and Open Source Unix Terminal Emulator

Generating the Key with Cygwin: Unix Commands

1. Open Cygwin. If properly configured, Cygwin 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 in "cd." This relocates the working directory to your home directory.
2. Enter "ssh-keygen -d." This commands the program 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.

Tunneling with the Cygwin: Unix commands

• First, begin the program.
• At the prompt, enter "ssh -2 -x -L 2401:localhost:2401 tunnel@openoffice.org"
• The server should ask you for your passphrase. Enter it. If the passphrase is entered wrongly, the server will immediately ask for your password. This request indicates a failure. You should try again, and hope for better luck.
• If this is your first time, the server will send you a message along these lines:
  • Host key not found from the list of known hosts.
  • Are you sure you want to continue connecting (yes/no)?
• Enter "Yes." You can't just enter "y"; you have to spell it out.
• The server will then respond with: "Host "openoffice.org" added to the list of known hosts."
• The screen does not show a prompt. It may, at most, say something. That's how it should be. The tunnel has been established. You are now ready to begin using CVS.
• But: Your CVSROOT needs to point to your localhost to use the tunnel
• You can, at this point, minimize the terminal, but do not close it or enter Ctrl-C (^C). Doing so will kill the terminal tunnel.

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 IssueZilla issue. (To use IssueZilla you must be registered; but, then, to actually use the key you have to be a registered user.) Assign it to "ssh2key@openoffice.org" in the "www" component. 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. We will then send you an acknowledgment alerting you of your ability to use the certificate to tunnel to OpenOffice.org. Should you run into difficulties, do not hesitate to contact ssh2key@openoffice.org.
3. Note: Your CVSROOT needs to point at your localhost to use the tunnel

What to do after you have 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 perplexingly blank screen, and a message indicating when you last logged in.. And this is the way it should be.

What you must do now: Log on to CVS. As mentioned before, this document does not touch upon CVS protocols, only how to establish an SSH tunnel. But, to emphasize the issue, the establishment of the tunnel is distinct from loggin into the CVS repository. The tunnel only enables you to log in. For documentation on how to use CVS, please see the Help on CVS.

See below, How to use CVS with a tunnel.

See also the new document generated by Miljenko Williams of Website that does a fine job of explaining not only tunneling and Cygwin, but also CVS.

How to use CVS with a tunnel

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: