mirror of
https://github.com/markqvist/unsignedio
synced 2026-08-12 17:40:37 -04:00
184 lines
13 KiB
HTML
184 lines
13 KiB
HTML
|
|
<!doctype html>
|
|
<html>
|
|
<head>
|
|
<link rel="stylesheet" href="../css/water.css?v=19">
|
|
<link rel="shortcut icon" type="image/x-icon" href="../gfx/icon.png">
|
|
<meta charset="utf-8"/>
|
|
<title>unsigned.io</title>
|
|
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
|
|
|
<meta property="og:title" content="unsigned.io">
|
|
<meta name="description" content="unsigned.io">
|
|
<meta property="og:description" content="unsigned.io">
|
|
<meta property="og:image" content="https://unsigned.io/gfx/unsigned_logo.webp">
|
|
<meta property="og:url" content="https://unsigned.io/software/LXMF.html">
|
|
<meta property="og:title" content="unsigned.io">
|
|
<meta name="twitter:card" content="summary_large_image">
|
|
<meta property="twitter:domain" content="unsigned.io">
|
|
<meta property="twitter:url" content="https://unsigned.io/software/LXMF.html">
|
|
<meta name="twitter:title" content="unsigned.io">
|
|
<meta name="twitter:description" content="unsigned.io">
|
|
<meta name="twitter:image" content="https://unsigned.io/gfx/unsigned_logo.webp">
|
|
|
|
</head>
|
|
<body>
|
|
<div id="load_overlay" style="background-color:#2a2a2f; position:absolute; top:0px; left:0px; width:100%; height:100%; z-index:2000;"></div>
|
|
<span class="logo">unsigned.io</span>
|
|
<center>
|
|
<p><span class="menu"><a href="../index.html">Home</a> | <a href="../log.html">Log</a> | <a href="../guides.html">Guides</a> | <a href="../software/index.html">Software</a> | <a href="../hardware/index.html">Hardware</a> | <a href="https://github.com/markqvist/Reticulum/discussions">Discussions</a> | <a href="../shop.html">Shop</a> | <a href="../contact.html">Contact Me</a> | <a href="../donate.html">Donate</a></span></p>
|
|
</center><hr><h1>Lightweight Extensible Message Format</h1>
|
|
<p>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 <a href="https://reticulum.network">Reticulum</a> 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.</p>
|
|
<p>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 <em>paper message</em> transport.</p>
|
|
<p>User-facing clients built on LXMF include:</p>
|
|
<ul>
|
|
<li><a href="https://unsigned.io/sideband">Sideband</a></li>
|
|
<li><a href="https://unsigned.io/nomadnet">Nomad Network</a></li>
|
|
<li><a href="https://github.com/HarlekinSimplex/nexus_messenger">Nexus Messenger</a></li>
|
|
</ul>
|
|
<h2>Structure</h2>
|
|
<p>LXMF messages are stored in a simple and efficient format, that's easy to parse and write.</p>
|
|
<h3>The format follows this general structure:</h3>
|
|
<ul>
|
|
<li>Destination</li>
|
|
<li>Source</li>
|
|
<li>Ed25519 Signature</li>
|
|
<li>Payload<ul>
|
|
<li>Timestamp</li>
|
|
<li>Content</li>
|
|
<li>Title</li>
|
|
<li>Fields</li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
<h3>And these rules:</h3>
|
|
<ol>
|
|
<li>A LXMF message is identified by its <strong>message-id</strong>, which is a SHA-256 hash of the <strong>Destination</strong>, <strong>Source</strong> and <strong>Payload</strong>. The message-id is never included directly in the message, since it can always be inferred from the message itself.</li>
|
|
</ol>
|
|
<p>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 theses cases a <em>transient-id</em> is used to identify the message while in storage or transit.</p>
|
|
<ol>
|
|
<li>
|
|
<p><strong>Destination</strong>, <strong>Source</strong>, <strong>Signature</strong> and <strong>Payload</strong> parts are mandatory, as is the <strong>Timestamp</strong> part of the payload.</p>
|
|
<ul>
|
|
<li>The <strong>Destination</strong> and <strong>Source</strong> fields are 10-byte Reticulum destination hashes</li>
|
|
<li>The <strong>Signature</strong> field is a 64-byte Ed25519 signature of the <strong>Destination</strong>, <strong>Source</strong>, <strong>Payload</strong> and <strong>message-id</strong></li>
|
|
<li>The <strong>Payload</strong> part is a <a href="https://msgpack.org">msgpacked</a> list containing four items:<ol>
|
|
<li>The <strong>Timestamp</strong> is a double-precision floating point number representing the number of seconds since the UNIX epoch.</li>
|
|
<li>The <strong>Content</strong> is the optional content or body of the message</li>
|
|
<li>The <strong>Title</strong> is an optional title for the message</li>
|
|
<li>The <strong>Fields</strong> is an optional dictionary</li>
|
|
</ol>
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
<li>
|
|
<p>The <strong>Content</strong>, <strong>Title</strong> and <strong>Fields</strong> parts must be included in the message structure, but can be left empty.</p>
|
|
</li>
|
|
<li>
|
|
<p>The <strong>Fields</strong> part can be left empty, or contain a dictionary of any structure or depth.</p>
|
|
</li>
|
|
</ol>
|
|
<h2>Usage Examples</h2>
|
|
<p>LXMF offers flexibility to implement many different messaging schemes, ranging from human communication to machine control and sensor monitoring. Here's a few examples:</p>
|
|
<ul>
|
|
<li>
|
|
<p>A messaging system for passing short, simple messages between human users, akin to SMS can be implemented using only the <strong>Content</strong> field, and leaving all other optional fields empty.</p>
|
|
</li>
|
|
<li>
|
|
<p>For sending full-size mail, an email-like system can be implemented using the <strong>Title</strong> and <strong>Content</strong> fields to store "subject" and "body" parts of the message, and optionally the <strong>Fields</strong> part can be used to store attachments or other metadata.</p>
|
|
</li>
|
|
<li>
|
|
<p>Machine-control messages or sensor readings can be implemented using command structures embedded in the <strong>Fields</strong> dictionary.</p>
|
|
</li>
|
|
<li>
|
|
<p>Distributed discussion or news-groups, akin to USENET or similar systems, can be implemented using the relevant fields and LXMF Propagation Nodes. Broadcast bulletins can be implemented in a similar fashion.</p>
|
|
</li>
|
|
</ul>
|
|
<h2>Propagation Nodes</h2>
|
|
<p>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.</p>
|
|
<p>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.</p>
|
|
<h2>The LXM Router</h2>
|
|
<p>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.</p>
|
|
<p>Programatically, using the LXM Router to send a message is as simple as:</p>
|
|
<pre><code class="language-python">import LXMF
|
|
|
|
lxm_router = LXMF.LXMRouter()
|
|
|
|
message = LXMF.LXMessage(destination, source, "This is a short, simple message.")
|
|
|
|
lxm_router.handle_outbound(message)
|
|
|
|
</code></pre>
|
|
<p>The LXM Router then handles the heavy lifting, such as message packing, encryption, delivery confirmation, path lookup, routing, retries and failure notifications.</p>
|
|
<h2>Transport Encryption</h2>
|
|
<p>LXMF uses encryption provided by <a href="https://reticulum.network">Reticulum</a>, and thus uses end-to-end encryption by default. The delivery method of a message will influence which transport encryption scheme is used.</p>
|
|
<ul>
|
|
<li>
|
|
<p>A message can be delivered opportunistically, embedded in a single Reticulum packet. In this cases the message will be opportunistically routed through the network, and will be encrypted with <em>ephemeral</em> keys derived with <em>ECDH</em> on <em>Curve25519</em>. This mode offers Perfect Forward Secrecy.</p>
|
|
</li>
|
|
<li>
|
|
<p>If a message is delivered to the Reticulum GROUP destination type, the message will be transported using <em>AES-128</em> encryption.</p>
|
|
</li>
|
|
<li>
|
|
<p>If a message is delivered over a Reticulum link (which is the default method), the message will be encrypted with <em>ephemeral</em> keys derived with <em>ECDH</em> on <em>Curve25519</em>. This mode offers Perfect Forward Secrecy.</p>
|
|
</li>
|
|
</ul>
|
|
<h2>Wire Format & Overhead</h2>
|
|
<p>Assuming the default Reticulum configuration, the binary wire-format is as follows:</p>
|
|
<ul>
|
|
<li>16 bytes destination hash</li>
|
|
<li>16 bytes source hash</li>
|
|
<li>64 bytes Ed25519 signature</li>
|
|
<li>Remaining bytes of <a href="https://msgpack.org">msgpack</a> payload data, in accordance with the structure defined above</li>
|
|
</ul>
|
|
<p>The complete message overhead for LXMF is only 99 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.</p>
|
|
<h2>Example Paper Message</h2>
|
|
<p>You can try out the paper messaging functionality by using the following QR-code. It is a paper message sent to the LXMF address <code>6b3362bd2c1dbf87b66a85f79a8d8c75</code>. To be able to decrypt and read the message, you will need to import the following Reticulum Identity to an LXMF messaging app:</p>
|
|
<p><code>3BPTDTQCRZPKJT3TXAJCMQFMOYWIM3OCLKPWMG4HCF2T4CH3YZHVNHNRDU6QAZWV2KBHMWBNT2C62TQEVC5GLFM4MN25VLZFSK3ADRQ=</code></p>
|
|
<p>The <a href="https://unsigned.io/sideband">Sideband</a> application allows you to do this easily. After the 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>
|
|
<p align="center"><img width="50%" src="../images/paper_msg_test.png"/></p>
|
|
|
|
<p>You can also find the entire message in <a href="lxm://azNivSwdv4e2aoX3mo2MdTAozuI7BlzrLlHULmnVgpz3dNT9CMPVwgywzCJP8FVogj5j_kU7j7ywuvBNcr45kRTrd19c3iHenmnSDe4VEd6FuGsAiT0Khzl7T81YZHPTDhRNp0FdhDE9AJ7uphw7zKMyqhHHxOxqrYeBeKF66gpPxDceqjsOApvsSwggjcuHBx9OxOBy05XmnJxA1unCKgvNfOFYc1T47luxoY3c0dLOJnJPwZuFRytx2TXlQNZzOJ28yTEygIfkDqEO9mZi5lgev7XZJ0DvgioQxMIyoCm7lBUzfq66zW3SQj6vHHph7bhr36dLOCFgk4fZA6yia2MlTT9KV66Tn2l8mPNDlvuSAJhwDA_xx2PN9zKadCjo9sItkAp8r-Ss1CzoUWZUAyT1oDw7ly6RrzGBG-e3eM3CL6u1juIeFiHby7_3cON-6VTUuk4xR5nwKlFTu5vsYMVXe5H3VahiDSS4Q1aqX7I">this link</a>:</p>
|
|
<p><code>lxm://azNivSwdv4e2aoX3mo2MdTAozuI7BlzrLlHULmnVgpz3dNT9CMPVwgywzCJP8FVogj5j_kU7j7ywuvBNcr45kRTrd19c3iHenmnSDe4VEd6FuGsAiT0Khzl7T81YZHPTDhRNp0FdhDE9AJ7uphw7zKMyqhHHxOxqrYeBeKF66gpPxDceqjsOApvsSwggjcuHBx9OxOBy05XmnJxA1unCKgvNfOFYc1T47luxoY3c0dLOJnJPwZuFRytx2TXlQNZzOJ28yTEygIfkDqEO9mZi5lgev7XZJ0DvgioQxMIyoCm7lBUzfq66zW3SQj6vHHph7bhr36dLOCFgk4fZA6yia2MlTT9KV66Tn2l8mPNDlvuSAJhwDA_xx2PN9zKadCjo9sItkAp8r-Ss1CzoUWZUAyT1oDw7ly6RrzGBG-e3eM3CL6u1juIeFiHby7_3cON-6VTUuk4xR5nwKlFTu5vsYMVXe5H3VahiDSS4Q1aqX7I</code></p>
|
|
<p>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.</p>
|
|
<h2>Caveat Emptor</h2>
|
|
<p>LXMF is beta software, and should be considered experimental. While it has been built with cryptography best-practices very foremost in mind, it <em>has not</em> 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.</p>
|
|
<h2>Installation</h2>
|
|
<p>If you want to try out LXMF, you can install it with pip:</p>
|
|
<pre><code class="language-bash">pip3 install lxmf
|
|
</code></pre>
|
|
<h2>Development Roadmap</h2>
|
|
<p>LXMF is actively being developed, and the following improvements and features are currently planned for implementation:</p>
|
|
<ul>
|
|
<li>Write and release full API and protocol documentation</li>
|
|
<li>Content Destinations, and easy to use API for group messaging and discussion threads </li>
|
|
<li>Sneakernet and physical transport functionality</li>
|
|
<li>Documenting and possibly expanding LXMF limits and priorities</li>
|
|
<li>Sync affinity based on link speeds and distances, for more intelligently choosing peer sync order</li>
|
|
<li>Markets on LXMF</li>
|
|
</ul>
|
|
<h2>Support LXMF Development</h2>
|
|
<p>You can help support the continued development of open, free and private communications systems by donating via one of the following channels:</p>
|
|
<ul>
|
|
<li>Monero<br/>
|
|
<code>84FpY1QbxHcgdseePYNmhTHcrgMX4nFfBYtz2GKYToqHVVhJp8Eaw1Z1EedRnKD19b3B8NiLCGVxzKV17UMmmeEsCrPyA5w</code>
|
|
<br/><br/></li>
|
|
<li>Ethereum<br/>
|
|
<code>0xFDabC71AC4c0C78C95aDDDe3B4FA19d6273c5E73</code>
|
|
<br/><br/></li>
|
|
<li>Bitcoin<br/>
|
|
<code>35G9uWVzrpJJibzUwpNUQGQNFzLirhrYAH</code>
|
|
<br/><br/></li>
|
|
<li>Ko-Fi<br/>
|
|
<a href="https://ko-fi.com/markqvist"><code>https://ko-fi.com/markqvist</code></a></li>
|
|
</ul>
|
|
<br/><hr/><span class="no_print"><center><br/><i>This website is running on a 100% solar powered server</i><br/><br/>☀️<br/><br/><i><small>Unless otherwise noted, everything here is put into the world under a <a href="../LICENSE.txt">CC BY-NC-SA 4.0</a> license.<br/>Feel free to share and remix, just remember the attribution.
|
|
</small></i></center></span>
|
|
<div class="print_only donation_block"><br/>
|
|
Contribute to keeping information on Free & Open Communications systems available for all.<br/>
|
|
You can donate directly to <b>unsigned.io</b> by using one of the following QR codes:<br/><br/>
|
|
<span class="donate_qr"><img src="../gfx/donate_xmr.png"/><br/>Monero</span>
|
|
<span class="donate_qr"><img src="../gfx/donate_btc.png"/><br/>Bitcoin</span>
|
|
<span class="donate_qr"><img src="../gfx/donate_eth.png"/><br/>Ethereum</span>
|
|
</div>
|
|
</body></html>
|