Embedthis Appweb 3.4.0
Home > Users Guide > SSL

Quick Nav

See Also

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 document provides step-by-step instructions for configuring SSL in Appweb. If you are unfamiliar with SSL, please read the SSL Overview first.

SSL Quick Start

The default binary installation of Appweb will support SSL on port 4443 for all network interfaces. You can immediately test SSL access to documents by using the https:// scheme and 4443 as the port. For example, to access the home page using SSL, use this URL in your browser:

https://127.0.0.1:4443/index.html

Self-Signed Certificate

Appweb is shipped with a self-signed certificate to identify the web 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 SSL and manage secure access to the server. These directives can be specified in the Default Server section or in a Virtual Host section. When included in a Virtual Host section, the SSL directives will only apply 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 in the appweb.conf configuration file:

<VirtualHost *:4443>
    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"
</VirtualHost>

This set of directives enables SSL on port 4443 for all network interfaces and uses the default supplied self-signed certificate to identify the server.

The <virtualHost *:4443> directive instructs Appweb to process requests from all interfaces on port 4443 using this virtual host configuration.

The DocumentRoot "$SERVER_ROOT/web" locates documents for this virtual host 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 and the SSLCertificateKeyFile directive specifies the server private key 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 negotiating 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 supports two SSL implementations:

The binary installation will use the OpenSSL SSL provider by default.

© Embedthis Software LLC, 2003-2012. All rights reserved. Embedthis, Ejscript and Appweb are trademarks of Embedthis Software LLC.