7.2 Creating an HTTPS server

The SWI-Prolog infrastructure provides two main ways to launch an HTTPS server:

• Using library(http/thread_httpd), the server is started in HTTPS mode by adding an option ssl/1 to http_server/2. The argument of ssl/1 is an option list that is passed as the third argument to ssl_context/3.
• Using library(http/http_unix_daemon), an HTTPS server is started by using the command line argument --https.

Two items are typically specified as, respectively, options or additional command line arguments:

• server certificate. This identifies the server and acts as a public key for the encryption.
• private key of the server, which must be kept secret. The key may be protected by a password. If this is the case, the server must provide the password by means of the password option, the pem_password_hook callback or, in case of the Unix daemon, via the --pwfile or --password command line options.

Here is an example that uses the self-signed demo certificates distributed with the SSL package. As is typical for publicly accessible HTTPS servers, this version does not require a certificate from the client:

:- use_module(library(http/thread_httpd)).
:- use_module(library(http/http_ssl_plugin)).

https_server(Port, Options) :-
        http_server(reply,
                    [ port(Port),
                      ssl([ certificate_file('etc/server/server-cert.pem'),
                            key_file('etc/server/server-key.pem'),
                            password("apenoot1")
                          ])
                    | Options
                    ]).

There are two hooks that let you extend HTTPS servers with custom definitions:

• http:ssl_server_create_hook(+SSL0, -SSL, +Options): This extensible predicate is called exactly once, after creating an HTTPS server with Options. If this predicate succeeds, SSL is the context that is used for negotiating all new connections. Otherwise, SSL0 is used, which is the context that was created with the given options.
• http:ssl_server_open_client_hook(+SSL0, -SSL, +Options): This predicate is called before each connection that the server negotiates with a client. If this predicate succeeds, SSL is the context that is used for the new connection. Otherwise, SSL0 is used, which is the context that was created when launching the server.

Important use cases of these hooks are running dual-stack RSA/ECDSA servers, updating certificates while the server keeps running, and tweaking SSL parameters for connections. Use ssl_set_options/3 to create and configure copies of existing contexts in these hooks.

The example file https.pl also provides a server that does require the client to show its certificate. This provides an additional level of security, often used to allow a selected set of clients to perform sensitive tasks.

Note that a single Prolog program can call http_server/2 with different parameters to provide services at several security levels as described below. These servers can either use their own dispatching or commonly use http_dispatch/1 and check the port property of the request to verify they are called with the desired security level. If a service is approached at a too low level of security, the handler can deny access or use HTTP redirect to send the client to to appropriate interface.

• A plain HTTP server at port 80. This can either be used for non-sensitive information or for redirecting to a more secure service.
• An HTTPS server at port 443 for sensitive services to the general public.
• An HTTPS server that demands for a client key on a selected port for administrative tasks or sensitive machine-to-machine communication.