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 for all network interfaces. You can immediately test SSL access to documents by using the https:// scheme. For example, to access the home page using SSL, use this URL in your browser:

https://localhost/

Self-Signed Certificate

Appweb is shipped with a self-signed certificate to identify the web server.

SECURITY WARNING: This certificate is suitable for testing purposes only and your browser will issue a 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.

The relevant SSL directives are:

• SSLCertificateFile
• SSLCertificateKeyFile
• SSLCipherSuite
• ListenSecure

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

• SSLVerifyClient
• SSLVerifyIssuer
• SSLCACertificateFile
• SSLCACertificatePath

SSL Configuration Example

Consider the default Appweb SSL configuration in the appweb.conf configuration file:

SSLCertificateFile "self.crt"
SSLCertificateKeyFile "self.key"
ListenSecure 443

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

The ListenSecure directive instructs Appweb to process requests from all interfaces on port 443 using current SSL configuration.

The SSLCertificateFile directive specifies the server certificate to use and the SSLCertificateKeyFile directive specifies the server private key for signing.

SECURITY WARNING: You must obtain or generate a SSL certificate 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.

SSL Providers

Appweb employs an open architecture SSL Provider interface so that customers can select or create an SSL provider for their needs.

Appweb provides multiple SSL implementations:

• MbedTLS -- designed for embedded use. This is the default SSL stack and is pre-integrated with Appweb. It is configured and enabled by default.
• OpenSSL -- designed for enterprise use. See http://www.openssl.org.

The binary installation will use the MbedTLS provider by default.

To build with OpenSSL, please consult the projects/README.md file included with the source code.