Certificate Manager

Overview

The Certificate Manager is a centralized system for generating, managing, and deploying X.509 certificates across ControlBird. It lets you build a complete internal public key infrastructure (PKI), import externally-signed certificates, and attach certificates to protocol endpoints so connections are encrypted and authenticated. Protocols including OPC UA, MQTT, DNP3, and HTTP/HTTPS consume certificates through TLS-enabled endpoints.

All certificate material is persisted and versioned. You manage individual certificate records along with global settings such as expiry warnings and the revocation list.

Capabilities

• Generate self-signed and CA-signed certificates
• Generate Certificate Signing Requests (CSRs) for submission to external CAs
• Import externally-signed certificates and auto-extract their metadata
• Renew certificates while retaining the existing configuration
• Revoke certificates and automatically regenerate the CRL
• Encrypt private keys with PKCS#8 using a passphrase
• Build and traverse multi-level certificate chains
• Define Subject Alternative Names (DNS and IP)
• Automatically monitor certificate expiry status
• Integrate with ACME / Let's Encrypt using HTTP-01 and DNS-01 challenges
• Auto-renew ACME certificates before they expire

Certificate Types

Every certificate has a type that determines its role and key usages. You choose the type when the certificate is created, and it is inferred automatically when importing an existing certificate.

Key Algorithms

The key algorithm selects the key pair used when generating a certificate. RSA offers broad compatibility; ECDSA produces smaller keys and faster handshakes.

Certificate Status

The Certificate Manager tracks each certificate's lifecycle through its status. A periodic expiry check updates statuses automatically based on the validity end date and the configured expiry warning window (default 30 days). The UI renders each status as a color-coded badge.

Certificate Records

Each certificate record stores both the certificate material (the certificate, its private key, and the CA chain) and the configuration used to generate it: the subject details, key algorithm, validity period, Subject Alternative Names, and a reference to the signing CA. When you import a certificate, the subject, issuer, serial number, validity dates, and fingerprint are parsed from the certificate automatically. Records are persisted and versioned.

Global Settings

Certificate operations such as generation, renewal, and revocation remain highly available. Alongside individual certificates, you configure global settings: the expiry warning window (default 30 days) determines how far ahead a certificate is marked Expiring, and the revocation-list refresh interval (default 24 hours) controls how often the CRL is regenerated.

Building a Certificate Authority

A typical deployment starts with a self-signed root, optionally adds one or more intermediates, then issues leaf certificates (Server, Client, or Peer) signed by an intermediate or the root.

1. Open the Certificate Manager app and select the CA Hierarchy tab.
2. Click New Certificate, set Certificate Type to RootCA, leave Signing CA empty, and submit to generate a self-signed root.
3. Create an IntermediateCA the same way, but select the root as its Signing CA.
4. Issue Server, Client, or Peer certificates from their respective tabs, selecting the intermediate (or root) as the Signing CA.

Example: root CA

Name:                 Root CA
Certificate Type:     RootCA
Key Algorithm:        RSA-4096
Common Name (CN):     ControlBird Root
Organization (O):     My Org
Validity (days):      3650
Signing CA:           (none)

Example: server certificate with SANs

Name:                 server.local
Certificate Type:     Server
Common Name (CN):     server.local
Subject Alt Names:    DNS:server.local,DNS:server.example.com,IP:192.168.1.10
Signing CA:           Intermediate CA
Validity (days):      365

Importing and Signing Externally

The Certificate Manager is not limited to internally generated certificates. You can bring in certificates issued elsewhere, or have an external CA sign keys generated by ControlBird.

Import an externally-signed certificate

Create a new certificate and paste the PEM certificate data into the certificate data field. On submit, the subject, issuer, serial number, and validity dates are extracted automatically, the certificate type is inferred from the certificate's extensions, and it is marked Valid.

Generate a CSR for an external CA

When creating a certificate, choose the CSR generation mode instead of direct generation. Configure the subject fields and submit to produce a Certificate Signing Request. Send the CSR to your external CA, and when the signed certificate is returned, import it to complete the process.

Attaching Certificates to Protocol Endpoints

Protocol endpoints enable TLS through two settings: a TlsEnabled toggle and a reference to a certificate. When TLS is enabled, the endpoint secures its connection using the referenced certificate.

For example, to secure a DNP3 master, open the Dnp3MasterTlsEndpoint, enable TLS, and point its certificate reference at a Server certificate. The endpoint then uses that certificate for the connection. See the device configuration walkthrough for the endpoint setup flow.

Web Server

