mod_ssl (Webmaster in a Nutshell, 3rd Edition)

start page | rating of books | rating of authors | reviews | copyrights

19.32. mod_ssl

The mod_ssl enables encrypted, secure transactions between the server and client with SSL (Secure Sockets Layer) Versions 2 and 3, and TLS (Transport Layer Security) Version 1. Apache uses OpenSSL as its cryptography engine. Apache 2.0 and up.

The directives in this module set the locations of certificate and key files, specify options for the behavior of the encryption engine, and set up authorization requirements for access to protected parts of the server. The module also creates a number of new SSL_* environment variables, which will be available to SSI, CGI, and custom logging formats.

SSLCACertificateFile

SSLCACertificateFile filename

[server config, within <VirtualHost>]

Specifies the location of a single file that contains all of the certificates for the Certificate Authorities that you need for client verification. The file is a concatenation of the separate certificates, in order of preference. You can also use separate certificate files located in a single directory specified by SSLCACertificatePath.

SSLCACertificatePath

SSLCACertificatePath directory

[server config, within <VirtualHost>]

Specifies the directory containing the PEM-encoded certificate files for the Certificate Authorities that you need for client verification. Certificate files are accessed with hash filenames via symbolic links of the form hashname.N, This directory can be set up properly using the Makefile provided with mod_ssl.

SSLCARevocationFile

SSLCARevocationFile filename

[server config, within <VirtualHost>]

Specifies a file containing multiple, encoded Certificate Revocation Lists (CRLs) of the Certificate Authorities used by your clients. CRLs are used to revoke client certificates during authentication.

SSLCARevocationPath

SSLCARevocationPath directory

[server config, within <VirtualHost>]

Specifies the directory containing Certificate Revocation Lists (CRLs) for Certificate Authorities used by clients. Encoded CRL files are accessed with hash filenames via symbolic links of the form hashname.rN, This directory can be set up properly using the Makefile provided with mod_ssl.

SSLCertificateChainFile

SSLCertificateChainFile filename

[server config, within <VirtualHost>]

Specifies the single file containing all the server's certificates as a certificate chain establishing a path of trust. This will include the server's certificate and the certificate of the CA that issued it. It could possibly go to higher levels of CA certificates.

SSLCertificateFile

SSLCertificateFile filename

[server config, within <VirtualHost>]

Specifies the file containing the server's certificate and optionally, its RSA or DSA private key.

SSLCertificateKeyFile

SSLCertificateKeyFile filename

[server config, within <VirtualHost>]

Specifies the file containing the server's Private key. This directive must be used in conjunction with SSLCertificateFile, which specifies the certificate file (when the Private key is not included there).

SSLCipherSuite

SSLCipherSuite cipher_spec

[server config, within <VirtualHost> or <Directory>, or .htaccess]

This directive combines a number of cipher specifications to configure the Cipher Suite. The Cipher Suite is the set of methods or algorithms used by the server and client to establish secure communications. The cipher suite is negotiated during the handshake phase, just after a client sends an SSL request. The cipher_spec provided by this directive lists a set of methods that the server will support for a request. The client and server negotiate the most common and preferred methods in this list to use for transactions.

The cipher_spec is a rather complex string that requires at least one declaration for each of the following: a key exchange algorithm, an authentication algorithm, a cipher or encryption algorithm, and MAC digest algorithm. You can additionally declare an export cipher. There are many different tags for specific ciphers that can be combined for the cipher spec. Certain alias tags have been defined to group ciphers into specific sets that comprise certain protocols and levels of security. Table 19-2 lists the alias tags.

Table 19-2. Cipher tag aliases

Tag	Description
`SSLv2`	All SSL 2.0 ciphers
`SSLv3`	All SSL 3.0 ciphers
`TLSv1`	All TLS 1.0 ciphers
`EXP`	All export ciphers
`EXPORT40`	40-bit export ciphers only
`EXPORT56`	56-bit export ciphers only
`LOW`	All low strength ciphers (no export, single DES)
`MEDIUM`	All ciphers with 128-bit encryption
`HIGH`	All Triple-DES ciphers
`RSA`	All ciphers that use RSA key exchange
`DH`	All ciphers that use Diffie-Hellman key exchange
`EDH`	All ciphers that use Ephemeral Diffie-Hellman key exchange
`ADH`	All ciphers that use Anonymous Diffie-Hellman key exchange
`DSS`	All ciphers that use DSS authentication
`NULL`	All ciphers that don't use encryption

The cipher_spec string is composed of a list of cipher tags separated by colons. Each tag may also have a qualifier placed before it. No qualifier means that the cipher is added to the list. A + means that the cipher is added and is pulled to this location on the cipher order. A - means that the cipher is removed from the list, but can be added somewhere else. A ! means that the cipher cannot be used at all.

The default value for this directive demonstrates these features:

ALL:!ADH:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP

