# CA Certificates

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.

{% hint style="info" %}
In production environments, we recommend that you use a custom CA certificate that your organization manages and has authorized for the external PKI.
{% endhint %}

### 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.

{% hint style="info" %}
In production environments, we recommend that you use a custom CA certificate that your organization manages and has authorized for the external PKI.
{% endhint %}

## Adding Custom CA Certificates

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

{% hint style="info" %}
All certificate and key files must be in PEM format.
{% endhint %}

### 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](https://docs.cybus.io/2-0-6/documentation/security/tls-certificates/ca-certificates/certificates-view).

<figure><img src="https://639096190-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FfDpOJO2upcq5EpoSahvK%2Fuploads%2Fgit-blob-7971bda8360048240e6ba180628fbe68f702b473%2Fadd-certificates.png?alt=media" alt=""><figcaption></figcaption></figure>

3. 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.

{% tabs %}
{% tab title="Kubernetes" %}

#### Adding Custom CA Certificates via the Certs Volume (Kubernetes)

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

{% code lineNumbers="true" %}

```bash
cat ca-chain.pem >> cybus_ca.crt
```

{% endcode %}

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

{% code lineNumbers="true" %}

```bash
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
```

{% endcode %}

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

{% code lineNumbers="true" %}

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

{% endcode %}

4. [Restart Connectware](https://docs.cybus.io/2-0-6/documentation/installation-and-upgrades/restarting-connectware) to apply the changes.
   {% endtab %}

{% tab title="Docker" %}

#### Adding CA Certificates via the Certs Volume (Docker)

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

{% code lineNumbers="true" %}

```bash
cat ca-chain.pem >> cybus_ca.crt
```

{% endcode %}

2. Upload the modified `cybus_ca.crt` to Connectware:

{% code lineNumbers="true" %}

```bash
# 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
```

{% endcode %}

3. 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.

{% code lineNumbers="true" %}

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

{% endcode %}

4. [Restart Connectware](https://docs.cybus.io/2-0-6/documentation/installation-and-upgrades/restarting-connectware) to apply the changes.
   {% endtab %}
   {% endtabs %}

## 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](https://docs.cybus.io/2-0-6/documentation/security/tls-certificates/ca-certificates/certificates-view).
3. Click **Remove Certificate**.