docs/manual/ssl/ssl_compat.wml

#use "ssl_template.inc" title="Compatibility" tag=compat num=4

<page_prev name="Reference"   url="ssl_reference.html">
<page_next name="HowTo"       url="ssl_howto.html">

#use wml::std::toc style=nbsp

<quotation width=200 author="Unknown">
All PCs are compatible. But some of
them are more compatible than others.
</quotation>

<p>
<table cellspacing=0 cellpadding=0 border=0>
<tr valign=bottom>
<td>

<big H>ere 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).

</td>
<td>
&nbsp;&nbsp;
</td>
<td>

<div align=right>
<table cellspacing=0 cellpadding=5 border=0 bgcolor="#ccccff">
<tr>
<td bgcolor="#333399">
<font face="Arial,Helvetica" color="#ccccff">
<b>Table Of Contents</b>
</font>
</td>
</tr>
<tr>
<td>
<font face="Arial,Helvetica" size=-1>
<toc>
</font>
</td>
</tr>
</table>
</div>

</td>
</tr>
</table>

<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.

<h2>Configuration Directives</h2>

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>
<float name="table1" caption="Table 1: Configuration Directive Mapping">
<table border=0 cellspacing=0 cellpadding=2 width=598>
<tr id=D>
<td><strong>Old Directive</strong></td>
<td><strong>mod_ssl Directive</strong></td>
<td><strong>Comment</strong></td>
</tr>
<tr id=H><td colspan=3><b>Apache-SSL 1.x &amp; mod_ssl 2.0.x compatibility:</b></td></tr>
<tr id=D><td><code>SSLEnable</code></td><td><code>SSLEngine on</code></td><td>compactified</td></tr>
<tr id=H><td><code>SSLDisable</code></td><td><code>SSLEngine off</code></td><td>compactified</td></tr>
<tr id=D><td><code>SSLLogFile</code> <em>file</em></td><td><code>SSLLog</code> <em>file</em></td><td>compactified</td></tr>
<tr id=H><td><code>SSLRequiredCiphers</code> <em>spec</em></td><td><code>SSLCipherSuite</code> <em>spec</em></td><td>renamed</td></tr>
<tr id=D><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 id=H><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 id=D><td><code>SSLFakeBasicAuth</td><td><code>SSLOptions +FakeBasicAuth</code></td><td>merged</td></tr>
<tr id=H><td><code>SSLCacheServerPath</code> <em>dir</em></td><td>-</td><td>functionality removed</td></tr>
<tr id=D><td><code>SSLCacheServerPort</code> <em>integer</em></td><td>-</td><td>functionality removed</td></tr>

<tr id=H><td colspan=3><b>Apache-SSL 1.x compatibility:</b></td></tr>
<tr id=D><td><code>SSLExportClientCertificates</td><td><code>SSLOptions +ExportCertData</code></td><td>merged</td></tr>
<tr id=H><td><code>SSLCacheServerRunDir</code> <em>dir</em></td><td>-</td><td>functionality not supported</td></tr>

