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

   1
   2 #use "ssl_template.inc" title="Compatibility" tag=compat num=4
   3
   4 <page_prev name="Reference"   url="ssl_reference.html">
   5 <page_next name="HowTo"       url="ssl_howto.html">
   6
   7 #use wml::std::toc style=nbsp
   8
   9 <quotation width=200 author="Unknown">
  10 All PCs are compatible. But some of
  11 them are more compatible than others.
  12 </quotation>
  13
  14 <p>
  15 <table cellspacing=0 cellpadding=0 border=0>
  16 <tr valign=bottom>
  17 <td>
  18
  19 <big H>ere we talk about backward compatibility to other SSL solutions. As you
  20 perhaps know, mod_ssl is not the only existing SSL solution for Apache.
  21 Actually there are four additional major products available on the market: Ben
  22 Laurie's freely available <a href="http://www.apache-ssl.org/">Apache-SSL</a>
  23 (from where mod_ssl were originally derived in 1998), RedHat's commercial <a
  24 href="http://www.redhat.com/products/product-details.phtml?id=rhsa">Secure Web
  25 Server</a> (which is based on mod_ssl), Covalent's commercial <a
  26 href="http://raven.covalent.net/">Raven SSL Module</a> (also based on mod_ssl)
  27 and finally C2Net's commercial product <a
  28 href="http://www.c2.net/products/stronghold/">Stronghold</a> (based on a
  29 different evolution branch named Sioux up to Stronghold 2.x and based on
  30 mod_ssl since Stronghold 3.x).
  31
  32 </td>
  33 <td>
  34 &nbsp;&nbsp;
  35 </td>
  36 <td>
  37
  38 <div align=right>
  39 <table cellspacing=0 cellpadding=5 border=0 bgcolor="#ccccff">
  40 <tr>
  41 <td bgcolor="#333399">
  42 <font face="Arial,Helvetica" color="#ccccff">
  43 <b>Table Of Contents</b>
  44 </font>
  45 </td>
  46 </tr>
  47 <tr>
  48 <td>
  49 <font face="Arial,Helvetica" size=-1>
  50 <toc>
  51 </font>
  52 </td>
  53 </tr>
  54 </table>
  55 </div>
  56
  57 </td>
  58 </tr>
  59 </table>
  60
  61 <p>
  62 The idea in mod_ssl is mainly the following: because mod_ssl provides mostly a
  63 superset of the functionality of all other solutions we can easily provide
  64 backward compatibility for most of the cases. Actually there are three
  65 compatibility areas we currently address: configuration directives,
  66 environment variables and custom log functions.
  67
  68 <h2>Configuration Directives</h2>
  69
  70 For backward compatibility to the configuration directives of other SSL
  71 solutions we do an on-the-fly mapping: directives which have a direct
  72 counterpart in mod_ssl are mapped silently while other directives lead to a
  73 warning message in the logfiles.  The currently implemented directive mapping
  74 is listed in <a href="#table1">Table 1</a>.  Currently full backward
  75 compatibilty is provided only for Apache-SSL 1.x and mod_ssl 2.0.x.
  76 Compatibility to Sioux 1.x and Stronghold 2.x is only partial because of
  77 special functionality in these interfaces which mod_ssl (still) doesn't
  78 provide.
  79
  80 <p>
  81 <float name="table1" caption="Table 1: Configuration Directive Mapping">
  82 <table border=0 cellspacing=0 cellpadding=2 width=598>
  83 <tr id=D>
  84 <td><strong>Old Directive</strong></td>
  85 <td><strong>mod_ssl Directive</strong></td>
  86 <td><strong>Comment</strong></td>
  87 </tr>
  88 <tr id=H><td colspan=3><b>Apache-SSL 1.x &amp; mod_ssl 2.0.x compatibility:</b></td></tr>
  89 <tr id=D><td><code>SSLEnable</code></td><td><code>SSLEngine on</code></td><td>compactified</td></tr>
  90 <tr id=H><td><code>SSLDisable</code></td><td><code>SSLEngine off</code></td><td>compactified</td></tr>
  91 <tr id=D><td><code>SSLLogFile</code> <em>file</em></td><td><code>SSLLog</code> <em>file</em></td><td>compactified</td></tr>
  92 <tr id=H><td><code>SSLRequiredCiphers</code> <em>spec</em></td><td><code>SSLCipherSuite</code> <em>spec</em></td><td>renamed</td></tr>
  93 <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>
  94 <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>
  95 <tr id=D><td><code>SSLFakeBasicAuth</td><td><code>SSLOptions +FakeBasicAuth</code></td><td>merged</td></tr>
  96 <tr id=H><td><code>SSLCacheServerPath</code> <em>dir</em></td><td>-</td><td>functionality removed</td></tr>
  97 <tr id=D><td><code>SSLCacheServerPort</code> <em>integer</em></td><td>-</td><td>functionality removed</td></tr>
  98
  99 <tr id=H><td colspan=3><b>Apache-SSL 1.x compatibility:</b></td></tr>
 100 <tr id=D><td><code>SSLExportClientCertificates</td><td><code>SSLOptions +ExportCertData</code></td><td>merged</td></tr>
 101 <tr id=H><td><code>SSLCacheServerRunDir</code> <em>dir</em></td><td>-</td><td>functionality not supported</td></tr>
 102
 103 <tr id=D><td colspan=3><b>Sioux 1.x compatibility:</b></td></tr>
 104 <tr id=H><td><code>SSL_CertFile</code> <em>file</em></td><td><code>SSLCertificateFile</code> <em>file</em></td><td>renamed</td></tr>
 105 <tr id=D><td><code>SSL_KeyFile</code> <em>file</em></td><td><code>SSLCertificateKeyFile</code> <em>file</em></td><td>renamed</td></tr>
 106 <tr id=H><td><code>SSL_CipherSuite</code> <em>arg</em></td><td><code>SSLCipherSuite</code> <em>arg</em></td><td>renamed</td></tr>
 107 <tr id=D><td><code>SSL_X509VerifyDir</code> <em>arg</em></td><td><code>SSLCACertificatePath</code> <em>arg</em></td><td>renamed</td></tr>
 108 <tr id=H><td><code>SSL_Log</code> <em>file</em></td><td><code>SSLLogFile</code> <em>file</em></td><td>renamed</td></tr>
 109 <tr id=D><td><code>SSL_Connect</code> <em>flag</em></td><td><code>SSLEngine</code> <em>flag</em></td><td>renamed</td></tr>
 110 <tr id=H><td><code>SSL_ClientAuth</code> <em>arg</em></td><td><code>SSLVerifyClient</code> <em>arg</em></td><td>renamed</td></tr>
 111 <tr id=D><td><code>SSL_X509VerifyDepth</code> <em>arg</em></td><td><code>SSLVerifyDepth</code> <em>arg</em></td><td>renamed</td></tr>
 112 <tr id=H><td><code>SSL_FetchKeyPhraseFrom</code> <em>arg</em></td><td>-</td><td>not directly mappable; use SSLPassPhraseDialog</td></tr>
 113 <tr id=D><td><code>SSL_SessionDir</code> <em>dir</em></td><td>-</td><td>not directly mappable; use SSLSessionCache</td></tr>
 114 <tr id=H><td><code>SSL_Require</code> <em>expr</em></td><td>-</td><td>not directly mappable; use SSLRequire</td></tr>
 115 <tr id=D><td><code>SSL_CertFileType</code> <em>arg</em></td><td>-</td><td>functionality not supported</td></tr>
 116 <tr id=H><td><code>SSL_KeyFileType</code> <em>arg</em></td><td>-</td><td>functionality not supported</td></tr>
 117 <tr id=D><td><code>SSL_X509VerifyPolicy</code> <em>arg</em></td><td>-</td><td>functionality not supported</td></tr>
 118 <tr id=H><td><code>SSL_LogX509Attributes</code> <em>arg</em></td><td>-</td><td>functionality not supported</td></tr>
 119
 120 <tr id=D><td colspan=3><b>Stronghold 2.x compatibility:</b></td></tr>
 121 <tr id=H><td><code>StrongholdAccelerator</code> <em>dir</em></td><td>-</td><td>functionality not supported</td></tr>
 122 <tr id=H><td><code>StrongholdKey</code> <em>dir</em></td><td>-</td><td>functionality not supported</td></tr>
 123 <tr id=H><td><code>StrongholdLicenseFile</code> <em>dir</em></td><td>-</td><td>functionality not supported</td></tr>
 124 <tr id=H><td><code>SSLFlag</code> <em>flag</em></td><td><code>SSLEngine</code> <em>flag</em></td><td>renamed</td></tr>
 125 <tr id=D><td><code>SSLSessionLockFile</code> <em>file</em></td><td><code>SSLMutex</code> <em>file</em></td><td>renamed</td></tr>
 126 <tr id=H><td><code>SSLCipherList</code> <em>spec</em></td><td><code>SSLCipherSuite</code> <em>spec</em></td><td>renamed</td></tr>
 127 <tr id=D><td><code>RequireSSL</code></td><td><code>SSLRequireSSL</code></td><td>renamed</td></tr>
 128 <tr id=H><td><code>SSLErrorFile</code> <em>file</em></td><td>-</td><td>functionality not supported</td></tr>
 129 <tr id=H><td><code>SSLRoot</code> <em>dir</em></td><td>-</td><td>functionality not supported</td></tr>
 130 <tr id=D><td><code>SSL_CertificateLogDir</code> <em>dir</em></td><td>-</td><td>functionality not supported</td></tr>
 131 <tr id=H><td><code>AuthCertDir</code> <em>dir</em></td><td>-</td><td>functionality not supported</td></tr>
 132 <tr id=D><td><code>SSL_Group</code> <em>name</em></td><td>-</td><td>functionality not supported</td></tr>
 133 <tr id=H><td><code>SSLProxyMachineCertPath</code> <em>dir</em></td><td>-</td><td>functionality not supported</td></tr>
 134 <tr id=D><td><code>SSLProxyMachineCertFile</code> <em>file</em></td><td>-</td><td>functionality not supported</td></tr>
 135 <tr id=H><td><code>SSLProxyCACertificatePath</code> <em>dir</em></td><td>-</td><td>functionality not supported</td></tr>
 136 <tr id=D><td><code>SSLProxyCACertificateFile</code> <em>file</em></td><td>-</td><td>functionality not supported</td></tr>
 137 <tr id=H><td><code>SSLProxyVerifyDepth</code> <em>number</em></td><td>-</td><td>functionality not supported</td></tr>
 138 <tr id=D><td><code>SSLProxyCipherList</code> <em>spec</em></td><td>-</td><td>functionality not supported</td></tr>
 139 </table>
 140 </float>
 141
 142 <p>
 143 <br>
 144 <h2>Environment Variables</h2>
 145
 146 When you use ``<code>SSLOptions +CompatEnvVars</code>'' additional environment
 147 variables are generated. They all correspond to existing official mod_ssl
 148 variables.  The currently implemented variable derivation is listed in <a
 149 href="#table2">Table 2</a>.
 150
 151 <p>
 152 <float name="table2" caption="Table 2: Environment Variable Derivation">
 153 <table border=0 cellspacing=0 cellpadding=2 width=598>
 154 <tr id=D>
 155 <td><strong>Old Variable</strong></td>
 156 <td><strong>mod_ssl Variable</strong></td>
 157 <td><strong>Comment</strong></td>
 158 </tr>
 159 <tr id=H><td><code>SSL_PROTOCOL_VERSION</code></td><td><code>SSL_PROTOCOL</code></td><td>renamed</td></tr>
 160 <tr id=D><td><code>SSLEAY_VERSION</code></td><td><code>SSL_VERSION_LIBRARY</code></td><td>renamed</td></tr>
 161 <tr id=H><td><code>HTTPS_SECRETKEYSIZE</code></td><td><code>SSL_CIPHER_USEKEYSIZE</code></td><td>renamed</td></tr>
 162 <tr id=D><td><code>HTTPS_KEYSIZE</code></td><td><code>SSL_CIPHER_ALGKEYSIZE</code></td><td>renamed</td></tr>
 163 <tr id=H><td><code>HTTPS_CIPHER</code></td><td><code>SSL_CIPHER</code></td><td>renamed</td></tr>
 164 <tr id=D><td><code>HTTPS_EXPORT</code></td><td><code>SSL_CIPHER_EXPORT</code></td><td>renamed</td></tr>
 165 <tr id=H><td><code>SSL_SERVER_KEY_SIZE</code></td><td><code>SSL_CIPHER_ALGKEYSIZE</code></td><td>renamed</td></tr>
 166 <tr id=D><td><code>SSL_SERVER_CERTIFICATE</code></td><td><code>SSL_SERVER_CERT</code></td><td>renamed</td></tr>
 167 <tr id=H><td><code>SSL_SERVER_CERT_START</code></td><td><code>SSL_SERVER_V_START</code></td><td>renamed</td></tr>
 168 <tr id=D><td><code>SSL_SERVER_CERT_END</code></td><td><code>SSL_SERVER_V_END</code></td><td>renamed</td></tr>
 169 <tr id=H><td><code>SSL_SERVER_CERT_SERIAL</code></td><td><code>SSL_SERVER_M_SERIAL</code></td><td>renamed</td></tr>
 170 <tr id=H><td><code>SSL_SERVER_SIGNATURE_ALGORITHM</code></td><td><code>SSL_SERVER_A_SIG</code></td><td>renamed</td></tr>
 171 <tr id=H><td><code>SSL_SERVER_DN</code></td><td><code>SSL_SERVER_S_DN</code></td><td>renamed</td></tr>
 172 <tr id=H><td><code>SSL_SERVER_CN</code></td><td><code>SSL_SERVER_S_DN_CN</code></td><td>renamed</td></tr>
 173 <tr id=D><td><code>SSL_SERVER_EMAIL</code></td><td><code>SSL_SERVER_S_DN_Email</code></td><td>renamed</td></tr>
 174 <tr id=H><td><code>SSL_SERVER_O</code></td><td><code>SSL_SERVER_S_DN_O</code></td><td>renamed</td></tr>
 175 <tr id=D><td><code>SSL_SERVER_OU</code></td><td><code>SSL_SERVER_S_DN_OU</code></td><td>renamed</td></tr>
 176 <tr id=H><td><code>SSL_SERVER_C</code></td><td><code>SSL_SERVER_S_DN_C</code></td><td>renamed</td></tr>
 177 <tr id=D><td><code>SSL_SERVER_SP</code></td><td><code>SSL_SERVER_S_DN_SP</code></td><td>renamed</td></tr>
 178 <tr id=H><td><code>SSL_SERVER_L</code></td><td><code>SSL_SERVER_S_DN_L</code></td><td>renamed</td></tr>
 179 <tr id=H><td><code>SSL_SERVER_IDN</code></td><td><code>SSL_SERVER_I_DN</code></td><td>renamed</td></tr>
 180 <tr id=D><td><code>SSL_SERVER_ICN</code></td><td><code>SSL_SERVER_I_DN_CN</code></td><td>renamed</td></tr>
 181 <tr id=H><td><code>SSL_SERVER_IEMAIL</code></td><td><code>SSL_SERVER_I_DN_Email</code></td><td>renamed</td></tr>
 182 <tr id=D><td><code>SSL_SERVER_IO</code></td><td><code>SSL_SERVER_I_DN_O</code></td><td>renamed</td></tr>
 183 <tr id=H><td><code>SSL_SERVER_IOU</code></td><td><code>SSL_SERVER_I_DN_OU</code></td><td>renamed</td></tr>
 184 <tr id=D><td><code>SSL_SERVER_IC</code></td><td><code>SSL_SERVER_I_DN_C</code></td><td>renamed</td></tr>
 185 <tr id=H><td><code>SSL_SERVER_ISP</code></td><td><code>SSL_SERVER_I_DN_SP</code></td><td>renamed</td></tr>
 186 <tr id=D><td><code>SSL_SERVER_IL</code></td><td><code>SSL_SERVER_I_DN_L</code></td><td>renamed</td></tr>
 187 <tr id=H><td><code>SSL_CLIENT_CERTIFICATE</code></td><td><code>SSL_CLIENT_CERT</code></td><td>renamed</td></tr>
 188 <tr id=D><td><code>SSL_CLIENT_CERT_START</code></td><td><code>SSL_CLIENT_V_START</code></td><td>renamed</td></tr>
 189 <tr id=H><td><code>SSL_CLIENT_CERT_END</code></td><td><code>SSL_CLIENT_V_END</code></td><td>renamed</td></tr>
 190 <tr id=H><td><code>SSL_CLIENT_CERT_SERIAL</code></td><td><code>SSL_CLIENT_M_SERIAL</code></td><td>renamed</td></tr>
 191 <tr id=H><td><code>SSL_CLIENT_SIGNATURE_ALGORITHM</code></td><td><code>SSL_CLIENT_A_SIG</code></td><td>renamed</td></tr>
 192 <tr id=D><td><code>SSL_CLIENT_DN</code></td><td><code>SSL_CLIENT_S_DN</code></td><td>renamed</td></tr>
 193 <tr id=D><td><code>SSL_CLIENT_CN</code></td><td><code>SSL_CLIENT_S_DN_CN</code></td><td>renamed</td></tr>
 194 <tr id=H><td><code>SSL_CLIENT_EMAIL</code></td><td><code>SSL_CLIENT_S_DN_Email</code></td><td>renamed</td></tr>
 195 <tr id=D><td><code>SSL_CLIENT_O</code></td><td><code>SSL_CLIENT_S_DN_O</code></td><td>renamed</td></tr>
 196 <tr id=H><td><code>SSL_CLIENT_OU</code></td><td><code>SSL_CLIENT_S_DN_OU</code></td><td>renamed</td></tr>
 197 <tr id=D><td><code>SSL_CLIENT_C</code></td><td><code>SSL_CLIENT_S_DN_C</code></td><td>renamed</td></tr>
 198 <tr id=H><td><code>SSL_CLIENT_SP</code></td><td><code>SSL_CLIENT_S_DN_SP</code></td><td>renamed</td></tr>
 199 <tr id=D><td><code>SSL_CLIENT_L</code></td><td><code>SSL_CLIENT_S_DN_L</code></td><td>renamed</td></tr>
 200 <tr id=D><td><code>SSL_CLIENT_IDN</code></td><td><code>SSL_CLIENT_I_DN</code></td><td>renamed</td></tr>
 201 <tr id=H><td><code>SSL_CLIENT_ICN</code></td><td><code>SSL_CLIENT_I_DN_CN</code></td><td>renamed</td></tr>
 202 <tr id=D><td><code>SSL_CLIENT_IEMAIL</code></td><td><code>SSL_CLIENT_I_DN_Email</code></td><td>renamed</td></tr>
 203 <tr id=H><td><code>SSL_CLIENT_IO</code></td><td><code>SSL_CLIENT_I_DN_O</code></td><td>renamed</td></tr>
 204 <tr id=D><td><code>SSL_CLIENT_IOU</code></td><td><code>SSL_CLIENT_I_DN_OU</code></td><td>renamed</td></tr>
 205 <tr id=H><td><code>SSL_CLIENT_IC</code></td><td><code>SSL_CLIENT_I_DN_C</code></td><td>renamed</td></tr>
 206 <tr id=D><td><code>SSL_CLIENT_ISP</code></td><td><code>SSL_CLIENT_I_DN_SP</code></td><td>renamed</td></tr>
 207 <tr id=H><td><code>SSL_CLIENT_IL</code></td><td><code>SSL_CLIENT_I_DN_L</code></td><td>renamed</td></tr>
 208 <tr id=H><td><code>SSL_EXPORT</code></td><td><code>SSL_CIPHER_EXPORT</code></td><td>renamed</td></tr>
 209 <tr id=H><td><code>SSL_KEYSIZE</code></td><td><code>SSL_CIPHER_ALGKEYSIZE</code></td><td>renamed</td></tr>
 210 <tr id=H><td><code>SSL_SECKEYSIZE</code></td><td><code>SSL_CIPHER_USEKEYSIZE</code></td><td>renamed</td></tr>
 211 <tr id=H><td><code>SSL_SSLEAY_VERSION</code></td><td><code>SSL_VERSION_LIBRARY</code></td><td>renamed</td></tr>
 212 <tr id=D><td><code>SSL_STRONG_CRYPTO</code></td><td><code>-</code></td><td>Not supported by mod_ssl</td></tr>
 213 <tr id=D><td><code>SSL_SERVER_KEY_EXP</code></td><td><code>-</code></td><td>Not supported by mod_ssl</td></tr>
 214 <tr id=H><td><code>SSL_SERVER_KEY_ALGORITHM</code></td><td><code>-</code></td><td>Not supported by mod_ssl</td></tr>
 215 <tr id=D><td><code>SSL_SERVER_KEY_SIZE</code></td><td><code>-</code></td><td>Not supported by mod_ssl</td></tr>
 216 <tr id=H><td><code>SSL_SERVER_SESSIONDIR</code></td><td><code>-</code></td><td>Not supported by mod_ssl</td></tr>
 217 <tr id=D><td><code>SSL_SERVER_CERTIFICATELOGDIR</code></td><td><code>-</code></td><td>Not supported by mod_ssl</td></tr>
 218 <tr id=H><td><code>SSL_SERVER_CERTFILE</code></td><td><code>-</code></td><td>Not supported by mod_ssl</td></tr>
 219 <tr id=D><td><code>SSL_SERVER_KEYFILE</code></td><td><code>-</code></td><td>Not supported by mod_ssl</td></tr>
 220 <tr id=H><td><code>SSL_SERVER_KEYFILETYPE</code></td><td><code>-</code></td><td>Not supported by mod_ssl</td></tr>
 221 <tr id=D><td><code>SSL_CLIENT_KEY_EXP</code></td><td><code>-</code></td><td>Not supported by mod_ssl</td></tr>
 222 <tr id=H><td><code>SSL_CLIENT_KEY_ALGORITHM</code></td><td><code>-</code></td><td>Not supported by mod_ssl</td></tr>
 223 <tr id=D><td><code>SSL_CLIENT_KEY_SIZE</code></td><td><code>-</code></td><td>Not supported by mod_ssl</td></tr>
 224 </table>
 225 </float>
 226
 227 <p>
 228 <br>
 229 <h2>Custom Log Functions</h2>
 230
 231 When mod_ssl is built into Apache or at least loaded (under DSO situation)
 232 additional functions exist for the <a
 233 href="../mod_log_config.html#formats">Custom Log Format</a> of <a
 234 href="../mod_log_config.html">mod_log_config</a> as documented in the Reference
 235 Chapter. Beside the ``<code>%{</code><em>varname</em><code>}x</code>''
 236 eXtension format function which can be used to expand any variables provided
 237 by any module, an additional Cryptography
 238 ``<code>%{</code><em>name</em><code>}c</code>'' cryptography format function
 239 exists for backward compatibility.  The currently implemented function calls
 240 are listed in <a href="#table3">Table 3</a>.
 241
 242 <p>
 243 <float name="table3" caption="Table 3: Custom Log Cryptography Function">
 244 <table border=0 cellspacing=0 cellpadding=2 width=598>
 245 <tr id=H>
 246  <td><strong>Function Call</strong></td>
 247  <td><strong>Description</strong></td>
 248 </tr>
 249 <tr id=D><td><code>%...{version}c</code></td>   <td>SSL protocol version</td></tr>
 250 <tr id=H><td><code>%...{cipher}c</code></td>    <td>SSL cipher</td></tr>
 251 <tr id=D><td><code>%...{subjectdn}c</code></td> <td>Client Certificate Subject Distinguished Name</td></tr>
 252 <tr id=H><td><code>%...{issuerdn}c</code></td>  <td>Client Certificate Issuer  Distinguished Name</td></tr>
 253 <tr id=D><td><code>%...{errcode}c</code></td>   <td>Certificate Verification Error (numerical)</td></tr>
 254 <tr id=H><td><code>%...{errstr}c</code></td>    <td>Certificate Verification Error (string)</td></tr>
 255 </table>
 256 </float>
 257