API: Agents

Agents and permission management

In las2peer, each action is performed by an agent. These agents are passively hosted by nodes. Agents can have different types representing different actors in the network. Usually, agents have an asymmetric key pair to encrypt stored artifacts and communication.

Agent types

las2peer provides the following standard agents:

• PassphraseAgent: agents that represent a single actor and are accessible by a passphrase
  • UserAgent: represents a (probably human) user
  • ServiceAgent: represents a service (unique per service name and version and node)
• GroupAgent: a group of agents, holds a list of members which can access the group

Group agents are used to implement more advanced rights management as member agents can act on behalf of the group. Also, group agents can be a member of another group agent.

Agent states and explicit unlocking

An agent can be in an unlocked or locked state. Unlocked agents can be used to decrypt data or sign data as the agent. Locked agents can only be used to obtain metadata of the agent. To unlock a locked agent, the unlock() method can be used. For PassphraseAgents, the agent's passphrase should be passed as argument and for GroupAgents another unlocked agent instance that is direct member of the group.

The main agent

Each service call is bound to a context which includes an unlocked main agent obtainable via Context.get().getMainAgent(). It represents the agent that called the service method and should be used for access control.

When calling Context methods, this main agent is used for operations in the network by default. However, operations can also be used by specifying them as last parameter. E.g. requestAgent(String id) fetches and unlocks the specified agent using the main agent while requestAgent(String id, Agent using) uses using for unlocking the fetched agent.

Create and update agents

UserAgents

Usually, you don't have to create user agents from the service. las2peer or, more specifically a connector, usually creates agents for its users. To create a new user agent, the createUserAgent(String passphrase) can be used. This will return an unlocked user agent instance which is not known to the network yet.

To store or update a user agent, call storeAgent(Agent agent). If the operation succeeds, the agent is globally available.

A user has an user name and an email adress which are unique in the network and accessible via the getters and setters of the UserAgent. During the store operation, these fields are registered and an exception is thrown if it already exist.

GroupAgents and group management

To create a new group of agents, call createGroupAgent(Agent[] members) which will create a new unlocked group agent instance with the given initial member list. Again, the agent has to be stored in the network using storeAgent(Agent agent).

At the moment, each group member is able to add or remove members.

To add group members, call addMember(Agent agent). This agent has (after storing) full access to the group and can act as the group.

Removing group members is not really possible in a p2p network. Once a user has unlocked a group, it has seen the key pair of the group and thus has access to all data accessible with this key pair. However, las2peer allows to revoke a membership using revokeMember(Agent agent). This means, that the agent still has access to the group's data that has been created prior to the revoke, but all data that is created from there on is not accessible by the revoked member anymore.

To check whether an agent is a direct member of the group (excluding transitive memberships), use hasMember(Agent agent).

Remember to store the group after each update.

Get agents from the network and test access

There are two options for fetching agents from the network:

• fetchAgent(String id): Returns an locked agent instance.

• requestAgent(String id [, Agent using]): Fetches and unlocks the specified agent. In case of groups, also transitive memberships are considered for unlocking. The semantic is "give me the agent if I have access to it, but I don't want to know how exactly I can access it".

These methods throw AgentExceptions such as AgentAccessDeniedException or AgentNotFoundException and should be self explaining.

If you just want to check if an agent has access to an agent (e.g. is able to unlock it), you can use hasAccess(String id [, Agent using]).

AnonymousAgent

The anonymous agent is not a real agent. It is used for anonymous requests in the network. Due to its nature the anonymous agent can only

• access unencrypted envelopes
• perform RMI calls

and cannot

• store envelopes to the network
• guarantee edge to edge encryption between nodes

In the service, it can be checked if the current agent is anonymous:

if (Context.get().getMainAgent() instanceof AnonymousAgent) {
  // do sth
}

However, las2peer throws *AccessDeniedExceptions if an illegal operation is performed with an AnonymousAgent.