mod_ssl¶
The mod_ssl module adds HTTPS support. After enabling mod_ssl the logon window and other secure pages will be served using HTTPS.
SSL support can be switched on for each site separately. Virtual hosting of sites via HTTPS is possible. In order to get working SSL connections you need to enable a module providing SSL certificates. Module mod_ssl_self_signed is an example of such a module. The role of this module is secure dispatching.
Configuration¶
There are four configurarion options. They can be set in the admin. All four are optional and will be either set or replaced with a default when not set.
mod_ssl.is_secure
When this configuration is set to something else then
0
orfalse
then mod_ssl will ensure that sessions started while using HTTPS are secured and only valid on HTTPS.The autologon cookie will also be HTTPS only (if set from a HTTPS connection).
Besides that mod_ssl will ensure that, after using HTTPS, all following pages will be served using HTTPS. Unless specifically specified otherwise in the dispatch rules.
This is done by adding the
{ssl, keep}
option to all dispatch rules that do not have anssl
option already.mod_ssl.is_ssl
- Force all dispatch rules to use
{ssl, true}
, unless specified otherwise. Use this in combination withmod_ssl.is_secure
to ensure serving a site over HTTPS. mod_ssl.is_permanent
- When set to
true
it makes http to HTTPS protocol redirects for dispatch rules which use{ssl, true}
to be permanent redirects. The default setting isfalse
which will make redirects temporary redirects.
Serving a page via SSL¶
The dispatch rule argument ssl
defines if a page will be
served over HTTPS or HTTP.
There are three variations:
{ssl, any}
- Keep the same protocol as before, don‘t switch beteen HTTP and HTTPS. This used for lib and image files.
{ssl, true}
- Force a switch to HTTPS. When accessing the page using http then the page will be reloaded using HTTPS. This is useful for logon, logoff and other authentication or secure pages.
{ssl, false}
- Force a switch to HTTP. When accessing the page using HTTPS then the page will be reloaded using HTTP. This is useful for pages with embedded video or other non HTTPS content.
When the ssl
option is not specified then it defaults to {ssl, false}
. Unless
the mod_ssl.is_secure
option is set, then default is {ssl, any}
.
Example of a page delivered using HTTPS:
{logon, ["logon"], controller_logon, [{ssl, true}]}
And of a dispatch rule that should keep the protocol, in this case the lib controller used for serving css, javascript and other static lib files:
{lib, ["lib",'*'], controller_lib, [{ssl, any}]}
Notifications¶
When you want to implement your own certificate handling you have to implement a notification handler which returns the certificates to the underlying HTTPS server. This can be needed when you have a site with different aliases, or when you can want to implement automated certificate handling for a specific certificate authority.
ssl_options{server_name=ServerName}
- Sent back the certificate, key or other ssl options.
ServerName
is the name of the server found in the SSL handshake. Expects a proplist with Erlangssl:ssloptions()
. This proplist will override the default ssl options for this connection. For more information about the possible properties see Erlang SSL. Whenundefined
is returned the SSL handshake will fail and the connection wil be dropped.