From 8e5cb45941a78b57c41132e604eb8a0b6b03e711 Mon Sep 17 00:00:00 2001 From: Panos Kalogeropoulos Date: Sun, 21 Sep 2025 16:27:08 +0200 Subject: [PATCH 1/4] Update documentation with warning and more information about keystore passwords and how to change them. --- docs/user-guide/agents-protocols/mqtt.md | 9 ++++++++- .../user-guide/agents-protocols/mqtt.md | 17 ++++++++++++----- 2 files changed, 20 insertions(+), 6 deletions(-) diff --git a/docs/user-guide/agents-protocols/mqtt.md b/docs/user-guide/agents-protocols/mqtt.md index a383098..66dc2c8 100644 --- a/docs/user-guide/agents-protocols/mqtt.md +++ b/docs/user-guide/agents-protocols/mqtt.md @@ -14,6 +14,8 @@ OpenRemote also has an [MQTT Broker](../manager-apis.md#mqtt-api-mqtt-broker) (o ## Connecting to an MQTT broker using (m)TLS, AWS IoT Core + + AWS IoT Core provides the option to authenticate clients to the MQTT broker using X.509 Client Certificates. To do so, we will need to add the X.509 client certificates assigned to the Thing we have created to OpenRemote's realm-specific KeyStores. Below is a tutorial of how that can be done; @@ -26,11 +28,16 @@ They are all provided after accessing that thing's dashboard and creating a new Download the Device Certificate and activate it, download the private key file, and the Amazon Trust Services endpoint RSA 2048 bit key. -The password of everything keystore-related is `OR_ADMIN_PASSWORD`, for when it is requested. +:::warning +The password of the keystore and the password of each keypair within the keystore should be the same, and it should be set to `OR_KEYSTORE_PASSWORD`. Otherwise, you may see errors like `Get Key failed: Given final block not properly padded`. If you do, make sure you change the passwords to be the same. You can find a more detailed explanation in [this GitHub issue](https://github.com/openremote/openremote/issues/2093). +::: + +The password of everything keystore-related is `OR_KEYSTORE_PASSWORD`, for when it is requested. If it is not set as an environment variable before starting OpenRemote for the first time, it will default to ``. If you want to change the password later, you will need to change it in both the keystore and the truststore, as well as the passwords of each keypair within the keystore and truststore, and make sure to set `OR_KEYSTORE_PASSWORD` as that password. Make sure that OpenRemote has been started at least once before proceeding, so that the required keystore files are created automatically. If you have a pre-existing keystore file, make sure to provide the file's location using `OR_SSL_CLIENT_KEYSTORE_FILE`, `OR_SSL_CLIENT_TRUSTSTORE_FILE`, and `OR_SSL_CLIENT_KEYSTORE_PASSWORD` or `OR_SSL_CLIENT_TRUSTSTORE_PASSWORD` for their passwords. + After doing so, we need to: - Combine the certificate and Private Key into a PKCS#12 keypair file, so that it can be easily imported into the KeyStore: ```bash diff --git a/versioned_docs/version-1.8.0/user-guide/agents-protocols/mqtt.md b/versioned_docs/version-1.8.0/user-guide/agents-protocols/mqtt.md index a383098..c73af44 100644 --- a/versioned_docs/version-1.8.0/user-guide/agents-protocols/mqtt.md +++ b/versioned_docs/version-1.8.0/user-guide/agents-protocols/mqtt.md @@ -7,13 +7,15 @@ sidebar_position: 8 There is an MQTT Agent (Client) in OpenRemote that you can use to connect to an external MQTT Broker. First use the MQTT Agent to establish the connection to the broker. Then create an asset with attribute(s) of the Value Type that matches the incoming/outgoing data, and give those attributes the configuration item 'Agent Link'. In this agent link select -your MQTT Agent and add the parameter Publish Topic or Subscription Topic. We have no extensive documentation yet, -and recommend to [check our forum](https://forum.openremote.io/t/mqtt-agents-publish-subscription/985). +your MQTT Agent and add the parameter Publish Topic or Subscription Topic. We have no extensive documentation yet, +and recommend to [check our forum](https://forum.openremote.io/t/mqtt-agents-publish-subscription/985). OpenRemote also has an [MQTT Broker](../manager-apis.md#mqtt-api-mqtt-broker) (or MQTT API). ## Connecting to an MQTT broker using (m)TLS, AWS IoT Core + + AWS IoT Core provides the option to authenticate clients to the MQTT broker using X.509 Client Certificates. To do so, we will need to add the X.509 client certificates assigned to the Thing we have created to OpenRemote's realm-specific KeyStores. Below is a tutorial of how that can be done; @@ -26,17 +28,22 @@ They are all provided after accessing that thing's dashboard and creating a new Download the Device Certificate and activate it, download the private key file, and the Amazon Trust Services endpoint RSA 2048 bit key. -The password of everything keystore-related is `OR_ADMIN_PASSWORD`, for when it is requested. +:::warning +The password of the keystore and the password of each keypair within the keystore should be the same, and it should be set to `OR_KEYSTORE_PASSWORD`. Otherwise, you may see errors like `Get Key failed: Given final block not properly padded`. If you do, make sure you change the passwords to be the same. You can find a more detailed explanation in [this GitHub issue](https://github.com/openremote/openremote/issues/2093). +::: + +The password of everything keystore-related is `OR_KEYSTORE_PASSWORD`, for when it is requested. If it is not set as an environment variable before starting OpenRemote for the first time, it will default to ``. If you want to change the password later, you will need to change it in both the keystore and the truststore, as well as the passwords of each keypair within the keystore and truststore, and make sure to set `OR_KEYSTORE_PASSWORD` as that password. Make sure that OpenRemote has been started at least once before proceeding, so that the required keystore files are created automatically. If you have a pre-existing keystore file, make sure to provide the file's location using `OR_SSL_CLIENT_KEYSTORE_FILE`, `OR_SSL_CLIENT_TRUSTSTORE_FILE`, and `OR_SSL_CLIENT_KEYSTORE_PASSWORD` or `OR_SSL_CLIENT_TRUSTSTORE_PASSWORD` for their passwords. + After doing so, we need to: - Combine the certificate and Private Key into a PKCS#12 keypair file, so that it can be easily imported into the KeyStore: ```bash openssl pkcs12 -export -in OpenRemoteAWSCertificate.pem.crt -inkey OpenRemoteAWSPrivate.key -out OpenRemoteAWSKeyPair.p12 -name openremoteagent ``` -- Import the keypair into the existing keystore. +- Import the keypair into the existing keystore. **Warning! the alias you use here will be used to distinguish between keypairs to be used in different agents.** For this to work, you will need to use the following format; `.`. For example, we will use `master.OpenRemoteAwsIoTClientCertificate`. So we will be creating the agent in the master realm, and the certificate alias we will provide is `OpenRemoteAwsIoTClientCertificate`. ```shell @@ -54,7 +61,7 @@ Now, we are ready to start OpenRemote again, and create a new MQTT Agent. In that agent, ensure that you have set: - The correct host and port (AWS IoT Core MQTT broker is set to `8883`) - Secure mode turned on -- Set the certificate alias to the alias we set above, without the realm and the `.`: `OpenRemoteAwsIoTClientCertificate`. The alias is used to allow the MQTT agent to select the correct certificate to use for the authentication. +- Set the certificate alias to the alias we set above, without the realm and the `.`: `OpenRemoteAwsIoTClientCertificate`. The alias is used to allow the MQTT agent to select the correct certificate to use for the authentication. - Set the client ID, ensuring that it is allowed by the created Policy of the thing (Check AWS IoT Dashboard->``->Certificate->Policy to verify) The agent attempts to connect, and it successfully authenticates and connects to the MQTT broker, ready to pub/sub according to your needs. From d01646111e98147fed7972ea443cf172f6a938d8 Mon Sep 17 00:00:00 2001 From: Panos Kalogeropoulos Date: Sun, 28 Sep 2025 14:54:15 +0200 Subject: [PATCH 2/4] Update documentation with warning and more information about keystore passwords and how to change them. --- docs/user-guide/agents-protocols/mqtt.md | 4 +--- .../version-1.8.0/user-guide/agents-protocols/mqtt.md | 4 +--- 2 files changed, 2 insertions(+), 6 deletions(-) diff --git a/docs/user-guide/agents-protocols/mqtt.md b/docs/user-guide/agents-protocols/mqtt.md index 66dc2c8..7317e63 100644 --- a/docs/user-guide/agents-protocols/mqtt.md +++ b/docs/user-guide/agents-protocols/mqtt.md @@ -14,8 +14,6 @@ OpenRemote also has an [MQTT Broker](../manager-apis.md#mqtt-api-mqtt-broker) (o ## Connecting to an MQTT broker using (m)TLS, AWS IoT Core - - AWS IoT Core provides the option to authenticate clients to the MQTT broker using X.509 Client Certificates. To do so, we will need to add the X.509 client certificates assigned to the Thing we have created to OpenRemote's realm-specific KeyStores. Below is a tutorial of how that can be done; @@ -29,7 +27,7 @@ They are all provided after accessing that thing's dashboard and creating a new Download the Device Certificate and activate it, download the private key file, and the Amazon Trust Services endpoint RSA 2048 bit key. :::warning -The password of the keystore and the password of each keypair within the keystore should be the same, and it should be set to `OR_KEYSTORE_PASSWORD`. Otherwise, you may see errors like `Get Key failed: Given final block not properly padded`. If you do, make sure you change the passwords to be the same. You can find a more detailed explanation in [this GitHub issue](https://github.com/openremote/openremote/issues/2093). +The password of the keystore and the password of each keypair within the keystore should be the same, and it should be set to `OR_KEYSTORE_PASSWORD`. Otherwise, you may see errors like `Get Key failed: Given final block not properly padded`. You can find a more detailed explanation in [this GitHub issue](https://github.com/openremote/openremote/issues/2093). ::: The password of everything keystore-related is `OR_KEYSTORE_PASSWORD`, for when it is requested. If it is not set as an environment variable before starting OpenRemote for the first time, it will default to ``. If you want to change the password later, you will need to change it in both the keystore and the truststore, as well as the passwords of each keypair within the keystore and truststore, and make sure to set `OR_KEYSTORE_PASSWORD` as that password. diff --git a/versioned_docs/version-1.8.0/user-guide/agents-protocols/mqtt.md b/versioned_docs/version-1.8.0/user-guide/agents-protocols/mqtt.md index c73af44..b753bf2 100644 --- a/versioned_docs/version-1.8.0/user-guide/agents-protocols/mqtt.md +++ b/versioned_docs/version-1.8.0/user-guide/agents-protocols/mqtt.md @@ -14,8 +14,6 @@ OpenRemote also has an [MQTT Broker](../manager-apis.md#mqtt-api-mqtt-broker) (o ## Connecting to an MQTT broker using (m)TLS, AWS IoT Core - - AWS IoT Core provides the option to authenticate clients to the MQTT broker using X.509 Client Certificates. To do so, we will need to add the X.509 client certificates assigned to the Thing we have created to OpenRemote's realm-specific KeyStores. Below is a tutorial of how that can be done; @@ -29,7 +27,7 @@ They are all provided after accessing that thing's dashboard and creating a new Download the Device Certificate and activate it, download the private key file, and the Amazon Trust Services endpoint RSA 2048 bit key. :::warning -The password of the keystore and the password of each keypair within the keystore should be the same, and it should be set to `OR_KEYSTORE_PASSWORD`. Otherwise, you may see errors like `Get Key failed: Given final block not properly padded`. If you do, make sure you change the passwords to be the same. You can find a more detailed explanation in [this GitHub issue](https://github.com/openremote/openremote/issues/2093). +The password of the keystore and the password of each keypair within the keystore should be the same, and it should be set to `OR_KEYSTORE_PASSWORD`. Otherwise, you may see errors like `Get Key failed: Given final block not properly padded`. You can find a more detailed explanation in [this GitHub issue](https://github.com/openremote/openremote/issues/2093). ::: The password of everything keystore-related is `OR_KEYSTORE_PASSWORD`, for when it is requested. If it is not set as an environment variable before starting OpenRemote for the first time, it will default to ``. If you want to change the password later, you will need to change it in both the keystore and the truststore, as well as the passwords of each keypair within the keystore and truststore, and make sure to set `OR_KEYSTORE_PASSWORD` as that password. From ad3eaecee4bdfb889b9b803c653b79d2e2f1a365 Mon Sep 17 00:00:00 2001 From: Panos Kalogeropoulos Date: Sun, 28 Sep 2025 14:55:44 +0200 Subject: [PATCH 3/4] Update documentation with warning and more information about keystore passwords and how to change them. --- docs/user-guide/agents-protocols/mqtt.md | 2 -- .../version-1.8.0/user-guide/agents-protocols/mqtt.md | 2 -- 2 files changed, 4 deletions(-) diff --git a/docs/user-guide/agents-protocols/mqtt.md b/docs/user-guide/agents-protocols/mqtt.md index 7317e63..3254682 100644 --- a/docs/user-guide/agents-protocols/mqtt.md +++ b/docs/user-guide/agents-protocols/mqtt.md @@ -34,8 +34,6 @@ The password of everything keystore-related is `OR_KEYSTORE_PASSWORD`, for when Make sure that OpenRemote has been started at least once before proceeding, so that the required keystore files are created automatically. If you have a pre-existing keystore file, make sure to provide the file's location using `OR_SSL_CLIENT_KEYSTORE_FILE`, `OR_SSL_CLIENT_TRUSTSTORE_FILE`, and `OR_SSL_CLIENT_KEYSTORE_PASSWORD` or `OR_SSL_CLIENT_TRUSTSTORE_PASSWORD` for their passwords. - - After doing so, we need to: - Combine the certificate and Private Key into a PKCS#12 keypair file, so that it can be easily imported into the KeyStore: ```bash diff --git a/versioned_docs/version-1.8.0/user-guide/agents-protocols/mqtt.md b/versioned_docs/version-1.8.0/user-guide/agents-protocols/mqtt.md index b753bf2..082b2ee 100644 --- a/versioned_docs/version-1.8.0/user-guide/agents-protocols/mqtt.md +++ b/versioned_docs/version-1.8.0/user-guide/agents-protocols/mqtt.md @@ -34,8 +34,6 @@ The password of everything keystore-related is `OR_KEYSTORE_PASSWORD`, for when Make sure that OpenRemote has been started at least once before proceeding, so that the required keystore files are created automatically. If you have a pre-existing keystore file, make sure to provide the file's location using `OR_SSL_CLIENT_KEYSTORE_FILE`, `OR_SSL_CLIENT_TRUSTSTORE_FILE`, and `OR_SSL_CLIENT_KEYSTORE_PASSWORD` or `OR_SSL_CLIENT_TRUSTSTORE_PASSWORD` for their passwords. - - After doing so, we need to: - Combine the certificate and Private Key into a PKCS#12 keypair file, so that it can be easily imported into the KeyStore: ```bash From cfcc31267b3e7321a5f68a6ec88f3d34cffc76ae Mon Sep 17 00:00:00 2001 From: Panos Kalogeropoulos Date: Sun, 28 Sep 2025 15:01:16 +0200 Subject: [PATCH 4/4] Update documentation with warning and more information about keystore passwords and how to change them. --- docs/user-guide/agents-protocols/mqtt.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/user-guide/agents-protocols/mqtt.md b/docs/user-guide/agents-protocols/mqtt.md index 3254682..ba5584b 100644 --- a/docs/user-guide/agents-protocols/mqtt.md +++ b/docs/user-guide/agents-protocols/mqtt.md @@ -7,8 +7,8 @@ sidebar_position: 8 There is an MQTT Agent (Client) in OpenRemote that you can use to connect to an external MQTT Broker. First use the MQTT Agent to establish the connection to the broker. Then create an asset with attribute(s) of the Value Type that matches the incoming/outgoing data, and give those attributes the configuration item 'Agent Link'. In this agent link select -your MQTT Agent and add the parameter Publish Topic or Subscription Topic. We have no extensive documentation yet, -and recommend to [check our forum](https://forum.openremote.io/t/mqtt-agents-publish-subscription/985). +your MQTT Agent and add the parameter Publish Topic or Subscription Topic. We have no extensive documentation yet, +and recommend to [check our forum](https://forum.openremote.io/t/mqtt-agents-publish-subscription/985). OpenRemote also has an [MQTT Broker](../manager-apis.md#mqtt-api-mqtt-broker) (or MQTT API).