API Reference¶
This reference guide lists and explains all classes exposed by the RNS API.
Classes¶
Communication over a Reticulum network is achieved using a set of classes exposed by RNS.
Reticulum¶
- class RNS.Reticulum(configdir=None)¶
This class is used to initialise access to Reticulum within a program. You must create exactly one instance of this class before carrying out any other RNS operations, such as creating destinations or sending traffic. Every independently executed program must create their own instance of the Reticulum class, but Reticulum will automatically handle inter-program communication on the same system, and expose all connected programs to external interfaces as well.
As soon as an instance of this class is created, Reticulum will start opening and configuring any hardware devices specified in the supplied configuration.
Currently the first running instance must be kept running while other local instances are connected, as the first created instance will act as a master instance that directly communicates with external hardware such as modems, TNCs and radios. If a master instance is asked to exit, it will not exit until all client processes have terminated (unless killed forcibly).
If you are running Reticulum on a system with several different programs that use RNS starting and terminating at different times, it will be advantageous to run a master RNS instance as a daemon for other programs to use on demand.
- static should_allow_unencrypted()¶
Returns whether unencrypted links are allowed by the current configuration.
- Returns
True if the current running configuration allows downgrading links to plaintext. False if not.
- static should_use_implicit_proof()¶
Returns whether proofs sent are explicit or implicit.
- Returns
True if the current running configuration specifies to use implicit proofs. False if not.
- static transport_enabled()¶
Returns whether Transport is enabled for the running instance.
When Transport is enabled, Reticulum will route traffic for other peers, respond to path requests and pass announces over the network.
- Returns
True if Transport is enabled, False if not.
Identity¶
- class RNS.Identity(create_keys=True)¶
This class is used to manage identities in Reticulum. It provides methods for encryption, decryption, signatures and verification, and is the basis for all encrypted communication over Reticulum networks.
- Parameters
create_keys – Specifies whether new encryption and signing keys should be generated.
- CURVE = 'Curve25519'¶
The curve used for Elliptic Curve DH key exchanges
- KEYSIZE = 512¶
X25519 key size in bits. A complete key is the concatenation of a 256 bit encryption key, and a 256 bit signing key.
- TRUNCATED_HASHLENGTH = 80¶
Constant specifying the truncated hash length (in bits) used by Reticulum for addressable hashes and other purposes. Non-configurable.
- static recall(destination_hash)¶
Recall identity for a destination hash.
- Parameters
destination_hash – Destination hash as bytes.
- Returns
An RNS.Identity instance that can be used to create an outgoing RNS.Destination, or None if the destination is unknown.
- static recall_app_data(destination_hash)¶
Recall last heard app_data for a destination hash.
- Parameters
destination_hash – Destination hash as bytes.
- Returns
Bytes containing app_data, or None if the destination is unknown.
- static full_hash(data)¶
Get a SHA-256 hash of passed data.
- Parameters
data – Data to be hashed as bytes.
- Returns
SHA-256 hash as bytes
- static truncated_hash(data)¶
Get a truncated SHA-256 hash of passed data.
- Parameters
data – Data to be hashed as bytes.
- Returns
Truncated SHA-256 hash as bytes
- static get_random_hash()¶
Get a random SHA-256 hash.
- Parameters
data – Data to be hashed as bytes.
- Returns
Truncated SHA-256 hash of random data as bytes
- static from_file(path)¶
Create a new RNS.Identity instance from a file. Can be used to load previously created and saved identities into Reticulum.
- Parameters
path – The full path to the saved RNS.Identity data
- Returns
A RNS.Identity instance, or None if the loaded data was invalid.
- static from_bytes(prv_bytes)¶
Create a new RNS.Identity instance from bytes of private key. Can be used to load previously created and saved identities into Reticulum.
- Parameters
prv_bytes – The bytes of private a saved private key. HAZARD! Never not use this to generate a new key by feeding random data in prv_bytes.
- Returns
A RNS.Identity instance, or None if the bytes data was invalid.
- get_private_key()¶
- Returns
The private key as bytes
- get_public_key()¶
- Returns
The public key as bytes
- load_private_key(prv_bytes)¶
Load a private key into the instance.
- Parameters
prv_bytes – The private key as bytes.
- Returns
True if the key was loaded, otherwise False.
- load_public_key(pub_bytes)¶
Load a public key into the instance.
- Parameters
pub_bytes – The public key as bytes.
- Returns
True if the key was loaded, otherwise False.
- to_file(path)¶
Saves the identity to a file. This will write the private key to disk, and anyone with access to this file will be able to decrypt all communication for the identity. Be very careful with this method.
- Parameters
path – The full path specifying where to save the identity.
- Returns
True if the file was saved, otherwise False.
- encrypt(plaintext)¶
Encrypts information for the identity.
- Parameters
plaintext – The plaintext to be encrypted as bytes.
- Returns
Ciphertext token as bytes.
- Raises
KeyError if the instance does not hold a public key.
- decrypt(ciphertext_token)¶
Decrypts information for the identity.
- Parameters
ciphertext – The ciphertext to be decrypted as bytes.
- Returns
Plaintext as bytes, or None if decryption fails.
- Raises
KeyError if the instance does not hold a private key.
- sign(message)¶
Signs information by the identity.
- Parameters
message – The message to be signed as bytes.
- Returns
Signature as bytes.
- Raises
KeyError if the instance does not hold a private key.
- validate(signature, message)¶
Validates the signature of a signed message.
- Parameters
signature – The signature to be validated as bytes.
message – The message to be validated as bytes.
- Returns
True if the signature is valid, otherwise False.
- Raises
KeyError if the instance does not hold a public key.
Destination¶
- class RNS.Destination(identity, direction, type, app_name, *aspects)¶
A class used to describe endpoints in a Reticulum Network. Destination instances are used both to create outgoing and incoming endpoints. The destination type will decide if encryption, and what type, is used in communication with the endpoint. A destination can also announce its presence on the network, which will also distribute necessary keys for encrypted communication with it.
- Parameters
identity – An instance of RNS.Identity. Can hold only public keys for an outgoing destination, or holding private keys for an ingoing.
direction –
RNS.Destination.IN
orRNS.Destination.OUT
type –
RNS.Destination.SINGLE
,RNS.Destination.GROUP
orRNS.Destination.PLAIN
.app_name – A string specifying the app name.
*aspects – Any non-zero number of string arguments.
- static full_name(app_name, *aspects)¶
- Returns
A string containing the full human-readable name of the destination, for an app_name and a number of aspects.
- static app_and_aspects_from_name(full_name)¶
- Returns
A tuple containing the app name and a list of aspects, for a full-name string.
- static hash_from_name_and_identity(full_name, identity)¶
- Returns
A destination name in adressable hash form, for a full name string and Identity instance.
- static hash(app_name, *aspects)¶
- Returns
A destination name in adressable hash form, for an app_name and a number of aspects.
- announce(app_data=None, path_response=False)¶
Creates an announce packet for this destination and broadcasts it on all relevant interfaces. Application specific data can be added to the announce.
- Parameters
app_data – bytes containing the app_data.
path_response – Internal flag used by RNS.Transport. Ignore.
- set_link_established_callback(callback)¶
Registers a function to be called when a link has been established to this destination.
- Parameters
callback – A function or method to be called.
- set_packet_callback(callback)¶
Registers a function to be called when a packet has been received by this destination.
- Parameters
callback – A function or method to be called.
- set_proof_requested_callback(callback)¶
Registers a function to be called when a proof has been requested for a packet sent to this destination. Allows control over when and if proofs should be returned for received packets.
- Parameters
callback – A function or method to be called. The callback must return one of True or False. If the callback returns True, a proof will be sent. If it returns False, a proof will not be sent.
- set_proof_strategy(proof_strategy)¶
Sets the destinations proof strategy.
- Parameters
proof_strategy – One of
RNS.Destination.PROVE_NONE
,RNS.Destination.PROVE_ALL
orRNS.Destination.PROVE_APP
. IfRNS.Destination.PROVE_APP
is set, the proof_requested_callback will be called to determine whether a proof should be sent or not.
- register_request_handler(path, response_generator=None, allow=0, allowed_list=None)¶
Registers a request handler.
- Parameters
path – The path for the request handler to be registered.
response_generator – A function or method with the signature response_generator(path, data, request_id, remote_identity, requested_at) to be called. Whatever this funcion returns will be sent as a response to the requester. If the function returns
None
, no response will be sent.allow – One of
RNS.Destination.ALLOW_NONE
,RNS.Destination.ALLOW_ALL
orRNS.Destination.ALLOW_LIST
. IfRNS.Destination.ALLOW_LIST
is set, the request handler will only respond to requests for identified peers in the supplied list.allowed_list – A list of bytes-like RNS.Identity hashes.
- Raises
ValueError
if any of the supplied arguments are invalid.
- deregister_request_handler(path)¶
Deregisters a request handler.
- Parameters
path – The path for the request handler to be deregistered.
- Returns
True if the handler was deregistered, otherwise False.
- create_keys()¶
For a
RNS.Destination.GROUP
type destination, creates a new symmetric key.- Raises
TypeError
if called on an incompatible type of destination.
- get_private_key()¶
For a
RNS.Destination.GROUP
type destination, returns the symmetric private key.- Raises
TypeError
if called on an incompatible type of destination.
- load_private_key(key)¶
For a
RNS.Destination.GROUP
type destination, loads a symmetric private key.- Parameters
key – A bytes-like containing the symmetric key.
- Raises
TypeError
if called on an incompatible type of destination.
- encrypt(plaintext)¶
Encrypts information for
RNS.Destination.SINGLE
orRNS.Destination.GROUP
type destination.- Parameters
plaintext – A bytes-like containing the plaintext to be encrypted.
- Raises
ValueError
if destination does not hold a necessary key for encryption.
- decrypt(ciphertext)¶
Decrypts information for
RNS.Destination.SINGLE
orRNS.Destination.GROUP
type destination.- Parameters
ciphertext – Bytes containing the ciphertext to be decrypted.
- Raises
ValueError
if destination does not hold a necessary key for decryption.
- sign(message)¶
Signs information for
RNS.Destination.SINGLE
type destination.- Parameters
message – Bytes containing the message to be signed.
- Returns
A bytes-like containing the message signature, or None if the destination could not sign the message.
- set_default_app_data(app_data=None)¶
Sets the default app_data for the destination. If set, the default app_data will be included in every announce sent by the destination, unless other app_data is specified in the announce method.
- Parameters
app_data – A bytes-like containing the default app_data, or a callable returning a bytes-like containing the app_data.
- clear_default_app_data()¶
Clears default app_data previously set for the destination.
Packet¶
- class RNS.Packet(destination, data, packet_type=0, context=0, transport_type=0, header_type=0, transport_id=None, attached_interface=None, create_receipt=True)¶
The Packet class is used to create packet instances that can be sent over a Reticulum network. Packets to will automatically be encrypted if they are adressed to a
RNS.Destination.SINGLE
destination,RNS.Destination.GROUP
destination or a RNS.Link.For
RNS.Destination.GROUP
destinations, Reticulum will use the pre-shared key configured for the destination.For
RNS.Destination.SINGLE
destinations and RNS.Link destinations, reticulum will use ephemeral keys, and offers Forward Secrecy.- Parameters
destination – A RNS.Destination instance to which the packet will be sent.
data – The data payload to be included in the packet as bytes.
create_receipt – Specifies whether a RNS.PacketReceipt should be created when instantiating the packet.
type – Internal use by RNS.Transport. Defaults to
RNS.Packet.DATA
, and should not be specified.context – Internal use by RNS.Transport. Ignore.
transport_type – Internal use by RNS.Transport. Ignore.
transport_id – Internal use by RNS.Transport. Ignore.
attached_interface – Internal use by RNS.Transport. Ignore.
- ENCRYPTED_MDU = 383¶
The maximum size of the payload data in a single encrypted packet
- PLAIN_MDU = 477¶
The maximum size of the payload data in a single unencrypted packet
- send()¶
Sends the packet.
- Returns
A RNS.PacketReceipt instance if create_receipt was set to True when the packet was instantiated, if not returns None. If the packet could not be sent False is returned.
- resend()¶
Re-sends the packet.
- Returns
A RNS.PacketReceipt instance if create_receipt was set to True when the packet was instantiated, if not returns None. If the packet could not be sent False is returned.
Packet Receipt¶
- class RNS.PacketReceipt(packet)¶
The PacketReceipt class is used to receive notifications about RNS.Packet instances sent over the network. Instances of this class should never be created manually, but always returned from a the send() method of a RNS.Packet instance.
- get_status()¶
- Returns
The status of the associated RNS.Packet instance. Can be one of
RNS.PacketReceipt.SENT
,RNS.PacketReceipt.DELIVERED
,RNS.PacketReceipt.FAILED
orRNS.PacketReceipt.CULLED
.
- get_rtt()¶
- Returns
The round-trip-time in seconds
- set_timeout(timeout)¶
Sets a timeout in seconds
- Parameters
timeout – The timeout in seconds.
- set_delivery_callback(callback)¶
Sets a function that gets called if a successfull delivery has been proven.
- Parameters
callback – A callable with the signature callback(packet_receipt)
- set_timeout_callback(callback)¶
Sets a function that gets called if the delivery times out.
- Parameters
callback – A callable with the signature callback(packet_receipt)
Link¶
- class RNS.Link(destination=None, established_callback=None, closed_callback=None, owner=None, peer_pub_bytes=None, peer_sig_pub_bytes=None)¶
This class.
- Parameters
destination – A RNS.Destination instance which to establish a link to.
established_callback – A function or method with the signature callback(link) to be called when the link has been established.
closed_callback – A function or method with the signature callback(link) to be called when the link is closed.
owner – Internal use by RNS.Transport, ignore this argument.
peer_pub_bytes – Internal use, ignore this argument.
peer_sig_pub_bytes – Internal use, ignore this argument.
- CURVE = 'Curve25519'¶
The curve used for Elliptic Curve DH key exchanges
- DEFAULT_TIMEOUT = 60.0¶
Default timeout for link establishment in seconds.
- KEEPALIVE = 360¶
Interval for sending keep-alive packets on established links in seconds.
- identify(identity)¶
Identifies the initiator of the link to the remote peer. This can only happen once the link has been established, and is carried out over the encrypted link. The identity is only revealed to the remote peer, and initiator anonymity is thus preserved. This method can be used for authentication.
- Parameters
identity – An RNS.Identity instance to identify as.
- request(path, data=None, response_callback=None, failed_callback=None, timeout=None)¶
Sends a request to the remote peer.
- Parameters
path – The request path.
response_callback – An optional function or method with the signature response_callback(request_receipt) to be called when a response is received. See the Request Example for more info.
failed_callback – An optional function or method with the signature failed_callback(request_receipt) to be called when a request fails. See the Request Example for more info.
timeout – An optional timeout in seconds for the request. If None is supplied, this defaults to
RNS.Packet.TIMEOUT
.
- no_inbound_for()¶
- Returns
The time in seconds since last inbound packet on the link.
- no_outbound_for()¶
- Returns
The time in seconds since last outbound packet on the link.
- inactive_for()¶
- Returns
The time in seconds since activity on the link.
- get_remote_identity()¶
- Returns
The identity of the remote peer, if it is known
- teardown()¶
Closes the link and purges encryption keys. New keys will be used if a new link to the same destination is established.
- set_packet_callback(callback)¶
Registers a function to be called when a packet has been received over this link.
- Parameters
callback – A function or method with the signature callback(message, packet) to be called.
- set_resource_callback(callback)¶
Registers a function to be called when a resource has been advertised over this link. If the function returns True the resource will be accepted. If it returns False it will be ignored.
- Parameters
callback – A function or method with the signature callback(resource) to be called.
- set_resource_started_callback(callback)¶
Registers a function to be called when a resource has begun transferring over this link.
- Parameters
callback – A function or method with the signature callback(resource) to be called.
- set_resource_concluded_callback(callback)¶
Registers a function to be called when a resource has concluded transferring over this link.
- Parameters
callback – A function or method with the signature callback(resource) to be called.
- set_remote_identified_callback(callback)¶
Registers a function to be called when an initiating peer has identified over this link.
- Parameters
callback – A function or method with the signature callback(identity) to be called.
- set_resource_strategy(resource_strategy)¶
Sets the resource strategy for the link.
- Parameters
resource_strategy – One of
RNS.Link.ACCEPT_NONE
,RNS.Link.ACCEPT_ALL
orRNS.Link.ACCEPT_APP
. IfRNS.Link.ACCEPT_APP
is set, the resource_callback will be called to determine whether the resource should be accepted or not.- Raises
TypeError if the resource strategy is unsupported.
- disable_encryption()¶
HAZARDOUS. This will downgrade the link to encryptionless. All information over the link will be sent in plaintext. Never use this in production applications. Should only be used for debugging purposes, and will disappear in a future version.
If encryptionless links are not explicitly allowed in the users configuration file, Reticulum will terminate itself along with the client application and throw an error message to the user.
Resource¶
- class RNS.Resource(data, link, advertise=True, auto_compress=True, callback=None, progress_callback=None, timeout=None, segment_index=1, original_hash=None, request_id=None, is_response=False)¶
The Resource class allows transferring arbitrary amounts of data over a link. It will automatically handle sequencing, compression, coordination and checksumming.
- Parameters
data – The data to be transferred. Can be bytes or an open file handle. See the Filetransfer Example for details.
link – The RNS.Link instance on which to transfer the data.
advertise – Whether to automatically advertise the resource. Can be True or False.
auto_compress – Whether to auto-compress the resource. Can be True or False.
callback – A callable with the signature callback(resource). Will be called when the resource transfer concludes.
progress_callback – A callable with the signature callback(resource). Will be called whenever the resource transfer progress is updated.
segment_index – Internal use, ignore.
original_hash – Internal use, ignore.
is_request – Internal use, ignore.
is_response – Internal use, ignore.
- advertise()¶
Advertise the resource. If the other end of the link accepts the resource advertisement it will begin transferring.
- cancel()¶
Cancels transferring the resource.
- progress()¶
- Returns
The current progress of the resource transfer as a float between 0.0 and 1.0.
Transport¶
- class RNS.Transport¶
- static register_announce_handler(handler)¶
Registers an announce handler.
- Parameters
handler – Must be an object with an aspect_filter attribute and a received_announce(destination_hash, announced_identity, app_data) callable. See the Announce Example for more info.
- static deregister_announce_handler(handler)¶
Deregisters an announce handler.
- Parameters
handler – The announce handler to be deregistered.
- static has_path(destination_hash)¶
- Parameters
destination_hash – A destination hash as bytes.
- Returns
True if a path to the destination is known, otherwise False.
- static request_path(destination_hash)¶
Requests a path to the destination from the network. If another reachable peer on the network knows a path, it will announce it.
- Parameters
destination_hash – A destination hash as bytes.