Changeset 2b16350 in mod_gnutls


Ignore:
Timestamp:
Apr 15, 2013, 4:21:20 PM (6 years ago)
Author:
Daniel Kahn Gillmor <dkg@…>
Branches:
debian/master, debian/stretch-backports, jessie-backports, master, upstream
Children:
70e7652
Parents:
e7527b9
git-author:
Daniel Kahn Gillmor <dkg@…> (04/09/13 16:04:14)
git-committer:
Daniel Kahn Gillmor <dkg@…> (04/15/13 16:21:20)
Message:

clean up documentation, list GnuTLSEnable as the first option

Location:
docs
Files:
2 edited

Legend:

Unmodified
Added
Removed
  • docs/Makefile

    re7527b9 r2b16350  
    33
    44mod_gnutls_manual.%: mod_gnutls_manual.mdwn
    5         pandoc --toc -f markdown -o $@ $<
     5        pandoc --toc --standalone -f markdown -o $@ $<
    66
    77clean:
  • docs/mod_gnutls_manual.mdwn

    re7527b9 r2b16350  
    1010
    1111Compilation & Installation
    12 --------------------------
     12==========================
    1313
    1414`mod_gnutls` uses the `./configure && make && make install` mechanism
     
    3636
    3737Integration
    38 -----------
    39 
    40 To activate mod\_gnutls just add the following line to your httpd.conf
     38===========
     39
     40To activate `mod_gnutls` just add the following line to your httpd.conf
    4141and restart Apache:
    4242
    43 `LoadModule gnutls_module modules/mod_gnutls.so`
     43    LoadModule gnutls_module modules/mod_gnutls.so
    4444
    4545* * * * *
    4646
    47 Configuration Directives:
    48 -------------------------
    49 
    50 #### GnuTLSCache
    51 
    52 ##### Description:
    53 
    54 Configure SSL Session Cache\
    55 
    56 ##### Syntax:
    57 
    58        GnuTLSCache [*dbm*|*gdbm*|*memcache*|*none*] [path|server
    59 list|-]\
    60 
    61 ##### Default:
    62 
    63       GnuTLSCache none\
    64 
    65 ##### Context:
    66 
    67       server config\
    68 
    69 This directive configures the SSL Session Cache for mod\_gnutls.\
    70  This could be shared between machines of different architectures.
    71 
    72 **dbm (Requires Berkeley DBM)**\
    73  Uses the default Berkeley DB backend of APR DBM to cache SSL Sessions
    74 results.\
    75  The argument is a relative or absolute path to be used as the DBM Cache
    76 file.\
    77  This is compatible with most operating systems, but needs the Apache
    78 Runtime to be compiled with Berkeley DBM support.\
    79  **gdbm**\
    80  Uses the GDBM backend of APR DBM to cache SSL Sessions results.\
    81  The argument is a relative or absolute path to be used as the DBM Cache
    82 file.\
    83  This is the recommended option.\
    84  **memcache**\
    85  Uses a memcached server to cache the SSL Session.\
    86  The argument is a space separated list of servers. If no port number is
    87 supplied, the default of 11211 is used.\
    88  This can be used to share a session cache between all servers in a
    89 cluster.\
    90  **none**\
    91  Turns off all caching of SSL Sessions.\
    92  This can significantly reduce the performance of mod\_gnutls since even
    93 followup connections by a client must renegotiate parameters instead of
    94 reusing old ones.\
    95  This is the default, since it requires no configuration.\
    96 
    97 #### GnuTLSCacheTimeout
    98 
    99 ##### Description:
    100 
    101 Timeout for SSL Session Cache expiration\
    102 
    103 ##### Syntax:
    104 
    105        GnuTLSCacheTimeout *seconds*\
    106 
    107 ##### Default:
    108 
    109       GnuTLSCacheTimeout 300\
    110 
    111 ##### Context:
    112 
    113       server config\
    114 
    115 Sets the timeout for SSL Session Cache entries expiration.\
    116  This directive is valid even if Session Tickets are used, and indicates
    117 the expiration time of the ticket in seconds.
    118 
    119 #### GnuTLSSessionTickets
    120 
    121 ##### Description:
    122 
    123 Enable Session Tickets for the server\
    124 
    125 ##### Syntax:
    126 
    127        GnuTLSSessionTickets [ *on* | *off* ]\
    128 
    129 ##### Default:
    130 
    131       *off*\
    132 
    133 ##### Context:
    134 
    135       server config, virtual host\
     47Configuration Directives
     48========================
     49
     50`GnuTLSEnable`
     51--------------
     52
     53Enable GnuTLS for this virtual host
     54
     55    GnuTLSEnable [on|off]
     56
     57Default: *off*\
     58Context: virtual host
     59
     60This directive enables SSL/TLS Encryption for a Virtual Host.
     61
     62`GnuTLSCache`
     63-------------
     64
     65Configure SSL Session Cache
     66
     67    GnuTLSCache [dbm|gdbm|memcache|none] [PATH|SERVERLIST|-]
     68
     69Default: `GnuTLSCache none`\
     70Context: server config
     71
     72This directive configures the SSL Session Cache for `mod_gnutls`.
     73This could be shared between machines of different architectures.
     74
     75`dbm` (Requires Berkeley DBM)
     76:   Uses the default Berkeley DB backend of APR DBM to cache SSL
     77    Sessions results.  The argument is a relative or absolute path to
     78    be used as the DBM Cache file. This is compatible with most
     79    operating systems, but needs the Apache Runtime to be compiled
     80    with Berkeley DBM support.
     81
     82`gdbm`
     83:   Uses the GDBM backend of APR DBM to cache SSL Sessions results.
     84
     85    The argument is a relative or absolute path to be used as the DBM Cache
     86    file.  This is the recommended option.
     87
     88`memcache`
     89:   Uses a memcached server to cache the SSL Session.
     90
     91    The argument is a space separated list of servers. If no port
     92    number is supplied, the default of 11211 is used.  This can be
     93    used to share a session cache between all servers in a cluster.
     94
     95`none`
     96:   Turns off all caching of SSL Sessions.
     97
     98    This can significantly reduce the performance of `mod_gnutls` since
     99    even followup connections by a client must renegotiate parameters
     100    instead of reusing old ones.  This is the default, since it
     101    requires no configuration.
     102
     103`GnuTLSCacheTimeout`
     104--------------------
     105
     106Timeout for SSL Session Cache expiration
     107
     108    GnuTLSCacheTimeout SECONDS
     109
     110Default: `GnuTLSCacheTimeout 300`\
     111Context: server config
     112
     113Sets the timeout for SSL Session Cache entries expiration.  This
     114directive is valid even if Session Tickets are used, and indicates the
     115expiration time of the ticket in seconds.
     116
     117`GnuTLSSessionTickets`
     118----------------------
     119
     120Enable Session Tickets for the server
     121
     122    GnuTLSSessionTickets [on|off]
     123
     124Default: `off`\
     125Context: server config, virtual host
    136126
    137127To avoid storing data for TLS session resumption it is allowed to
    138 provide client with a ticket, to use on return.\
    139  Use for servers with limited storage, and don't combine with
    140 GnuTLSCache.\
    141  For a pool of servers this option is not recommended since the tickets
    142 are unique for the issuing server only.
    143 
    144 #### GnuTLSCertificateFile
    145 
    146 ##### Description:
    147 
    148 Set to the PEM Encoded Server Certificate\
    149 
    150 ##### Syntax:
    151 
    152        GnuTLSCertificateFile *file-path*\
    153 
    154 ##### Default:
    155 
    156       *none*\
    157 
    158 ##### Context:
    159 
    160       server config, virtual host\
     128provide client with a ticket, to use on return.  Use for servers with
     129limited storage, and don't combine with GnuTLSCache. For a pool of
     130servers this option is not recommended since the tickets are unique
     131for the issuing server only.
     132
     133
     134`GnuTLSCertificateFile`
     135-----------------------
     136
     137Set to the PEM Encoded Server Certificate
     138
     139    GnuTLSCertificateFile FILEPATH
     140
     141Default: *none*\
     142Context: server config, virtual host
    161143
    162144Takes an absolute or relative path to a PEM-encoded X.509 certificate to
     
    167149as the last certificate in the list.
    168150
    169 #### GnuTLSKeyFile
    170 
    171 ##### Description:
    172 
    173 Set to the PEM Encoded Server Certificate\
    174 
    175 ##### Syntax:
    176 
    177        GnuTLSCertificateFile *file-path*\
    178 
    179 ##### Default:
    180 
    181       *none*\
    182 
    183 ##### Context:
    184 
    185       server config, virtual host\
    186 
    187 Takes an absolute or relative path to the Server Private Key.\
    188  This key cannot currently be password protected.
     151`GnuTLSKeyFile`
     152---------------
     153
     154Set to the PEM Encoded Server Certificate
     155
     156    GnuTLSCertificateFile FILEPATH
     157
     158Default: *none*\
     159Context: server config, virtual host
     160
     161Takes an absolute or relative path to the Server Private Key.  This
     162key cannot currently be password protected.
    189163
    190164**Security Warning:**\
     
    193167apache user.
    194168
    195 #### GnuTLSPGPCertificateFile
    196 
    197 ##### Description:
    198 
    199 Set to a base64 Encoded Server OpenPGP Certificate\
    200 
    201 ##### Syntax:
    202 
    203        GnuTLSPGPCertificateFile *file-path*\
    204 
    205 ##### Default:
    206 
    207       *none*\
    208 
    209 ##### Context:
    210 
    211       server config, virtual host\
     169`GnuTLSPGPCertificateFile`
     170--------------------------
     171
     172Set to a base64 Encoded Server OpenPGP Certificate
     173
     174    GnuTLSPGPCertificateFile FILEPATH
     175
     176Default: *none*\
     177Context: server config, virtual host
    212178
    213179Takes an absolute or relative path to a base64 Encoded OpenPGP
    214180Certificate to use as this Server's Certificate.
    215181
    216 #### GnuTLSPGPKeyFile
    217 
    218 ##### Description:
    219 
    220 Set to the Server OpenPGP Secret Key\
    221 
    222 ##### Syntax:
    223 
    224        GnuTLSPGPKeyFile *file-path*\
    225 
    226 ##### Default:
    227 
    228       *none*\
    229 
    230 ##### Context:
    231 
    232       server config, virtual host\
     182`GnuTLSPGPKeyFile`
     183------------------
     184
     185Set to the Server OpenPGP Secret Key
     186
     187    GnuTLSPGPKeyFile FILEPATH
     188
     189Default: *none*\
     190Context: server config, virtual host
    233191
    234192Takes an absolute or relative path to the Server Private Key. This key
     
    240198apache user.
    241199
    242 #### GnuTLSClientVerify
    243 
    244 ##### Description:
     200`GnuTLSClientVerify`
     201--------------------
    245202
    246203Enable Client Certificate Verification\
    247204
    248 ##### Syntax:
    249 
    250        GnuTLSClientVerify [ *ignore* | *request* | *require* ]\
    251 
    252 ##### Default:
    253 
    254       *ignore*\
    255 
    256 ##### Context:
    257 
    258       server config, virtual host, directory, .htaccess\
     205    GnuTLSClientVerify [ignore|request|require]
     206
     207Default: `ignore`\
     208Context: server config, virtual host, directory, .htaccess
    259209
    260210This directive controls the use of SSL Client Certificate
    261 Authentication.\
    262  If used in the .htaccess context, it can force TLS re-negotiation.
    263 
    264 **ignore**\
    265  mod\_gnutls will ignore the contents of any SSL Client Certificates
    266 sent.\
    267  It will not request that the client sends a certificate.\
    268  **request**\
    269  The client certificate will be requested, but not required.\
    270  The Certificate will be validated if sent.\
    271  The output of the validation status will be stored in the
    272 SSL\_CLIENT\_VERIFY environment variable and can be "SUCCESS", "FAILED"
    273 or "NONE".\
    274  **require**\
    275  A Client certificate will be required. Any requests without a valid
    276 client certificate will be denied.\
    277  The SSL\_CLIENT\_VERIFY environment variable will only be set to
    278 "SUCCESS".
    279 
    280 #### GnuTLSClientCAFile
    281 
    282 ##### Description:
    283 
    284 Set to the PEM Encoded Certificate Authority Certificate\
    285 
    286 ##### Syntax:
    287 
    288        GnuTLSClientCAFile *file-path*\
    289 
    290 ##### Default:
    291 
    292       *none*\
    293 
    294 ##### Context:
    295 
    296       server config, virtual host\
     211Authentication. If used in the .htaccess context, it can force TLS
     212re-negotiation.
     213
     214`ignore`
     215:   `mod_gnutls` will ignore the contents of any SSL Client Certificates
     216    sent. It will not request that the client sends a certificate.
     217
     218`request`
     219:   The client certificate will be requested, but not required.
     220    The Certificate will be validated if sent.  The output of the
     221    validation status will be stored in the `SSL_CLIENT_VERIFY`
     222    environment variable and can be `SUCCESS`, `FAILED` or `NONE`.
     223
     224`require`
     225:   A Client certificate will be required. Any requests without a valid
     226    client certificate will be denied.  The `SSL_CLIENT_VERIFY`
     227    environment variable will only be set to `SUCCESS`.
     228
     229`GnuTLSClientCAFile`
     230--------------------
     231
     232Set to the PEM Encoded Certificate Authority Certificate
     233
     234    GnuTLSClientCAFile FILEPATH
     235
     236Default: *none*
     237Context: server config, virtual host
    297238
    298239Takes an absolute or relative path to a PEM Encoded Certificate to use
    299 as a Certificate Authority with Client Certificate Authentication.\
    300  This file may contain a list of trusted authorities.\
    301 
    302 #### GnuTLSPGPKeyringFile
    303 
    304 ##### Description:
    305 
    306 Set to a base64 Encoded key ring\
    307 
    308 ##### Syntax:
    309 
    310        GnuTLSPGPKeyringFile *file-path*\
    311 
    312 ##### Default:
    313 
    314       *none*\
    315 
    316 ##### Context:
    317 
    318       server config, virtual host\
    319 
    320 Takes an absolute or relative path to a base64 Encoded Certificate list
    321 (key ring) to use as a means of verification of Client Certificates.\
    322  This file should contain a list of trusted signers.
    323 
    324 #### GnuTLSEnable
    325 
    326 ##### Description:
    327 
    328 Enable GnuTLS for this virtual host\
    329 
    330 ##### Syntax:
    331 
    332        GnuTLSEnable [ *on* | *off* ] \
    333 
    334 ##### Default:
    335 
    336       *off*\
    337 
    338 ##### Context:
    339 
    340       virtual host\
    341 
    342 This directive enables SSL/TLS Encryption for a Virtual Host.
    343 
    344 #### GnuTLSDHFile
    345 
    346 ##### Description:
    347 
    348 Set to the PKCS \#3 encoded Diffie Hellman parameters\
    349 
    350 ##### Syntax:
    351 
    352        GnuTLSDHFile *file-path* \
    353 
    354 ##### Default:
    355 
    356       *none*\
    357 
    358 ##### Context:
    359 
    360       server config, virtual host\
    361 
    362 Takes an absolute or relative path to a PKCS \#3 encoded DH parameters.\
    363  Those are used when the DHE key exchange method is enabled.\
    364  You can generate this file using "certtool --generate-dh-params --bits
    365 2048".\
    366  If not set mod\_gnutls will use the included parameters.
    367 
    368 #### GnuTLSSRPPasswdFile
    369 
    370 ##### Description:
    371 
    372 Set to the SRP password file for SRP ciphersuites\
    373 
    374 ##### Syntax:
    375 
    376        GnuTLSSRPPasswdFile *file-path* \
    377 
    378 ##### Default:
    379 
    380       *none*\
    381 
    382 ##### Context:
    383 
    384       server config, virtual host\
    385 
    386 Takes an absolute or relative path to an SRP password file. This is the
    387 same format as used in libsrp.\
    388  You can generate such file using the command "srptool --passwd
    389 /etc/tpasswd --passwd-conf /etc/tpasswd.conf -u test" to set a password
    390 for user test.\
    391  This password file holds the username, a password verifier and the
     240as a Certificate Authority with Client Certificate Authentication.
     241This file may contain a list of trusted authorities.
     242
     243`GnuTLSPGPKeyringFile`
     244----------------------
     245
     246Set to a base64 Encoded key ring
     247
     248    GnuTLSPGPKeyringFile FILEPATH
     249
     250Default: *none*\
     251Context: server config, virtual host
     252
     253Takes an absolute or relative path to a base64 Encoded Certificate
     254list (key ring) to use as a means of verification of Client
     255Certificates.  This file should contain a list of trusted signers.
     256
     257`GnuTLSDHFile`
     258--------------
     259
     260Set to the PKCS \#3 encoded Diffie Hellman parameters
     261
     262    GnuTLSDHFile FILEPATH
     263
     264Default: *none*\
     265Context: server config, virtual host
     266
     267Takes an absolute or relative path to a PKCS \#3 encoded DH
     268parameters.Those are used when the DHE key exchange method is enabled.
     269You can generate this file using `certtool --generate-dh-params --bits
     2702048`.  If not set `mod_gnutls` will use the included parameters.
     271
     272`GnuTLSSRPPasswdFile`
     273---------------------
     274
     275Set to the SRP password file for SRP ciphersuites
     276
     277    GnuTLSSRPPasswdFile FILEPATH
     278
     279Default: *none*\
     280Context: server config, virtual host
     281
     282Takes an absolute or relative path to an SRP password file. This is
     283the same format as used in libsrp.  You can generate such file using
     284the command `srptool --passwd /etc/tpasswd --passwd-conf
     285/etc/tpasswd.conf -u test` to set a password for user test.  This
     286password file holds the username, a password verifier and the
    392287dependency to the SRP parameters.
    393288
    394 #### GnuTLSSRPPasswdConfFile
    395 
    396 ##### Description:
    397 
    398 Set to the SRP password.conf file for SRP ciphersuites\
    399 
    400 ##### Syntax:
    401 
    402        GnuTLSSRPPasswdConfFile *file-path* \
    403 
    404 ##### Default:
    405 
    406       *none*\
    407 
    408 ##### Context:
    409 
    410       server config, virtual host\
    411 
    412 Takes an absolute or relative path to an SRP password.conf file. This is
    413 the same format as used in libsrp.\
    414  You can generate such file using the command "srptool --create-conf
    415 /etc/tpasswd.conf".\
    416  This file holds the SRP parameters and is associate with the password
    417 file (the verifiers depends on these parameters).
    418 
    419 #### GnuTLSPriorities
    420 
    421 ##### Description:
     289`GnuTLSSRPPasswdConfFile`
     290-------------------------
     291
     292Set to the SRP password.conf file for SRP ciphersuites
     293
     294    GnuTLSSRPPasswdConfFile FILEPATH
     295
     296Default: *none*\
     297Context: server config, virtual host
     298
     299Takes an absolute or relative path to an SRP password.conf file. This
     300is the same format as used in `libsrp`.  You can generate such file
     301using the command `srptool --create-conf /etc/tpasswd.conf`.  This
     302file holds the SRP parameters and is associate with the password file
     303(the verifiers depends on these parameters).
     304
     305`GnuTLSPriorities`
     306------------------
    422307
    423308Set the allowed ciphers, key exchange algorithms, MACs and compression
    424 methods\
    425 
    426 ##### Syntax:
    427 
    428        GnuTLSPriorities *+cipher0:+cipher1:...:+cipherN*\
    429 
    430 ##### Default:
    431 
    432       *none*\
    433 
    434 ##### Context:
    435 
    436       server config, virtual host\
    437 
    438 Takes a semi-colon separated list of ciphers, key exchange methods\
    439  Message authentication codes and compression methods to enable.\
    440  The allowed keywords are specified in the gnutls\_priority\_init()
    441 function of GnuTLS.\
    442  It's documentation can be found at [Core GnuTLS
    443 functions](http://www.gnu.org/software/gnutls/manual/html_node/Core-functions.html#Core-functions).\
    444  In brief you can specify a set of ciphersuites from the choices:\
    445 
    446 -   **NONE**: The empty list.
    447 -   **EXPORT**: A list with all the supported cipher combinations
    448     including the "EXPORT" strength algorithms.
    449 -   **PERFORMANCE**: A list with all the secure cipher combinations
    450     sorted in terms of performance.
    451 -   **NORMAL**: A list with all the secure cipher combinations sorted
     309methods
     310
     311    GnuTLSPriorities +CIPHER_0:+CIPHER_1:...:+CIPHER_N
     312
     313Default: *none*\
     314Context: server config, virtual host
     315
     316Takes a semi-colon separated list of ciphers, key exchange methods
     317Message authentication codes and compression methods to enable.
     318The allowed keywords are specified in the `gnutls_priority_init()`
     319function of GnuTLS.
     320
     321Its documentation can be found at [Core GnuTLS functions](http://www.gnu.org/software/gnutls/manual/html_node/Core-functions.html#Core-functions).
     322In brief you can specify a set of ciphersuites from the choices:
     323
     324`NONE`
     325:   The empty list.
     326
     327`EXPORT`
     328:   A list with all the supported cipher combinations
     329    including the `EXPORT` strength algorithms.
     330
     331`PERFORMANCE`
     332:   A list with all the secure cipher combinations sorted in terms of performance.
     333
     334`NORMAL`
     335:   A list with all the secure cipher combinations sorted
    452336    with respect to security margin (subjective term).
    453 -   **SECURE**: A list with all the secure cipher combinations including
     337
     338`SECURE`
     339:   A list with all the secure cipher combinations including
    454340    the 256-bit ciphers sorted with respect to security margin.
    455341
    456 Additionally you can add or remove algorithms using the "+" and "!"
    457 prefixes respectively.\
    458  That is in order to disable the ARCFOUR cipher from the "NORMAL" set
    459 you can use the string **NORMAL**:!ARCFOUR-128\
    460  Other options such as the protocol version and the compression method
    461 can be specified using the **VERS-** and **COMP-** prefixes.\
    462  So in order to remove or add a specific TLS version from the "NORMAL"
    463 set use **NORMAL:!VERS-SSL3.0**.\
    464  To enable zlib compression use **NORMAL:+COMP-DEFLATE**.\
    465  However it is recommended not to add compression at this level.\
    466  With the "NONE" set, in order to be usable, you have to specify a
    467 complete set of combinations of protocol versions,\
    468  cipher algorithms (**AES-128-CBC**), key exchange algorithms (**RSA**),
    469 message authentication codes (**SHA1**) and compression methods
    470 (**COMP-NULL**).\
    471  \
    472  All the supported algorithms are:\
    473 
    474 -   **Ciphers**: AES-256-CBC, AES-128-CBC, CAMELLIA-256-CBC,
    475     CAMELLIA-128-CBC, ARCFOUR-128, 3DES-CBC, ARCFOUR-40
    476 -   **Key exchange methods**: RSA, DHE-RSA, DHE-DSS, SRP, SRP-RSA,
    477     SRP-DSS, ANON-DH
    478 -   **Message authentication codes**: SHA1, MD5
    479 -   **Compression methods**: COMP-DEFLATE, COMP-NULL
    480 -   **Protocol versions**: VERS-TLS1.1, VERS-TLS1.0, VERS-SSL3.0
    481 
    482 The special keyword "%COMPAT" will disable some security features such
     342Additionally you can add or remove algorithms using the `+` and `!`
     343prefixes respectively.
     344
     345For example, in order to disable the `ARCFOUR` cipher from the `NORMAL` set
     346you can use the string `NORMAL:!ARCFOUR-128`
     347
     348Other options such as the protocol version and the compression method
     349can be specified using the `VERS-` and `COMP-` prefixes.
     350
     351So in order to remove or add a specific TLS version from the `NORMAL`
     352set, use `NORMAL:!VERS-SSL3.0`.  And to enable zlib compression use
     353`NORMAL:+COMP-DEFLATE`.
     354
     355
     356However it is recommended not to add compression at this level.  With
     357the `NONE` set, in order to be usable, you have to specify a complete
     358set of combinations of protocol versions, cipher algorithms
     359(`AES-128-CBC`), key exchange algorithms (`RSA`), message
     360authentication codes (`SHA1`) and compression methods (`COMP-NULL`).
     361
     362You can find a list of all supported Ciphers, Versions, MACs, etc.  by
     363running `gnutls-cli --list`.
     364
     365The special keyword `%COMPAT` will disable some security features such
    483366as protection against statistical attacks to ciphertext data in order to
    484367achieve maximum compatibility (some broken mobile clients need this).
    485368
    486 #### GnuTLSExportCertificates
    487 
    488 ##### Description:
    489 
    490 Export the PEM encoded certificates to CGIs\
    491 
    492 ##### Syntax:
    493 
    494        GnuTLSExportCertificates [ *on* | *off* ]\
    495 
    496 ##### Default:
    497 
    498       *off*\
    499 
    500 ##### Context:
    501 
    502       server config, virtual host\
     369`GnuTLSExportCertificates`
     370--------------------------
     371
     372Export the PEM encoded certificates to CGIs
     373
     374    GnuTLSExportCertificates [on|off]
     375
     376Default: `off`\
     377Context: server config, virtual host
    503378
    504379This directive enables exporting the full certificates of the server and
    505380the client to CGI scripts. The exported certificates will be PEM-encoded
    506 (if X.509) or ASCII-armored (if OpenPGP).\
    507 With GnuTLSExportCertificates enabled, mod\_gnutls exports the same
    508 environment variables as mod\_ssl.
     381(if X.509) or ASCII-armored (if OpenPGP).
     382With GnuTLSExportCertificates enabled, `mod_gnutls` exports the same
     383environment variables to the CGI process as `mod_ssl`.
    509384
    510385* * * * *
    511386
    512387Configuration Examples
    513 ----------------------
    514 
    515 #### Simple Standard SSL Example:
     388======================
     389
     390Simple Standard SSL Example
     391---------------------------
    516392
    517393The following is an example of standard SSL Hosting, using one IP
    518394Addresses for each virtual host
    519395
    520 `             # Load the module into Apache.             LoadModule gnutls_module modules/mod_gnutls.so             GnuTLSCache gdbm /var/cache/www-tls-cache             GnuTLSCacheTimeout 500             # With normal SSL Websites, you need one IP Address per-site.             Listen 1.2.3.1:443             Listen 1.2.3.2:443             Listen 1.2.3.3:443             Listen 1.2.3.4:443             <VirtualHost 1.2.3.1:443>             GnuTLSEnable on             GnuTLSPriorities NONE:+AES-128-CBC:+3DES-CBC:+ARCFOUR-128:+RSA:+DHE-RSA:+DHE-DSS:+SHA1:+MD5:+COMP-NULL             DocumentRoot /www/site1.example.com/html             ServerName site1.example.com:443             GnuTLSCertificateFile conf/ssl/site1.crt             GnuTLSKeyFile conf/ss/site1.key             </VirtualHost>             <VirtualHost 1.2.3.2:443>             # This virtual host enables SRP authentication             GnuTLSEnable on             GnuTLSPriorities NORMAL:+SRP             DocumentRoot /www/site2.example.com/html             ServerName site2.example.com:443             GnuTLSSRPPasswdFile conf/ssl/tpasswd.site2             GnuTLSSRPPasswdConfFile conf/ssl/tpasswd.site2.conf             </VirtualHost>             <VirtualHost 1.2.3.3:443>             # This server enables SRP, OpenPGP and X.509 authentication.             GnuTLSEnable on             GnuTLSPriorities NORMAL:+SRP:+SRP-RSA:+SRP-DSS             DocumentRoot /www/site3.example.com/html             ServerName site3.example.com:443             GnuTLSCertificateFile conf/ssl/site3.crt             GnuTLSKeyFile conf/ss/site3.key             GnuTLSClientVerify ignore             GnuTLSPGPCertificateFile conf/ss/site3.pub.asc             GnuTLSPGPKeyFile conf/ss/site3.sec.asc             GnuTLSSRPPasswdFile conf/ssl/tpasswd.site3             GnuTLSSRPPasswdConfFile conf/ssl/tpasswd.site3.conf             </VirtualHost>             <VirtualHost 1.2.3.4:443>             GnuTLSEnable on             # %COMPAT disables some security features to enable maximum compatibility with clients.             GnuTLSPriorities NONE:+AES-128-CBC:+ARCFOUR-128:+RSA:+SHA1:+MD5:+COMP-NULL:%COMPAT             DocumentRoot /www/site4.example.com/html             ServerName site4.example.com:443             GnuTLSCertificateFile conf/ssl/site4.crt             GnuTLSKeyFile conf/ss/site4.key             </VirtualHost>             `
    521 
    522 #### Server Name Indication Example:
    523 
    524 mod\_gnutls can also use 'Server Name Indication', as specified in RFC
    525 3546.\
    526  This allows hosting many SSL Websites, with a Single IP Address.\
    527  Currently all the recent browsers support this standard.\
    528  Here is an example, using SNI:\
    529  `             `
    530 
    531 \# Load the module into Apache.\
    532  LoadModule gnutls\_module modules/mod\_gnutls.so\
    533  \# With normal SSL Websites, you need one IP Address per-site.\
    534  Listen 1.2.3.1:443\
    535  \# This could also be 'Listen \*:443',\
    536  \# just like '\*:80' is common for non-https\
    537  \# No caching. Enable session tickets. Timeout is still used for\
    538  \# ticket expiration.\
    539  GnuTLSCacheTimeout 600\
    540  \# This tells apache, that for this IP/Port combination, we want to
    541 use\
    542  \# Name Based Virtual Hosting. In the case of Server Name Indication,\
    543  \# it lets mod\_gnutls pick the correct Server Certificate.\
    544  NameVirtualHost 1.2.3.1:443\
    545  \<VirtualHost 1.2.3.1:443\>\
    546  GnuTLSEnable on\
    547  GnuTLSSessionTickets on\
    548  GnuTLSPriorities NORMAL\
    549  DocumentRoot /www/site1.example.com/html\
    550  ServerName site1.example.com:443\
    551  GnuTLSCertificateFile conf/ssl/site1.crt\
    552  GnuTLSKeyFile conf/ss/site1.key\
    553  \</VirtualHost\>\
    554  \<VirtualHost 1.2.3.1:443\>\
    555  GnuTLSEnable on\
    556  GnuTLSPriorities NORMAL\
    557  DocumentRoot /www/site2.example.com/html\
    558  ServerName site2.example.com:443\
    559  GnuTLSCertificateFile conf/ssl/site2.crt\
    560  GnuTLSKeyFile conf/ss/site2.key\
    561  \</VirtualHost\>\
    562  \<VirtualHost 1.2.3.1:443\>\
    563  GnuTLSEnable on\
    564  GnuTLSPriorities NORMAL\
    565  DocumentRoot /www/site3.example.com/html\
    566  ServerName site3.example.com:443\
    567  GnuTLSCertificateFile conf/ssl/site3.crt\
    568  GnuTLSKeyFile conf/ss/site3.key\
    569  \</VirtualHost\>\
    570  \<VirtualHost 1.2.3.1:443\>\
    571  GnuTLSEnable on\
    572  GnuTLSPriorities NORMAL\
    573  DocumentRoot /www/site4.example.com/html\
    574  ServerName site4.example.com:443\
    575  GnuTLSCertificateFile conf/ssl/site4.crt\
    576  GnuTLSKeyFile conf/ss/site4.key\
    577  \</VirtualHost\>\
     396     # Load the module into Apache.
     397     LoadModule gnutls_module modules/mod_gnutls.so
     398     GnuTLSCache gdbm /var/cache/www-tls-cache
     399     GnuTLSCacheTimeout 500
     400     # With normal SSL Websites, you need one IP Address per-site.
     401     Listen 1.2.3.1:443
     402     Listen 1.2.3.2:443
     403     Listen 1.2.3.3:443
     404     Listen 1.2.3.4:443
     405     <VirtualHost 1.2.3.1:443>
     406     GnuTLSEnable on
     407     GnuTLSPriorities NONE:+AES-128-CBC:+3DES-CBC:+ARCFOUR-128:+RSA:+DHE-RSA:+DHE-DSS:+SHA1:+MD5:+COMP-NULL
     408     DocumentRoot /www/site1.example.com/html
     409     ServerName site1.example.com:443
     410     GnuTLSCertificateFile conf/ssl/site1.crt
     411     GnuTLSKeyFile conf/ss/site1.key
     412     </VirtualHost>
     413     <VirtualHost 1.2.3.2:443>
     414     # This virtual host enables SRP authentication
     415     GnuTLSEnable on
     416     GnuTLSPriorities NORMAL:+SRP
     417     DocumentRoot /www/site2.example.com/html
     418     ServerName site2.example.com:443
     419     GnuTLSSRPPasswdFile conf/ssl/tpasswd.site2
     420     GnuTLSSRPPasswdConfFile conf/ssl/tpasswd.site2.conf
     421     </VirtualHost>
     422     <VirtualHost 1.2.3.3:443>
     423     # This server enables SRP, OpenPGP and X.509 authentication.
     424     GnuTLSEnable on
     425     GnuTLSPriorities NORMAL:+SRP:+SRP-RSA:+SRP-DSS
     426     DocumentRoot /www/site3.example.com/html
     427     ServerName site3.example.com:443
     428     GnuTLSCertificateFile conf/ssl/site3.crt
     429     GnuTLSKeyFile conf/ss/site3.key
     430     GnuTLSClientVerify ignore
     431     GnuTLSPGPCertificateFile conf/ss/site3.pub.asc
     432     GnuTLSPGPKeyFile conf/ss/site3.sec.asc
     433     GnuTLSSRPPasswdFile conf/ssl/tpasswd.site3
     434     GnuTLSSRPPasswdConfFile conf/ssl/tpasswd.site3.conf
     435     </VirtualHost>
     436     <VirtualHost 1.2.3.4:443>
     437     GnuTLSEnable on
     438     # %COMPAT disables some security features to enable maximum compatibility with clients.
     439     GnuTLSPriorities NONE:+AES-128-CBC:+ARCFOUR-128:+RSA:+SHA1:+MD5:+COMP-NULL:%COMPAT
     440     DocumentRoot /www/site4.example.com/html
     441     ServerName site4.example.com:443
     442     GnuTLSCertificateFile conf/ssl/site4.crt
     443     GnuTLSKeyFile conf/ss/site4.key
     444     </VirtualHost>
     445
     446Server Name Indication Example
     447------------------------------
     448
     449`mod_gnutls` can also use "Server Name Indication", as specified in
     450RFC 3546.  This allows hosting many SSL Websites, with a Single IP
     451Address.  Currently all the recent browsers support this
     452standard. Here is an example, using SNI: ` `
     453
     454
     455     # Load the module into Apache.
     456     LoadModule gnutls_module modules/mod_gnutls.so
     457     # With normal SSL Websites, you need one IP Address per-site.
     458     Listen 1.2.3.1:443
     459     # This could also be 'Listen *:443',
     460     # just like '*:80' is common for non-https
     461     # No caching. Enable session tickets. Timeout is still used for
     462     # ticket expiration.
     463     GnuTLSCacheTimeout 600
     464     # This tells apache, that for this IP/Port combination, we want to use
     465     # Name Based Virtual Hosting. In the case of Server Name Indication,
     466     # it lets mod_gnutls pick the correct Server Certificate.
     467     NameVirtualHost 1.2.3.1:443
     468     <VirtualHost 1.2.3.1:443>
     469     GnuTLSEnable on
     470     GnuTLSSessionTickets on
     471     GnuTLSPriorities NORMAL
     472     DocumentRoot /www/site1.example.com/html
     473     ServerName site1.example.com:443
     474     GnuTLSCertificateFile conf/ssl/site1.crt
     475     GnuTLSKeyFile conf/ss/site1.key
     476     </VirtualHost>
     477     <VirtualHost 1.2.3.1:443>
     478     GnuTLSEnable on
     479     GnuTLSPriorities NORMAL
     480     DocumentRoot /www/site2.example.com/html
     481     ServerName site2.example.com:443
     482     GnuTLSCertificateFile conf/ssl/site2.crt
     483     GnuTLSKeyFile conf/ss/site2.key
     484     </VirtualHost>
     485     <VirtualHost 1.2.3.1:443>
     486     GnuTLSEnable on
     487     GnuTLSPriorities NORMAL
     488     DocumentRoot /www/site3.example.com/html
     489     ServerName site3.example.com:443
     490     GnuTLSCertificateFile conf/ssl/site3.crt
     491     GnuTLSKeyFile conf/ss/site3.key
     492     </VirtualHost>
     493     <VirtualHost 1.2.3.1:443>
     494     GnuTLSEnable on
     495     GnuTLSPriorities NORMAL
     496     DocumentRoot /www/site4.example.com/html
     497     ServerName site4.example.com:443
     498     GnuTLSCertificateFile conf/ssl/site4.crt
     499     GnuTLSKeyFile conf/ss/site4.key
     500     </VirtualHost>
     501
    578502
    579503* * * * *
    580504
    581 Performance Issues:
     505Performance Issues
     506==================
     507
     508`mod_gnutls` by default uses conservative settings for the server.
     509You can fine tune the configuration to reduce the load on a busy
     510server.  The following examples do exactly this:
     511
     512
     513     # Load the module into Apache.
     514     LoadModule gnutls_module modules/mod_gnutls.so
     515     # Using 4 memcache servers to distribute the SSL Session Cache.
     516     GnuTLSCache memcache "mc1.example.com mc2.example.com mc3.example.com mc4.example.com"
     517     GnuTLSCacheTimeout 600
     518     Listen 1.2.3.1:443
     519     NameVirtualHost 1.2.3.1:443
     520     <VirtualHost 1.2.3.1:443>
     521     GnuTLSEnable on
     522     # Here we disable the Perfect forward secrecy ciphersuites (DHE)
     523     # and disallow AES-256 since AES-128 is just fine.
     524     GnuTLSPriorities NORMAL:!DHE-RSA:!DHE-DSS:!AES-256-CBC:%COMPAT
     525     DocumentRoot /www/site1.example.com/html
     526     ServerName site1.example.com:443
     527     GnuTLSCertificateFile conf/ssl/site1.crt
     528     GnuTLSKeyFile conf/ss/site1.key
     529     </VirtualHost>
     530     <VirtualHost 1.2.3.1:443>
     531     GnuTLSEnable on
     532     # Here we instead of disabling the DHE ciphersuites we use
     533     # Diffie Hellman parameters of smaller size than the default (2048 bits).
     534     # Using small numbers from 768 to 1024 bits should be ok once they are
     535     # regenerated every few hours.
     536     # Use "certtool --generate-dh-params --bits 1024" to get those
     537     GnuTLSDHFile /etc/apache2/dh.params
     538     GnuTLSPriorities NORMAL:!AES-256-CBC:%COMPAT
     539     DocumentRoot /www/site2.example.com/html
     540     ServerName site2.example.com:443
     541     GnuTLSCertificateFile conf/ssl/site2.crt
     542     GnuTLSKeyFile conf/ss/site2.key
     543     </VirtualHost>
     544
     545* * * * *
     546
     547Environment Variables
     548=====================
     549
     550`mod_gnutls` exports the following environment variables to scripts.
     551These are compatible with `mod_ssl`.
     552
     553`HTTPS`
     554-------
     555
     556Can be `on` or `off`
     557
     558`SSL_VERSION_LIBRARY`
     559---------------------
     560
     561The version of the GnuTLS library
     562
     563`SSL_VERSION_INTERFACE`
     564-----------------------
     565
     566The version of this module
     567
     568`SSL_PROTOCOL`
     569--------------
     570
     571The SSL or TLS protocol name (such as `TLS 1.0` etc.)
     572
     573`SSL_CIPHER`
     574------------
     575
     576The SSL or TLS cipher suite name
     577
     578`SSL_COMPRESS_METHOD`
     579---------------------
     580
     581The negotiated compression method (`NULL` or `DEFLATE`)
     582
     583`SSL_SRP_USER`
     584--------------
     585
     586The SRP username used for authentication (only set when
     587`GnuTLSSRPPasswdFile` and `GnuTLSSRPPasswdConfFile` are configured).
     588
     589`SSL_CIPHER_USEKEYSIZE` & `SSL_CIPHER_ALGKEYSIZE`
     590-------------------------------------------------
     591
     592The number if bits used in the used cipher algorithm.
     593
     594This does not fully reflect the security level since the size of
     595RSA or DHE key exchange parameters affect the security level too.
     596
     597`SSL_CIPHER_EXPORT`
    582598-------------------
    583599
    584 mod\_gnutls by default uses conservative settings for the server.\
    585  You can fine tune the configuration to reduce the load on a busy
    586 server.\
    587  The following examples do exactly this:\
    588 
    589 `             # Load the module into Apache.             LoadModule gnutls_module modules/mod_gnutls.so             # Using 4 memcache servers to distribute the SSL Session Cache.             GnuTLSCache memcache "mc1.example.com mc2.example.com mc3.example.com mc4.example.com"             GnuTLSCacheTimeout 600             Listen 1.2.3.1:443             NameVirtualHost 1.2.3.1:443             <VirtualHost 1.2.3.1:443>             GnuTLSEnable on             # Here we disable the Perfect forward secrecy ciphersuites (DHE)             # and disallow AES-256 since AES-128 is just fine.             GnuTLSPriorities NORMAL:!DHE-RSA:!DHE-DSS:!AES-256-CBC:%COMPAT             DocumentRoot /www/site1.example.com/html             ServerName site1.example.com:443             GnuTLSCertificateFile conf/ssl/site1.crt             GnuTLSKeyFile conf/ss/site1.key             </VirtualHost>             <VirtualHost 1.2.3.1:443>             GnuTLSEnable on             # Here we instead of disabling the DHE ciphersuites we use             # Diffie Hellman parameters of smaller size than the default (2048 bits).             # Using small numbers from 768 to 1024 bits should be ok once they are             # regenerated every few hours.             # Use "certtool --generate-dh-params --bits 1024" to get those             GnuTLSDHFile /etc/apache2/dh.params             GnuTLSPriorities NORMAL:!AES-256-CBC:%COMPAT             DocumentRoot /www/site2.example.com/html             ServerName site2.example.com:443             GnuTLSCertificateFile conf/ssl/site2.crt             GnuTLSKeyFile conf/ss/site2.key             </VirtualHost>             `
    590 
    591 * * * * *
    592 
    593 Environment Variables:
    594 ----------------------
    595 
    596 mod\_gnutls exports the following environment variables to scripts.\
    597  These are compatible with mod\_ssl.
    598 
    599 ###### HTTPS
    600 
    601 Can be "on" or "off"
    602 
    603 ###### SSL\_VERSION\_LIBRARY
    604 
    605 The version of the gnutls library
    606 
    607 ###### SSL\_VERSION\_INTERFACE
    608 
    609 The version of this module
    610 
    611 ###### SSL\_PROTOCOL
    612 
    613 The SSL or TLS protocol name (such as "TLS 1.0" etc.)
    614 
    615 ###### SSL\_CIPHER
    616 
    617 The SSL or TLS cipher suite name
    618 
    619 ###### SSL\_COMPRESS\_METHOD
    620 
    621 The negotiated compression method (NULL or DEFLATE)
    622 
    623 ###### SSL\_SRP\_USER
    624 
    625 The SRP username used for authentication (only set when
    626 GnuTLSSRPPasswdFile and GnuTLSSRPPasswdConfFile are configured).
    627 
    628 ###### SSL\_CIPHER\_USEKEYSIZE & SSL\_CIPHER\_ALGKEYSIZE
    629 
    630 The number if bits used in the used cipher algorithm.
    631 
    632 This does not fully reflect the security level since the size of
    633 
    634 RSA or DHE key exchange parameters affect the security level too.
    635 
    636 ###### SSL\_CIPHER\_EXPORT
    637 
    638 True or False. Whether the cipher suite negotiated is an export one.
    639 
    640 ###### SSL\_SESSION\_ID
     600`True` or `False`. Whether the cipher suite negotiated is an export one.
     601
     602`SSL_SESSION_ID`
     603----------------
    641604
    642605The session ID negotiated in this session. Can be the same during client
    643606reloads.
    644607
    645 ###### SSL\_CLIENT\_V\_REMAIN
     608`SSL_CLIENT_V_REMAIN`
     609---------------------
    646610
    647611The number of days until the client's certificate is expired.
    648612
    649 ###### SSL\_CLIENT\_V\_START
     613`SSL_CLIENT_V_START`
     614--------------------
    650615
    651616The activation time of client's certificate.
    652617
    653 ###### SSL\_CLIENT\_V\_END
     618`SSL_CLIENT_V_END`
     619------------------
    654620
    655621The expiration time of client's certificate.
    656622
    657 ###### SSL\_CLIENT\_S\_DN
     623`SSL_CLIENT_S_DN`
     624-----------------
    658625
    659626The distinguished name of client's certificate in RFC2253 format.
    660627
    661 ###### SSL\_CLIENT\_I\_DN
     628`SSL_CLIENT_I_DN`
     629-----------------
    662630
    663631The SSL or TLS cipher suite name
    664632
    665 ###### SSL\_CLIENT\_S\_AN%
    666 
    667 These will contain the alternative names of the client certificate (% is
     633`SSL_CLIENT_S_AN%`
     634------------------
     635
     636These will contain the alternative names of the client certificate (`%` is
    668637a number starting from zero).
    669638
    670 The values will be prepended by "DNSNAME:", "RFC822NAME:" or "URI:"
     639The values will be prepended by `DNSNAME:`, `RFC822NAME:` or `URI:`
    671640depending on the type.
    672641
    673 If it is not supported the value "UNSUPPORTED" will be set.
    674 
    675 ###### SSL\_SERVER\_M\_SERIAL
     642If it is not supported the value `UNSUPPORTED` will be set.
     643
     644`SSL_SERVER_M_SERIAL`
     645---------------------
    676646
    677647The serial number of the server's certificate.
    678648
    679 ###### SSL\_SERVER\_M\_VERSION
     649`SSL_SERVER_M_VERSION`
     650----------------------
    680651
    681652The version of the server's certificate.
    682653
    683 ###### SSL\_SERVER\_A\_SIG
     654`SSL_SERVER_A_SIG`
     655------------------
    684656
    685657The algorithm used for the signature in server's certificate.
    686658
    687 ###### SSL\_SERVER\_A\_KEY
     659`SSL_SERVER_A_KEY`
     660------------------
    688661
    689662The public key algorithm in server's certificate.
    690663
    691 ###### SSL\_SERVER\_CERT
     664`SSL_SERVER1_CERT`
     665------------------
    692666
    693667The PEM-encoded server certificate.
    694668
    695 ###### SSL\_SERVER\_CERT\_TYPE
    696 
    697 The certificate type can be X.509 or OPENPGP.
     669`SSL_SERVER_CERT_TYPE`
     670----------------------
     671
     672The certificate type can be `X.509` or `OPENPGP`.
Note: See TracChangeset for help on using the changeset viewer.