SSL Directives

SSLEngine

Description	Enable SSL processing.
Synopsis	SSLEngine [on | off]
Context	Default Server, Virtual Host
Example	SSLEngine on

The SSLEngine directive enables SSL processing for the enclosing block of directives. They may be for either the default server or a Virtual Host.

By default the SSL engine is not enabled.

SSLProtocol

Description	Specify the SSL protocols to enable.
Synopsis	SSLProtocol [+ | -] protocol ...
Context	Default Server, Virtual Host
Example	SSLProtocol all -SSLV2

The SSLProtocol directive defines which SSL protocol variants to enable for use. The following protocol options are available:

SSLv2

This is the original Secure Sockets Layer (SSL) protocol defined by Netscape. It has several flaws and should not be used if SSLv3 or TLSv1 are available.

SSLv3

This is the Secure Sockets Layer (SSL) protocol version 3.

TLSv1

This is the Transport Layer Security (TLS) protcol version 1. It is the most current SSL standard defined by the IETF and should be used if available.

ALL

Enables all SSL protocol variants.

SECURITY WARNING:  You should not use SSLv2 if possible. The following examples is the recommended configuration for the SSLProtocol directive. It will enable SSLv3 and TLSv1 and will disable SSLv2

SSLProtocol all -SSLv2

SSLCipherSuite

Description	Selects the Cipher suite to use when negotiating SSL sessions.
Synopsis	SSLCipherSuite cipher-spec
Context	Default Server, Virtual Host
Example	LogLevel 2

The SSLCipherSuite directive specifies the cipher algorithms to use when handshaking and negotiating SSL sessions. It specifies the ciphers that AppWeb will accept the client using.

This is a complex directive. Don't change it unless you really know what you are doing. It is easy to weaken your security via bad edits. The follow explanation has been taken from the Apache documentation:

An SSL cipher specification in cipher-spec is composed of 4 major attributes plus a few extra minor ones:

• Key Exchange Algorithm:
  RSA or Diffie-Hellman variants.
• Authentication Algorithm:
  RSA, Diffie-Hellman, DSS or none.
• Cipher/Encryption Algorithm:
  DES, Triple-DES, RC4, RC2, IDEA or none.
• MAC Digest Algorithm:
  MD5, SHA or SHA1.

An SSL cipher can also be an export cipher and is either a SSLv2 or SSLv3/TLSv1 cipher (here TLSv1 is equivalent to SSLv3). To specify which ciphers to use, one can either specify all the Ciphers, one at a time, or use aliases to specify the preference and order for the ciphers (see Table 1).

Tag	Description
Key Exchange Algorithm:
kRSA	RSA key exchange
kDHr	Diffie-Hellman key exchange with RSA key
kDHd	Diffie-Hellman key exchange with DSA key
kEDH	Ephemeral (temp.key) Diffie-Hellman key exchange (no cert)
Authentication Algorithm:
aNULL	No authentication
aRSA	RSA authentication
aDSS	DSS authentication
aDH	Diffie-Hellman authentication
Cipher Encoding Algorithm:
eNULL	No encoding
DES	DES encoding
3DES	Triple-DES encoding
RC4	RC4 encoding
RC2	RC2 encoding
IDEA	IDEA encoding
MAC Digest Algorithm:
MD5	MD5 hash function
SHA1	SHA1 hash function
SHA	SHA hash function
Aliases:
SSLv2	all SSL version 2.0 ciphers
SSLv3	all SSL version 3.0 ciphers
TLSv1	all TLS version 1.0 ciphers
EXP	all export ciphers
EXPORT40	all 40-bit export ciphers only
EXPORT56	all 56-bit export ciphers only
LOW	all low strength ciphers (no export, single DES)
MEDIUM	all ciphers with 128 bit encryption
HIGH	all ciphers using Triple-DES
RSA	all ciphers using RSA key exchange
DH	all ciphers using Diffie-Hellman key exchange
EDH	all ciphers using Ephemeral Diffie-Hellman key exchange
ADH	all ciphers using Anonymous Diffie-Hellman key exchange
DSS	all ciphers using DSS authentication
NULL	all ciphers using no encryption

Now where this becomes interesting is that these can be put together to specify the order and ciphers you wish to use. To speed this up there are also aliases (SSLv2, SSLv3, TLSv1, EXP, LOW, MEDIUM, HIGH) for certain groups of ciphers. These tags can be joined together with prefixes to form the cipher-spec. Available prefixes are:

• none: add cipher to list

• +: add ciphers to list and pull them to current location in list

• -: remove cipher from list (can be added later again)

• !: kill cipher from list completely (can not be added later again)

A simpler way to look at all of this is to use the ``openssl ciphers -v'' command which provides a nice way to successively create the correct cipher-spec string. The default cipher-spec string is:


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

which means the following: first, remove from consideration any ciphers that do not authenticate, i.e. for SSL only the Anonymous Diffie-Hellman ciphers. Next, use ciphers using RC4 and RSA. Next include the high, medium and then the low security ciphers. Finally pull all SSLv2 and export ciphers to the end of the list.

SSLCertificateFile

Description	Defines the location of the X.509 file containing the server certificate
Synopsis	SSLCertificateFile path
Context	Default Server, Virtual Host
Example	SSLCertificateFile /var/appWeb/server.crt

The SSLCertificateFile directive defines the file containing the PEM encoded X.509 certificate for the server. The file may also contain the private key for the server in which case you do not need to use the SSLCertificateKeyFile directive.

The path may be an absolute path or it may be relative to the ServerRoot.

SSLCertificateKeyFile

Description	Defines the location of the server's private key
Synopsis	SSLCertificateKeyFile
Context	Default Server, Virtual Host
Example	SSLCertificateKeyFile /var/appWeb/server.key.pem

The SSLCertificateKeyFile directive defines the file containing the PEM encoded private key file for the server. This directive is not required if the server's private key is combined with the certificate file.

If the private key is encrypted, you will be prompted to enter the pass-phrase to decript the private key on system reboot.

SECURITY WARNING: There is a delima here. If you use a crypted private key, the server will pause until you enter the pass-phrase which makes headless operation impossible. If you do not encrypt the private key, your private key is more vulnerable should the server be compromised. Which option you choose depends on whether headless operation is essential or not.

SSLCACertificateFile

Description	Defines the location of the certificate file for client authentication
Synopsis	SSLCACertificateFile path
Context	Default Server, Virtual Host
Example	SSLCACertificateFile /var/appWeb/ca.crt

The SSLCACertificateFile directive defines the file containing the certificates to use when authenticating client certificates. This directive is only necessary if you wish to verify client certificates. If so, you must specify the "SSLVerifyClient Require" directive.

The certificate file contains the concatenated certificates to use in preference order. The path may be an absolute path or it may be relative to the ServerRoot.

You may alternatively use SSLCACertificatePath if you have separate certificates.

SSLCACertificatePath

Description	Defines the directory containing the certificates to use for client authentication.
Synopsis	SSLCACertificatePath
Context	Default Server, Virtual Host
Example	SSLCACertificatePath /var/appWeb/certs

The SSLCACertificatePath directive defines the directory containing the certificates to use when authenticating client certificates. This directive is only necessary if you wish to verify client certificates. If so, you must specify the "SSLVerifyClient Require" directive.

The path may be an absolute path or it may be relative to the ServerRoot.

You may alternatively use SSLCACertificateFile if you have a bundle of certificates concatenated together.