mTLS in HSYCO 4.1: only clients with a valid certificate can connect

From HSYCO 4.1 the server can require a certificate from every client that connects. With Mutual TLS (mTLS) it is no longer only the client that checks the server’s identity: HSYCO checks the client’s as well, and a connection without a valid certificate is refused before the login page even appears.

For building automation integrators, this means access can be limited to specific devices, such as a maintenance technician’s tablet, the control room PC or an external system using the HTTP interface, on top of the usual username and password.

Where it is enabled

mTLS is enabled separately for two interfaces, with two configuration parameters:

• RequireMTLSWebUI, for the web interface;
• RequireMTLSHttpRaw, for the HTTP raw interface.

Certificates managed in HSYCO

Client certificates are managed from the Manager settings, with no external tools:

• generation of self-signed certificates (2048-bit RSA, SHA-256 signature), exported as a PKCS#12 file with an optional password, to be installed on the client device;
• import of existing certificates in PKCS#12, PEM or DER format. You can also import a certificate authority’s certificate: HSYCO then accepts any client whose certificate that CA has signed;
• revocation: delete the certificate from the list of trusted clients, and that client’s later connections are refused.

The list of trusted certificates is kept in a separate file, clients.keys. HSYCO reloads it automatically when it changes, without a restart, and synchronises it between Master and Slave in high-availability installations.

Validity and expiry

On every connection HSYCO checks that the certificate is trusted and within its validity period. An expired certificate is refused just like an unknown one, and every refusal is logged with the client’s IP address.

Each certificate’s expiry date is shown in the Manager. Renewal is not automatic, so a certificate must be replaced before it expires. The check relies on the server clock, which should therefore be kept synchronised via NTP.

Before you enable it

• With mTLS enabled on the web interface, if the only administrator certificate expires or is deleted, web access is lost. It can only be recovered from the file system, via SSH or the console, by setting RequireMTLSWebUI=false in hsyco.ini.
• clients.keys holds the only copy of the trusted client list and must be included in backups.

The full configuration is described in the documentation: Client certificates (mTLS).