docs/manual/ssl/ssl_faq.html.en

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