William/Reticulum
1
0
Fork 0
mirror of https://github.com/markqvist/Reticulum.git synced 2024-11-05 05:40:14 +00:00
Code Issues Packages Projects Releases Wiki Activity

Updated documentation to reflect 128-bit address space

Browse Source
This commit is contained in:
Mark Qvist 2022-07-01 23:30:20 +02:00
parent bc39a1acf1
commit 304610c682
6 changed files with 50 additions and 47 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
docs/source/conf.py
View File

@ -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 ---------------------------------------------------

23
docs/source/gettingstartedfast.rst
View File

@ -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

4
docs/source/support.rst
View File

@ -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

40
docs/source/understanding.rst
View File

@ -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

26
docs/source/using.rst
View File

@ -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

2
docs/source/whatis.rst
View File

@ -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