home | O'Reilly's CD bookshelfs | FreeBSD | Linux | Cisco | Cisco Exam    

Apache The Definitive Guide, 3rd EditionApache: The Definitive GuideSearch this book

11.8. SSL Directives

Apache-SSL's directives for Apache v1.3 follow, with the new ones introduced by v2 after that. Then there is a small section at the end of the chapter concerning cipher suites.

11.8.1. Apache-SSL Directives for Apache v1.3

SSLDenySSL

SSLDenySSL
Server config, .htaccess, virtual host, directory
Not available in Apache v2

The obverse of SSL RequireSSL, this directive denies access if SSL is active. You might want to do this to maintain the server's performance. In a complicated Config file, a section might inadvertently have SSL enabled and would slow things down: this directive would solve the problem — in a crude way.

SSLFakeBasicAuth

SSLFakeBasicAuth
Server config, virtual host
Not available in Apache v2

This directive makes Apache pretend that the user has been logged in using basic authentication (see Chapter 5), except that instead of the username you get the one-line X509, a version of the client's certificate. If you switch this on, along with SSLVerifyClient, you should see the results in one of the logs. The code adds a predefined password.

SSLNoCAList

SSLNoCAList
Server config, virtual host
Not available in Apache v2

This directive disables presentation of the CA list for client certificate authentication. Unlikely to be useful in a production environment, it is extremely handy for testing purposes.

CustomLog


CustomLog nickname
Server config, virtual host
Not available in Apache v2

CustomLog is a standard Apache directive (see Chapter 10 ) to which Apache-SSL adds some extra categories that can be logged:

{cipher}c
The name of the cipher being used for this connection.

{clientcert}c
The one-line version of the certificate presented by the client.

{errcode}c
If the client certificate verification failed, this is the SSLeay error code. In the case of success, a "-" will be logged.

{errstr}c
This is the SSLeay string corresponding to the error code.

{version}c
The version of SSL being used. If you are using SSLeay versions prior to 0.9.0, then this is simply a number: 2 for SSL2 or 3 for SSL3. For SSLeay Version 0.9.0 and later, it is a string, currently one of "SSL2," "SSL3," or "TLS1."

Example

CustomLog logs/ssl_log "%t %{cipher}c %{clientcert}c %{errcode}c {%errstr}c"

11.8.2. SSL Directives for Apache v2

All but six of the directives for Apache v2 are new. These continue in use:

SSLSessionCacheTimeout 
SSLCertificateFile 
SSLCertificateKeyFile 
SSLVerifyClient 
SSLVerifyDepth 
SSLRequireSSL

and are described earlier. There is some backward compatibility, explained at http://httpd.apache.org/docs-2.0/ssl/ssl_compat.html, but it is probably better to decide which version of Apache you want and then to use the appropriate set of directives.

SSLPassPhraseDialog

SSLPassPhraseDialog type
Default: builtin
Server config
Apache v2 only

When Apache starts up it has to read the various Certificate (see SSLCertificateFile) and Private Key (see SSLCertificateKeyFile) files of the SSL-enabled virtual servers. The Private Key files are usually encrypted, so mod_ssl needs to query the administrator for a passphrase to decrypt those files. This query can be done in two different ways, specified by type:

builtin
This is the default: an interactive dialog occurs at startup. The administrator has to type in the passphrase for each encrypted Private Key file. Since the same pass phrase may apply to several files, it is tried on all of them that have not yet been opened.

exec:/path/to/program
An external program is specified which is called at startup for each encrypted Private Key file. It is called with two arguments (the first is servername:portnumber; the second is either RSA or DSA), indicating the server and algorithm to use. It should then print the passphrase to stdout. The idea is that this program first runs security checks to make sure that the system is not compromised by an attacker. If these checks are passed, it provides the appropriate passphrase. Each passphrase is tried, as earlier, on all the unopened private key files.

Example

SSLPassPhraseDialog exec:/usr/local/apache/sbin/pp-filter
SSLMutex

SSLMutex type
Default: none BUT SEE WARNING BELOW!
Server config
Apache v2 only

