Changeset 04f48a2 in mod_gnutls for README


Ignore:
Timestamp:
Feb 21, 2014, 4:52:24 AM (9 years ago)
Author:
Daniel Kahn Gillmor <dkg@…>
Branches:
asyncio, debian/master, debian/stretch-backports, jessie-backports, main, master, proxy-ticket, upstream
Children:
999cdec
Parents:
8232c8b
Message:

trim down the readme so that we have one place for documentation.

File:
1 edited

Legend:

Unmodified
Added
Removed

  • README

    r8232c8b r04f48a2  
     1mod_gnutls, Apache GnuTLS module
     2================================
    13
    2                 mod_gnutls, Apache GnuTLS module.
    3                 =================================
     4  https://mod.gnutls.org/
    45
    5 $LastChangedDate: $
     6Mailing List:
    67
    7 Contents:
     8  mod_gnutls development <mod_gnutls-devel@lists.gnutls.org>
    89
    9      I. ABOUT
    10     II. AUTHORS
    11    III. MAINTAINERS
    12     IV. LICENSE
    13      V. PREREQUISITES
    14     VI. INSTALLATION
    15    VII. BASIC CONFIGURATION
    16   VIII. CREATE OPENPGP CREDENTIALS FOR THE SERVER
     10Lead Maintainer:
    1711
     12  Daniel Kahn Gillmor <dkg@fifthhorseman.net>
    1813
     14Past maintainers and other contributors:
    1915
    20 I.    ABOUT
     16  Paul Querna <chip at force-elite.com>
     17  Nikos Mavrogiannopoulos <nmav at gnutls.org>
     18  Dash Shendy <neuromancer at dash.za.net>
    2119
    22       This module started back in September of 2004 because I was tired of
    23       trying to fix bugs in mod_ssl.  mod_ssl is a giant beast of a module --
    24       no offense to it's authors is intended -- but I believe it has fallen
    25       prey to massive feature bloat.
     20Prerequisites
     21-------------
    2622
    27       When I started hacking on httpd, mod_ssl remained a great mystery to me,
    28       and when I actually looked at it, I ran away.  The shear amount code is
    29       huge, and it does not conform to the style guidelines.  It was painful to
    30       read, and even harder to debug.  I wanted to understand how it worked,
    31       and I had recently heard about GnuTLS, so long story short, I decided to
    32       implement a mod_gnutls.
     23 * GnuTLS          >= 2.12.6 <http://www.gnutls.org/> (3.* preferred)
     24 * Apache HTTPD    >= 2.2 <http://httpd.apache.org/> (2.4.* preferred)
     25 * autotools & gcc
     26 * APR Memcache    >= 0.7.0 (Optional)
     27 * libmsv          >= 0.1 (Optional)
    3328
    34          Lines of Code in mod_ssl: 15,324
    35          Lines of Code in mod_gnutls: 3,594
     29Installation
     30------------
    3631
    37       Because of writing mod_gnutls, I now understand how input and output
    38       filters work, better than I ever thought possible.  It was a little
    39       painful at times, and some parts lift code and ideas directly from
    40       mod_ssl.  Kudos to the original authors of mod_ssl.
     32 tar xzvf mod_gnutls-version.tar.gz
     33 cd mod_gnutls-version/
     34 autoreconf -fiv
     35 ./configure --with-apxs=PATH --enable-msva
     36 make
     37 make install
     38 # Configure & restart apache
    4139
     40Configuration
     41-------------
    4242
    43 
    44 II.   AUTHORS
    45 
    46       Paul Querna <chip at force-elite.com>
    47       Nikos Mavrogiannopoulos <nmav at gnutls.org>
    48       Dash Shendy <neuromancer at dash.za.net>
    49 
    50 III.  MAINTAINERS
    51 
    52       Dash Shendy <neuromancer at dash.za.net>
    53       Execute `autoreconf -v -i -f` to Auto-generate files
    54 
    55 IV.   LICENSE
    56 
    57       Apache License, Version 2.0 (see the LICENSE file for details)
    58 
    59 V.    PREREQUISITES
    60 
    61       * GnuTLS          >= 2.12.6 <http://www.gnu.org/software/gnutls/>
    62       * Apache HTTPD    >= 2.0.42 <http://httpd.apache.org/>
    63       *                 >= 2.1.5-dev
    64       * ARP Memcache    >= 0.7.0 (Optinal)
    65 
    66 
    67 VI.   INSTALLATION
    68 
    69       * tar xzvf mod_gnutls-version.tar.gz
    70       * cd mod_gnutls-version/
    71       * ./configure --with-apxs=PATH --with-apr-memcache-prefix=PATH \
    72         --with-apr-memcache-libs=PATH --with-apr-memcache-includes=PATH
    73       * make
    74       * make install
    75       * Configure & restart apache
    76 
    77 VII.  BASIC CONFIGURATION
    78 
    79       LoadModule gnutls_module modules/mod_gnutls.so
    80      
    81       # mod_gnutls can optionally use a memcached server to store it's SSL
    82       # Sessions.  This is useful in a cluster environment, where you want all
    83       # of your servers to share a single SSL session cache.
    84       #GnuTLSCache memcache "127.0.0.1 server2.example.com server3.example.com"
    85      
    86       # The Default method is to use a DBM backed Cache.  It isn't super fast,
    87       # but it is portable and does not require another server to be running
    88       # like memcached.
    89       GnuTLSCache dbm conf/gnutls_cache
    90      
    91       <VirtualHost 1.2.3.4:443>
    92 
    93         # Enable mod_gnutls handlers for this virtual host
    94         GnuTLSEnable On
    95      
    96         # This is the private key for your server
    97         GnuTLSX509KeyFile conf/server.key
    98      
    99         # This is the server certificate
    100         GnuTLSX509CertificateFile conf/server.cert
    101 
    102       </VirtualHost>
    103      
    104       # A more advanced configuration
    105       GnuTLSCache dbm "/var/cache/www-tls-cache/cache"
    106       GnuTLSCacheTimeout 600
    107       NameVirtualHost 1.2.3.4:443
    108      
    109       <VirtualHost 1.2.3.4:443>
    110 
    111         Servername server.com:443
    112         GnuTLSEnable on
    113         GnuTLSPriority NORMAL
    114 
    115         # Export exactly the same environment variables as mod_ssl to CGI
    116         # scripts.
    117         GNUTLSExportCertificates on
    118      
    119         GnuTLSX509CertificateFile /etc/apache2/server-cert.pem
    120         GnuTLSX509KeyFile /etc/apache2/server-key.pem
    121      
    122         # To enable SRP you must have these files installed.  Check the gnutls
    123         # srptool.
    124         GnuTLSSRPPasswdFile /etc/apache2/tpasswd
    125         GnuTLSSRPPasswdConfFile /etc/apache2/tpasswd.conf
    126      
    127         # In order to verify client certificates.  Other options to
    128         # GnuTLSClientVerify could be ignore or require.  The
    129         # GnuTLSClientCAFile contains the CAs to verify client certificates.
    130         GnuTLSClientVerify request
    131         GnuTLSX509CAFile ca.pem
    132 
    133       </VirtualHost>
    134      
    135       # A setup for OpenPGP and X.509 authentication
    136       <VirtualHost 1.2.3.4:443>
    137 
    138         Servername crystal.lan:443
    139         GnuTLSEnable on
    140         GnuTLSPriorities NORMAL:+COMP-NULL
    141      
    142         # Setup the openpgp keys
    143         GnuTLSPGPCertificateFile /etc/apache2/test.pub.asc
    144         GnuTLSPGPKeyFile /etc/apache2/test.sec.asc
    145      
    146         # - and the X.509 keys
    147         GnuTLSCertificateFile /etc/apache2/server-cert.pem
    148         GnuTLSKeyFile /etc/apache2/server-key.pem
    149 
    150         GnuTLSClientVerify ignore
    151      
    152         # To avoid using the default DH params
    153         GnuTLSDHFile /etc/apache2/dh.pem
    154      
    155         # These are only needed if GnuTLSClientVerify != ignore
    156         GnuTLSClientCAFile ca.pem
    157         GnuTLSPGPKeyringFile /etc/apache2/ring.asc
    158 
    159       </VirtualHost>
    160 
    161 
    162 
    163 IX.   CREATE OPENPGP CREDENTIALS FOR THE SERVER
    164 
    165       mod_gnutls currently cannot read encrypted OpenPGP credentials.  That is,
    166       when you generate a key with gpg and gpg prompts you for a passphrase,
    167       just press enter.  Then press enter again, to confirm an empty
    168       passphrase.  http://news.gmane.org/gmane.comp.apache.outoforder.modules
    169 
    170       These instructions are from the GnuTLS manual:
    171       http://www.gnu.org/software/gnutls/manual/html_node/Invoking-gnutls_002dserv.html#Invoking-gnutls_002dserv
    172 
    173         $ gpg --gen-key
    174         ...enter whatever details you want, use 'test.gnutls.org' as name...
    175 
    176       Make a note of the OpenPGP key identifier of the newly generated key,
    177       here it was 5D1D14D8.  You will need to export the key for GnuTLS to be
    178       able to use it.
    179 
    180          $ gpg -a --export 5D1D14D8 > openpgp-server.txt
    181          $ gpg -a --export-secret-keys 5D1D14D8 > openpgp-server-key.txt
     43 Please see doc/mod_gnutls_manual.mdwn for more details.
Note: See TracChangeset for help on using the changeset viewer.