CA Certificates

Learn about Certificate authority (CA) configuration and trust management.

Certificate Authority (CA) certificates are used to validate other certificates. Connectware uses a certificate system that includes both built-in Cybus CA certificates and any custom CA certificates you choose to add. These certificates establish trust relationships between different systems and verify the authenticity of connections.

CA Certificate Types

Default Cybus CA Certificates

Connectware includes built-in Cybus CA certificates, which are pre-installed and maintained by the system. These form the foundation of Connectware’s security infrastructure.

• The externally used CA certificate chain is maintained in the cybus_ca.crt certificate bundle file within the certs volume.

• The internally used CA certificate chain is maintained in the shared_yearly_ca.crt certificate bundle file within the certs volume.

• Which CA an agent requires depends on the hostname through which it connects to Connectware. For example, through the Connectware ingress, or directly to the Control Streaming Server (NATS) through the internal network. The combined CA bundle cybus_combined_ca.crt (in the certs volume) contains both external (cybus_ca.crt) and internal (shared_yearly_ca.crt) chains and can be used by Connectware agents for TLS chain verification. This simplifies the configuration.

By default, Connectware automatically manages the certificates.

• The internal certificate (shared_yearly_ca.crt) is handled by the system and requires no user action.

• The external certificate (cybus_ca.crt) is intended for user customization. You can extend the default server certificate (signed by the external CA) with additional hostnames, or replace the entire external PKI (cybus_ca.crt, cybus_server.crt, cybus_server.key, cybus_client.crt, cybus_client.key) with one managed by your organization. For example, by a central IT security team.

In production environments, we recommend that you use a custom CA certificate that your organization manages and has authorized for the external PKI.

Custom CA Certificates

Custom CA certificates are user-provided Certificate Authority certificates that you add to the system to establish trust for secure communications with external systems. These certificates allow Connectware to authenticate and verify devices, clients, or servers that use certificates signed by a non-default or custom CA, rather than relying solely on the built-in Cybus CA.

By adding custom CA certificates, you can integrate your own Public Key Infrastructure (PKI) to ensure that Connectware can recognize and trust certificates issued by external CAs. This increases security and flexibility for specific industry use cases or corporate policies.

In production environments, we recommend that you use a custom CA certificate that your organization manages and has authorized for the external PKI.

Adding Custom CA Certificates

You can add custom CA certificates to Connectware via the Admin UI and via the certs volume.

All certificate and key files must be in PEM format.

Adding Custom CA Certificates via the Admin UI

You can add your custom CA certificate to Connectware via the Admin UI. When you add a certificate, a backup of the current certificates is created. The last backup will be overwritten with the newly created backup and then the uploaded certificate will be appended to the current certificate chain.

1. Select User > User Certificates.

2. In the Certificates view, click Add Certificate. See Certificates View.

1. In the file browser, select your certificate file and click Open.

Adding Custom CA Certificates via the Certs Volume

You can add your custom CA certificate to Connectware via the certs volume.

Prerequisites

The following files are available:

• The cybus_ca.crt from Connectware.

• The ca-chain.pem CA certificate chain in PEM format.

• Connectware has a planned maintenance downtime.

Kubernetes

Adding Custom CA Certificates via the Certs Volume (Kubernetes)

1. Append your ca-chain.crt to cybus_ca.crt:

cat ca-chain.pem >> cybus_ca.crt

1. Upload the modified cybus_ca.crt to Connectware. Make sure to specify the Connectware namespace:

namespace=<namespace>
pod=$(kubectl -n ${namespace} get pod -o name -lapp.kubernetes.io/name=auth-server | head -1 | sed 's/pod\///g');
kubectl -n ${namespace} cp -c auth-server cybus_ca.crt $pod:/connectware_certs/cybus_ca.crt
kubectl -n ${namespace} exec $pod -c auth-server -- chown -R root:root /connectware_certs
kubectl -n ${namespace} exec $pod -c auth-server -- chmod 664 /connectware_certs/cybus_ca.crt

1. Restart the system-control-server deployment to rebuild and synchronize the combined CA bundle (cybus_combined_ca.crt):

kubectl -n [connectware-namespace] rollout restart deployment system-control-server

1. Restart Connectware to apply the changes.

Docker

Adding CA Certificates via the Certs Volume (Docker)

1. Append your ca-chain.crt to cybus_ca.crt:

cat ca-chain.pem >> cybus_ca.crt

1. Upload the modified cybus_ca.crt to Connectware:

# Get the container ID or name using labels
container_id=$(docker container ls -q -f "label=io.cybus.connectware=core" -f "label=com.docker.compose.service=auth-server")

# Copy the modified CA certificate
docker cp cybus_ca.crt $container_id:/connectware_certs/cybus_ca.crt

# Set proper ownership and permissions
docker exec $container_id chown -R root:root /connectware_certs
docker exec $container_id chmod 664 /connectware_certs/cybus_ca.crt

1. Restart the system-control-server deployment to rebuild and synchronize the combined CA bundle (cybus_combined_ca.crt). Ensure that only a single Connectware instance is running.

docker restart $(docker container ls -f "label=io.cybus.connectware=core" -f "label=com.docker.compose.service=system-control-server" -q)

1. Restart Connectware to apply the changes.

Removing CA Certificates

You must have at least two CA certificates in Connectware to remove a certificate, as one certificate must always remain in the system.

1. Select User > User Certificates.

2. In the certificates list, click the arrow next to the certificate that you want to remove. See Certificates View.

3. Click Remove Certificate.