Aranya Documentation An overview of the Aranya project

Walkthrough

The goal of this guide is to utilize Aranya, RBAC, and AFC for sending end-to-end encrypted data between applications. See the core concepts section for more details on the components used in this walkthrough. To see an example implementation with code, see the examples in the Aranya repo. This guide focuses on the high level operations and does not provide code.

This guide assumes the default policy is being used for authorization and key management.

The first step is to create config files for each Aranya daemon and run a daemon for each device that will be part of the team. At startup, the daemon will generate a keybundle containing the device identity and other cryptographic keys, if that information has not already been generated.

Once the device daemons have been started, create a team of devices on the Aranya graph by having the team owner device create the team and add the public key bundles of the other devices to the team. Each device must configure other devices on the network as sync peers in order to receive the latest updates to the Aranya graph as new commands are added to the graph. Each operation such as creating a team, adding a device to a team, assigning permissions to use labels, etc. adds commands to the Aranya graph which peers must sync via the network in order to stay up to date with the state of the team.

Once the team has been created, assign labels to pairs of devices that are allowed to communicate securely with each other via AFC channels. Pairs of devices with the role of Member can create AFC channels with a certain label as long as both devices have permission to use the label assigned to them. Once an AFC channel has been created between two devices, the creator/sender can encrypt data with seal(), send it to the receiver device over a transport implemented in the application, then the receiver device can decrypt the data with open().

Building Aranya Daemon

Pre-built daemon executable for various platforms are attached to the latest release. If there is already an executable available for your architecture, building the daemon is optional.

The following platforms are currently supported:

  • linux/amd64
  • linux/arm64
  • macos/amd64

Other unix-based platforms with matching hardware architectures are likely supported.

Platforms that are not yet supported:

  • windows
  • linux/arm32

The following dependencies must be present on the machine before building Aranya:

Checkout the aranya repo locally.

To build the daemon, invoke:

$ cargo make build

The daemon executable will be generated at: <repo>/target/release/aranya-daemon

Daemon Config Files

At runtime, each daemon loads a configuration file. This config file includes syncer network address configuration and a path to non-volatile Aranya graph storage. A complete example of a daemon configuration file can be found here.

Based on this example, create a configuration file for each device daemon. Remember to change the IP addresses, ports, and other device-specific values for each device.

Or, directly use the daemon configuration files from the C example. This example has configs for each device in the tutorial.

Now that the daemons have been configured, we can run them!

Running The Aranya Daemon

Once the daemon has been built, it can be run like this:

$ target/release/aranya-daemon <path to daemon config file>

Creating an Aranya Team

We are now ready to create an Aranya team and set up AFC channels to communicate between devices on the team. The step-by-step process for each of these portions is listed below, followed by an outline of the relevant APIs and reference documentation needed to do the integration in the desired language.

  1. Create a daemon config file for each device that will be on the Aranya team.
  2. Start the daemon executables for each device on the Aranya team.
  3. Owner device creates a team.
  4. Owner device adds other devices to team using their public key bundles: admin device, operator device, member devices.
  5. Each device on the team should configure sync peers in order to stay up-to-date with the latest graph commands that have been published for the team.

Setting Up Roles (RBAC), Permissions, Labels

Since permissions are managed via RBAC roles rather than directly assigning permissions to devices, “Device with AssignRole permission” means “Device that has been assigned a role that has the AssignRole permission”.

Once an Aranya team has been created, roles/permissions/labels must be setup before peers are allowed to communicate via AFC channels:

  1. Team owner sets up default roles with setup_default_roles(). E.g. Owner, Admin, Operator, Member. Note that the Owner role has permission to do everything by default. It is recommended to only use the Owner role to bootstrap the team by delegating/segmenting permissions to other roles.
  2. Team owner assigns the default roles to devices on the team. Since the Member role has CanUseAfc permission by default, it is recommended to assign the Member role to any devices that will create/receive an AFC channel. Otherwise, you would need to assign the CanUseAfc permission to each device’s role before usage of AFC channels would be permitted.
  3. Device with CreateLabel permission creates labels. Note that the Owner and Admin roles have the CreateLabel permission by default.
  4. Device with AssignLabel permission assigns labels to devices to grant them permission to use AFC channels with those labels. Since the Member role has CanUseAfc permission by default, it is recommended to assign labels to devices that have been assigned the Member role. Otherwise, you would need to assign the CanUseAfc permission to each device’s role before usage of AFC channels would be permitted. Note that Owner and Operator roles have the AssignLabel permission by default.
  5. Optional step: device with CanChangeRolePerms assigns CanUseAfc permission to any role that needs to be able to create/receive an AFC channel. Note that the Member role has CanUseAfc permission by default so this step may not be required if only devices with the Member role are using AFC channels.

Sending and Receiving Data With AFC Channels

Now that RBAC permissions have been configured, peers can communicate via AFC channels:

  1. Devices with the Member role create AFC channels with peer devices on the network using assigned labels. Two member devices that have the same label assigned to them may create an AFC channel between themselves using that label as long as they both have the CanUseAfc permission. The creator of the channel is the sender which means it is allowed to encrypt data with seal(). The receiver of the channel is the reader which means it is allowed to decrypt data with open().
  2. Member devices seal()/open() data via AFC channels.
  3. The application is responsible for sending datagrams encrypted by seal() between devices via whatever application level transport it chooses.

Getting Started With Rust

Rust Example

Rust example

Rust API Docs

Rust API

Method Cheat Sheet

Abridged. There are additional functions for queries and other functions.

Client methods:

  • create_team() - Create an Aranya team
  • add_team(...) - Add an Aranya team to a device

Team methods:

  • add_device_to_team(...) - Add a device to the Aranya team
  • add_sync_peer(...) - Add peer to sync with
  • create_label(...) - Create a new label
  • assign_label(...) - Assign an label to a device

Afc methods:

  • create_channel(...) - Creates a unidirectional AFC channel. The creator of the channel can only seal() and the receiver of the channel can only open().
  • accept_channel(...) - Receives a ctrl message from the creator of an AFC channel in order to create the open() side of the channel.
  • seal(...) - Uses an AFC channel to encrypt a plaintext
  • open(...) - Decrypts an encrypted AFC datagram that was originally encrypted with seal()

Getting Started With C

C Example

C Example

C API Docs

C API

Method Cheat Sheet

Abridged. There are additional functions for queries and other functions.

  • aranya_create_team(...) - Create an Aranya team
  • aranya_add_team(...) - Add an Aranya team to a device
  • aranya_add_device_to_team(...) - Add a device to the Aranya team
  • aranya_add_sync_peer(...) - Add peer to sync with
  • aranya_create_label(...) - Create a new label
  • aranya_assign_label(...) - Assign an label to a device
  • aranya_afc_create_channel(...) - Create an AFC channel, creating a control message for the peer to setup the channel
  • aranya_afc_accept_channel(...) - Accept an AFC channel, consuming the control message to setup the channel
  • aranya_afc_channel_seal(...) - Uses an AFC channel to encrypt a plaintext
  • aranya_afc_channel_open(...) - Decrypts an encrypted AFC datagram that was originally encrypted with seal()

Security Considerations

This getting started guide is intended as an example to be run on a single machine. As such, a single machine is used to generate all key bundles and run all daemons under a single user account.

In production, each Aranya device key bundle should be created under separate user accounts on their respective machines and daemon working directories should only grant read-write access to their respective daemon executable. This avoids a single access point for all Aranya device keys in case a machine or user account is compromised.

Policy

Permission for devices to execute the operations outlined in this guide are determined by the implemented policy.