diff --git a/param-docs/parameter-pages/MQTT/CACert.md b/param-docs/parameter-pages/MQTT/CACert.md index 4c0a9214..da9f4067 100644 --- a/param-docs/parameter-pages/MQTT/CACert.md +++ b/param-docs/parameter-pages/MQTT/CACert.md @@ -1,25 +1,24 @@ # Parameter `CACert` Default Value: `""` -Example: `/config/certs/RootCA.pem`. +Example: `/config/certs/RootCA.crt`. !!! Warning This is an **Expert Parameter**! Only change it if you understand what it does! Path to the CA certificate file. -This is part of the configuration to enable TLS for MQTT. +This is part of the configuration to enable TLS 1.2 for MQTT.
+ The CA Certificate is used by the client to validate the broker is who it claims to be. It allows the client to authenticate the server, which is the first part of the MTLS handshake. Usually there is a common RootCA certificate for the MQTT broker. More information is available [here](https://jomjol.github.io/AI-on-the-edge-device-docs/MQTT-API/#mqtt-tls). +For more information on how to create your own certificate, see: [mosquitto.org](https://mosquitto.org/man/mosquitto-tls-7.html) or [emqx.com](https://www.emqx.com/en/blog/emqx-server-ssl-tls-secure-connection-configuration-guide). + !!! Note This also means that you might have to change the protocol and port in [uri](https://jomjol.github.io/AI-on-the-edge-device-docs/Parameters/#parameter-uri) to `mqtts://example.com:8883`! -!!! Note - Only TLS 1.2 is supported! - -!!! Note Only Certificates up to 4096 Bit are supported! diff --git a/param-docs/parameter-pages/MQTT/ClientCert.md b/param-docs/parameter-pages/MQTT/ClientCert.md index 9902efd4..1cccd48a 100644 --- a/param-docs/parameter-pages/MQTT/ClientCert.md +++ b/param-docs/parameter-pages/MQTT/ClientCert.md @@ -1,23 +1,23 @@ # Parameter `ClientCert` Default Value: `""` -Example: `/config/certs/client.pem.crt`. +Example: `/config/certs/client.crt`. !!! Warning This is an **Expert Parameter**! Only change it if you understand what it does! Path to the Client Certificate file. -This is part of the configuration to enable TLS for MQTT. +This is part of the configuration to enable TLS 1.2 for MQTT.
+ The Client Certificate is used by the client to prove its identity to the server, in conjunction with the Client Key. It is the second part of the MTLS handshake. Usually there is a one pair of Client Certificate/Key for each client that connects to the MQTT broker. More information is available [here](https://jomjol.github.io/AI-on-the-edge-device-docs/MQTT-API/#mqtt-tls). -!!! Note - If set, `ClientKey` must be set too - This also means that you might have to change the protocol and port in [uri](https://jomjol.github.io/AI-on-the-edge-device-docs/Parameters/#parameter-uri) to `mqtts://example.com:8883`! +For more information on how to create your own certificate, see: [mosquitto.org](https://mosquitto.org/man/mosquitto-tls-7.html) or [emqx.com](https://www.emqx.com/en/blog/emqx-server-ssl-tls-secure-connection-configuration-guide). !!! Note - Only TLS 1.2 is supported! + If set, `ClientKey` must be set too. + This also means that you might have to change the protocol and port in [uri](https://jomjol.github.io/AI-on-the-edge-device-docs/Parameters/#parameter-uri) to `mqtts://example.com:8883`! diff --git a/param-docs/parameter-pages/MQTT/ClientKey.md b/param-docs/parameter-pages/MQTT/ClientKey.md index b976ba19..3479476b 100644 --- a/param-docs/parameter-pages/MQTT/ClientKey.md +++ b/param-docs/parameter-pages/MQTT/ClientKey.md @@ -1,22 +1,22 @@ # Parameter `ClientKey` Default Value: `""` -Example: `/config/certs/client.pem.key`. +Example: `/config/certs/client.key`. !!! Warning This is an **Expert Parameter**! Only change it if you understand what it does! Path to the Client Key file. -This is part of the configuration to enable TLS for MQTT. +This is part of the configuration to enable TLS 1.2 for MQTT.
+ The Client Key is used by the client to prove its identity to the server, in conjunction with the Client Certificate. It is the second part of the MTLS handshake. Usually there is a one pair of Client Certificate/Key for each client that connects to the MQTT broker -!!! Note - If set, `ClientCert` must be set too - This also means that you might have to change the protocol and port in [uri](https://jomjol.github.io/AI-on-the-edge-device-docs/Parameters/#parameter-uri) to `mqtts://example.com:8883`! +For more information on how to create your own certificate, see: [mosquitto.org](https://mosquitto.org/man/mosquitto-tls-7.html) or [emqx.com](https://www.emqx.com/en/blog/emqx-server-ssl-tls-secure-connection-configuration-guide). !!! Note - Only TLS 1.2 is supported! + If set, `ClientCert` must be set too. + This also means that you might have to change the protocol and port in [uri](https://jomjol.github.io/AI-on-the-edge-device-docs/Parameters/#parameter-uri) to `mqtts://example.com:8883`! diff --git a/param-docs/parameter-pages/MQTT/ValidateServerCert.md b/param-docs/parameter-pages/MQTT/ValidateServerCert.md index dc3ed9b3..0c71f411 100644 --- a/param-docs/parameter-pages/MQTT/ValidateServerCert.md +++ b/param-docs/parameter-pages/MQTT/ValidateServerCert.md @@ -5,15 +5,16 @@ Default Value: `true` !!! Warning This is an **Expert Parameter**! Only change it if you understand what it does! -Enable or disable the validation of the server certificate. +Enable or disable the validation of the server certificate CN field.
If `enabled (true)`, the certificate sent by the server is validated using the configured [Root CA Certificate file](https://jomjol.github.io/AI-on-the-edge-device-docs/Parameters/#parameter-cacert).
The server name in [uri](https://jomjol.github.io/AI-on-the-edge-device-docs/Parameters/#parameter-uri) is compared with the CN field of the server certificate.
-A connection will be only established if these match.
-It ensures the origin of the server. +A connection is only established if they agree. It ensures the origin of the server. -If `disabled (false)`, only the validity of the certificate (e.g. expiry) is checked, not the origin (CN field).
-If you use public brokers, make sure to set this parameter to "enabled", to avoid potential MITM-Attacks! +If `disabled (false)`, the ESP32 skipped any validation of server certificate CN field.
+This reduces the security of TLS and makes the *MQTT* client susceptible to MITM attacks. !!! Note This also means that you might have to change the protocol and port in to `mqtts://example.com:8883`! + + If you use public brokers, is recommended to set this parameter to "enabled (true)".