ssl_reference.wml

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

    This <i>forces</i> forbidden access when <code>SSLRequireSSL</code> or
    <code>SSLRequire</code> successfully decided that access should be
    forbidden. Usually the default is that in the case where a ``<code>Satisfy
    any</code>'' directive is used, and other access restrictions are passed,
    denial of access due to <code>SSLRequireSSL</code> or
    <code>SSLRequire</code> is overridden (because that's how the Apache
    <tt>Satisfy</tt> mechanism should work.) But for strict access restriction
    you can use <code>SSLRequireSSL</code> and/or <code>SSLRequire</code> in
    combination with an ``<code>SSLOptions +StrictRequire</code>''. Then an
    additional ``<code>Satisfy Any</code>'' has no chance once mod_ssl has
    decided to deny access.
<p>
<li><code>OptRenegotiate</code>
    <p>
    This enables optimized SSL connection renegotiation handling when SSL
    directives are used in per-directory context. By default a strict
    scheme is enabled where <i>every</i> per-directory reconfiguration of
    SSL parameters causes a <i>full</i> SSL renegotiation handshake. When this
    option is used mod_ssl tries to avoid unnecessary handshakes by doing more
    granular (but still safe) parameter checks. Nevertheless these granular
    checks sometimes maybe not what the user expects, so enable this on a
    per-directory basis only, please.
</ul>

<p>
Example:
<blockquote>
<pre>
SSLOptions +FakeBasicAuth -StrictRequire
&lt;Files ~ "\.(cgi|shtml)$"&gt;
    SSLOptions +StdEnvVars +CompatEnvVars -ExportCertData
&lt;Files&gt;
</pre>
</blockquote>


<!-- SSLRequireSSL -------------------------------------------------->

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

<directive
    name="SSLRequireSSL"
    description="Deny access when SSL is not used for the HTTP request"
    syntax="<code>SSLRequireSSL</code>"
    default="<em>None</em>"
    context="directory, .htaccess"
    override="AuthConfig"
    compat="mod_ssl 2.0"
>

<p>
This directive forbids access unless HTTP over SSL (i.e. HTTPS) is enabled for
the current connection.  This is very handy inside the SSL-enabled virtual
host or directories for defending against configuration errors that expose
stuff that should be protected. When this directive is present all requests
are denied which are not using SSL.

<p>
Example:
<blockquote>
<pre>
SSLRequireSSL
</pre>
</blockquote>


<!-- SSLRequire ----------------------------------------------------->

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

<directive
    name="SSLRequire"
    description="Allow access only when an arbitrarily complex boolean expression is true"
    syntax="<code>SSLRequire</code> <em>expression</em>"
    default="<em>None</em>"
    context="directory, .htaccess"
    override="AuthConfig"
    compat="mod_ssl 2.1"
>

<p>
This directive specifies a general access requirement which has to be
fulfilled in order to allow access. It's a very powerful directive because the
requirement specification is an arbitrarily complex boolean expression
containing any number of access checks.

<p>
The <em>expression</em> must match the following syntax (given as a BNF
grammar notation):

<blockquote>
<pre>
expr     ::= "<b>true</b>" | "<b>false</b>" 
           | "<b>!</b>" expr
           | expr "<b>&&</b>" expr
           | expr "<b>||</b>" expr
           | "<b>(</b>" expr "<b>)</b>"
           | comp

comp     ::= word "<b>==</b>" word | word "<b>eq</b>" word
           | word "<b>!=</b>" word | word "<b>ne</b>" word
           | word "<b>&lt;</b>"  word | word "<b>lt</b>" word
           | word "<b>&lt;=</b>" word | word "<b>le</b>" word
           | word "<b>&gt;</b>"  word | word "<b>gt</b>" word
           | word "<b>&gt;=</b>" word | word "<b>ge</b>" word
           | word "<b>in</b>" "<b>{</b>" wordlist "<b>}</b>"
           | word "<b>=~</b>" regex
           | word "<b>!~</b>" regex

