Update MQTT Agent mTLS docs to clarify Keystore password usage and setup

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).
 
@@ -26,10 +26,13 @@ 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`. You can find a more detailed explanation in [this GitHub issue](https://github.com/openremote/openremote/issues/2093).
+:::
 
-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.
+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 `<empty string>`. 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:

versioned_docs/version-1.8.0/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).
 
@@ -26,17 +26,20 @@ 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`. You can find a more detailed explanation in [this GitHub issue](https://github.com/openremote/openremote/issues/2093).
+:::
 
-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.
+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 `<empty string>`. 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; `<the realm where you will be creating the agent>.<an alias you will enter into the OpenRemote agent configuration>`. 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 +57,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->`<your thing's name>`->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.