ca setting guidance or auto detection when configuring the mosquitto bridge via tedge connect

[reubenmiller]

Is your feature improvement request related to a problem? Please describe.

Improve guidance to users for setting the correct c8y.root_cert_path path (e.g. either a file or directory) to ensure thin-edge.io is able to connect to the intended Cumulocity instance via HTTPS and MQTT.

The mosquitto settings which are created when running tedge connect c8y, the mosquitto ca setting is dependent on whether the c8y.root_cert_path is set to a directory or a file. The table shows how the tedge settings are converted to the following mosquitto settings:

tedge setting	value	mosquitto setting
c8y.root_cert_path	/etc/ssl/certs (directory)	bridge_capath
c8y.root_cert_path	/etc/ssl/certs/ca-certificates.crt (file)	bridge_cafile

However the problem arises when the default directory (/etc/ssl/certs) is used, and when it only contains a single file /etc/ss/certs/ca-certificates.crt with multiple certificates concatenated inside it, then mosquitto ignores the file entirely and the bridge connection will fail with the follow errors:

1691514337: OpenSSL Error: error:14090086:SSL routines:ssl3_get_server_certificate:certificate verify failed
1691514337: Socket error on client Cumulocity, disconnecting.

Diving into the mosquitto configuration manual, it clearly states that when using the bridge_capath setting, then the user must run the openssl command, openssl rehash <path to bridge_capath>, however this command ignores files which contain more than 1 cert, so again the user is left confused/overwhelmed about how to get the cloud connection working.

Below is the snippet from the mosquitto conf docs detailing about the rehash action.

bridge_capath is used to define the path to a directory containing the PEM encoded CA certificates that have signed the certificate for the remote broker. For bridge_capath to work correctly, the certificate files must have ".crt" as the file ending and you must run "openssl rehash " each time you add/remove a certificate.

Then finally after debugging the mosquitto logs and simple trial and error, the user might discover that using a ca file path works instead of a directory, and they update the setting in thin-edge using the following command:

sudo tedge config set c8y.root_cert_path /etc/ssl/certs/ca-certificates.crt

Describe the solution you'd like

The exact solution is unclear, however the solution should aim at reducing the amount of configuration for users that are not familiar with the ca settings, and nuances of different linux distributions.

But some solutions could include:

• improve documentation by adding some simple checks when to use the folder setting, and when to use a single file
• auto detect the sensible c8y.root_cert_path default setting based on the contents of the /etc/ssl/certs folder, e.g.
  • Use a default value of /etc/ssl/certs/ if the directory exists and contains more than 1 certificate
  • Use a default value of /etc/ssl/certs/ca-certifications if the file exists, and it is the only cert file in the /etc/ssl/certs directory

Describe alternatives you've considered

Additional context

[didier-wenzek]

The exact solution is unclear

I would go with better documentation, because auto-detection might be an end-less pursuit. You provided a clear statement of the issue. The doc can be simpler and focus on guidance. Say:

1. c8y.root_cert_path is the path to the file containing the c8y signing certificate (possibly along other root certificates).
2. If you are not sure which file contains the certificate for Cumulocity among all the files of a directory such as /etc/ssl/certs, then c8y.root_cert_path can be set to this directory, letting the system figure out which one to use. There are two caveats though. Be sure to run openssl rehash if you add a certificate. And be sure the C8Y signing certificate is not grouped with others in a single file as such files are ignored by mosquitto. If this is the case, you have to set c8y.root_cert_path pointing to the file and not the directory.