source: mod_gnutls/README @ 37b52ea

debian/masterdebian/stretch-backportsjessie-backportsupstream
Last change on this file since 37b52ea was 0acdcd1, checked in by Dash Shendy <neuromancer@…>, 8 years ago

Added INSTALLATION + MAINTAINERS sections

  • Property mode set to 100644
File size: 5.8 KB
Line 
1
2                mod_gnutls, Apache GnuTLS module.
3                =================================
4
5$LastChangedDate: $
6
7Contents:
8
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
17
18
19
20I.    ABOUT
21
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.
26
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.
33
34         Lines of Code in mod_ssl: 15,324
35         Lines of Code in mod_gnutls: 3,594
36
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.
41
42
43
44II.   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
50III.  MAINTAINERS
51
52      Dash Shendy <neuromancer at dash.za.net>
53      Execute `autoreconf -v -i -f` to Auto-generate files
54
55IV.   LICENSE
56
57      Apache License, Version 2.0 (see the LICENSE file for details)
58
59V.    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
67VI.   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
77VII.  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
163IX.   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
Note: See TracBrowser for help on using the repository browser.