Changeset d8afa3e in mod_gnutls for doc


Ignore:
Timestamp:
Dec 17, 2016, 6:56:34 PM (5 years ago)
Author:
Daniel Kahn Gillmor <dkg@…>
Branches:
debian/master, debian/stretch-backports, upstream
Children:
c598e21, d2b32f1
Parents:
ce12806 (diff), 677754f (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:

New upstream version 0.8.0

Location:
doc
Files:
1 added
1 edited

Legend:

Unmodified
Added
Removed
  • doc/mod_gnutls_manual.mdwn

    rce12806 rd8afa3e  
    5353========================
    5454
    55 `GnuTLSEnable`
    56 --------------
     55General Options
     56---------------
     57
     58### GnuTLSEnable
    5759
    5860Enable GnuTLS for this virtual host
     
    6567This directive enables SSL/TLS Encryption for a Virtual Host.
    6668
    67 `GnuTLSCache`
    68 -------------
    69 
    70 Configure SSL Session Cache
     69### GnuTLSCache
     70
     71Configure TLS Session Cache
    7172
    7273    GnuTLSCache [dbm|gdbm|memcache|none] [PATH|SERVERLIST|-]
     
    7576Context: server config
    7677
    77 This directive configures the SSL Session Cache for `mod_gnutls`.
    78 This could be shared between machines of different architectures.
     78This directive configures the TLS Session Cache for `mod_gnutls`.
     79This could be shared between machines of different architectures. If a
     80DBM cache is used, access is serialized using the `gnutls-cache`
     81mutex. Which DBM types are available is part of the APR (Apache
     82Portable Runtime) compile time configuration.
    7983
    8084`dbm` (Requires Berkeley DBM)
    81 :   Uses the default Berkeley DB backend of APR DBM to cache SSL
    82     Sessions results.  The argument is a relative or absolute path to
    83     be used as the DBM Cache file. This is compatible with most
    84     operating systems, but needs the Apache Runtime to be compiled
    85     with Berkeley DBM support.
    86 
    87 `gdbm`
    88 :   Uses the GDBM backend of APR DBM to cache SSL Sessions results.
    89 
    90     The argument is a relative or absolute path to be used as the DBM Cache
    91     file.  This is the recommended option.
     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.
    9297
    9398`memcache`
    94 :   Uses a memcached server to cache the SSL Session.
     99:   Uses memcached server(s) to cache TLS Session data.
    95100
    96101    The argument is a space separated list of servers. If no port
     
    99104
    100105`none`
    101 :   Turns off all caching of SSL Sessions.
     106:   Turns off all caching of TLS Sessions.
    102107
    103108    This can significantly reduce the performance of `mod_gnutls` since
     
    106111    requires no configuration.
    107112
    108 `GnuTLSCacheTimeout`
    109 --------------------
    110 
    111 Timeout for SSL Session Cache expiration
     113### GnuTLSCacheTimeout
     114
     115Timeout for TLS Session Cache expiration
    112116
    113117    GnuTLSCacheTimeout SECONDS
     
    116120Context: server config
    117121
    118 Sets the timeout for SSL Session Cache entries expiration.  This
    119 directive is valid even if Session Tickets are used, and indicates the
    120 expiration time of the ticket in seconds.
    121 
    122 `GnuTLSSessionTickets`
    123 ----------------------
     122Sets the timeout for TLS Session Cache entries expiration. This value
     123is also used for OCSP responses if they do not contain a `nextUpdate`
     124time.
     125
     126### GnuTLSSessionTickets
    124127
    125128Enable Session Tickets for the server
     
    130133Context: server config, virtual host
    131134
    132 To avoid storing data for TLS session resumption it is allowed to
    133 provide client with a ticket, to use on return.  Use for servers with
    134 limited storage, and don't combine with GnuTLSCache. For a pool of
    135 servers this option is not recommended since the tickets are unique
    136 for the issuing server only.
    137 
    138 
    139 `GnuTLSCertificateFile`
    140 -----------------------
    141 
    142 Set to the PEM Encoded Server Certificate
    143 
    144     GnuTLSCertificateFile FILEPATH
    145 
    146 Default: *none*\
    147 Context: server config, virtual host
    148 
    149 Takes an absolute or relative path to a PEM-encoded X.509 certificate to
    150 use as this Server's End Entity (EE) certificate. If you need to supply
    151 certificates for intermediate Certificate Authorities (iCAs), they
    152 should be listed in sequence in the file, from EE to the iCA closest to
    153 the root CA. Optionally, you can also include the root CA's certificate
    154 as the last certificate in the list.
    155 
    156 Since version 0.7 this can be a PKCS #11 URL.
    157 
    158 `GnuTLSKeyFile`
    159 ---------------
    160 
    161 Set to the PEM Encoded Server Private Key
    162 
    163     GnuTLSKeyFile FILEPATH
    164 
    165 Default: *none*\
    166 Context: server config, virtual host
    167 
    168 Takes an absolute or relative path to the Server Private Key. Set
    169 `GnuTLSPIN` if the key file is encrypted.
    170 
    171 Since version 0.7 this can be a PKCS #11 URL.
    172 
    173 **Security Warning:**\
    174 This private key must be protected. It is read while Apache is still
    175 running as root, and does not need to be readable by the nobody or
    176 apache user.
    177 
    178 `GnuTLSPGPCertificateFile`
    179 --------------------------
    180 
    181 Set to a base64 Encoded Server OpenPGP Certificate
    182 
    183     GnuTLSPGPCertificateFile FILEPATH
    184 
    185 Default: *none*\
    186 Context: server config, virtual host
    187 
    188 Takes an absolute or relative path to a base64 Encoded OpenPGP
    189 Certificate to use as this Server's Certificate.
    190 
    191 `GnuTLSPGPKeyFile`
    192 ------------------
    193 
    194 Set to the Server OpenPGP Secret Key
    195 
    196     GnuTLSPGPKeyFile FILEPATH
    197 
    198 Default: *none*\
    199 Context: server config, virtual host
    200 
    201 Takes an absolute or relative path to the Server Private Key. This key
    202 cannot currently be password protected.
    203 
    204 **Security Warning:**\
    205  This private key must be protected. It is read while Apache is still
    206 running as root, and does not need to be readable by the nobody or
    207 apache user.
    208 
    209 `GnuTLSClientVerify`
    210 --------------------
    211 
    212 Enable Client Certificate Verification\
     135To avoid storing data for TLS session resumption the server can
     136provide clients with tickets, to use on return. Tickets are an
     137alternative to using a session cache, mostly used for busy servers
     138with limited storage. For a pool of servers this option is not
     139recommended since the tickets are bound to the issuing server only.
     140
     141If this option is set in the global configuration, virtual hosts
     142without a `GnuTLSSessionTickets` setting will use the global setting.
     143
     144*Warning:* Currently the master key that protects the tickets is
     145generated only on server start, and there is no mechanism to roll over
     146the key. If session tickets are enabled it is highly recommened to
     147restart the server regularly to protect past sessions in case an
     148attacker gains access to server memory.
     149
     150### GnuTLSClientVerify
     151
     152Enable Client Certificate Verification
    213153
    214154    GnuTLSClientVerify [ignore|request|require]
     
    217157Context: server config, virtual host, directory, .htaccess
    218158
    219 This directive controls the use of SSL Client Certificate
     159This directive controls the use of TLS Client Certificate
    220160Authentication. If used in the .htaccess context, it can force TLS
    221161re-negotiation.
    222162
    223163`ignore`
    224 :   `mod_gnutls` will ignore the contents of any SSL Client Certificates
     164:   `mod_gnutls` will ignore the contents of any TLS Client Certificates
    225165    sent. It will not request that the client sends a certificate.
    226166
     
    236176    environment variable will only be set to `SUCCESS`.
    237177
    238 `GnuTLSClientCAFile`
    239 --------------------
    240 
    241 Set to the PEM Encoded Certificate Authority Certificate
    242 
    243     GnuTLSClientCAFile FILEPATH
    244 
    245 Default: *none*
    246 Context: server config, virtual host
    247 
    248 Takes an absolute or relative path to a PEM Encoded Certificate to use
    249 as a Certificate Authority with Client Certificate Authentication.
    250 This file may contain a list of trusted authorities.
    251 
    252 `GnuTLSPGPKeyringFile`
    253 ----------------------
    254 
    255 Set to a base64 Encoded key ring
    256 
    257     GnuTLSPGPKeyringFile FILEPATH
    258 
    259 Default: *none*\
    260 Context: server config, virtual host
    261 
    262 Takes an absolute or relative path to a base64 Encoded Certificate
    263 list (key ring) to use as a means of verification of Client
    264 Certificates.  This file should contain a list of trusted signers.
    265 
    266 `GnuTLSDHFile`
    267 --------------
     178### GnuTLSDHFile
    268179
    269180Set to the PKCS \#3 encoded Diffie Hellman parameters
     
    2791902048`.  If not set `mod_gnutls` will use the included parameters.
    280191
    281 `GnuTLSSRPPasswdFile`
    282 ---------------------
    283 
    284 Set to the SRP password file for SRP ciphersuites
    285 
    286     GnuTLSSRPPasswdFile FILEPATH
    287 
    288 Default: *none*\
    289 Context: server config, virtual host
    290 
    291 Takes an absolute or relative path to an SRP password file. This is
    292 the same format as used in libsrp.  You can generate such file using
    293 the command `srptool --passwd /etc/tpasswd --passwd-conf
    294 /etc/tpasswd.conf -u test` to set a password for user test.  This
    295 password file holds the username, a password verifier and the
    296 dependency to the SRP parameters.
    297 
    298 `GnuTLSSRPPasswdConfFile`
    299 -------------------------
    300 
    301 Set to the SRP password.conf file for SRP ciphersuites
    302 
    303     GnuTLSSRPPasswdConfFile FILEPATH
    304 
    305 Default: *none*\
    306 Context: server config, virtual host
    307 
    308 Takes an absolute or relative path to an SRP password.conf file. This
    309 is the same format as used in `libsrp`.  You can generate such file
    310 using the command `srptool --create-conf /etc/tpasswd.conf`.  This
    311 file holds the SRP parameters and is associate with the password file
    312 (the verifiers depends on these parameters).
    313 
    314 `GnuTLSPriorities`
    315 ------------------
    316 
    317 Set the allowed ciphers, key exchange algorithms, MACs and compression
    318 methods
     192### GnuTLSPriorities
     193
     194Set the allowed protocol versions, ciphers, key exchange algorithms,
     195MACs and compression methods
    319196
    320197    GnuTLSPriorities NORMAL:+CIPHER_0:+CIPHER_1:...:+CIPHER_N
     
    323200Context: server config, virtual host
    324201
    325 Takes a semi-colon separated list of ciphers, key exchange methods
    326 Message authentication codes and compression methods to enable.
    327 The allowed keywords are specified in the `gnutls_priority_init()`
    328 function of GnuTLS.
    329 
    330 Full details can be found at [the GnuTLS documentation](http://gnutls.org/manual/html_node/Priority-Strings.html#Priority-Strings).
    331 In brief you can specify a set of ciphersuites from the choices:
    332 
    333 `NONE`
    334 :   The empty list.
    335 
    336 `EXPORT`
    337 :   A list with all the supported cipher combinations
    338     including the `EXPORT` strength algorithms.
     202Takes a colon separated list of protocol version, ciphers, key
     203exchange methods message authentication codes, and compression methods
     204to enable. The allowed keywords are specified in the
     205`gnutls_priority_init()` function of GnuTLS.
     206
     207Please refer to [the GnuTLS documentation](https://gnutls.org/manual/html_node/Priority-Strings.html#Priority-Strings)
     208for details. A few commonly used sets are listed below, note that
     209their exact meaning may change with GnuTLS versions.
    339210
    340211`PERFORMANCE`
    341 :   A list with all the secure cipher combinations sorted in terms of performance.
     212:   A list with all the secure cipher combinations sorted in terms of
     213    performance.
    342214
    343215`NORMAL`
     
    345217    with respect to security margin (subjective term).
    346218
    347 `SECURE`
    348 :   A list with all the secure cipher combinations including
    349     the 256-bit ciphers sorted with respect to security margin.
    350 
    351 Additionally you can add or remove algorithms using the `+` and `!`
    352 prefixes respectively.
    353 
    354 For example, in order to disable the `ARCFOUR` cipher from the `NORMAL` set
    355 you can use the string `NORMAL:!ARCFOUR-128`
    356 
    357 Other options such as the protocol version and the compression method
    358 can be specified using the `VERS-` and `COMP-` prefixes.
    359 
    360 So in order to remove or add a specific TLS version from the `NORMAL`
    361 set, use `NORMAL:!VERS-SSL3.0`.  And to enable zlib compression use
    362 `NORMAL:+COMP-DEFLATE`.
    363 
    364 
    365 However it is recommended not to add compression at this level.  With
    366 the `NONE` set, in order to be usable, you have to specify a complete
    367 set of combinations of protocol versions, cipher algorithms
    368 (`AES-128-CBC`), key exchange algorithms (`RSA`), message
    369 authentication codes (`SHA1`) and compression methods (`COMP-NULL`).
     219`SECURE128`
     220:   A list with all the secure cipher suites that offer a security level
     221    of 128-bit or more.
     222
     223`PFS`
     224:   Only cipher suites offering perfect forward secrecy (ECDHE and DHE),
     225    sorted by security margin.
     226
     227You can add or remove algorithms using the `+` and `!` prefixes
     228respectively. For example, in order to use the `NORMAL` set but
     229disable TLS 1.0 and 1.1 you can use the string
     230`NORMAL:!VERS-TLS1.0:!VERS-TLS1.1`.
    370231
    371232You can find a list of all supported Ciphers, Versions, MACs, etc.  by
    372233running `gnutls-cli --list`.
    373234
    374 The special keyword `%COMPAT` will disable some security features such
    375 as protection against statistical attacks to ciphertext data in order to
    376 achieve maximum compatibility (some broken mobile clients need this).
    377 
    378 `GnuTLSP11Module`
    379 ------------------
     235### GnuTLSP11Module
    380236
    381237Load this PKCS #11 module.
     
    389245defaults. May occur multiple times to load multiple modules.
    390246
    391 `GnuTLSPIN`
    392 ------------------
     247### GnuTLSPIN
    393248
    394249Set the PIN to be used to access encrypted key files or PKCS #11 objects.
     
    403258or openssl encrypted keys.
    404259
    405 `GnuTLSSRKPIN`
    406 ------------------
    407 
    408 Set the SRK PIN to be used to unlaccess the TPM.
     260### GnuTLSSRKPIN
     261
     262Set the SRK PIN to be used to access the TPM.
    409263
    410264    GnuTLSSRKPIN XXXXXX
     
    416270the TPM module.
    417271
    418 `GnuTLSExportCertificates`
    419 --------------------------
     272### GnuTLSExportCertificates
    420273
    421274Export the PEM encoded certificates to CGIs
     
    444297environment variables to the CGI process as `mod_ssl`.
    445298
    446 
    447 `GnuTLSProxyEngine`
    448 --------------
     299X.509 Certificate Authentication
     300--------------------------------
     301
     302### GnuTLSCertificateFile
     303
     304Set to the PEM Encoded Server Certificate
     305
     306    GnuTLSCertificateFile FILEPATH
     307
     308Default: *none*\
     309Context: server config, virtual host
     310
     311Takes an absolute or relative path to a PEM-encoded X.509 certificate to
     312use as this Server's End Entity (EE) certificate. If you need to supply
     313certificates for intermediate Certificate Authorities (iCAs), they
     314should be listed in sequence in the file, from EE to the iCA closest to
     315the root CA. Optionally, you can also include the root CA's certificate
     316as the last certificate in the list.
     317
     318Since version 0.7 this can be a PKCS #11 URL.
     319
     320### GnuTLSKeyFile
     321
     322Set to the PEM Encoded Server Private Key
     323
     324    GnuTLSKeyFile FILEPATH
     325
     326Default: *none*\
     327Context: server config, virtual host
     328
     329Takes an absolute or relative path to the Server Private Key. Set
     330`GnuTLSPIN` if the key file is encrypted.
     331
     332Since version 0.7 this can be a PKCS #11 URL.
     333
     334**Security Warning:**\
     335This private key must be protected. It is read while Apache is still
     336running as root, and does not need to be readable by the nobody or
     337apache user.
     338
     339### GnuTLSClientCAFile
     340
     341Set the PEM encoded Certificate Authority list to use for X.509 base
     342client authentication
     343
     344    GnuTLSClientCAFile FILEPATH
     345
     346Default: *none*
     347Context: server config, virtual host
     348
     349Takes an absolute or relative path to a PEM Encoded Certificate to use
     350as a Certificate Authority with Client Certificate Authentication.
     351This file may contain a list of trusted authorities.
     352
     353OpenPGP Certificate Authentication
     354----------------------------------
     355
     356### GnuTLSPGPCertificateFile
     357
     358Set to a base64 Encoded Server OpenPGP Certificate
     359
     360    GnuTLSPGPCertificateFile FILEPATH
     361
     362Default: *none*\
     363Context: server config, virtual host
     364
     365Takes an absolute or relative path to a base64 Encoded OpenPGP
     366Certificate to use as this Server's Certificate.
     367
     368### GnuTLSPGPKeyFile
     369
     370Set to the Server OpenPGP Secret Key
     371
     372    GnuTLSPGPKeyFile FILEPATH
     373
     374Default: *none*\
     375Context: server config, virtual host
     376
     377Takes an absolute or relative path to the Server Private Key. This key
     378cannot currently be password protected.
     379
     380**Security Warning:**\
     381 This private key must be protected. It is read while Apache is still
     382running as root, and does not need to be readable by the nobody or
     383apache user.
     384
     385### GnuTLSPGPKeyringFile
     386
     387Set to a base64 Encoded key ring
     388
     389    GnuTLSPGPKeyringFile FILEPATH
     390
     391Default: *none*\
     392Context: server config, virtual host
     393
     394Takes an absolute or relative path to a base64 Encoded Certificate
     395list (key ring) to use as a means of verification of Client
     396Certificates.  This file should contain a list of trusted signers.
     397
     398SRP Authentication
     399------------------
     400
     401### GnuTLSSRPPasswdFile
     402
     403Set to the SRP password file for SRP ciphersuites
     404
     405    GnuTLSSRPPasswdFile FILEPATH
     406
     407Default: *none*\
     408Context: server config, virtual host
     409
     410Takes an absolute or relative path to an SRP password file. This is
     411the same format as used in libsrp.  You can generate such file using
     412the command `srptool --passwd /etc/tpasswd --passwd-conf
     413/etc/tpasswd.conf -u test` to set a password for user test.  This
     414password file holds the username, a password verifier and the
     415dependency to the SRP parameters.
     416
     417### GnuTLSSRPPasswdConfFile
     418
     419Set to the SRP password.conf file for SRP ciphersuites
     420
     421    GnuTLSSRPPasswdConfFile FILEPATH
     422
     423Default: *none*\
     424Context: server config, virtual host
     425
     426Takes an absolute or relative path to an SRP password.conf file. This
     427is the same format as used in `libsrp`.  You can generate such file
     428using the command `srptool --create-conf /etc/tpasswd.conf`.  This
     429file holds the SRP parameters and is associate with the password file
     430(the verifiers depends on these parameters).
     431
     432TLS Proxy Configuration
     433-----------------------
     434
     435### GnuTLSProxyEngine
    449436
    450437Enable TLS proxy connections for this virtual host
     
    458445host.
    459446
    460 `GnuTLSProxyCAFile`
    461 --------------------
     447### GnuTLSProxyCAFile
    462448
    463449Set to the PEM encoded Certificate Authority Certificate
     
    474460always fail due to lack of a trusted CA.
    475461
    476 `GnuTLSProxyCRLFile`
    477 --------------------
     462### GnuTLSProxyCRLFile
    478463
    479464Set to the PEM encoded Certificate Revocation List
     
    488473back end servers. The file may contain a list of CRLs.
    489474
    490 `GnuTLSProxyCertificateFile`
    491 -----------------------
     475### GnuTLSProxyCertificateFile
    492476
    493477Set to the PEM encoded Client Certificate
     
    510494provide the matching private key.
    511495
    512 `GnuTLSProxyKeyFile`
    513 ---------------
     496### GnuTLSProxyKeyFile
    514497
    515498Set to the PEM encoded Private Key
     
    529512apache user.
    530513
    531 `GnuTLSProxyPriorities`
    532 ------------------
     514### GnuTLSProxyPriorities
    533515
    534516Set the allowed ciphers, key exchange algorithms, MACs and compression
     
    545527`GnuTLSProxyEngine` is `On`.
    546528
     529OCSP Stapling Configuration
     530---------------------------
     531
     532### GnuTLSOCSPStapling
     533
     534Enable OCSP stapling for this (virtual) host.
     535
     536    GnuTLSOCSPStapling [On|Off]
     537
     538Default: *off*\
     539Context: server config, virtual host
     540
     541OCSP stapling, formally known as the TLS Certificate Status Request
     542extension, allows the server to provide the client with an OCSP
     543response for its certificate during the handshake. This way the client
     544does not have to send an OCSP request to the CA to check the
     545certificate status, which offers privacy and performance advantages.
     546
     547Using OCSP stapling has a few requirements:
     548
     549* Caching OCSP responses requires a cache, so `GnuTLSCache` must not
     550  be `none`.
     551* `GnuTLSCertificateFile` must contain the issuer CA certificate in
     552  addition to the server certificate so responses can be verified.
     553* The certificate must either contain an OCSP access URI using HTTP,
     554  or `GnuTLSOCSPResponseFile` must be set.
     555
     556OCSP cache updates are serialized using the `gnutls-ocsp` mutex.
     557
     558### GnuTLSOCSPCheckNonce
     559
     560Check the nonce in OCSP responses?
     561
     562    GnuTLSOCSPCheckNonce [On|Off]
     563
     564Default: *on*\
     565Context: server config, virtual host
     566
     567Some CAs refuse to send nonces in their OCSP responses, probably
     568because that way they can cache responses. If your CA is one of them
     569you can use this flag to disable nonce verification. Note that
     570`mod_gnutls` will _send_ a nonce either way.
     571
     572### GnuTLSOCSPResponseFile
     573
     574Read the OCSP response for stapling from this file instead of sending
     575a request over HTTP.
     576
     577    GnuTLSOCSPResponseFile /path/to/response.der
     578
     579Default: *empty*\
     580Context: server config, virtual host
     581
     582The response file must be updated externally, for example using a cron
     583job. This option is an alternative to the server fetching OCSP
     584responses over HTTP. Reasons to use this option include:
     585
     586* Performing OCSP requests separate from the web server, to prevent slow
     587  responses from stalling handshakes.
     588* The issuer CA uses an access method other than HTTP.
     589* Testing
     590
     591You can use a GnuTLS `ocsptool` command like the following to create
     592and update the response file:
     593
     594    ocsptool --ask --nonce --load-issuer ca_cert.pem \
     595        --load-cert server_cert.pem --outfile ocsp_response.der
     596
     597Additional error checking is highly recommended. You may have to
     598remove the `--nonce` option if the OCSP responder of your CA does not
     599support nonces.
     600
     601### GnuTLSOCSPCacheTimeout
     602
     603Cache timeout for OCSP responses
     604
     605    GnuTLSOCSPCacheTimeout SECONDS
     606
     607Default: *3600*\
     608Context: server config, virtual host
     609
     610Cached OCSP responses will be refreshed after the configured number of
     611seconds. How long this timeout should reasonably be depends on your
     612CA, namely how often its OCSP responder is updated and how long
     613responses are valid. Note that a response will not be cached beyond
     614its lifetime as denoted in the `nextUpdate` field of the response.
     615
     616### GnuTLSOCSPFailureTimeout
     617
     618Wait this many seconds before retrying a failed OCSP request.
     619
     620    GnuTLSOCSPFailureTimeout SECONDS
     621
     622Default: *300*\
     623Context: server config, virtual host
     624
     625Retries of failed OCSP requests must be rate limited to avoid
     626overloading both the server using mod_gnutls and the CA's OCSP
     627responder. A shorter value increases the load on both sides, a longer
     628one means that stapling will remain disabled for longer after a failed
     629request.
     630
     631### GnuTLSOCSPSocketTimeout
     632
     633Timeout for TCP sockets used to send OCSP requests
     634
     635    GnuTLSOCSPFailureTimeout SECONDS
     636
     637Default: *6*\
     638Context: server config, virtual host
     639
     640Stalled OCSP requests must time out after a while to prevent stalling
     641the server too much. However, if the timeout is too short requests may
     642fail with a slow OCSP responder or high latency network
     643connection. This parameter allows you to adjust the timeout if
     644necessary.
     645
     646Note that this is not an upper limit for the completion of an OCSP
     647request but a socket timeout. The connection will time out if there is
     648no activity (successful send or receive) at all for the configured
     649time.
     650
    547651* * * * *
    548652
     
    550654======================
    551655
    552 Simple Standard SSL Example
     656Simple Standard TLS Example
    553657---------------------------
    554658
    555 The following is an example of standard SSL Hosting, using one IP
    556 Addresses for each virtual host
     659The following is an example of simple TLS hosting, using one IP
     660Addresses for each virtual host.
    557661
    558662     # Load the module into Apache.
     
    560664     GnuTLSCache gdbm /var/cache/www-tls-cache
    561665     GnuTLSCacheTimeout 500
    562      # With normal SSL Websites, you need one IP Address per-site.
    563      Listen 1.2.3.1:443
    564      Listen 1.2.3.2:443
    565      Listen 1.2.3.3:443
    566      Listen 1.2.3.4:443
    567      <VirtualHost 1.2.3.1:443>
    568      GnuTLSEnable on
    569      GnuTLSPriorities NONE:+AES-128-CBC:+3DES-CBC:+ARCFOUR-128:+RSA:+DHE-RSA:+DHE-DSS:+SHA1:+MD5:+COMP-NULL
    570      DocumentRoot /www/site1.example.com/html
    571      ServerName site1.example.com:443
    572      GnuTLSCertificateFile conf/ssl/site1.crt
    573      GnuTLSKeyFile conf/ss/site1.key
     666
     667     # Without SNI you need one IP Address per-site.
     668     Listen 192.0.2.1:443
     669     Listen 192.0.2.2:443
     670     Listen 192.0.2.3:443
     671     Listen 192.0.2.4:443
     672
     673     <VirtualHost 192.0.2.1:443>
     674         GnuTLSEnable on
     675         GnuTLSPriorities SECURE128
     676         DocumentRoot /www/site1.example.com/html
     677         ServerName site1.example.com:443
     678         GnuTLSCertificateFile conf/tls/site1.crt
     679         GnuTLSKeyFile conf/tls/site1.key
    574680     </VirtualHost>
    575      <VirtualHost 1.2.3.2:443>
    576      # This virtual host enables SRP authentication
    577      GnuTLSEnable on
    578      GnuTLSPriorities NORMAL:+SRP
    579      DocumentRoot /www/site2.example.com/html
    580      ServerName site2.example.com:443
    581      GnuTLSSRPPasswdFile conf/ssl/tpasswd.site2
    582      GnuTLSSRPPasswdConfFile conf/ssl/tpasswd.site2.conf
     681
     682     <VirtualHost 192.0.2.2:443>
     683         # This virtual host enables SRP authentication
     684         GnuTLSEnable on
     685         GnuTLSPriorities NORMAL:+SRP
     686         DocumentRoot /www/site2.example.com/html
     687         ServerName site2.example.com:443
     688         GnuTLSSRPPasswdFile conf/tls/tpasswd.site2
     689         GnuTLSSRPPasswdConfFile conf/tls/tpasswd.site2.conf
    583690     </VirtualHost>
    584      <VirtualHost 1.2.3.3:443>
    585      # This server enables SRP, OpenPGP and X.509 authentication.
    586      GnuTLSEnable on
    587      GnuTLSPriorities NORMAL:+SRP:+SRP-RSA:+SRP-DSS
    588      DocumentRoot /www/site3.example.com/html
    589      ServerName site3.example.com:443
    590      GnuTLSCertificateFile conf/ssl/site3.crt
    591      GnuTLSKeyFile conf/ss/site3.key
    592      GnuTLSClientVerify ignore
    593      GnuTLSPGPCertificateFile conf/ss/site3.pub.asc
    594      GnuTLSPGPKeyFile conf/ss/site3.sec.asc
    595      GnuTLSSRPPasswdFile conf/ssl/tpasswd.site3
    596      GnuTLSSRPPasswdConfFile conf/ssl/tpasswd.site3.conf
     691
     692     <VirtualHost 192.0.2.3:443>
     693         # This server enables SRP, OpenPGP and X.509 authentication.
     694         GnuTLSEnable on
     695         GnuTLSPriorities NORMAL:+SRP:+SRP-RSA:+SRP-DSS:+CTYPE-OPENPGP
     696         DocumentRoot /www/site3.example.com/html
     697         ServerName site3.example.com:443
     698         GnuTLSCertificateFile conf/tls/site3.crt
     699         GnuTLSKeyFile conf/tls/site3.key
     700         GnuTLSClientVerify ignore
     701         GnuTLSPGPCertificateFile conf/tls/site3.pub.asc
     702         GnuTLSPGPKeyFile conf/tls/site3.sec.asc
     703         GnuTLSSRPPasswdFile conf/tls/tpasswd.site3
     704         GnuTLSSRPPasswdConfFile conf/tls/tpasswd.site3.conf
    597705     </VirtualHost>
    598      <VirtualHost 1.2.3.4:443>
    599      GnuTLSEnable on
    600      # %COMPAT disables some security features to enable maximum compatibility with clients.
    601      GnuTLSPriorities NONE:+AES-128-CBC:+ARCFOUR-128:+RSA:+SHA1:+MD5:+COMP-NULL:%COMPAT
    602      DocumentRoot /www/site4.example.com/html
    603      ServerName site4.example.com:443
    604      GnuTLSCertificateFile conf/ssl/site4.crt
    605      GnuTLSKeyFile conf/ss/site4.key
     706
     707     <VirtualHost 192.0.2.4:443>
     708         GnuTLSEnable on
     709         # %COMPAT disables some security features to enable maximum
     710         # compatibility with clients. Don't use this if you need strong
     711         # security.
     712         GnuTLSPriorities NORMAL:%COMPAT
     713         DocumentRoot /www/site4.example.com/html
     714         ServerName site4.example.com:443
     715         GnuTLSCertificateFile conf/tls/site4.crt
     716         GnuTLSKeyFile conf/tls/site4.key
    606717     </VirtualHost>
    607718
     
    609720------------------------------
    610721
    611 `mod_gnutls` can also use "Server Name Indication", as specified in
    612 RFC 3546.  This allows hosting many SSL Websites, with a Single IP
    613 Address.  Currently all the recent browsers support this
    614 standard. Here is an example, using SNI: ` `
    615 
     722`mod_gnutls` supports "Server Name Indication", as specified in
     723RFC 3546. This allows hosting many TLS websites with a single IP
     724address. All recent browsers support this standard. Here is an
     725example using SNI:
    616726
    617727     # Load the module into Apache.
    618728     LoadModule gnutls_module modules/mod_gnutls.so
    619      # With normal SSL Websites, you need one IP Address per-site.
    620      Listen 1.2.3.1:443
    621      # This could also be 'Listen *:443',
    622      # just like '*:80' is common for non-https
    623      # No caching. Enable session tickets. Timeout is still used for
    624      # ticket expiration.
    625      GnuTLSCacheTimeout 600
    626      # This tells apache, that for this IP/Port combination, we want to use
    627      # Name Based Virtual Hosting. In the case of Server Name Indication,
    628      # it lets mod_gnutls pick the correct Server Certificate.
    629      NameVirtualHost 1.2.3.1:443
    630      <VirtualHost 1.2.3.1:443>
    631      GnuTLSEnable on
    632      GnuTLSSessionTickets on
    633      GnuTLSPriorities NORMAL
    634      DocumentRoot /www/site1.example.com/html
    635      ServerName site1.example.com:443
    636      GnuTLSCertificateFile conf/ssl/site1.crt
    637      GnuTLSKeyFile conf/ss/site1.key
     729
     730     # SNI allows hosting multiple sites using one IP address. This
     731     # could also be 'Listen *:443', just like '*:80' is common for
     732     # non-HTTPS
     733     Listen 198.51.100.1:443
     734
     735     <VirtualHost _default_:443>
     736         GnuTLSEnable on
     737         GnuTLSSessionTickets on
     738         GnuTLSPriorities NORMAL
     739         DocumentRoot /www/site1.example.com/html
     740         ServerName site1.example.com:443
     741         GnuTLSCertificateFile conf/tls/site1.crt
     742         GnuTLSKeyFile conf/tls/site1.key
    638743     </VirtualHost>
    639      <VirtualHost 1.2.3.1:443>
    640      GnuTLSEnable on
    641      GnuTLSPriorities NORMAL
    642      DocumentRoot /www/site2.example.com/html
    643      ServerName site2.example.com:443
    644      GnuTLSCertificateFile conf/ssl/site2.crt
    645      GnuTLSKeyFile conf/ss/site2.key
     744
     745     <VirtualHost _default_:443>
     746         GnuTLSEnable on
     747         GnuTLSPriorities NORMAL
     748         DocumentRoot /www/site2.example.com/html
     749         ServerName site2.example.com:443
     750         GnuTLSCertificateFile conf/tls/site2.crt
     751         GnuTLSKeyFile conf/tls/site2.key
    646752     </VirtualHost>
    647      <VirtualHost 1.2.3.1:443>
    648      GnuTLSEnable on
    649      GnuTLSPriorities NORMAL
    650      DocumentRoot /www/site3.example.com/html
    651      ServerName site3.example.com:443
    652      GnuTLSCertificateFile conf/ssl/site3.crt
    653      GnuTLSKeyFile conf/ss/site3.key
     753
     754     <VirtualHost _default_:443>
     755         GnuTLSEnable on
     756         GnuTLSPriorities NORMAL
     757         DocumentRoot /www/site3.example.com/html
     758         ServerName site3.example.com:443
     759         GnuTLSCertificateFile conf/tls/site3.crt
     760         GnuTLSKeyFile conf/tls/site3.key
    654761     </VirtualHost>
    655      <VirtualHost 1.2.3.1:443>
    656      GnuTLSEnable on
    657      GnuTLSPriorities NORMAL
    658      DocumentRoot /www/site4.example.com/html
    659      ServerName site4.example.com:443
    660      GnuTLSCertificateFile conf/ssl/site4.crt
    661      GnuTLSKeyFile conf/ss/site4.key
     762
     763     <VirtualHost _default_:443>
     764         GnuTLSEnable on
     765         GnuTLSPriorities NORMAL
     766         DocumentRoot /www/site4.example.com/html
     767         ServerName site4.example.com:443
     768         GnuTLSCertificateFile conf/tls/site4.crt
     769         GnuTLSKeyFile conf/tls/site4.key
    662770     </VirtualHost>
    663771
    664 
    665 * * * * *
    666 
    667 Performance Issues
    668 ==================
    669 
    670 `mod_gnutls` by default uses conservative settings for the server.
    671 You can fine tune the configuration to reduce the load on a busy
    672 server.  The following examples do exactly this:
    673 
     772OCSP Stapling Example
     773---------------------
     774
     775This example uses an X.509 server certificate. The server will fetch
     776OCSP responses from the responder listed in the certificate and store
     777them im a memcached cache shared with another server.
    674778
    675779     # Load the module into Apache.
    676780     LoadModule gnutls_module modules/mod_gnutls.so
    677      # Using 4 memcache servers to distribute the SSL Session Cache.
    678      GnuTLSCache memcache "mc1.example.com mc2.example.com mc3.example.com mc4.example.com"
     781     GnuTLSCache memcache "192.0.2.1:11211 192.0.2.2:11211"
    679782     GnuTLSCacheTimeout 600
    680      Listen 1.2.3.1:443
    681      NameVirtualHost 1.2.3.1:443
    682      <VirtualHost 1.2.3.1:443>
    683      GnuTLSEnable on
    684      # Here we disable the Perfect forward secrecy ciphersuites (DHE)
    685      # and disallow AES-256 since AES-128 is just fine.
    686      GnuTLSPriorities NORMAL:!DHE-RSA:!DHE-DSS:!AES-256-CBC:%COMPAT
    687      DocumentRoot /www/site1.example.com/html
    688      ServerName site1.example.com:443
    689      GnuTLSCertificateFile conf/ssl/site1.crt
    690      GnuTLSKeyFile conf/ss/site1.key
    691      </VirtualHost>
    692      <VirtualHost 1.2.3.1:443>
    693      GnuTLSEnable on
    694      # Here we instead of disabling the DHE ciphersuites we use
    695      # Diffie Hellman parameters of smaller size than the default (2048 bits).
    696      # Using small numbers from 768 to 1024 bits should be ok once they are
    697      # regenerated every few hours.
    698      # Use "certtool --generate-dh-params --bits 1024" to get those
    699      GnuTLSDHFile /etc/apache2/dh.params
    700      GnuTLSPriorities NORMAL:!AES-256-CBC:%COMPAT
    701      DocumentRoot /www/site2.example.com/html
    702      ServerName site2.example.com:443
    703      GnuTLSCertificateFile conf/ssl/site2.crt
    704      GnuTLSKeyFile conf/ss/site2.key
     783
     784     Listen 192.0.2.1:443
     785
     786     <VirtualHost _default_:443>
     787         GnuTLSEnable          On
     788         GnuTLSPriorities      NORMAL
     789         DocumentRoot          /www/site1.example.com/html
     790         ServerName            site1.example.com:443
     791         GnuTLSCertificateFile conf/tls/site1.crt
     792         GnuTLSKeyFile         conf/tls/site1.key
     793         GnuTLSPriorities      NORMAL
     794         GnuTLSOCSPStapling    On
    705795     </VirtualHost>
    706796
Note: See TracChangeset for help on using the changeset viewer.