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