HTTPS and certificates

The web console and the node API are served over HTTPS. Nodes receive their own keys, the configuration and the secrets they need (DICOMweb credentials, de-identification keys) this way, so the connection must be encrypted.

A certificate from your CA (recommended)

A certificate issued by a CA your browsers and nodes already trust needs no further setup on either side.

• Its subject or subject alternative names must include every name browsers and nodes use: the server’s DNS name, a load-balanced name for several central servers, and any alias.
• Windows: import it, with its private key, into the computer’s store (LocalMachine\My), and give its thumbprint to the installer (CERTTHUMBPRINT) or set CertificateThumbprint under HKLM\SOFTWARE\Routes\Central. Find thumbprints with Get-ChildItem Cert:\LocalMachine\My.
• Linux and containers: give the file: CertificatePath (PKCS#12, or PEM with CertificateKeyPath) and CertificatePassword if it has one.

Renewing a CA certificate: import the new one and update the thumbprint (or replace the file), then restart the service. Nodes trust it through the CA, so they need nothing.

The self-signed default

Without a certificate, the central service makes one for itself on first start, valid for five years, and serves HTTPS with it. Browsers warn about it until it is trusted; nodes trust it by its thumbprint, which Configuration › Node enrollment shows.

• Windows: it is kept in LocalMachine\My as Symmetricare Routes Central (self-signed). Give each node the thumbprint: CENTRALTHUMBPRINT when installing, or CentralCertificateThumbprints under HKLM\SOFTWARE\Routes\Node.
• Linux and containers: it is kept in the data folder (https-self-signed.pfx). With CertificateExportPath set, the central service also writes its public part to that folder, and nodes given the file (CentralCertificatePath) trust it directly, and follow it when it changes. The Docker compose file does this.

The self-signed certificate replaces itself, with nothing for you to do:

1. 90 days before it ends, the central service makes its successor and tells every connected node to trust it. Nodes hear it in their next heartbeat, over the connection they already trust, and remember it across restarts.
2. 30 days before it ends, the central service starts serving the successor, without a restart.

Configuration › Node enrollment shows the successor’s thumbprint while both exist, and its install command gives nodes both. Only a node that was offline for the whole 60 days misses it: give it the new thumbprint (CentralCertificateThumbprints, ; separated) when it comes back.

Plain HTTP

The central service refuses to serve plain HTTP on addresses other machines can reach, unless told to:

• Behind a reverse proxy or load balancer that terminates TLS, set HttpsMode to Http (HTTPSMODE=Http when installing), and give nodes and browsers the proxy’s https:// address.
• On the same machine only (http://localhost:5080), plain HTTP is always allowed, for testing.

Nodes warn in their log when they reach the central service over plain HTTP.

Changing from HTTP to HTTPS later

Set CertificateThumbprint (or HttpsMode to SelfSigned) under HKLM\SOFTWARE\Routes\Central, restart the service, then give each node the https:// address in CentralUrl (and, for a self-signed certificate, its thumbprint) under HKLM\SOFTWARE\Routes\Node, and restart the nodes.

Browsers and Windows sign-in

Browsers send Windows sign-in automatically to intranet sites. If users are asked for a password, add the console’s address to the Local Intranet zone (Internet Options › Security, or Group Policy).