Changeset 71e9a5c in mod_gnutls for README


Ignore:
Timestamp:
Aug 22, 2015, 3:53:31 PM (6 years ago)
Author:
Daniel Kahn Gillmor <dkg@…>
Branches:
debian/master, debian/stretch-backports, jessie-backports
Children:
b837187
Parents:
2db6923 (diff), 4addf74 (diff)
Note: this is a merge changeset, the changes displayed below correspond to the merge itself.
Use the (diff) links above to see all the changes relative to each parent.
Message:

Merge tag 'upstream/0.7' into debian

Upstream version 0.7

File:
1 edited

Legend:

Unmodified
Added
Removed
  • README

    r2db6923 r71e9a5c  
     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  Thomas Klute <thomas2.klute@uni-dortmund.de>
    1813
     14Past maintainers and other contributors:
    1915
    20 I.    ABOUT
     16  Daniel Kahn Gillmor <dkg@fifthhorseman.net>
     17  Paul Querna <chip at force-elite.com>
     18  Nikos Mavrogiannopoulos <nmav at gnutls.org>
     19  Dash Shendy <neuromancer at dash.za.net>
    2120
    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.
     21Prerequisites
     22-------------
    2623
    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.
     24 * GnuTLS          >= 3.1.4 <http://www.gnutls.org/> (3.2.* or newer preferred)
     25 * Apache HTTPD    >= 2.2 <http://httpd.apache.org/> (2.4.* preferred)
     26 * autotools & gcc
     27 * APR Memcache    >= 0.7.0 (Optional)
     28 * libmsv          >= 0.1 (Optional, enable with ./configure --enable-msva)
     29 * pandoc   (for documentation, optional)
     30 * pdflatex (for PDF documentation, optional)
    3331
    34          Lines of Code in mod_ssl: 15,324
    35          Lines of Code in mod_gnutls: 3,594
     32Installation
     33------------
    3634
    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.
     35 tar xzvf mod_gnutls-version.tar.gz
     36 cd mod_gnutls-version/
     37 autoreconf -fiv
     38 ./configure
     39 make
     40 make install
     41 # Configure & restart apache
    4142
     43It is recommended to run "make check" before "make install". You may
     44need to pass TEST_HOST or TEST_IP to ./configure for the tests to work
     45correctly, please see test/README for details.
    4246
     47Configuration
     48-------------
    4349
    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
     50Please see doc/mod_gnutls_manual.mdwn for more details. If pandoc is
     51available, HTML and PDF (requires pdflatex) documentation will be
     52built and installed as well.
Note: See TracChangeset for help on using the changeset viewer.