aboutsummaryrefslogtreecommitdiffstats
path: root/README
diff options
context:
space:
mode:
Diffstat (limited to 'README')
-rw-r--r--README232
1 files changed, 146 insertions, 86 deletions
diff --git a/README b/README
index 5198ed7..ad7f9c6 100644
--- a/README
+++ b/README
@@ -1,111 +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
139
140 GnuTLSClientVerify ignore
141
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
148
149 </VirtualHost>
150
151
152
153VI. CREATE OPENPGP CREDENTIALS FOR THE SERVER
154
155 mod_gnutls currently cannot read encrypted OpenPGP credentials. That is,
156 when you generate a key with gpg and gpg prompts you for a passphrase,
157 just press enter. Then press enter again, to confirm an empty
158 passphrase. http://news.gmane.org/gmane.comp.apache.outoforder.modules
95 159
96# setup the openpgp keys 160 These instructions are from the GnuTLS manual:
97 GnuTLSPGPCertificateFile /etc/apache2/test.pub.asc 161 http://www.gnu.org/software/gnutls/manual/html_node/Invoking-gnutls_002dserv.html#Invoking-gnutls_002dserv
98 GnuTLSPGPKeyFile /etc/apache2/test.sec.asc
99 162
100# and the X.509 keys 163 $ gpg --gen-key
101 GnuTLSCertificateFile /etc/apache2/server-cert.pem 164 ...enter whatever details you want, use 'test.gnutls.org' as name...
102 GnuTLSKeyFile /etc/apache2/server-key.pem
103 GnuTLSClientVerify ignore
104 165
105# To avoid using the default DH params 166 Make a note of the OpenPGP key identifier of the newly generated key,
106 GnuTLSDHFile /etc/apache2/dh.pem 167 here it was 5D1D14D8. You will need to export the key for GnuTLS to be
168 able to use it.
107 169
108# these are only needed if GnuTLSClientVerify != ignore 170 $ gpg -a --export 5D1D14D8 > openpgp-server.txt
109 GnuTLSClientCAFile ca.pem 171 $ gpg -a --export-secret-keys 5D1D14D8 > openpgp-server-key.txt
110 GnuTLSPGPKeyringFile /etc/apache2/ring.asc
111</VirtualHost>
generated by cgit (git 2.34.1) at 2025-10-24 21:29:49 +0000