Name Value Descwhere <x509> is a component of an X509 DN.
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
Although CustomLog is a standard Apache directive, Apache-SSL adds some extra information that can be logged:
{cipher}cThe name of the cipher being used for this connection.
{clientcert}cThe "one-line" version of the certificate presented by the client.
{errcode}cIf the client certificate verification failed, this is the SSLeay error code. In the case of success a "-" will be logged.
{errstr}cThis is the SSLeay string corresponding to the error code.
{version}cThe 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"
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-MD5or (a rather sensible one to use by default):SSLBanCipher NULL-MD5 NULL-SHA
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
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
Check all certificates in the chain against their CRLs, rather than just the client certificate.
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/gcacheorSSLCacheServerPath bin/gcache
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 12345orSSLCacheServerPort /a/path/to/a/socket
Set the directory gcache runs in. Useful only for debugging, so gcache can produce core dumps.
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
embedded in SSLCertificateFileThis 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.pemorSSLCertificateKeyFile certs/my.server.key.pem
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.
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>
SSLEnableDisable SSL. This is useful if you wish to run both secure and nonsecure hosts on the same server. Conversely, SSL is enabled via SSLEnable.
SSLEnableEnable SSL. The default, but if you've used SSLDisable in the main server, you can enable SSL again for virtual hosts using this directive.
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.
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.
Disable presentation of CA list for client certificate authentication. Unlikely to be useful in a production environment, but extremely handy for testing purposes.
Disable SSL version 2 - this version has know security issues, so unless there's a good reason, always use this command.
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.
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".
Instead of returning an SSL error to the client, permit the SSL session to be established and set the named environment variable to "YES".
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.
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.
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
Require SSL. This can be used in
Example:
<Directory /some/where/important> SSLRequireSSL </Directory>
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
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
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 0This 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 0In 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
Encrypted SSLeay name Config name Keysize KeysizeReturn to the Apache-SSL homepage.
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