The cipher_spec first includes all ciphers, then removes the ones it doesn't want (!ADH) and adjusts the order of preference for the remaining ciphers. See the Apache and OpenSSL documentation for a complete list of cipher tags and complete information on using SSL for secure server communications.

SSLEngine

SSLEngine off|on

[server config, within <VirtualHost>]

Enables or disables the SSL/TLS protocol engine for the server or a virtual host.

SSLMutex

SSLMutex type

[server config]

Configures the SSL engines mutex (mutual exclusion) mechanism to synchronize multiple server processes' access to the SSL session cache. There are three types that can be used:

file:/path/name: On Unix systems, you can specify a file that is used as the mutex lock. This option is not usable in the Win32 environment.
sem: This options uses an IPC semaphore process flag for synchronization on Unix and a Windows Mutex flag on Win32.
none: The default specifies that no exclusion mechanism is used. This may result in mangled information in the SSL session cache.

SSLOptions

SSLOptions [+|-]option...

[server config, within <VirtualHost> or <Directory>, or .htaccess]

Controls a number of SSL runtime options. Per-directory or location merging of options is controlled by the + or - prepended to an option. A + option adds to the set of options that are in place from an higher-level specification. A - options removes an localized option that was in place from a higher-level specification. The available options are:

StdEnvVars: Creates the standard set of SSL-related environment variables. Since there are many of these and gathering this information can cause a performance hit, this configurable per directory, for example, is for CGI and SSL requests only.
CompatEnvVars: Creates a set of environment variables that enable compatibility with previous Apache SSL programs.
ExportCertData: Creates environment variables containing the encoded server and client certificate information for use with CGI.
FakeBasicAuth: Allows basic authorization to be mocked using the Subject Distinguished Name (DN) of a client certificate as a valid username. No password is requested from the user, but the user file must have the appropriately encoded string for "password" for this scheme to work.
StrictRequire: Forces strict SSL authorization (with SSLRequire or SSLRequireSSL) to be satisfied regardless of whether other authorization requirements are met when the Satisfy any directive is used. Without this option, Satisfy any overrides a forbidden access from SSL if other authorization requirements are met.
OptRenegotiate: Allows for optimized renegotiation handling of SSL connections when directory-specific directives are specified. Normally, full renegotiation will be performed.

SSLPassPhraseDialog

SSLPassPhraseDialog type

[server config]

Sets the type of dialog used to get the administrator's pass phrase for accessing encrypted private keys. The administrator needs to provide this information during server startup. The valid types are:

builtin: This uses an interactive dialog at the terminal at startup. The administrator provides the pass phrase for each encrypted private key file. There is a reuse mechanism for multiple keys used on virtual hosts. Pass phrases will automatically be retried to see if it can be used for multiple key files, thus saving some input.
exec:/path/script: This option calls a program at startup to produce the pass phrase however it sees fit, and send it to stdout for use with the terminal dialog described by the builtin option. The script is called with two arguments. The first argument is servername:portnumber, The second is either RSA or DSA, which is determined by the encryption used by the key file. This method is very flexible, and the administrator can provide any number of security checks to the process.

SSLProtocol

SSLProtocol[+|-]protocol

[server config, or within <VirtualHost>]

Specifies the SSL protocol(s) used by the server. The values can be: SSLv2, SSLv3, TLSv1, or All. The + or - flags are used to add or remove a protocol from a set.

SSLProxyCACertificateFile

SSLProxyCACertificateFile

[server config, within <VirtualHost>]

Specifies the location of a single file that contains all of the certificates for the Certificate Authorities that you need for remote server verification. The file is a concatenation of the separate certificates, in order of preference. You can also use separate certificate files located in a single directory specified by SSLProxyCA-CertificatePath.

SSLProxyCACertificatePath

SSLProxyCACertificatePath

[server config, within <VirtualHost>]

Specifies the directory containing the PEM-encoded certificate files for the Certificate Authorities that you need for remote server verification. Certificate files are accessed with hash filenames via symbolic links of the form hashname.N, This directory can be set up properly using the Makefile provided with mod_ssl.

SSLProxyCARevocationFile

SSLProxyCARevocationFile

[server config, within <VirtualHost>]

Specifies a file containing multiple, encoded Certificate Revocation Lists (CRLs) of the Certificate Authorities used by remote servers. CRLs are used to revoke remote server certificates during authentication.

SSLProxyCARevocationPath

SSLProxyCARevocationPath

[server config, within <VirtualHost>]

Specifies the directory containing Certificate Revocation Lists (CRLs) for Certificate Authorities used by remote servers. Encoded CRL files are accessed with hash filenames via symbolic links of the form hashname.rN. This directory can be set up properly using the Makefile provided with mod_ssl.

SSLProxyCipherSuite

SSLProxyCipherSuite cipher_spec

[server config, within <VirtualHost> or <Directory>, or .htaccess]

Specifies the cipher suite used for a proxy connection. The options are the same as SSLCipherSuite.

SSLProxyEngine

SSLProxyEngine on|off

[server config, within <VirtualHost>]

