You are viewing a plain text version of this content. The canonical link for it is here.
Posted to cvs@httpd.apache.org by nd...@apache.org on 2002/09/28 05:47:35 UTC
cvs commit: httpd-2.0/docs/manual/ssl index.xml ssl_compat.html.en ssl_compat.xml ssl_faq.html.en ssl_faq.xml index.html.en ssl_compat.html ssl_faq.html
nd 2002/09/27 20:47:35
Modified: docs/manual/ssl index.html.en
Added: docs/manual/ssl index.xml ssl_compat.html.en ssl_compat.xml
ssl_faq.html.en ssl_faq.xml
Removed: docs/manual/ssl ssl_compat.html ssl_faq.html
Log:
new SSL XML, part one
revised the original submission (mostly
markup changes and some structural rearranges)
Submitted by: Thomas Sj�gren <th...@northernsecurity.net>
Revision Changes Path
1.4 +14 -25 httpd-2.0/docs/manual/ssl/index.html.en
Index: index.html.en
===================================================================
RCS file: /home/cvs/httpd-2.0/docs/manual/ssl/index.html.en,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- index.html.en 25 Jul 2002 21:46:41 -0000 1.3
+++ index.html.en 28 Sep 2002 03:47:35 -0000 1.4
@@ -1,23 +1,16 @@
-<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
- "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
-
-<html xmlns="http://www.w3.org/1999/xhtml">
- <head>
-<title>Apache SSL/TLS Encryption</title>
-</head>
-
-<body bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#000080" alink="#FF0000">
-<!--#include virtual="header.html" -->
-
-<h1 align="center">SSL/TLS Strong Encryption</h1>
-
-<p>The Apache HTTP Server module <a href="../mod/mod_ssl.html">mod_ssl</a>
-provides an interface to the <a
-href="http://www.openssl.org/">OpenSSL</a> library, which provides
+<?xml version="1.0" encoding="ISO-8859-1"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en"><head><!--
+ XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
+ This file is generated from xml source: DO NOT EDIT
+ XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
+ --><title>Apache SSL/TLS Encryption - Apache HTTP Server</title><link href="../style/css/manual.css" rel="stylesheet" media="all" type="text/css" title="Main stylesheet" /><link href="../style/css/manual-loose-100pc.css" rel="alternate stylesheet" media="all" type="text/css" title="No Sidebar - Default font size" /><link href="../style/css/manual-print.css" rel="stylesheet" media="print" type="text/css" /><link href="../images/favicon.ico" rel="shortcut icon" /></head><body id="manual-page"><div id="page-header"><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><p class="apache">Apache HTTP Server Version 2.0</p><img alt="" src="../images/feather.gif" /></div><div class="up"><a href="./"><img title="<-" alt="<-" src="../images/left.gif" /></a></div><div id="path"><a href="http://www.apache.org/">Apache</a> > <a href="http://httpd.apache.org/">HTTP Server</a> > <a href="http://httpd.apache.org/docs-project/">Documentation</a> > <a href="../">Version 2.0</a></div><div id="page-content"><div id="preamble"><h1>Apache SSL/TLS Encryption</h1>
+<p>The Apache HTTP Server module <code class="module"><a href="../mod/mod_ssl.html">mod_ssl</a></code>
+provides an interface to the <a href="http://www.openssl.org/">OpenSSL</a> library, which provides
Strong Encryption using the Secure Sockets Layer and Transport Layer
Security protocols. The module and this documentation are based on
Ralf S. Engelschall's mod_ssl project.</p>
-
+</div><div id="quickview"><ul id="toc"><li><img alt="" src="../images/down.gif" /> <a href="#documentation">Documentation</a></li><li><img alt="" src="../images/down.gif" /> <a href="#mod-ssl">mod_ssl</a></li></ul></div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div><div class="section"><h2><a name="documentation" id="documentation">Documentation</a></h2>
<ul>
<li><a href="ssl_intro.html">Introduction</a></li>
<li><a href="ssl_compat.html">Compatibility</a></li>
@@ -25,12 +18,8 @@
<li><a href="ssl_faq.html">Frequently Asked Questions</a></li>
<li><a href="ssl_glossary.html">Glossary</a></li>
</ul>
-
+</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div><div class="section"><h2><a name="mod-ssl" id="mod-ssl">mod_ssl</a></h2>
<p>Extensive documentation on the directives and environment variables
-provided by this module is provided in the <a
-href="../mod/mod_ssl.html">mod_ssl reference documentation</a>.</p>
-
-
- <!--#include virtual="footer.html" -->
- </body>
-</html>
+provided by this module is provided in the <a href="../mod/mod_ssl.html">mod_ssl reference documentation</a>.
+</p>
+</div></div><div id="footer"><p class="apache">Maintained by the <a href="http://httpd.apache.org/docs-project/">Apache HTTP Server Documentation Project</a></p><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></body></html>
\ No newline at end of file
1.1 httpd-2.0/docs/manual/ssl/index.xml
Index: index.xml
===================================================================
<?xml version='1.0' encoding='UTF-8' ?>
<!DOCTYPE manualpage SYSTEM "../style/manualpage.dtd">
<?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
<manualpage>
<relativepath href=".."/>
<title>Apache SSL/TLS Encryption</title>
<summary>
<p>The Apache HTTP Server module <module>mod_ssl</module>
provides an interface to the <a
href="http://www.openssl.org/">OpenSSL</a> library, which provides
Strong Encryption using the Secure Sockets Layer and Transport Layer
Security protocols. The module and this documentation are based on
Ralf S. Engelschall's mod_ssl project.</p>
</summary>
<section id="documentation"><title>Documentation</title>
<ul>
<li><a href="ssl_intro.html">Introduction</a></li>
<li><a href="ssl_compat.html">Compatibility</a></li>
<li><a href="ssl_howto.html">How-To</a></li>
<li><a href="ssl_faq.html">Frequently Asked Questions</a></li>
<li><a href="ssl_glossary.html">Glossary</a></li>
</ul>
</section>
<section id="mod-ssl"><title>mod_ssl</title>
<p>Extensive documentation on the directives and environment variables
provided by this module is provided in the <a
href="../mod/mod_ssl.html">mod_ssl reference documentation</a>.
</p>
</section>
</manualpage>
1.1 httpd-2.0/docs/manual/ssl/ssl_compat.html.en
Index: ssl_compat.html.en
===================================================================
<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en"><head><!--
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
This file is generated from xml source: DO NOT EDIT
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
--><title>SSL/TLS Strong Encryption: Compatibility - Apache HTTP Server</title><link href="../style/css/manual.css" rel="stylesheet" media="all" type="text/css" title="Main stylesheet" /><link href="../style/css/manual-loose-100pc.css" rel="alternate stylesheet" media="all" type="text/css" title="No Sidebar - Default font size" /><link href="../style/css/manual-print.css" rel="stylesheet" media="print" type="text/css" /><link href="../images/favicon.ico" rel="shortcut icon" /></head><body id="manual-page"><div id="page-header"><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><p class="apache">Apache HTTP Server Version 2.0</p><img alt="" src="../images/feather.gif" /></div><div class="up"><a href="./"><img title="<-" alt="<-" src="../images/left.gif" /></a></div><div id="path"><a href="http://www.apache.org/">Apache</a> > <a href="http://httpd.apache.org/">HTTP Server</a> > <a href="http://httpd.apache.org/docs-project/">Documentation</a> > <a href="../">Version 2.0</a></div><div id="page-content"><div id="preamble"><h1>SSL/TLS Strong Encryption: Compatibility</h1>
<blockquote>
<p>All PCs are compatible. But some of
them are more compatible than others.</p>
<p class="cite">--<cite>Unknown</cite></p>
</blockquote>
<p>
Here we talk about backward compatibility to other SSL solutions. As you
perhaps know, mod_ssl is not the only existing SSL solution for Apache.
Actually there are four additional major products available on the market: Ben
Laurie's freely available <a href="http://www.apache-ssl.org/">Apache-SSL</a>
(from where mod_ssl were originally derived in 1998), RedHat's commercial <a href="http://www.redhat.com/products/product-details.phtml?id=rhsa">Secure Web
Server</a> (which is based on mod_ssl), Covalent's commercial <a href="http://raven.covalent.net/">Raven SSL Module</a> (also based on mod_ssl)
and finally C2Net's commercial product <a href="http://www.c2.net/products/stronghold/">Stronghold</a> (based on a
different evolution branch named Sioux up to Stronghold 2.x and based on
mod_ssl since Stronghold 3.x).</p>
<p>
The idea in mod_ssl is mainly the following: because mod_ssl provides mostly a
superset of the functionality of all other solutions we can easily provide
backward compatibility for most of the cases. Actually there are three
compatibility areas we currently address: configuration directives,
environment variables and custom log functions.</p>
</div><div id="quickview"><ul id="toc"><li><img alt="" src="../images/down.gif" /> <a href="#configuration">Configuration Directives</a></li><li><img alt="" src="../images/down.gif" /> <a href="#variables">Environment Variables</a></li><li><img alt="" src="../images/down.gif" /> <a href="#customlog">Custom Log Functions</a></li></ul></div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div><div class="section"><h2><a name="configuration" id="configuration">Configuration Directives</a></h2>
<p>For backward compatibility to the configuration directives of other SSL
solutions we do an on-the-fly mapping: directives which have a direct
counterpart in mod_ssl are mapped silently while other directives lead to a
warning message in the logfiles. The currently implemented directive mapping
is listed in <a href="#table1">Table 1</a>. Currently full backward
compatibilty is provided only for Apache-SSL 1.x and mod_ssl 2.0.x.
Compatibility to Sioux 1.x and Stronghold 2.x is only partial because of
special functionality in these interfaces which mod_ssl (still) doesn't
provide.</p>
<h3><a name="table1" id="table1">Table 1: Configuration Directive Mapping</a></h3>
<table>
<tr><th>Old Directive</th><th>mod_ssl Directive</th><th>Comment</th></tr>
<tr><th colspan="3">Apache-SSL 1.x & mod_ssl 2.0.x compatibility:</th></tr>
<tr><td><code>SSLEnable</code></td><td><code>SSLEngine on</code></td><td>compactified</td></tr>
<tr><td><code>SSLDisable</code></td><td><code>SSLEngine off</code></td><td>compactified</td></tr>
<tr><td><code>SSLLogFile</code> <em>file</em></td><td><code>SSLLog</code> <em>file</em></td><td>compactified</td></tr>
<tr><td><code>SSLRequiredCiphers</code> <em>spec</em></td><td><code>SSLCipherSuite</code> <em>spec</em></td><td>renamed</td></tr>
<tr><td><code>SSLRequireCipher</code> <em>c1</em> ...</td><td><code>SSLRequire %{SSL_CIPHER} in {"</code><em>c1</em><code>",
...}</code></td><td>generalized</td></tr>
<tr><td><code>SSLBanCipher</code> <em>c1</em> ...</td><td><code>SSLRequire not (%{SSL_CIPHER} in {"</code><em>c1</em><code>",
...})</code></td><td>generalized</td></tr>
<tr><td><code>SSLFakeBasicAuth</code></td><td><code>SSLOptions +FakeBasicAuth</code></td><td>merged</td></tr>
<tr><td><code>SSLCacheServerPath</code> <em>dir</em></td><td>-</td><td>functionality removed</td></tr>
<tr><td><code>SSLCacheServerPort</code> <em>integer</em></td><td>-</td><td>functionality removed</td></tr>
<tr><th colspan="3">Apache-SSL 1.x compatibility:</th></tr>
<tr><td><code>SSLExportClientCertificates</code></td><td><code>SSLOptions +ExportCertData</code></td><td>merged</td></tr>
<tr><td><code>SSLCacheServerRunDir</code> <em>dir</em></td><td>-</td><td>functionality not supported</td></tr>
<tr><th colspan="3">Sioux 1.x compatibility:</th></tr>
<tr><td><code>SSL_CertFile</code> <em>file</em></td><td><code>SSLCertificateFile</code> <em>file</em></td><td>renamed</td></tr>
<tr><td><code>SSL_KeyFile</code> <em>file</em></td><td><code>SSLCertificateKeyFile</code> <em>file</em></td><td>renamed</td></tr>
<tr><td><code>SSL_CipherSuite</code> <em>arg</em></td><td><code>SSLCipherSuite</code> <em>arg</em></td><td>renamed</td></tr>
<tr><td><code>SSL_X509VerifyDir</code> <em>arg</em></td><td><code>SSLCACertificatePath</code> <em>arg</em></td><td>renamed</td></tr>
<tr><td><code>SSL_Log</code> <em>file</em></td><td><code>SSLLogFile</code> <em>file</em></td><td>renamed</td></tr>
<tr><td><code>SSL_Connect</code> <em>flag</em></td><td><code>SSLEngine</code> <em>flag</em></td><td>renamed</td></tr>
<tr><td><code>SSL_ClientAuth</code> <em>arg</em></td><td><code>SSLVerifyClient</code> <em>arg</em></td><td>renamed</td></tr>
<tr><td><code>SSL_X509VerifyDepth</code> <em>arg</em></td><td><code>SSLVerifyDepth</code> <em>arg</em></td><td>renamed</td></tr>
<tr><td><code>SSL_FetchKeyPhraseFrom</code> <em>arg</em></td><td>-</td><td>not directly mappable; use SSLPassPhraseDialog</td></tr>
<tr><td><code>SSL_SessionDir</code> <em>dir</em></td><td>-</td><td>not directly mappable; use SSLSessionCache</td></tr>
<tr><td><code>SSL_Require</code> <em>expr</em></td><td>-</td><td>not directly mappable; use SSLRequire</td></tr>
<tr><td><code>SSL_CertFileType</code> <em>arg</em></td><td>-</td><td>functionality not supported</td></tr>
<tr><td><code>SSL_KeyFileType</code> <em>arg</em></td><td>-</td><td>functionality not supported</td></tr>
<tr><td><code>SSL_X509VerifyPolicy</code> <em>arg</em></td><td>-</td><td>functionality not supported</td></tr>
<tr><td><code>SSL_LogX509Attributes</code> <em>arg</em></td><td>-</td><td>functionality not supported</td></tr>
<tr><th colspan="3">Stronghold 2.x compatibility:</th></tr>
<tr><td><code>StrongholdAccelerator</code> <em>dir</em></td><td>-</td><td>functionality not supported</td></tr>
<tr><td><code>StrongholdKey</code> <em>dir</em></td><td>-</td><td>functionality not supported</td></tr>
<tr><td><code>StrongholdLicenseFile</code> <em>dir</em></td><td>-</td><td>functionality not supported</td></tr>
<tr><td><code>SSLFlag</code> <em>flag</em></td><td><code>SSLEngine</code> <em>flag</em></td><td>renamed</td></tr>
<tr><td><code>SSLSessionLockFile</code> <em>file</em></td><td><code>SSLMutex</code> <em>file</em></td><td>renamed</td></tr>
<tr><td><code>SSLCipherList</code> <em>spec</em></td><td><code>SSLCipherSuite</code> <em>spec</em></td><td>renamed</td></tr>
<tr><td><code>RequireSSL</code></td><td><code>SSLRequireSSL</code></td><td>renamed</td></tr>
<tr><td><code>SSLErrorFile</code> <em>file</em></td><td>-</td><td>functionality not supported</td></tr>
<tr><td><code>SSLRoot</code> <em>dir</em></td><td>-</td><td>functionality not supported</td></tr>
<tr><td><code>SSL_CertificateLogDir</code> <em>dir</em></td><td>-</td><td>functionality not supported</td></tr>
<tr><td><code>AuthCertDir</code> <em>dir</em></td><td>-</td><td>functionality not supported</td></tr>
<tr><td><code>SSL_Group</code> <em>name</em></td><td>-</td><td>functionality not supported</td></tr>
<tr><td><code>SSLProxyMachineCertPath</code> <em>dir</em></td><td>-</td><td>functionality not supported</td></tr>
<tr><td><code>SSLProxyMachineCertFile</code> <em>file</em></td><td>-</td><td>functionality not supported</td></tr>
<tr><td><code>SSLProxyCACertificatePath</code> <em>dir</em></td><td>-</td><td>functionality not supported</td></tr>
<tr><td><code>SSLProxyCACertificateFile</code> <em>file</em></td><td>-</td><td>functionality not supported</td></tr>
<tr><td><code>SSLProxyVerifyDepth</code> <em>number</em></td><td>-</td><td>functionality not supported</td></tr>
<tr><td><code>SSLProxyCipherList</code> <em>spec</em></td><td>-</td><td>functionality not supported</td></tr>
</table>
</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div><div class="section"><h2><a name="variables" id="variables">Environment Variables</a></h2>
<p>When you use ``<code>SSLOptions +CompatEnvVars</code>'' additional environment
variables are generated. They all correspond to existing official mod_ssl
variables. The currently implemented variable derivation is listed in <a href="#table2">Table 2</a>.</p>
<h3><a name="table2" id="table2">Table 2: Environment Variable Derivation</a></h3>
<table>
<tr><th>Old Variable</th><th>mod_ssl Variable</th><th>Comment</th></tr>
<tr><td><code>SSL_PROTOCOL_VERSION</code></td><td><code>SSL_PROTOCOL</code></td><td>renamed</td></tr>
<tr><td><code>SSLEAY_VERSION</code></td><td><code>SSL_VERSION_LIBRARY</code></td><td>renamed</td></tr>
<tr><td><code>HTTPS_SECRETKEYSIZE</code></td><td><code>SSL_CIPHER_USEKEYSIZE</code></td><td>renamed</td></tr>
<tr><td><code>HTTPS_KEYSIZE</code></td><td><code>SSL_CIPHER_ALGKEYSIZE</code></td><td>renamed</td></tr>
<tr><td><code>HTTPS_CIPHER</code></td><td><code>SSL_CIPHER</code></td><td>renamed</td></tr>
<tr><td><code>HTTPS_EXPORT</code></td><td><code>SSL_CIPHER_EXPORT</code></td><td>renamed</td></tr>
<tr><td><code>SSL_SERVER_KEY_SIZE</code></td><td><code>SSL_CIPHER_ALGKEYSIZE</code></td><td>renamed</td></tr>
<tr><td><code>SSL_SERVER_CERTIFICATE</code></td><td><code>SSL_SERVER_CERT</code></td><td>renamed</td></tr>
<tr><td><code>SSL_SERVER_CERT_START</code></td><td><code>SSL_SERVER_V_START</code></td><td>renamed</td></tr>
<tr><td><code>SSL_SERVER_CERT_END</code></td><td><code>SSL_SERVER_V_END</code></td><td>renamed</td></tr>
<tr><td><code>SSL_SERVER_CERT_SERIAL</code></td><td><code>SSL_SERVER_M_SERIAL</code></td><td>renamed</td></tr>
<tr><td><code>SSL_SERVER_SIGNATURE_ALGORITHM</code></td><td><code>SSL_SERVER_A_SIG</code></td><td>renamed</td></tr>
<tr><td><code>SSL_SERVER_DN</code></td><td><code>SSL_SERVER_S_DN</code></td><td>renamed</td></tr>
<tr><td><code>SSL_SERVER_CN</code></td><td><code>SSL_SERVER_S_DN_CN</code></td><td>renamed</td></tr>
<tr><td><code>SSL_SERVER_EMAIL</code></td><td><code>SSL_SERVER_S_DN_Email</code></td><td>renamed</td></tr>
<tr><td><code>SSL_SERVER_O</code></td><td><code>SSL_SERVER_S_DN_O</code></td><td>renamed</td></tr>
<tr><td><code>SSL_SERVER_OU</code></td><td><code>SSL_SERVER_S_DN_OU</code></td><td>renamed</td></tr>
<tr><td><code>SSL_SERVER_C</code></td><td><code>SSL_SERVER_S_DN_C</code></td><td>renamed</td></tr>
<tr><td><code>SSL_SERVER_SP</code></td><td><code>SSL_SERVER_S_DN_SP</code></td><td>renamed</td></tr>
<tr><td><code>SSL_SERVER_L</code></td><td><code>SSL_SERVER_S_DN_L</code></td><td>renamed</td></tr>
<tr><td><code>SSL_SERVER_IDN</code></td><td><code>SSL_SERVER_I_DN</code></td><td>renamed</td></tr>
<tr><td><code>SSL_SERVER_ICN</code></td><td><code>SSL_SERVER_I_DN_CN</code></td><td>renamed</td></tr>
<tr><td><code>SSL_SERVER_IEMAIL</code></td><td><code>SSL_SERVER_I_DN_Email</code></td><td>renamed</td></tr>
<tr><td><code>SSL_SERVER_IO</code></td><td><code>SSL_SERVER_I_DN_O</code></td><td>renamed</td></tr>
<tr><td><code>SSL_SERVER_IOU</code></td><td><code>SSL_SERVER_I_DN_OU</code></td><td>renamed</td></tr>
<tr><td><code>SSL_SERVER_IC</code></td><td><code>SSL_SERVER_I_DN_C</code></td><td>renamed</td></tr>
<tr><td><code>SSL_SERVER_ISP</code></td><td><code>SSL_SERVER_I_DN_SP</code></td><td>renamed</td></tr>
<tr><td><code>SSL_SERVER_IL</code></td><td><code>SSL_SERVER_I_DN_L</code></td><td>renamed</td></tr>
<tr><td><code>SSL_CLIENT_CERTIFICATE</code></td><td><code>SSL_CLIENT_CERT</code></td><td>renamed</td></tr>
<tr><td><code>SSL_CLIENT_CERT_START</code></td><td><code>SSL_CLIENT_V_START</code></td><td>renamed</td></tr>
<tr><td><code>SSL_CLIENT_CERT_END</code></td><td><code>SSL_CLIENT_V_END</code></td><td>renamed</td></tr>
<tr><td><code>SSL_CLIENT_CERT_SERIAL</code></td><td><code>SSL_CLIENT_M_SERIAL</code></td><td>renamed</td></tr>
<tr><td><code>SSL_CLIENT_SIGNATURE_ALGORITHM</code></td><td><code>SSL_CLIENT_A_SIG</code></td><td>renamed</td></tr>
<tr><td><code>SSL_CLIENT_DN</code></td><td><code>SSL_CLIENT_S_DN</code></td><td>renamed</td></tr>
<tr><td><code>SSL_CLIENT_CN</code></td><td><code>SSL_CLIENT_S_DN_CN</code></td><td>renamed</td></tr>
<tr><td><code>SSL_CLIENT_EMAIL</code></td><td><code>SSL_CLIENT_S_DN_Email</code></td><td>renamed</td></tr>
<tr><td><code>SSL_CLIENT_O</code></td><td><code>SSL_CLIENT_S_DN_O</code></td><td>renamed</td></tr>
<tr><td><code>SSL_CLIENT_OU</code></td><td><code>SSL_CLIENT_S_DN_OU</code></td><td>renamed</td></tr>
<tr><td><code>SSL_CLIENT_C</code></td><td><code>SSL_CLIENT_S_DN_C</code></td><td>renamed</td></tr>
<tr><td><code>SSL_CLIENT_SP</code></td><td><code>SSL_CLIENT_S_DN_SP</code></td><td>renamed</td></tr>
<tr><td><code>SSL_CLIENT_L</code></td><td><code>SSL_CLIENT_S_DN_L</code></td><td>renamed</td></tr>
<tr><td><code>SSL_CLIENT_IDN</code></td><td><code>SSL_CLIENT_I_DN</code></td><td>renamed</td></tr>
<tr><td><code>SSL_CLIENT_ICN</code></td><td><code>SSL_CLIENT_I_DN_CN</code></td><td>renamed</td></tr>
<tr><td><code>SSL_CLIENT_IEMAIL</code></td><td><code>SSL_CLIENT_I_DN_Email</code></td><td>renamed</td></tr>
<tr><td><code>SSL_CLIENT_IO</code></td><td><code>SSL_CLIENT_I_DN_O</code></td><td>renamed</td></tr>
<tr><td><code>SSL_CLIENT_IOU</code></td><td><code>SSL_CLIENT_I_DN_OU</code></td><td>renamed</td></tr>
<tr><td><code>SSL_CLIENT_IC</code></td><td><code>SSL_CLIENT_I_DN_C</code></td><td>renamed</td></tr>
<tr><td><code>SSL_CLIENT_ISP</code></td><td><code>SSL_CLIENT_I_DN_SP</code></td><td>renamed</td></tr>
<tr><td><code>SSL_CLIENT_IL</code></td><td><code>SSL_CLIENT_I_DN_L</code></td><td>renamed</td></tr>
<tr><td><code>SSL_EXPORT</code></td><td><code>SSL_CIPHER_EXPORT</code></td><td>renamed</td></tr>
<tr><td><code>SSL_KEYSIZE</code></td><td><code>SSL_CIPHER_ALGKEYSIZE</code></td><td>renamed</td></tr>
<tr><td><code>SSL_SECKEYSIZE</code></td><td><code>SSL_CIPHER_USEKEYSIZE</code></td><td>renamed</td></tr>
<tr><td><code>SSL_SSLEAY_VERSION</code></td><td><code>SSL_VERSION_LIBRARY</code></td><td>renamed</td></tr>
<tr><td><code>SSL_STRONG_CRYPTO</code></td><td><code>-</code></td><td>Not supported by mod_ssl</td></tr>
<tr><td><code>SSL_SERVER_KEY_EXP</code></td><td><code>-</code></td><td>Not supported by mod_ssl</td></tr>
<tr><td><code>SSL_SERVER_KEY_ALGORITHM</code></td><td><code>-</code></td><td>Not supported by mod_ssl</td></tr>
<tr><td><code>SSL_SERVER_KEY_SIZE</code></td><td><code>-</code></td><td>Not supported by mod_ssl</td></tr>
<tr><td><code>SSL_SERVER_SESSIONDIR</code></td><td><code>-</code></td><td>Not supported by mod_ssl</td></tr>
<tr><td><code>SSL_SERVER_CERTIFICATELOGDIR</code></td><td><code>-</code></td><td>Not supported by mod_ssl</td></tr>
<tr><td><code>SSL_SERVER_CERTFILE</code></td><td><code>-</code></td><td>Not supported by mod_ssl</td></tr>
<tr><td><code>SSL_SERVER_KEYFILE</code></td><td><code>-</code></td><td>Not supported by mod_ssl</td></tr>
<tr><td><code>SSL_SERVER_KEYFILETYPE</code></td><td><code>-</code></td><td>Not supported by mod_ssl</td></tr>
<tr><td><code>SSL_CLIENT_KEY_EXP</code></td><td><code>-</code></td><td>Not supported by mod_ssl</td></tr>
<tr><td><code>SSL_CLIENT_KEY_ALGORITHM</code></td><td><code>-</code></td><td>Not supported by mod_ssl</td></tr>
<tr><td><code>SSL_CLIENT_KEY_SIZE</code></td><td><code>-</code></td><td>Not supported by mod_ssl</td></tr>
</table>
</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div><div class="section"><h2><a name="customlog" id="customlog">Custom Log Functions</a></h2>
<p>
When mod_ssl is built into Apache or at least loaded (under DSO situation)
additional functions exist for the <a href="../mod/mod_log_config.html#formats">Custom Log Format</a> of
<code class="module"><a href="../mod/mod_log_config.html">mod_log_config</a></code> as documented in the Reference
Chapter. Beside the ``<code>%{</code><em>varname</em><code>}x</code>''
eXtension format function which can be used to expand any variables provided
by any module, an additional Cryptography
``<code>%{</code><em>name</em><code>}c</code>'' cryptography format function
exists for backward compatibility. The currently implemented function calls
are listed in <a href="#table3">Table 3</a>.</p>
<h3><a name="table3" id="table3">Table 3: Custom Log Cryptography Function</a></h3>
<table>
<tr><th>Function Call</th><th>Description</th></tr>
<tr><td><code>%...{version}c</code></td> <td>SSL protocol version</td></tr>
<tr><td><code>%...{cipher}c</code></td> <td>SSL cipher</td></tr>
<tr><td><code>%...{subjectdn}c</code></td> <td>Client Certificate Subject Distinguished Name</td></tr>
<tr><td><code>%...{issuerdn}c</code></td> <td>Client Certificate Issuer Distinguished Name</td></tr>
<tr><td><code>%...{errcode}c</code></td> <td>Certificate Verification Error (numerical)</td></tr>
<tr><td><code>%...{errstr}c</code></td> <td>Certificate Verification Error (string)</td></tr>
</table>
</div></div><div id="footer"><p class="apache">Maintained by the <a href="http://httpd.apache.org/docs-project/">Apache HTTP Server Documentation Project</a></p><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></body></html>
1.1 httpd-2.0/docs/manual/ssl/ssl_compat.xml
Index: ssl_compat.xml
===================================================================
<?xml version='1.0' encoding='UTF-8' ?>
<!DOCTYPE manualpage SYSTEM "../style/manualpage.dtd">
<?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
<manualpage>
<relativepath href=".."/>
<title>SSL/TLS Strong Encryption: Compatibility</title>
<summary>
<blockquote>
<p>All PCs are compatible. But some of
them are more compatible than others.</p>
<p class="cite">--<cite>Unknown</cite></p>
</blockquote>
<p>
Here we talk about backward compatibility to other SSL solutions. As you
perhaps know, mod_ssl is not the only existing SSL solution for Apache.
Actually there are four additional major products available on the market: Ben
Laurie's freely available <a href="http://www.apache-ssl.org/">Apache-SSL</a>
(from where mod_ssl were originally derived in 1998), RedHat's commercial <a
href="http://www.redhat.com/products/product-details.phtml?id=rhsa">Secure Web
Server</a> (which is based on mod_ssl), Covalent's commercial <a
href="http://raven.covalent.net/">Raven SSL Module</a> (also based on mod_ssl)
and finally C2Net's commercial product <a
href="http://www.c2.net/products/stronghold/">Stronghold</a> (based on a
different evolution branch named Sioux up to Stronghold 2.x and based on
mod_ssl since Stronghold 3.x).</p>
<p>
The idea in mod_ssl is mainly the following: because mod_ssl provides mostly a
superset of the functionality of all other solutions we can easily provide
backward compatibility for most of the cases. Actually there are three
compatibility areas we currently address: configuration directives,
environment variables and custom log functions.</p>
</summary>
<section id="configuration"><title>Configuration Directives</title>
<p>For backward compatibility to the configuration directives of other SSL
solutions we do an on-the-fly mapping: directives which have a direct
counterpart in mod_ssl are mapped silently while other directives lead to a
warning message in the logfiles. The currently implemented directive mapping
is listed in <a href="#table1">Table 1</a>. Currently full backward
compatibilty is provided only for Apache-SSL 1.x and mod_ssl 2.0.x.
Compatibility to Sioux 1.x and Stronghold 2.x is only partial because of
special functionality in these interfaces which mod_ssl (still) doesn't
provide.</p>
<section id="table1">
<title>Table 1: Configuration Directive Mapping</title>
<table style="zebra">
<tr><th>Old Directive</th><th>mod_ssl Directive</th><th>Comment</th></tr>
<tr><th colspan="3">Apache-SSL 1.x & mod_ssl 2.0.x compatibility:</th></tr>
<tr><td><code>SSLEnable</code></td><td><code>SSLEngine on</code></td><td>compactified</td></tr>
<tr><td><code>SSLDisable</code></td><td><code>SSLEngine off</code></td><td>compactified</td></tr>
<tr><td><code>SSLLogFile</code> <em>file</em></td><td><code>SSLLog</code> <em>file</em></td><td>compactified</td></tr>
<tr><td><code>SSLRequiredCiphers</code> <em>spec</em></td><td><code>SSLCipherSuite</code> <em>spec</em></td><td>renamed</td></tr>
<tr><td><code>SSLRequireCipher</code> <em>c1</em> ...</td><td><code>SSLRequire %{SSL_CIPHER} in {"</code><em>c1</em><code>",
...}</code></td><td>generalized</td></tr>
<tr><td><code>SSLBanCipher</code> <em>c1</em> ...</td><td><code>SSLRequire not (%{SSL_CIPHER} in {"</code><em>c1</em><code>",
...})</code></td><td>generalized</td></tr>
<tr><td><code>SSLFakeBasicAuth</code></td><td><code>SSLOptions +FakeBasicAuth</code></td><td>merged</td></tr>
<tr><td><code>SSLCacheServerPath</code> <em>dir</em></td><td>-</td><td>functionality removed</td></tr>
<tr><td><code>SSLCacheServerPort</code> <em>integer</em></td><td>-</td><td>functionality removed</td></tr>
<tr><th colspan="3">Apache-SSL 1.x compatibility:</th></tr>
<tr><td><code>SSLExportClientCertificates</code></td><td><code>SSLOptions +ExportCertData</code></td><td>merged</td></tr>
<tr><td><code>SSLCacheServerRunDir</code> <em>dir</em></td><td>-</td><td>functionality not supported</td></tr>
<tr><th colspan="3">Sioux 1.x compatibility:</th></tr>
<tr><td><code>SSL_CertFile</code> <em>file</em></td><td><code>SSLCertificateFile</code> <em>file</em></td><td>renamed</td></tr>
<tr><td><code>SSL_KeyFile</code> <em>file</em></td><td><code>SSLCertificateKeyFile</code> <em>file</em></td><td>renamed</td></tr>
<tr><td><code>SSL_CipherSuite</code> <em>arg</em></td><td><code>SSLCipherSuite</code> <em>arg</em></td><td>renamed</td></tr>
<tr><td><code>SSL_X509VerifyDir</code> <em>arg</em></td><td><code>SSLCACertificatePath</code> <em>arg</em></td><td>renamed</td></tr>
<tr><td><code>SSL_Log</code> <em>file</em></td><td><code>SSLLogFile</code> <em>file</em></td><td>renamed</td></tr>
<tr><td><code>SSL_Connect</code> <em>flag</em></td><td><code>SSLEngine</code> <em>flag</em></td><td>renamed</td></tr>
<tr><td><code>SSL_ClientAuth</code> <em>arg</em></td><td><code>SSLVerifyClient</code> <em>arg</em></td><td>renamed</td></tr>
<tr><td><code>SSL_X509VerifyDepth</code> <em>arg</em></td><td><code>SSLVerifyDepth</code> <em>arg</em></td><td>renamed</td></tr>
<tr><td><code>SSL_FetchKeyPhraseFrom</code> <em>arg</em></td><td>-</td><td>not directly mappable; use SSLPassPhraseDialog</td></tr>
<tr><td><code>SSL_SessionDir</code> <em>dir</em></td><td>-</td><td>not directly mappable; use SSLSessionCache</td></tr>
<tr><td><code>SSL_Require</code> <em>expr</em></td><td>-</td><td>not directly mappable; use SSLRequire</td></tr>
<tr><td><code>SSL_CertFileType</code> <em>arg</em></td><td>-</td><td>functionality not supported</td></tr>
<tr><td><code>SSL_KeyFileType</code> <em>arg</em></td><td>-</td><td>functionality not supported</td></tr>
<tr><td><code>SSL_X509VerifyPolicy</code> <em>arg</em></td><td>-</td><td>functionality not supported</td></tr>
<tr><td><code>SSL_LogX509Attributes</code> <em>arg</em></td><td>-</td><td>functionality not supported</td></tr>
<tr><th colspan="3">Stronghold 2.x compatibility:</th></tr>
<tr><td><code>StrongholdAccelerator</code> <em>dir</em></td><td>-</td><td>functionality not supported</td></tr>
<tr><td><code>StrongholdKey</code> <em>dir</em></td><td>-</td><td>functionality not supported</td></tr>
<tr><td><code>StrongholdLicenseFile</code> <em>dir</em></td><td>-</td><td>functionality not supported</td></tr>
<tr><td><code>SSLFlag</code> <em>flag</em></td><td><code>SSLEngine</code> <em>flag</em></td><td>renamed</td></tr>
<tr><td><code>SSLSessionLockFile</code> <em>file</em></td><td><code>SSLMutex</code> <em>file</em></td><td>renamed</td></tr>
<tr><td><code>SSLCipherList</code> <em>spec</em></td><td><code>SSLCipherSuite</code> <em>spec</em></td><td>renamed</td></tr>
<tr><td><code>RequireSSL</code></td><td><code>SSLRequireSSL</code></td><td>renamed</td></tr>
<tr><td><code>SSLErrorFile</code> <em>file</em></td><td>-</td><td>functionality not supported</td></tr>
<tr><td><code>SSLRoot</code> <em>dir</em></td><td>-</td><td>functionality not supported</td></tr>
<tr><td><code>SSL_CertificateLogDir</code> <em>dir</em></td><td>-</td><td>functionality not supported</td></tr>
<tr><td><code>AuthCertDir</code> <em>dir</em></td><td>-</td><td>functionality not supported</td></tr>
<tr><td><code>SSL_Group</code> <em>name</em></td><td>-</td><td>functionality not supported</td></tr>
<tr><td><code>SSLProxyMachineCertPath</code> <em>dir</em></td><td>-</td><td>functionality not supported</td></tr>
<tr><td><code>SSLProxyMachineCertFile</code> <em>file</em></td><td>-</td><td>functionality not supported</td></tr>
<tr><td><code>SSLProxyCACertificatePath</code> <em>dir</em></td><td>-</td><td>functionality not supported</td></tr>
<tr><td><code>SSLProxyCACertificateFile</code> <em>file</em></td><td>-</td><td>functionality not supported</td></tr>
<tr><td><code>SSLProxyVerifyDepth</code> <em>number</em></td><td>-</td><td>functionality not supported</td></tr>
<tr><td><code>SSLProxyCipherList</code> <em>spec</em></td><td>-</td><td>functionality not supported</td></tr>
</table>
</section>
</section>
<section id="variables"><title>Environment Variables</title>
<p>When you use ``<code>SSLOptions +CompatEnvVars</code>'' additional environment
variables are generated. They all correspond to existing official mod_ssl
variables. The currently implemented variable derivation is listed in <a
href="#table2">Table 2</a>.</p>
<section id="table2">
<title>Table 2: Environment Variable Derivation</title>
<table style="zebra">
<tr><th>Old Variable</th><th>mod_ssl Variable</th><th>Comment</th></tr>
<tr><td><code>SSL_PROTOCOL_VERSION</code></td><td><code>SSL_PROTOCOL</code></td><td>renamed</td></tr>
<tr><td><code>SSLEAY_VERSION</code></td><td><code>SSL_VERSION_LIBRARY</code></td><td>renamed</td></tr>
<tr><td><code>HTTPS_SECRETKEYSIZE</code></td><td><code>SSL_CIPHER_USEKEYSIZE</code></td><td>renamed</td></tr>
<tr><td><code>HTTPS_KEYSIZE</code></td><td><code>SSL_CIPHER_ALGKEYSIZE</code></td><td>renamed</td></tr>
<tr><td><code>HTTPS_CIPHER</code></td><td><code>SSL_CIPHER</code></td><td>renamed</td></tr>
<tr><td><code>HTTPS_EXPORT</code></td><td><code>SSL_CIPHER_EXPORT</code></td><td>renamed</td></tr>
<tr><td><code>SSL_SERVER_KEY_SIZE</code></td><td><code>SSL_CIPHER_ALGKEYSIZE</code></td><td>renamed</td></tr>
<tr><td><code>SSL_SERVER_CERTIFICATE</code></td><td><code>SSL_SERVER_CERT</code></td><td>renamed</td></tr>
<tr><td><code>SSL_SERVER_CERT_START</code></td><td><code>SSL_SERVER_V_START</code></td><td>renamed</td></tr>
<tr><td><code>SSL_SERVER_CERT_END</code></td><td><code>SSL_SERVER_V_END</code></td><td>renamed</td></tr>
<tr><td><code>SSL_SERVER_CERT_SERIAL</code></td><td><code>SSL_SERVER_M_SERIAL</code></td><td>renamed</td></tr>
<tr><td><code>SSL_SERVER_SIGNATURE_ALGORITHM</code></td><td><code>SSL_SERVER_A_SIG</code></td><td>renamed</td></tr>
<tr><td><code>SSL_SERVER_DN</code></td><td><code>SSL_SERVER_S_DN</code></td><td>renamed</td></tr>
<tr><td><code>SSL_SERVER_CN</code></td><td><code>SSL_SERVER_S_DN_CN</code></td><td>renamed</td></tr>
<tr><td><code>SSL_SERVER_EMAIL</code></td><td><code>SSL_SERVER_S_DN_Email</code></td><td>renamed</td></tr>
<tr><td><code>SSL_SERVER_O</code></td><td><code>SSL_SERVER_S_DN_O</code></td><td>renamed</td></tr>
<tr><td><code>SSL_SERVER_OU</code></td><td><code>SSL_SERVER_S_DN_OU</code></td><td>renamed</td></tr>
<tr><td><code>SSL_SERVER_C</code></td><td><code>SSL_SERVER_S_DN_C</code></td><td>renamed</td></tr>
<tr><td><code>SSL_SERVER_SP</code></td><td><code>SSL_SERVER_S_DN_SP</code></td><td>renamed</td></tr>
<tr><td><code>SSL_SERVER_L</code></td><td><code>SSL_SERVER_S_DN_L</code></td><td>renamed</td></tr>
<tr><td><code>SSL_SERVER_IDN</code></td><td><code>SSL_SERVER_I_DN</code></td><td>renamed</td></tr>
<tr><td><code>SSL_SERVER_ICN</code></td><td><code>SSL_SERVER_I_DN_CN</code></td><td>renamed</td></tr>
<tr><td><code>SSL_SERVER_IEMAIL</code></td><td><code>SSL_SERVER_I_DN_Email</code></td><td>renamed</td></tr>
<tr><td><code>SSL_SERVER_IO</code></td><td><code>SSL_SERVER_I_DN_O</code></td><td>renamed</td></tr>
<tr><td><code>SSL_SERVER_IOU</code></td><td><code>SSL_SERVER_I_DN_OU</code></td><td>renamed</td></tr>
<tr><td><code>SSL_SERVER_IC</code></td><td><code>SSL_SERVER_I_DN_C</code></td><td>renamed</td></tr>
<tr><td><code>SSL_SERVER_ISP</code></td><td><code>SSL_SERVER_I_DN_SP</code></td><td>renamed</td></tr>
<tr><td><code>SSL_SERVER_IL</code></td><td><code>SSL_SERVER_I_DN_L</code></td><td>renamed</td></tr>
<tr><td><code>SSL_CLIENT_CERTIFICATE</code></td><td><code>SSL_CLIENT_CERT</code></td><td>renamed</td></tr>
<tr><td><code>SSL_CLIENT_CERT_START</code></td><td><code>SSL_CLIENT_V_START</code></td><td>renamed</td></tr>
<tr><td><code>SSL_CLIENT_CERT_END</code></td><td><code>SSL_CLIENT_V_END</code></td><td>renamed</td></tr>
<tr><td><code>SSL_CLIENT_CERT_SERIAL</code></td><td><code>SSL_CLIENT_M_SERIAL</code></td><td>renamed</td></tr>
<tr><td><code>SSL_CLIENT_SIGNATURE_ALGORITHM</code></td><td><code>SSL_CLIENT_A_SIG</code></td><td>renamed</td></tr>
<tr><td><code>SSL_CLIENT_DN</code></td><td><code>SSL_CLIENT_S_DN</code></td><td>renamed</td></tr>
<tr><td><code>SSL_CLIENT_CN</code></td><td><code>SSL_CLIENT_S_DN_CN</code></td><td>renamed</td></tr>
<tr><td><code>SSL_CLIENT_EMAIL</code></td><td><code>SSL_CLIENT_S_DN_Email</code></td><td>renamed</td></tr>
<tr><td><code>SSL_CLIENT_O</code></td><td><code>SSL_CLIENT_S_DN_O</code></td><td>renamed</td></tr>
<tr><td><code>SSL_CLIENT_OU</code></td><td><code>SSL_CLIENT_S_DN_OU</code></td><td>renamed</td></tr>
<tr><td><code>SSL_CLIENT_C</code></td><td><code>SSL_CLIENT_S_DN_C</code></td><td>renamed</td></tr>
<tr><td><code>SSL_CLIENT_SP</code></td><td><code>SSL_CLIENT_S_DN_SP</code></td><td>renamed</td></tr>
<tr><td><code>SSL_CLIENT_L</code></td><td><code>SSL_CLIENT_S_DN_L</code></td><td>renamed</td></tr>
<tr><td><code>SSL_CLIENT_IDN</code></td><td><code>SSL_CLIENT_I_DN</code></td><td>renamed</td></tr>
<tr><td><code>SSL_CLIENT_ICN</code></td><td><code>SSL_CLIENT_I_DN_CN</code></td><td>renamed</td></tr>
<tr><td><code>SSL_CLIENT_IEMAIL</code></td><td><code>SSL_CLIENT_I_DN_Email</code></td><td>renamed</td></tr>
<tr><td><code>SSL_CLIENT_IO</code></td><td><code>SSL_CLIENT_I_DN_O</code></td><td>renamed</td></tr>
<tr><td><code>SSL_CLIENT_IOU</code></td><td><code>SSL_CLIENT_I_DN_OU</code></td><td>renamed</td></tr>
<tr><td><code>SSL_CLIENT_IC</code></td><td><code>SSL_CLIENT_I_DN_C</code></td><td>renamed</td></tr>
<tr><td><code>SSL_CLIENT_ISP</code></td><td><code>SSL_CLIENT_I_DN_SP</code></td><td>renamed</td></tr>
<tr><td><code>SSL_CLIENT_IL</code></td><td><code>SSL_CLIENT_I_DN_L</code></td><td>renamed</td></tr>
<tr><td><code>SSL_EXPORT</code></td><td><code>SSL_CIPHER_EXPORT</code></td><td>renamed</td></tr>
<tr><td><code>SSL_KEYSIZE</code></td><td><code>SSL_CIPHER_ALGKEYSIZE</code></td><td>renamed</td></tr>
<tr><td><code>SSL_SECKEYSIZE</code></td><td><code>SSL_CIPHER_USEKEYSIZE</code></td><td>renamed</td></tr>
<tr><td><code>SSL_SSLEAY_VERSION</code></td><td><code>SSL_VERSION_LIBRARY</code></td><td>renamed</td></tr>
<tr><td><code>SSL_STRONG_CRYPTO</code></td><td><code>-</code></td><td>Not supported by mod_ssl</td></tr>
<tr><td><code>SSL_SERVER_KEY_EXP</code></td><td><code>-</code></td><td>Not supported by mod_ssl</td></tr>
<tr><td><code>SSL_SERVER_KEY_ALGORITHM</code></td><td><code>-</code></td><td>Not supported by mod_ssl</td></tr>
<tr><td><code>SSL_SERVER_KEY_SIZE</code></td><td><code>-</code></td><td>Not supported by mod_ssl</td></tr>
<tr><td><code>SSL_SERVER_SESSIONDIR</code></td><td><code>-</code></td><td>Not supported by mod_ssl</td></tr>
<tr><td><code>SSL_SERVER_CERTIFICATELOGDIR</code></td><td><code>-</code></td><td>Not supported by mod_ssl</td></tr>
<tr><td><code>SSL_SERVER_CERTFILE</code></td><td><code>-</code></td><td>Not supported by mod_ssl</td></tr>
<tr><td><code>SSL_SERVER_KEYFILE</code></td><td><code>-</code></td><td>Not supported by mod_ssl</td></tr>
<tr><td><code>SSL_SERVER_KEYFILETYPE</code></td><td><code>-</code></td><td>Not supported by mod_ssl</td></tr>
<tr><td><code>SSL_CLIENT_KEY_EXP</code></td><td><code>-</code></td><td>Not supported by mod_ssl</td></tr>
<tr><td><code>SSL_CLIENT_KEY_ALGORITHM</code></td><td><code>-</code></td><td>Not supported by mod_ssl</td></tr>
<tr><td><code>SSL_CLIENT_KEY_SIZE</code></td><td><code>-</code></td><td>Not supported by mod_ssl</td></tr>
</table>
</section>
</section>
<section id="customlog"><title>Custom Log Functions</title>
<p>
When mod_ssl is built into Apache or at least loaded (under DSO situation)
additional functions exist for the <a
href="../mod/mod_log_config.html#formats">Custom Log Format</a> of
<module>mod_log_config</module> as documented in the Reference
Chapter. Beside the ``<code>%{</code><em>varname</em><code>}x</code>''
eXtension format function which can be used to expand any variables provided
by any module, an additional Cryptography
``<code>%{</code><em>name</em><code>}c</code>'' cryptography format function
exists for backward compatibility. The currently implemented function calls
are listed in <a href="#table3">Table 3</a>.</p>
<section id="table3">
<title>Table 3: Custom Log Cryptography Function</title>
<table>
<tr><th>Function Call</th><th>Description</th></tr>
<tr><td><code>%...{version}c</code></td> <td>SSL protocol version</td></tr>
<tr><td><code>%...{cipher}c</code></td> <td>SSL cipher</td></tr>
<tr><td><code>%...{subjectdn}c</code></td> <td>Client Certificate Subject Distinguished Name</td></tr>
<tr><td><code>%...{issuerdn}c</code></td> <td>Client Certificate Issuer Distinguished Name</td></tr>
<tr><td><code>%...{errcode}c</code></td> <td>Certificate Verification Error (numerical)</td></tr>
<tr><td><code>%...{errstr}c</code></td> <td>Certificate Verification Error (string)</td></tr>
</table>
</section>
</section>
</manualpage>
1.1 httpd-2.0/docs/manual/ssl/ssl_faq.html.en
Index: ssl_faq.html.en
===================================================================
<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en"><head><!--
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
This file is generated from xml source: DO NOT EDIT
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
--><title>SSL/TLS Strong Encryption: FAQ - Apache HTTP Server</title><link href="../style/css/manual.css" rel="stylesheet" media="all" type="text/css" title="Main stylesheet" /><link href="../style/css/manual-loose-100pc.css" rel="alternate stylesheet" media="all" type="text/css" title="No Sidebar - Default font size" /><link href="../style/css/manual-print.css" rel="stylesheet" media="print" type="text/css" /><link href="../images/favicon.ico" rel="shortcut icon" /></head><body id="manual-page"><div id="page-header"><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><p class="apache">Apache HTTP Server Version 2.0</p><img alt="" src="../images/feather.gif" /></div><div class="up"><a href="./"><img title="<-" alt="<-" src="../images/left.gif" /></a></div><div id="path"><a href="http://www.apache.org/">Apache</a> > <a href="http://httpd.apache.org/">HTTP Server</a> > <a href="http://httpd.apache.org/docs-project/">Documentation</a> > <a href="../">Version 2.0</a></div><div id="page-content"><div id="preamble"><h1>SSL/TLS Strong Encryption: FAQ</h1>
<blockquote>
<p>The wise man doesn't give the right answers,
he poses the right questions.</p>
<p class="cite">--<cite>Claude Levi-Strauss</cite></p>
</blockquote>
<p>This chapter is a collection of frequently asked questions (FAQ) and
corresponding answers following the popular USENET tradition. Most of these
questions occured on the Newsgroup <code><a href="news:comp.infosystems.www.servers.unix">comp.infosystems.www.servers.unix</a></code> or the mod_ssl Support
Mailing List <code><a href="mailto:modssl-users@modssl.org">modssl-users@modssl.org</a></code>. They are collected at this place
to avoid answering the same questions over and over.</p>
<p>Please read this chapter at least once when installing mod_ssl or at least
search for your problem here before submitting a problem report to the
author.</p>
</div><div id="quickview"><ul id="toc"><li><img alt="" src="../images/down.gif" /> <a href="#about">About The Module</a></li><li><img alt="" src="../images/down.gif" /> <a href="#installation">About Installation</a></li><li><img alt="" src="../images/down.gif" /> <a href="#aboutconfig">About Configuration</a></li><li><img alt="" src="../images/down.gif" /> <a href="#aboutcerts">About Certificates</a></li><li><img alt="" src="../images/down.gif" /> <a href="#aboutssl">About SSL Protocol</a></li><li><img alt="" src="../images/down.gif" /> <a href="#support">About Support</a></li></ul></div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div><div class="section"><h2><a name="about" id="about">About The Module</a></h2>
<ul>
<li><a href="#history">What is the history of mod_ssl?</a></li>
<li><a href="#apssl-diff">Apache-SSL vs. mod_ssl: differences?</a></li>
<li><a href="#commalt">mod_ssl vs. commercial alternatives?</a></li>
<li><a href="#modversion">mod_ssl/Apache versions?</a></li>
<li><a href="#y2k">mod_ssl and Year 2000?</a></li>
<li><a href="#wassenaar">mod_ssl and Wassenaar Arrangement?</a></li>
</ul>
<h3><a name="history" id="history">What is the history of mod_ssl?</a></h3>
<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
Apache 1.2.6 to Apache 1.3b6. Because of conflicts with Ben
Laurie's development cycle it then was re-assembled from scratch for
Apache 1.3.0 by merging the old mod_ssl 1.x with the newer Apache-SSL
1.18. From this point on mod_ssl lived its own life as mod_ssl v2. The
first publically released version was mod_ssl 2.0.0 from August 10th,
1998. As of this writing (August 1999) the current mod_ssl version
is 2.4.0.</p>
<p>After one year of very active development with over 1000 working hours and
over 40 releases mod_ssl reached its current state. The result is an
already very clean source base implementing a very rich functionality.
The code size increased by a factor of 4 to currently a total of over
10.000 lines of ANSI C consisting of approx. 70% code and 30% code
documentation. From the original Apache-SSL code currently approx. 5% is
remaining only.</p>
<p>After the US export restrictions for cryptographic software were
opened, mod_ssl was integrated into the code base of Apache V2 in 2001.</p>
<h3><a name="apssl-diff" id="apssl-diff">What are the functional differences between mod_ssl and Apache-SSL, from which
it is originally derived?</a></h3>
<p>This neither can be answered in short (there were too many code changes)
nor can be answered at all by the author (there would immediately be flame
wars with no reasonable results at the end). But as you easily can guess
from the 5% of remaining Apache-SSL code, a lot of differences exists,
although user-visible backward compatibility exists for most things.</p>
<p>When you really want a detailed comparison you have to read the entries in
the large <code>CHANGES</code> file that is in the mod_ssl
distribution. Usually this is much too hard-core. So I recommend you to
either believe in the opinion and recommendations of other users (the
simplest approach) or do a comparison yourself (the most reasonable
approach). For the latter, grab distributions of mod_ssl (from <a href="http://www.modssl.org/">http://www.modssl.org</a>) and Apache-SSL
(from <a href="http://www.apache-ssl.org/">http://www.apache-ssl.org</a>),
install both packages, read their documentation and try them out yourself.
Then choose the one which pleases you most.</p>
<p>A few final hints to help direct your comparison: quality of documentation
("can you easily find answers and are they sufficient?"), quality of
source code ("is the source code reviewable so you can make sure there
aren't any trapdoors or inherent security risks because of bad programming
style?"), easy and clean installation ("can the SSL functionality easily
added to an Apache source tree without manual editing or patching?"),
clean integration into Apache ("is the SSL functionality encapsulated and
cleanly separated from the remaining Apache functionality?"), support for
Dynamic Shared Object (DSO) facility ("can the SSL functionality built as
a separate DSO for maximum flexibility?"), Win32 port ("is the SSL
functionality available also under the Win32 platform?"), amount and
quality of functionality ("is the provided SSL functionality and control
possibilities sufficient for your situation?"), quality of problem tracing
("is it possible for you to easily trace down the problems via logfiles,
etc?"), etc. pp.</p>
<h3><a name="commalt" id="commalt">What are the major differences between mod_ssl and
the commercial alternatives like Raven or Stronghold?</a></h3>
<p>In the past (until September 20th, 2000) the major difference was
the RSA license which one received (very cheaply in contrast to
a direct licensing from RSA DSI) with the commercial Apache SSL
products. On the other hand, one needed this license only in the US,
of course. So for non-US citizens this point was useless. But now
even for US citizens the situations changed because the RSA patent
expired on September 20th, 2000 and RSA DSI also placed the RSA
algorithm explicitly into the public domain.</p>
<p>Second, there is the point that one has guaranteed support from
the commercial vendors. On the other hand, if you monitored the
Open Source quality of mod_ssl and the support activities
found on <a href="mailto:modssl-users@modssl.org">
<code>modssl-users@modssl.org</code></a>, you could ask yourself
whether you are really convinced that you can get better support
from a commercial vendor.</p>
<p>Third, people often think they would receive perhaps at least a
better technical SSL solution than mod_ssl from the commercial
vendors. But this is not really true, because all commercial
alternatives (Raven 1.4.x, Stronghold 3.x, RedHat SWS 2.x, etc.)
<em>are</em> actually based on mod_ssl and OpenSSL. The reason for
this common misunderstanding is mainly because some vendors make no
attempt to make it reasonably clear that their product is actually
mod_ssl based. So, do not think, just because the commercial
alternatives are usually more expensive, that you are also receiving
an alternative <em>technical</em> SSL solution. This is usually not
the case. Actually the vendor versions of Apache, mod_ssl and OpenSSL
often stay behind the latest free versions and perhaps this way still do not
include important bug and security fixes. On the other hand,
it sometimes occurs that a vendor version includes useful changes
which are not available through the official freely available
packages. But most vendors play fair and contribute back those
changes to the free software world, of course.</p>
<p>So, in short: There are lots of commercial versions of the popular
Apache+mod_ssl+OpenSSL server combination available. Every user
should decide carefully whether they really need to buy a commercial
version or whether it would not be sufficient to directly use the
free and official versions of the Apache, mod_ssl and OpenSSL
packages.</p>
<h3><a name="modversion" id="modversion">How do I know which mod_ssl version is for which Apache version?</a></h3>
<p>That's trivial: mod_ssl uses version strings of the syntax
<em><mod_ssl-version></em>-<em><apache-version></em>, for
instance <code>2.4.0-1.3.9</code>. This directly indicates that it's
mod_ssl version 2.4.0 for Apache version 1.3.9. And this also means you
<em>only</em> can apply this mod_ssl version to exactly this Apache
version (unless you use the <code>--force</code> option to mod_ssl's
<code>configure</code> command ;-).</p>
<h3><a name="y2k" id="y2k">Is mod_ssl Year 2000 compliant?</a></h3>
<p>Yes, mod_ssl is Year 2000 compliant.</p>
<p>Because first mod_ssl internally never stores years as two digits.
Instead it always uses the ANSI C & POSIX numerical data type
<code>time_t</code> type, which on almost all Unix platforms at the moment
is a <code>signed long</code> (usually 32-bits) representing seconds since
epoch of January 1st, 1970, 00:00 UTC. This signed value overflows in
early January 2038 and not in the year 2000. Second, date and time
presentations (for instance the variable ``<code>%{TIME_YEAR}</code>'')
are done with full year value instead of abbreviating to two digits.</p>
<p>Additionally according to a <a href="http://www.apache.org/docs/misc/FAQ.html#year2000">Year 2000
statement</a> from the Apache Group, the Apache webserver is Year 2000
compliant, too. But whether OpenSSL or the underlaying Operating System
(either a Unix or Win32 platform) is Year 2000 compliant is a different
question which cannot be answered here.</p>
<h3><a name="wassenaar" id="wassenaar">What about mod_ssl and the Wassenaar Arrangement?</a></h3>
<p>First, let us explain what <dfn>Wassenaar</dfn> and its <dfn>Arrangement on
Export Controls for Conventional Arms and Dual-Use Goods and
Technologies</dfn> is: This is a international regime, established 1995, to
control trade in conventional arms and dual-use goods and technology. It
replaced the previous <dfn>CoCom</dfn> regime. 33 countries are signatories:
Argentina, Australia, Austria, Belgium, Bulgaria, Canada, Czech Republic,
Denmark, Finland, France, Germany, Greece, Hungary, Ireland, Italy, Japan,
Luxembourg, Netherlands, New Zealand, Norway, Poland, Portugal, Republic
of Korea, Romania, Russian Federation, Slovak Republic, Spain, Sweden,
Switzerland, Turkey, Ukraine, United Kingdom and United States. For more
details look at <a href="http://www.wassenaar.org/">http://www.wassenaar.org/</a>.</p>
<p>In short: The aim of the Wassenaar Arrangement is to prevent the build up
of military capabilities that threaten regional and international security
and stability. The Wassenaar Arrangement controls the export of
cryptography as a dual-use good, i.e., one that has both military and
civilian applications. However, the Wassenaar Arrangement also provides an
exemption from export controls for mass-market software and free software.</p>
<p>In the current Wassenaar <cite>List of Dual Use Goods and Technologies And
Munitions</cite>, under <q>GENERAL SOFTWARE NOTE (GSN)</q> it says
<q>The Lists do not control "software" which is either: 1. [...] 2. "in
the public domain".</q> And under <q>DEFINITIONS OF TERMS USED IN
THESE LISTS</q> one can find the definition: <q>In the public
domain": This means "technology" or "software" which has been made
available without restrictions upon its further dissemination. N.B.
Copyright restrictions do not remove "technology" or "software" from being
"in the public domain".</q></p>
<p>So, both mod_ssl and OpenSSL are <q>in the public domain</q> for the purposes
of the Wassenaar Agreement and its <q>List of Dual Use Goods and
Technologies And Munitions List</q>.</p>
<p>Additionally the Wassenaar Agreement itself has no direct consequence for
exporting cryptography software. What is actually allowed or forbidden to
be exported from the countries has still to be defined in the local laws
of each country. And at least according to official press releases from
the German BMWi (see <a href="http://www.bmwi.de/presse/1998/1208prm2.html">here</a>) and the
Switzerland Bawi (see <a href="http://jya.com/wass-ch.htm">here</a>) there
will be no forthcoming export restriction for free cryptography software
for their countries. Remember that mod_ssl is created in Germany and
distributed from Switzerland.</p>
<p>So, mod_ssl and OpenSSL are not affected by the Wassenaar Agreement.</p>
</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div><div class="section"><h2><a name="installation" id="installation">About Installation</a></h2>
<ul>
<li><a href="#coredump">Core dumps for HTTPS requests?</a></li>
<li><a href="#php3">Core dumps for Apache+mod_ssl+PHP3?</a></li>
<li><a href="#undefinedsym">Undefined symbols on startup?</a></li>
<li><a href="#mutex">Permission problem on SSLMutex</a></li>
<li><a href="#mm">Shared memory and process size?</a></li>
<li><a href="#mmpath">Shared memory and pathname?</a></li>
<li><a href="#entropy">PRNG and not enough entropy?</a></li>
</ul>
<h3><a name="coredump" id="coredump">When I access my website the first time via HTTPS I get a core dump?</a></h3>
<p>There can be a lot of reasons why a core dump can occur, of course.
Ranging from buggy third-party modules, over buggy vendor libraries up to
a buggy mod_ssl version. But the above situation is often caused by old or
broken vendor DBM libraries. To solve it either build mod_ssl with the
built-in SDBM library (specify <code>--enable-rule=SSL_SDBM</code> at the
APACI command line) or switch from <code>SSLSessionCache dbm:</code> to the
newer <code>SSLSessionCache shm:</code>'' variant (after you have rebuilt
Apache with MM, of course).</p>
<h3><a name="php3" id="php3">My Apache dumps core when I add both mod_ssl and PHP3?</a></h3>
<p>Make sure you add mod_ssl to the Apache source tree first and then do a
fresh configuration and installation of PHP3. For SSL support EAPI patches
are required which have to change internal Apache structures. PHP3 needs
to know about these in order to work correctly. Always make sure that
<code>-DEAPI</code> is contained in the compiler flags when PHP3 is built.</p>
<h3><a name="undefinedsym" id="undefinedsym">When I startup Apache I get errors about undefined symbols like ap_global_ctx?</a></h3>
<p>This actually means you installed mod_ssl as a DSO, but without rebuilding
Apache with EAPI. Because EAPI is a requirement for mod_ssl, you need an
extra patched Apache (containing the EAPI patches) and you have to build
this Apache with EAPI enabled (explicitly specify
<code>--enable-rule=EAPI</code> at the APACI command line).</p>
<h3><a name="mutex" id="mutex">When I startup Apache I get permission errors related to SSLMutex?</a></h3>
<p>When you receive entries like ``<code>mod_ssl: Child could not open
SSLMutex lockfile /opt/apache/logs/ssl_mutex.18332 (System error follows)
[...] System: Permission denied (errno: 13)</code>'' this is usually
caused by to restrictive permissions on the <em>parent</em> directories.
Make sure that all parent directories (here <code>/opt</code>,
<code>/opt/apache</code> and <code>/opt/apache/logs</code>) have the x-bit
set at least for the UID under which Apache's children are running (see
the <code class="directive"><a href="../mod/mpm_common.html#user">User</a></code> directive of Apache).</p>
<h3><a name="mm" id="mm">When I use the MM library and the shared memory cache each process grows
1.5MB according to `top' although I specified 512000 as the cache size?</a></h3>
<p>The additional 1MB are caused by the global shared memory pool EAPI
allocates for all modules and which is not used by mod_ssl for
various reasons. So the actually allocated shared memory is always
1MB more than what you specify on <code class="directive"><a href="../mod/mod_ssl.html#sslsessioncache">SSLSessionCache</a></code>.
But don't be confused by the display of `top': although is
indicates that <em>each</em> process grow, this is not reality, of
course. Instead the additional memory consumption is shared by
all processes, i.e. the 1.5MB are allocated only once per Apache
instance and not once per Apache server process.</p>
<h3><a name="mmpath" id="mmpath">Apache creates files in a directory declared by the internal
EAPI_MM_CORE_PATH define. Is there a way to override the path using a
configuration directive?</a></h3>
<p>No, there is not configuration directive, because for technical
bootstrapping reasons, a directive not possible at all. Instead
use ``<code>CFLAGS='-DEAPI_MM_CORE_PATH="/path/to/wherever/"'
./configure ...</code>'' when building Apache or use option
<code>-d</code> when starting <code>httpd</code>.</p>
<h3><a name="entropy" id="entropy">When I fire up the server, mod_ssl stops with the error
"Failed to generate temporary 512 bit RSA private key", why?</a></h3>
<p>Cryptographic software needs a source of unpredictable data
to work correctly. Many open source operating systems provide
a "randomness device" that serves this purpose (usually named
<code>/dev/random</code>). On other systems, applications have to
seed the OpenSSL Pseudo Random Number Generator (PRNG) manually with
appropriate data before generating keys or performing public key
encryption. As of version 0.9.5, the OpenSSL functions that need
randomness report an error if the PRNG has not been seeded with
at least 128 bits of randomness. So mod_ssl has to provide enough
entropy to the PRNG to work correctly. For this one has to use the
<code>SSLRandomSeed</code> directives.</p>
</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div><div class="section"><h2><a name="aboutconfig" id="aboutconfig">About Configuration</a></h2>
<ul>
<li><a href="#parallel">HTTP and HTTPS with a single server?</a></li>
<li><a href="#ports">Where is the HTTPS port?</a></li>
<li><a href="#httpstest">How to test HTTPS manually?</a></li>
<li><a href="#hang">Why does my connection hang?</a></li>
<li><a href="#refused">Why do I get connection refused?</a></li>
<li><a href="#envvars">Why are the <code>SSL_XXX</code> variables missing?</a></li>
<li><a href="#relative">How to switch with relative hyperlinks?</a></li>
</ul>
<h3><a name="parallel" id="parallel">Is it possible to provide HTTP and HTTPS with a single server?</a></h3>
<p>Yes, HTTP and HTTPS use different server ports, so there is no direct
conflict between them. Either run two separate server instances (one binds
to port 80, the other to port 443) or even use Apache's elegant virtual
hosting facility where you can easily create two virtual servers which
Apache dispatches: one responding to port 80 and speaking HTTP and one
responding to port 443 speaking HTTPS.</p>
<h3><a name="ports" id="ports">I know that HTTP is on port 80, but where is HTTPS?</a></h3>
<p>You can run HTTPS on any port, but the standards specify port 443, which
is where any HTTPS compliant browser will look by default. You can force
your browser to look on a different port by specifying it in the URL like
this (for port 666): <code>https://secure.server.dom:666/</code></p>
<h3><a name="httpstest" id="httpstest">How can I speak HTTPS manually for testing purposes?</a></h3>
<p>While you usually just use</p>
<div class="example"><p><code>$ telnet localhost 80<br />
GET / HTTP/1.0</code></p></div>
<p>for simple testing the HTTP protocol of Apache, it's not so easy for
HTTPS because of the SSL protocol between TCP and HTTP. But with the
help of OpenSSL's <code>s_client</code> command you can do a similar
check even for HTTPS:</p>
<div class="example"><p><code>$ openssl s_client -connect localhost:443 -state -debug<br />
GET / HTTP/1.0</code></p></div>
<p>Before the actual HTTP response you receive detailed information about the
SSL handshake. For a more general command line client which directly
understands both the HTTP and HTTPS scheme, can perform GET and POST
methods, can use a proxy, supports byte ranges, etc. you should have a
look at nifty <a href="http://curl.haxx.nu/">cURL</a>
tool. With it you can directly check if your Apache is running fine on
Port 80 and 443 as following:</p>
<div class="example"><p><code>$ curl http://localhost/<br />
$ curl https://localhost/</code></p></div>
<h3><a name="hang" id="hang">Why does the connection hang when I connect to my SSL-aware Apache server?</a></h3>
<p>Because you connected with HTTP to the HTTPS port, i.e. you used an URL of
the form ``<code>http://</code>'' instead of ``<code>https://</code>''.
This also happens the other way round when you connect via HTTPS to a HTTP
port, i.e. when you try to use ``<code>https://</code>'' on a server that
doesn't support SSL (on this port). Make sure you are connecting to a
virtual server that supports SSL, which is probably the IP associated with
your hostname, not localhost (127.0.0.1).</p>
<h3><a name="refused" id="refused">Why do I get ``Connection Refused'' messages when trying to access my freshly
installed Apache+mod_ssl server via HTTPS?</a></h3>
<p>There can be various reasons. Some of the common mistakes is that people
start Apache with just ``<code>apachectl start</code>'' (or
``<code>httpd</code>'') instead of ``<code>apachectl startssl</code>'' (or
``<code>httpd -DSSL</code>''. Or you're configuration is not correct. At
least make sure that your <code class="directive"><a href="../mod/mpm_common.html#listen">Listen</a></code>
directives match your <code class="directive"><a href="../mod/core.html#virtualhost"><VirtualHost></a></code>
directives. And if all fails, please do yourself a favor and start over with the
default configuration mod_ssl provides you.</p>
<h3><a name="envvars" id="envvars">In my CGI programs and SSI scripts the various documented
<code>SSL_XXX</code> variables do not exist. Why?</a></h3>
<p>Just make sure you have ``<code>SSLOptions +StdEnvVars</code>''
enabled for the context of your CGI/SSI requests.</p>
<h3><a name="relative" id="relative">How can I use relative hyperlinks to switch between HTTP and HTTPS?</a></h3>
<p>Usually you have to use fully-qualified hyperlinks because
you have to change the URL scheme. But with the help of some URL
manipulations through mod_rewrite you can achieve the same effect while
you still can use relative URLs:</p>
<div class="example"><p><code>
RewriteEngine on<br />
RewriteRule ^/(.*):SSL$ https://%{SERVER_NAME}/$1 [R,L]<br />
RewriteRule ^/(.*):NOSSL$ http://%{SERVER_NAME}/$1 [R,L]
</code></p></div>
This rewrite ruleset lets you use hyperlinks of the form
<div class="example"><p><code><a href="document.html:SSL"></code></p></div>
</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div><div class="section"><h2><a name="aboutcerts" id="aboutcerts">About Certificates</a></h2>
<ul>
<li><a href="#keyscerts">What are Keys, CSRs and Certs?</a></li>
<li><a href="#startup">Difference on startup?</a></li>
<li><a href="#realcert">How to create a real cert?</a></li>
<li><a href="#ownca">How to create my own CA?</a></li>
<li><a href="#passphrase">How to change a pass phrase?</a></li>
<li><a href="#removepassphrase">How to remove a pass phrase?</a></li>
<li><a href="#verify">How to verify a key/cert pair?</a></li>
<li><a href="#badcert">Bad Certificate Error?</a></li>
<li><a href="#keysize">Why does a 2048-bit key not work?</a></li>
<li><a href="#hashsymlinks">Why is client auth broken?</a></li>
<li><a href="#pemder">How to convert from PEM to DER?</a></li>
<li><a href="#verisign">Verisign and the magic getca program?</a></li>
<li><a href="#sgc">Global IDs or SGC?</a></li>
<li><a href="#gid">Global IDs and Cert Chain?</a></li>
</ul>
<h3><a name="keyscerts" id="keyscerts">What are RSA Private Keys, CSRs and Certificates?</a></h3>
<p>The RSA private key file is a digital file that you can use to decrypt
messages sent to you. It has a public component which you distribute (via
your Certificate file) which allows people to encrypt those messages to
you. A Certificate Signing Request (CSR) is a digital file which contains
your public key and your name. You send the CSR to a Certifying Authority
(CA) to be converted into a real Certificate. A Certificate contains your
RSA public key, your name, the name of the CA, and is digitally signed by
your CA. Browsers that know the CA can verify the signature on that
Certificate, thereby obtaining your RSA public key. That enables them to
send messages which only you can decrypt.
See the <a href="ssl_intro.html">Introduction</a> chapter for a general
description of the SSL protocol.</p>
<h3><a name="startup" id="startup">Seems like there is a difference on startup between the original Apache and an SSL-aware Apache?</a></h3>
<p>Yes, in general, starting Apache with a built-in mod_ssl is just like
starting an unencumbered Apache, except for the fact that when you have a
pass phrase on your SSL private key file. Then a startup dialog pops up
asking you to enter the pass phrase.</p>
<p>To type in the pass phrase manually when starting the server can be
problematic, for instance when starting the server from the system boot
scripts. As an alternative to this situation you can follow the steps
below under ``How can I get rid of the pass-phrase dialog at Apache
startup time?''.</p>
<h3><a name="realcert" id="realcert">Ok, I've got my server installed and want to create a real SSL
server Certificate for it. How do I do it?</a></h3>
<p>Here is a step-by-step description:</p>
<ol>
<li>Make sure OpenSSL is really installed and in your <code>PATH</code>.
But some commands even work ok when you just run the
``<code>openssl</code>'' program from within the OpenSSL source tree as
``<code>./apps/openssl</code>''.<br />
<br />
</li>
<li>Create a RSA private key for your Apache server
(will be Triple-DES encrypted and PEM formatted):<br />
<br />
<code><strong>$ openssl genrsa -des3 -out server.key 1024</strong></code><br />
<br />
Please backup this <code>server.key</code> file and remember the
pass-phrase you had to enter at a secure location.
You can see the details of this RSA private key via the command:<br />
<br />
<code><strong>$ openssl rsa -noout -text -in server.key</strong></code><br />
<br />
And you could create a decrypted PEM version (not recommended)
of this RSA private key via:<br />
<br />
<code><strong>$ openssl rsa -in server.key -out server.key.unsecure</strong></code><br />
<br />
</li>
<li>Create a Certificate Signing Request (CSR) with the server RSA private
key (output will be PEM formatted):<br />
<br />
<code><strong>$ openssl req -new -key server.key -out server.csr</strong></code><br />
<br />
Make sure you enter the FQDN ("Fully Qualified Domain Name") of the
server when OpenSSL prompts you for the "CommonName", i.e. when you
generate a CSR for a website which will be later accessed via
<code>https://www.foo.dom/</code>, enter "www.foo.dom" here.
You can see the details of this CSR via the command<br />
<br />
<code><strong>$ openssl req -noout -text -in server.csr</strong></code><br />
<br />
</li>
<li>You now have to send this Certificate Signing Request (CSR) to
a Certifying Authority (CA) for signing. The result is then a real
Certificate which can be used for Apache. Here you have two options:
First you can let the CSR sign by a commercial CA like Verisign or
Thawte. Then you usually have to post the CSR into a web form, pay for
the signing and await the signed Certificate you then can store into a
server.crt file. For more information about commercial CAs have a look
at the following locations:<br />
<br />
<ol>
<li> Verisign<br />
<a href="http://digitalid.verisign.com/server/apacheNotice.htm">
http://digitalid.verisign.com/server/apacheNotice.htm
</a>
</li>
<li> Thawte Consulting<br />
<a href="http://www.thawte.com/certs/server/request.html">
http://www.thawte.com/certs/server/request.html
</a>
</li>
<li> CertiSign Certificadora Digital Ltda.<br />
<a href="http://www.certisign.com.br">
http://www.certisign.com.br
</a>
</li>
<li> IKS GmbH<br />
<a href="http://www.iks-jena.de/produkte/ca/">
http://www.iks-jena.de/produkte/ca/
</a>
</li>
<li> Uptime Commerce Ltd.<br />
<a href="http://www.uptimecommerce.com">
http://www.uptimecommerce.com
</a>
</li>
<li> BelSign NV/SA<br />
<a href="http://www.belsign.be">
http://www.belsign.be
</a>
</li>
</ol>
<br />
Second you can use your own CA and now have to sign the CSR yourself by
this CA. Read the next answer in this FAQ on how to sign a CSR with
your CA yourself.
You can see the details of the received Certificate via the command:<br />
<br />
<code><strong>$ openssl x509 -noout -text -in server.crt</strong></code><br />
</li>
<li>Now you have two files: <code>server.key</code> and
<code>server.crt</code>. These now can be used as following inside your
Apache's <code>httpd.conf</code> file:
<pre>
SSLCertificateFile /path/to/this/server.crt
SSLCertificateKeyFile /path/to/this/server.key
</pre>
The <code>server.csr</code> file is no longer needed.
</li>
</ol>
<h3><a name="ownca" id="ownca">How can I create and use my own Certificate Authority (CA)?</a></h3>
<p>The short answer is to use the <code>CA.sh</code> or <code>CA.pl</code>
script provided by OpenSSL. The long and manual answer is this:</p>
<ol>
<li>Create a RSA private key for your CA
(will be Triple-DES encrypted and PEM formatted):<br />
<br />
<code><strong>$ openssl genrsa -des3 -out ca.key 1024</strong></code><br />
<br />
Please backup this <code>ca.key</code> file and remember the
pass-phrase you currently entered at a secure location.
You can see the details of this RSA private key via the command<br />
<br />
<code><strong>$ openssl rsa -noout -text -in ca.key</strong></code><br />
<br />
And you can create a decrypted PEM version (not recommended) of this
private key via:<br />
<br />
<code><strong>$ openssl rsa -in ca.key -out ca.key.unsecure</strong></code><br />
<br />
</li>
<li>Create a self-signed CA Certificate (X509 structure)
with the RSA key of the CA (output will be PEM formatted):<br />
<br />
<code><strong>$ openssl req -new -x509 -days 365 -key ca.key -out ca.crt</strong></code><br />
<br />
You can see the details of this Certificate via the command:<br />
<br />
<code><strong>$ openssl x509 -noout -text -in ca.crt</strong></code><br />
<br />
</li>
<li>Prepare a script for signing which is needed because
the ``<code>openssl ca</code>'' command has some strange requirements
and the default OpenSSL config doesn't allow one easily to use
``<code>openssl ca</code>'' directly. So a script named
<code>sign.sh</code> is distributed with the mod_ssl distribution
(subdir <code>pkg.contrib/</code>). Use this script for signing.
</li>
<li>Now you can use this CA to sign server CSR's in order to create real
SSL Certificates for use inside an Apache webserver (assuming
you already have a <code>server.csr</code> at hand):<br />
<br />
<code><strong>$ ./sign.sh server.csr</strong></code><br />
<br />
This signs the server CSR and results in a <code>server.crt</code> file.<br />
</li>
</ol>
<h3><a name="passphrase" id="passphrase">How can I change the pass-phrase on my private key file?</a></h3>
<p>You simply have to read it with the old pass-phrase and write it again
by specifying the new pass-phrase. You can accomplish this with the following
commands:</p>
<p><code><strong>$ openssl rsa -des3 -in server.key -out server.key.new</strong></code><br />
<code><strong>$ mv server.key.new server.key</strong></code><br /></p>
<p>Here you're asked two times for a PEM pass-phrase. At the first
prompt enter the old pass-phrase and at the second prompt
enter the new pass-phrase.</p>
<h3><a name="removepassphrase" id="removepassphrase">How can I get rid of the pass-phrase dialog at Apache startup time?</a></h3>
<p>The reason why this dialog pops up at startup and every re-start
is that the RSA private key inside your server.key file is stored in
encrypted format for security reasons. The pass-phrase is needed to be
able to read and parse this file. When you can be sure that your server is
secure enough you perform two steps:</p>
<ol>
<li>Remove the encryption from the RSA private key (while
preserving the original file):<br />
<br />
<code><strong>$ cp server.key server.key.org</strong></code><br />
<code><strong>$ openssl rsa -in server.key.org -out server.key</strong></code><br />
<br />
</li>
<li>Make sure the server.key file is now only readable by root:<br />
<br />
<code><strong>$ chmod 400 server.key</strong></code><br />
<br />
</li>
</ol>
<p>Now <code>server.key</code> will contain an unencrypted copy of the key.
If you point your server at this file it will not prompt you for a
pass-phrase. HOWEVER, if anyone gets this key they will be able to
impersonate you on the net. PLEASE make sure that the permissions on that
file are really such that only root or the web server user can read it
(preferably get your web server to start as root but run as another
server, and have the key readable only by root).</p>
<p>As an alternative approach you can use the ``<code>SSLPassPhraseDialog
exec:/path/to/program</code>'' facility. But keep in mind that this is
neither more nor less secure, of course.</p>
<h3><a name="verify" id="verify">How do I verify that a private key matches its Certificate?</a></h3>
<p>The private key contains a series of numbers. Two of those numbers form
the "public key", the others are part of your "private key". The "public
key" bits are also embedded in your Certificate (we get them from your
CSR). To check that the public key in your cert matches the public
portion of your private key, you need to view the cert and the key and
compare the numbers. To view the Certificate and the key run the
commands:</p>
<p><code><strong>$ openssl x509 -noout -text -in server.crt</strong></code><br />
<code><strong>$ openssl rsa -noout -text -in server.key</strong></code></p>
<p>The `modulus' and the `public exponent' portions in the key and the
Certificate must match. But since the public exponent is usually 65537
and it's bothering comparing long modulus you can use the following
approach:</p>
<p><code><strong>$ openssl x509 -noout -modulus -in server.crt | openssl md5</strong></code><br />
<code><strong>$ openssl rsa -noout -modulus -in server.key | openssl md5</strong></code></p>
<p>And then compare these really shorter numbers. With overwhelming
probability they will differ if the keys are different. BTW, if I want to
check to which key or certificate a particular CSR belongs you can compute</p>
<p><code><strong>$ openssl req -noout -modulus -in server.csr | openssl md5</strong></code></p>
<h3><a name="badcert" id="badcert">What does it mean when my connections fail with an "alert bad certificate"
error?</a></h3>
<p>Usually when you see errors like <code>OpenSSL: error:14094412: SSL
routines:SSL3_READ_BYTES:sslv3 alert bad certificate</code> in the SSL
logfile, this means that the browser was unable to handle the server
certificate/private-key which perhaps contain a RSA-key not equal to 1024
bits. For instance Netscape Navigator 3.x is one of those browsers.</p>
<h3><a name="keysize" id="keysize">Why does my 2048-bit private key not work?</a></h3>
<p>The private key sizes for SSL must be either 512 or 1024 for compatibility
with certain web browsers. A keysize of 1024 bits is recommended because
keys larger than 1024 bits are incompatible with some versions of Netscape
Navigator and Microsoft Internet Explorer, and with other browsers that
use RSA's BSAFE cryptography toolkit.</p>
<h3><a name="hashsymlinks" id="hashsymlinks">Why is client authentication broken after upgrading from
SSLeay version 0.8 to 0.9?</a></h3>
<p>The CA certificates under the path you configured with
<code>SSLCACertificatePath</code> are found by SSLeay through hash
symlinks. These hash values are generated by the `<code>openssl x509 -noout
-hash</code>' command. But the algorithm used to calculate the hash for a
certificate has changed between SSLeay 0.8 and 0.9. So you have to remove
all old hash symlinks and re-create new ones after upgrading. Use the
<code>Makefile</code> mod_ssl placed into this directory.</p>
<h3><a name="pemder" id="pemder">How can I convert a certificate from PEM to DER format?</a></h3>
<p>The default certificate format for SSLeay/OpenSSL is PEM, which actually
is Base64 encoded DER with header and footer lines. For some applications
(e.g. Microsoft Internet Explorer) you need the certificate in plain DER
format. You can convert a PEM file <code>cert.pem</code> into the
corresponding DER file <code>cert.der</code> with the following command:
<code><strong>$ openssl x509 -in cert.pem -out cert.der -outform DER</strong></code></p>
<h3><a name="verisign" id="verisign">I try to install a Verisign certificate. Why can't I find neither the
<code>getca</code> nor <code>getverisign</code> programs Verisign mentions?</a></h3>
<p>This is because Verisign has never provided specific instructions
for Apache+mod_ssl. Rather they tell you what you should do
if you were using C2Net's Stronghold (a commercial Apache
based server with SSL support). The only thing you have to do
is to save the certificate into a file and give the name of
that file to the <code>SSLCertificateFile</code> directive.
Remember that you need to give the key file in as well (see
<code>SSLCertificateKeyFile</code> directive). For a better
CA-related overview on SSL certificate fiddling you can look at <a href="http://www.thawte.com/certs/server/keygen/mod_ssl.html">Thawte's mod_ssl instructions</a>.</p>
<h3><a name="sgc" id="sgc">Can I use the Server Gated Cryptography (SGC) facility (aka Verisign Global
ID) also with mod_ssl?</a></h3>
<p>Yes, mod_ssl since version 2.1 supports the SGC facility. You don't have
to configure anything special for this, just use a Global ID as your
server certificate. The <em>step up</em> of the clients are then
automatically handled by mod_ssl under run-time. For details please read
the <code>README.GlobalID</code> document in the mod_ssl distribution.</p>
<h3><a name="gid" id="gid">After I have installed my new Verisign Global ID server certificate, the
browsers complain that they cannot verify the server certificate?</a></h3>
<p>That is because Verisign uses an intermediate CA certificate between
the root CA certificate (which is installed in the browsers) and
the server certificate (which you installed in the server). You
should have received this additional CA certificate from Verisign.
If not, complain to them. Then configure this certificate with the
<code>SSLCertificateChainFile</code> directive in the server. This
makes sure the intermediate CA certificate is send to the browser
and this way fills the gap in the certificate chain.</p>
</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div><div class="section"><h2><a name="aboutssl" id="aboutssl">About SSL Protocol</a></h2>
<ul>
<li><a href="#random">Random SSL errors under heavy load?</a></li>
<li><a href="#load">Why has the server a higher load?</a></li>
<li><a href="#establishing">Why are connections horribly slow?</a></li>
<li><a href="#ciphers">Which ciphers are supported?</a></li>
<li><a href="#adh">How to use Anonymous-DH ciphers</a></li>
<li><a href="#sharedciphers">Why do I get 'no shared ciphers'?</a></li>
<li><a href="#vhosts">HTTPS and name-based vhosts</a></li>
<li><a href="#lockicon">The lock icon in Netscape locks very late</a></li>
<li><a href="#msie">Why do I get I/O errors with MSIE clients?</a></li>
<li><a href="#nn">Why do I get I/O errors with NS clients?</a></li>
</ul>
<h3><a name="random" id="random">Why do I get lots of random SSL protocol errors under heavy server load?</a></h3>
<p>There can be a number of reasons for this, but the main one
is problems with the SSL session Cache specified by the
<code class="directive"><a href="../mod/mod_ssl.html#sslsessioncache">SSLSessionCache</a></code> directive. The DBM session
cache is most likely the source of the problem, so trying the SHM session cache or
no cache at all may help.</p>
<h3><a name="load" id="load">Why has my webserver a higher load now that I run SSL there?</a></h3>
<p>Because SSL uses strong cryptographic encryption and this needs a lot of
number crunching. And because when you request a webpage via HTTPS even
the images are transfered encrypted. So, when you have a lot of HTTPS
traffic the load increases.</p>
<h3><a name="establishing" id="establishing">Often HTTPS connections to my server require up to 30 seconds for establishing
the connection, although sometimes it works faster?</a></h3>
<p>Usually this is caused by using a <code>/dev/random</code> device for
<code>SSLRandomSeed</code> which is blocking in read(2) calls if not
enough entropy is available. Read more about this problem in the refernce
chapter under <code>SSLRandomSeed</code>.</p>
<h3><a name="ciphers" id="ciphers">What SSL Ciphers are supported by mod_ssl?</a></h3>
<p>Usually just all SSL ciphers which are supported by the
version of OpenSSL in use (can depend on the way you built
OpenSSL). Typically this at least includes the following:</p>
<ol>
<li>RC4 with MD5</li>
<li>RC4 with MD5 (export version restricted to 40-bit key)</li>
<li>RC2 with MD5</li>
<li>RC2 with MD5 (export version restricted to 40-bit key)</li>
<li>IDEA with MD5</li>
<li>DES with MD5</li>
<li>Triple-DES with MD5</li>
</ol>
<p>To determine the actual list of supported ciphers you can
run the following command:</p>
<div class="example"><p><code>$ openssl ciphers -v</code></p></div>
<h3><a name="adh" id="adh">I want to use Anonymous Diffie-Hellman (ADH) ciphers, but I always get ``no
shared cipher'' errors?</a></h3>
<p>In order to use Anonymous Diffie-Hellman (ADH) ciphers, it is not enough
to just put ``<code>ADH</code>'' into your <code>SSLCipherSuite</code>.
Additionally you have to build OpenSSL with
``<code>-DSSL_ALLOW_ADH</code>''. Because per default OpenSSL does not
allow ADH ciphers for security reasons. So if you are actually enabling
these ciphers make sure you are informed about the side-effects.</p>
<h3><a name="sharedciphers" id="sharedciphers">I always just get a 'no shared ciphers' error if
I try to connect to my freshly installed server?</a></h3>
<p>Either you have messed up your <code>SSLCipherSuite</code>
directive (compare it with the pre-configured example in
<code>httpd.conf-dist</code>) or you have choosen the DSA/DH
algorithms instead of RSA when you generated your private key
and ignored or overlooked the warnings. If you have choosen
DSA/DH, then your server no longer speaks RSA-based SSL ciphers
(at least not until you also configure an additional RSA-based
certificate/key pair). But current browsers like NS or IE only speak
RSA ciphers. The result is the "no shared ciphers" error. To fix
this, regenerate your server certificate/key pair and this time
choose the RSA algorithm.</p>
<h3><a name="vhosts" id="vhosts">Why can't I use SSL with name-based/non-IP-based virtual hosts?</a></h3>
<p>The reason is very technical. Actually it's some sort of a chicken and
egg problem: The SSL protocol layer stays below the HTTP protocol layer
and encapsulates HTTP. When an SSL connection (HTTPS) is established
Apache/mod_ssl has to negotiate the SSL protocol parameters with the
client. For this mod_ssl has to consult the configuration of the virtual
server (for instance it has to look for the cipher suite, the server
certificate, etc.). But in order to dispatch to the correct virtual server
Apache has to know the <code>Host</code> HTTP header field. For this the
HTTP request header has to be read. This cannot be done before the SSL
handshake is finished. But the information is already needed at the SSL
handshake phase. Bingo!</p>
<h3><a name="lockicon" id="lockicon">When I use Basic Authentication over HTTPS the lock icon in Netscape browsers
still shows the unlocked state when the dialog pops up. Does this mean the
username/password is still transmitted unencrypted?</a></h3>
<p>No, the username/password is already transmitted encrypted. The icon in
Netscape browsers is just not really synchronized with the SSL/TLS layer
(it toggles to the locked state when the first part of the actual webpage
data is transferred which is not quite correct) and this way confuses
people. The Basic Authentication facility is part of the HTTP layer and
this layer is above the SSL/TLS layer in HTTPS. And before any HTTP data
communication takes place in HTTPS the SSL/TLS layer has already done the
handshake phase and switched to encrypted communication. So, don't get
confused by this icon.</p>
<h3><a name="msie" id="msie">When I connect via HTTPS to an Apache+mod_ssl+OpenSSL server with Microsoft Internet
Explorer (MSIE) I get various I/O errors. What is the reason?</a></h3>
<p>The first reason is that the SSL implementation in some MSIE versions has
some subtle bugs related to the HTTP keep-alive facility and the SSL close
notify alerts on socket connection close. Additionally the interaction
between SSL and HTTP/1.1 features are problematic with some MSIE versions,
too. You've to work-around these problems by forcing
Apache+mod_ssl+OpenSSL to not use HTTP/1.1, keep-alive connections or
sending the SSL close notify messages to MSIE clients. This can be done by
using the following directive in your SSL-aware virtual host section:</p>
<div class="example"><p><code>
SetEnvIf User-Agent ".*MSIE.*" \<br />
nokeepalive ssl-unclean-shutdown \<br />
downgrade-1.0 force-response-1.0
</code></p></div>
<p>Additionally it is known some MSIE versions have also problems
with particular ciphers. Unfortunately one cannot workaround these
bugs only for those MSIE particular clients, because the ciphers
are already used in the SSL handshake phase. So a MSIE-specific
<code class="directive"><a href="../mod/mod_setenvif.html#setenvif">SetEnvIf</a></code> doesn't work
to solve these problems. Instead one has to do more drastic
adjustments to the global parameters. But before you decide to do
this, make sure your clients really have problems. If not, do not
do this, because it affects all(!) your clients, i.e., also your
non-MSIE clients.</p>
<p>The next problem is that 56bit export versions of MSIE 5.x browsers have a
broken SSLv3 implementation which badly interacts with OpenSSL versions
greater than 0.9.4. You can either accept this and force your clients to
upgrade their browsers, or you downgrade to OpenSSL 0.9.4 (hmmm), or you
can decide to workaround it by accepting the drawback that your workaround
will horribly affect also other browsers:</p>
<div class="example"><p><code>SSLProtocol all -SSLv3</code></p></div>
<p>This completely disables the SSLv3 protocol and lets those browsers work.
But usually this is an even less acceptable workaround. A more reasonable
workaround is to address the problem more closely and disable only the
ciphers which cause trouble.</p>
<div class="example"><p><code>SSLCipherSuite
ALL:!ADH:<strong>!EXPORT56</strong>:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP</code>
</p></div>
<p>This also lets the broken MSIE versions work, but only removes the
newer 56bit TLS ciphers.</p>
<p>Another problem with MSIE 5.x clients is that they refuse to connect to
URLs of the form <code>https://12.34.56.78/</code> (IP-addresses are used
instead of the hostname), if the server is using the Server Gated
Cryptography (SGC) facility. This can only be avoided by using the fully
qualified domain name (FQDN) of the website in hyperlinks instead, because
MSIE 5.x has an error in the way it handles the SGC negotiation.</p>
<p>And finally there are versions of MSIE which seem to require that
an SSL session can be reused (a totally non standard-conforming
behaviour, of course). Connection with those MSIE versions only work
if a SSL session cache is used. So, as a work-around, make sure you
are using a session cache (see <code class="directive"><a href="../mod/mod_ssl.html#sslsessioncache">SSLSessionCache</a></code> directive).</p>
<h3><a name="nn" id="nn">When I connect via HTTPS to an Apache+mod_ssl server with Netscape Navigator I
get I/O errors and the message "Netscape has encountered bad data from the
server" What's the reason?</a></h3>
<p>
The problem usually is that you had created a new server certificate with
the same DN, but you had told your browser to accept forever the old
server certificate. Once you clear the entry in your browser for the old
certificate, everything usually will work fine. Netscape's SSL
implementation is correct, so when you encounter I/O errors with Netscape
Navigator it is most of the time caused by the configured certificates.</p>
</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div><div class="section"><h2><a name="support" id="support">About Support</a></h2>
<ul>
<li><a href="#resources">Resources in case of problems?</a></li>
<li><a href="#contact">Support in case of problems?</a></li>
<li><a href="#reportdetails">How to write a problem report?</a></li>
<li><a href="#coredumphelp">I got a core dump, can you help me?</a></li>
<li><a href="#backtrace">How to get a backtrace?</a></li>
</ul>
<h3><a name="resources" id="resources">What information resources are available in case of mod_ssl problems?</a></h3>
<p>The following information resources are available.
In case of problems you should search here first.</p>
<dl>
<dt>Answers in the User Manual's F.A.Q. List (this)</dt>
<dd><a href="http://httpd.apache.org/docs-2.0/ssl/ssl_faq.html">
http://httpd.apache.org/docs-2.0/ssl/ssl_faq.html</a><br />
First look inside the F.A.Q. (this text), perhaps your problem is such
popular that it was already answered a lot of times in the past.
</dd>
<dt>Postings from the modssl-users Support Mailing List
<a href="http://www.modssl.org/support/">
http://www.modssl.org/support/</a></dt>
<dd>Second search for your problem in one of the existing archives of the
modssl-users mailing list. Perhaps your problem popped up at least once for
another user, too.
</dd>
<dt>Problem Reports in the Bug Database
<a href="http://www.modssl.org/support/bugdb/">
http://www.modssl.org/support/bugdb/</a></dt>
<dd>Third look inside the mod_ssl Bug Database. Perhaps
someone else already has reported the problem.
</dd>
</dl>
<h3><a name="contact" id="contact">What support contacts are available in case of mod_ssl problems?</a></h3>
<p>The following lists all support possibilities for mod_ssl, in order of
preference, i.e. start in this order and do not pick the support possibility
you just like most, please.</p>
<ol>
<li><em>Write a Problem Report into the Bug Database</em><br />
<a href="http://www.modssl.org/support/bugdb/">
http://www.modssl.org/support/bugdb/</a><br />
This is the preferred way of submitting your problem report, because this
way it gets filed into the bug database (it cannot be lost) <em>and</em>
send to the modssl-users mailing list (others see the current problems and
learn from answers).
</li>
<li><em>Write a Problem Report to the modssl-users Support Mailing List</em><br />
<a href="mailto:modssl-users@modssl.org">
modssl-users@modssl.org</a><br />
This is the second way of submitting your problem report. You have to
subscribe to the list first, but then you can easily discuss your problem
with both the author and the whole mod_ssl user community.
</li>
<li><em>Write a Problem Report to the author</em><br />
<a href="mailto:rse@engelschall.com">rse@engelschall.com</a><br />
This is the last way of submitting your problem report. Please avoid this
in your own interest because the author is really a very busy men. Your
mail will always be filed to one of his various mail-folders and is
usually not processed as fast as a posting on modssl-users.
</li>
</ol>
<h3><a name="reportdetails" id="reportdetails">What information and details I've to provide to
the author when writing a bug report?</a></h3>
<p>You have to at least always provide the following information:</p>
<dl>
<dt>Apache, mod_ssl and OpenSSL version information</dt>
<dd>The mod_ssl version you should really know. For instance, it's the version
number in the distribution tarball. The Apache version can be determined
by running ``<code>httpd -v</code>''. The OpenSSL version can be
determined by running ``<code>openssl version</code>''. Alternatively when
you have Lynx installed you can run the command ``<code>lynx -mime_header
http://localhost/ | grep Server</code>'' to determine all information in a
single step.
</dd>
<dt>The details on how you built and installed Apache+mod_ssl+OpenSSL</dt>
<dd>For this you can provide a logfile of your terminal session which shows
the configuration and install steps. Alternatively you can at least
provide the author with the APACI <code>configure</code> command line
you used (assuming you used APACI, of course).
</dd>
<dt>In case of core dumps please include a Backtrace</dt>
<dd>In case your Apache+mod_ssl+OpenSSL should really dumped core please attach
a stack-frame ``backtrace'' (see the next question on how to get it).
Without this information the reason for your core dump cannot be found.
So you have to provide the backtrace, please.
</dd>
<dt>A detailed description of your problem</dt>
<dd>Don't laugh, I'm totally serious. I already got a lot of problem reports
where the people not really said what's the actual problem is. So, in your
own interest (you want the problem be solved, don't you?) include as much
details as possible, please. But start with the essentials first, of
course.
</dd>
</dl>
<h3><a name="coredumphelp" id="coredumphelp">I got a core dump, can you help me?</a></h3>
<p>In general no, at least not unless you provide more details about the code
location where Apache dumped core. What is usually always required in
order to help you is a backtrace (see next question). Without this
information it is mostly impossible to find the problem and help you in
fixing it.</p>
<h3><a name="backtrace" id="backtrace">Ok, I got a core dump but how do I get a backtrace to find out the reason for it?</a></h3>
<p>Follow the following steps:</p>
<ol>
<li>Make sure you have debugging symbols available in at least
Apache and mod_ssl. On platforms where you use GCC/GDB you have to build
Apache+mod_ssl with ``<code>OPTIM="-g -ggdb3"</code>'' to achieve this. On
other platforms at least ``<code>OPTIM="-g"</code>'' is needed.
</li>
<li>Startup the server and try to produce the core-dump. For this you perhaps
want to use a directive like ``<code>CoreDumpDirectory /tmp</code>'' to
make sure that the core-dump file can be written. You then should get a
<code>/tmp/core</code> or <code>/tmp/httpd.core</code> file. When you
don't get this, try to run your server under an UID != 0 (root), because
most "current" kernels do not allow a process to dump core after it has
done a <code>setuid()</code> (unless it does an <code>exec()</code>) for
security reasons (there can be privileged information left over in
memory). Additionally you can run ``<code>/path/to/httpd -X</code>''
manually to force Apache to not fork.
</li>
<li>Analyze the core-dump. For this run <code>gdb /path/to/httpd
/tmp/httpd.core</code> or a similar command has to run. In GDB you then
just have to enter the <code>bt</code> command and, voila, you get the
backtrace. For other debuggers consult your local debugger manual. Send
this backtrace to the author.
</li>
</ol>
</div></div><div id="footer"><p class="apache">Maintained by the <a href="http://httpd.apache.org/docs-project/">Apache HTTP Server Documentation Project</a></p><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></body></html>
1.1 httpd-2.0/docs/manual/ssl/ssl_faq.xml
Index: ssl_faq.xml
===================================================================
<?xml version='1.0' encoding='UTF-8' ?>
<!DOCTYPE manualpage SYSTEM "../style/manualpage.dtd">
<?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
<manualpage>
<relativepath href=".."/>
<title>SSL/TLS Strong Encryption: FAQ</title>
<summary>
<blockquote>
<p>The wise man doesn't give the right answers,
he poses the right questions.</p>
<p class="cite">--<cite>Claude Levi-Strauss</cite></p>
</blockquote>
<p>This chapter is a collection of frequently asked questions (FAQ) and
corresponding answers following the popular USENET tradition. Most of these
questions occured on the Newsgroup <code><a href="news:comp.infosystems.www.servers.unix"
>comp.infosystems.www.servers.unix</a></code> or the mod_ssl Support
Mailing List <code><a href="mailto:modssl-users@modssl.org"
>modssl-users@modssl.org</a></code>. They are collected at this place
to avoid answering the same questions over and over.</p>
<p>Please read this chapter at least once when installing mod_ssl or at least
search for your problem here before submitting a problem report to the
author.</p>
</summary>
<section id="about"><title>About The Module</title>
<ul>
<li><a href="#history">What is the history of mod_ssl?</a></li>
<li><a href="#apssl-diff">Apache-SSL vs. mod_ssl: differences?</a></li>
<li><a href="#commalt">mod_ssl vs. commercial alternatives?</a></li>
<li><a href="#modversion">mod_ssl/Apache versions?</a></li>
<li><a href="#y2k">mod_ssl and Year 2000?</a></li>
<li><a href="#wassenaar">mod_ssl and Wassenaar Arrangement?</a></li>
</ul>
<section id="history"><title>What is the history of mod_ssl?</title>
<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
Apache 1.2.6 to Apache 1.3b6. Because of conflicts with Ben
Laurie's development cycle it then was re-assembled from scratch for
Apache 1.3.0 by merging the old mod_ssl 1.x with the newer Apache-SSL
1.18. From this point on mod_ssl lived its own life as mod_ssl v2. The
first publically released version was mod_ssl 2.0.0 from August 10th,
1998. As of this writing (August 1999) the current mod_ssl version
is 2.4.0.</p>
<p>After one year of very active development with over 1000 working hours and
over 40 releases mod_ssl reached its current state. The result is an
already very clean source base implementing a very rich functionality.
The code size increased by a factor of 4 to currently a total of over
10.000 lines of ANSI C consisting of approx. 70% code and 30% code
documentation. From the original Apache-SSL code currently approx. 5% is
remaining only.</p>
<p>After the US export restrictions for cryptographic software were
opened, mod_ssl was integrated into the code base of Apache V2 in 2001.</p>
</section>
<section id="apssl-diff"><title>What are the functional differences between mod_ssl and Apache-SSL, from which
it is originally derived?</title>
<p>This neither can be answered in short (there were too many code changes)
nor can be answered at all by the author (there would immediately be flame
wars with no reasonable results at the end). But as you easily can guess
from the 5% of remaining Apache-SSL code, a lot of differences exists,
although user-visible backward compatibility exists for most things.</p>
<p>When you really want a detailed comparison you have to read the entries in
the large <code>CHANGES</code> file that is in the mod_ssl
distribution. Usually this is much too hard-core. So I recommend you to
either believe in the opinion and recommendations of other users (the
simplest approach) or do a comparison yourself (the most reasonable
approach). For the latter, grab distributions of mod_ssl (from <a
href="http://www.modssl.org/">http://www.modssl.org</a>) and Apache-SSL
(from <a href="http://www.apache-ssl.org/">http://www.apache-ssl.org</a>),
install both packages, read their documentation and try them out yourself.
Then choose the one which pleases you most.</p>
<p>A few final hints to help direct your comparison: quality of documentation
("can you easily find answers and are they sufficient?"), quality of
source code ("is the source code reviewable so you can make sure there
aren't any trapdoors or inherent security risks because of bad programming
style?"), easy and clean installation ("can the SSL functionality easily
added to an Apache source tree without manual editing or patching?"),
clean integration into Apache ("is the SSL functionality encapsulated and
cleanly separated from the remaining Apache functionality?"), support for
Dynamic Shared Object (DSO) facility ("can the SSL functionality built as
a separate DSO for maximum flexibility?"), Win32 port ("is the SSL
functionality available also under the Win32 platform?"), amount and
quality of functionality ("is the provided SSL functionality and control
possibilities sufficient for your situation?"), quality of problem tracing
("is it possible for you to easily trace down the problems via logfiles,
etc?"), etc. pp.</p>
</section>
<section id="commalt"><title>What are the major differences between mod_ssl and
the commercial alternatives like Raven or Stronghold?</title>
<p>In the past (until September 20th, 2000) the major difference was
the RSA license which one received (very cheaply in contrast to
a direct licensing from RSA DSI) with the commercial Apache SSL
products. On the other hand, one needed this license only in the US,
of course. So for non-US citizens this point was useless. But now
even for US citizens the situations changed because the RSA patent
expired on September 20th, 2000 and RSA DSI also placed the RSA
algorithm explicitly into the public domain.</p>
<p>Second, there is the point that one has guaranteed support from
the commercial vendors. On the other hand, if you monitored the
Open Source quality of mod_ssl and the support activities
found on <a href="mailto:modssl-users@modssl.org">
<code>modssl-users@modssl.org</code></a>, you could ask yourself
whether you are really convinced that you can get better support
from a commercial vendor.</p>
<p>Third, people often think they would receive perhaps at least a
better technical SSL solution than mod_ssl from the commercial
vendors. But this is not really true, because all commercial
alternatives (Raven 1.4.x, Stronghold 3.x, RedHat SWS 2.x, etc.)
<em>are</em> actually based on mod_ssl and OpenSSL. The reason for
this common misunderstanding is mainly because some vendors make no
attempt to make it reasonably clear that their product is actually
mod_ssl based. So, do not think, just because the commercial
alternatives are usually more expensive, that you are also receiving
an alternative <em>technical</em> SSL solution. This is usually not
the case. Actually the vendor versions of Apache, mod_ssl and OpenSSL
often stay behind the latest free versions and perhaps this way still do not
include important bug and security fixes. On the other hand,
it sometimes occurs that a vendor version includes useful changes
which are not available through the official freely available
packages. But most vendors play fair and contribute back those
changes to the free software world, of course.</p>
<p>So, in short: There are lots of commercial versions of the popular
Apache+mod_ssl+OpenSSL server combination available. Every user
should decide carefully whether they really need to buy a commercial
version or whether it would not be sufficient to directly use the
free and official versions of the Apache, mod_ssl and OpenSSL
packages.</p>
</section>
<section id="modversion"><title>How do I know which mod_ssl version is for which Apache version?</title>
<p>That's trivial: mod_ssl uses version strings of the syntax
<em><mod_ssl-version></em>-<em><apache-version></em>, for
instance <code>2.4.0-1.3.9</code>. This directly indicates that it's
mod_ssl version 2.4.0 for Apache version 1.3.9. And this also means you
<em>only</em> can apply this mod_ssl version to exactly this Apache
version (unless you use the <code>--force</code> option to mod_ssl's
<code>configure</code> command ;-).</p>
</section>
<section id="y2k"><title>Is mod_ssl Year 2000 compliant?</title>
<p>Yes, mod_ssl is Year 2000 compliant.</p>
<p>Because first mod_ssl internally never stores years as two digits.
Instead it always uses the ANSI C & POSIX numerical data type
<code>time_t</code> type, which on almost all Unix platforms at the moment
is a <code>signed long</code> (usually 32-bits) representing seconds since
epoch of January 1st, 1970, 00:00 UTC. This signed value overflows in
early January 2038 and not in the year 2000. Second, date and time
presentations (for instance the variable ``<code>%{TIME_YEAR}</code>'')
are done with full year value instead of abbreviating to two digits.</p>
<p>Additionally according to a <a
href="http://www.apache.org/docs/misc/FAQ.html#year2000">Year 2000
statement</a> from the Apache Group, the Apache webserver is Year 2000
compliant, too. But whether OpenSSL or the underlaying Operating System
(either a Unix or Win32 platform) is Year 2000 compliant is a different
question which cannot be answered here.</p>
</section>
<section id="wassenaar"><title>What about mod_ssl and the Wassenaar Arrangement?</title>
<p>First, let us explain what <dfn>Wassenaar</dfn> and its <dfn>Arrangement on
Export Controls for Conventional Arms and Dual-Use Goods and
Technologies</dfn> is: This is a international regime, established 1995, to
control trade in conventional arms and dual-use goods and technology. It
replaced the previous <dfn>CoCom</dfn> regime. 33 countries are signatories:
Argentina, Australia, Austria, Belgium, Bulgaria, Canada, Czech Republic,
Denmark, Finland, France, Germany, Greece, Hungary, Ireland, Italy, Japan,
Luxembourg, Netherlands, New Zealand, Norway, Poland, Portugal, Republic
of Korea, Romania, Russian Federation, Slovak Republic, Spain, Sweden,
Switzerland, Turkey, Ukraine, United Kingdom and United States. For more
details look at <a
href="http://www.wassenaar.org/">http://www.wassenaar.org/</a>.</p>
<p>In short: The aim of the Wassenaar Arrangement is to prevent the build up
of military capabilities that threaten regional and international security
and stability. The Wassenaar Arrangement controls the export of
cryptography as a dual-use good, i.e., one that has both military and
civilian applications. However, the Wassenaar Arrangement also provides an
exemption from export controls for mass-market software and free software.</p>
<p>In the current Wassenaar <cite>List of Dual Use Goods and Technologies And
Munitions</cite>, under <q>GENERAL SOFTWARE NOTE (GSN)</q> it says
<q>The Lists do not control "software" which is either: 1. [...] 2. "in
the public domain".</q> And under <q>DEFINITIONS OF TERMS USED IN
THESE LISTS</q> one can find the definition: <q>In the public
domain": This means "technology" or "software" which has been made
available without restrictions upon its further dissemination. N.B.
Copyright restrictions do not remove "technology" or "software" from being
"in the public domain".</q></p>
<p>So, both mod_ssl and OpenSSL are <q>in the public domain</q> for the purposes
of the Wassenaar Agreement and its <q>List of Dual Use Goods and
Technologies And Munitions List</q>.</p>
<p>Additionally the Wassenaar Agreement itself has no direct consequence for
exporting cryptography software. What is actually allowed or forbidden to
be exported from the countries has still to be defined in the local laws
of each country. And at least according to official press releases from
the German BMWi (see <a
href="http://www.bmwi.de/presse/1998/1208prm2.html">here</a>) and the
Switzerland Bawi (see <a href="http://jya.com/wass-ch.htm">here</a>) there
will be no forthcoming export restriction for free cryptography software
for their countries. Remember that mod_ssl is created in Germany and
distributed from Switzerland.</p>
<p>So, mod_ssl and OpenSSL are not affected by the Wassenaar Agreement.</p>
</section>
</section>
<!-- /about -->
<section id="installation"><title>About Installation</title>
<ul>
<li><a href="#coredump">Core dumps for HTTPS requests?</a></li>
<li><a href="#php3">Core dumps for Apache+mod_ssl+PHP3?</a></li>
<li><a href="#undefinedsym">Undefined symbols on startup?</a></li>
<li><a href="#mutex">Permission problem on SSLMutex</a></li>
<li><a href="#mm">Shared memory and process size?</a></li>
<li><a href="#mmpath">Shared memory and pathname?</a></li>
<li><a href="#entropy">PRNG and not enough entropy?</a></li>
</ul>
<section id="coredump"><title>When I access my website the first time via HTTPS I get a core dump?</title>
<p>There can be a lot of reasons why a core dump can occur, of course.
Ranging from buggy third-party modules, over buggy vendor libraries up to
a buggy mod_ssl version. But the above situation is often caused by old or
broken vendor DBM libraries. To solve it either build mod_ssl with the
built-in SDBM library (specify <code>--enable-rule=SSL_SDBM</code> at the
APACI command line) or switch from <code>SSLSessionCache dbm:</code> to the
newer <code>SSLSessionCache shm:</code>'' variant (after you have rebuilt
Apache with MM, of course).</p>
</section>
<section id="php3"><title>My Apache dumps core when I add both mod_ssl and PHP3?</title>
<p>Make sure you add mod_ssl to the Apache source tree first and then do a
fresh configuration and installation of PHP3. For SSL support EAPI patches
are required which have to change internal Apache structures. PHP3 needs
to know about these in order to work correctly. Always make sure that
<code>-DEAPI</code> is contained in the compiler flags when PHP3 is built.</p>
</section>
<section id="undefinedsym"><title>When I startup Apache I get errors about undefined symbols like ap_global_ctx?</title>
<p>This actually means you installed mod_ssl as a DSO, but without rebuilding
Apache with EAPI. Because EAPI is a requirement for mod_ssl, you need an
extra patched Apache (containing the EAPI patches) and you have to build
this Apache with EAPI enabled (explicitly specify
<code>--enable-rule=EAPI</code> at the APACI command line).</p>
</section>
<section id="mutex"><title>When I startup Apache I get permission errors related to SSLMutex?</title>
<p>When you receive entries like ``<code>mod_ssl: Child could not open
SSLMutex lockfile /opt/apache/logs/ssl_mutex.18332 (System error follows)
[...] System: Permission denied (errno: 13)</code>'' this is usually
caused by to restrictive permissions on the <em>parent</em> directories.
Make sure that all parent directories (here <code>/opt</code>,
<code>/opt/apache</code> and <code>/opt/apache/logs</code>) have the x-bit
set at least for the UID under which Apache's children are running (see
the <directive module="mpm_common">User</directive> directive of Apache).</p>
</section>
<section id="mm"><title>When I use the MM library and the shared memory cache each process grows
1.5MB according to `top' although I specified 512000 as the cache size?</title>
<p>The additional 1MB are caused by the global shared memory pool EAPI
allocates for all modules and which is not used by mod_ssl for
various reasons. So the actually allocated shared memory is always
1MB more than what you specify on <directive module="mod_ssl">SSLSessionCache</directive>.
But don't be confused by the display of `top': although is
indicates that <em>each</em> process grow, this is not reality, of
course. Instead the additional memory consumption is shared by
all processes, i.e. the 1.5MB are allocated only once per Apache
instance and not once per Apache server process.</p>
</section>
<section id="mmpath"><title>Apache creates files in a directory declared by the internal
EAPI_MM_CORE_PATH define. Is there a way to override the path using a
configuration directive?</title>
<p>No, there is not configuration directive, because for technical
bootstrapping reasons, a directive not possible at all. Instead
use ``<code>CFLAGS='-DEAPI_MM_CORE_PATH="/path/to/wherever/"'
./configure ...</code>'' when building Apache or use option
<code>-d</code> when starting <code>httpd</code>.</p>
</section>
<section id="entropy"><title>When I fire up the server, mod_ssl stops with the error
"Failed to generate temporary 512 bit RSA private key", why?</title>
<p>Cryptographic software needs a source of unpredictable data
to work correctly. Many open source operating systems provide
a "randomness device" that serves this purpose (usually named
<code>/dev/random</code>). On other systems, applications have to
seed the OpenSSL Pseudo Random Number Generator (PRNG) manually with
appropriate data before generating keys or performing public key
encryption. As of version 0.9.5, the OpenSSL functions that need
randomness report an error if the PRNG has not been seeded with
at least 128 bits of randomness. So mod_ssl has to provide enough
entropy to the PRNG to work correctly. For this one has to use the
<code>SSLRandomSeed</code> directives.</p>
</section>
</section>
<!-- /installation -->
<section id="aboutconfig"><title>About Configuration</title>
<ul>
<li><a href="#parallel">HTTP and HTTPS with a single server?</a></li>
<li><a href="#ports">Where is the HTTPS port?</a></li>
<li><a href="#httpstest">How to test HTTPS manually?</a></li>
<li><a href="#hang">Why does my connection hang?</a></li>
<li><a href="#refused">Why do I get connection refused?</a></li>
<li><a href="#envvars">Why are the <code>SSL_XXX</code> variables missing?</a></li>
<li><a href="#relative">How to switch with relative hyperlinks?</a></li>
</ul>
<section id="parallel"><title>Is it possible to provide HTTP and HTTPS with a single server?</title>
<p>Yes, HTTP and HTTPS use different server ports, so there is no direct
conflict between them. Either run two separate server instances (one binds
to port 80, the other to port 443) or even use Apache's elegant virtual
hosting facility where you can easily create two virtual servers which
Apache dispatches: one responding to port 80 and speaking HTTP and one
responding to port 443 speaking HTTPS.</p>
</section>
<section id="ports"><title>I know that HTTP is on port 80, but where is HTTPS?</title>
<p>You can run HTTPS on any port, but the standards specify port 443, which
is where any HTTPS compliant browser will look by default. You can force
your browser to look on a different port by specifying it in the URL like
this (for port 666): <code>https://secure.server.dom:666/</code></p>
</section>
<section id="httpstest"><title>How can I speak HTTPS manually for testing purposes?</title>
<p>While you usually just use</p>
<example>$ telnet localhost 80<br />
GET / HTTP/1.0</example>
<p>for simple testing the HTTP protocol of Apache, it's not so easy for
HTTPS because of the SSL protocol between TCP and HTTP. But with the
help of OpenSSL's <code>s_client</code> command you can do a similar
check even for HTTPS:</p>
<example>$ openssl s_client -connect localhost:443 -state -debug<br />
GET / HTTP/1.0</example>
<p>Before the actual HTTP response you receive detailed information about the
SSL handshake. For a more general command line client which directly
understands both the HTTP and HTTPS scheme, can perform GET and POST
methods, can use a proxy, supports byte ranges, etc. you should have a
look at nifty <a href="http://curl.haxx.nu/">cURL</a>
tool. With it you can directly check if your Apache is running fine on
Port 80 and 443 as following:</p>
<example>$ curl http://localhost/<br />
$ curl https://localhost/</example>
</section>
<section id="hang"><title>Why does the connection hang when I connect to my SSL-aware Apache server?</title>
<p>Because you connected with HTTP to the HTTPS port, i.e. you used an URL of
the form ``<code>http://</code>'' instead of ``<code>https://</code>''.
This also happens the other way round when you connect via HTTPS to a HTTP
port, i.e. when you try to use ``<code>https://</code>'' on a server that
doesn't support SSL (on this port). Make sure you are connecting to a
virtual server that supports SSL, which is probably the IP associated with
your hostname, not localhost (127.0.0.1).</p>
</section>
<section id="refused"><title>Why do I get ``Connection Refused'' messages when trying to access my freshly
installed Apache+mod_ssl server via HTTPS?</title>
<p>There can be various reasons. Some of the common mistakes is that people
start Apache with just ``<code>apachectl start</code>'' (or
``<code>httpd</code>'') instead of ``<code>apachectl startssl</code>'' (or
``<code>httpd -DSSL</code>''. Or you're configuration is not correct. At
least make sure that your <directive module="mpm_common">Listen</directive>
directives match your <directive type="section" module="core">VirtualHost</directive>
directives. And if all fails, please do yourself a favor and start over with the
default configuration mod_ssl provides you.</p>
</section>
<section id="envvars"><title>In my CGI programs and SSI scripts the various documented
<code>SSL_XXX</code> variables do not exist. Why?</title>
<p>Just make sure you have ``<code>SSLOptions +StdEnvVars</code>''
enabled for the context of your CGI/SSI requests.</p>
</section>
<section id="relative"><title>How can I use relative hyperlinks to switch between HTTP and HTTPS?</title>
<p>Usually you have to use fully-qualified hyperlinks because
you have to change the URL scheme. But with the help of some URL
manipulations through mod_rewrite you can achieve the same effect while
you still can use relative URLs:</p>
<example>
RewriteEngine on<br />
RewriteRule ^/(.*):SSL$ https://%{SERVER_NAME}/$1 [R,L]<br />
RewriteRule ^/(.*):NOSSL$ http://%{SERVER_NAME}/$1 [R,L]
</example>
This rewrite ruleset lets you use hyperlinks of the form
<example><a href="document.html:SSL"></example>
</section>
</section>
<!-- configuration -->
<section id="aboutcerts"><title>About Certificates</title>
<ul>
<li><a href="#keyscerts">What are Keys, CSRs and Certs?</a></li>
<li><a href="#startup">Difference on startup?</a></li>
<li><a href="#realcert">How to create a real cert?</a></li>
<li><a href="#ownca">How to create my own CA?</a></li>
<li><a href="#passphrase">How to change a pass phrase?</a></li>
<li><a href="#removepassphrase">How to remove a pass phrase?</a></li>
<li><a href="#verify">How to verify a key/cert pair?</a></li>
<li><a href="#badcert">Bad Certificate Error?</a></li>
<li><a href="#keysize">Why does a 2048-bit key not work?</a></li>
<li><a href="#hashsymlinks">Why is client auth broken?</a></li>
<li><a href="#pemder">How to convert from PEM to DER?</a></li>
<li><a href="#verisign">Verisign and the magic getca program?</a></li>
<li><a href="#sgc">Global IDs or SGC?</a></li>
<li><a href="#gid">Global IDs and Cert Chain?</a></li>
</ul>
<section id="keyscerts"><title>What are RSA Private Keys, CSRs and Certificates?</title>
<p>The RSA private key file is a digital file that you can use to decrypt
messages sent to you. It has a public component which you distribute (via
your Certificate file) which allows people to encrypt those messages to
you. A Certificate Signing Request (CSR) is a digital file which contains
your public key and your name. You send the CSR to a Certifying Authority
(CA) to be converted into a real Certificate. A Certificate contains your
RSA public key, your name, the name of the CA, and is digitally signed by
your CA. Browsers that know the CA can verify the signature on that
Certificate, thereby obtaining your RSA public key. That enables them to
send messages which only you can decrypt.
See the <a href="ssl_intro.html">Introduction</a> chapter for a general
description of the SSL protocol.</p>
</section>
<section id="startup"><title>Seems like there is a difference on startup between the original Apache and an SSL-aware Apache?</title>
<p>Yes, in general, starting Apache with a built-in mod_ssl is just like
starting an unencumbered Apache, except for the fact that when you have a
pass phrase on your SSL private key file. Then a startup dialog pops up
asking you to enter the pass phrase.</p>
<p>To type in the pass phrase manually when starting the server can be
problematic, for instance when starting the server from the system boot
scripts. As an alternative to this situation you can follow the steps
below under ``How can I get rid of the pass-phrase dialog at Apache
startup time?''.</p>
</section>
<section id="realcert"><title>Ok, I've got my server installed and want to create a real SSL
server Certificate for it. How do I do it?</title>
<p>Here is a step-by-step description:</p>
<ol>
<li>Make sure OpenSSL is really installed and in your <code>PATH</code>.
But some commands even work ok when you just run the
``<code>openssl</code>'' program from within the OpenSSL source tree as
``<code>./apps/openssl</code>''.<br />
<br />
</li>
<li>Create a RSA private key for your Apache server
(will be Triple-DES encrypted and PEM formatted):<br />
<br />
<code><strong>$ openssl genrsa -des3 -out server.key 1024</strong></code><br />
<br />
Please backup this <code>server.key</code> file and remember the
pass-phrase you had to enter at a secure location.
You can see the details of this RSA private key via the command:<br />
<br />
<code><strong>$ openssl rsa -noout -text -in server.key</strong></code><br />
<br />
And you could create a decrypted PEM version (not recommended)
of this RSA private key via:<br />
<br />
<code><strong>$ openssl rsa -in server.key -out server.key.unsecure</strong></code><br />
<br />
</li>
<li>Create a Certificate Signing Request (CSR) with the server RSA private
key (output will be PEM formatted):<br />
<br />
<code><strong>$ openssl req -new -key server.key -out server.csr</strong></code><br />
<br />
Make sure you enter the FQDN ("Fully Qualified Domain Name") of the
server when OpenSSL prompts you for the "CommonName", i.e. when you
generate a CSR for a website which will be later accessed via
<code>https://www.foo.dom/</code>, enter "www.foo.dom" here.
You can see the details of this CSR via the command<br />
<br />
<code><strong>$ openssl req -noout -text -in server.csr</strong></code><br />
<br />
</li>
<li>You now have to send this Certificate Signing Request (CSR) to
a Certifying Authority (CA) for signing. The result is then a real
Certificate which can be used for Apache. Here you have two options:
First you can let the CSR sign by a commercial CA like Verisign or
Thawte. Then you usually have to post the CSR into a web form, pay for
the signing and await the signed Certificate you then can store into a
server.crt file. For more information about commercial CAs have a look
at the following locations:<br />
<br />
<ol>
<li> Verisign<br />
<a href="http://digitalid.verisign.com/server/apacheNotice.htm">
http://digitalid.verisign.com/server/apacheNotice.htm
</a>
</li>
<li> Thawte Consulting<br />
<a href="http://www.thawte.com/certs/server/request.html">
http://www.thawte.com/certs/server/request.html
</a>
</li>
<li> CertiSign Certificadora Digital Ltda.<br />
<a href="http://www.certisign.com.br">
http://www.certisign.com.br
</a>
</li>
<li> IKS GmbH<br />
<a href="http://www.iks-jena.de/produkte/ca/">
http://www.iks-jena.de/produkte/ca/
</a>
</li>
<li> Uptime Commerce Ltd.<br />
<a href="http://www.uptimecommerce.com">
http://www.uptimecommerce.com
</a>
</li>
<li> BelSign NV/SA<br />
<a href="http://www.belsign.be">
http://www.belsign.be
</a>
</li>
</ol>
<br />
Second you can use your own CA and now have to sign the CSR yourself by
this CA. Read the next answer in this FAQ on how to sign a CSR with
your CA yourself.
You can see the details of the received Certificate via the command:<br />
<br />
<code><strong>$ openssl x509 -noout -text -in server.crt</strong></code><br />
</li>
<li>Now you have two files: <code>server.key</code> and
<code>server.crt</code>. These now can be used as following inside your
Apache's <code>httpd.conf</code> file:
<pre>
SSLCertificateFile /path/to/this/server.crt
SSLCertificateKeyFile /path/to/this/server.key
</pre>
The <code>server.csr</code> file is no longer needed.
</li>
</ol>
</section>
<section id="ownca"><title>How can I create and use my own Certificate Authority (CA)?</title>
<p>The short answer is to use the <code>CA.sh</code> or <code>CA.pl</code>
script provided by OpenSSL. The long and manual answer is this:</p>
<ol>
<li>Create a RSA private key for your CA
(will be Triple-DES encrypted and PEM formatted):<br />
<br />
<code><strong>$ openssl genrsa -des3 -out ca.key 1024</strong></code><br />
<br />
Please backup this <code>ca.key</code> file and remember the
pass-phrase you currently entered at a secure location.
You can see the details of this RSA private key via the command<br />
<br />
<code><strong>$ openssl rsa -noout -text -in ca.key</strong></code><br />
<br />
And you can create a decrypted PEM version (not recommended) of this
private key via:<br />
<br />
<code><strong>$ openssl rsa -in ca.key -out ca.key.unsecure</strong></code><br />
<br />
</li>
<li>Create a self-signed CA Certificate (X509 structure)
with the RSA key of the CA (output will be PEM formatted):<br />
<br />
<code><strong>$ openssl req -new -x509 -days 365 -key ca.key -out ca.crt</strong></code><br />
<br />
You can see the details of this Certificate via the command:<br />
<br />
<code><strong>$ openssl x509 -noout -text -in ca.crt</strong></code><br />
<br />
</li>
<li>Prepare a script for signing which is needed because
the ``<code>openssl ca</code>'' command has some strange requirements
and the default OpenSSL config doesn't allow one easily to use
``<code>openssl ca</code>'' directly. So a script named
<code>sign.sh</code> is distributed with the mod_ssl distribution
(subdir <code>pkg.contrib/</code>). Use this script for signing.
</li>
<li>Now you can use this CA to sign server CSR's in order to create real
SSL Certificates for use inside an Apache webserver (assuming
you already have a <code>server.csr</code> at hand):<br />
<br />
<code><strong>$ ./sign.sh server.csr</strong></code><br />
<br />
This signs the server CSR and results in a <code>server.crt</code> file.<br />
</li>
</ol>
</section>
<section id="passphrase"><title>How can I change the pass-phrase on my private key file?</title>
<p>You simply have to read it with the old pass-phrase and write it again
by specifying the new pass-phrase. You can accomplish this with the following
commands:</p>
<p><code><strong>$ openssl rsa -des3 -in server.key -out server.key.new</strong></code><br />
<code><strong>$ mv server.key.new server.key</strong></code><br /></p>
<p>Here you're asked two times for a PEM pass-phrase. At the first
prompt enter the old pass-phrase and at the second prompt
enter the new pass-phrase.</p>
</section>
<section id="removepassphrase"><title>How can I get rid of the pass-phrase dialog at Apache startup time?</title>
<p>The reason why this dialog pops up at startup and every re-start
is that the RSA private key inside your server.key file is stored in
encrypted format for security reasons. The pass-phrase is needed to be
able to read and parse this file. When you can be sure that your server is
secure enough you perform two steps:</p>
<ol>
<li>Remove the encryption from the RSA private key (while
preserving the original file):<br />
<br />
<code><strong>$ cp server.key server.key.org</strong></code><br />
<code><strong>$ openssl rsa -in server.key.org -out server.key</strong></code><br />
<br />
</li>
<li>Make sure the server.key file is now only readable by root:<br />
<br />
<code><strong>$ chmod 400 server.key</strong></code><br />
<br />
</li>
</ol>
<p>Now <code>server.key</code> will contain an unencrypted copy of the key.
If you point your server at this file it will not prompt you for a
pass-phrase. HOWEVER, if anyone gets this key they will be able to
impersonate you on the net. PLEASE make sure that the permissions on that
file are really such that only root or the web server user can read it
(preferably get your web server to start as root but run as another
server, and have the key readable only by root).</p>
<p>As an alternative approach you can use the ``<code>SSLPassPhraseDialog
exec:/path/to/program</code>'' facility. But keep in mind that this is
neither more nor less secure, of course.</p>
</section>
<section id="verify"><title>How do I verify that a private key matches its Certificate?</title>
<p>The private key contains a series of numbers. Two of those numbers form
the "public key", the others are part of your "private key". The "public
key" bits are also embedded in your Certificate (we get them from your
CSR). To check that the public key in your cert matches the public
portion of your private key, you need to view the cert and the key and
compare the numbers. To view the Certificate and the key run the
commands:</p>
<p><code><strong>$ openssl x509 -noout -text -in server.crt</strong></code><br />
<code><strong>$ openssl rsa -noout -text -in server.key</strong></code></p>
<p>The `modulus' and the `public exponent' portions in the key and the
Certificate must match. But since the public exponent is usually 65537
and it's bothering comparing long modulus you can use the following
approach:</p>
<p><code><strong>$ openssl x509 -noout -modulus -in server.crt | openssl md5</strong></code><br />
<code><strong>$ openssl rsa -noout -modulus -in server.key | openssl md5</strong></code></p>
<p>And then compare these really shorter numbers. With overwhelming
probability they will differ if the keys are different. BTW, if I want to
check to which key or certificate a particular CSR belongs you can compute</p>
<p><code><strong>$ openssl req -noout -modulus -in server.csr | openssl md5</strong></code></p>
</section>
<section id="badcert"><title>What does it mean when my connections fail with an "alert bad certificate"
error?</title>
<p>Usually when you see errors like <code>OpenSSL: error:14094412: SSL
routines:SSL3_READ_BYTES:sslv3 alert bad certificate</code> in the SSL
logfile, this means that the browser was unable to handle the server
certificate/private-key which perhaps contain a RSA-key not equal to 1024
bits. For instance Netscape Navigator 3.x is one of those browsers.</p>
</section>
<section id="keysize"><title>Why does my 2048-bit private key not work?</title>
<p>The private key sizes for SSL must be either 512 or 1024 for compatibility
with certain web browsers. A keysize of 1024 bits is recommended because
keys larger than 1024 bits are incompatible with some versions of Netscape
Navigator and Microsoft Internet Explorer, and with other browsers that
use RSA's BSAFE cryptography toolkit.</p>
</section>
<section id="hashsymlinks"><title>Why is client authentication broken after upgrading from
SSLeay version 0.8 to 0.9?</title>
<p>The CA certificates under the path you configured with
<code>SSLCACertificatePath</code> are found by SSLeay through hash
symlinks. These hash values are generated by the `<code>openssl x509 -noout
-hash</code>' command. But the algorithm used to calculate the hash for a
certificate has changed between SSLeay 0.8 and 0.9. So you have to remove
all old hash symlinks and re-create new ones after upgrading. Use the
<code>Makefile</code> mod_ssl placed into this directory.</p>
</section>
<section id="pemder"><title>How can I convert a certificate from PEM to DER format?</title>
<p>The default certificate format for SSLeay/OpenSSL is PEM, which actually
is Base64 encoded DER with header and footer lines. For some applications
(e.g. Microsoft Internet Explorer) you need the certificate in plain DER
format. You can convert a PEM file <code>cert.pem</code> into the
corresponding DER file <code>cert.der</code> with the following command:
<code><strong>$ openssl x509 -in cert.pem -out cert.der -outform DER</strong></code></p>
</section>
<section id="verisign"><title>I try to install a Verisign certificate. Why can't I find neither the
<code>getca</code> nor <code>getverisign</code> programs Verisign mentions?</title>
<p>This is because Verisign has never provided specific instructions
for Apache+mod_ssl. Rather they tell you what you should do
if you were using C2Net's Stronghold (a commercial Apache
based server with SSL support). The only thing you have to do
is to save the certificate into a file and give the name of
that file to the <code>SSLCertificateFile</code> directive.
Remember that you need to give the key file in as well (see
<code>SSLCertificateKeyFile</code> directive). For a better
CA-related overview on SSL certificate fiddling you can look at <a
href="http://www.thawte.com/certs/server/keygen/mod_ssl.html">Thawte's mod_ssl instructions</a>.</p>
</section>
<section id="sgc"><title>Can I use the Server Gated Cryptography (SGC) facility (aka Verisign Global
ID) also with mod_ssl?</title>
<p>Yes, mod_ssl since version 2.1 supports the SGC facility. You don't have
to configure anything special for this, just use a Global ID as your
server certificate. The <em>step up</em> of the clients are then
automatically handled by mod_ssl under run-time. For details please read
the <code>README.GlobalID</code> document in the mod_ssl distribution.</p>
</section>
<section id="gid"><title>After I have installed my new Verisign Global ID server certificate, the
browsers complain that they cannot verify the server certificate?</title>
<p>That is because Verisign uses an intermediate CA certificate between
the root CA certificate (which is installed in the browsers) and
the server certificate (which you installed in the server). You
should have received this additional CA certificate from Verisign.
If not, complain to them. Then configure this certificate with the
<code>SSLCertificateChainFile</code> directive in the server. This
makes sure the intermediate CA certificate is send to the browser
and this way fills the gap in the certificate chain.</p>
</section>
</section>
<!-- /certs -->
<section id="aboutssl"><title>About SSL Protocol</title>
<ul>
<li><a href="#random">Random SSL errors under heavy load?</a></li>
<li><a href="#load">Why has the server a higher load?</a></li>
<li><a href="#establishing">Why are connections horribly slow?</a></li>
<li><a href="#ciphers">Which ciphers are supported?</a></li>
<li><a href="#adh">How to use Anonymous-DH ciphers</a></li>
<li><a href="#sharedciphers">Why do I get 'no shared ciphers'?</a></li>
<li><a href="#vhosts">HTTPS and name-based vhosts</a></li>
<li><a href="#lockicon">The lock icon in Netscape locks very late</a></li>
<li><a href="#msie">Why do I get I/O errors with MSIE clients?</a></li>
<li><a href="#nn">Why do I get I/O errors with NS clients?</a></li>
</ul>
<section id="random"><title>Why do I get lots of random SSL protocol errors under heavy server load?</title>
<p>There can be a number of reasons for this, but the main one
is problems with the SSL session Cache specified by the
<directive module="mod_ssl">SSLSessionCache</directive> directive. The DBM session
cache is most likely the source of the problem, so trying the SHM session cache or
no cache at all may help.</p>
</section>
<section id="load"><title>Why has my webserver a higher load now that I run SSL there?</title>
<p>Because SSL uses strong cryptographic encryption and this needs a lot of
number crunching. And because when you request a webpage via HTTPS even
the images are transfered encrypted. So, when you have a lot of HTTPS
traffic the load increases.</p>
</section>
<section id="establishing"><title>Often HTTPS connections to my server require up to 30 seconds for establishing
the connection, although sometimes it works faster?</title>
<p>Usually this is caused by using a <code>/dev/random</code> device for
<code>SSLRandomSeed</code> which is blocking in read(2) calls if not
enough entropy is available. Read more about this problem in the refernce
chapter under <code>SSLRandomSeed</code>.</p>
</section>
<section id="ciphers"><title>What SSL Ciphers are supported by mod_ssl?</title>
<p>Usually just all SSL ciphers which are supported by the
version of OpenSSL in use (can depend on the way you built
OpenSSL). Typically this at least includes the following:</p>
<ol>
<li>RC4 with MD5</li>
<li>RC4 with MD5 (export version restricted to 40-bit key)</li>
<li>RC2 with MD5</li>
<li>RC2 with MD5 (export version restricted to 40-bit key)</li>
<li>IDEA with MD5</li>
<li>DES with MD5</li>
<li>Triple-DES with MD5</li>
</ol>
<p>To determine the actual list of supported ciphers you can
run the following command:</p>
<example>$ openssl ciphers -v</example>
</section>
<section id="adh"><title>I want to use Anonymous Diffie-Hellman (ADH) ciphers, but I always get ``no
shared cipher'' errors?</title>
<p>In order to use Anonymous Diffie-Hellman (ADH) ciphers, it is not enough
to just put ``<code>ADH</code>'' into your <code>SSLCipherSuite</code>.
Additionally you have to build OpenSSL with
``<code>-DSSL_ALLOW_ADH</code>''. Because per default OpenSSL does not
allow ADH ciphers for security reasons. So if you are actually enabling
these ciphers make sure you are informed about the side-effects.</p>
</section>
<section id="sharedciphers"><title>I always just get a 'no shared ciphers' error if
I try to connect to my freshly installed server?</title>
<p>Either you have messed up your <code>SSLCipherSuite</code>
directive (compare it with the pre-configured example in
<code>httpd.conf-dist</code>) or you have choosen the DSA/DH
algorithms instead of RSA when you generated your private key
and ignored or overlooked the warnings. If you have choosen
DSA/DH, then your server no longer speaks RSA-based SSL ciphers
(at least not until you also configure an additional RSA-based
certificate/key pair). But current browsers like NS or IE only speak
RSA ciphers. The result is the "no shared ciphers" error. To fix
this, regenerate your server certificate/key pair and this time
choose the RSA algorithm.</p>
</section>
<section id="vhosts"><title>Why can't I use SSL with name-based/non-IP-based virtual hosts?</title>
<p>The reason is very technical. Actually it's some sort of a chicken and
egg problem: The SSL protocol layer stays below the HTTP protocol layer
and encapsulates HTTP. When an SSL connection (HTTPS) is established
Apache/mod_ssl has to negotiate the SSL protocol parameters with the
client. For this mod_ssl has to consult the configuration of the virtual
server (for instance it has to look for the cipher suite, the server
certificate, etc.). But in order to dispatch to the correct virtual server
Apache has to know the <code>Host</code> HTTP header field. For this the
HTTP request header has to be read. This cannot be done before the SSL
handshake is finished. But the information is already needed at the SSL
handshake phase. Bingo!</p>
</section>
<section id="lockicon"><title>When I use Basic Authentication over HTTPS the lock icon in Netscape browsers
still shows the unlocked state when the dialog pops up. Does this mean the
username/password is still transmitted unencrypted?</title>
<p>No, the username/password is already transmitted encrypted. The icon in
Netscape browsers is just not really synchronized with the SSL/TLS layer
(it toggles to the locked state when the first part of the actual webpage
data is transferred which is not quite correct) and this way confuses
people. The Basic Authentication facility is part of the HTTP layer and
this layer is above the SSL/TLS layer in HTTPS. And before any HTTP data
communication takes place in HTTPS the SSL/TLS layer has already done the
handshake phase and switched to encrypted communication. So, don't get
confused by this icon.</p>
</section>
<section id="msie"><title>When I connect via HTTPS to an Apache+mod_ssl+OpenSSL server with Microsoft Internet
Explorer (MSIE) I get various I/O errors. What is the reason?</title>
<p>The first reason is that the SSL implementation in some MSIE versions has
some subtle bugs related to the HTTP keep-alive facility and the SSL close
notify alerts on socket connection close. Additionally the interaction
between SSL and HTTP/1.1 features are problematic with some MSIE versions,
too. You've to work-around these problems by forcing
Apache+mod_ssl+OpenSSL to not use HTTP/1.1, keep-alive connections or
sending the SSL close notify messages to MSIE clients. This can be done by
using the following directive in your SSL-aware virtual host section:</p>
<example>
SetEnvIf User-Agent ".*MSIE.*" \<br />
nokeepalive ssl-unclean-shutdown \<br />
downgrade-1.0 force-response-1.0
</example>
<p>Additionally it is known some MSIE versions have also problems
with particular ciphers. Unfortunately one cannot workaround these
bugs only for those MSIE particular clients, because the ciphers
are already used in the SSL handshake phase. So a MSIE-specific
<directive module="mod_setenvif">SetEnvIf</directive> doesn't work
to solve these problems. Instead one has to do more drastic
adjustments to the global parameters. But before you decide to do
this, make sure your clients really have problems. If not, do not
do this, because it affects all(!) your clients, i.e., also your
non-MSIE clients.</p>
<p>The next problem is that 56bit export versions of MSIE 5.x browsers have a
broken SSLv3 implementation which badly interacts with OpenSSL versions
greater than 0.9.4. You can either accept this and force your clients to
upgrade their browsers, or you downgrade to OpenSSL 0.9.4 (hmmm), or you
can decide to workaround it by accepting the drawback that your workaround
will horribly affect also other browsers:</p>
<example>SSLProtocol all -SSLv3</example>
<p>This completely disables the SSLv3 protocol and lets those browsers work.
But usually this is an even less acceptable workaround. A more reasonable
workaround is to address the problem more closely and disable only the
ciphers which cause trouble.</p>
<example><p><code>SSLCipherSuite
ALL:!ADH:<strong>!EXPORT56</strong>:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP</code>
</p></example>
<p>This also lets the broken MSIE versions work, but only removes the
newer 56bit TLS ciphers.</p>
<p>Another problem with MSIE 5.x clients is that they refuse to connect to
URLs of the form <code>https://12.34.56.78/</code> (IP-addresses are used
instead of the hostname), if the server is using the Server Gated
Cryptography (SGC) facility. This can only be avoided by using the fully
qualified domain name (FQDN) of the website in hyperlinks instead, because
MSIE 5.x has an error in the way it handles the SGC negotiation.</p>
<p>And finally there are versions of MSIE which seem to require that
an SSL session can be reused (a totally non standard-conforming
behaviour, of course). Connection with those MSIE versions only work
if a SSL session cache is used. So, as a work-around, make sure you
are using a session cache (see <directive module="mod_ssl"
>SSLSessionCache</directive> directive).</p>
</section>
<section id="nn"><title>When I connect via HTTPS to an Apache+mod_ssl server with Netscape Navigator I
get I/O errors and the message "Netscape has encountered bad data from the
server" What's the reason?</title>
<p>
The problem usually is that you had created a new server certificate with
the same DN, but you had told your browser to accept forever the old
server certificate. Once you clear the entry in your browser for the old
certificate, everything usually will work fine. Netscape's SSL
implementation is correct, so when you encounter I/O errors with Netscape
Navigator it is most of the time caused by the configured certificates.</p>
</section>
</section>
<!-- /aboutssl -->
<section id="support"><title>About Support</title>
<ul>
<li><a href="#resources">Resources in case of problems?</a></li>
<li><a href="#contact">Support in case of problems?</a></li>
<li><a href="#reportdetails">How to write a problem report?</a></li>
<li><a href="#coredumphelp">I got a core dump, can you help me?</a></li>
<li><a href="#backtrace">How to get a backtrace?</a></li>
</ul>
<section id="resources"><title>What information resources are available in case of mod_ssl problems?</title>
<p>The following information resources are available.
In case of problems you should search here first.</p>
<dl>
<dt>Answers in the User Manual's F.A.Q. List (this)</dt>
<dd><a href="http://httpd.apache.org/docs-2.0/ssl/ssl_faq.html">
http://httpd.apache.org/docs-2.0/ssl/ssl_faq.html</a><br />
First look inside the F.A.Q. (this text), perhaps your problem is such
popular that it was already answered a lot of times in the past.
</dd>
<dt>Postings from the modssl-users Support Mailing List
<a href="http://www.modssl.org/support/">
http://www.modssl.org/support/</a></dt>
<dd>Second search for your problem in one of the existing archives of the
modssl-users mailing list. Perhaps your problem popped up at least once for
another user, too.
</dd>
<dt>Problem Reports in the Bug Database
<a href="http://www.modssl.org/support/bugdb/">
http://www.modssl.org/support/bugdb/</a></dt>
<dd>Third look inside the mod_ssl Bug Database. Perhaps
someone else already has reported the problem.
</dd>
</dl>
</section>
<section id="contact"><title>What support contacts are available in case of mod_ssl problems?</title>
<p>The following lists all support possibilities for mod_ssl, in order of
preference, i.e. start in this order and do not pick the support possibility
you just like most, please.</p>
<ol>
<li><em>Write a Problem Report into the Bug Database</em><br />
<a href="http://www.modssl.org/support/bugdb/">
http://www.modssl.org/support/bugdb/</a><br />
This is the preferred way of submitting your problem report, because this
way it gets filed into the bug database (it cannot be lost) <em>and</em>
send to the modssl-users mailing list (others see the current problems and
learn from answers).
</li>
<li><em>Write a Problem Report to the modssl-users Support Mailing List</em><br />
<a href="mailto:modssl-users@modssl.org">
modssl-users@modssl.org</a><br />
This is the second way of submitting your problem report. You have to
subscribe to the list first, but then you can easily discuss your problem
with both the author and the whole mod_ssl user community.
</li>
<li><em>Write a Problem Report to the author</em><br />
<a href="mailto:rse@engelschall.com">rse@engelschall.com</a><br />
This is the last way of submitting your problem report. Please avoid this
in your own interest because the author is really a very busy men. Your
mail will always be filed to one of his various mail-folders and is
usually not processed as fast as a posting on modssl-users.
</li>
</ol>
</section>
<section id="reportdetails"><title>What information and details I've to provide to
the author when writing a bug report?</title>
<p>You have to at least always provide the following information:</p>
<dl>
<dt>Apache, mod_ssl and OpenSSL version information</dt>
<dd>The mod_ssl version you should really know. For instance, it's the version
number in the distribution tarball. The Apache version can be determined
by running ``<code>httpd -v</code>''. The OpenSSL version can be
determined by running ``<code>openssl version</code>''. Alternatively when
you have Lynx installed you can run the command ``<code>lynx -mime_header
http://localhost/ | grep Server</code>'' to determine all information in a
single step.
</dd>
<dt>The details on how you built and installed Apache+mod_ssl+OpenSSL</dt>
<dd>For this you can provide a logfile of your terminal session which shows
the configuration and install steps. Alternatively you can at least
provide the author with the APACI <code>configure</code> command line
you used (assuming you used APACI, of course).
</dd>
<dt>In case of core dumps please include a Backtrace</dt>
<dd>In case your Apache+mod_ssl+OpenSSL should really dumped core please attach
a stack-frame ``backtrace'' (see the next question on how to get it).
Without this information the reason for your core dump cannot be found.
So you have to provide the backtrace, please.
</dd>
<dt>A detailed description of your problem</dt>
<dd>Don't laugh, I'm totally serious. I already got a lot of problem reports
where the people not really said what's the actual problem is. So, in your
own interest (you want the problem be solved, don't you?) include as much
details as possible, please. But start with the essentials first, of
course.
</dd>
</dl>
</section>
<section id="coredumphelp"><title>I got a core dump, can you help me?</title>
<p>In general no, at least not unless you provide more details about the code
location where Apache dumped core. What is usually always required in
order to help you is a backtrace (see next question). Without this
information it is mostly impossible to find the problem and help you in
fixing it.</p>
</section>
<section id="backtrace"><title>Ok, I got a core dump but how do I get a backtrace to find out the reason for it?</title>
<p>Follow the following steps:</p>
<ol>
<li>Make sure you have debugging symbols available in at least
Apache and mod_ssl. On platforms where you use GCC/GDB you have to build
Apache+mod_ssl with ``<code>OPTIM="-g -ggdb3"</code>'' to achieve this. On
other platforms at least ``<code>OPTIM="-g"</code>'' is needed.
</li>
<li>Startup the server and try to produce the core-dump. For this you perhaps
want to use a directive like ``<code>CoreDumpDirectory /tmp</code>'' to
make sure that the core-dump file can be written. You then should get a
<code>/tmp/core</code> or <code>/tmp/httpd.core</code> file. When you
don't get this, try to run your server under an UID != 0 (root), because
most "current" kernels do not allow a process to dump core after it has
done a <code>setuid()</code> (unless it does an <code>exec()</code>) for
security reasons (there can be privileged information left over in
memory). Additionally you can run ``<code>/path/to/httpd -X</code>''
manually to force Apache to not fork.
</li>
<li>Analyze the core-dump. For this run <code>gdb /path/to/httpd
/tmp/httpd.core</code> or a similar command has to run. In GDB you then
just have to enter the <code>bt</code> command and, voila, you get the
backtrace. For other debuggers consult your local debugger manual. Send
this backtrace to the author.
</li>
</ol>
</section>
</section>
</manualpage>