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: FAQ - 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.min.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="<-" alt="<-" src="/images/left.gif" /></a></div> 21<div id="path"> 22<a href="http://www.apache.org/">Apache</a> > <a href="http://httpd.apache.org/">HTTP Server</a> > <a href="http://httpd.apache.org/docs/">Documentation</a> > <a href="../">Version 2.4</a> > <a href="./">SSL/TLS</a></div><div id="page-content"><div id="preamble"><h1>SSL/TLS Strong Encryption: FAQ</h1> 23<div class="toplang"> 24<p><span>Available Languages: </span><a href="/en/ssl/ssl_faq.html" title="English"> en </a> | 25<a href="/fr/ssl/ssl_faq.html" hreflang="fr" rel="alternate" title="Fran�ais"> fr </a></p> 26</div> 27 28<blockquote> 29<p>The wise man doesn't give the right answers, 30he poses the right questions.</p> 31<p class="cite">-- <cite>Claude Levi-Strauss</cite></p> 32 33</blockquote> 34</div> 35<div id="quickview"><ul id="toc"><li><img alt="" src="/images/down.gif" /> <a href="#installation">Installation</a></li> 36<li><img alt="" src="/images/down.gif" /> <a href="#aboutconfig">Configuration</a></li> 37<li><img alt="" src="/images/down.gif" /> <a href="#aboutcerts">Certificates</a></li> 38<li><img alt="" src="/images/down.gif" /> <a href="#aboutssl">The SSL Protocol</a></li> 39<li><img alt="" src="/images/down.gif" /> <a href="#support">mod_ssl Support</a></li> 40</ul><ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div> 41<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 42<div class="section"> 43<h2><a name="installation" id="installation">Installation</a></h2> 44<ul> 45<li><a href="#mutex">Why do I get permission errors related to 46SSLMutex when I start Apache?</a></li> 47<li><a href="#entropy">Why does mod_ssl stop with the error "Failed to 48generate temporary 512 bit RSA private key" when I start Apache?</a></li> 49</ul> 50 51<h3><a name="mutex" id="mutex">Why do I get permission errors related to 52 SSLMutex when I start Apache?</a></h3> 53 <p>Errors such as ``<code>mod_ssl: Child could not open 54 SSLMutex lockfile /opt/apache/logs/ssl_mutex.18332 (System error follows) 55 [...] System: Permission denied (errno: 13)</code>'' are usually 56 caused by overly restrictive permissions on the <em>parent</em> directories. 57 Make sure that all parent directories (here <code>/opt</code>, 58 <code>/opt/apache</code> and <code>/opt/apache/logs</code>) have the x-bit 59 set for, at minimum, the UID under which Apache's children are running (see 60 the <code class="directive"><a href="/mod/mod_unixd.html#user">User</a></code> directive).</p> 61 62 63<h3><a name="entropy" id="entropy">Why does mod_ssl stop with the error 64 "Failed to generate temporary 512 bit RSA private key" when I start 65 Apache?</a></h3> 66 <p>Cryptographic software needs a source of unpredictable data 67 to work correctly. Many open source operating systems provide 68 a "randomness device" that serves this purpose (usually named 69 <code>/dev/random</code>). On other systems, applications have to 70 seed the OpenSSL Pseudo Random Number Generator (PRNG) manually with 71 appropriate data before generating keys or performing public key 72 encryption. As of version 0.9.5, the OpenSSL functions that need 73 randomness report an error if the PRNG has not been seeded with 74 at least 128 bits of randomness.</p> 75 <p>To prevent this error, <code class="module"><a href="/mod/mod_ssl.html">mod_ssl</a></code> has to provide 76 enough entropy to the PRNG to allow it to work correctly. This can 77 be done via the <code class="directive"><a href="/mod/mod_ssl.html#sslrandomseed">SSLRandomSeed</a></code> 78 directive.</p> 79 80</div><div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 81<div class="section"> 82<h2><a name="aboutconfig" id="aboutconfig">Configuration</a></h2> 83<ul> 84<li><a href="#parallel">Is it possible to provide HTTP and HTTPS from 85the same server?</a></li> 86<li><a href="#ports">Which port does HTTPS use?</a></li> 87<li><a href="#httpstest">How do I speak HTTPS manually for testing 88purposes?</a></li> 89<li><a href="#hang">Why does the connection hang when I connect to my 90SSL-aware Apache server?</a></li> 91<li><a href="#refused">Why do I get ``Connection Refused'' errors, when 92trying to access my newly installed Apache+mod_ssl server via HTTPS?</a></li> 93<li><a href="#envvars">Why are the <code>SSL_XXX</code> variables not 94available to my CGI & SSI scripts?</a></li> 95<li><a href="#relative">How can I switch between HTTP and HTTPS in 96relative hyperlinks?</a></li> 97</ul> 98 99<h3><a name="parallel" id="parallel">Is it possible to provide HTTP and HTTPS 100 from the same server?</a></h3> 101 <p>Yes. HTTP and HTTPS use different server ports (HTTP binds to 102 port 80, HTTPS to port 443), so there is no direct conflict between 103 them. You can either run two separate server instances bound to 104 these ports, or use Apache's elegant virtual hosting facility to 105 create two virtual servers, both served by the same instance of Apache 106 - one responding over HTTP to requests on port 80, and the other 107 responding over HTTPS to requests on port 443.</p> 108 109 110<h3><a name="ports" id="ports">Which port does HTTPS use?</a></h3> 111<p>You can run HTTPS on any port, but the standards specify port 443, which 112 is where any HTTPS compliant browser will look by default. You can force 113 your browser to look on a different port by specifying it in the URL. For 114 example, if your server is set up to serve pages over HTTPS on port 8080, 115 you can access them at <code>https://example.com:8080/</code></p> 116 117 118<h3><a name="httpstest" id="httpstest">How do I speak HTTPS manually for testing purposes?</a></h3> 119 <p>While you usually just use</p> 120 121 <div class="example"><p><code>$ telnet localhost 80<br /> 122 GET / HTTP/1.0</code></p></div> 123 124 <p>for simple testing of Apache via HTTP, it's not so easy for 125 HTTPS because of the SSL protocol between TCP and HTTP. With the 126 help of OpenSSL's <code>s_client</code> command, however, you can 127 do a similar check via HTTPS:</p> 128 129 <div class="example"><p><code>$ openssl s_client -connect localhost:443 -state -debug<br /> 130 GET / HTTP/1.0</code></p></div> 131 132 <p>Before the actual HTTP response you will receive detailed 133 information about the SSL handshake. For a more general command 134 line client which directly understands both HTTP and HTTPS, can 135 perform GET and POST operations, can use a proxy, supports byte 136 ranges, etc. you should have a look at the nifty 137 <a href="http://curl.haxx.se/">cURL</a> tool. Using this, you can 138 check that Apache is responding correctly to requests via HTTP and 139 HTTPS as follows:</p> 140 141 <div class="example"><p><code>$ curl http://localhost/<br /> 142 $ curl https://localhost/</code></p></div> 143 144 145<h3><a name="hang" id="hang">Why does the connection hang when I connect 146 to my SSL-aware Apache server?</a></h3> 147 148<p>This can happen when you try to connect to a HTTPS server (or virtual 149 server) via HTTP (eg, using <code>http://example.com/</code> instead of 150 <code>https://example.com</code>). It can also happen when trying to 151 connect via HTTPS to a HTTP server (eg, using 152 <code>https://example.com/</code> on a server which doesn't support HTTPS, 153 or which supports it on a non-standard port). Make sure that you're 154 connecting to a (virtual) server that supports SSL.</p> 155 156<h3><a name="refused" id="refused">Why do I get ``Connection Refused'' messages, 157 when trying to access my newly installed Apache+mod_ssl server via HTTPS?</a></h3> 158<p> 159 This error can be caused by an incorrect configuration. 160 Please make sure that your <code class="directive"><a href="/mod/mpm_common.html#listen">Listen</a></code> directives match your 161 <code class="directive"><a href="/mod/core.html#virtualhost"><VirtualHost></a></code> 162 directives. If all else fails, please start afresh, using the default 163 configuration provided by <code class="module"><a href="/mod/mod_ssl.html">mod_ssl</a></code>.</p> 164 165 166<h3><a name="envvars" id="envvars">Why are the <code>SSL_XXX</code> variables 167 not available to my CGI & SSI scripts?</a></h3> 168<p>Please make sure you have ``<code>SSLOptions +StdEnvVars</code>'' 169 enabled for the context of your CGI/SSI requests.</p> 170 171 172<h3><a name="relative" id="relative">How can I switch between HTTP and HTTPS in relative 173 hyperlinks?</a></h3> 174 175<p>Usually, to switch between HTTP and HTTPS, you have to use 176 fully-qualified hyperlinks (because you have to change the URL 177 scheme). Using <code class="module"><a href="/mod/mod_rewrite.html">mod_rewrite</a></code> however, you can 178 manipulate relative hyperlinks, to achieve the same effect.</p> 179 <pre class="prettyprint lang-config">RewriteEngine on 180RewriteRule ^/(.*)_SSL$ https://%{SERVER_NAME}/$1 [R,L] 181RewriteRule ^/(.*)_NOSSL$ http://%{SERVER_NAME}/$1 [R,L]</pre> 182 183 184 <p>This rewrite ruleset lets you use hyperlinks of the form 185 <code><a href="document.html_SSL"></code>, to switch to HTTPS 186 in a relative link. (Replace SSL with NOSSL to switch to HTTP.)</p> 187 188</div><div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 189<div class="section"> 190<h2><a name="aboutcerts" id="aboutcerts">Certificates</a></h2> 191<ul> 192<li><a href="#keyscerts">What are RSA Private Keys, CSRs and 193Certificates?</a></li> 194<li><a href="#startup">Is there a difference on startup between 195a non-SSL-aware Apache and an SSL-aware Apache?</a></li> 196<li><a href="#selfcert">How do I create a self-signed SSL 197Certificate for testing purposes?</a></li> 198<li><a href="#realcert">How do I create a real SSL Certificate?</a></li> 199<li><a href="#ownca">How do I create and use my own Certificate 200Authority (CA)?</a></li> 201<li><a href="#passphrase">How can I change the pass-phrase on my private 202key file?</a></li> 203<li><a href="#removepassphrase">How can I get rid of the pass-phrase 204dialog at Apache startup time?</a></li> 205<li><a href="#verify">How do I verify that a private key matches its 206Certificate?</a></li> 207<li><a href="#pemder">How can I convert a certificate from PEM to DER 208format?</a></li> 209<li><a href="#gid">Why do browsers complain that they cannot 210verify my server certificate?</a></li> 211</ul> 212 213<h3><a name="keyscerts" id="keyscerts">What are RSA Private Keys, CSRs and Certificates?</a></h3> 214<p>An RSA private key file is a digital file that you can use to decrypt 215 messages sent to you. It has a public component which you distribute (via 216 your Certificate file) which allows people to encrypt those messages to 217 you.</p> 218 <p>A Certificate Signing Request (CSR) is a digital file which contains 219 your public key and your name. You send the CSR to a Certifying Authority 220 (CA), who will convert it into a real Certificate, by signing it.</p> 221 <p>A Certificate contains your 222 RSA public key, your name, the name of the CA, and is digitally signed by 223 the CA. Browsers that know the CA can verify the signature on that 224 Certificate, thereby obtaining your RSA public key. That enables them to 225 send messages which only you can decrypt.</p> 226 <p>See the <a href="ssl_intro.html">Introduction</a> chapter for a general 227 description of the SSL protocol.</p> 228 229 230<h3><a name="startup" id="startup">Is there a difference on startup between 231 a non-SSL-aware Apache and an SSL-aware Apache?</a></h3> 232<p>Yes. In general, starting Apache with 233 <code class="module"><a href="/mod/mod_ssl.html">mod_ssl</a></code> built-in is just like starting Apache 234 without it. However, if you have a passphrase on your SSL private 235 key file, a startup dialog will pop up which asks you to enter the 236 pass phrase.</p> 237 238 <p>Having to manually enter the passphrase when starting the server 239 can be problematic - for example, when starting the server from the 240 system boot scripts. In this case, you can follow the steps 241 <a href="#removepassphrase">below</a> to remove the passphrase from 242 your private key. Bear in mind that doing so brings additional security 243 risks - proceed with caution!</p> 244 245 246<h3><a name="selfcert" id="selfcert">How do I create a self-signed SSL 247Certificate for testing purposes?</a></h3> 248 <ol> 249 <li>Make sure OpenSSL is installed and in your <code>PATH</code>.<br /> 250 <br /> 251 </li> 252 <li>Run the following command, to create <code>server.key</code> and 253 <code>server.crt</code> files:<br /> 254 <code><strong>$ openssl req -new -x509 -nodes -out server.crt 255 -keyout server.key</strong></code><br /> 256 These can be used as follows in your <code>httpd.conf</code> 257 file: 258 <pre class="prettyprint lang-config">SSLCertificateFile /path/to/this/server.crt 259SSLCertificateKeyFile /path/to/this/server.key</pre> 260 261 </li> 262 <li>It is important that you are aware that this 263 <code>server.key</code> does <em>not</em> have any passphrase. 264 To add a passphrase to the key, you should run the following 265 command, and enter & verify the passphrase as requested.<br /> 266 <p><code><strong>$ openssl rsa -des3 -in server.key -out 267 server.key.new</strong></code><br /> 268 <code><strong>$ mv server.key.new server.key</strong></code><br /></p> 269 Please backup the <code>server.key</code> file, and the passphrase 270 you entered, in a secure location. 271 </li> 272 </ol> 273 274 275<h3><a name="realcert" id="realcert">How do I create a real SSL Certificate?</a></h3> 276<p>Here is a step-by-step description:</p> 277 <ol> 278 <li>Make sure OpenSSL is installed and in your <code>PATH</code>. 279 <br /> 280 <br /> 281 </li> 282 <li>Create a RSA private key for your Apache server 283 (will be Triple-DES encrypted and PEM formatted):<br /> 284 <br /> 285 <code><strong>$ openssl genrsa -des3 -out server.key 2048</strong></code><br /> 286 <br /> 287 Please backup this <code>server.key</code> file and the 288 pass-phrase you entered in a secure location. 289 You can see the details of this RSA private key by using the command:<br /> 290 291 <br /> 292 <code><strong>$ openssl rsa -noout -text -in server.key</strong></code><br /> 293 <br /> 294 If necessary, you can also create a decrypted PEM version (not 295 recommended) of this RSA private key with:<br /> 296 <br /> 297 <code><strong>$ openssl rsa -in server.key -out server.key.unsecure</strong></code><br /> 298 <br /> 299 300 </li> 301 <li>Create a Certificate Signing Request (CSR) with the server RSA private 302 key (output will be PEM formatted):<br /> 303 <br /> 304 <code><strong>$ openssl req -new -key server.key -out server.csr</strong></code><br /> 305 <br /> 306 Make sure you enter the FQDN ("Fully Qualified Domain Name") of the 307 server when OpenSSL prompts you for the "CommonName", i.e. when you 308 generate a CSR for a website which will be later accessed via 309 <code>https://www.foo.dom/</code>, enter "www.foo.dom" here. 310 You can see the details of this CSR by using<br /> 311 312 <br /> 313 <code><strong>$ openssl req -noout -text -in server.csr</strong></code><br /> 314 <br /> 315 </li> 316 <li>You now have to send this Certificate Signing Request (CSR) to 317 a Certifying Authority (CA) to be signed. Once the CSR has been 318 signed, you will have a real Certificate, which can be used by 319 Apache. You can have a CSR signed by a commercial CA, or you can 320 create your own CA to sign it.<br /> 321 Commercial CAs usually ask you to post the CSR into a web form, 322 pay for the signing, and then send a signed Certificate, which 323 you can store in a server.crt file.<br /> 324 325 For details on how to create your own CA, and use this to sign 326 a CSR, see <a href="#ownca">below</a>.<br /> 327 328 Once your CSR has been signed, you can see the details of the 329 Certificate as follows:<br /> 330 <br /> 331 <code><strong>$ openssl x509 -noout -text -in server.crt</strong></code><br /> 332 333 </li> 334 <li>You should now have two files: <code>server.key</code> and 335 <code>server.crt</code>. These can be used as follows in your 336 <code>httpd.conf</code> file: 337 <pre class="prettyprint lang-config">SSLCertificateFile /path/to/this/server.crt 338SSLCertificateKeyFile /path/to/this/server.key</pre> 339 340 The <code>server.csr</code> file is no longer needed. 341 </li> 342 343 </ol> 344 345 346<h3><a name="ownca" id="ownca">How do I create and use my own Certificate Authority (CA)?</a></h3> 347 <p>The short answer is to use the <code>CA.sh</code> or <code>CA.pl</code> 348 script provided by OpenSSL. Unless you have a good reason not to, 349 you should use these for preference. If you cannot, you can create a 350 self-signed Certificate as follows:</p> 351 352 <ol> 353 <li>Create a RSA private key for your server 354 (will be Triple-DES encrypted and PEM formatted):<br /> 355 <br /> 356 <code><strong>$ openssl genrsa -des3 -out server.key 2048</strong></code><br /> 357 <br /> 358 Please backup this <code>host.key</code> file and the 359 pass-phrase you entered in a secure location. 360 You can see the details of this RSA private key by using the 361 command:<br /> 362 <code><strong>$ openssl rsa -noout -text -in server.key</strong></code><br /> 363 <br /> 364 If necessary, you can also create a decrypted PEM version (not 365 recommended) of this RSA private key with:<br /> 366 <br /> 367 <code><strong>$ openssl rsa -in server.key -out server.key.unsecure</strong></code><br /> 368 <br /> 369 </li> 370 <li>Create a self-signed Certificate (X509 structure) 371 with the RSA key you just created (output will be PEM formatted):<br /> 372 <br /> 373 <code><strong>$ openssl req -new -x509 -nodes -sha1 -days 365 374 -key server.key -out server.crt</strong></code><br /> 375 <br /> 376 This signs the server CSR and results in a <code>server.crt</code> file.<br /> 377 You can see the details of this Certificate using:<br /> 378 <br /> 379 <code><strong>$ openssl x509 -noout -text -in server.crt</strong></code><br /> 380 <br /> 381 </li> 382 </ol> 383 384 385<h3><a name="passphrase" id="passphrase">How can I change the pass-phrase on my private key file?</a></h3> 386<p>You simply have to read it with the old pass-phrase and write it again, 387 specifying the new pass-phrase. You can accomplish this with the following 388 commands:</p> 389 390 391 <p><code><strong>$ openssl rsa -des3 -in server.key -out server.key.new</strong></code><br /> 392 <code><strong>$ mv server.key.new server.key</strong></code><br /></p> 393 394 <p>The first time you're asked for a PEM pass-phrase, you should 395 enter the old pass-phrase. After that, you'll be asked again to 396 enter a pass-phrase - this time, use the new pass-phrase. If you 397 are asked to verify the pass-phrase, you'll need to enter the new 398 pass-phrase a second time.</p> 399 400 401<h3><a name="removepassphrase" id="removepassphrase">How can I get rid of the pass-phrase dialog at Apache startup time?</a></h3> 402<p>The reason this dialog pops up at startup and every re-start 403 is that the RSA private key inside your server.key file is stored in 404 encrypted format for security reasons. The pass-phrase is needed to decrypt 405 this file, so it can be read and parsed. Removing the pass-phrase 406 removes a layer of security from your server - proceed with caution!</p> 407 <ol> 408 <li>Remove the encryption from the RSA private key (while 409 keeping a backup copy of the original file):<br /> 410 <br /> 411 <code><strong>$ cp server.key server.key.org</strong></code><br /> 412 <code><strong>$ openssl rsa -in server.key.org -out server.key</strong></code><br /> 413 414 <br /> 415 </li> 416 <li>Make sure the server.key file is only readable by root:<br /> 417 <br /> 418 <code><strong>$ chmod 400 server.key</strong></code><br /> 419 <br /> 420 </li> 421 </ol> 422 423 <p>Now <code>server.key</code> contains an unencrypted copy of the key. 424 If you point your server at this file, it will not prompt you for a 425 pass-phrase. HOWEVER, if anyone gets this key they will be able to 426 impersonate you on the net. PLEASE make sure that the permissions on this 427 file are such that only root or the web server user can read it 428 (preferably get your web server to start as root but run as another 429 user, and have the key readable only by root).</p> 430 431 <p>As an alternative approach you can use the ``<code>SSLPassPhraseDialog 432 exec:/path/to/program</code>'' facility. Bear in mind that this is 433 neither more nor less secure, of course.</p> 434 435 436<h3><a name="verify" id="verify">How do I verify that a private key matches its Certificate?</a></h3> 437<p>A private key contains a series of numbers. Two of these numbers form 438 the "public key", the others are part of the "private key". The "public 439 key" bits are included when you generate a CSR, and subsequently form 440 part of the associated Certificate.</p> 441 <p>To check that the public key in your Certificate matches the public 442 portion of your private key, you simply need to compare these numbers. 443 To view the Certificate and the key run the commands:</p> 444 445 <p><code><strong>$ openssl x509 -noout -text -in server.crt</strong></code><br /> 446 <code><strong>$ openssl rsa -noout -text -in server.key</strong></code></p> 447 448 <p>The `modulus' and the `public exponent' portions in the key and the 449 Certificate must match. As the public exponent is usually 65537 450 and it's difficult to visually check that the long modulus numbers 451 are the same, you can use the following approach:</p> 452 453 <p><code><strong>$ openssl x509 -noout -modulus -in server.crt | openssl md5</strong></code><br /> 454 <code><strong>$ openssl rsa -noout -modulus -in server.key | openssl md5</strong></code></p> 455 456 <p>This leaves you with two rather shorter numbers to compare. It is, 457 in theory, possible that these numbers may be the same, without the 458 modulus numbers being the same, but the chances of this are 459 overwhelmingly remote.</p> 460 <p>Should you wish to check to which key or certificate a particular 461 CSR belongs you can perform the same calculation on the CSR as 462 follows:</p> 463 464 <p><code><strong>$ openssl req -noout -modulus -in server.csr | openssl md5</strong></code></p> 465 466 467<h3><a name="pemder" id="pemder">How can I convert a certificate from PEM to DER format?</a></h3> 468<p>The default certificate format for OpenSSL is PEM, which is simply 469 Base64 encoded DER, with header and footer lines. For some applications 470 (e.g. Microsoft Internet Explorer) you need the certificate in plain DER 471 format. You can convert a PEM file <code>cert.pem</code> into the 472 corresponding DER file <code>cert.der</code> using the following command: 473 <code><strong>$ openssl x509 -in cert.pem -out cert.der -outform DER</strong></code></p> 474 475 476<h3><a name="gid" id="gid">Why do browsers complain that they cannot verify my server certificate?</a></h3> 477 478 <p>One reason this might happen is because your server certificate is signed 479 by an intermediate CA. Various CAs, such as Verisign or Thawte, have started 480 signing certificates not with their root certificate but with intermediate 481 certificates.</p> 482 483 <p>Intermediate CA certificates lie between the root CA certificate (which is 484 installed in the browsers) and the server certificate (which you installed 485 on the server). In order for the browser to be able to traverse and verify 486 the trust chain from the server certificate to the root certificate it 487 needs need to be given the intermediate certificates. The CAs should 488 be able to provide you such intermediate certificate packages that can be 489 installed on the server.</p> 490 491 <p>You need to include those intermediate certificates with the 492 <code class="directive"><a href="/mod/mod_ssl.html#sslcertificatechainfile">SSLCertificateChainFile</a></code> 493 directive.</p> 494 495</div><div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 496<div class="section"> 497<h2><a name="aboutssl" id="aboutssl">The SSL Protocol</a></h2> 498<ul> 499<li><a href="#random">Why do I get lots of random SSL protocol 500errors under heavy server load?</a></li> 501<li><a href="#load">Why does my webserver have a higher load, now 502that it serves SSL encrypted traffic?</a></li> 503<li><a href="#establishing">Why do HTTPS connections to my server 504sometimes take up to 30 seconds to establish a connection?</a></li> 505<li><a href="#ciphers">What SSL Ciphers are supported by mod_ssl?</a></li> 506<li><a href="#adh">Why do I get ``no shared cipher'' errors, when 507trying to use Anonymous Diffie-Hellman (ADH) ciphers?</a></li> 508<li><a href="#sharedciphers">Why do I get a 'no shared ciphers' 509error when connecting to my newly installed server?</a></li> 510<li><a href="#vhosts">Why can't I use SSL with name-based/non-IP-based 511virtual hosts?</a></li> 512<li><a href="#vhosts2">Is it possible to use Name-Based Virtual 513Hosting to identify different SSL virtual hosts?</a></li> 514<li><a href="#comp">How do I get SSL compression working?</a></li> 515<li><a href="#lockicon">When I use Basic Authentication over HTTPS 516the lock icon in Netscape browsers stays unlocked when the dialog pops up. 517Does this mean the username/password is being sent unencrypted?</a></li> 518<li><a href="#msie">Why do I get I/O errors when connecting via 519HTTPS to an Apache+mod_ssl server with Microsoft Internet Explorer 520(MSIE)?</a></li> 521<li><a href="#srp">How do I enable TLS-SRP?</a></li> 522<li><a href="#javadh">Why do I get handshake failures with Java-based clients when using a certificate with more than 1024 bits?</a></li> 523</ul> 524 525<h3><a name="random" id="random">Why do I get lots of random SSL protocol 526errors under heavy server load?</a></h3> 527<p>There can be a number of reasons for this, but the main one 528 is problems with the SSL session Cache specified by the 529 <code class="directive"><a href="/mod/mod_ssl.html#sslsessioncache">SSLSessionCache</a></code> directive. The DBM session 530 cache is the most likely source of the problem, so using the SHM session cache (or 531 no cache at all) may help.</p> 532 533 534<h3><a name="load" id="load">Why does my webserver have a higher load, now 535that it serves SSL encrypted traffic?</a></h3> 536<p>SSL uses strong cryptographic encryption, which necessitates a lot of 537 number crunching. When you request a webpage via HTTPS, everything (even 538 the images) is encrypted before it is transferred. So increased HTTPS 539 traffic leads to load increases.</p> 540 541 542<h3><a name="establishing" id="establishing">Why do HTTPS connections to my server 543sometimes take up to 30 seconds to establish a connection?</a></h3> 544<p>This is usually caused by a <code>/dev/random</code> device for 545 <code class="directive"><a href="/mod/mod_ssl.html#sslrandomseed">SSLRandomSeed</a></code> which blocks the 546 read(2) call until enough entropy is available to service the 547 request. More information is available in the reference 548 manual for the <code class="directive"><a href="/mod/mod_ssl.html#sslrandomseed">SSLRandomSeed</a></code> 549 directive.</p> 550 551 552<h3><a name="ciphers" id="ciphers">What SSL Ciphers are supported by mod_ssl?</a></h3> 553<p>Usually, any SSL ciphers supported by the version of OpenSSL in use, 554 are also supported by <code class="module"><a href="/mod/mod_ssl.html">mod_ssl</a></code>. Which ciphers are 555 available can depend on the way you built OpenSSL. Typically, at 556 least the following ciphers are supported:</p> 557 558 <ol> 559 <li>RC4 with SHA1</li> 560 <li>AES with SHA1</li> 561 <li>Triple-DES with SHA1</li> 562 </ol> 563 564 <p>To determine the actual list of ciphers available, you should run 565 the following:</p> 566 <div class="example"><p><code>$ openssl ciphers -v</code></p></div> 567 568 569<h3><a name="adh" id="adh">Why do I get ``no shared cipher'' errors, when 570trying to use Anonymous Diffie-Hellman (ADH) ciphers?</a></h3> 571<p>By default, OpenSSL does <em>not</em> allow ADH ciphers, for security 572 reasons. Please be sure you are aware of the potential side-effects 573 if you choose to enable these ciphers.</p> 574 <p>In order to use Anonymous Diffie-Hellman (ADH) ciphers, you must 575 build OpenSSL with ``<code>-DSSL_ALLOW_ADH</code>'', and then add 576 ``<code>ADH</code>'' into your <code class="directive"><a href="/mod/mod_ssl.html#sslciphersuite">SSLCipherSuite</a></code>.</p> 577 578 579<h3><a name="sharedciphers" id="sharedciphers">Why do I get a 'no shared ciphers' 580error when connecting to my newly installed server?</a></h3> 581<p>Either you have made a mistake with your 582 <code class="directive"><a href="/mod/mod_ssl.html#sslciphersuite">SSLCipherSuite</a></code> 583 directive (compare it with the pre-configured example in 584 <code>extra/httpd-ssl.conf</code>) or you chose to use DSA/DH 585 algorithms instead of RSA when you generated your private key 586 and ignored or overlooked the warnings. If you have chosen 587 DSA/DH, then your server cannot communicate using RSA-based SSL 588 ciphers (at least until you configure an additional RSA-based 589 certificate/key pair). Modern browsers like NS or IE can only 590 communicate over SSL using RSA ciphers. The result is the 591 "no shared ciphers" error. To fix this, regenerate your server 592 certificate/key pair, using the RSA algorithm.</p> 593 594 595<h3><a name="vhosts" id="vhosts">Why can't I use SSL with name-based/non-IP-based virtual hosts?</a></h3> 596<p>The reason is very technical, and a somewhat "chicken and egg" problem. 597 The SSL protocol layer stays below the HTTP protocol layer and 598 encapsulates HTTP. When an SSL connection (HTTPS) is established 599 Apache/mod_ssl has to negotiate the SSL protocol parameters with the 600 client. For this, mod_ssl has to consult the configuration of the virtual 601 server (for instance it has to look for the cipher suite, the server 602 certificate, etc.). But in order to go to the correct virtual server 603 Apache has to know the <code>Host</code> HTTP header field. To do this, the 604 HTTP request header has to be read. This cannot be done before the SSL 605 handshake is finished, but the information is needed in order to 606 complete the SSL handshake phase. See the next question for how to 607 circumvent this issue.</p> 608 609 <p>Note that if you have a wildcard SSL certificate, or a 610 certificate that has multiple hostnames on it using subjectAltName 611 fields, you can use SSL on name-based virtual hosts without further 612 workarounds.</p> 613 614 615<h3><a name="vhosts2" id="vhosts2">Is it possible to use Name-Based 616Virtual Hosting to identify different SSL virtual hosts?</a></h3> 617 <p>Name-Based Virtual Hosting is a very popular method of identifying 618 different virtual hosts. It allows you to use the same IP address and 619 the same port number for many different sites. When people move on to 620 SSL, it seems natural to assume that the same method can be used to have 621 lots of different SSL virtual hosts on the same server.</p> 622 623 <p>It is possible, but only if using a 2.2.12 or later web server, 624 built with 0.9.8j or later OpenSSL. This is because it requires a 625 feature that only the most recent revisions of the SSL 626 specification added, called Server Name Indication (SNI).</p> 627 628 <p>Note that if you have a wildcard SSL certificate, or a 629 certificate that has multiple hostnames on it using subjectAltName 630 fields, you can use SSL on name-based virtual hosts without further 631 workarounds.</p> 632 633 <p>The reason is that the SSL protocol is a separate layer which 634 encapsulates the HTTP protocol. So the SSL session is a separate 635 transaction, that takes place before the HTTP session has begun. 636 The server receives an SSL request on IP address X and port Y 637 (usually 443). Since the SSL request did not contain any Host: 638 field, the server had no way to decide which SSL virtual host to use. 639 Usually, it just used the first one it found which matched the 640 port and IP address specified.</p> 641 642 <p>If you are using a version of the web server and OpenSSL that 643 support SNI, though, and the client's browser also supports SNI, 644 then the hostname is included in the original SSL request, and the 645 web server can select the correct SSL virtual host.</p> 646 647 <p>You can, of course, use Name-Based Virtual Hosting to identify many 648 non-SSL virtual hosts (all on port 80, for example) and then 649 have a single SSL virtual host (on port 443). But if you do this, 650 you must make sure to put the non-SSL port number on the NameVirtualHost 651 directive, e.g.</p> 652 653 <pre class="prettyprint lang-config">NameVirtualHost 192.168.1.1:80</pre> 654 655 656 <p>Other workaround solutions include: </p> 657 658 <p>Using separate IP addresses for different SSL hosts. 659 Using different port numbers for different SSL hosts.</p> 660 661 662<h3><a name="comp" id="comp">How do I get SSL compression working?</a></h3> 663<p>Although SSL compression negotiation was defined in the specification 664of SSLv2 and TLS, it took until May 2004 for RFC 3749 to define DEFLATE as 665a negotiable standard compression method. 666</p> 667<p>OpenSSL 0.9.8 started to support this by default when compiled with the 668<code>zlib</code> option. If both the client and the server support compression, 669it will be used. However, most clients still try to initially connect with an 670SSLv2 Hello. As SSLv2 did not include an array of preferred compression algorithms 671in its handshake, compression cannot be negotiated with these clients. 672If the client disables support for SSLv2, either an SSLv3 or TLS Hello 673may be sent, depending on which SSL library is used, and compression may 674be set up. You can verify whether clients make use of SSL compression by 675logging the <code>%{SSL_COMPRESS_METHOD}x</code> variable. 676</p> 677 678 679<h3><a name="lockicon" id="lockicon">When I use Basic Authentication over HTTPS 680the lock icon in Netscape browsers stays unlocked when the dialog pops up. 681Does this mean the username/password is being sent unencrypted?</a></h3> 682<p>No, the username/password is transmitted encrypted. The icon in 683 Netscape browsers is not actually synchronized with the SSL/TLS layer. 684 It only toggles to the locked state when the first part of the actual 685 webpage data is transferred, which may confuse people. The Basic 686 Authentication facility is part of the HTTP layer, which is above 687 the SSL/TLS layer in HTTPS. Before any HTTP data communication takes 688 place in HTTPS, the SSL/TLS layer has already completed its handshake 689 phase, and switched to encrypted communication. So don't be 690 confused by this icon.</p> 691 692 693<h3><a name="msie" id="msie">Why do I get I/O errors when connecting via 694HTTPS to an Apache+mod_ssl server with older versions of Microsoft Internet 695Explorer (MSIE)?</a></h3> 696<p>The first reason is that the SSL implementation in some MSIE versions has 697 some subtle bugs related to the HTTP keep-alive facility and the SSL close 698 notify alerts on socket connection close. Additionally the interaction 699 between SSL and HTTP/1.1 features are problematic in some MSIE versions. 700 You can work around these problems by forcing Apache not to use HTTP/1.1, 701 keep-alive connections or send the SSL close notify messages to MSIE clients. 702 This can be done by using the following directive in your SSL-aware 703 virtual host section:</p> 704 <pre class="prettyprint lang-config">SetEnvIf User-Agent "MSIE [2-5]" \ 705 nokeepalive ssl-unclean-shutdown \ 706 downgrade-1.0 force-response-1.0</pre> 707 708 <p>Further, some MSIE versions have problems with particular ciphers. 709 Unfortunately, it is not possible to implement a MSIE-specific 710 workaround for this, because the ciphers are needed as early as the 711 SSL handshake phase. So a MSIE-specific 712 <code class="directive"><a href="/mod/mod_setenvif.html#setenvif">SetEnvIf</a></code> won't solve these 713 problems. Instead, you will have to make more drastic 714 adjustments to the global parameters. Before you decide to do 715 this, make sure your clients really have problems. If not, do not 716 make these changes - they will affect <em>all</em> your clients, MSIE 717 or otherwise.</p> 718 719 720<h3><a name="srp" id="srp">How do I enable TLS-SRP?</a></h3> 721 <p>TLS-SRP (Secure Remote Password key exchange for TLS, specified in RFC 5054) 722 can supplement or replace certificates in authenticating an SSL connection. 723 To use TLS-SRP, set the 724 <code class="directive"><a href="/mod/mod_ssl.html#sslsrpverifierfile">SSLSRPVerifierFile</a></code> directive to 725 point to an OpenSSL SRP verifier file. To create the verifier file, use the 726 <code>openssl</code> tool:</p> 727 <div class="example"><p><code> 728 openssl srp -srpvfile passwd.srpv -add username 729 </code></p></div> 730 <p>After creating this file, specify it in the SSL server configuration:</p> 731 <div class="example"><p><code> 732 SSLSRPVerifierFile /path/to/passwd.srpv 733 </code></p></div> 734 <p>To force clients to use non-certificate TLS-SRP cipher suites, use the 735 following directive:</p> 736 <div class="example"><p><code> 737 SSLCipherSuite "!DSS:!aRSA:SRP" 738 </code></p></div> 739 740 741<h3><a name="javadh" id="javadh">Why do I get handshake failures with Java-based clients when using a certificate with more than 1024 bits?</a></h3> 742 <p>Beginning with version 2.4.7, 743 <code class="module"><a href="/mod/mod_ssl.html">mod_ssl</a></code> will use DH parameters which include primes 744 with lengths of more than 1024 bits. Java 7 and earlier limit their 745 support for DH prime sizes to a maximum of 1024 bits, however.</p> 746 747 <p>If your Java-based client aborts with exceptions such as 748 <code>java.lang.RuntimeException: Could not generate DH keypair</code> and 749 <code>java.security.InvalidAlgorithmParameterException: Prime size must be 750 multiple of 64, and can only range from 512 to 1024 (inclusive)</code>, 751 and httpd logs <code>tlsv1 alert internal error (SSL alert number 80)</code> 752 (at <code class="directive"><a href="/mod/core.html#loglevel">LogLevel</a></code> <code>info</code> 753 or higher), you can either rearrange mod_ssl's cipher list with 754 <code class="directive"><a href="/mod/mod_ssl.html#sslciphersuite">SSLCipherSuite</a></code> 755 (possibly in conjunction with <code class="directive"><a href="/mod/mod_ssl.html#sslhonorcipherorder">SSLHonorCipherOrder</a></code>), 756 or you can use the <code class="directive"><a href="/mod/mod_ssl.html#sslcertificatefile">SSLCertificateFile</a></code> 757 directive to configure custom DH parameters with a 1024-bit prime, which 758 will always have precedence over any of the built-in DH parameters.</p> 759 760 <p>To generate custom DH parameters, use the <code>openssl dhparam</code> 761 command. Alternatively, you can append the following standard 1024-bit DH 762 parameters from <a href="http://www.ietf.org/rfc/rfc2409.txt">RFC 2409</a>, 763 section 6.2 to the respective 764 <code class="directive"><a href="/mod/mod_ssl.html#sslcertificatefile">SSLCertificateFile</a></code> file:</p> 765 <div class="example"><pre>-----BEGIN DH PARAMETERS----- 766MIGHAoGBAP//////////yQ/aoiFowjTExmKLgNwc0SkCTgiKZ8x0Agu+pjsTmyJR 767Sgh5jjQE3e+VGbPNOkMbMCsKbfJfFDdP4TVtbVHCReSFtXZiXn7G9ExC6aY37WsL 768/1y29Aa37e44a/taiZ+lrp8kEXxLH+ZJKGZR7OZTgf//////////AgEC 769-----END DH PARAMETERS-----</pre></div> 770 771 772</div><div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 773<div class="section"> 774<h2><a name="support" id="support">mod_ssl Support</a></h2> 775<ul> 776<li><a href="#resources">What information resources are available in 777case of mod_ssl problems?</a></li> 778<li><a href="#contact">What support contacts are available in case of 779mod_ssl problems?</a></li> 780<li><a href="#reportdetails">What information should I 781provide when writing a bug report?</a></li> 782<li><a href="#coredumphelp">I had a core dump, can you help me?</a></li> 783<li><a href="#backtrace">How do I get a backtrace, to help find the reason 784for my core dump?</a></li> 785</ul> 786 787<h3><a name="resources" id="resources">What information resources are available in case of mod_ssl problems?</a></h3> 788<p>The following information resources are available. 789 In case of problems you should search here first.</p> 790 791 <dl> 792 <dt>Answers in the User Manual's F.A.Q. List (this)</dt> 793 <dd><a href="http://httpd.apache.org/docs/2.4/ssl/ssl_faq.html"> 794 http://httpd.apache.org/docs/2.4/ssl/ssl_faq.html</a><br /> 795 First check the F.A.Q. (this text). If your problem is a common 796 one, it may have been answered several times before, and been included 797 in this doc. 798 </dd> 799 </dl> 800 801 802<h3><a name="contact" id="contact">What support contacts are available in case 803of mod_ssl problems?</a></h3> 804 <p>The following lists all support possibilities for mod_ssl, in order of 805 preference. Please go through these possibilities 806 <em>in this order</em> - don't just pick the one you like the look of. </p> 807 <ol> 808 809 <li><em>Send a Problem Report to the Apache httpd Users Support Mailing List</em><br /> 810 <a href="mailto:users@httpd.apache.org"> 811 users@httpd.apache.org</a><br /> 812 This is the second way of submitting your problem report. Again, you must 813 subscribe to the list first, but you can then easily discuss your problem 814 with the whole Apache httpd user community. 815 </li> 816 817 <li><em>Write a Problem Report in the Bug Database</em><br /> 818 <a href="http://httpd.apache.org/bug_report.html"> 819 http://httpd.apache.org/bug_report.html</a><br /> 820 This is the last way of submitting your problem report. You should only 821 do this if you've already posted to the mailing lists, and had no success. 822 Please follow the instructions on the above page <em>carefully</em>. 823 </li> 824 </ol> 825 826 827<h3><a name="reportdetails" id="reportdetails">What information should I 828provide when writing a bug report?</a></h3> 829<p>You should always provide at least the following information:</p> 830 831 <dl> 832 <dt>Apache httpd and OpenSSL version information</dt> 833 <dd>The Apache version can be determined 834 by running <code>httpd -v</code>. The OpenSSL version can be 835 determined by running <code>openssl version</code>. Alternatively, if 836 you have Lynx installed, you can run the command <code>lynx -mime_header 837 http://localhost/ | grep Server</code> to gather this information in a 838 single step. 839 </dd> 840 841 <dt>The details on how you built and installed Apache httpd and OpenSSL</dt> 842 <dd>For this you can provide a logfile of your terminal session which shows 843 the configuration and install steps. If this is not possible, you 844 should at least provide the <code class="program"><a href="/programs/configure.html">configure</a></code> command line you used. 845 </dd> 846 847 <dt>In case of core dumps please include a Backtrace</dt> 848 <dd>If your Apache httpd dumps its core, please attach 849 a stack-frame ``backtrace'' (see <a href="#backtrace">below</a> 850 for information on how to get this). This information is required 851 in order to find a reason for your core dump. 852 </dd> 853 854 <dt>A detailed description of your problem</dt> 855 <dd>Don't laugh, we really mean it! Many problem reports don't 856 include a description of what the actual problem is. Without this, 857 it's very difficult for anyone to help you. So, it's in your own 858 interest (you want the problem be solved, don't you?) to include as 859 much detail as possible, please. Of course, you should still include 860 all the essentials above too. 861 </dd> 862 </dl> 863 864 865<h3><a name="coredumphelp" id="coredumphelp">I had a core dump, can you help me?</a></h3> 866<p>In general no, at least not unless you provide more details about the code 867 location where Apache dumped core. What is usually always required in 868 order to help you is a backtrace (see next question). Without this 869 information it is mostly impossible to find the problem and help you in 870 fixing it.</p> 871 872 873<h3><a name="backtrace" id="backtrace">How do I get a backtrace, to help find 874the reason for my core dump?</a></h3> 875<p>Following are the steps you will need to complete, to get a backtrace:</p> 876 <ol> 877 <li>Make sure you have debugging symbols available, at least 878 in Apache. On platforms where you use GCC/GDB, you will have to build 879 Apache+mod_ssl with ``<code>OPTIM="-g -ggdb3"</code>'' to get this. On 880 other platforms at least ``<code>OPTIM="-g"</code>'' is needed. 881 </li> 882 883 <li>Start the server and try to reproduce the core-dump. For this you may 884 want to use a directive like ``<code>CoreDumpDirectory /tmp</code>'' to 885 make sure that the core-dump file can be written. This should result 886 in a <code>/tmp/core</code> or <code>/tmp/httpd.core</code> file. If you 887 don't get one of these, try running your server under a non-root UID. 888 Many modern kernels do not allow a process to dump core after it has 889 done a <code>setuid()</code> (unless it does an <code>exec()</code>) for 890 security reasons (there can be privileged information left over in 891 memory). If necessary, you can run <code>/path/to/httpd -X</code> 892 manually to force Apache to not fork. 893 </li> 894 895 <li>Analyze the core-dump. For this, run <code>gdb /path/to/httpd 896 /tmp/httpd.core</code> or a similar command. In GDB, all you 897 have to do then is to enter <code>bt</code>, and voila, you get the 898 backtrace. For other debuggers consult your local debugger manual. 899 </li> 900 </ol> 901 902</div></div> 903<div class="bottomlang"> 904<p><span>Available Languages: </span><a href="/en/ssl/ssl_faq.html" title="English"> en </a> | 905<a href="/fr/ssl/ssl_faq.html" hreflang="fr" rel="alternate" title="Fran�ais"> fr </a></p> 906</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&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> 907<script type="text/javascript"><!--//--><![CDATA[//><!-- 908var comments_shortname = 'httpd'; 909var comments_identifier = 'http://httpd.apache.org/docs/2.4/ssl/ssl_faq.html'; 910(function(w, d) { 911 if (w.location.hostname.toLowerCase() == "httpd.apache.org") { 912 d.write('<div id="comments_thread"><\/div>'); 913 var s = d.createElement('script'); 914 s.type = 'text/javascript'; 915 s.async = true; 916 s.src = 'https://comments.apache.org/show_comments.lua?site=' + comments_shortname + '&page=' + comments_identifier; 917 (d.getElementsByTagName('head')[0] || d.getElementsByTagName('body')[0]).appendChild(s); 918 } 919 else { 920 d.write('<div id="comments_thread">Comments are disabled for this page at the moment.<\/div>'); 921 } 922})(window, document); 923//--><!]]></script></div><div id="footer"> 924<p class="apache">Copyright 2014 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> 925<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[//><!-- 926if (typeof(prettyPrint) !== 'undefined') { 927 prettyPrint(); 928} 929//--><!]]></script> 930</body></html>
