Sponsored by
Sponsored by
Policy is written using a domain specific language which is fully customizable to allow integrators to define the exact authority model that best fits their needs, with as much granularity as appropriate. Each Aranya instance contains a copy of the policy to ensure consistent and reliable enforcement across all endpoints.
The policy outlines the full set of operations that devices can perform throughout the system and specifies the permission requirements for each. These operations are represented as structured data, called “Commands”, and the set of requirements needed to execute a command is embedded in its definition in the policy file. Hence, execution of any command will involve evaluation of its underlying policy and successfully meeting all the requirements will allow for its described operation to be carried out, while the command itself is stored in an immutable audit log of control operations.
To execute actions, a custom policy file must be written and validated prior to deployment. Policies outline the accepted actions that can be issued and the corresponding commands that will be generated. Successful commands will emit effects and/or write facts (stored key value pairs) to the graph. The following is a basic overview of the parts that make up a policy.
The following is a basic overview of the parts that make up a policy. For more detailed descriptions, see the policy language spec.
Action: Actions are an application’s entry point into the policy. They are functions that can perform client-side checks and publish Commands into the local database. When new Commands arrive (from either local creation, or synced from other nodes), the policy for those Commands is evaluated, which may produce fact changes and effects. Actions are, alongside Effects, part of the application interface contract implemented by the policy. Actions execute atomically - they only succeed if all the Commands they produce succeed.
Command: Commands are called via Actions or Syncing with another peer. A Command defines structured data (the fields block), methods for packing and unpacking this data (seal and open blocks), and the policy decisions for processing data (finish and recall blocks).
Effect: Effects are structured data emitted by policy and recall blocks, which communicate changes and status from the policy to the application. The shape of an Effect is defined by policy.
Fact: A Fact is a key-value pair stored in the Fact DB. The shape of a
fact is defined in policy with the fact schema statements, e.g.
fact Foo[key int]=>{value int}. Fact keys and values are tuples and can
contain multiple fields. For example:
fact TeamAdmin[teamID: int, deviceID: int]=>{name: string, team: string}.
To make changes to a graph, a device calls an action to generate one or more commands. Another way to think about commands is to envision a piece of data (or fact) that you can manipulate by calling an action. The action is merely the “act” you wish to perform on the data and the command holds the actual execution of this action. Both actions and commands can be implemented on raw data if that data is passed to the action. For example, an action may be adding/removing devices, creating/ deleting channels, or sending encrypted data. Once an action is called, the generated command is then evaluated by the policy engine to determine its validity given the current state and loaded policy.
If a command is valid, it may be stored on the graph and some facts may be added, updated, or removed in the fact database. An effect, which provides information at the application level about the operation that was performed, can also be produced when a command is published. Upon syncing, all other peers may see the new validated command on the DAG. If they are authorized to view its contents, such as an encrypted message, then they will be able to obtain that too.
Ephemeral sessions behave in a similar manner as regular Policy Actions and Commands, with the distinction that ephemeral Commands are never saved to the Graph. Users write ephemeral Commands in a similar manner as on-graph Commands, they can emit effects and perform Policy checks, but they will not save anything to the FactDB. Ephemeral commands can be processed locally or sent to peers; this can be useful for things like setting up encryption keys. When a Client processes an ephemeral command locally, they receive back the command as a string of serialized bytes, which then can be sent to peers to be deserialized and processed. Ephemeral Commands are transmitted between peers using a user defined transport mechanism. Ephemeral commands can be sent via any means to peers who can process/validate them and that we include a secure real-time data exchange which relies on ephemeral commands (see “real-time data exchange”)[].
This data:
- Is validated and authorized by policies
- Doesn't have the same persistence guarantees
- Is used primarily for real-time data exchange
For information on how to write policy, see the policy writing guide.