Fixes to mTLS for MQTT Agent documentation (#10)

docs/user-guide/agents-protocols/mqtt.md

@@ -20,33 +20,36 @@ KeyStores. Below is a tutorial of how that can be done;
 
 You will need to have `keytool` installed; this can also be done using any GUI for keystores (ex. [KeyStore Explorer](https://github.com/kaikramer/keystore-explorer)).
 
-After creating a Thing, you need to retrieve its certificate, its private key, and Amazon's Root CA certificate.
+After creating a Thing in AWS IoT Core, you need to retrieve its certificate, its private key, and Amazon's Root CA certificate.
 
 They are all provided after accessing that thing's dashboard and creating a new certificate for it: ![img.png](img/aws-iot-mqtt-broker-download-links.png)
 
 Download the Device Certificate and activate it, download the private key file, and the Amazon Trust Services endpoint RSA 2048 bit key.
 
-Make sure that OpenRemote has been started at least once before proceeding, so that the required keystore files are generated.
+The password of everything keystore-related is ``OR_ADMIN_PASSWORD``, for when it is requested.
+
+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_ADMIN_PASSWORD`, for when it is requested.
 
 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. Take note of the input for the `alias` parameter, we'll need it later:
+- 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
-keytool -importkeystore -destkeystore <storage dir>/client_keystore.p12 -srckeystore OpenRemoteAWSKeyPair.p12 -srcstoretype PKCS12 -alias <realm name of your choice>.OpenRemoteAwsIoTClientCertificate
+keytool -importkeystore -destkeystore <storage dir>/client_keystore.p12 -srckeystore OpenRemoteAWSKeyPair.p12 -srcstoretype PKCS12 -alias master.OpenRemoteAwsIoTClientCertificate
 ```
 - Import the Amazon Root CA certificate into the truststore;
 ```shell
-keytool -importcert -file AmazonRootCA1.pem -keystore <storage dir>/<realm>.client_truststore -alias amazonrootca1
+keytool -importcert -file AmazonRootCA1.pem -keystore <storage dir>/client_truststore.p12 -alias amazonrootca1
 ```
 
 Now, we are ready to start OpenRemote again, and create a new MQTT Agent.
 
-**Make sure** that the Agent is situated in the realm that is specified in the Alias from the command above, or else OpenRemote will not be able to retrieve the correct certificate.
+**Make sure** that the Agent is situated in the realm that is specified in the Alias from the command above, or else OpenRemote will not be able to retrieve the correct certificate. An error will be logged with more information if that happens.
 
 In that agent, ensure that you have set:
 - The correct host and port (AWS IoT Core MQTT broker is set to `8883`)