[Httpd Wiki] Update of "OCSPStapling" by JeffTrawick

[Apache Wiki <wi...@apache.org>]

Dear Wiki user,

You have subscribed to a wiki page or wiki category on "Httpd Wiki" for change notification.

The "OCSPStapling" page has been changed by JeffTrawick:
https://wiki.apache.org/httpd/OCSPStapling

Comment:
OCSP Stapling hand-holding

New page:
#format wiki
#language en
== OCSP Stapling ==
OCSP Stapling is one of the many new features introduced with httpd 2.4.  It allows client software using SSL to communicate with your server to efficiently check that your server certificate has not been revoked.  The primary how-to for OCSP Stapling in httpd is at [[http://httpd.apache.org/docs/2.4/ssl/ssl_howto.html#ocspstapling|OCSP Stapling How-To]].  Read that first.

This guide includes:

 * summary of fixes to OCSP Stapling in different releases of httpd
 * distribution-specific information about enabling OCSP Stapling

=== Fixes related to OCSP Stapling in different 2.4.x levels ===

Note: Some distributors of httpd, including Linux vendors, use a particular httpd 2.4.x version for the life of the related product, and choose to selectively apply fixes to that codebase without fully upgrading httpd to a new version.  Any stapling-related fixes which vendors have backported to an older 2.4.x version are not reflected in the following table.

|| '''First open source release with fix''' || '''Considerations''' || Description ||
|| 2.4.11 || If you don’t have the crash, you don’t care about this bug. || PR 54357 – crash at startup or restart with stapling enabled in some configurations ||
|| 2.4.10 || The fix only affects certificates with no responder (rare). || Better handling for certificates with no responder ||

=== Distribution-specific hints for enabling OCSP Stapling ===

OCSP Stapling is usually enabled using only global (non vhost-specific) directives.  In some cases, vhost-specific directives may be required.  For example, you may have a default SSL-enabled vhost which uses a self-signed certificate which is intended to handle only those requests for a server name not supported in your configuration, which will result in stapling-related log messages at startup since stapling can't be performed for that certificate.  You could quiet those log messages by adding {{{SSLUseStapling Off}}} inside the related vhost.

A number of third-party distributions of httpd have their own conventions for where global and vhost-specific SSL configuration directives are placed.  A number of these distributions are covered below.  (In the event that you bypass the distribution's configuration layout, the material below will not be useful.)

==== Open source distribution of httpd with the default layout ====

The default configuration uses {{{conf/extra/httpd-ssl.conf}}} for the global SSL configuration as well as the default SSL-enabled vhost.  Place these directives before the {{{## SSL Virtual Host Context}}} comment:

{{{
SSLUseStapling On
SSLStaplingCache shmcb:logs/ssl_stapling(32768)
}}}

Beginning with httpd 2.4.11, the default configuration will include these directives, commented out.  Simply uncomment {{{SSLUseStapling}}} and {{{SSLStaplingCache}}}.  If you install httpd 2.4.11 or later over an existing httpd 2.4.x installation, the new default SSL configuration will be stored in {{{conf/original/extra/httpd-ssl.conf}}}; you can carefully compare your existing configuration with the new default to see what improvements you wish to integrate into your existing configuration.

==== Apache Lounge distribution of httpd for Windows ====

Note: Apache Lounge is not affiliated with the Apache Software Foundation.

The default configuration files in this distribution match those of the open source httpd distribution.  Be aware that paths for run-time files such as {{{SSLSessionCache}}} are hard-coded to {{{C:/Apache24/logs}}}, which should have already been changed by the administrator based on where httpd is installed.   Use the same directory in your {{{SSLStaplingCache}}} directive as in your existing {{{SSLSessionCache}}} directive.

==== FreeBSD 9 and 10 Port Package “apache24” ====

The normal default {{{httpd-ssl.conf}}} file is in the directory {{{/usr/local/etc/apache24/extra}}}; that contains global SSL settings as well as settings for the default SSL-enabled virtual host.

Non-default virtual host configurations will likely be stored in the directory {{{/usr/local/etc/apache24/Includes}}}.

==== openSUSE 13.2 ====

The global mod_ssl configuration is in the file {{{/etc/apache2/ssl-global.conf}}}.  The platform configurations use the directory {{{/var/lib/apache2}}} for the location of cache and other run-time files, so the two minimal lines required to enable OCSP Stapling for this platform are

{{{
SSLUseStapling On
SSLStaplingCache shmcb:/var/lib/apache2/ssl_stapling(32768)
}}}

These directives should be placed just before {{{</IfModule>}}} directive at the end of {{{ssl-global.conf}}}.

In the event that the OCSP Stapling configuration should differ for some virtual hosts, make any changes for the default virtual host in {{{/etc/apache2/default-vhost-ssl.conf}}}, and for other SSL-enabled virtual hosts in {{{/etc/apache2/vhosts.d/my-vhost-ssl.conf}}}. 

==== Red Hat Enterprise Linux 7, CentOS 7, and Fedora 20 ====

The global mod_ssl configuration is in the file {{{/etc/httpd/conf.d/ssl.conf}}}.  The platform configurations use the directory {{{/run/httpd}}} for the location of cache and other run-time files, so the two minimal lines required to enable OCSP Stapling for this platform are

{{{
SSLUseStapling On
SSLStaplingCache shmcb:/run/httpd/ssl_stapling(32768)
}}}

These directives should be placed just before the following text:

{{{
##
## SSL Virtual Host Context
##
<VirtualHost _default_:443>
}}}

Any other OCSP Stapling directives required globally would be placed here as well.

In the event that the OCSP Stapling configuration should differ for some virtual hosts, the file to edit will likely differ based on site policy.  The platform {{{.conf}}} file referred to above also defines a default SSL-enabled virtual host for port 443, so changes to that virtual host would be made there.  Any other SSL-enabled virtual hosts would likely be defined in site-specific files within the {{{/etc/httpd/conf.d directory}}}.

==== Ubuntu 14, Debian test (Jessie) ====

The global mod_ssl configuration is in the file {{{/etc/apache2/mods-available/ssl.conf}}} and is symlinked into {{{/etc/apache2/mods-enabled}}} once you run {{{a2enmod}}} for mod_ssl.  The Ubuntu configurations use the variable {{{APACHE_RUN_DIR}}} for the location of cache and other run-time files, so the two minimal lines required to enable OCSP Stapling for Ubuntu are

{{{
SSLUseStapling On
SSLStaplingCache shmcb:${APACHE_RUN_DIR}/ssl_stapling(32768)
}}}

These directives should be placed just before {{{</IfModule>}}} near the end of the file.  Any other OCSP Stapling directives required globally would be placed here as well.

In the event that the OCSP Stapling configuration should differ for some virtual hosts, edit the appropriate file in the {{{/etc/apache2/sites-enabled}}} directory, and add the required directives inside the SSL-enabled virtual host.  The default SSL-enabled virtual host may be in {{{/etc/sites-enabled/default-ssl.conf}}}.

---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org