wordlist ::= word 
           | wordlist "<b>,</b>" word

word     ::= digit
           | cstring
           | variable
           | function

digit    ::= [0-9]+
cstring  ::= "..."
variable ::= "<b>%{</b>" varname "<b>}</b>" 
function ::= funcname "<b>(</b>" funcargs "<b>)</b>"
</pre>
</blockquote>

while for <code>varname</code> any variable from <a href="#table3">Table 3</a>
can be used.  Finally for <code>funcname</code> the following functions
are available:

<ul>
<li><code>file(</code><em>filename</em><code>)</code>
    <p>
    This function takes one string argument and expands to the contents of the
    file. This is especially useful for matching this contents against a
    regular expression, etc.
</ul>

Notice that <em>expression</em> is first parsed into an internal machine
representation and then evaluated in a second step. Actually, in Global and
Per-Server Class context <em>expression</em> is parsed at startup time and
at runtime only the machine representation is executed. For Per-Directory
context this is different: here <em>expression</em> has to be parsed and
immediately executed for every request.

<p>
Example:
<blockquote>
<pre>
SSLRequire (    %{SSL_CIPHER} !~ m/^(EXP|NULL)-/ \\
            and %{SSL_CLIENT_S_DN_O} eq "Snake Oil, Ltd." \\
            and %{SSL_CLIENT_S_DN_OU} in {"Staff", "CA", "Dev"} \\
            and %{TIME_WDAY} >= 1 and %{TIME_WDAY} <= 5 \\
            and %{TIME_HOUR} >= 8 and %{TIME_HOUR} <= 20       ) \\
           or %{REMOTE_ADDR} =~ m/^192\.76\.162\.[0-9]+$/
</pre>
</blockquote>

<float name="table3" caption="Table 3: Available Variables for SSLRequire">
<table><tr><td>
<em>Standard CGI/1.0 and Apache variables:</em>
<pre>
HTTP_USER_AGENT        PATH_INFO             AUTH_TYPE       
HTTP_REFERER           QUERY_STRING          SERVER_SOFTWARE  
HTTP_COOKIE            REMOTE_HOST           API_VERSION      
HTTP_FORWARDED         REMOTE_IDENT          TIME_YEAR       
HTTP_HOST              IS_SUBREQ             TIME_MON        
HTTP_PROXY_CONNECTION  DOCUMENT_ROOT         TIME_DAY        
HTTP_ACCEPT            SERVER_ADMIN          TIME_HOUR       
HTTP:headername        SERVER_NAME           TIME_MIN        
THE_REQUEST            SERVER_PORT           TIME_SEC        
REQUEST_METHOD         SERVER_PROTOCOL       TIME_WDAY       
REQUEST_SCHEME         REMOTE_ADDR           TIME            
REQUEST_URI            REMOTE_USER           ENV:<b>variablename</b>
REQUEST_FILENAME
</pre> 

<em>SSL-related variables:</em>
<pre>
HTTPS                  SSL_CLIENT_M_VERSION   SSL_SERVER_M_VERSION
                       SSL_CLIENT_M_SERIAL    SSL_SERVER_M_SERIAL 
