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