Onboarding Devices to Your Cluster
Onboarding happens one time for each device you add to your cluster.
Once you have a single device up and running, it can be your “root”, and it can allow new devices to join the cluster. This greatly simplifies settings, as you don’t have to enter frequencies, encryption keys, etc on multiple devices.
In fact, you never have to enter an encryption key anywhere, they are automatically generated and you don’t even have to think about them.
Private Mesh Clusters
Any ChatterBox device belongs to one or more private mesh clusters. When you first start up and initialize a ChatterBox device, it creates its own brand new cluster, and also is forever the root of that cluster. In many cases this is a temporary / throwaway cluster (if it’s about to join an existing one).
The Cluster Root
The cluster root is essentially the admin of a cluster.
Only the root is allowed to add more devices to the cluster, and all devices automatically trust any new devices the root decides to onboard.
The root device generates a set of symmetric keys that will be a cluster-wide secret. The root device also generates its own public/private keypair for encryption and signing.
Both of these are generated using a hardware RNG that is part of the device.
Additional Devices (non-root)
All other devices in the cluster must be invited/onboarded. This includes nodes, communicators, sensors, etc.
They will essentially be invisible until they have the symmetric keys or frequency hopping pattern until they are onboarded.
Onboarding: Trusting a new Device
The two devices need to be within LoRa range, the cluster root selects “onboard a device” in settings, and the new device selects “join cluster”.
The two devices exchange public keys via LoRa, and the remaining interaction is automatic and encrypted.
During onboarding, the root device will:
Generate a certificate (signature) for the new device
Issue the new device a a cluster-specific identifier
Transmit the cluster’s identifier, symmetric keys, frequency range, and few other things
Once the interaction is complete, the new device is considered “onboarded” and is now a trusted part of the cluster.
This new device will now be listening and transmitting on the cluster-specific rotating frequency pattern, using its own private key for signing / encrypting, as well as the cluster’s symmetric keys for various purposes.
Key Exchanges: In the Wild
After a device has been onboarded into the cluster, it will be listening / pinging / transmitting on the same rotating frequency as the rest of the cluster, and claiming to be part of the cluster.
Existing on-cluster devices will not recognize this new device, and will challenge it for proof within a minute or two.
Upon being challenged, any device will transmit or broadcast its public key, identifier, alias, and root-signed signature of those things, as proof that it belongs to the cluster. The challenger also provides the same (id, alias, public key, & certificate).
From that point forward, both devices trust one another, and will begin to utilize one another for mesh caching, routing, and other cluster functions.
Key Forwarding
If allowed by your device (it’s a setting), devices do not need to be directly within RF range to exchange keys. In this scenario, a mesh packet will be received that has an unknown device as the sender or recipient.
Upon receiving this packet to or from an unknown device, the recipient will broadcast a request for the unknown device’s public key.
Any already-trusted device can then transmit the key to the requestor, and the public key will be trusted, along with the previously-unknown device.
This can be disabled with a setting.
