Adding a device to Aranya requires completing an onboarding procedure. This onboarding procedure is a series of out-of-band exchanges and actions that devices must perform to properly establish their cryptographic identities within the team.
Prerequisites:
AddDevice permission.Onboarding happens in three phases:
AddDevice permission, using add_device().add_team().Phases 1 and 2 can happen in either order.
AddDevice permissionThe new device first transfers its PublicKeyBundle to the device that will add it to the team. The PublicKeyBundle contains the new device’s public keys, and is used by the Aranya graph to authenticate and authorize actions. It contains no secrets, but it should be transferred over a channel that protects its integrity, so that the adding device knows the keys really belong to the new device.
The new device can get its bundle with Client::get_public_key_bundle() and its device ID with Client::get_device_id(). The device ID is used to refer to the device in later calls, such as assigning roles and labels.
The adding device calls Team::add_device() with the bundle, an optional initial role and a rank. The rank must be less than or equal to the adding device’s own rank. See Access Management for how roles and ranks work.
The new device needs to track the team in local storage. The adding device shares the team ID with the new device out of band, and the new device calls Client::add_team() with an AddTeamConfig containing that team ID. The team ID is not a secret.
No other team secret needs to be shared. Sync is authenticated with each device’s certificate, so the PSK seeds used before Aranya 7.0 are no longer needed.
Finally, the new device needs to sync the command that added it to the team. It can sync with any device on the team that has this command.
Each device calls Team::add_sync_peer() with the other device’s sync address. The address’s host must match the SAN in that device’s certificate. The daemons connect over QUIC and authenticate each other with mTLS before exchanging commands.
Sync peers are not persisted. The daemon keeps its list of sync peers in memory only. Each time a daemon restarts, the application must call add_sync_peer() again for each of its peers. Until it does, the device won’t sync.
Once the new device has synced, it can confirm it is on the team by calling Team::devices() and checking that its own device ID is listed, or by calling Team::device(id).role() to check its role.
Note: It is common to see “no such storage” errors on the device being added if it syncs before the team is fully initialized locally. These are non-fatal errors and will resolve once the device has synced the command that added it and has set up the local storage.