Home

Awesome

Lightweight Extensible Message Format

LXMF is a simple and flexible messaging format and delivery protocol that allows a wide variety of implementations, while using as little bandwidth as possible. It is built on top of Reticulum and offers zero-conf message routing, end-to-end encryption and Forward Secrecy, and can be transported over any kind of medium that Reticulum supports.

LXMF is efficient enough that it can deliver messages over extremely low-bandwidth systems such as packet radio or LoRa. Encrypted LXMF messages can also be encoded as QR-codes or text-based URIs, allowing completely analog paper message transport.

User-facing clients built on LXMF include:

Community-provided tools and utilities for LXMF include:

Structure

LXMF messages are stored in a simple and efficient format, that's easy to parse and write.

The format follows this general structure:

And these rules:

  1. A LXMF message is identified by its message-id, which is a SHA-256 hash of the Destination, Source and Payload. The message-id is never included directly in the message, since it can always be inferred from the message itself.

    In some cases the actual message-id cannot be inferred, for example when a Propagation Node is storing an encrypted message for an offline user. In these cases a transient-id is used to identify the message while in storage or transit.

  2. Destination, Source, Signature and Payload parts are mandatory, as is the Timestamp part of the payload.

    • The Destination and Source fields are 16-byte Reticulum destination hashes
    • The Signature field is a 64-byte Ed25519 signature of the Destination, Source, Payload and message-id
    • The Payload part is a msgpacked list containing four items:
      1. The Timestamp is a double-precision floating point number representing the number of seconds since the UNIX epoch.
      2. The Content is the optional content or body of the message
      3. The Title is an optional title for the message
      4. The Fields is an optional dictionary

  3. The Content, Title and Fields parts must be included in the message structure, but can be left empty.

  4. The Fields part can be left empty, or contain a dictionary of any structure or depth.

Usage Examples

LXMF offers flexibility to implement many different messaging schemes, ranging from human communication to machine control and sensor monitoring. Here are a few examples:

Propagation Nodes

LXM Propagation Nodes offer a way to store and forward messages to users or endpoints that are not directly reachable at the time of message emission. Propagation Nodes can also provide infrastructure for distributed bulletin, news or discussion boards.

When Propagation Nodes exist on a Reticulum network, they will by default peer with each other and synchronise messages, automatically creating an encrypted, distributed message store. Users and other endpoints can retrieve messages destined for them from any available Propagation Nodes on the network.

The LXM Router

The LXM Router handles transporting messages over a Reticulum network, managing delivery receipts, outbound and inbound queues, and is the point of API interaction for client programs. The LXM Router also implements functionality for acting as an LXMF Propagation Node.

Programatically, using the LXM Router to send a message is as simple as:

import LXMF

lxm_router = LXMF.LXMRouter()

message = LXMF.LXMessage(destination, source, "This is a short, simple message.")

lxm_router.handle_outbound(message)

The LXM Router then handles the heavy lifting, such as message packing, encryption, delivery confirmation, path lookup, routing, retries and failure notifications.

Transport Encryption

LXMF uses encryption provided by Reticulum, and thus uses end-to-end encryption by default. The delivery method of a message will influence which transport encryption scheme is used.

Wire Format & Overhead

Assuming the default Reticulum configuration, the binary wire-format is as follows:

The complete message overhead for LXMF is only 111 bytes, which in return gives you timestamped, digitally signed, infinitely extensible, end-to-end encrypted, zero-conf routed, minimal-infrastructure messaging that's easy to use and build applications with.

Code Examples

Before writing your own programs using LXMF, you need to have a basic understanding of how the Reticulum protocol and API works. Please see the Reticulum Manual. For a few simple examples of how to send and receive messages with LXMF, please see the receiver example and the sender example included in this repository.

Example Paper Message

You can try out the paper messaging functionality by using the following QR code. It is a paper message sent to the LXMF address 6b3362bd2c1dbf87b66a85f79a8d8c75. To be able to decrypt and read the message, you will need to import the following Reticulum Identity to an LXMF messaging app:

3BPTDTQCRZPKJT3TXAJCMQFMOYWIM3OCLKPWMG4HCF2T4CH3YZHVNHNRDU6QAZWV2KBHMWBNT2C62TQEVC5GLFM4MN25VLZFSK3ADRQ=

The Sideband application allows you to do this easily. After you have imported the identity into an app of your choice, you can scan the following QR code and open it in the app, where it will be decrypted and added as a message.