The Web Server tab sets how the node serves its web UI, its API and the command-line tools. A self-hosted node starts with HTTP on port 3000 and HTTPS on port 3443, using a self-signed certificate it creates on first start. On a ControlBird Cloud node the tab is read-only: ControlBird Cloud provides HTTPS for it.

The tab shows:

• the current mode, the addresses the node listens on, and the addresses it is open at;
• the certificate it serves, its expiry date and, for the node's own certificate, when it was last replaced;
• Download node certificate, which saves the served certificate as a PEM file. Install it as a trusted certificate on computers and phones to stop browser warnings, and give it to the command-line tools as CB_NODE_CA_FILE.

Modes

In every mode the node still serves plain HTTP on port 3000 to requests from its own machine, so services and tools running on the node keep working.

Changing the mode or certificate

Changing these settings needs the security.web-server permission, which the Owner, Administrator and Playing With Fire roles include. Other users see the tab read-only.

1. Choose a Mode.
2. For a mode that serves HTTPS, choose a Certificate from your Server certificates, or select Import certificate... to add one.
3. Select Apply.

The change takes effect within seconds without restarting the node, and applies entirely or not at all. If it moves the page you are using to another address, for example from http:// to HTTPS only, the tab warns you first and asks you to confirm with Apply and move. Afterwards, sign in again at the new address, turn push notifications off and on again on each phone, and update the redirect addresses registered with your OpenID Connect providers.

Importing a certificate

Import certificate... takes a name, the certificate in PEM form, an optional chain of intermediate certificates, the private key in PEM form, and a passphrase if the key is encrypted. The import is refused, with the reason, when the private key does not belong to the certificate, when the certificate has expired, or when it is not valid for server authentication. The imported certificate appears on the Server tab and can be chosen on the Web Server tab.

Renewal and replacement

• The node's own certificate is valid for 825 days. About 30 days before it expires, the node replaces it with a new certificate and a new key, keeping the same names. The Web Server tab then shows a notice, and the low-severity Web Server Certificate Rotated alarm stays raised for 7 days. Download the new certificate and install it wherever the old one was trusted.
• A certificate you imported or chose is never replaced by the node. When you renew it in Certificate Manager, or ACME renews it, the web server starts serving the renewed certificate without a restart.
• The node's own certificate names localhost, the loopback addresses, and the machine's host name and addresses. Add the names and addresses clients use with the CB_PUBLIC_HOSTNAME environment variable, a comma-separated list, when the node first starts. See HTTPS and the Node Certificate.
• If the chosen certificate cannot be loaded when the node starts, or port 3443 is in use, the node serves plain HTTP only and raises the Web Server Certificate alarm until a certificate is applied successfully.

Renewal and Revocation

Renew

Select a certificate and click Regenerate to extend its validity with a new expiry date. The existing configuration (subject, key algorithm, and signing CA) is retained. Renewal always generates a fresh key and certificate; there is no key-rotation mode that reuses the existing key.

Revoke

Select a certificate and click Revoke. The status becomes Revoked, the revocation time is recorded, and the CRL is regenerated automatically.

Certificate Revocation List (CRL)

The Revocation List tab manages the CRL. It is regenerated on the configurable refresh interval (default 24 hours) and immediately whenever a certificate is revoked. Adjust the interval in the global settings, or click Regenerate to force an immediate update. The tab shows the time of the most recent run.

Encrypted Private Keys

When a passphrase is set, the private key is encrypted as PKCS#8 using a passphrase-derived key. The Certificate Manager handles encryption and decryption for you.

ACME / Let's Encrypt

The Certificate Manager can obtain publicly trusted certificates through ACME. You configure ACME per certificate, supplying the account email, directory URL, and challenge type. The Certificate Manager handles the ACME account and order lifecycle for you.

Both HTTP-01 and DNS-01 challenge types are supported. With ACME and auto-renew enabled, a certificate enters auto-renewal once it falls within its configured renewal window before expiration; the service then runs the order, verify, and finalize steps automatically.

Limitations

• Protocol endpoints do not yet fully support PKCS#8 encrypted private keys.
• ACME DNS-01 challenges require manual DNS TXT record updates; auto-renewal only covers HTTP-01.
• Subject Alternative Names must be entered manually as a prefixed, comma-separated string.
• Revoked certificates cannot be renewed.
• There is no automatic CRL cleanup; old revoked certificates remain listed.
• There is no key-rotation mode, renewal always generates a new key and certificate.
• External PKI integration is limited to internal generation, CSR submission, and ACME.
• Deleting a certificate does not check for active endpoint references first.