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

   1
   2 #use "ssl_template.inc" title="HowTo" tag=howto num=5
   3
   4 <page_prev name="Compatibility" url="ssl_compat.html">
   5 <page_next name="F.A.Q. List"   url="ssl_faq.html">
   6
   7 #use wml::std::toc style=nbsp
   8
   9 <quotation width=200 author="Standard textbook cookie">
  10 ``The solution of this problem is trivial
  11   and is left as an exercise for the reader.''
  12 </quotation>
  13
  14 <p>
  15 <table cellspacing=0 cellpadding=0 border=0>
  16 <tr valign=bottom>
  17 <td>
  18
  19 <big H>ow to solve particular security constraints for an SSL-aware webserver
  20 is not always obvious because of the coherences between SSL, HTTP and Apache's
  21 way of processing requests. This chapter gives instructions on how to solve
  22 such typical situations. Treat is as a first step to find out the final
  23 solution, but always try to understand the stuff before you use it. Nothing is
  24 worse than using a security solution without knowing its restrictions and
  25 coherences.
  26
  27 </td>
  28 <td>
  29 &nbsp;&nbsp;
  30 </td>
  31 <td>
  32
  33 <div align=right>
  34 <table cellspacing=0 cellpadding=5 border=0 bgcolor="#ccccff" width=300>
  35 <tr>
  36 <td bgcolor="#333399">
  37 <font face="Arial,Helvetica" color="#ccccff">
  38 <b>Table Of Contents</b>
  39 </font>
  40 </td>
  41 </tr>
  42 <tr>
  43 <td>
  44 <font face="Arial,Helvetica" size=-1>
  45 <toc>
  46 </font>
  47 </td>
  48 </tr>
  49 </table>
  50 </div>
  51
  52 </td>
  53 </tr>
  54 </table>
  55
  56 #   container tag for layouting a question
  57 <define-tag howto endtag=required>
  58 <preserve ref>
  59 <preserve toc>
  60 <set-var %attributes>
  61 <p>
  62 <li><toc_h3 alt="<get-var toc>"></toc_h3>
  63     <a name="<get-var ref>"></a>
  64     <strong id="howto">%body</strong>\
  65     &nbsp;&nbsp;
  66     [<a href="http://www.modssl.org/docs/2.8/ssl_howto.html#<get-var ref>"><b>L</b></a>]
  67     <p>
  68 <restore toc>
  69 <restore ref>
  70 </define-tag>
  71
  72 <define-tag config endtag=required>
  73 <preserve file>
  74 <set-var %attributes>
  75 <ifeq "<get-var file>" "" <set-var file="httpd.conf">>
  76 <box header="<font face="Arial,Helvetica" color="#999999"><get-var file></font>"
  77      bdwidth=1 bdcolor="#cccccc" bgcolor="#ffffff" fgcolor="#000000">
  78 <pre>
  79 %body
  80 </pre>
  81 </box>\
  82 <restore file>
  83 </define-tag>
  84
  85 <h2>Cipher Suites and Enforced Strong Security</h2>
  86
  87 <ul>
  88
  89 <howto ref="cipher-sslv2" toc="SSLv2 only server">
  90 How can I create a real SSLv2-only server?
  91 </howto>
  92
  93 The following creates an SSL server which speaks only the SSLv2 protocol and
  94 its ciphers.
  95
  96 <p>
  97 <config>
  98 SSLProtocol -all +SSLv2
  99 SSLCipherSuite SSLv2:+HIGH:+MEDIUM:+LOW:+EXP
 100 </config>
 101
 102 <howto ref="cipher-strong" toc="strong encryption only server">
 103 How can I create an SSL server which accepts strong encryption only?
 104 </howto>
 105
 106 The following enables only the seven strongest ciphers:
 107
 108 <p>
 109 <config>
 110 SSLProtocol all
 111 SSLCipherSuite HIGH:MEDIUM
 112 </config>
 113
 114 <howto ref="cipher-sgc" toc="server gated cryptography">
 115 How can I create an SSL server which accepts strong encryption only,
 116 but allows export browsers to upgrade to stronger encryption?
 117 </howto>
 118
 119 This facility is called Server Gated Cryptography (SGC) and details you can
 120 find in the <code>README.GlobalID</code> document in the mod_ssl distribution.
 121 In short: The server has a Global ID server certificate, signed by a special
 122 CA certificate from Verisign which enables strong encryption in export
 123 browsers. This works as following: The browser connects with an export cipher,
 124 the server sends its Global ID certificate, the browser verifies it and
 125 subsequently upgrades the cipher suite before any HTTP communication takes
 126 place. The question now is: How can we allow this upgrade, but enforce strong
 127 encryption. Or in other words: Browser either have to initially connect with
 128 strong encryption or have to upgrade to strong encryption, but are not allowed
 129 to keep the export ciphers. The following does the trick:
 130
 131 <p>
 132 <config>
 133 \#   allow all ciphers for the inital handshake,
 134 \#   so export browsers can upgrade via SGC facility
 135 SSLCipherSuite ALL:!ADH:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP:+eNULL
 136 &lt;Directory /usr/local/apache/htdocs&gt;
 137 \#   but finally deny all browsers which haven't upgraded
 138 SSLRequire %{SSL_CIPHER_USEKEYSIZE} &gt;= 128
 139 &lt;/Directory&gt;
 140 </config>
 141
 142 <howto ref="cipher-perdir" toc="stronger per-directory requirements">
 143 How can I create an SSL server which accepts all types of ciphers in general,
 144 but requires a strong ciphers for access to a particular URL?
 145 </howto>
 146
 147 Obviously you cannot just use a server-wide <code>SSLCipherSuite</code> which
 148 restricts the ciphers to the strong variants. But mod_ssl allows you to
 149 reconfigure the cipher suite in per-directory context and automatically forces
 150 a renegotiation of the SSL parameters to meet the new configuration. So, the
 151 solution is:
 152
 153 <p>
 154 <config>
 155 \#   be liberal in general
 156 SSLCipherSuite ALL:!ADH:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP:+eNULL
 157 &lt;Location /strong/area&gt;
 158 \#   but https://hostname/strong/area/ and below requires strong ciphers
 159 SSLCipherSuite HIGH:MEDIUM
 160 &lt;/Location&gt;
 161 </config>
 162
 163 </ul>
 164
 165 <h2>Client Authentication and Access Control</h2>
 166
 167 <ul>
 168
 169 <howto ref="auth-simple" toc="simple certificate-based client authentication">
 170 How can I authenticate clients based on certificates when I know all my
 171 clients?
 172 </howto>
 173
 174 When you know your user community (i.e. a closed user group situation), as
 175 it's the case for instance in an Intranet, you can use plain certificate
 176 authentication. All you have to do is to create client certificates signed by
 177 your own CA certificate <code>ca.crt</code> and then verifiy the clients
 178 against this certificate.
 179
 180 <p>
 181 <config>
 182 \#   require a client certificate which has to be directly
 183 \#   signed by our CA certificate in ca.crt
 184 SSLVerifyClient require
 185 SSLVerifyDepth 1
 186 SSLCACertificateFile conf/ssl.crt/ca.crt
 187 </config>
 188
 189 <howto ref="auth-selective" toc="selective certificate-based client authentication">
 190 How can I authenticate my clients for a particular URL based on certificates
 191 but still allow arbitrary clients to access the remaining parts of the server?
 192 </howto>
 193
 194 For this we again use the per-directory reconfiguration feature of mod_ssl:
 195
 196 <p>
 197 <config>
 198 SSLVerifyClient none
 199 SSLCACertificateFile conf/ssl.crt/ca.crt
 200 &lt;Location /secure/area&gt;
 201 SSLVerifyClient require
 202 SSLVerifyDepth 1
 203 &lt;/Location&gt;
 204 </config>
 205
 206 <howto ref="auth-particular" toc="particular certificate-based client authentication">
 207 How can I authenticate only particular clients for a some URLs based
 208 on certificates but still allow arbitrary clients to access the remaining
 209 parts of the server?
 210 </howto>
 211
 212 The key is to check for various ingredients of the client certficate.  Usually
 213 this means to check the whole or part of the Distinguished Name (DN) of the
 214 Subject.  For this two methods exists: The <code>mod_auth</code> based variant
 215 and the <code>SSLRequire</code> variant. The first method is good when the
 216 clients are of totally different type, i.e. when their DNs have no common
 217 fields (usually the organisation, etc.). In this case you've to establish a
 218 password database containing <em>all</em> clients. The second method is better
 219 when your clients are all part of a common hierarchy which is encoded into the
 220 DN. Then you can match them more easily.
 221
 222 <p>
 223 The first method:
 224
 225 <p>
 226 <config file="/usr/local/apache/conf/httpd.conf">
 227 SSLVerifyClient      none
 228 &lt;Directory /usr/local/apache/htdocs/secure/area&gt;
 229 SSLVerifyClient      require
 230 SSLVerifyDepth       5
 231 SSLCACertificateFile conf/ssl.crt/ca.crt
 232 SSLCACertificatePath conf/ssl.crt
 233 SSLOptions           +FakeBasicAuth
 234 SSLRequireSSL
 235 AuthName             "Snake Oil Authentication"
 236 AuthType             Basic
 237 AuthUserFile         /usr/local/apache/conf/httpd.passwd
 238 require              valid-user
 239 &lt;/Directory&gt;
 240 </config>
 241
 242 <p>
 243 <config file="/usr/local/apache/conf/httpd.passwd">
 244 /C=DE/L=Munich/O=Snake Oil, Ltd./OU=Staff/CN=Foo:xxj31ZMTZzkVA
 245 /C=US/L=S.F./O=Snake Oil, Ltd./OU=CA/CN=Bar:xxj31ZMTZzkVA
 246 /C=US/L=L.A./O=Snake Oil, Ltd./OU=Dev/CN=Quux:xxj31ZMTZzkVA
 247 </config>
 248
 249 <p>
 250 The second method:
 251
 252 <p>
 253 <config>
 254 SSLVerifyClient      none
 255 &lt;Directory /usr/local/apache/htdocs/secure/area&gt;
 256 SSLVerifyClient      require
 257 SSLVerifyDepth       5
 258 SSLCACertificateFile conf/ssl.crt/ca.crt
 259 SSLCACertificatePath conf/ssl.crt
 260 SSLOptions           +FakeBasicAuth
 261 SSLRequireSSL
 262 SSLRequire           %{SSL_CLIENT_S_DN_O}  eq "Snake Oil, Ltd." and \\
 263                      %{SSL_CLIENT_S_DN_OU} in {"Staff", "CA", "Dev"}
 264 &lt;/Directory&gt;
 265 </config>
 266
 267 <howto ref="auth-intranet" toc="intranet vs. internet authentication"> How can
 268 I require HTTPS with strong ciphers and either basic authentication or client
 269 certificates for access to a subarea on the Intranet website for clients
 270 coming from the Internet but still allow plain HTTP access for clients on the
 271 Intranet?
 272 </howto>
 273
 274 Let us assume the Intranet can be distinguished through the IP network
 275 192.160.1.0/24 and the subarea on the Intranet website has the URL
 276 <tt>/subarea</tt>. Then configure the following outside your HTTPS virtual
 277 host (so it applies to both HTTPS and HTTP):
 278
 279 <p>
 280 <config>
 281 SSLCACertificateFile conf/ssl.crt/company-ca.crt
 282
 283 &lt;Directory /usr/local/apache/htdocs&gt;
 284 \#   Outside the subarea only Intranet access is granted
 285 Order                deny,allow
 286 Deny                 from all
 287 Allow                from 192.168.1.0/24
 288 &lt;/Directory&gt;
 289
 290 &lt;Directory /usr/local/apache/htdocs/subarea&gt;
 291 \#   Inside the subarea any Intranet access is allowed
 292 \#   but from the Internet only HTTPS + Strong-Cipher + Password
 293 \#   or the alternative HTTPS + Strong-Cipher + Client-Certificate
 294
 295 \#   If HTTPS is used, make sure a strong cipher is used.
 296 \#   Additionally allow client certs as alternative to basic auth.
 297 SSLVerifyClient      optional
 298 SSLVerifyDepth       1
 299 SSLOptions           +FakeBasicAuth +StrictRequire
 300 SSLRequire           %{SSL_CIPHER_USEKEYSIZE} &gt;= 128
 301
 302 \#   Force clients from the Internet to use HTTPS
 303 RewriteEngine        on
 304 RewriteCond          %{REMOTE_ADDR} !^192\.168\.1\.[0-9]+$
 305 RewriteCond          %{HTTPS} !=on
 306 RewriteRule          .* - [F]
 307
 308 \#   Allow Network Access and/or Basic Auth
 309 Satisfy              any
 310
 311 \#   Network Access Control
 312 Order                deny,allow
 313 Deny                 from all
 314 Allow                192.168.1.0/24
 315
 316 \#   HTTP Basic Authentication
 317 AuthType             basic
 318 AuthName             "Protected Intranet Area"
 319 AuthUserFile         conf/protected.passwd
 320 Require              valid-user
 321 &lt;/Directory&gt;
 322 </config>
 323
 324 </ul>
 325