C - A P P E N D I X -

A P P E N D I X C

SSL Configuration Directives for Apache Web Servers

This appendix lists directives for using Sun Crypto Accelerator 1000 software to configure SSL support for Apache Web Servers. Configure directives in your http.conf file. Refer to the Apache Web Server documentation for more information.

1. SSLPassPhraseDialog exec:program

Context: Global

This directive informs the Apache Web Server that the specified program should be executed to collect the password for key file. program should print the collected password to standard output.

If multiple key files are present, and have common passwords, then program will only be executed once (each collected password is tried before running program again.)

program is executed with two arguments, the first is the name of the server, in the form servername:port, for example, www.fictional-company.com:443. (Port 443 is the typical port for SSL based web servers.) The second argument is the type of key in the key file (keytype). keytype can be either RSA or DSA.

Note - Because this program can be executed during system startup, be sure to design it to cope with the situation where the console is not a tty device (that is a tty(3c) returns false).

The supplied program /opt/SUNWconn/crypto/bin/sslpassword can be used for the program executable. This program automatically prompts for the password, suppressing the display of the password as it is entered.

The supplied sslpassword program also automatically searches for passwords in files, which can be used to avoid user interaction when the web server starts up. Passwords for key files are searched for in files named /etc/apache/servername:port.keytype.pass. If this file is not present, then the file /etc/apache/default.pass is used. The content of these password files is just the unencrypted password on a line by itself.

Note - Password files should be protected by permissions so that only the UNIX user that the web server runs as can read the file. This user should be the same user as configured with the standard Apache User directive.

If not specified, the default behavior uses an internal prompting mechanism. Sun customers are advised to not use the default, and use the supplied sslpassword program instead, to avoid problems with interaction at system startup.

2. SSLEngine (on|off)

Context: Global, virtual host

This directive enables the SSL protocol. It is typically used in a virtual host to enable SSL on a subset of servers. One form commonly used is:

<VirtualHost _default_:443>

SSLEngine on

</VirtualHost>

This statement configures the use of SSL for any servers listening on port 443 (the standard HTTPS port). If not present, this protocol is turned off by default.

3. SSLProtocol [+-]protocol

Context: global, virtual host

This directive configures the protocol(s) that the server should use for SSL transactions. The available protocols are listed and described in TABLE C-1:


Protocol	Description
`SSLv2`	Original standard SSL protocol from Netscape
`SSLv3`	Updated version of the SSL protocol, supported by most popular web browsers
`TLSv1`	Update to `SSLv3` currently undergoing IETF standardization, with minimal browser support
`all`	Enable all protocols

Using the plus (+) or minus (-) signs, protocols can be added or removed. For example, to disable support for SSLv2, the following directive could be used:

SSLProtocol all -SSLv2

The preceding statement is equivalent to:

SSLProtocol +SSLv3 +TLSv1

4. SSLCipherSuite cipher-spec

Context: Global, virtual host, directory, .htaccess

The SSLCipherSuite directive is used to configure which SSL ciphers are available for use and their preference. In global context or virtual host context, directive is used during the initial SSL handshake. In per-directory context, it forces an SSL renegotiation to use the named ciphers. The renegotation takes place after the request is read, but before the response is sent.

The cipher-spec is a colon-delimited list of the ciphers described in TABLE C-2. In TABLE C-2, DH refers to Diffie-Hellman and DSS refers to the Digital Signature Standard.


