1Safe(3)               User Contributed Perl Documentation              Safe(3)
2
3
4

NAME

6       DBIx::Safe - Safer access to your database through a DBI database
7       handle
8

VERSION

10       This documents version 1.2.5 of the DBIx::Safe module
11

SYNOPSIS

13         use DBIx::Safe;
14
15         $dbh = DBI->connect($dbn, $user, $pass, {AutoCommit => 0});
16
17         my $safedbh = DBIx::Safe->new({ dbh => $dbh });
18
19         $safedbh->allow_command('SELECT INSERT UPDATE');
20
21         $safedbh->allow_regex(qr{LOCK TABLE \w+ IN EXCLUSIVE MODE});
22
23         $safedbh->deny_regex(qr{LOCK TABLE pg_});
24
25         $safedbh->allow_attribute('PrintError RaiseError');
26

DESCRIPTION

28       The purpose of this module is to give controlled, limited access to an
29       application, rather than simply passing it a raw database handle
30       through DBI. DBIx::Safe acts as a wrapper to the database, by only
31       allowing through the commands you tell it to. It filters all things
32       related to the database handle - methods and attributes.
33
34       The typical usage is for your application to create a database handle
35       via a normal DBI call to new(), then pass that to DBIx::Safe->new(),
36       which will return you a DBIx::Safe object. After specifying exactly
37       what is and what is not allowed, you can pass the object to the
38       untrusted application. The object will act very similar to a DBI
39       database handle, and in most cases can be used interchangeably.
40
41       By default, nothing is allowed to run at all. There are many things you
42       can control.  You can specify which SQL commands are allowed, by
43       indicating the first word in the SQL statement (e.g. 'SELECT'). You can
44       specify which database methods are allowed to run (e.g. 'ping'). You
45       can specify a regular expression that allows matching SQL statements to
46       run (e.g. 'qr{SET TIMEZONE}'). You can specify a regular expression
47       that is NOT allowed to run (e.g. qr(UPDATE xxx}). Finally, you can
48       indicate which database attributes are allowed to be read and changed
49       (e.g. 'PrintError'). For all of the above, there are matching methods
50       to remove them as well.
51
52   Deciding what statements to allow
53       Anytime a statement is sent to the server via the DBIx::Safe database
54       handle, it is first examined to see if it is allowed to run or not.
55       There are three major checks that occur when a statement is sent.
56       First, the initial word of the statement, known as the command, is
57       extracted. Next, the entire statement is checked against the list of
58       denied regular expressions.  Next, the command is checked against the
59       list of allowed commands. If there is no match, the statement is
60       checked against the list of allowed regular expressions.
61
62       Each DBD may implement additional or slightly different checks. For
63       example, if using Postgres, no semi-colons are allowed unless the
64       command is one of SELECT, INSERT, UPDATE, or DELETE, to prevent
65       multiple commands from running. (The four listed commands can be
66       checked in another way for multiple commands, so they are allowed to
67       have semicolons).
68
69   Deciding what attributes to allow
70       Database handle attributes are controlled by a single list of allowed
71       keys. If the key is allowed, the underlying database handle value is
72       returned or changed (or both).  Note that the attribute "AutoCommit" is
73       never allowed to be changed.
74
75   Methods
76       new()
77
78       Creates a new DBIx::Safe object. Requires a mandatory "dbh" argument
79       containing an active database handle. Optional arguments are
80       "allow_command", "allow_regex", "deny_regex", and "allow_attribute".
81
82       allow_command()
83
84       Specifies which commands are allowed to be used. Can be a whitespace-
85       separated list of words in a string, or an arrayref of such strings.
86       Returns the current list of allowed commands. Duplicate commands will
87       throw an error.
88
89       unallow_command()
90
91       Same as allow_command, but will remove words from the list.
92
93       allow_regex()
94
95       Specifies regular expressions which are allowed to run. Argument must
96       be a regular expression, or an arrayref of regular expressions. Returns
97       the current list.
98
99       unallow_regex()
100
101       Same as allow_regex, but will remove regexes from the list.
102
103       deny_regex()
104
105       Specifies regular expressions which are NOT allowed to run. Arguments
106       and return the same as allow_regex().
107
108       undeny regex()
109
110       Same as deny_regex, but will remove regexes from the list.
111
112       allow_attribute()
113
114       Specifies database handle attributes that are allowed to be changed. By
115       default, nothing can be read.  Argument is a whitespace-separated list
116       of words in a string, or an arrayref of such strings. Returns the
117       current list.
118
119       unallow_attribute()
120
121       Same as allow_attributes, but removes attributes from the list.
122
123   Testing
124       DBIx::Safe has a very comprehensive test suite, so please use it! The
125       only thing you should need is a database connection, by setting the
126       environment variables DBI_DSN and DBI_USER (and DBI_PASS if needed).
127
128       You can optionally run the module through Perl::Critic by setting the
129       TEST_AUTHOR environment variable.  You will need to have the modules
130       Perl::Critic and Test::Perl::Critic installed.
131
132       Please report any test failures to the author or
133       bucardo-general@bucardo.org.
134
135   Supported Databases
136       Due to the difficulty of ensuring safe access to the database, each
137       type of database must be specifically written into DBIx::Safe. Current
138       databases supported are: Postgres (DBD::Pg).
139

WEBSITE

141       The latest version and other information about DBIx::Safe can be found
142       at: http://bucardo.org/dbix_safe/
143

DEVELOPMENT

145       The latest development version can be checked out by using git:
146
147         git clone http://bucardo.org/dbixsafe.git/
148

BUGS

150       Bugs should be reported to the author or bucardo-general@bucardo.org.
151

AUTHOR

153       Greg Sabino Mullane <greg@endpoint.com>
154
156       Copyright 2006-2007 Greg Sabino Mullane <greg@endpoint.com>.
157
158       This software is free to use: see the LICENSE file for details.
159
160
161
162perl v5.12.0                      2007-10-15                           Safe(3)
Impressum