<tr id=D><td colspan=3><b>Sioux 1.x compatibility:</b></td></tr>
<tr id=H><td><code>SSL_CertFile</code> <em>file</em></td><td><code>SSLCertificateFile</code> <em>file</em></td><td>renamed</td></tr>
<tr id=D><td><code>SSL_KeyFile</code> <em>file</em></td><td><code>SSLCertificateKeyFile</code> <em>file</em></td><td>renamed</td></tr>
<tr id=H><td><code>SSL_CipherSuite</code> <em>arg</em></td><td><code>SSLCipherSuite</code> <em>arg</em></td><td>renamed</td></tr>
<tr id=D><td><code>SSL_X509VerifyDir</code> <em>arg</em></td><td><code>SSLCACertificatePath</code> <em>arg</em></td><td>renamed</td></tr>
<tr id=H><td><code>SSL_Log</code> <em>file</em></td><td><code>SSLLogFile</code> <em>file</em></td><td>renamed</td></tr>
<tr id=D><td><code>SSL_Connect</code> <em>flag</em></td><td><code>SSLEngine</code> <em>flag</em></td><td>renamed</td></tr>
<tr id=H><td><code>SSL_ClientAuth</code> <em>arg</em></td><td><code>SSLVerifyClient</code> <em>arg</em></td><td>renamed</td></tr>
<tr id=D><td><code>SSL_X509VerifyDepth</code> <em>arg</em></td><td><code>SSLVerifyDepth</code> <em>arg</em></td><td>renamed</td></tr>
<tr id=H><td><code>SSL_FetchKeyPhraseFrom</code> <em>arg</em></td><td>-</td><td>not directly mappable; use SSLPassPhraseDialog</td></tr>
<tr id=D><td><code>SSL_SessionDir</code> <em>dir</em></td><td>-</td><td>not directly mappable; use SSLSessionCache</td></tr>
<tr id=H><td><code>SSL_Require</code> <em>expr</em></td><td>-</td><td>not directly mappable; use SSLRequire</td></tr>
<tr id=D><td><code>SSL_CertFileType</code> <em>arg</em></td><td>-</td><td>functionality not supported</td></tr>
<tr id=H><td><code>SSL_KeyFileType</code> <em>arg</em></td><td>-</td><td>functionality not supported</td></tr>
<tr id=D><td><code>SSL_X509VerifyPolicy</code> <em>arg</em></td><td>-</td><td>functionality not supported</td></tr>
<tr id=H><td><code>SSL_LogX509Attributes</code> <em>arg</em></td><td>-</td><td>functionality not supported</td></tr>

<tr id=D><td colspan=3><b>Stronghold 2.x compatibility:</b></td></tr>
<tr id=H><td><code>StrongholdAccelerator</code> <em>dir</em></td><td>-</td><td>functionality not supported</td></tr>
<tr id=H><td><code>StrongholdKey</code> <em>dir</em></td><td>-</td><td>functionality not supported</td></tr>
<tr id=H><td><code>StrongholdLicenseFile</code> <em>dir</em></td><td>-</td><td>functionality not supported</td></tr>
<tr id=H><td><code>SSLFlag</code> <em>flag</em></td><td><code>SSLEngine</code> <em>flag</em></td><td>renamed</td></tr>
<tr id=D><td><code>SSLSessionLockFile</code> <em>file</em></td><td><code>SSLMutex</code> <em>file</em></td><td>renamed</td></tr>
<tr id=H><td><code>SSLCipherList</code> <em>spec</em></td><td><code>SSLCipherSuite</code> <em>spec</em></td><td>renamed</td></tr>
<tr id=D><td><code>RequireSSL</code></td><td><code>SSLRequireSSL</code></td><td>renamed</td></tr>
<tr id=H><td><code>SSLErrorFile</code> <em>file</em></td><td>-</td><td>functionality not supported</td></tr>
<tr id=H><td><code>SSLRoot</code> <em>dir</em></td><td>-</td><td>functionality not supported</td></tr>
<tr id=D><td><code>SSL_CertificateLogDir</code> <em>dir</em></td><td>-</td><td>functionality not supported</td></tr>
<tr id=H><td><code>AuthCertDir</code> <em>dir</em></td><td>-</td><td>functionality not supported</td></tr>
<tr id=D><td><code>SSL_Group</code> <em>name</em></td><td>-</td><td>functionality not supported</td></tr>
<tr id=H><td><code>SSLProxyMachineCertPath</code> <em>dir</em></td><td>-</td><td>functionality not supported</td></tr>
<tr id=D><td><code>SSLProxyMachineCertFile</code> <em>file</em></td><td>-</td><td>functionality not supported</td></tr>
<tr id=H><td><code>SSLProxyCACertificatePath</code> <em>dir</em></td><td>-</td><td>functionality not supported</td></tr>
<tr id=D><td><code>SSLProxyCACertificateFile</code> <em>file</em></td><td>-</td><td>functionality not supported</td></tr>
<tr id=H><td><code>SSLProxyVerifyDepth</code> <em>number</em></td><td>-</td><td>functionality not supported</td></tr>
<tr id=D><td><code>SSLProxyCipherList</code> <em>spec</em></td><td>-</td><td>functionality not supported</td></tr>
</table>
</float>

