NAME

Authz::Path - Use XPath-like ACLs

SYNOPSIS

$authz = new My::ACLs;

if($authz -> has_attributes($user, $path, $attrs)) {
   # do something
}

DESCRIPTION

Authz::Path provides the basic logic for ACLs. It is an abstract class that does not actual manage the storage of ACLs. You will need to subclass Authz::Path and provide a storage mechanism.

PATHS

Paths are made up of a sub-set of the XPath language:

/

The slash (/) is the component separator. Alone, it describes the root of the resource heirarchy.

//

The double slash (//) stands in place of any number of components (zero or more). Alone, it matches any possible path that does not specify attributes or a final component. To match any component with any attributes, use //*|//*@*.

@

The at sign (@) is the attribute separator. A path should only have one. It separates the final component from any attribute. If no attribute follows it, it stands for the general collection of attributes for an object.

|

The pipe symbol (|) separates paths which together specify a union.

&

The ampersand (&) separates paths which together specify an intersection. Intersection has higher precedence to union. For example, the path //a/* & //*@name | //b/* is considered to be (//a/* & //*@name) | //b/*, not //a/* & (//*@name | //b/*). There are no parenthesis for grouping in actual path expressions.

!

An odd number of initial bangs (!) will negate the following clause, up to a pipe (|) or ampersand (&). An even number of initial bangs will have no effect.

Paths may also contain special components:

SELF

This refers to the path describing the user or actor. This allows the specification of ACLs that are specific to each user without having to have a separate ACL for each user. For example, to allow each user their own test area, allow /testing/SELF//* for all users that can do testing.

SELFTYPE

This refers to the type of object described by SELF. This defaults to user.

Fn

The components beginning with F followed by an integer refer to particular parts of the user path that are variable, such as // or *. These are numbered starting at 1 and increasing as they are encountered. Each part of an intersection is also counted.

Examples

The following are some examples of paths.

//*

This matches any path. Attaching attributes to this path will apply them to all objects.

//*@name

This matches the name attribute of all objects.

//*/*

This matches any component that is not at the top-level.

!//a//* & //b//*

This matches any path that has a b component and not an a component.

METHODS

fetch_acls

$acls = $authz -> fetch_acls($user, $resource)

This method must be defined in the derived class. This method provides any ACL information that might be useful in the current ACL query as indicated by the user and resource string arguments.

The return value is a hash reference with the following structure:

{ user_path => { resource_path => { %attributes } } }

The attribute mapping maps attribute names to numeric values. Negative values are considered to be prohibitive while positive values are permissive. Undefined or zero values are ignored.

Both $user and $resource will be array references. The first element will be the type of object the path is referring to. The second element will be the path describing the set of such objects.

The safest set of information to return is all ACLs that describe the relationship between the $user and $resource object types.

fetch_groups

$groups = $authz -> fetch_groups($user);

This method must be defined in the derived class. This method provides the list of user groups the given $user belongs to. The $user may be an actual user or a group.

$user will be an array reference. The first element will be the type of the object the path is referring to. The second element will be the path describing the set of such objects.

This method should return an array reference to a list of group names. No object types should be specified since they are all user groups.

fetch_resource_groups

$groups = $authz -> fetch_resource_groups($resource);

This method must be defined in the derived class. This method provides the list of resource groups the given $resource belongs to.

$resource will be an array reference. The first element will be the type of the object the path is referring to. The second element will be the path describing the set of such objects.

This method should return an array reference to a list of group names. No object types should be specified since they are all resource groups.

ACLs applied to a resource group restrict the possible ACLs that may be applied to the resource group for a user or user group. This makes it easy to manage what can be done to a set of resources whether or not anyone is actually allowed to do it.

new

This creates a new authorization object. The following options may be passed.

group

This is the string to use to denote the user group type.

resource_group

This is the string to use to denote the resource group type.

user

This is the string to use to denote the user type.

path_cmp

This method may be called as either a static function or an object method. If an object is used, then the regular expression translations of the path expressions are cached in the object.

Static method:  Authz::Path::path_cmp($path_a, $path_b)
Object method: $authz -> path_cmp($path_a, $path_b)

Comparisons of intersections with other intersections are not supported (i.e., only one of the paths should have an intersection). Likewise, only one of the paths should contain negations.

This method returns one of four values:

undef

The two paths describe disjoint sets.

0

The two paths describe overlapping sets. Both of the paths describe elements not described by the other.

1

The first path describes a superset of the set described by the second path, or the two paths describe equivalent sets.

-1

The first path describes a subset of the set described by the second path.

path2regex

This method will translate a path to a regular expression. The path_cmp method uses this for certain comparisons.

If this is called as an object method, it will cache translations. Otherwise, it may be called as a static method.

Static method: Authz::Path::path2regex($path);
Object method: $authz -> path2regex($path)

Some example translations (cleaned up a little):

//*@*

qr(?-xism:(?:
    /+           # one or more initial slashes
    ((?:
        [^/@|&]+
        /+
    )*)          # any number of slash-separated path components
    (?:/)*       # any number of trailing slashes
    ([^/@|&]+)   # component
    @
    ([^/@|&]+)   # attribute
) )x

/*/a | /*/b

qr(?-xism:
    (?:/([^/@|&]+)/b)  # /<any component>/b
    |                  # OR
    (?:/([^/@|&]+)/a)  # /<any component>/a
)x

/*/a & /*/*@*

qr(?-xism:(?:
   (?(?=/([^/@|&]+)/a)   # if we match /<any component>/a
       (?:               # then match:
           /
           ([^/\@\|&]+)  # any component
           /
           ([^/\@\|&]+)  # any component
           @
           ([^/\@\|&]+)  # any attribute
       )
   )                     # otherwise, we fail
))x

!//a//* & //b//*

qr(?-xism:(?:
   (?(?=
       (?:
           (?! /+((?:[^/@|&]+/+)*)(?:/)*a/+((?:[^/@|&]+/+)*)(?:/)*([^/@|&]+))
           |
           (?:!/+((?:[^/@|&]+/+)*)(?:/)*a/+((?:[^/@|&]+/+)*)(?:/)*([^/@|&]+))
       )
     )
     (?:
               /+((?:[^/@|&]+/+)*)(?:/)*b/+((?:[^/@|&]+/+)*)(?:/)*([^/@|&]+)
     )
   )
))x

query_acls

query_attributes

AUTHOR

James G. Smith, <jsmith@cpan.org>

COPYRIGHT

Copyright (C) 2003 Texas A&M University. All Rights Reserved.

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

cpanm Gestinanna

perl -MCPAN -e shell
install Gestinanna