ssl_reference.wml

mod_ssl-2.8.31-1.3.41.tar.gz 好用的ssl工具

#use "ssl_template.inc" title="Reference" tag=ref num=3 

<page_prev name="Introduction"  url="ssl_intro.html">
<page_next name="Compatibility" url="ssl_compat.html">

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

<quotation width=150 author="Unknown">
``Try to understand everything,
but believe nothing!''
</quotation>

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

<big T>his chapter provides a reference to all configuration directives and
additional user visible features mod_ssl provides. It's intended as the
official resource when you want to know how a particilar mod_ssl functionality
is actually configured or activated.  Each directive is documented similar to
the way standard Apache directives are documented in the official Apache
documentation set, i.e. for each directive especially the syntax, default and
context where applicable is given. 

<p>
Notice that there are three major classes of directives which are used by
mod_ssl: First <em>Global Directives</em> (i.e. directives with context
``server config''), which can occur inside the server config files but only
outside of any sectioning commands like &lt;VirtualHost&gt;.  Second
<em>Per-Server Directives</em> (i.e. those with context ``server config,
virtual host''), which can occur inside the server config files both outside
(for the main/default server) and inside &lt;VirtualHost&gt; sections.  

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

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

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

<p>
And third <em>Per-Directory Directives</em> (i.e. those with context ``server
config, virtual host, directory, .htaccess''), which can pretty much occur
everywhere.  Especially both inside the server config files and the
per-directory <code>.htaccess</code> files.  The three classes are subsets of
each other, i.e. directives from the per-directory class can also be used in
the per-server and global context, and directives from the per-server class
can also be used the in the global context.

<p>
Additional directives and environment variables provided by mod_ssl (via
on-the-fly mapping) for backward compatiblity to other Apache SSL solutions
are documented in the <a href="ssl_compat.html">Compatibility</a> chapter.


<h1>Configuration Directives</h1>

The most visible and error-prone things of mod_ssl are its configuration
directives. So we document them in great detail here to assist you in setting
up the best possible configuration of your SSL-aware webserver.


<!-- SSLPassPhraseDialog -------------------------------------------->

<p>
<br>
<a name="SSLPassPhraseDialog"></a>
<h2>SSLPassPhraseDialog</h2>

<p>
<directive
    name="SSLPassPhraseDialog"
    description="Type of pass phrase dialog for encrypted private keys"
    syntax="<code>SSLPassPhraseDialog</code> <em>type</em>"
    default="<code>SSLPassPhraseDialog builtin</code>"
    context="server config"
    override="<em>Not applicable</em>"
    compat="mod_ssl 2.1"
>

<p>
When Apache starts up it has to read the various Certificate (see <a
href="#SSLCertificateFile">SSLCertificateFile</a>) and Private Key (see <a
href="#SSLCertificateKeyFile">SSLCertificateKeyFile</a>) files of the
SSL-enabled virtual servers. Because for security reasons the Private Key
files are usually encrypted, mod_ssl needs to query the administrator for a
Pass Phrase in order to decrypt those files. This query can be done in two ways
which can be configured by <em>type</em>:

<ul>
<li><code>builtin</code>
    <p>
    This is the default where an interactive terminal dialog occurs at startup
    time just before Apache detaches from the terminal. Here the administrator
    has to manually enter the Pass Phrase for each encrypted Private Key file.
    Because a lot of SSL-enabled virtual hosts can be configured, the
    following reuse-scheme is used to minimize the dialog: When a Private Key
    file is encrypted, all known Pass Phrases (at the beginning there are
    none, of course) are tried. If one of those known Pass Phrases succeeds no
    dialog pops up for this particular Private Key file.  If none succeeded,
    another Pass Phrase is queried on the terminal and remembered for the next
    round (where it perhaps can be reused). 
    <p> 
    This scheme allows mod_ssl to be maximally flexible (because for N encrypted
    Private Key files you <em>can</em> use N different Pass Phrases - but then
    you have to enter all of them, of course) while minimizing the terminal
    dialog (i.e. when you use a single Pass Phrase for all N Private Key files
    this Pass Phrase is queried only once).
<p>
<li><code>exec:/path/to/program</code>
    <p>
    Here an external program is configured which is called at startup for each
    encrypted Private Key file. It is called with two arguments (the first is
    of the form ``<code>servername:portnumber</code>'', the second is either
    ``<code>RSA</code>'' or ``<code>DSA</code>''), which indicate for which
    server and algorithm it has to print the corresponding Pass Phrase to
    <code>stdout</code>.  The intent is that this external program first runs
    security checks to make sure that the system is not compromised by an
    attacker, and only when these checks were passed successfully it provides
    the Pass Phrase. 
    <p>
    Both these security checks, and the way the Pass Phrase is determined, can
    be as complex as you like. Mod_ssl just defines the interface: an
    executable program which provides the Pass Phrase on <code>stdout</code>.
    Nothing more or less! So, if you're really paranoid about security, here
    is your interface. Anything else has to be left as an exercise to the
    administrator, because local security requirements are so different.
    <p>
    The reuse-algorithm above is used here, too. In other words: The external
    program is called only once per unique Pass Phrase.
</ul>

<p>
Example:
<blockquote>
<pre>
SSLPassPhraseDialog exec:/usr/local/apache/sbin/pp-filter
</pre>
</blockquote>


<!-- SSLMutex ------------------------------------------------------->

<p>
<br>
<a name="SSLMutex"></a>
<h2>SSLMutex</h2>

<p>
<directive
    name="SSLMutex"
    description="Semaphore for internal mutual exclusion of operations"
    syntax="<code>SSLMutex</code> <em>type</em>"
    default="<code>SSLMutex none</code>"
    context="server config"
    override="<em>Not applicable</em>"
    compat="mod_ssl 2.1"
