Aranya Documentation An overview of the Aranya project

Onboarding

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:

  1. The new device has a certificate signed by a CA that the other devices on the team trust. The certificate’s subject alternative name must match the address other devices will use to reach it. See Certificates.
  2. The new device has a daemon running. Starting the daemon generates the device’s cryptographic keys if they do not already exist. Private keys are stored locally in the keystore and must be kept secret.
  3. A team has been created by the owner device, and a device on the team has a role with the AddDevice permission.

Onboarding happens in three phases:

  1. The new device is added to the team by a device whose role has the AddDevice permission, using add_device().
  2. The new device adds the team to its local storage by calling add_team().
  3. The devices configure each other as sync peers, and the new device syncs the command that added it to the team.

Phases 1 and 2 can happen in either order.

Phase 1: Device Addition by Role with AddDevice permission

The 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.

Phase 2: Team added locally by device

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.

Phase 3: Synchronization Setup

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.

Verifying onboarding

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.