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

   1 <?xml version="1.0" encoding="ISO-8859-1"?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
   3 <html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en"><head><!--
   4         XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
   5               This file is generated from xml source: DO NOT EDIT
   6         XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
   7       -->
   8 <title>SSL/TLS Strong Encryption: How-To - Apache HTTP Server</title>
   9 <link href="../style/css/manual.css" rel="stylesheet" media="all" type="text/css" title="Main stylesheet" />
  10 <link href="../style/css/manual-loose-100pc.css" rel="alternate stylesheet" media="all" type="text/css" title="No Sidebar - Default font size" />
  11 <link href="../style/css/manual-print.css" rel="stylesheet" media="print" type="text/css" />
  12 <link href="../images/favicon.ico" rel="shortcut icon" /></head>
  13 <body id="manual-page"><div id="page-header">
  14 <p class="menu"><a href="../mod/">Modules</a> | <a href="../mod/directives.html">Directives</a> | <a href="../faq/">FAQ</a> | <a href="../glossary.html">Glossary</a> | <a href="../sitemap.html">Sitemap</a></p>
  15 <p class="apache">Apache HTTP Server Version 2.3</p>
  16 <img alt="" src="../images/feather.gif" /></div>
  17 <div class="up"><a href="./"><img title="&lt;-" alt="&lt;-" src="../images/left.gif" /></a></div>
  18 <div id="path">
  19 <a href="http://www.apache.org/">Apache</a> &gt; <a href="http://httpd.apache.org/">HTTP Server</a> &gt; <a href="http://httpd.apache.org/docs/">Documentation</a> &gt; <a href="../">Version 2.3</a> &gt; <a href="./">SSL/TLS</a></div><div id="page-content"><div id="preamble"><h1>SSL/TLS Strong Encryption: How-To</h1>
  20 <div class="toplang">
  21 <p><span>Available Languages: </span><a href="../en/ssl/ssl_howto.html" title="English">&nbsp;en&nbsp;</a></p>
  22 </div>
  23
  24 <blockquote>
  25 <p>The solution to this problem is trivial
  26 and is left as an exercise for the reader.</p>
  27
  28 <p class="cite">-- <cite>Standard textbook cookie</cite></p>
  29 </blockquote>
  30
  31 <p>How to solve particular security problems for an SSL-aware
  32 webserver is not always obvious because of the interactions between SSL,
  33 HTTP and Apache's way of processing requests. This chapter gives
  34 instructions on how to solve some typical situations. Treat it as a first
  35 step to find out the final solution, but always try to understand the
  36 stuff before you use it. Nothing is worse than using a security solution
  37 without knowing its restrictions and how it interacts with other systems.</p>
  38 </div>
  39 <div id="quickview"><ul id="toc"><li><img alt="" src="../images/down.gif" /> <a href="#ciphersuites">Cipher Suites and Enforcing Strong Security</a></li>
  40 <li><img alt="" src="../images/down.gif" /> <a href="#accesscontrol">Client Authentication and Access Control</a></li>
  41 </ul></div>
  42 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
  43 <div class="section">
  44 <h2><a name="ciphersuites" id="ciphersuites">Cipher Suites and Enforcing Strong Security</a></h2>
  45
  46 <ul>
  47 <li><a href="#realssl">How can I create a real SSLv2-only server?</a></li>
  48 <li><a href="#onlystrong">How can I create an SSL server which accepts strong encryption only?</a></li>
  49 <li><a href="#upgradeenc">How can I create an SSL server which accepts strong encryption only, but allows
  50 export browsers to upgrade to stronger encryption?</a></li>
  51 <li><a href="#strongurl">How can I create an SSL server which accepts all types of ciphers in general, but
  52 requires a strong cipher for access to a particular URL?</a></li>
  53 </ul>
  54
  55 <h3><a name="realssl" id="realssl">How can I create a real SSLv2-only server?</a></h3>
  56
  57     <p>The following creates an SSL server which speaks only the SSLv2 protocol and
  58     its ciphers.</p>
  59
  60     <div class="example"><h3>httpd.conf</h3><p><code>
  61       SSLProtocol -all +SSLv2<br />
  62       SSLCipherSuite SSLv2:+HIGH:+MEDIUM:+LOW:+EXP<br />
  63     </code></p></div>
  64
  65
  66 <h3><a name="onlystrong" id="onlystrong">How can I create an SSL server which accepts strong encryption
  67 only?</a></h3>
  68
  69     <p>The following enables only the seven strongest ciphers:</p>
  70     <div class="example"><h3>httpd.conf</h3><p><code>
  71       SSLProtocol all<br />
  72       SSLCipherSuite HIGH:MEDIUM<br />
  73     </code></p></div>
  74
  75
  76 <h3><a name="upgradeenc" id="upgradeenc">How can I create an SSL server which accepts strong encryption
  77 only, but allows export browsers to upgrade to stronger encryption?</a></h3>
  78
  79     <p>This facility is called Server Gated Cryptography (SGC) and requires
  80     a Global ID server certificate, signed by a special CA certificate
  81     from Verisign. This enables strong encryption in 'export' versions of
  82     browsers, which traditionally could not support it (because of US export
  83     restrictions).</p>
  84     <p>When a browser connects with an export cipher, the server sends its Global
  85     ID certificate. The browser verifies this, and can then upgrade its
  86     cipher suite before any HTTP communication takes place. The problem
  87     lies in allowing browsers to upgrade in this fashion, but still requiring
  88     strong encryption. In other words, we want browsers to either start a
  89     connection with strong encryption, or to start with export ciphers but
  90     upgrade to strong encryption before beginning HTTP communication.</p>
  91     <p>This can be done as follows:</p>
  92     <div class="example"><h3>httpd.conf</h3><p><code>
  93       # allow all ciphers for the initial handshake,<br />
  94       # so export browsers can upgrade via SGC facility<br />
  95       SSLCipherSuite ALL:!ADH:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP:+eNULL<br />
  96       <br />
  97       &lt;Directory /usr/local/apache2/htdocs&gt;<br />
  98       # but finally deny all browsers which haven't upgraded<br />
  99       SSLRequire %{SSL_CIPHER_USEKEYSIZE} &gt;= 128<br />
 100       &lt;/Directory&gt;
 101     </code></p></div>
 102
 103
 104 <h3><a name="strongurl" id="strongurl">How can I create an SSL server which accepts all types of ciphers
 105 in general, but requires a strong ciphers for access to a particular
 106 URL?</a></h3>
 107
 108     <p>Obviously, a server-wide <code class="directive"><a href="../mod/mod_ssl.html#sslciphersuite">SSLCipherSuite</a></code> which restricts
 109     ciphers to the strong variants, isn't the answer here. However,
 110     <code class="module"><a href="../mod/mod_ssl.html">mod_ssl</a></code> can be reconfigured within <code>Location</code>
 111     blocks, to give a per-directory solution, and can automatically force
 112     a renegotiation of the SSL parameters to meet the new configuration.
 113     This can be done as follows:</p>
 114     <div class="example"><p><code>
 115       # be liberal in general<br />
 116       SSLCipherSuite ALL:!ADH:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP:+eNULL<br />
 117       <br />
 118       &lt;Location /strong/area&gt;<br />
 119       # but https://hostname/strong/area/ and below<br />
 120       # requires strong ciphers<br />
 121       SSLCipherSuite HIGH:MEDIUM<br />
 122       &lt;/Location&gt;
 123     </code></p></div>
 124
 125 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 126 <div class="section">
 127 <h2><a name="accesscontrol" id="accesscontrol">Client Authentication and Access Control</a></h2>
 128
 129 <ul>
 130 <li><a href="#allclients">How can I force clients to authenticate using certificates?</a></li>
 131 <li><a href="#arbitraryclients">How can I force clients to authenticate using certificates for a
 132         particular URL, but still allow arbitrary clients to access the rest of the server?</a></li>
 133 <li><a href="#certauthenticate">How can I allow only clients who have certificates to access a
 134         particular URL, but allow all clients to access the rest of the server?</a></li>
 135 <li><a href="#intranet">How can I require HTTPS with strong ciphers, and either
 136 basic authentication or client certificates, for access to part of the
 137 Intranet website, for clients coming from the Internet?</a></li>
 138 </ul>
 139
 140 <h3><a name="allclients" id="allclients">How can I force clients to authenticate using certificates?</a></h3>
 141
 142
 143     <p>When you know all of your users (eg, as is often the case on a corporate
 144     Intranet), you can require plain certificate authentication. All you
 145     need to do is to create client certificates signed by your own CA
 146     certificate (<code>ca.crt</code>) and then verify the clients against this
 147     certificate.</p>
 148     <div class="example"><h3>httpd.conf</h3><p><code>
 149       # require a client certificate which has to be directly<br />
 150       # signed by our CA certificate in ca.crt<br />
 151       SSLVerifyClient require<br />
 152       SSLVerifyDepth 1<br />
 153       SSLCACertificateFile conf/ssl.crt/ca.crt
 154     </code></p></div>
 155
 156
 157 <h3><a name="arbitraryclients" id="arbitraryclients">How can I force clients to authenticate using certificates for a
 158         particular URL, but still allow arbitrary clients to access the rest of the server?</a></h3>
 159
 160
 161 <p>To force clients to authenticate using certificates for a particular URL,
 162         you can use the per-directory reconfiguration features of <code class="module"><a href="../mod/mod_ssl.html">mod_ssl</a></code>:</p>
 163
 164     <div class="example"><h3>httpd.conf</h3><p><code>
 165     SSLVerifyClient none<br />
 166     SSLCACertificateFile conf/ssl.crt/ca.crt<br />
 167     <br />
 168     &lt;Location /secure/area&gt;<br />
 169     SSLVerifyClient require<br />
 170     SSLVerifyDepth 1<br />
 171     &lt;/Location&gt;<br />
 172     </code></p></div>
 173
 174
 175 <h3><a name="certauthenticate" id="certauthenticate">How can I allow only clients who have certificates to access a
 176         particular URL, but allow all clients to access the rest of the server?</a></h3>
 177
 178
 179     <p>The key to doing this is checking that part of the client certificate
 180     matches what you expect. Usually this means checking all or part of the
 181     Distinguished Name (DN), to see if it contains some known string.
 182     There are two ways to do this, using either <code class="module"><a href="../mod/mod_auth_basic.html">mod_auth_basic</a></code> or
 183     <code class="directive"><a href="../mod/mod_ssl.html#sslrequire">SSLRequire</a></code>.</p>
 184
 185     <p>The <code class="module"><a href="../mod/mod_auth_basic.html">mod_auth_basic</a></code> method is generally required when
 186     the certificates are completely arbitrary, or when their DNs have
 187     no common fields (usually the organisation, etc.). In this case,
 188     you should establish a password database containing <em>all</em>
 189     clients allowed, as follows:</p>
 190
 191     <div class="example"><h3>httpd.conf</h3><pre>
 192 SSLVerifyClient      none
 193 &lt;Directory /usr/local/apache2/htdocs/secure/area&gt;
 194
 195 SSLVerifyClient      require
 196 SSLVerifyDepth       5
 197 SSLCACertificateFile conf/ssl.crt/ca.crt
 198 SSLCACertificatePath conf/ssl.crt
 199 SSLOptions           +FakeBasicAuth
 200 SSLRequireSSL
 201 AuthName             "Snake Oil Authentication"
 202 AuthType             Basic
 203 AuthBasicProvider    file
 204 AuthUserFile         /usr/local/apache2/conf/httpd.passwd
 205 require              valid-user
 206 &lt;/Directory&gt;</pre></div>
 207
 208     <p>The password used in this example is the DES encrypted string "password".
 209     See the <code class="directive"><a href="../mod/mod_ssl.html#ssloptions">SSLOptions</a></code> docs for more
 210     information.</p>
 211
 212     <div class="example"><h3>httpd.passwd</h3><pre>
 213 /C=DE/L=Munich/O=Snake Oil, Ltd./OU=Staff/CN=Foo:xxj31ZMTZzkVA
 214 /C=US/L=S.F./O=Snake Oil, Ltd./OU=CA/CN=Bar:xxj31ZMTZzkVA
 215 /C=US/L=L.A./O=Snake Oil, Ltd./OU=Dev/CN=Quux:xxj31ZMTZzkVA</pre></div>
 216
 217     <p>When your clients are all part of a common hierarchy, which is encoded
 218     into the DN, you can match them more easily using <code class="directive"><a href="../mod/mod_ssl.html#sslrequire">SSLRequire</a></code>, as follows:</p>
 219
 220
 221     <div class="example"><h3>httpd.conf</h3><pre>
 222 SSLVerifyClient      none
 223 &lt;Directory /usr/local/apache2/htdocs/secure/area&gt;
 224
 225   SSLVerifyClient      require
 226   SSLVerifyDepth       5
 227   SSLCACertificateFile conf/ssl.crt/ca.crt
 228   SSLCACertificatePath conf/ssl.crt
 229   SSLOptions           +FakeBasicAuth
 230   SSLRequireSSL
 231   SSLRequire       %{SSL_CLIENT_S_DN_O}  eq "Snake Oil, Ltd." \
 232                and %{SSL_CLIENT_S_DN_OU} in {"Staff", "CA", "Dev"}
 233 &lt;/Directory&gt;</pre></div>
 234
 235
 236 <h3><a name="intranet" id="intranet">How can I require HTTPS with strong ciphers, and either basic
 237 authentication or client certificates, for access to part of the
 238 Intranet website, for clients coming from the Internet? I still want to allow
 239 plain HTTP access for clients on the Intranet.</a></h3>
 240
 241
 242    <p>These examples presume that clients on the Intranet have IPs in the range
 243    192.160.1.0/24, and that the part of the Intranet website you want to allow
 244    internet access to is <code>/usr/local/apache2/htdocs/subarea</code>.
 245    This configuration should remain outside of your HTTPS virtual host, so
 246    that it applies to both HTTPS and HTTP.</p>
 247
 248     <div class="example"><h3>httpd.conf</h3><pre>
 249 SSLCACertificateFile conf/ssl.crt/company-ca.crt
 250
 251 &lt;Directory /usr/local/apache2/htdocs&gt;
 252 #   Outside the subarea only Intranet access is granted
 253 Order                deny,allow
 254 Deny                 from all
 255 Allow                from 192.168.1.0/24
 256 &lt;/Directory&gt;
 257
 258 &lt;Directory /usr/local/apache2/htdocs/subarea&gt;
 259 #   Inside the subarea any Intranet access is allowed
 260 #   but from the Internet only HTTPS + Strong-Cipher + Password
 261 #   or the alternative HTTPS + Strong-Cipher + Client-Certificate
 262
 263 #   If HTTPS is used, make sure a strong cipher is used.
 264 #   Additionally allow client certs as alternative to basic auth.
 265 SSLVerifyClient      optional
 266 SSLVerifyDepth       1
 267 SSLOptions           +FakeBasicAuth +StrictRequire
 268 SSLRequire           %{SSL_CIPHER_USEKEYSIZE} &gt;= 128
 269
 270 #   Force clients from the Internet to use HTTPS
 271 RewriteEngine        on
 272 RewriteCond          %{REMOTE_ADDR} !^192\.168\.1\.[0-9]+$
 273 RewriteCond          %{HTTPS} !=on
 274 RewriteRule          .* - [F]
 275
 276 #   Allow Network Access and/or Basic Auth
 277 Satisfy              any
 278
 279 #   Network Access Control
 280 Order                deny,allow
 281 Deny                 from all
 282 Allow                192.168.1.0/24
 283
 284 #   HTTP Basic Authentication
 285 AuthType             basic
 286 AuthName             "Protected Intranet Area"
 287 AuthBasicProvider    file
 288 AuthUserFile         conf/protected.passwd
 289 Require              valid-user
 290 &lt;/Directory&gt;</pre></div>
 291
 292 </div></div>
 293 <div class="bottomlang">
 294 <p><span>Available Languages: </span><a href="../en/ssl/ssl_howto.html" title="English">&nbsp;en&nbsp;</a></p>
 295 </div><div id="footer">
 296 <p class="apache">Copyright 2008 The Apache Software Foundation.<br />Licensed under the <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a>.</p>
 297 <p class="menu"><a href="../mod/">Modules</a> | <a href="../mod/directives.html">Directives</a> | <a href="../faq/">FAQ</a> | <a href="../glossary.html">Glossary</a> | <a href="../sitemap.html">Sitemap</a></p></div>
 298 </body></html>