Using Matrix Encryption
End-to-end encrypted rooms utilize the Olm algorithm to encrypt messages. Piecewise is able to read these messages, but some setup is involved in making things work.
Important note: Piecewise can handle unencrypted message retrieval from Matrix without any special setup. This guide need only be followed if you wish for your bot to receive encrypted messages.
Create an account
You will want a dedicated Matrix account for your bot. If you do not have a dedicated bot account on a homeserver, create one. Here is a list of public homeservers.
Set up encryption keys
Before using your account in Piecewise, you’ll need to log into its account in order to set up encryption keys. This guide will reference the popular Element client.
- Open Element, either from your homeserver, from app.element.io, or from the downloadable app.
- Log in with the username and password for your bot. Remember to set your homeserver properly.
- Encryption keys are now automatically set up for you within your browser. You should export your E2E keys and store them in a safe place.
Log in with Piecewise
Now you’ll need to log in to the account with Piecewise in order to add it to your devices list.
- Drag the Matrix configuration block onto your workspace. Enter your full Matrix handle (i.e. @piecewise:piecewise.im), select the PASSWORD authentication option, and enter your bot’s password.
- Click the “Run” button at the top of the screen. This will initiate a connection to your homeserver and add Piecewise to your bot account’s devices list.
Verify your bot’s account
In general, in order for other clients to trust your bot’s encryption keys and send you encrypted messages, the Piecewise Matrix client will need to be “trusted.” There may be other ways of accomplishing this, but this is the easiest in my opinion:
- Create a private room from your bot account (the
+in the top left corner of Element) and enable E2E encryption.
- Click on “Room info” in the top right, then click People -> the bot’s name.
- Click the Piecewise session’s name - it may look like a random string of letters and numbers like T12345Y6789.
- A “Not Trusted” dialog will appear. Click “Manually Verify By Text”, and then “Verify Session”.
- Your session will now be verified. Any users that have previously communicated with your bot may have to refresh their clients in order for them to trust your keys.
- These steps will have to be completed on each computer you wish to run your bot on.
- If you change your bot’s Matrix password, these steps will have to be completed again.
- The authentication information is stored in the .lazurite folder as matrix_[sha512hash].token. Your bot’s encryption information is stored in the .lazurite folder as matrix__username_homeserver.name.store. Keep these files safe as they contain everything anyone would need to log in to your bot’s Matrix account.
- In theory, these files are portable and can be used to authenticate your bot in multiple locations, but this configuration is not recommended or supported.