2 #use "ssl_template.inc" title="Reference" tag=ref num=3
4 <page_prev name="Introduction" url="ssl_intro.html">
5 <page_next name="Compatibility" url="ssl_compat.html">
7 #use wml::std::toc style=nbsp
10 <quotation width=150 author="Unknown">
11 ``Try to understand everything,
12 but believe nothing!''
16 <table cellspacing="0" cellpadding="0" border="0">
20 <big T>his chapter provides a reference to all configuration directives and
21 additional user visible features mod_ssl provides. It's intended as the
22 official resource when you want to know how a particilar mod_ssl functionality
23 is actually configured or activated. Each directive is documented similar to
24 the way standard Apache directives are documented in the official Apache
25 documentation set, i.e. for each directive especially the syntax, default and
26 context where applicable is given.
29 Notice that there are three major classes of directives which are used by
30 mod_ssl: First <em>Global Directives</em> (i.e. directives with context
31 ``server config''), which can occur inside the server config files but only
32 outside of any sectioning commands like <VirtualHost>. Second
33 <em>Per-Server Directives</em> (i.e. those with context ``server config,
34 virtual host''), which can occur inside the server config files both outside
35 (for the main/default server) and inside <VirtualHost> sections.
44 <table cellspacing="0" cellpadding="5" border="0" bgcolor="#ccccff">
46 <td bgcolor="#333399">
47 <font face="Arial,Helvetica" color="#ccccff">
48 <b>Table Of Contents</b>
54 <font face="Arial,Helvetica" size="-1">
67 And third <em>Per-Directory Directives</em> (i.e. those with context ``server
68 config, virtual host, directory, .htaccess''), which can pretty much occur
69 everywhere. Especially both inside the server config files and the
70 per-directory <code>.htaccess</code> files. The three classes are subsets of
71 each other, i.e. directives from the per-directory class can also be used in
72 the per-server and global context, and directives from the per-server class
73 can also be used the in the global context.
76 Additional directives and environment variables provided by mod_ssl (via
77 on-the-fly mapping) for backward compatiblity to other Apache SSL solutions
78 are documented in the <a href="ssl_compat.html">Compatibility</a> chapter.
81 <h1>Configuration Directives</h1>
83 The most visible and error-prone things of mod_ssl are its configuration
84 directives. So we document them in great detail here to assist you in setting
85 up the best possible configuration of your SSL-aware webserver.
88 <!-- SSLPassPhraseDialog -------------------------------------------->
92 <a name="SSLPassPhraseDialog"></a>
93 <h2>SSLPassPhraseDialog</h2>
97 name="SSLPassPhraseDialog"
98 description="Type of pass phrase dialog for encrypted private keys"
99 syntax="<code>SSLPassPhraseDialog</code> <em>type</em>"
100 default="<code>SSLPassPhraseDialog builtin</code>"
101 context="server config"
102 override="<em>Not applicable</em>"
107 When Apache starts up it has to read the various Certificate (see <a
108 href="#SSLCertificateFile">SSLCertificateFile</a>) and Private Key (see <a
109 href="#SSLCertificateKeyFile">SSLCertificateKeyFile</a>) files of the
110 SSL-enabled virtual servers. Because for security reasons the Private Key
111 files are usually encrypted, mod_ssl needs to query the administrator for a
112 Pass Phrase in order to decrypt those files. This query can be done in two ways
113 which can be configured by <em>type</em>:
116 <li><code>builtin</code>
118 This is the default where an interactive terminal dialog occurs at startup
119 time just before Apache detaches from the terminal. Here the administrator
120 has to manually enter the Pass Phrase for each encrypted Private Key file.
121 Because a lot of SSL-enabled virtual hosts can be configured, the
122 following reuse-scheme is used to minimize the dialog: When a Private Key
123 file is encrypted, all known Pass Phrases (at the beginning there are
124 none, of course) are tried. If one of those known Pass Phrases succeeds no
125 dialog pops up for this particular Private Key file. If none succeeded,
126 another Pass Phrase is queried on the terminal and remembered for the next
127 round (where it perhaps can be reused).
129 This scheme allows mod_ssl to be maximally flexible (because for N encrypted
130 Private Key files you <em>can</em> use N different Pass Phrases - but then
131 you have to enter all of them, of course) while minimizing the terminal
132 dialog (i.e. when you use a single Pass Phrase for all N Private Key files
133 this Pass Phrase is queried only once).
135 <li><code>exec:/path/to/program</code>
137 Here an external program is configured which is called at startup for each
138 encrypted Private Key file. It is called with two arguments (the first is
139 of the form ``<code>servername:portnumber</code>'', the second is either
140 ``<code>RSA</code>'' or ``<code>DSA</code>''), which indicate for which
141 server and algorithm it has to print the corresponding Pass Phrase to
142 <code>stdout</code>. The intent is that this external program first runs
143 security checks to make sure that the system is not compromised by an
144 attacker, and only when these checks were passed successfully it provides
147 Both these security checks, and the way the Pass Phrase is determined, can
148 be as complex as you like. Mod_ssl just defines the interface: an
149 executable program which provides the Pass Phrase on <code>stdout</code>.
150 Nothing more or less! So, if you're really paranoid about security, here
151 is your interface. Anything else has to be left as an exercise to the
152 administrator, because local security requirements are so different.
154 The reuse-algorithm above is used here, too. In other words: The external
155 program is called only once per unique Pass Phrase.
162 SSLPassPhraseDialog exec:/usr/local/apache/sbin/pp-filter
167 <!-- SSLMutex ------------------------------------------------------->
171 <a name="SSLMutex"></a>
177 description="Semaphore for internal mutual exclusion of operations"
178 syntax="<code>SSLMutex</code> <em>type</em>"
179 default="<code>SSLMutex none</code>"
180 context="server config"
181 override="<em>Not applicable</em>"
186 This configures the SSL engine's semaphore (aka. lock) which is used for mutual
187 exclusion of operations which have to be done in a synchronized way between the
188 pre-forked Apache server processes. This directive can only be used in the
189 global server context because it's only useful to have one global mutex.
192 The following Mutex <em>types</em> are available:
195 <li><code>none</code>
197 This is the default where no Mutex is used at all. Use it at your own
198 risk. But because currently the Mutex is mainly used for synchronizing
199 write access to the SSL Session Cache you can live without it as long
200 as you accept a sometimes garbled Session Cache. So it's not recommended
201 to leave this the default. Instead configure a real Mutex.
203 <li><code>file:/path/to/mutex</code>
205 This is the portable and (under Unix) always provided Mutex variant where
206 a physical (lock-)file is used as the Mutex. Always use a local disk
207 filesystem for <code>/path/to/mutex</code> and never a file residing on a
208 NFS- or AFS-filesystem. Note: Internally, the Process ID (PID) of the
209 Apache parent process is automatically appended to
210 <code>/path/to/mutex</code> to make it unique, so you don't have to worry
211 about conflicts yourself. Notice that this type of mutex is not available
212 under the Win32 environment. There you <i>have</i> to use the semaphore
217 This is the most elegant but also most non-portable Mutex variant where a
218 SysV IPC Semaphore (under Unix) and a Windows Mutex (under Win32) is used
219 when possible. It is only available when the underlying platform
227 SSLMutex file:/usr/local/apache/logs/ssl_mutex
232 <!-- SSLRandomSeed -------------------------------------------------->
236 <a name="SSLRandomSeed"></a>
237 <h2>SSLRandomSeed</h2>
242 description="Pseudo Random Number Generator (PRNG) seeding source"
243 syntax="<code>SSLRandomSeed</code> <em>context</em> <em>source</em> [<em>bytes</em>]"
244 default="<em>none</em>"
245 context="server config"
246 override="<em>Not applicable</em>"
251 This configures one or more sources for seeding the Pseudo Random Number
252 Generator (PRNG) in OpenSSL at startup time (<em>context</em> is
253 <code>startup</code>) and/or just before a new SSL connection is established
254 (<em>context</em> is <code>connect</code>). This directive can only be used
255 in the global server context because the PRNG is a global facility.
258 The following <em>source</em> variants are available:
261 <li><code>builtin</code>
262 <p> This is the always available builtin seeding source. Its usage
263 consumes minimum CPU cycles under runtime and hence can be always used
264 without drawbacks. The source used for seeding the PRNG contains of the
265 current time, the current process id and (when applicable) a randomly
266 choosen 1KB extract of the inter-process scoreboard structure of Apache.
267 The drawback is that this is not really a strong source and at startup
268 time (where the scoreboard is still not available) this source just
269 produces a few bytes of entropy. So you should always, at least for the
270 startup, use an additional seeding source.
272 <li><code>file:/path/to/source</code>
274 This variant uses an external file <code>/path/to/source</code> as the
275 source for seeding the PRNG. When <em>bytes</em> is specified, only the
276 first <em>bytes</em> number of bytes of the file form the entropy (and
277 <em>bytes</em> is given to <code>/path/to/source</code> as the first
278 argument). When <em>bytes</em> is not specified the whole file forms the
279 entropy (and <code>0</code> is given to <code>/path/to/source</code> as
280 the first argument). Use this especially at startup time, for instance
281 with an available <code>/dev/random</code> and/or
282 <code>/dev/urandom</code> devices (which usually exist on modern Unix
283 derivates like FreeBSD and Linux).
285 <em>But be careful</em>: Usually <code>/dev/random</code> provides only as
286 much entropy data as it actually has, i.e. when you request 512 bytes of
287 entropy, but the device currently has only 100 bytes available two things
288 can happen: On some platforms you receive only the 100 bytes while on
289 other platforms the read blocks until enough bytes are available (which
290 can take a long time). Here using an existing <code>/dev/urandom</code> is
291 better, because it never blocks and actually gives the amount of requested
292 data. The drawback is just that the quality of the received data may not
295 On some platforms like FreeBSD one can even control how the entropy is
296 actually generated, i.e. by which system interrupts. More details one can
297 find under <i>rndcontrol(8)</i> on those platforms. Alternatively, when
298 your system lacks such a random device, you can use tool
299 like <a href="http://www.lothar.com/tech/crypto/">EGD</a>
300 (Entropy Gathering Daemon) and run its client program with the
301 <code>exec:/path/to/program/</code> variant (see below) or use
302 <code>egd:/path/to/egd-socket</code> (see below).
304 <li><code>exec:/path/to/program</code>
306 This variant uses an external executable <code>/path/to/program</code> as
307 the source for seeding the PRNG. When <em>bytes</em> is specified, only the
308 first <em>bytes</em> number of bytes of its <code>stdout</code> contents
309 form the entropy. When <em>bytes</em> is not specified, the entirety of
310 the data produced on <code>stdout</code> form the entropy. Use this only
311 at startup time when you need a very strong seeding with the help of an
312 external program (for instance as in the example above with the
313 <code>truerand</code> utility you can find in the mod_ssl distribution
314 which is based on the AT&T <em>truerand</em> library). Using this in
315 the connection context slows down the server too dramatically, of course.
316 So usually you should avoid using external programs in that context.
318 <li><code>egd:/path/to/egd-socket</code> (Unix only)
320 This variant uses the Unix domain socket of the
321 external Entropy Gathering Daemon (EGD) (see <a
322 href="http://www.lothar.com/tech/crypto/">http://www.lothar.com/tech
323 /crypto/</a>) to seed the PRNG. Use this if no random device exists
331 SSLRandomSeed startup builtin
332 SSLRandomSeed startup file:/dev/random
333 SSLRandomSeed startup file:/dev/urandom 1024
334 SSLRandomSeed startup exec:/usr/local/bin/truerand 16
335 SSLRandomSeed connect builtin
336 SSLRandomSeed connect file:/dev/random
337 SSLRandomSeed connect file:/dev/urandom 1024
342 <!-- SSLSessionCache ------------------------------------------------>
346 <a name="SSLSessionCache"></a>
347 <h2>SSLSessionCache</h2>
350 name="SSLSessionCache"
351 description="Type of the global/inter-process SSL Session Cache"
352 syntax="<code>SSLSessionCache</code> <em>type</em>"
353 default="<code>SSLSessionCache none</code>"
354 context="server config"
355 override="<em>Not applicable</em>"
360 This configures the storage type of the global/inter-process SSL Session
361 Cache. This cache is an optional facility which speeds up parallel request
362 processing. For requests to the same server process (via HTTP keep-alive),
363 OpenSSL already caches the SSL session information locally. But because modern
364 clients request inlined images and other data via parallel requests (usually
365 up to four parallel requests are common) those requests are served by
366 <em>different</em> pre-forked server processes. Here an inter-process cache
367 helps to avoid unneccessary session handshakes.
370 The following two storage <em>type</em>s are currently supported:
373 <li><code>none</code>
375 This is the default and just disables the global/inter-process Session
376 Cache. There is no drawback in functionality, but a noticeable speed
377 penalty can be observed.
379 <li><code>dbm:/path/to/datafile</code>
381 This makes use of a DBM hashfile on the local disk to synchronize the
382 local OpenSSL memory caches of the server processes. The slight increase
383 in I/O on the server results in a visible request speedup for your
384 clients, so this type of storage is generally recommended.
386 <li><code>shm:/path/to/datafile</code>[<code>(</code><i>size</i><code>)</code>]
388 This makes use of a high-performance hash table (approx. <i>size</i> bytes
389 in size) inside a shared memory segment in RAM (established via
390 <code>/path/to/datafile</code>) to synchronize the local OpenSSL memory
391 caches of the server processes. This storage type is not available on all
392 platforms. See the mod_ssl <code>INSTALL</code> document for details on
393 how to build Apache+EAPI with shared memory support.
400 SSLSessionCache dbm:/usr/local/apache/logs/ssl_gcache_data
401 SSLSessionCache shm:/usr/local/apache/logs/ssl_gcache_data(512000)
406 <!-- SSLSessionCacheTimeout ----------------------------------------->
410 <a name="SSLSessionCacheTimeout"></a>
411 <h2>SSLSessionCacheTimeout</h2>
414 name="SSLSessionCacheTimeout"
415 description="Number of seconds before an SSL session expires in the Session Cache"
416 syntax="<code>SSLSessionCacheTimeout</code> <em>seconds</em>"
417 default="<code>SSLSessionCacheTimeout 300</code>"
418 context="server config, virtual host"
419 override="<em>Not applicable</em>"
424 This directive sets the timeout in seconds for the information stored in the
425 global/inter-process SSL Session Cache and the OpenSSL internal memory cache.
426 It can be set as low as 15 for testing, but should be set to higher
427 values like 300 in real life.
433 SSLSessionCacheTimeout 600
438 <!-- SSLEngine ------------------------------------------------------>
442 <a name="SSLEngine"></a>
447 description="SSL Engine Operation Switch"
448 syntax="<code>SSLEngine</code> <em>on|off</em>"
449 default="<code>SSLEngine off</code>"
450 context="server config, virtual host"
451 override="<em>Not applicable</em>"
456 This directive toggles the usage of the SSL/TLS Protocol Engine. This is
457 usually used inside a <VirtualHost> section to enable SSL/TLS for a
458 particular virtual host. By default the SSL/TLS Protocol Engine is disabled
459 for both the main server and all configured virtual hosts.
465 <VirtualHost _default_:443>
473 <!-- SSLProtocol ---------------------------------------------------->
477 <a name="SSLProtocol"></a>
482 description="Configure usable SSL protocol flavors"
483 syntax="<code>SSLProtocol</code> [+-]<em>protocol</em> ..."
484 default="<code>SSLProtocol all</code>"
485 context="server config, virtual host"
491 This directive can be used to control the SSL protocol flavors mod_ssl should
492 use when establishing its server environment. Clients then can only connect
493 with one of the provided protocols.
496 The available (case-insensitive) <em>protocol</em>s are:
499 <li><code>SSLv2</code>
501 This is the Secure Sockets Layer (SSL) protocol, version 2.0. It is the
502 original SSL protocol as designed by Netscape Corporation.
504 <li><code>SSLv3</code>
506 This is the Secure Sockets Layer (SSL) protocol, version 3.0. It is the
507 successor to SSLv2 and the currently (as of February 1999) de-facto
508 standardized SSL protocol from Netscape Corporation. It's supported by
509 almost all popular browsers.
511 <li><code>TLSv1</code>
513 This is the Transport Layer Security (TLS) protocol, version 1.0. It is the
514 successor to SSLv3 and currently (as of February 1999) still under
515 construction by the Internet Engineering Task Force (IETF). It's still
516 not supported by all popular browsers.
520 This is a shortcut for ``<code>+SSLv2 +SSLv3 +TLSv1</code>'' and a
521 convinient way for enabling all protocols except one when used in
522 combination with the minus sign on a protocol as the example above shows.
529 \# enable SSLv3 and TLSv1, but not SSLv2
530 SSLProtocol all -SSLv2
535 <!-- SSLCipherSuite ------------------------------------------------->
539 <a name="SSLCipherSuite"></a>
540 <h2>SSLCipherSuite</h2>
543 name="SSLCipherSuite"
544 description="Cipher Suite available for negotiation in SSL handshake"
545 syntax="<code>SSLCipherSuite</code> <em>cipher-spec</em>"
546 default="<code>SSLCipherSuite ALL:!ADH:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP</code>"
547 context="server config, virtual host, directory, .htaccess"
548 override="AuthConfig"
553 This complex directive uses a colon-separated <em>cipher-spec</em> string
554 consisting of OpenSSL cipher specifications to configure the Cipher Suite the
555 client is permitted to negotiate in the SSL handshake phase. Notice that this
556 directive can be used both in per-server and per-directory context. In
557 per-server context it applies to the standard SSL handshake when a connection
558 is established. In per-directory context it forces a SSL renegotation with the
559 reconfigured Cipher Suite after the HTTP request was read but before the HTTP
563 An SSL cipher specification in <em>cipher-spec</em> is composed of 4 major
564 attributes plus a few extra minor ones:
567 <li><em>Key Exchange Algorithm</em>:<br>
568 RSA or Diffie-Hellman variants.
570 <li><em>Authentication Algorithm</em>:<br>
571 RSA, Diffie-Hellman, DSS or none.
573 <li><em>Cipher/Encryption Algorithm</em>:<br>
574 DES, Triple-DES, RC4, RC2, IDEA or none.
576 <li><em>MAC Digest Algorithm</em>:<br>
580 An SSL cipher can also be an export cipher and is either a SSLv2 or SSLv3/TLSv1
581 cipher (here TLSv1 is equivalent to SSLv3). To specify which ciphers to use,
582 one can either specify all the Ciphers, one at a time, or use aliases to
583 specify the preference and order for the ciphers (see <a href="#table1">Table
587 <float name="table1" caption="Table 1: OpenSSL Cipher Specification Tags">
588 <table border="0" cellspacing="0" cellpadding="2" width=598>
589 <tr id=D><td><b>Tag</b></td> <td><b>Description</b></td>
591 <tr id=H><td colspan=2><em>Key Exchange Algorithm:</em></td></tr>
592 <tr id=D><td><code>kRSA</code></td> <td>RSA key exchange</td></tr>
593 <tr id=H><td><code>kDHr</code></td> <td>Diffie-Hellman key exchange with RSA key</td></tr>
594 <tr id=D><td><code>kDHd</code></td> <td>Diffie-Hellman key exchange with DSA key</td></tr>
595 <tr id=H><td><code>kEDH</code></td> <td>Ephemeral (temp.key) Diffie-Hellman key exchange (no cert)</td> </tr>
597 <tr id=H><td colspan=2><em>Authentication Algorithm:</em></td></tr>
598 <tr id=D><td><code>aNULL</code></td> <td>No authentication</td></tr>
599 <tr id=H><td><code>aRSA</code></td> <td>RSA authentication</td></tr>
600 <tr id=D><td><code>aDSS</code></td> <td>DSS authentication</td> </tr>
601 <tr id=H><td><code>aDH</code></td> <td>Diffie-Hellman authentication</td></tr>
603 <tr id=D><td colspan=2><em>Cipher Encoding Algorithm:</em></td></tr></tr>
604 <tr id=H><td><code>eNULL</code></td> <td>No encoding</td> </tr>
605 <tr id=D><td><code>DES</code></td> <td>DES encoding</td> </tr>
606 <tr id=H><td><code>3DES</code></td> <td>Triple-DES encoding</td> </tr>
607 <tr id=D><td><code>RC4</code></td> <td>RC4 encoding</td> </tr>
608 <tr id=H><td><code>RC2</code></td> <td>RC2 encoding</td> </tr>
609 <tr id=D><td><code>IDEA</code></td> <td>IDEA encoding</td> </tr>
611 <tr id=H><td colspan=2><em>MAC Digest Algorithm</em>:</td></tr>
612 <tr id=D><td><code>MD5</code></td> <td>MD5 hash function</td></tr>
613 <tr id=H><td><code>SHA1</code></td> <td>SHA1 hash function</td></tr>
614 <tr id=D><td><code>SHA</code></td> <td>SHA hash function</td> </tr>
616 <tr id=H><td colspan=2><em>Aliases:</em></td></tr>
617 <tr id=D><td><code>SSLv2</code></td> <td>all SSL version 2.0 ciphers</td></tr>
618 <tr id=H><td><code>SSLv3</code></td> <td>all SSL version 3.0 ciphers</td> </tr>
619 <tr id=D><td><code>TLSv1</code></td> <td>all TLS version 1.0 ciphers</td> </tr>
620 <tr id=H><td><code>EXP</code></td> <td>all export ciphers</td> </tr>
621 <tr id=D><td><code>EXPORT40</code></td> <td>all 40-bit export ciphers only</td> </tr>
622 <tr id=H><td><code>EXPORT56</code></td> <td>all 56-bit export ciphers only</td> </tr>
623 <tr id=D><td><code>LOW</code></td> <td>all low strength ciphers (no export, single DES)</td></tr>
624 <tr id=H><td><code>MEDIUM</code></td> <td>all ciphers with 128 bit encryption</td> </tr>
625 <tr id=D><td><code>HIGH</code></td> <td>all ciphers using Triple-DES</td> </tr>
626 <tr id=H><td><code>RSA</code></td> <td>all ciphers using RSA key exchange</td> </tr>
627 <tr id=D><td><code>DH</code></td> <td>all ciphers using Diffie-Hellman key exchange</td> </tr>
628 <tr id=H><td><code>EDH</code></td> <td>all ciphers using Ephemeral Diffie-Hellman key exchange</td> </tr>
629 <tr id=D><td><code>ADH</code></td> <td>all ciphers using Anonymous Diffie-Hellman key exchange</td> </tr>
630 <tr id=H><td><code>DSS</code></td> <td>all ciphers using DSS authentication</td> </tr>
631 <tr id=D><td><code>NULL</code></td> <td>all ciphers using no encryption</td> </tr>
637 Now where this becomes interesting is that these can be put together
638 to specify the order and ciphers you wish to use. To speed this up
639 there are also aliases (<code>SSLv2, SSLv3, TLSv1, EXP, LOW, MEDIUM,
640 HIGH</code>) for certain groups of ciphers. These tags can be joined
641 together with prefixes to form the <em>cipher-spec</em>. Available
645 <li>none: add cipher to list
646 <li><code>+</code>: add ciphers to list and pull them to current location in list
647 <li><code>-</code>: remove cipher from list (can be added later again)
648 <li><code>!</code>: kill cipher from list completely (can <b>not</b> be added later again)
651 A simpler way to look at all of this is to use the ``<code>openssl ciphers
652 -v</code>'' command which provides a nice way to successively create the
653 correct <em>cipher-spec</em> string. The default <em>cipher-spec</em> string
654 is ``<code>ALL:!ADH:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP</code>'' which
655 means the following: first, remove from consideration any ciphers that do not
656 authenticate, i.e. for SSL only the Anonymous Diffie-Hellman ciphers. Next,
657 use ciphers using RC4 and RSA. Next include the high, medium and then the low
658 security ciphers. Finally <em>pull</em> all SSLv2 and export ciphers to the
663 $ openssl ciphers -v 'ALL:!ADH:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP'
664 NULL-SHA SSLv3 Kx=RSA Au=RSA Enc=None Mac=SHA1
665 NULL-MD5 SSLv3 Kx=RSA Au=RSA Enc=None Mac=MD5
666 EDH-RSA-DES-CBC3-SHA SSLv3 Kx=DH Au=RSA Enc=3DES(168) Mac=SHA1
668 EXP-RC4-MD5 SSLv3 Kx=RSA(512) Au=RSA Enc=RC4(40) Mac=MD5 export
669 EXP-RC2-CBC-MD5 SSLv2 Kx=RSA(512) Au=RSA Enc=RC2(40) Mac=MD5 export
670 EXP-RC4-MD5 SSLv2 Kx=RSA(512) Au=RSA Enc=RC4(40) Mac=MD5 export
674 The complete list of particular RSA & DH ciphers for SSL is given in <a
675 href="#table2">Table 2</a>.
681 # allow only strongest RSA ciphers
682 SSLCipherSuite RSA:!EXP:!NULL:+HIGH:+MEDIUM:-LOW
687 <float name="table2" caption="Table 2: Particular SSL Ciphers">
688 <table border="0" cellspacing="0" cellpadding="2" width=598>
689 <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>
691 <tr id=H><td colspan=7><em>RSA Ciphers:</em></td></tr>
692 <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>
693 <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>
694 <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>
695 <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>
696 <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>
697 <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>
698 <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>
699 <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>
700 <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>
701 <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>
702 <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>
703 <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>
704 <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>
705 <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>
706 <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>
707 <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>
708 <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>
709 <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>
711 <tr id=D><td colspan=7><em>Diffie-Hellman Ciphers:</em></td></tr>
712 <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>
713 <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>
714 <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>
715 <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>
716 <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>
717 <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>
718 <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>
719 <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>
720 <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>
721 <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>
722 <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>
727 <!-- SSLCertificateFile --------------------------------------------->
731 <a name="SSLCertificateFile"></a>
732 <h2>SSLCertificateFile</h2>
735 name="SSLCertificateFile"
736 description="Server PEM-encoded X.509 Certificate file"
737 syntax="<code>SSLCertificateFile</code> <em>filename</em>"
738 default="<em>None</em>"
739 context="server config, virtual host"
740 override="<em>Not applicable</em>"
745 This directive points to the PEM-encoded Certificate file for the server and
746 optionally also to the corresponding RSA or DSA Private Key file for it
747 (contained in the same file). If the contained Private Key is encrypted the
748 Pass Phrase dialog is forced at startup time. This directive can be used up to
749 two times (referencing different filenames) when both a RSA and a DSA based
750 server certificate is used in parallel.
756 SSLCertificateFile /usr/local/apache/conf/ssl.crt/server.crt
761 <!-- SSLCertificateKeyFile ------------------------------------------>
765 <a name="SSLCertificateKeyFile"></a>
766 <h2>SSLCertificateKeyFile</h2>
769 name="SSLCertificateKeyFile"
770 description="Server PEM-encoded Private Key file"
771 syntax="<code>SSLCertificateKeyFile</code> <em>filename</em>"
772 default="<em>None</em>"
773 context="server config, virtual host"
774 override="<em>Not applicable</em>"
779 This directive points to the PEM-encoded Private Key file for the server. If
780 the Private Key is not combined with the Certificate in the
781 <code>SSLCertificateFile</code>, use this additional directive to point to the
782 file with the stand-alone Private Key. When <code>SSLCertificateFile</code>
783 is used and the file contains both the Certificate and the Private Key this
784 directive need not be used. But we strongly discourage this practice.
785 Instead we recommend you to separate the Certificate and the Private Key. If
786 the contained Private Key is encrypted, the Pass Phrase dialog is forced at
787 startup time. This directive can be used up to two times (referencing
788 different filenames) when both a RSA and a DSA based private key is used in
795 SSLCertificateKeyFile /usr/local/apache/conf/ssl.key/server.key
800 <!-- SSLCertificateChainFile ---------------------------------------->
804 <a name="SSLCertificateChainFile"></a>
805 <h2>SSLCertificateChainFile</h2>
808 name="SSLCertificateChainFile"
809 description="File of PEM-encoded Server CA Certificates"
810 syntax="<code>SSLCertificateChainFile</code> <em>filename</em>"
811 default="<em>None</em>"
812 context="server config, virtual host"
813 override="<em>Not applicable</em>"
814 compat="mod_ssl 2.3.6"
818 This directive sets the optional <em>all-in-one</em> file where you can
819 assemble the certificates of Certification Authorities (CA) which form the
820 certificate chain of the server certificate. This starts with the issuing CA
821 certificate of of the server certificate and can range up to the root CA
822 certificate. Such a file is simply the concatenation of the various
823 PEM-encoded CA Certificate files, usually in certificate chain order.
826 This should be used alternatively and/or additionally to <a
827 href="#SSLCACertificatePath">SSLCACertificatePath</a> for explicitly
828 constructing the server certificate chain which is sent to the browser in
829 addition to the server certificate. It is especially useful to avoid conflicts
830 with CA certificates when using client authentication. Because although
831 placing a CA certificate of the server certificate chain into <a
832 href="#SSLCACertificatePath">SSLCACertificatePath</a> has the same effect for
833 the certificate chain construction, it has the side-effect that client
834 certificates issued by this same CA certificate are also accepted on client
835 authentication. That's usually not one expect.
838 But be careful: Providing the certificate chain works only if you are using a
839 <i>single</i> (either RSA <i>or</i> DSA) based server certificate. If you are
840 using a coupled RSA+DSA certificate pair, this will work only if actually both
841 certificates use the <i>same</i> certificate chain. Else the browsers will be
842 confused in this situation.
848 SSLCertificateChainFile /usr/local/apache/conf/ssl.crt/ca.crt
853 <!-- SSLCACertificatePath ------------------------------------------->
857 <a name="SSLCACertificatePath"></a>
858 <h2>SSLCACertificatePath</h2>
861 name="SSLCACertificatePath"
862 description="Directory of PEM-encoded CA Certificates for Client Auth."
863 syntax="<code>SSLCACertificatePath</code> <em>directory</em>"
864 default="<em>None</em>"
865 context="server config, virtual host"
866 override="<em>Not applicable</em>"
871 This directive sets the directory where you keep the Certificates of
872 Certification Authorities (CAs) whose clients you deal with. These are used to
873 verify the client certificate on Client Authentication.
876 The files in this directory have to be PEM-encoded and are accessed through
877 hash filenames. So usually you can't just place the Certificate files
878 there: you also have to create symbolic links named
879 <i>hash-value</i><tt>.N</tt>. And you should always make sure this directory
880 contains the appropriate symbolic links. Use the <code>Makefile</code> which
881 comes with mod_ssl to accomplish this task.
887 SSLCACertificatePath /usr/local/apache/conf/ssl.crt/
892 <!-- SSLCACertificateFile ------------------------------------------->
896 <a name="SSLCACertificateFile"></a>
897 <h2>SSLCACertificateFile</h2>
900 name="SSLCACertificateFile"
901 description="File of concatenated PEM-encoded CA Certificates for Client Auth."
902 syntax="<code>SSLCACertificateFile</code> <em>filename</em>"
903 default="<em>None</em>"
904 context="server config, virtual host"
905 override="<em>Not applicable</em>"
910 This directive sets the <em>all-in-one</em> file where you can assemble the
911 Certificates of Certification Authorities (CA) whose <em>clients</em> you deal
912 with. These are used for Client Authentication. Such a file is simply the
913 concatenation of the various PEM-encoded Certificate files, in order of
914 preference. This can be used alternatively and/or additionally to <a
915 href="#SSLCACertificatePath">SSLCACertificatePath</a>.
921 SSLCACertificateFile /usr/local/apache/conf/ssl.crt/ca-bundle-client.crt
926 <!-- SSLCARevocationPath -------------------------------------------->
930 <a name="SSLCARevocationPath"></a>
931 <h2>SSLCARevocationPath</h2>
934 name="SSLCARevocationPath"
935 description="Directory of PEM-encoded CA CRLs for Client Auth."
936 syntax="<code>SSLCARevocationPath</code> <em>directory</em>"
937 default="<em>None</em>"
938 context="server config, virtual host"
939 override="<em>Not applicable</em>"
944 This directive sets the directory where you keep the Certificate Revocation
945 Lists (CRL) of Certification Authorities (CAs) whose clients you deal with.
946 These are used to revoke the client certificate on Client Authentication.
949 The files in this directory have to be PEM-encoded and are accessed through
950 hash filenames. So usually you have not only to place the CRL files there.
951 Additionally you have to create symbolic links named
952 <i>hash-value</i><tt>.rN</tt>. And you should always make sure this directory
953 contains the appropriate symbolic links. Use the <code>Makefile</code> which
954 comes with mod_ssl to accomplish this task.
960 SSLCARevocationPath /usr/local/apache/conf/ssl.crl/
965 <!-- SSLCARevocationFile -------------------------------------------->
969 <a name="SSLCARevocationFile"></a>
970 <h2>SSLCARevocationFile</h2>
973 name="SSLCARevocationFile"
974 description="File of concatenated PEM-encoded CA CRLs for Client Auth."
975 syntax="<code>SSLCARevocationFile</code> <em>filename</em>"
976 default="<em>None</em>"
977 context="server config, virtual host"
978 override="<em>Not applicable</em>"
983 This directive sets the <em>all-in-one</em> file where you can assemble the
984 Certificate Revocation Lists (CRL) of Certification Authorities (CA) whose
985 <em>clients</em> you deal with. These are used for Client Authentication.
986 Such a file is simply the concatenation of the various PEM-encoded CRL
987 files, in order of preference. This can be used alternatively and/or
988 additionally to <a href="#SSLCARevocationPath">SSLCARevocationPath</a>.
994 SSLCARevocationFile /usr/local/apache/conf/ssl.crl/ca-bundle-client.crl
999 <!-- SSLVerifyClient ------------------------------------------------->
1003 <a name="SSLVerifyClient"></a>
1004 <h2>SSLVerifyClient</h2>
1007 name="SSLVerifyClient"
1008 description="Type of Client Certificate verification"
1009 syntax="<code>SSLVerifyClient</code> <em>level</em>"
1010 default="<code>SSLVerifyClient none</code>"
1011 context="server config, virtual host, directory, .htaccess"
1012 override="AuthConfig"
1013 compat="mod_ssl 2.0"
1017 This directive sets the Certificate verification level for the Client
1018 Authentication. Notice that this directive can be used both in per-server and
1019 per-directory context. In per-server context it applies to the client
1020 authentication process used in the standard SSL handshake when a connection is
1021 established. In per-directory context it forces a SSL renegotation with the
1022 reconfigured client verification level after the HTTP request was read but
1023 before the HTTP response is sent.
1026 The following levels are available for <em>level</em>:
1029 <li><strong>none</strong>:
1030 no client Certificate is required at all
1031 <li><strong>optional</strong>:
1032 the client <em>may</em> present a valid Certificate
1033 <li><strong>require</strong>:
1034 the client <em>has to</em> present a valid Certificate
1035 <li><strong>optional_no_ca</strong>:
1036 the client may present a valid Certificate<br>
1037 but it need not to be (successfully) verifiable.
1040 In practice only levels <strong>none</strong> and <strong>require</strong> are
1041 really interesting, because level <strong>optional</strong> doesn't work with
1042 all browsers and level <strong>optional_no_ca</strong> is actually against the
1043 idea of authentication (but can be used to establish SSL test pages, etc.)
1049 SSLVerifyClient require
1054 <!-- SSLVerifyDepth ------------------------------------------------->
1058 <a name="SSLVerifyDepth"></a>
1059 <h2>SSLVerifyDepth</h2>
1062 name="SSLVerifyDepth"
1063 description="Maximum depth of CA Certificates in Client Certificate verification"
1064 syntax="<code>SSLVerifyDepth</code> <em>number</em>"
1065 default="<code>SSLVerifyDepth 1</code>"
1066 context="server config, virtual host, directory, .htaccess"
1067 override="AuthConfig"
1068 compat="mod_ssl 2.0"
1072 This directive sets how deeply mod_ssl should verify before deciding that the
1073 clients don't have a valid certificate. Notice that this directive can be
1074 used both in per-server and per-directory context. In per-server context it
1075 applies to the client authentication process used in the standard SSL
1076 handshake when a connection is established. In per-directory context it forces
1077 a SSL renegotation with the reconfigured client verification depth after the
1078 HTTP request was read but before the HTTP response is sent.
1081 The depth actually is the maximum number of intermediate certificate issuers,
1082 i.e. the number of CA certificates which are max allowed to be followed while
1083 verifying the client certificate. A depth of 0 means that self-signed client
1084 certificates are accepted only, the default depth of 1 means the client
1085 certificate can be self-signed or has to be signed by a CA which is directly
1086 known to the server (i.e. the CA's certificate is under
1087 <code>SSLCACertificatePath</code>), etc.
1098 <!-- SSLLog --------------------------------------------------------->
1102 <a name="SSLLog"></a>
1107 description="Where to write the dedicated SSL engine logfile"
1108 syntax="<code>SSLLog</code> <em>filename</em>"
1109 default="<em>None</em>"
1110 context="server config, virtual host"
1111 override="<em>Not applicable</em>"
1112 compat="mod_ssl 2.1"
1116 This directive sets the name of the dedicated SSL protocol engine logfile.
1117 Error type messages are additionally duplicated to the general Apache error
1118 log file (directive <code>ErrorLog</code>). Put this somewhere where it cannot
1119 be used for symlink attacks on a real server (i.e. somewhere where only root
1120 can write). If the <em>filename</em> does not begin with a slash
1121 ('<code>/</code>') then it is assumed to be relative to the <em>Server
1122 Root</em>. If <em>filename</em> begins with a bar ('<code>|</code>') then the
1123 following string is assumed to be a path to an executable program to which a
1124 reliable pipe can be established. The directive should occur only once per
1125 virtual server config.
1131 SSLLog /usr/local/apache/logs/ssl_engine_log
1136 <!-- SSLLogLevel ---------------------------------------------------->
1140 <a name="SSLLogLevel"></a>
1141 <h2>SSLLogLevel</h2>
1145 description="Logging level for the dedicated SSL engine logfile"
1146 syntax="<code>SSLLogLevel</code> <em>level</em>"
1147 default="<code>SSLLogLevel none</code>"
1148 context="server config, virtual host"
1149 override="<em>Not applicable</em>"
1150 compat="mod_ssl 2.1"
1154 This directive sets the verbosity degree of the dedicated SSL protocol engine
1155 logfile. The <em>level</em> is one of the following (in ascending order where
1156 higher levels include lower levels):
1159 <li><code>none</code><br>
1160 no dedicated SSL logging is done, but messages of level
1161 ``<code>error</code>'' are still written to the general Apache error
1164 <li><code>error</code><br>
1165 log messages of error type only, i.e. messages which show fatal situations
1166 (processing is stopped). Those messages are also duplicated to the
1167 general Apache error logfile.
1169 <li><code>warn</code><br>
1170 log also warning messages, i.e. messages which show non-fatal problems
1171 (processing is continued).
1173 <li><code>info</code><br>
1174 log also informational messages, i.e. messages which show major
1177 <li><code>trace</code><br>
1178 log also trace messages, i.e. messages which show minor processing steps.
1180 <li><code>debug</code><br>
1181 log also debugging messages, i.e. messages which show development and
1182 low-level I/O information.
1194 <!-- SSLOptions ----------------------------------------------------->
1198 <a name="SSLOptions"></a>
1203 description="Configure various SSL engine run-time options"
1204 syntax="<code>SSLOptions</code> [+-]<em>option</em> ..."
1205 default="<em>None</em>"
1206 context="server config, virtual host, directory, .htaccess"
1208 compat="mod_ssl 2.1"
1212 This directive can be used to control various run-time options on a
1213 per-directory basis. Normally, if multiple <code>SSLOptions</code> could
1214 apply to a directory, then the most specific one is taken completely; the
1215 options are not merged. However if <em>all</em> the options on the
1216 <code>SSLOptions</code> directive are preceded by a plus (<code>+</code>) or
1217 minus (<code>-</code>) symbol, the options are merged. Any options preceded by
1218 a <code>+</code> are added to the options currently in force, and any options
1219 preceded by a <code>-</code> are removed from the options currently in force.
1222 The available <em>option</em>s are:
1225 <li><code>StdEnvVars</code>
1227 When this option is enabled, the standard set of SSL related CGI/SSI
1228 environment variables are created. This per default is disabled for
1229 performance reasons, because the information extraction step is a
1230 rather expensive operation. So one usually enables this option for
1231 CGI and SSI requests only.
1233 <li><code>CompatEnvVars</code>
1235 When this option is enabled, additional CGI/SSI environment variables are
1236 created for backward compatibility to other Apache SSL solutions. Look in
1237 the <a href="ssl_compat.html">Compatibility</a> chapter for details
1238 on the particular variables generated.
1240 <li><code>ExportCertData</code>
1242 When this option is enabled, additional CGI/SSI environment variables are
1243 created: <code>SSL_SERVER_CERT</code>, <code>SSL_CLIENT_CERT</code> and
1244 <code>SSL_CLIENT_CERT_CHAIN</code><i>n</i> (with <i>n</i> = 0,1,2,..).
1245 These contain the PEM-encoded X.509 Certificates of server and client for
1246 the current HTTPS connection and can be used by CGI scripts for deeper
1247 Certificate checking. Additionally all other certificates of the client
1248 certificate chain are provided, too. This bloats up the environment a
1249 little bit which is why you have to use this option to enable it on
1252 <li><code>FakeBasicAuth</code>
1254 When this option is enabled, the Subject Distinguished Name (DN) of the
1255 Client X509 Certificate is translated into a HTTP Basic Authorization
1256 username. This means that the standard Apache authentication methods can
1257 be used for access control. The user name is just the Subject of the
1258 Client's X509 Certificate (can be determined by running OpenSSL's
1259 <code>openssl x509</code> command: <code>openssl x509 -noout -subject -in
1260 </code><em>certificate</em><code>.crt</code>). Note that no password is
1261 obtained from the user. Every entry in the user file needs this password:
1262 ``<code>xxj31ZMTZzkVA</code>'', which is the DES-encrypted version of the
1263 word `<code>password</code>''. Those who live under MD5-based encryption
1264 (for instance under FreeBSD or BSD/OS, etc.) should use the following MD5
1265 hash of the same word: ``<code>$1$OXLyS...$Owx8s2/m9/gfkcRVXzgoE/</code>''.
1267 <li><code>StrictRequire</code>
1269 This <i>forces</i> forbidden access when <code>SSLRequireSSL</code> or
1270 <code>SSLRequire</code> successfully decided that access should be
1271 forbidden. Usually the default is that in the case where a ``<code>Satisfy
1272 any</code>'' directive is used, and other access restrictions are passed,
1273 denial of access due to <code>SSLRequireSSL</code> or
1274 <code>SSLRequire</code> is overridden (because that's how the Apache
1275 <tt>Satisfy</tt> mechanism should work.) But for strict access restriction
1276 you can use <code>SSLRequireSSL</code> and/or <code>SSLRequire</code> in
1277 combination with an ``<code>SSLOptions +StrictRequire</code>''. Then an
1278 additional ``<code>Satisfy Any</code>'' has no chance once mod_ssl has
1279 decided to deny access.
1281 <li><code>OptRenegotiate</code>
1283 This enables optimized SSL connection renegotiation handling when SSL
1284 directives are used in per-directory context. By default a strict
1285 scheme is enabled where <i>every</i> per-directory reconfiguration of
1286 SSL parameters causes a <i>full</i> SSL renegotiation handshake. When this
1287 option is used mod_ssl tries to avoid unnecessary handshakes by doing more
1288 granular (but still safe) parameter checks. Nevertheless these granular
1289 checks sometimes maybe not what the user expects, so enable this on a
1290 per-directory basis only, please.
1297 SSLOptions +FakeBasicAuth -StrictRequire
1298 <Files ~ "\.(cgi|shtml)$">
1299 SSLOptions +StdEnvVars +CompatEnvVars -ExportCertData
1305 <!-- SSLRequireSSL -------------------------------------------------->
1309 <a name="SSLRequireSSL"></a>
1310 <h2>SSLRequireSSL</h2>
1313 name="SSLRequireSSL"
1314 description="Deny access when SSL is not used for the HTTP request"
1315 syntax="<code>SSLRequireSSL</code>"
1316 default="<em>None</em>"
1317 context="directory, .htaccess"
1318 override="AuthConfig"
1319 compat="mod_ssl 2.0"
1323 This directive forbids access unless HTTP over SSL (i.e. HTTPS) is enabled for
1324 the current connection. This is very handy inside the SSL-enabled virtual
1325 host or directories for defending against configuration errors that expose
1326 stuff that should be protected. When this directive is present all requests
1327 are denied which are not using SSL.
1338 <!-- SSLRequire ----------------------------------------------------->
1342 <a name="SSLRequire"></a>
1347 description="Allow access only when an arbitrarily complex boolean expression is true"
1348 syntax="<code>SSLRequire</code> <em>expression</em>"
1349 default="<em>None</em>"
1350 context="directory, .htaccess"
1351 override="AuthConfig"
1352 compat="mod_ssl 2.1"
1356 This directive specifies a general access requirement which has to be
1357 fulfilled in order to allow access. It's a very powerful directive because the
1358 requirement specification is an arbitrarily complex boolean expression
1359 containing any number of access checks.
1362 The <em>expression</em> must match the following syntax (given as a BNF
1367 expr ::= "<b>true</b>" | "<b>false</b>"
1369 | expr "<b>&&</b>" expr
1370 | expr "<b>||</b>" expr
1371 | "<b>(</b>" expr "<b>)</b>"
1374 comp ::= word "<b>==</b>" word | word "<b>eq</b>" word
1375 | word "<b>!=</b>" word | word "<b>ne</b>" word
1376 | word "<b><</b>" word | word "<b>lt</b>" word
1377 | word "<b><=</b>" word | word "<b>le</b>" word
1378 | word "<b>></b>" word | word "<b>gt</b>" word
1379 | word "<b>>=</b>" word | word "<b>ge</b>" word
1380 | word "<b>in</b>" "<b>{</b>" wordlist "<b>}</b>"
1381 | word "<b>=~</b>" regex
1382 | word "<b>!~</b>" regex
1385 | wordlist "<b>,</b>" word
1394 variable ::= "<b>%{</b>" varname "<b>}</b>"
1395 function ::= funcname "<b>(</b>" funcargs "<b>)</b>"
1399 while for <code>varname</code> any variable from <a href="#table3">Table 3</a>
1400 can be used. Finally for <code>funcname</code> the following functions
1404 <li><code>file(</code><em>filename</em><code>)</code>
1406 This function takes one string argument and expands to the contents of the
1407 file. This is especially useful for matching this contents against a
1408 regular expression, etc.
1411 Notice that <em>expression</em> is first parsed into an internal machine
1412 representation and then evaluated in a second step. Actually, in Global and
1413 Per-Server Class context <em>expression</em> is parsed at startup time and
1414 at runtime only the machine representation is executed. For Per-Directory
1415 context this is different: here <em>expression</em> has to be parsed and
1416 immediately executed for every request.
1422 SSLRequire ( %{SSL_CIPHER} !~ m/^(EXP|NULL)-/ \\
1423 and %{SSL_CLIENT_S_DN_O} eq "Snake Oil, Ltd." \\
1424 and %{SSL_CLIENT_S_DN_OU} in {"Staff", "CA", "Dev"} \\
1425 and %{TIME_WDAY} >= 1 and %{TIME_WDAY} <= 5 \\
1426 and %{TIME_HOUR} >= 8 and %{TIME_HOUR} <= 20 ) \\
1427 or %{REMOTE_ADDR} =~ m/^192\.76\.162\.[0-9]+$/
1431 <float name="table3" caption="Table 3: Available Variables for SSLRequire">
1433 <em>Standard CGI/1.0 and Apache variables:</em>
1435 HTTP_USER_AGENT PATH_INFO AUTH_TYPE
1436 HTTP_REFERER QUERY_STRING SERVER_SOFTWARE
1437 HTTP_COOKIE REMOTE_HOST API_VERSION
1438 HTTP_FORWARDED REMOTE_IDENT TIME_YEAR
1439 HTTP_HOST IS_SUBREQ TIME_MON
1440 HTTP_PROXY_CONNECTION DOCUMENT_ROOT TIME_DAY
1441 HTTP_ACCEPT SERVER_ADMIN TIME_HOUR
1442 HTTP:headername SERVER_NAME TIME_MIN
1443 THE_REQUEST SERVER_PORT TIME_SEC
1444 REQUEST_METHOD SERVER_PROTOCOL TIME_WDAY
1445 REQUEST_SCHEME REMOTE_ADDR TIME
1446 REQUEST_URI REMOTE_USER ENV:<b>variablename</b>
1450 <em>SSL-related variables:</em>
1452 HTTPS SSL_CLIENT_M_VERSION SSL_SERVER_M_VERSION
1453 SSL_CLIENT_M_SERIAL SSL_SERVER_M_SERIAL
1454 SSL_PROTOCOL SSL_CLIENT_V_START SSL_SERVER_V_START
1455 SSL_SESSION_ID SSL_CLIENT_V_END SSL_SERVER_V_END
1456 SSL_CIPHER SSL_CLIENT_S_DN SSL_SERVER_S_DN
1457 SSL_CIPHER_EXPORT SSL_CLIENT_S_DN_C SSL_SERVER_S_DN_C
1458 SSL_CIPHER_ALGKEYSIZE SSL_CLIENT_S_DN_ST SSL_SERVER_S_DN_ST
1459 SSL_CIPHER_USEKEYSIZE SSL_CLIENT_S_DN_L SSL_SERVER_S_DN_L
1460 SSL_VERSION_LIBRARY SSL_CLIENT_S_DN_O SSL_SERVER_S_DN_O
1461 SSL_VERSION_INTERFACE SSL_CLIENT_S_DN_OU SSL_SERVER_S_DN_OU
1462 SSL_CLIENT_S_DN_CN SSL_SERVER_S_DN_CN
1463 SSL_CLIENT_S_DN_T SSL_SERVER_S_DN_T
1464 SSL_CLIENT_S_DN_I SSL_SERVER_S_DN_I
1465 SSL_CLIENT_S_DN_G SSL_SERVER_S_DN_G
1466 SSL_CLIENT_S_DN_S SSL_SERVER_S_DN_S
1467 SSL_CLIENT_S_DN_D SSL_SERVER_S_DN_D
1468 SSL_CLIENT_S_DN_UID SSL_SERVER_S_DN_UID
1469 SSL_CLIENT_S_DN_Email SSL_SERVER_S_DN_Email
1470 SSL_CLIENT_I_DN SSL_SERVER_I_DN
1471 SSL_CLIENT_I_DN_C SSL_SERVER_I_DN_C
1472 SSL_CLIENT_I_DN_ST SSL_SERVER_I_DN_ST
1473 SSL_CLIENT_I_DN_L SSL_SERVER_I_DN_L
1474 SSL_CLIENT_I_DN_O SSL_SERVER_I_DN_O
1475 SSL_CLIENT_I_DN_OU SSL_SERVER_I_DN_OU
1476 SSL_CLIENT_I_DN_CN SSL_SERVER_I_DN_CN
1477 SSL_CLIENT_I_DN_T SSL_SERVER_I_DN_T
1478 SSL_CLIENT_I_DN_I SSL_SERVER_I_DN_I
1479 SSL_CLIENT_I_DN_G SSL_SERVER_I_DN_G
1480 SSL_CLIENT_I_DN_S SSL_SERVER_I_DN_S
1481 SSL_CLIENT_I_DN_D SSL_SERVER_I_DN_D
1482 SSL_CLIENT_I_DN_UID SSL_SERVER_I_DN_UID
1483 SSL_CLIENT_I_DN_Email SSL_SERVER_I_DN_Email
1484 SSL_CLIENT_A_SIG SSL_SERVER_A_SIG
1485 SSL_CLIENT_A_KEY SSL_SERVER_A_KEY
1486 SSL_CLIENT_CERT SSL_SERVER_CERT
1487 SSL_CLIENT_CERT_CHAIN<b>n</b>
1496 <h1>Additional Features</h1>
1498 <h2>Environment Variables</h2>
1500 This module provides a lot of SSL information as additional environment
1501 variables to the SSI and CGI namespace. The generated variables are listed in
1502 <a href="#table4">Table 4</a>. For backward compatibility the information can
1503 be made available under different names, too. Look in the <a
1504 href="ssl_compat.html">Compatibility</a> chapter for details on the
1505 compatibility variables.
1508 <float name="table4" caption="Table 4: SSI/CGI Environment Variables">
1509 <table border="0" cellspacing="0" cellpadding="2" width=598>
1511 <td><b>Variable Name:</b></td>
1512 <td><b>Value Type:</b></td>
1513 <td><b>Description:</b></td>
1515 <tr id=D><td><code>HTTPS</code></td> <td>flag</td> <td>HTTPS is being used.</td></tr>
1516 <tr id=H><td><code>SSL_PROTOCOL</code></td> <td>string</td> <td>The SSL protocol version (SSLv2, SSLv3, TLSv1)</td></tr>
1517 <tr id=H><td><code>SSL_SESSION_ID</code></td> <td>string</td> <td>The hex-encoded SSL session id</td></tr>
1518 <tr id=D><td><code>SSL_CIPHER</code></td> <td>string</td> <td>The cipher specification name</td></tr>
1519 <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>
1520 <tr id=H><td><code>SSL_CIPHER_USEKEYSIZE</code></td> <td>number</td> <td>Number of cipher bits (actually used)</td></tr>
1521 <tr id=D><td><code>SSL_CIPHER_ALGKEYSIZE</code></td> <td>number</td> <td>Number of cipher bits (possible)</td></tr>
1522 <tr id=H><td><code>SSL_VERSION_INTERFACE</code></td> <td>string</td> <td>The mod_ssl program version</td></tr>
1523 <tr id=D><td><code>SSL_VERSION_LIBRARY</code></td> <td>string</td> <td>The OpenSSL program version</td></tr>
1524 <tr id=H><td><code>SSL_CLIENT_M_VERSION</code></td> <td>string</td> <td>The version of the client certificate</td></tr>
1525 <tr id=D><td><code>SSL_CLIENT_M_SERIAL</code></td> <td>string</td> <td>The serial of the client certificate</td></tr>
1526 <tr id=H><td><code>SSL_CLIENT_S_DN</code></td> <td>string</td> <td>Subject DN in client's certificate</td></tr>
1527 <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>
1528 <tr id=H><td><code>SSL_CLIENT_I_DN</code></td> <td>string</td> <td>Issuer DN of client's certificate</td></tr>
1529 <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>
1530 <tr id=H><td><code>SSL_CLIENT_V_START</code></td> <td>string</td> <td>Validity of client's certificate (start time)</td></tr>
1531 <tr id=D><td><code>SSL_CLIENT_V_END</code></td> <td>string</td> <td>Validity of client's certificate (end time)</td></tr>
1532 <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>
1533 <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>
1534 <tr id=H><td><code>SSL_CLIENT_CERT</code></td> <td>string</td> <td>PEM-encoded client certificate</td></tr>
1535 <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>
1536 <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>
1537 <tr id=D><td><code>SSL_SERVER_M_VERSION</code></td> <td>string</td> <td>The version of the server certificate</td></tr>
1538 <tr id=H><td><code>SSL_SERVER_M_SERIAL</code></td> <td>string</td> <td>The serial of the server certificate</td></tr>
1539 <tr id=D><td><code>SSL_SERVER_S_DN</code></td> <td>string</td> <td>Subject DN in server's certificate</td></tr>
1540 <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>
1541 <tr id=D><td><code>SSL_SERVER_I_DN</code></td> <td>string</td> <td>Issuer DN of server's certificate</td></tr>
1542 <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>
1543 <tr id=D><td><code>SSL_SERVER_V_START</code></td> <td>string</td> <td>Validity of server's certificate (start time)</td></tr>
1544 <tr id=H><td><code>SSL_SERVER_V_END</code></td> <td>string</td> <td>Validity of server's certificate (end time)</td></tr>
1545 <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>
1546 <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>
1547 <tr id=D><td><code>SSL_SERVER_CERT</code></td> <td>string</td> <td>PEM-encoded server certificate</td></tr>
1549 [ where <em>x509</em> is a component of a X.509 DN:
1550 <code>C,ST,L,O,OU,CN,T,I,G,S,D,UID,Email</code> ]
1556 <h2>Custom Log Formats</h2>
1558 When mod_ssl is built into Apache or at least loaded (under DSO situation)
1559 additional functions exist for the <a
1560 href="../mod_log_config.html#formats">Custom Log Format</a> of <a
1561 href="../mod_log_config.html">mod_log_config</a>. First there is an additional
1562 ``<code>%{</code><em>varname</em><code>}x</code>'' eXtension format function
1563 which can be used to expand any variables provided by any module, especially
1564 those provided by mod_ssl which can you find in <a href="#table4">Table 4</a>.
1567 For backward compatibility there is additionally a special
1568 ``<code>%{</code><em>name</em><code>}c</code>'' cryptography format function
1569 provided. Information about this function is provided in the <a
1570 href="ssl_compat.html">Compatibility</a> chapter.
1576 CustomLog logs/ssl_request_log \\
1577 "%t %h %{SSL_PROTOCOL}x %{SSL_CIPHER}x \"%r\" %b"