ssl_howto.xml revision 5d11895e12fd8f00d96b3c174ff054c843ae3d79
2dd3faebcd3cfd00efda38ffd2585d675e696b12Stephen Gallagher<!DOCTYPE manualpage SYSTEM "/style/manualpage.dtd">
2dd3faebcd3cfd00efda38ffd2585d675e696b12Stephen Gallagher<?xml-stylesheet type="text/xsl" href="/style/manual.en.xsl"?>
2dd3faebcd3cfd00efda38ffd2585d675e696b12Stephen Gallagher<!-- $LastChangedRevision$ -->
2dd3faebcd3cfd00efda38ffd2585d675e696b12Stephen Gallagher Licensed to the Apache Software Foundation (ASF) under one or more
2dd3faebcd3cfd00efda38ffd2585d675e696b12Stephen Gallagher contributor license agreements. See the NOTICE file distributed with
2dd3faebcd3cfd00efda38ffd2585d675e696b12Stephen Gallagher this work for additional information regarding copyright ownership.
2dd3faebcd3cfd00efda38ffd2585d675e696b12Stephen Gallagher The ASF licenses this file to You under the Apache License, Version 2.0
2dd3faebcd3cfd00efda38ffd2585d675e696b12Stephen Gallagher (the "License"); you may not use this file except in compliance with
2dd3faebcd3cfd00efda38ffd2585d675e696b12Stephen Gallagher the License. You may obtain a copy of the License at
2dd3faebcd3cfd00efda38ffd2585d675e696b12Stephen Gallagher http://www.apache.org/licenses/LICENSE-2.0
2dd3faebcd3cfd00efda38ffd2585d675e696b12Stephen Gallagher Unless required by applicable law or agreed to in writing, software
2dd3faebcd3cfd00efda38ffd2585d675e696b12Stephen Gallagher distributed under the License is distributed on an "AS IS" BASIS,
2dd3faebcd3cfd00efda38ffd2585d675e696b12Stephen Gallagher WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
2dd3faebcd3cfd00efda38ffd2585d675e696b12Stephen Gallagher See the License for the specific language governing permissions and
2dd3faebcd3cfd00efda38ffd2585d675e696b12Stephen Gallagher limitations under the License.
2dd3faebcd3cfd00efda38ffd2585d675e696b12Stephen Gallagher<parentdocument href="./">SSL/TLS</parentdocument>
2dd3faebcd3cfd00efda38ffd2585d675e696b12Stephen Gallagher <title>SSL/TLS Strong Encryption: How-To</title>
2dd3faebcd3cfd00efda38ffd2585d675e696b12Stephen Gallagher<p>The solution to this problem is trivial
2dd3faebcd3cfd00efda38ffd2585d675e696b12Stephen Gallagherand is left as an exercise for the reader.</p>
2dd3faebcd3cfd00efda38ffd2585d675e696b12Stephen Gallagher<p class="cite">-- <cite>Standard textbook cookie</cite></p>
2dd3faebcd3cfd00efda38ffd2585d675e696b12Stephen Gallagher<p>How to solve particular security problems for an SSL-aware
2dd3faebcd3cfd00efda38ffd2585d675e696b12Stephen Gallagherwebserver is not always obvious because of the interactions between SSL,
03abdaa21ecf562b714f204ca42379ff08626f75Simo SorceHTTP and Apache's way of processing requests. This chapter gives
2dd3faebcd3cfd00efda38ffd2585d675e696b12Stephen Gallagherinstructions on how to solve some typical situations. Treat it as a first
2dd3faebcd3cfd00efda38ffd2585d675e696b12Stephen Gallagherstep to find out the final solution, but always try to understand the
2dd3faebcd3cfd00efda38ffd2585d675e696b12Stephen Gallagherstuff before you use it. Nothing is worse than using a security solution
2dd3faebcd3cfd00efda38ffd2585d675e696b12Stephen Gallagherwithout knowing its restrictions and how it interacts with other systems.</p>
03abdaa21ecf562b714f204ca42379ff08626f75Simo Sorce<p>Your SSL configuration will need to contain, at a minumum, the
2dd3faebcd3cfd00efda38ffd2585d675e696b12Stephen Gallagherfollowing directives.</p>
2dd3faebcd3cfd00efda38ffd2585d675e696b12Stephen Gallagher Listen 443<br />
03abdaa21ecf562b714f204ca42379ff08626f75Simo Sorce <VirtualHost _default_:443><br />
2dd3faebcd3cfd00efda38ffd2585d675e696b12Stephen Gallagher SSLEngine on<br />
03abdaa21ecf562b714f204ca42379ff08626f75Simo Sorce SSLCertificateFile /path/to/www.comain.com.cert<br />
2dd3faebcd3cfd00efda38ffd2585d675e696b12Stephen Gallagher SSLCertificateKeyFile /path/to/www.domain.com.key<br />
2dd3faebcd3cfd00efda38ffd2585d675e696b12Stephen Gallagher </VirtualHost>
2dd3faebcd3cfd00efda38ffd2585d675e696b12Stephen Gallagher<title>Cipher Suites and Enforcing Strong Security</title>
2dd3faebcd3cfd00efda38ffd2585d675e696b12Stephen Gallagher<li><a href="#realssl">How can I create a real SSLv2-only server?</a></li>
8e5549e453558d4bebdec333a93e215d5d6ffaecSimo Sorce<li><a href="#onlystrong">How can I create an SSL server which accepts strong encryption only?</a></li>
2dd3faebcd3cfd00efda38ffd2585d675e696b12Stephen Gallagher<li><a href="#upgradeenc">How can I create an SSL server which accepts strong encryption only, but allows
2dd3faebcd3cfd00efda38ffd2585d675e696b12Stephen Gallagherexport browsers to upgrade to stronger encryption?</a></li>
2dd3faebcd3cfd00efda38ffd2585d675e696b12Stephen Gallagher<li><a href="#strongurl">How can I create an SSL server which accepts all types of ciphers in general, but
2dd3faebcd3cfd00efda38ffd2585d675e696b12Stephen Gallagherrequires a strong cipher for access to a particular URL?</a></li>
2dd3faebcd3cfd00efda38ffd2585d675e696b12Stephen Gallagher<title>How can I create an SSL server which accepts strong encryption
2dd3faebcd3cfd00efda38ffd2585d675e696b12Stephen Gallagher <p>The following enables only the strongest ciphers:</p>
2dd3faebcd3cfd00efda38ffd2585d675e696b12Stephen Gallagher SSLProtocol all -SSLv3<br />
2dd3faebcd3cfd00efda38ffd2585d675e696b12Stephen Gallagher SSLCipherSuite HIGH:!ADH:!EXP:!MD5:!NULL<br />
2dd3faebcd3cfd00efda38ffd2585d675e696b12Stephen Gallagher <p>While with the following configuration you enable two ciphers
2dd3faebcd3cfd00efda38ffd2585d675e696b12Stephen Gallagher which are resonably secure, and fast:</p>
8e5549e453558d4bebdec333a93e215d5d6ffaecSimo Sorce SSLProtocol all -SSLv3<br />
2dd3faebcd3cfd00efda38ffd2585d675e696b12Stephen Gallagher SSLCipherSuite RC4-SHA:AES128-SHA:HIGH:!ADH:!EXP:!MD5:!NULL<br />
2dd3faebcd3cfd00efda38ffd2585d675e696b12Stephen Gallagher SSLHonorCipherOrder on
2dd3faebcd3cfd00efda38ffd2585d675e696b12Stephen Gallagher <p>This strongly reflects the default value of <directive module="mod_ssl"
2dd3faebcd3cfd00efda38ffd2585d675e696b12Stephen Gallagher >SSLCipherSuite</directive> and is the recommanded way to configure it.</p>
2dd3faebcd3cfd00efda38ffd2585d675e696b12Stephen Gallagher<title>How can I create an SSL server which accepts all types of ciphers
2dd3faebcd3cfd00efda38ffd2585d675e696b12Stephen Gallagherin general, but requires a strong ciphers for access to a particular
2dd3faebcd3cfd00efda38ffd2585d675e696b12Stephen Gallagher module="mod_ssl">SSLCipherSuite</directive> which restricts
2dd3faebcd3cfd00efda38ffd2585d675e696b12Stephen Gallagher ciphers to the strong variants, isn't the answer here. However,
a3c8390d19593b1e5277d95bfb4ab206d4785150Nikolai Kondrashov <module>mod_ssl</module> can be reconfigured within <code>Location</code>
2dd3faebcd3cfd00efda38ffd2585d675e696b12Stephen Gallagher blocks, to give a per-directory solution, and can automatically force
2dd3faebcd3cfd00efda38ffd2585d675e696b12Stephen Gallagher a renegotiation of the SSL parameters to meet the new configuration.
2dd3faebcd3cfd00efda38ffd2585d675e696b12Stephen Gallagher This can be done as follows:</p>
2dd3faebcd3cfd00efda38ffd2585d675e696b12Stephen Gallagher # be liberal in general<br />
a3c8390d19593b1e5277d95bfb4ab206d4785150Nikolai Kondrashov SSLCipherSuite ALL:!ADH:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP:+eNULL<br />
2dd3faebcd3cfd00efda38ffd2585d675e696b12Stephen Gallagher # but https://hostname/strong/area/ and below<br />
2dd3faebcd3cfd00efda38ffd2585d675e696b12Stephen Gallagher # requires strong ciphers<br />
2dd3faebcd3cfd00efda38ffd2585d675e696b12Stephen Gallagher SSLCipherSuite HIGH:!ADH:!EXP:!MD5:!NULL<br />
2dd3faebcd3cfd00efda38ffd2585d675e696b12Stephen Gallagher </Location>
2dd3faebcd3cfd00efda38ffd2585d675e696b12Stephen Gallagher<!-- /ciphersuites -->
2dd3faebcd3cfd00efda38ffd2585d675e696b12Stephen Gallagher<title>Client Authentication and Access Control</title>
2dd3faebcd3cfd00efda38ffd2585d675e696b12Stephen Gallagher<li><a href="#allclients">How can I force clients to authenticate using certificates?</a></li>
2dd3faebcd3cfd00efda38ffd2585d675e696b12Stephen Gallagher<li><a href="#arbitraryclients">How can I force clients to authenticate using certificates for a
2dd3faebcd3cfd00efda38ffd2585d675e696b12Stephen Gallagher particular URL, but still allow arbitrary clients to access the rest of the server?</a></li>
2dd3faebcd3cfd00efda38ffd2585d675e696b12Stephen Gallagher<li><a href="#certauthenticate">How can I allow only clients who have certificates to access a
2dd3faebcd3cfd00efda38ffd2585d675e696b12Stephen Gallagher particular URL, but allow all clients to access the rest of the server?</a></li>
2dd3faebcd3cfd00efda38ffd2585d675e696b12Stephen Gallagher<li><a href="#intranet">How can I require HTTPS with strong ciphers, and either
2dd3faebcd3cfd00efda38ffd2585d675e696b12Stephen Gallagherbasic authentication or client certificates, for access to part of the
2dd3faebcd3cfd00efda38ffd2585d675e696b12Stephen GallagherIntranet website, for clients coming from the Internet?</a></li>
2dd3faebcd3cfd00efda38ffd2585d675e696b12Stephen Gallagher<title>How can I force clients to authenticate using certificates?</title>
2dd3faebcd3cfd00efda38ffd2585d675e696b12Stephen Gallagher <p>When you know all of your users (eg, as is often the case on a corporate
2dd3faebcd3cfd00efda38ffd2585d675e696b12Stephen Gallagher Intranet), you can require plain certificate authentication. All you
cbaba2f47da96c4191971bce86f03afb3f88864aSimo Sorce need to do is to create client certificates signed by your own CA
2dd3faebcd3cfd00efda38ffd2585d675e696b12Stephen Gallagher certificate (<code>ca.crt</code>) and then verify the clients against this
2dd3faebcd3cfd00efda38ffd2585d675e696b12Stephen Gallagher certificate.</p>
2dd3faebcd3cfd00efda38ffd2585d675e696b12Stephen Gallagher # require a client certificate which has to be directly<br />
2dd3faebcd3cfd00efda38ffd2585d675e696b12Stephen Gallagher # signed by our CA certificate in ca.crt<br />
2dd3faebcd3cfd00efda38ffd2585d675e696b12Stephen Gallagher SSLVerifyClient require<br />
2dd3faebcd3cfd00efda38ffd2585d675e696b12Stephen Gallagher SSLVerifyDepth 1<br />
2dd3faebcd3cfd00efda38ffd2585d675e696b12Stephen Gallagher<title>How can I force clients to authenticate using certificates for a
2dd3faebcd3cfd00efda38ffd2585d675e696b12Stephen Gallagher particular URL, but still allow arbitrary clients to access the rest of the server?</title>
2dd3faebcd3cfd00efda38ffd2585d675e696b12Stephen Gallagher <p>To force clients to authenticate using certificates for a particular URL,
2dd3faebcd3cfd00efda38ffd2585d675e696b12Stephen Gallagher you can use the per-directory reconfiguration features of
2dd3faebcd3cfd00efda38ffd2585d675e696b12Stephen Gallagher SSLVerifyClient none<br />
2dd3faebcd3cfd00efda38ffd2585d675e696b12Stephen Gallagher SSLCACertificateFile conf/ssl.crt/ca.crt<br />
2dd3faebcd3cfd00efda38ffd2585d675e696b12Stephen Gallagher SSLVerifyClient require<br />
2dd3faebcd3cfd00efda38ffd2585d675e696b12Stephen Gallagher SSLVerifyDepth 1<br />
2dd3faebcd3cfd00efda38ffd2585d675e696b12Stephen Gallagher </Location><br />
2dd3faebcd3cfd00efda38ffd2585d675e696b12Stephen Gallagher<title>How can I allow only clients who have certificates to access a
a3c8390d19593b1e5277d95bfb4ab206d4785150Nikolai Kondrashov particular URL, but allow all clients to access the rest of the server?</title>
2dd3faebcd3cfd00efda38ffd2585d675e696b12Stephen Gallagher <p>The key to doing this is checking that part of the client certificate
2dd3faebcd3cfd00efda38ffd2585d675e696b12Stephen Gallagher matches what you expect. Usually this means checking all or part of the
2dd3faebcd3cfd00efda38ffd2585d675e696b12Stephen Gallagher Distinguished Name (DN), to see if it contains some known string.
2dd3faebcd3cfd00efda38ffd2585d675e696b12Stephen Gallagher There are two ways to do this, using either <module>mod_auth_basic</module> or
2dd3faebcd3cfd00efda38ffd2585d675e696b12Stephen Gallagher <directive module="mod_ssl">SSLRequire</directive>.</p>
2dd3faebcd3cfd00efda38ffd2585d675e696b12Stephen Gallagher <p>The <module>mod_auth_basic</module> method is generally required when
2dd3faebcd3cfd00efda38ffd2585d675e696b12Stephen Gallagher the certificates are completely arbitrary, or when their DNs have
2dd3faebcd3cfd00efda38ffd2585d675e696b12Stephen Gallagher no common fields (usually the organisation, etc.). In this case,
2dd3faebcd3cfd00efda38ffd2585d675e696b12Stephen Gallagher you should establish a password database containing <em>all</em>
2dd3faebcd3cfd00efda38ffd2585d675e696b12Stephen Gallagher clients allowed, as follows:</p>
2dd3faebcd3cfd00efda38ffd2585d675e696b12Stephen GallagherSSLVerifyClient none
a3c8390d19593b1e5277d95bfb4ab206d4785150Nikolai Kondrashov<Directory /usr/local/apache2/htdocs/secure/area>
2dd3faebcd3cfd00efda38ffd2585d675e696b12Stephen GallagherSSLVerifyClient require
2dd3faebcd3cfd00efda38ffd2585d675e696b12Stephen GallagherSSLVerifyDepth 5
2dd3faebcd3cfd00efda38ffd2585d675e696b12Stephen GallagherSSLOptions +FakeBasicAuth
2dd3faebcd3cfd00efda38ffd2585d675e696b12Stephen GallagherAuthName "Snake Oil Authentication"
2dd3faebcd3cfd00efda38ffd2585d675e696b12Stephen GallagherAuthBasicProvider file
2dd3faebcd3cfd00efda38ffd2585d675e696b12Stephen GallagherAuthUserFile /usr/local/apache2/conf/httpd.passwd
2dd3faebcd3cfd00efda38ffd2585d675e696b12Stephen GallagherRequire valid-user
a3c8390d19593b1e5277d95bfb4ab206d4785150Nikolai Kondrashov</Directory></pre>
2dd3faebcd3cfd00efda38ffd2585d675e696b12Stephen Gallagher <p>The password used in this example is the DES encrypted string "password".
2dd3faebcd3cfd00efda38ffd2585d675e696b12Stephen Gallagher See the <directive module="mod_ssl">SSLOptions</directive> docs for more
2dd3faebcd3cfd00efda38ffd2585d675e696b12Stephen Gallagher information.</p>
2dd3faebcd3cfd00efda38ffd2585d675e696b12Stephen Gallagher/C=DE/L=Munich/O=Snake Oil, Ltd./OU=Staff/CN=Foo:xxj31ZMTZzkVA
2dd3faebcd3cfd00efda38ffd2585d675e696b12Stephen Gallagher/C=US/L=S.F./O=Snake Oil, Ltd./OU=CA/CN=Bar:xxj31ZMTZzkVA
2dd3faebcd3cfd00efda38ffd2585d675e696b12Stephen Gallagher/C=US/L=L.A./O=Snake Oil, Ltd./OU=Dev/CN=Quux:xxj31ZMTZzkVA</pre>
2dd3faebcd3cfd00efda38ffd2585d675e696b12Stephen Gallagher <p>When your clients are all part of a common hierarchy, which is encoded
2dd3faebcd3cfd00efda38ffd2585d675e696b12Stephen Gallagher into the DN, you can match them more easily using <directive module="mod_ssl"
2dd3faebcd3cfd00efda38ffd2585d675e696b12Stephen GallagherSSLVerifyClient none
2dd3faebcd3cfd00efda38ffd2585d675e696b12Stephen Gallagher<Directory /usr/local/apache2/htdocs/secure/area>
2dd3faebcd3cfd00efda38ffd2585d675e696b12Stephen Gallagher SSLVerifyClient require
2dd3faebcd3cfd00efda38ffd2585d675e696b12Stephen Gallagher SSLVerifyDepth 5
2dd3faebcd3cfd00efda38ffd2585d675e696b12Stephen Gallagher SSLOptions +FakeBasicAuth
2dd3faebcd3cfd00efda38ffd2585d675e696b12Stephen Gallagher SSLRequire %{SSL_CLIENT_S_DN_O} eq "Snake Oil, Ltd." \
2dd3faebcd3cfd00efda38ffd2585d675e696b12Stephen Gallagher and %{SSL_CLIENT_S_DN_OU} in {"Staff", "CA", "Dev"}
2dd3faebcd3cfd00efda38ffd2585d675e696b12Stephen Gallagher</Directory></pre>
2dd3faebcd3cfd00efda38ffd2585d675e696b12Stephen Gallagher<title>How can I require HTTPS with strong ciphers, and either basic
2dd3faebcd3cfd00efda38ffd2585d675e696b12Stephen Gallagherauthentication or client certificates, for access to part of the
2dd3faebcd3cfd00efda38ffd2585d675e696b12Stephen GallagherIntranet website, for clients coming from the Internet? I still want to allow
2dd3faebcd3cfd00efda38ffd2585d675e696b12Stephen Gallagherplain HTTP access for clients on the Intranet.</title>
2dd3faebcd3cfd00efda38ffd2585d675e696b12Stephen Gallagher <p>These examples presume that clients on the Intranet have IPs in the range
1a7529bf5f867b43e0475f7f9ac0cd8671fb16f1Pavel Březina 192.168.1.0/24, and that the part of the Intranet website you want to allow
1a7529bf5f867b43e0475f7f9ac0cd8671fb16f1Pavel Březina internet access to is <code>/usr/local/apache2/htdocs/subarea</code>.
47db32cd9cb2147bb40909352569d7c8274365dbPavel Březina This configuration should remain outside of your HTTPS virtual host, so
1a7529bf5f867b43e0475f7f9ac0cd8671fb16f1Pavel Březina that it applies to both HTTPS and HTTP.</p>
2dd3faebcd3cfd00efda38ffd2585d675e696b12Stephen GallagherSSLCACertificateFile conf/ssl.crt/company-ca.crt
2dd3faebcd3cfd00efda38ffd2585d675e696b12Stephen Gallagher<Directory /usr/local/apache2/htdocs>
2dd3faebcd3cfd00efda38ffd2585d675e696b12Stephen Gallagher# Outside the subarea only Intranet access is granted
2dd3faebcd3cfd00efda38ffd2585d675e696b12Stephen GallagherOrder deny,allow
2dd3faebcd3cfd00efda38ffd2585d675e696b12Stephen Gallagher</Directory>
2dd3faebcd3cfd00efda38ffd2585d675e696b12Stephen Gallagher<Directory /usr/local/apache2/htdocs/subarea>
a3c8390d19593b1e5277d95bfb4ab206d4785150Nikolai Kondrashov# Inside the subarea any Intranet access is allowed
2dd3faebcd3cfd00efda38ffd2585d675e696b12Stephen Gallagher# but from the Internet only HTTPS + Strong-Cipher + Password
2dd3faebcd3cfd00efda38ffd2585d675e696b12Stephen Gallagher# or the alternative HTTPS + Strong-Cipher + Client-Certificate
2dd3faebcd3cfd00efda38ffd2585d675e696b12Stephen Gallagher# If HTTPS is used, make sure a strong cipher is used.
2dd3faebcd3cfd00efda38ffd2585d675e696b12Stephen Gallagher# Additionally allow client certs as alternative to basic auth.
2dd3faebcd3cfd00efda38ffd2585d675e696b12Stephen GallagherSSLVerifyClient optional
2dd3faebcd3cfd00efda38ffd2585d675e696b12Stephen GallagherSSLVerifyDepth 1
2dd3faebcd3cfd00efda38ffd2585d675e696b12Stephen GallagherSSLOptions +FakeBasicAuth +StrictRequire
2dd3faebcd3cfd00efda38ffd2585d675e696b12Stephen GallagherSSLRequire %{SSL_CIPHER_USEKEYSIZE} >= 128
a3c8390d19593b1e5277d95bfb4ab206d4785150Nikolai Kondrashov# Force clients from the Internet to use HTTPS
2dd3faebcd3cfd00efda38ffd2585d675e696b12Stephen GallagherRewriteEngine on
2dd3faebcd3cfd00efda38ffd2585d675e696b12Stephen GallagherRewriteCond %{REMOTE_ADDR} !^192\.168\.1\.[0-9]+$
2dd3faebcd3cfd00efda38ffd2585d675e696b12Stephen GallagherRewriteCond %{HTTPS} !=on
2dd3faebcd3cfd00efda38ffd2585d675e696b12Stephen GallagherRewriteRule .* - [F]
2dd3faebcd3cfd00efda38ffd2585d675e696b12Stephen Gallagher# Network Access Control
2dd3faebcd3cfd00efda38ffd2585d675e696b12Stephen GallagherOrder deny,allow
a3c8390d19593b1e5277d95bfb4ab206d4785150Nikolai Kondrashov# HTTP Basic Authentication
2dd3faebcd3cfd00efda38ffd2585d675e696b12Stephen GallagherAuthName "Protected Intranet Area"
2dd3faebcd3cfd00efda38ffd2585d675e696b12Stephen GallagherAuthBasicProvider file
2dd3faebcd3cfd00efda38ffd2585d675e696b12Stephen GallagherRequire valid-user
2dd3faebcd3cfd00efda38ffd2585d675e696b12Stephen Gallagher</Directory></pre>
2dd3faebcd3cfd00efda38ffd2585d675e696b12Stephen Gallagher<!-- /access control -->
2dd3faebcd3cfd00efda38ffd2585d675e696b12Stephen Gallagher <p><module>mod_ssl</module> can log extremely verbose debugging information
2dd3faebcd3cfd00efda38ffd2585d675e696b12Stephen Gallagher to the error log, when its <directive module="core">LogLevel</directive> is
2dd3faebcd3cfd00efda38ffd2585d675e696b12Stephen Gallagher set to the higher trace levels. On the other hand, on a very busy server,
2dd3faebcd3cfd00efda38ffd2585d675e696b12Stephen Gallagher level <code>info</code> may already be too much. Remember that you can
2dd3faebcd3cfd00efda38ffd2585d675e696b12Stephen Gallagher configure the <directive module="core">LogLevel</directive> per module to
2dd3faebcd3cfd00efda38ffd2585d675e696b12Stephen Gallagher suite your needs.</p>