<?xml version="1.0" encoding="ISO-8859-1"?>
<document url="http://openejb.sf.net/cvs_ssh_windows_guideline.xml">
  <body>
    <title>Working CVS and SSH under Windows</title>
    
    <section title="Abstract">
    </section>
    
    <section title="Installing the PuTTY program">
      <p>
      PuTTY is a fully featured SSH client for Windows operation systems.
      PuTTY is available from the PuTTY <a href="http://www.chiark.greenend.org.uk/~sgtatham/putty/download.html">web site</a>.
      </p>
      
      <p>
      Note: You need a couple of binaries, the PuTTY program itself
      is not enough.
      <ul>
        <li>PuTTY.exe - The SSH client</li>
        <li>PSCP.exe - A secure copy program</li>
        <li>PLINK.exe - a command-line interface to the PuTTY back ends</li>
        <li>PAGEANT.exe - an SSH authentication agent for PuTTY, PSCP and Plink</li>
      </ul>
      </p>
      
      <section title="Including your PuTTY binaries in your default PATH">
        <p>
        You have to include the PuTTY binaries mentioned above in
        your system's default PATH. To do so add the path to your
        PuTTY binaries like the ollowing the your system's PATH
        environment variable.
        
        <pre><![CDATA[
        set PATH=C:\PROGRAM FILES\PUTTY;%PATH%
        ]]></pre>
        
        Note: This is just an example!
        </p>
        
        <p>
        To test your PuTTY installation, you can try to type the following
        command at the command prompt of a dos box.
        
        <pre><![CDATA[
        plink [developername]@shell.sourceforge.net
        ]]></pre>
        
        Change [developername] to your SF developer name. If the command
        succeeds you should be able to login to the SF system.
        </p>
        
        <p>
        <img src="images/plink_one.gif" alt="first access to a SF server using plink" border="0"/>
        
        
        <body-note>Figure 1: Accessing the SF server without having a public key installed on it.</body-note>
        </p>
      </section>
      
      <section title="How to generate your public/private RSA key">
        <p>
        SSH works with a private/public asymetric key scheme like it does
        PGP or other asymetric krypto systems. This fact requires that
        you generate a public/private key pair to use WinCVS with SSH (PuTTY).
        </p>
        
        <p>
        Generating these keys using the PuTTY key generator (PUTTYGEN.exe) is pretty easy.
        Just press 'generate' and move your mouse over the blank area until the key
        gets generated.
        </p>
        
        <p>
        After the procedure has finished you have to save the private/public key
        pair in a _SECURE_ place on your system by using the 'save public/private'
        buttons.
        </p>
        
        <p>
        Usually the private key is named ...
        
        <pre><![CDATA[
        identity
        ]]></pre>
        
        and the public key is named ...
        
        <pre><![CDATA[
        identity.pub
        ]]></pre>
        </p>
        

        <p>
        <img src="images/keygen.gif" alt="generating a public/private key pair" border="0"/>
    
        <body-note>Figure 2: The PuTTYgen program to generate a public/private key pair.</body-note>
        </p>
        
        <section title="A word from the wise (security note)">
          <p>
          The private key should _NEVER_ leave your system! Keep it as private
          as possible!
          </p>
        </section>
        
        <section title="How to install the public key on the SF system">
        
          <section title="Installing your public key manually">
            <p>
            The following section is just to demonstrate how the SSH
            public/private key system works. To get the public key installed
            on the SF OpenEJB CVS server you have to use SF's web based form
            for submiting public RSA keys.
            </p>
          
            <p>
            If you want to install your public key manually on one of the SF
            servers, you have to perform a few steps.
            <ul>
              <li>copy your key onto the SF server using secure copy</li>
              <li>logon the SF server using plink</li>
              <li>creating a .ssh directory.
              </li>
              <li>moving your public key in this newly created directory</li>
            </ul>
            </p>
            
            <p>
            The two figures below illustrate the processes described above.
            </p>
            
            <p>
            <img src="images/using_pscp.gif" alt="using PuTTY secure copy" border="0"/>
    
            <body-note>Figure 3: The PuTTYgen secure copy program to copy files in a secure manner.</body-note>
            </p>
            
            <p>
            <img src="images/installing_key.gif" alt="installing the public key on a SF server" border="0"/>
    
            <body-note>Figure 4: A few steps to a fully working SSH enabled SF account.</body-note>
            </p>
          </section>
        
          <section title="Installing your public key using the SF upload form">
            <p>
            The SF upload form for public RSA/DSA keys can be found at your account
            options page of your SF personal page.
            </p>
          
            <p>
            If you are using the SF web based form, your public key gets distributed
            within six hours to the following systems.
        
            <ul>
              <li>The OpenEJB SF server (openejb.sf.net)</li>
              <li>The SF shell server (shell.sf.net)</li>
              <li>The OpenEJB CVS server at SF (cvs.openejb.sf.net)</li>
            </ul>
            </p>
            
            <p>
            <img src="images/sf_key_upload.gif" alt="installing the public key using the SF upload page" border="0"/>
    
            <body-note>Figure 5: Here we go - The allready mentioned SF upload page for public keys.</body-note>
            </p>
          </section>
        </section>
        
        <section title="How to start and configure the PuTTY SSH agent">
          <p>
          The PuTTY SSH agent manages all your private RSA/DSA keys.
          </p>
          <p>
          Launching the PuTTY SSH agent is very easy - just execute the
          program 'PAGEANT.exe'. After starting the agent a new icon should
          reside in your system tray.
          </p>
          
          <section title="How to add a private key to the PuTTY SSH agent">
            <p>
            By openeing the PuTTY SSH agent you are able to add your private
            RSA/DSA key. Be carefull you have to use your private key (identity)!
            </p>
            
            <p>
            From now on the PuTTY SSH agent will log you in to any remote
            system which has your public key installed on it. No need to type passwords
            any more.
            </p>
            
            <p>
            <img src="images/pageant.gif" alt="adding privat keys to the PuTTY SSH agent" border="0"/>
    
            <body-note>Figure 6: The PuTTY SSH agent with a allready installed private key.</body-note>
            </p>
            
            <p>
            <img src="images/pageant_tray.gif" alt="pageant residing in your system tray" border="0"/>
    
            <body-note>Figure 7: The PuTTY SSH agent is allways accessable due to this system tray icon.</body-note>
            </p>
          </section>
          
          <section title="Testing your private/public keys">
            <p>
            </p>
            
            <p>
            <img src="images/plink_two.gif" alt="Using plink in conjunction with pageant" border="0"/>
    
            <body-note>Figure 8: Using Plink without the need of providing a password.</body-note>
            </p>
          </section>
          
          <section title="A word from the wise (security note)">
            <p>
            Never leave your computer alone while running the PuTTY SSH agent!
            With the use of this agent, everybody might login to the SF servers
            without even having to know your password.
            </p>
          </section>
        </section>
      </section>
    </section>
    
    <section title="Configuring WinCVS to work with SSH (PuTTY)">
      <p>
      There are just a few steps left until you will have a fully working CVS/SSH couple ;-)
      </p>
      
      <section title="Making changes to the CVSROOT variable">
        <p>
        If you want to use WinCVS in conjunction with SSH you have to use
        the SSH authentication method (aka :ext)
        
        The figure below shows my basic WinCVS settings.
        </p>
        
        <p>
        <img src="images/cvs_basic.gif" alt="basic changes to WinCVS" border="0"/>

        <body-note>Figure 9: These are the basic settings wich have to be set inside WinCVS.</body-note>
        </p>
      </section>
      
      <section title="Additional but important WinCVS options">
      <p>
      Finally you have to provide the SSH binary which should be used by
      WinCVS. In our case this is PLINK.exe.
      </p>
      
      <p>
      <img src="images/cvs_advanced.gif" alt="advanced WinCVS settings" border="0"/>

      <body-note>Figure 10: Providing the SSH binary to WinCVS.</body-note>
      </p>
      
      <p>
      From now on you should be able to work with CVS using SSH as you
      did earlier without SSH.
      </p>
      </section>
    </section>
  </body>
</document>
