Access Management (Control Plane)

Aranya allows the application to enforce Identity and Access Management (IDAM) via decentralized Role-Based Access Control (RBAC) and Attribute-Based Access Control (ABAC). Device permissions are managed via RBAC and are enforced by the policy on every endpoint. Other permissions like usage of the data plane are governed by assigning labels (attributes) that grant devices permission to communicate with other devices and enabling devices with certain roles to use AFC via the CanUseAfc permission.

To encourage more secure and easily auditable RBAC schemes, Aranya does not allow permissions to be assigned directly to devices. Instead, permissions are assigned to roles and roles are assigned to devices. Permissions assigned to roles are inherited by devices with the role assigned to them. Each device can have either have a single role assigned to it or no role assigned to it (multiple role assignments to a single device is not currently supported). If there is a scenario where it appears that multiple roles need to be assigned to a device, create a new custom role with the union of the permissions of both roles and assign that to the device instead.

Role assignments and permissions are stored on graph, meaning assignment and revocation are enforced on each device. Before performing an operation, the device’s role is checked against the policy to verify its permissions. When other devices process commands from this device, they will also check for valid permissions.

Object Rank

Every device, role, and label in Aranya has a numeric rank that determines its position in an authorization hierarchy. Authorization checks use a strict greater-than (>) comparison: a device can only operate on objects with a lower rank. Objects of equal rank cannot modify each other. This prevents deadlocks by conflicting changes of equal authorty.

Default Hierarchy

When a team is created and default roles are set up, the following ranks are assigned:

New devices are added with an application-specified rank lower than the role they are being assigned. The owner device intentionally outranks its own role so it can modify the owner role’s permissions. This is the sole exception to the role_rank >= device_rank invariant enforced for all other role assignments.

Key Properties

• role_rank >= device_rank: Enforced at role assignment time. A device cannot be assigned a role with a lower rank, which prevents it from modifying its own role.
• Role ranks are immutable: Role ranks cannot be changed after creation. To change a role’s rank, create a new role at the desired rank, migrate devices, and delete the old role.
• ChangeRank permission: Allows modifying device and label ranks at runtime. A device can lower its own rank but cannot raise it.

Example

An Admin device (rank 800) assigns the Member role (rank 600) to a new device (rank 500):

1. Admin outranks Member Role: 800 > 600 – allowed
2. Admin outranks new device: 800 > 500 – allowed
3. Member Role rank >= new device rank: 600 >= 500 – allowed

Result: Assignment succeeds.

Privilege Escalation Mitigations

To mitigate the risk of privilege escalation:

• Devices are not allowed to assign roles to themselves (enforced by strict > rank comparison – a device cannot outrank itself)
• A device must have the ChangeRolePerms permission and outrank the target role to change its permissions
• A device must have the AssignRole permission and outrank both the target role and device to assign a role
• A device must have the RevokeRole permission and outrank both the target role and device to revoke a role
• Permissions revoked from roles are transitively revoked from devices with that role assigned to them
• Roles revoked from devices will transitively revoke all permissions from the device
• When a device’s role is changed, it transitively inherits the permissions from the new role, and loses any permissions it had from the old role

Default Roles

The Aranya policy defines a set of default roles that can be assigned to devices. These roles can be initialized by invoking the setup_default_roles() action.

• Owner role permissions (all permissions):
• AddDevice
• RemoveDevice
• TerminateTeam
• ChangeRank
• CreateRole
• DeleteRole
• AssignRole
• RevokeRole
• ChangeRolePerms
• SetupDefaultRole
• CreateLabel
• DeleteLabel
• AssignLabel
• RevokeLabel
• CanUseAfc

• CreateAfcUniChannel

• Admin role permissions:
• ChangeRank
• AddDevice
• RemoveDevice
• CreateLabel
• DeleteLabel
• CreateRole
• DeleteRole

• ChangeRolePerms

• Operator role permissions:
• AssignLabel
• RevokeLabel
• AssignRole

• RevokeRole

• Member role permissions:
• CanUseAfc
• CreateAfcUniChannel

