==================================================================
OpenSSH Extension to Hash Host Names & Addresses in known_hosts[2]
==================================================================


Motivation
==========

If host names and addresses are stored in plaintext, an adversary who
obtains a user's password will have access to the full list of hosts that
the compromised user has ever previously contacted from the compromised
host.  By hashing the the host names and addresses, we prevent the adversary
from reading them directly.  (The adversary can still verify whether or not
a given host name or address is in the known_host file.)


File format changes
===================

In the known_hosts and known_hosts2 files, host names & addresses
are replaced by salt/hash pairs defined as follows:

  <host>     = the host name/address to be hashed.
  <salt_b64> = base64(random 64 bits)
  <hash_b64> = base64(SHA1(<salt> o <host>))
  <salt/hash pair> = '<' o salt_b64 o '-' o hash_b64 o '>'


New utilities
=============
  remove-knownhost [-f file] <host>
    Removes entries for a host name/address from the calling user's
    known_hosts[2] files (or any other file of the same format specified
    via the -f option).

  ssh-showkey [-f file] <host>
    Show the known_host entry and key fingerprint for the host name/address
    specified by the caller.  Searches the calling user's known_hosts[2]
    files unless another file of the same format is specified via the 
    -f option.

  ssh-hostname-encoder -o <oldfile> -n <newfile>
    Converts your old known_host file to a new file with hashed hosts.
    <oldfile> must not equal <newfile>

  mv-via-overwrite <srcfile> <destfile>
    Replaces contents of <dstfile> with those in <srcfile>
    (The source file is left intact -- unlike standard mv.)

  convert_known_hosts.pl
    Converts all known_hosts[2] files for all user home directories to
    hashed hosts format.
    See below under: "IMPORTANT - Converting existing known_hosts entries"

Patching
========

The SunOS version of patch is rather deficient. For SunOS users, we recommend
first downloading and installing the GNU patch utility which can be obtained
from:

http://www.gnu.org/software/patch/patch.html

To patch a standard OpenSSH-3.9p1 source tree execute the following commands
and then follow the installation instructions below.

$ gunzip openssh-3.9p1-hashed-hosts.patch.gz
$ patch -p0 < openssh-3.9p1-hashed-hosts.patch


Installation
============

$ ./configure
$ make
$ make install

Convert old known_hosts[2] files to hashed host format (see below).


IMPORTANT - Converting existing known_hosts entries
===================================================

Backwards compatibility is maintained with plaintext known_hosts
entries, but to obtain the security benefits of host hashing one must
hash the host names and addresses in the existing entries of your
known_hosts file.

After running "make install", issue the following commands to convert
all known_host files on your system into hashed hosts format and
to look for other files that may contain plaintext hostnames.

$ sh ./build-CR.sh    # If you are using a *COLLECT* version of the patch
$ su root
$ perl convert_known_hosts.pl -a

You will be prompted to enter a passphrase to be used when encrypting
the original known_hosts files (as a means of preserving them should
the patch have problems or should a user demand their plaintext data
back.)  Make sure to use a passphrase that is not used for anything
else on your system.

For each known_host file, the convert_known_hosts.pl script will then
  (1) backup known_hosts files to blowfish cipher encoded files with the
      ".backup.bf" (if such a backup file already exists, it will
      be appropriately renamed with its date of creation attached.)
  (2) Replace the known_host file with one in which all the entries are
      in hashed format.

It will then search for other files in users' .ssh/ directories that have
"hosts" in their name and ask if you want to encrypt these as well.
No files other than known_hosts[2] should have hosts in its name,
but often program like emacs leave temp files around (e.g. known_hosts~)
that have plaintext host entries in them.

To decode a .backup.bf file, use
$ openssl bf -d -in ~/.ssh/known_hosts.backup.bf -out old_known_hosts

For more detailed usage information on convert_known_hosts.pl, including
commands to convert a single user directory at a time, type:
$ perl convert_known_hosts.pl -help


Authors
=======
   Jaeyeon Jung - MIT CSAIL
   Stuart Schechter - Harvard University DEAS
   Will Stockwell - MIT CSAIL

With thanks to
==============
   Craig Agricola
   Colleen Shannon
   Victor Hazlewood
   Lars Kellogg-Stedman