This configures the SSL engine's semaphore — i.e., a multiuser lock — which is used to synchronize operations between the preforked Apache server processes. This directive can only be used in the global server context.

The following mutex types are available:

none
This is the default where no mutex is used at all. Because the mutex is mainly used for synchronizing write access to the SSL session cache, the result of not having a mutex will probably be a corrupt session cache . . . which would be bad, and we do not recommend it.

file:/path/to/mutex
Use this to configure a real mutex file by defining the path and name. Always use a local disk filesystem for /path/to/mutex and never a file residing on a NFS- or AFS-filesystem. The Process ID (PID) of the Apache parent process is automatically appended to /path/to/mutex to make it unique, so you don't have to worry about conflicts yourself. Notice that this type of mutex is not available in Win32.

sem
A semaphore mutex is available under SysV Unices and must be used in Win32.

Example

SSLMutex file:/usr/local/apache/logs/ssl_mutex
SSLRandomSeed

SSLRandomSeed context source [bytes]
Apache v2 only

This configures one or more sources for seeding the PRNG in OpenSSL at startup time (context is 'startup') and/or just before a new SSL connection is established (context is 'connect'). This directive can only be used in the global server context because the PRNG is a global facility.

Specifying the builtin value for source indicates the built-in seeding source. The source used for seeding the PRNG consists of the current time, the current process id, and (when applicable) a randomly chosen 1KB extract of the interprocess scoreboard structure of Apache. However, this is not a strong source, and at startup time (where the scoreboard is not available) it produces only a few bytes of entropy.

So if you are seeding at startup, you should use an additional seeding source of the form:

file:/path/to/source 

This variant uses an external file /path/to/source as the source for seeding the PRNG. When bytes is specified, only the first bytes number of bytes of the file form the entropy (and bytes is given to /path/to/source as the first argument). When bytes is not specified, the whole file forms the entropy (and 0 is given to /path/to/source as the first argument). Use this especially at startup time, for instance with /dev/random and/or /dev/urandom devices (which usually exist on modern Unix derivatives like FreeBSD and Linux).

NOTE: Although /dev/random provides better quality data, it may not have the number of bytes available that you have requested. On some systems the read waits until the requested number of bytes becomes available — which could be annoying; on others you get however many bytes it actually has available — which may not be enough.

Using /dev/urandom may be better, because it never blocks and reliably gives the amount of requested data. The drawback is just that the quality of the data may not be the best.

On some platforms like FreeBSD one can control how the entropy is generated. See man rndcontrol(8). Alternatively, you can use tools like EGD (Entropy Gathering Daemon) and run its client program with the exec:/path/to/program/ variant (see later) or use egd:/path/to/egd-socket (see later).

You can also use an external executable as the source for seeding:

exec:/path/to/program 

This variant uses an external executable /path/to/program as the source for seeding the PRNG. When bytes is specified, only the first bytes number of bytes of stdout form the entropy. When bytes is not specified, all the data on stdout forms the entropy. Use this only at startup time when you need a very strong seeding with the help of an external program. But using this in the connection context slows the server down dramatically.

The final variant for source uses the Unix domain socket of the external Entropy Gathering Daemon (EGD):

egd:/path/to/egd-socket (Unix only) 

