[Phpgroupware-developers] New ACL functionality

[Dan Kuykendall]

I am well underway on this new ACL and decided to step back a little and 
explain how it works and what it can do.

I have all the basic functionality working in code now and am just 
filling it in and making it all a clean object to be able to replace the 
current ACL (which after this re-write proves to perform terribly and 
has overly complicated design with a majorly lacking feature set.

The major new features are that it now supports inheritance, inherited 
rights masks, nested memberships (not yet explained in the following), 
better performance and cleaner more understandable code.
It no longer has the concept of explict deny because rights masks can 
accomplish the same thing and are more flexible.

Heres an explaintion of how it works overal.
This is the first draft and would greatly appreciate help in cleaning 
this up.
-------------------------------------------------------------
To help understand how the ACL works it requires an understanding of bit 
set operations. This probably sounds more complicated than it is so I 
will explain here.

Bit switches:
Lets look at it as a series of 8 switches that can be used to represent 
any number between 1 and 256
The values of the switches are as follows
switch - 1   2   3   4   5   6   7   8
value  - 1   2   4   8   16  32  64  128

To get a value you just turn on the switches which will add up to the 
desired value
So the value of 3 would mean switches 1 and 2 are turned on.
The value of 20 would mean switches 5 and 3 are on. 5th value of 16 plus 
3rds values of 4 = 20.
For 256 we would turn on all switches

Using switches to represent rights:
In ACL's we think of each switch as a right, so lets look at them as follows
switch  - 1     2      3       4
value   - 1     2      4       8
right   - read  edit   delete  create
                        
I am only using the first 4 switches in this case and thats fine.

So if I want a user to have read and write access I would add a record 
with rights = 3
To give them read, edit and create rights I would give the user rights = 
11 (values 1+2+8)
rights = 15 would give them all four of the rights.

Adding rights/switches (not your normal math):
When I add up a users rights with their rights given to them by their 
groups I simply flip switches using bit math operations.
So lets say a user has rights of 11 (read, edit delete) and is a member 
of group1 which has rights of 10 (edit, create). If you use normal 
addition you would end up with 21 which is not what we want. 21 would be 
switches 1, 3 and 5 and the user would not have the correct rights.
So using bit operations it works as follows.
User rights of 11 turn on switches 1, 2, and 3.
Group1 rights turn on switches 2 and 4
Notice switch 2 was turned on twice, which basicly means the second time 
did nothing.
So now when I look at the value it is 15 as we want.
I hope your following so far, but even if you dont understand fully read 
on to see how this is put into action for powerful inheritance and masking.

Inheritance:
We support rights inheritance in our ACL.
Basicly you can think of this easiest as a directory model.
Lets say you have a directory of c:\data and you have read, and create 
rights.
Inheritance would mean that you have both read and create rights to 
c:\data\subdir1
You can also have specified edit and delete rights to c:\data\subdir1 
thereby giving you all 4 rights
So when I do is first go to the top dir c:\data and get your rights, 
then get the rights to subdir1 and add them together using bit math.
This hold true for c:\data\subdir1\docs. First I will check c:\data, 
then c:\data\subdir1 then
c:\data\subdir1\docs and add up as I go.

Inherited Rights Mask (IRM):
IRMs take the action of removing rights or you can think of it as 
turning off switches.
Lets look at the example again: c:\data\subdir1\docs
At c:\data we have read and create.
At c:\data\subdir1 we have edit and delete
The effective rights of c:\data\subdir1 will be all four when we inherit 
from c:\data

Now lets say we dont want the user to have anything but read rights to
anything in and under c:\data\subdir1\docs
For this we will apply a mask for edit, delete and create. Basicly this 
amounts to turning off those
three switches at the point the mask is applied.
Lets look at it like this
c:\data turn on switches 1 and 4.
c:\data\subdir1 turn on switches 2 and 3
c:\data\subdir1\docs turn OFF switches 2, 3 and 4

Now anything under c:\data\subdir1\docs you only have switch 1 turned 
on, so the user only
has read access.
These IRMs are very important to understand in order to allow an admin 
to secure their environment.

Closing Points:
If you have any issues with understanding how this all works feel free 
to email me at address@hidden
It would also be useful to look at Novell Netware's security model, 
because our design closly follows theirs.