source: mod_gnutls/README @ 0499540

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

$LastChangedDate: $

Contents:

     I. ABOUT
    II. AUTHORS
   III. LICENSE
    IV. STATUS
     V. BASIC CONFIGURATION
    VI. 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 force-elite.com>
      Nikos Mavrogiannopoulos <nmav gnutls.org>



III.  LICENSE

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



IV.   STATUS

      * SSL and TLS connections with all popular browsers work!
      * Sets environmental vars for scripts (compatible with mod_ssl vars)
      * Supports memcached as a distributed SSL session cache
      * Supports DBM as a local SSL session cache
      * Support for server name indication (SNI), RFC3546
      * Support for client certificates
      * Support for secure remote password (SRP), RFC5054



V.    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>



VI.   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