Certificates

Certificate based authentication

Bondix can leverage certificates to authenticate incoming tunnel connections. Instead of manually creating tunnels for each device on the server, you create a root certificate that you then sign client certificates with. When an incoming tunnel connects with a certificate, the server creates an ad-hoc tunnel configuration automatically, making it scalable.

If you want to know how to configure the SSL certificate on your own Bondix server, please visit this page: Server Certificates

Prerequisites

Setting up certificates

Bondix server ships with some scripts located in the .ssl subdirectory:

cd /opt/bondix/server/ssl
./create-server-cert.sh

This script creates a self signed server certificate, and a root certificate used for signing client certificates. It is automatically run after installation, but make sure that a `client-root.key´ and `client-root.crt` file exist within the .ssl subdirectory. Otherwise, run the script.

Tell Bondix Server to use client certificate authentication

In `/etc/saneserver.json`, look for the following line:

{"target": "server", "action": "add-https", "host": "0.0.0.0", "port": "443", "allowMonitor": true},

We'll add the parameter "rootCA": "client-root.key" so the JSON looks like this:

{"target": "server", "action": "add-https", "host": "0.0.0.0", "port": "443", "allowMonitor": true, "rootCA": "client-root.key"},

If you have multiple listeners or use separate ports for webinterface and incoming tunnels, you'll have to add the parameter in the according command. Adding client certificate authentication where incoming tunnels are prohibited has no effect.

Finally, restart the server via `systemctl restart bondix`

Create a client certificate

In the ssl server subfolder, we'll also find a script to create a client certificate:

 cd /opt/bondix/server/ssl
 ./create-client-cert.sh <TunnelName>

Please make sure that the script is run within the same directory, and that `<TunnelName>` is unique for each instance. The script will output a certificate/key pair (<TunnelName>.crt & <TunnelName>.key) in ./ssl/clients/.

Set up client for certificate authentication

Client Certificate Auth configuration

Finally, on the client, set 'Config Mode' to '"Certificate"' and insert your certificate/key pair. Finally, don't forget to set up the server's hostname or IP address. Once connected, the tunnel should show up on the server with no further configuration required.

Setting up Tunnel Limits

When using certificate authentication, you might encounter that too many clients are connected to your server, even when working with multiple endpoints. To address the issue, you can set up Bondix server to facilitate a soft limit of total active tunnels connected. For this, you will have to add the following configuration command to `/etc/saneserver.json`:

{"target": "tunnel", "action": "set-tunnel-limit", "maxTunnel": 100, "gracePeriod": 30}

• 'maxTunnel' specifies the maximum number of active tunnels. Tunnels connecting after this limit has exceeded will be asked to connect to a different server. This server must be either configured as secondary server on the client, or you must use a hostname with multiple IP records.
• 'gracePeriod' specifies a time period in seconds in which a tunnel that was previously rejected can reconnect without being declined. This soft limit ensures that a tunnel can always connect, even if no resources are available on secondary servers either.

Auto-Remove stale certificate tunnels

Depending on your usecase scenario you might run into the issue that you have much fluctuation in tunnels that use certificate authentication. By default, these tunnels are not deleted automatically. This behavior can be enabled by adding this command to `/etc/saneserver.json`:

{"target": "tunnel", "action": "set-tunnel-autoremove", "enabled": true, "timeout": 600}

• 'timeout' specifies the lifetime of a certificate based tunnel on the server in seconds.