From: Noirin Plunkett Date: Sun, 15 Jan 2006 14:12:47 +0000 (+0000) Subject: Rewrite of the mod_ssl HOWTO - only language changes, no code changes. X-Git-Tag: 2.3.0~2609 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=766f0e20d80d05972ffe8e9d4ab0a47e2b515af0;p=thirdparty%2Fapache%2Fhttpd.git Rewrite of the mod_ssl HOWTO - only language changes, no code changes. git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@369201 13f79535-47bb-0310-9956-ffa450edef68 --- diff --git a/docs/manual/ssl/ssl_howto.xml b/docs/manual/ssl/ssl_howto.xml index 8273e8f6daf..955b92f6c3c 100644 --- a/docs/manual/ssl/ssl_howto.xml +++ b/docs/manual/ssl/ssl_howto.xml @@ -27,28 +27,30 @@
-

The solution of this problem is trivial +

The solution to this problem is trivial and is left as an exercise for the reader.

-- Standard textbook cookie

-

How to solve particular security constraints for an SSL-aware -webserver is not always obvious because of the coherences between SSL, +

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.

+without knowing its restrictions and how it interacts with other systems.
-Cipher Suites and Enforced Strong Security +Cipher Suites and Enforcing Strong Security
@@ -75,18 +77,19 @@ only?
How can I create an SSL server which accepts strong encryption only, but allows export browsers to upgrade to stronger encryption? -

This facility is called Server Gated Cryptography (SGC) and details - you can find in the README.GlobalID 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:

+

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).

+

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.

+

This can be done as follows:

httpd.conf # allow all ciphers for the initial handshake,
# so export browsers can upgrade via SGC facility
@@ -103,12 +106,13 @@ only, but allows export browsers to upgrade to stronger encryption? 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? -

Obviously you cannot just use a server-wide SSLCipherSuite 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 +

Obviously, a server-wide SSLCipherSuite which restricts + ciphers to the strong variants, isn't the answer here. However, + mod_ssl can be reconfigured within Location + 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:

+ This can be done as follows:

# be liberal in general
SSLCipherSuite ALL:!ADH:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP:+eNULL
@@ -126,20 +130,23 @@ URL?
Client Authentication and Access Control
-How can I authenticate clients based on certificates when I know -all my clients? -

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 - ca.crt and then verify the clients against this +How can I force clients to authenticate using certificates? + +

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 (ca.crt) and then verify the clients against this certificate.

httpd.conf # require a client certificate which has to be directly
@@ -151,11 +158,11 @@ all my clients?
-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? -

For this we again use the per-directory reconfiguration feature - of mod_ssl:

+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? + +

To force clients to authenticate using certificates for a particular URL, + you can use the per-directory reconfiguration features of mod_ssl:

httpd.conf SSLVerifyClient none
@@ -169,22 +176,21 @@ parts of the server?
-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? -

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 mod_auth_basic based variant and the SSLRequire 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 all - 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.

- -

The first method:

+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? + +

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 mod_auth_basic or + SSLRequire.

+ +

The mod_auth_basic 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 all + clients allowed, as follows:

+ httpd.conf
 SSLVerifyClient      none
 <Directory /usr/local/apache2/htdocs/secure/area>
@@ -209,7 +215,10 @@ require              valid-user
 /C=US/L=L.A./O=Snake Oil, Ltd./OU=Dev/CN=Quux:xxj31ZMTZzkVA
 -

The second method:

+

When your clients are all part of a common hierarchy, which is encoded + into the DN, you can match them more easily using SSLRequire, as follows:

+ httpd.conf
 SSLVerifyClient      none
@@ -228,14 +237,16 @@ SSLVerifyClient      none
-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? -

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 /subarea. Then configure the following outside - your HTTPS virtual host (so it applies to both HTTPS and HTTP):

+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. + +

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 /usr/local/apache2/htdocs/subarea. + This configuration should remain outside of your HTTPS virtual host, so + that it applies to both HTTPS and HTTP.

httpd.conf
 SSLCACertificateFile conf/ssl.crt/company-ca.crt
@@ -287,5 +298,3 @@ Require              valid-user
 
 
 
-
-