Secure communication with server ================================ The default setup is to use HTTPS between the client and the server and to use the frontend-webserver as a *proxy* for the backend (with a proper URL prefix). The backend uses a separate port (default is port 8081). Clients/frontend may alternatively be configured to use the backend *directly*. If using the backend directly from a different computer and if especially if communication is crossing subnets, the communication should always be secured. From version 3.0, HTTPS will be mandatory for login-sessions to other servers than localhost. .. note:: From version 3.0, the frontend webserver is configured with a `self-signed `_ certificate. This means that the webbrowser will not allow access before you explicitly make an exception for the certificate in question. If you plan to have many users, consider getting a certificate signed by a known CA. One example is *Lets Encrypt* which is free and easy to use. Setting up the server with HTTPS -------------------------------- The frontend webserver is by default set up with HTTPS and a certficate. It is also possible to configure the backend to use HTTPS. The frontend webserver is configured in `/etc/apache2/sites-enabled/aprs_ssl.conf` and you may edit the path to the certificate and the private key there if necessary. A certificate can be imported into a keystore to make it available for the backend-server as well. Getting the certificate ^^^^^^^^^^^^^^^^^^^^^^^ A `certificate `_ is mainly a public key (cryptographic key) along with information about the identity of the owner of the certificate, that is signed by some `certification authority `_ (CA). If we know and trust the CA (and its public key) we can check the digital signature of the certificate and we can trust that this certificate is authentic. When opening a connection to a HTTPS site a certificate of the server is first presented. If the client-browser accepts it, we can use the public key of the server to securely establish an encrypted communication channel and authenticate the server (that it is really what it says it is). Web-browsers have installed a set of CA-certificates that it trusts. It is also possible for users to add or remove certificates and trust. We need a certificate for our *aprsd* server and there are mainly four ways to do it. Scripts are available to install it in the `Java keystore `_ format to be used by *aprsd*. **Alternative 0**: **This is the default setting in Polaric Server 3.0 and later.** A `self-signed `_ certicate is generated by the package *ssl-cert* when installing the server. This certificate can be used by *Polaric Aprsd*, but clients browsers need to be told explicitly that this certificate is ok to use (make an exception from the general rule not to trust unverified certificates). The frontend (Polaric Webapp2) is also configured to use this certificate for secure connections. Client web-browsers should use HTTPS. To configure *aprsd* to use this certificate use this command (as root):: polaric-importcert-snakeoil **Alternative 1**: If the server runs on some domain (for example `mydomain.org`) and machine as a frontend server which already have a certificate. We can use it for the *aprsd* as well. If this certificate is automatically installed by using a service like `Lets Encrypt `_ and *certbot*, a certificate is placed at a certain location: You may check if the directory `/etc/letsencrypt/live/` exists. To make it available for *aprsd* run the following command as root (assume that `mydomain.org` is the domain of your frontend server and the certificate):: polaric-importcert-letsencrypt mydomain.org **Alternative 2** A certificate can also be created *manually*, either `self-signed `_ or signed by a CA (typically by generating a CSR, sending it to a CA for signing), you can configure the frontend-server to used and optionally import it into the keystore. How to generate CSRs etc. is outside the scope of this document. Assume that you have the certificate and that it is stored in a file cert.pem and the private key is stored in a file privkey.pem it can be importted this way (make sure the private key is not password-protected and that the domain name of the certificate matches the real domain of your webserver):: polaric-importcert cert.pem privkey.pem The scripts used here will install the certificate along with its private key in a keystore file available to *aprsd*. It will also generate and install the password for the keystore in the `server.ini` config file. Activating HTTPS mode in aprsd ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ When the certificate is imported, you can activate HTTPS mode by editing `/etc/polaric-aprsd/server.ini` and make sure that the ``httpserver.secure`` property is set to *true* and restart the server. Configuring the client-side ^^^^^^^^^^^^^^^^^^^^^^^^^^^ You can tell the clients to use the backend directly with HTTPS mode by enabling the following lines and disabling AJAXPREFIX and WSPREFIX (comment out) in `/etc/polaric-webapp2/config.js`:: PORT(8081) SECURE(true)