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 <manualpage metafile="ssl_howto.xml.meta">
   5 <parentdocument href="./">SSL/TLS</parentdocument>
   6
   7   <title>SSL/TLS Strong Encryption: How-To</title>
   8
   9 <summary>
  10 <blockquote>
  11 <p>The solution of this problem is trivial
  12 and is left as an exercise for the reader.</p>
  13
  14 <p class="cite">-- <cite>Standard textbook cookie</cite></p>
  15 </blockquote>
  16
  17 <p>How to solve particular security constraints for an SSL-aware
  18 webserver is not always obvious because of the coherences between SSL,
  19 HTTP and Apache's way of processing requests. This chapter gives
  20 instructions on how to solve such typical situations. Treat is as a first
  21 step to find out the final solution, but always try to understand the
  22 stuff before you use it. Nothing is worse than using a security solution
  23 without knowing its restrictions and coherences.</p>
  24 </summary>
  25
  26 <section id="ciphersuites">
  27 <title>Cipher Suites and Enforced Strong Security</title>
  28 <ul>
  29 <li><a href="#realssl">SSLv2 only server</a></li>
  30 <li><a href="#onlystrong">strong encryption only server</a></li>
  31 <li><a href="#upgradeenc">server gated cryptography</a></li>
  32 <li><a href="#strongurl">stronger per-directory requirements</a></li>
  33 </ul>
  34
  35 <section id="realssl">
  36 <title>How can I create a real SSLv2-only server?</title>
  37     <p>The following creates an SSL server which speaks only the SSLv2 protocol and
  38     its ciphers.</p>
  39
  40     <example><title>httpd.conf</title>
  41       SSLProtocol -all +SSLv2<br />
  42       SSLCipherSuite SSLv2:+HIGH:+MEDIUM:+LOW:+EXP<br />
  43     </example>
  44 </section>
  45
  46 <section id="onlystrong">
  47 <title>How can I create an SSL server which accepts strong encryption
  48 only?</title>
  49     <p>The following enables only the seven strongest ciphers:</p>
  50     <example><title>httpd.conf</title>
  51       SSLProtocol all<br />
  52       SSLCipherSuite HIGH:MEDIUM<br />
  53     </example>
  54 </section>
  55
  56 <section id="upgradeenc">
  57 <title>How can I create an SSL server which accepts strong encryption
  58 only, but allows export browsers to upgrade to stronger encryption?</title>
  59     <p>This facility is called Server Gated Cryptography (SGC) and details
  60     you can find in the <code>README.GlobalID</code> document in the
  61     mod_ssl distribution. In short: The server has a Global ID server
  62     certificate, signed by a special CA certificate from Verisign which
  63     enables strong encryption in export browsers. This works as following:
  64     The browser connects with an export cipher, the server sends its Global
  65     ID certificate, the browser verifies it and subsequently upgrades the
  66     cipher suite before any HTTP communication takes place. The question
  67     now is: How can we allow this upgrade, but enforce strong encryption.
  68     Or in other words: Browser either have to initially connect with
  69     strong encryption or have to upgrade to strong encryption, but are
  70     not allowed to keep the export ciphers. The following does the trick:</p>
  71     <example><title>httpd.conf</title>
  72       # allow all ciphers for the initial handshake,<br />
  73       # so export browsers can upgrade via SGC facility<br />
  74       SSLCipherSuite ALL:!ADH:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP:+eNULL<br />
  75       <br />
  76       &lt;Directory /usr/local/apache2/htdocs&gt;<br />
  77       # but finally deny all browsers which haven't upgraded<br />
  78       SSLRequire %{SSL_CIPHER_USEKEYSIZE} &gt;= 128<br />
  79       &lt;/Directory&gt;
  80     </example>
  81 </section>
  82
  83 <section id="strongurl">
  84 <title>How can I create an SSL server which accepts all types of ciphers
  85 in general, but requires a strong ciphers for access to a particular
  86 URL?</title>
  87     <p>Obviously you cannot just use a server-wide <directive
  88     module="mod_ssl">SSLCipherSuite</directive> which restricts the
  89     ciphers to the strong variants. But mod_ssl allows you to reconfigure
  90     the cipher suite in per-directory context and automatically forces
  91     a renegotiation of the SSL parameters to meet the new configuration.
  92     So, the solution is:</p>
  93     <example>
  94       # be liberal in general<br />
  95       SSLCipherSuite ALL:!ADH:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP:+eNULL<br />
  96       <br />
  97       &lt;Location /strong/area&gt;<br />
  98       # but https://hostname/strong/area/ and below<br />
  99       # requires strong ciphers<br />
 100       SSLCipherSuite HIGH:MEDIUM<br />
 101       &lt;/Location&gt;
 102     </example>
 103 </section>
 104 </section>
 105 <!-- /ciphersuites -->
 106
 107 <section id="accesscontrol">
 108 <title>Client Authentication and Access Control</title>
 109 <ul>
 110 <li><a href="#allclients">simple certificate-based client authentication</a></li>
 111 <li><a href="#arbitraryclients">selective certificate-based client authentication</a></li>
 112 <li><a href="#certauthenticate">particular certificate-based client authentication</a></li>
 113 <li><a href="#intranet">intranet vs. internet authentication</a></li>
 114 </ul>
 115
 116 <section id="allclients">
 117 <title>How can I authenticate clients based on certificates when I know
 118 all my clients?</title>
 119     <p>When you know your user community (i.e. a closed user group
 120     situation), as it's the case for instance in an Intranet, you can
 121     use plain certificate authentication. All you have to do is to
 122     create client certificates signed by your own CA certificate
 123     <code>ca.crt</code> and then verify the clients against this
 124     certificate.</p>
 125     <example><title>httpd.conf</title>
 126       # require a client certificate which has to be directly<br />
 127       # signed by our CA certificate in ca.crt<br />
 128       SSLVerifyClient require<br />
 129       SSLVerifyDepth 1<br />
 130       SSLCACertificateFile conf/ssl.crt/ca.crt
 131     </example>
 132 </section>
 133
 134 <section id="arbitraryclients">
 135 <title>How can I authenticate my clients for a particular URL based on
 136 certificates but still allow arbitrary clients to access the remaining
 137 parts of the server?</title>
 138     <p>For this we again use the per-directory reconfiguration feature
 139     of <module>mod_ssl</module>:</p>
 140
 141     <example><title>httpd.conf</title>
 142     SSLVerifyClient none<br />
 143     SSLCACertificateFile conf/ssl.crt/ca.crt<br />
 144     <br />
 145     &lt;Location /secure/area&gt;<br />
 146     SSLVerifyClient require<br />
 147     SSLVerifyDepth 1<br />
 148     &lt;/Location&gt;<br />
 149     </example>
 150 </section>
 151
 152 <section id="certauthenticate">
 153 <title>How can I authenticate only particular clients for a some URLs based
 154 on certificates but still allow arbitrary clients to access the remaining
 155 parts of the server?</title>
 156     <p>The key is to check for various ingredients of the client certificate.
 157     Usually this means to check the whole or part of the Distinguished
 158     Name (DN) of the Subject. For this two methods exists: The <module
 159     >mod_auth_basic</module> based variant and the <directive
 160     module="mod_ssl">SSLRequire</directive> variant. The first method is
 161     good when the clients are of totally different type, i.e. when their
 162     DNs have no common fields (usually the organisation, etc.). In this
 163     case you've to establish a password database containing <em>all</em>
 164     clients. The second method is better when your clients are all part of
 165     a common hierarchy which is encoded into the DN. Then you can match
 166     them more easily.</p>
 167
 168     <p>The first method:</p>
 169     <example><title>httpd.conf</title><pre>
 170 SSLVerifyClient      none
 171 &lt;Directory /usr/local/apache2/htdocs/secure/area&gt;
 172
 173 SSLVerifyClient      require
 174 SSLVerifyDepth       5
 175 SSLCACertificateFile conf/ssl.crt/ca.crt
 176 SSLCACertificatePath conf/ssl.crt
 177 SSLOptions           +FakeBasicAuth
 178 SSLRequireSSL
 179 AuthName             "Snake Oil Authentication"
 180 AuthType             Basic
 181 AuthBasicProvider    file
 182 AuthUserFile         /usr/local/apache2/conf/httpd.passwd
 183 require              valid-user
 184 &lt;/Directory&gt;</pre>
 185     </example>
 186
 187     <example><title>httpd.passwd</title><pre>
 188 /C=DE/L=Munich/O=Snake Oil, Ltd./OU=Staff/CN=Foo:xxj31ZMTZzkVA
 189 /C=US/L=S.F./O=Snake Oil, Ltd./OU=CA/CN=Bar:xxj31ZMTZzkVA
 190 /C=US/L=L.A./O=Snake Oil, Ltd./OU=Dev/CN=Quux:xxj31ZMTZzkVA</pre>
 191     </example>
 192
 193     <p>The second method:</p>
 194
 195     <example><title>httpd.conf</title><pre>
 196 SSLVerifyClient      none
 197 &lt;Directory /usr/local/apache2/htdocs/secure/area&gt;
 198
 199   SSLVerifyClient      require
 200   SSLVerifyDepth       5
 201   SSLCACertificateFile conf/ssl.crt/ca.crt
 202   SSLCACertificatePath conf/ssl.crt
 203   SSLOptions           +FakeBasicAuth
 204   SSLRequireSSL
 205   SSLRequire       %{SSL_CLIENT_S_DN_O}  eq "Snake Oil, Ltd." \
 206                and %{SSL_CLIENT_S_DN_OU} in {"Staff", "CA", "Dev"}
 207 &lt;/Directory&gt;</pre>
 208     </example>
 209 </section>
 210
 211 <section id="intranet">
 212 <title>How can I require HTTPS with strong ciphers and either basic
 213 authentication or client certificates for access to a subarea on the
 214 Intranet website for clients coming from the Internet but still allow
 215 plain HTTP access for clients on the Intranet?</title>
 216    <p>Let us assume the Intranet can be distinguished through the IP
 217    network 192.160.1.0/24 and the subarea on the Intranet website has
 218    the URL <code>/subarea</code>. Then configure the following outside
 219    your HTTPS virtual host (so it applies to both HTTPS and HTTP):</p>
 220
 221     <example><title>httpd.conf</title><pre>
 222 SSLCACertificateFile conf/ssl.crt/company-ca.crt
 223
 224 &lt;Directory /usr/local/apache2/htdocs&gt;
 225 #   Outside the subarea only Intranet access is granted
 226 Order                deny,allow
 227 Deny                 from all
 228 Allow                from 192.168.1.0/24
 229 &lt;/Directory&gt;
 230
 231 &lt;Directory /usr/local/apache2/htdocs/subarea&gt;
 232 #   Inside the subarea any Intranet access is allowed
 233 #   but from the Internet only HTTPS + Strong-Cipher + Password
 234 #   or the alternative HTTPS + Strong-Cipher + Client-Certificate
 235
 236 #   If HTTPS is used, make sure a strong cipher is used.
 237 #   Additionally allow client certs as alternative to basic auth.
 238 SSLVerifyClient      optional
 239 SSLVerifyDepth       1
 240 SSLOptions           +FakeBasicAuth +StrictRequire
 241 SSLRequire           %{SSL_CIPHER_USEKEYSIZE} &gt;= 128
 242
 243 #   Force clients from the Internet to use HTTPS
 244 RewriteEngine        on
 245 RewriteCond          %{REMOTE_ADDR} !^192\.168\.1\.[0-9]+$
 246 RewriteCond          %{HTTPS} !=on
 247 RewriteRule          .* - [F]
 248
 249 #   Allow Network Access and/or Basic Auth
 250 Satisfy              any
 251
 252 #   Network Access Control
 253 Order                deny,allow
 254 Deny                 from all
 255 Allow                192.168.1.0/24
 256
 257 #   HTTP Basic Authentication
 258 AuthType             basic
 259 AuthName             "Protected Intranet Area"
 260 AuthBasicProvider    file
 261 AuthUserFile         conf/protected.passwd
 262 Require              valid-user
 263 &lt;/Directory&gt;</pre>
 264     </example>
 265 </section>
 266 </section>
 267 <!-- /access control -->
 268
 269 </manualpage>
 270
 271
 272