Configuring SSL

AppWeb supports the Secure Sockets Layer (SSL) protocol for authenticating systems and encrypting data. Use of this protocol enables secure data transmission to and from clients in a standards-based manner.

This following document provides a step by step for configuring SSL in AppWeb. If you are unfamiliar with SSL, please read the SSL Overview first.

SSL Quick Start

To assist you in testing SSL quickly, AppWeb, once installed, will support SSL on port 4443 for all network interfaces. It is configured by default to use the OpenSSL SSL provider. However you can change this and use other SSL implementations such as the embedded PeerSec MatrixSSL stack.

AppWeb is shipped with a self-signed certificate which is used to identify the server. This certificate is suitable for testing purposes only and your browser will issue warning when you access the server. For production use, you should obtain your own service certificate from signing authorities such as Verisign.

SSL Configuration Directives

AppWeb uses several configuration file directives to control how SSL will operate. These directives may be included in the Default Server section or they may be included in any Virtual Host section. When included in a Virtual Host section, the SSL directives will only apply for for that virtual host.

The relevant SSL directives are:

There are some additional directives that are necessary should you wish to have AppWeb verify client certificates. These directives are:

SSL Configuration Example

Consider the default AppWeb SSL configuration:


    DocumentRoot "$SERVER_ROOT/web"
    SSLEngine on
    SSLCipherSuite ALL:!ADH:!EXPORT56:RC4+RSA:+HIGH:+ \
     MEDIUM:+LOW:+SSLv2:+EXP:+eNULL
    SSLProtocol ALL -SSLV2
    SSLCertificateFile "$SERVER_ROOT/server.crt"
    SSLCertificateKeyFile "$SERVER_ROOT/server.key.pem"

This set of directives in the AppWeb configuration file, appWeb.conf enables SSL on port 4443 for all network interfaces and uses the default self-signed certificate to identify the server.

The directive instructs AppWeb to process requests from all interfaces on port 4443 using this virtual host configuration.

The DocumentRoot "$SERVER_ROOT/web" locates web documents in the web subdirectory under the ServerRoot.

The SSLEngine directive enables SSL processing for this virtual host. Only requests that use SSL will be honored.

The SSLCipherSuite directive configures the underlying SSL provider to use the appropriate ciphers when negotiating the session with the client. See the SSLCipherSuite directive for details about how to create the cipher spec.

The SSLProtocol directive enables all SSL protocol version except for SSLv2 which is somewhat flawed.

The SSLCertificateFile directive specifies the server certificate to use.

The SSLCertificateKeyFile directive specifies the server private key to for signing.

SECURITY WARNING: You must regenerate the server certificate and server key before using this example in a production environment.

The server key file is a PEM encoded private key. You may supply either an encrypted private key or a decrypted private key. If you use an encrypted private key, the server will prompt you for a pass-phrase to decrypt the key when the server boots.

Generating Keys and Certificates

To generate a request file that you can send to a certificate issuing authority such as Verisign, use the following openssl command or equivalent command from your SSL provider:

openssl genrsa -des3 -out server.key 1024
openssl req -new -key server.key -out server.csr

This will generate a server key in the file server.key and will generate a certificate request in the file server.csr that you can send to the issuing authority. The issuing authority will generate a server certificate for your server and they will sign it with their private key. Subsequently, clients will be able to use the signing authorities public key to decrypt your server certificate and thus verify the identity of your server when negotiation a SSL session. When running these commands, you will be prompted to enter a pass-phrase password to decrypt the server private key. REMEMBER this password.

SECURITY WARNING: Safeguard the server.key private key jealously. If this falls into malicious hands, then your server identity may be highjacked by another site.

SSL Providers

AppWeb employs an open architecture SSL Provider interface so that customers can select the ideal SSL provider for their needs. Different SSL implementations excel in various ways. Some are compact, others are fast and some are extensive in their cipher support.

AppWeb current supports two SSL implementations

OpenSSL -- designed for enterprise use. See http://www.openssl.org.
PeerSec MatrixSSL -- designed for embedding. See http://www.peersec.com.