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.

To mitigate the risk of privilege escalation:

Devices are not allowed to assign roles to themselves
Devices are not allowed to assign permissions to roles that they do not have themselves
Devices are not allowed to assign themselves as a role owner of another role
A role must have the CanChangeRolePerms management permission before changing another role’s permissions
A role must have the CanAssignRole management permission before assigning a role to another device
A role must have the CanRevokeRole management permission before revoking a role from another device
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:
AddDevice
RemoveDevice
CreateLabel
DeleteLabel
AssignLabel
RevokeLabel
AssignRole
RevokeRole
SetupDefaultRole
ChangeRoleManagingRole
ChangeLabelManagingRole
TerminateTeam
CanUseAfc
CreateAfcUniChannel
Admin role permissions:
AddDevice
RemoveDevice
CreateLabel
DeleteLabel
ChangeLabelManagingRole
AssignRole
RevokeRole
Operator role permissions:
AssignLabel
RevokeLabel
AssignRole
RevokeRole
Member role permissions:
CanUseAfc
CreateAfcUniChannel

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

enum SimplePerm {
    // # 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,

    // # 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 set up default roles. This can only be done
    // once, so this permission can only effectively be used by
    // the `owner` role.
    SetupDefaultRole,
    // The role can add a managing role to or remove a managing
    // role from a target role.
    ChangeRoleManagingRole,

    // # Labels
    //
    // The role can create a label.
    CreateLabel,
    // The role can delete a label.
    DeleteLabel,
    // The role can grant a target role the ability to manage a
    // label. This management ability includes deleting a label
    // and adding/revoking a label to a device.
    ChangeLabelManagingRole,
    // The role can assign a label to a device. The role must
    // also have label management permissions granted by a role
    // with the `ChangeLabelManagingRole` permission above.
    AssignLabel,
    // The role can revoke a label from a device. The role must
    // also have label management permissions granted by a role
    // with the `ChangeLabelManagingRole` permission above.
    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,
}

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

Custom Roles

Generalized custom roles functionality can be enabled with the preview feature flag. This includes support for creating/deleting custom roles, modifying their permissions, and assigning roles to devices.

When a new role is created via create_role(owning_role id), it must have an initial owning role assigned to it. The owning role can add other roles as owners of that role (add_role_owner()). Each role requires at least one owning role to manage it at all times.

An owning role can modify the target role’s permissions (add_perm_to_role(), remove_perm_from_role()), assign the role to other devices assign_role()/change_role(), or revoke the role from other devices revoke_role(). A device cannot assign a role to itself as this could result in privilege escalation. A device cannot assign a permission to a role it does not have as this could result in privilege escalation.

An owning role may choose to delegate certain role management permissions to other roles (assign_role_management_permission(), revoke_role_management_permission()).

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

enum RoleManagementPerm {
    // Grants a managing role the ability to assign the target role
    // to any device except itself.
    CanAssignRole,
    // Grants a managing role the ability to revoke the target role
    // from any device.
    CanRevokeRole,
    // Grants a managing role the ability to change the permissions
    // assigned to the target role.
    CanChangeRolePerms,
}

A role may be deleted by a device who’s role has the CanDeleteRole permission.

Refer to the default policy for more information on custom roles, role owners, and role management permissions.

Onboarding

Devices can be onboarded to the team with an optional initial role with the add_device() action. 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, Admins, and Owners can directly revoke a label from a 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.

Aranya Documentation An overview of the Aranya project