aboutsummaryrefslogtreecommitdiffstats
path: root/README
blob: 34054b65b398a466f140ff3d3182a4b495f9370d (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
mod_gnutls 

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 ammount 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.

----------------------------

Author: Paul Querna <chip force-elite.com>

Heavily modified by Nikos Mavrogiannopoulos <nmav gnutls.org>

License: Apache Software License v2.0. (see the LICENSE file for details)

Current Status:
- SSL and TLS connections with all popular browsers work!
- Sets enviromental 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
- Support for Client Certificates
- Support for TLS-SRP

Basic Configuration:

LoadModule gnutls_module  modules/mod_gnutls.so

# mod_gnutls can optionaly use a memcached server to store it's SSL Sessions.
# This is useful in a cluster enviroment, 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>
    # insert other directives ... here ...

    # This enables the 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
# To 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>

Create OpenPGP credentials for the server:

IMPORTANT: 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