source: mod_gnutls/README @ b01d6a2

debian/masterdebian/stretch-backportsjessie-backportsmsvaupstream
Last change on this file since b01d6a2 was fe0c93a, checked in by Dash Shendy <neuromancer@…>, 8 years ago

Updated README

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