SSL_PROTOCOL           SSL_CLIENT_V_START     SSL_SERVER_V_START  
SSL_SESSION_ID         SSL_CLIENT_V_END       SSL_SERVER_V_END    
SSL_CIPHER             SSL_CLIENT_S_DN        SSL_SERVER_S_DN     
SSL_CIPHER_EXPORT      SSL_CLIENT_S_DN_C      SSL_SERVER_S_DN_C   
SSL_CIPHER_ALGKEYSIZE  SSL_CLIENT_S_DN_ST     SSL_SERVER_S_DN_ST  
SSL_CIPHER_USEKEYSIZE  SSL_CLIENT_S_DN_L      SSL_SERVER_S_DN_L   
SSL_VERSION_LIBRARY    SSL_CLIENT_S_DN_O      SSL_SERVER_S_DN_O   
SSL_VERSION_INTERFACE  SSL_CLIENT_S_DN_OU     SSL_SERVER_S_DN_OU  
                       SSL_CLIENT_S_DN_CN     SSL_SERVER_S_DN_CN  
                       SSL_CLIENT_S_DN_T      SSL_SERVER_S_DN_T  
                       SSL_CLIENT_S_DN_I      SSL_SERVER_S_DN_I  
                       SSL_CLIENT_S_DN_G      SSL_SERVER_S_DN_G  
                       SSL_CLIENT_S_DN_S      SSL_SERVER_S_DN_S  
                       SSL_CLIENT_S_DN_D      SSL_SERVER_S_DN_D  
                       SSL_CLIENT_S_DN_UID    SSL_SERVER_S_DN_UID  
                       SSL_CLIENT_S_DN_Email  SSL_SERVER_S_DN_Email
                       SSL_CLIENT_I_DN        SSL_SERVER_I_DN       
                       SSL_CLIENT_I_DN_C      SSL_SERVER_I_DN_C    
                       SSL_CLIENT_I_DN_ST     SSL_SERVER_I_DN_ST   
                       SSL_CLIENT_I_DN_L      SSL_SERVER_I_DN_L    
                       SSL_CLIENT_I_DN_O      SSL_SERVER_I_DN_O    
                       SSL_CLIENT_I_DN_OU     SSL_SERVER_I_DN_OU   
                       SSL_CLIENT_I_DN_CN     SSL_SERVER_I_DN_CN   
                       SSL_CLIENT_I_DN_T      SSL_SERVER_I_DN_T  
                       SSL_CLIENT_I_DN_I      SSL_SERVER_I_DN_I  
                       SSL_CLIENT_I_DN_G      SSL_SERVER_I_DN_G  
                       SSL_CLIENT_I_DN_S      SSL_SERVER_I_DN_S  
                       SSL_CLIENT_I_DN_D      SSL_SERVER_I_DN_D  
                       SSL_CLIENT_I_DN_UID    SSL_SERVER_I_DN_UID  
                       SSL_CLIENT_I_DN_Email  SSL_SERVER_I_DN_Email
                       SSL_CLIENT_A_SIG       SSL_SERVER_A_SIG    
                       SSL_CLIENT_A_KEY       SSL_SERVER_A_KEY    
                       SSL_CLIENT_CERT        SSL_SERVER_CERT    
                       SSL_CLIENT_CERT_CHAIN<b>n</b>
                       SSL_CLIENT_VERIFY
</pre>
</td></tr></table>
</float>

<br>
<br>
<p>
<h1>Additional Features</h1>

<h2>Environment Variables</h2>

This module provides a lot of SSL information as additional environment
variables to the SSI and CGI namespace. The generated variables are listed in
<a href="#table4">Table 4</a>. For backward compatibility the information can
be made available under different names, too.  Look in the <a
href="ssl_compat.html">Compatibility</a> chapter for details on the
compatibility variables.

<p>
<float name="table4" caption="Table 4: SSI/CGI Environment Variables">
<table border="0" cellspacing="0" cellpadding="2" width=598>
<tr id=H>
 <td><b>Variable Name:</b></td> 
 <td><b>Value Type:</b></td> 
 <td><b>Description:</b></td>
