ssl_howto.xml revision afe2543c218dd49e057064dacd3282b2b84e80c9
53bd0c89aa4743dc41a6394db5a90717c1ca4517Liam O'Reilly<!DOCTYPE manualpage SYSTEM "/style/manualpage.dtd">
e9458b1a7a19a63aa4c179f9ab20f4d50681c168Jens Elkner<?xml-stylesheet type="text/xsl" href="/style/manual.en.xsl"?>
53bd0c89aa4743dc41a6394db5a90717c1ca4517Liam O'Reilly<!-- $LastChangedRevision$ -->
53bd0c89aa4743dc41a6394db5a90717c1ca4517Liam O'Reilly Licensed to the Apache Software Foundation (ASF) under one or more
53bd0c89aa4743dc41a6394db5a90717c1ca4517Liam O'Reilly contributor license agreements. See the NOTICE file distributed with
53bd0c89aa4743dc41a6394db5a90717c1ca4517Liam O'Reilly this work for additional information regarding copyright ownership.
53bd0c89aa4743dc41a6394db5a90717c1ca4517Liam O'Reilly The ASF licenses this file to You under the Apache License, Version 2.0
53bd0c89aa4743dc41a6394db5a90717c1ca4517Liam O'Reilly (the "License"); you may not use this file except in compliance with
33bdce26495121cdbce30331ef90a1969126a840Liam O'Reilly the License. You may obtain a copy of the License at
9aeda2b3ae8ce0b018955521e4ca835a8ba8a27bLiam O'Reilly Unless required by applicable law or agreed to in writing, software
57221209d11b05aa0373cc3892d5df89ba96ebf9Christian Maeder distributed under the License is distributed on an "AS IS" BASIS,
66bc8d6e69cde43f1ccbeb76104cf7b8038acd6cChristian Maeder WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
66bc8d6e69cde43f1ccbeb76104cf7b8038acd6cChristian Maeder See the License for the specific language governing permissions and
e90dc723887d541f809007ae81c9bb73ced9592eChristian Maeder limitations under the License.
66bc8d6e69cde43f1ccbeb76104cf7b8038acd6cChristian Maeder<parentdocument href="./">SSL/TLS</parentdocument>
33bdce26495121cdbce30331ef90a1969126a840Liam O'Reilly <title>SSL/TLS Strong Encryption: How-To</title>
53bd0c89aa4743dc41a6394db5a90717c1ca4517Liam O'Reilly<p>This documented is intended to get you started, and get a few things
7830e8fa7442fb7452af7ecdba102bc297ae367eChristian Maederworking. You are strongly encouraged to read the rest of the SSL
f21c7417bdd1c0282025cba0f5cb0ff5bc5c98eeLiam O'Reillydocumentation, and arrive at a deeper understanding of the material,
648fe1220044aac847acbdfbc4155af5556063ebChristian Maederbefore progressing to the advanced techniques.</p>
7830e8fa7442fb7452af7ecdba102bc297ae367eChristian Maeder<p>Your SSL configuration will need to contain, at minimum, the
33bdce26495121cdbce30331ef90a1969126a840Liam O'Reillyfollowing directives.</p>
2a5b885d9350ec6dd8bc4992ee91d2f68aa592f4Christian Maeder<VirtualHost *:443>
b1f12c962a6fb28a298b36cf6a1dcf2ad788fb58Christian Maeder SSLCertificateFile /path/to/www.example.com.cert
b1f12c962a6fb28a298b36cf6a1dcf2ad788fb58Christian Maeder SSLCertificateKeyFile /path/to/www.example.com.key
1a38107941725211e7c3f051f7a8f5e12199f03acmaeder</VirtualHost>
9e5f4073e948104307d43c3962d624b8416f191fLiam O'Reilly<title>Cipher Suites and Enforcing Strong Security</title>
648fe1220044aac847acbdfbc4155af5556063ebChristian Maeder<li><a href="#onlystrong">How can I create an SSL server which accepts strong encryption only?</a></li>
648fe1220044aac847acbdfbc4155af5556063ebChristian Maeder<li><a href="#strongurl">How can I create an SSL server which accepts all types of ciphers in general, but
648fe1220044aac847acbdfbc4155af5556063ebChristian Maederrequires a strong cipher for access to a particular URL?</a></li>
648fe1220044aac847acbdfbc4155af5556063ebChristian Maeder<title>How can I create an SSL server which accepts strong encryption
648fe1220044aac847acbdfbc4155af5556063ebChristian Maeder <p>The following enables only the strongest ciphers:</p>
ebd23ec61635b0bebf7969d14f65b9d1e39f2b26Liam O'Reilly SSLCipherSuite HIGH:!aNULL:!MD5
9aeda2b3ae8ce0b018955521e4ca835a8ba8a27bLiam O'Reilly <p>While with the following configuration you specify a preference
9aeda2b3ae8ce0b018955521e4ca835a8ba8a27bLiam O'Reilly for specific speed-optimized ciphers (which will be selected by
33bdce26495121cdbce30331ef90a1969126a840Liam O'Reilly mod_ssl, provided that they are supported by the client):</p>
648fe1220044aac847acbdfbc4155af5556063ebChristian MaederSSLCipherSuite RC4-SHA:AES128-SHA:HIGH:!aNULL:!MD5
648fe1220044aac847acbdfbc4155af5556063ebChristian MaederSSLHonorCipherOrder on
33bdce26495121cdbce30331ef90a1969126a840Liam O'Reilly<title>How can I create an SSL server which accepts all types of ciphers
33bdce26495121cdbce30331ef90a1969126a840Liam O'Reillyin general, but requires a strong ciphers for access to a particular
648fe1220044aac847acbdfbc4155af5556063ebChristian Maeder module="mod_ssl">SSLCipherSuite</directive> which restricts
648fe1220044aac847acbdfbc4155af5556063ebChristian Maeder ciphers to the strong variants, isn't the answer here. However,
648fe1220044aac847acbdfbc4155af5556063ebChristian Maeder <module>mod_ssl</module> can be reconfigured within <code>Location</code>
fa373bc327620e08861294716b4454be8d25669fChristian Maeder blocks, to give a per-directory solution, and can automatically force
fa373bc327620e08861294716b4454be8d25669fChristian Maeder a renegotiation of the SSL parameters to meet the new configuration.
fa373bc327620e08861294716b4454be8d25669fChristian Maeder This can be done as follows:</p>
648fe1220044aac847acbdfbc4155af5556063ebChristian Maeder# be liberal in general
648fe1220044aac847acbdfbc4155af5556063ebChristian MaederSSLCipherSuite ALL:!aNULL:RC4+RSA:+HIGH:+MEDIUM:+LOW:+EXP:+eNULL
7857a35e3af533dfbd0f0e18638ebd211e6358a0Christian Maeder# requires strong ciphers
7857a35e3af533dfbd0f0e18638ebd211e6358a0Christian MaederSSLCipherSuite HIGH:!aNULL:!MD5
9aeda2b3ae8ce0b018955521e4ca835a8ba8a27bLiam O'Reilly</Location>
e7cd36335f0f7be9ed5005e71d94c2856b588d62Christian Maeder<!-- /ciphersuites -->
648fe1220044aac847acbdfbc4155af5556063ebChristian Maeder<title>Client Authentication and Access Control</title>
7857a35e3af533dfbd0f0e18638ebd211e6358a0Christian Maeder<li><a href="#allclients">How can I force clients to authenticate using certificates?</a></li>
33bdce26495121cdbce30331ef90a1969126a840Liam O'Reilly<li><a href="#arbitraryclients">How can I force clients to authenticate using certificates for a
33bdce26495121cdbce30331ef90a1969126a840Liam O'Reilly particular URL, but still allow arbitrary clients to access the rest of the server?</a></li>
648fe1220044aac847acbdfbc4155af5556063ebChristian Maeder<li><a href="#certauthenticate">How can I allow only clients who have certificates to access a
648fe1220044aac847acbdfbc4155af5556063ebChristian Maeder particular URL, but allow all clients to access the rest of the server?</a></li>
648fe1220044aac847acbdfbc4155af5556063ebChristian Maeder<li><a href="#intranet">How can I require HTTPS with strong ciphers, and either
c0833539c8cf577dd3f2497792fbdd818442744cChristian Maederbasic authentication or client certificates, for access to part of the
d5833d2ee7bafcbf2fdd2bdfd9a728c769b100c7Christian MaederIntranet website, for clients coming from the Internet?</a></li>
648fe1220044aac847acbdfbc4155af5556063ebChristian Maeder<title>How can I force clients to authenticate using certificates?</title>
33bdce26495121cdbce30331ef90a1969126a840Liam O'Reilly <p>When you know all of your users (eg, as is often the case on a corporate
eb48217dfa67ddb87b8fbd846de293d0636bd578Christian Maeder Intranet), you can require plain certificate authentication. All you
c0833539c8cf577dd3f2497792fbdd818442744cChristian Maeder need to do is to create client certificates signed by your own CA
33bdce26495121cdbce30331ef90a1969126a840Liam O'Reilly certificate (<code>ca.crt</code>) and then verify the clients against this
7830e8fa7442fb7452af7ecdba102bc297ae367eChristian Maeder certificate.</p>
7830e8fa7442fb7452af7ecdba102bc297ae367eChristian Maeder# require a client certificate which has to be directly
33bdce26495121cdbce30331ef90a1969126a840Liam O'Reilly# signed by our CA certificate in ca.crt
eb48217dfa67ddb87b8fbd846de293d0636bd578Christian MaederSSLVerifyClient require
eb48217dfa67ddb87b8fbd846de293d0636bd578Christian MaederSSLVerifyDepth 1
648fe1220044aac847acbdfbc4155af5556063ebChristian Maeder<title>How can I force clients to authenticate using certificates for a
4314e26a12954cb1c9be4dea10aa8103edac5bbbChristian Maeder particular URL, but still allow arbitrary clients to access the rest of the server?</title>
ebd23ec61635b0bebf7969d14f65b9d1e39f2b26Liam O'Reilly <p>To force clients to authenticate using certificates for a particular URL,
648fe1220044aac847acbdfbc4155af5556063ebChristian Maeder you can use the per-directory reconfiguration features of
648fe1220044aac847acbdfbc4155af5556063ebChristian MaederSSLVerifyClient none
648fe1220044aac847acbdfbc4155af5556063ebChristian MaederSSLVerifyClient require
33bdce26495121cdbce30331ef90a1969126a840Liam O'ReillySSLVerifyDepth 1
d5833d2ee7bafcbf2fdd2bdfd9a728c769b100c7Christian Maeder</Location>
e0f1794e365dd347e97b37d7d22b2fce27296fa1Christian Maeder<title>How can I allow only clients who have certificates to access a
648fe1220044aac847acbdfbc4155af5556063ebChristian Maeder particular URL, but allow all clients to access the rest of the server?</title>
2a5b885d9350ec6dd8bc4992ee91d2f68aa592f4Christian Maeder <p>The key to doing this is checking that part of the client certificate
7857a35e3af533dfbd0f0e18638ebd211e6358a0Christian Maeder matches what you expect. Usually this means checking all or part of the
7857a35e3af533dfbd0f0e18638ebd211e6358a0Christian Maeder Distinguished Name (DN), to see if it contains some known string.
2a5b885d9350ec6dd8bc4992ee91d2f68aa592f4Christian Maeder There are two ways to do this, using either <module>mod_auth_basic</module> or
648fe1220044aac847acbdfbc4155af5556063ebChristian Maeder <directive module="mod_ssl">SSLRequire</directive>.</p>
7857a35e3af533dfbd0f0e18638ebd211e6358a0Christian Maeder <p>The <module>mod_auth_basic</module> method is generally required when
7857a35e3af533dfbd0f0e18638ebd211e6358a0Christian Maeder the certificates are completely arbitrary, or when their DNs have
7857a35e3af533dfbd0f0e18638ebd211e6358a0Christian Maeder no common fields (usually the organisation, etc.). In this case,
7830e8fa7442fb7452af7ecdba102bc297ae367eChristian Maeder you should establish a password database containing <em>all</em>
648fe1220044aac847acbdfbc4155af5556063ebChristian Maeder clients allowed, as follows:</p>
648fe1220044aac847acbdfbc4155af5556063ebChristian MaederSSLVerifyClient none
648fe1220044aac847acbdfbc4155af5556063ebChristian Maeder<Directory /usr/local/apache2/htdocs/secure/area>
648fe1220044aac847acbdfbc4155af5556063ebChristian Maeder SSLVerifyClient require
bcd914850de931848b86d7728192a149f9c0108bChristian Maeder SSLVerifyDepth 5
33bdce26495121cdbce30331ef90a1969126a840Liam O'Reilly SSLOptions +FakeBasicAuth
bc350328e6ac2d9074317e222b4207a6aa49afeaLiam O'Reilly SSLRequireSSL
bc350328e6ac2d9074317e222b4207a6aa49afeaLiam O'Reilly AuthName "Snake Oil Authentication"
580f1724640a78be687e79d0ec95dd2665e77e91Liam O'Reilly AuthType Basic
b1f12c962a6fb28a298b36cf6a1dcf2ad788fb58Christian Maeder AuthBasicProvider file
b1f12c962a6fb28a298b36cf6a1dcf2ad788fb58Christian Maeder AuthUserFile /usr/local/apache2/conf/httpd.passwd
b1f12c962a6fb28a298b36cf6a1dcf2ad788fb58Christian Maeder Require valid-user
b1f12c962a6fb28a298b36cf6a1dcf2ad788fb58Christian Maeder</Directory>
f21c7417bdd1c0282025cba0f5cb0ff5bc5c98eeLiam O'Reilly <p>The password used in this example is the DES encrypted string "password".
f21c7417bdd1c0282025cba0f5cb0ff5bc5c98eeLiam O'Reilly See the <directive module="mod_ssl">SSLOptions</directive> docs for more
3d3889e0cefcdce9b3f43c53aaa201943ac2e895Jonathan von Schroeder information.</p>
3d3889e0cefcdce9b3f43c53aaa201943ac2e895Jonathan von Schroeder <example><title>httpd.passwd</title><pre>
b1f12c962a6fb28a298b36cf6a1dcf2ad788fb58Christian Maeder/C=DE/L=Munich/O=Snake Oil, Ltd./OU=Staff/CN=Foo:xxj31ZMTZzkVA
3d3889e0cefcdce9b3f43c53aaa201943ac2e895Jonathan von Schroeder/C=US/L=S.F./O=Snake Oil, Ltd./OU=CA/CN=Bar:xxj31ZMTZzkVA
3d3889e0cefcdce9b3f43c53aaa201943ac2e895Jonathan von Schroeder/C=US/L=L.A./O=Snake Oil, Ltd./OU=Dev/CN=Quux:xxj31ZMTZzkVA</pre>
d381ab99d6e2e56e09030577d65d9a118f246d35Christian Maeder <p>When your clients are all part of a common hierarchy, which is encoded
d381ab99d6e2e56e09030577d65d9a118f246d35Christian Maeder into the DN, you can match them more easily using <directive module="mod_ssl"
b1f12c962a6fb28a298b36cf6a1dcf2ad788fb58Christian MaederSSLVerifyClient none
bc350328e6ac2d9074317e222b4207a6aa49afeaLiam O'Reilly<Directory /usr/local/apache2/htdocs/secure/area>
bc350328e6ac2d9074317e222b4207a6aa49afeaLiam O'Reilly SSLVerifyClient require
bc350328e6ac2d9074317e222b4207a6aa49afeaLiam O'Reilly SSLVerifyDepth 5
580f1724640a78be687e79d0ec95dd2665e77e91Liam O'Reilly SSLOptions +FakeBasicAuth
b1f12c962a6fb28a298b36cf6a1dcf2ad788fb58Christian Maeder SSLRequireSSL
b1f12c962a6fb28a298b36cf6a1dcf2ad788fb58Christian Maeder SSLRequire %{SSL_CLIENT_S_DN_O} eq "Snake Oil, Ltd." \
b1f12c962a6fb28a298b36cf6a1dcf2ad788fb58Christian Maeder and %{SSL_CLIENT_S_DN_OU} in {"Staff", "CA", "Dev"}
b1f12c962a6fb28a298b36cf6a1dcf2ad788fb58Christian Maeder</Directory>
7d96b1ef2b8597330aedee6713615ec15508edcfLiam O'Reilly<title>How can I require HTTPS with strong ciphers, and either basic
7d96b1ef2b8597330aedee6713615ec15508edcfLiam O'Reillyauthentication or client certificates, for access to part of the
bc350328e6ac2d9074317e222b4207a6aa49afeaLiam O'ReillyIntranet website, for clients coming from the Internet? I still want to allow
bc350328e6ac2d9074317e222b4207a6aa49afeaLiam O'Reillyplain HTTP access for clients on the Intranet.</title>
bc350328e6ac2d9074317e222b4207a6aa49afeaLiam O'Reilly <p>These examples presume that clients on the Intranet have IPs in the range
f19dc06364e8d6ea36f7c170e1f7a0677de63184Liam O'Reilly 192.168.1.0/24, and that the part of the Intranet website you want to allow
f19dc06364e8d6ea36f7c170e1f7a0677de63184Liam O'Reilly internet access to is <code>/usr/local/apache2/htdocs/subarea</code>.
f19dc06364e8d6ea36f7c170e1f7a0677de63184Liam O'Reilly This configuration should remain outside of your HTTPS virtual host, so
bc350328e6ac2d9074317e222b4207a6aa49afeaLiam O'Reilly that it applies to both HTTPS and HTTP.</p>
f19dc06364e8d6ea36f7c170e1f7a0677de63184Liam O'ReillySSLCACertificateFile conf/ssl.crt/company-ca.crt
3d3889e0cefcdce9b3f43c53aaa201943ac2e895Jonathan von Schroeder # Outside the subarea only Intranet access is granted
ee48a7a67da604356b665e51aa7545536a09b737Christian Maeder</Directory>
ee48a7a67da604356b665e51aa7545536a09b737Christian Maeder<Directory /usr/local/apache2/htdocs/subarea>
ee48a7a67da604356b665e51aa7545536a09b737Christian Maeder # Inside the subarea any Intranet access is allowed
ee48a7a67da604356b665e51aa7545536a09b737Christian Maeder # but from the Internet only HTTPS + Strong-Cipher + Password
dc403ff45531bc75a7544b8b5fc52a5217a1a54aChristian Maeder # or the alternative HTTPS + Strong-Cipher + Client-Certificate
45e2bc90dd11147156ddd7f9651ce8b2ec00f2a1Christian Maeder # If HTTPS is used, make sure a strong cipher is used.
45e2bc90dd11147156ddd7f9651ce8b2ec00f2a1Christian Maeder # Additionally allow client certs as alternative to basic auth.
ee48a7a67da604356b665e51aa7545536a09b737Christian Maeder SSLVerifyClient optional
b1f12c962a6fb28a298b36cf6a1dcf2ad788fb58Christian Maeder SSLVerifyDepth 1
b1f12c962a6fb28a298b36cf6a1dcf2ad788fb58Christian Maeder SSLOptions +FakeBasicAuth +StrictRequire
b1f12c962a6fb28a298b36cf6a1dcf2ad788fb58Christian Maeder SSLRequire %{SSL_CIPHER_USEKEYSIZE} >= 128
2a5b885d9350ec6dd8bc4992ee91d2f68aa592f4Christian Maeder # Force clients from the Internet to use HTTPS
fa373bc327620e08861294716b4454be8d25669fChristian Maeder RewriteEngine on
fa373bc327620e08861294716b4454be8d25669fChristian Maeder RewriteCond %{REMOTE_ADDR} !^192\.168\.1\.[0-9]+$
fa373bc327620e08861294716b4454be8d25669fChristian Maeder RewriteCond %{HTTPS} !=on
fa373bc327620e08861294716b4454be8d25669fChristian Maeder RewriteRule . - [F]
fa373bc327620e08861294716b4454be8d25669fChristian Maeder # Network Access Control