Homec4science
Diffusion invenio-infoscience (master) Browse

R3600/modules/webaccess/doc/hacking/firerole_api.html.wml
46b0eaf575femaster

Last Change
Raw File

firerole_api.html.wml
View Options

## $Id$
## This file is part of CDS Invenio.
## Copyright (C) 2002, 2003, 2004, 2005, 2006, 2007 CERN.
##
## CDS Invenio is free software; you can redistribute it and/or
## modify it under the terms of the GNU General Public License as
## published by the Free Software Foundation; either version 2 of the
## License, or (at your option) any later version.
##
## CDS Invenio is distributed in the hope that it will be useful, but
## WITHOUT ANY WARRANTY; without even the implied warranty of
## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
## General Public License for more details.
##
## You should have received a copy of the GNU General Public License
## along with CDS Invenio; if not, write to the Free Software Foundation, Inc.,
## 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA.
#include "cdspage.wml" \
title="FireRole Internals" \
navbar_name="hacking-webaccess" \
navtrail_previous_links="<a class=navtrail href=<WEBURL>/hacking/>Hacking CDS Invenio</a> &gt; <a class=navtrail href=<WEBURL>/hacking/webaccess/index.html>FireRole Internals</a> " \
navbar_select="hacking-FireRole-api"
<p>Version <: print generate_pretty_revision_date_string('$Id$'); :>
<pre>
The "Firewall like role definition engine" (FireRole) is a tool for describing
formally set of users and checking users against this description for membership.
FireRole rules are strings defined as in the <a href="../admin/firerole.html">FireRole language description</a> page.
In order to use FireRole rules with the engine you have to compile these strings with
the <strong>compile_role_definition</strong> function.
The compiled form could be serialized and stored into a database with the provided
function <strong>serialize</strong> and later loaded with <strong>deserialize</strong>.
To build a user description you have to use the <strong>collect_user_info</strong> in
the module <em>webuser</em>. This function, given a <em>mod_python request object</em>
or a <em>uid</em> returns a dictionary with all the collectable user informations (when
using the request objects these includes the <em>ip address</em> and the <em>host</em>
of the user, too).
Passing both the user_info dictionary and the compiled (deserialized) FireRole
definition to the <strong>acc_FireRole_check_user</strong> function returns a
<em>boolean value</em> stating if the user belong to the set described by this
definition.
FireRole definitions are integrated with <em>accROLEs</em>, in fact, you can pass
a uid, a req_object or user_info a dictionary to <strong>acc_authorize_action</strong>.
If necessary collect_user_info will be implicitly called, and user authorizations
will be checked first against direct traditional uid membership and then against
FireRole definitions.
<H2>API</H2>
<em>from webuser</em>
def <strong>collect_user_info</strong>(req):
"""Given the mod_python request object rec or a uid it returns a dictionary
containing at least the keys uid, nickname, email, groups, plus any external keys in
the user preferences (collected at login time and built by the different
external authentication plugins) and if the mod_python request object is
provided, also the remote_ip and remote_host fields.
"""
<em>from access_control_FireRole</em>
def <strong>compile_role_definition</strong>(FireRole_def_src):
""" Given a text in which every row contains a rule it returns the compiled
object definition.
Rules have the following syntax:
allow|deny [not] field {list of one or more (double)quoted string or regexp}
or allow|deny any
Every row may contain a # sign followed by a comment which are discarded.
Field could be any key contained in a user_info dictionary. If the key does
not exist in the dictionary, the rule is skipped.
The first rule which matches return.
"""
def <strong>serialize</strong>(FireRole_def_src):
""" Serialize and compress a definition."""
def <strong>deserialize</strong>(FireRole_def_ser):
""" Deserialize and decompress a definition."""
def <strong>acc_FireRole_check_user</strong>(user_info, FireRole_def_obj):
""" Given a user_info dictionary, it matches the rules inside the deserializez
compiled definition in order to discover if the current user match the roles
corresponding to this definition.
@param user_info a dict produced by collect_user_info which contains every
info about a user
@param definition a compiled deserialized definition produced by compile_role_defintion
@return True if the user match the definition, False otherwise.
"""
</pre>
c4science · Help