httpd-cvs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From noi...@apache.org
Subject svn commit: r369201 - /httpd/httpd/trunk/docs/manual/ssl/ssl_howto.xml
Date Sun, 15 Jan 2006 14:12:58 GMT
Author: noirin
Date: Sun Jan 15 06:12:47 2006
New Revision: 369201

URL: http://svn.apache.org/viewcvs?rev=369201&view=rev
Log:
Rewrite of the mod_ssl HOWTO - only language changes, no code changes.


Modified:
    httpd/httpd/trunk/docs/manual/ssl/ssl_howto.xml

Modified: httpd/httpd/trunk/docs/manual/ssl/ssl_howto.xml
URL: http://svn.apache.org/viewcvs/httpd/httpd/trunk/docs/manual/ssl/ssl_howto.xml?rev=369201&r1=369200&r2=369201&view=diff
==============================================================================
--- httpd/httpd/trunk/docs/manual/ssl/ssl_howto.xml (original)
+++ httpd/httpd/trunk/docs/manual/ssl/ssl_howto.xml Sun Jan 15 06:12:47 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
 &lt;Directory /usr/local/apache2/htdocs/secure/area&gt;
@@ -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>
-
-
 



Mime
View raw message