Notes on getting Bazaar Explorer working with an SSH Agent, with an emphasis on Microsoft Windows

// LICENSE
// Copyright is hereby assigned to Canonical.

// NO WARRANTIES
// No warranty of accuracy or suitability for any purpose is expressed or implied.
// This document has been prepared with reasonable care but may be subject to errors and omissions.
// Recipient accepts all consequences deriving from the posession and/or use of this document and 
// specifically indemnifies and holds harmless the original author against all claims of real damages, 
// imaginary damages, statutory damages and brain damages.

// SPECIAL DISCLAIMER
// Notwithstanding the fact that this document describes certain cryptographic software, 
// this document is not to be construed as an inducement of any kind to install, use, 
// distribute or deal in crytographic software.
// It is your responsibility to ensure that your actions are legal under all applicable laws.


Our objective is to securely share bzr branches with a team of developers, who may have no knowledge of GNU/Linux or SSH, over communication channels of unestablished trustworthiness.  These notes do however assume that *you* are familiar with these systems and tools and are designed to help you help your developers.

We're going to assume that the shared bzr branches will be hosted on a GNU/Linux machine with hostname "elcentro" running an OpenSSH server.   We'll call elcentro "the server" because it runs sshd, even though bazaar itself uses a decentralized (distributed) architecture.  

First, make sure the server 'elcentro' has the following installed

				openssh-server
				bzr (includes the bzr smartserver)