>

<p>
This configures the SSL engine's semaphore (aka. lock) which is used for mutual
exclusion of operations which have to be done in a synchronized way between the
pre-forked Apache server processes. This directive can only be used in the
global server context because it's only useful to have one global mutex.

<p>
The following Mutex <em>types</em> are available:

<ul>
<li><code>none</code>
    <p>
    This is the default where no Mutex is used at all. Use it at your own
    risk. But because currently the Mutex is mainly used for synchronizing
    write access to the SSL Session Cache you can live without it as long
    as you accept a sometimes garbled Session Cache. So it's not recommended
    to leave this the default. Instead configure a real Mutex.
<p>
<li><code>file:/path/to/mutex</code>
    <p>
    This is the portable and (under Unix) always provided Mutex variant where
    a physical (lock-)file is used as the Mutex. Always use a local disk
    filesystem for <code>/path/to/mutex</code> and never a file residing on a
    NFS- or AFS-filesystem. Note: Internally, the Process ID (PID) of the
    Apache parent process is automatically appended to
    <code>/path/to/mutex</code> to make it unique, so you don't have to worry
    about conflicts yourself. Notice that this type of mutex is not available
    under the Win32 environment. There you <i>have</i> to use the semaphore
    mutex.
<p>
<li><code>sem</code>
    <p>
    This is the most elegant but also most non-portable Mutex variant where a
    SysV IPC Semaphore (under Unix) and a Windows Mutex (under Win32) is used
    when possible. It is only available when the underlying platform
    supports it.
</ul>

<p>
Example:
<blockquote>
<pre>
SSLMutex file:/usr/local/apache/logs/ssl_mutex
</pre>
</blockquote>


<!-- SSLRandomSeed -------------------------------------------------->

<p>
<br>
<a name="SSLRandomSeed"></a>
<h2>SSLRandomSeed</h2>

<p>
<directive
    name="SSLRandomSeed"
    description="Pseudo Random Number Generator (PRNG) seeding source"
    syntax="<code>SSLRandomSeed</code> <em>context</em> <em>source</em> [<em>bytes</em>]"
    default="<em>none</em>"
    context="server config"
    override="<em>Not applicable</em>"
    compat="mod_ssl 2.2"
>

<p>
This configures one or more sources for seeding the Pseudo Random Number
Generator (PRNG) in OpenSSL at startup time (<em>context</em> is
<code>startup</code>) and/or just before a new SSL connection is established
(<em>context</em> is <code>connect</code>).  This directive can only be used
in the global server context because the PRNG is a global facility.

<p>
The following <em>source</em> variants are available:

<ul>
<li><code>builtin</code>
    <p> This is the always available builtin seeding source.  It's usage
    consumes minimum CPU cycles under runtime and hence can be always used
    without drawbacks. The source used for seeding the PRNG contains of the
    current time, the current process id and (when applicable) a randomly
    choosen 1KB extract of the inter-process scoreboard structure of Apache.
    The drawback is that this is not really a strong source and at startup
    time (where the scoreboard is still not available) this source just
    produces a few bytes of entropy. So you should always, at least for the
    startup, use an additional seeding source.
<p>
<li><code>file:/path/to/source</code>
    <p>
    This variant uses an external file <code>/path/to/source</code> as the
    source for seeding the PRNG. When <em>bytes</em> is specified, only the
    first <em>bytes</em> number of bytes of the file form the entropy (and
    <em>bytes</em> is given to <code>/path/to/source</code> as the first
    argument). When <em>bytes</em> is not specified the whole file forms the
    entropy (and <code>0</code> is given to <code>/path/to/source</code> as
    the first argument). Use this especially at startup time, for instance
    with an available <code>/dev/random</code> and/or
    <code>/dev/urandom</code> devices (which usually exist on modern Unix
    derivates like FreeBSD and Linux).
    <p>
    <em>But be careful</em>: Usually <code>/dev/random</code> provides only as
    much entropy data as it actually has, i.e. when you request 512 bytes of
    entropy, but the device currently has only 100 bytes available two things
    can happen: On some platforms you receive only the 100 bytes while on
    other platforms the read blocks until enough bytes are available (which
    can take a long time). Here using an existing <code>/dev/urandom</code> is
    better, because it never blocks and actually gives the amount of requested
    data. The drawback is just that the quality of the received data may not
    be the best. 
    <p>
    On some platforms like FreeBSD one can even control how the entropy is
    actually generated, i.e. by which system interrupts. More details one can
    find under <i>rndcontrol(8)</i> on those platforms.  Alternatively, when
    your system lacks such a random device, you can use tool
    like <a href="http://www.lothar.com/tech/crypto/">EGD</a>
    (Entropy Gathering Daemon) and run it's client program with the
    <code>exec:/path/to/program/</code> variant (see below) or use
    <code>egd:/path/to/egd-socket</code> (see below).
<p>
<li><code>exec:/path/to/program</code>
    <p>
    This variant uses an external executable <code>/path/to/program</code> as
    the source for seeding the PRNG. When <em>bytes</em> is specified, only the
    first <em>bytes</em> number of bytes of its <code>stdout</code> contents
    form the entropy. When <em>bytes</em> is not specified, the entirety of
    the data produced on <code>stdout</code> form the entropy. Use this only
    at startup time when you need a very strong seeding with the help of an
    external program (for instance as in the example above with the
    <code>truerand</code> utility you can find in the mod_ssl distribution
    which is based on the AT&amp;T <em>truerand</em> library). Using this in
    the connection context slows down the server too dramatically, of course.
    So usually you should avoid using external programs in that context.
<p>