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 4000 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 is 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/cryptov2/bin/apgetpass 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. These password files contain only 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. Do not use the default; 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:

TABLE C-1 SSL Protocols

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, this 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.

TABLE C-2 Available SSL Ciphers

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.

TABLE C-3 SSL Aliases

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.

TABLE C-4 Special Characters to Configure Cipher Preference

Character

Description

<none>

Adds cipher to list

!

Removes a cipher from the list entirely--it cannot be added again

+

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

TABLE C-5 SSL Verify Client Levels

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.

TABLE C-6 SSL Log Level Values

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.

TABLE C-7 Available SSL Options

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_CHAINn (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.