This variant uses the Unix domain socket of the EGD (see http://www.lothar.com/tech/crypto/) to seed the PRNG. Use this if no random device exists on your platform.

Examples

SSLRandomSeed startup builtin
SSLRandomSeed startup file:/dev/random
SSLRandomSeed startup file:/dev/urandom 1024
SSLRandomSeed startup exec:/usr/local/bin/truerand 16
SSLRandomSeed connect builtin
SSLRandomSeed connect file:/dev/random
SSLRandomSeed connect file:/dev/urandom 1024
SSLSessionCache

SSLSessionCache type
SSLSessionCache none
Server config
Apache v2 only

This configures the storage type of the global/interprocess SSL Session Cache. This cache is an optional facility that speeds up parallel request processing. SSL session information, which are processed in requests to the same server process (via HTTP keepalive), are cached locally. But because modern clients request inlined images and other data via parallel requests (up to four parallel requests are common), those requests are served by different preforked server processes. Here an interprocess cache helps to avoid unnecessary session handshakes.

The following storage types are currently supported:

none
This is the default and just disables the global/interprocess Session Cache. There is no drawback in functionality, but a noticeable drop in speed penalty can result.

dbm:/path/to/datafile
This makes use of a DBM hashfile on the local disk to synchronize the local OpenSSL memory caches of the server processes. The slight increase in I/O on the server results in a visible request speedup for your clients, so this type of storage is generally recommended.

shm:/path/to/datafile[(size)]
This makes use of a high-performance hash table (approximately size bytes big) inside a shared memory segment in RAM (established via /path/to/datafile) to synchronize the local OpenSSL memory caches of the server processes. This storage type is not available on all platforms.

Examples

SSLSessionCache dbm:/usr/local/apache/logs/ssl_gcache_data
SSLSessionCache shm:/usr/local/apache/logs/ssl_gcache_data(512000)
SSLEngine

SSLEngine on|offSSL
Engine off
Server config, virtual host

You might think this was to do with an external hardware engine — but not so. This turns SSL on or off. It is equivalent to SSLEnable and SSLDisable, which you can use instead. This is usually used inside a <VirtualHost> section to enable SSL/TLS for a particular virtual host. By default the SSL/TLS Protocol Engine is disabled for both the main server and all configured virtual hosts.

Example

<VirtualHost _default_:443>
SSLEngine on
...
</VirtualHost>
SSLProtocol

SSLProtocol [+-]protocol ...
Default: SSLProtocol all
Server config, virtual host
Apache v2 only

This directive can be used to control the SSL protocol flavors mod_ssl should use when establishing its server environment. Clients then can only connect with one of the provided protocols.

The available (case-insensitive) protocols are as follows:

SSLv2
This is the Secure Sockets Layer (SSL) protocol, Version 2.0. It is the original SSL protocol as designed by Netscape Corporation.

SSLv3
This is the Secure Sockets Layer (SSL) protocol, Version 3.0. It is the successor to SSLv2 and the currently (as of February 1999) de-facto standardized SSL protocol from Netscape Corporation. It is supported by most popular browsers.

TLSv1
This is the Transport Layer Security (TLS) protocol, Version 1.0, which is the latest and greatest, IETF-approved version of SSL.

All
This is a shortcut for "+SSLv2 +SSLv3 +TLSv1" and a convenient way for enabling all protocols except one when used in combination with the minus sign on a protocol, as the following example shows.

Example

#   enable SSLv3 and TLSv1, but not SSLv2
SSLProtocol all -SSLv2
SSLCertificateFile

See earlier, Apache v1.3.

SSLCertificateKeyFile

See earlier, Apache v1.3.

SSLCACertificatePath

SSLCACertificatePath directory
Server config, virtual host
Apache v2 only

This directive sets the directory where you keep the certificates of CAs with whose clients you deal. These are used to verify the client certificate on client authentication.

The files in this directory have to be PEM-encoded and are accessed through hash filenames. So usually you can't just place the Certificate files there: you also have to create symbolic links named hash-value.N. You should always make sure this directory contains the appropriate symbolic links. The utility tools/c_rehash that comes with OpenSSL does this.

Example

SSLCACertificatePath /usr/local/apache/conf/ssl.crt/
SSLCACertificateFile

SSLCACertificateFile filename
Server config, virtual host
Apache v2 only

This directive sets the all-in-one file where you can assemble the certificates CAs with whose clients you deal. These are used for Client Authentication. Such a file is simply the concatenation of the various PEM-encoded certificate files, in order of preference. This can be used instead of, or as well as, SSLCACertificatePath.

Example

SSLCACertificateFile /usr/local/apache/conf/ssl.crt/ca-bundle-client.crt
SSL CAR evocation path

SSLCARevocationPath directory
Server config, virtual host
Apache v2 only

This directive sets the directory where you keep the Certificate Revocation Lists (CRL) of CAs with whose clients you deal. These are used to revoke the client certificate on Client Authentication.

The files in this directory have to be PEM-encoded and are accessed through hashed filenames. Create symbolic links named hash-value.rN. to the files you put there. Use the Makefile that comes with mod_ssl to accomplish this task.

Example:

SSLCARevocationPath /usr/local/apache/conf/ssl.crl/
SSL CAR evocation file

SSLCARevocationFile filename
Server config, virtual host
Apache v2 only

This directive sets the all-in-one file where you can assemble the CRL of CA with whose clients you deal. These are used for Client Authentication. Such a file is simply the concatenation of the various PEM-encoded CRL files, in order of preference. This can be used alternatively and/or additionally to SSLCARevocationPath.

Example:

SSLCARevocationFile /usr/local/apache/conf/ssl.crl/ca-bundle-client.crl
SSLVerifyClient

See earlier, Apache v1.3.

SSLVerifyDepth

See earlier, Apache v1.3.

Slog

SSLLog filename
Server config, virtual host
Apache v2 only

This directive sets the name of the dedicated SSL protocol engine log file. Error messages are additionally duplicated to the general Apache error_log file (directive ErrorLog). Put this somewhere where it cannot be used for symlink attacks on a real server (i.e., somewhere where only root can write). If the filename does not begin with a slash ("/"), then it is assumed to be relative to the Server Root. If filename begins with a bar ("|") then the string following is assumed to be a path to an executable program to which a reliable pipe can be established. This directive should be used once per virtual server config.

Example

SSLLog /usr/local/apache/logs/ssl_engine_log
SSLLogLevel

SSLLogLevel level
Default: SSLLogLevel none
Server config, virtual host

This directive sets the verbosity of the dedicated SSL protocol engine log file. The level is one of the following (in ascending order where higher levels include lower levels):

none
No dedicated SSL logging; messages of level error are still written to the general Apache error log file.

error
Log messages of error type only, i.e., messages that show fatal situations (processing is stopped). Those messages are also duplicated to the general Apache error log file.

warn
Log warning messages, i.e., messages that show nonfatal problems (processing is continued).

info
Log informational messages, i.e., messages that show major processing steps.

trace
Log trace messages, i.e., messages that show minor processing steps.

debug
Log debugging messages, i.e., messages that show development and low-level I/O information.

Example

SSLLogLevel warn
SSLOptions

SSLOptions [+-]option ...
Server config, virtual host, directory, .htaccess
Apache v2 only

This directive can be used to control various runtime options on a per-directory basis. Normally, if multiple SSLOptions could apply to a directory, then the most specific one is taken completely, and the options are not merged. However, if all the options on the SSLOptions directive are preceded by a plus (+) or minus (-) symbol, the options are merged. Any options preceded by a + are added to the options currently in force, and any options preceded by a - are removed from the options currently in force.

The available options are as follows:

StdEnvVars
When this option is enabled, the standard set of SSL-related CGI/SSI environment variables are created. By default, this is disabled for performance reasons, because the information extraction step is an expensive operation. So one usually enables this option for CGI and SSI requests only.

CompatEnvVars
When this option is enabled, additional CGI/SSI environment variables are created for backward compatibility with other Apache SSL solutions. Look in the Compatibility chapter of the Apache documentation (httpd.apache.org/docs-2.0/ssl/ssl_compat.html) for details on the particular variables generated.

ExportCertData
When this option is enabled, additional CGI/SSI environment variables are created: SSL_SERVER_CERT, SSL_CLIENT_CERT and SSL_CLIENT_CERT_CHAINn (with n = 0,1,2,...). These contain the PEM-encoded X.509 Certificates of server and client for the current HTTPS connection and can be used by CGI scripts for deeper Certificate checking. All other certificates of the client certificate chain are provided, too. This bloats the environment somewhat.

FakeBasicAuth
The effect of FakeBasicAuth is to allow the webmaster to treat authorization by encrypted certificates as if it were done by the old Authentication directives. This makes everyone's lives simpler because the standard directives Limit, Require, and Satisfy ... can be used.

When this option is enabled, the Subject Distinguished Name (DN) of the Client X509 Certificate is translated into a HTTP Basic Authorization username. The username is just the Subject of the Client's X509 Certificate (can be determined by running OpenSSL's openssl x509 command: openssl x509 -noout -subject -in certificate.crt). The easiest way to find this is to get the user to browse to the web site. The name will then be found in the log.

