Changeset 19e80a5 in mod_gnutls for doc/mod_gnutls_manual.mdwn


Ignore:
Timestamp:
Jan 28, 2019, 2:50:38 PM (21 months ago)
Author:
Fiona Klute <fiona.klute@…>
Branches:
debian/master
Children:
102aa67
Parents:
0931b35 (diff), ea9c699 (diff)
Note: this is a merge changeset, the changes displayed below correspond to the merge itself.
Use the (diff) links above to see all the changes relative to each parent.
Message:

Update upstream source from tag 'upstream/0.9.0'

Update to upstream version '0.9.0'
with Debian dir 619b546038886b240d2c8e61ee1a1b13ce0867d7

File:
1 edited

Legend:

Unmodified
Added
Removed
  • doc/mod_gnutls_manual.mdwn

    r0931b35 r19e80a5  
    44
    55`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
    7 Layer (SSL)) using the GnuTLS library.  More information about the
    8 module can be found at [the project's website](https://mod.gnutls.org/).
     6(HTTP over Transport Layer Security (TLS)) using the GnuTLS library.
     7More information about the module can be found at
     8[the project's website](https://mod.gnutls.org/).
    99
    1010* * * * *
     
    4848    LoadModule gnutls_module modules/mod_gnutls.so
    4949
     50Note on HTTP/2
     51--------------
     52
     53HTTP/2 is supported with `mod_gnutls`. However, full support requires
     54compiling with GnuTLS 3.6.3 or later. When using lower versions all
     55virtual hosts using `mod_gnutls` with overlapping IP/port combinations
     56need to use identical `Protocols` directives for protocol negotiation
     57to work correctly.
     58
     59The technical reason is that using HTTP/2 requires ALPN (Application
     60Layer Protocol Negotiation) to be set up before GnuTLS parses the TLS
     61ClientHello message, but earlier hooks cannot use
     62`gnutls_server_name_get()` to retrieve SNI (Server Name Indication)
     63data for virtual host selection. Because of this `mod_gnutls` provides
     64its own early SNI parser, which requires the `gnutls_ext_raw_parse()`
     65function introduced in GnuTLS 3.6.3 to retrieve the extension data in
     66a *pre* client hello hook.
     67
     68During build `./configure` will report "Early SNI: yes" if your
     69version of GnuTLS is new enough.
     70
    5071* * * * *
    5172
     
    7192Configure TLS Session Cache
    7293
    73     GnuTLSCache [dbm|gdbm|memcache|none] [PATH|SERVERLIST|-]
     94    GnuTLSCache (shmcb|dbm|memcache|...|none)[:PARAMETERS]
    7495
    7596Default: `GnuTLSCache none`\
    7697Context: server config
    7798
    78 This directive configures the TLS Session Cache for `mod_gnutls`.
    79 This could be shared between machines of different architectures. If a
    80 DBM cache is used, access is serialized using the `gnutls-cache`
    81 mutex. Which DBM types are available is part of the APR (Apache
    82 Portable Runtime) compile time configuration.
    83 
    84 `dbm` (Requires Berkeley DBM)
    85 :   Uses the Berkeley DB backend of APR DBM to cache TLS Session
    86         data.
    87 
    88         The argument is a relative or absolute path to be used as
    89     the DBM Cache file. This is compatible with most operating
    90     systems.
    91 
    92 `gdbm` (Requires GDBM)
    93 :   Uses the GDBM backend of APR DBM to cache TLS Session data.
    94 
    95     The argument is a relative or absolute path to be used as the DBM
    96     Cache file.
     99This directive configures the TLS Session Cache for `mod_gnutls`. This
     100could be shared between machines of different architectures. If the
     101selected cache implementation is not thread-safe, access is serialized
     102using the `gnutls-cache` mutex.
     103
     104Which cache implementations are available depends on your Apache
     105installation and configuration, `mod_gnutls` can use any socache
     106provider. In general you will need to load a `mod_socache_PROVIDER`
     107module. Common options are described below, please check the Apache
     108HTTPD documentation for details on available providers and their
     109configuration.
     110
     111`shmcb`
     112:   Uses a shared memory segment. This is a high performance local
     113    cache. The parameter is a relative or absolute path to be used if
     114    the local shared memory implementation requires one, followed by
     115    the cache size in bytes enclosed in parentheses.
     116
     117    Example: `shmcb:cache/gnutls_cache(65536)`
     118
     119`dbm`
     120:   Uses a DBM cache file. The parameter is a relative or absolute
     121    path to be used as the DBM cache file.
     122
     123    Example: `dbm:cache/gnutls_cache`
    97124
    98125`memcache`
    99 :   Uses memcached server(s) to cache TLS Session data.
    100 
    101     The argument is a space separated list of servers. If no port
    102     number is supplied, the default of 11211 is used.  This can be
    103     used to share a session cache between all servers in a cluster.
     126:   Uses memcached server(s) to cache TLS session data. The parameter
     127    is a comma separated list of servers (host:port). This can be used
     128    to share a session cache between all servers in a cluster.
     129
     130    Example: `memcache:memcache.example.com:12345,memcache2.example.com:12345`
    104131
    105132`none`
    106 :   Turns off all caching of TLS Sessions.
    107 
    108     This can significantly reduce the performance of `mod_gnutls` since
    109     even followup connections by a client must renegotiate parameters
    110     instead of reusing old ones.  This is the default, since it
    111     requires no configuration.
     133:   Turns off all caching of TLS sessions.
     134
     135    This can significantly reduce the performance of `mod_gnutls`
     136    since even followup connections by a client must renegotiate
     137    parameters instead of reusing old ones. This is the default, since
     138    it requires no configuration.
     139
     140    Session tickets are an alternative to using a session cache,
     141    please see `GnuTLSSessionTickets`. Note that for TLS 1.3 GnuTLS
     142    supports resumption using session tickets only as of version
     143    3.6.4.
    112144
    113145### GnuTLSCacheTimeout
     
    118150
    119151Default: `GnuTLSCacheTimeout 300`\
    120 Context: server config
    121 
    122 Sets the timeout for TLS Session Cache entries expiration. This value
    123 is also used for OCSP responses if they do not contain a `nextUpdate`
    124 time.
     152Context: server config, virtual host
     153
     154Sets the expiration timeout for cached TLS sessions.
    125155
    126156### GnuTLSSessionTickets
     
    130160    GnuTLSSessionTickets [on|off]
    131161
    132 Default: `off`\
    133 Context: server config, virtual host
    134 
    135 To avoid storing data for TLS session resumption the server can
    136 provide clients with tickets, to use on return. Tickets are an
    137 alternative to using a session cache, mostly used for busy servers
    138 with limited storage. For a pool of servers this option is not
    139 recommended since the tickets are bound to the issuing server only.
     162Default: `on` with GnuTLS 3.6.4 and newer, `off` otherwise\
     163Context: server config, virtual host
     164
     165Session tickets allow TLS session resumption without session state
     166stored on the server, using encrypted tickets provided to the clients
     167instead. Tickets are an alternative to using a session cache, and
     168currently the only session resumption mechanism in TLS 1.3. For a pool
     169of servers this option is not recommended since the tickets are bound
     170to the issuing server only.
    140171
    141172If this option is set in the global configuration, virtual hosts
    142173without a `GnuTLSSessionTickets` setting will use the global setting.
    143174
    144 *Warning:* Currently the master key that protects the tickets is
    145 generated only on server start, and there is no mechanism to roll over
    146 the key. If session tickets are enabled it is highly recommened to
    147 restart the server regularly to protect past sessions in case an
    148 attacker gains access to server memory.
     175*Warning:* With GnuTLS version before 3.6.4 the master key that
     176protects the tickets is generated only on server start, and there is
     177no mechanism to roll over the key. If session tickets are enabled it
     178is highly recommended to restart the server regularly to protect past
     179sessions in case an attacker gains access to server memory. GnuTLS
     1803.6.4 introduced an automatic TOTP-based key rollover, so this warning
     181does not apply any more and tickets are enabled by default.
    149182
    150183### GnuTLSClientVerify
     
    204237    GnuTLSPriorities NORMAL:+CIPHER_0:+CIPHER_1:...:+CIPHER_N
    205238
    206 Default: *none*\
    207 Context: server config, virtual host
    208 
    209 Takes a colon separated list of protocol version, ciphers, key
    210 exchange methods message authentication codes, and compression methods
    211 to enable. The allowed keywords are specified in the
    212 `gnutls_priority_init()` function of GnuTLS.
    213 
    214 Please refer to [the GnuTLS documentation](https://gnutls.org/manual/html_node/Priority-Strings.html#Priority-Strings)
    215 for details. A few commonly used sets are listed below, note that
    216 their exact meaning may change with GnuTLS versions.
    217 
    218 `PERFORMANCE`
    219 :   A list with all the secure cipher combinations sorted in terms of
    220     performance.
    221 
    222 `NORMAL`
    223 :   A list with all the secure cipher combinations sorted
    224     with respect to security margin (subjective term).
    225 
    226 `SECURE128`
    227 :   A list with all the secure cipher suites that offer a security level
    228     of 128-bit or more.
    229 
    230 `PFS`
    231 :   Only cipher suites offering perfect forward secrecy (ECDHE and DHE),
    232     sorted by security margin.
    233 
    234 You can add or remove algorithms using the `+` and `!` prefixes
    235 respectively. For example, in order to use the `NORMAL` set but
    236 disable TLS 1.0 and 1.1 you can use the string
    237 `NORMAL:!VERS-TLS1.0:!VERS-TLS1.1`.
    238 
    239 You can find a list of all supported Ciphers, Versions, MACs, etc.  by
    240 running `gnutls-cli --list`.
     239Default: `NORMAL`\
     240Context: server config, virtual host
     241
     242Sets the allowed protocol version(s), ciphers, key exchange methods,
     243message authentication codes, and other TLS parameters for the server.
     244The parameter is a GnuTLS priority string as described in the
     245[the GnuTLS documentation](https://gnutls.org/manual/html_node/Priority-Strings.html).
     246
     247For example, to disable TLS 1.0 use `NORMAL:-VERS-TLS1.0`.
    241248
    242249### GnuTLSP11Module
     
    289296server and the client to CGI scripts via the `SSL_SERVER_CERT` and
    290297`SSL_CLIENT_CERT` environment variables. The exported certificates
    291 will be PEM-encoded (if X.509) or ASCII-armored (if OpenPGP) up to the
    292 size given.  The type of the certificate will be exported in
    293 `SSL_SERVER_CERT_TYPE` and `SSL_CLIENT_CERT_TYPE`.
     298will be PEM-encoded, limited to the given size. The type of the
     299certificate will be exported in `SSL_SERVER_CERT_TYPE` and
     300`SSL_CLIENT_CERT_TYPE`.
    294301
    295302SIZE should be an integer number of bytes, or may be written with a
    296303trailing `K` to indicate kibibytes.  `off` means the same thing as
    297304`0`, in which case the certificates will not be exported to the
    298 environment.  `on` is an alias for `16K`. If a non-zero size is
     305environment. `on` is an alias for `16K`. If a non-zero size is
    299306specified for this directive, but a certificate is too large to fit in
    300307the buffer, then the corresponding environment variable will contain
     
    309316### GnuTLSCertificateFile
    310317
    311 Set to the PEM Encoded Server Certificate
     318Set the PEM encoded server certificate or certificate chain
    312319
    313320    GnuTLSCertificateFile FILEPATH
     
    316323Context: server config, virtual host
    317324
    318 Takes an absolute or relative path to a PEM-encoded X.509 certificate to
    319 use as this Server's End Entity (EE) certificate. If you need to supply
    320 certificates for intermediate Certificate Authorities (iCAs), they
    321 should be listed in sequence in the file, from EE to the iCA closest to
    322 the root CA. Optionally, you can also include the root CA's certificate
    323 as the last certificate in the list.
    324 
    325 Since version 0.7 this can be a PKCS #11 URL.
     325FILEPATH is an absolute or relative path to a file containing the
     326PEM-encoded X.509 certificate to use as this Server's End Entity (EE)
     327certificate, and optionally those of the issuing Certificate
     328Authorities (CAs). If the file contains multiple certificates they
     329should be ordered from EE to the CA closest to the root CA (or the
     330root CA itself).
     331
     332Including at least the immediately issuing CA is highly recommended
     333because it is required for OCSP stapling.
     334
     335Since version 0.7 this can be a PKCS #11 URL instead of a file.
     336
     337On Linux and other Unix-like systems you can create the file with a
     338command like this (assuming "CA 1" issued the server certificate and
     339has been issued by "Root CA" itself):
     340
     341        $ cat server.pem ca-1.pem root-ca.pem >server-chain.pem
    326342
    327343### GnuTLSKeyFile
     
    357373as a Certificate Authority with Client Certificate Authentication.
    358374This file may contain a list of trusted authorities.
    359 
    360 OpenPGP Certificate Authentication
    361 ----------------------------------
    362 
    363 *Warning:* OpenPGP support has been deprecated in GnuTLS since version
    364 3.5.9 and will be removed completely. Consequently, OpenPGP support in
    365 `mod_gnutls` is deprecated as well and will be removed in a future
    366 release.
    367 
    368 ### GnuTLSPGPCertificateFile
    369 
    370 Set to a base64 Encoded Server OpenPGP Certificate
    371 
    372     GnuTLSPGPCertificateFile FILEPATH
    373 
    374 Default: *none*\
    375 Context: server config, virtual host
    376 
    377 Takes an absolute or relative path to a base64 Encoded OpenPGP
    378 Certificate to use as this Server's Certificate.
    379 
    380 ### GnuTLSPGPKeyFile
    381 
    382 Set to the Server OpenPGP Secret Key
    383 
    384     GnuTLSPGPKeyFile FILEPATH
    385 
    386 Default: *none*\
    387 Context: server config, virtual host
    388 
    389 Takes an absolute or relative path to the Server Private Key. This key
    390 cannot currently be password protected.
    391 
    392 **Security Warning:**\
    393  This private key must be protected. It is read while Apache is still
    394 running as root, and does not need to be readable by the nobody or
    395 apache user.
    396 
    397 ### GnuTLSPGPKeyringFile
    398 
    399 Set to a base64 Encoded key ring
    400 
    401     GnuTLSPGPKeyringFile FILEPATH
    402 
    403 Default: *none*\
    404 Context: server config, virtual host
    405 
    406 Takes an absolute or relative path to a base64 Encoded Certificate
    407 list (key ring) to use as a means of verification of Client
    408 Certificates.  This file should contain a list of trusted signers.
    409375
    410376SRP Authentication
     
    531497    GnuTLSProxyPriorities NORMAL:+CIPHER_0:+CIPHER_1:...:+CIPHER_N
    532498
    533 Default: *none*\
    534 Context: server config, virtual host
    535 
    536 This option is used to set the allowed ciphers, key exchange
    537 algorithms, MACs and compression methods for proxy connections. It
    538 takes the same parameters as `GnuTLSPriorities`. Required if
    539 `GnuTLSProxyEngine` is `On`.
     499Default: `NORMAL`\
     500Context: server config, virtual host
     501
     502Sets the allowed protocol version(s), ciphers, key exchange methods,
     503message authentication codes, and other TLS parameters for TLS proxy
     504connections. Like for `GnuTLSPriorities` the parameter is a GnuTLS
     505priority string as described in the
     506[the GnuTLS documentation](https://gnutls.org/manual/html_node/Priority-Strings.html).
    540507
    541508OCSP Stapling Configuration
     
    548515    GnuTLSOCSPStapling [On|Off]
    549516
    550 Default: *off*\
     517Default: *on* if requirements are met, *off* otherwise\
    551518Context: server config, virtual host
    552519
    553520OCSP stapling, formally known as the TLS Certificate Status Request
    554 extension, allows the server to provide the client with an OCSP
    555 response for its certificate during the handshake. This way the client
    556 does not have to send an OCSP request to the CA to check the
    557 certificate status, which offers privacy and performance advantages.
     521extension, allows the server to provide the client with a cached OCSP
     522response for its certificate during the handshake. With OCSP stapling
     523the client does not have to send an OCSP request to the issuer CA to
     524check the certificate status, which offers privacy and performance
     525advantages, and avoids the security issue of how to handle errors that
     526prevent the client from getting a response.
    558527
    559528Using OCSP stapling has a few requirements:
    560529
    561 * Caching OCSP responses requires a cache, so `GnuTLSCache` must not
    562   be `none`.
    563530* `GnuTLSCertificateFile` must contain the issuer CA certificate in
    564531  addition to the server certificate so responses can be verified.
    565 * The certificate must either contain an OCSP access URI using HTTP,
    566   or `GnuTLSOCSPResponseFile` must be set.
     532* The server certificate must either contain an OCSP access URI using
     533  HTTP, or `GnuTLSOCSPResponseFile` must be set.
     534* Caching OCSP responses requires a cache to store responses. If
     535  `mod_socache_shmcb` is loaded `mod_gnutls` can set up the cache
     536  automatically without additional configuration, see
     537  `GnuTLSOCSPCache`.
     538
     539Stapling is activated by default if these requirements are met. If
     540`GnuTLSOCSPStapling` is explicitly set to `on` unmet requirements are
     541an error.
    567542
    568543OCSP cache updates are serialized using the `gnutls-ocsp` mutex.
     544
     545### GnuTLSOCSPCache
     546
     547OCSP stapling cache configuration
     548
     549        GnuTLSOCSPCache (shmcb|memcache|...|none)[:PARAMETERS]
     550
     551Default: `shmcb:gnutls_ocsp_cache`\
     552Context: server config
     553
     554This directive configures the OCSP stapling cache, and uses the same
     555syntax as `GnuTLSOCSPCache`. Please check there for details.
     556
     557The default should be reasonable for most servers and requires
     558[mod\_socache\_shmcb](http://httpd.apache.org/docs/current/en/mod/mod_socache_shmcb.html)
     559to be loaded. Servers with very many virtual hosts may need to
     560increase the default cache size via the parameters string, those with
     561few virtual hosts and memory constraints could save a few KB by reducing
     562it. Note that `mod_socache_dbm` has a size constraint for entries that
     563is generally too small for OCSP responses.
     564
     565If the selected cache implementation is not thread-safe, access
     566is serialized using the `gnutls-ocsp-cache` mutex.
     567
     568### GnuTLSOCSPAutoRefresh
     569
     570Regularly refresh cached OCSP response independent of TLS handshakes?
     571
     572    GnuTLSOCSPAutoRefresh [On|Off]
     573
     574Default: *on*\
     575Context: server config, virtual host
     576
     577By default `mod_gnutls` will regularly refresh the cached OCSP
     578response for hosts that have OCSP stapling enabled, regardless of
     579whether it is used. This has advantages over updating the OCSP
     580response only if a TLS handshake needs it:
     581
     582* Updating the cached response before it expires can hide short
     583  unavailability of the OCSP responder, if a repeated request is
     584  successful before the cache expires (see below).
     585
     586* Handshakes are not slowed down by fetching responses.
     587
     588The interval to the next request is determined as follows: After a
     589successful OCSP request the next one is scheduled for a random period
     590between `GnuTLSOCSPFuzzTime` and half of it before
     591`GnuTLSOCSPCacheTimeout` expires. For example, if the cache timeout is
     5923600 seconds and the fuzz time 600 seconds, the next request will be
     593sent after 3000 to 3300 seconds. If the validity period of the
     594response expires before then, the selected interval is halved until it
     595is smaller than the time until expiry. If an OCSP request fails, it is
     596retried after `GnuTLSOCSPFailureTimeout`.
     597
     598Regularly updating the OCSP cache requires `mod_watchdog`,
     599`mod_gnutls` will fall back to updating the OCSP cache during
     600handshakes if `mod_watchdog` is not available or this option is set to
     601`Off`.
    569602
    570603### GnuTLSOCSPCheckNonce
     
    641674request.
    642675
     676### GnuTLSOCSPFuzzTime
     677
     678Update the cached OCSP response up to this time before the cache expires
     679
     680    GnuTLSOCSPFuzzTime SECONDS
     681
     682Default: *larger of GnuTLSOCSPCacheTimeout / 8 and GnuTLSOCSPFailureTimeout \* 2*\
     683Context: server config, virtual host
     684
     685Refreshing the cached response before it expires hides short OCSP
     686responder unavailability. See `GnuTLSOCSPAutoRefresh` for how this
     687value is used, using at least twice `GnuTLSOCSPFailureTimeout` is
     688recommended.
     689
    643690### GnuTLSOCSPSocketTimeout
    644691
     
    666713======================
    667714
    668 Simple Standard TLS Example
    669 ---------------------------
    670 
    671 The following is an example of simple TLS hosting, using one IP
    672 Addresses for each virtual host.
     715Minimal Example
     716---------------
     717
     718A minimal server configuration using mod_gnutls might look like this
     719(other than the default setup):
     720
     721     # Load mod_gnutls into Apache.
     722     LoadModule gnutls_module modules/mod_gnutls.so
     723
     724         Listen 192.0.2.1:443
     725
     726     <VirtualHost _default_:443>
     727             # Standard virtual host stuff
     728         DocumentRoot /www/site1.example.com/html
     729         ServerName site1.example.com:443
     730         
     731                 # Minimal mod_gnutls setup: enable, and set credentials
     732                 GnuTLSEnable on
     733         GnuTLSCertificateFile conf/tls/site1_cert_chain.pem
     734         GnuTLSKeyFile conf/tls/site1_key.pem
     735     </VirtualHost>
     736
     737This gives you an HTTPS site using the GnuTLS `NORMAL` set of
     738ciphersuites. OCSP stapling will be enabled if the server certificate
     739contains an OCSP URI, `conf/tls/site1_cert_chain.pem` contains the
     740issuer certificate in addition to the server's, and
     741[mod\_socache\_shmcb](http://httpd.apache.org/docs/current/en/mod/mod_socache_shmcb.html)
     742is loaded. With Gnutls 3.6.4 or newer session tickets are enabled,
     743too.
     744
     745Virtual Hosts with Server Name Indication
     746-----------------------------------------
     747
     748`mod_gnutls` supports Server Name Indication (SNI), as specified in
     749[RFC 6066, Section 3](https://tools.ietf.org/html/rfc6066#section-3).
     750This allows hosting many TLS websites with a single IP address, you
     751can just add virtual host configurations. All recent browsers support
     752this standard. Here is an example using SNI:
    673753
    674754     # Load the module into Apache.
    675755     LoadModule gnutls_module modules/mod_gnutls.so
    676      GnuTLSCache gdbm /var/cache/www-tls-cache
    677      GnuTLSCacheTimeout 500
    678 
    679      # Without SNI you need one IP Address per-site.
     756         # This example server uses session tickets, no cache.
     757     GnuTLSSessionTickets on
     758
     759     # SNI allows hosting multiple sites using one IP address. This
     760     # could also be 'Listen *:443', just like '*:80' is common for
     761     # non-HTTPS
     762     Listen 198.51.100.1:443
     763
     764     <VirtualHost _default_:443>
     765         GnuTLSEnable on
     766         DocumentRoot /www/site1.example.com/html
     767         ServerName site1.example.com:443
     768         GnuTLSCertificateFile conf/tls/site1.crt
     769         GnuTLSKeyFile conf/tls/site1.key
     770     </VirtualHost>
     771
     772     <VirtualHost _default_:443>
     773         GnuTLSEnable on
     774         DocumentRoot /www/site2.example.com/html
     775         ServerName site2.example.com:443
     776         GnuTLSCertificateFile conf/tls/site2.crt
     777         GnuTLSKeyFile conf/tls/site2.key
     778     </VirtualHost>
     779
     780     <VirtualHost _default_:443>
     781         GnuTLSEnable on
     782         DocumentRoot /www/site3.example.com/html
     783         ServerName site3.example.com:443
     784         GnuTLSCertificateFile conf/tls/site3.crt
     785         GnuTLSKeyFile conf/tls/site3.key
     786         # Enable HTTP/2. With GnuTLS before version 3.6.3 all
     787         # virtual hosts in this example would have to share this
     788         # directive to work correctly.
     789         Protocols h2 http/1.1
     790     </VirtualHost>
     791
     792Virtual Hosts without SNI
     793-------------------------
     794
     795If you need to support clients that do not use SNI, you have to use a
     796unique IP address/port combination for each virtual host. In this
     797example all virtual hosts use the default port for HTTPS (443) and
     798different IP addresses.
     799
     800     # Load the module into Apache.
     801     LoadModule gnutls_module modules/mod_gnutls.so
     802         # This example server uses a session cache.
     803     GnuTLSCache dbm:/var/cache/www-tls-cache
     804     GnuTLSCacheTimeout 1200
     805
     806     # Without SNI you need one IP Address per site. The IP addresses
     807         # are listed separately for clarity, you could also use "Listen 443"
     808         # to use that port on all available IP addresses.
    680809     Listen 192.0.2.1:443
    681810     Listen 192.0.2.2:443
    682811     Listen 192.0.2.3:443
    683      Listen 192.0.2.4:443
    684812
    685813     <VirtualHost 192.0.2.1:443>
     
    703831
    704832     <VirtualHost 192.0.2.3:443>
    705          # This server enables SRP, OpenPGP and X.509 authentication.
     833         # This server enables SRP and X.509 authentication.
    706834         GnuTLSEnable on
    707          GnuTLSPriorities NORMAL:+SRP:+SRP-RSA:+SRP-DSS:+CTYPE-OPENPGP
     835         GnuTLSPriorities NORMAL:+SRP:+SRP-RSA:+SRP-DSS
    708836         DocumentRoot /www/site3.example.com/html
    709837         ServerName site3.example.com:443
     
    711839         GnuTLSKeyFile conf/tls/site3.key
    712840         GnuTLSClientVerify ignore
    713          GnuTLSPGPCertificateFile conf/tls/site3.pub.asc
    714          GnuTLSPGPKeyFile conf/tls/site3.sec.asc
    715841         GnuTLSSRPPasswdFile conf/tls/tpasswd.site3
    716842         GnuTLSSRPPasswdConfFile conf/tls/tpasswd.site3.conf
    717843     </VirtualHost>
    718844
    719      <VirtualHost 192.0.2.4:443>
    720          GnuTLSEnable on
    721          # %COMPAT disables some security features to enable maximum
    722          # compatibility with clients. Don't use this if you need strong
    723          # security.
    724          GnuTLSPriorities NORMAL:%COMPAT
    725          DocumentRoot /www/site4.example.com/html
    726          ServerName site4.example.com:443
    727          GnuTLSCertificateFile conf/tls/site4.crt
    728          GnuTLSKeyFile conf/tls/site4.key
    729      </VirtualHost>
    730 
    731 Server Name Indication Example
    732 ------------------------------
    733 
    734 `mod_gnutls` supports "Server Name Indication", as specified in
    735 [RFC 6066, Section 3](https://tools.ietf.org/html/rfc6066#section-3). This
    736 allows hosting many TLS websites with a single IP address. All recent
    737 browsers support this standard. Here is an example using SNI:
     845OCSP Stapling Example
     846---------------------
     847
     848This is an example with a customized OCSP stapling configuration. What
     849is a resonable cache timeout varies depending on how long your CA's
     850OCSP responses are valid. Some CAs provide responses that are valid
     851for multiple days, in that case timeout and fuzz time could be
     852significantly larger.
    738853
    739854     # Load the module into Apache.
    740855     LoadModule gnutls_module modules/mod_gnutls.so
    741 
    742      # SNI allows hosting multiple sites using one IP address. This
    743      # could also be 'Listen *:443', just like '*:80' is common for
    744      # non-HTTPS
    745      Listen 198.51.100.1:443
     856         # A 64K cache is more than enough for one response
     857     GnuTLSOCSPCache shmcb:ocsp_cache(65536)
     858
     859     Listen 192.0.2.1:443
    746860
    747861     <VirtualHost _default_:443>
    748          GnuTLSEnable on
    749          GnuTLSSessionTickets on
    750          GnuTLSPriorities NORMAL
    751          DocumentRoot /www/site1.example.com/html
    752          ServerName site1.example.com:443
    753          GnuTLSCertificateFile conf/tls/site1.crt
    754          GnuTLSKeyFile conf/tls/site1.key
    755      </VirtualHost>
    756 
    757      <VirtualHost _default_:443>
    758          GnuTLSEnable on
    759          GnuTLSPriorities NORMAL
    760          DocumentRoot /www/site2.example.com/html
    761          ServerName site2.example.com:443
    762          GnuTLSCertificateFile conf/tls/site2.crt
    763          GnuTLSKeyFile conf/tls/site2.key
    764      </VirtualHost>
    765 
    766      <VirtualHost _default_:443>
    767          GnuTLSEnable on
    768          GnuTLSPriorities NORMAL
    769          DocumentRoot /www/site3.example.com/html
    770          ServerName site3.example.com:443
    771          GnuTLSCertificateFile conf/tls/site3.crt
    772          GnuTLSKeyFile conf/tls/site3.key
    773      </VirtualHost>
    774 
    775      <VirtualHost _default_:443>
    776          GnuTLSEnable on
    777          GnuTLSPriorities NORMAL
    778          DocumentRoot /www/site4.example.com/html
    779          ServerName site4.example.com:443
    780          GnuTLSCertificateFile conf/tls/site4.crt
    781          GnuTLSKeyFile conf/tls/site4.key
    782      </VirtualHost>
    783 
    784 OCSP Stapling Example
    785 ---------------------
    786 
    787 This example uses an X.509 server certificate. The server will fetch
    788 OCSP responses from the responder listed in the certificate and store
    789 them im a memcached cache shared with another server.
    790 
    791      # Load the module into Apache.
    792      LoadModule gnutls_module modules/mod_gnutls.so
    793      GnuTLSCache memcache "192.0.2.1:11211 192.0.2.2:11211"
    794      GnuTLSCacheTimeout 600
    795 
    796      Listen 192.0.2.1:443
    797 
    798      <VirtualHost _default_:443>
    799          GnuTLSEnable          On
    800          GnuTLSPriorities      NORMAL
    801          DocumentRoot          /www/site1.example.com/html
    802          ServerName            site1.example.com:443
    803          GnuTLSCertificateFile conf/tls/site1.crt
    804          GnuTLSKeyFile         conf/tls/site1.key
    805          GnuTLSPriorities      NORMAL
    806          GnuTLSOCSPStapling    On
     862         GnuTLSEnable           On
     863         DocumentRoot           /www/site1.example.com/html
     864         ServerName             site1.example.com:443
     865         GnuTLSCertificateFile  conf/tls/site1_cert_chain.pem
     866         GnuTLSKeyFile          conf/tls/site1_key.pem
     867         GnuTLSOCSPStapling     On
     868                 # The cached OCSP response is kept for up to 4 hours,
     869                 # with updates scheduled every 3 to 3.5 hours.
     870         GnuTLSOCSPCacheTimeout 21600
     871                 GnuTLSOCSPFuzzTime     3600
    807872     </VirtualHost>
    808873
     
    9381003------------------
    9391004
    940 The PEM-encoded (X.509) or ASCII-armored (OpenPGP) server certificate
    941 (see the `GnuTLSExportCertificates` directive).
     1005The PEM-encoded (X.509) server certificate (see the
     1006`GnuTLSExportCertificates` directive).
    9421007
    9431008`SSL_SERVER_CERT_TYPE`
    9441009----------------------
    9451010
    946 The certificate type can be `X.509` or `OPENPGP`.
     1011The certificate type will be `X.509`.
    9471012
    9481013`SSL_CLIENT_CERT`
    9491014------------------
    9501015
    951 The PEM-encoded (X.509) or ASCII-armored (OpenPGP) client certificate
    952 (see the `GnuTLSExportCertificates` directive).
     1016PEM-encoded (X.509) client certificate, if any (see the
     1017`GnuTLSExportCertificates` directive).
    9531018
    9541019`SSL_CLIENT_CERT_TYPE`
    9551020----------------------
    9561021
    957 The certificate type can be `X.509` or `OPENPGP`.
     1022The certificate type will be `X.509`, if any.
Note: See TracChangeset for help on using the changeset viewer.