kssl 0.3  README 08 August 2000

 Copyright (c) 1999-2000 Vern Staats
 Some rights reserved.


 DESCRIPTION
 -----------

 kssl is a set of patches to OpenSSL to add support for Kerberos as an
 authentication method.  It is based on an expired draft RFC by Medvinsky
 and Hur: draft-ietf-tls-kerb-cipher-suites-03.txt.  Additional patches
 are provided for apache and mod_ssl.

 Since kssl is basically a wart on OpenSSL it adopts the BSD-style
 OpenSSL License, included here as "LICENSE".  Both commercial and
 non-commercial use is permitted, subject to patent and U.S. export
 control restrictions.


 REQUIREMENTS
 ------------

 Kerberos 5:
    1)  krb5r1.0.6 libraries and include files: 
            /usr/local/krb5/include/ krb5.h
            /usr/local/krb5/lib/ lib{gssapi_krb5,krb5,com_err,crypto}.a
    2)  A friendly KDC admin.  A new service principle name of the form
        "kssl/your.host.fqdn@YOUR.REALM" will need to be added to your
        KDC and to a keytab file on your kssl service host.
    http://web.mit.edu/kerberos/www/krb5-1.0/announce.html

 OpenSSL 0.9.5a:
    http://www.openssl.org/source/openssl-0.9.5a.tar.gz
 
 mod_ssl 2.6.5-1.3.12
    http://www.modssl.org/source/mod_ssl-2.6.5-1.3.12.tar.gz

 Apache 1.3.12:
    http://www.apache.org/dist/apache_1.3.12.tar.gz

 patch 2.5:
    ftp://prep.ai.mit.edu/pub/gnu/patch/

 Perl:
    Something or other in here almost certainly requires Perl.


 RESTRICTIONS
 ------------

 As stated in the mod_ssl README: "Various companies hold various patents
 for various algorithms in various locations around the world.  _YOU_ are
 responsible for ensuring that your use of any algorithms is legal by
 checking if there are any patents in your country."  IANAL, but my read
 is that use of IDEA is questionable, while RSA is free for use by the
 U.S. government.  According to the RSA Labs FAQ, Question 6.3.1:
 <A href="http://www.rsasecurity.com/rsalabs/faq/6-3-1.html">
 Is RSA Patented?</A>:  "... The U.S. government can use RSA without a
 license because it was invented at MIT with partial government funding."

 See also:
    http://www.rsasecurity.com/rsalabs/ for RSA issues (RSA, RC5, RC4)
    http://www.ascom.ch/ regarding the IDEA algorithm

 Please REMEMBER that export/import and/or use of cryptography software or
 even just providing cryptography hooks is illegal in some parts of the
 world.  When you re-distribute this package or even email
 patches/suggestions to the authors or other people PLEASE PAY CLOSE
 ATTENTION TO ANY APPLICABLE EXPORT/IMPORT LAWS.  The authors of kssl,
 mod_ssl, OpenSSL, &etc are not liable for any violations you make here.
 So be carefully yourself.

 Export from the United States is regulated under "EI controls" of the
 Export Administration Regulations (EAR, 15 CFR 730-744) of the U.S.
 Commerce Department, Bureau of Export Administration (BXA). 
 http://www.bxa.doc.gov/


 DISCLAIMER
 __________

 THIS SOFTWARE IS PROVIDED BY VERN STAATS ``AS IS'' AND ANY EXPRESSED
 OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
 WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
 ARE DISCLAIMED.  IN NO EVENT SHALL VERN STAATS OR OTHER PARTIES
 ASSOCIATED WITH THIS PROJECT BE LIABLE FOR ANY DIRECT, INDIRECT,
 INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
 BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
 LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
 CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
 LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
 ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 POSSIBILITY OF SUCH DAMAGE.

 REFERENCES TO REQUIRED, COMPATIBLE, OR HELPFUL SOFTWARE PRODUCTS,
 HOWEVER WONDERFUL THEY MAY BE, SHOULD NOT BE CONSTRUED AS OFFICIAL
 ENDORSEMENT OF SUCH PRODUCTS.


 CREDITS
 _______

 Obviously this project would be impossible without the work of
 these, and a great many other, people:

 Ari Medvinsky and Matthew Hur (draft-ietf-tls-kerb-cipher-suites-03.txt).
 The OpenSSL project, Eric A. Young and Tim J. Hudson (SSLeay).
 The Apache Group and the NCSA (Apache).
 Ben Laurie (Apache-SSL) and Ralf S. Engelschall (mod_ssl).
 Lincoln Stein and Doug MacEachern (the O'Reilly Apache Modules book).
 Brian Tung (the Addison-Wesley Kerberos book).
 MIT Project Athena (the Kerberos source code).
 Ken Hornstein and Dave McGrew (various Kerberos questions).
 Larry Lidz (w3m patches).

 In addition, if it is not already apparent, the README files from
 OpenSSL and mod_ssl have been plagarized with wanton abandon.


 PORTS
 -----

 This software is known to work on:

    SunOS 5.8
    SuSE Linux 6.3


 INSTALLATION
 ------------

 First have your KDC admin create a new Kerberos service principal for
 kssl/your.host.fqdn@YOUR.REALM (for appropriate values of YOUR.REALM
 and your.host.fqdn, of course).  If you are planning to run a 
 Kerberized web server, your.host.fqdn would be the fully qualified
 domain name of your web server.  Next, ask the KDC admin to extract
 a keytab file for you.  Normally this would be the /etc/krb5.keytab
 file on your server, but Apache doesn't like to run as root so put
 it in /etc/krb5.keytab.kssl.  This file should be owned by the
 Apache uid (usually nobody:nobody) with 0600 permissions.

 The following is a set of streamlined instructions for building a
 fairly vanilla distribution.  It assumes that you _are_ permitted
 to use RSA and _are_not_ permitted to use IDEA.  In other cases
 you will have to refer to the per-package installation instructions
 ... which you are encouraged to read anyway.  Lines preceeded by
 "$" require root permission.

 Unpack the required software packages:
    cd ..
    gunzip <openssl-0.9.5a.tar.gz        | tar xvf -
    gunzip <mod_ssl-2.6.5-1.3.12.tar.gz  | tar xvf -
    gunzip <apache_1.3.12.tar.gz         | tar xvf -

 Build OpenSSL:
    #   For SGI, add:   setenv CC cc
    patch -p0 <mod_kssl-0.3/patches/openssl-0.9.5a.kssl-0.3.patch
    cd openssl-0.9.5a
    ./config no-idea        #  For Linux, add:  "no-asm"
    make |& tee results.make
    make test
    #
    #   For kssl,  make test  has been modified to _not_ test
    #   Kerberized SSL.  Here is the kssl test:
    #
    #   Server, running as root (or as nobody):
    #       cd openssl-0.9.5a/apps
    #       setenv RANDFILE randjunk
    #       echo "$$ " `date` >randjunk; vmstat -s >>randjunk;
    #       ps -el >>randjunk; netstat -ni >>randjunk; netstat -na >>randjunk
    #       ./openssl s_server -cipher KRB5-DES-CBC3-MD5
    #
    #   Client:
    #       cd openssl-0.9.5a
    #       kinit
    #       apps/openssl s_client -connect $server:4433 -debug -state
    #
    #   Client and Server:
    #       Assuming everything is working correctly, you can
    #       now type stuff back and forth at yourself.  Wheee!
    #       Now kdestroy on client and repeat to verify that the
    #       connection fails without a valid kerberos ticket.
    #
    $ make install
    cd ..

 Build mod_ssl:
    patch -p0 <mod_kssl-0.3/patches/mod_ssl-2.6.5-1.3.12.kssl-0.3.patch
    cd mod_ssl-2.6.5-1.3.12
    ./configure --with-apache=../apache_1.3.12
    #   You should skip the instructions given by the configure script
    #   and NOT proceed directly to the apache directory at this point.
    cd ..

 Build mod_kssl:
    cd mod_kssl-0.3
    ./configure --help
    #  note options for configuring sample web pages:
    #       --with-examples=/tmp/kssl.web
    #       --with-principal=username@YOUR.KERBEROS.REALM
    #  note that this will also patch apache
    ./configure --with-apache=../apache_1.3.12
    cd ..

 Build Apache:
    cd apache_1.3.12
    setenv SSL_BASE /usr/local/ssl
    setenv KRB5_BASE /usr/local/krb5    
    setenv CFLAGS "-DNO_IDEA  -DKSSL_KLP"
    ./configure  --prefix=/usr/local/apache             \
        --activate-module=src/modules/kssl/mod_kssl.c   \
        --enable-module=proxy --enable-module=ssl
    make |& tee results.make
    #
    #   #   If you don't already have a server certificate...
    #
    #   #   For testing:
    #   make certificate TYPE=dummy  
    #   cp conf/ssl.crt/server.crt /tmp/kssl.web/conf/ssl.crt/server.crt
    #   cp conf/ssl.key/server.key /tmp/kssl.web/conf/ssl.key/server.key
    #
    #   #   For real:
    #   make certificate TYPE=custom
    #   #   See also:  http://www.modssl.org/docs/2.4/ssl_faq.html#ToC26
    #   

 Run Apache:
    #
    #   For testing:
    $ src/httpd -DSSL -X -f /tmp/kssl.web/conf/httpd.conf
    #
    #   For real:
    $ make install
    $ /usr/local/apache/bin/apachectl startssl

 Clients:
    #
    #   See the "CLIENTS" file for instructions on building w3m, etc.

 See also all the README and INSTALL files for OpenSSL, mod_ssl, and
 Apache, and, in particular, the mod_ssl HTML docs.


 CONFIGURATION
 -------------

 The kssl patches to OpenSSL add four new cipher-specs which can be 
 used with the mod_ssl SSLCipherSuite directive.  The new ones are:
     KRB5-DES-CBC3-MD5  KRB5-DES-CBC-MD5
     KRB5-DES-CBC3-SHA  KRB5-DES-CBC-SHA

 Examples:
    SSLCipherSuite KRB5-DES-CBC3-MD5
    SSLCipherSuite 3DES+kKRB5+aKRB5:DES+kKRB5+aKRB5
    and maybe:  SSLRequire  ( %{SSL_CIPHER} =~ m/^(KRB5-DES|KRB5-3DES)-/ )

 Several new Apache configuration directives are defined in mod_kssl:

    Directive           Default             Define per-server/per-directory
    --------------      ------------                      --- ---
    KRB5Service         kssl                               S
    KRB5KeytabFile      /etc/krb5.keytab.<KRB5Service>     S
    KRB5Realm           <None>                             S   D
    KRB5Principal       <None>                             S   D
    KRB5User            <None>                             S   D

 If you don't take the defaults then you _must_ define KRB5Service and
 KRB5KeytabFile in the per-server configuration.  These directives
 accept one argument.

 KRB5Realm and KRB5User may be used to restrict access to directories
 based on the Kerberos authenticated Realm and User name of the client.
 KRB5Principal = <KRB5User>@<KRB5Realm>.  These directives accept 
 multiple arguments.  KRB5* directives given in a subdirectory are
 NOT merged with KRB5* directives from the parent directory.  This
 is a feature.

 Example:

    <Location "/test/krb5_realm/">
        SSLRequireSSL
        SSLCipherSuite  KRB5-DES-CBC3-MD5
        KRB5Realm       YOUR.REALM
    </Location>

 See also the sample web pages and the mod_ssl HTML docs.


 CLIENTS
 -------

 See the "CLIENTS" file.

 
 PROXIES
 -------

 See the "PROXIES" file.


 PROBLEMS 
 --------

 If you have problems, please first verify
    (a) that you are using the latest supported versions of OpenSSL,
        mod_ssl, and Apache, and
    (b) that OpenSSL, mod_ssl, and Apache all function correctly
        WITHOUT having the kssl patches applied.

 Take a look at the "TROUBLESHOOTING" file.
 Then contact me: staatsvr@asc.hpc.mil