source: mod_gnutls/doc/mod_gnutls_manual.mdwn @ 0cd8f3d

debian/masterdebian/stretch-backportsupstream
Last change on this file since 0cd8f3d was 0cd8f3d, checked in by Thomas Klute <thomas2.klute@…>, 3 years ago

Update OCSP stapling documentation

  • Property mode set to 100644
File size: 26.5 KB
RevLine 
[e7527b9]1% `mod_gnutls` Manual
[4ee45a1]2
3* * * * *
4
[bce7907]5`mod_gnutls` is a module for the Apache web server that provides HTTPS
6(HTTP over Transport Layer Security (TLS) or the older Secure Sockets
7Layer (SSL)) using the GnuTLS library.  More information about the
8module can be found at [the project's website](https://mod.gnutls.org/).
[4ee45a1]9
10* * * * *
11
12Compilation & Installation
[2b16350]13==========================
[4ee45a1]14
[e7527b9]15`mod_gnutls` uses the `./configure && make && make install` mechanism
16common to many Open Source programs.  Most of the dirty work is
17handled by either `./configure` or Apache's `apxs` utility. If you have
18built Apache modules before, there shouldn't be any surprises for you.
19
20The interesting options you can pass to configure are:
21
22`--with-apxs=PATH`
23:   This option is used to specify the location of the apxs utility that
24    was installed as part of apache. Specify the location of the
25    binary, not the directory it is located in.
26
[dc058b8]27`--with-apu-config=PATH`
28:   Path to APR Utility Library config tool (`apu-1-config`)
[e7527b9]29
30`--help`
31:   Provides a list of all available configure options.
[4ee45a1]32
[dff57b4]33It is recommended to run `make check` before installation. If your
34system doesn't have a loopback device with IPv6 and IPv4 support or
35`localhost` does not resolve to at least one of `[::1]` and
36`127.0.0.1`, you may have to set the `TEST_HOST` or `TEST_IP`
[dc058b8]37environment variables when running `./configure` to make the test
38suite work correctly.
39
[4ee45a1]40* * * * *
41
42Integration
[2b16350]43===========
[4ee45a1]44
[2b16350]45To activate `mod_gnutls` just add the following line to your httpd.conf
[4ee45a1]46and restart Apache:
47
[2b16350]48    LoadModule gnutls_module modules/mod_gnutls.so
[4ee45a1]49
50* * * * *
51
[2b16350]52Configuration Directives
53========================
[4ee45a1]54
[df49a2d]55General Options
56---------------
57
58### GnuTLSEnable
[4ee45a1]59
[2b16350]60Enable GnuTLS for this virtual host
[4ee45a1]61
[2b16350]62    GnuTLSEnable [on|off]
[4ee45a1]63
[2b16350]64Default: *off*\
65Context: virtual host
[4ee45a1]66
[2b16350]67This directive enables SSL/TLS Encryption for a Virtual Host.
[4ee45a1]68
[df49a2d]69### GnuTLSCache
[4ee45a1]70
[743e31f]71Configure TLS Session Cache
[4ee45a1]72
[2b16350]73    GnuTLSCache [dbm|gdbm|memcache|none] [PATH|SERVERLIST|-]
[4ee45a1]74
[2b16350]75Default: `GnuTLSCache none`\
76Context: server config
[4ee45a1]77
[743e31f]78This directive configures the TLS Session Cache for `mod_gnutls`.
[c005645]79This could be shared between machines of different architectures. If a
80DBM cache is used, access is serialized using the `gnutls-cache`
81mutex.
[4ee45a1]82
[2b16350]83`dbm` (Requires Berkeley DBM)
[743e31f]84:   Uses the default Berkeley DB backend of APR DBM to cache TLS
[444e6ed]85    Session data. The argument is a relative or absolute path to
[2b16350]86    be used as the DBM Cache file. This is compatible with most
87    operating systems, but needs the Apache Runtime to be compiled
88    with Berkeley DBM support.
[4ee45a1]89
[2b16350]90`gdbm`
[444e6ed]91:   Uses the GDBM backend of APR DBM to cache TLS Session data.
[4ee45a1]92
[2b16350]93    The argument is a relative or absolute path to be used as the DBM Cache
94    file.  This is the recommended option.
[4ee45a1]95
[2b16350]96`memcache`
[444e6ed]97:   Uses memcached server(s) to cache TLS Session data.
[4ee45a1]98
[2b16350]99    The argument is a space separated list of servers. If no port
100    number is supplied, the default of 11211 is used.  This can be
101    used to share a session cache between all servers in a cluster.
[4ee45a1]102
[2b16350]103`none`
[743e31f]104:   Turns off all caching of TLS Sessions.
[4ee45a1]105
[2b16350]106    This can significantly reduce the performance of `mod_gnutls` since
107    even followup connections by a client must renegotiate parameters
108    instead of reusing old ones.  This is the default, since it
109    requires no configuration.
[4ee45a1]110
[df49a2d]111### GnuTLSCacheTimeout
[4ee45a1]112
[743e31f]113Timeout for TLS Session Cache expiration
[4ee45a1]114
[2b16350]115    GnuTLSCacheTimeout SECONDS
[4ee45a1]116
[2b16350]117Default: `GnuTLSCacheTimeout 300`\
118Context: server config
[4ee45a1]119
[444e6ed]120Sets the timeout for TLS Session Cache entries expiration. This value
121is also used for OCSP responses if they do not contain a `nextUpdate`
122time.
[4ee45a1]123
[df49a2d]124### GnuTLSSessionTickets
[4ee45a1]125
[2b16350]126Enable Session Tickets for the server
[4ee45a1]127
[2b16350]128    GnuTLSSessionTickets [on|off]
[4ee45a1]129
[2b16350]130Default: `off`\
131Context: server config, virtual host
[4ee45a1]132
[444e6ed]133To avoid storing data for TLS session resumption the server can
134provide clients with tickets, to use on return. Tickets are an
[e9ef72c]135alternative to using a session cache, mostly used for busy servers
136with limited storage. For a pool of servers this option is not
137recommended since the tickets are bound to the issuing server only.
[4ee45a1]138
[e9ef72c]139If this option is set in the global configuration, virtual hosts
140without a `GnuTLSSessionTickets` setting will use the global setting.
141
142*Warning:* Currently the master key that protects the tickets is
143generated only on server start, and there is no mechanism to roll over
144the key. If session tickets are enabled it is highly recommened to
145restart the server regularly to protect past sessions in case an
146attacker gains access to server memory.
[4ee45a1]147
[df49a2d]148### GnuTLSClientVerify
[4ee45a1]149
[df49a2d]150Enable Client Certificate Verification
[4ee45a1]151
[2b16350]152    GnuTLSClientVerify [ignore|request|require]
[4ee45a1]153
[2b16350]154Default: `ignore`\
155Context: server config, virtual host, directory, .htaccess
[4ee45a1]156
[743e31f]157This directive controls the use of TLS Client Certificate
[2b16350]158Authentication. If used in the .htaccess context, it can force TLS
159re-negotiation.
[4ee45a1]160
[2b16350]161`ignore`
[743e31f]162:   `mod_gnutls` will ignore the contents of any TLS Client Certificates
[2b16350]163    sent. It will not request that the client sends a certificate.
[4ee45a1]164
[2b16350]165`request`
166:   The client certificate will be requested, but not required.
167    The Certificate will be validated if sent.  The output of the
168    validation status will be stored in the `SSL_CLIENT_VERIFY`
169    environment variable and can be `SUCCESS`, `FAILED` or `NONE`.
[4ee45a1]170
[2b16350]171`require`
172:   A Client certificate will be required. Any requests without a valid
173    client certificate will be denied.  The `SSL_CLIENT_VERIFY`
174    environment variable will only be set to `SUCCESS`.
[4ee45a1]175
[df49a2d]176### GnuTLSDHFile
[4ee45a1]177
[2b16350]178Set to the PKCS \#3 encoded Diffie Hellman parameters
[4ee45a1]179
[2b16350]180    GnuTLSDHFile FILEPATH
[4ee45a1]181
[2b16350]182Default: *none*\
183Context: server config, virtual host
[4ee45a1]184
[2b16350]185Takes an absolute or relative path to a PKCS \#3 encoded DH
186parameters.Those are used when the DHE key exchange method is enabled.
187You can generate this file using `certtool --generate-dh-params --bits
1882048`.  If not set `mod_gnutls` will use the included parameters.
[4ee45a1]189
[df49a2d]190### GnuTLSPriorities
[4ee45a1]191
[c3c96ca]192Set the allowed protocol versions, ciphers, key exchange algorithms,
193MACs and compression methods
[4ee45a1]194
[5409165]195    GnuTLSPriorities NORMAL:+CIPHER_0:+CIPHER_1:...:+CIPHER_N
[4ee45a1]196
[2b16350]197Default: *none*\
198Context: server config, virtual host
[4ee45a1]199
[c3c96ca]200Takes a colon separated list of protocol version, ciphers, key
201exchange methods message authentication codes, and compression methods
202to enable. The allowed keywords are specified in the
203`gnutls_priority_init()` function of GnuTLS.
[4ee45a1]204
[c3c96ca]205Please refer to [the GnuTLS documentation](https://gnutls.org/manual/html_node/Priority-Strings.html#Priority-Strings)
206for details. A few commonly used sets are listed below, note that
207their exact meaning may change with GnuTLS versions.
[4ee45a1]208
[2b16350]209`PERFORMANCE`
[c3c96ca]210:   A list with all the secure cipher combinations sorted in terms of
211    performance.
[4ee45a1]212
[2b16350]213`NORMAL`
214:   A list with all the secure cipher combinations sorted
215    with respect to security margin (subjective term).
[4ee45a1]216
[c3c96ca]217`SECURE128`
218:   A list with all the secure cipher suites that offer a security level
219    of 128-bit or more.
[4ee45a1]220
[c3c96ca]221`PFS`
222:   Only cipher suites offering perfect forward secrecy (ECDHE and DHE),
223    sorted by security margin.
[4ee45a1]224
[c3c96ca]225You can add or remove algorithms using the `+` and `!` prefixes
226respectively. For example, in order to use the `NORMAL` set but
227disable TLS 1.0 and 1.1 you can use the string
228`NORMAL:!VERS-TLS1.0:!VERS-TLS1.1`.
[4ee45a1]229
[2b16350]230You can find a list of all supported Ciphers, Versions, MACs, etc.  by
231running `gnutls-cli --list`.
[4ee45a1]232
[df49a2d]233### GnuTLSP11Module
[8873a06]234
[7764015]235Load this PKCS #11 module.
[8873a06]236
237    GnuTLSP11Module PATH_TO_LIBRARY
238
239Default: *none*\
240Context: server config
241
[9ca1f21]242Load this PKCS #11 provider module, instead of the system
243defaults. May occur multiple times to load multiple modules.
[8873a06]244
[df49a2d]245### GnuTLSPIN
[031acac]246
247Set the PIN to be used to access encrypted key files or PKCS #11 objects.
248
249    GnuTLSPIN XXXXXX
250
251Default: *none*\
252Context: server config, virtual host
253
254Takes a string to be used as a PIN for the protected objects in
255a security module, or as a key to be used to decrypt PKCS #8, PKCS #12,
256or openssl encrypted keys.
257
[df49a2d]258### GnuTLSSRKPIN
[031acac]259
[df49a2d]260Set the SRK PIN to be used to access the TPM.
[031acac]261
262    GnuTLSSRKPIN XXXXXX
263
264Default: *none*\
265Context: server config, virtual host
266
267Takes a string to be used as a PIN for the protected objects in
268the TPM module.
269
[df49a2d]270### GnuTLSExportCertificates
[4ee45a1]271
[2b16350]272Export the PEM encoded certificates to CGIs
[4ee45a1]273
[999cdec]274    GnuTLSExportCertificates [off|on|SIZE]
[4ee45a1]275
[2b16350]276Default: `off`\
277Context: server config, virtual host
[4ee45a1]278
[999cdec]279This directive configures exporting the full certificates of the
280server and the client to CGI scripts via the `SSL_SERVER_CERT` and
281`SSL_CLIENT_CERT` environment variables. The exported certificates
282will be PEM-encoded (if X.509) or ASCII-armored (if OpenPGP) up to the
283size given.  The type of the certificate will be exported in
284`SSL_SERVER_CERT_TYPE` and `SSL_CLIENT_CERT_TYPE`.
285
286SIZE should be an integer number of bytes, or may be written with a
287trailing `K` to indicate kibibytes.  `off` means the same thing as
288`0`, in which case the certificates will not be exported to the
289environment.  `on` is an alias for `16K`.  If a non-zero size is
290specified for this directive, but a certificate is too large to fit in
291the buffer, then the corresponding environment variable will contain
292the fixed string `GNUTLS_CERTIFICATE_SIZE_LIMIT_EXCEEDED`.
293
[2b16350]294With GnuTLSExportCertificates enabled, `mod_gnutls` exports the same
295environment variables to the CGI process as `mod_ssl`.
[4ee45a1]296
[df49a2d]297X.509 Certificate Authentication
298--------------------------------
299
300### GnuTLSCertificateFile
[d8ae2a0]301
[df49a2d]302Set to the PEM Encoded Server Certificate
303
304    GnuTLSCertificateFile FILEPATH
305
306Default: *none*\
307Context: server config, virtual host
308
309Takes an absolute or relative path to a PEM-encoded X.509 certificate to
310use as this Server's End Entity (EE) certificate. If you need to supply
311certificates for intermediate Certificate Authorities (iCAs), they
312should be listed in sequence in the file, from EE to the iCA closest to
313the root CA. Optionally, you can also include the root CA's certificate
314as the last certificate in the list.
315
316Since version 0.7 this can be a PKCS #11 URL.
317
318### GnuTLSKeyFile
319
320Set to the PEM Encoded Server Private Key
321
322    GnuTLSKeyFile FILEPATH
323
324Default: *none*\
325Context: server config, virtual host
326
327Takes an absolute or relative path to the Server Private Key. Set
328`GnuTLSPIN` if the key file is encrypted.
329
330Since version 0.7 this can be a PKCS #11 URL.
331
332**Security Warning:**\
333This private key must be protected. It is read while Apache is still
334running as root, and does not need to be readable by the nobody or
335apache user.
336
337### GnuTLSClientCAFile
338
339Set the PEM encoded Certificate Authority list to use for X.509 base
340client authentication
341
342    GnuTLSClientCAFile FILEPATH
343
344Default: *none*
345Context: server config, virtual host
346
347Takes an absolute or relative path to a PEM Encoded Certificate to use
348as a Certificate Authority with Client Certificate Authentication.
349This file may contain a list of trusted authorities.
350
351OpenPGP Certificate Authentication
352----------------------------------
353
354### GnuTLSPGPCertificateFile
355
356Set to a base64 Encoded Server OpenPGP Certificate
357
358    GnuTLSPGPCertificateFile FILEPATH
359
360Default: *none*\
361Context: server config, virtual host
362
363Takes an absolute or relative path to a base64 Encoded OpenPGP
364Certificate to use as this Server's Certificate.
365
366### GnuTLSPGPKeyFile
367
368Set to the Server OpenPGP Secret Key
369
370    GnuTLSPGPKeyFile FILEPATH
371
372Default: *none*\
373Context: server config, virtual host
374
375Takes an absolute or relative path to the Server Private Key. This key
376cannot currently be password protected.
377
378**Security Warning:**\
379 This private key must be protected. It is read while Apache is still
380running as root, and does not need to be readable by the nobody or
381apache user.
382
383### GnuTLSPGPKeyringFile
384
385Set to a base64 Encoded key ring
386
387    GnuTLSPGPKeyringFile FILEPATH
388
389Default: *none*\
390Context: server config, virtual host
391
392Takes an absolute or relative path to a base64 Encoded Certificate
393list (key ring) to use as a means of verification of Client
394Certificates.  This file should contain a list of trusted signers.
395
396SRP Authentication
397------------------
398
399### GnuTLSSRPPasswdFile
400
401Set to the SRP password file for SRP ciphersuites
402
403    GnuTLSSRPPasswdFile FILEPATH
404
405Default: *none*\
406Context: server config, virtual host
407
408Takes an absolute or relative path to an SRP password file. This is
409the same format as used in libsrp.  You can generate such file using
410the command `srptool --passwd /etc/tpasswd --passwd-conf
411/etc/tpasswd.conf -u test` to set a password for user test.  This
412password file holds the username, a password verifier and the
413dependency to the SRP parameters.
414
415### GnuTLSSRPPasswdConfFile
416
417Set to the SRP password.conf file for SRP ciphersuites
418
419    GnuTLSSRPPasswdConfFile FILEPATH
420
421Default: *none*\
422Context: server config, virtual host
423
424Takes an absolute or relative path to an SRP password.conf file. This
425is the same format as used in `libsrp`.  You can generate such file
426using the command `srptool --create-conf /etc/tpasswd.conf`.  This
427file holds the SRP parameters and is associate with the password file
428(the verifiers depends on these parameters).
429
430TLS Proxy Configuration
431-----------------------
432
433### GnuTLSProxyEngine
[d8ae2a0]434
435Enable TLS proxy connections for this virtual host
436
[a2e3c33]437    GnuTLSProxyEngine [on|off]
[d8ae2a0]438
439Default: *off*\
440Context: virtual host
441
442This directive enables support for TLS proxy connections for a virtual
443host.
444
[df49a2d]445### GnuTLSProxyCAFile
[d8ae2a0]446
[809c422]447Set to the PEM encoded Certificate Authority Certificate
[d8ae2a0]448
449    GnuTLSProxyCAFile FILEPATH
450
451Default: *none*\
452Context: server config, virtual host
453
[809c422]454Takes an absolute or relative path to a PEM encoded certificate to use
[d8ae2a0]455as a Certificate Authority when verifying certificates provided by
456proxy back end servers. This file may contain a list of trusted
457authorities. If not set, verification of TLS back end servers will
458always fail due to lack of a trusted CA.
459
[df49a2d]460### GnuTLSProxyCRLFile
[809c422]461
462Set to the PEM encoded Certificate Revocation List
463
464    GnuTLSProxyCRLFile FILEPATH
465
466Default: *none*\
467Context: server config, virtual host
468
469Takes an absolute or relative path to a PEM encoded Certificate
470Revocation List to use when verifying certificates provided by proxy
471back end servers. The file may contain a list of CRLs.
472
[df49a2d]473### GnuTLSProxyCertificateFile
[d8ae2a0]474
[809c422]475Set to the PEM encoded Client Certificate
[d8ae2a0]476
477    GnuTLSProxyCertificateFile FILEPATH
478
479Default: *none*\
480Context: server config, virtual host
481
[809c422]482Takes an absolute or relative path to a PEM encoded X.509 certificate
[d8ae2a0]483to use as this Server's End Entity (EE) client certificate for TLS
484client authentication in proxy TLS connections. If you need to supply
485certificates for intermediate Certificate Authorities (iCAs), they
486should be listed in sequence in the file, from EE to the iCA closest
487to the root CA. Optionally, you can also include the root CA's
488certificate as the last certificate in the list.
489
490If not set, TLS client authentication will be disabled for TLS proxy
491connections. If set, `GnuTLSProxyKeyFile` must be set as well to
492provide the matching private key.
493
[df49a2d]494### GnuTLSProxyKeyFile
[d8ae2a0]495
[809c422]496Set to the PEM encoded Private Key
[d8ae2a0]497
498    GnuTLSProxyKeyFile FILEPATH
499
500Default: *none*\
501Context: server config, virtual host
502
503Takes an absolute or relative path to the Private Key matching the
504certificate configured using the `GnuTLSProxyCertificateFile`
505directive. This key cannot currently be password protected.
506
507**Security Warning:**\
508This private key must be protected. It is read while Apache is still
509running as root, and does not need to be readable by the nobody or
510apache user.
511
[df49a2d]512### GnuTLSProxyPriorities
[f030883]513
514Set the allowed ciphers, key exchange algorithms, MACs and compression
515methods for proxy connections
516
517    GnuTLSProxyPriorities NORMAL:+CIPHER_0:+CIPHER_1:...:+CIPHER_N
518
519Default: *none*\
520Context: server config, virtual host
521
522This option is used to set the allowed ciphers, key exchange
523algorithms, MACs and compression methods for proxy connections. It
524takes the same parameters as `GnuTLSPriorities`. Required if
[a2e3c33]525`GnuTLSProxyEngine` is `On`.
[f030883]526
[df49a2d]527OCSP Stapling Configuration
528---------------------------
529
530### GnuTLSOCSPStapling
[5a5032f]531
[0cd8f3d]532Enable OCSP stapling for this (virtual) host.
[5a5032f]533
534    GnuTLSOCSPStapling [On|Off]
535
536Default: *off*\
537Context: server config, virtual host
538
539OCSP stapling, formally known as the TLS Certificate Status Request
540extension, allows the server to provide the client with an OCSP
541response for its certificate during the handshake. This way the client
542does not have to send an OCSP request to the CA to check the
543certificate status, which offers privacy and performance advantages.
544
545Using OCSP stapling has a few requirements:
546
547* Caching OCSP responses requires a cache, so `GnuTLSCache` must not
548  be `none`.
549* `GnuTLSCertificateFile` must contain the issuer CA certificate in
550  addition to the server certificate so responses can be verified.
551* The certificate must either contain an OCSP access URI using HTTP,
552  or `GnuTLSOCSPResponseFile` must be set.
553
554OCSP cache updates are serialized using the `gnutls-ocsp` mutex.
555
[df49a2d]556### GnuTLSOCSPResponseFile
[5a5032f]557
[0cd8f3d]558Read the OCSP response for stapling from this file instead of sending
559a request over HTTP.
[5a5032f]560
561    GnuTLSOCSPResponseFile /path/to/response.der
562
563Default: *empty*\
564Context: server config, virtual host
565
566The response file must be updated externally, for example using a cron
567job. This option is an alternative to the server fetching OCSP
568responses over HTTP. Reasons to use this option include:
569
570* Performing OCSP requests separate from the web server, to prevent slow
571  responses from stalling handshakes.
572* The issuer CA uses an access method other than HTTP.
573* Testing
574
[df49a2d]575### GnuTLSOCSPGraceTime
[5a5032f]576
[0cd8f3d]577Replace cached OCSP responses this many seconds before they expire.
[5a5032f]578
579    GnuTLSOCSPGraceTime SECONDS
580
581Default: *60*\
582Context: server config, virtual host
583
584A cached OCSP response should be updated a little before it expires to
585account for potential clock skew between server, CA, and client, as
[0cd8f3d]586well as transmission time in corner cases. Note that a response
587without a `nextUpdate` field will be subject to the default cache
588lifetime.
[5a5032f]589
[c6dda6d]590### GnuTLSOCSPFailureTimeout
591
[0cd8f3d]592Wait this many seconds before retrying a failed OCSP request.
[c6dda6d]593
594    GnuTLSOCSPFailureTimeout SECONDS
595
596Default: *300*\
597Context: server config, virtual host
598
599Retries of failed OCSP requests must be rate limited to avoid
600overloading both the server using mod_gnutls and the CA's OCSP
601responder. A shorter value increases the load on both sides, a longer
602one means that stapling will remain disabled for longer after a failed
603request.
604
[333bbc7]605### GnuTLSOCSPSocketTimeout
606
[0cd8f3d]607Timeout for TCP sockets used to send OCSP requests
[333bbc7]608
609    GnuTLSOCSPFailureTimeout SECONDS
610
611Default: *6*\
612Context: server config, virtual host
613
614Stalled OCSP requests must time out after a while to prevent stalling
615the server too much. However, if the timeout is too short requests may
616fail with a slow OCSP responder or high latency network
617connection. This parameter allows you to adjust the timeout if
618necessary.
619
620Note that this is not an upper limit for the completion of an OCSP
621request but a socket timeout. The connection will time out if there is
622no activity (successful send or receive) at all for the configured
623time.
624
[4ee45a1]625* * * * *
626
627Configuration Examples
[2b16350]628======================
[4ee45a1]629
[743e31f]630Simple Standard TLS Example
[2b16350]631---------------------------
[4ee45a1]632
[fc124e9]633The following is an example of simple TLS hosting, using one IP
634Addresses for each virtual host.
[4ee45a1]635
[2b16350]636     # Load the module into Apache.
637     LoadModule gnutls_module modules/mod_gnutls.so
638     GnuTLSCache gdbm /var/cache/www-tls-cache
639     GnuTLSCacheTimeout 500
[fc124e9]640
641     # Without SNI you need one IP Address per-site.
642     Listen 192.0.2.1:443
643     Listen 192.0.2.2:443
644     Listen 192.0.2.3:443
645     Listen 192.0.2.4:443
646
647     <VirtualHost 192.0.2.1:443>
648         GnuTLSEnable on
649         GnuTLSPriorities SECURE128
650         DocumentRoot /www/site1.example.com/html
651         ServerName site1.example.com:443
652         GnuTLSCertificateFile conf/tls/site1.crt
653         GnuTLSKeyFile conf/tls/site1.key
[2b16350]654     </VirtualHost>
[fc124e9]655
656     <VirtualHost 192.0.2.2:443>
657         # This virtual host enables SRP authentication
658         GnuTLSEnable on
659         GnuTLSPriorities NORMAL:+SRP
660         DocumentRoot /www/site2.example.com/html
661         ServerName site2.example.com:443
662         GnuTLSSRPPasswdFile conf/tls/tpasswd.site2
663         GnuTLSSRPPasswdConfFile conf/tls/tpasswd.site2.conf
[2b16350]664     </VirtualHost>
[fc124e9]665
666     <VirtualHost 192.0.2.3:443>
667         # This server enables SRP, OpenPGP and X.509 authentication.
668         GnuTLSEnable on
669         GnuTLSPriorities NORMAL:+SRP:+SRP-RSA:+SRP-DSS:+CTYPE-OPENPGP
670         DocumentRoot /www/site3.example.com/html
671         ServerName site3.example.com:443
672         GnuTLSCertificateFile conf/tls/site3.crt
673         GnuTLSKeyFile conf/tls/site3.key
674         GnuTLSClientVerify ignore
675         GnuTLSPGPCertificateFile conf/tls/site3.pub.asc
676         GnuTLSPGPKeyFile conf/tls/site3.sec.asc
677         GnuTLSSRPPasswdFile conf/tls/tpasswd.site3
678         GnuTLSSRPPasswdConfFile conf/tls/tpasswd.site3.conf
[2b16350]679     </VirtualHost>
[fc124e9]680
681     <VirtualHost 192.0.2.4:443>
682         GnuTLSEnable on
683         # %COMPAT disables some security features to enable maximum
684         # compatibility with clients. Don't use this if you need strong
685         # security.
686         GnuTLSPriorities NORMAL:%COMPAT
687         DocumentRoot /www/site4.example.com/html
688         ServerName site4.example.com:443
689         GnuTLSCertificateFile conf/tls/site4.crt
690         GnuTLSKeyFile conf/tls/site4.key
[2b16350]691     </VirtualHost>
692
693Server Name Indication Example
694------------------------------
695
[fc124e9]696`mod_gnutls` supports "Server Name Indication", as specified in
697RFC 3546. This allows hosting many TLS websites with a single IP
698address. All recent browsers support this standard. Here is an
699example using SNI:
[2b16350]700
701     # Load the module into Apache.
702     LoadModule gnutls_module modules/mod_gnutls.so
[fc124e9]703
704     # SNI allows hosting multiple sites using one IP address. This
705     # could also be 'Listen *:443', just like '*:80' is common for
706     # non-HTTPS
707     Listen 198.51.100.1:443
708
709     <VirtualHost _default_:443>
710         GnuTLSEnable on
711         GnuTLSSessionTickets on
712         GnuTLSPriorities NORMAL
713         DocumentRoot /www/site1.example.com/html
714         ServerName site1.example.com:443
715         GnuTLSCertificateFile conf/tls/site1.crt
716         GnuTLSKeyFile conf/tls/site1.key
[2b16350]717     </VirtualHost>
[4ee45a1]718
[fc124e9]719     <VirtualHost _default_:443>
720         GnuTLSEnable on
721         GnuTLSPriorities NORMAL
722         DocumentRoot /www/site2.example.com/html
723         ServerName site2.example.com:443
724         GnuTLSCertificateFile conf/tls/site2.crt
725         GnuTLSKeyFile conf/tls/site2.key
726     </VirtualHost>
[4ee45a1]727
[fc124e9]728     <VirtualHost _default_:443>
729         GnuTLSEnable on
730         GnuTLSPriorities NORMAL
731         DocumentRoot /www/site3.example.com/html
732         ServerName site3.example.com:443
733         GnuTLSCertificateFile conf/tls/site3.crt
734         GnuTLSKeyFile conf/tls/site3.key
735     </VirtualHost>
[4ee45a1]736
[fc124e9]737     <VirtualHost _default_:443>
738         GnuTLSEnable on
739         GnuTLSPriorities NORMAL
740         DocumentRoot /www/site4.example.com/html
741         ServerName site4.example.com:443
742         GnuTLSCertificateFile conf/tls/site4.crt
743         GnuTLSKeyFile conf/tls/site4.key
744     </VirtualHost>
[2b16350]745
[fc124e9]746OCSP Stapling Example
747---------------------
[2b16350]748
[fc124e9]749This example uses an X.509 server certificate. The server will fetch
750OCSP responses from the responder listed in the certificate and store
751them im a memcached cache shared with another server.
[2b16350]752
753     # Load the module into Apache.
754     LoadModule gnutls_module modules/mod_gnutls.so
[fc124e9]755     GnuTLSCache memcache "192.0.2.1:11211 192.0.2.2:11211"
[2b16350]756     GnuTLSCacheTimeout 600
[fc124e9]757
758     Listen 192.0.2.1:443
759
760     <VirtualHost _default_:443>
761         GnuTLSEnable          On
762         GnuTLSPriorities      NORMAL
763         DocumentRoot          /www/site1.example.com/html
764         ServerName            site1.example.com:443
765         GnuTLSCertificateFile conf/tls/site1.crt
766         GnuTLSKeyFile         conf/tls/site1.key
767         GnuTLSPriorities      NORMAL
768         GnuTLSOCSPStapling    On
[2b16350]769     </VirtualHost>
[4ee45a1]770
771* * * * *
772
[2b16350]773Environment Variables
774=====================
[4ee45a1]775
[2b16350]776`mod_gnutls` exports the following environment variables to scripts.
777These are compatible with `mod_ssl`.
[4ee45a1]778
[2b16350]779`HTTPS`
780-------
[4ee45a1]781
[2b16350]782Can be `on` or `off`
[4ee45a1]783
[2b16350]784`SSL_VERSION_LIBRARY`
785---------------------
[4ee45a1]786
[2b16350]787The version of the GnuTLS library
[4ee45a1]788
[2b16350]789`SSL_VERSION_INTERFACE`
790-----------------------
[4ee45a1]791
792The version of this module
793
[2b16350]794`SSL_PROTOCOL`
795--------------
[4ee45a1]796
[2b16350]797The SSL or TLS protocol name (such as `TLS 1.0` etc.)
[4ee45a1]798
[2b16350]799`SSL_CIPHER`
800------------
[4ee45a1]801
802The SSL or TLS cipher suite name
803
[2b16350]804`SSL_COMPRESS_METHOD`
805---------------------
[4ee45a1]806
[2b16350]807The negotiated compression method (`NULL` or `DEFLATE`)
[4ee45a1]808
[2b16350]809`SSL_SRP_USER`
810--------------
[4ee45a1]811
812The SRP username used for authentication (only set when
[2b16350]813`GnuTLSSRPPasswdFile` and `GnuTLSSRPPasswdConfFile` are configured).
[4ee45a1]814
[2b16350]815`SSL_CIPHER_USEKEYSIZE` & `SSL_CIPHER_ALGKEYSIZE`
816-------------------------------------------------
[4ee45a1]817
818The number if bits used in the used cipher algorithm.
819
820This does not fully reflect the security level since the size of
821RSA or DHE key exchange parameters affect the security level too.
822
[5674676]823`SSL_DH_PRIME_BITS`
824-------------------
825
826The number if bits in the modulus for the DH group, if DHE or static
827DH is used.
828
829This will not be set if DH is not used.
830
[2b16350]831`SSL_CIPHER_EXPORT`
832-------------------
[4ee45a1]833
[2b16350]834`True` or `False`. Whether the cipher suite negotiated is an export one.
[4ee45a1]835
[2b16350]836`SSL_SESSION_ID`
837----------------
[4ee45a1]838
839The session ID negotiated in this session. Can be the same during client
840reloads.
841
[2b16350]842`SSL_CLIENT_V_REMAIN`
843---------------------
[4ee45a1]844
845The number of days until the client's certificate is expired.
846
[2b16350]847`SSL_CLIENT_V_START`
848--------------------
[4ee45a1]849
850The activation time of client's certificate.
851
[2b16350]852`SSL_CLIENT_V_END`
853------------------
[4ee45a1]854
855The expiration time of client's certificate.
856
[2b16350]857`SSL_CLIENT_S_DN`
858-----------------
[4ee45a1]859
860The distinguished name of client's certificate in RFC2253 format.
861
[2b16350]862`SSL_CLIENT_I_DN`
863-----------------
[4ee45a1]864
865The SSL or TLS cipher suite name
866
[2b16350]867`SSL_CLIENT_S_AN%`
868------------------
[4ee45a1]869
[2b16350]870These will contain the alternative names of the client certificate (`%` is
[4ee45a1]871a number starting from zero).
872
[2b16350]873The values will be prepended by `DNSNAME:`, `RFC822NAME:` or `URI:`
[4ee45a1]874depending on the type.
875
[2b16350]876If it is not supported the value `UNSUPPORTED` will be set.
[4ee45a1]877
[2b16350]878`SSL_SERVER_M_SERIAL`
879---------------------
[4ee45a1]880
881The serial number of the server's certificate.
882
[2b16350]883`SSL_SERVER_M_VERSION`
884----------------------
[4ee45a1]885
886The version of the server's certificate.
887
[2b16350]888`SSL_SERVER_A_SIG`
889------------------
[4ee45a1]890
891The algorithm used for the signature in server's certificate.
892
[2b16350]893`SSL_SERVER_A_KEY`
894------------------
[4ee45a1]895
896The public key algorithm in server's certificate.
897
[999cdec]898`SSL_SERVER_CERT`
[2b16350]899------------------
[4ee45a1]900
[999cdec]901The PEM-encoded (X.509) or ASCII-armored (OpenPGP) server certificate
902(see the `GnuTLSExportCertificates` directive).
[4ee45a1]903
[2b16350]904`SSL_SERVER_CERT_TYPE`
905----------------------
[4ee45a1]906
[2b16350]907The certificate type can be `X.509` or `OPENPGP`.
[ac32bb5]908
[999cdec]909`SSL_CLIENT_CERT`
910------------------
911
912The PEM-encoded (X.509) or ASCII-armored (OpenPGP) client certificate
913(see the `GnuTLSExportCertificates` directive).
914
[ac32bb5]915`SSL_CLIENT_CERT_TYPE`
916----------------------
917
918The certificate type can be `X.509` or `OPENPGP`.
Note: See TracBrowser for help on using the repository browser.