uk.ac.soton.itinnovation.grid.pbac2.pdp
Interface PDP

All Known Subinterfaces:

PDPService

All Known Implementing Classes:

PDPImpl, PDPServiceImpl

public interface PDP

The PDP decides whether a given operation is allowed on a given resource. If allowed, the resource is locked and the current state of the resource returned. When the service has finished working on the resource, it uses the PDP to unlock it.

Field Summary

static String	DESTROYED_STATE If a resource is unlocked while in this state, it is destroyed (removed from the PBAC system).
static String	GROUP_MEMBER_ROLE As an alternative to checking certificates, a MatchRule can test whether the subject has this role in some other resource.
static String	UNINITIALISED_STATE When a new process is created, it is locked and in this state.

Method Summary

void	addPolicyRule(String resourceID, PolicyRule rule) Add a new rule for a resource.
void	check(String resourceID, SubjectDescription subjectDesc, String action) Checks if the request is granted.
void	deployPolicy(String resourceTypeID, String policyClassName, String modelData, String defaultVersion) Deploy a new resource type.
String[]	getAvailableSignals(String resourceID) List the signals available given the current state of the resource.
String	getDefaultVersion(String resourceTypeID) Get the service's default policy version at the time this policy was deployed.
String[]	getDeployedPolicies() List the policies currently deployed.
boolean	getHasRole(String resourceID, SubjectDescription subjectDesc, String role) Check whether the given subject has the named role in 'resourceID'.
PolicyRule[]	getPolicyRules(String resourceID, String processRole) Get the list of rules for membership of the given role.
String[]	getProcessRolesForSubject(String resourceID, SubjectDescription subjectDesc) Get the list of roles of which this subject is a member.
String	getProcessState(String resourceID) Return the current process state of a resource.
String[]	getResources(String resourceTypeID, SubjectDescription subjectDesc, String processState) Get the list of resources in which the given subject has membership of some role.
String	getResourceStatusMessage(String resourceID) Used for the admin interface only.
String	getResourceType(String resourceID) Get the type of a resource.
String	getStaticPolicy(String resourceTypeID) Returns the modelData previously set using deployPolicy.
String[]	getValidProcessRoles(String resourceTypeID) List the valid process roles for this model.
String	getVersion() Returns the version of PBAC being used.
String	lockAndCheck(String resourceID, SubjectDescription subjectDesc, String action) Locks the resource and checks if the request is granted.
String	lockForAdmin(String resourceID, String action) Like lockAndCheck, but without the check.
void	newProcess(String resourceTypeID, String resourceID) Creates a new process for a given resource.
void	removePolicyRule(String resourceID, PolicyRule rule) Remove a rule from a resource.
String	signal(String resourceID, String event) Signal an event on the resource.
void	undeployPolicy(String resourceTypeID) Undeploy a policy.
String	unlock(String resourceID) Unlocks a resource.

Field Detail

UNINITIALISED_STATE

static final String UNINITIALISED_STATE

When a new process is created, it is locked and in this state. If a resource is unlocked while in this state, it is destroyed (removed from the PBAC system).

See Also:

Constant Field Values

DESTROYED_STATE

static final String DESTROYED_STATE

If a resource is unlocked while in this state, it is destroyed (removed from the PBAC system). Normally, a process will first move into a 'finished' state, which may allow operations such as getStatus() for a while. After a grace period, the process will then transition to DESTROYED_STATE to be removed completely.

See Also:

Constant Field Values

GROUP_MEMBER_ROLE

static final String GROUP_MEMBER_ROLE

As an alternative to checking certificates, a MatchRule can test whether the subject has this role in some other resource. Any resource type that defines this role can thus act as a group. For example, you could have a 'managers' resource where all managers have the GROUP_MEMBER_ROLE role. Then, other resources can have rules like: Grant role 'auditor' if subject is a member of 'managers'

See Also:

Constant Field Values

Method Detail

lockAndCheck

String lockAndCheck(String resourceID,
                    SubjectDescription subjectDesc,
                    String action)
                    throws AcquireResourceLockTimeoutException,
                           InvalidResourceIDException,
                           NotAuthorisedException,
                           ActionCurrentlyUnavailableException,
                           InvalidActionException,
                           InvalidSubjectDescriptorException,
                           ResourceTypeNotDeployedException

Locks the resource and checks if the request is granted. If the request fails, the resource is unlocked before returning.

Parameters:

resourceID - the resource in question

subjectDesc - the subject's description

action - the requested action

Returns:

the current state, which may be needed by the service operation

Throws:

InvalidActionException - if the action is not valid

AcquireResourceLockTimeoutException - if we cant get exclusive access to the resource in the timeout period

InvalidSubjectDescriptorException - if the subject descriptor is invalid

InvalidResourceIDException - if the resource ID is not recognised

NotAuthorisedException - if the user is not authorised on the action in the resource

ResourceTypeNotDeployedException - if the resource's type is no longer valid (undeployed)

ActionCurrentlyUnavailableException - if the user is authorised to execute the action on the resource but can't right now

check

