Apache-SSL Documentation

Last updated: May 01, 2001

Directives


CGI Environment Variables

Status: Extension
Module: Apache-SSL

Name			Value		Desc

HTTPS [if SET] HTTPS is being used. HTTPS_CIPHER <string> SSL/TLS cipherspec SSL_CIPHER <string> The same as HTTPS_CIPHER SSL_PROTOCOL_VERSION <string> Self explanatory SSL_SSLEAY_VERSION <string> Self explanatory HTTPS_KEYSIZE <number> Number of bits in the session key HTTPS_SECRETKEYSIZE <number> Number of bits in the secret key SSL_CLIENT_DN <string> DN in client's certificate SSL_CLIENT_<x509> <string> Component of client's DN SSL_CLIENT_I_DN <string> DN of issuer of client's certificate SSL_CLIENT_I_<x509> <string> Component of client's issuer's DN SSL_SERVER_DN <string> DN in server's certificate SSL_SERVER_<x509> <string> Component of server's DN SSL_SERVER_I_DN <string> DN of issuer of server's certificate SSL_SERVER_I_<x509> <string> Component of server's issuer's DN SSL_CLIENT_CERT <string> Base64 encoding of client cert SSL_CLIENT_CERT_CHAIN_n <string> Base64 encoding of client cert chain
where <x509> is a component of an X509 DN.


CustomLog

Status: Extension
Module: Apache-SSL

Although CustomLog is a standard Apache directive, Apache-SSL adds some extra information 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 %{version}c"



SSLBanCipher

Syntax: SSLBanCipher cipher-list
Context: server config, virtual host, .htaccess, directory
Override: FileInfo
Status: Extension
Module: Apache-SSL
Compatibility: ??

This directive specifies a space-separated list of cipher suites, as per SSLRequireCipher, except it bans them. It goes like this: if banned, reject; if required, accept; if no required ciphers listed, accept.

Examples:

SSLBanCipher RC4-MD5 EXP-RC4-MD5
or (a rather sensible one to use by default):
SSLBanCipher NULL-MD5 NULL-SHA


SSLCACertificateFile

Syntax: SSLCACertificateFile file
Context: server config, virtual host
Status: Extension
Module: Apache-SSL
Compatibility: ??

You can use this directive instead of SSLCACertificatePath to specify a single certificate file. This file can contain more than one certificate.

Example:

SSLCACertificateFile /usr/local/apache/certs/my.ca.pem


SSLCACertificatePath

Syntax: SSLCACertificatePath directory
Context: server config, virtual host
Status: Extension
Module: Apache-SSL
Compatibility: ??

This is the path to the directory where you keep the certificates of the certification authorities whose client certificates you are prepared to accept. They must be PEM encoded (or, at least, what SSLeay calls PEM encoded).

Example:

SSLCACertificatePath /usr/local/apache/certs


SSLCacheServerPath

Syntax: SSLCacheServerPath command
Context: server config
Status: Extension
Module: Apache-SSL
Compatibility: ??

This is the path of the global cache server executable, gcache. It can be absolute or relative to the ServerRoot.

Example:

SSLCacheServerPath /usr/local/apache/bin/gcache
or
SSLCacheServerPath bin/gcache


SSLCacheServerPort

Syntax: SSLCacheServerPort port|filename
Context: server config
Status: Extension
Module: Apache-SSL
Compatibility: apache_1.3.2+ssl_1.27

The global cache server specified in SSLCacheServerPath can use either TCP/IP or Unix domain sockets. If the argument is a number, then a TCP/IP port at that number is used, otherwise it must be a fully qualified filename to use for a Unix domain socket.

Note that an attacker can do bad things if they can connect to gcache, so it is important to ensure that Apache-SSL is the only thing that can connect to the port specified, either with firewalls or with appropriate file permissions on a Unix domain socket.

Examples:

SSLCacheServerPort 12345
or
SSLCacheServerPort /a/path/to/a/socket


SSLCacheServerRunDir

Syntax: SSLCacheServerRunDir directory
Context: server config
Status: Extension
Module: Apache-SSL
Compatibility: ??

Set the directory gcache runs in. Useful only for debugging, so gcache can produce core dumps.


SSLCertificateFile

Syntax: SSLCertificateFile file
Context: server config, virtual host
Status: Extension
Module: Apache-SSL
Compatibility: ??