For a full list of permissions refer to the Perm enum in the default policy. They are copied here for convenience but may be out-of-date:

enum Perm {
    // # Team management
    //
    // The role can add a device to the team.
    AddDevice,
    // The role can remove a device from the team.
    RemoveDevice,
    // The role can terminate the team. This causes all team
    // commands to fail until a new team is created.
    TerminateTeam,

    // # Rank
    //
    // The role can change the rank of an object.
    ChangeRank,

    // # Roles
    //
    // The role can create a role.
    CreateRole,
    // The role can delete a role.
    DeleteRole,
    // The role can assign a role to other devices.
    AssignRole,
    // The role can revoke a role from other devices.
    RevokeRole,
    // The role can change permissions of other roles.
    ChangeRolePerms,
    // The role can set up default roles. This can only be done
    // once, so this permission can only effectively be used by
    // the `owner` role.
    SetupDefaultRole,

    // # Labels
    //
    // The role can create a label.
    CreateLabel,
    // The role can delete a label.
    DeleteLabel,
    // The role can assign a label to a device.
    AssignLabel,
    // The role can revoke a label from a device.
    RevokeLabel,

    // # AFC
    //
    // The role can use AFC. This controls the ability to
    // create or receive a unidirectional AFC channels.
    CanUseAfc,
    // The role can create a unidirectional AFC channel.
    CreateAfcUniChannel,
}

Custom Roles

Custom roles can be created, modified, and deleted at runtime.

A new role is created with create_role(role_name, rank), which takes a human-readable name and a rank that determines the role’s position in the authorization hierarchy. The creating device must have the CreateRole permission and its rank must be >= the new role’s rank.

Once created, a role’s permissions can be managed by any device that has the ChangeRolePerms permission and outranks the target role:

• add_perm_to_role(role_id, perm) – adds a permission to the role
• remove_perm_from_role(role_id, perm) – removes a permission from the role

Role assignment and revocation are controlled by separate permissions:

• assign_role(device_id, role_id) – assigns a role to a device that has no role (requires AssignRole + outranking both the role and device)
• change_role(device_id, old_role_id, new_role_id) – atomically changes a device’s role (requires RevokeRole for the old role and AssignRole for the new role)
• revoke_role(device_id, role_id) – revokes a role from a device (requires RevokeRole + outranking both the role and device)

A device cannot assign a role to itself. This is enforced by the rank system’s strict > comparison – a device cannot outrank itself.

A role can be deleted with delete_role(role_id) by a device whose role has the DeleteRole permission and outranks the target role. The role must not be assigned to any devices at the time of deletion.

The Owner role must always retain at least 1 device assignment. Attempts to revoke or change away from the owner role when it is the last remaining owner assignment will be rejected.

Refer to the default policy for more information on custom roles and permissions.

Onboarding

Devices can be onboarded to the team with an initial rank and an optional initial role using the add_device(device_keys, initial_role_id, rank) action. The rank determines the device’s position in the authorization hierarchy (see Object Rank). A device can be removed from the team with the remove_device() action.

Labels

Labels are used to define access to use data planes like AFC. In order for a device to utilize AFC, a label must be defined and assigned to that device and the peer they intend to communicate with.

Creation and Assignment

Labels have three levels of access control: permission to create, permission to assign, and permission to utilize. Channel labels can be created by any device that has a role with CreateLabel permission via the create_label() action. In order to utilize a label, a device that has a role with the AssignLabel permission must assign a device permission to use the label via the assign_label() action. The device must also have the CanUseAfc permission assigned to its role in order to use the label when creating/receiving an AFC channel.

Revocation

Labels can be revoked in two ways: direct revocation for a specific device (e.g. revoke_label_from_device()), and deleting the label (delete_label()). Operators and Owners can directly revoke a label from a device (any role with RevokeLabel permission that outranks both the label and target device). Revoking a label from a device directly causes any peers that were communicating with that device to drop the channel and refuse future messages.

How permissions are enforced

Aranya uses endpoint enforcement for the policy. Whenever an operation requiring some sort of permission check is taken the device will check against the current policy based on the current known set of commands. Using that information, the device can decide to accept or reject the operation.