mirror of
https://github.com/markqvist/Reticulum.git
synced 2024-11-26 15:30:18 +00:00
Updated documentation to reflect 128-bit address space
This commit is contained in:
parent
bc39a1acf1
commit
304610c682
@ -22,7 +22,7 @@ copyright = '2022, Mark Qvist'
|
|||||||
author = 'Mark Qvist'
|
author = 'Mark Qvist'
|
||||||
|
|
||||||
# The full version, including alpha/beta/rc tags
|
# The full version, including alpha/beta/rc tags
|
||||||
release = '0.3.8 beta'
|
release = '0.3.9 beta'
|
||||||
|
|
||||||
|
|
||||||
# -- General configuration ---------------------------------------------------
|
# -- General configuration ---------------------------------------------------
|
||||||
|
@ -161,20 +161,25 @@ by adding one of the following interfaces to your ``.reticulum/config`` file:
|
|||||||
|
|
||||||
.. code::
|
.. code::
|
||||||
|
|
||||||
# For connecting over TCP/IP:
|
# TCP/IP interface to the Dublin hub
|
||||||
[[RNS Testnet Frankfurt]]
|
[[RNS Testnet Dublin]]
|
||||||
type = TCPClientInterface
|
type = TCPClientInterface
|
||||||
interface_enabled = yes
|
enabled = yes
|
||||||
outgoing = True
|
target_host = dublin.connect.reticulum.network
|
||||||
target_host = frankfurt.rns.unsigned.io
|
|
||||||
target_port = 4965
|
target_port = 4965
|
||||||
|
|
||||||
|
# TCP/IP interface to the Frankfurt hub
|
||||||
|
[[RNS Testnet Dublin]]
|
||||||
|
type = TCPClientInterface
|
||||||
|
enabled = yes
|
||||||
|
target_host = frankfurt.connect.reticulum.network
|
||||||
|
target_port = 5377
|
||||||
|
|
||||||
# For connecting over I2P:
|
# Interface to I2P hub A
|
||||||
[[RNS Testnet I2P Node A]]
|
[[RNS Testnet I2P Hub A]]
|
||||||
type = I2PInterface
|
type = I2PInterface
|
||||||
interface_enabled = yes
|
enabled = yes
|
||||||
peers = ykzlw5ujbaqc2xkec4cpvgyxj257wcrmmgkuxqmqcur7cq3w3lha.b32.i2p
|
peers = uxg5kubabakh3jtnvsipingbr5574dle7bubvip7llfvwx2tgrua.b32.i2p
|
||||||
|
|
||||||
Many other Reticulum instances are connecting to this testnet, and you can also join it
|
Many other Reticulum instances are connecting to this testnet, and you can also join it
|
||||||
via other entry points if you know them. There is absolutely no control over the network
|
via other entry points if you know them. There is absolutely no control over the network
|
||||||
|
@ -14,9 +14,7 @@ Donations are gratefully accepted via the following channels:
|
|||||||
.. code:: text
|
.. code:: text
|
||||||
|
|
||||||
Monero:
|
Monero:
|
||||||
84FpY1QbxHcgdseePYNmhTHcrgMX4nFf
|
84FpY1QbxHcgdseePYNmhTHcrgMX4nFfBYtz2GKYToqHVVhJp8Eaw1Z1EedRnKD19b3B8NiLCGVxzKV17UMmmeEsCrPyA5w
|
||||||
BYtz2GKYToqHVVhJp8Eaw1Z1EedRnKD1
|
|
||||||
9b3B8NiLCGVxzKV17UMmmeEsCrPyA5w
|
|
||||||
|
|
||||||
Ethereum:
|
Ethereum:
|
||||||
0x81F7B979fEa6134bA9FD5c701b3501A2e61E897a
|
0x81F7B979fEa6134bA9FD5c701b3501A2e61E897a
|
||||||
|
@ -117,29 +117,29 @@ Reticulum uses the singular concept of *destinations*. Any application using Ret
|
|||||||
networking stack will need to create one or more destinations to receive data, and know the
|
networking stack will need to create one or more destinations to receive data, and know the
|
||||||
destinations it needs to send data to.
|
destinations it needs to send data to.
|
||||||
|
|
||||||
All destinations in Reticulum are represented as a 10 byte hash, derived from truncating a full
|
All destinations in Reticulum are _represented_ as a 16 byte hash. This hash is derived from truncating a full
|
||||||
SHA-256 hash of identifying characteristics of the destination. To users, the destination addresses
|
SHA-256 hash of identifying characteristics of the destination. To users, the destination addresses
|
||||||
will be displayed as 10 bytes in hexadecimal representation, as in the following example: ``<80e29bf7cccaf31431b3>``.
|
will be displayed as 16 hexadecimal bytes, like this example: ``<13425ec15b621c1d928589718000d814>``.
|
||||||
|
|
||||||
The truncation size of 10 bytes (80 bits) for destinations has been choosen as a reasonable tradeoff between address space
|
The truncation size of 16 bytes (128 bits) for destinations has been choosen as a reasonable tradeoff
|
||||||
|
between address space
|
||||||
and packet overhead. The address space accomodated by this size can support many billions of
|
and packet overhead. The address space accomodated by this size can support many billions of
|
||||||
simultaneously active devices on the same network, while keeping packet overhead low, which is
|
simultaneously active devices on the same network, while keeping packet overhead low, which is
|
||||||
essential on low-bandwidth networks. In the very unlikely case that this address space nears
|
essential on low-bandwidth networks. In the very unlikely case that this address space nears
|
||||||
congestion, a one-line code change can upgrade the Reticulum address space all the way up to 256
|
congestion, a one-line code change can upgrade the Reticulum address space all the way up to 256
|
||||||
bits, ensuring the Reticulum address space could potentially support galactic-scale networks.
|
bits, ensuring the Reticulum address space could potentially support galactic-scale networks.
|
||||||
This is obviusly complete and ridiculous over-allocation, and as such, the current 80 bits should
|
This is obviusly complete and ridiculous over-allocation, and as such, the current 128 bits should
|
||||||
be sufficient, even far into the future.
|
be sufficient, even far into the future.
|
||||||
|
|
||||||
By default Reticulum encrypts all data using elliptic curve cryptography. Any packet sent to a
|
By default Reticulum encrypts all data using elliptic curve cryptography. Any packet sent to a
|
||||||
destination is encrypted with a derived ephemeral key. Reticulum can also set up an encrypted
|
destination is encrypted with a derived ephemeral key. Reticulum can also set up an encrypted
|
||||||
channel to a destination with *Forward Secrecy* and *Initiator Anonymity* using a elliptic
|
channel to a destination, called a *Link*. Both data sent over Links and single packets offer
|
||||||
curve cryptography and ephemeral keys derived from a Diffie Hellman exchange on Curve25519. In
|
*Forward Secrecy* and *Initiator Anonymity*, by using an Elliptic Curve Diffie Hellman key exchange
|
||||||
Reticulum terminology, this is called a *Link*. The multi-hop transport, coordination, verification
|
on Curve25519 to derive ephemeral keys. The multi-hop transport, coordination, verification
|
||||||
and reliability layers are fully autonomous and also based on elliptic curve cryptography.
|
and reliability layers are fully autonomous and also based on elliptic curve cryptography.
|
||||||
|
|
||||||
Reticulum also offers symmetric key encryption for group-oriented communications, as well as
|
Reticulum also offers symmetric key encryption for group-oriented communications, as well as
|
||||||
unencrypted packets for broadcast purposes, or situations where you need the communication to be in
|
unencrypted packets for local broadcast purposes.
|
||||||
plain text.
|
|
||||||
|
|
||||||
Reticulum can connect to a variety of interfaces such as radio modems, data radios and serial ports,
|
Reticulum can connect to a variety of interfaces such as radio modems, data radios and serial ports,
|
||||||
and offers the possibility to easily tunnel Reticulum traffic over IP links such as the Internet or
|
and offers the possibility to easily tunnel Reticulum traffic over IP links such as the Internet or
|
||||||
@ -186,7 +186,7 @@ Destination Naming
|
|||||||
^^^^^^^^^^^^^^^^^^
|
^^^^^^^^^^^^^^^^^^
|
||||||
|
|
||||||
Destinations are created and named in an easy to understand dotted notation of *aspects*, and
|
Destinations are created and named in an easy to understand dotted notation of *aspects*, and
|
||||||
represented on the network as a hash of this value. The hash is a SHA-256 truncated to 80 bits. The
|
represented on the network as a hash of this value. The hash is a SHA-256 truncated to 128 bits. The
|
||||||
top level aspect should always be a unique identifier for the application using the destination.
|
top level aspect should always be a unique identifier for the application using the destination.
|
||||||
The next levels of aspects can be defined in any way by the creator of the application.
|
The next levels of aspects can be defined in any way by the creator of the application.
|
||||||
|
|
||||||
@ -202,7 +202,7 @@ application name, a device type and measurement type, like this:
|
|||||||
aspects : remotesensor, temperature
|
aspects : remotesensor, temperature
|
||||||
|
|
||||||
full name : environmentlogger.remotesensor.temperature
|
full name : environmentlogger.remotesensor.temperature
|
||||||
hash : fa7ddfab5213f916dea
|
hash : 4faf1b2e0a077e6a9d92fa051f256038
|
||||||
|
|
||||||
For the *single* destination, Reticulum will automatically append the associated public key as a
|
For the *single* destination, Reticulum will automatically append the associated public key as a
|
||||||
destination aspect before hashing. This is done to ensure only the correct destination is reached,
|
destination aspect before hashing. This is done to ensure only the correct destination is reached,
|
||||||
@ -683,7 +683,7 @@ Wire Format
|
|||||||
|
|
||||||
A Reticulum packet is composed of the following fields:
|
A Reticulum packet is composed of the following fields:
|
||||||
|
|
||||||
[HEADER 2 bytes] [ADDRESSES 10/20 bytes] [CONTEXT 1 byte] [DATA 0-477 bytes]
|
[HEADER 2 bytes] [ADDRESSES 16/32 bytes] [CONTEXT 1 byte] [DATA 0-465 bytes]
|
||||||
|
|
||||||
* The HEADER field is 2 bytes long.
|
* The HEADER field is 2 bytes long.
|
||||||
* Byte 1: [IFAC Flag], [Header Type], [Propagation Type], [Destination Type] and [Packet Type]
|
* Byte 1: [IFAC Flag], [Header Type], [Propagation Type], [Destination Type] and [Packet Type]
|
||||||
@ -695,15 +695,15 @@ Wire Format
|
|||||||
capabilities and configuration.
|
capabilities and configuration.
|
||||||
|
|
||||||
* The ADDRESSES field contains either 1 or 2 addresses.
|
* The ADDRESSES field contains either 1 or 2 addresses.
|
||||||
* Each address is 10 bytes long.
|
* Each address is 16 bytes long.
|
||||||
* The Header Type flag in the HEADER field determines
|
* The Header Type flag in the HEADER field determines
|
||||||
whether the ADDRESSES field contains 1 or 2 addresses.
|
whether the ADDRESSES field contains 1 or 2 addresses.
|
||||||
* Addresses are Reticulum hashes truncated to 10 bytes.
|
* Addresses are SHA-256 hashes truncated to 16 bytes.
|
||||||
|
|
||||||
* The CONTEXT field is 1 byte.
|
* The CONTEXT field is 1 byte.
|
||||||
* It is used by Reticulum to determine packet context.
|
* It is used by Reticulum to determine packet context.
|
||||||
|
|
||||||
* The DATA field is between 0 and 477 bytes.
|
* The DATA field is between 0 and 465 bytes.
|
||||||
* It contains the packets data payload.
|
* It contains the packets data payload.
|
||||||
|
|
||||||
IFAC Flag
|
IFAC Flag
|
||||||
@ -714,8 +714,8 @@ Wire Format
|
|||||||
|
|
||||||
Header Types
|
Header Types
|
||||||
-----------------
|
-----------------
|
||||||
type 1 0 Two byte header, one 10 byte address field
|
type 1 0 Two byte header, one 16 byte address field
|
||||||
type 2 1 Two byte header, two 10 byte address fields
|
type 2 1 Two byte header, two 16 byte address fields
|
||||||
|
|
||||||
|
|
||||||
Propagation Types
|
Propagation Types
|
||||||
@ -747,7 +747,7 @@ Wire Format
|
|||||||
HEADER FIELD DESTINATION FIELDS CONTEXT FIELD DATA FIELD
|
HEADER FIELD DESTINATION FIELDS CONTEXT FIELD DATA FIELD
|
||||||
_______|_______ ________________|________________ ________|______ __|_
|
_______|_______ ________________|________________ ________|______ __|_
|
||||||
| | | | | | | |
|
| | | | | | | |
|
||||||
01010000 00000100 [HASH1, 10 bytes] [HASH2, 10 bytes] [CONTEXT, 1 byte] [DATA]
|
01010000 00000100 [HASH1, 16 bytes] [HASH2, 16 bytes] [CONTEXT, 1 byte] [DATA]
|
||||||
|| | | | |
|
|| | | | |
|
||||||
|| | | | +-- Hops = 4
|
|| | | | +-- Hops = 4
|
||||||
|| | | +------- Packet Type = DATA
|
|| | | +------- Packet Type = DATA
|
||||||
@ -762,7 +762,7 @@ Wire Format
|
|||||||
HEADER FIELD DESTINATION FIELD CONTEXT FIELD DATA FIELD
|
HEADER FIELD DESTINATION FIELD CONTEXT FIELD DATA FIELD
|
||||||
_______|_______ _______|_______ ________|______ __|_
|
_______|_______ _______|_______ ________|______ __|_
|
||||||
| | | | | | | |
|
| | | | | | | |
|
||||||
00000000 00000111 [HASH1, 10 bytes] [CONTEXT, 1 byte] [DATA]
|
00000000 00000111 [HASH1, 16 bytes] [CONTEXT, 1 byte] [DATA]
|
||||||
|| | | | |
|
|| | | | |
|
||||||
|| | | | +-- Hops = 0
|
|| | | | +-- Hops = 0
|
||||||
|| | | +------- Packet Type = DATA
|
|| | | +------- Packet Type = DATA
|
||||||
@ -777,7 +777,7 @@ Wire Format
|
|||||||
HEADER FIELD IFAC FIELD DESTINATION FIELD CONTEXT FIELD DATA FIELD
|
HEADER FIELD IFAC FIELD DESTINATION FIELD CONTEXT FIELD DATA FIELD
|
||||||
_______|_______ ______|______ _______|_______ ________|______ __|_
|
_______|_______ ______|______ _______|_______ ________|______ __|_
|
||||||
| | | | | | | | | |
|
| | | | | | | | | |
|
||||||
10000000 00000111 [IFAC, N bytes] [HASH1, 10 bytes] [CONTEXT, 1 byte] [DATA]
|
10000000 00000111 [IFAC, N bytes] [HASH1, 16 bytes] [CONTEXT, 1 byte] [DATA]
|
||||||
|| | | | |
|
|| | | | |
|
||||||
|| | | | +-- Hops = 0
|
|| | | | +-- Hops = 0
|
||||||
|| | | +------- Packet Type = DATA
|
|| | | +------- Packet Type = DATA
|
||||||
|
@ -223,7 +223,7 @@ interfaces, similar to the ``ifconfig`` program.
|
|||||||
Traffic : 8.49 KB↑
|
Traffic : 8.49 KB↑
|
||||||
9.23 KB↓
|
9.23 KB↓
|
||||||
|
|
||||||
Reticulum Transport Instance <5245a8efe1788c6a70e1> running
|
Reticulum Transport Instance <5245a8efe1788c6a1cd36144a270e13b> running
|
||||||
|
|
||||||
.. code:: text
|
.. code:: text
|
||||||
|
|
||||||
@ -248,10 +248,10 @@ destinations on the Reticulum network.
|
|||||||
.. code:: text
|
.. code:: text
|
||||||
|
|
||||||
# Run rnpath
|
# Run rnpath
|
||||||
rnpath eca6f4e4dc26ae329e61
|
rnpath c89b4da064bf66d280f0e4d8abfd9806
|
||||||
|
|
||||||
# Example output
|
# Example output
|
||||||
Path found, destination <eca6f4e4dc26ae329e61> is 4 hops away via <56b115c30cd386cad69c> on TCPInterface[Testnet/frankfurt.rns.unsigned.io:4965]
|
Path found, destination <c89b4da064bf66d280f0e4d8abfd9806> is 4 hops away via <f53a1c4278e0726bb73fcc623d6ce763> on TCPInterface[Testnet/frankfurt.connect.reticulu.network:4965]
|
||||||
|
|
||||||
.. code:: text
|
.. code:: text
|
||||||
|
|
||||||
@ -285,11 +285,11 @@ destinations will not have this option enabled, and will not be probable.
|
|||||||
.. code:: text
|
.. code:: text
|
||||||
|
|
||||||
# Run rnprobe
|
# Run rnprobe
|
||||||
rnprobe example_utilities.echo.request 9382f334de63217a4278
|
rnprobe example_utilities.echo.request 2d03725b327348980d570f739a3a5708
|
||||||
|
|
||||||
# Example output
|
# Example output
|
||||||
Sent 16 byte probe to <9382f334de63217a4278>
|
Sent 16 byte probe to <2d03725b327348980d570f739a3a5708>
|
||||||
Valid reply received from <9382f334de63217a4278>
|
Valid reply received from <2d03725b327348980d570f739a3a5708>
|
||||||
Round-trip time is 38.469 milliseconds over 2 hops
|
Round-trip time is 38.469 milliseconds over 2 hops
|
||||||
|
|
||||||
.. code:: text
|
.. code:: text
|
||||||
@ -319,10 +319,10 @@ files through Reticulum.
|
|||||||
|
|
||||||
# Run rncp on the receiving system, specifying which identities
|
# Run rncp on the receiving system, specifying which identities
|
||||||
# are allowed to send files
|
# are allowed to send files
|
||||||
rncp --receive -a 940ea3f9e1037d38758f -a e28d5aee4317c24a9041
|
rncp --receive -a 1726dbad538775b5bf9b0ea25a4079c8 -a c50cc4e4f7838b6c31f60ab9032cbc62
|
||||||
|
|
||||||
# From another system, copy a file to the receiving system
|
# From another system, copy a file to the receiving system
|
||||||
rncp ~/path/to/file.tgz 256320d405d6d525d1e9
|
rncp ~/path/to/file.tgz 73cbd378bb0286ed11a707c13447bb1e
|
||||||
|
|
||||||
You can specify as many allowed senders as needed, or complete disable authentication.
|
You can specify as many allowed senders as needed, or complete disable authentication.
|
||||||
|
|
||||||
@ -362,21 +362,21 @@ output.
|
|||||||
|
|
||||||
# Run rnx on the listening system, specifying which identities
|
# Run rnx on the listening system, specifying which identities
|
||||||
# are allowed to execute commands
|
# are allowed to execute commands
|
||||||
rncp --listen -a 8111c4ff2968ab0c1286 -a 590256654482b4ba4038
|
rncp --listen -a 941bed5e228775e5a8079fc38b1ccf3f -a 1b03013c25f1c2ca068a4f080b844a10
|
||||||
|
|
||||||
# From another system, run a command
|
# From another system, run a command
|
||||||
rnx ad9a4c9da60089d41c29 "cat /proc/cpuinfo"
|
rnx 7a55144adf826958a9529a3bcf08b149 "cat /proc/cpuinfo"
|
||||||
|
|
||||||
# Or enter the interactive mode pseudo-shell
|
# Or enter the interactive mode pseudo-shell
|
||||||
rnx ad9a4c9da60089d41c29 -x
|
rnx 7a55144adf826958a9529a3bcf08b149 -x
|
||||||
|
|
||||||
# The default identity file is stored in
|
# The default identity file is stored in
|
||||||
# ~/.reticulum/identities/rnx, but you can use
|
# ~/.reticulum/identities/rnx, but you can use
|
||||||
# another one, which will be created if it does
|
# another one, which will be created if it does
|
||||||
# not already exist
|
# not already exist
|
||||||
rnx ad9a4c9da60089d41c29 -i /path/to/identity
|
rnx 7a55144adf826958a9529a3bcf08b149 -i /path/to/identity -x
|
||||||
|
|
||||||
You can specify as many allowed senders as needed, or complete disable authentication.
|
You can specify as many allowed senders as needed, or completely disable authentication.
|
||||||
|
|
||||||
.. code:: text
|
.. code:: text
|
||||||
|
|
||||||
|
@ -50,7 +50,7 @@ What does Reticulum Offer?
|
|||||||
|
|
||||||
* Low cost of keeping links open at only 0.62 bits per second
|
* Low cost of keeping links open at only 0.62 bits per second
|
||||||
|
|
||||||
* Reliable and efficient transfer of arbritrary amounts of data
|
* Reliable and efficient transfer of arbitrary amounts of data
|
||||||
|
|
||||||
* Reticulum can handle a few bytes of data or files of many gigabytes
|
* Reticulum can handle a few bytes of data or files of many gigabytes
|
||||||
|
|
||||||
|
Loading…
Reference in New Issue
Block a user