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.

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.