CoMatrix

CoMatrix Gateway User Documentation

The CoMatrix gateway enables the usage of the Matrix CS-API 1 for constrained IoT devices via CoAP 2 and CBOR 3 in a constrained network (e.g. a 802.15.4/6LoWPAN network 4).

The CoMatrix gateway is a CoAP server which acts as a HTTP forward proxy (“cross-proxy”) and is based on aiocoap (“The Python CoAP library) 5. It creates valid Matrix Client-Server-API (CS-API r0.6.1) HTTP requests based on incoming CoAP requests. By default, it listens on all addresses, and the standard CoAP port (UDP 5683). Unfortunately, the gateway currently only supports plaintext CoAP because DTLS is only supported for CoAP clients in aiocoap at the moment. The IP address and port to listen on can be configured by passing CLI arguments. Caution: In case of a IPv6 link-local address the zone identifier needs to be specified (e.g. fe80::1%lowpan0).

Usage:

$ ./comatrix_gateway.py -h
usage: comatrix_gateway.py [-h] [-i IP] [-p PORT]

CoMatrix gateway - enables usage of the Matrix protocol for constrained IoT
devices

optional arguments://
  -h, --help            show this help message and exit
  -i IP, --ip IP        IP address to listen on (default: ::)
  -p PORT, --port PORT  UDP Port to listen on (default: 5683)

The gateway provides the following CoAP resources:

  • coap://[::]/.well-known/core - Lists all available resources
  • coap://[::]/register - Enables registration of a new Matrix-Synapse user
  • coap://[::]/login - Enables login of an existing Matrix-Synapse user
  • coap://[::]/join - Enables joining of a Matrix room after an invitation
  • coap://[::]/getmsg - Enables retrieving of the last message sent to a Matrix room
  • coap://[::]/send - Enables sending of a message to a Matrix room
  • coap://[::]/time - Non-Matrix-related resource, provides a Unix timestamp
  • coap://[::]/logout - Enables logout of an existing Matrix-Synapse user

Detailed descriptions of the resources are available in the Developer Documentation and in the comatrix_gateway.py file.

By default some debugging information is logged, e.g. information contained in the CoAP request like content format and message type.

Optional: Add hardcoded access token to perform CS-API requests to Matrix Synapse HS

It is possible to optionally set a hardcoded access token in comatrix_gateway.py (see line 73), which will be used to send HTTP requests to the Matrix Synapse HS 6 if no access token is contained in the received CoAP request (and required in the requested resource). This can be used to reduce the necessary packet sizes for (authenticated) CoAP requests sent (by a CoMatrix client) to the CoMatrix gateway by >200 bytes (with Synapse versions before v1.34, see update below).

Example access token (truncated): MDAxZWxvY2F0aW9uIG1hdHJpeC5sb2NhbGhvc3QKMDAxM2lyMWNpZCBub25jZSA9IFN6Vbdl5ETbryPgqzPNzmuC6-QIJzUr7Brz07X8wa_XAo

ACCESS_TOKEN_HC = 'MDAxZWxvY2F0aW9uIG1hdHJpeC5sb2NhbGhvc3QKMDAxM2lyMWNpZCBub25jZSA9IFN6Vbdl5ETbryPgqzPNzmuC6-QIJzUr7Brz07X8wa_XAo'

To find out the current access token of a user via Element (Matrix client) 7:

  1. Log in to the account you want to get the access token for. Click on the name in the top left corner, then “All Settings”.
  2. Click the “Help & About” tab (left side of the dialog).
  3. Scroll to the bottom and click on part of Access Token.
  4. Copy your access token to a safe place.

In the future Synapse’s access token implementation may be adapted to use shorter (random) strings instead of macaroons (cf. 8). Update 17.05.2021: 8 was already merged and released with Synapse v1.34 (cf. 9). The new access token format reduces access token length from >200 Bytes to ~50 Bytes.

Tests

Unfortunately, there are currently no unittests implemented.

CoMatrix currently provides a few Python scripts to test CoMatrix gateway behavior.

Prerequisites:

  • A Running Matrix-Synapse homeserver.
  • A Running CoMatrix gateway. Needs to be able to send to HTTP(S) requests to Matrix-Synapse HS.
  • The correct CoMatrix gateway and Matrix-Synapse URL needs to be set in the script file.

This list enumerates all available test scripts and their purpose:

  • comatrix_gateway_registration_logout_test.py: This script generates a random username and password (=username). This user is then registered at a Matrix-Synapse HS by sending a CoAP request to a CoMatrix gateway. The generated access token for this user (after successful registration) is then used to test the LogoutResource of the CoMatrix gateway.
  • comatrix_gateway_login_test.py: This script tests the login of an existing Matrix-Synapse user by sending a CoAP request to a CoMatrix gateway.
  • comatrix_gateway_getmsg_test.py: This script tests the receiving of the last message of a Matrix room by sending a CoAP request to a CoMatrix gateway.
  • comatrix_gateway_send_test.py: This script tests the sending of a new message to a Matrix room by sending a CoAP request to a CoMatrix gateway.
  • comatrix_gateway_join_test.py: This script tests the joining of a Matrix room after a user received an invitation from another user, by sending a CoAP request to a CoMatrix gateway.

Dependencies

Resources

  1. https://matrix.org/docs/spec/client_server/r0.6.1 ↩︎

  2. https://coap.technology/ ↩︎

  3. https://cbor.io/ ↩︎

  4. https://datatracker.ietf.org/wg/6lowpan/documents/ ↩︎

  5. https://github.com/chrysn/aiocoap ↩︎

  6. https://github.com/matrix-org/synapse ↩︎

  7. https://webapps.stackexchange.com/questions/131056/how-to-get-an-access-token-for-element-riot-matrix ↩︎

  8. https://github.com/matrix-org/synapse/pull/5588#issuecomment-794260500 ↩︎

  9. https://matrix.org/blog/2021/05/17/synapse-1-34-0-released ↩︎

CoMatrix Gateway Developer Documentation