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.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.2</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.2</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></p> 25</div> 26 27<blockquote> 28<p>The wise man doesn't give the right answers, 29he poses the right questions.</p> 30<p class="cite">-- <cite>Claude Levi-Strauss</cite></p> 31 32</blockquote> 33<p>This chapter is a collection of frequently asked questions (FAQ) and 34corresponding answers following the popular USENET tradition. Most of these 35questions occurred on the Newsgroup <code><a href="news:comp.infosystems.www.servers.unix">comp.infosystems.www.servers.unix</a></code> or the mod_ssl Support 36Mailing List <code><a href="mailto:modssl-users@modssl.org">modssl-users@modssl.org</a></code>. They are collected at this place 37to avoid answering the same questions over and over.</p> 38 39<p>Please read this chapter at least once when installing mod_ssl or at least 40search for your problem here before submitting a problem report to the 41author.</p> 42</div> 43<div id="quickview"><ul id="toc"><li><img alt="" src="/images/down.gif" /> <a href="#about">About The Module</a></li> 44<li><img alt="" src="/images/down.gif" /> <a href="#installation">Installation</a></li> 45<li><img alt="" src="/images/down.gif" /> <a href="#aboutconfig">Configuration</a></li> 46<li><img alt="" src="/images/down.gif" /> <a href="#aboutcerts">Certificates</a></li> 47<li><img alt="" src="/images/down.gif" /> <a href="#aboutssl">The SSL Protocol</a></li> 48<li><img alt="" src="/images/down.gif" /> <a href="#support">mod_ssl Support</a></li> 49</ul><ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div> 50<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 51<div class="section"> 52<h2><a name="about" id="about">About The Module</a></h2> 53<ul> 54<li><a href="#history">What is the history of mod_ssl?</a></li> 55<li><a href="#wassenaar">mod_ssl and Wassenaar Arrangement?</a></li> 56</ul> 57 58<h3><a name="history" id="history">What is the history of mod_ssl?</a></h3> 59<p>The mod_ssl v1 package was initially created in April 1998 by <a href="mailto:rse@engelschall.com">Ralf S. Engelschall</a> via porting <a href="mailto:ben@algroup.co.uk">Ben Laurie</a>'s <a href="http://www.apache-ssl.org/">Apache-SSL</a> 1.17 source patches for 60 Apache 1.2.6 to Apache 1.3b6. Because of conflicts with Ben 61 Laurie's development cycle it then was re-assembled from scratch for 62 Apache 1.3.0 by merging the old mod_ssl 1.x with the newer Apache-SSL 63 1.18. From this point on mod_ssl lived its own life as mod_ssl v2. The 64 first publicly released version was mod_ssl 2.0.0 from August 10th, 65 1998. </p> 66 67 <p>After US export restrictions on cryptographic software were 68 loosened, <code class="module"><a href="/mod/mod_ssl.html">mod_ssl</a></code> became part of the Apache HTTP 69 Server with the release of Apache httpd 2.</p> 70 71 72<h3><a name="wassenaar" id="wassenaar">Is mod_ssl affected by the Wassenaar Arrangement?</a></h3> 73<p>First, let us explain what <dfn>Wassenaar</dfn> and its <dfn>Arrangement on 74 Export Controls for Conventional Arms and Dual-Use Goods and 75 Technologies</dfn> is: This is a international regime, established in 1995, to 76 control trade in conventional arms and dual-use goods and technology. It 77 replaced the previous <dfn>CoCom</dfn> regime. Further details on 78 both the Arrangement and its signatories are available at <a href="http://www.wassenaar.org/">http://www.wassenaar.org/</a>.</p> 79 80 <p>In short, the aim of the Wassenaar Arrangement is to prevent the build up 81 of military capabilities that threaten regional and international security 82 and stability. The Wassenaar Arrangement controls the export of 83 cryptography as a dual-use good, that is, something that has both military and 84 civilian applications. However, the Wassenaar Arrangement also provides an 85 exemption from export controls for mass-market software and free software.</p> 86 87 <p>In the current Wassenaar <cite>List of Dual Use Goods and Technologies And 88 Munitions</cite>, under <q>GENERAL SOFTWARE NOTE (GSN)</q> it says 89 <q>The Lists do not control "software" which is either: 1. [...] 2. "in 90 the public domain".</q> And under <q>DEFINITIONS OF TERMS USED IN 91 THESE LISTS</q> we find <q>In the public 92 domain</q> defined as <q>"technology" or "software" which has been made 93 available without restrictions upon its further dissemination. Note: 94 Copyright restrictions do not remove "technology" or "software" from being 95 "in the public domain".</q></p> 96 97 <p>So, both mod_ssl and OpenSSL are <q>in the public domain</q> for the purposes 98 of the Wassenaar Arrangement and its <q>List of Dual Use Goods and 99 Technologies And Munitions List</q>, and thus not affected by its provisions.</p> 100 101 102</div><div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 103<div class="section"> 104<h2><a name="installation" id="installation">Installation</a></h2> 105<ul> 106<li><a href="#mutex">Why do I get permission errors related to 107SSLMutex when I start Apache?</a></li> 108<li><a href="#entropy">Why does mod_ssl stop with the error "Failed to 109generate temporary 512 bit RSA private key" when I start Apache?</a></li> 110</ul> 111 112<h3><a name="mutex" id="mutex">Why do I get permission errors related to 113 SSLMutex when I start Apache?</a></h3> 114 <p>Errors such as ``<code>mod_ssl: Child could not open 115 SSLMutex lockfile /opt/apache/logs/ssl_mutex.18332 (System error follows) 116 [...] System: Permission denied (errno: 13)</code>'' are usually 117 caused by overly restrictive permissions on the <em>parent</em> directories. 118 Make sure that all parent directories (here <code>/opt</code>, 119 <code>/opt/apache</code> and <code>/opt/apache/logs</code>) have the x-bit 120 set for, at minimum, the UID under which Apache's children are running (see 121 the <code class="directive"><a href="/mod/mpm_common.html#user">User</a></code> directive).</p> 122 123 124<h3><a name="entropy" id="entropy">Why does mod_ssl stop with the error 125 "Failed to generate temporary 512 bit RSA private key" when I start 126 Apache?</a></h3> 127 <p>Cryptographic software needs a source of unpredictable data 128 to work correctly. Many open source operating systems provide 129 a "randomness device" that serves this purpose (usually named 130 <code>/dev/random</code>). On other systems, applications have to 131 seed the OpenSSL Pseudo Random Number Generator (PRNG) manually with 132 appropriate data before generating keys or performing public key 133 encryption. As of version 0.9.5, the OpenSSL functions that need 134 randomness report an error if the PRNG has not been seeded with 135 at least 128 bits of randomness.</p> 136 <p>To prevent this error, <code class="module"><a href="/mod/mod_ssl.html">mod_ssl</a></code> has to provide 137 enough entropy to the PRNG to allow it to work correctly. This can 138 be done via the <code class="directive"><a href="/mod/mod_ssl.html#sslrandomseed">SSLRandomSeed</a></code> 139 directive.</p> 140 141</div><div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 142<div class="section"> 143<h2><a name="aboutconfig" id="aboutconfig">Configuration</a></h2> 144<ul> 145<li><a href="#parallel">Is it possible to provide HTTP and HTTPS from 146the same server?</a></li> 147<li><a href="#ports">Which port does HTTPS use?</a></li> 148<li><a href="#httpstest">How do I speak HTTPS manually for testing 149purposes?</a></li> 150<li><a href="#hang">Why does the connection hang when I connect to my 151SSL-aware Apache server?</a></li> 152<li><a href="#refused">Why do I get ``Connection Refused'' errors, when 153trying to access my newly installed Apache+mod_ssl server via HTTPS?</a></li> 154<li><a href="#envvars">Why are the <code>SSL_XXX</code> variables not 155available to my CGI & SSI scripts?</a></li> 156<li><a href="#relative">How can I switch between HTTP and HTTPS in 157relative hyperlinks?</a></li> 158</ul> 159 160<h3><a name="parallel" id="parallel">Is it possible to provide HTTP and HTTPS 161 from the same server?</a></h3> 162 <p>Yes. HTTP and HTTPS use different server ports (HTTP binds to 163 port 80, HTTPS to port 443), so there is no direct conflict between 164 them. You can either run two separate server instances bound to 165 these ports, or use Apache's elegant virtual hosting facility to 166 create two virtual servers, both served by the same instance of Apache 167 - one responding over HTTP to requests on port 80, and the other 168 responding over HTTPS to requests on port 443.</p> 169 170 171<h3><a name="ports" id="ports">Which port does HTTPS use?</a></h3> 172<p>You can run HTTPS on any port, but the standards specify port 443, which 173 is where any HTTPS compliant browser will look by default. You can force 174 your browser to look on a different port by specifying it in the URL. For 175 example, if your server is set up to serve pages over HTTPS on port 8080, 176 you can access them at <code>https://example.com:8080/</code></p> 177 178 179<h3><a name="httpstest" id="httpstest">How do I speak HTTPS manually for testing purposes?</a></h3> 180 <p>While you usually just use</p> 181 182 <div class="example"><p><code>$ telnet localhost 80<br /> 183 GET / HTTP/1.0</code></p></div> 184 185 <p>for simple testing of Apache via HTTP, it's not so easy for 186 HTTPS because of the SSL protocol between TCP and HTTP. With the 187 help of OpenSSL's <code>s_client</code> command, however, you can 188 do a similar check via HTTPS:</p> 189 190 <div class="example"><p><code>$ openssl s_client -connect localhost:443 -state -debug<br /> 191 GET / HTTP/1.0</code></p></div> 192 193 <p>Before the actual HTTP response you will receive detailed 194 information about the SSL handshake. For a more general command 195 line client which directly understands both HTTP and HTTPS, can 196 perform GET and POST operations, can use a proxy, supports byte 197 ranges, etc. you should have a look at the nifty 198 <a href="http://curl.haxx.se/">cURL</a> tool. Using this, you can 199 check that Apache is responding correctly to requests via HTTP and 200 HTTPS as follows:</p> 201 202 <div class="example"><p><code>$ curl http://localhost/<br /> 203 $ curl https://localhost/</code></p></div> 204 205 206<h3><a name="hang" id="hang">Why does the connection hang when I connect 207 to my SSL-aware Apache server?</a></h3> 208 209<p>This can happen when you try to connect to a HTTPS server (or virtual 210 server) via HTTP (eg, using <code>http://example.com/</code> instead of 211 <code>https://example.com</code>). It can also happen when trying to 212 connect via HTTPS to a HTTP server (eg, using 213 <code>https://example.com/</code> on a server which doesn't support HTTPS, 214 or which supports it on a non-standard port). Make sure that you're 215 connecting to a (virtual) server that supports SSL.</p> 216 217<h3><a name="refused" id="refused">Why do I get ``Connection Refused'' messages, 218 when trying to access my newly installed Apache+mod_ssl server via HTTPS?</a></h3> 219<p> 220 This error can be caused by an incorrect configuration. 221 Please make sure that your <code class="directive"><a href="/mod/mpm_common.html#listen">Listen</a></code> directives match your 222 <code class="directive"><a href="/mod/core.html#virtualhost"><VirtualHost></a></code> 223 directives. If all else fails, please start afresh, using the default 224 configuration provided by <code class="module"><a href="/mod/mod_ssl.html">mod_ssl</a></code>.</p> 225 226 227<h3><a name="envvars" id="envvars">Why are the <code>SSL_XXX</code> variables 228 not available to my CGI & SSI scripts?</a></h3> 229<p>Please make sure you have ``<code>SSLOptions +StdEnvVars</code>'' 230 enabled for the context of your CGI/SSI requests.</p> 231 232 233<h3><a name="relative" id="relative">How can I switch between HTTP and HTTPS in relative 234 hyperlinks?</a></h3> 235 236<p>Usually, to switch between HTTP and HTTPS, you have to use 237 fully-qualified hyperlinks (because you have to change the URL 238 scheme). Using <code class="module"><a href="/mod/mod_rewrite.html">mod_rewrite</a></code> however, you can 239 manipulate relative hyperlinks, to achieve the same effect.</p> 240 <div class="example"><p><code> 241 RewriteEngine on<br /> 242 RewriteRule ^/(.*)_SSL$ https://%{SERVER_NAME}/$1 [R,L]<br /> 243 RewriteRule ^/(.*)_NOSSL$ http://%{SERVER_NAME}/$1 [R,L] 244 </code></p></div> 245 246 <p>This rewrite ruleset lets you use hyperlinks of the form 247 <code><a href="document.html_SSL"></code>, to switch to HTTPS 248 in a relative link. (Replace SSL with NOSSL to switch to HTTP.)</p> 249 250</div><div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 251<div class="section"> 252<h2><a name="aboutcerts" id="aboutcerts">Certificates</a></h2> 253<ul> 254<li><a href="#keyscerts">What are RSA Private Keys, CSRs and 255Certificates?</a></li> 256<li><a href="#startup">Is there a difference on startup between 257a non-SSL-aware Apache and an SSL-aware Apache?</a></li> 258<li><a href="#selfcert">How do I create a self-signed SSL 259Certificate for testing purposes?</a></li> 260<li><a href="#realcert">How do I create a real SSL Certificate?</a></li> 261<li><a href="#ownca">How do I create and use my own Certificate 262Authority (CA)?</a></li> 263<li><a href="#passphrase">How can I change the pass-phrase on my private 264key file?</a></li> 265<li><a href="#removepassphrase">How can I get rid of the pass-phrase 266dialog at Apache startup time?</a></li> 267<li><a href="#verify">How do I verify that a private key matches its 268Certificate?</a></li> 269<li><a href="#badcert">Why do connections fail with an "alert bad 270certificate" error?</a></li> 271<li><a href="#keysize">Why does my 2048-bit private key not work?</a></li> 272<li><a href="#hashsymlinks">Why is client authentication broken after 273upgrading from SSLeay version 0.8 to 0.9?</a></li> 274<li><a href="#pemder">How can I convert a certificate from PEM to DER 275format?</a></li> 276<li><a href="#verisign">Why can't I find the 277<code>getca</code> or <code>getverisign</code> programs mentioned by 278Verisign, for installing my Verisign certificate?</a></li> 279<li><a href="#sgc">Can I use the Server Gated Cryptography (SGC) 280facility (aka Verisign Global ID) with mod_ssl?</a></li> 281<li><a href="#gid">Why do browsers complain that they cannot 282verify my server certificate?</a></li> 283</ul> 284 285<h3><a name="keyscerts" id="keyscerts">What are RSA Private Keys, CSRs and Certificates?</a></h3> 286<p>An RSA private key file is a digital file that you can use to decrypt 287 messages sent to you. It has a public component which you distribute (via 288 your Certificate file) which allows people to encrypt those messages to 289 you.</p> 290 <p>A Certificate Signing Request (CSR) is a digital file which contains 291 your public key and your name. You send the CSR to a Certifying Authority 292 (CA), who will convert it into a real Certificate, by signing it.</p> 293 <p>A Certificate contains your 294 RSA public key, your name, the name of the CA, and is digitally signed by 295 the CA. Browsers that know the CA can verify the signature on that 296 Certificate, thereby obtaining your RSA public key. That enables them to 297 send messages which only you can decrypt.</p> 298 <p>See the <a href="ssl_intro.html">Introduction</a> chapter for a general 299 description of the SSL protocol.</p> 300 301 302<h3><a name="startup" id="startup">Is there a difference on startup between 303 a non-SSL-aware Apache and an SSL-aware Apache?</a></h3> 304<p>Yes. In general, starting Apache with 305 <code class="module"><a href="/mod/mod_ssl.html">mod_ssl</a></code> built-in is just like starting Apache 306 without it. However, if you have a passphrase on your SSL private 307 key file, a startup dialog will pop up which asks you to enter the 308 pass phrase.</p> 309 310 <p>Having to manually enter the passphrase when starting the server 311 can be problematic - for example, when starting the server from the 312 system boot scripts. In this case, you can follow the steps 313 <a href="#removepassphrase">below</a> to remove the passphrase from 314 your private key. Bear in mind that doing so brings additional security 315 risks - proceed with caution!</p> 316 317 318<h3><a name="selfcert" id="selfcert">How do I create a self-signed SSL 319Certificate for testing purposes?</a></h3> 320 <ol> 321 <li>Make sure OpenSSL is installed and in your <code>PATH</code>.<br /> 322 <br /> 323 </li> 324 <li>Run the following command, to create <code>server.key</code> and 325 <code>server.crt</code> files:<br /> 326 <code><strong>$ openssl req -new -x509 -nodes -out server.crt 327 -keyout server.key</strong></code><br /> 328 These can be used as follows in your <code>httpd.conf</code> 329 file: 330 <pre> 331 SSLCertificateFile /path/to/this/server.crt 332 SSLCertificateKeyFile /path/to/this/server.key 333 </pre> 334 </li> 335 <li>It is important that you are aware that this 336 <code>server.key</code> does <em>not</em> have any passphrase. 337 To add a passphrase to the key, you should run the following 338 command, and enter & verify the passphrase as requested.<br /> 339 <p><code><strong>$ openssl rsa -des3 -in server.key -out 340 server.key.new</strong></code><br /> 341 <code><strong>$ mv server.key.new server.key</strong></code><br /></p> 342 Please backup the <code>server.key</code> file, and the passphrase 343 you entered, in a secure location. 344 </li> 345 </ol> 346 347 348<h3><a name="realcert" id="realcert">How do I create a real SSL Certificate?</a></h3> 349<p>Here is a step-by-step description:</p> 350 <ol> 351 <li>Make sure OpenSSL is installed and in your <code>PATH</code>. 352 <br /> 353 <br /> 354 </li> 355 <li>Create a RSA private key for your Apache server 356 (will be Triple-DES encrypted and PEM formatted):<br /> 357 <br /> 358 <code><strong>$ openssl genrsa -des3 -out server.key 1024</strong></code><br /> 359 <br /> 360 Please backup this <code>server.key</code> file and the 361 pass-phrase you entered in a secure location. 362 You can see the details of this RSA private key by using the command:<br /> 363 364 <br /> 365 <code><strong>$ openssl rsa -noout -text -in server.key</strong></code><br /> 366 <br /> 367 If necessary, you can also create a decrypted PEM version (not 368 recommended) of this RSA private key with:<br /> 369 <br /> 370 <code><strong>$ openssl rsa -in server.key -out server.key.unsecure</strong></code><br /> 371 <br /> 372 373 </li> 374 <li>Create a Certificate Signing Request (CSR) with the server RSA private 375 key (output will be PEM formatted):<br /> 376 <br /> 377 <code><strong>$ openssl req -new -key server.key -out server.csr</strong></code><br /> 378 <br /> 379 Make sure you enter the FQDN ("Fully Qualified Domain Name") of the 380 server when OpenSSL prompts you for the "CommonName", i.e. when you 381 generate a CSR for a website which will be later accessed via 382 <code>https://www.foo.dom/</code>, enter "www.foo.dom" here. 383 You can see the details of this CSR by using<br /> 384 385 <br /> 386 <code><strong>$ openssl req -noout -text -in server.csr</strong></code><br /> 387 <br /> 388 </li> 389 <li>You now have to send this Certificate Signing Request (CSR) to 390 a Certifying Authority (CA) to be signed. Once the CSR has been 391 signed, you will have a real Certificate, which can be used by 392 Apache. You can have a CSR signed by a commercial CA, or you can 393 create your own CA to sign it.<br /> 394 Commercial CAs usually ask you to post the CSR into a web form, 395 pay for the signing, and then send a signed Certificate, which 396 you can store in a server.crt file. For more information about 397 commercial CAs see the following locations:<br /> 398 <br /> 399 <ol> 400 <li> Verisign<br /> 401 <a href="http://digitalid.verisign.com/server/apacheNotice.htm"> 402 http://digitalid.verisign.com/server/apacheNotice.htm 403 </a> 404 </li> 405 <li> Thawte<br /> 406 <a href="http://www.thawte.com/">http://www.thawte.com/</a> 407 </li> 408 <li> CertiSign Certificadora Digital Ltda.<br /> 409 <a href="http://www.certisign.com.br"> 410 http://www.certisign.com.br 411 </a> 412 </li> 413 <li> IKS GmbH<br /> 414 <a href="http://www.iks-jena.de/leistungen/ca/"> 415 http://www.iks-jena.de/leistungen/ca/ 416 </a> 417 </li> 418 <li> Uptime Commerce Ltd.<br /> 419 <a href="http://www.uptimecommerce.com"> 420 http://www.uptimecommerce.com 421 </a> 422 </li> 423 <li> BelSign NV/SA<br /> 424 <a href="http://www.belsign.be"> 425 http://www.belsign.be 426 </a> 427 </li> 428 </ol> 429 430 For details on how to create your own CA, and use this to sign 431 a CSR, see <a href="#ownca">below</a>.<br /> 432 433 Once your CSR has been signed, you can see the details of the 434 Certificate as follows:<br /> 435 <br /> 436 <code><strong>$ openssl x509 -noout -text -in server.crt</strong></code><br /> 437 438 </li> 439 <li>You should now have two files: <code>server.key</code> and 440 <code>server.crt</code>. These can be used as follows in your 441 <code>httpd.conf</code> file: 442 <pre> 443 SSLCertificateFile /path/to/this/server.crt 444 SSLCertificateKeyFile /path/to/this/server.key 445 </pre> 446 The <code>server.csr</code> file is no longer needed. 447 </li> 448 449 </ol> 450 451 452<h3><a name="ownca" id="ownca">How do I create and use my own Certificate Authority (CA)?</a></h3> 453 <p>The short answer is to use the <code>CA.sh</code> or <code>CA.pl</code> 454 script provided by OpenSSL. Unless you have a good reason not to, 455 you should use these for preference. If you cannot, you can create a 456 self-signed Certificate as follows:</p> 457 458 <ol> 459 <li>Create a RSA private key for your server 460 (will be Triple-DES encrypted and PEM formatted):<br /> 461 <br /> 462 <code><strong>$ openssl genrsa -des3 -out server.key 1024</strong></code><br /> 463 <br /> 464 Please backup this <code>host.key</code> file and the 465 pass-phrase you entered in a secure location. 466 You can see the details of this RSA private key by using the 467 command:<br /> 468 <code><strong>$ openssl rsa -noout -text -in server.key</strong></code><br /> 469 <br /> 470 If necessary, you can also create a decrypted PEM version (not 471 recommended) of this RSA private key with:<br /> 472 <br /> 473 <code><strong>$ openssl rsa -in server.key -out server.key.unsecure</strong></code><br /> 474 <br /> 475 </li> 476 <li>Create a self-signed Certificate (X509 structure) 477 with the RSA key you just created (output will be PEM formatted):<br /> 478 <br /> 479 <code><strong>$ openssl req -new -x509 -nodes -sha1 -days 365 480 -key server.key -out server.crt</strong></code><br /> 481 <br /> 482 This signs the server CSR and results in a <code>server.crt</code> file.<br /> 483 You can see the details of this Certificate using:<br /> 484 <br /> 485 <code><strong>$ openssl x509 -noout -text -in server.crt</strong></code><br /> 486 <br /> 487 </li> 488 </ol> 489 490 491<h3><a name="passphrase" id="passphrase">How can I change the pass-phrase on my private key file?</a></h3> 492<p>You simply have to read it with the old pass-phrase and write it again, 493 specifying the new pass-phrase. You can accomplish this with the following 494 commands:</p> 495 496 497 <p><code><strong>$ openssl rsa -des3 -in server.key -out server.key.new</strong></code><br /> 498 <code><strong>$ mv server.key.new server.key</strong></code><br /></p> 499 500 <p>The first time you're asked for a PEM pass-phrase, you should 501 enter the old pass-phrase. After that, you'll be asked again to 502 enter a pass-phrase - this time, use the new pass-phrase. If you 503 are asked to verify the pass-phrase, you'll need to enter the new 504 pass-phrase a second time.</p> 505 506 507<h3><a name="removepassphrase" id="removepassphrase">How can I get rid of the pass-phrase dialog at Apache startup time?</a></h3> 508<p>The reason this dialog pops up at startup and every re-start 509 is that the RSA private key inside your server.key file is stored in 510 encrypted format for security reasons. The pass-phrase is needed to decrypt 511 this file, so it can be read and parsed. Removing the pass-phrase 512 removes a layer of security from your server - proceed with caution!</p> 513 <ol> 514 <li>Remove the encryption from the RSA private key (while 515 keeping a backup copy of the original file):<br /> 516 <br /> 517 <code><strong>$ cp server.key server.key.org</strong></code><br /> 518 <code><strong>$ openssl rsa -in server.key.org -out server.key</strong></code><br /> 519 520 <br /> 521 </li> 522 <li>Make sure the server.key file is only readable by root:<br /> 523 <br /> 524 <code><strong>$ chmod 400 server.key</strong></code><br /> 525 <br /> 526 </li> 527 </ol> 528 529 <p>Now <code>server.key</code> contains an unencrypted copy of the key. 530 If you point your server at this file, it will not prompt you for a 531 pass-phrase. HOWEVER, if anyone gets this key they will be able to 532 impersonate you on the net. PLEASE make sure that the permissions on this 533 file are such that only root or the web server user can read it 534 (preferably get your web server to start as root but run as another 535 user, and have the key readable only by root).</p> 536 537 <p>As an alternative approach you can use the ``<code>SSLPassPhraseDialog 538 exec:/path/to/program</code>'' facility. Bear in mind that this is 539 neither more nor less secure, of course.</p> 540 541 542<h3><a name="verify" id="verify">How do I verify that a private key matches its Certificate?</a></h3> 543<p>A private key contains a series of numbers. Two of these numbers form 544 the "public key", the others are part of the "private key". The "public 545 key" bits are included when you generate a CSR, and subsequently form 546 part of the associated Certificate.</p> 547 <p>To check that the public key in your Certificate matches the public 548 portion of your private key, you simply need to compare these numbers. 549 To view the Certificate and the key run the commands:</p> 550 551 <p><code><strong>$ openssl x509 -noout -text -in server.crt</strong></code><br /> 552 <code><strong>$ openssl rsa -noout -text -in server.key</strong></code></p> 553 554 <p>The `modulus' and the `public exponent' portions in the key and the 555 Certificate must match. As the public exponent is usually 65537 556 and it's difficult to visually check that the long modulus numbers 557 are the same, you can use the following approach:</p> 558 559 <p><code><strong>$ openssl x509 -noout -modulus -in server.crt | openssl md5</strong></code><br /> 560 <code><strong>$ openssl rsa -noout -modulus -in server.key | openssl md5</strong></code></p> 561 562 <p>This leaves you with two rather shorter numbers to compare. It is, 563 in theory, possible that these numbers may be the same, without the 564 modulus numbers being the same, but the chances of this are 565 overwhelmingly remote.</p> 566 <p>Should you wish to check to which key or certificate a particular 567 CSR belongs you can perform the same calculation on the CSR as 568 follows:</p> 569 570 <p><code><strong>$ openssl req -noout -modulus -in server.csr | openssl md5</strong></code></p> 571 572 573<h3><a name="badcert" id="badcert">Why do connections fail with an "alert 574bad certificate" error?</a></h3> 575<p>Errors such as <code>OpenSSL: error:14094412: SSL 576 routines:SSL3_READ_BYTES:sslv3 alert bad certificate</code> in the SSL 577 logfile, are usually caused by a browser which is unable to handle the server 578 certificate/private-key. For example, Netscape Navigator 3.x is 579 unable to handle RSA key lengths not equal to 1024 bits.</p> 580 581 582<h3><a name="keysize" id="keysize">Why does my 2048-bit private key not work?</a></h3> 583<p>The private key sizes for SSL must be either 512 or 1024 bits, for compatibility 584 with certain web browsers. A keysize of 1024 bits is recommended because 585 keys larger than 1024 bits are incompatible with some versions of Netscape 586 Navigator and Microsoft Internet Explorer, and with other browsers that 587 use RSA's BSAFE cryptography toolkit.</p> 588 589 590<h3><a name="hashsymlinks" id="hashsymlinks">Why is client authentication broken after upgrading from 591SSLeay version 0.8 to 0.9?</a></h3> 592<p>The CA certificates under the path you configured with 593 <code>SSLCACertificatePath</code> are found by SSLeay through hash 594 symlinks. These hash values are generated by the `<code>openssl x509 -noout 595 -hash</code>' command. However, the algorithm used to calculate the hash for a 596 certificate changed between SSLeay 0.8 and 0.9. You will need to remove 597 all old hash symlinks and create new ones after upgrading. Use the 598 <code>Makefile</code> provided by <code class="module"><a href="/mod/mod_ssl.html">mod_ssl</a></code>.</p> 599 600 601<h3><a name="pemder" id="pemder">How can I convert a certificate from PEM to DER format?</a></h3> 602<p>The default certificate format for SSLeay/OpenSSL is PEM, which is simply 603 Base64 encoded DER, with header and footer lines. For some applications 604 (e.g. Microsoft Internet Explorer) you need the certificate in plain DER 605 format. You can convert a PEM file <code>cert.pem</code> into the 606 corresponding DER file <code>cert.der</code> using the following command: 607 <code><strong>$ openssl x509 -in cert.pem -out cert.der -outform DER</strong></code></p> 608 609 610<h3><a name="verisign" id="verisign">Why can't I find the 611<code>getca</code> or <code>getverisign</code> programs mentioned by 612Verisign, for installing my Verisign certificate?</a></h3> 613<p>Verisign has never provided specific instructions 614 for Apache+mod_ssl. The instructions provided are for C2Net's 615 Stronghold (a commercial Apache based server with SSL support).</p> 616 <p>To install your certificate, all you need to do is to save the 617 certificate to a file, and give the name of that file to the 618 <code class="directive"><a href="/mod/mod_ssl.html#sslcertificatefile">SSLCertificateFile</a></code> directive. 619 You will also need to give it the key file. For more information, 620 see the <code class="directive"><a href="/mod/mod_ssl.html#sslcertificatekeyfile">SSLCertificateKeyFile</a></code> 621 directive.</p> 622 623 624<h3><a name="sgc" id="sgc">Can I use the Server Gated Cryptography (SGC) 625facility (aka Verisign Global ID) with mod_ssl?</a></h3> 626<p>Yes. <code class="module"><a href="/mod/mod_ssl.html">mod_ssl</a></code> has included support for the SGC 627 facility since version 2.1. No special configuration is required - 628 just use the Global ID as your server certificate. The 629 <em>step up</em> of the clients is then automatically handled by 630 <code class="module"><a href="/mod/mod_ssl.html">mod_ssl</a></code> at run-time.</p> 631 632 633<h3><a name="gid" id="gid">Why do browsers complain that they cannot 634verify my server certificate?</a></h3> 635 <p>One reason this might happen is because your server certificate is signed 636 by an intermediate CA. Various CAs, such as Verisign or Thawte, have started 637 signing certificates not with their root certificate but with intermediate 638 certificates.</p> 639 640 <p>Intermediate CA certificates lie between the root CA certificate (which is 641 installed in the browsers) and the server certificate (which you installed 642 on the server). In order for the browser to be able to traverse and verify 643 the trust chain from the server certificate to the root certificate it 644 needs need to be given the intermediate certificates. The CAs should 645 be able to provide you such intermediate certificate packages that can be 646 installed on the server.</p> 647 648 <p>You need to include those intermediate certificates with the 649 <code class="directive"><a href="/mod/mod_ssl.html#sslcertificatechainfile">SSLCertificateChainFile</a></code> 650 directive.</p> 651 652</div><div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 653<div class="section"> 654<h2><a name="aboutssl" id="aboutssl">The SSL Protocol</a></h2> 655<ul> 656<li><a href="#random">Why do I get lots of random SSL protocol 657errors under heavy server load?</a></li> 658<li><a href="#load">Why does my webserver have a higher load, now 659that it serves SSL encrypted traffic?</a></li> 660<li><a href="#establishing">Why do HTTPS connections to my server 661sometimes take up to 30 seconds to establish a connection?</a></li> 662<li><a href="#ciphers">What SSL Ciphers are supported by mod_ssl?</a></li> 663<li><a href="#adh">Why do I get ``no shared cipher'' errors, when 664trying to use Anonymous Diffie-Hellman (ADH) ciphers?</a></li> 665<li><a href="#sharedciphers">Why do I get a 'no shared ciphers' 666error when connecting to my newly installed server?</a></li> 667<li><a href="#vhosts">Why can't I use SSL with name-based/non-IP-based 668virtual hosts?</a></li> 669<li><a href="#vhosts2">Is it possible to use Name-Based Virtual 670Hosting to identify different SSL virtual hosts?</a></li> 671<li><a href="#comp">How do I get SSL compression working?</a></li> 672<li><a href="#lockicon">When I use Basic Authentication over HTTPS 673the lock icon in Netscape browsers stays unlocked when the dialog pops up. 674Does this mean the username/password is being sent unencrypted?</a></li> 675<li><a href="#msie">Why do I get I/O errors when connecting via 676HTTPS to an Apache+mod_ssl server with Microsoft Internet Explorer 677(MSIE)?</a></li> 678<li><a href="#nn">Why do I get I/O errors, or the message "Netscape has 679encountered bad data from the server", when connecting via 680HTTPS to an Apache+mod_ssl server with Netscape Navigator?</a></li> 681</ul> 682 683<h3><a name="random" id="random">Why do I get lots of random SSL protocol 684errors under heavy server load?</a></h3> 685<p>There can be a number of reasons for this, but the main one 686 is problems with the SSL session Cache specified by the 687 <code class="directive"><a href="/mod/mod_ssl.html#sslsessioncache">SSLSessionCache</a></code> directive. The DBM session 688 cache is the most likely source of the problem, so using the SHM session cache (or 689 no cache at all) may help.</p> 690 691 692<h3><a name="load" id="load">Why does my webserver have a higher load, now 693that it serves SSL encrypted traffic?</a></h3> 694<p>SSL uses strong cryptographic encryption, which necessitates a lot of 695 number crunching. When you request a webpage via HTTPS, everything (even 696 the images) is encrypted before it is transferred. So increased HTTPS 697 traffic leads to load increases.</p> 698 699 700<h3><a name="establishing" id="establishing">Why do HTTPS connections to my server 701sometimes take up to 30 seconds to establish a connection?</a></h3> 702<p>This is usually caused by a <code>/dev/random</code> device for 703 <code class="directive"><a href="/mod/mod_ssl.html#sslrandomseed">SSLRandomSeed</a></code> which blocks the 704 read(2) call until enough entropy is available to service the 705 request. More information is available in the reference 706 manual for the <code class="directive"><a href="/mod/mod_ssl.html#sslrandomseed">SSLRandomSeed</a></code> 707 directive.</p> 708 709 710<h3><a name="ciphers" id="ciphers">What SSL Ciphers are supported by mod_ssl?</a></h3> 711<p>Usually, any SSL ciphers supported by the version of OpenSSL in use, 712 are also supported by <code class="module"><a href="/mod/mod_ssl.html">mod_ssl</a></code>. Which ciphers are 713 available can depend on the way you built OpenSSL. Typically, at 714 least the following ciphers are supported:</p> 715 716 <ol> 717 <li>RC4 with MD5</li> 718 <li>RC4 with MD5 (export version restricted to 40-bit key)</li> 719 <li>RC2 with MD5</li> 720 <li>RC2 with MD5 (export version restricted to 40-bit key)</li> 721 <li>IDEA with MD5</li> 722 <li>DES with MD5</li> 723 <li>Triple-DES with MD5</li> 724 </ol> 725 726 <p>To determine the actual list of ciphers available, you should run 727 the following:</p> 728 <div class="example"><p><code>$ openssl ciphers -v</code></p></div> 729 730 731<h3><a name="adh" id="adh">Why do I get ``no shared cipher'' errors, when 732trying to use Anonymous Diffie-Hellman (ADH) ciphers?</a></h3> 733<p>By default, OpenSSL does <em>not</em> allow ADH ciphers, for security 734 reasons. Please be sure you are aware of the potential side-effects 735 if you choose to enable these ciphers.</p> 736 <p>In order to use Anonymous Diffie-Hellman (ADH) ciphers, you must 737 build OpenSSL with ``<code>-DSSL_ALLOW_ADH</code>'', and then add 738 ``<code>ADH</code>'' into your <code class="directive"><a href="/mod/mod_ssl.html#sslciphersuite">SSLCipherSuite</a></code>.</p> 739 740 741<h3><a name="sharedciphers" id="sharedciphers">Why do I get a 'no shared ciphers' 742error when connecting to my newly installed server?</a></h3> 743<p>Either you have made a mistake with your 744 <code class="directive"><a href="/mod/mod_ssl.html#sslciphersuite">SSLCipherSuite</a></code> 745 directive (compare it with the pre-configured example in 746 <code>httpd.conf-dist</code>) or you chose to use DSA/DH 747 algorithms instead of RSA when you generated your private key 748 and ignored or overlooked the warnings. If you have chosen 749 DSA/DH, then your server cannot communicate using RSA-based SSL 750 ciphers (at least until you configure an additional RSA-based 751 certificate/key pair). Modern browsers like NS or IE can only 752 communicate over SSL using RSA ciphers. The result is the 753 "no shared ciphers" error. To fix this, regenerate your server 754 certificate/key pair, using the RSA algorithm.</p> 755 756 757<h3><a name="vhosts" id="vhosts">Why can't I use SSL with name-based/non-IP-based virtual hosts?</a></h3> 758<p>The reason is very technical, and a somewhat "chicken and egg" problem. 759 The SSL protocol layer stays below the HTTP protocol layer and 760 encapsulates HTTP. When an SSL connection (HTTPS) is established 761 Apache/mod_ssl has to negotiate the SSL protocol parameters with the 762 client. For this, mod_ssl has to consult the configuration of the virtual 763 server (for instance it has to look for the cipher suite, the server 764 certificate, etc.). But in order to go to the correct virtual server 765 Apache has to know the <code>Host</code> HTTP header field. To do this, the 766 HTTP request header has to be read. This cannot be done before the SSL 767 handshake is finished, but the information is needed in order to 768 complete the SSL handshake phase. See the next question for how to 769 circumvent this issue.</p> 770 771 <p>Note that if you have a wildcard SSL certificate, or a 772 certificate that has multiple hostnames on it using subjectAltName 773 fields, you can use SSL on name-based virtual hosts without further 774 workarounds.</p> 775 776 777<h3><a name="vhosts2" id="vhosts2">Why is it not possible to use Name-Based 778Virtual Hosting to identify different SSL virtual hosts?</a></h3> 779 <p>Name-Based Virtual Hosting is a very popular method of identifying 780 different virtual hosts. It allows you to use the same IP address and 781 the same port number for many different sites. When people move on to 782 SSL, it seems natural to assume that the same method can be used to have 783 lots of different SSL virtual hosts on the same server.</p> 784 785 <p>It is possible, but only if using a 2.2.12 or later web server, 786 built with 0.9.8j or later OpenSSL. This is because it requires a 787 feature that only the most recent revisions of the SSL 788 specification added, called Server Name Indication (SNI).</p> 789 790 <p>Note that if you have a wildcard SSL certificate, or a 791 certificate that has multiple hostnames on it using subjectAltName 792 fields, you can use SSL on name-based virtual hosts without further 793 workarounds.</p> 794 795 <p>The reason is that the SSL protocol is a separate layer which 796 encapsulates the HTTP protocol. So the SSL session is a separate 797 transaction, that takes place before the HTTP session has begun. 798 The server receives an SSL request on IP address X and port Y 799 (usually 443). Since the SSL request did not contain any Host: 800 field, the server had no way to decide which SSL virtual host to use. 801 Usually, it just used the first one it found which matched the 802 port and IP address specified.</p> 803 804 <p>If you are using a version of the web server and OpenSSL that 805 support SNI, though, and the client's browser also supports SNI, 806 then the hostname is included in the original SSL request, and the 807 web server can select the correct SSL virtual host.</p> 808 809 <p>You can, of course, use Name-Based Virtual Hosting to identify many 810 non-SSL virtual hosts (all on port 80, for example) and then 811 have a single SSL virtual host (on port 443). But if you do this, 812 you must make sure to put the non-SSL port number on the NameVirtualHost 813 directive, e.g.</p> 814 815 <div class="example"><p><code> 816 NameVirtualHost 192.168.1.1:80 817 </code></p></div> 818 819 <p>Other workaround solutions include: </p> 820 821 <p>Using separate IP addresses for different SSL hosts. 822 Using different port numbers for different SSL hosts.</p> 823 824 825<h3><a name="comp" id="comp">How do I get SSL compression working?</a></h3> 826<p>Although SSL compression negotiation was defined in the specification 827of SSLv2 and TLS, it took until May 2004 for RFC 3749 to define DEFLATE as 828a negotiable standard compression method. 829</p> 830<p>OpenSSL 0.9.8 started to support this by default when compiled with the 831<code>zlib</code> option. If both the client and the server support compression, 832it will be used. However, most clients still try to initially connect with an 833SSLv2 Hello. As SSLv2 did not include an array of prefered compression algorithms 834in its handshake, compression cannot be negotiated with these clients. 835If the client disables support for SSLv2, either an SSLv3 or TLS Hello 836may be sent, depending on which SSL library is used, and compression may 837be set up. You can verify whether clients make use of SSL compression by 838logging the <code>%{SSL_COMPRESS_METHOD}x</code> variable. 839</p> 840 841 842<h3><a name="lockicon" id="lockicon">When I use Basic Authentication over HTTPS 843the lock icon in Netscape browsers stays unlocked when the dialog pops up. 844Does this mean the username/password is being sent unencrypted?</a></h3> 845<p>No, the username/password is transmitted encrypted. The icon in 846 Netscape browsers is not actually synchronized with the SSL/TLS layer. 847 It only toggles to the locked state when the first part of the actual 848 webpage data is transferred, which may confuse people. The Basic 849 Authentication facility is part of the HTTP layer, which is above 850 the SSL/TLS layer in HTTPS. Before any HTTP data communication takes 851 place in HTTPS, the SSL/TLS layer has already completed its handshake 852 phase, and switched to encrypted communication. So don't be 853 confused by this icon.</p> 854 855 856<h3><a name="msie" id="msie">Why do I get I/O errors when connecting via 857HTTPS to an Apache+mod_ssl server with Microsoft Internet Explorer (MSIE)?</a></h3> 858<p>The first reason is that the SSL implementation in some MSIE versions has 859 some subtle bugs related to the HTTP keep-alive facility and the SSL close 860 notify alerts on socket connection close. Additionally the interaction 861 between SSL and HTTP/1.1 features are problematic in some MSIE versions. 862 You can work around these problems by forcing Apache not to use HTTP/1.1, 863 keep-alive connections or send the SSL close notify messages to MSIE clients. 864 This can be done by using the following directive in your SSL-aware 865 virtual host section:</p> 866 <div class="example"><p><code> 867 SetEnvIf User-Agent ".*MSIE.*" \<br /> 868 nokeepalive ssl-unclean-shutdown \<br /> 869 downgrade-1.0 force-response-1.0 870 </code></p></div> 871 <p>Further, some MSIE versions have problems with particular ciphers. 872 Unfortunately, it is not possible to implement a MSIE-specific 873 workaround for this, because the ciphers are needed as early as the 874 SSL handshake phase. So a MSIE-specific 875 <code class="directive"><a href="/mod/mod_setenvif.html#setenvif">SetEnvIf</a></code> won't solve these 876 problems. Instead, you will have to make more drastic 877 adjustments to the global parameters. Before you decide to do 878 this, make sure your clients really have problems. If not, do not 879 make these changes - they will affect <em>all</em> your clients, MSIE 880 or otherwise.</p> 881 882 <p>The next problem is that 56bit export versions of MSIE 5.x 883 browsers have a broken SSLv3 implementation, which interacts badly 884 with OpenSSL versions greater than 0.9.4. You can accept this and 885 require your clients to upgrade their browsers, you can downgrade to 886 OpenSSL 0.9.4 (not advised), or you can work around this, accepting 887 that your workaround will affect other browsers too:</p> 888 <div class="example"><p><code>SSLProtocol all -SSLv3</code></p></div> 889 <p>will completely disables the SSLv3 protocol and allow those 890 browsers to work. A better workaround is to disable only those 891 ciphers which cause trouble.</p> 892 <div class="example"><p><code>SSLCipherSuite 893 ALL:!ADH:<strong>!EXPORT56</strong>:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP</code> 894 </p></div> 895 896 <p>This also allows the broken MSIE versions to work, but only removes the 897 newer 56bit TLS ciphers.</p> 898 899 <p>Another problem with MSIE 5.x clients is that they refuse to connect to 900 URLs of the form <code>https://12.34.56.78/</code> (where IP-addresses are used 901 instead of the hostname), if the server is using the Server Gated 902 Cryptography (SGC) facility. This can only be avoided by using the fully 903 qualified domain name (FQDN) of the website in hyperlinks instead, because 904 MSIE 5.x has an error in the way it handles the SGC negotiation.</p> 905 906 <p>And finally there are versions of MSIE which seem to require that 907 an SSL session can be reused (a totally non standard-conforming 908 behaviour, of course). Connecting with those MSIE versions only work 909 if a SSL session cache is used. So, as a work-around, make sure you 910 are using a session cache (see the <code class="directive"><a href="/mod/mod_ssl.html#sslsessioncache">SSLSessionCache</a></code> directive).</p> 911 912 913<h3><a name="nn" id="nn">Why do I get I/O errors, or the message "Netscape has 914encountered bad data from the server", when connecting via 915HTTPS to an Apache+mod_ssl server with Netscape Navigator?</a></h3> 916<p> 917 This usually occurs when you have created a new server certificate for 918 a given domain, but had previously told your browser to always accept 919 the old server certificate. Once you clear the entry for the old 920 certificate from your browser, everything should be fine. Netscape's SSL 921 implementation is correct, so when you encounter I/O errors with Netscape 922 Navigator it is usually caused by the configured certificates.</p> 923 924</div><div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 925<div class="section"> 926<h2><a name="support" id="support">mod_ssl Support</a></h2> 927<ul> 928<li><a href="#resources">What information resources are available in 929case of mod_ssl problems?</a></li> 930<li><a href="#contact">What support contacts are available in case of 931mod_ssl problems?</a></li> 932<li><a href="#reportdetails">What information should I 933provide when writing a bug report?</a></li> 934<li><a href="#coredumphelp">I had a core dump, can you help me?</a></li> 935<li><a href="#backtrace">How do I get a backtrace, to help find the reason 936for my core dump?</a></li> 937</ul> 938 939<h3><a name="resources" id="resources">What information resources are available in case of mod_ssl problems?</a></h3> 940<p>The following information resources are available. 941 In case of problems you should search here first.</p> 942 943 <dl> 944 <dt>Answers in the User Manual's F.A.Q. List (this)</dt> 945 <dd><a href="http://httpd.apache.org/docs/2.2/ssl/ssl_faq.html"> 946 http://httpd.apache.org/docs/2.2/ssl/ssl_faq.html</a><br /> 947 First check the F.A.Q. (this text). If your problem is a common 948 one, it may have been answered several times before, and been included 949 in this doc. 950 </dd> 951 <dt>Postings from the modssl-users Support Mailing List 952 <a href="http://www.modssl.org/support/">http://www.modssl.org/support/</a></dt> 953 <dd>Search for your problem in the archives of the modssl-users mailing list. 954 You're probably not the first person to have had this problem! 955 </dd> 956 </dl> 957 958 959<h3><a name="contact" id="contact">What support contacts are available in case 960of mod_ssl problems?</a></h3> 961 <p>The following lists all support possibilities for mod_ssl, in order of 962 preference. Please go through these possibilities 963 <em>in this order</em> - don't just pick the one you like the look of. </p> 964 <ol> 965 <li><em>Send a Problem Report to the modssl-users Support Mailing List</em><br /> 966 <a href="mailto:modssl-users@modssl.org"> 967 modssl-users@modssl.org</a><br /> 968 This is the preferred way of submitting your problem report, because this way, 969 others can see the problem, and learn from any answers. You must subscribe to 970 the list first, but you can then easily discuss your problem with both the 971 author and the whole mod_ssl user community. 972 </li> 973 974 <li><em>Send a Problem Report to the Apache httpd Users Support Mailing List</em><br /> 975 <a href="mailto:users@httpd.apache.org"> 976 users@httpd.apache.org</a><br /> 977 This is the second way of submitting your problem report. Again, you must 978 subscribe to the list first, but you can then easily discuss your problem 979 with the whole Apache httpd user community. 980 </li> 981 982 <li><em>Write a Problem Report in the Bug Database</em><br /> 983 <a href="http://httpd.apache.org/bug_report.html"> 984 http://httpd.apache.org/bug_report.html</a><br /> 985 This is the last way of submitting your problem report. You should only 986 do this if you've already posted to the mailing lists, and had no success. 987 Please follow the instructions on the above page <em>carefully</em>. 988 </li> 989 </ol> 990 991 992<h3><a name="reportdetails" id="reportdetails">What information should I 993provide when writing a bug report?</a></h3> 994<p>You should always provide at least the following information:</p> 995 996 <dl> 997 <dt>Apache and OpenSSL version information</dt> 998 <dd>The Apache version can be determined 999 by running <code>httpd -v</code>. The OpenSSL version can be 1000 determined by running <code>openssl version</code>. Alternatively, if 1001 you have Lynx installed, you can run the command <code>lynx -mime_header 1002 http://localhost/ | grep Server</code> to gather this information in a 1003 single step. 1004 </dd> 1005 1006 <dt>The details on how you built and installed Apache+mod_ssl+OpenSSL</dt> 1007 <dd>For this you can provide a logfile of your terminal session which shows 1008 the configuration and install steps. If this is not possible, you 1009 should at least provide the <code class="program"><a href="/programs/configure.html">configure</a></code> command line you used. 1010 </dd> 1011 1012 <dt>In case of core dumps please include a Backtrace</dt> 1013 <dd>If your Apache+mod_ssl+OpenSSL dumps its core, please attach 1014 a stack-frame ``backtrace'' (see <a href="#backtrace">below</a> 1015 for information on how to get this). This information is required 1016 in order to find a reason for your core dump. 1017 </dd> 1018 1019 <dt>A detailed description of your problem</dt> 1020 <dd>Don't laugh, we really mean it! Many problem reports don't 1021 include a description of what the actual problem is. Without this, 1022 it's very difficult for anyone to help you. So, it's in your own 1023 interest (you want the problem be solved, don't you?) to include as 1024 much detail as possible, please. Of course, you should still include 1025 all the essentials above too. 1026 </dd> 1027 </dl> 1028 1029 1030<h3><a name="coredumphelp" id="coredumphelp">I had a core dump, can you help me?</a></h3> 1031<p>In general no, at least not unless you provide more details about the code 1032 location where Apache dumped core. What is usually always required in 1033 order to help you is a backtrace (see next question). Without this 1034 information it is mostly impossible to find the problem and help you in 1035 fixing it.</p> 1036 1037 1038<h3><a name="backtrace" id="backtrace">How do I get a backtrace, to help find 1039the reason for my core dump?</a></h3> 1040<p>Following are the steps you will need to complete, to get a backtrace:</p> 1041 <ol> 1042 <li>Make sure you have debugging symbols available, at least 1043 in Apache. On platforms where you use GCC/GDB, you will have to build 1044 Apache+mod_ssl with ``<code>OPTIM="-g -ggdb3"</code>'' to get this. On 1045 other platforms at least ``<code>OPTIM="-g"</code>'' is needed. 1046 </li> 1047 1048 <li>Start the server and try to reproduce the core-dump. For this you may 1049 want to use a directive like ``<code>CoreDumpDirectory /tmp</code>'' to 1050 make sure that the core-dump file can be written. This should result 1051 in a <code>/tmp/core</code> or <code>/tmp/httpd.core</code> file. If you 1052 don't get one of these, try running your server under a non-root UID. 1053 Many modern kernels do not allow a process to dump core after it has 1054 done a <code>setuid()</code> (unless it does an <code>exec()</code>) for 1055 security reasons (there can be privileged information left over in 1056 memory). If necessary, you can run <code>/path/to/httpd -X</code> 1057 manually to force Apache to not fork. 1058 </li> 1059 1060 <li>Analyze the core-dump. For this, run <code>gdb /path/to/httpd 1061 /tmp/httpd.core</code> or a similar command. In GDB, all you 1062 have to do then is to enter <code>bt</code>, and voila, you get the 1063 backtrace. For other debuggers consult your local debugger manual. 1064 </li> 1065 </ol> 1066 1067</div></div> 1068<div class="bottomlang"> 1069<p><span>Available Languages: </span><a href="/en/ssl/ssl_faq.html" title="English"> en </a></p> 1070</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> 1071<script type="text/javascript"><!--//--><![CDATA[//><!-- 1072var comments_shortname = 'httpd'; 1073var comments_identifier = 'http://httpd.apache.org/docs/2.2/ssl/ssl_faq.html'; 1074(function(w, d) { 1075 if (w.location.hostname.toLowerCase() == "httpd.apache.org") { 1076 d.write('<div id="comments_thread"><\/div>'); 1077 var s = d.createElement('script'); 1078 s.type = 'text/javascript'; 1079 s.async = true; 1080 s.src = 'https://comments.apache.org/show_comments.lua?site=' + comments_shortname + '&page=' + comments_identifier; 1081 (d.getElementsByTagName('head')[0] || d.getElementsByTagName('body')[0]).appendChild(s); 1082 } 1083 else { 1084 d.write('<div id="comments_thread">Comments are disabled for this page at the moment.<\/div>'); 1085 } 1086})(window, document); 1087//--><!]]></script></div><div id="footer"> 1088<p class="apache">Copyright 2013 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> 1089<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[//><!-- 1090if (typeof(prettyPrint) !== 'undefined') { 1091 prettyPrint(); 1092} 1093//--><!]]></script> 1094</body></html>