Configuring SSL

GoAhead 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 GoAhead. If you are unfamiliar with SSL, please read the SSL Overview first.

Except for the MbedTLS stack which is integrated, GoAhead includes only the interface to the SSL stack and not the SSL library itself. You need to build your required SSL stack and then configure GoAhead to use that SSL stack. See Building From Source for details on configuring GoAhead to use SSL.

SSL Quick Start

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

https://127.0.0.1

Self-Signed Certificate

GoAhead 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 a warning when you access the server. For production use, you should obtain your own service certificate from signing authorities such as Verisign.

Build-time SSL Configuration Directives

GoAhead uses several main.bit configuration directives to control SSL and manage secure access to the server.

The relevant SSL directives are:

• key — SSL public key
• certificate — SSL certificate
• ciphers — Cipher suite to use for openssl
• caFile — File of certificates if verifying client certificates
• caPath — Directory of certificates if verifying client certificates

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 hijacked by another site.

SSL Providers

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

The MbedTLS SSL stack and interface are included with GoAhead. Other SSL interfaces are installed using the Pak Package manager.

• MbedTLS — designed for embedded use. Integrated with GoAhead and enabled by default.
• OpenSSL — large and complete. Designed for enterprise use. See http://www.openssl.org.