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" /><link rel="stylesheet" type="text/css" href="../style/css/prettify.css" />
  12 <script src="../style/scripts/prettify.js" type="text/javascript">
  13 </script>
  14
  15 <link href="../images/favicon.ico" rel="shortcut icon" /></head>
  16 <body id="manual-page"><div id="page-header">
  17 <p class="menu"><a href="../mod/">Modules</a> | <a href="../mod/directives.html">Directives</a> | <a href="http://wiki.apache.org/httpd/FAQ">FAQ</a> | <a href="../glossary.html">Glossary</a> | <a href="../sitemap.html">Sitemap</a></p>
  18 <p class="apache">Apache HTTP Server Version 2.4</p>
  19 <img alt="" src="../images/feather.gif" /></div>
  20 <div class="up"><a href="./"><img title="&lt;-" alt="&lt;-" src="../images/left.gif" /></a></div>
  21 <div id="path">
  22 <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.4</a> &gt; <a href="./">SSL/TLS</a></div><div id="page-content"><div id="preamble"><h1>SSL/TLS Strong Encryption: How-To</h1>
  23 <div class="toplang">
  24 <p><span>Available Languages: </span><a href="../en/ssl/ssl_howto.html" title="English">&nbsp;en&nbsp;</a> |
  25 <a href="../fr/ssl/ssl_howto.html" hreflang="fr" rel="alternate" title="Français">&nbsp;fr&nbsp;</a></p>
  26 </div>
  27
  28
  29 <p>This documented is intended to get you started, and get a few things
  30 working. You are strongly encouraged to read the rest of the SSL
  31 documentation, and arrive at a deeper understanding of the material,
  32 before progressing to the advanced techniques.</p>
  33 </div>
  34 <div id="quickview"><ul id="toc"><li><img alt="" src="../images/down.gif" /> <a href="#configexample">Basic Configuration Example</a></li>
  35 <li><img alt="" src="../images/down.gif" /> <a href="#ciphersuites">Cipher Suites and Enforcing Strong Security</a></li>
  36 <li><img alt="" src="../images/down.gif" /> <a href="#accesscontrol">Client Authentication and Access Control</a></li>
  37 <li><img alt="" src="../images/down.gif" /> <a href="#logging">Logging</a></li>
  38 </ul><ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div>
  39 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
  40 <div class="section">
  41 <h2><a name="configexample" id="configexample">Basic Configuration Example</a></h2>
  42
  43
  44 <p>Your SSL configuration will need to contain, at minimum, the
  45 following directives.</p>
  46
  47 <pre class="prettyprint lang-config">
  48 Listen 443
  49 &lt;VirtualHost *:443&gt;
  50     ServerName www.example.com
  51     SSLEngine on
  52     SSLCertificateFile /path/to/www.example.com.cert
  53     SSLCertificateKeyFile /path/to/www.example.com.key
  54 &lt;/VirtualHost&gt;
  55 </pre>
  56
  57
  58 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
  59 <div class="section">
  60 <h2><a name="ciphersuites" id="ciphersuites">Cipher Suites and Enforcing Strong Security</a></h2>
  61
  62 <ul>
  63 <li><a href="#onlystrong">How can I create an SSL server which accepts strong encryption only?</a></li>
  64 <li><a href="#strongurl">How can I create an SSL server which accepts all types of ciphers in general, but
  65 requires a strong cipher for access to a particular URL?</a></li>
  66 </ul>
  67
  68 <h3><a name="onlystrong" id="onlystrong">How can I create an SSL server which accepts strong encryption
  69 only?</a></h3>
  70
  71     <p>The following enables only the strongest ciphers:</p>
  72     <pre class="prettyprint lang-config">
  73       SSLCipherSuite HIGH:!aNULL:!MD5
  74     </pre>
  75
  76
  77     <p>While with the following configuration you specify a preference
  78     for specific speed-optimized ciphers (which will be selected by
  79     mod_ssl, provided that they are supported by the client):</p>
  80
  81     <pre class="prettyprint lang-config">
  82 SSLCipherSuite RC4-SHA:AES128-SHA:HIGH:!aNULL:!MD5
  83 SSLHonorCipherOrder on
  84     </pre>
  85
  86
  87
  88 <h3><a name="strongurl" id="strongurl">How can I create an SSL server which accepts all types of ciphers
  89 in general, but requires a strong ciphers for access to a particular
  90 URL?</a></h3>
  91
  92     <p>Obviously, a server-wide <code class="directive"><a href="../mod/mod_ssl.html#sslciphersuite">SSLCipherSuite</a></code> which restricts
  93     ciphers to the strong variants, isn't the answer here. However,
  94     <code class="module"><a href="../mod/mod_ssl.html">mod_ssl</a></code> can be reconfigured within <code>Location</code>
  95     blocks, to give a per-directory solution, and can automatically force
  96     a renegotiation of the SSL parameters to meet the new configuration.
  97     This can be done as follows:</p>
  98     <pre class="prettyprint lang-config">
  99 # be liberal in general
 100 SSLCipherSuite ALL:!aNULL:RC4+RSA:+HIGH:+MEDIUM:+LOW:+EXP:+eNULL
 101
 102 &lt;Location /strong/area&gt;
 103 # but https://hostname/strong/area/ and below
 104 # requires strong ciphers
 105 SSLCipherSuite HIGH:!aNULL:!MD5
 106 &lt;/Location&gt;
 107     </pre>
 108
 109
 110 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 111 <div class="section">
 112 <h2><a name="accesscontrol" id="accesscontrol">Client Authentication and Access Control</a></h2>
 113
 114 <ul>
 115 <li><a href="#allclients">How can I force clients to authenticate using certificates?</a></li>
 116 <li><a href="#arbitraryclients">How can I force clients to authenticate using certificates for a
 117         particular URL, but still allow arbitrary clients to access the rest of the server?</a></li>
 118 <li><a href="#certauthenticate">How can I allow only clients who have certificates to access a
 119         particular URL, but allow all clients to access the rest of the server?</a></li>
 120 <li><a href="#intranet">How can I require HTTPS with strong ciphers, and either
 121 basic authentication or client certificates, for access to part of the
 122 Intranet website, for clients coming from the Internet?</a></li>
 123 </ul>
 124
 125 <h3><a name="allclients" id="allclients">How can I force clients to authenticate using certificates?</a></h3>
 126
 127
 128     <p>When you know all of your users (eg, as is often the case on a corporate
 129     Intranet), you can require plain certificate authentication. All you
 130     need to do is to create client certificates signed by your own CA
 131     certificate (<code>ca.crt</code>) and then verify the clients against this
 132     certificate.</p>
 133     <pre class="prettyprint lang-config">
 134 # require a client certificate which has to be directly
 135 # signed by our CA certificate in ca.crt
 136 SSLVerifyClient require
 137 SSLVerifyDepth 1
 138 SSLCACertificateFile conf/ssl.crt/ca.crt
 139     </pre>
 140
 141
 142
 143 <h3><a name="arbitraryclients" id="arbitraryclients">How can I force clients to authenticate using certificates for a
 144   particular URL, but still allow arbitrary clients to access the rest of the server?</a></h3>
 145
 146
 147     <p>To force clients to authenticate using certificates for a particular URL,
 148     you can use the per-directory reconfiguration features of
 149     <code class="module"><a href="../mod/mod_ssl.html">mod_ssl</a></code>:</p>
 150
 151     <pre class="prettyprint lang-config">
 152 SSLVerifyClient none
 153 SSLCACertificateFile conf/ssl.crt/ca.crt
 154
 155 &lt;Location /secure/area&gt;
 156 SSLVerifyClient require
 157 SSLVerifyDepth 1
 158 &lt;/Location&gt;
 159     </pre>
 160
 161
 162
 163 <h3><a name="certauthenticate" id="certauthenticate">How can I allow only clients who have certificates to access a
 164   particular URL, but allow all clients to access the rest of the server?</a></h3>
 165
 166
 167     <p>The key to doing this is checking that part of the client certificate
 168     matches what you expect. Usually this means checking all or part of the
 169     Distinguished Name (DN), to see if it contains some known string.
 170     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
 171     <code class="directive"><a href="../mod/mod_ssl.html#sslrequire">SSLRequire</a></code>.</p>
 172
 173     <p>The <code class="module"><a href="../mod/mod_auth_basic.html">mod_auth_basic</a></code> method is generally required when
 174     the certificates are completely arbitrary, or when their DNs have
 175     no common fields (usually the organisation, etc.). In this case,
 176     you should establish a password database containing <em>all</em>
 177     clients allowed, as follows:</p>
 178
 179     <pre class="prettyprint lang-config">
 180 SSLVerifyClient      none
 181 SSLCACertificateFile conf/ssl.crt/ca.crt
 182 SSLCACertificatePath conf/ssl.crt
 183
 184 &lt;Directory /usr/local/apache2/htdocs/secure/area&gt;
 185     SSLVerifyClient      require
 186     SSLVerifyDepth       5
 187     SSLOptions           +FakeBasicAuth
 188     SSLRequireSSL
 189     AuthName             "Snake Oil Authentication"
 190     AuthType             Basic
 191     AuthBasicProvider    file
 192     AuthUserFile         /usr/local/apache2/conf/httpd.passwd
 193     Require              valid-user
 194 &lt;/Directory&gt;
 195     </pre>
 196
 197
 198     <p>The password used in this example is the DES encrypted string "password".
 199     See the <code class="directive"><a href="../mod/mod_ssl.html#ssloptions">SSLOptions</a></code> docs for more
 200     information.</p>
 201
 202     <div class="example"><h3>httpd.passwd</h3><pre>
 203 /C=DE/L=Munich/O=Snake Oil, Ltd./OU=Staff/CN=Foo:xxj31ZMTZzkVA
 204 /C=US/L=S.F./O=Snake Oil, Ltd./OU=CA/CN=Bar:xxj31ZMTZzkVA
 205 /C=US/L=L.A./O=Snake Oil, Ltd./OU=Dev/CN=Quux:xxj31ZMTZzkVA</pre></div>
 206
 207     <p>When your clients are all part of a common hierarchy, which is encoded
 208     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>
 209
 210
 211     <pre class="prettyprint lang-config">
 212 SSLVerifyClient      none
 213 SSLCACertificateFile conf/ssl.crt/ca.crt
 214 SSLCACertificatePath conf/ssl.crt
 215
 216 &lt;Directory /usr/local/apache2/htdocs/secure/area&gt;
 217   SSLVerifyClient      require
 218   SSLVerifyDepth       5
 219   SSLOptions           +FakeBasicAuth
 220   SSLRequireSSL
 221   SSLRequire       %{SSL_CLIENT_S_DN_O}  eq "Snake Oil, Ltd." \
 222                and %{SSL_CLIENT_S_DN_OU} in {"Staff", "CA", "Dev"}
 223 &lt;/Directory&gt;
 224     </pre>
 225
 226
 227
 228 <h3><a name="intranet" id="intranet">How can I require HTTPS with strong ciphers, and either basic
 229 authentication or client certificates, for access to part of the
 230 Intranet website, for clients coming from the Internet? I still want to allow
 231 plain HTTP access for clients on the Intranet.</a></h3>
 232
 233
 234    <p>These examples presume that clients on the Intranet have IPs in the range
 235    192.168.1.0/24, and that the part of the Intranet website you want to allow
 236    internet access to is <code>/usr/local/apache2/htdocs/subarea</code>.
 237    This configuration should remain outside of your HTTPS virtual host, so
 238    that it applies to both HTTPS and HTTP.</p>
 239
 240     <pre class="prettyprint lang-config">
 241 SSLCACertificateFile conf/ssl.crt/company-ca.crt
 242
 243 &lt;Directory /usr/local/apache2/htdocs&gt;
 244     #   Outside the subarea only Intranet access is granted
 245     Order                deny,allow
 246     Deny                 from all
 247     Allow                from 192.168.1.0/24
 248 &lt;/Directory&gt;
 249
 250 &lt;Directory /usr/local/apache2/htdocs/subarea&gt;
 251     #   Inside the subarea any Intranet access is allowed
 252     #   but from the Internet only HTTPS + Strong-Cipher + Password
 253     #   or the alternative HTTPS + Strong-Cipher + Client-Certificate
 254
 255     #   If HTTPS is used, make sure a strong cipher is used.
 256     #   Additionally allow client certs as alternative to basic auth.
 257     SSLVerifyClient      optional
 258     SSLVerifyDepth       1
 259     SSLOptions           +FakeBasicAuth +StrictRequire
 260     SSLRequire           %{SSL_CIPHER_USEKEYSIZE} &gt;= 128
 261
 262     #   Force clients from the Internet to use HTTPS
 263     RewriteEngine        on
 264     RewriteCond          %{REMOTE_ADDR} !^192\.168\.1\.[0-9]+$
 265     RewriteCond          %{HTTPS} !=on
 266     RewriteRule          . - [F]
 267
 268     #   Allow Network Access and/or Basic Auth
 269     Satisfy              any
 270
 271     #   Network Access Control
 272     Order                deny,allow
 273     Deny                 from all
 274     Allow                192.168.1.0/24
 275
 276     #   HTTP Basic Authentication
 277     AuthType             basic
 278     AuthName             "Protected Intranet Area"
 279     AuthBasicProvider    file
 280     AuthUserFile         conf/protected.passwd
 281     Require              valid-user
 282 &lt;/Directory&gt;
 283     </pre>
 284
 285
 286 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 287 <div class="section">
 288 <h2><a name="logging" id="logging">Logging</a></h2>
 289
 290
 291     <p><code class="module"><a href="../mod/mod_ssl.html">mod_ssl</a></code> can log extremely verbose debugging information
 292     to the error log, when its <code class="directive"><a href="../mod/core.html#loglevel">LogLevel</a></code> is
 293     set to the higher trace levels. On the other hand, on a very busy server,
 294     level <code>info</code> may already be too much. Remember that you can
 295     configure the <code class="directive"><a href="../mod/core.html#loglevel">LogLevel</a></code> per module to
 296     suite your needs.</p>
 297 </div></div>
 298 <div class="bottomlang">
 299 <p><span>Available Languages: </span><a href="../en/ssl/ssl_howto.html" title="English">&nbsp;en&nbsp;</a> |
 300 <a href="../fr/ssl/ssl_howto.html" hreflang="fr" rel="alternate" title="Français">&nbsp;fr&nbsp;</a></p>
 301 </div><div class="top"><a href="#page-header"><img src="../images/up.gif" alt="top" /></a></div><div class="section"><h2><a id="comments_section" name="comments_section">Comments</a></h2><div class="warning"><strong>Notice:</strong><br />This is not a Q&amp;A section. Comments placed here should be pointed towards suggestions on improving the documentation or server, and may be removed again by our moderators if they are either implemented or considered invalid/off-topic. Questions on how to manage the Apache HTTP Server should be directed at either our IRC channel, #httpd, on Freenode, or sent to our <a href="http://httpd.apache.org/lists.html">mailing lists</a>.</div>
 302 <script type="text/javascript"><!--//--><![CDATA[//><!--
 303 var comments_shortname = 'httpd';
 304 var comments_identifier = 'http://httpd.apache.org/docs/2.4/ssl/ssl_howto.html';
 305 (function(w, d) {
 306     if (w.location.hostname.toLowerCase() == "httpd.apache.org") {
 307         d.write('<div id="comments_thread"><\/div>');
 308         var s = d.createElement('script');
 309         s.type = 'text/javascript';
 310         s.async = true;
 311         s.src = 'https://comments.apache.org/show_comments.lua?site=' + comments_shortname + '&page=' + comments_identifier;
 312         (d.getElementsByTagName('head')[0] || d.getElementsByTagName('body')[0]).appendChild(s);
 313     }
 314     else {
 315         d.write('<div id="comments_thread">Comments are disabled for this page at the moment.<\/div>');
 316     }
 317 })(window, document);
 318 //--><!]]></script></div><div id="footer">
 319 <p class="apache">Copyright 2012 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>
 320 <p class="menu"><a href="../mod/">Modules</a> | <a href="../mod/directives.html">Directives</a> | <a href="http://wiki.apache.org/httpd/FAQ">FAQ</a> | <a href="../glossary.html">Glossary</a> | <a href="../sitemap.html">Sitemap</a></p></div><script type="text/javascript"><!--//--><![CDATA[//><!--
 321 if (typeof(prettyPrint) !== 'undefined') {
 322     prettyPrint();
 323 }
 324 //--><!]]></script>
 325 </body></html>