<p>
<br>
<h2>Environment Variables</h2>

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>
<float name="table2" caption="Table 2: Environment Variable Derivation">
<table border=0 cellspacing=0 cellpadding=2 width=598>
<tr id=D>
<td><strong>Old Variable</strong></td>
<td><strong>mod_ssl Variable</strong></td>
<td><strong>Comment</strong></td>
</tr>
<tr id=H><td><code>SSL_PROTOCOL_VERSION</code></td><td><code>SSL_PROTOCOL</code></td><td>renamed</td></tr>
<tr id=D><td><code>SSLEAY_VERSION</code></td><td><code>SSL_VERSION_LIBRARY</code></td><td>renamed</td></tr>
<tr id=H><td><code>HTTPS_SECRETKEYSIZE</code></td><td><code>SSL_CIPHER_USEKEYSIZE</code></td><td>renamed</td></tr>
<tr id=D><td><code>HTTPS_KEYSIZE</code></td><td><code>SSL_CIPHER_ALGKEYSIZE</code></td><td>renamed</td></tr>
<tr id=H><td><code>HTTPS_CIPHER</code></td><td><code>SSL_CIPHER</code></td><td>renamed</td></tr>
<tr id=D><td><code>HTTPS_EXPORT</code></td><td><code>SSL_CIPHER_EXPORT</code></td><td>renamed</td></tr>
<tr id=H><td><code>SSL_SERVER_KEY_SIZE</code></td><td><code>SSL_CIPHER_ALGKEYSIZE</code></td><td>renamed</td></tr>
<tr id=D><td><code>SSL_SERVER_CERTIFICATE</code></td><td><code>SSL_SERVER_CERT</code></td><td>renamed</td></tr>
<tr id=H><td><code>SSL_SERVER_CERT_START</code></td><td><code>SSL_SERVER_V_START</code></td><td>renamed</td></tr>
<tr id=D><td><code>SSL_SERVER_CERT_END</code></td><td><code>SSL_SERVER_V_END</code></td><td>renamed</td></tr>
<tr id=H><td><code>SSL_SERVER_CERT_SERIAL</code></td><td><code>SSL_SERVER_M_SERIAL</code></td><td>renamed</td></tr>
<tr id=H><td><code>SSL_SERVER_SIGNATURE_ALGORITHM</code></td><td><code>SSL_SERVER_A_SIG</code></td><td>renamed</td></tr>
<tr id=H><td><code>SSL_SERVER_DN</code></td><td><code>SSL_SERVER_S_DN</code></td><td>renamed</td></tr>
<tr id=H><td><code>SSL_SERVER_CN</code></td><td><code>SSL_SERVER_S_DN_CN</code></td><td>renamed</td></tr>
<tr id=D><td><code>SSL_SERVER_EMAIL</code></td><td><code>SSL_SERVER_S_DN_Email</code></td><td>renamed</td></tr>
<tr id=H><td><code>SSL_SERVER_O</code></td><td><code>SSL_SERVER_S_DN_O</code></td><td>renamed</td></tr>
<tr id=D><td><code>SSL_SERVER_OU</code></td><td><code>SSL_SERVER_S_DN_OU</code></td><td>renamed</td></tr>
<tr id=H><td><code>SSL_SERVER_C</code></td><td><code>SSL_SERVER_S_DN_C</code></td><td>renamed</td></tr>
<tr id=D><td><code>SSL_SERVER_SP</code></td><td><code>SSL_SERVER_S_DN_SP</code></td><td>renamed</td></tr>
<tr id=H><td><code>SSL_SERVER_L</code></td><td><code>SSL_SERVER_S_DN_L</code></td><td>renamed</td></tr>
<tr id=H><td><code>SSL_SERVER_IDN</code></td><td><code>SSL_SERVER_I_DN</code></td><td>renamed</td></tr>
<tr id=D><td><code>SSL_SERVER_ICN</code></td><td><code>SSL_SERVER_I_DN_CN</code></td><td>renamed</td></tr>
<tr id=H><td><code>SSL_SERVER_IEMAIL</code></td><td><code>SSL_SERVER_I_DN_Email</code></td><td>renamed</td></tr>
<tr id=D><td><code>SSL_SERVER_IO</code></td><td><code>SSL_SERVER_I_DN_O</code></td><td>renamed</td></tr>
<tr id=H><td><code>SSL_SERVER_IOU</code></td><td><code>SSL_SERVER_I_DN_OU</code></td><td>renamed</td></tr>
<tr id=D><td><code>SSL_SERVER_IC</code></td><td><code>SSL_SERVER_I_DN_C</code></td><td>renamed</td></tr>
<tr id=H><td><code>SSL_SERVER_ISP</code></td><td><code>SSL_SERVER_I_DN_SP</code></td><td>renamed</td></tr>
<tr id=D><td><code>SSL_SERVER_IL</code></td><td><code>SSL_SERVER_I_DN_L</code></td><td>renamed</td></tr>
<tr id=H><td><code>SSL_CLIENT_CERTIFICATE</code></td><td><code>SSL_CLIENT_CERT</code></td><td>renamed</td></tr>
<tr id=D><td><code>SSL_CLIENT_CERT_START</code></td><td><code>SSL_CLIENT_V_START</code></td><td>renamed</td></tr>
<tr id=H><td><code>SSL_CLIENT_CERT_END</code></td><td><code>SSL_CLIENT_V_END</code></td><td>renamed</td></tr>
<tr id=H><td><code>SSL_CLIENT_CERT_SERIAL</code></td><td><code>SSL_CLIENT_M_SERIAL</code></td><td>renamed</td></tr>
<tr id=H><td><code>SSL_CLIENT_SIGNATURE_ALGORITHM</code></td><td><code>SSL_CLIENT_A_SIG</code></td><td>renamed</td></tr>
<tr id=D><td><code>SSL_CLIENT_DN</code></td><td><code>SSL_CLIENT_S_DN</code></td><td>renamed</td></tr>
<tr id=D><td><code>SSL_CLIENT_CN</code></td><td><code>SSL_CLIENT_S_DN_CN</code></td><td>renamed</td></tr>
<tr id=H><td><code>SSL_CLIENT_EMAIL</code></td><td><code>SSL_CLIENT_S_DN_Email</code></td><td>renamed</td></tr>
<tr id=D><td><code>SSL_CLIENT_O</code></td><td><code>SSL_CLIENT_S_DN_O</code></td><td>renamed</td></tr>
<tr id=H><td><code>SSL_CLIENT_OU</code></td><td><code>SSL_CLIENT_S_DN_OU</code></td><td>renamed</td></tr>
<tr id=D><td><code>SSL_CLIENT_C</code></td><td><code>SSL_CLIENT_S_DN_C</code></td><td>renamed</td></tr>
<tr id=H><td><code>SSL_CLIENT_SP</code></td><td><code>SSL_CLIENT_S_DN_SP</code></td><td>renamed</td></tr>
<tr id=D><td><code>SSL_CLIENT_L</code></td><td><code>SSL_CLIENT_S_DN_L</code></td><td>renamed</td></tr>
<tr id=D><td><code>SSL_CLIENT_IDN</code></td><td><code>SSL_CLIENT_I_DN</code></td><td>renamed</td></tr>
<tr id=H><td><code>SSL_CLIENT_ICN</code></td><td><code>SSL_CLIENT_I_DN_CN</code></td><td>renamed</td></tr>
<tr id=D><td><code>SSL_CLIENT_IEMAIL</code></td><td><code>SSL_CLIENT_I_DN_Email</code></td><td>renamed</td></tr>
<tr id=H><td><code>SSL_CLIENT_IO</code></td><td><code>SSL_CLIENT_I_DN_O</code></td><td>renamed</td></tr>
<tr id=D><td><code>SSL_CLIENT_IOU</code></td><td><code>SSL_CLIENT_I_DN_OU</code></td><td>renamed</td></tr>
<tr id=H><td><code>SSL_CLIENT_IC</code></td><td><code>SSL_CLIENT_I_DN_C</code></td><td>renamed</td></tr>
<tr id=D><td><code>SSL_CLIENT_ISP</code></td><td><code>SSL_CLIENT_I_DN_SP</code></td><td>renamed</td></tr>
<tr id=H><td><code>SSL_CLIENT_IL</code></td><td><code>SSL_CLIENT_I_DN_L</code></td><td>renamed</td></tr>
<tr id=H><td><code>SSL_EXPORT</code></td><td><code>SSL_CIPHER_EXPORT</code></td><td>renamed</td></tr>
<tr id=H><td><code>SSL_KEYSIZE</code></td><td><code>SSL_CIPHER_ALGKEYSIZE</code></td><td>renamed</td></tr>
<tr id=H><td><code>SSL_SECKEYSIZE</code></td><td><code>SSL_CIPHER_USEKEYSIZE</code></td><td>renamed</td></tr>
<tr id=H><td><code>SSL_SSLEAY_VERSION</code></td><td><code>SSL_VERSION_LIBRARY</code></td><td>renamed</td></tr>
<tr id=D><td><code>SSL_STRONG_CRYPTO</code></td><td><code>-</code></td><td>Not supported by mod_ssl</td></tr>
<tr id=D><td><code>SSL_SERVER_KEY_EXP</code></td><td><code>-</code></td><td>Not supported by mod_ssl</td></tr>
<tr id=H><td><code>SSL_SERVER_KEY_ALGORITHM</code></td><td><code>-</code></td><td>Not supported by mod_ssl</td></tr>
<tr id=D><td><code>SSL_SERVER_KEY_SIZE</code></td><td><code>-</code></td><td>Not supported by mod_ssl</td></tr>
<tr id=H><td><code>SSL_SERVER_SESSIONDIR</code></td><td><code>-</code></td><td>Not supported by mod_ssl</td></tr>
<tr id=D><td><code>SSL_SERVER_CERTIFICATELOGDIR</code></td><td><code>-</code></td><td>Not supported by mod_ssl</td></tr>
<tr id=H><td><code>SSL_SERVER_CERTFILE</code></td><td><code>-</code></td><td>Not supported by mod_ssl</td></tr>
<tr id=D><td><code>SSL_SERVER_KEYFILE</code></td><td><code>-</code></td><td>Not supported by mod_ssl</td></tr>
<tr id=H><td><code>SSL_SERVER_KEYFILETYPE</code></td><td><code>-</code></td><td>Not supported by mod_ssl</td></tr>
<tr id=D><td><code>SSL_CLIENT_KEY_EXP</code></td><td><code>-</code></td><td>Not supported by mod_ssl</td></tr>
<tr id=H><td><code>SSL_CLIENT_KEY_ALGORITHM</code></td><td><code>-</code></td><td>Not supported by mod_ssl</td></tr>
<tr id=D><td><code>SSL_CLIENT_KEY_SIZE</code></td><td><code>-</code></td><td>Not supported by mod_ssl</td></tr>
</table>
</float>

