INTRODUCTION
------------

SRP stands for the Secure Remote Password protocol, and it represents a new
mechanism for performing password-based authentication and key exchange over
potentially insecure networks.  SRP offers both security and convenience
improvements over authentication techniques currently in use.

The main repository for SRP information and this distribution is

	http://srp.stanford.edu/srp/

This site explains the advantages of SRP and the case for moving to
an "exponential" based password file format as implemented by the
Exponential Password Suite (EPS).  The new password file format enables
networked services to perform secure, password-only authentication
over the network.

This distribution consists of the Exponential Password Suite
which includes replacements for login, su, passwd and a new utility
called tconf.  Also included are versions of ftp, ftpd, telnet and
telnetd which implement the SRP protocol and provide for secure remote
authentication and possibly encryption (if you are in the US for now).


THE EXPONENTIAL PASSWORD SUITE
------------------------------

This distribution of EPS is designed to complement your existing
password file format (/etc/passwd or /etc/shadow).  Installing
EPS will create two additional files for providing secure remote
authentication:

	/etc/tpasswd
	/etc/tpasswd.conf

Once the EPS passwd utility is installed, any subsequent password
changes by a user will be reflected in BOTH the regular password
file and the EPS /etc/tpasswd file.  Thus installing the EPS suite
will NOT BREAK any programs (e.g. xlock) which rely on the regular
password file.

The distribution also includes replacements for login and su.  These
versions will authenticate users using the tpasswd file if
the user has set their tpasswd entry and revert to authenticating
based on the regular password file if not.  Note that installing
login and su is completely OPTIONAL.  Since the tpasswd file and
the regular password file are kept in sync by the EPS passwd utility,
the regular login and su should continue to work correctly.  However,
the EPS login program provides the added feature of prompting users
to change their passwords the first time they log into the system
after the EPS suite has been installed.  This forces them to update
their tpasswd entry which allows for secure remote authentication.

The login, su and passwd programs are based on the Linux Shadow
Suite distribution (shadow-970616).  The EPS versions support most
of the features of the shadow suite (e.g. /etc/login.defs).  For more
information about these features, please refer to the shadow suite.

The tconf utility updates the /etc/tpasswd.conf which holds the
parameters for N and g (see web site if you would like this explained).
Since N and g do not necessarily need to be changed, tconf need only
be run at install time.  It is recommended that you start off with
a 1024-bit field size.


TELNET AND FTP
--------------

The new SRP-enabled versions of telnet, telnetd, ftp and ftpd implement
the SRP protocol and provide for secure remote password-only authentication
when an SRP-enabled client connects with an SRP-enabled server.  However,
note that all these programs are BACKWARDS-COMPATIBLE with existing
clients and servers.  Thus, for example, a non-SRP-enabled telnet client 
may connect with an SRP-enabled telnet server and vice versa although,
of course, the authentication/connection will be insecure.
Some new features included are:

	ftp -c [cipher] -h [hash]	select cipher and hash
	ftpd -a				only allow SRP enabled clients
	telnetd -a valid		only allow SRP enabled clients

Some notes about using the telnet and ftp clients:

1. For both telnet and ftp, once an SRP authentication fails (you typed
   in your password wrong) the clients will attempt to revert to a
   regular authentication (send cleartext password).  Thus, if you want
   to reauthenticate using SRP you should abort the insecure authentication
   and try again.  In ftp you may use the "user <username>" command and
   in telnet you should restart the client.

2. For telnet, the client will use your username on your local system
   and assume this is the same as the username on the remote system.
   This may cause SRP authentication to fail immediately if there
   is no such user on the remote system.  You should use
   "telnet -l <remote-username> <remote-host>" in order to authenticate
   using SRP successfully.

3. Note that if you use the -a option with ftpd and telnetd, you will 
   NOT be able to connect using non-SRP-enabled clients.  Make sure
   you have clients available on the hosts from which you want to
   connect and that all users have set their tpasswd entry.


BUILDING THE DISTRIBUTION
-------------------------

0. Install one of the supported math libraries.  Currently, both
   GNU MP 2.0.2 and cryptolib-1.1 are supported.  If one of these
   is already installed on your system, continue to Step 1.

   For GNU MP, untar the distribution into the gmp-2.0.2 stub in
   the top-level directory.  Read the instructions in the package
   and build the library.

   For cryptolib, untar the distribution into the cryptolib_1.1 stub
   in the top-level directory.  Examine the Makefile before building
   the package on your system.

1. From the main srp directory run:

     ./configure
     make

   This should build libsrp, libkrypto, the base package, and telnet
   and ftp.

   NOTE: If you are using cryptolib, add the "--with-cryptolib"
   option to configure.

   Otherwise, no option needs to be specified, since GNU MP is
   assumed by default.

   You can also specify the following options to configure:

     --with-krb4
     --with-krb5
     --with-srp
     --with-spx
     --with-rsaencpwd
     --with-krb4encpwd

     These select which authentication mechanisms to compile into
     telnet and telnetd.

     --enable-noencryption
     --with-des
     --with-cast

     These select which (if any) encryption algorithms to support.

     --enable-loginf

     Informs telnetd that your /bin/login supports the -f option.
     If your system doesn't support login -f, you may need to add
     "localhost" to your /etc/hosts.equiv file.

   The default options are --with-srp --with-cast.  Right now, only
   --with-cryptolib and --enable-noencryption are supported by all
   packages.  The remaining switches are primarily for telnet, though
   they should be supported more widely in future releases.


INSTALLING THE BINARIES
-----------------------

Once you have built all the executables. cd to the inst directory and
PLEASE READ the files INSTALL.EPS and INSTALL.SRP carefully for
instructions on installing.  You could be LOCKED OUT of your system if
you do not follow this advice!


LICENSE
-------

Please read the file "LICENSE" in the docs directory.


ACKNOWLEDGMENTS
---------------

This software is built on top of many other publicly available packages.
Please see the files "Acknowledgements" and "Copyrights" in the docs
directory.


BUG REPORTS
-----------

Please send bug reports to:

	tjw@cs.stanford.edu	(Thomas Wu)
	ejhong@cs.stanford.edu	(Eugene Jhong)

