# Server Certificates

The server certificate ensure secure connections to Connectware and must be properly maintained to avoid security issues. Regular certificate updates are necessary following Let's Encrypt renewals through `certbot` or when deploying self-signed certificates in your environment.

Without proper certificate configuration, users may encounter browser security warnings when accessing the [Admin UI](https://docs.cybus.io/2-0-6/getting-started/admin-ui). To establish trusted communication within enterprise networks, Connectware requires server certificates that are trusted and validated by your organization's Public Key Infrastructure (PKI).

## Generating the Server Certificate

The following procedure can be performed on any system with OpenSSL installed.

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

1. To define the server certificate configuration, create or modify an `openssl.cnf` file with the following parameters. Customize the values to match your specific environment:

{% code lineNumbers="true" %}

```bash
[alt_names]
DNS.1 = localhost
DNS.2 = server.cybus.io
DNS.3 = *.cybus.io
DNS.4 = *.dev.cybus.io
DNS.5 = a048ffe65867e4a02b615faa014e3cdb-1179064562.cybus.io
DNS.6 = *.eu-central.cybus.io
IP.1 = 127.0.0.1
IP.2 = 192.168.178.110
IP.3 = 172.17.0.1

[req]
# Options for the `req` tool (`man req`).
default_bits        = 2048
distinguished_name  = req_distinguished_name
string_mask         = utf8only
default_md          = sha256
prompt              = no

# Extension to add when the -x509 option is used.
x509_extensions     = server_cert
extensions          = server_cert
req_extensions      = server_cert

[req_distinguished_name]
countryName              = DE
stateOrProvinceName      = HH
0.organizationName       = Acme Test 002
organizationalUnitName   = Shopfloor
commonName               = Cybus Connectware Server 1

[server_cert]
# Extensions for server certificates (`man x509v3_config`).
basicConstraints = CA:FALSE
nsCertType = server
nsComment = "OpenSSL Generated Server Certificate"
subjectKeyIdentifier = hash
keyUsage = critical, digitalSignature, keyEncipherment
extendedKeyUsage = serverAuth
subjectAltName=@alt_names
```

{% endcode %}

2. To generate a new private key, run the following command:

{% code lineNumbers="true" %}

```bash
openssl genrsa -out cybus_server.key 2048
```

{% endcode %}

3. Store the `cybus_server.key` file in a secure location.
4. Generate a Certificate Sign Request (CSR) using your private key:

{% code lineNumbers="true" %}

```bash
openssl req -new -key cybus_server.key -out cybus_server.csr -config openssl.cnf
```

{% endcode %}

5. Submit the CSR to your IT department or certificate authority.
6. After receiving the signed server certificate, store the `cybus_server.crt` file in a secure location.

## Installing the Server Certificate

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

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

### Installing the Server Certificate (Kubernetes)

1. Obtain the corporate certificate (.crt) and key (.key) files from your IT department.
2. Copy these files to Connectware's certificate volume using the following commands:

   Replace `[path-to/your-key-file.key]` and `[path-to/your-cert-file.crt]` with the absolute paths to your key and certificate files.

   Replace `[namespace]` with the Kubernetes namespace that hosts your Connectware installation.

{% code lineNumbers="true" %}

```bash
kubectl -n [namespace] cp [path-to/your-key-file.key] $(kubectl -n [namespace] get pod -lapp=system-control-server -o name | sed -e 's/pod\///g'):/connectware_certs/cybus_server.key
kubectl -n [namespace] cp [path-to/your-cert-file.crt] $(kubectl -n [namespace] get pod -lapp=system-control-server -o name | sed -e 's/pod\///g'):/connectware_certs/cybus_server.crt
```

{% endcode %}

3. After updating the certificates, [restart Connectware](https://docs.cybus.io/2-0-6/documentation/installation-and-upgrades/restarting-connectware) to apply the changes.

{% hint style="warning" %}
You must also add the CA certificate to Connectware to establish the trust chain. See [CA Certificates](https://docs.cybus.io/2-0-6/documentation/security/tls-certificates/ca-certificates).
{% endhint %}
{% endtab %}

{% tab title="Docker" %}

### Installing the Server Certificate (Docker)

1. Obtain the corporate certificate (.crt) and key (.key) files from your IT department.
2. Copy these files to Connectware's certificate volume using the following commands:

   Replace `[path-to/your-key-file.key]` and `[path-to/your-cert-file.crt]` with the absolute paths to your key and certificate files.

{% 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 key and certificate files
docker cp [path-to/your-key-file.key] $container_id:/connectware_certs/cybus_server.key
docker cp [path-to/your-cert-file.crt] $container_id:/connectware_certs/cybus_server.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_server.key
docker exec $container_id chmod 664 /connectware_certs/cybus_server.crt
```

{% endcode %}

3. After updating the certificates, [restart Connectware](https://docs.cybus.io/2-0-6/documentation/installation-and-upgrades/restarting-connectware) to apply the changes.

{% hint style="warning" %}
You must also add the CA certificate to Connectware to establish the trust chain. See [CA Certificates](https://docs.cybus.io/2-0-6/documentation/security/tls-certificates/ca-certificates).
{% endhint %}
{% endtab %}
{% endtabs %}