Next, make sure the following packages are available on each developer's machine, depending on whether it is a Windows or GNU/Linux machine:

	GNU/Linux:
				openssh-client
				bzr (obviously)
	
	Windows:
				PuTTY [http://www.chiark.greenend.org.uk/~sgtatham/putty]
				bzr (obviously)


We'll also assume that the branches to be shared are owned in the GNU/Linux account permissions sense by a user named 'ardilla' with password 'secreta'.  The user ardilla will be the operator responsible for administering the use of bzr and branches on elcentro, but absolutely should not be 'root' or an sudoer.  

Note that that the branches do not need to be in /home/ardilla'.  Wherever the branches are stored, they just need to be 'chown ardilla'.  Note that user ardilla does, however, need a home directory, because that's where the SSH public keys of the developers will be stored.  So if you were hoping tomake ardilla homeless, sorry, you can't.  We will discuss that in detail below.  The important thing here is that the branches on the server are perfectly ordinary bzr branches which happen to be owned by user ardilla.  

Each developer needs an RSA keypair [1] before she can interact with the branches.  RSA is a public-key
encrytion method [2] which will allow the server to authenticate the identity of each developer and also
securely encrypt all data in transit between developers' machines and the server.

You could do the following steps for each developer, but I recommend having developers do it themselves.  After all, why should they trust you not to keep a copy of their secret key?


1. Generate an RSA keypair on the developer's machine/account.

    On Linux, this is easily done with ssh-keygen.
    On Ubuntu and other distributions based on Debian, ssh-keygen is included in the openssh-client package.
    Running ssh-keygen is pretty easy, but of course it has a man page if you get stuck.

    On Windows, the PuTTY suite [3] is convenient and provides PuTTYgen to generate keys.
    Just run PuTTYgen from the PuTTY program group in the Windows Start menu and follow the friendly advice.
    One point to note!  Do not export the public key from PuTTYgen.  It is in a format which OpenSSH does
    not recognize.  Instead, copy-and-paste the public key from the read-only textedit control to a textfile
    called public.txt which we will use in the next step.
    
    Common Sense:
        Do not leave the passphrase empty!
        Choose a strong unique password, different from any of your other passwords!
		Place the private key in a safe place over which you (the key owner) have exclusive physical control!
		
    On GNU/Linux, your private key is typically stored in /home/user/.ssh/id_rsa.  
    Leave it there so ssh-agent finds it automatically.
    
    On Windows, we will put our private key(s) in our home directory:
    
    	C:\Users\<username>\PrivateKeys on Windows 7 
    	C:\Documents and Settings\<username>\My Documents\PrivateKeys on Windows XP


2. Copy the PUBLIC key of the RSA keypair to the server
 
    The public key needs to be stored on our server, elcentro, which is hosting branches.  
    The OpenSSH server running on server elcentro will use the public key to permit the holder of 
    the corresponding private key to access the branches (and anything else, by the way) owned by
    user ardilla.  Corollary: Don't let ardilla own anything you don't want to make accessible to any developer!

    On Linux, the ssh-client package provides a convenient script, ssh-copy-id, to append your public key 		
    to the authorized_keys file in /home/ardilla/.ssh/ on the server.  You can also paste your public key
    manually.
    
    Note for Windows users!  The public-key file created by PuTTY is in an not compatible with OpenSHH.
    The public key displayed in the GUI textbox is the one you need to copy to the server.

    Manual method: You need to log into server elcentro as user ardilla and either create or append to 
    the public key to /home/ardilla/.ssh/authorized_keys.  Paste your public key into this file.
    Be careful not to introduce typos.  Spelling is obviously critical for keys.
    
    Note that if you have every developer do this himself, he will need to log into server elcentro as 
    user ardilla.  You may not want this, even though you intend to trust him with everything owned by 
    user ardilla.  For example, if you are setting up many developers at once, it maybe more convenient to
    have the all developers give you their public keys so that you can add them to the authorized_keys
    file in one big batch.  It's up to you.


3. Set up an SSH Agent

	We could start using Bazaar with SSH right now.  But each developer would have to enter the
	passphrase for her provate key every time a secure communication occurs.  Bazaar executes 
	three or four secure communications for a single 'bzr log' so this will quickly become annoying.

	So you'll probably want an ssh agent running on each developer's machine.  An ssh agent is a trusted
	program which monitors requests for the private key.  The first time (per login) that the key is
	needed, the ssh agent prompts for the passphrase.  After that, the shh agent automatically provides
	the secret key when needed.  Thus your the developer needs to enter her passphrase only once per login.

    Linux:      The ssh-client package also provides ssh-agent.  
                If you're running an Ubuntu desktop, you probably already have ssh-agent running in 
                your X Window session.

    Windows:    The PuTTY suite provides pageant.exe for this.  We'll discuss how to set it up.

                Locate the pageant executable, pageant.exe.
                Create a shortcut to it.
                Edit the shortcut:
                
                Was: C:\Program Files\PuTTY\pageant.exe
                Now: "C:\Program Files\PuTTY\pageant.exe" "C:\Users\<username>\PrivateKeys\user@domain.ppk"
                
                Place the shortcut in your Startup programs.
                Each time you log into Windows, pageant will prompt you for the passphrase 
                for your private key.  Then, each time bzr needs your private key, pageant remembers 
                that you have already authenticated.  Try it now.  Log out, and log back in.


4. Verify that the RSA keypairs are actually working.

    Linux:      In a shell, enter 'ssh ardilla@elcentro'
                You will be prompted for the passphrase for your secret key, if it's not already cached by ssh-agent.
                You should be logged in to server elcentro automatically as user ardilla.
                Close the connection to elcentro.
                Enter 'ssh ardilla@elcentro'.
                You will *not* be prompted for the passphrase for your secret key; ssh-agent remembers.

    Windows:    Run PuTTY.
                Enter "ardilla@elcentro" for the connection.
                You should *not* be prompted for a password, assuming you provided it to pageant at login.  
                You should be logged in to server elcentro automatically as user ardilla.


5. Troubleshooting

    If you were not logged in automatically, or if you were prompted for a password, then either your
    public key is not correct in /home/ardilla/.ssh/authorized_keys on server *or* an ssh agent 
    (pageant on Winodws) is not running *or* the ssh agent was unable to locate your private key.


6. Multiple Teams

	Some organizations will need to limit which developers can access which branches on the server.
	Since we are using a user account (ardilla) on the server to control access, other project "teams" can 
	be set up to "own" the branches of other projects.  So for your next project, simply create a new
	user 'ardilla2' with password 'seceta2' (obviously this is a bad example!) on server elcentro and
	repeat the public-key distribution process in step 2 above for *only* the developers which need
	access to the branches of the new project.  Note that you are reusing the same public keys; you do not
	need (and probably do not want) to generate new RSA keypairs for every project.  
	
	But be careful!  Depending on how well you trust your developers, you may want to opt for the
	approach of having all the developers give you their public keys so that you (the trusted IT person)
	can load them into the authorized_keys file in the appropriate user account (ardilla, ardilla2, ...).
	True story.  I once saw a developer blurt out a password in an attempt to be 'helpful' to other
	developers.  So I had to assume he was helpful even when I wasn't watching.  So after I changed 
	all the passwords (aye!) I switched to the 'you-give-me-your-public-key-and-i-will-put-it-where-it-	
	needs-to-go' system.
	
	This process can obviously be repeated as many times as needed for fine-grained control of which
	developers can access which branches.  For this reason, you may want user names on elcentro like
	'project1' and 'project2' to make the bzr commands more intuitive in the next step and more easy
	to remember and administer.
		
7. Setting up Bazaar Explorer (each developer must do this)

    i.      Install
    ii.     Prepare to use
    iii.    Get your first checkout

    Install:
    
        On Linux, install bzr, bzr-tools and bzr-explore packages for your distribution.
        On Windows, teh easiest think to do is install the Windows Stand-Alone Installer for bzr.

    Prepare to use:
    
        Launch Bazaar Explorer.
        From the main menu, select Settings > Configuration > User Configuration
        Select the tab named General.
        Fill in your name and email address.
        Click OK.

    Get your first checkout (example for Windows 7):
    
	Launch Bazaar Explorer if it is not already open.
	Select the "Welcome" page if it is not already displayed.
	Choose "Get project source from elsewhere."
	Click on "Checkout"
	Enter branch source as "bzr+ssh://ardilla@elcentro/home/bzr/test/trunk"
	Enter local directory as "C:\Users\<username>\checkouts\test"
	Press OK.  Watch it work!


        
        
[1] http://en.wikipedia.org/wiki/RSA
[2] http://en.wikipedia.org/wiki/Public-key_cryptography
[3] http://www.chiark.greenend.org.uk/~sgtatham/putty

Martitza Mendez <martitzam@gmail.com>