source: mod_gnutls/README @ 2db6923

                mod_gnutls, Apache GnuTLS module.
                =================================

$LastChangedDate: $

Contents:

     I. ABOUT
    II. AUTHORS
   III. MAINTAINERS
    IV. LICENSE
     V. PREREQUISITES
    VI. INSTALLATION
   VII. BASIC CONFIGURATION
  VIII. CREATE OPENPGP CREDENTIALS FOR THE SERVER



I.    ABOUT

      This module started back in September of 2004 because I was tired of
      trying to fix bugs in mod_ssl.  mod_ssl is a giant beast of a module --
      no offense to it's authors is intended -- but I believe it has fallen
      prey to massive feature bloat.

      When I started hacking on httpd, mod_ssl remained a great mystery to me,
      and when I actually looked at it, I ran away.  The shear amount code is
      huge, and it does not conform to the style guidelines.  It was painful to
      read, and even harder to debug.  I wanted to understand how it worked,
      and I had recently heard about GnuTLS, so long story short, I decided to
      implement a mod_gnutls.

         Lines of Code in mod_ssl: 15,324
         Lines of Code in mod_gnutls: 3,594

      Because of writing mod_gnutls, I now understand how input and output
      filters work, better than I ever thought possible.  It was a little
      painful at times, and some parts lift code and ideas directly from
      mod_ssl.  Kudos to the original authors of mod_ssl.



II.   AUTHORS

      Paul Querna <chip at force-elite.com>
      Nikos Mavrogiannopoulos <nmav at gnutls.org>
      Dash Shendy <neuromancer at dash.za.net>

III.  MAINTAINERS

      Dash Shendy <neuromancer at dash.za.net>
      Execute `autoreconf -v -i -f` to Auto-generate files

IV.   LICENSE

      Apache License, Version 2.0 (see the LICENSE file for details)

V.    PREREQUISITES

      * GnuTLS          >= 2.12.6 <http://www.gnu.org/software/gnutls/>
      * Apache HTTPD    >= 2.0.42 <http://httpd.apache.org/>
      *                 >= 2.1.5-dev 
      * ARP Memcache    >= 0.7.0 (Optinal)


VI.   INSTALLATION

      * tar xzvf mod_gnutls-version.tar.gz
      * cd mod_gnutls-version/
      * ./configure --with-apxs=PATH --with-apr-memcache-prefix=PATH \ 
        --with-apr-memcache-libs=PATH --with-apr-memcache-includes=PATH
      * make
      * make install
      * Configure & restart apache

VII.  BASIC CONFIGURATION

      LoadModule gnutls_module modules/mod_gnutls.so
      
      # mod_gnutls can optionally use a memcached server to store it's SSL
      # Sessions.  This is useful in a cluster environment, where you want all
      # of your servers to share a single SSL session cache.
      #GnuTLSCache memcache "127.0.0.1 server2.example.com server3.example.com"
      
      # The Default method is to use a DBM backed Cache.  It isn't super fast,
      # but it is portable and does not require another server to be running
      # like memcached.
      GnuTLSCache dbm conf/gnutls_cache
      
      <VirtualHost 1.2.3.4:443>

        # Enable mod_gnutls handlers for this virtual host
        GnuTLSEnable On
      
        # This is the private key for your server
        GnuTLSX509KeyFile conf/server.key
      
        # This is the server certificate
        GnuTLSX509CertificateFile conf/server.cert

      </VirtualHost>
      
      # A more advanced configuration
      GnuTLSCache dbm "/var/cache/www-tls-cache/cache"
      GnuTLSCacheTimeout 600
      NameVirtualHost 1.2.3.4:443
      
      <VirtualHost 1.2.3.4:443>

        Servername server.com:443
        GnuTLSEnable on
        GnuTLSPriority NORMAL

        # Export exactly the same environment variables as mod_ssl to CGI
        # scripts.
        GNUTLSExportCertificates on
      
        GnuTLSX509CertificateFile /etc/apache2/server-cert.pem
        GnuTLSX509KeyFile /etc/apache2/server-key.pem
      
        # To enable SRP you must have these files installed.  Check the gnutls
        # srptool.
        GnuTLSSRPPasswdFile /etc/apache2/tpasswd
        GnuTLSSRPPasswdConfFile /etc/apache2/tpasswd.conf
      
        # In order to verify client certificates.  Other options to
        # GnuTLSClientVerify could be ignore or require.  The
        # GnuTLSClientCAFile contains the CAs to verify client certificates.
        GnuTLSClientVerify request
        GnuTLSX509CAFile ca.pem

      </VirtualHost>
      
      # A setup for OpenPGP and X.509 authentication
      <VirtualHost 1.2.3.4:443>

        Servername crystal.lan:443
        GnuTLSEnable on
        GnuTLSPriorities NORMAL:+COMP-NULL
      
        # Setup the openpgp keys
        GnuTLSPGPCertificateFile /etc/apache2/test.pub.asc
        GnuTLSPGPKeyFile /etc/apache2/test.sec.asc
      
        # - and the X.509 keys
        GnuTLSCertificateFile /etc/apache2/server-cert.pem
        GnuTLSKeyFile /etc/apache2/server-key.pem

        GnuTLSClientVerify ignore
      
        # To avoid using the default DH params
        GnuTLSDHFile /etc/apache2/dh.pem
      
        # These are only needed if GnuTLSClientVerify != ignore
        GnuTLSClientCAFile ca.pem
        GnuTLSPGPKeyringFile /etc/apache2/ring.asc

      </VirtualHost>



IX.   CREATE OPENPGP CREDENTIALS FOR THE SERVER

      mod_gnutls currently cannot read encrypted OpenPGP credentials.  That is,
      when you generate a key with gpg and gpg prompts you for a passphrase,
      just press enter.  Then press enter again, to confirm an empty
      passphrase.  http://news.gmane.org/gmane.comp.apache.outoforder.modules

      These instructions are from the GnuTLS manual:
      http://www.gnu.org/software/gnutls/manual/html_node/Invoking-gnutls_002dserv.html#Invoking-gnutls_002dserv

        $ gpg --gen-key
        ...enter whatever details you want, use 'test.gnutls.org' as name...

      Make a note of the OpenPGP key identifier of the newly generated key,
      here it was 5D1D14D8.  You will need to export the key for GnuTLS to be
      able to use it.

         $ gpg -a --export 5D1D14D8 > openpgp-server.txt
         $ gpg -a --export-secret-keys 5D1D14D8 > openpgp-server-key.txt