# Apache-SSL Documentation

Last updated: February 06, 2004

## Directives

- CGI Environment Variables
- CustomLog
- SSLBanCipher
- SSLCACertificateFile
- SSLCACertificatePath
- SSLCRLCheckAll
- SSLCacheServerPath
- SSLCacheServerPort
- SSLCacheServerRunDir
- SSLCertificateFile
- SSLCertificateKeyFile
- SSLCheckClientDN
- SSLDenySSL
- SSLDisable
- SSLEnable
- SSLExportClientCertificates
- SSLFakeBasicAuth
- SSLNoCAList
- SSLNoV2
- SSLOnCRLExpirySetEnv
- SSLOnNoCRLSetEnv
- SSLOnRevocationSetEnv
- SSLRandomFile
- SSLRandomFilePerConnection
- SSLRequireCipher
- SSLRequireSSL
- SSLRequiredCiphers
- SSLSessionCacheTimeout
- SSLUseCRL
- SSLVerifyClient
- SSLVerifyDepth

## 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

## SSLCRLCheckAll

Syntax: SSLCRLCheckAll
Context: server config, virtual host
Status: Extension
Module: Apache-SSL
Compatibility: apache_1.3.28+ssl_1.50

Check all certificates in the chain against their CRLs, rather than just the client certificate.

## 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

## SSLCheckClientDN

Syntax: SSLCheckClientDN file
Context: server config, virtual host
Status: Extension
Module: Apache-SSL
Compatibility: apache_1.3.19+ssl_1.43

The client DN is checked against the file. If it appears in the file, access is permitted, if it does not, it isn't. This allows client certificates to be checked and basic auth to be used as well, which cannot happen with the alternative, SSLFakeBasicAuth.

## 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>

See also CheckClientDN.

## 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.

## SSLNoV2

Syntax: SSLNoV2
Context: server config, virtual host
Status: Extension
Module: Apache-SSL
Compatibility: apache_1.3.29+ssl_1.53

Disable SSL version 2 - this version has know security issues, so unless there's a good reason, always use this command.

## SSLOnCRLExpirySetEnv

Syntax: SSLOnCRLExpirySetEnv var
Context: server config, virtual host
Status: Extension
Module: Apache-SSL
Compatibility: apache_1.3.28+ssl_1.52

If the CRL has expired, instead of returning an error to the client, permit the SSL session to be established and set the named environment variable to "YES". Note that there is no SSL error to handle this situation, so when this directive isn't use, the error returned by OpenSSL is that the client certificate has expired.

## SSLOnNoCRLSetEnv

Syntax: SSLOnNoCRLSetEnv var
Context: server config, virtual host
Status: Extension
Module: Apache-SSL
Compatibility: apache_1.3.28+ssl_1.52

If there is no CRL for the client certificate, instead of returning an error to the client, permit the SSL session to be established and set the named environment variable to "YES".

## SSLOnRevocationSetEnv

Syntax: SSLOnRevocationSetEnv var
Context: server config, virtual host
Status: Extension
Module: Apache-SSL
Compatibility: apache_1.3.28+ssl_1.50

Instead of returning an SSL error to the client, permit the SSL session to be established and set the named environment variable to "YES".

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

>       SSLRandomFile file /dev/urandom 1024

>         or

>       SSLRandomFile 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

## SSLUseCRL

Syntax: SSLUseCRL
Context: server config, virtual host
Status: Extension
Module: Apache-SSL
Compatibility: apache_1.3.28+ssl_1.50

Client certificates are checked against an appropriate CRL. The CRL is expected to be in the path set by SSLCACerificatePath. The CRL should be in PEM format, and softlinked to a file of the form `<hash>.r<number>`. Assuming no hash collisions this can be generated like this:

>     hash=`openssl crl -hash -in $file -noout`
>     ln -sf $file $hash.r0

N.B. The CRL is not reloaded when updated - Apache must be restarted for that to happen!

## 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,1,2,3 Ben Laurie, Adam Laurie.
With acknowledgement to Ralf S. Engelschall.