> ## Documentation Index > Fetch the complete documentation index at: https://docs.coreflux.org/llms.txt > Use this file to discover all available pages before exploring further. # Certificates > Manage the broker's TLS server certificate, Root CA, and mTLS client trust store from the Coreflux HUB > [!NOTE] > > The Certificates tab is new in HUB 2.12 and needs broker 2.22. On an older broker the tab reports **Unsupported broker version**. ## 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](/hub/system/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 ![Coreflux HUB Broker Settings window on the Certificates tab. Server certificate card for mqtt.acme-factory.com and Root CA card for Acme Industrial Root CA, both Valid, each with issuer, algorithm, expiry, SHA-256 fingerprint, and Download and Replace buttons, above the trust store settings](https://mintcdn.com/coreflux/3mb0wROxLOvLuS2Q/images/system/certificates/certificates-broker-light.png?fit=max\&auto=format\&n=3mb0wROxLOvLuS2Q\&q=85\&s=c45fad78631e2e77f62f44f229b1d20b) 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 (`.bak-`), 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 ![Client certificates list with Total 7, Valid 4, Expiring 2, and Expired 1, the drop zone, search and filters, and rows for energy-meter-gw, historian-01, line1-plc and line2-plc.acme-factory.com, mes-connector, packaging-robot-02, scada-gateway, and the revoked hmi-panel-03](https://mintcdn.com/coreflux/3mb0wROxLOvLuS2Q/images/system/certificates/certificates-clients-light.png?fit=max\&auto=format\&n=3mb0wROxLOvLuS2Q\&q=85\&s=ed47833d5e1634e66a39228ee7fcff2d) ### Trust store settings | Setting | Broker field | What it does | | - | - | - | | **Storage path** | `ClientCertificateSourcePath` | Folder of trusted client certificates. Empty means the default: `/var/lib/coreflux/certs` on Linux and macOS, `C:\ProgramData\Coreflux\certs` on Windows. The hint under the field says whether the broker can read and write it. | | **Expiry alert** | `CertificateExpiryThresholdDays` | Days before expiry at which a certificate counts as **Expiring**. 1 to 365, default 30. Applies to client certificates, the server certificate, and the Root CA. | | **Require client certificates** | `ClientCertificationValidation` | TLS clients must present a trusted certificate. Takes full effect on the TLS listeners after a broker restart. | | **Validate chain to the Root CA** | `CheckCertificateChainValidation` | Also checks that a client certificate chains to the Root CA. Off means only the trusted list is checked. Takes effect immediately. | 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. > [!TIP] > > In Docker, keep the trust store in a `certs` subfolder of the project volume, for example `/etc/project/certs`, so certificates persist with the rest of the broker data. 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. > [!WARNING] > > Uploading a certificate trusts it. A client presenting it can complete mTLS as soon as the upload finishes. * **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. ![Certificate detail panel for line2-plc.acme-factory.com marked Expiring soon, showing its file path, issuer, algorithm, serial, not before, not after, SANs, and SHA-256, with Download and Revoke buttons](https://mintcdn.com/coreflux/3mb0wROxLOvLuS2Q/images/system/certificates/certificate-detail-light.png?fit=max\&auto=format\&n=3mb0wROxLOvLuS2Q\&q=85\&s=3c2559eb17e4982f8db00561abeca4a6) **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 ![HUB status bar with a red dot and 7 Certificates; the popover lists 4 valid, 2 expiring, and 1 expired, with mes-connector expired, line2-plc and historian-01 expiring, and an Open Certificates link](https://mintcdn.com/coreflux/3mb0wROxLOvLuS2Q/images/system/certificates/certificates-status-bar-light.png?fit=max\&auto=format\&n=3mb0wROxLOvLuS2Q\&q=85\&s=0598220ce2f9a68e8b66b932a9408251) 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`](/latest/mqtt-broker/sys-topics#syscorefluxcertificatessummary) topic. ## From MQTT The HUB uses the admin-only [`-brokerCertificates`](/latest/mqtt-broker/commands#broker-certificates) command. You can script the same operations over `$SYS/Coreflux/Command`. ## Next Steps > **[TLS and mTLS settings](/latest/mqtt-broker/configuration#mutual-tls-mtls)** > > Configure server certificates and client validation in the broker config. > **[System Configuration](/hub/system/configuration)** > > The other Broker Settings tabs. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.