This is your PEM-encoded server certificate (strictly, it is what SSLeay calls PEM, which isn't really).

Example:

SSLCertificateFile /usr/local/apache/certs/my.server.pem


SSLCertificateKeyFile

Syntax: SSLCertificateKeyFile file
Default: embedded in SSLCertificateFile
Context: server config, virtual host
Status: Extension
Module: Apache-SSL
Compatibility: ??

This is the private key of your certificate, PEM-encoded. If the key is not combined with the SSLCertificateFile, use this directive to point at the key file. If the filename starts with /, it specifies an absolute path; otherwise, it is relative to the default certificate area that is currently defined by SSLeay to be either: /usr/local/ssl/private or wherever_you_told_ssl_to_install/private.

Examples:

SSLCertificateKeyFile /usr/local/apache/certs/my.server.key.pem
or
SSLCertificateKeyFile certs/my.server.key.pem


SSLDenySSL

Syntax: SSLDenySSL
Context: server config, virtual host, .htaccess, directory
Override: FileInfo
Status: Extension
Module: Apache-SSL
Compatibility: apache_1.3.6+ssl_1.36

Deny SSL. The opposite of SSLRequireSSL. Access will be denied if SSL is active.

Example:

<Directory /some/where/that/must/be/in/the/clear>
  SSLDenySSL
</Directory>


SSLDisable

Syntax: SSLDisable
Default: SSLEnable
Context: server config, virtual host
Status: Extension
Module: Apache-SSL
Compatibility: ??

Disable SSL. This is useful if you wish to run both secure and nonsecure hosts on the same server. Conversely, SSL is enabled via SSLEnable.


SSLEnable

Syntax: SSLEnable
Default: SSLEnable
Context: server config, virtual host
Status: Extension
Module: Apache-SSL
Compatibility: ??

Enable SSL. The default, but if you've used SSLDisable in the main server, you can enable SSL again for virtual hosts using this directive.


SSLExportClientCertificates

Syntax: SSLExportClientCertificates
Context: server config, virtual host, .htaccess, directory
Status: Extension
Module: Apache-SSL
Compatibility: apache_1.3.2+ssl_1.27

Export client certificates and the certificate chain behind them to CGIs. The certificates are base 64 encoded in the environment variables SSL_CLIENT_CERT and SSL_CLIENT_CERT_CHAIN_n, where n runs from 1 upwards.

Example:

For a working example, see: https://www.apache-ssl.org/cgi/cert-export
Simple shell script source for the above example can be found here.

N.B. This directive is only enabled if APACHE_SSL_EXPORT_CERTS is set to TRUE in .../src/include/buff.h.


SSLFakeBasicAuth

Syntax: SSLFakeBasicAuth
Context: server config, virtual host
Status: Extension
Module: Apache-SSL
Compatibility: ??

This directive simulates user logons using basic authentication, using the one-line certificate name - a version of the client's certificate produced by the SSLeay function X509_NAME_oneline() (note that this may be the Distinguished Name of the subject of the cert, but SSLeay appears to make no promise of this). If enabled with SSLVerifyClient, you should see the name in the error log when a non-authorised user attempts a connection, and access will be refused. To allow access to the user, add the name and fixed password ''xxj31ZMTZzkVA'' (which is ''password'' encrypted) to the auth file.

Example:

  SSLFakeBasicAuth
  <Directory /www/watchdog/htdocs>
     AllowOverride none
     AuthUserFile /www/auth/watchdog/users
     AuthType Basic
     AuthName Watchdog
     Require valid-user
   </Directory>

SSLNoCAList

Syntax: SSLNoCAList
Context: server config, virtual host
Status: Extension
Module: Apache-SSL
Compatibility: apache_1.3.6+ssl_1.34

Disable presentation of CA list for client certificate authentication. Unlikely to be useful in a production environment, but extremely handy for testing purposes.


SSLRandomFile

Syntax: SSLRandomFile file|egd file|egd-socket bytes
Context: server config
Status: Extension
Module: Apache-SSL
Compatibility: apache_1.3.4+ssl_1.31

Load some randomness. This is loaded at startup, reading at most bytes bytes from file. The randomness will be shared between all server instances. You can have as many of these as you want.

Example:

  SSLRandomFilePerConnection file /dev/urandom 1024

    or

  SSLRandomFilePerConnection egd /path/to/egd/socket 1024

N.B. This directive may cause your server to hang until the requested number of random bytes have been read from the device. If in doubt, check the functionality of /dev/random on your platform, but as a general rule, the alternate device /dev/urandom will return immediately (at the potential cost of less randomness). On systems that have no random device, tools such as the Entropy Gathering Daemon can be used to provide random data. The first argument specifies if the random source is a file/device or the egd socket. On a Sun, it is rumoured you can install a package called SUNski that will give you /etc/random. It is also part of patch 105710-01.


SSLRandomFilePerConnection

Syntax: SSLRandomFilePerConnection file|egd file|egd-socket bytes
Context: server config
Status: Extension
Module: Apache-SSL
Compatibility: apache_1.3.4+ssl_1.31

Load some randomness (per connection). This will be loaded before SSL is negotiated for each connection. Again, you can have as many of these as you want, and they will all be used at each connection.

Example:

  SSLRandomFilePerConnection file /dev/urandom 1024

    or

  SSLRandomFilePerConnection egd /path/to/egd/socket 1024

N.B. See footnote for SSLRandomFile above.


SSLRequireCipher

Syntax: SSLRequireCipher cipher-list
Context: server config, virtual host, .htaccess, directory
Override: FileInfo
Status: Extension
Module: Apache-SSL
Compatibility: ??

This directive specifies a space-separated list of cipher suites, used after the connection is established to verify the cipher. This is a per-directory option. Possible suites are listed below.

Example:

SSLRequireCipher RC4-MD5 EXP-RC4-MD5


SSLRequireSSL

Syntax: SSLRequireSSL
Context: server config, virtual host, .htaccess, directory
Override: FileInfo
Status: Extension
Module: Apache-SSL
Compatibility: ??

Require SSL. This can be used in sections (and elsewhere) to protect against inadvertantly disabling SSL. If SSL is not in use when this directive applies, access will be refused. This is a useful belt-and-braces measure for critical information. Conversely, deny SSL connections with SSLDenySSL.

Example:

<Directory /some/where/important>
  SSLRequireSSL
</Directory>


SSLRequiredCiphers

Syntax: SSLRequiredCiphers cipher-list
Context: server config, virtual host
Status: Extension
Module: Apache-SSL
Compatibility: ??

This directive specifies a colon-separated list of cipher suites, used by SSLeay to limit what the client end can do. Possible suites are listed below. The SSL protocol does not restrict clients and servers to a single encryption brew for the secure exchange of information. There are a number of possible cryptographic ingredients, but as in any cooking pot, some ingredients go better together than others. The seriously interested can refer to Bruce Schneier's Applied Crytography, published by John Wiley & Sons, in conjunction with the SSL specification (from Netscape). The list of cipher suites is also in the SSLeay software at .../ssl/ssl.h. The macro names give a better idea of what is meant than the text strings.

Example:

SSLRequiredCiphers RC4-MD5:RC4-SHA:IDEA-CBC-MD5:DES-CBC3-SHA


SSLSessionCacheTimeout

Syntax: SSLSessionCacheTimeout seconds
Context: server config, virtual host
Status: Extension
Module: Apache-SSL
Compatibility: ??

A session key is generated when a client connects to the server for the first time. This directive sets the length of time in seconds that the session key will be cached locally. Lower values are safer (an attacker then has a limited time to crack the key before a new one will be used) but also slower, as the key will be regenerated at each timeout. If client certificates are being requested by the server, they will also be required to be re-presented at each timeout. For many purposes timeouts measured in hours are perfectly safe.

Example:

SSLSessionCacheTimeout 3600


SSLVerifyClient

Syntax: SSLVerifyClient level
Default: SSLVerifyClient 0
Context: server config, virtual host
Status: Extension
Module: Apache-SSL
Compatibility: ??

This directive defines what certification you require of clients:

0 - No certificate required.
1 - The client may present a valid certificate. If a certificate is presented, it must be from a Certification Authority for which the server holds a certificate.
2 - The client must present a valid certificate.
3 - The client may present a valid certificate, but not necessarily from a Certification Authority for which the server holds a certificate.

Example:

SSLVerifyClient 2


SSLVerifyDepth

Syntax: SSLVertifyDepth depth
Default: SSLVerifyDepth 0
Context: server config, virtual host
Status: Extension
Module: Apache-SSL
Compatibility: ??

In real life, the certificate we are dealing with was issued by a CA who in turn relied on another CA to validate them, and so on, back to a root certificate. This directive specifies how far up or down the chain we are prepared to go before giving up. What happens when we give up is determined by the setting given to SSLVerifyClient. Normally you only trust certificates signed directly by a CA you've authorised, so this should be set to 1.

Example:

SSLVerifyDepth 1


Cipher Suites

									Encrypted
SSLeay name				Config name		Keysize	Keysize

SSL3_TXT_RSA_IDEA_128_SHA IDEA-CBC-SHA 128 128 SSL3_TXT_RSA_NULL_MD5 NULL-MD5 0 0 SSL3_TXT_RSA_NULL_SHA NULL-SHA 0 0 SSL3_TXT_RSA_RC4_40_MD5 EXP-RC4-MD5 128 40 SSL3_TXT_RSA_RC4_128_MD5 RC4-MD5 128 128 SSL3_TXT_RSA_RC4_128_SHA RC4-SHA 128 128 SSL3_TXT_RSA_RC2_40_MD5 EXP-RC2-CBC-MD5 128 40 SSL3_TXT_RSA_IDEA_128_SHA IDEA-CBC-MD5 128 128 SSL3_TXT_RSA_DES_40_CBC_SHA EXP-DES-CBC-SHA 56 40 SSL3_TXT_RSA_DES_64_CBC_SHA DES-CBC-SHA 56 56 SSL3_TXT_RSA_DES_192_CBC3_SHA DES-CBC3-SHA 168 168 SSL3_TXT_DH_DSS_DES_40_CBC_SHA EXP-DH-DSS-DES-CBC-SHA 56 40 SSL3_TXT_DH_DSS_DES_64_CBC_SHA DH-DSS-DES-CBC-SHA 56 56 SSL3_TXT_DH_DSS_DES_192_CBC3_SHA DH-DSS-DES-CBC3-SHA 168 168 SSL3_TXT_DH_RSA_DES_40_CBC_SHA EXP-DH-RSA-DES-CBC-SHA 56 40 SSL3_TXT_DH_RSA_DES_64_CBC_SHA DH-RSA-DES-CBC-SHA 56 56 SSL3_TXT_DH_RSA_DES_192_CBC3_SHA DH-RSA-DES-CBC3-SHA 168 168 SSL3_TXT_EDH_DSS_DES_40_CBC_SHA EXP-EDH-DSS-DES-CBC-SHA 56 40 SSL3_TXT_EDH_DSS_DES_64_CBC_SHA EDH-DSS-DES-CBC-SHA 56 56 SSL3_TXT_EDH_DSS_DES_192_CBC3_SHA EDH-DSS-DES-CBC3-SHA 168 168 SSL3_TXT_EDH_RSA_DES_40_CBC_SHA EXP-EDH-RSA-DES-CBC 56 40 SSL3_TXT_EDH_RSA_DES_64_CBC_SHA EDH-RSA-DES-CBC-SHA 56 56 SSL3_TXT_EDH_RSA_DES_192_CBC3_SHA EDH-RSA-DES-CBC3-SHA 168 168 SSL3_TXT_ADH_RC4_40_MD5 EXP-ADH-RC4-MD5 128 40 SSL3_TXT_ADH_RC4_128_MD5 ADH-RC4-MD5 128 128 SSL3_TXT_ADH_DES_40_CBC_SHA EXP-ADH-DES-CBC-SHA 128 40 SSL3_TXT_ADH_DES_64_CBC_SHA ADH-DES-CBC-SHA 56 56 SSL3_TXT_ADH_DES_192_CBC_SHA ADH-DES-CBC3-SHA 168 168 SSL3_TXT_FZA_DMS_NULL_SHA FZA-NULL-SHA 0 0 SSL3_TXT_FZA_DMS_FZA_SHA FZA-FZA-CBC-SHA -1 -1 SSL3_TXT_FZA_DMS_RC4_SHA FZA-RC4-SHA 128 128 SSL2_TXT_DES_64_CFB64_WITH_MD5_1 DES-CFB-M1 56 56 SSL2_TXT_RC2_128_CBC_WITH_MD5 RC2-CBC-MD5 128 128 SSL2_TXT_DES_64_CBC_WITH_MD5 DES-CBC-MD5 56 56 SSL2_TXT_DES_192_EDE3_CBC_WITH_MD5 DES-CBC3-MD5 168 168 SSL2_TXT_RC4_64_WITH_MD5 RC4-64-MD5 64 64 SSL2_TXT_NULL NULL 0 0
Return to the Apache-SSL homepage.



Copyright © 1995,6,7,8,9,2000 Ben Laurie, Adam Laurie.
With acknowledgement to Ralf S. Engelschall.