<p>
<br>
<h2>Custom Log Functions</h2>

When mod_ssl is built into Apache or at least loaded (under DSO situation)
additional functions exist for the <a
href="../mod_log_config.html#formats">Custom Log Format</a> of <a
href="../mod_log_config.html">mod_log_config</a> 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>
<float name="table3" caption="Table 3: Custom Log Cryptography Function">
<table border=0 cellspacing=0 cellpadding=2 width=598>
<tr id=H>
 <td><strong>Function Call</strong></td>
 <td><strong>Description</strong></td>
</tr>
<tr id=D><td><code>%...{version}c</code></td>   <td>SSL protocol version</td></tr>
<tr id=H><td><code>%...{cipher}c</code></td>    <td>SSL cipher</td></tr>
<tr id=D><td><code>%...{subjectdn}c</code></td> <td>Client Certificate Subject Distinguished Name</td></tr>
<tr id=H><td><code>%...{issuerdn}c</code></td>  <td>Client Certificate Issuer  Distinguished Name</td></tr>
<tr id=D><td><code>%...{errcode}c</code></td>   <td>Certificate Verification Error (numerical)</td></tr>
<tr id=H><td><code>%...{errstr}c</code></td>    <td>Certificate Verification Error (string)</td></tr>
</table>
</float>