Changeset 1a3068c in mod_gnutls for doc/mod_gnutls_manual.mdwn


Ignore:
Timestamp:
Oct 1, 2018, 1:03:16 PM (14 months ago)
Author:
Fiona Klute <fiona.klute@…>
Branches:
debian/master, master
Children:
5f15295
Parents:
bac1a32
Message:

Update documentation on OCSP stapling and the certificate file

File:
1 edited

Legend:

Unmodified
Added
Removed
  • doc/mod_gnutls_manual.mdwn

    rbac1a32 r1a3068c  
    295295### GnuTLSCertificateFile
    296296
    297 Set to the PEM Encoded Server Certificate
     297Set the PEM encoded server certificate or certificate chain
    298298
    299299    GnuTLSCertificateFile FILEPATH
     
    302302Context: server config, virtual host
    303303
    304 Takes an absolute or relative path to a PEM-encoded X.509 certificate to
    305 use as this Server's End Entity (EE) certificate. If you need to supply
    306 certificates for intermediate Certificate Authorities (iCAs), they
    307 should be listed in sequence in the file, from EE to the iCA closest to
    308 the root CA. Optionally, you can also include the root CA's certificate
    309 as the last certificate in the list.
    310 
    311 Since version 0.7 this can be a PKCS #11 URL.
     304FILEPATH is an absolute or relative path to a file containing the
     305PEM-encoded X.509 certificate to use as this Server's End Entity (EE)
     306certificate, and optionally those of the issuing Certificate
     307Authorities (CAs). If the file contains multiple certificates they
     308should be ordered from EE to the CA closest to the root CA (or the
     309root CA itself).
     310
     311Including at least the immediately issuing CA is highly recommended
     312because it is required for OCSP stapling.
     313
     314Since version 0.7 this can be a PKCS #11 URL instead of a file.
     315
     316On Linux and other Unix-like systems you can create the file with a
     317command like this (assuming "CA 1" issued the server certificate and
     318has been issued by "Root CA" itself):
     319
     320        $ cat server.pem ca-1.pem root-ca.pem >server-chain.pem
    312321
    313322### GnuTLSKeyFile
     
    485494    GnuTLSOCSPStapling [On|Off]
    486495
    487 Default: *off*\
     496Default: *on* if requirements are met, *off* otherwise\
    488497Context: server config, virtual host
    489498
    490499OCSP stapling, formally known as the TLS Certificate Status Request
    491 extension, allows the server to provide the client with an OCSP
    492 response for its certificate during the handshake. This way the client
    493 does not have to send an OCSP request to the CA to check the
    494 certificate status, which offers privacy and performance advantages.
     500extension, allows the server to provide the client with a cached OCSP
     501response for its certificate during the handshake. With OCSP stapling
     502the client does not have to send an OCSP request to the issuer CA to
     503check the certificate status, which offers privacy and performance
     504advantages, and avoids the security issue of how to handle errors that
     505prevent the client from getting a response.
    495506
    496507Using OCSP stapling has a few requirements:
    497508
    498 * Caching OCSP responses requires a cache, so `GnuTLSCache` must not
    499   be `none`.
    500509* `GnuTLSCertificateFile` must contain the issuer CA certificate in
    501510  addition to the server certificate so responses can be verified.
    502 * The certificate must either contain an OCSP access URI using HTTP,
    503   or `GnuTLSOCSPResponseFile` must be set.
     511* The server certificate must either contain an OCSP access URI using
     512  HTTP, or `GnuTLSOCSPResponseFile` must be set.
     513* Caching OCSP responses requires a cache to store responses. If
     514  `mod_socache_shmcb` is loaded `mod_gnutls` can set up the cache
     515  automatically without additional configuration, see
     516  `GnuTLSOCSPCache`.
     517
     518Stapling is activated by default if these requirements are met. If
     519`GnuTLSOCSPStapling` is explicitly set to `on` unmet requirements are
     520an error.
    504521
    505522OCSP cache updates are serialized using the `gnutls-ocsp` mutex.
     523
     524### GnuTLSOCSPCache
     525
     526OCSP stapling cache configuration
     527
     528        GnuTLSOCSPCache (shmcb|memcache|...|none)[:PARAMETERS]
     529
     530Default: `shmcb:gnutls_ocsp_cache`\
     531Context: server config
     532
     533This directive configures the OCSP stapling cache, and uses the same
     534syntax as `GnuTLSOCSPCache`. Please check there for details.
     535
     536The default should be reasonable for most servers and requires
     537`mod_socache_shmcb` to be loaded. Servers with very many virtual hosts
     538may need to increase the default cache size via the parameters string,
     539those with few virtual hosts and constrains could save a few KB by
     540reducing it. Note that `mod_socache_dbm` has a size constraint for
     541entries that is generally too small for OCSP responses.
     542
     543If the selected cache implementation is not thread-safe, access
     544is serialized using the `gnutls-ocsp-cache` mutex.
    506545
    507546### GnuTLSOCSPAutoRefresh
Note: See TracChangeset for help on using the changeset viewer.