Cipher-Tag	Protocol	Key Exchange	Auth.	Encryption	MAC	Type
`DES-CBC3-SHA`	SSLv3	RSA	RSA	3DES (168-bit)	SHA1
`DES-CBC3-MD5`	SSLv2	RSA	RSA	3DES (168-bit)	MD5
`RC4-SHA`	SSLv3	RSA	RSA	ARCFOUR (128-bit)	SHA1
`RC4-MD5`	SSLv3	RSA	RSA	ARCFOUR (128-bit)	MD5
`RC4-MD5`	SSLv2	RSA	RSA	ARCFOUR (128-bit)	MD5
RC2-CBC-MD5	SSLv2	RSA	RSA	ARCTWO (128-bit)
`DES-CBC-SHA`	SSLv3	RSA	RSA	DES (56-bit)	SHA1
`RC4-64-MD5`	SSLv2	RSA	RSA	ARCFOUR (64-bit)	MD5
`DES-CBC-MD5`	SSLv2	RSA	RSA	DES (56-bit)	MD5
`EXP-DES-CBC-SHA`	SSLv3	RSA (512 bit)	RSA	DES (40-bit)	SHA1	export
`EXP-RC2-CBC-MD5`	SSLv2	RSA (512 bit)	RSA	ARCTWO (40-bit)	SHA1	export
`EXP-RC2-CBC-MD5`	SSLv3	RSA (512 bit)	RSA	ARCTWO (40-bit)	SHA1	export
`EXP-RC4-MD5`	SSLv3	RSA (512 bit)	RSA	ARCFOUR (40-bit)	MD5	export
`EXP-RC4-MD5`	SSLv2	RSA (512 bit)	RSA	ARCFOUR (40-bit)	MD5	export
`NULL-SHA`	SSLv3	RSA	RSA	None	SHA1
`NULL-MD5`	SSLv3	RSA	RSA	None	MD5
`ADH-DES-CBC3-SHA`	SSLv3	DH	None	3DES (168-bit)	SHA1
`ADH-DES-CBC-SHA`	SSLv3	DH	None	DES (56-bit)	SHA1
`ADH-RC4-MD5`	SSLv3	DH	None	ARCFOUR (128-bit)	MD5
`EDH-RSA-DES-CBC3-SHA`	SSLv3	DH	RSA	3DES (168-bit)	SHA1
`EDH-DSS-DES-CBC3-SHA`	SSLv3	DH	DSS	3DES (168-bit)	SHA1
`EDH-RSA-DES-CBC-SHA`	SSLv3	DH	RSA	DES (56-bit)	SHA1
`EDH-DSS-DES-CBC-SHA`	SSLv3	DH	DSS	DES (56-bit)	SHA1
`EXP-EDH-RSA-DES-CBC-SHA`	SSLv3	DH (512 bit)	RSA	DES (40-bit)	SHA1	export
`EXP-EDH-DSS-DES-CBC-SHA`	SSLv3	DH (512 bit)	DSS	DES (40-bit)	SHA1	export
`EXP-ADH-DES-CBC-SHA`	SSLv3	DH (512 bit)	None	DES (40-bit)	SHA1	export
`EXP-ADH-RC4-MD5`	SSLv3	DH (512 bit)	None	ARCFOUR (40-bit)	MD5	export

TABLE C-3 lists and describes the aliases that provide macro-like groupings.


