Certificates

​

Why Use Certificates?

A broker that serves MQTTS or WSS presents a server certificate, and with mutual TLS (mTLS) it also checks the certificates clients present. The Certificates tab lets an administrator see and change all of that from the HUB: which certificate the broker presents, which Root CA it validates client chains against, which client certificates it trusts, and which are about to expire. You don’t need shell access to the broker host.

​

When to Use It

• Renew the server certificate before it expires, without restarting the broker.
• Onboard a device by trusting its client certificate.
• Cut off a device by revoking its certificate.
• Watch expiry across the server certificate, the Root CA, and every trusted client certificate.

​

Open the Certificates Tab

Open System Config (Broker Settings) and select Certificates, the tab right after General. You need administrator rights on the broker (AllowedSystemConfiguration, shown as Full Access in User Management). The tab has two parts: Broker, the identity the broker presents on its TLS ports, and Clients, the trust store used for mTLS.

​

Broker: Server Certificate and Root CA

Each card shows the certificate’s common name, status, issuer, algorithm, expiry date with the days left, and SHA-256 fingerprint.

• Download saves the public certificate as PEM (broker-server.crt or broker-root-ca.crt). Private keys are never downloaded.
• Replace uploads a new certificate.

​

Replace the server certificate

Upload a .pfx/.p12 with its passphrase, a PEM that embeds the private key, or a certificate plus a separate key file (and the key passphrase if it is encrypted). The key must be RSA or ECDSA. The broker checks that the key matches the certificate before it writes anything.

• ServerCertificatePath already set and TLS running: the broker keeps a timestamped backup of the old files (<file>.bak-<yyyyMMddHHmmss>), writes the new ones in the same format, and swaps them in. New TLS connections use the new certificate right away. Existing connections stay up. No restart.
• No server certificate configured yet: the broker writes server.pem to a broker/ folder under the storage path, sets ServerCertificatePath to it, and asks you to restart the broker to turn TLS on.

​

Replace the Root CA

Upload the CA certificate (.crt, .pem, or .cer) used to validate client certificate chains. The broker keeps a timestamped backup of the old file and applies the new CA to chain validation immediately. If the uploaded certificate is not marked as a CA, the broker still installs it and warns you.

​

Clients: the mTLS Trust Store

​

Trust store settings

The broker refuses a storage path that:

• is not absolute,
• is the filesystem root or inside a system folder (for example /etc, /usr, /proc, /root, or the Windows and Program Files folders), unless it is a subfolder of CONFIG_PATH (see below),
• is the CONFIG_PATH folder itself, which holds the broker config and secrets. The error suggests a certs subfolder instead,
• is the folder that holds the broker’s server certificate or key,
• on Linux and macOS, sits outside the allowed roots: /var/lib, /opt, /srv, /data, /mnt, /media, /home, /Users, temp folders, the default path’s parent, and the folders in COREFLUX_DATA_PATH and CONFIG_PATH. Add roots with COREFLUX_CERT_STORAGE_ROOTS (a list separated by : on Linux and macOS).

A subfolder of CONFIG_PATH is allowed even when CONFIG_PATH sits under a system folder. In Docker, where CONFIG_PATH is /etc/project, /etc/project/certs works. This exception doesn’t apply when CONFIG_PATH is a system folder itself: with CONFIG_PATH=/etc, paths under /etc stay refused. Symbolic links are resolved first, so the check applies to the real folder: a link that points into a system folder, or out of CONFIG_PATH, is refused. If the folder doesn’t exist, the broker creates it. When the path can’t be used (missing, unreadable, or read-only), the tab shows a red banner with the reason. On a non-default path, Reset to default puts the default back. A read-only path still lists certificates, but upload and revoke are disabled.

​

Upload client certificates

Click Upload or drop files on the drop zone. Accepted types are .crt, .pem, .cer, .der, .p12, and .pfx, up to 10 MB each. Private keys and CSRs are refused: .key and .csr files, and PEM files that contain only a key or a CSR. The error reads “Private keys and CSRs are not stored in the client trust store; use Replace on the broker certificate to install a server key.” To install a server key, use Replace on the broker certificate.

• PKCS#12 (.p12, .pfx): the HUB asks for the passphrase. The broker stores only the certificates, as a .pem, and discards the private key and the passphrase.
• PEM with an embedded private key: the key is discarded and only the certificate is stored. The detail view says so.
• Duplicates: a certificate already in the store is refused. A revoked certificate can’t be uploaded again. Restore it from the revoked/ folder on the host instead.

The broker reloads the trust store after each upload. Every change is written to the audit log.

​

Find a certificate

The list shows each certificate’s common name, file name, status, algorithm, and expiry. Search by common name, issuer, or file name, and filter by All, Valid, Expiring, or Expired. Select a row to open its detail: issuer, algorithm, serial, validity dates, SANs, SHA-256 fingerprint, and the file path. Download saves certificate files only. Files holding a private key, and symbolic links, can’t be downloaded.

​

Revoke a certificate

Choose Revoke from the row menu or the detail view, then confirm. The broker moves the file to revoked/ under the storage path and rejects new connections that present it immediately. The revocation is audit-logged. Revoked certificates stay in the list with a Revoked badge. Certificates in the folder set by ClientCertificateRevocationListPath are also treated as revoked.

​

Status Bar Alerts

The HUB status bar always shows a certificate count, for example 7 Certificates, with a colored dot: red when a certificate is expired or invalid (unreadable or not yet valid) or the storage path is unavailable, yellow when one is expiring, and green when everything is valid. The server certificate and the Root CA count too. Hover the indicator to see the counts per status and the certificates that need attention. Click it, or Open Certificates in the popover, to open the Certificates tab filtered to the matching certificates. The indicator reads the retained $SYS/Coreflux/Certificates/Summary topic.

​

From MQTT

The HUB uses the admin-only -brokerCertificates command. You can script the same operations over $SYS/Coreflux/Command.

​

Next Steps