Safe(3) User Contributed Perl Documentation Safe(3)NAMEDBIx::Safe - Safer access to your database through a DBI database
handle
VERSION
This documents version 1.2.5 of the DBIx::Safe module
SYNOPSIS
use DBIx::Safe;
$dbh = DBI->connect($dbn, $user, $pass, {AutoCommit => 0});
my $safedbh = DBIx::Safe->new({ dbh => $dbh });
$safedbh->allow_command('SELECT INSERT UPDATE');
$safedbh->allow_regex(qr{LOCK TABLE \w+ IN EXCLUSIVE MODE});
$safedbh->deny_regex(qr{LOCK TABLE pg_});
$safedbh->allow_attribute('PrintError RaiseError');
DESCRIPTION
The purpose of this module is to give controlled, limited access to an
application, rather than simply passing it a raw database handle
through DBI. DBIx::Safe acts as a wrapper to the database, by only
allowing through the commands you tell it to. It filters all things
related to the database handle - methods and attributes.
The typical usage is for your application to create a database handle
via a normal DBI call to new(), then pass that to DBIx::Safe->new(),
which will return you a DBIx::Safe object. After specifying exactly
what is and what is not allowed, you can pass the object to the
untrusted application. The object will act very similar to a DBI
database handle, and in most cases can be used interchangeably.
By default, nothing is allowed to run at all. There are many things you
can control. You can specify which SQL commands are allowed, by
indicating the first word in the SQL statement (e.g. 'SELECT'). You can
specify which database methods are allowed to run (e.g. 'ping'). You
can specify a regular expression that allows matching SQL statements to
run (e.g. 'qr{SET TIMEZONE}'). You can specify a regular expression
that is NOT allowed to run (e.g. qr(UPDATE xxx}). Finally, you can
indicate which database attributes are allowed to be read and changed
(e.g. 'PrintError'). For all of the above, there are matching methods
to remove them as well.
Deciding what statements to allow
Anytime a statement is sent to the server via the DBIx::Safe database
handle, it is first examined to see if it is allowed to run or not.
There are three major checks that occur when a statement is sent.
First, the initial word of the statement, known as the command, is
extracted. Next, the entire statement is checked against the list of
denied regular expressions. Next, the command is checked against the
list of allowed commands. If there is no match, the statement is
checked against the list of allowed regular expressions.
Each DBD may implement additional or slightly different checks. For
example, if using Postgres, no semi-colons are allowed unless the
command is one of SELECT, INSERT, UPDATE, or DELETE, to prevent
multiple commands from running. (The four listed commands can be
checked in another way for multiple commands, so they are allowed to
have semicolons).
Deciding what attributes to allow
Database handle attributes are controlled by a single list of allowed
keys. If the key is allowed, the underlying database handle value is
returned or changed (or both). Note that the attribute "AutoCommit" is
never allowed to be changed.
Methods
new()
Creates a new DBIx::Safe object. Requires a mandatory "dbh" argument
containing an active database handle. Optional arguments are
"allow_command", "allow_regex", "deny_regex", and "allow_attribute".
allow_command()
Specifies which commands are allowed to be used. Can be a whitespace-
separated list of words in a string, or an arrayref of such strings.
Returns the current list of allowed commands. Duplicate commands will
throw an error.
unallow_command()
Same as allow_command, but will remove words from the list.
allow_regex()
Specifies regular expressions which are allowed to run. Argument must
be a regular expression, or an arrayref of regular expressions. Returns
the current list.
unallow_regex()
Same as allow_regex, but will remove regexes from the list.
deny_regex()
Specifies regular expressions which are NOT allowed to run. Arguments
and return the same as allow_regex().
undeny regex()
Same as deny_regex, but will remove regexes from the list.
allow_attribute()
Specifies database handle attributes that are allowed to be changed. By
default, nothing can be read. Argument is a whitespace-separated list
of words in a string, or an arrayref of such strings. Returns the
current list.
unallow_attribute()
Same as allow_attributes, but removes attributes from the list.
Testing
DBIx::Safe has a very comprehensive test suite, so please use it! The
only thing you should need is a database connection, by setting the
environment variables DBI_DSN and DBI_USER (and DBI_PASS if needed).
You can optionally run the module through Perl::Critic by setting the
TEST_AUTHOR environment variable. You will need to have the modules
Perl::Critic and Test::Perl::Critic installed.
Please report any test failures to the author or
bucardo-general@bucardo.org.
Supported Databases
Due to the difficulty of ensuring safe access to the database, each
type of database must be specifically written into DBIx::Safe. Current
databases supported are: Postgres (DBD::Pg).
WEBSITE
The latest version and other information about DBIx::Safe can be found
at: http://bucardo.org/dbix_safe/
DEVELOPMENT
The latest development version can be checked out by using git:
git clone http://bucardo.org/dbixsafe.git/
BUGS
Bugs should be reported to the author or bucardo-general@bucardo.org.
AUTHOR
Greg Sabino Mullane <greg@endpoint.com>
LICENSE AND COPYRIGHT
Copyright 2006-2007 Greg Sabino Mullane <greg@endpoint.com>.
This software is free to use: see the LICENSE file for details.
perl v5.14.1 2007-10-15 Safe(3)
