| <?xml version='1.0' encoding='UTF-8' ?> |
| <!DOCTYPE manualpage SYSTEM "../style/manualpage.dtd"> |
| <?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?> |
| <!-- $LastChangedRevision$ --> |
| |
| <!-- |
| Licensed to the Apache Software Foundation (ASF) under one or more |
| contributor license agreements. See the NOTICE file distributed with |
| this work for additional information regarding copyright ownership. |
| The ASF licenses this file to You under the Apache License, Version 2.0 |
| (the "License"); you may not use this file except in compliance with |
| the License. You may obtain a copy of the License at |
| |
| http://www.apache.org/licenses/LICENSE-2.0 |
| |
| Unless required by applicable law or agreed to in writing, software |
| distributed under the License is distributed on an "AS IS" BASIS, |
| WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| See the License for the specific language governing permissions and |
| limitations under the License. |
| --> |
| |
| <manualpage metafile="ssl_howto.xml.meta"> |
| <parentdocument href="./">SSL/TLS</parentdocument> |
| |
| <title>SSL/TLS Strong Encryption: How-To</title> |
| |
| <summary> |
| |
| <p>This document is intended to get you started, and get a few things |
| working. You are strongly encouraged to read the rest of the SSL |
| documentation, and arrive at a deeper understanding of the material, |
| before progressing to the advanced techniques.</p> |
| </summary> |
| |
| <section id="configexample"> |
| <title>Basic Configuration Example</title> |
| |
| <p>Your SSL configuration will need to contain, at minimum, the |
| following directives.</p> |
| |
| <highlight language="config"> |
| LoadModule ssl_module modules/mod_ssl.so |
| |
| Listen 443 |
| <VirtualHost *:443> |
| ServerName www.example.com |
| SSLEngine on |
| SSLCertificateFile "/path/to/www.example.com.cert" |
| SSLCertificateKeyFile "/path/to/www.example.com.key" |
| </VirtualHost> |
| </highlight> |
| |
| </section> |
| |
| <section id="ciphersuites"> |
| <title>Cipher Suites and Enforcing Strong Security</title> |
| <ul> |
| <li><a href="#onlystrong">How can I create an SSL server which accepts strong encryption only?</a></li> |
| <li><a href="#strongurl">How can I create an SSL server which accepts all types of ciphers in general, but |
| requires a strong cipher for access to a particular URL?</a></li> |
| </ul> |
| |
| <section id="onlystrong"> |
| <title>How can I create an SSL server which accepts strong encryption |
| only?</title> |
| <p>The following enables only the strongest ciphers:</p> |
| <highlight language="config"> |
| SSLCipherSuite HIGH:!aNULL:!MD5 |
| </highlight> |
| |
| <p>While with the following configuration you specify a preference |
| for specific speed-optimized ciphers (which will be selected by |
| mod_ssl, provided that they are supported by the client):</p> |
| |
| <highlight language="config"> |
| SSLCipherSuite RC4-SHA:AES128-SHA:HIGH:!aNULL:!MD5 |
| SSLHonorCipherOrder on |
| </highlight> |
| </section> |
| |
| <section id="strongurl"> |
| <title>How can I create an SSL server which accepts all types of ciphers |
| in general, but requires a strong ciphers for access to a particular |
| URL?</title> |
| <p>Obviously, a server-wide <directive |
| module="mod_ssl">SSLCipherSuite</directive> which restricts |
| ciphers to the strong variants, isn't the answer here. However, |
| <module>mod_ssl</module> can be reconfigured within <code>Location</code> |
| blocks, to give a per-directory solution, and can automatically force |
| a renegotiation of the SSL parameters to meet the new configuration. |
| This can be done as follows:</p> |
| <highlight language="config"> |
| # be liberal in general |
| SSLCipherSuite ALL:!aNULL:RC4+RSA:+HIGH:+MEDIUM:+LOW:+EXP:+eNULL |
| |
| <Location "/strong/area"> |
| # but https://hostname/strong/area/ and below |
| # requires strong ciphers |
| SSLCipherSuite HIGH:!aNULL:!MD5 |
| </Location> |
| </highlight> |
| </section> |
| </section> |
| <!-- /ciphersuites --> |
| |
| <section id="ocspstapling"> |
| <title>OCSP Stapling</title> |
| |
| <p>The Online Certificate Status Protocol (OCSP) is a mechanism for |
| determining whether or not a server certificate has been revoked, and OCSP |
| Stapling is a special form of this in which the server, such as httpd and |
| mod_ssl, maintains current OCSP responses for its certificates and sends |
| them to clients which communicate with the server. Most certificates |
| contain the address of an OCSP responder maintained by the issuing |
| Certificate Authority, and mod_ssl can communicate with that responder to |
| obtain a signed response that can be sent to clients communicating with |
| the server.</p> |
| |
| <p>Because the client can obtain the certificate revocation status from |
| the server, without requiring an extra connection from the client to the |
| Certificate Authority, OCSP Stapling is the preferred way for the |
| revocation status to be obtained. Other benefits of eliminating the |
| communication between clients and the Certificate Authority are that the |
| client browsing history is not exposed to the Certificate Authority and |
| obtaining status is more reliable by not depending on potentially heavily |
| loaded Certificate Authority servers.</p> |
| |
| <p>Because the response obtained by the server can be reused for all clients |
| using the same certificate during the time that the response is valid, the |
| overhead for the server is minimal.</p> |
| |
| <p>Once general SSL support has been configured properly, enabling OCSP |
| Stapling generally requires only very minor modifications to the httpd |
| configuration — the addition of these two directives:</p> |
| |
| <highlight language="config"> |
| SSLUseStapling On |
| SSLStaplingCache "shmcb:logs/ssl_stapling(32768)" |
| </highlight> |
| |
| <p>These directives are placed at global scope (i.e., not within a virtual |
| host definition) wherever other global SSL configuration directives are |
| placed, such as in <code>conf/extra/httpd-ssl.conf</code> for normal |
| open source builds of httpd, <code>/etc/apache2/mods-enabled/ssl.conf</code> |
| for the Ubuntu or Debian-bundled httpd, etc.</p> |
| |
| <p>The path on the <directive>SSLStaplingCache</directive> directive |
| (e.g., <code>logs/</code>) should match the one on the |
| <directive>SSLSessionCache</directive> directive. This path is relative |
| to <directive>ServerRoot</directive>.</p> |
| |
| <p>This particular <directive>SSLStaplingCache</directive> directive requires |
| <module>mod_socache_shmcb</module> (from the <code>shmcb</code> prefix on the |
| directive's argument). This module is usually enabled already for |
| <directive>SSLSessionCache</directive> or on behalf of some module other than |
| <module>mod_ssl</module>. If you enabled an SSL session cache using a |
| mechanism other than <module>mod_socache_shmcb</module>, use that alternative |
| mechanism for <directive>SSLStaplingCache</directive> as well. For example:</p> |
| |
| <highlight language="config"> |
| SSLSessionCache "dbm:logs/ssl_scache" |
| SSLStaplingCache "dbm:logs/ssl_stapling" |
| </highlight> |
| |
| <p>You can use the openssl command-line program to verify that an OCSP response |
| is sent by your server:</p> |
| |
| <pre> |
| $ openssl s_client -connect www.example.com:443 -status -servername www.example.com |
| ... |
| OCSP response: |
| ====================================== |
| OCSP Response Data: |
| OCSP Response Status: successful (0x0) |
| Response Type: Basic OCSP Response |
| ... |
| Cert Status: Good |
| ... |
| </pre> |
| |
| <p>The following sections highlight the most common situations which require |
| further modification to the configuration. Refer also to the |
| <module>mod_ssl</module> reference manual.</p> |
| |
| <section> |
| <title>If more than a few SSL certificates are used for the server</title> |
| <p>OCSP responses are stored in the SSL stapling cache. While the responses |
| are typically a few hundred to a few thousand bytes in size, mod_ssl |
| supports OCSP responses up to around 10K bytes in size. With more than a |
| few certificates, the stapling cache size (32768 bytes in the example above) |
| may need to be increased. Error message AH01929 will be logged in case of |
| an error storing a response.</p> |
| </section> |
| |
| <section> |
| <title>If the certificate does not point to an OCSP responder, or if a |
| different address must be used</title> |
| <p>Refer to the |
| <directive module="mod_ssl">SSLStaplingForceURL</directive> directive.</p> |
| |
| <p>You can confirm that a server certificate points to an OCSP responder |
| using the openssl command-line program, as follows:</p> |
| |
| <pre> |
| $ openssl x509 -in ./www.example.com.crt -text | grep 'OCSP.*http' |
| OCSP - URI:http://ocsp.example.com |
| </pre> |
| |
| <p>If the OCSP URI is provided and the web server can communicate to it |
| directly without using a proxy, no configuration is required. Note that |
| firewall rules that control outbound connections from the web server may |
| need to be adjusted.</p> |
| |
| <p>If no OCSP URI is provided, contact your Certificate Authority to |
| determine if one is available; if so, configure it with |
| <directive module="mod_ssl">SSLStaplingForceURL</directive> in the virtual |
| host that uses the certificate.</p> |
| </section> |
| |
| <section> |
| <title>If multiple SSL-enabled virtual hosts are configured and OCSP |
| Stapling should be disabled for some</title> |
| |
| <p>Add <code>SSLUseStapling Off</code> to the virtual hosts for which OCSP |
| Stapling should be disabled.</p> |
| </section> |
| |
| <section> |
| <title>If the OCSP responder is slow or unreliable</title> |
| <p>Several directives are available to handle timeouts and errors. Refer |
| to the documentation for the |
| <directive module="mod_ssl">SSLStaplingFakeTryLater</directive>, |
| <directive module="mod_ssl">SSLStaplingResponderTimeout</directive>, and |
| <directive module="mod_ssl">SSLStaplingReturnResponderErrors</directive> |
| directives.</p> |
| </section> |
| |
| <section> |
| <title>If mod_ssl logs error AH02217</title> |
| <pre> |
| AH02217: ssl_stapling_init_cert: Can't retrieve issuer certificate! |
| </pre> |
| <p>In order to support OCSP Stapling when a particular server certificate is |
| used, the certificate chain for that certificate must be configured. If it |
| was not configured as part of enabling SSL, the AH02217 error will be issued |
| when stapling is enabled, and an OCSP response will not be provided for clients |
| using the certificate.</p> |
| |
| <p>Refer to the <directive module="mod_ssl">SSLCertificateChainFile</directive> |
| and <directive module="mod_ssl">SSLCertificateFile</directive> for instructions |
| for configuring the certificate chain.</p> |
| </section> |
| |
| </section> |
| <!-- /ocspstapling --> |
| |
| <section id="accesscontrol"> |
| <title>Client Authentication and Access Control</title> |
| <ul> |
| <li><a href="#allclients">How can I force clients to authenticate using certificates?</a></li> |
| <li><a href="#arbitraryclients">How can I force clients to authenticate using certificates for a |
| particular URL, but still allow arbitrary clients to access the rest of the server?</a></li> |
| <li><a href="#certauthenticate">How can I allow only clients who have certificates to access a |
| particular URL, but allow all clients to access the rest of the server?</a></li> |
| <li><a href="#intranet">How can I require HTTPS with strong ciphers, and either |
| basic authentication or client certificates, for access to part of the |
| Intranet website, for clients coming from the Internet?</a></li> |
| </ul> |
| |
| <section id="allclients"> |
| <title>How can I force clients to authenticate using certificates?</title> |
| |
| <p>When you know all of your users (eg, as is often the case on a corporate |
| Intranet), you can require plain certificate authentication. All you |
| need to do is to create client certificates signed by your own CA |
| certificate (<code>ca.crt</code>) and then verify the clients against this |
| certificate.</p> |
| <highlight language="config"> |
| # require a client certificate which has to be directly |
| # signed by our CA certificate in ca.crt |
| SSLVerifyClient require |
| SSLVerifyDepth 1 |
| SSLCACertificateFile "conf/ssl.crt/ca.crt" |
| </highlight> |
| </section> |
| |
| <section id="arbitraryclients"> |
| <title>How can I force clients to authenticate using certificates for a |
| particular URL, but still allow arbitrary clients to access the rest of the server?</title> |
| |
| <p>To force clients to authenticate using certificates for a particular URL, |
| you can use the per-directory reconfiguration features of |
| <module>mod_ssl</module>:</p> |
| |
| <highlight language="config"> |
| SSLVerifyClient none |
| SSLCACertificateFile "conf/ssl.crt/ca.crt" |
| |
| <Location "/secure/area"> |
| SSLVerifyClient require |
| SSLVerifyDepth 1 |
| </Location> |
| </highlight> |
| </section> |
| |
| <section id="certauthenticate"> |
| <title>How can I allow only clients who have certificates to access a |
| particular URL, but allow all clients to access the rest of the server?</title> |
| |
| <p>The key to doing this is checking that part of the client certificate |
| matches what you expect. Usually this means checking all or part of the |
| Distinguished Name (DN), to see if it contains some known string. |
| There are two ways to do this, using either <module>mod_auth_basic</module> or |
| <directive module="mod_ssl">SSLRequire</directive>.</p> |
| |
| <p>The <module>mod_auth_basic</module> method is generally required when |
| the certificates are completely arbitrary, or when their DNs have |
| no common fields (usually the organisation, etc.). In this case, |
| you should establish a password database containing <em>all</em> |
| clients allowed, as follows:</p> |
| |
| <highlight language="config"> |
| SSLVerifyClient none |
| SSLCACertificateFile "conf/ssl.crt/ca.crt" |
| SSLCACertificatePath "conf/ssl.crt" |
| |
| <Directory "/usr/local/apache2/htdocs/secure/area"> |
| SSLVerifyClient require |
| SSLVerifyDepth 5 |
| SSLOptions +FakeBasicAuth |
| SSLRequireSSL |
| AuthName "Snake Oil Authentication" |
| AuthType Basic |
| AuthBasicProvider file |
| AuthUserFile "/usr/local/apache2/conf/httpd.passwd" |
| Require valid-user |
| </Directory> |
| </highlight> |
| |
| <p>The password used in this example is the DES encrypted string "password". |
| See the <directive module="mod_ssl">SSLOptions</directive> docs for more |
| information.</p> |
| |
| <example><title>httpd.passwd</title><pre> |
| /C=DE/L=Munich/O=Snake Oil, Ltd./OU=Staff/CN=Foo:xxj31ZMTZzkVA |
| /C=US/L=S.F./O=Snake Oil, Ltd./OU=CA/CN=Bar:xxj31ZMTZzkVA |
| /C=US/L=L.A./O=Snake Oil, Ltd./OU=Dev/CN=Quux:xxj31ZMTZzkVA</pre> |
| </example> |
| |
| <p>When your clients are all part of a common hierarchy, which is encoded |
| into the DN, you can match them more easily using <directive module="mod_ssl" |
| >SSLRequire</directive>, as follows:</p> |
| |
| |
| <highlight language="config"> |
| SSLVerifyClient none |
| SSLCACertificateFile "conf/ssl.crt/ca.crt" |
| SSLCACertificatePath "conf/ssl.crt" |
| |
| <Directory "/usr/local/apache2/htdocs/secure/area"> |
| SSLVerifyClient require |
| SSLVerifyDepth 5 |
| SSLOptions +FakeBasicAuth |
| SSLRequireSSL |
| SSLRequire %{SSL_CLIENT_S_DN_O} eq "Snake Oil, Ltd." \ |
| and %{SSL_CLIENT_S_DN_OU} in {"Staff", "CA", "Dev"} |
| </Directory> |
| </highlight> |
| </section> |
| |
| <section id="intranet"> |
| <title>How can I require HTTPS with strong ciphers, and either basic |
| authentication or client certificates, for access to part of the |
| Intranet website, for clients coming from the Internet? I still want to allow |
| plain HTTP access for clients on the Intranet.</title> |
| |
| <p>These examples presume that clients on the Intranet have IPs in the range |
| 192.168.1.0/24, and that the part of the Intranet website you want to allow |
| internet access to is <code>/usr/local/apache2/htdocs/subarea</code>. |
| This configuration should remain outside of your HTTPS virtual host, so |
| that it applies to both HTTPS and HTTP.</p> |
| |
| <highlight language="config"> |
| SSLCACertificateFile "conf/ssl.crt/company-ca.crt" |
| |
| <Directory "/usr/local/apache2/htdocs"> |
| # Outside the subarea only Intranet access is granted |
| Require ip 192.168.1.0/24 |
| </Directory> |
| |
| <Directory "/usr/local/apache2/htdocs/subarea"> |
| # Inside the subarea any Intranet access is allowed |
| # but from the Internet only HTTPS + Strong-Cipher + Password |
| # or the alternative HTTPS + Strong-Cipher + Client-Certificate |
| |
| # If HTTPS is used, make sure a strong cipher is used. |
| # Additionally allow client certs as alternative to basic auth. |
| SSLVerifyClient optional |
| SSLVerifyDepth 1 |
| SSLOptions +FakeBasicAuth +StrictRequire |
| SSLRequire %{SSL_CIPHER_USEKEYSIZE} >= 128 |
| |
| # Force clients from the Internet to use HTTPS |
| RewriteEngine on |
| RewriteCond "%{REMOTE_ADDR}" "!^192\.168\.1\.[0-9]+$" |
| RewriteCond "%{HTTPS}" "!=on" |
| RewriteRule "." "-" [F] |
| |
| # Allow Network Access and/or Basic Auth |
| Satisfy any |
| |
| # Network Access Control |
| Require ip 192.168.1.0/24 |
| |
| # HTTP Basic Authentication |
| AuthType basic |
| AuthName "Protected Intranet Area" |
| AuthBasicProvider file |
| AuthUserFile "conf/protected.passwd" |
| Require valid-user |
| </Directory> |
| </highlight> |
| </section> |
| </section> |
| <!-- /access control --> |
| |
| <section id="logging"> |
| <title>Logging</title> |
| |
| <p><module>mod_ssl</module> can log extremely verbose debugging information |
| to the error log, when its <directive module="core">LogLevel</directive> is |
| set to the higher trace levels. On the other hand, on a very busy server, |
| level <code>info</code> may already be too much. Remember that you can |
| configure the <directive module="core">LogLevel</directive> per module to |
| suite your needs.</p> |
| </section> |
| |
| </manualpage> |
| |