NAME

VUser::ACL - vuser access control lists

DESCRIPTION

METHODS

revision

Returns the extension's revision. This is may return an empty string;

version

Returns the extensions official version. This man not return an empty string.

DESIGN DISCUSSION

NB: The following discussion was used as a design guide and will probably match up with the implementation but it may not. When it doubt, consult the API docs and/or the code. -- PerlStalker

We need to provide two features: authentication and access control. Storage for each should support backends such as SQLite, MySQL, etc.

Authentication

Probably the most varied module. I can imagine many installs that will want to use vuser specific user stores in a local DB and others that will auth against, e.g. POP3 or IMAP. The auth system must be flexible to support these plus any others that a local admin may want to add. This is similar to to the current extension framework and a similar API should probably be used.

If we're going to match the Extension system, then we need a register*() function or two.

register_auth (\&sub)

\&sub is a reference to a sub that takes the following params:

$cfg

A reference to the Config::IniFile hash. This is the same as what's passed to tasks by ExtHandler.

$user

The username of the account trying to connect.

$password

The password of the user trying to connect.

$ip_address

The IP address of the user trying to connect. sub() may use the IP address to restrict access but is not required to. Note: Further access control by IP address is provided by the access control system described below.

sub() returns one of three possible values:

ALLOW

The user is authenticated. Processing stops.

DENY

The user is denied. Processing stops. Because there may be many more modules handling authentication, auth modules are encouraged to return UNKNOWN if the user does not exist, but should return DENY if the user exists but the passwords don't match.

UNKNOWN

sub() was unable to determine if the user should be allowed or not. Processing continues. If no sub() returns an ALLOW or DENY response, the user is denied.

auth_add

auth_get

Plugins must return an array of hash refs with keys: user, password, ip.

Access Control

Just because a user authenticates doesn't mean that he needs access to everything that vuser might let him do. This is more vuser specific than the auth module discussed above. Here about the only thing we need to worry about is different storage backends. However, since we don't know all the possible backends that could be used, we'll use a registration system here, too.

register_acl (\&sub)

\&sub is a reference to a sub that takes the following params:

$cfg

A reference to the Config::IniFile hash. This is the same as what's passed to tasks by ExtHandler.

$user

The user that wants to do something.

$ip_address

The IP address of the user.

$keyword

The keyword

$action

The action the user is trying to run. If action is '_meta', then the option (below) is treated as a meta data name.

$option

An option to the keyword/action pair.

$value

The value of the option above. Having the value allows us to allow a user to see/change/delete/whatever certain values but not others. This may be a pattern or regex.

For example, one might allow an email user to be able to use vuser to change their password or the password of some number of sub accounts. Specifically, postmaster@example.com could be allowed to change passwords for sally@example.com, joe@example or any address in the example.com domain but sally@example.com could only change her own password.

Any or all of the above parameters may be used to restrict (or grant) access. sub() must return one of the following values:

ALLOW

Allow the user to do the action with the actions.

DENY

User is not allowed to do the action.

UNKNOWN

The ACL module was not able to determine if the user is allowed or not. If no module returns an ALLOW or DENY, then access is denied or allowed based on a setting in the config file.

acl_add

This is run as a regular task.

A note about the user option: user is the actual user name of the user or '#name' for a group. The group '#GLOBAL' is reserved. #GLOBAL allows an admin to set permissions for all users.

AUTHOR

Randy Smith <perlstalker@gmail.com>

LICENSE

This file is part of vuser.

vuser is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.

vuser is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with vuser; if not, write to the Free Software
Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA