issrg.pba.rbac
Class PermisRBAC

java.lang.Object
  issrg.pba.rbac.PermisRBAC

All Implemented Interfaces:

PBAAPI

Direct Known Subclasses:

ManagedPermisRBAC

public class PermisRBAC
extends java.lang.Object
implements PBAAPI

This is the Permis implementation of the PBAAPI. It works with a variety of authorization token formats, in particular, it can handle X.509 Attribute Certificates and uses Role Based access control and the policy is the XML Policy that accords to Policy10.DTD.

When the object has been constructed successfully, the caller (the AEF - Access decision Enforcement Function; see ISO 10181-3 access control framework; or the PEP - Policy Enforcement Point) can use the object to make access decisions for various user requests.

In order to make a decision the caller must obtain the user's credentials. This can be done by calling any of the range of getCreds methods, providing both Push and Pull models. If Pull model is used, the user authorisation tokens are retrieved from the repository, specified in the constructor. After that the delegation chain is established, and the user set of credentials is calculated by parsing the tokens. The PermisRBAC object uses Role attributes from the authorisation tokens, for which the OID and allowed range of values are specified in the Policy (obtained at construction time). Thus the Credentials for the user are calculated and stored in the Subject object.

Now the decision method can be called for the Subject as many times as the AEF or PEP decides is appropriate before the credentials become outdated and need to be refreshed. Note also that the same Subject can only be used by the PermisRBAC object that created it. It cannot be used by other PermisRBAC object(s), even if they are initialised with the same Policy OID: to check this the object ascertains if the owner of the Subject object is itself and throws an exception at decision time if it is not. This is done to ensure the credentials of the Subject are up to date and are not forged or confused with credentials obtained from another PermisRBAC instance.

When calling the decision method, the AEF must pass the Action that the user wants to perform, and the Target the user wants to perform the action on. A set of other contextual parameters is passed as environmental variables. They can be used by the PermisRBAC object when calculating the decision, if the Policy requires so. The decision method either returns a boolean result (true meaning grant access, false meaning deny), or throws a PbaException, when a decision cannot be made.

If you need to know which roles the user has got (usually it is for auditing purposes), you can extract them using the getRoleValues method of the RoleBasedCredentials object. See the example in the RoleBasedCredentials documentation for that method.

Version:

0.2

Author:

A Otenko, E Ball, D W Chadwick

Field Summary

java.lang.String	TIME_VARIABLE This is the name of the environmental variable used to locate the clock with current time.
protected int	TIMEOUT

Constructor Summary

protected	PermisRBAC()
	PermisRBAC(PolicyFinder pf) This constructor constructs a PermisRBAC object based on the provided PolicyFinder Object.
	PermisRBAC(PolicyFinder pf, AttributeRepository ar, AuthzTokenParser authParser) This constructor is used by all other constructors indirectly.
	PermisRBAC(PolicyFinder pf, java.lang.String[] urls, AuthzTokenParser authParser) This constructor builds a PermisRBAC object given a PolicyFinder, an array of URLs of Attribute Repositories with the Authorisation Tokens in them, and the AuthTokenParser to use.
	PermisRBAC(PolicyFinder pf, java.lang.String url, AuthzTokenParser authParser) This constructor builds a PermisRBAC object given a PolicyFinder, a URL of a single Attribute Repository with the Authorisation Tokens in it, and the AuthTokenParser to use.

Method Summary

