Certificates: Difference between revisions

From Bondix Wiki
(REworked)
m (formatting)
 
(2 intermediate revisions by the same user not shown)
Line 1: Line 1:
[[Category:Server]]
[[Category:Server]]


=Certificate based authentication=
= 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.
Bondix offers the capability to authenticate incoming tunnel connections using certificates. This method eliminates the need for manual tunnel creation for each device on the server. By creating a root certificate and signing client certificates with it, the server can automatically generate ad-hoc tunnel configurations for incoming connections, enhancing scalability.


If you want to know how to configure the SSL certificate on your own Bondix server, please visit this page: [[Server_Certificates_with_LetsEncrypt|Server Certificates]]
For guidance on configuring the SSL certificate on your Bondix server, please refer to: [[Server_Certificates_with_LetsEncrypt|Server Certificates]].
 
== Prerequisites ==
 
=== Setting Up Certificates ===
The Bondix server includes scripts within the ./ssl subdirectory for certificate setup:


==Prerequisites==
===Setting up certificates===
Bondix server ships with some scripts located in the .ssl subdirectory:
  cd /opt/bondix/server/ssl
  cd /opt/bondix/server/ssl
  ./create-server-cert.sh
  ./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.
This script generates a self-signed server certificate and a root certificate for client certificate signing. It is executed automatically post-installation. Ensure the presence of <code>client-root.key</code> and <code>client-root.crt</code> in the ./ssl subdirectory; if absent, rerun the script.


===Tell Bondix Server to use client certificate authentication===
Apply this parameter where necessary, considering multiple listeners or separate ports for different services. Note that adding this authentication method has no effect where incoming tunnels are not allowed. Restart the server with <code>systemctl restart bondix</code> to apply changes.
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:
=== Generating a Client Certificate ===
  {"target": "server", "action": "add-https", "host": "0.0.0.0", "port": "443", "allowMonitor": true, "rootCA": "client-root.key"},
Generate client certificates using a script located in the ssl server subfolder:
  cd /opt/bondix/server/ssl
./create-client-cert.sh <TunnelName>


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.
Ensure the script is executed in the intended directory and that <TunnelName> is distinct for each certificate. The script outputs a certificate and key pair in <code>./ssl/clients/</code>.


Finally, restart the server via `systemctl restart bondix`
=== Configuring the Client for Certificate Authentication ===
[[File:Client Certificate Config.png|thumb|Client Certificate Auth configuration]]
On the client side, select 'Certificate' as the 'Config Mode' and input the generated certificate/key pair. Additionally, configure the server's hostname or IP address. The tunnel will then appear on the server without requiring further setup.


===Create a client certificate===
= Additional Options =
In the ssl server subfolder, we'll also find a script to create a client certificate:
== Setting Up Tunnel Limits ==
  cd /opt/bondix/server/ssl
To manage the number of clients connected to the server when using certificate authentication, introduce a soft limit on the total active tunnels with the following configuration in <code>/etc/saneserver.json</code>:
  ./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/.
{"target": "tunnel", "action": "set-tunnel-limit", "maxTunnel": 100, "gracePeriod": 30},


===Set up client for certificate authentication===
* '''maxTunnel''' determines the maximum active tunnels. Exceeding this limit prompts tunnels to connect to an alternate server, configured either as a secondary server on the client or through a hostname with multiple IP records.
[[File:Client Certificate Config.png|thumb|Client Certificate Auth configuration]]
* '''gracePeriod''' is the duration in seconds allowing a previously rejected tunnel to reconnect without denial, ensuring connectivity even when resources on secondary servers are unavailable.
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 =
== Auto-Removing Stale Certificate Tunnels ==
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`:
To address fluctuation in tunnels utilizing certificate authentication, enable automatic tunnel removal with the following addition 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.
{"target": "tunnel", "action": "set-tunnel-autoremove", "enabled": true, "timeout": 600}
* '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 =
* '''timeout''' sets the lifespan of a certificate-based tunnel on the server in seconds, facilitating the management of active 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.
After making changes to <code>/etc/saneserver.json</code> , the service must be restarted via <code>systemctl restart bondix</code>

Latest revision as of 23:15, 7 February 2024


Certificate-Based Authentication

Bondix offers the capability to authenticate incoming tunnel connections using certificates. This method eliminates the need for manual tunnel creation for each device on the server. By creating a root certificate and signing client certificates with it, the server can automatically generate ad-hoc tunnel configurations for incoming connections, enhancing scalability.

For guidance on configuring the SSL certificate on your Bondix server, please refer to: Server Certificates.

Prerequisites

Setting Up Certificates

The Bondix server includes scripts within the ./ssl subdirectory for certificate setup: 

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

This script generates a self-signed server certificate and a root certificate for client certificate signing. It is executed automatically post-installation. Ensure the presence of client-root.key and client-root.crt in the ./ssl subdirectory; if absent, rerun the script.

Apply this parameter where necessary, considering multiple listeners or separate ports for different services. Note that adding this authentication method has no effect where incoming tunnels are not allowed. Restart the server with systemctl restart bondix to apply changes.

Generating a Client Certificate

Generate client certificates using a script located in the ssl server subfolder: 

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

Ensure the script is executed in the intended directory and that <TunnelName> is distinct for each certificate. The script outputs a certificate and key pair in ./ssl/clients/.

Configuring the Client for Certificate Authentication

Client Certificate Auth configuration

On the client side, select 'Certificate' as the 'Config Mode' and input the generated certificate/key pair. Additionally, configure the server's hostname or IP address. The tunnel will then appear on the server without requiring further setup.

Additional Options

Setting Up Tunnel Limits

To manage the number of clients connected to the server when using certificate authentication, introduce a soft limit on the total active tunnels with the following configuration in /etc/saneserver.json: 

{"target": "tunnel", "action": "set-tunnel-limit", "maxTunnel": 100, "gracePeriod": 30},
  • maxTunnel determines the maximum active tunnels. Exceeding this limit prompts tunnels to connect to an alternate server, configured either as a secondary server on the client or through a hostname with multiple IP records.
  • gracePeriod is the duration in seconds allowing a previously rejected tunnel to reconnect without denial, ensuring connectivity even when resources on secondary servers are unavailable.

Auto-Removing Stale Certificate Tunnels

To address fluctuation in tunnels utilizing certificate authentication, enable automatic tunnel removal with the following addition to /etc/saneserver.json: 

{"target": "tunnel", "action": "set-tunnel-autoremove", "enabled": true, "timeout": 600}
  • timeout sets the lifespan of a certificate-based tunnel on the server in seconds, facilitating the management of active tunnels.

After making changes to /etc/saneserver.json , the service must be restarted via systemctl restart bondix

Retrieved from "https://wiki.bondix.dev/index.php?title=Certificates&oldid=647"