libmfacl

libmfacl is an access control list library implemented in PHP.

<?php

require('libmfacl.php');

mfacl_init('file://aclfile.acl') || die(mfacl_error()."\n");

if (mfacl_lookup($uid, $oid, $mode))
{
    echo 'access granted';
}
else
{
    echo 'access denied';
}

$uid is the numeric ID of the user requesting access, $oid is the numeric ID of the object being accessed and $mode is the mode(s) of access. $mode can contain multiple modes by ANDing the values together.

Drivers

There are three four storage drivers available. To use a particular driver you must specify it in the DSN passed to mfacl_init.

cdb

The cdb driver takes advantage of Dan Bernstien's cdb hasing algorithm for extremely fast lookups in a compiled flat-file format.

Before you can use this driver make sure PHP has been compiled with dba support or that the dba extensions in installed. cdb files are a compiled hash table, so preparing the plain text version of the file is necessary before compilation. This consists of creating ACL records in the cdb format:

+klen,dlen:key->data

In the case of an ACL record, this becomes:

+uidoidlen,modelen:uid:oid->mode

Let's break this up and explain each piece separately.

The first part of the record uidoidlen is the length of the uid and oid fields plus 1 (for the colon). This can be represented as

uidlen + oidlen + 1

The second part (modelen) is simply the length of the mode field. The third part (uid:oid) is the combination of the uid and oid fields to generate the unique key for the hash. The uid and oid fields are separated by a colon. And finally, the last part (mode) is simply the mode.

After preparing the plain text file, it must be compiled using the cdbmake utility.

cdbmake acl.cdb acl.tmp < acl.rules

acl.cdb is the name of the compiled file, acl.tmp is the temporary file where the compilation will occur and acl.rules is the plain tet file to use for the compilation.

Once you have a compiled file, you can reference it in the driver's DSN.

cdb://acl.db

Note that the cdb format does not support updates of the compiled csb file. Any changes must be performed on the plain text file and then compiled into a new cdb file.

file

The file driver provides the best out-of-the-box performance in respect to the number of lookups that it can perform per second. It's drawbacks are that use within web-applications is limited because allowing the application to write changes to the file is a security risk. If this is the case, the mysql driver is a good alternative;

Records are structured as follows:

uid:oid:mode

Each line can contain one record. Lines that begin with # and blank lines are ignored.

The uid, oid and mode fields must contain numeric values. If non-numeric values are encountered they will be type-casted to intergers which may result in unexpected results.

mem

The mem (memory) driver was initially intended for applications that required extremely fast lookups. Since the file driver has made many improvements that allow it to rival the speed of this driver with a much smaller memory footprint, this driver has been deprecated.

mysql

The mysql driver is probably the best choice for web-based applications that grant the ability to modify the ACL records to users. The results of this driver should be very satisfactory using a stock MySQL server setup, but ultimately the performance of the driver rests in the hands of the MySQL server administrator and their knowledge of the finer points of tuning the server.

The table structure for the MySQL driver is:

CREATE TABLE mfacl_records (
    uid int(4) unsigned,
    oid int(4) unsigned,
    mode int(1) unsigned
);

You can change the name of the table if you like, but remember to reference the new name in the DSN.

To use this driver with the mfacl library, specify the mysql driver name in the DSN:

mysql://user:passwd@host:port/database/table

If you don't specify port or table they will default to 3306 and mfacl_records respectively.