Alias	Description
`SSLv2`	All SSL version 2.0 ciphers
`SSLv3`	All SSL version 3.0 ciphers
`EXP`	All export-grade ciphers
`EXPORT40`	All 40-bit export ciphers
`EXPORT56`	All 56-bit export ciphers
`LOW`	Lower strength ciphers (DES, 40-bit RC4)
`MEDIUM`	All 128-bit ciphers
`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

The preference of ciphers can be configured using the special characters listed and described in TABLE C-4.


Character	Description
<none>	Add cipher to list
!	Remove a cipher from the list entirely--it cannot be added again
+	Add cipher to list, and pull to current location (possibly demoting it)
-	Remove cipher from list (can be added later in list)

The default value of cipher-spec is

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

The default configures all ciphers except anonymous (unauthenticated) Diffie-Hellman, giving preference to ARCFOUR and RSA, and then higher grades of encryption over the lower grades.

5. SSLCertificateFile file

Context: Global, virtual host

This directive specifies the location of the PEM-encoded X.509 certificate file for this server.

6. SSLCertificateKeyFile file

Context: Global, virtual host

This directive specifies the location of the PEM-encoded private key file for this server, corresponding to the certificate configured with the SSLCertificateFile directive.

7. SSLCertificateChainFile file

Context: Global, virtual host

This directive specifies the location of a file containing the PEM-encoded certificates making up the certification path of the server. You can use the directive to assist clients in verifying the server's certificate when the server's certificate is not directly signed by an authority that the client recognizes.

Certificates in the chain are assumed to be valid for client authentication as well, when client authentication (SSLVerifyClient) is used.

8. SSLCACertificateFile file

Context: Global, virtual host

This directive specifies the location of a file containing the concatenation of the certificates for certification authorities (CAs) used for client authentication.

9. SSLCARevocationFile file

Context: Global, virtual host

This directive specifies the location of a file containing the concatenation of the certificate revocation lists of CAs used for client authentication.

10. SSLVerifyClient level

Context: Global, virtual host, directory, .htaccess

This directive configures the authentication of clients to the server. (Note that this is not normally needed for e-commerce applications, but has use in other applications.)

Values for level are listed and described in TABLE C-5.


Level	Description
`none`	No client certificate is required
`optional`	Client may present a valid certificate
`require`	Client must present a valid certificate
`optional_no_ca`	Client may present a certificate, but it need not be valid

Typically either none or require is used. The default is none.

11. SSLVerifyDepth depth

Context: Global, virtual host, directory, .htaccess

This directive specifies the maximum certificate chain depth that the server will allow for client certificates. A value of 0 means that only self-signed certificates are eligible, whereas a value of 1 means that client certificates must be signed by a CA known directly to the server (through the SSLCACertificateFile). Larger values permit delegation of the CA.

12. SSLLog filename

Context: Global, virtual host

This directive specifies a log file where SSL-specific information will be logged. If not specified (default), then no SSL-specific information will be logged.

13. SSLLogLevel level

Context: Global, virtual host

This directive specifies the verbosity of the information logged in the SSL log file. Values for level are listed and described in TABLE C-6.


Value	Description
`none`	no logging, but error messages are still sent to the standard Apache error log
`warn`	Include warning messages
`info`	Include information messages
`trace`	Include trace messages
`debug`	Include debugging messages

14. SSLOptions [+-] option

Context: Global, virtual host, directory, .htaccess

This directive configures SSL runtime options on a per-directory basis. Options can be added to the current configuration by prefixing them with a plus sign (+), or removed using a minus sign (-). If multiple options could apply to a directory, the most restrictive option is used; the options are not merged.

Options are listed and described in TABLE C-7.


Options	Description
`StdEnvVars`	Standard set of SSL-related CGI/SSI environment variables are created--there is a performance penalty for this.
`ExportCertData`	Causes the `SSL_SERVER_CERT`, `SSL_CLIENT_CERT` and `SSL_CLIENT_CERT_CHAIN`n (n = 0, 1, ...) environment variables to be exported. These variables contain PEM-encoded certificates for the client and server.
`FakeBasicAuth`	Distinguished Name (DN) of the client certificate is translated into an HTTP Basic Authentication Username, and is "faked" to have authentication. This allows the use of standard Apache access control mechanisms with SSL client authentication without prompting the user for a password. Entries for these users in the Apache password files must use the encrypted password `xxj31ZMTZzkVA`, which is just an encrypted form (`crypt`(3c)) of the word "password."
`StrictRequire`	Forces a forbidden access due to `SSLRequireSSL` to be denied, even in the presence of other directives, such as `Satisfy` `Any`, which might override this.

15. SSLRequireSSL

Context: Directory, .htaccess

This directive forbids access in a given directory unless HTTPS is used. Use the directive to guard against misconfigurations that might otherwise leave a directory's contents available to unauthenticated and unencrypted accesses.