Permissions

Las2peer provides a decentralized permission system by using Agents. There are three different types of Agents: ServiceAgents, UserAgents and GroupAgents. ServiceAgents execute a service on a node. UserAgents represent the user calling the service.

You can give rights to users using UserAgents and executing serivces using ServiceAgents. To handle user-related access and data, always use the UserAgent. To provide group access, you can use GroupAgents. GroupAgents can contain any other agent (including other GroupAgents) but can be used in the same manner as other agent types.

When executing a service, the service has access to the user through the Context, which holds the UserAgents and provides methods for checking group memberships and permissions.

To learn more about Agents, read the Agent tutorial.

##Retrieve Agents from Storage

If you need to get an agent by id, you can use

getContext().getAgent(long id)

This will return a locked copy of the agent. Please note that each method call returns a new instance.

##Lock and Unlock Agents

When a service is called, the Context holds an unlocked main agent, representing the calling agent.

getContext().getMainAgent()

If you want to unlock additional UserAgents or ServiceAgents, you can unlock them using

agent.unlockPrivateKey(String passphrase)

and forget the passphrase using

agent.lockPrivateKey(String passphrase)

However, dealing with lock/unlock is not recommended as more secure higher level features are available (see below)

##GroupAgents

###Creation

First you create a GroupAgent with:

GroupAgent group = GroupAgent.createGroupAgent(Agent[] members);

Unlock it using an unlocked member:

group.unlockPrivateKey(Agent member);

Store it in the node:

getContext().getLocalNode().storeAgent(group);

Now, you can use it as any other agent.

###Managing members

To add or remove members, you first have to unlock the agent as shown above. Then, you can use

group.addMember(Agent a) and group.removeMember([Agent agent|long id])

to add or remove members. Then, you have to store the agent in the node as shown above.

###Check group memberships

If you want to check group membership of an agent, you can use group.isMember([Agent agent|long id]). Recursive memberships can be checked by calling group.isMemberRecursive([Agent agent|long id]).

These methods do not require neither an unlocked GroupAgent nor an unlocked Agent as parameter.

##Higher level features

The Context provides methods to hide lock/unlock logic from the service developer. The following methods are related to the Context's main agent, that means they check if the main agent is able to unlock a GroupAgent. Moreover, these methods only return unlocked agents or throw an SecurityException if this is not possible; unlocked agents are cached in the Context. All methods support recursive group unlocking.

• getContext().requestGroupAgent(long id) returns an unlocked group agent
• getContext().requestAgent(long id) returns an unlocked agent
• getContext().hasAccess(long id) returns true, if the main agent can unlock the given agent, i.e. inherits its permissions

It is recommended to use these methods as they are simple to use and avoid wrong usage.

Do not lock these agents, this will be done automatically. Never lock the Context's main agent as this may lead to SecurityExceptions.

##Storage

There is another tutorial on how to set up permissions for the storage.