<p align="center"><img width="50%" src="./docs/paper_msg_test.png"/></p>

You can also find the entire message in <a href="lxm://azNivSwdv4e2aoX3mo2MdTAozuI7BlzrLlHULmnVgpz3dNT9CMPVwgywzCJP8FVogj5j_kU7j7ywuvBNcr45kRTrd19c3iHenmnSDe4VEd6FuGsAiT0Khzl7T81YZHPTDhRNp0FdhDE9AJ7uphw7zKMyqhHHxOxqrYeBeKF66gpPxDceqjsOApvsSwggjcuHBx9OxOBy05XmnJxA1unCKgvNfOFYc1T47luxoY3c0dLOJnJPwZuFRytx2TXlQNZzOJ28yTEygIfkDqEO9mZi5lgev7XZJ0DvgioQxMIyoCm7lBUzfq66zW3SQj6vHHph7bhr36dLOCFgk4fZA6yia2MlTT9KV66Tn2l8mPNDlvuSAJhwDA_xx2PN9zKadCjo9sItkAp8r-Ss1CzoUWZUAyT1oDw7ly6RrzGBG-e3eM3CL6u1juIeFiHby7_3cON-6VTUuk4xR5nwKlFTu5vsYMVXe5H3VahiDSS4Q1aqX7I">this link</a>:

lxm://azNivSwdv4e2aoX3mo2MdTAozuI7BlzrLlHULmnVgpz3dNT9CMPVwgywzCJP8FVogj5j_kU7j7ywuvBNcr45kRTrd19c3iHenmnSDe4VEd6FuGsAiT0Khzl7T81YZHPTDhRNp0FdhDE9AJ7uphw7zKMyqhHHxOxqrYeBeKF66gpPxDceqjsOApvsSwggjcuHBx9OxOBy05XmnJxA1unCKgvNfOFYc1T47luxoY3c0dLOJnJPwZuFRytx2TXlQNZzOJ28yTEygIfkDqEO9mZi5lgev7XZJ0DvgioQxMIyoCm7lBUzfq66zW3SQj6vHHph7bhr36dLOCFgk4fZA6yia2MlTT9KV66Tn2l8mPNDlvuSAJhwDA_xx2PN9zKadCjo9sItkAp8r-Ss1CzoUWZUAyT1oDw7ly6RrzGBG-e3eM3CL6u1juIeFiHby7_3cON-6VTUuk4xR5nwKlFTu5vsYMVXe5H3VahiDSS4Q1aqX7I

On operating systems that allow for registering custom URI-handlers, you can click the link, and it will be decoded directly in your LXMF client. This works with Sideband on Android.

Installation

If you want to try out LXMF, you can install it with pip:

pip install lxmf

If you are using an operating system that blocks normal user package installation via pip, you can return pip to normal behaviour by editing the ~/.config/pip/pip.conf file, and adding the following directive in the [global] section:

[global]
break-system-packages = true

Alternatively, you can use the pipx tool to install Reticulum in an isolated environment:

pipx install lxmf

Daemon Included

The lxmf package comes with the lxmd program, a fully functional (but lightweight) LXMF message router and propagation node daemon. After installing the lxmf package, you can run lxmd --help to learn more about the command-line options:

$ lxmd --help

usage: lxmd [-h] [--config CONFIG] [--rnsconfig RNSCONFIG] [-p] [-i PATH] [-v] [-q] [-s] [--exampleconfig] [--version]

Lightweight Extensible Messaging Daemon

options:
  -h, --help            show this help message and exit
  --config CONFIG       path to alternative lxmd config directory
  --rnsconfig RNSCONFIG
                        path to alternative Reticulum config directory
  -p, --propagation-node
                        run an LXMF Propagation Node
  -i PATH, --on-inbound PATH
                        executable to run when a message is received
  -v, --verbose
  -q, --quiet
  -s, --service         lxmd is running as a service and should log to file
  --exampleconfig       print verbose configuration example to stdout and exit
  --version             show program's version number and exit

Or run lxmd --exampleconfig to generate a commented example configuration documenting all the available configuration directives.

Caveat Emptor

LXMF is beta software, and should be considered experimental. While it has been built with cryptography best practices very foremost in mind, it has not been externally security audited, and there could very well be privacy-breaking bugs. If you want to help out, or help sponsor an audit, please do get in touch.

Development Roadmap

LXMF is actively being developed, and the following improvements and features are currently planned for implementation: