Installing the SRP distribution ------------------------------- Getting Started --------------- Installation is explained in detail in the configuration section below. If you want to build a full-fledged copy of the SRP distribution, the simplest way to get started is to unpack and build OpenSSL on your system, and run: $ ./configure --with-openssl=/usr/local/src/openssl-0.9.7f # Replace with absolute path to OpenSSL on your system $ make $ make install This will build the SRP distribution with default options enabled, and then install the binaries under /usr/local, which is the default location. If your system already has OpenSSL installed, then './configure' without options should work. Configuring the Distribution ---------------------------- The distribution is configured by specifying options to the top-level 'configure' script. The following sections discuss the various supported options in more detail. 1. Configuring crypto library support The SRP library uses an underlying cryptographic library to do large-number arithmetic, compute message digests, and generate random numbers. In addition, other parts of the distribution, like SRP Telnet, may use this library to encrypt data and even negotiate SSL/TLS sessions. The distribution can be configured to use a variety of crypto and big integer libraries. The choice of libraries may also influence the options enabled in the SRP distribution and the necessity for additional libraries. Since encryption is no longer bundled with the distribution, encryption support is entirely dependent on underlying libraries. Read the section below (A through F) depending on which library you plan to use. A. OpenSSL Versions: 0.9.7g (recommended) 0.9.5a (minimum) Where to get it: http://www.openssl.org/ OpenSSL is probably the best option for most environments. It is available on a wide variety of platforms, has fairly fast implementations of many cryptographic algorithms, and supports SSL/TLS, which is used by SRP Telnet for session security. Option: --with-openssl= The directory must be an absolute path to the directory where OpenSSL was built on your system. If this option is specified without a directory, the Makefiles will look for OpenSSL in the default system locations. The SRP library will use OpenSSL's implementation of SHA-1 and their random number generator, and will combine its own entropy sources with OpenSSL's default seeding routines. Additionally, CAST and DES will be enabled for both FTP and Telnet, and Blowfish and MD5 will be enabled for FTP; OpenSSL's implementations of these algorithms will be used. Kerberos (if enabled) will use OpenSSL's DES implementation instead of its own. NOTE: OpenSSL 0.9.7 no longer defines DES "compatibility" symbols, so if you use 0.9.7 or later in conjunction with --with-krb4, you may get link errors unless you specify --with-des and give it the path to a compiled copy of libdes. B. GNU MP Versions: 4.1.4 (recommended) 2.0.2 (minimum) Where to get it: http://www.swox.com/gmp/ GNU MP is the GNU multiprecision math library. Although it is not designed as a cryptographic library, the SRP distribution can use it for arbitrary-precision math and fall back on internal implementations of other algorithms. The latest versions of GMP offer excellent performance, comparable to that of the routines in the OpenSSL library. Versions as old as 1.3.2 have been known to work, though performance is not as good as more recent versions. Option: --with-gmp= Like with OpenSSL, the directory must be an absolute path, and if it is not specified, the Makefiles will look in the default system directories for GMP. The SRP library will use its internal implementation of SHA-1, as well as an internal cryptographic random-number generator (based on SHA-1) and its own entropy generation code. Since GNU MP does not contain any encryption algorithms or hash functions, specifying --with-gmp alone will result in Telnet and FTP with no encryption enabled (FTP will still support SHA-1 for message authentication). To enable DES encryption, get Eric Young's libdes, build it, and specify --with-des=. To enable CAST encryption, contact me for a copy of my public-domain CAST source (see cast/README) and specify --with-cast. Telnet and FTP will find it in the right place once it is installed. C. Libgcrypt Versions: 1.2.1 (recommended) 1.2.0 (minimum) Where to get it: ftp://ftp.gnupg.org/gcrypt/libgcrypt/ Libgcrypt is the GNU crypto library, used by GnuPG, GnuTLS, and other packages. Option: --with-gcrypt= The SRP library will use libgcrypt's bignum/MPI implementation, its SHA-1 implementation, and its random number generator. D. TomCrypt Versions: 1.01 (recommended) 1.00 (minimum) Where to get it: http://libtomcrypt.org/ LibTomCrypt is a cryptography library implemented by Tom St Denis. It contains the LibTomMath bignum library, described below, as well as implementations of a wide range of cryptographic algorithms. Option: --with-tomcrypt= The SRP library will use LibTomCrypt's SHA-1 implementation, as well as its Yarrow-based random number generator, and combine its entropy sources with LibTomCrypt's platform- specific entropy-gathering routines. Additionally, CAST encryption will be enabled for both FTP and Telnet, and MD5 (for integrity checking) will be enabled for FTP. DES, Triple-DES, and Blowfish are not yet integrated at this time. E. TomMath Versions: 0.35 (recommended) 0.15 (minimum) Where to get it: http://math.libtomcrypt.org/ LibTomMath is a large-integer math library based on the MPI library API but re-implemented by Tom St Denis. LibTomMath has considerably improved performance relative to MPI. Option: --with-tommath= Since LibTomMath does not include a random number generator, symmetric ciphers, or hash algorithms, SRP will use its own internal implementations, unless overridden as described in the GNU MP section above. F. MPI Version: 1.8.6 (recommended) Where to get it: http://thayer.dartmouth.edu/~sting/mpi/ MPI is a simple, portable large-integer arithmetic library written by Michael J. Fromberger. It was designed primarily for portability as opposed to speed. Option: --with-mpi= Since MPI does not include a random number generator, symmetric ciphers, or hash algorithms, SRP will use its own internal implementations, unless overridden as described in the GNU MP section above. G. CryptoLib Versions: 1.2 (recommended) 1.1 (minimum) Where to get it: ftp://ftp.zedz.com/pub/crypto/libraries/cryptolib/ CryptoLib was written by Matt Blaze and Jack Lacy at AT&T Bell Labs several years ago. The official site tells you how to get an official copy via E-mail; it should be possible to find CryptoLib via a mirror site if you look hard enough. CryptoLib supports a handful of cryptographic algorithms, and contains its own large number math library. Option: --with-cryptolib= To use CryptoLib, you must specify the directory in this option, because the library's name conflicts with a library found on many systems (libcrypt.a). Because of a bug in CryptoLib 1.1's SHA-1 implementation, the SRP library will still use its own SHA-1 code. It will use CryptoLib's DES-based random number generator, but because CryptoLib 1.1's entropy-gathering routine has problems on some platforms, SRP will gather its own entropy and use it to seed CryptoLib's generator. CryptoLib contains DES support, which will be used by both Telnet and FTP. To enable CAST encryption as well, contact me for a copy of my public-domain CAST source (see cast/README) and specify --with-cast. Telnet and FTP will find it in the right place once it is installed. CryptoLib does not support numbers larger than 2048 bits, which causes a problem with version 2 of libsrp which does support larger moduli. 2. Other options 'configure' understands a variety of other options, most of which take default values depending on how the main crypto library is configured: --prefix= Sets the install location for binaries. Applications are installed in the 'bin' subdirectory, servers and administrator utilities go in 'sbin', libraries go in 'lib', and header files go in 'include'. By default this is '/usr/local'. --with-pam The SRP distribution comes with support for Pluggable Authentication Modules (PAM). Normally, the configuration script will attempt to autodetect PAM support, but this option can be explicitly enabled or disabled. See base/pam_eps/README for information about the EPS PAM modules. --enable-tls SSL/TLS in Telnet is enabled by default when OpenSSL is used. --disable-tls disables it. This option is disabled and not supported with CryptoLib and GNU MP. --enable-tls_krb5 Enable Kerberos5-based authentication via TLS ciphersuites. This option is experimental and is disabled by default. It requires Kerberos5 ciphersuite support in your TLS library. --with-zlib This enables zlib-based compression in TLS. This option is experimental and is disabled by default. Eventually this will be update to autodetect libz once compression support is more fully standardized and tested in TLS. --enable-forward_x Enable X11 session forwarding in Telnet. This option is enabled by default and can be disabled with --disable-forward_x. --enable-fwdx_unix_sock If 'enable-forward_x' is enabled, this enables the use of local (Unix domain) sockets. --disable-fwdx_unix_sock forces Telnet to use a loopback IP address (127.0.0.1) instead. --with-cast Enables the CAST-128 encryption algorithm and the associated encryption options in Telnet and FTP. If OpenSSL or LibTomCrypt is used, this is enabled by default, and the crypto library's CAST implementation is linked in. Otherwise, CAST is disabled by default. If CAST is explicitly enabled with a crypto library that doesn't support it, the unbundled CAST source code in the "cast" subdirectory is required. Please contact Tom Wu (tjw@cs.stanford.edu) if you wish to obtain a copy of this implementation. --with-des, --with-des= Enables Telnet/FTP DES encryption. If either OpenSSL or CryptoLib is used, this option is enabled by default, and that library's DES implementation is used. This option is disabled by default with GMP. If the option is explicitly enabled with a directory argument, Telnet expects to find Eric Young's libdes (version 3 or later recommended) there. --with-rsa Enables RSA-based ciphersuites and certificates with SSL/TLS enabled Telnet. This is enabled by default, but should be disabled (--without-rsa) if your copy of OpenSSL was built without RSA support. --enable-loginf Uses the '-f' option if your /bin/login supports it. --disable-loginf if it doesn't. --with-krb4 Kerberos V4 authentication. Disabled by default. If this flag is given in conjunction with --with-krb5, K5's V4 compatibility mode is enabled. Otherwise, "classic" Kerberos V4 is assumed. --with-krb5, --with-krb5= Kerberos V5 authentication. Disabled by default. This will generally require MIT's Kerberos V5 distribution, the directory to which should be given as an argument to this option. This directory is usually named 'src' in the distribution and has 'include' and 'lib' subdirectories. NOTE: this option is not currently supported with the CryptoLib library option due to symbol conflicts. --with-srp SRP authentication. Always enabled. --without-srp does not work and is not supported. --with-spx SPX authentication. Disabled by default. Experimental and not officially supported. --with-rsaencpwd RSA encrypted password authentication. Disabled by default. Experimental and not officially supported. --with-krb4encpwd Kerberos V4-encrypted password authentication. Disabled by default. Experimental and not officially supported. --disable-ncurses, --disable-curses Normally, the configuration script looks for terminal support in termlib, ncurses, curses, and termcap, in that order. These options suppress the automatic check for the corresponding libraries. This is useful if your system has a buggy "ncurses" or "curses" library. --enable-glob Use glob(3) in libc for pattern matching in ftp/ftpd. This should ONLY be enabled if you know your libc's glob(3) is safe; by default this is disabled, and a builtin substitute is used. --with-engine Use ENGINE support in OpenSSL for external crypto support. SRP can take advantage of some crypto accelerators to boost performance. 3. Building the distribution Type 'make' from the top-level directory. 4. Intalling the binaries Type 'make install' from the top-level directory as root. Files will be installed under the directory tree specified by the --prefix option, or /usr/local by default. 5. Setting up your system You should be able to test the 'telnet' and 'ftp' client binaries directly by pointing them at servers. For more information on how to use them, particularly their new security features, read 'telnet/README', 'telnet/README.TLS', and 'ftp/README'. This section describes how to set up a server with EPS passwords. Getting Started Quickly: - Run 'tconf' as root (this utility is in 'base/src'). Pick one of the "predefined" fields. Field #6 is a good choice (1024 bits). This creates /etc/tpasswd.conf, which is needed by the rest of the distribution. - If you're using PAM, and you have a file called '/etc/pam.d/passwd' file, then add the following line at the end of that file: password required /lib/security/pam_eps_passwd.so If your PAM installation uses '/etc/pam.conf' instead, then add the following line in the 'passwd' section: passwd password required /lib/security/pam_eps_passwd.so and the following line in the DEFAULT section: DEFAULT password required /lib/security/pam_eps_passwd.so The pathname in the last field should point to where you actually installed the EPS PAM modules. - The 'passwd' command should now continue to set legacy passwords in /etc/passwd or /etc/shadow, while also setting EPS passwords in the /etc/tpasswd file. You can test this by changing a user's password with 'passwd' and seeing if an entry is created in /etc/tpasswd. - If this works, you should be able to install 'telnetd' and 'ftpd', and test logging into your system securely. Congratulations! The rest of this document covers the administrative housekeeping involved with the EPS password system in more detail. It also covers more advanced options for customizing Telnet and FTP security options on your system. 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. For additional flexiblity, EPS is available as a set of Pluggable Authentication Modules (PAM), which integrate seamlessly with existing password-management software. 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 and should not be done at all if you are using PAM. 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 " command and in telnet you should restart the client. 2. 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.