Since the user has a certificate, we do not need to get a password from her. Every entry in the user file needs the encrypted version of the password "password". The simple way to build the file is to create the first entry:

htpasswd -c sales bill

All things being equal, htpasswd will use the operating system's favorite encryption method, which is what Apache will use as well. On our system, FreeBSD, this is CRYPT, and this was the result:

bill:$1$RBZaI/..$/n0bgKUfnccGEsg4WQUVx

You can continue with this:

htpasswd  sales sam
htpasswd  sales sonia
...

typing in the password twice each time, or you can just edit the file sales to get:

bill:$1$RBZaI/..$/n0bgKUfnccGEsg4WQUVx
sam:$1$RBZaI/..$/n0bgKUfnccGEsg4WQUVx
sonia:$1$RBZaI/..$/n0bgKUfnccGEsg4WQUVx
StrictRequire
This forces forbidden access when SSLRequireSSL or SSLRequire successfully decided that access should be forbidden. Usually the default is that in the case where a "Satisfy any" directive is used and other access restrictions are passed, denial of access due to SSLRequireSSL or SSLRequire is overridden (because that's how the Apache Satisfy mechanism works.) But for strict access restriction you can use SSLRequireSSL and/or SSLRequire in combination with an "SSLOptions +StrictRequire". Then an additional "Satisfy Any" has no chance once mod_ssl has decided to deny access.

OptRenegotiate
This enables optimized SSL connection renegotiation handling when SSL directives are used in per-directory context. By default, a strict scheme is enabled where every per-directory reconfiguration of SSL parameters causes a full 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 may not be what the user expects, so please enable this on a per-directory basis only.

Example

SSLOptions +FakeBasicAuth -StrictRequire
<Files ~ "\.(cgi|shtml)$">
    SSLOptions +StdEnvVars +CompatEnvVars -ExportCertData
<Files>
SSLRequireSSL

SSLRequireSSL
directory, .htaccess
Apache v2 only

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, which are not using SSL, are denied.

Example

SSLRequireSSL
SSLRequire

SSLRequire expression
directory, .htaccess
Override: AuthConfig
Apache v2 only

This directive invokes a test that has to be fulfilled to allow access. It is a powerful directive because the test is an arbitrarily complex Boolean expression containing any number of access checks.

The expression must match the following syntax (given as a BNF grammar notation — see http://www.cs.man.ac.uk/~pjj/bnf/bnf.html):

expr     ::= "true" | "false"
           | "!" expr
           | expr "&&" expr
           | expr "||" expr
           | "(" expr ")"
           | comp

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

wordlist ::= word
           | wordlist "," word

word     ::= digit
           | cstring
           | variable
           | function

digit    ::= [0-9]+
cstring  ::= "..."
variable ::= "%{" varname "}"
function ::= funcname "(" funcargs ")"

while for varname any of the following standard CGI and Apache variables can be used:

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:variablename

REQUEST_FILENAME

   
as well as any of the following SSL-related variables:

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

   
Finally, for funcname the following functions are available:

file(filename) 

This function takes one string argument and expands to the contents of the file. This is especially useful for matching the contents against a regular expression

Notice that expression is first parsed into an internal machine representation and then evaluated in a second step. In global and per-server class contexts, expression is parsed at startup time. At runtime only the machine representation is executed. In the per-directory context expression is parsed and executed at each request.

Example

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]+$/

In plain English, we require the cipher not to be export or null, the organization to be "Snake Oil, Ltd.," the organizational unit to be one of "Staff," "CA," or "DEV," the date and time to be between Monday and Friday and between 8a.m. and 6p.m., or for the client to come from 192.76.162.



Library Navigation Links

Copyright © 2003 O'Reilly & Associates. All rights reserved.







??????????????@Mail.ru