granicus.if.org Git - apache/blob - docs/manual/ssl/ssl_compat.xml

   1 <?xml version='1.0' encoding='UTF-8' ?>
   2 <!DOCTYPE manualpage SYSTEM "../style/manualpage.dtd">
   3 <?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
   4 <!-- $LastChangedRevision$ -->
   5
   6 <!--
   7  Copyright 2002-2005 The Apache Software Foundation or its licensors, as
   8  applicable.
   9
  10  Licensed under the Apache License, Version 2.0 (the "License");
  11  you may not use this file except in compliance with the License.
  12  You may obtain a copy of the License at
  13
  14      http://www.apache.org/licenses/LICENSE-2.0
  15
  16  Unless required by applicable law or agreed to in writing, software
  17  distributed under the License is distributed on an "AS IS" BASIS,
  18  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  19  See the License for the specific language governing permissions and
  20  limitations under the License.
  21 -->
  22
  23 <manualpage metafile="ssl_compat.xml.meta">
  24 <parentdocument href="./">SSL/TLS</parentdocument>
  25
  26   <title>SSL/TLS Strong Encryption: Compatibility</title>
  27
  28 <summary>
  29 <blockquote>
  30 <p>All PCs are compatible. But some of
  31 them are more compatible than others.</p>
  32 <p class="cite">-- <cite>Unknown</cite></p>
  33 </blockquote>
  34
  35 <p>
  36 This page covers backwards compatibility between mod_ssl and other
  37 SSL solutions.  mod_ssl is not the only SSL solution for Apache; four
  38 additional products are (or were) also available: Ben Laurie's freely
  39 available <a href="http://www.apache-ssl.org/">Apache-SSL</a> (from
  40 where mod_ssl were originally derived in 1998), Red Hat's commercial
  41 <a
  42 href="http://www.redhat.com/products/product-details.phtml?id=rhsa">Secure
  43 Web Server</a> (which was based on mod_ssl), Covalent's commercial <a
  44 href="http://www.covalent.net/">Raven SSL Module</a> (also based on
  45 mod_ssl) and finally C2Net's (now Red Hat's) commercial product <a
  46 href="http://www.redhat.com/explore/stronghold/">Stronghold</a> (based
  47 on a different evolution branch named Sioux up to Stronghold 2.x and
  48 based on mod_ssl since Stronghold 3.x).</p>
  49
  50 <p>
  51 mod_ssl mostly provides a superset of the functionality of all the other
  52 solutions, so it's simple to migrate from one of the older modules to
  53 mod_ssl. The configuration directives and environment variable names
  54 used by the older SSL solutions vary from those used in mod_ssl;
  55 mapping tables are included here to give the equivalents used by mod_ssl.</p>
  56 </summary>
  57
  58 <section id="configuration"><title>Configuration Directives</title>
  59 <p>The mapping between configuration directives used by Apache-SSL
  60 1.x and mod_ssl 2.0.x is given in <a href="#table1">Table
  61 1</a>. The mapping from Sioux 1.x and Stronghold 2.x is only partial
  62 because of special functionality in these interfaces which mod_ssl
  63 doesn't provide.</p>
  64
  65
  66 <section id="table1">
  67 <title>Table 1: Configuration Directive Mapping</title>
  68 <table style="zebra">
  69 <columnspec><column width=".32"/><column width=".32"/>
  70 <column width=".32"/></columnspec>
  71 <tr><th>Old Directive</th><th>mod_ssl Directive</th><th>Comment</th></tr>
  72
  73 <tr><th colspan="3">Apache-SSL 1.x &amp; mod_ssl 2.0.x compatibility:</th></tr>
  74 <tr><td><code>SSLEnable</code></td><td><code>SSLEngine on</code></td><td>compactified</td></tr>
  75 <tr><td><code>SSLDisable</code></td><td><code>SSLEngine off</code></td><td>compactified</td></tr>
  76 <tr><td><code>SSLLogFile</code> <em>file</em></td><td><code>SSLLog</code> <em>file</em></td><td>compactified</td></tr>
  77
  78 <tr><td><code>SSLRequiredCiphers</code> <em>spec</em></td><td><code>SSLCipherSuite</code> <em>spec</em></td><td>renamed</td></tr>
  79 <tr><td><code>SSLRequireCipher</code> <em>c1</em> ...</td><td><code>SSLRequire %{SSL_CIPHER} in {"</code><em>c1</em><code>",
  80 ...}</code></td><td>generalized</td></tr>
  81
  82 <tr><td><code>SSLBanCipher</code> <em>c1</em> ...</td><td><code>SSLRequire not (%{SSL_CIPHER} in {"</code><em>c1</em><code>",
  83 ...})</code></td><td>generalized</td></tr>
  84 <tr><td><code>SSLFakeBasicAuth</code></td><td><code>SSLOptions +FakeBasicAuth</code></td><td>merged</td></tr>
  85 <tr><td><code>SSLCacheServerPath</code> <em>dir</em></td><td>-</td><td>functionality removed</td></tr>
  86
  87 <tr><td><code>SSLCacheServerPort</code> <em>integer</em></td><td>-</td><td>functionality removed</td></tr>
  88 <tr><th colspan="3">Apache-SSL 1.x compatibility:</th></tr>
  89 <tr><td><code>SSLExportClientCertificates</code></td><td><code>SSLOptions +ExportCertData</code></td><td>merged</td></tr>
  90 <tr><td><code>SSLCacheServerRunDir</code> <em>dir</em></td><td>-</td><td>functionality not supported</td></tr>
  91
  92 <tr><th colspan="3">Sioux 1.x compatibility:</th></tr>
  93 <tr><td><code>SSL_CertFile</code> <em>file</em></td><td><code>SSLCertificateFile</code> <em>file</em></td><td>renamed</td></tr>
  94 <tr><td><code>SSL_KeyFile</code> <em>file</em></td><td><code>SSLCertificateKeyFile</code> <em>file</em></td><td>renamed</td></tr>
  95
  96 <tr><td><code>SSL_CipherSuite</code> <em>arg</em></td><td><code>SSLCipherSuite</code> <em>arg</em></td><td>renamed</td></tr>
  97 <tr><td><code>SSL_X509VerifyDir</code> <em>arg</em></td><td><code>SSLCACertificatePath</code> <em>arg</em></td><td>renamed</td></tr>
  98 <tr><td><code>SSL_Log</code> <em>file</em></td><td><code>SSLLogFile</code> <em>file</em></td><td>renamed</td></tr>
  99
 100 <tr><td><code>SSL_Connect</code> <em>flag</em></td><td><code>SSLEngine</code> <em>flag</em></td><td>renamed</td></tr>
 101 <tr><td><code>SSL_ClientAuth</code> <em>arg</em></td><td><code>SSLVerifyClient</code> <em>arg</em></td><td>renamed</td></tr>
 102 <tr><td><code>SSL_X509VerifyDepth</code> <em>arg</em></td><td><code>SSLVerifyDepth</code> <em>arg</em></td><td>renamed</td></tr>
 103
 104 <tr><td><code>SSL_FetchKeyPhraseFrom</code> <em>arg</em></td><td>-</td><td>not directly mappable; use SSLPassPhraseDialog</td></tr>
 105 <tr><td><code>SSL_SessionDir</code> <em>dir</em></td><td>-</td><td>not directly mappable; use SSLSessionCache</td></tr>
 106 <tr><td><code>SSL_Require</code> <em>expr</em></td><td>-</td><td>not directly mappable; use SSLRequire</td></tr>
 107
 108 <tr><td><code>SSL_CertFileType</code> <em>arg</em></td><td>-</td><td>functionality not supported</td></tr>
 109 <tr><td><code>SSL_KeyFileType</code> <em>arg</em></td><td>-</td><td>functionality not supported</td></tr>
 110 <tr><td><code>SSL_X509VerifyPolicy</code> <em>arg</em></td><td>-</td><td>functionality not supported</td></tr>
 111
 112 <tr><td><code>SSL_LogX509Attributes</code> <em>arg</em></td><td>-</td><td>functionality not supported</td></tr>
 113 <tr><th colspan="3">Stronghold 2.x compatibility:</th></tr>
 114 <tr><td><code>StrongholdAccelerator</code> <em>engine</em></td><td><code>SSLCryptoDevice</code> <em>engine</em></td><td>renamed</td></tr>
 115 <tr><td><code>StrongholdKey</code> <em>dir</em></td><td>-</td><td>functionality not needed</td></tr>
 116
 117 <tr><td><code>StrongholdLicenseFile</code> <em>dir</em></td><td>-</td><td>functionality not needed</td></tr>
 118 <tr><td><code>SSLFlag</code> <em>flag</em></td><td><code>SSLEngine</code> <em>flag</em></td><td>renamed</td></tr>
 119 <tr><td><code>SSLSessionLockFile</code> <em>file</em></td><td><code>SSLMutex</code> <em>file</em></td><td>renamed</td></tr>
 120
 121 <tr><td><code>SSLCipherList</code> <em>spec</em></td><td><code>SSLCipherSuite</code> <em>spec</em></td><td>renamed</td></tr>
 122 <tr><td><code>RequireSSL</code></td><td><code>SSLRequireSSL</code></td><td>renamed</td></tr>
 123 <tr><td><code>SSLErrorFile</code> <em>file</em></td><td>-</td><td>functionality not supported</td></tr>
 124
 125 <tr><td><code>SSLRoot</code> <em>dir</em></td><td>-</td><td>functionality not supported</td></tr>
 126 <tr><td><code>SSL_CertificateLogDir</code> <em>dir</em></td><td>-</td><td>functionality not supported</td></tr>
 127 <tr><td><code>AuthCertDir</code> <em>dir</em></td><td>-</td><td>functionality not supported</td></tr>
 128
 129 <tr><td><code>SSL_Group</code> <em>name</em></td><td>-</td><td>functionality not supported</td></tr>
 130 <tr><td><code>SSLProxyMachineCertPath</code> <em>dir</em></td><td><code>SSLProxyMachineCertificatePath</code> <em>dir</em></td><td>renamed</td></tr>
 131 <tr><td><code>SSLProxyMachineCertFile</code> <em>file</em></td><td><code>SSLProxyMachineCertificateFile</code> <em>file</em></td><td>renamed</td></tr>
 132
 133 <tr><td><code>SSLProxyCipherList</code> <em>spec</em></td><td><code>SSLProxyCipherSpec</code> <em>spec</em></td><td>renamed</td></tr>
 134 </table>
 135 </section>
 136 </section>
 137
 138 <section id="variables"><title>Environment Variables</title>
 139
 140 <p>The mapping between environment variable names used by the older
 141 SSL solutions and the names used by mod_ssl is given in <a
 142 href="#table2">Table 2</a>.</p>
 143
 144 <section id="table2">
 145 <title>Table 2: Environment Variable Derivation</title>
 146 <table style="zebra">
 147 <columnspec><column width=".38"/><column width=".38"/>
 148 <column width=".2"/></columnspec>
 149 <tr><th>Old Variable</th><th>mod_ssl Variable</th><th>Comment</th></tr>
 150
 151 <tr><td><code>SSL_PROTOCOL_VERSION</code></td><td><code>SSL_PROTOCOL</code></td><td>renamed</td></tr>
 152 <tr><td><code>SSLEAY_VERSION</code></td><td><code>SSL_VERSION_LIBRARY</code></td><td>renamed</td></tr>
 153 <tr><td><code>HTTPS_SECRETKEYSIZE</code></td><td><code>SSL_CIPHER_USEKEYSIZE</code></td><td>renamed</td></tr>
 154 <tr><td><code>HTTPS_KEYSIZE</code></td><td><code>SSL_CIPHER_ALGKEYSIZE</code></td><td>renamed</td></tr>
 155 <tr><td><code>HTTPS_CIPHER</code></td><td><code>SSL_CIPHER</code></td><td>renamed</td></tr>
 156
 157 <tr><td><code>HTTPS_EXPORT</code></td><td><code>SSL_CIPHER_EXPORT</code></td><td>renamed</td></tr>
 158 <tr><td><code>SSL_SERVER_KEY_SIZE</code></td><td><code>SSL_CIPHER_ALGKEYSIZE</code></td><td>renamed</td></tr>
 159 <tr><td><code>SSL_SERVER_CERTIFICATE</code></td><td><code>SSL_SERVER_CERT</code></td><td>renamed</td></tr>
 160 <tr><td><code>SSL_SERVER_CERT_START</code></td><td><code>SSL_SERVER_V_START</code></td><td>renamed</td></tr>
 161 <tr><td><code>SSL_SERVER_CERT_END</code></td><td><code>SSL_SERVER_V_END</code></td><td>renamed</td></tr>
 162
 163 <tr><td><code>SSL_SERVER_CERT_SERIAL</code></td><td><code>SSL_SERVER_M_SERIAL</code></td><td>renamed</td></tr>
 164 <tr><td><code>SSL_SERVER_SIGNATURE_ALGORITHM</code></td><td><code>SSL_SERVER_A_SIG</code></td><td>renamed</td></tr>
 165 <tr><td><code>SSL_SERVER_DN</code></td><td><code>SSL_SERVER_S_DN</code></td><td>renamed</td></tr>
 166 <tr><td><code>SSL_SERVER_CN</code></td><td><code>SSL_SERVER_S_DN_CN</code></td><td>renamed</td></tr>
 167 <tr><td><code>SSL_SERVER_EMAIL</code></td><td><code>SSL_SERVER_S_DN_Email</code></td><td>renamed</td></tr>
 168
 169 <tr><td><code>SSL_SERVER_O</code></td><td><code>SSL_SERVER_S_DN_O</code></td><td>renamed</td></tr>
 170 <tr><td><code>SSL_SERVER_OU</code></td><td><code>SSL_SERVER_S_DN_OU</code></td><td>renamed</td></tr>
 171 <tr><td><code>SSL_SERVER_C</code></td><td><code>SSL_SERVER_S_DN_C</code></td><td>renamed</td></tr>
 172 <tr><td><code>SSL_SERVER_SP</code></td><td><code>SSL_SERVER_S_DN_SP</code></td><td>renamed</td></tr>
 173 <tr><td><code>SSL_SERVER_L</code></td><td><code>SSL_SERVER_S_DN_L</code></td><td>renamed</td></tr>
 174
 175 <tr><td><code>SSL_SERVER_IDN</code></td><td><code>SSL_SERVER_I_DN</code></td><td>renamed</td></tr>
 176 <tr><td><code>SSL_SERVER_ICN</code></td><td><code>SSL_SERVER_I_DN_CN</code></td><td>renamed</td></tr>
 177 <tr><td><code>SSL_SERVER_IEMAIL</code></td><td><code>SSL_SERVER_I_DN_Email</code></td><td>renamed</td></tr>
 178 <tr><td><code>SSL_SERVER_IO</code></td><td><code>SSL_SERVER_I_DN_O</code></td><td>renamed</td></tr>
 179 <tr><td><code>SSL_SERVER_IOU</code></td><td><code>SSL_SERVER_I_DN_OU</code></td><td>renamed</td></tr>
 180
 181 <tr><td><code>SSL_SERVER_IC</code></td><td><code>SSL_SERVER_I_DN_C</code></td><td>renamed</td></tr>
 182 <tr><td><code>SSL_SERVER_ISP</code></td><td><code>SSL_SERVER_I_DN_SP</code></td><td>renamed</td></tr>
 183 <tr><td><code>SSL_SERVER_IL</code></td><td><code>SSL_SERVER_I_DN_L</code></td><td>renamed</td></tr>
 184 <tr><td><code>SSL_CLIENT_CERTIFICATE</code></td><td><code>SSL_CLIENT_CERT</code></td><td>renamed</td></tr>
 185 <tr><td><code>SSL_CLIENT_CERT_START</code></td><td><code>SSL_CLIENT_V_START</code></td><td>renamed</td></tr>
 186
 187 <tr><td><code>SSL_CLIENT_CERT_END</code></td><td><code>SSL_CLIENT_V_END</code></td><td>renamed</td></tr>
 188 <tr><td><code>SSL_CLIENT_CERT_SERIAL</code></td><td><code>SSL_CLIENT_M_SERIAL</code></td><td>renamed</td></tr>
 189 <tr><td><code>SSL_CLIENT_SIGNATURE_ALGORITHM</code></td><td><code>SSL_CLIENT_A_SIG</code></td><td>renamed</td></tr>
 190 <tr><td><code>SSL_CLIENT_DN</code></td><td><code>SSL_CLIENT_S_DN</code></td><td>renamed</td></tr>
 191 <tr><td><code>SSL_CLIENT_CN</code></td><td><code>SSL_CLIENT_S_DN_CN</code></td><td>renamed</td></tr>
 192
 193 <tr><td><code>SSL_CLIENT_EMAIL</code></td><td><code>SSL_CLIENT_S_DN_Email</code></td><td>renamed</td></tr>
 194 <tr><td><code>SSL_CLIENT_O</code></td><td><code>SSL_CLIENT_S_DN_O</code></td><td>renamed</td></tr>
 195 <tr><td><code>SSL_CLIENT_OU</code></td><td><code>SSL_CLIENT_S_DN_OU</code></td><td>renamed</td></tr>
 196 <tr><td><code>SSL_CLIENT_C</code></td><td><code>SSL_CLIENT_S_DN_C</code></td><td>renamed</td></tr>
 197 <tr><td><code>SSL_CLIENT_SP</code></td><td><code>SSL_CLIENT_S_DN_SP</code></td><td>renamed</td></tr>
 198
 199 <tr><td><code>SSL_CLIENT_L</code></td><td><code>SSL_CLIENT_S_DN_L</code></td><td>renamed</td></tr>
 200 <tr><td><code>SSL_CLIENT_IDN</code></td><td><code>SSL_CLIENT_I_DN</code></td><td>renamed</td></tr>
 201 <tr><td><code>SSL_CLIENT_ICN</code></td><td><code>SSL_CLIENT_I_DN_CN</code></td><td>renamed</td></tr>
 202 <tr><td><code>SSL_CLIENT_IEMAIL</code></td><td><code>SSL_CLIENT_I_DN_Email</code></td><td>renamed</td></tr>
 203 <tr><td><code>SSL_CLIENT_IO</code></td><td><code>SSL_CLIENT_I_DN_O</code></td><td>renamed</td></tr>
 204
 205 <tr><td><code>SSL_CLIENT_IOU</code></td><td><code>SSL_CLIENT_I_DN_OU</code></td><td>renamed</td></tr>
 206 <tr><td><code>SSL_CLIENT_IC</code></td><td><code>SSL_CLIENT_I_DN_C</code></td><td>renamed</td></tr>
 207 <tr><td><code>SSL_CLIENT_ISP</code></td><td><code>SSL_CLIENT_I_DN_SP</code></td><td>renamed</td></tr>
 208 <tr><td><code>SSL_CLIENT_IL</code></td><td><code>SSL_CLIENT_I_DN_L</code></td><td>renamed</td></tr>
 209 <tr><td><code>SSL_EXPORT</code></td><td><code>SSL_CIPHER_EXPORT</code></td><td>renamed</td></tr>
 210
 211 <tr><td><code>SSL_KEYSIZE</code></td><td><code>SSL_CIPHER_ALGKEYSIZE</code></td><td>renamed</td></tr>
 212 <tr><td><code>SSL_SECKEYSIZE</code></td><td><code>SSL_CIPHER_USEKEYSIZE</code></td><td>renamed</td></tr>
 213 <tr><td><code>SSL_SSLEAY_VERSION</code></td><td><code>SSL_VERSION_LIBRARY</code></td><td>renamed</td></tr>
 214 <tr><td><code>SSL_STRONG_CRYPTO</code></td><td><code>-</code></td><td>Not supported by mod_ssl</td></tr>
 215 <tr><td><code>SSL_SERVER_KEY_EXP</code></td><td><code>-</code></td><td>Not supported by mod_ssl</td></tr>
 216
 217 <tr><td><code>SSL_SERVER_KEY_ALGORITHM</code></td><td><code>-</code></td><td>Not supported by mod_ssl</td></tr>
 218 <tr><td><code>SSL_SERVER_KEY_SIZE</code></td><td><code>-</code></td><td>Not supported by mod_ssl</td></tr>
 219 <tr><td><code>SSL_SERVER_SESSIONDIR</code></td><td><code>-</code></td><td>Not supported by mod_ssl</td></tr>
 220 <tr><td><code>SSL_SERVER_CERTIFICATELOGDIR</code></td><td><code>-</code></td><td>Not supported by mod_ssl</td></tr>
 221 <tr><td><code>SSL_SERVER_CERTFILE</code></td><td><code>-</code></td><td>Not supported by mod_ssl</td></tr>
 222
 223 <tr><td><code>SSL_SERVER_KEYFILE</code></td><td><code>-</code></td><td>Not supported by mod_ssl</td></tr>
 224 <tr><td><code>SSL_SERVER_KEYFILETYPE</code></td><td><code>-</code></td><td>Not supported by mod_ssl</td></tr>
 225 <tr><td><code>SSL_CLIENT_KEY_EXP</code></td><td><code>-</code></td><td>Not supported by mod_ssl</td></tr>
 226 <tr><td><code>SSL_CLIENT_KEY_ALGORITHM</code></td><td><code>-</code></td><td>Not supported by mod_ssl</td></tr>
 227 <tr><td><code>SSL_CLIENT_KEY_SIZE</code></td><td><code>-</code></td><td>Not supported by mod_ssl</td></tr>
 228 </table>
 229 </section>
 230 </section>
 231
 232 <section id="customlog"><title>Custom Log Functions</title>
 233 <p>
 234 When mod_ssl is enabled, additional functions exist for the <a
 235 href="../mod/mod_log_config.html#formats">Custom Log Format</a> of
 236 <module>mod_log_config</module> as documented in the Reference
 237 Chapter. Beside the ``<code>%{</code><em>varname</em><code>}x</code>''
 238 eXtension format function which can be used to expand any variables provided
 239 by any module, an additional Cryptography
 240 ``<code>%{</code><em>name</em><code>}c</code>'' cryptography format function
 241 exists for backward compatibility. The currently implemented function calls
 242 are listed in <a href="#table3">Table 3</a>.</p>
 243
 244 <section id="table3">
 245 <title>Table 3: Custom Log Cryptography Function</title>
 246 <table>
 247 <columnspec><column width=".2"/><column width=".4"/></columnspec>
 248 <tr><th>Function Call</th><th>Description</th></tr>
 249
 250 <tr><td><code>%...{version}c</code></td>   <td>SSL protocol version</td></tr>
 251 <tr><td><code>%...{cipher}c</code></td>    <td>SSL cipher</td></tr>
 252 <tr><td><code>%...{subjectdn}c</code></td> <td>Client Certificate Subject Distinguished Name</td></tr>
 253 <tr><td><code>%...{issuerdn}c</code></td>  <td>Client Certificate Issuer Distinguished Name</td></tr>
 254 <tr><td><code>%...{errcode}c</code></td>   <td>Certificate Verification Error (numerical)</td></tr>
 255
 256 <tr><td><code>%...{errstr}c</code></td>    <td>Certificate Verification Error (string)</td></tr>
 257 </table>
 258 </section>
 259 </section>
 260
 261 </manualpage>