gacl/docs/manual.html

   1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
   2 <HTML>
   3 <HEAD>
   4         <META HTTP-EQUIV="CONTENT-TYPE" CONTENT="text/html; charset=iso-8859-1">
   5         <TITLE>phpGACL</TITLE>
   6         <META NAME="GENERATOR" CONTENT="OpenOffice.org 2.0  (Linux)">
   7         <META NAME="AUTHOR" CONTENT="jrussell">
   8         <META NAME="CREATED" CONTENT="20030206;8320000">
   9         <META NAME="CHANGED" CONTENT="20060903;16430300">
  10         <META NAME="SDFOOTNOTE" CONTENT=";;;;P">
  11         <META NAME="SDENDNOTE" CONTENT="ARABIC">
  12         <STYLE TYPE="text/css">
  13         <!--
  14                 @page { size: 8.27in 11.69in; margin: 1.18in }
  15                 P { margin-top: 0.08in; margin-bottom: 0.08in; color: #000000; line-height: 0.17in; widows: 2; orphans: 2 }
  16                 P.western { font-family: "Bitstream Vera Sans Mono", sans-serif; font-size: 10pt; so-language: en-US }
  17                 P.cjk { font-family: "Times New Roman", serif; font-size: 10pt; so-language: ja-JP }
  18                 H1 { margin-bottom: 0.04in; border-top: none; border-bottom: 1px solid #4700b8; border-left: 5.00pt solid #4700b8; border-right: none; padding-top: 0in; padding-bottom: 0.02in; padding-left: 0.02in; padding-right: 0in; color: #000000; widows: 2; orphans: 2; page-break-before: always }
  19                 H1.western { font-family: "Arial", sans-serif; font-size: 16pt; so-language: en-GB }
  20                 H1.cjk { font-family: "MS Mincho", "MS ??", monospace; font-size: 16pt; so-language: ja-JP }
  21                 H1.ctl { font-family: "Arial Unicode MS"; font-size: 12pt; font-weight: medium }
  22                 H2 { margin-bottom: 0.04in; color: #000000; widows: 2; orphans: 2 }
  23                 H2.western { font-family: "Georgia", serif; font-size: 13pt; so-language: en-GB; font-style: normal }
  24                 H2.cjk { font-family: "MS Mincho", "MS ??", monospace; font-size: 14pt; so-language: ja-JP; font-style: italic }
  25                 H2.ctl { font-family: "Arial Unicode MS"; font-size: 12pt; font-weight: medium }
  26                 H3 { margin-top: 0.08in; margin-bottom: 0.08in; color: #000000; line-height: 0.17in; widows: 2; orphans: 2 }
  27                 H3.western { font-family: "Helv", "Arial", sans-serif; font-size: 10pt; so-language: en-GB }
  28                 H3.cjk { font-family: "Times New Roman", serif; font-size: 10pt; so-language: ja-JP }
  29                 H3.ctl { font-family: "Arial Unicode MS"; font-size: 12pt; font-weight: medium }
  30                 H4 { margin-top: 0.08in; margin-bottom: 0.08in; color: #000000; line-height: 0.17in; widows: 2; orphans: 2 }
  31                 H4.western { font-family: "Helv", "Arial", sans-serif; font-size: 10pt; so-language: en-GB; font-style: italic; font-weight: medium }
  32                 H4.cjk { font-family: "Times New Roman", serif; font-size: 10pt; so-language: ja-JP; font-style: italic; font-weight: medium }
  33                 H4.ctl { font-family: "Arial Unicode MS"; font-size: 12pt; font-weight: medium }
  34                 A:link { color: #0000ff }
  35         -->
  36         </STYLE>
  37 </HEAD>
  38 <BODY LANG="en-US" TEXT="#000000" LINK="#0000ff" DIR="LTR">
  39 <P LANG="en-GB" ALIGN=CENTER STYLE="margin-top: 0.17in; line-height: 100%; page-break-after: avoid">
  40 <IMG SRC="manual_html_m54d0ced8.png" NAME="Graphic6" ALIGN=RIGHT WIDTH=165 HEIGHT=45 BORDER=0><BR CLEAR=RIGHT><BR><BR>
  41 </P>
  42 <P LANG="en-GB" ALIGN=CENTER STYLE="margin-top: 0.17in; line-height: 100%; page-break-after: avoid">
  43 <FONT FACE="Luxi Sans, sans-serif"><FONT SIZE=5><B>Generic Access
  44 Control Lists with PHP</B></FONT></FONT></P>
  45 <P CLASS="western"><FONT FACE="Bitstream Vera Sans Mono, sans-serif">Mike
  46 Benoit &lt;</FONT><FONT COLOR="#0000ff"><U><A HREF="mailto:ipso@snappymail.ca"><FONT FACE="Bitstream Vera Sans Mono, sans-serif">ipso@snappymail.ca</FONT></A></U></FONT><FONT FACE="Bitstream Vera Sans Mono, sans-serif">&gt;<BR>James
  47 Russell &lt;</FONT><A HREF="mailto:james-phpgacl@ps2-pro.com"><FONT FACE="Bitstream Vera Sans Mono, sans-serif">james-phpgacl@ps2-pro.com</FONT></A><FONT FACE="Bitstream Vera Sans Mono, sans-serif">&gt;<BR>Karsten
  48 Dambekalns &lt;</FONT><A HREF="mailto:k.dambekalns@fishfarm.de"><FONT FACE="Bitstream Vera Sans Mono, sans-serif">k.dambekalns@fishfarm.de</FONT></A><FONT FACE="Bitstream Vera Sans Mono, sans-serif">&gt;</FONT></P>
  49 <P CLASS="western"><FONT FACE="Bitstream Vera Sans Mono, sans-serif">Copyright
  50 &copy; 2002-2006 Mike Benoit<BR>Copyright &copy; 2003, James
  51 Russell<BR>Copyright &copy; 2003, Karsten Dambekalns</FONT></P>
  52 <P CLASS="western"><FONT FACE="Bitstream Vera Sans Mono, sans-serif">Document
  53 Version: 60</FONT></P>
  54 <P CLASS="western"><FONT FACE="Bitstream Vera Sans Mono, sans-serif">Last
  55 Updated:<B> <SDFIELD TYPE=DATETIME SDNUM="1033;1033;MMMM D, YYYY">September 3, 2006</SDFIELD>
  56 - <SDFIELD TYPE=DATETIME SDVAL="37761.788287037" SDNUM="1033;1033;HH:MM AM/PM">06:55 PM</SDFIELD></B></FONT></P>
  57 <H1 LANG="en-GB" CLASS="western">Table of Contents</H1>
  58 <DIV ID="Table of Contents1" DIR="LTR" STYLE="background: transparent">
  59         <P LANG="en-GB" STYLE="margin-top: 0in; margin-bottom: 0.08in; line-height: 100%">
  60         <FONT FACE="Arial, sans-serif">Table of Contents        2</FONT></P>
  61         <P LANG="en-GB" STYLE="margin-top: 0in; margin-bottom: 0.08in; line-height: 100%">
  62         <FONT FACE="Arial, sans-serif">About    4</FONT></P>
  63         <P LANG="en-GB" STYLE="margin-left: 0.17in; text-indent: 0in; margin-top: 0in; margin-bottom: 0.08in; line-height: 100%">
  64         <FONT FACE="Arial, sans-serif">What is it?      4</FONT></P>
  65         <P LANG="en-GB" STYLE="margin-left: 0.17in; text-indent: 0in; margin-top: 0in; margin-bottom: 0.08in; line-height: 100%">
  66         <FONT FACE="Arial, sans-serif">Where can I get it?      4</FONT></P>
  67         <P LANG="en-GB" STYLE="margin-left: 0.17in; text-indent: 0in; margin-top: 0in; margin-bottom: 0.08in; line-height: 100%">
  68         <FONT FACE="Arial, sans-serif">What do I need to run it?        4</FONT></P>
  69         <P LANG="en-GB" STYLE="margin-left: 0.17in; text-indent: 0in; margin-top: 0in; margin-bottom: 0.08in; line-height: 100%">
  70         <FONT FACE="Arial, sans-serif">Who is responsible for it?       4</FONT></P>
  71         <P LANG="en-GB" STYLE="margin-top: 0in; margin-bottom: 0.08in; line-height: 100%">
  72         <FONT FACE="Arial, sans-serif">Introduction     5</FONT></P>
  73         <P LANG="en-GB" STYLE="margin-left: 0.17in; text-indent: 0in; margin-top: 0in; margin-bottom: 0.08in; line-height: 100%">
  74         <FONT FACE="Arial, sans-serif">Understanding Access Control     5</FONT></P>
  75         <P LANG="en-GB" STYLE="margin-left: 0.33in; text-indent: 0in; margin-top: 0in; margin-bottom: 0.08in; line-height: 100%">
  76         <FONT FACE="Arial, sans-serif">Who/Where        5</FONT></P>
  77         <P LANG="en-GB" STYLE="margin-left: 0.33in; text-indent: 0in; margin-top: 0in; margin-bottom: 0.08in; line-height: 100%">
  78         <FONT FACE="Arial, sans-serif">Who/Where        6</FONT></P>
  79         <P LANG="en-GB" STYLE="margin-left: 0.17in; text-indent: 0in; margin-top: 0in; margin-bottom: 0.08in; line-height: 100%">
  80         <FONT FACE="Arial, sans-serif">Defining access control with
  81         phpGACL 6</FONT></P>
  82         <P LANG="en-GB" STYLE="margin-left: 0.17in; text-indent: 0in; margin-top: 0in; margin-bottom: 0.08in; line-height: 100%">
  83         <FONT FACE="Arial, sans-serif">Fine-grain access control        8</FONT></P>
  84         <P LANG="en-GB" STYLE="margin-left: 0.17in; text-indent: 0in; margin-top: 0in; margin-bottom: 0.08in; line-height: 100%">
  85         <FONT FACE="Arial, sans-serif">Multi-level Groups       8</FONT></P>
  86         <P LANG="en-GB" STYLE="margin-left: 0.17in; text-indent: 0in; margin-top: 0in; margin-bottom: 0.08in; line-height: 100%">
  87         <FONT FACE="Arial, sans-serif">How does phpGACL determine
  88         permissions?    9</FONT></P>
  89         <P LANG="en-GB" STYLE="margin-left: 0.17in; text-indent: 0in; margin-top: 0in; margin-bottom: 0.08in; line-height: 100%">
  90         <FONT FACE="Arial, sans-serif">Adding groups    10</FONT></P>
  91         <P LANG="en-GB" STYLE="margin-left: 0.17in; text-indent: 0in; margin-top: 0in; margin-bottom: 0.08in; line-height: 100%">
  92         <FONT FACE="Arial, sans-serif">Adding people    11</FONT></P>
  93         <P LANG="en-GB" STYLE="margin-left: 0.17in; text-indent: 0in; margin-top: 0in; margin-bottom: 0.08in; line-height: 100%">
  94         <FONT FACE="Arial, sans-serif">Resolving conflicts      11</FONT></P>
  95         <P LANG="en-GB" STYLE="margin-left: 0.17in; text-indent: 0in; margin-top: 0in; margin-bottom: 0.08in; line-height: 100%">
  96         <FONT FACE="Arial, sans-serif">Naming Access Objects    12</FONT></P>
  97         <P LANG="en-GB" STYLE="margin-left: 0.17in; text-indent: 0in; margin-top: 0in; margin-bottom: 0.08in; line-height: 100%">
  98         <FONT FACE="Arial, sans-serif">Adding Sections  14</FONT></P>
  99         <P LANG="en-GB" STYLE="margin-left: 0.17in; text-indent: 0in; margin-top: 0in; margin-bottom: 0.08in; line-height: 100%">
 100         <FONT FACE="Arial, sans-serif">Multiple Purposes        15</FONT></P>
 101         <P LANG="en-GB" STYLE="margin-left: 0.17in; text-indent: 0in; margin-top: 0in; margin-bottom: 0.08in; line-height: 100%">
 102         <FONT FACE="Arial, sans-serif">Access eXtension Objects 16</FONT></P>
 103         <P LANG="en-GB" STYLE="margin-top: 0in; margin-bottom: 0.08in; line-height: 100%">
 104         <FONT FACE="Arial, sans-serif">Installation     18</FONT></P>
 105         <P LANG="en-GB" STYLE="margin-left: 0.17in; text-indent: 0in; margin-top: 0in; margin-bottom: 0.08in; line-height: 100%">
 106         <FONT FACE="Arial, sans-serif">Basic setup      18</FONT></P>
 107         <P LANG="en-GB" STYLE="margin-left: 0.17in; text-indent: 0in; margin-top: 0in; margin-bottom: 0.08in; line-height: 100%">
 108         <FONT FACE="Arial, sans-serif">Advanced setup   19</FONT></P>
 109         <P LANG="en-GB" STYLE="margin-left: 0.33in; text-indent: 0in; margin-top: 0in; margin-bottom: 0.08in; line-height: 100%">
 110         <FONT FACE="Arial, sans-serif">Reusing an already existing ADOdb
 111         installation    19</FONT></P>
 112         <P LANG="en-GB" STYLE="margin-left: 0.33in; text-indent: 0in; margin-top: 0in; margin-bottom: 0.08in; line-height: 100%">
 113         <FONT FACE="Arial, sans-serif">Reusing an already existing Smarty
 114         installation    20</FONT></P>
 115         <P LANG="en-GB" STYLE="margin-left: 0.33in; text-indent: 0in; margin-top: 0in; margin-bottom: 0.08in; line-height: 100%">
 116         <FONT FACE="Arial, sans-serif">How do I move  the phpGACL files out
 117         of my website tree while leaving a link in the tree for
 118         administration? 20</FONT></P>
 119         <P LANG="en-GB" STYLE="margin-top: 0in; margin-bottom: 0.08in; line-height: 100%">
 120         <FONT FACE="Arial, sans-serif">Using phpGACL in your application        21</FONT></P>
 121         <P LANG="en-GB" STYLE="margin-left: 0.17in; text-indent: 0in; margin-top: 0in; margin-bottom: 0.08in; line-height: 100%">
 122         <FONT FACE="Arial, sans-serif">Basic usage      21</FONT></P>
 123         <P LANG="en-GB" STYLE="margin-left: 0.17in; text-indent: 0in; margin-top: 0in; margin-bottom: 0.08in; line-height: 100%">
 124         <FONT FACE="Arial, sans-serif">Advanced usage   21</FONT></P>
 125         <P LANG="en-GB" STYLE="margin-top: 0in; margin-bottom: 0.08in; line-height: 100%">
 126         <FONT FACE="Arial, sans-serif">Using the ACL admin utility      22</FONT></P>
 127         <P LANG="en-GB" STYLE="margin-left: 0.17in; text-indent: 0in; margin-top: 0in; margin-bottom: 0.08in; line-height: 100%">
 128         <FONT FACE="Arial, sans-serif">ACL's    22</FONT></P>
 129         <P LANG="en-GB" STYLE="margin-left: 0.33in; text-indent: 0in; margin-top: 0in; margin-bottom: 0.08in; line-height: 100%">
 130         <FONT FACE="Arial, sans-serif">Creating 22</FONT></P>
 131         <P LANG="en-GB" STYLE="margin-left: 0.33in; text-indent: 0in; margin-top: 0in; margin-bottom: 0.08in; line-height: 100%">
 132         <FONT FACE="Arial, sans-serif">Sections 23</FONT></P>
 133         <P LANG="en-GB" STYLE="margin-left: 0.33in; text-indent: 0in; margin-top: 0in; margin-bottom: 0.08in; line-height: 100%">
 134         <FONT FACE="Arial, sans-serif">Extended Return Value    24</FONT></P>
 135         <P LANG="en-GB" STYLE="margin-left: 0.33in; text-indent: 0in; margin-top: 0in; margin-bottom: 0.08in; line-height: 100%">
 136         <FONT FACE="Arial, sans-serif">Notes    24</FONT></P>
 137         <P LANG="en-GB" STYLE="margin-top: 0in; margin-bottom: 0.08in; line-height: 100%">
 138         <FONT FACE="Arial, sans-serif">Glossary 25</FONT></P>
 139         <P LANG="en-GB" STYLE="margin-left: 0.17in; text-indent: 0in; margin-top: 0in; margin-bottom: 0.08in; line-height: 100%">
 140         <FONT FACE="Arial, sans-serif">ACO      25</FONT></P>
 141         <P LANG="en-GB" STYLE="margin-left: 0.17in; text-indent: 0in; margin-top: 0in; margin-bottom: 0.08in; line-height: 100%">
 142         <FONT FACE="Arial, sans-serif">ARO      25</FONT></P>
 143         <P LANG="en-GB" STYLE="margin-left: 0.17in; text-indent: 0in; margin-top: 0in; margin-bottom: 0.08in; line-height: 100%">
 144         <FONT FACE="Arial, sans-serif">AXO      25</FONT></P>
 145         <P LANG="en-GB" STYLE="margin-top: 0in; margin-bottom: 0.08in; line-height: 100%">
 146         <FONT FACE="Arial, sans-serif">References       26</FONT></P>
 147         <P LANG="en-GB" STYLE="margin-left: 0.17in; text-indent: 0in; margin-top: 0in; margin-bottom: 0.08in; line-height: 100%">
 148         <FONT FACE="Arial, sans-serif">phpGACL API      26</FONT></P>
 149         <P LANG="en-GB" STYLE="margin-left: 0.17in; text-indent: 0in; margin-top: 0in; margin-bottom: 0.08in; line-height: 100%">
 150         <FONT FACE="Arial, sans-serif">phpGACL Examples and Tutorials   26</FONT></P>
 151         <P LANG="en-GB" STYLE="margin-left: 0.17in; text-indent: 0in; margin-top: 0in; margin-bottom: 0.08in; line-height: 100%">
 152         <FONT FACE="Arial, sans-serif">Access Control Resources 26</FONT></P>
 153         <P LANG="en-GB" STYLE="margin-top: 0in; margin-bottom: 0.08in; line-height: 100%">
 154         <FONT FACE="Arial, sans-serif">FAQ      27</FONT></P>
 155         <P LANG="en-GB" STYLE="margin-left: 0.17in; text-indent: 0in; margin-top: 0in; margin-bottom: 0.08in; line-height: 100%">
 156         <FONT FACE="Arial, sans-serif">Can phpGACL handle large sets of
 157         data?   27</FONT></P>
 158 </DIV>
 159 <P LANG="en-GB" STYLE="margin-top: 0in; margin-bottom: 0.08in; line-height: 100%">
 160 <BR><BR>
 161 </P>
 162 <H1 LANG="en-GB" CLASS="western">About</H1>
 163 <H2 LANG="en-GB" CLASS="western"><FONT FACE="Bitstream Vera Sans Mono, sans-serif">What
 164 is it?</FONT></H2>
 165 <P CLASS="western"><FONT FACE="Bitstream Vera Sans Mono, sans-serif">phpGACL
 166 is an set of functions that allows you to apply access control to
 167 arbitrary objects (web pages, databases, etc) by other arbitrary
 168 objects (users, remote hosts, etc).</FONT></P>
 169 <P CLASS="western"><FONT FACE="Bitstream Vera Sans Mono, sans-serif">It
 170 offers fine-grained access control with simple management, and is
 171 very fast.</FONT></P>
 172 <P CLASS="western"><FONT FACE="Bitstream Vera Sans Mono, sans-serif">It
 173 is written in PHP (hence <B>php</B>GACL), a popular scripting
 174 language that is commonly used to dynamically create web pages. The
 175 GACL part of phpGACL stands for Generic Access Control List.</FONT></P>
 176 <H2 LANG="en-GB" CLASS="western"><FONT FACE="Bitstream Vera Sans Mono, sans-serif">Where
 177 can I get it?</FONT></H2>
 178 <P CLASS="western"><FONT FACE="Bitstream Vera Sans Mono, sans-serif">phpGACL
 179 is hosted by sourceforge.net at </FONT><A HREF="http://phpGACL.sourceforge.net/"><FONT FACE="Bitstream Vera Sans Mono, sans-serif">http://phpGACL.sourceforge.net/</FONT></A></P>
 180 <H2 LANG="en-GB" CLASS="western"><FONT FACE="Bitstream Vera Sans Mono, sans-serif">What
 181 do I need to run it?</FONT></H2>
 182 <P CLASS="western"><FONT FACE="Bitstream Vera Sans Mono, sans-serif">phpGACL
 183 requires a relational database to store the access control
 184 information. It accesses this database via an abstract wrapper called
 185 </FONT><A HREF="http://php.weblogs.com/adodb"><FONT FACE="Bitstream Vera Sans Mono, sans-serif">ADOdb</FONT></A><FONT FACE="Bitstream Vera Sans Mono, sans-serif">.
 186 This is compatible with databases such as PostgreSQL, MySQL and
 187 Oracle.</FONT></P>
 188 <P CLASS="western"><FONT FACE="Bitstream Vera Sans Mono, sans-serif">phpGACL
 189 is written in the </FONT><A HREF="http://www.php.net/"><FONT FACE="Bitstream Vera Sans Mono, sans-serif">PHP</FONT></A><FONT FACE="Bitstream Vera Sans Mono, sans-serif">
 190 scripting language. It requires PHP 4.2 and above.</FONT></P>
 191 <P CLASS="western"><FONT FACE="Bitstream Vera Sans Mono, sans-serif">Access
 192 Control List administration is performed by a web interface, and
 193 therefore it is necessary to have a web server with PHP support, such
 194 as </FONT><A HREF="http://httpd.apache.org/"><FONT FACE="Bitstream Vera Sans Mono, sans-serif">Apache</FONT></A><FONT FACE="Bitstream Vera Sans Mono, sans-serif">.</FONT></P>
 195 <H2 LANG="en-GB" CLASS="western"><FONT FACE="Bitstream Vera Sans Mono, sans-serif">Who
 196 is responsible for it?</FONT></H2>
 197 <P CLASS="western"><FONT FACE="Bitstream Vera Sans Mono, sans-serif">Mike
 198 Benoit &lt;</FONT><A HREF="mailto:ipso@snappymail.ca"><FONT FACE="Bitstream Vera Sans Mono, sans-serif">ipso@snappymail.ca</FONT></A><FONT FACE="Bitstream Vera Sans Mono, sans-serif">&gt;
 199 is the author and project manager.</FONT></P>
 200 <P CLASS="western"><FONT FACE="Bitstream Vera Sans Mono, sans-serif">James
 201 Russell &lt;j</FONT><A HREF="mailto:ames-phpgacl@ps2-pro.com"><FONT FACE="Bitstream Vera Sans Mono, sans-serif">ames-phpgacl@ps2-pro.com</FONT></A><FONT FACE="Bitstream Vera Sans Mono, sans-serif">&gt;
 202 and Karsten Dambekalns &lt;</FONT><A HREF="mailto:k.dambekalns@fishfarm.de"><FONT FACE="Bitstream Vera Sans Mono, sans-serif">k.dambekalns@fishfarm.de</FONT></A><FONT FACE="Bitstream Vera Sans Mono, sans-serif">&gt;
 203 did the documentation.</FONT></P>
 204 <H1 LANG="en-GB" CLASS="western">Introduction</H1>
 205 <H2 LANG="en-GB" CLASS="western"><FONT FACE="Bitstream Vera Sans Mono, sans-serif">Understanding
 206 Access Control</FONT></H2>
 207 <P CLASS="western" STYLE="line-height: 0.17in"><FONT FACE="Bitstream Vera Sans Mono, sans-serif"><FONT SIZE=2>The
 208 best way to explain access control is to use examples with real
 209 things rather than trying to relate to concepts.</FONT></FONT></P>
 210 <P CLASS="western" STYLE="line-height: 0.17in"><FONT FACE="Bitstream Vera Sans Mono, sans-serif"><FONT SIZE=2>Han
 211 is captain of the Millennium Falcon and Chewie is his second officer.
 212 They've taken on board some passengers: Luke, Obi-wan, R2D2 and C3PO.
 213 Han needs to define access restrictions for various rooms of the
 214 ship: The Cockpit, Lounge, Engines and the external Guns.</FONT></FONT></P>
 215 <P CLASS="western" STYLE="line-height: 0.17in"><FONT FACE="Bitstream Vera Sans Mono, sans-serif"><FONT SIZE=2>Han
 216 says: &quot;Me and Chewie should have access to everywhere, but after
 217 a particularly messy hyperdrive repair, I forbid Chewie from going
 218 near the Engine Room ever again. Passengers are confined to the
 219 Passenger's Lounge.&quot;</FONT></FONT></P>
 220 <P CLASS="western" STYLE="line-height: 0.17in"><FONT FACE="Bitstream Vera Sans Mono, sans-serif"><FONT SIZE=2>Let's
 221 assume from now on that access is Boolean. That is, the result of
 222 looking up a person's access to a room is either ALLOW or DENY. There
 223 is no middle ground.</FONT></FONT></P>
 224 <P LANG="en-GB" CLASS="western" STYLE="line-height: 0.17in"><FONT FACE="Bitstream Vera Sans Mono, sans-serif"><FONT SIZE=3><FONT SIZE=2><FONT COLOR="#000000"><SPAN LANG="en-US">If
 225 we mapped this statement into an </SPAN><B>access matrix</B><SPAN LANG="en-US">
 226 showing who has access to where, it would look something like this (O
 227 means ALLOW, X means DENY):</SPAN></FONT></FONT></FONT></FONT></P>
 228 <DL>
 229         <DD>
 230         <TABLE WIDTH=337 BORDER=1 BORDERCOLOR="#000000" CELLPADDING=7 CELLSPACING=0>
 231                 <COL WIDTH=81>
 232                 <COL WIDTH=56>
 233                 <COL WIDTH=44>
 234                 <COL WIDTH=31>
 235                 <COL WIDTH=53>
 236                 <TR VALIGN=TOP>
 237                         <TD WIDTH=81>
 238                                 <H3 LANG="en-GB" CLASS="western" ALIGN=RIGHT><FONT FACE="Bitstream Vera Sans Mono, sans-serif">Who/Where</FONT></H3>
 239                         </TD>
 240                         <TD WIDTH=56>
 241                                 <P CLASS="western" ALIGN=CENTER><FONT FACE="Bitstream Vera Sans Mono, sans-serif"><FONT SIZE=2>Cockpit</FONT></FONT></P>
 242                         </TD>
 243                         <TD WIDTH=44>
 244                                 <P CLASS="western" ALIGN=CENTER><FONT FACE="Bitstream Vera Sans Mono, sans-serif"><FONT SIZE=2>Lounge</FONT></FONT></P>
 245                         </TD>
 246                         <TD WIDTH=31>
 247                                 <P CLASS="western" ALIGN=CENTER><FONT FACE="Bitstream Vera Sans Mono, sans-serif"><FONT SIZE=2>Guns</FONT></FONT></P>
 248                         </TD>
 249                         <TD WIDTH=53>
 250                                 <P CLASS="western" ALIGN=CENTER><FONT FACE="Bitstream Vera Sans Mono, sans-serif"><FONT SIZE=2>Engines</FONT></FONT></P>
 251                         </TD>
 252                 </TR>
 253                 <TR VALIGN=TOP>
 254                         <TD WIDTH=81>
 255                                 <P CLASS="western" ALIGN=RIGHT><FONT FACE="Bitstream Vera Sans Mono, sans-serif"><FONT SIZE=2>Han</FONT></FONT></P>
 256                         </TD>
 257                         <TD WIDTH=56 BGCOLOR="#00ff00">
 258                                 <P CLASS="western" ALIGN=CENTER><FONT FACE="Bitstream Vera Sans Mono, sans-serif"><FONT SIZE=2>O</FONT></FONT></P>
 259                         </TD>
 260                         <TD WIDTH=44 BGCOLOR="#00ff00">
 261                                 <P CLASS="western" ALIGN=CENTER><FONT FACE="Bitstream Vera Sans Mono, sans-serif"><FONT SIZE=2>O</FONT></FONT></P>
 262                         </TD>
 263                         <TD WIDTH=31 BGCOLOR="#00ff00">
 264                                 <P CLASS="western" ALIGN=CENTER><FONT FACE="Bitstream Vera Sans Mono, sans-serif"><FONT SIZE=2>O</FONT></FONT></P>
 265                         </TD>
 266                         <TD WIDTH=53 BGCOLOR="#00ff00">
 267                                 <P CLASS="western" ALIGN=CENTER><FONT FACE="Bitstream Vera Sans Mono, sans-serif"><FONT SIZE=2>O</FONT></FONT></P>
 268                         </TD>
 269                 </TR>
 270                 <TR VALIGN=TOP>
 271                         <TD WIDTH=81>
 272                                 <P CLASS="western" ALIGN=RIGHT><FONT FACE="Bitstream Vera Sans Mono, sans-serif"><FONT SIZE=2>Chewie</FONT></FONT></P>
 273                         </TD>
 274                         <TD WIDTH=56 BGCOLOR="#00ff00">
 275                                 <P CLASS="western" ALIGN=CENTER><FONT FACE="Bitstream Vera Sans Mono, sans-serif"><FONT SIZE=2>O</FONT></FONT></P>
 276                         </TD>
 277                         <TD WIDTH=44 BGCOLOR="#00ff00">
 278                                 <P CLASS="western" ALIGN=CENTER><FONT FACE="Bitstream Vera Sans Mono, sans-serif"><FONT SIZE=2>O</FONT></FONT></P>
 279                         </TD>
 280                         <TD WIDTH=31 BGCOLOR="#00ff00">
 281                                 <P CLASS="western" ALIGN=CENTER><FONT FACE="Bitstream Vera Sans Mono, sans-serif"><FONT SIZE=2>O</FONT></FONT></P>
 282                         </TD>
 283                         <TD WIDTH=53 BGCOLOR="#ff0000">
 284                                 <P CLASS="western" ALIGN=CENTER><FONT FACE="Bitstream Vera Sans Mono, sans-serif"><FONT SIZE=2>X</FONT></FONT></P>
 285                         </TD>
 286                 </TR>
 287                 <TR VALIGN=TOP>
 288                         <TD WIDTH=81>
 289                                 <P CLASS="western" ALIGN=RIGHT><FONT FACE="Bitstream Vera Sans Mono, sans-serif"><FONT SIZE=2>Obi-wan</FONT></FONT></P>
 290                         </TD>
 291                         <TD WIDTH=56 BGCOLOR="#ff0000">
 292                                 <P CLASS="western" ALIGN=CENTER><FONT FACE="Bitstream Vera Sans Mono, sans-serif"><FONT SIZE=2>X</FONT></FONT></P>
 293                         </TD>
 294                         <TD WIDTH=44 BGCOLOR="#00ff00">
 295                                 <P CLASS="western" ALIGN=CENTER><FONT FACE="Bitstream Vera Sans Mono, sans-serif"><FONT SIZE=2>O</FONT></FONT></P>
 296                         </TD>
 297                         <TD WIDTH=31 BGCOLOR="#ff0000">
 298                                 <P CLASS="western" ALIGN=CENTER><FONT FACE="Bitstream Vera Sans Mono, sans-serif"><FONT SIZE=2>X</FONT></FONT></P>
 299                         </TD>
 300                         <TD WIDTH=53 BGCOLOR="#ff0000">
 301                                 <P CLASS="western" ALIGN=CENTER><FONT FACE="Bitstream Vera Sans Mono, sans-serif"><FONT SIZE=2>X</FONT></FONT></P>
 302                         </TD>
 303                 </TR>
 304                 <TR VALIGN=TOP>
 305                         <TD WIDTH=81>
 306                                 <P CLASS="western" ALIGN=RIGHT><FONT FACE="Bitstream Vera Sans Mono, sans-serif"><FONT SIZE=2>Luke</FONT></FONT></P>
 307                         </TD>
 308                         <TD WIDTH=56 BGCOLOR="#ff0000">
 309                                 <P CLASS="western" ALIGN=CENTER><FONT FACE="Bitstream Vera Sans Mono, sans-serif"><FONT SIZE=2>X</FONT></FONT></P>
 310                         </TD>
 311                         <TD WIDTH=44 BGCOLOR="#00ff00">
 312                                 <P CLASS="western" ALIGN=CENTER><FONT FACE="Bitstream Vera Sans Mono, sans-serif"><FONT SIZE=2>O</FONT></FONT></P>
 313                         </TD>
 314                         <TD WIDTH=31 BGCOLOR="#ff0000">
 315                                 <P CLASS="western" ALIGN=CENTER><FONT FACE="Bitstream Vera Sans Mono, sans-serif"><FONT SIZE=2>X</FONT></FONT></P>
 316                         </TD>
 317                         <TD WIDTH=53 BGCOLOR="#ff0000">
 318                                 <P CLASS="western" ALIGN=CENTER><FONT FACE="Bitstream Vera Sans Mono, sans-serif"><FONT SIZE=2>X</FONT></FONT></P>
 319                         </TD>
 320                 </TR>
 321                 <TR VALIGN=TOP>
 322                         <TD WIDTH=81>
 323                                 <P CLASS="western" ALIGN=RIGHT><FONT FACE="Bitstream Vera Sans Mono, sans-serif"><FONT SIZE=2>R2-D2</FONT></FONT></P>
 324                         </TD>
 325                         <TD WIDTH=56 BGCOLOR="#ff0000">
 326                                 <P CLASS="western" ALIGN=CENTER><FONT FACE="Bitstream Vera Sans Mono, sans-serif"><FONT SIZE=2>X</FONT></FONT></P>
 327                         </TD>
 328                         <TD WIDTH=44 BGCOLOR="#00ff00">
 329                                 <P CLASS="western" ALIGN=CENTER><FONT FACE="Bitstream Vera Sans Mono, sans-serif"><FONT SIZE=2>O</FONT></FONT></P>
 330                         </TD>
 331                         <TD WIDTH=31 BGCOLOR="#ff0000">
 332                                 <P CLASS="western" ALIGN=CENTER><FONT FACE="Bitstream Vera Sans Mono, sans-serif"><FONT SIZE=2>X</FONT></FONT></P>
 333                         </TD>
 334                         <TD WIDTH=53 BGCOLOR="#ff0000">
 335                                 <P CLASS="western" ALIGN=CENTER><FONT FACE="Bitstream Vera Sans Mono, sans-serif"><FONT SIZE=2>X</FONT></FONT></P>
 336                         </TD>
 337                 </TR>
 338                 <TR VALIGN=TOP>
 339                         <TD WIDTH=81>
 340                                 <P CLASS="western" ALIGN=RIGHT><FONT FACE="Bitstream Vera Sans Mono, sans-serif"><FONT SIZE=2>C3PO</FONT></FONT></P>
 341                         </TD>
 342                         <TD WIDTH=56 BGCOLOR="#ff0000">
 343                                 <P CLASS="western" ALIGN=CENTER><FONT FACE="Bitstream Vera Sans Mono, sans-serif"><FONT SIZE=2>X</FONT></FONT></P>
 344                         </TD>
 345                         <TD WIDTH=44 BGCOLOR="#00ff00">
 346                                 <P CLASS="western" ALIGN=CENTER><FONT FACE="Bitstream Vera Sans Mono, sans-serif"><FONT SIZE=2>O</FONT></FONT></P>
 347                         </TD>
 348                         <TD WIDTH=31 BGCOLOR="#ff0000">
 349                                 <P CLASS="western" ALIGN=CENTER><FONT FACE="Bitstream Vera Sans Mono, sans-serif"><FONT SIZE=2>X</FONT></FONT></P>
 350                         </TD>
 351                         <TD WIDTH=53 BGCOLOR="#ff0000">
 352                                 <P CLASS="western" ALIGN=CENTER><FONT FACE="Bitstream Vera Sans Mono, sans-serif"><FONT SIZE=2>X</FONT></FONT></P>
 353                         </TD>
 354                 </TR>
 355         </TABLE>
 356 </DL>
 357 <P LANG="en-GB" CLASS="western" STYLE="line-height: 0.17in"><FONT FACE="Bitstream Vera Sans Mono, sans-serif"><FONT SIZE=3><FONT SIZE=2><FONT COLOR="#000000"><SPAN LANG="en-US">The
 358 columns list the rooms that Han wants to restrict access to, and the
 359 rows list the people that might request access to those rooms. More
 360 generally, the &quot;rooms&quot; are &quot;things to control access
 361 on&quot;. We call these </SPAN><B>Access Control Objects</B><SPAN LANG="en-US">
 362 (ACOs). The &quot;people&quot; are &quot;things </SPAN><I>requesting</I><SPAN LANG="en-US">
 363 access&quot;. We call these </SPAN><B>Access Request Objects</B><SPAN LANG="en-US">
 364 (AROs). The </SPAN><I>people</I><SPAN LANG="en-US"> request access to
 365 the </SPAN><I>rooms</I><SPAN LANG="en-US">, or in our terminology,
 366 </SPAN><I>AROs</I><SPAN LANG="en-US"> request access to the </SPAN><I>ACOs</I><SPAN LANG="en-US">.</SPAN></FONT></FONT></FONT></FONT></P>
 367 <P LANG="en-GB" CLASS="western" STYLE="line-height: 0.17in"><FONT FACE="Bitstream Vera Sans Mono, sans-serif"><FONT SIZE=3><FONT SIZE=2><FONT COLOR="#000000"><SPAN LANG="en-US">There
 368 is a third type of Object, the </SPAN><B>Access eXtention Object</B><SPAN LANG="en-US">
 369 (AXO) that we'll discuss later. These objects share many attributes
 370 and are collectively referred to as Access Objects.</SPAN></FONT></FONT></FONT></FONT></P>
 371 <P CLASS="western" STYLE="line-height: 0.17in"><FONT FACE="Bitstream Vera Sans Mono, sans-serif"><FONT SIZE=2>Managing
 372 access using an access matrix like the one above has advantages and
 373 disadvantages.</FONT></FONT></P>
 374 <P LANG="en-GB" CLASS="western" STYLE="line-height: 0.17in"><FONT FACE="Bitstream Vera Sans Mono, sans-serif"><FONT SIZE=2><I>Advantages:</I></FONT></FONT></P>
 375 <UL>
 376         <LI><P CLASS="western" STYLE="line-height: 0.17in"><FONT FACE="Bitstream Vera Sans Mono, sans-serif"><FONT SIZE=2>It's
 377         very fine-grained. It's possible to control access for an individual
 378         person if necessary.</FONT></FONT></P>
 379         <LI><P LANG="en-GB" CLASS="western" STYLE="line-height: 0.17in"><FONT FACE="Bitstream Vera Sans Mono, sans-serif"><FONT SIZE=3><SPAN LANG="en-US"><FONT SIZE=2><FONT COLOR="#000000">It's
 380         easy to see <U>who</U> has access to <U>what</U>. The answer is
 381         stored in the intersection of the person and the room.</FONT></FONT></SPAN></FONT></FONT></P>
 382 </UL>
 383 <P LANG="en-GB" CLASS="western" STYLE="line-height: 0.17in"><FONT FACE="Bitstream Vera Sans Mono, sans-serif"><FONT SIZE=2><I>Disadvantages:</I></FONT></FONT></P>
 384 <UL>
 385         <LI VALUE=1><P CLASS="western" STYLE="line-height: 0.17in"><FONT FACE="Bitstream Vera Sans Mono, sans-serif"><FONT SIZE=2>It's
 386         difficult to manage on a large scale. 6 passengers and 4 places is
 387         fairly simple, but what if there were thousands of passengers and
 388         hundreds of places, and you need to restrict access to large groups
 389         of them at once, but still retain enough fine-grained control to
 390         manage access for an individual? That would mean a lot of fiddly and
 391         lengthy adjustment to the matrix, and it's a difficult task to
 392         verify that the final matrix is correct.</FONT></FONT></P>
 393         <LI><P CLASS="western" STYLE="line-height: 0.17in"><FONT FACE="Bitstream Vera Sans Mono, sans-serif"><FONT SIZE=2>It's
 394         hard to summarize or visualize. The above example is fairly simple
 395         to summarize in a few sentences (as Han did above), but what if the
 396         matrix looked like this?</FONT></FONT></P>
 397         <TABLE WIDTH=337 BORDER=1 BORDERCOLOR="#000000" CELLPADDING=7 CELLSPACING=0>
 398                 <COL WIDTH=81>
 399                 <COL WIDTH=52>
 400                 <COL WIDTH=44>
 401                 <COL WIDTH=35>
 402                 <COL WIDTH=54>
 403                 <TR VALIGN=TOP>
 404                         <TD WIDTH=81>
 405                                 <H3 LANG="en-GB" CLASS="western" ALIGN=RIGHT><FONT FACE="Bitstream Vera Sans Mono, sans-serif">Who/Where</FONT></H3>
 406                         </TD>
 407                         <TD WIDTH=52>
 408                                 <P CLASS="western" ALIGN=CENTER><FONT FACE="Bitstream Vera Sans Mono, sans-serif"><FONT SIZE=2>Cockpit</FONT></FONT></P>
 409                         </TD>
 410                         <TD WIDTH=44>
 411                                 <P CLASS="western" ALIGN=CENTER><FONT FACE="Bitstream Vera Sans Mono, sans-serif"><FONT SIZE=2>Lounge</FONT></FONT></P>
 412                         </TD>
 413                         <TD WIDTH=35>
 414                                 <P CLASS="western" ALIGN=CENTER><FONT FACE="Bitstream Vera Sans Mono, sans-serif"><FONT SIZE=2>Guns</FONT></FONT></P>
 415                         </TD>
 416                         <TD WIDTH=54>
 417                                 <P CLASS="western" ALIGN=CENTER><FONT FACE="Bitstream Vera Sans Mono, sans-serif"><FONT SIZE=2>Engines</FONT></FONT></P>
 418                         </TD>
 419                 </TR>
 420                 <TR VALIGN=TOP>
 421                         <TD WIDTH=81>
 422                                 <P CLASS="western" ALIGN=RIGHT><FONT FACE="Bitstream Vera Sans Mono, sans-serif"><FONT SIZE=2>Han</FONT></FONT></P>
 423                         </TD>
 424                         <TD WIDTH=52 BGCOLOR="#00ff00">
 425                                 <P CLASS="western" ALIGN=CENTER><FONT FACE="Bitstream Vera Sans Mono, sans-serif"><FONT SIZE=2>O</FONT></FONT></P>
 426                         </TD>
 427                         <TD WIDTH=44 BGCOLOR="#00ff00">
 428                                 <P CLASS="western" ALIGN=CENTER><FONT FACE="Bitstream Vera Sans Mono, sans-serif"><FONT SIZE=2>O</FONT></FONT></P>
 429                         </TD>
 430                         <TD WIDTH=35 BGCOLOR="#00ff00">
 431                                 <P CLASS="western" ALIGN=CENTER><FONT FACE="Bitstream Vera Sans Mono, sans-serif"><FONT SIZE=2>O</FONT></FONT></P>
 432                         </TD>
 433                         <TD WIDTH=54 BGCOLOR="#00ff00">
 434                                 <P CLASS="western" ALIGN=CENTER><FONT FACE="Bitstream Vera Sans Mono, sans-serif"><FONT SIZE=2>O</FONT></FONT></P>
 435                         </TD>
 436                 </TR>
 437                 <TR VALIGN=TOP>
 438                         <TD WIDTH=81>
 439                                 <P CLASS="western" ALIGN=RIGHT><FONT FACE="Bitstream Vera Sans Mono, sans-serif"><FONT SIZE=2>Chewie</FONT></FONT></P>
 440                         </TD>
 441                         <TD WIDTH=52 BGCOLOR="#00ff00">
 442                                 <P CLASS="western" ALIGN=CENTER><FONT FACE="Bitstream Vera Sans Mono, sans-serif"><FONT SIZE=2>O</FONT></FONT></P>
 443                         </TD>
 444                         <TD WIDTH=44 BGCOLOR="#ff0000">
 445                                 <P CLASS="western" ALIGN=CENTER><FONT FACE="Bitstream Vera Sans Mono, sans-serif"><FONT SIZE=2>X</FONT></FONT></P>
 446                         </TD>
 447                         <TD WIDTH=35 BGCOLOR="#00ff00">
 448                                 <P CLASS="western" ALIGN=CENTER><FONT FACE="Bitstream Vera Sans Mono, sans-serif"><FONT SIZE=2>O</FONT></FONT></P>
 449                         </TD>
 450                         <TD WIDTH=54 BGCOLOR="#ff0000">
 451                                 <P CLASS="western" ALIGN=CENTER><FONT FACE="Bitstream Vera Sans Mono, sans-serif"><FONT SIZE=2>X</FONT></FONT></P>
 452                         </TD>
 453                 </TR>
 454                 <TR VALIGN=TOP>
 455                         <TD WIDTH=81>
 456                                 <P CLASS="western" ALIGN=RIGHT><FONT FACE="Bitstream Vera Sans Mono, sans-serif"><FONT SIZE=2>Obi-wan</FONT></FONT></P>
 457                         </TD>
 458                         <TD WIDTH=52 BGCOLOR="#ff0000">
 459                                 <P CLASS="western" ALIGN=CENTER><FONT FACE="Bitstream Vera Sans Mono, sans-serif"><FONT SIZE=2>X</FONT></FONT></P>
 460                         </TD>
 461                         <TD WIDTH=44 BGCOLOR="#00ff00">
 462                                 <P CLASS="western" ALIGN=CENTER><FONT FACE="Bitstream Vera Sans Mono, sans-serif"><FONT SIZE=2>O</FONT></FONT></P>
 463                         </TD>
 464                         <TD WIDTH=35 BGCOLOR="#ff0000">
 465                                 <P CLASS="western" ALIGN=CENTER><FONT FACE="Bitstream Vera Sans Mono, sans-serif"><FONT SIZE=2>X</FONT></FONT></P>
 466                         </TD>
 467                         <TD WIDTH=54 BGCOLOR="#ff0000">
 468                                 <P CLASS="western" ALIGN=CENTER><FONT FACE="Bitstream Vera Sans Mono, sans-serif"><FONT SIZE=2>X</FONT></FONT></P>
 469                         </TD>
 470                 </TR>
 471                 <TR VALIGN=TOP>
 472                         <TD WIDTH=81>
 473                                 <P CLASS="western" ALIGN=RIGHT><FONT FACE="Bitstream Vera Sans Mono, sans-serif"><FONT SIZE=2>Luke</FONT></FONT></P>
 474                         </TD>
 475                         <TD WIDTH=52 BGCOLOR="#00ff00">
 476                                 <P CLASS="western" ALIGN=CENTER><FONT FACE="Bitstream Vera Sans Mono, sans-serif"><FONT SIZE=2>O</FONT></FONT></P>
 477                         </TD>
 478                         <TD WIDTH=44 BGCOLOR="#00ff00">
 479                                 <P CLASS="western" ALIGN=CENTER><FONT FACE="Bitstream Vera Sans Mono, sans-serif"><FONT SIZE=2>O</FONT></FONT></P>
 480                         </TD>
 481                         <TD WIDTH=35 BGCOLOR="#00ff00">
 482                                 <P CLASS="western" ALIGN=CENTER><FONT FACE="Bitstream Vera Sans Mono, sans-serif"><FONT SIZE=2>O</FONT></FONT></P>
 483                         </TD>
 484                         <TD WIDTH=54 BGCOLOR="#ff0000">
 485                                 <P CLASS="western" ALIGN=CENTER><FONT FACE="Bitstream Vera Sans Mono, sans-serif"><FONT SIZE=2>X</FONT></FONT></P>
 486                         </TD>
 487                 </TR>
 488                 <TR VALIGN=TOP>
 489                         <TD WIDTH=81>
 490                                 <P CLASS="western" ALIGN=RIGHT><FONT FACE="Bitstream Vera Sans Mono, sans-serif"><FONT SIZE=2>R2-D2</FONT></FONT></P>
 491                         </TD>
 492                         <TD WIDTH=52 BGCOLOR="#ff0000">
 493                                 <P CLASS="western" ALIGN=CENTER><FONT FACE="Bitstream Vera Sans Mono, sans-serif"><FONT SIZE=2>X</FONT></FONT></P>
 494                         </TD>
 495                         <TD WIDTH=44 BGCOLOR="#00ff00">
 496                                 <P CLASS="western" ALIGN=CENTER><FONT FACE="Bitstream Vera Sans Mono, sans-serif"><FONT SIZE=2>O</FONT></FONT></P>
 497                         </TD>
 498                         <TD WIDTH=35 BGCOLOR="#ff0000">
 499                                 <P CLASS="western" ALIGN=CENTER><FONT FACE="Bitstream Vera Sans Mono, sans-serif"><FONT SIZE=2>X</FONT></FONT></P>
 500                         </TD>
 501                         <TD WIDTH=54 BGCOLOR="#00ff00">
 502                                 <P CLASS="western" ALIGN=CENTER><FONT FACE="Bitstream Vera Sans Mono, sans-serif"><FONT SIZE=2>O</FONT></FONT></P>
 503                         </TD>
 504                 </TR>
 505                 <TR VALIGN=TOP>
 506                         <TD WIDTH=81>
 507                                 <P CLASS="western" ALIGN=RIGHT><FONT FACE="Bitstream Vera Sans Mono, sans-serif"><FONT SIZE=2>C3PO</FONT></FONT></P>
 508                         </TD>
 509                         <TD WIDTH=52 BGCOLOR="#00ff00">
 510                                 <P CLASS="western" ALIGN=CENTER><FONT FACE="Bitstream Vera Sans Mono, sans-serif"><FONT SIZE=2>O</FONT></FONT></P>
 511                         </TD>
 512                         <TD WIDTH=44 BGCOLOR="#00ff00">
 513                                 <P CLASS="western" ALIGN=CENTER><FONT FACE="Bitstream Vera Sans Mono, sans-serif"><FONT SIZE=2>O</FONT></FONT></P>
 514                         </TD>
 515                         <TD WIDTH=35 BGCOLOR="#ff0000">
 516                                 <P CLASS="western" ALIGN=CENTER><FONT FACE="Bitstream Vera Sans Mono, sans-serif"><FONT SIZE=2>X</FONT></FONT></P>
 517                         </TD>
 518                         <TD WIDTH=54 BGCOLOR="#00ff00">
 519                                 <P CLASS="western" ALIGN=CENTER><FONT FACE="Bitstream Vera Sans Mono, sans-serif"><FONT SIZE=2>O</FONT></FONT></P>
 520                         </TD>
 521                 </TR>
 522         </TABLE>
 523         <P CLASS="western" STYLE="line-height: 0.17in"><FONT FACE="Bitstream Vera Sans Mono, sans-serif"><FONT SIZE=2>This
 524         matrix is not so obvious to summarize, and it's not clear to the
 525         reader why those access decisions might have been made in the first
 526         place.</FONT></FONT></P>
 527 </UL>
 528 <H2 LANG="en-GB" CLASS="western"><FONT FACE="Bitstream Vera Sans Mono, sans-serif">Defining
 529 access control with phpGACL</FONT></H2>
 530 <P CLASS="western"><FONT FACE="Bitstream Vera Sans Mono, sans-serif">It
 531 seems that for large or complex situations, this 'access matrix'
 532 approach is clearly unsuitable. We need a better system that
 533 maintains the advantages (fine-grain control and a clear idea of <U>who</U>
 534 has access to <U>what</U>) but removes the disadvantages (difficult
 535 to summarize, and difficult to manage large groups of people at
 536 once). One solution is phpGACL.</FONT></P>
 537 <P LANG="en-GB" CLASS="western" STYLE="line-height: 0.17in"><FONT FACE="Bitstream Vera Sans Mono, sans-serif"><FONT SIZE=3><SPAN LANG="en-US"><FONT SIZE=2><FONT COLOR="#000000">phpGACL
 538 doesn't describe access from the 'bottom-up' like the Access Matrix
 539 above. Instead, it describes it 'top-down', like the textual
 540 description of Han's access policy. This is a very flexible system
 541 that allows you to manage access in large groups, it neatly
 542 summarizes the access policy, and it's easy to see <U>who </U>has
 543 access to <U>what</U>.</FONT></FONT></SPAN></FONT></FONT></P>
 544 <P LANG="en-GB" CLASS="western" STYLE="line-height: 0.17in"><FONT FACE="Bitstream Vera Sans Mono, sans-serif"><FONT SIZE=3><FONT SIZE=2><FONT COLOR="#000000"><SPAN LANG="en-US">An
 545 </SPAN><B>ARO tree</B><SPAN LANG="en-US"> defines a hierarchy of
 546 </SPAN><B>Groups</B><SPAN LANG="en-US"> and AROs (things that request
 547 access). This is very similar to a tree view of folders and files.
 548 The 'folders' are the Groups and the 'files' are AROs.</SPAN></FONT></FONT></FONT></FONT></P>
 549 <P CLASS="western" STYLE="line-height: 0.17in"><FONT FACE="Bitstream Vera Sans Mono, sans-serif"><FONT SIZE=2>Let's
 550 make an ACL tree for the people on Han's ship. First we define some
 551 categories for the people. It's clear that Han and Chewie run the
 552 ship, and the rest of them are just passengers:</FONT></FONT></P>
 553 <P CLASS="western" STYLE="line-height: 0.17in"><FONT FACE="Courier New, monospace"><FONT SIZE=2>Millennium
 554 Falcon Passengers               Group<BR>&#9500;&#9472;Crew                                     Group<BR>&#9474;
 555 &#9500;&#9472;Han                                       ARO<BR>&#9474;
 556 &#9492;&#9472;Chewie                                    ARO<BR>&#9492;&#9472;Passengers                         Group<BR>
 557  &#9500;&#9472;Obi-wan                                  ARO<BR>  &#9500;&#9472;Luke                                     ARO<BR>
 558 &#9500;&#9472;R2D2                                      ARO<BR>  &#9492;&#9472;C3PO                                     ARO</FONT></FONT></P>
 559 <P CLASS="western" STYLE="line-height: 0.17in"><FONT FACE="Bitstream Vera Sans Mono, sans-serif"><FONT SIZE=2>This
 560 tree by itself doesn't specify any access policy; it just shows how
 561 we're grouping the people who might request access (AROs).</FONT></FONT></P>
 562 <P CLASS="western"><FONT FACE="Bitstream Vera Sans Mono, sans-serif">We
 563 apply access restrictions by assigning instructions about a
 564 particular room (ACO) to Groups or AROs in the tree. Han says: &quot;By
 565 default, no-one should be allowed access to any room on the
 566 Millennium Falcon. But the Crew should have access to every room. The
 567 Passengers should only have access to the Lounge.&quot;</FONT></P>
 568 <P LANG="en-GB" CLASS="western" STYLE="line-height: 0.17in"><FONT FACE="Times New Roman, serif"><FONT SIZE=3><FONT SIZE=2><FONT FACE="Courier New, monospace"><FONT COLOR="#000000"><SPAN LANG="en-US">Millennium
 569 Falcon Passengers<BR>&#9500;&#9472;Crew         </SPAN><B>[ALLOW: ALL]</B><SPAN LANG="en-US"><BR>&#9474;
 570 &#9500;&#9472;Han<BR>&#9474; &#9492;&#9472;Chewie<BR>&#9492;&#9472;Passengers   </SPAN><B>[ALLOW:
 571 Lounge]</B><SPAN LANG="en-US"><BR>  &#9500;&#9472;Obi-wan<BR>
 572 &#9500;&#9472;Luke<BR>  &#9500;&#9472;R2D2<BR>  &#9492;&#9472;C3PO</SPAN></FONT></FONT></FONT></FONT></FONT></P>
 573 <P CLASS="western" STYLE="line-height: 0.17in"><FONT FACE="Bitstream Vera Sans Mono, sans-serif"><FONT SIZE=2>To
 574 interpret this ARO tree, we start from the top and work our way down.</FONT></FONT></P>
 575 <P CLASS="western" STYLE="line-height: 0.17in"><FONT FACE="Bitstream Vera Sans Mono, sans-serif"><FONT SIZE=2>Firstly,
 576 the default policy is always to deny access. Permissions have been
 577 overridden for the &quot;Crew&quot;, so they have access to
 578 everywhere (&quot;ALL&quot; is a synonym for all rooms: &quot;Cockpit,
 579 Lounge, Guns, Engines&quot;). The &quot;Passengers&quot; have access
 580 only to the Lounge.</FONT></FONT></P>
 581 <P LANG="en-GB" CLASS="western" STYLE="line-height: 0.17in"><FONT FACE="Bitstream Vera Sans Mono, sans-serif"><FONT SIZE=3><SPAN LANG="en-US"><FONT SIZE=2><FONT COLOR="#000000">This
 582 way of describing the access policy is much clearer than the access
 583 matrix. You can easily see who has access to what, and it's easier to
 584 determine <U>why</U> they've got access (it seems obvious that Han
 585 and Chewie would have access to everything, since they're grouped
 586 under &quot;Crew&quot;).</FONT></FONT></SPAN></FONT></FONT></P>
 587 <P CLASS="western" STYLE="line-height: 0.17in"><FONT FACE="Bitstream Vera Sans Mono, sans-serif"><FONT SIZE=2>To
 588 summarize:</FONT></FONT></P>
 589 <UL>
 590         <LI VALUE=1><P LANG="en-GB" CLASS="western" STYLE="line-height: 0.17in">
 591         <FONT FACE="Bitstream Vera Sans Mono, sans-serif"><FONT SIZE=3><FONT SIZE=2><FONT COLOR="#000000"><B>Access
 592         Control Objects </B><SPAN LANG="en-US">(ACOs) are the things we want
 593         to control access to (e.g. web pages, databases, rooms, etc).</SPAN></FONT></FONT></FONT></FONT></P>
 594         <LI><P LANG="en-GB" CLASS="western" STYLE="line-height: 0.17in"><FONT FACE="Bitstream Vera Sans Mono, sans-serif"><FONT SIZE=3><FONT SIZE=2><FONT COLOR="#000000"><B>Access
 595         Request Objects</B><SPAN LANG="en-US"> (AROs) are the things that
 596         request access (e.g. people, remote computers, etc)</SPAN></FONT></FONT></FONT></FONT></P>
 597         <LI><P LANG="en-GB" CLASS="western" STYLE="line-height: 0.17in"><FONT FACE="Bitstream Vera Sans Mono, sans-serif"><FONT SIZE=3><FONT SIZE=2><FONT COLOR="#000000"><B>ARO
 598         trees</B><SPAN LANG="en-US"> define a hierarchy of </SPAN><B>Groups</B><SPAN LANG="en-US">
 599         and AROs. Groups can contain other Groups and AROs.</SPAN></FONT></FONT></FONT></FONT></P>
 600         <LI><P CLASS="western" STYLE="line-height: 0.17in"><FONT FACE="Bitstream Vera Sans Mono, sans-serif"><FONT SIZE=2>The
 601         default 'catch-all' policy for the ARO tree is always &quot;DENY
 602         ALL&quot;.</FONT></FONT></P>
 603         <LI><P CLASS="western" STYLE="line-height: 0.17in"><FONT FACE="Bitstream Vera Sans Mono, sans-serif"><FONT SIZE=2>To
 604         assign access policy, work your way down the tree, explicitly
 605         assigning permissions to Groups and AROs for each ACO as the need
 606         arises.</FONT></FONT></P>
 607 </UL>
 608 <H2 LANG="en-GB" CLASS="western"><FONT FACE="Bitstream Vera Sans Mono, sans-serif">Fine-grain
 609 access control</FONT></H2>
 610 <P CLASS="western" STYLE="line-height: 0.17in"><FONT FACE="Bitstream Vera Sans Mono, sans-serif"><FONT SIZE=2>Oops!
 611 What about Chewie? By grouping him in &quot;Crew&quot;, Han has
 612 indirectly given him access to the Engines! He doesn't want that
 613 after what Chewie recently did to the hyperdrive, so he adds a rule
 614 to disallow this:</FONT></FONT></P>
 615 <P LANG="en-GB" CLASS="western" STYLE="line-height: 0.17in"><FONT FACE="Times New Roman, serif"><FONT SIZE=3><FONT SIZE=2><FONT FACE="Courier New, monospace"><FONT COLOR="#000000"><SPAN LANG="en-US">Millennium
 616 Falcon Passengers<BR>&#9500;&#9472;Crew         [ALLOW: ALL]<BR>&#9474;
 617 &#9500;&#9472;Han<BR>&#9474; &#9492;&#9472;Chewie               </SPAN><B>[DENY:
 618 Engines]</B><SPAN LANG="en-US"><BR>&#9492;&#9472;Passengers     [ALLOW:
 619 Lounge]<BR>  &#9500;&#9472;Obi-wan<BR>  &#9500;&#9472;Luke<BR>
 620 &#9500;&#9472;R2D2<BR>  &#9492;&#9472;C3PO</SPAN></FONT></FONT></FONT></FONT></FONT></P>
 621 <P CLASS="western" STYLE="line-height: 0.17in"><FONT FACE="Bitstream Vera Sans Mono, sans-serif"><FONT SIZE=2>This
 622 is an example of the way you can control access policy in a
 623 fine-grained manner. It is not necessary to move Chewie to another
 624 Group; we simply over-ride the access policy at a lower level.</FONT></FONT></P>
 625 <P CLASS="western" STYLE="line-height: 0.17in"><FONT FACE="Bitstream Vera Sans Mono, sans-serif"><FONT SIZE=2>Another
 626 example of fine-grain control happens when the Empire attacks; Han
 627 needs to let Luke man the guns, and let R2D2 repair the hyperdrive in
 628 the Engine room. He can do this by over-riding the general
 629 permissions granted by their status as a &quot;Passenger&quot;:</FONT></FONT></P>
 630 <P LANG="en-GB" CLASS="western" STYLE="line-height: 0.17in"><FONT FACE="Times New Roman, serif"><FONT SIZE=3><FONT SIZE=2><FONT FACE="Courier New, monospace"><FONT COLOR="#000000"><SPAN LANG="en-US">Millennium
 631 Falcon Passengers<BR>&#9500;&#9472;Crew         [ALLOW: ALL]<BR>&#9474;
 632 &#9500;&#9472;Han<BR>&#9474; &#9492;&#9472;Chewie               [DENY:
 633 Engines]<BR>&#9492;&#9472;Passengers    [ALLOW: Lounge]<BR>  &#9500;&#9472;Obi-wan<BR>
 634  &#9500;&#9472;Luke             </SPAN><B>[ALLOW: Guns]</B><SPAN LANG="en-US"><BR>
 635  &#9500;&#9472;R2D2             </SPAN><B>[ALLOW: Engines]</B><SPAN LANG="en-US"><BR>
 636  &#9492;&#9472;C3PO</SPAN></FONT></FONT></FONT></FONT></FONT></P>
 637 <H2 CLASS="western"><FONT FACE="Bitstream Vera Sans Mono, sans-serif">Multi-level
 638 Groups</FONT></H2>
 639 <P CLASS="western" STYLE="line-height: 0.17in"><FONT FACE="Bitstream Vera Sans Mono, sans-serif"><FONT SIZE=2>Groups
 640 can be extended to any level in the ARO tree. For example, you could
 641 add a Group &quot;Jedi&quot; to &quot;Passengers&quot;. Most
 642 passengers would be categorized under &quot;Passengers&quot;, but
 643 Luke and Obi-wan would be under &quot;Jedi&quot; and therefore might
 644 be extended extra privileges (like access to the Cockpit):</FONT></FONT></P>
 645 <P LANG="en-GB" CLASS="western" STYLE="line-height: 0.17in"><FONT FACE="Times New Roman, serif"><FONT SIZE=3><FONT SIZE=2><FONT FACE="Courier New, monospace"><FONT COLOR="#000000"><SPAN LANG="en-US">Millennium
 646 Falcon Passengers<BR>&#9500;&#9472;Crew         [ALLOW: ALL]<BR>&#9474;
 647 &#9500;&#9472;Han<BR>&#9474; &#9492;&#9472;Chewie               [DENY:
 648 Engines]<BR>&#9492;&#9472;Passengers    [ALLOW: Lounge]<BR>
 649 &#9500;&#9472;</SPAN><B>Jedi            [ALLOW: Cockpit]</B><SPAN LANG="en-US"><BR>
 650  &#9474; &#9500;&#9472;</SPAN><B>Obi-wan</B><SPAN LANG="en-US"><BR>
 651 &#9474; &#9492;&#9472;</SPAN><B>Luke</B><SPAN LANG="en-US">             [ALLOW:
 652 Guns] <BR>  &#9500;&#9472;R2D2          [ALLOW: Engines]<BR>  &#9492;&#9472;C3PO</SPAN></FONT></FONT></FONT></FONT></FONT></P>
 653 <H2 CLASS="western"><FONT FACE="Bitstream Vera Sans Mono, sans-serif">How
 654 does phpGACL determine permissions?</FONT></H2>
 655 <P CLASS="western" STYLE="line-height: 0.17in"><FONT FACE="Bitstream Vera Sans Mono, sans-serif"><FONT SIZE=2>When
 656 the ship's computer (running phpGACL of course) checks access, the
 657 only question it can ask itself is &quot;Does person X have access to
 658 room Y?&quot; In phpGACL terms, this is rephrased as &quot;Does ARO
 659 'X' have access to ACO 'Y'?&quot;</FONT></FONT></P>
 660 <P CLASS="western" STYLE="line-height: 0.17in"><FONT FACE="Bitstream Vera Sans Mono, sans-serif"><FONT SIZE=2>phpGACL
 661 determines whether a specific person has access to a specific room by
 662 working from the top of the ARO tree towards the specified person,
 663 noting explicit access controls for that place along the way. When it
 664 reaches that person, it uses the last explicit access control it
 665 encountered as the result to return. In this way, you can define
 666 access controls for groups of people, but over-ride them further down
 667 the tree if you need to.</FONT></FONT></P>
 668 <P LANG="en-GB" CLASS="western" STYLE="line-height: 0.17in"><FONT FACE="Bitstream Vera Sans Mono, sans-serif"><FONT SIZE=3><FONT SIZE=2><FONT COLOR="#000000"><B>Example
 669 1</B><SPAN LANG="en-US">: We ask: &quot;Does Luke have access to the
 670 Lounge?&quot;.</SPAN></FONT></FONT></FONT></FONT></P>
 671 <UL>
 672         <LI VALUE=1><P CLASS="western" STYLE="line-height: 0.17in"><FONT FACE="Bitstream Vera Sans Mono, sans-serif"><FONT SIZE=2>Set
 673         the default result, &quot;DENY&quot;.</FONT></FONT></P>
 674         <LI><P CLASS="western" STYLE="line-height: 0.17in"><FONT FACE="Bitstream Vera Sans Mono, sans-serif"><FONT SIZE=2>Work
 675         out a path to Luke:</FONT></FONT></P>
 676 </UL>
 677 <H4 LANG="en-GB" CLASS="western"><FONT FACE="Bitstream Vera Sans Mono, sans-serif">     Millennium
 678 Falcon Passengers &rarr; Passengers &rarr; Jedi &rarr; Luke</FONT></H4>
 679 <UL>
 680         <LI VALUE=1><P CLASS="western" STYLE="line-height: 0.17in"><FONT FACE="Bitstream Vera Sans Mono, sans-serif"><FONT SIZE=2>Start
 681         at the top of the tree and move towards Luke: The &quot;Millennium
 682         Falcon Passengers&quot; node doesn't say anything about any room, so
 683         do nothing here.</FONT></FONT></P>
 684         <LI><P CLASS="western" STYLE="line-height: 0.17in"><FONT FACE="Bitstream Vera Sans Mono, sans-serif"><FONT SIZE=2>Move
 685         on to &quot;Passengers&quot;, which explicitly says that
 686         &quot;Passengers&quot; have Lounge access, so change the internal
 687         result to &quot;ALLOW&quot;.</FONT></FONT></P>
 688         <LI><P CLASS="western" STYLE="line-height: 0.17in"><FONT FACE="Bitstream Vera Sans Mono, sans-serif"><FONT SIZE=2>Move
 689         to the &quot;Jedi&quot; node, which doesn't mention the Lounge at
 690         all.</FONT></FONT></P>
 691         <LI><P CLASS="western" STYLE="line-height: 0.17in"><FONT FACE="Bitstream Vera Sans Mono, sans-serif"><FONT SIZE=2>Finally
 692         move to Luke's node, and again there's nothing there about the
 693         Lounge.</FONT></FONT></P>
 694         <LI><P CLASS="western" STYLE="line-height: 0.17in"><FONT FACE="Bitstream Vera Sans Mono, sans-serif"><FONT SIZE=2>There's
 695         nowhere left to go, so the result returned is the current value of
 696         the internal result: &quot;ALLOW&quot;</FONT></FONT></P>
 697 </UL>
 698 <P LANG="en-GB" CLASS="western" STYLE="line-height: 0.17in"><FONT FACE="Bitstream Vera Sans Mono, sans-serif"><FONT SIZE=3><FONT SIZE=2><FONT COLOR="#000000"><B>Example
 699 2</B><SPAN LANG="en-US">: We ask: &quot;Does Chewie have access to
 700 the Engines?&quot;</SPAN></FONT></FONT></FONT></FONT></P>
 701 <UL>
 702         <LI VALUE=1><P CLASS="western" STYLE="line-height: 0.17in"><FONT FACE="Bitstream Vera Sans Mono, sans-serif"><FONT SIZE=2>Set
 703         the default result, &quot;DENY&quot;.</FONT></FONT></P>
 704         <LI><P CLASS="western" STYLE="line-height: 0.17in"><FONT FACE="Bitstream Vera Sans Mono, sans-serif"><FONT SIZE=2>Work
 705         out a path to Chewie:</FONT></FONT></P>
 706 </UL>
 707 <H4 LANG="en-GB" CLASS="western"><FONT FACE="Bitstream Vera Sans Mono, sans-serif">     Millennium
 708 Falcon Passengers &rarr; Crew &rarr; Chewie</FONT></H4>
 709 <UL>
 710         <LI><P CLASS="western">Start at the top of the tree and move towards
 711         Chewie. The &quot;Millennium Falcon Passengers&quot; node doesn't
 712         say anything about anywhere, so do nothing here.</P>
 713         <LI><P CLASS="western" STYLE="line-height: 0.17in"><FONT FACE="Bitstream Vera Sans Mono, sans-serif"><FONT SIZE=2>Move
 714         on to &quot;Crew&quot;, which explicitly says that &quot;Crew&quot;
 715         have Engine access, so change the internal result to &quot;ALLOW&quot;.</FONT></FONT></P>
 716         <LI><P CLASS="western" STYLE="line-height: 0.17in"><FONT FACE="Bitstream Vera Sans Mono, sans-serif"><FONT SIZE=2>Move
 717         to Chewie's node, and there's an explicit rule saying that he
 718         doesn't have access to the Engines, so change the internal result to
 719         &quot;DENY&quot;.</FONT></FONT></P>
 720         <LI><P CLASS="western" STYLE="line-height: 0.17in"><FONT FACE="Bitstream Vera Sans Mono, sans-serif"><FONT SIZE=2>There's
 721         nowhere left to go, so the result returned is the current value of
 722         the internal result: &quot;DENY&quot;</FONT></FONT></P>
 723 </UL>
 724 <P CLASS="western" STYLE="line-height: 0.17in"><FONT FACE="Bitstream Vera Sans Mono, sans-serif"><FONT SIZE=2>As
 725 you can see from the examples, if a Group doesn't explicitly specify
 726 a permission for a room, then that Group inherits the access
 727 restrictions of its parent for that room. If the root node
 728 (&quot;Millennium Falcon Passengers&quot;) doesn't specify a
 729 permission, it inherits it from the default setting (&quot;DENY ALL&quot;
 730 in the above examples).</FONT></FONT></P>
 731 <P CLASS="western" STYLE="line-height: 0.17in"><FONT FACE="Bitstream Vera Sans Mono, sans-serif"><FONT SIZE=2>This
 732 implies a couple of interesting points about the ARO tree:</FONT></FONT></P>
 733 <UL>
 734         <LI VALUE=1><P CLASS="western" STYLE="line-height: 0.17in"><FONT FACE="Bitstream Vera Sans Mono, sans-serif"><FONT SIZE=2>The
 735         ARO tree always shows the full list of the AROs. It would not make
 736         sense to ask &quot;Does Jabba have access to the Cockpit?&quot;
 737         because Jabba has not been defined in this system. However, phpGACL
 738         does not check to see if AROs or ACOs exist before performing the
 739         check, so if this question was actually asked then the result would
 740         be the default &quot;DENY&quot;.</FONT></FONT></P>
 741         <LI><P CLASS="western" STYLE="line-height: 0.17in"><FONT FACE="Bitstream Vera Sans Mono, sans-serif"><FONT SIZE=2>The
 742         ARO tree may not display some defined ACOs, and relies on the
 743         default setting to define access policy. For example, say Han
 744         defined a &quot;Bathroom&quot; ACO. Any question like &quot;Does
 745         Luke have access to the Bathroom?&quot; would have the answer
 746         &quot;DENY&quot;, because the default is &quot;DENY&quot; and
 747         nowhere in the ARO tree does it ever explicitly mention the
 748         Bathroom. Keep in mind when examining the ARO tree that some ACOs
 749         may not be visible.</FONT></FONT></P>
 750 </UL>
 751 <P LANG="en-GB" CLASS="western" STYLE="line-height: 0.17in"><FONT FACE="Bitstream Vera Sans Mono, sans-serif"><FONT SIZE=3><FONT SIZE=2><FONT COLOR="#000000"><B>Note:</B><SPAN LANG="en-US">
 752 When asking phpGACL questions about access to an ACO, it is not
 753 possible to use Groups as AROs (even though it might 'seem' right).
 754 For example, it is impossible to answer the question &quot;Do
 755 Passengers have access to Guns?&quot; The complete answer is not a
 756 Boolean &quot;ALLOW&quot; or &quot;DENY&quot;, but the more complex
 757 &quot;Luke and Obi-wan can but R2D2 and C3PO cannot.&quot; phpGACL is
 758 not designed to return that kind of answer.</SPAN></FONT></FONT></FONT></FONT></P>
 759 <H2 CLASS="western"><FONT FACE="Bitstream Vera Sans Mono, sans-serif">Adding
 760 groups</FONT></H2>
 761 <P CLASS="western" STYLE="line-height: 0.17in"><FONT FACE="Bitstream Vera Sans Mono, sans-serif"><FONT SIZE=2>Han
 762 feels this ACL is starting to look a little complicated. There are so
 763 many exceptions! Perhaps he should make another group, &quot;Engineers&quot;,
 764 containing the people who are allowed access to the Engines and Guns.
 765 That group should contain Han and R2D2 since they're both capable of
 766 repairing the engines and guns. This means Han can remove some of
 767 those messy exceptions-to-the-rules, and that has the benefit of
 768 making the description clearer:</FONT></FONT></P>
 769 <P CLASS="western"><FONT FACE="Courier New, monospace">Default: DENY
 770 ALL<BR>Millennium Falcon Passengers<BR>&#9500;&#9472;Crew               [ALLOW:
 771 ALL]<BR>&#9474; &#9500;&#9472;Han<BR>&#9474; &#9492;&#9472;Chewie               [DENY:
 772 Engines]<BR>&#9500;&#9472;Passengers    [ALLOW: Lounge]<BR>&#9474;
 773 &#9500;&#9472;Jedi              [ALLOW: Cockpit]<BR>&#9474; &#9474; &#9500;&#9472;Obi-wan<BR>&#9474;
 774 &#9474; &#9492;&#9472;Luke              [ALLOW: Guns] <BR>&#9474; &#9500;&#9472;R2D2<BR>&#9474;
 775 &#9492;&#9472;C3PO<BR>&#9492;&#9472;<B>Engineers                [ALLOW: Engines,
 776 Guns]</B><BR>  &#9500;&#9472;<B>Han</B><BR>  &#9492;&#9472;<B>R2D2</B></FONT></P>
 777 <P CLASS="western" STYLE="line-height: 0.17in"><FONT FACE="Bitstream Vera Sans Mono, sans-serif"><FONT SIZE=2>We
 778 can read this as &quot;By default, no-one has access to anywhere.
 779 Crew have access to everywhere (except Chewie, who has no access to
 780 the Engines). Passengers only have access to the Lounge, except Jedi
 781 who also have access to the Cockpit. Luke has access to the Guns too.
 782 Engineers are allowed access to the Engines and Guns.&quot;</FONT></FONT></P>
 783 <P LANG="en-GB" CLASS="western" STYLE="line-height: 0.17in"><FONT FACE="Bitstream Vera Sans Mono, sans-serif"><FONT SIZE=3><FONT SIZE=2><FONT COLOR="#000000"><SPAN LANG="en-US">Most
 784 importantly, we can see that Han and R2D2 are now in </SPAN><I>two</I><SPAN LANG="en-US">
 785 places in the ACL. It is not necessary for them to be uniquely
 786 categorized at all. This defines the policy more clearly to the
 787 reader: &quot;Ahh, Han and R2D2 have access to the Engines and Guns
 788 because they're </SPAN><I>engineers</I><SPAN LANG="en-US">.&quot;</SPAN></FONT></FONT></FONT></FONT></P>
 789 <H2 CLASS="western"><FONT FACE="Bitstream Vera Sans Mono, sans-serif">Adding
 790 people</FONT></H2>
 791 <P CLASS="western" STYLE="line-height: 0.17in"><FONT FACE="Bitstream Vera Sans Mono, sans-serif"><FONT SIZE=2>Han
 792 goes to Cloud City to pick up Lando and get some repairs. Lando's the
 793 Millennium Falcon's previous owner, so Han reckons he qualifies as
 794 Crew. Lando also offers the services of his top engineer, Hontook,
 795 for help with repairing the ship while they're in dock.</FONT></FONT></P>
 796 <P CLASS="western"><FONT FACE="Courier New, monospace">Default: DENY
 797 ALL<BR>Millennium Falcon Passengers<BR>&#9500;&#9472;Crew               [ALLOW:
 798 ALL]<BR>&#9474; &#9500;&#9472;Han<BR>&#9474; &#9500;&#9472;Chewie               [DENY:
 799 Engines]<BR>&#9474; &#9492;&#9472;<B>Lando</B><BR>&#9500;&#9472;Passengers      [ALLOW:
 800 Lounge]<BR>&#9474; &#9500;&#9472;Jedi           [ALLOW: Cockpit]<BR>&#9474; &#9474;
 801 &#9500;&#9472;Obi-wan<BR>&#9474; &#9474; &#9492;&#9472;Luke             [ALLOW:
 802 Guns] <BR>&#9474; &#9500;&#9472;R2D2<BR>&#9474;
 803 &#9492;&#9472;C3PO<BR>&#9492;&#9472;Engineers           [ALLOW: Engines,
 804 Guns]<BR>  &#9500;&#9472;Han<BR>  &#9500;&#9472;R2D2<BR>  &#9492;&#9472;<B>Hontook</B></FONT></P>
 805 <P CLASS="western" STYLE="line-height: 0.17in"><FONT FACE="Bitstream Vera Sans Mono, sans-serif"><FONT SIZE=2>This
 806 shows how easy it is to grant new people access. If we used the
 807 original matrix scheme, we'd have to set permissions for each room
 808 for both Lando and Hontook. Instead, we simply add them to their
 809 appropriate groups and their access is implicitly and easily defined.</FONT></FONT></P>
 810 <H2 CLASS="western"><FONT FACE="Bitstream Vera Sans Mono, sans-serif">Resolving
 811 conflicts</FONT></H2>
 812 <P CLASS="western"><FONT FACE="Bitstream Vera Sans Mono, sans-serif">What
 813 happens if we add Chewie to the list of Engineers?</FONT></P>
 814 <P CLASS="western"><FONT FACE="Courier New, monospace">Default: DENY
 815 ALL<BR>Millennium Falcon Passengers<BR>&#9500;&#9472;Crew               [ALLOW:
 816 ALL]<BR>&#9474; &#9500;&#9472;Han<BR>&#9474; &#9500;&#9472;Chewie               [DENY:
 817 Engines]<BR>&#9474; &#9492;&#9472;Lando<BR>&#9500;&#9472;Passengers     [ALLOW:
 818 Lounge]<BR>&#9474; &#9500;&#9472;Jedi           [ALLOW: Cockpit]<BR>&#9474; &#9474;
 819 &#9500;&#9472;Obi-wan<BR>&#9474; &#9474; &#9492;&#9472;Luke             [ALLOW:
 820 Guns] <BR>&#9474; &#9500;&#9472;R2D2<BR>&#9474;
 821 &#9492;&#9472;C3PO<BR>&#9492;&#9472;Engineers           [ALLOW: Engines,
 822 Guns]<BR>  &#9500;&#9472;Han<BR>  &#9500;&#9472;R2D2<BR>  &#9500;&#9472;Hontook<BR>
 823  &#9492;&#9472;<B>Chewie</B></FONT></P>
 824 <P CLASS="western">This makes Chewie's access to the Engines
 825 ambiguous, because now there are two paths from the root of the tree
 826 to Chewie. If the ship's computer follows one path (along the &quot;Crew&quot;
 827 branch), the result is &quot;DENY access to Engines.&quot; If it
 828 follows the other path (along the &quot;Engineers&quot; branch) then
 829 the result is &quot;ALLOW access to Engines&quot;. So, is he allowed
 830 or denied?</P>
 831 <P CLASS="western">phpGACL will warn you if you add or edit an
 832 multiply-grouped ARO in such a way that the ARO's access to an
 833 arbitrary ACO would be ambiguous. But it is <U>up to you</U> to
 834 resolve the conflict.</P>
 835 <P CLASS="western">If we now asked phpGACL the question &quot;Does
 836 Chewie have access to Engines?&quot; the result returned is the
 837 result given by the <U>last ACL entry to be modified</U> (this is
 838 phpGACL's policy). In this case the result is ALLOW, because the
 839 &quot;ALLOW: Engines, Guns&quot; directive assigned to the Engineers
 840 Group is more recent than the &quot;DENY: Engines&quot; directive
 841 assigned to Chewie's Group.</P>
 842 <P CLASS="western">When ambiguous access entries exist in the ACL,
 843 the ACL is said to be <B>inconsistent</B>. Inconsistent ACLs can be
 844 very dangerous, and you may unwittingly provide access to
 845 inappropriate people if you allow your ACL to remain in this state.
 846 When phpGACL warns you that the ACL is inconsistent, it is best to
 847 resolve the conflicts as soon as possible to regain consistency.</P>
 848 <P CLASS="western">To resolve the conflict in this case, we could
 849 either:</P>
 850 <UL>
 851         <LI VALUE=1><P CLASS="western">Remove the &quot;DENY: Engines&quot;
 852         directive from Chewie's entry under the Crew Group.</P>
 853         <LI><P CLASS="western">Add a &quot;DENY: Engines&quot; directive to
 854         Chewie's entry under the Engineers Group.</P>
 855         <LI><P CLASS="western">Remove Chewie from the Engineers Group, since
 856         Han doesn't think him a worthy Engineer anyway.</P>
 857 </UL>
 858 <P CLASS="western">Han chooses option 3, and removes Chewie from the
 859 Engineers list.</P>
 860 <H2 CLASS="western">Naming Access Objects</H2>
 861 <P CLASS="western" STYLE="line-height: 0.17in"><FONT FACE="Helv, Arial, sans-serif"><FONT SIZE=2>phpGACL
 862 uniquely identifies each Access Object (AROs, AXOs and ACOs) with a
 863 two-keyword combination and it's Access Object type.</FONT></FONT></P>
 864 <P CLASS="western" STYLE="line-height: 0.17in"><FONT FACE="Helv, Arial, sans-serif"><FONT SIZE=2>The
 865 tuple &quot;(Access Object type, Section, Value)&quot; uniquely
 866 identifies any Access Object.</FONT></FONT></P>
 867 <P CLASS="western" STYLE="line-height: 0.17in"><FONT FACE="Helv, Arial, sans-serif"><FONT SIZE=2>The
 868 first element of the tuple is the type of Access Object (ARO, AXO or
 869 ACO).</FONT></FONT></P>
 870 <P LANG="en-GB" CLASS="western" STYLE="line-height: 0.17in"><FONT FACE="Times New Roman, serif"><FONT SIZE=3><FONT SIZE=2><FONT FACE="Helv, Arial, sans-serif"><FONT COLOR="#000000"><SPAN LANG="en-US">The
 871 second element of the tuple, called the </SPAN><B>Section</B><SPAN LANG="en-US">,
 872 is a user-defined string which names the general category of the
 873 Access Object. Multiple Access Objects can share the same Section
 874 name. The Section name should be short but descriptive. It's used in
 875 the user interface in selection boxes, so try not to make it too
 876 long.</SPAN></FONT></FONT></FONT></FONT></FONT></P>
 877 <P CLASS="western" STYLE="line-height: 0.17in"><FONT FACE="Helv, Arial, sans-serif"><FONT SIZE=2>Sections
 878 are stored in a flat namespace; they are not nestable like Groups.
 879 Sections have nothing to do with Groups or the ARO/AXO trees - they
 880 are purely a mechanism for helping to maintain large numbers of
 881 Access Objects.</FONT></FONT></P>
 882 <P LANG="en-GB" CLASS="western" STYLE="line-height: 0.17in"><FONT FACE="Times New Roman, serif"><FONT SIZE=3><FONT SIZE=2><FONT FACE="Helv, Arial, sans-serif"><FONT COLOR="#000000"><SPAN LANG="en-US">The
 883 third element of the tuple is a user-defined name for the Access
 884 Object, and is called the </SPAN><B>Value</B><SPAN LANG="en-US">. <U>A
 885 Value cannot contain spaces</U> (however, a Section can).</SPAN></FONT></FONT></FONT></FONT></FONT></P>
 886 <P CLASS="western" STYLE="line-height: 0.17in"><FONT FACE="Helv, Arial, sans-serif"><FONT SIZE=2><U>Both
 887 Section and Values are case sensitive.</U></FONT></FONT></P>
 888 <P LANG="en-GB" CLASS="western" STYLE="margin-left: 0.38in; margin-top: 0in; margin-bottom: 0in; line-height: 0.17in">
 889 <FONT FACE="Times New Roman, serif"><FONT SIZE=3><FONT SIZE=2><FONT COLOR="#000000"><FONT FACE="Helv, Arial, sans-serif"><B>Aside:</B><SPAN LANG="en-US">
 890 It is commonly asked why strings are used to identify Access Objects,
 891 rather than integers which ostensibly seem faster. The answer is for
 892 legibility. It is much easier to understand:<BR>        </SPAN></FONT><SPAN LANG="en-US"><FONT FACE="Courier, Courier New, monospace">acl_check('system',
 893 'login', 'users', 'john_doe');<BR></FONT><FONT FACE="Helv, Arial, sans-serif">than:</FONT><FONT FACE="Courier, Courier New, monospace"><BR>     acl_check(10,
 894 21004, 15, 20304);</FONT></SPAN></FONT></FONT></FONT></FONT></P>
 895 <P LANG="en-GB" CLASS="western" STYLE="line-height: 0.17in"><FONT FACE="Times New Roman, serif"><FONT SIZE=3><FONT SIZE=2><FONT FACE="Helv, Arial, sans-serif"><FONT COLOR="#000000"><SPAN LANG="en-US">Since
 896 it is often obvious from the context which type of Access Object we
 897 are referring to, the interface for phpGACL (and this documentation)
 898 drops the Access Object type and uses the format &quot;</SPAN><B>Section
 899 &gt; Value</B><SPAN LANG="en-US">&quot; when displaying the name of
 900 an Access Object. However, the API requires an Access Object's
 901 &quot;Section&quot; and &quot;Value&quot; to be specified in separate
 902 function arguments (the Access Object type is usually implicit in the
 903 argument description).</SPAN></FONT></FONT></FONT></FONT></FONT></P>
 904 <P LANG="en-GB" CLASS="western" STYLE="line-height: 0.17in"><FONT FACE="Helv, Arial, sans-serif"><FONT SIZE=2><B>Example
 905 ACO &quot;Section &gt; Values&quot;:</B></FONT></FONT></P>
 906 <UL>
 907         <LI VALUE=1><P CLASS="western" STYLE="line-height: 0.17in"><FONT FACE="Helv, Arial, sans-serif"><FONT SIZE=2>&quot;Floors
 908         &gt; 1st&quot;</FONT></FONT></P>
 909         <LI><P CLASS="western" STYLE="line-height: 0.17in"><FONT FACE="Helv, Arial, sans-serif"><FONT SIZE=2>&quot;Floors
 910         &gt; 2nd&quot;</FONT></FONT></P>
 911         <LI><P CLASS="western" STYLE="line-height: 0.17in"><FONT FACE="Helv, Arial, sans-serif"><FONT SIZE=2>&quot;Rooms
 912         &gt; Engines&quot;</FONT></FONT></P>
 913 </UL>
 914 <P CLASS="western"><B>Example ARO &quot;Section &gt; Values&quot;:</B></P>
 915 <UL>
 916         <LI VALUE=1><P CLASS="western" STYLE="line-height: 0.17in"><FONT FACE="Helv, Arial, sans-serif"><FONT SIZE=2>&quot;People
 917         &gt; John_Smith&rdquo;</FONT></FONT></P>
 918         <LI><P CLASS="western" STYLE="line-height: 0.17in">&ldquo;<FONT FACE="Helv, Arial, sans-serif"><FONT SIZE=2>People
 919         &gt; Cathy_Jones&rdquo;</FONT></FONT></P>
 920         <LI><P CLASS="western" STYLE="line-height: 0.17in">&ldquo;<FONT FACE="Helv, Arial, sans-serif"><FONT SIZE=2>Hosts
 921         &gt; sandbox.something.com&rdquo;</FONT></FONT></P>
 922 </UL>
 923 <P CLASS="western"><B>Example API usage:</B></P>
 924 <UL>
 925         <LI VALUE=1><P CLASS="western" STYLE="font-weight: medium; line-height: 0.17in">
 926         <FONT FACE="Helv, Arial, sans-serif"><FONT SIZE=2>acl_check (
 927         aco_section, aco_value, aro_section, aro_value);</FONT></FONT></P>
 928         <LI><P CLASS="western" STYLE="font-weight: medium; line-height: 0.17in">
 929         <FONT FACE="Helv, Arial, sans-serif"><FONT SIZE=2>acl_check (
 930         'Floors', '2nd', 'People', 'John_Smith' );</FONT></FONT></P>
 931 </UL>
 932 <P CLASS="western" STYLE="line-height: 0.17in"><FONT FACE="Helv, Arial, sans-serif"><FONT SIZE=2><B>Valid
 933 Naming Restrictions Examples:</B></FONT></FONT></P>
 934 <UL>
 935         <LI VALUE=1><P CLASS="western" STYLE="line-height: 0.17in"><FONT FACE="Helv, Arial, sans-serif"><FONT SIZE=2>&quot;ACO
 936         -Frob &gt; Flerg&quot;, &quot;ARO - Frob &gt; Flerg&quot; (The
 937         Section and Value are the same in both, but this is fine as
 938         namespaces are separate across Access Object types)</FONT></FONT></P>
 939         <LI><P CLASS="western" STYLE="line-height: 0.17in"><FONT FACE="Helv, Arial, sans-serif"><FONT SIZE=2>&quot;ACO
 940         -Frob &gt; Flerg&quot;, &quot;ACO - Frob &gt; Queegle&quot; (The
 941         Access Object type and Section are the same, but this is fine as the
 942         Values are different)</FONT></FONT></P>
 943         <LI><P CLASS="western" STYLE="line-height: 0.17in"><FONT FACE="Helv, Arial, sans-serif"><FONT SIZE=2>&quot;AXO
 944         - Frob Hrung &gt; Flerg&quot; (Sections can contain spaces)</FONT></FONT></P>
 945 </UL>
 946 <P LANG="en-GB" CLASS="western" STYLE="line-height: 0.17in"><FONT FACE="Helv, Arial, sans-serif"><FONT SIZE=2><B>Invalid
 947 Naming Restrictions Examples:</B></FONT></FONT></P>
 948 <UL>
 949         <LI VALUE=1><P CLASS="western" STYLE="line-height: 0.17in"><FONT FACE="Helv, Arial, sans-serif"><FONT SIZE=2>&quot;ACO
 950         - Frob &gt; Flerg&quot;, &quot;ACO - Frob &gt; Flerg&quot; (&quot;Access
 951         Object type - Section &gt; Value&quot; must be unique)</FONT></FONT></P>
 952         <LI><P CLASS="western" STYLE="line-height: 0.17in"><FONT FACE="Helv, Arial, sans-serif"><FONT SIZE=2>&quot;ACO
 953         - Frob &gt; Flerg Habit&quot; (Values cannot contain spaces)</FONT></FONT></P>
 954 </UL>
 955 <H2 LANG="en-GB" CLASS="western">Adding Sections</H2>
 956 <P LANG="en-GB" STYLE="line-height: 100%"><FONT FACE="Helv, Arial, sans-serif">Before
 957 you can add a new Access Object, its Section must be defined. To add
 958 a new section, use the add_object_section() function.</FONT></P>
 959 <P LANG="en-GB" CLASS="western" STYLE="line-height: 100%"><FONT FACE="Arial, sans-serif"><FONT SIZE=2>add_object_section
 960 (</FONT></FONT></P>
 961 <P LANG="en-GB" STYLE="margin-left: 2.5in; text-indent: -2in; line-height: 100%">
 962 <FONT FACE="Arial, sans-serif"><FONT FACE="Courier New, monospace">string
 963 NAME,</FONT>    A short description of what this Section is for. (e.g.
 964 &quot;Levels in building&quot;).</FONT></P>
 965 <P LANG="en-GB" STYLE="margin-left: 2.5in; text-indent: -2in; line-height: 100%">
 966 <FONT FACE="Arial, sans-serif"><FONT FACE="Courier New, monospace">string
 967 VALUE,</FONT>   The name of the Section (e.g. &quot;Floor&quot;).</FONT></P>
 968 <P LANG="en-GB" STYLE="margin-left: 2.5in; text-indent: -2in; line-height: 100%">
 969 <FONT FACE="Arial, sans-serif"><FONT FACE="Courier New, monospace">int
 970 ORDER,</FONT>   An arbitrary value which affects the order this Section
 971 appears in the UI.</FONT></P>
 972 <P LANG="en-GB" STYLE="margin-left: 2.5in; text-indent: -2in; line-height: 100%">
 973 <FONT FACE="Arial, sans-serif"><FONT FACE="Courier New, monospace">bool
 974 HIDDEN, </FONT>Whether this should appear in the UI or not (TRUE
 975 means that is will be hidden).</FONT></P>
 976 <P LANG="en-GB" STYLE="margin-left: 2.5in; text-indent: -2in; line-height: 100%">
 977 <FONT FACE="Arial, sans-serif"><FONT FACE="Courier New, monospace">string
 978 GROUP_TYPE)     </FONT>The Access Object type (&quot;aco&quot;, &quot;aro&quot;
 979 or &quot;axo&quot;)</FONT></P>
 980 <P CLASS="western" STYLE="line-height: 0.17in"><FONT FACE="Helv, Arial, sans-serif"><FONT SIZE=2>Han
 981 creates 3 Sections for the AROs. &quot;Humans&quot;, &quot;Aliens&quot;
 982 and &quot;Androids&quot;. Let's list the AROs with their full names</FONT></FONT></P>
 983 <P CLASS="western"><FONT FACE="Courier New, monospace">Millennium
 984 Falcon Passengers<BR>&#9500;&#9472;Crew                         [ALLOW: ALL]<BR>&#9474;
 985 &#9500;&#9472;<B>&quot;Humans &gt; Han&quot;</B><BR>&#9474; &#9500;&#9472;<B>&quot;Aliens
 986 &gt; Chewie&quot;</B>           [DENY: Engines]<BR>&#9474; &#9492;&#9472;<B>&quot;Humans
 987 &gt; Lando&quot;</B><BR>&#9500;&#9472;Passengers                        [ALLOW: Lounge]<BR>&#9474;
 988 &#9500;&#9472;Jedi                              [ALLOW: Cockpit]<BR>&#9474; &#9474; &#9500;&#9472;<B>&quot;Humans
 989 &gt; Obi-wan&quot;</B><BR>&#9474; &#9474; &#9492;&#9472;<B>&quot;Humans
 990 &gt; Luke&quot;</B>             [ALLOW: Guns] <BR>&#9474; &#9500;&#9472;<B>&quot;Androids
 991 &gt; R2D2&quot;</B><BR>&#9474; &#9492;&#9472;<B>&quot;Androids &gt;
 992 C3PO&quot;</B><BR>&#9492;&#9472;Engineers                               [ALLOW: Engines, Guns]<BR>
 993  &#9500;&#9472;<B>&quot;Humans &gt; Han&quot;</B><BR>  &#9500;&#9472;<B>&quot;Androids
 994 &gt; R2D2&quot;</B><BR>  &#9492;&#9472;<B>&quot;Aliens &gt; Hontook&quot;</B></FONT></P>
 995 <P CLASS="western" STYLE="line-height: 0.17in"><FONT FACE="Helv, Arial, sans-serif"><FONT SIZE=2>Sections
 996 are just a way of categorizing Access Objects, to make the user
 997 interface more usable, and the code for acl_check() more readable.
 998 They do not affect the way phpGACL determines access to an object.
 999 They cannot be nested (so it would not be able to create a &quot;Males&quot;
1000 sub-Section under &quot;Humans&quot; for example; you'd have to
1001 create a Section called &quot;Humans-Male&quot; or similar)</FONT></FONT></P>
1002 <H2 CLASS="western">Multiple Purposes</H2>
1003 <P CLASS="western" STYLE="line-height: 0.17in"><FONT FACE="Helv, Arial, sans-serif"><FONT SIZE=2>You
1004 may need to use phpGACL for multiple independent purposes. For
1005 example, you may need to restrict user access to web pages, and also
1006 remote host access to your server. The two tasks are not related.</FONT></FONT></P>
1007 <P CLASS="western" STYLE="line-height: 0.17in"><FONT FACE="Helv, Arial, sans-serif"><FONT SIZE=2>phpGACL
1008 can handle this in three different ways.</FONT></FONT></P>
1009 <UL>
1010         <LI VALUE=1><P CLASS="western" STYLE="line-height: 0.17in"><FONT FACE="Helv, Arial, sans-serif"><FONT SIZE=2>It
1011         can use an alternative database to store the access tables.</FONT></FONT></P>
1012         <LI><P CLASS="western" STYLE="line-height: 0.17in"><FONT FACE="Helv, Arial, sans-serif"><FONT SIZE=2>It
1013         can use the same database but with differently named access tables.
1014         (this feature is not implemented yet).</FONT></FONT></P>
1015         <LI><P CLASS="western" STYLE="line-height: 0.17in"><FONT FACE="Helv, Arial, sans-serif"><FONT SIZE=2>You
1016         can store the Access Objects for both purposes in the same tables,
1017         and carefully manage your list so that they don't conflict.</FONT></FONT></P>
1018 </UL>
1019 <P CLASS="western" STYLE="line-height: 0.17in"><FONT FACE="Helv, Arial, sans-serif"><FONT SIZE=2>To
1020 implement Option 1 (and Option 2 when it becomes available), use the
1021 $gacl_options array when creating a new phpGACL class. This allows
1022 you to specify the database and table name prefixes to use:</FONT></FONT></P>
1023 <P CLASS="western" STYLE="margin-top: 0in; margin-bottom: 0in; line-height: 0.17in">
1024 <FONT FACE="Courier, Courier New, monospace"><FONT SIZE=2>$gacl_options
1025 = array(<BR>    'db_table_prefix' =&gt; 'gacl_',<BR>    'db_type' =&gt;
1026 'mysql',<BR>    'db_host' =&gt; 'host1',<BR>    'db_user' =&gt;
1027 'user',<BR>     'db_password' =&gt; 'passwd',<BR>       'db_name' =&gt;
1028 'gacl');</FONT></FONT></P>
1029 <P CLASS="western" STYLE="margin-top: 0in; margin-bottom: 0in; line-height: 0.17in">
1030 <BR>
1031 </P>
1032 <P CLASS="western" STYLE="margin-top: 0in; margin-bottom: 0in; line-height: 0.17in">
1033 <FONT FACE="Courier, Courier New, monospace"><FONT SIZE=2>$gacl_host1
1034 = new gacl($gacl_options);</FONT></FONT></P>
1035 <P CLASS="western" STYLE="line-height: 0.17in"><FONT FACE="Helv, Arial, sans-serif"><FONT SIZE=2>To
1036 implement Option 3, you must be careful, since phpGACL doesn't know
1037 the relationship between your different tasks, and it will be
1038 possible to make meaningless Access Policy Directives.</FONT></FONT></P>
1039 <P CLASS="western" STYLE="line-height: 0.17in"><FONT FACE="Helv, Arial, sans-serif"><FONT SIZE=2>For
1040 example, say Han wanted to restrict access to other ships contacting
1041 his ship's computer, in addition to restricting access to the
1042 different rooms. To do this, he might add &quot;Luke's X-Wing
1043 Fighter&quot; as a remote ship ARO (in addition to other ships and an
1044 ACO for the ship's computer). Because all AROs are in the same ARO
1045 tree, it would be possible to create an APD like &quot;Ships &gt;
1046 Luke's X-Wing Fighter&quot; [ALLOW: &quot;Rooms &gt; Lounge&quot;],
1047 which would be totally meaningless! To help reduce mistakes like
1048 this, good Section naming can make it clearer what Access Objects are
1049 for which tasks. It should be obvious to any administrator that it's
1050 meaningless to assign a Ship permission to use a Room.</FONT></FONT></P>
1051 <H2 LANG="en-GB" CLASS="western">Access eXtension Objects</H2>
1052 <P CLASS="western"><B>Access eXtension Objects</B> (AXOs) can add a
1053 3rd dimension to the permissions that can be configured in phpGACL.
1054 We've seen how phpGACL allows you to combine an ARO and an ACO (2
1055 dimensions) to create an Access Policy Directive. This is great for
1056 simple permission requests like:</P>
1057 <P CLASS="western">     Luke (ARO) requests access to &quot;Guns&quot;
1058 (ACO)</P>
1059 <P CLASS="western">If that's all you need, that's fine - AXOs are
1060 totally optional.</P>
1061 <P CLASS="western">But because all ACOs are considered equal, it
1062 makes it difficult to manage if there are many ACOs. If this is the
1063 case, we can change the way we look at Access Objects to manage it
1064 more easily.</P>
1065 <P CLASS="western">AXOs are identical to AROs in many respects. There
1066 is an AXO tree (separate from the ARO tree), with it's own Groups and
1067 AXOs. When dealing with AXOs, consider an AXO to take the old role of
1068 the ACO (i.e. &quot;things to control access on&quot;), and change
1069 the view of ACOs from &quot;things to control access on&quot; to
1070 &quot;actions that are requested&quot;.</P>
1071 <P CLASS="western"><B>ARO and ACO-only View:</B></P>
1072 <UL>
1073         <LI VALUE=1><P CLASS="western">AROs: Things requesting access</P>
1074         <LI><P CLASS="western">ACOs: Things to control access on</P>
1075 </UL>
1076 <P CLASS="western"><B>ARO, ACO and AXO View:</B></P>
1077 <UL>
1078         <LI VALUE=1><P CLASS="western">AROs: Things requesting access</P>
1079         <LI><P CLASS="western">ACOs: Actions that are requested</P>
1080         <LI><P CLASS="western">AXOs: Things to control access on</P>
1081 </UL>
1082 <P CLASS="western"><B>Example:</B></P>
1083 <P CLASS="western">A website manager is trying to manage access to
1084 projects on the website. The ARO tree consists of all the users:</P>
1085 <P CLASS="western"><FONT FACE="Courier New, monospace">Website<BR>&#9500;&#9472;Administrators<BR>&#9474;
1086 &#9500;&#9472;Alice<BR>&#9474; &#9492;&#9472;Carol<BR>&#9492;&#9472;Users<BR>
1087  &#9500;&#9472;Bob<BR>  &#9492;&#9472;Alan</FONT></P>
1088 <P CLASS="western">The projects are organized by Operating System
1089 into categories in the AXO tree:</P>
1090 <P CLASS="western"><FONT FACE="Courier New, monospace">Projects<BR>&#9500;&#9472;Linux<BR>&#9474;
1091 &#9500;&#9472;SpamFilter2<BR>&#9474; &#9492;&#9472;AutoLinusWorshipper<BR>&#9492;&#9472;Windows<BR>
1092  &#9500;&#9472;PaperclipKiller<BR>  &#9492;&#9472;PopupStopper</FONT></P>
1093 <P CLASS="western">The actions that can be taken with each project
1094 are &quot;View&quot; and &quot;Edit&quot;. These are the ACOs.</P>
1095 <P CLASS="western">Now we want Bob to have &quot;View&quot; access to
1096 all the Linux projects, so it's possible to add an ACL that links
1097 Bob's ARO to the View ACO and the Linux AXO, and thus we can ask the
1098 question:</P>
1099 <P CLASS="western">     Bob (ARO) requests access to &quot;View&quot;
1100 (ACO) the project(s) called &quot;Linux&quot; (AXO)</P>
1101 <P CLASS="western">Keep in mind AXO's are optional, if you don't
1102 specify an AXO when calling acl_check() and a matching ACL exists
1103 with no AXO, it will be allowed. However if <U>only</U> ACLs exist
1104 with AXO's, and you call acl_check() without an AXO, it will fail.</P>
1105 <P CLASS="western">So basically as soon as you specify an AXO when
1106 calling acl_check(), acl_check() will only search ACLs containing
1107 AXO's. If no AXO is specified, only ACLs without AXOs are searched.
1108 This in theory (I haven't benchmarked) gives us a slight performance
1109 increase as well.</P>
1110 <H1 LANG="en-GB" CLASS="western">Installation</H1>
1111 <H2 LANG="en-GB" CLASS="western">Basic setup</H2>
1112 <OL>
1113         <LI><P CLASS="western">Untar the distribution .tar.gz file into the
1114         root or a subdirectory of your web site. You might want to rename it
1115         to something more suitable.<BR><BR><BR>
1116         </P>
1117         <P CLASS="western"><IMG SRC="manual_html_m48c2db5c.png" NAME="Graphic1" ALIGN=LEFT WIDTH=474 HEIGHT=146 BORDER=0><BR CLEAR=LEFT></P>
1118         <LI><P CLASS="western">Edit phpgacl/gacl.ini.php using your
1119         favourite editor and set the db_type, db_host, db_user, db_password,
1120         and db_name you will be using.</P>
1121         <LI><P CLASS="western">Create the database you specified in db_name
1122         on the server.<BR><BR><BR>
1123         </P>
1124         <P CLASS="western"><IMG SRC="manual_html_m770a5a15.png" NAME="Graphic3" ALIGN=LEFT WIDTH=397 HEIGHT=123 BORDER=0><BR CLEAR=LEFT></P>
1125         <P CLASS="western"></P>
1126         <LI><P CLASS="western">Surf to
1127         http://yoursite.net/phpgacl/setup.php. The required tables will be
1128         installed based on your choice of database. Don't be afraid of the
1129         truckload of output, if all goes well you will see only success
1130         messages.<BR><BR><BR>
1131         </P>
1132 </OL>
1133 <P CLASS="western"><IMG SRC="manual_html_7dced6ce.png" NAME="Graphic4" ALIGN=LEFT WIDTH=519 HEIGHT=504 BORDER=0><BR CLEAR=LEFT><BR><BR>
1134 </P>
1135 <OL START=5>
1136         <LI><P CLASS="western">Now follow the last advice shown on that
1137         screen and create the phpgacl/admin/smarty/templates_c directory. It
1138         must be writable by the user the webserver runs as. If you don't do
1139         this, you will not be able to use the CAL admin!</P>
1140         <LI><P CLASS="western">Click the link at the bottom of the
1141         successful setup page or surf
1142         to:<BR>http://yoursite.net/phpgacl/admin/acl_admin.php</P>
1143 </OL>
1144 <H2 LANG="en-GB" CLASS="western">Advanced setup</H2>
1145 <H3 LANG="en-GB" CLASS="western">Reusing an already existing ADOdb
1146 installation</H3>
1147 <P CLASS="western">If you already have ADOdb installed you can get
1148 phpGACL to use this copy of ADOdb.</P>
1149 <OL>
1150         <LI><P CLASS="western">Edit phpgacl/gacl.class.php so that ADODB_DIR
1151         reflects the location of the ADOdb library in your path.</P>
1152         <LI><P CLASS="western">Rename the phpgacl/adodb folder to something
1153         else like adodb_x and reload the phpgacl/admin/acl_admin.php page to
1154         ensure it still works.</P>
1155         <LI><P CLASS="western">Erase the adodb directory installed with
1156         phpGACL.</P>
1157 </OL>
1158 <H3 LANG="en-GB" CLASS="western">Reusing an already existing Smarty
1159 installation</H3>
1160 <P CLASS="western">If you already have ADOdb installed you can get
1161 phpGACL to use this copy of ADOdb.</P>
1162 <OL>
1163         <LI><P CLASS="western">Edit phpgacl/admin/gacl_admin.inc.php so that
1164         the variables $smarty_dir and $smarty_compile_dir reflect the
1165         location of the Smarty library in your path and the template_c
1166         directory you already use.</P>
1167         <P CLASS="western">Move the templates directory that came with
1168         phpGACL to another directory (e.g. one level up). Adjust the
1169         $smarty_template_dir so it points to the new location. If you like
1170         you can move those templates to your existing templates folder, of
1171         course.</P>
1172         <LI><P CLASS="western">Rename the phpgacl/smarty folder to something
1173         else like smarty_x and reload the phpgacl/admin/acl_admin.php page
1174         to ensure it still works.</P>
1175         <LI><P CLASS="western">Erase the smarty directory installed with
1176         phpGACL.</P>
1177 </OL>
1178 <H3 LANG="en-GB" CLASS="western">How do I move  the phpGACL files out
1179 of my website tree while leaving a link in the tree for
1180 administration?</H3>
1181 <OL>
1182         <LI><P CLASS="western">Go to your website root.</P>
1183         <LI><P CLASS="western">Move the phpGACL directory to your includes
1184         directory and create a symlink to the admin directory where you want
1185         the admin tool to go. For example:</P>
1186         <P CLASS="western">mv phpgacl/ /www/includes_directory<BR>ln -s
1187         /www/includes_directory/phpgacl/admin/ gacl</P>
1188         <LI><P CLASS="western">Now surfing to
1189         http://yoursite.net/gacl/acl_admin.php will take you to the admin
1190         page. If it doesn't work, make sure your Webserver allows symbolic
1191         links in the website tree.</P>
1192 </OL>
1193 <H1 LANG="en-GB" CLASS="western">Using phpGACL in your application</H1>
1194 <H2 LANG="en-GB" CLASS="western">Basic usage</H2>
1195 <P CLASS="western">This example shows a basic example of using
1196 phpGACL in your code. It uses the ADOdb abstraction layer as well,
1197 and shows a simple way to validate a login attempt against a
1198 database.</P>
1199 <P CLASS="western"><FONT FACE="Courier New"><FONT COLOR="#ff0000">//
1200 include basic ACL api</FONT><BR><FONT COLOR="#00cccc">include</FONT>('<FONT COLOR="#008000">phpgacl/gacl.class.php</FONT>');<BR>$<FONT COLOR="#ff6633">gacl</FONT>
1201 = <FONT COLOR="#00cccc">new</FONT> gacl();</FONT></P>
1202 <P CLASS="western"><FONT FACE="Courier New">$<FONT COLOR="#ff6633">username</FONT>
1203 = $<FONT COLOR="#ff6633">db</FONT>-&gt;<FONT COLOR="#00cccc">quote</FONT>($<FONT COLOR="#ff6633">_POST</FONT>['<FONT COLOR="#008000">username</FONT>']);<BR>$<FONT COLOR="#ff6633">password</FONT>
1204 = $<FONT COLOR="#ff6633">db</FONT>-&gt;<FONT COLOR="#00cccc">quote</FONT>(md5($<FONT COLOR="#ff6633">_POST</FONT>['<FONT COLOR="#008000">password</FONT>']));<BR>$<FONT COLOR="#ff6633">sql</FONT>
1205 = '<FONT COLOR="#008000">SELECT name FROM users WHERE name=</FONT>';<BR>$<FONT COLOR="#ff6633">sql</FONT>
1206 .= $<FONT COLOR="#ff6633">username</FONT>.' <FONT COLOR="#008000">AND
1207 password=</FONT>'.$<FONT COLOR="#ff6633">password</FONT>;<BR>$<FONT COLOR="#ff6633">row</FONT>
1208 = $<FONT COLOR="#ff6633">db</FONT>-&gt;<FONT COLOR="#00cccc">GetRow</FONT>($<FONT COLOR="#ff6633">sql</FONT>);</FONT></P>
1209 <P CLASS="western"><FONT FACE="Courier New"><FONT COLOR="#00cccc">if</FONT>($<FONT COLOR="#ff6633">gacl</FONT>-&gt;<FONT COLOR="#00cccc">acl_check</FONT>('<FONT COLOR="#008000">system</FONT>','<FONT COLOR="#008000">login</FONT>','<FONT COLOR="#008000">user</FONT>',$<FONT COLOR="#ff6633">row</FONT>['<FONT COLOR="#008000">name</FONT>'])){<BR>
1210  $<FONT COLOR="#ff6633">_SESSION</FONT>['<FONT COLOR="#008000">username</FONT>']
1211 = $<FONT COLOR="#ff6633">row</FONT>['<FONT COLOR="#008000">name</FONT>'];<BR>
1212  <FONT COLOR="#00cccc">return</FONT> <FONT COLOR="#6b4794">true</FONT>;<BR>}<BR><FONT COLOR="#00cccc">else</FONT><BR>
1213  <FONT COLOR="#00cccc">return</FONT> <FONT COLOR="#6b4794">false</FONT>;</FONT></P>
1214 <P CLASS="western">As you can see there is only one call to
1215 acl_check() in this code. What does it do? Well, it</P>
1216 <UL>
1217         <LI><P CLASS="western">checks the ARO object $row['name'] from the
1218         ARO section 'user'</P>
1219         <LI><P CLASS="western">against the ACO object 'login' from the ACO
1220         section 'system'.</P>
1221 </UL>
1222 <H2 LANG="en-GB" CLASS="western">Advanced usage</H2>
1223 <P CLASS="western"><BR><BR>
1224 </P>
1225 <H1 LANG="en-GB" CLASS="western">Using the ACL admin utility</H1>
1226 <P CLASS="western">If you want to get a grip on the included ACL
1227 admin utitlity, it will help you a lot if you run the example.php
1228 file. It contains some ACO, ARO and AXO objects, as well as some ACL
1229 defined using those objects. After running it, you should see some
1230 sample data in the admin interface.<BR><BR><BR>
1231 </P>
1232 <P CLASS="western"><IMG SRC="manual_html_4b803670.png" NAME="Graphic5" ALIGN=LEFT WIDTH=531 HEIGHT=488 BORDER=0><BR CLEAR=LEFT><BR><BR>
1233 </P>
1234 <P CLASS="western">Play around with it, and if you get stuck, come
1235 back and read on...</P>
1236 <P CLASS="western">(yet to be written)</P>
1237 <H2 LANG="en-GB" CLASS="western">ACL's</H2>
1238 <H3 LANG="en-GB" CLASS="western">Creating</H3>
1239 <P CLASS="western">You must have a minimum of an ACO and an ARO
1240 defined to create an ACL.</P>
1241 <P CLASS="western">Select an ACO Section then select from the
1242 available items show in the Access Control Objects list.  Click the [
1243 &gt; &gt; ] button to add the Section-ACO to the Selected list.  You
1244 may add any number of Section-ACO pairs to this list.</P>
1245 <P CLASS="western"><IMG SRC="manual_html_m608b392a.png" NAME="Graphic9" ALIGN=LEFT WIDTH=531 HEIGHT=177 BORDER=0><BR CLEAR=LEFT><BR><BR>
1246 </P>
1247 <P CLASS="western">Next select an ARO Section.  At this point you may
1248 select from either the Access Request Objects list or from the ARO
1249 Groups list.</P>
1250 <P CLASS="western"><IMG SRC="manual_html_157037e7.png" NAME="Graphic10" ALIGN=LEFT WIDTH=531 HEIGHT=157 BORDER=0><BR CLEAR=LEFT><BR><BR>
1251 </P>
1252 <P CLASS="western">Select on of the ACL Sections (usually &ldquo;user&rdquo;
1253 for this case), provide a brief description in the Note area and then
1254 click Submit.  Click on the &ldquo;ACL Admin&rdquo; tab and you will
1255 see your new ACL in the list.</P>
1256 <H3 LANG="en-GB" CLASS="western">Sections</H3>
1257 <P CLASS="western"><IMG SRC="manual_html_676f8c98.png" NAME="Graphic7" ALIGN=LEFT WIDTH=518 HEIGHT=149 BORDER=0><BR CLEAR=LEFT>A
1258 default install provides you with two ACL sections &ndash; 'system'
1259 and 'user'.  You would typically put user created ACL's (for example,
1260 those you enter via the admin interface) in the 'user' section and
1261 put ACL's generated by code in the 'system' section.  However, you
1262 can use the ACL sections to provide any other logical grouping that
1263 suits your purposes.</P>
1264 <H3 LANG="en-GB" CLASS="western">Extended Return Value</H3>
1265 <P CLASS="western">Typically a call to the acl_check method will
1266 return a boolean value.  However, you may specify a different value
1267 or evan a string to be returned.
1268 </P>
1269 <P CLASS="western">For example, you may negotiate for a user to login
1270 at a cost of $0.20 per time by default and another for $0.18 per time
1271 under a different scheme.  You could create a separate ACL for the
1272 default login and for the special use but varying the 'return value'.
1273  If the call to acl_check is successful, you will know the cost of
1274 the login via the return value.</P>
1275 <H3 LANG="en-GB" CLASS="western">Notes</H3>
1276 <P CLASS="western">It's a good idea to add a note when creating an
1277 ACL to help remember it's purpose, for example &ldquo;Basic
1278 permissions for a user in the Administrator group&rdquo;.</P>
1279 <P CLASS="western"><IMG SRC="manual_html_m4f4324cb.png" NAME="Graphic8" ALIGN=LEFT WIDTH=526 HEIGHT=120 BORDER=0><BR CLEAR=LEFT><BR><BR>
1280 </P>
1281 <H1 LANG="en-GB" CLASS="western"><A NAME="Glossary"></A>Glossary</H1>
1282 <H2 LANG="en-GB" CLASS="western">ACO</H2>
1283 <P CLASS="western" STYLE="line-height: 0.17in"><FONT FACE="Helv, Arial, sans-serif"><FONT SIZE=2><DFN>Access
1284 Control Object &ndash; An action that are requested to be performed.</DFN></FONT></FONT></P>
1285 <H2 LANG="en-GB" CLASS="western">ARO</H2>
1286 <P CLASS="western" STYLE="line-height: 0.17in"><FONT FACE="Helv, Arial, sans-serif"><FONT SIZE=2><DFN><SPAN LANG="en-US"><FONT SIZE=2><FONT FACE="Helv, Arial, sans-serif"><FONT COLOR="#000000">Access
1287 Request Object &ndash; An entity (for example, a user) that is
1288 requesting an action to be performed.</FONT></FONT></FONT></SPAN></DFN></FONT></FONT></P>
1289 <H2 LANG="en-GB" CLASS="western">AXO</H2>
1290 <P CLASS="western" STYLE="line-height: 0.17in"><FONT FACE="Helv, Arial, sans-serif"><FONT SIZE=2><DFN><SPAN LANG="en-US"><FONT SIZE=2><FONT FACE="Helv, Arial, sans-serif"><FONT COLOR="#000000">Access
1291 eXtension Object &ndash; An object to perform an action on for an
1292 entity.</FONT></FONT></FONT></SPAN></DFN></FONT></FONT></P>
1293 <H1 LANG="en-GB" CLASS="western">References</H1>
1294 <H2 LANG="en-GB" CLASS="western">phpGACL API</H2>
1295 <P LANG="en-GB" CLASS="western" STYLE="line-height: 100%"><FONT FACE="Helv, Arial"><FONT SIZE=2>The
1296 API documentation is included in the tarball under the /docs/phpdoc/
1297 directory.</FONT></FONT></P>
1298 <H2 LANG="en-GB" CLASS="western">phpGACL Examples and Tutorials</H2>
1299 <P LANG="en-GB" CLASS="western" STYLE="line-height: 100%"><FONT FACE="Helv, Arial"><FONT SIZE=2>See
1300 example.php included in the tarball.</FONT></FONT></P>
1301 <H2 LANG="en-GB" CLASS="western">Access Control Resources</H2>
1302 <P LANG="en-GB" CLASS="western" STYLE="line-height: 100%"><FONT FACE="Helv, Arial"><FONT SIZE=2>.
1303 . .</FONT></FONT></P>
1304 <P CLASS="western"><BR><BR>
1305 </P>
1306 <H1 LANG="en-GB" CLASS="western">FAQ</H1>
1307 <H2 LANG="en-GB" CLASS="western">Can phpGACL handle large sets of
1308 data?</H2>
1309 <P LANG="en-GB" CLASS="western" STYLE="line-height: 100%"><FONT FACE="Helv, Arial"><FONT SIZE=2>Not
1310 a problem at all. We've tested up to 100,000 AXO's and 100,000 ARO's
1311 on moderate hardware even. The performance issues come down to how
1312 well you can cache the ACL's, and how fast your database server is.</FONT></FONT></P>
1313 </BODY>
1314 </HTML>