1<html> 2<head> 3<title>mod_ssl: Reference</title> 4 5<!-- 6 Copyright (c) 1998-2001 Ralf S. Engelschall. All rights reserved. 7 8 Redistribution and use in source and binary forms, with or without 9 modification, are permitted provided that the following conditions 10 are met: 11 12 1. Redistributions of source code must retain the above 13 copyright notice, this list of conditions and the following 14 disclaimer. 15 16 2. Redistributions in binary form must reproduce the above 17 copyright notice, this list of conditions and the following 18 disclaimer in the documentation and/or other materials 19 provided with the distribution. 20 21 3. All advertising materials mentioning features or use of this 22 software must display the following acknowledgment: 23 "This product includes software developed by 24 Ralf S. Engelschall <rse@engelschall.com> for use in the 25 mod_ssl project (http://www.modssl.org/)." 26 27 4. The name "mod_ssl" must not be used to endorse or promote 28 products derived from this software without prior written 29 permission. 30 31 5. Redistributions of any form whatsoever must retain the 32 following acknowledgment: 33 "This product includes software developed by 34 Ralf S. Engelschall <rse@engelschall.com> for use in the 35 mod_ssl project (http://www.modssl.org/)." 36 37 THIS SOFTWARE IS PROVIDED BY RALF S. ENGELSCHALL ``AS IS'' AND ANY 38 EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 39 IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 40 PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL RALF S. ENGELSCHALL OR 41 HIS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 42 SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 43 NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 44 LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 45 HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, 46 STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 47 ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED 48 OF THE POSSIBILITY OF SUCH DAMAGE. 49--> 50<style type="text/css"><!-- 51A:link { 52 text-decoration: none; 53 color: #6666cc; 54} 55A:active { 56 text-decoration: none; 57 color: #6666cc; 58} 59A:visited { 60 text-decoration: none; 61 color: #6666cc; 62} 63#sf { 64 font-family: arial,helvetica; 65 font-variant: normal; 66 font-style: normal; 67} 68H1 { 69 font-weight: bold; 70 font-size: 24pt; 71 line-height: 24pt; 72 font-family: arial,helvetica; 73 font-variant: normal; 74 font-style: normal; 75} 76H2 { 77 font-weight: bold; 78 font-size: 18pt; 79 line-height: 18pt; 80 font-family: arial,helvetica; 81 font-variant: normal; 82 font-style: normal; 83} 84H3 { 85 font-weight: bold; 86 font-size: 14pt; 87 line-height: 14pt; 88 font-family: arial,helvetica; 89 font-variant: normal; 90 font-style: normal; 91} 92H4 { 93 font-weight: bold; 94 font-size: 12pt; 95 line-height: 12pt; 96 font-family: arial,helvetica; 97 font-variant: normal; 98 font-style: normal; 99} 100#H { 101} 102#D { 103 background-color: #f0f0f0; 104} 105#faq { 106 font-weight: bold; 107 font-size: 16pt; 108 line-height: 16pt; 109 font-family: arial,helvetica; 110 font-variant: normal; 111 font-style: normal; 112} 113#howto { 114 font-weight: bold; 115 font-size: 16pt; 116 line-height: 16pt; 117 font-family: arial,helvetica; 118 font-variant: normal; 119 font-style: normal; 120} 121#term { 122 font-weight: bold; 123 font-size: 16pt; 124 line-height: 16pt; 125 font-family: arial,helvetica; 126 font-variant: normal; 127 font-style: normal; 128} 129--></style> 130<script type="text/javascript" language="JavaScript"> 131<!-- Hiding the code 132function ro_imgNormal(imgName) { 133 if (document.images) { 134 document[imgName].src = eval(imgName + '_n.src'); 135 self.status = ''; 136 } 137} 138function ro_imgOver(imgName, descript) { 139 if (document.images) { 140 document[imgName].src = eval(imgName + '_o.src'); 141 self.status = descript; 142 } 143} 144// done hiding --> 145</script> 146<script type="text/javascript" language="JavaScript"> 147<!-- Hiding the code 148if (document.images) { 149 ro_img_prev_top_n = new Image(); 150 ro_img_prev_top_n.src = 'ssl_template.navbut-prev-n.gif'; 151 ro_img_prev_top_o = new Image(); 152 ro_img_prev_top_o.src = 'ssl_template.navbut-prev-s.gif'; 153} 154// done hiding --> 155</script> 156<script type="text/javascript" language="JavaScript"> 157<!-- Hiding the code 158if (document.images) { 159 ro_img_prev_bot_n = new Image(); 160 ro_img_prev_bot_n.src = 'ssl_template.navbut-prev-n.gif'; 161 ro_img_prev_bot_o = new Image(); 162 ro_img_prev_bot_o.src = 'ssl_template.navbut-prev-s.gif'; 163} 164// done hiding --> 165</script> 166<script type="text/javascript" language="JavaScript"> 167<!-- Hiding the code 168if (document.images) { 169 ro_img_next_top_n = new Image(); 170 ro_img_next_top_n.src = 'ssl_template.navbut-next-n.gif'; 171 ro_img_next_top_o = new Image(); 172 ro_img_next_top_o.src = 'ssl_template.navbut-next-s.gif'; 173} 174// done hiding --> 175</script> 176<script type="text/javascript" language="JavaScript"> 177<!-- Hiding the code 178if (document.images) { 179 ro_img_next_bot_n = new Image(); 180 ro_img_next_bot_n.src = 'ssl_template.navbut-next-n.gif'; 181 ro_img_next_bot_o = new Image(); 182 ro_img_next_bot_o.src = 'ssl_template.navbut-next-s.gif'; 183} 184// done hiding --> 185</script> 186</head> 187<body bgcolor="#ffffff" text="#000000" link="#333399" alink="#9999ff" vlink="#000066"> 188<div align="center"> 189<table width="600" cellspacing="0" cellpadding="0" border="0" summary=""> 190<tr> 191 <td> 192 <img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="600" height="1" align="bottom" border="0"><br> 193 <table width="600" cellspacing="0" cellpadding="0" summary=""> 194 <tr> 195 <td> 196 <table width="600" summary=""> 197 <tr> 198 <td align="left" valign="bottom"> 199 <font face="Arial,Helvetica" size="+2"><b>mod_ssl</b></font> 200 </td> 201 <td align="right"> 202 <img src="ssl_template.head-chapter.gif" alt="Chapter" width="175" height="94"> <img src="ssl_template.head-num-3.gif" alt="3" width="74" height="89"> 203 </td> 204 </tr> 205 </table> 206 </td> 207 </tr> 208 <tr> 209 <td><img src="ssl_template.imgdot-1x1-000000.gif" alt="" width="600" height="2" align="bottom" border="0"></td> 210 </tr> 211 <tr> 212 <td> 213 <table width="600" border="0" summary=""> 214 <tr> 215 <td valign="top" align="left" width="250"> 216<a href="ssl_intro.html" onmouseover="ro_imgOver('ro_img_prev_top', 'previous page'); return true" onmouseout="ro_imgNormal('ro_img_prev_top'); return true" onfocus="ro_imgOver('ro_img_prev_top', 'previous page'); return true" onblur="ro_imgNormal('ro_img_prev_top'); return true"><img name="ro_img_prev_top" src="ssl_template.navbut-prev-n.gif" alt="previous page" width="70" height="18" border="0"></a><br><font color="#000000">Introduction</font> 217 </td> 218 <td valign="top" align="right" width="250"> 219<a href="ssl_compat.html" onmouseover="ro_imgOver('ro_img_next_top', 'next page'); return true" onmouseout="ro_imgNormal('ro_img_next_top'); return true" onfocus="ro_imgOver('ro_img_next_top', 'next page'); return true" onblur="ro_imgNormal('ro_img_next_top'); return true"><img name="ro_img_next_top" src="ssl_template.navbut-next-n.gif" alt="next page" width="70" height="18" border="0"></a><br><font color="#000000">Compatibility</font> 220 </td> 221 </tr> 222 </table> 223 </td> 224 </tr> 225 <tr> 226 <td> 227 <br> 228 <img src="ssl_template.title-ref.gif" alt="Reference" width="456" height="60"> 229 </td> 230 </tr> 231 </table> 232<div align="right"> 233<table cellspacing="0" cellpadding="0" width="150" summary=""> 234<tr> 235<td> 236<em> 237``Try to understand everything, 238but believe nothing!'' 239</em> 240</td> 241</tr> 242<tr> 243<td align="right"> 244<font size="-1"> 245Unknown 246</font> 247</td> 248</tr> 249</table> 250</div> 251<p> 252<table cellspacing="0" cellpadding="0" border="0" summary=""> 253<tr valign="bottom"> 254<td> 255<img src="ssl_reference.gfont000.gif" alt="T" width="34" height="34" border="0" align="left"> 256his chapter provides a reference to all configuration directives and 257additional user visible features mod_ssl provides. It's intended as the 258official resource when you want to know how a particilar mod_ssl functionality 259is actually configured or activated. Each directive is documented similar to 260the way standard Apache directives are documented in the official Apache 261documentation set, i.e. for each directive especially the syntax, default and 262context where applicable is given. 263<p> 264Notice that there are three major classes of directives which are used by 265mod_ssl: First <em>Global Directives</em> (i.e. directives with context 266``server config''), which can occur inside the server config files but only 267outside of any sectioning commands like <VirtualHost>. Second 268<em>Per-Server Directives</em> (i.e. those with context ``server config, 269virtual host''), which can occur inside the server config files both outside 270(for the main/default server) and inside <VirtualHost> sections. 271</td> 272<td> 273 274</td> 275<td> 276<div align="right"> 277<table cellspacing="0" cellpadding="5" border="0" bgcolor="#ccccff" summary=""> 278<tr> 279<td bgcolor="#333399"> 280<font face="Arial,Helvetica" color="#ccccff"> 281<b>Table Of Contents</b> 282</font> 283</td> 284</tr> 285<tr> 286<td> 287<font face="Arial,Helvetica" size="-1"> 288<a href="#ToC1"><strong>Configuration Directives</strong></a><br> 289 <a href="#ToC2"><strong>SSLPassPhraseDialog</strong></a><br> 290 <a href="#ToC3"><strong>SSLMutex</strong></a><br> 291 <a href="#ToC4"><strong>SSLRandomSeed</strong></a><br> 292 <a href="#ToC5"><strong>SSLSessionCache</strong></a><br> 293 <a href="#ToC6"><strong>SSLSessionCacheTimeout</strong></a><br> 294 <a href="#ToC7"><strong>SSLEngine</strong></a><br> 295 <a href="#ToC8"><strong>SSLProtocol</strong></a><br> 296 <a href="#ToC9"><strong>SSLCipherSuite</strong></a><br> 297 <a href="#ToC10"><strong>SSLCertificateFile</strong></a><br> 298 <a href="#ToC11"><strong>SSLCertificateKeyFile</strong></a><br> 299 <a href="#ToC12"><strong>SSLCertificateChainFile</strong></a><br> 300 <a href="#ToC13"><strong>SSLCACertificatePath</strong></a><br> 301 <a href="#ToC14"><strong>SSLCACertificateFile</strong></a><br> 302 <a href="#ToC15"><strong>SSLCARevocationPath</strong></a><br> 303 <a href="#ToC16"><strong>SSLCARevocationFile</strong></a><br> 304 <a href="#ToC17"><strong>SSLVerifyClient</strong></a><br> 305 <a href="#ToC18"><strong>SSLVerifyDepth</strong></a><br> 306 <a href="#ToC19"><strong>SSLLog</strong></a><br> 307 <a href="#ToC20"><strong>SSLLogLevel</strong></a><br> 308 <a href="#ToC21"><strong>SSLOptions</strong></a><br> 309 <a href="#ToC22"><strong>SSLRequireSSL</strong></a><br> 310 <a href="#ToC23"><strong>SSLRequire</strong></a><br> 311<a href="#ToC24"><strong>Additional Features</strong></a><br> 312 <a href="#ToC25"><strong>Environment Variables</strong></a><br> 313 <a href="#ToC26"><strong>Custom Log Formats</strong></a><br> 314</font> 315</td> 316</tr> 317</table> 318</div> 319</td> 320</tr> 321</table> 322<p> 323And third <em>Per-Directory Directives</em> (i.e. those with context ``server 324config, virtual host, directory, .htaccess''), which can pretty much occur 325everywhere. Especially both inside the server config files and the 326per-directory <code>.htaccess</code> files. The three classes are subsets of 327each other, i.e. directives from the per-directory class can also be used in 328the per-server and global context, and directives from the per-server class 329can also be used the in the global context. 330<p> 331Additional directives and environment variables provided by mod_ssl (via 332on-the-fly mapping) for backward compatiblity to other Apache SSL solutions 333are documented in the <a href="ssl_compat.html">Compatibility</a> chapter. 334<h1><a name="ToC1">Configuration Directives</a></h1> 335The most visible and error-prone things of mod_ssl are its configuration 336directives. So we document them in great detail here to assist you in setting 337up the best possible configuration of your SSL-aware webserver. 338<!-- SSLPassPhraseDialog --------------------------------------------> 339<p> 340<br> 341<a name="SSLPassPhraseDialog"></a> 342<h2><a name="ToC2">SSLPassPhraseDialog</a></h2> 343<p> 344<table cellspacing="0" cellpadding="1" bgcolor="#cccccc" border="0" summary=""> 345<tr> 346<td> 347<table bgcolor="white" width="600" cellspacing="0" cellpadding="5" border="0" summary=""> 348<tr> 349<td> 350<table cellspacing="0" cellpadding="1" border="0" summary=""> 351<tr><td> 352<font face="Arial,Helvetica"><b>Name:</b></font></a> </td><td> <b>SSLPassPhraseDialog</b></td></tr> 353<tr><td> 354<font face="Arial,Helvetica"><b>Description:</b></font></a> </td><td> Type of pass phrase dialog for encrypted private keys</td></tr> 355<tr><td><a 356 href="../directive-dict.html#Syntax" 357 rel="Help" 358><font face="Arial,Helvetica"><b>Syntax:</b></font></a> </td><td> <code>SSLPassPhraseDialog</code> <em>type</em></td></tr> 359<tr><td><a 360 href="../directive-dict.html#Default" 361 rel="Help" 362><font face="Arial,Helvetica"><b>Default:</b></font></a> </td><td> <code>SSLPassPhraseDialog builtin</code></td></tr> 363<tr><td><a 364 href="../directive-dict.html#Context" 365 rel="Help" 366><font face="Arial,Helvetica"><b>Context:</b></font></a> </td><td> server config</td></tr> 367<tr><td><a 368 href="../directive-dict.html#Override" 369 rel="Help" 370><font face="Arial,Helvetica"><b>Override:</b></font></a> </td><td> <em>Not applicable</em></td></tr> 371<tr><td><a 372 href="../directive-dict.html#Status" 373 rel="Help" 374><font face="Arial,Helvetica"><b>Status:</b></font></a> </td><td> Extension</td></tr> 375<tr><td><a 376 href="../directive-dict.html#Module" 377 rel="Help" 378><font face="Arial,Helvetica"><b>Module:</b></font></a> </td><td> mod_ssl</td></tr> 379<tr><td><a 380 href="../directive-dict.html#Compatibility" 381 rel="Help" 382><font face="Arial,Helvetica"><b>Compatibility:</b></font></a> </td><td> mod_ssl 2.1 </td></tr> 383</table> 384</td> 385</tr> 386</table> 387</td> 388</tr> 389</table> 390<p> 391When Apache starts up it has to read the various Certificate (see <a 392href="#SSLCertificateFile">SSLCertificateFile</a>) and Private Key (see <a 393href="#SSLCertificateKeyFile">SSLCertificateKeyFile</a>) files of the 394SSL-enabled virtual servers. Because for security reasons the Private Key 395files are usually encrypted, mod_ssl needs to query the administrator for a 396Pass Phrase in order to decrypt those files. This query can be done in two ways 397which can be configured by <em>type</em>: 398<ul> 399<li><code>builtin</code> 400 <p> 401 This is the default where an interactive terminal dialog occurs at startup 402 time just before Apache detaches from the terminal. Here the administrator 403 has to manually enter the Pass Phrase for each encrypted Private Key file. 404 Because a lot of SSL-enabled virtual hosts can be configured, the 405 following reuse-scheme is used to minimize the dialog: When a Private Key 406 file is encrypted, all known Pass Phrases (at the beginning there are 407 none, of course) are tried. If one of those known Pass Phrases succeeds no 408 dialog pops up for this particular Private Key file. If none succeeded, 409 another Pass Phrase is queried on the terminal and remembered for the next 410 round (where it perhaps can be reused). 411 <p> 412 This scheme allows mod_ssl to be maximally flexible (because for N encrypted 413 Private Key files you <em>can</em> use N different Pass Phrases - but then 414 you have to enter all of them, of course) while minimizing the terminal 415 dialog (i.e. when you use a single Pass Phrase for all N Private Key files 416 this Pass Phrase is queried only once). 417<p> 418<li><code>exec:/path/to/program</code> 419 <p> 420 Here an external program is configured which is called at startup for each 421 encrypted Private Key file. It is called with two arguments (the first is 422 of the form ``<code>servername:portnumber</code>'', the second is either 423 ``<code>RSA</code>'' or ``<code>DSA</code>''), which indicate for which 424 server and algorithm it has to print the corresponding Pass Phrase to 425 <code>stdout</code>. The intent is that this external program first runs 426 security checks to make sure that the system is not compromised by an 427 attacker, and only when these checks were passed successfully it provides 428 the Pass Phrase. 429 <p> 430 Both these security checks, and the way the Pass Phrase is determined, can 431 be as complex as you like. Mod_ssl just defines the interface: an 432 executable program which provides the Pass Phrase on <code>stdout</code>. 433 Nothing more or less! So, if you're really paranoid about security, here 434 is your interface. Anything else has to be left as an exercise to the 435 administrator, because local security requirements are so different. 436 <p> 437 The reuse-algorithm above is used here, too. In other words: The external 438 program is called only once per unique Pass Phrase. 439</ul> 440<p> 441Example: 442<blockquote> 443<pre> 444SSLPassPhraseDialog exec:/usr/local/apache/sbin/pp-filter 445</pre> 446</blockquote> 447<!-- SSLMutex -------------------------------------------------------> 448<p> 449<br> 450<a name="SSLMutex"></a> 451<h2><a name="ToC3">SSLMutex</a></h2> 452<p> 453<table cellspacing="0" cellpadding="1" bgcolor="#cccccc" border="0" summary=""> 454<tr> 455<td> 456<table bgcolor="white" width="600" cellspacing="0" cellpadding="5" border="0" summary=""> 457<tr> 458<td> 459<table cellspacing="0" cellpadding="1" border="0" summary=""> 460<tr><td> 461<font face="Arial,Helvetica"><b>Name:</b></font></a> </td><td> <b>SSLMutex</b></td></tr> 462<tr><td> 463<font face="Arial,Helvetica"><b>Description:</b></font></a> </td><td> Semaphore for internal mutual exclusion of operations</td></tr> 464<tr><td><a 465 href="../directive-dict.html#Syntax" 466 rel="Help" 467><font face="Arial,Helvetica"><b>Syntax:</b></font></a> </td><td> <code>SSLMutex</code> <em>type</em></td></tr> 468<tr><td><a 469 href="../directive-dict.html#Default" 470 rel="Help" 471><font face="Arial,Helvetica"><b>Default:</b></font></a> </td><td> <code>SSLMutex none</code></td></tr> 472<tr><td><a 473 href="../directive-dict.html#Context" 474 rel="Help" 475><font face="Arial,Helvetica"><b>Context:</b></font></a> </td><td> server config</td></tr> 476<tr><td><a 477 href="../directive-dict.html#Override" 478 rel="Help" 479><font face="Arial,Helvetica"><b>Override:</b></font></a> </td><td> <em>Not applicable</em></td></tr> 480<tr><td><a 481 href="../directive-dict.html#Status" 482 rel="Help" 483><font face="Arial,Helvetica"><b>Status:</b></font></a> </td><td> Extension</td></tr> 484<tr><td><a 485 href="../directive-dict.html#Module" 486 rel="Help" 487><font face="Arial,Helvetica"><b>Module:</b></font></a> </td><td> mod_ssl</td></tr> 488<tr><td><a 489 href="../directive-dict.html#Compatibility" 490 rel="Help" 491><font face="Arial,Helvetica"><b>Compatibility:</b></font></a> </td><td> mod_ssl 2.1 </td></tr> 492</table> 493</td> 494</tr> 495</table> 496</td> 497</tr> 498</table> 499<p> 500This configures the SSL engine's semaphore (aka. lock) which is used for mutual 501exclusion of operations which have to be done in a synchronized way between the 502pre-forked Apache server processes. This directive can only be used in the 503global server context because it's only useful to have one global mutex. 504<p> 505The following Mutex <em>types</em> are available: 506<ul> 507<li><code>none</code> 508 <p> 509 This is the default where no Mutex is used at all. Use it at your own 510 risk. But because currently the Mutex is mainly used for synchronizing 511 write access to the SSL Session Cache you can live without it as long 512 as you accept a sometimes garbled Session Cache. So it's not recommended 513 to leave this the default. Instead configure a real Mutex. 514<p> 515<li><code>file:/path/to/mutex</code> 516 <p> 517 This is the portable and (under Unix) always provided Mutex variant where 518 a physical (lock-)file is used as the Mutex. Always use a local disk 519 filesystem for <code>/path/to/mutex</code> and never a file residing on a 520 NFS- or AFS-filesystem. Note: Internally, the Process ID (PID) of the 521 Apache parent process is automatically appended to 522 <code>/path/to/mutex</code> to make it unique, so you don't have to worry 523 about conflicts yourself. Notice that this type of mutex is not available 524 under the Win32 environment. There you <i>have</i> to use the semaphore 525 mutex. 526<p> 527<li><code>sem</code> 528 <p> 529 This is the most elegant but also most non-portable Mutex variant where a 530 SysV IPC Semaphore (under Unix) and a Windows Mutex (under Win32) is used 531 when possible. It is only available when the underlying platform 532 supports it. 533</ul> 534<p> 535Example: 536<blockquote> 537<pre> 538SSLMutex file:/usr/local/apache/logs/ssl_mutex 539</pre> 540</blockquote> 541<!-- SSLRandomSeed --------------------------------------------------> 542<p> 543<br> 544<a name="SSLRandomSeed"></a> 545<h2><a name="ToC4">SSLRandomSeed</a></h2> 546<p> 547<table cellspacing="0" cellpadding="1" bgcolor="#cccccc" border="0" summary=""> 548<tr> 549<td> 550<table bgcolor="white" width="600" cellspacing="0" cellpadding="5" border="0" summary=""> 551<tr> 552<td> 553<table cellspacing="0" cellpadding="1" border="0" summary=""> 554<tr><td> 555<font face="Arial,Helvetica"><b>Name:</b></font></a> </td><td> <b>SSLRandomSeed</b></td></tr> 556<tr><td> 557<font face="Arial,Helvetica"><b>Description:</b></font></a> </td><td> Pseudo Random Number Generator (PRNG) seeding source</td></tr> 558<tr><td><a 559 href="../directive-dict.html#Syntax" 560 rel="Help" 561><font face="Arial,Helvetica"><b>Syntax:</b></font></a> </td><td> <code>SSLRandomSeed</code> <em>context</em> <em>source</em> [<em>bytes</em>]</td></tr> 562<tr><td><a 563 href="../directive-dict.html#Default" 564 rel="Help" 565><font face="Arial,Helvetica"><b>Default:</b></font></a> </td><td> <em>none</em></td></tr> 566<tr><td><a 567 href="../directive-dict.html#Context" 568 rel="Help" 569><font face="Arial,Helvetica"><b>Context:</b></font></a> </td><td> server config</td></tr> 570<tr><td><a 571 href="../directive-dict.html#Override" 572 rel="Help" 573><font face="Arial,Helvetica"><b>Override:</b></font></a> </td><td> <em>Not applicable</em></td></tr> 574<tr><td><a 575 href="../directive-dict.html#Status" 576 rel="Help" 577><font face="Arial,Helvetica"><b>Status:</b></font></a> </td><td> Extension</td></tr> 578<tr><td><a 579 href="../directive-dict.html#Module" 580 rel="Help" 581><font face="Arial,Helvetica"><b>Module:</b></font></a> </td><td> mod_ssl</td></tr> 582<tr><td><a 583 href="../directive-dict.html#Compatibility" 584 rel="Help" 585><font face="Arial,Helvetica"><b>Compatibility:</b></font></a> </td><td> mod_ssl 2.2 </td></tr> 586</table> 587</td> 588</tr> 589</table> 590</td> 591</tr> 592</table> 593<p> 594This configures one or more sources for seeding the Pseudo Random Number 595Generator (PRNG) in OpenSSL at startup time (<em>context</em> is 596<code>startup</code>) and/or just before a new SSL connection is established 597(<em>context</em> is <code>connect</code>). This directive can only be used 598in the global server context because the PRNG is a global facility. 599<p> 600The following <em>source</em> variants are available: 601<ul> 602<li><code>builtin</code> 603 <p> This is the always available builtin seeding source. It's usage 604 consumes minimum CPU cycles under runtime and hence can be always used 605 without drawbacks. The source used for seeding the PRNG contains of the 606 current time, the current process id and (when applicable) a randomly 607 choosen 1KB extract of the inter-process scoreboard structure of Apache. 608 The drawback is that this is not really a strong source and at startup 609 time (where the scoreboard is still not available) this source just 610 produces a few bytes of entropy. So you should always, at least for the 611 startup, use an additional seeding source. 612<p> 613<li><code>file:/path/to/source</code> 614 <p> 615 This variant uses an external file <code>/path/to/source</code> as the 616 source for seeding the PRNG. When <em>bytes</em> is specified, only the 617 first <em>bytes</em> number of bytes of the file form the entropy (and 618 <em>bytes</em> is given to <code>/path/to/source</code> as the first 619 argument). When <em>bytes</em> is not specified the whole file forms the 620 entropy (and <code>0</code> is given to <code>/path/to/source</code> as 621 the first argument). Use this especially at startup time, for instance 622 with an available <code>/dev/random</code> and/or 623 <code>/dev/urandom</code> devices (which usually exist on modern Unix 624 derivates like FreeBSD and Linux). 625 <p> 626 <em>But be careful</em>: Usually <code>/dev/random</code> provides only as 627 much entropy data as it actually has, i.e. when you request 512 bytes of 628 entropy, but the device currently has only 100 bytes available two things 629 can happen: On some platforms you receive only the 100 bytes while on 630 other platforms the read blocks until enough bytes are available (which 631 can take a long time). Here using an existing <code>/dev/urandom</code> is 632 better, because it never blocks and actually gives the amount of requested 633 data. The drawback is just that the quality of the received data may not 634 be the best. 635 <p> 636 On some platforms like FreeBSD one can even control how the entropy is 637 actually generated, i.e. by which system interrupts. More details one can 638 find under <i>rndcontrol(8)</i> on those platforms. Alternatively, when 639 your system lacks such a random device, you can use tool 640 like <a href="http://www.lothar.com/tech/crypto/">EGD</a> 641 (Entropy Gathering Daemon) and run it's client program with the 642 <code>exec:/path/to/program/</code> variant (see below) or use 643 <code>egd:/path/to/egd-socket</code> (see below). 644<p> 645<li><code>exec:/path/to/program</code> 646 <p> 647 This variant uses an external executable <code>/path/to/program</code> as 648 the source for seeding the PRNG. When <em>bytes</em> is specified, only the 649 first <em>bytes</em> number of bytes of its <code>stdout</code> contents 650 form the entropy. When <em>bytes</em> is not specified, the entirety of 651 the data produced on <code>stdout</code> form the entropy. Use this only 652 at startup time when you need a very strong seeding with the help of an 653 external program (for instance as in the example above with the 654 <code>truerand</code> utility you can find in the mod_ssl distribution 655 which is based on the AT&T <em>truerand</em> library). Using this in 656 the connection context slows down the server too dramatically, of course. 657 So usually you should avoid using external programs in that context. 658<p> 659<li><code>egd:/path/to/egd-socket</code> (Unix only) 660 <p> 661 This variant uses the Unix domain socket of the 662 external Entropy Gathering Daemon (EGD) (see <a 663 href="http://www.lothar.com/tech/crypto/">http://www.lothar.com/tech 664 /crypto/</a>) to seed the PRNG. Use this if no random device exists 665 on your platform. 666</ul> 667<p> 668Example: 669<blockquote> 670<pre> 671SSLRandomSeed startup builtin 672SSLRandomSeed startup file:/dev/random 673SSLRandomSeed startup file:/dev/urandom 1024 674SSLRandomSeed startup exec:/usr/local/bin/truerand 16 675SSLRandomSeed connect builtin 676SSLRandomSeed connect file:/dev/random 677SSLRandomSeed connect file:/dev/urandom 1024 678</pre> 679</blockquote> 680<!-- SSLSessionCache ------------------------------------------------> 681<p> 682<br> 683<a name="SSLSessionCache"></a> 684<h2><a name="ToC5">SSLSessionCache</a></h2> 685<table cellspacing="0" cellpadding="1" bgcolor="#cccccc" border="0" summary=""> 686<tr> 687<td> 688<table bgcolor="white" width="600" cellspacing="0" cellpadding="5" border="0" summary=""> 689<tr> 690<td> 691<table cellspacing="0" cellpadding="1" border="0" summary=""> 692<tr><td> 693<font face="Arial,Helvetica"><b>Name:</b></font></a> </td><td> <b>SSLSessionCache</b></td></tr> 694<tr><td> 695<font face="Arial,Helvetica"><b>Description:</b></font></a> </td><td> Type of the global/inter-process SSL Session Cache</td></tr> 696<tr><td><a 697 href="../directive-dict.html#Syntax" 698 rel="Help" 699><font face="Arial,Helvetica"><b>Syntax:</b></font></a> </td><td> <code>SSLSessionCache</code> <em>type</em></td></tr> 700<tr><td><a 701 href="../directive-dict.html#Default" 702 rel="Help" 703><font face="Arial,Helvetica"><b>Default:</b></font></a> </td><td> <code>SSLSessionCache none</code></td></tr> 704<tr><td><a 705 href="../directive-dict.html#Context" 706 rel="Help" 707><font face="Arial,Helvetica"><b>Context:</b></font></a> </td><td> server config</td></tr> 708<tr><td><a 709 href="../directive-dict.html#Override" 710 rel="Help" 711><font face="Arial,Helvetica"><b>Override:</b></font></a> </td><td> <em>Not applicable</em></td></tr> 712<tr><td><a 713 href="../directive-dict.html#Status" 714 rel="Help" 715><font face="Arial,Helvetica"><b>Status:</b></font></a> </td><td> Extension</td></tr> 716<tr><td><a 717 href="../directive-dict.html#Module" 718 rel="Help" 719><font face="Arial,Helvetica"><b>Module:</b></font></a> </td><td> mod_ssl</td></tr> 720<tr><td><a 721 href="../directive-dict.html#Compatibility" 722 rel="Help" 723><font face="Arial,Helvetica"><b>Compatibility:</b></font></a> </td><td> mod_ssl 2.1 </td></tr> 724</table> 725</td> 726</tr> 727</table> 728</td> 729</tr> 730</table> 731<p> 732This configures the storage type of the global/inter-process SSL Session 733Cache. This cache is an optional facility which speeds up parallel request 734processing. For requests to the same server process (via HTTP keep-alive), 735OpenSSL already caches the SSL session information locally. But because modern 736clients request inlined images and other data via parallel requests (usually 737up to four parallel requests are common) those requests are served by 738<em>different</em> pre-forked server processes. Here an inter-process cache 739helps to avoid unneccessary session handshakes. 740<p> 741The following two storage <em>type</em>s are currently supported: 742<ul> 743<li><code>none</code> 744 <p> 745 This is the default and just disables the global/inter-process Session 746 Cache. There is no drawback in functionality, but a noticeable speed 747 penalty can be observed. 748<p> 749<li><code>dbm:/path/to/datafile</code> 750 <p> 751 This makes use of a DBM hashfile on the local disk to synchronize the 752 local OpenSSL memory caches of the server processes. The slight increase 753 in I/O on the server results in a visible request speedup for your 754 clients, so this type of storage is generally recommended. 755<p> 756<li><code>shm:/path/to/datafile</code>[<code>(</code><i>size</i><code>)</code>] 757 <p> 758 This makes use of a high-performance hash table (approx. <i>size</i> bytes 759 in size) inside a shared memory segment in RAM (established via 760 <code>/path/to/datafile</code>) to synchronize the local OpenSSL memory 761 caches of the server processes. This storage type is not available on all 762 platforms. See the mod_ssl <code>INSTALL</code> document for details on 763 how to build Apache+EAPI with shared memory support. 764</ul> 765<p> 766Examples: 767<blockquote> 768<pre> 769SSLSessionCache dbm:/usr/local/apache/logs/ssl_gcache_data 770SSLSessionCache shm:/usr/local/apache/logs/ssl_gcache_data(512000) 771</pre> 772</blockquote> 773<!-- SSLSessionCacheTimeout -----------------------------------------> 774<p> 775<br> 776<a name="SSLSessionCacheTimeout"></a> 777<h2><a name="ToC6">SSLSessionCacheTimeout</a></h2> 778<table cellspacing="0" cellpadding="1" bgcolor="#cccccc" border="0" summary=""> 779<tr> 780<td> 781<table bgcolor="white" width="600" cellspacing="0" cellpadding="5" border="0" summary=""> 782<tr> 783<td> 784<table cellspacing="0" cellpadding="1" border="0" summary=""> 785<tr><td> 786<font face="Arial,Helvetica"><b>Name:</b></font></a> </td><td> <b>SSLSessionCacheTimeout</b></td></tr> 787<tr><td> 788<font face="Arial,Helvetica"><b>Description:</b></font></a> </td><td> Number of seconds before an SSL session expires in the Session Cache</td></tr> 789<tr><td><a 790 href="../directive-dict.html#Syntax" 791 rel="Help" 792><font face="Arial,Helvetica"><b>Syntax:</b></font></a> </td><td> <code>SSLSessionCacheTimeout</code> <em>seconds</em></td></tr> 793<tr><td><a 794 href="../directive-dict.html#Default" 795 rel="Help" 796><font face="Arial,Helvetica"><b>Default:</b></font></a> </td><td> <code>SSLSessionCacheTimeout 300</code></td></tr> 797<tr><td><a 798 href="../directive-dict.html#Context" 799 rel="Help" 800><font face="Arial,Helvetica"><b>Context:</b></font></a> </td><td> server config, virtual host</td></tr> 801<tr><td><a 802 href="../directive-dict.html#Override" 803 rel="Help" 804><font face="Arial,Helvetica"><b>Override:</b></font></a> </td><td> <em>Not applicable</em></td></tr> 805<tr><td><a 806 href="../directive-dict.html#Status" 807 rel="Help" 808><font face="Arial,Helvetica"><b>Status:</b></font></a> </td><td> Extension</td></tr> 809<tr><td><a 810 href="../directive-dict.html#Module" 811 rel="Help" 812><font face="Arial,Helvetica"><b>Module:</b></font></a> </td><td> mod_ssl</td></tr> 813<tr><td><a 814 href="../directive-dict.html#Compatibility" 815 rel="Help" 816><font face="Arial,Helvetica"><b>Compatibility:</b></font></a> </td><td> mod_ssl 2.0 </td></tr> 817</table> 818</td> 819</tr> 820</table> 821</td> 822</tr> 823</table> 824<p> 825This directive sets the timeout in seconds for the information stored in the 826global/inter-process SSL Session Cache and the OpenSSL internal memory cache. 827It can be set as low as 15 for testing, but should be set to higher 828values like 300 in real life. 829<p> 830Example: 831<blockquote> 832<pre> 833SSLSessionCacheTimeout 600 834</pre> 835</blockquote> 836<!-- SSLEngine ------------------------------------------------------> 837<p> 838<br> 839<a name="SSLEngine"></a> 840<h2><a name="ToC7">SSLEngine</a></h2> 841<table cellspacing="0" cellpadding="1" bgcolor="#cccccc" border="0" summary=""> 842<tr> 843<td> 844<table bgcolor="white" width="600" cellspacing="0" cellpadding="5" border="0" summary=""> 845<tr> 846<td> 847<table cellspacing="0" cellpadding="1" border="0" summary=""> 848<tr><td> 849<font face="Arial,Helvetica"><b>Name:</b></font></a> </td><td> <b>SSLEngine</b></td></tr> 850<tr><td> 851<font face="Arial,Helvetica"><b>Description:</b></font></a> </td><td> SSL Engine Operation Switch</td></tr> 852<tr><td><a 853 href="../directive-dict.html#Syntax" 854 rel="Help" 855><font face="Arial,Helvetica"><b>Syntax:</b></font></a> </td><td> <code>SSLEngine</code> <em>on|off</em></td></tr> 856<tr><td><a 857 href="../directive-dict.html#Default" 858 rel="Help" 859><font face="Arial,Helvetica"><b>Default:</b></font></a> </td><td> <code>SSLEngine off</code></td></tr> 860<tr><td><a 861 href="../directive-dict.html#Context" 862 rel="Help" 863><font face="Arial,Helvetica"><b>Context:</b></font></a> </td><td> server config, virtual host</td></tr> 864<tr><td><a 865 href="../directive-dict.html#Override" 866 rel="Help" 867><font face="Arial,Helvetica"><b>Override:</b></font></a> </td><td> <em>Not applicable</em></td></tr> 868<tr><td><a 869 href="../directive-dict.html#Status" 870 rel="Help" 871><font face="Arial,Helvetica"><b>Status:</b></font></a> </td><td> Extension</td></tr> 872<tr><td><a 873 href="../directive-dict.html#Module" 874 rel="Help" 875><font face="Arial,Helvetica"><b>Module:</b></font></a> </td><td> mod_ssl</td></tr> 876<tr><td><a 877 href="../directive-dict.html#Compatibility" 878 rel="Help" 879><font face="Arial,Helvetica"><b>Compatibility:</b></font></a> </td><td> mod_ssl 2.1 </td></tr> 880</table> 881</td> 882</tr> 883</table> 884</td> 885</tr> 886</table> 887<p> 888This directive toggles the usage of the SSL/TLS Protocol Engine. This is 889usually used inside a <VirtualHost> section to enable SSL/TLS for a 890particular virtual host. By default the SSL/TLS Protocol Engine is disabled 891for both the main server and all configured virtual hosts. 892<p> 893Example: 894<blockquote> 895<pre> 896<VirtualHost _default_:443> 897SSLEngine on 898... 899</VirtualHost> 900</pre> 901</blockquote> 902<!-- SSLProtocol ----------------------------------------------------> 903<p> 904<br> 905<a name="SSLProtocol"></a> 906<h2><a name="ToC8">SSLProtocol</a></h2> 907<table cellspacing="0" cellpadding="1" bgcolor="#cccccc" border="0" summary=""> 908<tr> 909<td> 910<table bgcolor="white" width="600" cellspacing="0" cellpadding="5" border="0" summary=""> 911<tr> 912<td> 913<table cellspacing="0" cellpadding="1" border="0" summary=""> 914<tr><td> 915<font face="Arial,Helvetica"><b>Name:</b></font></a> </td><td> <b>SSLProtocol</b></td></tr> 916<tr><td> 917<font face="Arial,Helvetica"><b>Description:</b></font></a> </td><td> Configure usable SSL protocol flavors</td></tr> 918<tr><td><a 919 href="../directive-dict.html#Syntax" 920 rel="Help" 921><font face="Arial,Helvetica"><b>Syntax:</b></font></a> </td><td> <code>SSLProtocol</code> [+-]<em>protocol</em> ...</td></tr> 922<tr><td><a 923 href="../directive-dict.html#Default" 924 rel="Help" 925><font face="Arial,Helvetica"><b>Default:</b></font></a> </td><td> <code>SSLProtocol all</code></td></tr> 926<tr><td><a 927 href="../directive-dict.html#Context" 928 rel="Help" 929><font face="Arial,Helvetica"><b>Context:</b></font></a> </td><td> server config, virtual host</td></tr> 930<tr><td><a 931 href="../directive-dict.html#Override" 932 rel="Help" 933><font face="Arial,Helvetica"><b>Override:</b></font></a> </td><td> Options</td></tr> 934<tr><td><a 935 href="../directive-dict.html#Status" 936 rel="Help" 937><font face="Arial,Helvetica"><b>Status:</b></font></a> </td><td> Extension</td></tr> 938<tr><td><a 939 href="../directive-dict.html#Module" 940 rel="Help" 941><font face="Arial,Helvetica"><b>Module:</b></font></a> </td><td> mod_ssl</td></tr> 942<tr><td><a 943 href="../directive-dict.html#Compatibility" 944 rel="Help" 945><font face="Arial,Helvetica"><b>Compatibility:</b></font></a> </td><td> mod_ssl 2.2 </td></tr> 946</table> 947</td> 948</tr> 949</table> 950</td> 951</tr> 952</table> 953<p> 954This directive can be used to control the SSL protocol flavors mod_ssl should 955use when establishing its server environment. Clients then can only connect 956with one of the provided protocols. 957<p> 958The available (case-insensitive) <em>protocol</em>s are: 959<ul> 960<li><code>SSLv2</code> 961 <p> 962 This is the Secure Sockets Layer (SSL) protocol, version 2.0. It is the 963 original SSL protocol as designed by Netscape Corporation. 964<p> 965<li><code>SSLv3</code> 966 <p> 967 This is the Secure Sockets Layer (SSL) protocol, version 3.0. It is the 968 successor to SSLv2 and the currently (as of February 1999) de-facto 969 standardized SSL protocol from Netscape Corporation. It's supported by 970 almost all popular browsers. 971<p> 972<li><code>TLSv1</code> 973 <p> 974 This is the Transport Layer Security (TLS) protocol, version 1.0. It is the 975 successor to SSLv3 and currently (as of February 1999) still under 976 construction by the Internet Engineering Task Force (IETF). It's still 977 not supported by any popular browsers. 978<p> 979<li><code>All</code> 980 <p> 981 This is a shortcut for ``<code>+SSLv2 +SSLv3 +TLSv1</code>'' and a 982 convinient way for enabling all protocols except one when used in 983 combination with the minus sign on a protocol as the example above shows. 984</ul> 985<p> 986Example: 987<blockquote> 988<pre> 989# enable SSLv3 and TLSv1, but not SSLv2 990SSLProtocol all -SSLv2 991</pre> 992</blockquote> 993<!-- SSLCipherSuite -------------------------------------------------> 994<p> 995<br> 996<a name="SSLCipherSuite"></a> 997<h2><a name="ToC9">SSLCipherSuite</a></h2> 998<table cellspacing="0" cellpadding="1" bgcolor="#cccccc" border="0" summary=""> 999<tr> 1000<td> 1001<table bgcolor="white" width="600" cellspacing="0" cellpadding="5" border="0" summary=""> 1002<tr> 1003<td> 1004<table cellspacing="0" cellpadding="1" border="0" summary=""> 1005<tr><td> 1006<font face="Arial,Helvetica"><b>Name:</b></font></a> </td><td> <b>SSLCipherSuite</b></td></tr> 1007<tr><td> 1008<font face="Arial,Helvetica"><b>Description:</b></font></a> </td><td> Cipher Suite available for negotiation in SSL handshake</td></tr> 1009<tr><td><a 1010 href="../directive-dict.html#Syntax" 1011 rel="Help" 1012><font face="Arial,Helvetica"><b>Syntax:</b></font></a> </td><td> <code>SSLCipherSuite</code> <em>cipher-spec</em></td></tr> 1013<tr><td><a 1014 href="../directive-dict.html#Default" 1015 rel="Help" 1016><font face="Arial,Helvetica"><b>Default:</b></font></a> </td><td> <code>SSLCipherSuite ALL:!ADH:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP</code></td></tr> 1017<tr><td><a 1018 href="../directive-dict.html#Context" 1019 rel="Help" 1020><font face="Arial,Helvetica"><b>Context:</b></font></a> </td><td> server config, virtual host, directory, .htaccess</td></tr> 1021<tr><td><a 1022 href="../directive-dict.html#Override" 1023 rel="Help" 1024><font face="Arial,Helvetica"><b>Override:</b></font></a> </td><td> AuthConfig</td></tr> 1025<tr><td><a 1026 href="../directive-dict.html#Status" 1027 rel="Help" 1028><font face="Arial,Helvetica"><b>Status:</b></font></a> </td><td> Extension</td></tr> 1029<tr><td><a 1030 href="../directive-dict.html#Module" 1031 rel="Help" 1032><font face="Arial,Helvetica"><b>Module:</b></font></a> </td><td> mod_ssl</td></tr> 1033<tr><td><a 1034 href="../directive-dict.html#Compatibility" 1035 rel="Help" 1036><font face="Arial,Helvetica"><b>Compatibility:</b></font></a> </td><td> mod_ssl 2.1 </td></tr> 1037</table> 1038</td> 1039</tr> 1040</table> 1041</td> 1042</tr> 1043</table> 1044<p> 1045This complex directive uses a colon-separated <em>cipher-spec</em> string 1046consisting of OpenSSL cipher specifications to configure the Cipher Suite the 1047client is permitted to negotiate in the SSL handshake phase. Notice that this 1048directive can be used both in per-server and per-directory context. In 1049per-server context it applies to the standard SSL handshake when a connection 1050is established. In per-directory context it forces a SSL renegotation with the 1051reconfigured Cipher Suite after the HTTP request was read but before the HTTP 1052response is sent. 1053<p> 1054An SSL cipher specification in <em>cipher-spec</em> is composed of 4 major 1055attributes plus a few extra minor ones: 1056<ul> 1057<li><em>Key Exchange Algorithm</em>:<br> 1058 RSA or Diffie-Hellman variants. 1059<p> 1060<li><em>Authentication Algorithm</em>:<br> 1061 RSA, Diffie-Hellman, DSS or none. 1062<p> 1063<li><em>Cipher/Encryption Algorithm</em>:<br> 1064 DES, Triple-DES, RC4, RC2, IDEA or none. 1065<p> 1066<li><em>MAC Digest Algorithm</em>:<br> 1067 MD5, SHA or SHA1. 1068</ul> 1069An SSL cipher can also be an export cipher and is either a SSLv2 or SSLv3/TLSv1 1070cipher (here TLSv1 is equivalent to SSLv3). To specify which ciphers to use, 1071one can either specify all the Ciphers, one at a time, or use aliases to 1072specify the preference and order for the ciphers (see <a href="#table1">Table 10731</a>). 1074<p> 1075<div align="center"> 1076<a name="table1"></a> 1077<table width="600" cellspacing="0" cellpadding="1" border="0" summary=""> 1078<caption align="bottom" id="sf">Table 1: OpenSSL Cipher Specification Tags</caption> 1079<tr><td bgcolor="#cccccc"> 1080<table width="598" cellpadding="5" cellspacing="0" border="0" summary=""> 1081<tr><td valign="top" align="center" bgcolor="#ffffff"> 1082<table border="0" cellspacing="0" cellpadding="2" width="598" summary=""> 1083<tr id="D"><td><b>Tag</b></td> <td><b>Description</b></td> 1084<tr id="H"><td colspan="2"><em>Key Exchange Algorithm:</em></td></tr> 1085<tr id="D"><td><code>kRSA</code></td> <td>RSA key exchange</td></tr> 1086<tr id="H"><td><code>kDHr</code></td> <td>Diffie-Hellman key exchange with RSA key</td></tr> 1087<tr id="D"><td><code>kDHd</code></td> <td>Diffie-Hellman key exchange with DSA key</td></tr> 1088<tr id="H"><td><code>kEDH</code></td> <td>Ephemeral (temp.key) Diffie-Hellman key exchange (no cert)</td> </tr> 1089<tr id="H"><td colspan="2"><em>Authentication Algorithm:</em></td></tr> 1090<tr id="D"><td><code>aNULL</code></td> <td>No authentication</td></tr> 1091<tr id="H"><td><code>aRSA</code></td> <td>RSA authentication</td></tr> 1092<tr id="D"><td><code>aDSS</code></td> <td>DSS authentication</td> </tr> 1093<tr id="H"><td><code>aDH</code></td> <td>Diffie-Hellman authentication</td></tr> 1094<tr id="D"><td colspan="2"><em>Cipher Encoding Algorithm:</em></td></tr></tr> 1095<tr id="H"><td><code>eNULL</code></td> <td>No encoding</td> </tr> 1096<tr id="D"><td><code>DES</code></td> <td>DES encoding</td> </tr> 1097<tr id="H"><td><code>3DES</code></td> <td>Triple-DES encoding</td> </tr> 1098<tr id="D"><td><code>RC4</code></td> <td>RC4 encoding</td> </tr> 1099<tr id="H"><td><code>RC2</code></td> <td>RC2 encoding</td> </tr> 1100<tr id="D"><td><code>IDEA</code></td> <td>IDEA encoding</td> </tr> 1101<tr id="H"><td colspan="2"><em>MAC Digest Algorithm</em>:</td></tr> 1102<tr id="D"><td><code>MD5</code></td> <td>MD5 hash function</td></tr> 1103<tr id="H"><td><code>SHA1</code></td> <td>SHA1 hash function</td></tr> 1104<tr id="D"><td><code>SHA</code></td> <td>SHA hash function</td> </tr> 1105<tr id="H"><td colspan="2"><em>Aliases:</em></td></tr> 1106<tr id="D"><td><code>SSLv2</code></td> <td>all SSL version 2.0 ciphers</td></tr> 1107<tr id="H"><td><code>SSLv3</code></td> <td>all SSL version 3.0 ciphers</td> </tr> 1108<tr id="D"><td><code>TLSv1</code></td> <td>all TLS version 1.0 ciphers</td> </tr> 1109<tr id="H"><td><code>EXP</code></td> <td>all export ciphers</td> </tr> 1110<tr id="D"><td><code>EXPORT40</code></td> <td>all 40-bit export ciphers only</td> </tr> 1111<tr id="H"><td><code>EXPORT56</code></td> <td>all 56-bit export ciphers only</td> </tr> 1112<tr id="D"><td><code>LOW</code></td> <td>all low strength ciphers (no export, single DES)</td></tr> 1113<tr id="H"><td><code>MEDIUM</code></td> <td>all ciphers with 128 bit encryption</td> </tr> 1114<tr id="D"><td><code>HIGH</code></td> <td>all ciphers using Triple-DES</td> </tr> 1115<tr id="H"><td><code>RSA</code></td> <td>all ciphers using RSA key exchange</td> </tr> 1116<tr id="D"><td><code>DH</code></td> <td>all ciphers using Diffie-Hellman key exchange</td> </tr> 1117<tr id="H"><td><code>EDH</code></td> <td>all ciphers using Ephemeral Diffie-Hellman key exchange</td> </tr> 1118<tr id="D"><td><code>ADH</code></td> <td>all ciphers using Anonymous Diffie-Hellman key exchange</td> </tr> 1119<tr id="H"><td><code>DSS</code></td> <td>all ciphers using DSS authentication</td> </tr> 1120<tr id="D"><td><code>NULL</code></td> <td>all ciphers using no encryption</td> </tr> 1121</table> 1122</td> 1123</tr></table> 1124</td></tr></table> 1125</div> 1126<p> 1127Now where this becomes interesting is that these can be put together 1128to specify the order and ciphers you wish to use. To speed this up 1129there are also aliases (<code>SSLv2, SSLv3, TLSv1, EXP, LOW, MEDIUM, 1130HIGH</code>) for certain groups of ciphers. These tags can be joined 1131together with prefixes to form the <em>cipher-spec</em>. Available 1132prefixes are: 1133<ul> 1134<li>none: add cipher to list 1135<li><code>+</code>: add ciphers to list and pull them to current location in list 1136<li><code>-</code>: remove cipher from list (can be added later again) 1137<li><code>!</code>: kill cipher from list completely (can <b>not</b> be added later again) 1138</ul> 1139A simpler way to look at all of this is to use the ``<code>openssl ciphers 1140-v</code>'' command which provides a nice way to successively create the 1141correct <em>cipher-spec</em> string. The default <em>cipher-spec</em> string 1142is ``<code>ALL:!ADH:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP</code>'' which 1143means the following: first, remove from consideration any ciphers that do not 1144authenticate, i.e. for SSL only the Anonymous Diffie-Hellman ciphers. Next, 1145use ciphers using RC4 and RSA. Next include the high, medium and then the low 1146security ciphers. Finally <em>pull</em> all SSLv2 and export ciphers to the 1147end of the list. 1148<blockquote> 1149<pre> 1150$ openssl ciphers -v 'ALL:!ADH:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP' 1151NULL-SHA SSLv3 Kx=RSA Au=RSA Enc=None Mac=SHA1 1152NULL-MD5 SSLv3 Kx=RSA Au=RSA Enc=None Mac=MD5 1153EDH-RSA-DES-CBC3-SHA SSLv3 Kx=DH Au=RSA Enc=3DES(168) Mac=SHA1 1154... ... ... ... ... 1155EXP-RC4-MD5 SSLv3 Kx=RSA(512) Au=RSA Enc=RC4(40) Mac=MD5 export 1156EXP-RC2-CBC-MD5 SSLv2 Kx=RSA(512) Au=RSA Enc=RC2(40) Mac=MD5 export 1157EXP-RC4-MD5 SSLv2 Kx=RSA(512) Au=RSA Enc=RC4(40) Mac=MD5 export 1158</pre> 1159</blockquote> 1160The complete list of particular RSA & DH ciphers for SSL is given in <a 1161href="#table2">Table 2</a>. 1162<p> 1163Example: 1164<blockquote> 1165<pre> 1166SSLCipherSuite RSA:!EXP:!NULL:+HIGH:+MEDIUM:-LOW 1167</pre> 1168</blockquote> 1169<p> 1170<div align="center"> 1171<a name="table2"></a> 1172<table width="600" cellspacing="0" cellpadding="1" border="0" summary=""> 1173<caption align="bottom" id="sf">Table 2: Particular SSL Ciphers</caption> 1174<tr><td bgcolor="#cccccc"> 1175<table width="598" cellpadding="5" cellspacing="0" border="0" summary=""> 1176<tr><td valign="top" align="center" bgcolor="#ffffff"> 1177<table border="0" cellspacing="0" cellpadding="2" width="598" summary=""> 1178<tr id="D"><td><b>Cipher-Tag</b></td> <td><b>Protocol</b></td> <td><b>Key Ex.</b></td> <td><b>Auth.</b></td> <td><b>Enc.</b></td> <td><b>MAC</b></td> <td><b>Type</b></td> </tr> 1179<tr id="H"><td colspan="7"><em>RSA Ciphers:</em></td></tr> 1180<tr id="D"><td><code>DES-CBC3-SHA</code></td> <td>SSLv3</td> <td>RSA</td> <td>RSA</td> <td>3DES(168)</td> <td>SHA1</td> <td> </td> </tr> 1181<tr id="H"><td><code>DES-CBC3-MD5</code></td> <td>SSLv2</td> <td>RSA</td> <td>RSA</td> <td>3DES(168)</td> <td>MD5</td> <td> </td> </tr> 1182<tr id="D"><td><code>IDEA-CBC-SHA</code></td> <td>SSLv3</td> <td>RSA</td> <td>RSA</td> <td>IDEA(128)</td> <td>SHA1</td> <td> </td> </tr> 1183<tr id="H"><td><code>RC4-SHA</code></td> <td>SSLv3</td> <td>RSA</td> <td>RSA</td> <td>RC4(128)</td> <td>SHA1</td> <td> </td> </tr> 1184<tr id="D"><td><code>RC4-MD5</code></td> <td>SSLv3</td> <td>RSA</td> <td>RSA</td> <td>RC4(128)</td> <td>MD5</td> <td> </td> </tr> 1185<tr id="H"><td><code>IDEA-CBC-MD5</code></td> <td>SSLv2</td> <td>RSA</td> <td>RSA</td> <td>IDEA(128)</td> <td>MD5</td> <td> </td> </tr> 1186<tr id="D"><td><code>RC2-CBC-MD5</code></td> <td>SSLv2</td> <td>RSA</td> <td>RSA</td> <td>RC2(128)</td> <td>MD5</td> <td> </td> </tr> 1187<tr id="H"><td><code>RC4-MD5</code></td> <td>SSLv2</td> <td>RSA</td> <td>RSA</td> <td>RC4(128)</td> <td>MD5</td> <td> </td> </tr> 1188<tr id="D"><td><code>DES-CBC-SHA</code></td> <td>SSLv3</td> <td>RSA</td> <td>RSA</td> <td>DES(56)</td> <td>SHA1</td> <td> </td> </tr> 1189<tr id="H"><td><code>RC4-64-MD5</code></td> <td>SSLv2</td> <td>RSA</td> <td>RSA</td> <td>RC4(64)</td> <td>MD5</td> <td> </td> </tr> 1190<tr id="D"><td><code>DES-CBC-MD5</code></td> <td>SSLv2</td> <td>RSA</td> <td>RSA</td> <td>DES(56)</td> <td>MD5</td> <td> </td> </tr> 1191<tr id="H"><td><code>EXP-DES-CBC-SHA</code></td> <td>SSLv3</td> <td>RSA(512)</td> <td>RSA</td> <td>DES(40)</td> <td>SHA1</td> <td> export</td> </tr> 1192<tr id="D"><td><code>EXP-RC2-CBC-MD5</code></td> <td>SSLv3</td> <td>RSA(512)</td> <td>RSA</td> <td>RC2(40)</td> <td>MD5</td> <td> export</td> </tr> 1193<tr id="H"><td><code>EXP-RC4-MD5</code></td> <td>SSLv3</td> <td>RSA(512)</td> <td>RSA</td> <td>RC4(40)</td> <td>MD5</td> <td> export</td> </tr> 1194<tr id="D"><td><code>EXP-RC2-CBC-MD5</code></td> <td>SSLv2</td> <td>RSA(512)</td> <td>RSA</td> <td>RC2(40)</td> <td>MD5</td> <td> export</td> </tr> 1195<tr id="H"><td><code>EXP-RC4-MD5</code></td> <td>SSLv2</td> <td>RSA(512)</td> <td>RSA</td> <td>RC4(40)</td> <td>MD5</td> <td> export</td> </tr> 1196<tr id="D"><td><code>NULL-SHA</code></td> <td>SSLv3</td> <td>RSA</td> <td>RSA</td> <td>None</td> <td>SHA1</td> <td> </td> </tr> 1197<tr id="H"><td><code>NULL-MD5</code></td> <td>SSLv3</td> <td>RSA</td> <td>RSA</td> <td>None</td> <td>MD5</td> <td> </td> </tr> 1198<tr id="D"><td colspan="7"><em>Diffie-Hellman Ciphers:</em></td></tr> 1199<tr id="H"><td><code>ADH-DES-CBC3-SHA</code></td> <td>SSLv3</td> <td>DH</td> <td>None</td> <td>3DES(168)</td> <td>SHA1</td> <td> </td> </tr> 1200<tr id="D"><td><code>ADH-DES-CBC-SHA</code></td> <td>SSLv3</td> <td>DH</td> <td>None</td> <td>DES(56)</td> <td>SHA1</td> <td> </td> </tr> 1201<tr id="H"><td><code>ADH-RC4-MD5</code></td> <td>SSLv3</td> <td>DH</td> <td>None</td> <td>RC4(128)</td> <td>MD5</td> <td> </td> </tr> 1202<tr id="D"><td><code>EDH-RSA-DES-CBC3-SHA</code></td> <td>SSLv3</td> <td>DH</td> <td>RSA</td> <td>3DES(168)</td> <td>SHA1</td> <td> </td> </tr> 1203<tr id="H"><td><code>EDH-DSS-DES-CBC3-SHA</code></td> <td>SSLv3</td> <td>DH</td> <td>DSS</td> <td>3DES(168)</td> <td>SHA1</td> <td> </td> </tr> 1204<tr id="D"><td><code>EDH-RSA-DES-CBC-SHA</code></td> <td>SSLv3</td> <td>DH</td> <td>RSA</td> <td>DES(56)</td> <td>SHA1</td> <td> </td> </tr> 1205<tr id="H"><td><code>EDH-DSS-DES-CBC-SHA</code></td> <td>SSLv3</td> <td>DH</td> <td>DSS</td> <td>DES(56)</td> <td>SHA1</td> <td> </td> </tr> 1206<tr id="D"><td><code>EXP-EDH-RSA-DES-CBC-SHA</code></td> <td>SSLv3</td> <td>DH(512)</td> <td>RSA</td> <td>DES(40)</td> <td>SHA1</td> <td> export</td> </tr> 1207<tr id="H"><td><code>EXP-EDH-DSS-DES-CBC-SHA</code></td> <td>SSLv3</td> <td>DH(512)</td> <td>DSS</td> <td>DES(40)</td> <td>SHA1</td> <td> export</td> </tr> 1208<tr id="D"><td><code>EXP-ADH-DES-CBC-SHA</code></td> <td>SSLv3</td> <td>DH(512)</td> <td>None</td> <td>DES(40)</td> <td>SHA1</td> <td> export</td> </tr> 1209<tr id="H"><td><code>EXP-ADH-RC4-MD5</code></td> <td>SSLv3</td> <td>DH(512)</td> <td>None</td> <td>RC4(40)</td> <td>MD5</td> <td> export</td> </tr> 1210</table> 1211</td> 1212</tr></table> 1213</td></tr></table> 1214</div> 1215<!-- SSLCertificateFile ---------------------------------------------> 1216<p> 1217<br> 1218<a name="SSLCertificateFile"></a> 1219<h2><a name="ToC10">SSLCertificateFile</a></h2> 1220<table cellspacing="0" cellpadding="1" bgcolor="#cccccc" border="0" summary=""> 1221<tr> 1222<td> 1223<table bgcolor="white" width="600" cellspacing="0" cellpadding="5" border="0" summary=""> 1224<tr> 1225<td> 1226<table cellspacing="0" cellpadding="1" border="0" summary=""> 1227<tr><td> 1228<font face="Arial,Helvetica"><b>Name:</b></font></a> </td><td> <b>SSLCertificateFile</b></td></tr> 1229<tr><td> 1230<font face="Arial,Helvetica"><b>Description:</b></font></a> </td><td> Server PEM-encoded X.509 Certificate file</td></tr> 1231<tr><td><a 1232 href="../directive-dict.html#Syntax" 1233 rel="Help" 1234><font face="Arial,Helvetica"><b>Syntax:</b></font></a> </td><td> <code>SSLCertificateFile</code> <em>filename</em></td></tr> 1235<tr><td><a 1236 href="../directive-dict.html#Default" 1237 rel="Help" 1238><font face="Arial,Helvetica"><b>Default:</b></font></a> </td><td> <em>None</em></td></tr> 1239<tr><td><a 1240 href="../directive-dict.html#Context" 1241 rel="Help" 1242><font face="Arial,Helvetica"><b>Context:</b></font></a> </td><td> server config, virtual host</td></tr> 1243<tr><td><a 1244 href="../directive-dict.html#Override" 1245 rel="Help" 1246><font face="Arial,Helvetica"><b>Override:</b></font></a> </td><td> <em>Not applicable</em></td></tr> 1247<tr><td><a 1248 href="../directive-dict.html#Status" 1249 rel="Help" 1250><font face="Arial,Helvetica"><b>Status:</b></font></a> </td><td> Extension</td></tr> 1251<tr><td><a 1252 href="../directive-dict.html#Module" 1253 rel="Help" 1254><font face="Arial,Helvetica"><b>Module:</b></font></a> </td><td> mod_ssl</td></tr> 1255<tr><td><a 1256 href="../directive-dict.html#Compatibility" 1257 rel="Help" 1258><font face="Arial,Helvetica"><b>Compatibility:</b></font></a> </td><td> mod_ssl 2.0 </td></tr> 1259</table> 1260</td> 1261</tr> 1262</table> 1263</td> 1264</tr> 1265</table> 1266<p> 1267This directive points to the PEM-encoded Certificate file for the server and 1268optionally also to the corresponding RSA or DSA Private Key file for it 1269(contained in the same file). If the contained Private Key is encrypted the 1270Pass Phrase dialog is forced at startup time. This directive can be used up to 1271two times (referencing different filenames) when both a RSA and a DSA based 1272server certificate is used in parallel. 1273<p> 1274Example: 1275<blockquote> 1276<pre> 1277SSLCertificateFile /usr/local/apache/conf/ssl.crt/server.crt 1278</pre> 1279</blockquote> 1280<!-- SSLCertificateKeyFile ------------------------------------------> 1281<p> 1282<br> 1283<a name="SSLCertificateKeyFile"></a> 1284<h2><a name="ToC11">SSLCertificateKeyFile</a></h2> 1285<table cellspacing="0" cellpadding="1" bgcolor="#cccccc" border="0" summary=""> 1286<tr> 1287<td> 1288<table bgcolor="white" width="600" cellspacing="0" cellpadding="5" border="0" summary=""> 1289<tr> 1290<td> 1291<table cellspacing="0" cellpadding="1" border="0" summary=""> 1292<tr><td> 1293<font face="Arial,Helvetica"><b>Name:</b></font></a> </td><td> <b>SSLCertificateKeyFile</b></td></tr> 1294<tr><td> 1295<font face="Arial,Helvetica"><b>Description:</b></font></a> </td><td> Server PEM-encoded Private Key file</td></tr> 1296<tr><td><a 1297 href="../directive-dict.html#Syntax" 1298 rel="Help" 1299><font face="Arial,Helvetica"><b>Syntax:</b></font></a> </td><td> <code>SSLCertificateKeyFile</code> <em>filename</em></td></tr> 1300<tr><td><a 1301 href="../directive-dict.html#Default" 1302 rel="Help" 1303><font face="Arial,Helvetica"><b>Default:</b></font></a> </td><td> <em>None</em></td></tr> 1304<tr><td><a 1305 href="../directive-dict.html#Context" 1306 rel="Help" 1307><font face="Arial,Helvetica"><b>Context:</b></font></a> </td><td> server config, virtual host</td></tr> 1308<tr><td><a 1309 href="../directive-dict.html#Override" 1310 rel="Help" 1311><font face="Arial,Helvetica"><b>Override:</b></font></a> </td><td> <em>Not applicable</em></td></tr> 1312<tr><td><a 1313 href="../directive-dict.html#Status" 1314 rel="Help" 1315><font face="Arial,Helvetica"><b>Status:</b></font></a> </td><td> Extension</td></tr> 1316<tr><td><a 1317 href="../directive-dict.html#Module" 1318 rel="Help" 1319><font face="Arial,Helvetica"><b>Module:</b></font></a> </td><td> mod_ssl</td></tr> 1320<tr><td><a 1321 href="../directive-dict.html#Compatibility" 1322 rel="Help" 1323><font face="Arial,Helvetica"><b>Compatibility:</b></font></a> </td><td> mod_ssl 2.0 </td></tr> 1324</table> 1325</td> 1326</tr> 1327</table> 1328</td> 1329</tr> 1330</table> 1331<p> 1332This directive points to the PEM-encoded Private Key file for the server. If 1333the Private Key is not combined with the Certificate in the 1334<code>SSLCertificateFile</code>, use this additional directive to point to the 1335file with the stand-alone Private Key. When <code>SSLCertificateFile</code> 1336is used and the file contains both the Certificate and the Private Key this 1337directive need not be used. But we strongly discourage this practice. 1338Instead we recommend you to separate the Certificate and the Private Key. If 1339the contained Private Key is encrypted, the Pass Phrase dialog is forced at 1340startup time. This directive can be used up to two times (referencing 1341different filenames) when both a RSA and a DSA based private key is used in 1342parallel. 1343<p> 1344Example: 1345<blockquote> 1346<pre> 1347SSLCertificateKeyFile /usr/local/apache/conf/ssl.key/server.key 1348</pre> 1349</blockquote> 1350<!-- SSLCertificateChainFile ----------------------------------------> 1351<p> 1352<br> 1353<a name="SSLCertificateChainFile"></a> 1354<h2><a name="ToC12">SSLCertificateChainFile</a></h2> 1355<table cellspacing="0" cellpadding="1" bgcolor="#cccccc" border="0" summary=""> 1356<tr> 1357<td> 1358<table bgcolor="white" width="600" cellspacing="0" cellpadding="5" border="0" summary=""> 1359<tr> 1360<td> 1361<table cellspacing="0" cellpadding="1" border="0" summary=""> 1362<tr><td> 1363<font face="Arial,Helvetica"><b>Name:</b></font></a> </td><td> <b>SSLCertificateChainFile</b></td></tr> 1364<tr><td> 1365<font face="Arial,Helvetica"><b>Description:</b></font></a> </td><td> File of PEM-encoded Server CA Certificates</td></tr> 1366<tr><td><a 1367 href="../directive-dict.html#Syntax" 1368 rel="Help" 1369><font face="Arial,Helvetica"><b>Syntax:</b></font></a> </td><td> <code>SSLCertificateChainFile</code> <em>filename</em></td></tr> 1370<tr><td><a 1371 href="../directive-dict.html#Default" 1372 rel="Help" 1373><font face="Arial,Helvetica"><b>Default:</b></font></a> </td><td> <em>None</em></td></tr> 1374<tr><td><a 1375 href="../directive-dict.html#Context" 1376 rel="Help" 1377><font face="Arial,Helvetica"><b>Context:</b></font></a> </td><td> server config, virtual host</td></tr> 1378<tr><td><a 1379 href="../directive-dict.html#Override" 1380 rel="Help" 1381><font face="Arial,Helvetica"><b>Override:</b></font></a> </td><td> <em>Not applicable</em></td></tr> 1382<tr><td><a 1383 href="../directive-dict.html#Status" 1384 rel="Help" 1385><font face="Arial,Helvetica"><b>Status:</b></font></a> </td><td> Extension</td></tr> 1386<tr><td><a 1387 href="../directive-dict.html#Module" 1388 rel="Help" 1389><font face="Arial,Helvetica"><b>Module:</b></font></a> </td><td> mod_ssl</td></tr> 1390<tr><td><a 1391 href="../directive-dict.html#Compatibility" 1392 rel="Help" 1393><font face="Arial,Helvetica"><b>Compatibility:</b></font></a> </td><td> mod_ssl 2.3.6 </td></tr> 1394</table> 1395</td> 1396</tr> 1397</table> 1398</td> 1399</tr> 1400</table> 1401<p> 1402This directive sets the optional <em>all-in-one</em> file where you can 1403assemble the certificates of Certification Authorities (CA) which form the 1404certificate chain of the server certificate. This starts with the issuing CA 1405certificate of of the server certificate and can range up to the root CA 1406certificate. Such a file is simply the concatenation of the various 1407PEM-encoded CA Certificate files, usually in certificate chain order. 1408<p> 1409This should be used alternatively and/or additionally to <a 1410href="#SSLCACertificatePath">SSLCACertificatePath</a> for explicitly 1411constructing the server certificate chain which is sent to the browser in 1412addition to the server certificate. It is especially useful to avoid conflicts 1413with CA certificates when using client authentication. Because although 1414placing a CA certificate of the server certificate chain into <a 1415href="#SSLCACertificatePath">SSLCACertificatePath</a> has the same effect for 1416the certificate chain construction, it has the side-effect that client 1417certificates issued by this same CA certificate are also accepted on client 1418authentication. That's usually not one expect. 1419<p> 1420But be careful: Providing the certificate chain works only if you are using a 1421<i>single</i> (either RSA <i>or</i> DSA) based server certificate. If you are 1422using a coupled RSA+DSA certificate pair, this will work only if actually both 1423certificates use the <i>same</i> certificate chain. Else the browsers will be 1424confused in this situation. 1425<p> 1426Example: 1427<blockquote> 1428<pre> 1429SSLCertificateChainFile /usr/local/apache/conf/ssl.crt/ca.crt 1430</pre> 1431</blockquote> 1432<!-- SSLCACertificatePath -------------------------------------------> 1433<p> 1434<br> 1435<a name="SSLCACertificatePath"></a> 1436<h2><a name="ToC13">SSLCACertificatePath</a></h2> 1437<table cellspacing="0" cellpadding="1" bgcolor="#cccccc" border="0" summary=""> 1438<tr> 1439<td> 1440<table bgcolor="white" width="600" cellspacing="0" cellpadding="5" border="0" summary=""> 1441<tr> 1442<td> 1443<table cellspacing="0" cellpadding="1" border="0" summary=""> 1444<tr><td> 1445<font face="Arial,Helvetica"><b>Name:</b></font></a> </td><td> <b>SSLCACertificatePath</b></td></tr> 1446<tr><td> 1447<font face="Arial,Helvetica"><b>Description:</b></font></a> </td><td> Directory of PEM-encoded CA Certificates for Client Auth.</td></tr> 1448<tr><td><a 1449 href="../directive-dict.html#Syntax" 1450 rel="Help" 1451><font face="Arial,Helvetica"><b>Syntax:</b></font></a> </td><td> <code>SSLCACertificatePath</code> <em>directory</em></td></tr> 1452<tr><td><a 1453 href="../directive-dict.html#Default" 1454 rel="Help" 1455><font face="Arial,Helvetica"><b>Default:</b></font></a> </td><td> <em>None</em></td></tr> 1456<tr><td><a 1457 href="../directive-dict.html#Context" 1458 rel="Help" 1459><font face="Arial,Helvetica"><b>Context:</b></font></a> </td><td> server config, virtual host</td></tr> 1460<tr><td><a 1461 href="../directive-dict.html#Override" 1462 rel="Help" 1463><font face="Arial,Helvetica"><b>Override:</b></font></a> </td><td> <em>Not applicable</em></td></tr> 1464<tr><td><a 1465 href="../directive-dict.html#Status" 1466 rel="Help" 1467><font face="Arial,Helvetica"><b>Status:</b></font></a> </td><td> Extension</td></tr> 1468<tr><td><a 1469 href="../directive-dict.html#Module" 1470 rel="Help" 1471><font face="Arial,Helvetica"><b>Module:</b></font></a> </td><td> mod_ssl</td></tr> 1472<tr><td><a 1473 href="../directive-dict.html#Compatibility" 1474 rel="Help" 1475><font face="Arial,Helvetica"><b>Compatibility:</b></font></a> </td><td> mod_ssl 2.0 </td></tr> 1476</table> 1477</td> 1478</tr> 1479</table> 1480</td> 1481</tr> 1482</table> 1483<p> 1484This directive sets the directory where you keep the Certificates of 1485Certification Authorities (CAs) whose clients you deal with. These are used to 1486verify the client certificate on Client Authentication. 1487<p> 1488The files in this directory have to be PEM-encoded and are accessed through 1489hash filenames. So usually you can't just place the Certificate files 1490there: you also have to create symbolic links named 1491<i>hash-value</i><tt>.N</tt>. And you should always make sure this directory 1492contains the appropriate symbolic links. Use the <code>Makefile</code> which 1493comes with mod_ssl to accomplish this task. 1494<p> 1495Example: 1496<blockquote> 1497<pre> 1498SSLCACertificatePath /usr/local/apache/conf/ssl.crt/ 1499</pre> 1500</blockquote> 1501<!-- SSLCACertificateFile -------------------------------------------> 1502<p> 1503<br> 1504<a name="SSLCACertificateFile"></a> 1505<h2><a name="ToC14">SSLCACertificateFile</a></h2> 1506<table cellspacing="0" cellpadding="1" bgcolor="#cccccc" border="0" summary=""> 1507<tr> 1508<td> 1509<table bgcolor="white" width="600" cellspacing="0" cellpadding="5" border="0" summary=""> 1510<tr> 1511<td> 1512<table cellspacing="0" cellpadding="1" border="0" summary=""> 1513<tr><td> 1514<font face="Arial,Helvetica"><b>Name:</b></font></a> </td><td> <b>SSLCACertificateFile</b></td></tr> 1515<tr><td> 1516<font face="Arial,Helvetica"><b>Description:</b></font></a> </td><td> File of concatenated PEM-encoded CA Certificates for Client Auth.</td></tr> 1517<tr><td><a 1518 href="../directive-dict.html#Syntax" 1519 rel="Help" 1520><font face="Arial,Helvetica"><b>Syntax:</b></font></a> </td><td> <code>SSLCACertificateFile</code> <em>filename</em></td></tr> 1521<tr><td><a 1522 href="../directive-dict.html#Default" 1523 rel="Help" 1524><font face="Arial,Helvetica"><b>Default:</b></font></a> </td><td> <em>None</em></td></tr> 1525<tr><td><a 1526 href="../directive-dict.html#Context" 1527 rel="Help" 1528><font face="Arial,Helvetica"><b>Context:</b></font></a> </td><td> server config, virtual host</td></tr> 1529<tr><td><a 1530 href="../directive-dict.html#Override" 1531 rel="Help" 1532><font face="Arial,Helvetica"><b>Override:</b></font></a> </td><td> <em>Not applicable</em></td></tr> 1533<tr><td><a 1534 href="../directive-dict.html#Status" 1535 rel="Help" 1536><font face="Arial,Helvetica"><b>Status:</b></font></a> </td><td> Extension</td></tr> 1537<tr><td><a 1538 href="../directive-dict.html#Module" 1539 rel="Help" 1540><font face="Arial,Helvetica"><b>Module:</b></font></a> </td><td> mod_ssl</td></tr> 1541<tr><td><a 1542 href="../directive-dict.html#Compatibility" 1543 rel="Help" 1544><font face="Arial,Helvetica"><b>Compatibility:</b></font></a> </td><td> mod_ssl 2.0 </td></tr> 1545</table> 1546</td> 1547</tr> 1548</table> 1549</td> 1550</tr> 1551</table> 1552<p> 1553This directive sets the <em>all-in-one</em> file where you can assemble the 1554Certificates of Certification Authorities (CA) whose <em>clients</em> you deal 1555with. These are used for Client Authentication. Such a file is simply the 1556concatenation of the various PEM-encoded Certificate files, in order of 1557preference. This can be used alternatively and/or additionally to <a 1558href="#SSLCACertificatePath">SSLCACertificatePath</a>. 1559<p> 1560Example: 1561<blockquote> 1562<pre> 1563SSLCACertificateFile /usr/local/apache/conf/ssl.crt/ca-bundle-client.crt 1564</pre> 1565</blockquote> 1566<!-- SSLCARevocationPath --------------------------------------------> 1567<p> 1568<br> 1569<a name="SSLCARevocationPath"></a> 1570<h2><a name="ToC15">SSLCARevocationPath</a></h2> 1571<table cellspacing="0" cellpadding="1" bgcolor="#cccccc" border="0" summary=""> 1572<tr> 1573<td> 1574<table bgcolor="white" width="600" cellspacing="0" cellpadding="5" border="0" summary=""> 1575<tr> 1576<td> 1577<table cellspacing="0" cellpadding="1" border="0" summary=""> 1578<tr><td> 1579<font face="Arial,Helvetica"><b>Name:</b></font></a> </td><td> <b>SSLCARevocationPath</b></td></tr> 1580<tr><td> 1581<font face="Arial,Helvetica"><b>Description:</b></font></a> </td><td> Directory of PEM-encoded CA CRLs for Client Auth.</td></tr> 1582<tr><td><a 1583 href="../directive-dict.html#Syntax" 1584 rel="Help" 1585><font face="Arial,Helvetica"><b>Syntax:</b></font></a> </td><td> <code>SSLCARevocationPath</code> <em>directory</em></td></tr> 1586<tr><td><a 1587 href="../directive-dict.html#Default" 1588 rel="Help" 1589><font face="Arial,Helvetica"><b>Default:</b></font></a> </td><td> <em>None</em></td></tr> 1590<tr><td><a 1591 href="../directive-dict.html#Context" 1592 rel="Help" 1593><font face="Arial,Helvetica"><b>Context:</b></font></a> </td><td> server config, virtual host</td></tr> 1594<tr><td><a 1595 href="../directive-dict.html#Override" 1596 rel="Help" 1597><font face="Arial,Helvetica"><b>Override:</b></font></a> </td><td> <em>Not applicable</em></td></tr> 1598<tr><td><a 1599 href="../directive-dict.html#Status" 1600 rel="Help" 1601><font face="Arial,Helvetica"><b>Status:</b></font></a> </td><td> Extension</td></tr> 1602<tr><td><a 1603 href="../directive-dict.html#Module" 1604 rel="Help" 1605><font face="Arial,Helvetica"><b>Module:</b></font></a> </td><td> mod_ssl</td></tr> 1606<tr><td><a 1607 href="../directive-dict.html#Compatibility" 1608 rel="Help" 1609><font face="Arial,Helvetica"><b>Compatibility:</b></font></a> </td><td> mod_ssl 2.3 </td></tr> 1610</table> 1611</td> 1612</tr> 1613</table> 1614</td> 1615</tr> 1616</table> 1617<p> 1618This directive sets the directory where you keep the Certificate Revocation 1619Lists (CRL) of Certification Authorities (CAs) whose clients you deal with. 1620These are used to revoke the client certificate on Client Authentication. 1621<p> 1622The files in this directory have to be PEM-encoded and are accessed through 1623hash filenames. So usually you have not only to place the CRL files there. 1624Additionally you have to create symbolic links named 1625<i>hash-value</i><tt>.rN</tt>. And you should always make sure this directory 1626contains the appropriate symbolic links. Use the <code>Makefile</code> which 1627comes with mod_ssl to accomplish this task. 1628<p> 1629Example: 1630<blockquote> 1631<pre> 1632SSLCARevocationPath /usr/local/apache/conf/ssl.crl/ 1633</pre> 1634</blockquote> 1635<!-- SSLCARevocationFile --------------------------------------------> 1636<p> 1637<br> 1638<a name="SSLCARevocationFile"></a> 1639<h2><a name="ToC16">SSLCARevocationFile</a></h2> 1640<table cellspacing="0" cellpadding="1" bgcolor="#cccccc" border="0" summary=""> 1641<tr> 1642<td> 1643<table bgcolor="white" width="600" cellspacing="0" cellpadding="5" border="0" summary=""> 1644<tr> 1645<td> 1646<table cellspacing="0" cellpadding="1" border="0" summary=""> 1647<tr><td> 1648<font face="Arial,Helvetica"><b>Name:</b></font></a> </td><td> <b>SSLCARevocationFile</b></td></tr> 1649<tr><td> 1650<font face="Arial,Helvetica"><b>Description:</b></font></a> </td><td> File of concatenated PEM-encoded CA CRLs for Client Auth.</td></tr> 1651<tr><td><a 1652 href="../directive-dict.html#Syntax" 1653 rel="Help" 1654><font face="Arial,Helvetica"><b>Syntax:</b></font></a> </td><td> <code>SSLCARevocationFile</code> <em>filename</em></td></tr> 1655<tr><td><a 1656 href="../directive-dict.html#Default" 1657 rel="Help" 1658><font face="Arial,Helvetica"><b>Default:</b></font></a> </td><td> <em>None</em></td></tr> 1659<tr><td><a 1660 href="../directive-dict.html#Context" 1661 rel="Help" 1662><font face="Arial,Helvetica"><b>Context:</b></font></a> </td><td> server config, virtual host</td></tr> 1663<tr><td><a 1664 href="../directive-dict.html#Override" 1665 rel="Help" 1666><font face="Arial,Helvetica"><b>Override:</b></font></a> </td><td> <em>Not applicable</em></td></tr> 1667<tr><td><a 1668 href="../directive-dict.html#Status" 1669 rel="Help" 1670><font face="Arial,Helvetica"><b>Status:</b></font></a> </td><td> Extension</td></tr> 1671<tr><td><a 1672 href="../directive-dict.html#Module" 1673 rel="Help" 1674><font face="Arial,Helvetica"><b>Module:</b></font></a> </td><td> mod_ssl</td></tr> 1675<tr><td><a 1676 href="../directive-dict.html#Compatibility" 1677 rel="Help" 1678><font face="Arial,Helvetica"><b>Compatibility:</b></font></a> </td><td> mod_ssl 2.3 </td></tr> 1679</table> 1680</td> 1681</tr> 1682</table> 1683</td> 1684</tr> 1685</table> 1686<p> 1687This directive sets the <em>all-in-one</em> file where you can assemble the 1688Certificate Revocation Lists (CRL) of Certification Authorities (CA) whose 1689<em>clients</em> you deal with. These are used for Client Authentication. 1690Such a file is simply the concatenation of the various PEM-encoded CRL 1691files, in order of preference. This can be used alternatively and/or 1692additionally to <a href="#SSLCARevocationPath">SSLCARevocationPath</a>. 1693<p> 1694Example: 1695<blockquote> 1696<pre> 1697SSLCARevocationFile /usr/local/apache/conf/ssl.crl/ca-bundle-client.crl 1698</pre> 1699</blockquote> 1700<!-- SSLVerifyClient -------------------------------------------------> 1701<p> 1702<br> 1703<a name="SSLVerifyClient"></a> 1704<h2><a name="ToC17">SSLVerifyClient</a></h2> 1705<table cellspacing="0" cellpadding="1" bgcolor="#cccccc" border="0" summary=""> 1706<tr> 1707<td> 1708<table bgcolor="white" width="600" cellspacing="0" cellpadding="5" border="0" summary=""> 1709<tr> 1710<td> 1711<table cellspacing="0" cellpadding="1" border="0" summary=""> 1712<tr><td> 1713<font face="Arial,Helvetica"><b>Name:</b></font></a> </td><td> <b>SSLVerifyClient</b></td></tr> 1714<tr><td> 1715<font face="Arial,Helvetica"><b>Description:</b></font></a> </td><td> Type of Client Certificate verification</td></tr> 1716<tr><td><a 1717 href="../directive-dict.html#Syntax" 1718 rel="Help" 1719><font face="Arial,Helvetica"><b>Syntax:</b></font></a> </td><td> <code>SSLVerifyClient</code> <em>level</em></td></tr> 1720<tr><td><a 1721 href="../directive-dict.html#Default" 1722 rel="Help" 1723><font face="Arial,Helvetica"><b>Default:</b></font></a> </td><td> <code>SSLVerifyClient none</code></td></tr> 1724<tr><td><a 1725 href="../directive-dict.html#Context" 1726 rel="Help" 1727><font face="Arial,Helvetica"><b>Context:</b></font></a> </td><td> server config, virtual host, directory, .htaccess</td></tr> 1728<tr><td><a 1729 href="../directive-dict.html#Override" 1730 rel="Help" 1731><font face="Arial,Helvetica"><b>Override:</b></font></a> </td><td> AuthConfig</td></tr> 1732<tr><td><a 1733 href="../directive-dict.html#Status" 1734 rel="Help" 1735><font face="Arial,Helvetica"><b>Status:</b></font></a> </td><td> Extension</td></tr> 1736<tr><td><a 1737 href="../directive-dict.html#Module" 1738 rel="Help" 1739><font face="Arial,Helvetica"><b>Module:</b></font></a> </td><td> mod_ssl</td></tr> 1740<tr><td><a 1741 href="../directive-dict.html#Compatibility" 1742 rel="Help" 1743><font face="Arial,Helvetica"><b>Compatibility:</b></font></a> </td><td> mod_ssl 2.0 </td></tr> 1744</table> 1745</td> 1746</tr> 1747</table> 1748</td> 1749</tr> 1750</table> 1751<p> 1752This directive sets the Certificate verification level for the Client 1753Authentication. Notice that this directive can be used both in per-server and 1754per-directory context. In per-server context it applies to the client 1755authentication process used in the standard SSL handshake when a connection is 1756established. In per-directory context it forces a SSL renegotation with the 1757reconfigured client verification level after the HTTP request was read but 1758before the HTTP response is sent. 1759<p> 1760The following levels are available for <em>level</em>: 1761<ul> 1762<li><strong>none</strong>: 1763 no client Certificate is required at all 1764<li><strong>optional</strong>: 1765 the client <em>may</em> present a valid Certificate 1766<li><strong>require</strong>: 1767 the client <em>has to</em> present a valid Certificate 1768<li><strong>optional_no_ca</strong>: 1769 the client may present a valid Certificate<br> 1770 but it need not to be (successfully) verifiable. 1771</ul> 1772In practice only levels <strong>none</strong> and <strong>require</strong> are 1773really interesting, because level <strong>optional</strong> doesn't work with 1774all browsers and level <strong>optional_no_ca</strong> is actually against the 1775idea of authentication (but can be used to establish SSL test pages, etc.) 1776<p> 1777Example: 1778<blockquote> 1779<pre> 1780SSLVerifyClient require 1781</pre> 1782</blockquote> 1783<!-- SSLVerifyDepth -------------------------------------------------> 1784<p> 1785<br> 1786<a name="SSLVerifyDepth"></a> 1787<h2><a name="ToC18">SSLVerifyDepth</a></h2> 1788<table cellspacing="0" cellpadding="1" bgcolor="#cccccc" border="0" summary=""> 1789<tr> 1790<td> 1791<table bgcolor="white" width="600" cellspacing="0" cellpadding="5" border="0" summary=""> 1792<tr> 1793<td> 1794<table cellspacing="0" cellpadding="1" border="0" summary=""> 1795<tr><td> 1796<font face="Arial,Helvetica"><b>Name:</b></font></a> </td><td> <b>SSLVerifyDepth</b></td></tr> 1797<tr><td> 1798<font face="Arial,Helvetica"><b>Description:</b></font></a> </td><td> Maximum depth of CA Certificates in Client Certificate verification</td></tr> 1799<tr><td><a 1800 href="../directive-dict.html#Syntax" 1801 rel="Help" 1802><font face="Arial,Helvetica"><b>Syntax:</b></font></a> </td><td> <code>SSLVerifyDepth</code> <em>number</em></td></tr> 1803<tr><td><a 1804 href="../directive-dict.html#Default" 1805 rel="Help" 1806><font face="Arial,Helvetica"><b>Default:</b></font></a> </td><td> <code>SSLVerifyDepth 1</code></td></tr> 1807<tr><td><a 1808 href="../directive-dict.html#Context" 1809 rel="Help" 1810><font face="Arial,Helvetica"><b>Context:</b></font></a> </td><td> server config, virtual host, directory, .htaccess</td></tr> 1811<tr><td><a 1812 href="../directive-dict.html#Override" 1813 rel="Help" 1814><font face="Arial,Helvetica"><b>Override:</b></font></a> </td><td> AuthConfig</td></tr> 1815<tr><td><a 1816 href="../directive-dict.html#Status" 1817 rel="Help" 1818><font face="Arial,Helvetica"><b>Status:</b></font></a> </td><td> Extension</td></tr> 1819<tr><td><a 1820 href="../directive-dict.html#Module" 1821 rel="Help" 1822><font face="Arial,Helvetica"><b>Module:</b></font></a> </td><td> mod_ssl</td></tr> 1823<tr><td><a 1824 href="../directive-dict.html#Compatibility" 1825 rel="Help" 1826><font face="Arial,Helvetica"><b>Compatibility:</b></font></a> </td><td> mod_ssl 2.0 </td></tr> 1827</table> 1828</td> 1829</tr> 1830</table> 1831</td> 1832</tr> 1833</table> 1834<p> 1835This directive sets how deeply mod_ssl should verify before deciding that the 1836clients don't have a valid certificate. Notice that this directive can be 1837used both in per-server and per-directory context. In per-server context it 1838applies to the client authentication process used in the standard SSL 1839handshake when a connection is established. In per-directory context it forces 1840a SSL renegotation with the reconfigured client verification depth after the 1841HTTP request was read but before the HTTP response is sent. 1842<p> 1843The depth actually is the maximum number of intermediate certificate issuers, 1844i.e. the number of CA certificates which are max allowed to be followed while 1845verifying the client certificate. A depth of 0 means that self-signed client 1846certificates are accepted only, the default depth of 1 means the client 1847certificate can be self-signed or has to be signed by a CA which is directly 1848known to the server (i.e. the CA's certificate is under 1849<code>SSLCACertificatePath</code>), etc. 1850<p> 1851Example: 1852<blockquote> 1853<pre> 1854SSLVerifyDepth 10 1855</pre> 1856</blockquote> 1857<!-- SSLLog ---------------------------------------------------------> 1858<p> 1859<br> 1860<a name="SSLLog"></a> 1861<h2><a name="ToC19">SSLLog</a></h2> 1862<table cellspacing="0" cellpadding="1" bgcolor="#cccccc" border="0" summary=""> 1863<tr> 1864<td> 1865<table bgcolor="white" width="600" cellspacing="0" cellpadding="5" border="0" summary=""> 1866<tr> 1867<td> 1868<table cellspacing="0" cellpadding="1" border="0" summary=""> 1869<tr><td> 1870<font face="Arial,Helvetica"><b>Name:</b></font></a> </td><td> <b>SSLLog</b></td></tr> 1871<tr><td> 1872<font face="Arial,Helvetica"><b>Description:</b></font></a> </td><td> Where to write the dedicated SSL engine logfile</td></tr> 1873<tr><td><a 1874 href="../directive-dict.html#Syntax" 1875 rel="Help" 1876><font face="Arial,Helvetica"><b>Syntax:</b></font></a> </td><td> <code>SSLLog</code> <em>filename</em></td></tr> 1877<tr><td><a 1878 href="../directive-dict.html#Default" 1879 rel="Help" 1880><font face="Arial,Helvetica"><b>Default:</b></font></a> </td><td> <em>None</em></td></tr> 1881<tr><td><a 1882 href="../directive-dict.html#Context" 1883 rel="Help" 1884><font face="Arial,Helvetica"><b>Context:</b></font></a> </td><td> server config, virtual host</td></tr> 1885<tr><td><a 1886 href="../directive-dict.html#Override" 1887 rel="Help" 1888><font face="Arial,Helvetica"><b>Override:</b></font></a> </td><td> <em>Not applicable</em></td></tr> 1889<tr><td><a 1890 href="../directive-dict.html#Status" 1891 rel="Help" 1892><font face="Arial,Helvetica"><b>Status:</b></font></a> </td><td> Extension</td></tr> 1893<tr><td><a 1894 href="../directive-dict.html#Module" 1895 rel="Help" 1896><font face="Arial,Helvetica"><b>Module:</b></font></a> </td><td> mod_ssl</td></tr> 1897<tr><td><a 1898 href="../directive-dict.html#Compatibility" 1899 rel="Help" 1900><font face="Arial,Helvetica"><b>Compatibility:</b></font></a> </td><td> mod_ssl 2.1 </td></tr> 1901</table> 1902</td> 1903</tr> 1904</table> 1905</td> 1906</tr> 1907</table> 1908<p> 1909This directive sets the name of the dedicated SSL protocol engine logfile. 1910Error type messages are additionally duplicated to the general Apache error 1911log file (directive <code>ErrorLog</code>). Put this somewhere where it cannot 1912be used for symlink attacks on a real server (i.e. somewhere where only root 1913can write). If the <em>filename</em> does not begin with a slash 1914('<code>/</code>') then it is assumed to be relative to the <em>Server 1915Root</em>. If <em>filename</em> begins with a bar ('<code>|</code>') then the 1916following string is assumed to be a path to an executable program to which a 1917reliable pipe can be established. The directive should occur only once per 1918virtual server config. 1919<p> 1920Example: 1921<blockquote> 1922<pre> 1923SSLLog /usr/local/apache/logs/ssl_engine_log 1924</pre> 1925</blockquote> 1926<!-- SSLLogLevel ----------------------------------------------------> 1927<p> 1928<br> 1929<a name="SSLLogLevel"></a> 1930<h2><a name="ToC20">SSLLogLevel</a></h2> 1931<table cellspacing="0" cellpadding="1" bgcolor="#cccccc" border="0" summary=""> 1932<tr> 1933<td> 1934<table bgcolor="white" width="600" cellspacing="0" cellpadding="5" border="0" summary=""> 1935<tr> 1936<td> 1937<table cellspacing="0" cellpadding="1" border="0" summary=""> 1938<tr><td> 1939<font face="Arial,Helvetica"><b>Name:</b></font></a> </td><td> <b>SSLLogLevel</b></td></tr> 1940<tr><td> 1941<font face="Arial,Helvetica"><b>Description:</b></font></a> </td><td> Logging level for the dedicated SSL engine logfile</td></tr> 1942<tr><td><a 1943 href="../directive-dict.html#Syntax" 1944 rel="Help" 1945><font face="Arial,Helvetica"><b>Syntax:</b></font></a> </td><td> <code>SSLLogLevel</code> <em>level</em></td></tr> 1946<tr><td><a 1947 href="../directive-dict.html#Default" 1948 rel="Help" 1949><font face="Arial,Helvetica"><b>Default:</b></font></a> </td><td> <code>SSLLogLevel none</code></td></tr> 1950<tr><td><a 1951 href="../directive-dict.html#Context" 1952 rel="Help" 1953><font face="Arial,Helvetica"><b>Context:</b></font></a> </td><td> server config, virtual host</td></tr> 1954<tr><td><a 1955 href="../directive-dict.html#Override" 1956 rel="Help" 1957><font face="Arial,Helvetica"><b>Override:</b></font></a> </td><td> <em>Not applicable</em></td></tr> 1958<tr><td><a 1959 href="../directive-dict.html#Status" 1960 rel="Help" 1961><font face="Arial,Helvetica"><b>Status:</b></font></a> </td><td> Extension</td></tr> 1962<tr><td><a 1963 href="../directive-dict.html#Module" 1964 rel="Help" 1965><font face="Arial,Helvetica"><b>Module:</b></font></a> </td><td> mod_ssl</td></tr> 1966<tr><td><a 1967 href="../directive-dict.html#Compatibility" 1968 rel="Help" 1969><font face="Arial,Helvetica"><b>Compatibility:</b></font></a> </td><td> mod_ssl 2.1 </td></tr> 1970</table> 1971</td> 1972</tr> 1973</table> 1974</td> 1975</tr> 1976</table> 1977<p> 1978This directive sets the verbosity degree of the dedicated SSL protocol engine 1979logfile. The <em>level</em> is one of the following (in ascending order where 1980higher levels include lower levels): 1981<ul> 1982<li><code>none</code><br> 1983 no dedicated SSL logging is done, but messages of level 1984 ``<code>error</code>'' are still written to the general Apache error 1985 logfile. 1986<p> 1987<li><code>error</code><br> 1988 log messages of error type only, i.e. messages which show fatal situations 1989 (processing is stopped). Those messages are also duplicated to the 1990 general Apache error logfile. 1991<p> 1992<li><code>warn</code><br> 1993 log also warning messages, i.e. messages which show non-fatal problems 1994 (processing is continued). 1995<p> 1996<li><code>info</code><br> 1997 log also informational messages, i.e. messages which show major 1998 processing steps. 1999<p> 2000<li><code>trace</code><br> 2001 log also trace messages, i.e. messages which show minor processing steps. 2002<p> 2003<li><code>debug</code><br> 2004 log also debugging messages, i.e. messages which show development and 2005 low-level I/O information. 2006</ul> 2007<p> 2008Example: 2009<blockquote> 2010<pre> 2011SSLLogLevel warn 2012</pre> 2013</blockquote> 2014<!-- SSLOptions -----------------------------------------------------> 2015<p> 2016<br> 2017<a name="SSLOptions"></a> 2018<h2><a name="ToC21">SSLOptions</a></h2> 2019<table cellspacing="0" cellpadding="1" bgcolor="#cccccc" border="0" summary=""> 2020<tr> 2021<td> 2022<table bgcolor="white" width="600" cellspacing="0" cellpadding="5" border="0" summary=""> 2023<tr> 2024<td> 2025<table cellspacing="0" cellpadding="1" border="0" summary=""> 2026<tr><td> 2027<font face="Arial,Helvetica"><b>Name:</b></font></a> </td><td> <b>SSLOptions</b></td></tr> 2028<tr><td> 2029<font face="Arial,Helvetica"><b>Description:</b></font></a> </td><td> Configure various SSL engine run-time options</td></tr> 2030<tr><td><a 2031 href="../directive-dict.html#Syntax" 2032 rel="Help" 2033><font face="Arial,Helvetica"><b>Syntax:</b></font></a> </td><td> <code>SSLOptions</code> [+-]<em>option</em> ...</td></tr> 2034<tr><td><a 2035 href="../directive-dict.html#Default" 2036 rel="Help" 2037><font face="Arial,Helvetica"><b>Default:</b></font></a> </td><td> <em>None</em></td></tr> 2038<tr><td><a 2039 href="../directive-dict.html#Context" 2040 rel="Help" 2041><font face="Arial,Helvetica"><b>Context:</b></font></a> </td><td> server config, virtual host, directory, .htaccess</td></tr> 2042<tr><td><a 2043 href="../directive-dict.html#Override" 2044 rel="Help" 2045><font face="Arial,Helvetica"><b>Override:</b></font></a> </td><td> Options</td></tr> 2046<tr><td><a 2047 href="../directive-dict.html#Status" 2048 rel="Help" 2049><font face="Arial,Helvetica"><b>Status:</b></font></a> </td><td> Extension</td></tr> 2050<tr><td><a 2051 href="../directive-dict.html#Module" 2052 rel="Help" 2053><font face="Arial,Helvetica"><b>Module:</b></font></a> </td><td> mod_ssl</td></tr> 2054<tr><td><a 2055 href="../directive-dict.html#Compatibility" 2056 rel="Help" 2057><font face="Arial,Helvetica"><b>Compatibility:</b></font></a> </td><td> mod_ssl 2.1 </td></tr> 2058</table> 2059</td> 2060</tr> 2061</table> 2062</td> 2063</tr> 2064</table> 2065<p> 2066This directive can be used to control various run-time options on a 2067per-directory basis. Normally, if multiple <code>SSLOptions</code> could 2068apply to a directory, then the most specific one is taken completely; the 2069options are not merged. However if <em>all</em> the options on the 2070<code>SSLOptions</code> directive are preceded by a plus (<code>+</code>) or 2071minus (<code>-</code>) symbol, the options are merged. Any options preceded by 2072a <code>+</code> are added to the options currently in force, and any options 2073preceded by a <code>-</code> are removed from the options currently in force. 2074<p> 2075The available <em>option</em>s are: 2076<ul> 2077<li><code>StdEnvVars</code> 2078 <p> 2079 When this option is enabled, the standard set of SSL related CGI/SSI 2080 environment variables are created. This per default is disabled for 2081 performance reasons, because the information extraction step is a 2082 rather expensive operation. So one usually enables this option for 2083 CGI and SSI requests only. 2084<p> 2085<li><code>CompatEnvVars</code> 2086 <p> 2087 When this option is enabled, additional CGI/SSI environment variables are 2088 created for backward compatibility to other Apache SSL solutions. Look in 2089 the <a href="ssl_compat.html">Compatibility</a> chapter for details 2090 on the particular variables generated. 2091<p> 2092<li><code>ExportCertData</code> 2093 <p> 2094 When this option is enabled, additional CGI/SSI environment variables are 2095 created: <code>SSL_SERVER_CERT</code>, <code>SSL_CLIENT_CERT</code> and 2096 <code>SSL_CLIENT_CERT_CHAIN</code><i>n</i> (with <i>n</i> = 0,1,2,..). 2097 These contain the PEM-encoded X.509 Certificates of server and client for 2098 the current HTTPS connection and can be used by CGI scripts for deeper 2099 Certificate checking. Additionally all other certificates of the client 2100 certificate chain are provided, too. This bloats up the environment a 2101 little bit which is why you have to use this option to enable it on 2102 demand. 2103<p> 2104<li><code>FakeBasicAuth</code> 2105 <p> 2106 When this option is enabled, the Subject Distinguished Name (DN) of the 2107 Client X509 Certificate is translated into a HTTP Basic Authorization 2108 username. This means that the standard Apache authentication methods can 2109 be used for access control. The user name is just the Subject of the 2110 Client's X509 Certificate (can be determined by running OpenSSL's 2111 <code>openssl x509</code> command: <code>openssl x509 -noout -subject -in 2112 </code><em>certificate</em><code>.crt</code>). Note that no password is 2113 obtained from the user. Every entry in the user file needs this password: 2114 ``<code>xxj31ZMTZzkVA</code>'', which is the DES-encrypted version of the 2115 word `<code>password</code>''. Those who live under MD5-based encryption 2116 (for instance under FreeBSD or BSD/OS, etc.) should use the following MD5 2117 hash of the same word: ``<code>$1$OXLyS...$Owx8s2/m9/gfkcRVXzgoE/</code>''. 2118<p> 2119<li><code>StrictRequire</code> 2120 <p> 2121 This <i>forces</i> forbidden access when <code>SSLRequireSSL</code> or 2122 <code>SSLRequire</code> successfully decided that access should be 2123 forbidden. Usually the default is that in the case where a ``<code>Satisfy 2124 any</code>'' directive is used, and other access restrictions are passed, 2125 denial of access due to <code>SSLRequireSSL</code> or 2126 <code>SSLRequire</code> is overridden (because that's how the Apache 2127 <tt>Satisfy</tt> mechanism should work.) But for strict access restriction 2128 you can use <code>SSLRequireSSL</code> and/or <code>SSLRequire</code> in 2129 combination with an ``<code>SSLOptions +StrictRequire</code>''. Then an 2130 additional ``<code>Satisfy Any</code>'' has no chance once mod_ssl has 2131 decided to deny access. 2132<p> 2133<li><code>OptRenegotiate</code> 2134 <p> 2135 This enables optimized SSL connection renegotiation handling when SSL 2136 directives are used in per-directory context. By default a strict 2137 scheme is enabled where <i>every</i> per-directory reconfiguration of 2138 SSL parameters causes a <i>full</i> SSL renegotiation handshake. When this 2139 option is used mod_ssl tries to avoid unnecessary handshakes by doing more 2140 granular (but still safe) parameter checks. Nevertheless these granular 2141 checks sometimes maybe not what the user expects, so enable this on a 2142 per-directory basis only, please. 2143</ul> 2144<p> 2145Example: 2146<blockquote> 2147<pre> 2148SSLOptions +FakeBasicAuth -StrictRequire 2149<Files ~ "\.(cgi|shtml)$"> 2150 SSLOptions +StdEnvVars +CompatEnvVars -ExportCertData 2151<Files> 2152</pre> 2153</blockquote> 2154<!-- SSLRequireSSL --------------------------------------------------> 2155<p> 2156<br> 2157<a name="SSLRequireSSL"></a> 2158<h2><a name="ToC22">SSLRequireSSL</a></h2> 2159<table cellspacing="0" cellpadding="1" bgcolor="#cccccc" border="0" summary=""> 2160<tr> 2161<td> 2162<table bgcolor="white" width="600" cellspacing="0" cellpadding="5" border="0" summary=""> 2163<tr> 2164<td> 2165<table cellspacing="0" cellpadding="1" border="0" summary=""> 2166<tr><td> 2167<font face="Arial,Helvetica"><b>Name:</b></font></a> </td><td> <b>SSLRequireSSL</b></td></tr> 2168<tr><td> 2169<font face="Arial,Helvetica"><b>Description:</b></font></a> </td><td> Deny access when SSL is not used for the HTTP request</td></tr> 2170<tr><td><a 2171 href="../directive-dict.html#Syntax" 2172 rel="Help" 2173><font face="Arial,Helvetica"><b>Syntax:</b></font></a> </td><td> <code>SSLRequireSSL</code></td></tr> 2174<tr><td><a 2175 href="../directive-dict.html#Default" 2176 rel="Help" 2177><font face="Arial,Helvetica"><b>Default:</b></font></a> </td><td> <em>None</em></td></tr> 2178<tr><td><a 2179 href="../directive-dict.html#Context" 2180 rel="Help" 2181><font face="Arial,Helvetica"><b>Context:</b></font></a> </td><td> directory, .htaccess</td></tr> 2182<tr><td><a 2183 href="../directive-dict.html#Override" 2184 rel="Help" 2185><font face="Arial,Helvetica"><b>Override:</b></font></a> </td><td> AuthConfig</td></tr> 2186<tr><td><a 2187 href="../directive-dict.html#Status" 2188 rel="Help" 2189><font face="Arial,Helvetica"><b>Status:</b></font></a> </td><td> Extension</td></tr> 2190<tr><td><a 2191 href="../directive-dict.html#Module" 2192 rel="Help" 2193><font face="Arial,Helvetica"><b>Module:</b></font></a> </td><td> mod_ssl</td></tr> 2194<tr><td><a 2195 href="../directive-dict.html#Compatibility" 2196 rel="Help" 2197><font face="Arial,Helvetica"><b>Compatibility:</b></font></a> </td><td> mod_ssl 2.0 </td></tr> 2198</table> 2199</td> 2200</tr> 2201</table> 2202</td> 2203</tr> 2204</table> 2205<p> 2206This directive forbids access unless HTTP over SSL (i.e. HTTPS) is enabled for 2207the current connection. This is very handy inside the SSL-enabled virtual 2208host or directories for defending against configuration errors that expose 2209stuff that should be protected. When this directive is present all requests 2210are denied which are not using SSL. 2211<p> 2212Example: 2213<blockquote> 2214<pre> 2215SSLRequireSSL 2216</pre> 2217</blockquote> 2218<!-- SSLRequire -----------------------------------------------------> 2219<p> 2220<br> 2221<a name="SSLRequire"></a> 2222<h2><a name="ToC23">SSLRequire</a></h2> 2223<table cellspacing="0" cellpadding="1" bgcolor="#cccccc" border="0" summary=""> 2224<tr> 2225<td> 2226<table bgcolor="white" width="600" cellspacing="0" cellpadding="5" border="0" summary=""> 2227<tr> 2228<td> 2229<table cellspacing="0" cellpadding="1" border="0" summary=""> 2230<tr><td> 2231<font face="Arial,Helvetica"><b>Name:</b></font></a> </td><td> <b>SSLRequire</b></td></tr> 2232<tr><td> 2233<font face="Arial,Helvetica"><b>Description:</b></font></a> </td><td> Allow access only when an arbitrarily complex boolean expression is true</td></tr> 2234<tr><td><a 2235 href="../directive-dict.html#Syntax" 2236 rel="Help" 2237><font face="Arial,Helvetica"><b>Syntax:</b></font></a> </td><td> <code>SSLRequire</code> <em>expression</em></td></tr> 2238<tr><td><a 2239 href="../directive-dict.html#Default" 2240 rel="Help" 2241><font face="Arial,Helvetica"><b>Default:</b></font></a> </td><td> <em>None</em></td></tr> 2242<tr><td><a 2243 href="../directive-dict.html#Context" 2244 rel="Help" 2245><font face="Arial,Helvetica"><b>Context:</b></font></a> </td><td> directory, .htaccess</td></tr> 2246<tr><td><a 2247 href="../directive-dict.html#Override" 2248 rel="Help" 2249><font face="Arial,Helvetica"><b>Override:</b></font></a> </td><td> AuthConfig</td></tr> 2250<tr><td><a 2251 href="../directive-dict.html#Status" 2252 rel="Help" 2253><font face="Arial,Helvetica"><b>Status:</b></font></a> </td><td> Extension</td></tr> 2254<tr><td><a 2255 href="../directive-dict.html#Module" 2256 rel="Help" 2257><font face="Arial,Helvetica"><b>Module:</b></font></a> </td><td> mod_ssl</td></tr> 2258<tr><td><a 2259 href="../directive-dict.html#Compatibility" 2260 rel="Help" 2261><font face="Arial,Helvetica"><b>Compatibility:</b></font></a> </td><td> mod_ssl 2.1 </td></tr> 2262</table> 2263</td> 2264</tr> 2265</table> 2266</td> 2267</tr> 2268</table> 2269<p> 2270This directive specifies a general access requirement which has to be 2271fulfilled in order to allow access. It's a very powerful directive because the 2272requirement specification is an arbitrarily complex boolean expression 2273containing any number of access checks. 2274<p> 2275The <em>expression</em> must match the following syntax (given as a BNF 2276grammar notation): 2277<blockquote> 2278<pre> 2279expr ::= "<b>true</b>" | "<b>false</b>" 2280 | "<b>!</b>" expr 2281 | expr "<b>&&</b>" expr 2282 | expr "<b>||</b>" expr 2283 | "<b>(</b>" expr "<b>)</b>" 2284 | comp 2285 2286comp ::= word "<b>==</b>" word | word "<b>eq</b>" word 2287 | word "<b>!=</b>" word | word "<b>ne</b>" word 2288 | word "<b><</b>" word | word "<b>lt</b>" word 2289 | word "<b><=</b>" word | word "<b>le</b>" word 2290 | word "<b>></b>" word | word "<b>gt</b>" word 2291 | word "<b>>=</b>" word | word "<b>ge</b>" word 2292 | word "<b>in</b>" "<b>{</b>" wordlist "<b>}</b>" 2293 | word "<b>=~</b>" regex 2294 | word "<b>!~</b>" regex 2295 2296wordlist ::= word 2297 | wordlist "<b>,</b>" word 2298 2299word ::= digit 2300 | cstring 2301 | variable 2302 | function 2303 2304digit ::= [0-9]+ 2305cstring ::= "..." 2306variable ::= "<b>%{</b>" varname "<b>}</b>" 2307function ::= funcname "<b>(</b>" funcargs "<b>)</b>" 2308</pre> 2309</blockquote> 2310while for <code>varname</code> any variable from <a href="#table3">Table 3</a> 2311can be used. Finally for <code>funcname</code> the following functions 2312are available: 2313<ul> 2314<li><code>file(</code><em>filename</em><code>)</code> 2315 <p> 2316 This function takes one string argument and expands to the contents of the 2317 file. This is especially useful for matching this contents against a 2318 regular expression, etc. 2319</ul> 2320Notice that <em>expression</em> is first parsed into an internal machine 2321representation and then evaluated in a second step. Actually, in Global and 2322Per-Server Class context <em>expression</em> is parsed at startup time and 2323at runtime only the machine representation is executed. For Per-Directory 2324context this is different: here <em>expression</em> has to be parsed and 2325immediately executed for every request. 2326<p> 2327Example: 2328<blockquote> 2329<pre> 2330SSLRequire ( %{SSL_CIPHER} !~ m/^(EXP|NULL)-/ \ 2331 and %{SSL_CLIENT_S_DN_O} eq "Snake Oil, Ltd." \ 2332 and %{SSL_CLIENT_S_DN_OU} in {"Staff", "CA", "Dev"} \ 2333 and %{TIME_WDAY} >= 1 and %{TIME_WDAY} <= 5 \ 2334 and %{TIME_HOUR} >= 8 and %{TIME_HOUR} <= 20 ) \ 2335 or %{REMOTE_ADDR} =~ m/^192\.76\.162\.[0-9]+$/ 2336</pre> 2337</blockquote> 2338<div align="center"> 2339<a name="table3"></a> 2340<table width="600" cellspacing="0" cellpadding="1" border="0" summary=""> 2341<caption align="bottom" id="sf">Table 3: Available Variables for SSLRequire</caption> 2342<tr><td bgcolor="#cccccc"> 2343<table width="598" cellpadding="5" cellspacing="0" border="0" summary=""> 2344<tr><td valign="top" align="center" bgcolor="#ffffff"> 2345<table summary=""><tr><td> 2346<em>Standard CGI/1.0 and Apache variables:</em> 2347<pre> 2348HTTP_USER_AGENT PATH_INFO AUTH_TYPE 2349HTTP_REFERER QUERY_STRING SERVER_SOFTWARE 2350HTTP_COOKIE REMOTE_HOST API_VERSION 2351HTTP_FORWARDED REMOTE_IDENT TIME_YEAR 2352HTTP_HOST IS_SUBREQ TIME_MON 2353HTTP_PROXY_CONNECTION DOCUMENT_ROOT TIME_DAY 2354HTTP_ACCEPT SERVER_ADMIN TIME_HOUR 2355HTTP:headername SERVER_NAME TIME_MIN 2356THE_REQUEST SERVER_PORT TIME_SEC 2357REQUEST_METHOD SERVER_PROTOCOL TIME_WDAY 2358REQUEST_SCHEME REMOTE_ADDR TIME 2359REQUEST_URI REMOTE_USER ENV:<b>variablename</b> 2360REQUEST_FILENAME 2361</pre> 2362<em>SSL-related variables:</em> 2363<pre> 2364HTTPS SSL_CLIENT_M_VERSION SSL_SERVER_M_VERSION 2365 SSL_CLIENT_M_SERIAL SSL_SERVER_M_SERIAL 2366SSL_PROTOCOL SSL_CLIENT_V_START SSL_SERVER_V_START 2367SSL_SESSION_ID SSL_CLIENT_V_END SSL_SERVER_V_END 2368SSL_CIPHER SSL_CLIENT_S_DN SSL_SERVER_S_DN 2369SSL_CIPHER_EXPORT SSL_CLIENT_S_DN_C SSL_SERVER_S_DN_C 2370SSL_CIPHER_ALGKEYSIZE SSL_CLIENT_S_DN_ST SSL_SERVER_S_DN_ST 2371SSL_CIPHER_USEKEYSIZE SSL_CLIENT_S_DN_L SSL_SERVER_S_DN_L 2372SSL_VERSION_LIBRARY SSL_CLIENT_S_DN_O SSL_SERVER_S_DN_O 2373SSL_VERSION_INTERFACE SSL_CLIENT_S_DN_OU SSL_SERVER_S_DN_OU 2374 SSL_CLIENT_S_DN_CN SSL_SERVER_S_DN_CN 2375 SSL_CLIENT_S_DN_T SSL_SERVER_S_DN_T 2376 SSL_CLIENT_S_DN_I SSL_SERVER_S_DN_I 2377 SSL_CLIENT_S_DN_G SSL_SERVER_S_DN_G 2378 SSL_CLIENT_S_DN_S SSL_SERVER_S_DN_S 2379 SSL_CLIENT_S_DN_D SSL_SERVER_S_DN_D 2380 SSL_CLIENT_S_DN_UID SSL_SERVER_S_DN_UID 2381 SSL_CLIENT_S_DN_Email SSL_SERVER_S_DN_Email 2382 SSL_CLIENT_I_DN SSL_SERVER_I_DN 2383 SSL_CLIENT_I_DN_C SSL_SERVER_I_DN_C 2384 SSL_CLIENT_I_DN_ST SSL_SERVER_I_DN_ST 2385 SSL_CLIENT_I_DN_L SSL_SERVER_I_DN_L 2386 SSL_CLIENT_I_DN_O SSL_SERVER_I_DN_O 2387 SSL_CLIENT_I_DN_OU SSL_SERVER_I_DN_OU 2388 SSL_CLIENT_I_DN_CN SSL_SERVER_I_DN_CN 2389 SSL_CLIENT_I_DN_T SSL_SERVER_I_DN_T 2390 SSL_CLIENT_I_DN_I SSL_SERVER_I_DN_I 2391 SSL_CLIENT_I_DN_G SSL_SERVER_I_DN_G 2392 SSL_CLIENT_I_DN_S SSL_SERVER_I_DN_S 2393 SSL_CLIENT_I_DN_D SSL_SERVER_I_DN_D 2394 SSL_CLIENT_I_DN_UID SSL_SERVER_I_DN_UID 2395 SSL_CLIENT_I_DN_Email SSL_SERVER_I_DN_Email 2396 SSL_CLIENT_A_SIG SSL_SERVER_A_SIG 2397 SSL_CLIENT_A_KEY SSL_SERVER_A_KEY 2398 SSL_CLIENT_CERT SSL_SERVER_CERT 2399 SSL_CLIENT_CERT_CHAIN<b>n</b> 2400 SSL_CLIENT_VERIFY 2401</pre> 2402</td></tr></table> 2403</td> 2404</tr></table> 2405</td></tr></table> 2406</div> 2407<br> 2408<br> 2409<p> 2410<h1><a name="ToC24">Additional Features</a></h1> 2411<h2><a name="ToC25">Environment Variables</a></h2> 2412This module provides a lot of SSL information as additional environment 2413variables to the SSI and CGI namespace. The generated variables are listed in 2414<a href="#table4">Table 4</a>. For backward compatibility the information can 2415be made available under different names, too. Look in the <a 2416href="ssl_compat.html">Compatibility</a> chapter for details on the 2417compatibility variables. 2418<p> 2419<div align="center"> 2420<a name="table4"></a> 2421<table width="600" cellspacing="0" cellpadding="1" border="0" summary=""> 2422<caption align="bottom" id="sf">Table 4: SSI/CGI Environment Variables</caption> 2423<tr><td bgcolor="#cccccc"> 2424<table width="598" cellpadding="5" cellspacing="0" border="0" summary=""> 2425<tr><td valign="top" align="center" bgcolor="#ffffff"> 2426<table border="0" cellspacing="0" cellpadding="2" width="598" summary=""> 2427<tr id="H"> 2428 <td><b>Variable Name:</b></td> 2429 <td><b>Value Type:</b></td> 2430 <td><b>Description:</b></td> 2431</tr> 2432<tr id="D"><td><code>HTTPS</code></td> <td>flag</td> <td>HTTPS is being used.</td></tr> 2433<tr id="H"><td><code>SSL_PROTOCOL</code></td> <td>string</td> <td>The SSL protocol version (SSLv2, SSLv3, TLSv1)</td></tr> 2434<tr id="H"><td><code>SSL_SESSION_ID</code></td> <td>string</td> <td>The hex-encoded SSL session id</td></tr> 2435<tr id="D"><td><code>SSL_CIPHER</code></td> <td>string</td> <td>The cipher specification name</td></tr> 2436<tr id="D"><td><code>SSL_CIPHER_EXPORT</code></td> <td>string</td> <td><code>true</code> if cipher is an export cipher</td></tr> 2437<tr id="H"><td><code>SSL_CIPHER_USEKEYSIZE</code></td> <td>number</td> <td>Number of cipher bits (actually used)</td></tr> 2438<tr id="D"><td><code>SSL_CIPHER_ALGKEYSIZE</code></td> <td>number</td> <td>Number of cipher bits (possible)</td></tr> 2439<tr id="H"><td><code>SSL_VERSION_INTERFACE</code></td> <td>string</td> <td>The mod_ssl program version</td></tr> 2440<tr id="D"><td><code>SSL_VERSION_LIBRARY</code></td> <td>string</td> <td>The OpenSSL program version</td></tr> 2441<tr id="H"><td><code>SSL_CLIENT_M_VERSION</code></td> <td>string</td> <td>The version of the client certificate</td></tr> 2442<tr id="D"><td><code>SSL_CLIENT_M_SERIAL</code></td> <td>string</td> <td>The serial of the client certificate</td></tr> 2443<tr id="H"><td><code>SSL_CLIENT_S_DN</code></td> <td>string</td> <td>Subject DN in client's certificate</td></tr> 2444<tr id="D"><td><code>SSL_CLIENT_S_DN_</code><em>x509</em></td> <td>string</td> <td>Component of client's Subject DN</td></tr> 2445<tr id="H"><td><code>SSL_CLIENT_I_DN</code></td> <td>string</td> <td>Issuer DN of client's certificate</td></tr> 2446<tr id="D"><td><code>SSL_CLIENT_I_DN_</code><em>x509</em></td> <td>string</td> <td>Component of client's Issuer DN</td></tr> 2447<tr id="H"><td><code>SSL_CLIENT_V_START</code></td> <td>string</td> <td>Validity of client's certificate (start time)</td></tr> 2448<tr id="D"><td><code>SSL_CLIENT_V_END</code></td> <td>string</td> <td>Validity of client's certificate (end time)</td></tr> 2449<tr id="H"><td><code>SSL_CLIENT_A_SIG</code></td> <td>string</td> <td>Algorithm used for the signature of client's certificate</td></tr> 2450<tr id="D"><td><code>SSL_CLIENT_A_KEY</code></td> <td>string</td> <td>Algorithm used for the public key of client's certificate</td></tr> 2451<tr id="H"><td><code>SSL_CLIENT_CERT</code></td> <td>string</td> <td>PEM-encoded client certificate</td></tr> 2452<tr id="D"><td><code>SSL_CLIENT_CERT_CHAIN</code><i>n</i></td> <td>string</td> <td>PEM-encoded certificates in client certificate chain</td></tr> 2453<tr id="H"><td><code>SSL_CLIENT_VERIFY</code></td> <td>string</td> <td><tt>NONE</tt>, <tt>SUCCESS</tt>, <tt>GENEROUS</tt> or <tt>FAILED:</tt><i>reason</i></td></tr> 2454<tr id="D"><td><code>SSL_SERVER_M_VERSION</code></td> <td>string</td> <td>The version of the server certificate</td></tr> 2455<tr id="H"><td><code>SSL_SERVER_M_SERIAL</code></td> <td>string</td> <td>The serial of the server certificate</td></tr> 2456<tr id="D"><td><code>SSL_SERVER_S_DN</code></td> <td>string</td> <td>Subject DN in server's certificate</td></tr> 2457<tr id="H"><td><code>SSL_SERVER_S_DN_</code><em>x509</em></td> <td>string</td> <td>Component of server's Subject DN</td></tr> 2458<tr id="D"><td><code>SSL_SERVER_I_DN</code></td> <td>string</td> <td>Issuer DN of server's certificate</td></tr> 2459<tr id="H"><td><code>SSL_SERVER_I_DN_</code><em>x509</em></td> <td>string</td> <td>Component of server's Issuer DN</td></tr> 2460<tr id="D"><td><code>SSL_SERVER_V_START</code></td> <td>string</td> <td>Validity of server's certificate (start time)</td></tr> 2461<tr id="H"><td><code>SSL_SERVER_V_END</code></td> <td>string</td> <td>Validity of server's certificate (end time)</td></tr> 2462<tr id="D"><td><code>SSL_SERVER_A_SIG</code></td> <td>string</td> <td>Algorithm used for the signature of server's certificate</td></tr> 2463<tr id="H"><td><code>SSL_SERVER_A_KEY</code></td> <td>string</td> <td>Algorithm used for the public key of server's certificate</td></tr> 2464<tr id="D"><td><code>SSL_SERVER_CERT</code></td> <td>string</td> <td>PEM-encoded server certificate</td></tr> 2465</table> 2466[ where <em>x509</em> is a component of a X.509 DN: 2467 <code>C,ST,L,O,OU,CN,T,I,G,S,D,UID,Email</code> ] 2468</td> 2469</tr></table> 2470</td></tr></table> 2471</div> 2472<p> 2473<br> 2474<h2><a name="ToC26">Custom Log Formats</a></h2> 2475When mod_ssl is built into Apache or at least loaded (under DSO situation) 2476additional functions exist for the <a 2477href="../mod_log_config.html#formats">Custom Log Format</a> of <a 2478href="../mod_log_config.html">mod_log_config</a>. First there is an additional 2479``<code>%{</code><em>varname</em><code>}x</code>'' eXtension format function 2480which can be used to expand any variables provided by any module, especially 2481those provided by mod_ssl which can you find in <a href="#table4">Table 4</a>. 2482<p> 2483For backward compatibility there is additionally a special 2484``<code>%{</code><em>name</em><code>}c</code>'' cryptography format function 2485provided. Information about this function is provided in the <a 2486href="ssl_compat.html">Compatibility</a> chapter. 2487<p> 2488Example: 2489<blockquote> 2490<pre> 2491CustomLog logs/ssl_request_log \ 2492 "%t %h %{SSL_PROTOCOL}x %{SSL_CIPHER}x \"%r\" %b" 2493</pre> 2494</blockquote> 2495 <p> 2496 <br> 2497 <table summary=""> 2498 <tr> 2499 <td> 2500 <table width="600" border="0" summary=""> 2501 <tr> 2502 <td valign="top" align="left" width="250"> 2503<a href="ssl_intro.html" onmouseover="ro_imgOver('ro_img_prev_bot', 'previous page'); return true" onmouseout="ro_imgNormal('ro_img_prev_bot'); return true" onfocus="ro_imgOver('ro_img_prev_bot', 'previous page'); return true" onblur="ro_imgNormal('ro_img_prev_bot'); return true"><img name="ro_img_prev_bot" src="ssl_template.navbut-prev-n.gif" alt="previous page" width="70" height="18" border="0"></a><br><font color="#000000">Introduction</font> 2504 </td> 2505 <td valign="top" align="right" width="250"> 2506<a href="ssl_compat.html" onmouseover="ro_imgOver('ro_img_next_bot', 'next page'); return true" onmouseout="ro_imgNormal('ro_img_next_bot'); return true" onfocus="ro_imgOver('ro_img_next_bot', 'next page'); return true" onblur="ro_imgNormal('ro_img_next_bot'); return true"><img name="ro_img_next_bot" src="ssl_template.navbut-next-n.gif" alt="next page" width="70" height="18" border="0"></a><br><font color="#000000">Compatibility</font> 2507 </td> 2508 </tr> 2509 </table> 2510 </td> 2511 </tr> 2512 <tr> 2513 <td><img src="ssl_template.imgdot-1x1-000000.gif" alt="" width="600" height="2" align="bottom" border="0"></td> 2514 </tr> 2515 <tr> 2516 <td><table width="598" summary=""> 2517 <tr> 2518 <td align="left"><font face="Arial,Helvetica"> 2519 <a href="http://www.modssl.org/">mod_ssl</a> 2.8, User Manual<br> 2520 The Apache Interface to OpenSSL 2521 </font> 2522 </td> 2523 <td align="right"><font face="Arial,Helvetica"> 2524 Copyright © 1998-2001 2525 <a href="http://www.engelschall.com/">Ralf S. Engelschall</a><br> 2526 All Rights Reserved<br> 2527 </font> 2528 </td> 2529 </tr> 2530 </table> 2531 </td> 2532 </tr> 2533 </table> 2534 </td> 2535</tr> 2536</table> 2537</div> 2538</body> 2539</html> 2540
