.\" Automatically generated by Pod::Man 4.09 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.if !\nF .nr F 0
.if \nF>0 \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    if !\nF==2 \{\
.        nr % 0
.        nr F 2
.    \}
.\}
.\" ========================================================================
.\"
.IX Title "Apache2::SiteControl::PermissionManager 3pm"
.TH Apache2::SiteControl::PermissionManager 3pm "2018-08-31" "perl v5.26.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Apache2::SiteControl::PermissionManager \- Rule\-based permission management
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  use Apache2::SiteControl::PermissionManager;
\&
\&  $manager = new Apache2::SiteControl::PermissionManager();
\&  $rule1 = new SomeSubclassOfSiteControl();
\&  $manager\->addRule($rule1);
\&  ...
\&
\&  $user = new SomeUserTypeYouDefineThatMakesSenseToRules;
\&
\&  if($manager\->can($user, $action, $resource)) {
\&     # OK to do action
\&  }
\&
\&  # For example
\&
\&  if($manager\->can($user, "read", "/etc/shadow")) {
\&     open DATA, "</etc/shadow";
\&     ...
\&  }
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module implements a user capabilities \s-1API.\s0 The basic idea is that you have
a set of users and a set of things that can be done in a system. In the code of
the system itself, you want to surround sensitive operations with code that
determines if the current user is allowed to do that operation.
.PP
This module attempts to make such a system possible, and easily extensible.
The module requires that you write implementations of rules for you system
that are subclasses of Apache2::SiteControl::Rule. The rules can be written to 
use any data types, which are abstractly known as \*(L"users\*(R", \*(L"actions\*(R", and
\&\*(L"resources.\*(R"
.PP
A user is some object that your applications uses to identify the person
operating the program. The expectation is that at some point the application 
authenticated the user and obtained their identity, and the rest of the 
application is merely applying a ruleset to determine what that user is
allowed to do. In the context of the SiteControl system, this user is a 
Apache2::SiteControl::User or subclass thereof.
.PP
An action can be any data type (i.e. simply a string). Again, it is really up
to the code of the rules (which are primarily written by you) to determine what
is valid.
.PP
The overall usage of this package is as follows:
.IP "\fB1.\fR Decide how you want to represent a user. (i.e. Apache2::SiteControl::User)" 8
.IX Item "1. Decide how you want to represent a user. (i.e. Apache2::SiteControl::User)"
.PD 0
.IP "\fB2.\fR Decide the critical sections of your code that need to be protected, and decide what to do if the user doesn't pass muster. For example if a screen should just hide fields, then the application code needs to reflect that." 8
.IX Item "2. Decide the critical sections of your code that need to be protected, and decide what to do if the user doesn't pass muster. For example if a screen should just hide fields, then the application code needs to reflect that."
.IP "\fB3.\fR Create a permission manager instance for your application. Typically use a singleton pattern (there need be only one manager). In the SiteControl system, this is done by a ManagerFactory that you write." 8
.IX Item "3. Create a permission manager instance for your application. Typically use a singleton pattern (there need be only one manager). In the SiteControl system, this is done by a ManagerFactory that you write."
.IP "\fB4.\fR Surround sensitive sections of code with something like:" 8
.IX Item "4. Surround sensitive sections of code with something like:"
.PD
.Vb 6
\&   if($manager\->can($user, "view salary", $payrollRecord))
\&   {
\&      # show salary fields
\&   } else
\&      # hide salary fields
\&   }
.Ve
.IP "\fB5.\fR Create rules that spell out the behavior you want and add them to your application's permission manager. The basic idea is that a rule can grant permission, or deny it. If it neither grants or denies, then the manager will take the safe route and say that the action cannot be taken. Part of the code for the rule for protecting salaries might look like:" 8
.IX Item "5. Create rules that spell out the behavior you want and add them to your application's permission manager. The basic idea is that a rule can grant permission, or deny it. If it neither grants or denies, then the manager will take the safe route and say that the action cannot be taken. Part of the code for the rule for protecting salaries might look like:"
.Vb 1
\&   package SalaryViewRule;
\&
\&   use Apache2::SiteControl::Rule;
\&   use Apache2::SiteControl::User;
\&
\&   use base qw(Apache2::SiteControl::Rule);
\&
\&   sub grants
\&   {
\&      $this = shift;
\&      $user = shift;
\&      $action = shift;
\&      $resource = shift;
\&
\&      # Do not grant on requests we don\*(Aqt understand.
\&      return 0 if(!$user\->isa("Apache2::SiteControl::User") ||
\&                  !$this\->isa("Apache2::SiteControl::Rule"));
\&
\&      if($action eq "view salary" && $resource\->isa("Payroll::Record")) {
\&         if($user\->getUsername() eq $resource\->getEmployeeName()) {
\&            return "user can view their own salary";
\&         }
\&      }
\&      return 0;
\&   }
.Ve
.Sp
Then in your subclass of ManagerFactory:
.Sp
.Vb 1
\&   use SalaryViewRule;
\&
\&   ...
\&
\&   $viewRule = new SalaryViewRule;
\&   $manager\->addRule($viewRule);
.Ve
.SH "METHODS"
.IX Header "METHODS"
.IP "\fBcan\fR(\fIuser\fR, \fIaction verb\fR, \fIresource\fR)" 8
.IX Item "can(user, action verb, resource)"
This is the primary method of the PermissionManager. It asks if the specified
user can do the specified action on the specified resource. For example,
.Sp
.Vb 1
\&   $manager\->can($user, "eat", "cake");
.Ve
.Sp
would return true if the user is allowed to eat cake. Note that this gives you 
quite a bit of flexibility, but at the expense of strong type safety. It is
suggested that all of your rules do type checking to insure that a rule is 
properly applied.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Apache2::SiteControl::Rule, Apache::SiteControl::ManagerFactory,
Apache2::SiteControl::UserFactory, Apache::SiteControl
.SH "AUTHOR"
.IX Header "AUTHOR"
This module was written by Tony Kay, <tkay@uoregon.edu>.
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"