aboutsummaryrefslogtreecommitdiffstats
path: root/README
blob: ad7f9c6f03cbfcc2aed64234d0ff8e62e40f4e58 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171

                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