Response	authzDecision(Subject subject, Action action, Target target, java.util.Map applicationContext) This method makes a decision, and in addition to that can provide a set of Obligations that the system must fulfil upon enforcement of the decision.(The method name is changed from response() to authzDecision())
boolean	decision(Subject subject, Action action, Target target, java.util.Map applicationContext) This method returns the boolean result of evaluating the Access Control Decision Function.(decision() is only here for backward compatibility.
protected void	finalize() This method is called by gc (JVM's Garbage Collector) when the Permis RBAC object is no longer referenced.
Subject	getCreds(java.security.Principal subjectDN) This method returns the credentials of the subject whose Principal is supplied (e.g. LDAPDNPrincipal represents the Subject's LDAP DN).
Subject	getCreds(java.security.Principal subjectDN, CredentialsService service) This method returns the credentials of the subject whose Principal is supplied (e.g. LDAPDNPrincipal represents the Subject's LDAP DN).
Subject	getCreds(java.security.Principal subjectDN, java.lang.Object[] creds) This method returns the credentials of the subject whose Principal and Authorisation Tokens are supplied (e.g. LDAPDNPrincipal represents the Subject's LDAP DN, and byte arrays of BER-encoded Attribute Certificates represent the Authorisation Tokens).
Subject	getCreds(java.security.Principal subjectDN, java.lang.Object[] creds, CredentialsService service) This method returns the credentials of the subject whose Principal and Authorisation Tokens are supplied (e.g. LDAPDNPrincipal represents the Subject's LDAP DN, and byte arrays of BER-encoded Attribute Certificates represent the Authorisation Tokens).
Subject	getCreds(java.security.Principal subject, java.lang.String[] urls, AuthzTokenParser authParser) This method returns the credentials of the subject, given the subject Principal and an array of repository URLs where his credentials are stored - semi-pull model.
protected Subject	getCreds(UserEntry subjectDN, java.lang.Object[] creds, AuthzTokenRepository repository, CredentialsService service) This is the root of the family of all getCreds; it can do both push and pull, and can set credentials lifetime for the given subject.
PolicyFinder	getPolicyFinder() This method returns the PolicyFinder used to initialise the object.
static MultiRepository	getRepositories(java.lang.String[] urls) This utility method will build a MultiRepository given a list of URLs.
protected static MultiRepository	getRepositories(java.lang.String[] urls, java.lang.String[] urls2) This method builds a MultiRepository that accesses two sets of repositories simultaneously.
int	getTimeOut() This method returns the time-out parameter of the system.
protected java.util.Map	initEnv(java.util.Map env) This method fills in the default variables that this version of PermisRBAC requires.
protected PermisSubject	newPermisSubject(java.security.Principal dn, CredentialsService service, java.lang.String policyOID, Credentials creds) Creates a Subject from the given parameters.
void	SAWSCloseLog()

Methods inherited from class java.lang.Object

clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

TIME_VARIABLE

public final java.lang.String TIME_VARIABLE

This is the name of the environmental variable used to locate the clock with current time. Its name is "time", so the XML should contain statements like this:

...<!-- IF-statement goes here. It compares if current time is "after 8am" -->
<GE>
<Environment Parameter="time" Type="Time"/>
<Constant Type="Time" Value="*-*-*T8:00"/>
</GE>

See Also:

Constant Field Values

TIMEOUT

protected int TIMEOUT

Constructor Detail

PermisRBAC

protected PermisRBAC()

PermisRBAC

public PermisRBAC(PolicyFinder pf)
           throws PbaException

This constructor constructs a PermisRBAC object based on the provided PolicyFinder Object. Using PolicyFinder, physical details of accessing and retreiving policies can be hidden from Permis.

Users should implement corresponsding PolicyFinder Subclass to allow PermisRBAC to access different formats of policies from different sources. A number of PolicyFinder implementations are provided by Permis.

Note that there is no AttributeRepository attached explicitly, so either the policy should contain a RepositoryPolicy, or PERMIS will work in push mode only.

Parameters:

pf - is the PolicyFinder that provides access to the policies that are used by PermisRBAC engine.

Throws:

PbaException

See Also:

issrg.pba.PolicyFinder

PermisRBAC

public PermisRBAC(PolicyFinder pf,
                  java.lang.String url,
                  AuthzTokenParser authParser)
           throws PbaException

This constructor builds a PermisRBAC object given a PolicyFinder, a URL of a single Attribute Repository with the Authorisation Tokens in it, and the AuthTokenParser to use. The Attribute Repositories are constructed from URLs using URLHandler.getRepositoryByURL, so the appropriate URLHandlers must be registered.

This is a shortcut for PermisRBAC(pf, new String[]{url}, authParser);

Parameters:

pf - - the PolicyFinder that provides the policy

url - - the URL of the single AttributeRepository with AuthorisationTokens; if null, the Repositories mentioned in the policy will be used, or PERMIS will work in push mode only, if none are specified in the policy

authParser - - the AuthTokenParser to use for parsing the Authorisation Tokens, obtained from the Attribute Repositories; if null the default AuthTokenParser will be used, as returned by CustomisePERMIS.getAuthTokenParser

Throws:

PbaException

See Also:

CustomisePERMIS#getAuthTokenParser, CustomisePERMIS.addURLHandler(java.lang.String), URLHandler.getRepositoryByURL(java.lang.String), URLHandler.addProtocol(URLHandler)

PermisRBAC

public PermisRBAC(PolicyFinder pf,
                  java.lang.String[] urls,
                  AuthzTokenParser authParser)
           throws PbaException

This constructor builds a PermisRBAC object given a PolicyFinder, an array of URLs of Attribute Repositories with the Authorisation Tokens in them, and the AuthTokenParser to use. The Attribute Repositories are constructed from URLs using URLHandler.getRepositoryByURL, so the appropriate URLHandlers must be registered.

Parameters:

pf - - the PolicyFinder that provides the policy

urls - - the URLs of the AttributeRepositories with AuthorisationTokens; if null, the Repositories mentioned in the policy will be used, or PERMIS will work in push mode only, if none are specified in the policy

authParser - - the AuthTokenParser to use for parsing the Authorisation Tokens, obtained from the Attribute Repositories; if null the default AuthTokenParser will be used, as returned by CustomisePERMIS.getAuthTokenParser

Throws:

PbaException

See Also:

CustomisePERMIS#getAuthTokenParser, CustomisePERMIS.addURLHandler(java.lang.String), URLHandler.getRepositoryByURL(java.lang.String), URLHandler.addProtocol(URLHandler)

PermisRBAC

public PermisRBAC(PolicyFinder pf,
                  AttributeRepository ar,
                  AuthzTokenParser authParser)
           throws PbaException

This constructor is used by all other constructors indirectly.

Parameters:

pf - - the PolicyFinder that locates the policy; if null, initialisation fails

ar - - the AttributeRepository used to retrieve Authorisation Tokens; if null, PERMIS will use the repositories specified in the policy, but if no repositories are specified there, PERMIS will work only in push mode (i.e. calls to getCreds without pushed authorisation tokens will yield subjects with no credentials)

authParser - - the AuthTokenParser used to decode the Authorisation Tokens pushed or pulled from repository; if null, the default AuthTokenParser set in CustomisePERMIS will be used

Throws:

PbaException

See Also:

CustomisePERMIS#getAuthTokenParser, CustomisePERMIS.addURLHandler(java.lang.String), URLHandler.getRepositoryByURL(java.lang.String), URLHandler.addProtocol(URLHandler)

Method Detail

decision

public boolean decision(Subject subject,
                        Action action,
                        Target target,
                        java.util.Map applicationContext)
                 throws PbaException

This method returns the boolean result of evaluating the Access Control Decision Function.(decision() is only here for backward compatibility. New applications should use the response() method.)

Specified by:

decision in interface PBAAPI

Parameters:

subject - the subject wishing to carry out the action on the target

action - the action that the subject wishes to carry out

target - the target object on which the action is carried out

applicationContext - a list of application contextual parameters

Returns:

true, if the requested access should be granted; false otherwise

Throws:

PbaException, - if the decision could not be made, or it can't be enforced (e.g. an Obligation must be enforced - use a response method in such cases)

PbaException

See Also:

PbaException

authzDecision

public Response authzDecision(Subject subject,
                              Action action,
                              Target target,
                              java.util.Map applicationContext)
                       throws PbaException

This method makes a decision, and in addition to that can provide a set of Obligations that the system must fulfil upon enforcement of the decision.(The method name is changed from response() to authzDecision())

Specified by:

authzDecision in interface PBAAPI

Parameters:

subject - the subject wishing to carry out the action on the target

action - the action that the subject wishes to carry out

target - the target object on which the action is carried out

applicationContext - a list of application contextual parameters

Returns:

response to the request. The response contains a decision and the associcated obligations if any.

Throws:

PbaException

See Also:

The method name is changed from response() to authzDecision()

getCreds

public Subject getCreds(java.security.Principal subjectDN)
                 throws PbaException

This method returns the credentials of the subject whose Principal is supplied (e.g. LDAPDNPrincipal represents the Subject's LDAP DN). (The PULL Model)

Parameters:

subjectDN - is the name of the subject

Returns:

the Subject object

Throws:

PbaException

getCreds

public Subject getCreds(java.security.Principal subjectDN,
                        CredentialsService service)
                 throws PbaException

This method returns the credentials of the subject whose Principal is supplied (e.g. LDAPDNPrincipal represents the Subject's LDAP DN). (The PULL Model)

It does the same as getCreds(Principal), but in addition sets a service specified by the AEF; for example session time, after which the credentials will be automatically expired.

Specified by:

getCreds in interface PBAAPI

Parameters:

subjectDN - is the name of the subject

service - is an object that will perform some additional checks on the returned set of credentials each time the decision is made (for example, Session Time); if null, no additional service is provided for the resulting Subject object

Returns:

the Subject object

Throws:

PbaException

See Also:

getCreds(Principal)

getCreds

public Subject getCreds(java.security.Principal subjectDN,
                        java.lang.Object[] creds)
                 throws PbaException

This method returns the credentials of the subject whose Principal and Authorisation Tokens are supplied (e.g. LDAPDNPrincipal represents the Subject's LDAP DN, and byte arrays of BER-encoded Attribute Certificates represent the Authorisation Tokens). (The PUSH Model)

Parameters:

subjectDN - is the name of the subject

creds - is the array of raw Authorisation Tokens, which will be parsed by the default AuthTokenParser (e.g. BER-encoded X.509 ACs) or an array of ParsedTokens (already parsed by your custom code); in both cases containing the whole delegation chain must be provided

Returns:

the Subject object

Throws:

PbaException

getCreds

public Subject getCreds(java.security.Principal subjectDN,
                        java.lang.Object[] creds,
                        CredentialsService service)
                 throws PbaException

This method returns the credentials of the subject whose Principal and Authorisation Tokens are supplied (e.g. LDAPDNPrincipal represents the Subject's LDAP DN, and byte arrays of BER-encoded Attribute Certificates represent the Authorisation Tokens). (The PUSH Model)

Specified by:

getCreds in interface PBAAPI

Parameters:

subjectDN - is the name of the subject

creds - is the array of raw Authorisation Tokens, which will be parsed by the default AuthTokenParser (e.g. BER-encoded X.509 ACs) or an array of ParsedTokens (already parsed by your custom code); in both cases containing the whole delegation chain must be provided

service - is the service to attach to the credentials

Returns:

the Subject object with CredentialService attached to it

Throws:

PbaException

getCreds

public Subject getCreds(java.security.Principal subject,
                        java.lang.String[] urls,
                        AuthzTokenParser authParser)
                 throws PbaException

This method returns the credentials of the subject, given the subject Principal and an array of repository URLs where his credentials are stored - semi-pull model. The method doesn't check whether all of the repositories are connectable. If they are not, a partial or even empty set of credentials will be returned.

Parameters:

subject - - the Principal of the subject

urls - - the array of the URLs of the repositories where the subject's credentials are stored.

authParser - - the AuthTokenParser to use when parsing the Authorisation Tokens; if null, the default AuthTokenParser will be used

Returns:

the Subject object

Throws:

PbaException

getCreds

protected Subject getCreds(UserEntry subjectDN,
                           java.lang.Object[] creds,
                           AuthzTokenRepository repository,
                           CredentialsService service)
                    throws PbaException

This is the root of the family of all getCreds; it can do both push and pull, and can set credentials lifetime for the given subject.

Parameters:

subjectDN - is the identifier of the subject; when X.509 flavour is configured it must contain either the PKC subject DN, or the PKC SerialNumber and Issuer DN, or both

creds - is an array of Authorisation Tokens (e.g. AttributeCertificates to use (push model); can be null (pull model)

repository - - the AuthTokenRepository from which the missing Authorisation Tokens will be obtained; if null, the AuthTokenRepository provided at construction time will be used; if creds is not null, this parameter is ignored

service - is attached to the Subject object, and will be called each time a decision is made; this way, for example, it is possible to expire the Subject object by throwing an exception

Throws:

PbaException

newPermisSubject

protected PermisSubject newPermisSubject(java.security.Principal dn,
                                         CredentialsService service,
                                         java.lang.String policyOID,
                                         Credentials creds)

Creates a Subject from the given parameters. This method should be overridden by any class that wants another implementation of Subject.

Parameters:

dn - the Principal

service - the service to use

policyOID - a string identifying the policy

creds - the Credentials for the subject to be returned

Returns:

the subject that is created

initEnv

protected java.util.Map initEnv(java.util.Map env)

This method fills in the default variables that this version of PermisRBAC requires.

finalize

protected void finalize()

This method is called by gc (JVM's Garbage Collector) when the Permis RBAC object is no longer referenced.

Overrides:

finalize in class java.lang.Object

SAWSCloseLog

public void SAWSCloseLog()

getTimeOut

public int getTimeOut()

This method returns the time-out parameter of the system.

getRepositories

public static MultiRepository getRepositories(java.lang.String[] urls)

This utility method will build a MultiRepository given a list of URLs. If a repository could not be contacted, it is removed from the list. Query the getRepositories methods on MultiRepository to see what repositories are used.

Parameters:

urls - - the array of URLs for which a MultiRepository is built; Bad URLs or Repositories that could not be contacted, are ignored

Returns:

MultiRepository that connects to all the specified URLs simultaneously, or null, if urls is null

getRepositories

protected static MultiRepository getRepositories(java.lang.String[] urls,
                                                 java.lang.String[] urls2)

This method builds a MultiRepository that accesses two sets of repositories simultaneously. Either or both arrays can be null.

This method is useful when initialising PERMIS RBAC with two sets of repositories: one read from a configuration, one obtained from a policy. Both sets are treated equally and neither is excluded from use.

Parameters:

urls - - the array of URLs; can be null

urls2 - - the array of URLs; can be null

getPolicyFinder

public PolicyFinder getPolicyFinder()

This method returns the PolicyFinder used to initialise the object. Never null.