granicus.if.org Git - apache/blob - docs/manual/ssl/ssl_howto.xml

   1 <?xml version='1.0' encoding='UTF-8' ?>
   2 <!DOCTYPE manualpage SYSTEM "../style/manualpage.dtd">
   3 <?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
   4 <!-- $LastChangedRevision$ -->
   5
   6 <!--
   7  Licensed to the Apache Software Foundation (ASF) under one or more
   8  contributor license agreements.  See the NOTICE file distributed with
   9  this work for additional information regarding copyright ownership.
  10  The ASF licenses this file to You under the Apache License, Version 2.0
  11  (the "License"); you may not use this file except in compliance with
  12  the License.  You may obtain a copy of the License at
  13
  14      http://www.apache.org/licenses/LICENSE-2.0
  15
  16  Unless required by applicable law or agreed to in writing, software
  17  distributed under the License is distributed on an "AS IS" BASIS,
  18  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  19  See the License for the specific language governing permissions and
  20  limitations under the License.
  21 -->
  22
  23 <manualpage metafile="ssl_howto.xml.meta">
  24 <parentdocument href="./">SSL/TLS</parentdocument>
  25
  26   <title>SSL/TLS Strong Encryption: How-To</title>
  27
  28 <summary>
  29
  30 <p>This documented is intended to get you started, and get a few things
  31 working. You are strongly encouraged to read the rest of the SSL
  32 documentation, and arrive at a deeper understanding of the material,
  33 before progressing to the advanced techniques.</p>
  34 </summary>
  35
  36 <section id="configexample">
  37 <title>Basic Configuration Example</title>
  38
  39 <p>Your SSL configuration will need to contain, at minimum, the
  40 following directives.</p>
  41
  42 <highlight language="config">
  43 Listen 443
  44 &lt;VirtualHost *:443&gt;
  45     ServerName www.example.com
  46     SSLEngine on
  47     SSLCertificateFile /path/to/www.example.com.cert
  48     SSLCertificateKeyFile /path/to/www.example.com.key
  49 &lt;/VirtualHost&gt;
  50 </highlight>
  51
  52 </section>
  53
  54 <section id="ciphersuites">
  55 <title>Cipher Suites and Enforcing Strong Security</title>
  56 <ul>
  57 <li><a href="#onlystrong">How can I create an SSL server which accepts strong encryption only?</a></li>
  58 <li><a href="#strongurl">How can I create an SSL server which accepts all types of ciphers in general, but
  59 requires a strong cipher for access to a particular URL?</a></li>
  60 </ul>
  61
  62 <section id="onlystrong">
  63 <title>How can I create an SSL server which accepts strong encryption
  64 only?</title>
  65     <p>The following enables only the strongest ciphers:</p>
  66     <highlight language="config">
  67       SSLCipherSuite HIGH:!aNULL:!MD5
  68     </highlight>
  69
  70     <p>While with the following configuration you specify a preference
  71     for specific speed-optimized ciphers (which will be selected by
  72     mod_ssl, provided that they are supported by the client):</p>
  73
  74     <highlight language="config">
  75 SSLCipherSuite RC4-SHA:AES128-SHA:HIGH:!aNULL:!MD5
  76 SSLHonorCipherOrder on
  77     </highlight>
  78 </section>
  79
  80 <section id="strongurl">
  81 <title>How can I create an SSL server which accepts all types of ciphers
  82 in general, but requires a strong ciphers for access to a particular
  83 URL?</title>
  84     <p>Obviously, a server-wide <directive
  85     module="mod_ssl">SSLCipherSuite</directive> which restricts
  86     ciphers to the strong variants, isn't the answer here. However,
  87     <module>mod_ssl</module> can be reconfigured within <code>Location</code>
  88     blocks, to give a per-directory solution, and can automatically force
  89     a renegotiation of the SSL parameters to meet the new configuration.
  90     This can be done as follows:</p>
  91     <highlight language="config">
  92 # be liberal in general
  93 SSLCipherSuite ALL:!aNULL:RC4+RSA:+HIGH:+MEDIUM:+LOW:+EXP:+eNULL
  94
  95 &lt;Location /strong/area&gt;
  96 # but https://hostname/strong/area/ and below
  97 # requires strong ciphers
  98 SSLCipherSuite HIGH:!aNULL:!MD5
  99 &lt;/Location&gt;
 100     </highlight>
 101 </section>
 102 </section>
 103 <!-- /ciphersuites -->
 104
 105 <section id="accesscontrol">
 106 <title>Client Authentication and Access Control</title>
 107 <ul>
 108 <li><a href="#allclients">How can I force clients to authenticate using certificates?</a></li>
 109 <li><a href="#arbitraryclients">How can I force clients to authenticate using certificates for a
 110         particular URL, but still allow arbitrary clients to access the rest of the server?</a></li>
 111 <li><a href="#certauthenticate">How can I allow only clients who have certificates to access a
 112         particular URL, but allow all clients to access the rest of the server?</a></li>
 113 <li><a href="#intranet">How can I require HTTPS with strong ciphers, and either
 114 basic authentication or client certificates, for access to part of the
 115 Intranet website, for clients coming from the Internet?</a></li>
 116 </ul>
 117
 118 <section id="allclients">
 119 <title>How can I force clients to authenticate using certificates?</title>
 120
 121     <p>When you know all of your users (eg, as is often the case on a corporate
 122     Intranet), you can require plain certificate authentication. All you
 123     need to do is to create client certificates signed by your own CA
 124     certificate (<code>ca.crt</code>) and then verify the clients against this
 125     certificate.</p>
 126     <highlight language="config">
 127 # require a client certificate which has to be directly
 128 # signed by our CA certificate in ca.crt
 129 SSLVerifyClient require
 130 SSLVerifyDepth 1
 131 SSLCACertificateFile conf/ssl.crt/ca.crt
 132     </highlight>
 133 </section>
 134
 135 <section id="arbitraryclients">
 136 <title>How can I force clients to authenticate using certificates for a
 137   particular URL, but still allow arbitrary clients to access the rest of the server?</title>
 138
 139     <p>To force clients to authenticate using certificates for a particular URL,
 140     you can use the per-directory reconfiguration features of
 141     <module>mod_ssl</module>:</p>
 142
 143     <highlight language="config">
 144 SSLVerifyClient none
 145 SSLCACertificateFile conf/ssl.crt/ca.crt
 146
 147 &lt;Location /secure/area&gt;
 148 SSLVerifyClient require
 149 SSLVerifyDepth 1
 150 &lt;/Location&gt;
 151     </highlight>
 152 </section>
 153
 154 <section id="certauthenticate">
 155 <title>How can I allow only clients who have certificates to access a
 156   particular URL, but allow all clients to access the rest of the server?</title>
 157
 158     <p>The key to doing this is checking that part of the client certificate
 159     matches what you expect. Usually this means checking all or part of the
 160     Distinguished Name (DN), to see if it contains some known string.
 161     There are two ways to do this, using either <module>mod_auth_basic</module> or
 162     <directive module="mod_ssl">SSLRequire</directive>.</p>
 163
 164     <p>The <module>mod_auth_basic</module> method is generally required when
 165     the certificates are completely arbitrary, or when their DNs have
 166     no common fields (usually the organisation, etc.). In this case,
 167     you should establish a password database containing <em>all</em>
 168     clients allowed, as follows:</p>
 169
 170     <highlight language="config">
 171 SSLVerifyClient      none
 172 SSLCACertificateFile conf/ssl.crt/ca.crt
 173 SSLCACertificatePath conf/ssl.crt
 174
 175 &lt;Directory /usr/local/apache2/htdocs/secure/area&gt;
 176     SSLVerifyClient      require
 177     SSLVerifyDepth       5
 178     SSLOptions           +FakeBasicAuth
 179     SSLRequireSSL
 180     AuthName             "Snake Oil Authentication"
 181     AuthType             Basic
 182     AuthBasicProvider    file
 183     AuthUserFile         /usr/local/apache2/conf/httpd.passwd
 184     Require              valid-user
 185 &lt;/Directory&gt;
 186     </highlight>
 187
 188     <p>The password used in this example is the DES encrypted string "password".
 189     See the <directive module="mod_ssl">SSLOptions</directive> docs for more
 190     information.</p>
 191
 192     <example><title>httpd.passwd</title><pre>
 193 /C=DE/L=Munich/O=Snake Oil, Ltd./OU=Staff/CN=Foo:xxj31ZMTZzkVA
 194 /C=US/L=S.F./O=Snake Oil, Ltd./OU=CA/CN=Bar:xxj31ZMTZzkVA
 195 /C=US/L=L.A./O=Snake Oil, Ltd./OU=Dev/CN=Quux:xxj31ZMTZzkVA</pre>
 196     </example>
 197
 198     <p>When your clients are all part of a common hierarchy, which is encoded
 199     into the DN, you can match them more easily using <directive module="mod_ssl"
 200     >SSLRequire</directive>, as follows:</p>
 201
 202
 203     <highlight language="config">
 204 SSLVerifyClient      none
 205 SSLCACertificateFile conf/ssl.crt/ca.crt
 206 SSLCACertificatePath conf/ssl.crt
 207
 208 &lt;Directory /usr/local/apache2/htdocs/secure/area&gt;
 209   SSLVerifyClient      require
 210   SSLVerifyDepth       5
 211   SSLOptions           +FakeBasicAuth
 212   SSLRequireSSL
 213   SSLRequire       %{SSL_CLIENT_S_DN_O}  eq "Snake Oil, Ltd." \
 214                and %{SSL_CLIENT_S_DN_OU} in {"Staff", "CA", "Dev"}
 215 &lt;/Directory&gt;
 216     </highlight>
 217 </section>
 218
 219 <section id="intranet">
 220 <title>How can I require HTTPS with strong ciphers, and either basic
 221 authentication or client certificates, for access to part of the
 222 Intranet website, for clients coming from the Internet? I still want to allow
 223 plain HTTP access for clients on the Intranet.</title>
 224
 225    <p>These examples presume that clients on the Intranet have IPs in the range
 226    192.168.1.0/24, and that the part of the Intranet website you want to allow
 227    internet access to is <code>/usr/local/apache2/htdocs/subarea</code>.
 228    This configuration should remain outside of your HTTPS virtual host, so
 229    that it applies to both HTTPS and HTTP.</p>
 230
 231     <highlight language="config">
 232 SSLCACertificateFile conf/ssl.crt/company-ca.crt
 233
 234 &lt;Directory /usr/local/apache2/htdocs&gt;
 235     #   Outside the subarea only Intranet access is granted
 236     Require              ip 192.168.1.0/24
 237 &lt;/Directory&gt;
 238
 239 &lt;Directory /usr/local/apache2/htdocs/subarea&gt;
 240     #   Inside the subarea any Intranet access is allowed
 241     #   but from the Internet only HTTPS + Strong-Cipher + Password
 242     #   or the alternative HTTPS + Strong-Cipher + Client-Certificate
 243
 244     #   If HTTPS is used, make sure a strong cipher is used.
 245     #   Additionally allow client certs as alternative to basic auth.
 246     SSLVerifyClient      optional
 247     SSLVerifyDepth       1
 248     SSLOptions           +FakeBasicAuth +StrictRequire
 249     SSLRequire           %{SSL_CIPHER_USEKEYSIZE} &gt;= 128
 250
 251     #   Force clients from the Internet to use HTTPS
 252     RewriteEngine        on
 253     RewriteCond          %{REMOTE_ADDR} !^192\.168\.1\.[0-9]+$
 254     RewriteCond          %{HTTPS} !=on
 255     RewriteRule          . - [F]
 256
 257     #   Allow Network Access and/or Basic Auth
 258     Satisfy              any
 259
 260     #   Network Access Control
 261     Require              ip 192.168.1.0/24
 262
 263     #   HTTP Basic Authentication
 264     AuthType             basic
 265     AuthName             "Protected Intranet Area"
 266     AuthBasicProvider    file
 267     AuthUserFile         conf/protected.passwd
 268     Require              valid-user
 269 &lt;/Directory&gt;
 270     </highlight>
 271 </section>
 272 </section>
 273 <!-- /access control -->
 274
 275 <section id="logging">
 276     <title>Logging</title>
 277
 278     <p><module>mod_ssl</module> can log extremely verbose debugging information
 279     to the error log, when its <directive module="core">LogLevel</directive> is
 280     set to the higher trace levels. On the other hand, on a very busy server,
 281     level <code>info</code> may already be too much. Remember that you can
 282     configure the <directive module="core">LogLevel</directive> per module to
 283     suite your needs.</p>
 284 </section>
 285
 286 </manualpage>
 287