Enables or disables the SSL engine for proxy connections. The default is off.

SSLProxyMachineCertificateFile

SSLProxyMachineCertificateFile

[server config]

Specifies the location of a single file that contains all of the certificates for the Certificate Authorities that are needed to verify the proxy server to remote servers. The file is a concatenation of the separate certificates, in order of preference. You can also use separate certificate files located in a single directory specified by SSLProxyMachineCertificatePath.

SSLProxyMachineCertificatePath

SSLProxyMachineCertificatePath

[server config]

Specifies the directory containing the PEM-encoded certificate files for the Certificate Authorities that you need to verify the proxy server to remote servers. Certificate files are accessed with hash filenames via symbolic links of the form hashname.N, This directory can be set up properly using the Makefile provided with mod_ssl.

SSLProxyProtocol

SSLProxyProtocol

[server config, within <VirtualHost>]

Specifies the SSL protocols available for the proxy server. The options are the same as SSLProtocol.

SSLProxyVerify

SSLProxyVerify level

[server config, within <VirtualHost> or <Directory>, or .htaccess]

Specifies the verification level required for remote server verification. value can be one of the following:

none: No remote server certificate is required.
require: A valid certificate must be presented by the remote server.
optional: A valid certificate may be required for the remote server. This option isn't very useful or supported.
optional_no_ca: The remote server is verified with or without a valid certificate. This is useful for test purposes only.

SSLProxyVerifyDepth

SSLProxyVerifyDepth number

[server config, within <VirtualHost> or <Directory>, or .htaccess]

Specifies the maximum verification depth that is allowed for determination of a valid certificate by a proxy server. The number is the number of unknown intermediate certificates allowed between the client and a certificate authority trusted by the client. For example, a depth of two would allow a client certificate that is certified by a CA unknown to the server. If that CA is certified by another CA known to the server, the verification is allowed. The default is 1.

SSLRandomSeed

SSLRandomSeed context source [bytes]

[server config]

Specifies the source of seeding for the pseudorandom number generator used by OpenSSL. context determines the seeding source either at startup or when a new SSL connection is made (connect).

The source specifies the utility that provides the random seed. builtin indicates that mod_ssl's internal seeding utility is used. It is a simple utility, but doesn't provide a strong seeding source. Other seeding sources are: file:/path/file, which uses the contents of a file to determine the seeding. This usually points to a device file for a random generator like /dev/random. exec:/path/prog points to an executable source for seeding. The source is the stream of bytes sent to stdout. For both file and executable sources, an optional argument specifying a number of bytes indicates that only the first bytes of the source (file or output) will be used. Without this argument, the complete source is used.

SSLRequire

SSLRequire expression

[within <Directory> or .htaccess]

Specifies the requirements that must be met before access is allowed to a resource. The access requirement is an arbitrarily complex boolean expression, whose syntax is very similar to common programming language syntax like C or Java. Logical and comparison operators can be used in any combination with the values of environment variables to determine access. Environment variables are available with the following syntax: %{variable}.

SSLRequireSSL

SSLRequireSSL

[within <Directory> or .htaccess]

When this directive is used (it has no arguments), it forbids access to a directory unless HTTP over SSL is used.

SSLSessionCache

SSLSessionCache type

[server config]

Specifies the type of resource used for the SSL session cache. The session cache contains the SSL verification information for an open session, and allows access to this information to the multiple processes involved in a client request session. Clients will commonly use HTTP KeepAlive to retrieve numerous files associated with a resource like inline images, style sheets, etc., simultaneously to reduce loading time.

This directive specifies the type of resource used for the session cache with the following options:

none: Disables the session cache. Functionality is not affected, but requests will take longer to complete.
dbm:/path/file: Specifies the name of a DBM hash file to use as the session cache file.
shm:/path/file: Specifies a hash table stored in shared memory for the session cache file. An optional size argument sets the size of the hashtable. This option is not available on all platforms.

SSLSessionCacheTimeout

SSLSessionCacheTimeout time

[server config, within <VirtualHost> or <Directory>, or .htaccess]

Specifies the timeout in seconds for the information in the session cache to be valid between requests. The default is 300.

SSLVerifyClient

SSLVerifyClient level

[server config, within <VirtualHost> or <Directory>, or .htaccess]

Specifies the verification level required for client verification. value can be one of the following:

none: No client certificate is required.
require: A valid certificate must be presented by the client.
optional: A valid certificate may be required for the client. This option isn't very useful or supported.
optional_no_ca: The client is verified with or without a valid certificate. This is useful for test purposes only.

SSLVerifyDepth

SSLVerifyDepth number

[server config, within <VirtualHost> or <Directory>, or .htaccess]

Specifies the maximum verification depth is allowed for determination of a valid certificate by a client. The number is the number of unknown intermediate certificates are allowed between the client and a certificate authority trusted by the server. For example, a depth of 2 would allow a client certificate that is certified by a CA unknown to the server. If that CA is certified by another CA known to the server, the verification is allowed. The default is 1.