void check(String resourceID,
           SubjectDescription subjectDesc,
           String action)
           throws InvalidResourceIDException,
                  ResourceNotLockedException,
                  NotAuthorisedException,
                  ActionCurrentlyUnavailableException,
                  InvalidActionException,
                  InvalidSubjectDescriptorException

Checks if the request is granted. The resource must be locked.

Parameters:

resourceID - the resource in question

subjectDesc - the subject's description

action - the requested action

Throws:

InvalidActionException - if the action is not valid

InvalidSubjectDescriptorException - if the subject descriptor is invalid

InvalidResourceIDException - if the resource ID is not recognised

ResourceNotLockedException - if the resource is not locked

NotAuthorisedException - if the user is not authorised on the action in the resource

ActionCurrentlyUnavailableException - if the user is authorised to execute the action on the resource but can't right now

lockForAdmin

String lockForAdmin(String resourceID,
                    String action)
                    throws AcquireResourceLockTimeoutException,
                           InvalidResourceIDException,
                           ResourceTypeNotDeployedException

Like lockAndCheck, but without the check. This is for admin interfaces. This operation is similar to lockAndCheck, except that 'action' is not checked (and need not even exist in the policy). Here, it is only used for informational purposes (for example, in log messages and in the string returned by getResourceStatusMessage).

Parameters:

resourceID - the resource to lock

action - the action which requires the resource to be locked

Throws:

AcquireResourceLockTimeoutException

InvalidResourceIDException

ResourceTypeNotDeployedException

signal

String signal(String resourceID,
              String event)
              throws EventCurrentlyUnavailableException,
                     InvalidResourceIDException,
                     InvalidEventException,
                     ResourceNotLockedException

Signal an event on the resource. The process state may be updated in response to this, according to the service policy.

Parameters:

resourceID - the resource in question

event - the event causing the transition

Returns:

the new state

Throws:

InvalidEventException - if the event is not valid according to the service policy

EventCurrentlyUnavailableException - if the event is not available in the current state

InvalidResourceIDException - if the resource ID is not recognised

ResourceNotLockedException - if the resource is not locked

getAvailableSignals

String[] getAvailableSignals(String resourceID)
                             throws InvalidResourceIDException

List the signals available given the current state of the resource. The resource may or may not be locked. If not locked, other callers may change the state so that the returned list is no longer valid.

Parameters:

resourceID - the resource in question

Returns:

a list of available events

Throws:

InvalidResourceIDException - if the resource ID is not recognised

unlock

String unlock(String resourceID)
              throws InvalidResourceIDException,
                     ResourceNotLockedException

Unlocks a resource. If the process state is UNINITIALISED_STATE or DESTROYED_STATE, the process is destroyed. Note that the state returned is for the moment the resource was unlocked; it may have been changed by another thread by the time you read it, and it therefore useful for display and logging purposes only.

Parameters:

resourceID - the resource in question

Returns:

the state of the resource when unlocked

Throws:

InvalidResourceIDException - if the resource ID is not recognised

ResourceNotLockedException - if the resource is not locked

getProcessState

String getProcessState(String resourceID)
                       throws InvalidResourceIDException

Return the current process state of a resource. The resource does not need to be locked to use this call. However, if it is not locked then the status may change at any time, so the result should only be used for informational purposes.

Returns:

the process state of the resource

Throws:

InvalidResourceIDException

addPolicyRule

void addPolicyRule(String resourceID,
                   PolicyRule rule)
                   throws InvalidResourceIDException,
                          InvalidPolicyRuleException,
                          ResourceNotLockedException

Add a new rule for a resource. The resource must be locked before a rule can be added.

Parameters:

resourceID - the resource being protected

rule - the rule to add

Throws:

InvalidResourceIDException

InvalidPolicyRuleException

ResourceNotLockedException

removePolicyRule

void removePolicyRule(String resourceID,
                      PolicyRule rule)
                      throws InvalidResourceIDException,
                             InvalidPolicyRuleException,
                             PolicyRuleNotFoundException,
                             ResourceNotLockedException

Remove a rule from a resource. The resource must be locked, and the rule must match one previously added with addAccessControlRule.

Parameters:

resourceID - the resource being protected

rule - the rule to remove

Throws:

InvalidResourceIDException

InvalidPolicyRuleException

PolicyRuleNotFoundException

ResourceNotLockedException

newProcess

void newProcess(String resourceTypeID,
                String resourceID)
                throws ResourceIDAlreadyExistsException,
                       ResourceTypeNotDeployedException

Creates a new process for a given resource. The new resource is locked when the call returns. You must call signal() at least once before unlocking (otherwise, unlocking will remove the new process).

Parameters:

resourceTypeID - the resource's type

resourceID - the resource ID (must not already have a PBAC process)

Throws:

ResourceIDAlreadyExistsException - if the resource is already managed by PBAC

ResourceTypeNotDeployedException - if the resourceTypeID is not currently deployed

getResourceType

String getResourceType(String resourceID)
                       throws InvalidResourceIDException

Get the type of a resource.

Parameters:

resourceID - the resource to check

Returns:

the resourceTypeID passed to newProcess() when this resource was registered

Throws:

InvalidResourceIDException - if the resource does not exist

getPolicyRules

