You are viewing a plain text version of this content. The canonical link for it is here.
Posted to cvs@httpd.apache.org by no...@apache.org on 2006/01/15 15:39:00 UTC
svn commit: r369204 -
/httpd/httpd/branches/2.2.x/docs/manual/ssl/ssl_howto.xml
Author: noirin
Date: Sun Jan 15 06:38:56 2006
New Revision: 369204
URL: http://svn.apache.org/viewcvs?rev=369204&view=rev
Log:
Backporting updated mod_ssl HOWTO
Modified:
httpd/httpd/branches/2.2.x/docs/manual/ssl/ssl_howto.xml
Modified: httpd/httpd/branches/2.2.x/docs/manual/ssl/ssl_howto.xml
URL: http://svn.apache.org/viewcvs/httpd/httpd/branches/2.2.x/docs/manual/ssl/ssl_howto.xml?rev=369204&r1=369203&r2=369204&view=diff
==============================================================================
--- httpd/httpd/branches/2.2.x/docs/manual/ssl/ssl_howto.xml (original)
+++ httpd/httpd/branches/2.2.x/docs/manual/ssl/ssl_howto.xml Sun Jan 15 06:38:56 2006
@@ -27,28 +27,30 @@
<summary>
<blockquote>
-<p>The solution of this problem is trivial
+<p>The solution to this problem is trivial
and is left as an exercise for the reader.</p>
<p class="cite">-- <cite>Standard textbook cookie</cite></p>
</blockquote>
-<p>How to solve particular security constraints for an SSL-aware
-webserver is not always obvious because of the coherences between SSL,
+<p>How to solve particular security problems for an SSL-aware
+webserver is not always obvious because of the interactions between SSL,
HTTP and Apache's way of processing requests. This chapter gives
-instructions on how to solve such typical situations. Treat it as a first
+instructions on how to solve some typical situations. Treat it as a first
step to find out the final solution, but always try to understand the
stuff before you use it. Nothing is worse than using a security solution
-without knowing its restrictions and coherences.</p>
+without knowing its restrictions and how it interacts with other systems.</p>
</summary>
<section id="ciphersuites">
-<title>Cipher Suites and Enforced Strong Security</title>
+<title>Cipher Suites and Enforcing Strong Security</title>
<ul>
-<li><a href="#realssl">SSLv2 only server</a></li>
-<li><a href="#onlystrong">strong encryption only server</a></li>
-<li><a href="#upgradeenc">server gated cryptography</a></li>
-<li><a href="#strongurl">stronger per-directory requirements</a></li>
+<li><a href="#realssl">How can I create a real SSLv2-only server?</a></li>
+<li><a href="#onlystrong">How can I create an SSL server which accepts strong encryption only?</a></li>
+<li><a href="#upgradeenc">How can I create an SSL server which accepts strong encryption only, but allows
+export browsers to upgrade to stronger encryption?</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="realssl">
@@ -75,18 +77,19 @@
<section id="upgradeenc">
<title>How can I create an SSL server which accepts strong encryption
only, but allows export browsers to upgrade to stronger encryption?</title>
- <p>This facility is called Server Gated Cryptography (SGC) and details
- you can find in the <code>README.GlobalID</code> document in the
- mod_ssl distribution. In short: The server has a Global ID server
- certificate, signed by a special CA certificate from Verisign which
- enables strong encryption in export browsers. This works as following:
- The browser connects with an export cipher, the server sends its Global
- ID certificate, the browser verifies it and subsequently upgrades the
- cipher suite before any HTTP communication takes place. The question
- now is: How can we allow this upgrade, but enforce strong encryption.
- Or in other words: Browser either have to initially connect with
- strong encryption or have to upgrade to strong encryption, but are
- not allowed to keep the export ciphers. The following does the trick:</p>
+ <p>This facility is called Server Gated Cryptography (SGC) and requires
+ a Global ID server certificate, signed by a special CA certificate
+ from Verisign. This enables strong encryption in 'export' versions of
+ browsers, which traditionally could not support it (because of US export
+ restrictions).</p>
+ <p>When a browser connects with an export cipher, the server sends its Global
+ ID certificate. The browser verifies this, and can then upgrade its
+ cipher suite before any HTTP communication takes place. The problem
+ lies in allowing browsers to upgrade in this fashion, but still requiring
+ strong encryption. In other words, we want browsers to either start a
+ connection with strong encryption, or to start with export ciphers but
+ upgrade to strong encryption before beginning HTTP communication.</p>
+ <p>This can be done as follows:</p>
<example><title>httpd.conf</title>
# allow all ciphers for the initial handshake,<br />
# so export browsers can upgrade via SGC facility<br />
@@ -103,12 +106,13 @@
<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 you cannot just use a server-wide <directive
- module="mod_ssl">SSLCipherSuite</directive> which restricts the
- ciphers to the strong variants. But mod_ssl allows you to reconfigure
- the cipher suite in per-directory context and automatically forces
+ <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.
- So, the solution is:</p>
+ This can be done as follows:</p>
<example>
# be liberal in general<br />
SSLCipherSuite ALL:!ADH:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP:+eNULL<br />
@@ -126,20 +130,23 @@
<section id="accesscontrol">
<title>Client Authentication and Access Control</title>
<ul>
-<li><a href="#allclients">simple certificate-based client authentication</a></li>
-<li><a href="#arbitraryclients">selective certificate-based client authentication</a></li>
-<li><a href="#certauthenticate">particular certificate-based client authentication</a></li>
-<li><a href="#intranet">intranet vs. internet authentication</a></li>
+<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 authenticate clients based on certificates when I know
-all my clients?</title>
- <p>When you know your user community (i.e. a closed user group
- situation), as it's the case for instance in an Intranet, you can
- use plain certificate authentication. All you have to do is to
- create client certificates signed by your own CA certificate
- <code>ca.crt</code> and then verify the clients against this
+<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>
<example><title>httpd.conf</title>
# require a client certificate which has to be directly<br />
@@ -151,11 +158,11 @@
</section>
<section id="arbitraryclients">
-<title>How can I authenticate my clients for a particular URL based on
-certificates but still allow arbitrary clients to access the remaining
-parts of the server?</title>
- <p>For this we again use the per-directory reconfiguration feature
- of <module>mod_ssl</module>:</p>
+<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>
<example><title>httpd.conf</title>
SSLVerifyClient none<br />
@@ -169,22 +176,21 @@
</section>
<section id="certauthenticate">
-<title>How can I authenticate only particular clients for a some URLs based
-on certificates but still allow arbitrary clients to access the remaining
-parts of the server?</title>
- <p>The key is to check for various ingredients of the client certificate.
- Usually this means to check the whole or part of the Distinguished
- Name (DN) of the Subject. For this two methods exists: The <module
- >mod_auth_basic</module> based variant and the <directive
- module="mod_ssl">SSLRequire</directive> variant. The first method is
- good when the clients are of totally different type, i.e. when their
- DNs have no common fields (usually the organisation, etc.). In this
- case you've to establish a password database containing <em>all</em>
- clients. The second method is better when your clients are all part of
- a common hierarchy which is encoded into the DN. Then you can match
- them more easily.</p>
+<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 first method:</p>
+ <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>
+
<example><title>httpd.conf</title><pre>
SSLVerifyClient none
<Directory /usr/local/apache2/htdocs/secure/area>
@@ -209,7 +215,10 @@
/C=US/L=L.A./O=Snake Oil, Ltd./OU=Dev/CN=Quux:xxj31ZMTZzkVA</pre>
</example>
- <p>The second method:</p>
+ <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>
+
<example><title>httpd.conf</title><pre>
SSLVerifyClient none
@@ -228,14 +237,16 @@
</section>
<section id="intranet">
-<title>How can I require HTTPS with strong ciphers and either basic
-authentication or client certificates for access to a subarea on the
-Intranet website for clients coming from the Internet but still allow
-plain HTTP access for clients on the Intranet?</title>
- <p>Let us assume the Intranet can be distinguished through the IP
- network 192.160.1.0/24 and the subarea on the Intranet website has
- the URL <code>/subarea</code>. Then configure the following outside
- your HTTPS virtual host (so it applies to both HTTPS and HTTP):</p>
+<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.160.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>
<example><title>httpd.conf</title><pre>
SSLCACertificateFile conf/ssl.crt/company-ca.crt
@@ -286,6 +297,4 @@
<!-- /access control -->
</manualpage>
-
-