</tr>
<tr id=D><td><code>HTTPS</code></td>                         <td>flag</td>      <td>HTTPS is being used.</td></tr>
<tr id=H><td><code>SSL_PROTOCOL</code></td>                  <td>string</td>    <td>The SSL protocol version (SSLv2, SSLv3, TLSv1)</td></tr>
<tr id=H><td><code>SSL_SESSION_ID</code></td>                <td>string</td>    <td>The hex-encoded SSL session id</td></tr>
<tr id=D><td><code>SSL_CIPHER</code></td>                    <td>string</td>    <td>The cipher specification name</td></tr>
<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>
<tr id=H><td><code>SSL_CIPHER_USEKEYSIZE</code></td>         <td>number</td>    <td>Number of cipher bits (actually used)</td></tr>
<tr id=D><td><code>SSL_CIPHER_ALGKEYSIZE</code></td>         <td>number</td>    <td>Number of cipher bits (possible)</td></tr>
<tr id=H><td><code>SSL_VERSION_INTERFACE</code></td>         <td>string</td>    <td>The mod_ssl program version</td></tr>
<tr id=D><td><code>SSL_VERSION_LIBRARY</code></td>           <td>string</td>    <td>The OpenSSL program version</td></tr>
<tr id=H><td><code>SSL_CLIENT_M_VERSION</code></td>          <td>string</td>    <td>The version of the client certificate</td></tr>
<tr id=D><td><code>SSL_CLIENT_M_SERIAL</code></td>           <td>string</td>    <td>The serial of the client certificate</td></tr>
<tr id=H><td><code>SSL_CLIENT_S_DN</code></td>               <td>string</td>    <td>Subject DN in client's certificate</td></tr>
<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>
<tr id=H><td><code>SSL_CLIENT_I_DN</code></td>               <td>string</td>    <td>Issuer DN of client's certificate</td></tr>
<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>
<tr id=H><td><code>SSL_CLIENT_V_START</code></td>            <td>string</td>    <td>Validity of client's certificate (start time)</td></tr>
<tr id=D><td><code>SSL_CLIENT_V_END</code></td>              <td>string</td>    <td>Validity of client's certificate (end time)</td></tr>
<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>
<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>
<tr id=H><td><code>SSL_CLIENT_CERT</code></td>               <td>string</td>    <td>PEM-encoded client certificate</td></tr>
<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>
<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>
<tr id=D><td><code>SSL_SERVER_M_VERSION</code></td>          <td>string</td>    <td>The version of the server certificate</td></tr>
<tr id=H><td><code>SSL_SERVER_M_SERIAL</code></td>           <td>string</td>    <td>The serial of the server certificate</td></tr>
<tr id=D><td><code>SSL_SERVER_S_DN</code></td>               <td>string</td>    <td>Subject DN in server's certificate</td></tr>
<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>
<tr id=D><td><code>SSL_SERVER_I_DN</code></td>               <td>string</td>    <td>Issuer DN of server's certificate</td></tr>
<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>
<tr id=D><td><code>SSL_SERVER_V_START</code></td>            <td>string</td>    <td>Validity of server's certificate (start time)</td></tr>
<tr id=H><td><code>SSL_SERVER_V_END</code></td>              <td>string</td>    <td>Validity of server's certificate (end time)</td></tr>
<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>
<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>
<tr id=D><td><code>SSL_SERVER_CERT</code></td>               <td>string</td>    <td>PEM-encoded server certificate</td></tr>
</table>
[ where <em>x509</em> is a component of a X.509 DN:
  <code>C,ST,L,O,OU,CN,T,I,G,S,D,UID,Email</code> ]
</float>


<p>
<br>
<h2>Custom Log Formats</h2>

When mod_ssl is built into Apache or at least loaded (under DSO situation)
additional functions exist for the <a
href="../mod_log_config.html#formats">Custom Log Format</a> of <a
href="../mod_log_config.html">mod_log_config</a>.  First there is an additional
``<code>%{</code><em>varname</em><code>}x</code>'' eXtension format function
which can be used to expand any variables provided by any module, especially
those provided by mod_ssl which can you find in <a href="#table4">Table 4</a>.

<p>
For backward compatibility there is additionally a special
``<code>%{</code><em>name</em><code>}c</code>'' cryptography format function
provided.  Information about this function is provided in the <a
href="ssl_compat.html">Compatibility</a> chapter.

<p>
Example:
<blockquote>
<pre>
CustomLog logs/ssl_request_log \\
          "%t %h %{SSL_PROTOCOL}x %{SSL_CIPHER}x \"%r\" %b"
</pre>
</blockquote>