PolicyRule[] getPolicyRules(String resourceID,
                            String processRole)
                            throws InvalidResourceIDException,
                                   ResourceNotLockedException

Get the list of rules for membership of the given role.

Parameters:

resourceID - the resource being protected

processRole - the role being queried, or null for all The resource does not need to be locked to use this call. However, if it is not locked then the status may change at any time, so the result should only be used for informational purposes.

Returns:

A set of MatchRule objects

Throws:

InvalidResourceIDException

ResourceNotLockedException

getResources

String[] getResources(String resourceTypeID,
                      SubjectDescription subjectDesc,
                      String processState)
                      throws ResourceTypeNotDeployedException,
                             InvalidSubjectDescriptorException,
                             InvalidStateException

Get the list of resources in which the given subject has membership of some role.

Parameters:

resourceTypeID - the type of resource to match

subjectDesc - the user to query on, or null for all resources

processState - the state the resource must be in, or null to match all states

Returns:

the list of resource ID strings for which this subject has some role

Throws:

ResourceTypeNotDeployedException

InvalidSubjectDescriptorException

InvalidStateException

getProcessRolesForSubject

String[] getProcessRolesForSubject(String resourceID,
                                   SubjectDescription subjectDesc)
                                   throws InvalidResourceIDException,
                                          ResourceNotLockedException,
                                          InvalidSubjectDescriptorException

Get the list of roles of which this subject is a member.

Parameters:

resourceID - the resource being protected

subjectDesc - the user to query on

Returns:

the list of roles which this subject can act in

Throws:

InvalidResourceIDException

ResourceNotLockedException

InvalidSubjectDescriptorException

getHasRole

boolean getHasRole(String resourceID,
                   SubjectDescription subjectDesc,
                   String role)
                   throws InvalidResourceIDException,
                          ResourceNotLockedException,
                          InvalidSubjectDescriptorException

Check whether the given subject has the named role in 'resourceID'. This is equivalent to calling getProcessRolesForSubject() and checking whether 'role' is in the returned list, but is more efficient.

Returns:

true if the subject has the role

Throws:

InvalidResourceIDException

ResourceNotLockedException

InvalidSubjectDescriptorException

deployPolicy

void deployPolicy(String resourceTypeID,
                  String policyClassName,
                  String modelData,
                  String defaultVersion)
                  throws ResourceTypeAlreadyDeployedException

Deploy a new resource type. The version number is used to warn the user when they need to upgrade the policy. When the service deploys its default policy OR when the user replaces it with a custom policy the SAME defaultVersion is passed. This means that the user will not be asked to upgrade. When the service is upgraded to a version with a newer default policy, the user will be prompted to upgrade.

Parameters:

resourceTypeID - the name of the type

policyClassName - the Java class to handle the type (implements ServicePolicy)

modelData - data to pass to the service policy constructor

defaultVersion - the version of the default policy for this version of the service

Throws:

ResourceTypeAlreadyDeployedException - if the type is already deployed

undeployPolicy

void undeployPolicy(String resourceTypeID)
                    throws ResourceTypeNotDeployedException,
                           AcquireResourceLockTimeoutException

Undeploy a policy. This first marks the policy as disabled, so resources of this type can't be created or locked (it is not an error if the type is already disabled; it remains disabled). The policy is then undeployed if no resources of that type are locked. If any are, it throws AcquireResourceLockTimeoutException with the policy still disabled. Call again later to actually undeploy.

Parameters:

resourceTypeID - the type to undeploy

Throws:

ResourceTypeNotDeployedException - if the resource type is not currently deployed

AcquireResourceLockTimeoutException - if some resources of this type are still locked

getStaticPolicy

String getStaticPolicy(String resourceTypeID)
                       throws ResourceTypeNotDeployedException

Returns the modelData previously set using deployPolicy.

Returns:

the modelData for this type

Throws:

ResourceTypeNotDeployedException - if these resource type is not currently deployed

getDeployedPolicies

String[] getDeployedPolicies()

List the policies currently deployed.

Returns:

an array of resource type IDs.

getValidProcessRoles

String[] getValidProcessRoles(String resourceTypeID)
                              throws ResourceTypeNotDeployedException

List the valid process roles for this model.

Returns:

an array of process role names.

Throws:

ResourceTypeNotDeployedException

getVersion

String getVersion()

Returns the version of PBAC being used.

getDefaultVersion

String getDefaultVersion(String resourceTypeID)
                         throws ResourceTypeNotDeployedException

Get the service's default policy version at the time this policy was deployed. If this is different to the current default policy version, the admin should be prompted to upgrade the policy.

Parameters:

resourceTypeID - the type to check

Returns:

the version passed to deployPolicy(java.lang.String, java.lang.String, java.lang.String, java.lang.String) when the policy was deployed

Throws:

ResourceTypeNotDeployedException - if this type isn't deployed

getResourceStatusMessage

String getResourceStatusMessage(String resourceID)
                                throws InvalidResourceIDException

Used for the admin interface only.

Returns:

a string describing this resource's process state and locked state.

Throws:

InvalidResourceIDException

See Also:

getProcessState(java.lang.String)