veil_mainpage.c

00001 /* ----------
00002  * veil_mainpage.c.in
00003  *
00004  *      Autoconf input file for veil_mainpage.c
00005  *
00006  *      Copyright (c) 2005, 2006 Marc Munro
00007  *      Author:  Marc Munro
00008  *  License: BSD
00009  *
00010  * $Id: veil_mainpage.c.in,v 1.9 2008/02/06 15:04:52 bloodnok Exp $
00011  * ----------
00012  */
00013 
00014 
00015 /*! \mainpage Veil
00016 \version 0.9.6 (Alpha)
00017 \section license License
00018 BSD
00019 \section intro_sec Introduction
00020 
00021 Veil is a data security add-on for Postgres.  It provides an API
00022 allowing you to control access to data at the row, or even column,
00023 level.  Different users will be able to run the same query and see
00024 different results.  Other database vendors describe this as a Virtual
00025 Private Database.
00026 
00027 \section Why Why do I need this?
00028 If you have a database-backed application that stores sensitive data,
00029 you will be taking at least some steps to protect that data.  Veil
00030 provides a way of protecting your data with a security mechanism
00031 within the database itself.  No matter how you access the database,
00032 whether you are a legitimate user or not, you cannot by-pass Veil
00033 without superuser privileges. 
00034 
00035 \subsection Advantages The Veil Advantage
00036 By placing security mechanisms within the database itself we get a
00037 number of advantages:
00038 - Ubiquity.  Security is always present, no matter what application or
00039 tool is used to connect to the database.  If your application is
00040 compromised, your data is still protected by Veil.  If an intruder gets
00041 past your outer defences and gains access to psql, your data is still
00042 protected.
00043 - Single Security Policy and Implementation.  If you have N applications
00044 to secure, you have to implement your security policy N times.  With
00045 Veil, all applications may be protected by a single implementation.
00046 - Strength in Depth.  For the truly security conscious, Veil provides
00047 yet another level of security.  If you want strength in depth, with
00048 layers and layers of security like an onion, Veil gives you that extra
00049 layer.
00050 - Performance.  Veil is designed to be both flexible and efficient.
00051 With a good implementation it is possible to build access controls with
00052 a very low overhead, typically much lower than building the equivalent
00053 security in each application.
00054 - Cooperation.  The Veil security model is designed to cooperate with your
00055 applications.  Although Veil is primarily concerned with data access
00056 controls, it can also be used to provide function-level privileges.  If
00057 your application has a sensitive function X, it can query the database,
00058 through Veil functions, to ask the question, "Does the current user have
00059 execute_X privilege?".  Also, that privilege can be managed in exactly
00060 the same way as any other privilege.
00061 - Flexibility.  Veil is a set of tools rather than a product.  How you
00062 use it is up to you.
00063 
00064 \section the-rest Veil Documentation
00065 - \subpage overview-page
00066 - \subpage API-page
00067 - \subpage Building
00068 - \subpage Demo 
00069 - \subpage Management
00070 - \subpage Esoteria
00071 - \subpage install
00072 - \subpage History
00073 - \subpage Feedback
00074 - \subpage Performance
00075 - \subpage Credits
00076 
00077 Next: \ref overview-page
00078 
00079 */
00080 /*! \page overview-page Overview: a quick introduction to Veil
00081 
00082 \section Overview-section Introduction
00083 The section introduces a number of key concepts, and shows the basic
00084 components of a Veil-protected system:
00085 - \ref over-views
00086 - \ref over-connections
00087 - \ref over-privs
00088 - \ref over-contexts
00089 - \ref over-funcs2
00090 - \ref over-roles
00091 
00092 \subsection over-views Secured Views and Access Functions
00093 Access controls are implemented using secured views and instead-of triggers.
00094 Users connect to an account that has access only to the secured views.
00095 For a table defined thus:
00096 \verbatim
00097 create table persons (
00098     person_id       integer not null,
00099     person_name     varchar(80) not null
00100 );
00101 \endverbatim
00102 The secured view would be defined something like this:
00103 \verbatim
00104 create view persons(
00105        person_id,
00106        person_name) as
00107 select person_id,
00108        person_name
00109 from   persons
00110 where  i_have_personal_priv(10013, person_id);
00111 \endverbatim
00112 
00113 A query performed on the view will return rows only for those persons
00114 where the current user has privilege 10013
00115 (<code>SELECT_PERSONS</code>).  We call the function
00116 <code>i_have_personal_priv()</code>, an access function.  Such
00117 functions are user-defined, and are used to determine whether the
00118 connected user has a specific privilege in any of a number of security
00119 contexts (see \ref over-contexts).  The example above is
00120 taken from the Veil demo application (\ref demo-sec) and 
00121 checks for privilege in the global and personal contexts.
00122 
00123 \subsection over-connections The Connected User and Connection Functions
00124 To determine a user's privileges, we have to know who that user is.
00125 At the start of each database session the user must be identified, and
00126 their privileges must be determined.  This is done by calling a
00127 connection function, eg:
00128 \verbatim
00129 select connect_person('Wilma', 'AuthenticationTokenForWilma');
00130 \endverbatim
00131 The connection function performs authentication, and stores the user's
00132 access privileges in Veil state variables.  These variables are then
00133 interrogated by the access functions used in the secured views.
00134 
00135 Prior to connection, or in the event of the connection failing, the
00136 session will have no privileges and will probably be unable to see any
00137 data.  Like access functions, connection functions are user-defined and 
00138 may be written in any language supported by PostgreSQL.
00139 
00140 \subsection over-privs Privileges
00141 Veil-based systems define access rights in terms of privileges.  A
00142 privilege is a named thing with a numerical value (actually, the name
00143 is kind of optional).
00144 
00145 An example will probably help.  Here is a definition of a privileges
00146 table and a subset of its data:
00147 \verbatim
00148 create table privileges (
00149     privilege_id    integer not null,
00150     privilege_name  varchar(80) not null
00151 );
00152 
00153 copy privileges (privilege_id, privilege_name) from stdin;
00154 10001   select_privileges
00155 10002   insert_privileges
00156 10003   update_privileges
00157 10004   delete_privileges
00158 . . .
00159 10013   select_persons
00160 10014   insert_persons
00161 10015   update_persons
00162 10016   delete_persons
00163 10017   select_projects
00164 10018   insert_projects
00165 10019   update_projects
00166 10020   delete_projects
00167 . . .
00168 10100   can_connect
00169 \.
00170 
00171 \endverbatim
00172 Each privilege describes something that a user can do.  It is up to the
00173 access and connection functions to make use of these privileges; the
00174 name of the privilege is only a clue to its intended usage.  In the
00175 example we might expect that a user that has not been given the
00176 <code>can_connect</code> privilege would not be able to authenticate
00177 using a connection function but this is entirely dependent on the
00178 implementation.
00179 
00180 \subsection over-contexts Security Contexts 
00181 
00182 Users may be assigned privileges in a number of different ways.  They
00183 may be assigned directly, indirectly through various relationships, or
00184 may be inferred by some means.  To aid in the discussion and design of a
00185 Veil-based security model we introduce the concept of security
00186 contexts, and we say that a user has a given set of privileges in a
00187 given context.  There are three types of security context:
00188 
00189  - Global Context.  This refers to privileges that a user has been given
00190    globally.  If a user has <code>select_persons</code> privilege in the
00191    global context, they will be able to select every record in the
00192    persons table.  Privileges in global context are exactly like
00193    database-level privileges: there is no row-level element to them.
00194 
00195  - Personal Context.  This context provides privileges on data that you
00196    may be said to own.  If you have <code>select_persons</code>
00197    privilege in only the personal context, you will only be able to
00198    select your own persons record.  Assignment of privileges in the
00199    personal context is often defined implicitly or globally, for all
00200    users, rather than granted explicitly to each user.  It is likely
00201    that everyone should have the same level of access to their own data
00202    so it makes little sense to have to explicitly assign the privileges
00203    for each individual user.
00204 
00205  - Relational Contexts.  These are the key to most row-level access
00206    controls.  Privileges assigned in a relational context are assigned
00207    through relationships between the connected user and the data to be
00208    accessed.  Examples of relational contexts include: assignments to
00209    projects, in which a user will gain access to project data only if
00210    they have been assigned to the project; and the management hierarchy
00211    within a business, in which a manager may have specific access to
00212    data about a staff member.  Note that determining a user's access
00213    rights in a relational context may require extra queries to be
00214    performed for each function call.  Your design should aim to minimise
00215    this.  Some applications may require a number of distinct relational 
00216    contexts.
00217 
00218 \subsection over-funcs2 Access Functions and Security Contexts
00219 Each access function will operate on privileges for a specific set of
00220 contexts.  For some tables, access will only be through global context.
00221 For others, it may be through global and personal as well as a number of
00222 different relational contexts.  Here, from the demo application, are a
00223 number of view definitions, each using a different access function, that
00224 checks different contexts.
00225 \verbatim
00226 create view privileges(
00227        privilege_id,
00228        privilege_name) as
00229 select privilege_id,
00230        privilege_name
00231 from   privileges
00232 where  i_have_global_priv(10001);
00233 
00234 . . .
00235 
00236 create view persons(
00237        person_id,
00238        person_name) as
00239 select person_id,
00240        person_name
00241 from   persons
00242 where  i_have_personal_priv(10013, person_id);
00243 
00244 . . .
00245 
00246 create view projects(
00247        project_id,
00248        project_name) as
00249 select project_id,
00250        project_name
00251 from   projects
00252 where  i_have_project_priv(10017, project_id);
00253 
00254 . . .
00255 
00256 create view assignments (
00257        project_id,
00258        person_id,
00259        role_id) as
00260 select project_id,
00261        person_id,
00262        role_id
00263 from   assignments
00264 where  i_have_proj_or_pers_priv(10025, project_id, person_id);
00265 \endverbatim
00266 
00267 In the <code>privileges</code> view, we only check for privilege in the
00268 global context.  This is a look-up view, and should be visible to all
00269 authenticated users.
00270 
00271 The <code>persons</code> view checks for privilege in both the global
00272 and personal contexts.  It takes an extra parameter identifying the
00273 person who owns the record.  If that person is the same as the connected
00274 user, then privileges in the personal context may be checked.  If not,
00275 only the global context applies.
00276 
00277 The <code>projects</code> view checks global and project contexts.  The
00278 project context is a relational context.  In the demo application, a
00279 user gains privileges in the project context through assignments.  An
00280 assignment is a relationship between a person and a project.  Each 
00281 assignment record has a role.  This role describes the set of privileges
00282 the assignee (person) has within the project context.
00283 
00284 The <code>assignments</code> view checks all three contexts (global,
00285 personal and project).  An assignment contains data about a person and a
00286 project so privileges may be acquired in either of the relational
00287 contexts, or globally.
00288 
00289 \subsection over-roles Grouping Privileges by Roles
00290 Privileges operate at a very low-level.  In a database of 100 tables,
00291 there are likely to be 500 to 1,000 privileges in use.  Managing
00292 users access at the privilege level is, at best, tedious.  Instead, we
00293 tend to group privileges into roles, and assign only roles to individual
00294 users.  Roles act as function-level collections of privileges.  For
00295 example, the role <code>project-readonly</code> might contain all of the
00296 <code>select_xxx</code> privileges required to read all project data.
00297 
00298 A further refinement allows roles to be collections of sub-roles.
00299 Defining suitable roles for a system is left as an exercise for the
00300 reader.
00301 
00302 Next: \ref API-page
00303 
00304 */
00305 /*! \page API-page The Veil API
00306 \section API-sec The Veil API
00307 This section describes the Veil API.  It consists of the following
00308 sections
00309 
00310 - \ref API-intro
00311 - \subpage API-variables
00312 - \subpage API-simple
00313 - \subpage API-bitmaps
00314 - \subpage API-bitmap-arrays
00315 - \subpage API-bitmap-hashes
00316 - \subpage API-int-arrays
00317 - \subpage API-control
00318 
00319 \section API-intro Veil API Overview
00320 Veil is an API that simply provides a set of state variable types, and 
00321 operations on those variable types, which are optimised for privilege
00322 examination and manipulation.
00323 
00324 The fundamental data type is the bitmap.  Bitmaps are used to
00325 efficiently record and test sets of privileges.  Bitmaps may be combined
00326 into bitmap arrays, which are contiguous groups of bitmaps indexed by
00327 integer, and bitmap hashes which are non-contiguous and may be indexed
00328 by text strings.
00329 
00330 In addition to the bitmap-based types, there are a small number of
00331 support types that just help things along.  If you think you have a case
00332 for defining a new type, please 
00333 \ref Feedback "contact" 
00334 the author.
00335 
00336 Next: \ref API-variables
00337 */
00338 /*! \page API-variables Variables
00339 Veil variables exist to record session and system state.  They retain
00340 their values across transactions.  Variables may be defined as either
00341 session variables or shared variables.
00342 
00343 All variables are referenced by name; the name of the variable is
00344 passed as a text string to Veil functions.
00345 
00346 Session variables are private to the connected session.  They are
00347 created when first referenced and, once defined, their type is set for
00348 the life of the session.
00349 
00350 Shared variables are global across all sessions.  Once a shared variable
00351 is defined, all sessions will have access to it.  Shared variables are
00352 defined in two steps.  First, the variable is defined as shared, and
00353 then it is initialised and accessed in the same way as for session
00354 variables.  Note that shared variables should only be modified within
00355 the function veil_init().
00356 
00357 Note that bitmap refs and bitmap hashes may not be stored in shared
00358 variables.
00359 
00360 The following types of variable are supported by Veil, and are described
00361 in subsequent sections:
00362 - integers 
00363 - ranges
00364 - bitmaps
00365 - bitmap refs
00366 - bitmap arrays
00367 - bitmap hashes
00368 - integer arrays
00369 
00370 The following functions comprise the Veil variables API:
00371 
00372 - <code>\ref API-variables-share</code>
00373 - <code>\ref API-variables-var</code>
00374 
00375 Note again that session variables are created on usage.  Their is no
00376 specific function for creating a variable in the variables API.  For an
00377 example of a function to create a variable see \ref API-bitmap-init.
00378 
00379 \section API-variables-share veil_share(text)
00380 \code
00381 function veil_share(text) returns bool
00382 \endcode
00383 
00384 This is used to define a specific variable as being shared.  A shared
00385 variable is accessible to all sessions and exists to reduce the need for
00386 multiple copies of identical data.  For instance in the Veil demo,
00387 role_privileges are recorded in a shared variable as they will be
00388 identical for all sessions, and to create a copy for each session  would
00389 be an unnecessary overhead.  This function should only be called from
00390 veil_init().
00391 
00392 \section API-variables-var veil_variables()
00393 \code
00394 function veil_variables() returns setof veil_variable_t
00395 \endcode
00396 
00397 This function returns a description for each variable known to the
00398 session.  It provides the name, the type, and whether the variable is
00399 shared.  It is primarily intended for interactive use when developing
00400 and debugging Veil-based systems.
00401 
00402 Next: \ref API-simple
00403 */
00404 /*! \page API-simple Basic Types: Integers and Ranges
00405 
00406 Veil's basic types are those that do not contain repeating groups
00407 (arrays, hashes, etc).  
00408 
00409 Ranges consist of a pair of values and are generally used to initialise
00410 the bounds of array and bitmap types.  Ranges may not contain nulls.
00411 
00412 The int4 type is used to record a simple nullable integer.  This is
00413 typically used to record the id of the connected user in a session.
00414 
00415 The following functions comprise the Veil basic types API:
00416 
00417 - <code>\ref API-basic-init-range</code>
00418 - <code>\ref API-basic-range</code>
00419 - <code>\ref API-basic-int4-set</code>
00420 - <code>\ref API-basic-int4-get</code>
00421 
00422 \section API-basic-init-range veil_init_range(text, int4, int4)
00423 \code
00424 function veil_init_range(text, int4, int4) returns int4
00425 \endcode
00426 
00427 This defines a range, and returns the extent of that range.
00428 
00429 \section API-basic-range veil_range(text)
00430 \code
00431 function veil_range(text) returns veil_range_t
00432 \endcode
00433 
00434 This returns the contents of a range.  It is intended primarily for
00435 interactive use.
00436 
00437 \section API-basic-int4-set veil_int4_set(text, int4)
00438 \code
00439 function veil_int4_set(text, int4) returns int4
00440 \endcode
00441 
00442 Sets an int4 variable to a value, returning that same value.
00443 
00444 \section API-basic-int4-get veil_int4_get(text)
00445 \code
00446 function veil_int4_get(text) returns int4
00447 \endcode
00448 
00449 Returns the value of an int4 variable.
00450 
00451 
00452 Next: \ref API-bitmaps
00453 */
00454 /*! \page API-bitmaps Bitmaps and Bitmap Refs
00455 Bitmaps are used to implement bounded sets.  Each bit in the bitmap may
00456 be on or off representing presence or absence of a value in the set.
00457 Typically bitmaps are used to record sets of privileges.
00458 
00459 A bitmap ref is a variable that may temporarily reference another
00460 bitmap.  These are useful for manipulating specific bitmaps within
00461 bitmap arrays or bitmap hashes.  All bitmap operations except for \ref
00462 API-bitmap-init may take the name of a bitmap ref instead of a bitmap.
00463 
00464 Bitmap refs may not be shared, and the reference is only accessible
00465 within the transaction that created it.  These restrictions exist to
00466 eliminate the possibility of references to deleted objects or to objects
00467 from other sessions.
00468 
00469 The following functions comprise the Veil bitmaps API:
00470 
00471 - <code>\ref API-bitmap-init</code>
00472 - <code>\ref API-bitmap-clear</code>
00473 - <code>\ref API-bitmap-setbit</code>
00474 - <code>\ref API-bitmap-clearbit</code>
00475 - <code>\ref API-bitmap-testbit</code>
00476 - <code>\ref API-bitmap-union</code>
00477 - <code>\ref API-bitmap-intersect</code>
00478 - <code>\ref API-bitmap-bits</code>
00479 - <code>\ref API-bitmap-range</code>
00480 
00481 \section API-bitmap-init veil_init_bitmap(text, text)
00482 \code
00483 function veil_init_bitmap(text, text) returns bool
00484 \endcode
00485 This is used to create or resize a bitmap.  The first parameter provides
00486 the name of the bitmap, the second is the name of a range variable that
00487 will govern the size of the bitmap.
00488 
00489 \section API-bitmap-clear veil_clear_bitmap(text)
00490 \code
00491 function veil_clear_bitmap(text) returns bool
00492 \endcode
00493 This is used to reset all bits in the bitmap.
00494 
00495 \section API-bitmap-setbit veil_bitmap_setbit(text, int4)
00496 \code
00497 function veil_bitmap_setbit(text, int4) returns bool
00498 \endcode
00499 This is used to set a specified bit in a bitmap.
00500 
00501 \section API-bitmap-clearbit veil_bitmap_clearbit(text, int4)
00502 \code
00503 function veil_bitmap_clearbit(text, int4) returns bool
00504 \endcode
00505 This is used to set a specified bit in a bitmap.
00506 
00507 \section API-bitmap-testbit veil_bitmap_testbit(text, int4)
00508 \code
00509 function veil_bitmap_testbit(text, int4) returns bool
00510 \endcode
00511 This is used to test a specified bit in a bitmap.  It returns true if
00512 the bit is set, false otherwise.
00513 
00514 \section API-bitmap-union veil_bitmap_union(text, int4)
00515 \code
00516 function veil_bitmap_union(text, text) returns bool
00517 \endcode
00518 Form the union of two bitmaps with the result going into the first.
00519 
00520 \section API-bitmap-intersect veil_bitmap_intersect(text, int4)
00521 \code
00522 function veil_bitmap_intersect(text, text) returns bool
00523 \endcode
00524 Form the intersection of two bitmaps with the result going into the first.
00525 
00526 \section API-bitmap-bits veil_bitmap_bits(text)
00527 \code
00528 function veil_bitmap_bits(text) returns setof int4
00529 \endcode
00530 This is used to list all bits set within a bitmap.  It is primarily for
00531 interactive use during development and debugging of Veil-based systems.
00532 
00533 \section API-bitmap-range veil_bitmap_range(text)
00534 \code
00535 function veil_bitmap_range(text) returns veil_range_t
00536 \endcode
00537 This returns the range of a bitmap.  It is primarily intended for
00538 interactive use.
00539 
00540 Next: \ref API-bitmap-arrays
00541 */
00542 /*! \page API-bitmap-arrays Bitmap Arrays
00543 A bitmap array is an array of identically-ranged bitmaps, indexed
00544 by an integer value.  They are initialised using two ranges, one for the
00545 range of each bitmap, and one providing the range of indices for the
00546 array.
00547 
00548 Typically bitmap arrays are used for collections of privileges, where
00549 each element of the collection is indexed by something like a role_id.
00550 
00551 The following functions comprise the Veil bitmap arrays API:
00552 
00553 - <code>\ref API-bmarray-init</code>
00554 - <code>\ref API-bmarray-clear</code>
00555 - <code>\ref API-bmarray-bmap</code>
00556 - <code>\ref API-bmarray-testbit</code>
00557 - <code>\ref API-bmarray-setbit</code>
00558 - <code>\ref API-bmarray-clearbit</code>
00559 - <code>\ref API-bmarray-union</code>
00560 - <code>\ref API-bmarray-intersect</code>
00561 - <code>\ref API-bmarray-bits</code>
00562 - <code>\ref API-bmarray-arange</code>
00563 - <code>\ref API-bmarray-brange</code>
00564 
00565 \section API-bmarray-init veil_init_bitmap_array(text, text, text)
00566 \code
00567 function veil_init_bitmap_array(text, text, text) returns bool
00568 \endcode
00569 Creates, or resets the ranges of, a bitmap array.
00570 
00571 \section API-bmarray-clear veil_clear_bitmap_array(text)
00572 \code
00573 function veil_clear_bitmap_array(text) returns bool
00574 \endcode
00575 Clear all bits in a bitmap array
00576 
00577 \section API-bmarray-bmap veil_bitmap_from_array(text, text, int4)
00578 \code
00579 function veil_bitmap_from_array(text, text, int4) returns text
00580 \endcode
00581 Generate a reference to a specific bitmap in a bitmap array
00582 
00583 \section API-bmarray-testbit veil_bitmap_array_testbit(text, int4, int4)
00584 \code
00585 function veil_bitmap_array_testbit(text, int4, int4) returns bool
00586 \endcode
00587 Test a specific bit in a bitmap array.
00588 
00589 \section API-bmarray-setbit veil_bitmap_array_setbit(text, int4, int4)
00590 \code
00591 function veil_bitmap_array_setbit(text, int4, int4) returns bool
00592 \endcode
00593 Set a specific bit in a bitmap array.
00594 
00595 \section API-bmarray-clearbit veil_bitmap_array_clearbit(text, int4, int4)
00596 \code
00597 function veil_bitmap_array_clearbit(text, int4, int4) returns bool
00598 \endcode
00599 Clear a specific bit in a bitmap array.
00600 
00601 \section API-bmarray-union veil_union_from_bitmap_array(text, text, int4)
00602 \code
00603 function veil_union_from_bitmap_array(text, text, int4) returns bool
00604 \endcode
00605 Union a bitmap with a specified bitmap from an array, with the result in
00606 the bitmap.  This is a faster shortcut for:
00607 
00608 <code>
00609 veil_bitmap_union(&lt;bitmap>, veil_bitmap_from_array(&lt;bitmap_array>, &lt;index>))
00610 </code>.
00611 
00612 \section API-bmarray-intersect veil_intersect_from_bitmap_array(text, text, int4)
00613 \code
00614 function veil_intersect_from_bitmap_array(text, text, int4) returns bool
00615 \endcode
00616 Intersect a bitmap with a specified bitmap from an array, with the result in
00617 the bitmap.  This is a faster shortcut for:
00618 
00619 <code>
00620 veil_bitmap_intersect(&lt;bitmap>, veil_bitmap_from_array(&lt;bitmap_array>, &lt;index>))
00621 </code>.
00622 
00623 \section API-bmarray-bits veil_bitmap_array_bits(text, int4)
00624 \code
00625 function veil_bitmap_array_bits(text, int4) returns setof int4
00626 \endcode
00627 Show all bits in the specific bitmap within an array.  This is primarily
00628 intended for interactive use when developing and debugging Veil-based
00629 systems.
00630 
00631 \section API-bmarray-arange veil_bitmap_array_arange(text)
00632 \code
00633 function veil_bitmap_array_arange(text) returns veil_range_t
00634 \endcode
00635 Show the range of array indices for the specified bitmap array.
00636 Primarily for interactive use.
00637 
00638 \section API-bmarray-brange veil_bitmap_array_brange(text)
00639 \code
00640 function veil_bitmap_array_brange(text) returns veil_range_t
00641 \endcode
00642 Show the range of all bitmaps in the specified bitmap array.
00643 Primarily for interactive use.
00644 
00645 
00646 Next: \ref API-bitmap-hashes
00647 */
00648 /*! \page API-bitmap-hashes Bitmap Hashes
00649 A bitmap hashes is a hash table of identically-ranged bitmaps, indexed
00650 by a text key.
00651 
00652 Typically bitmap hashes are used for sparse collections of privileges.
00653 
00654 Note that bitmap hashes may not be stored in shared variables as hashes
00655 in shared memory are insufficiently dynamic.
00656 
00657 The following functions comprise the Veil bitmap hashes API:
00658 
00659 - <code>\ref API-bmhash-init</code>
00660 - <code>\ref API-bmhash-clear</code>
00661 - <code>\ref API-bmhash-from</code>
00662 - <code>\ref API-bmhash-testbit</code>
00663 - <code>\ref API-bmhash-setbit</code>
00664 - <code>\ref API-bmhash-clearbit</code>
00665 - <code>\ref API-bmhash-union-into</code>
00666 - <code>\ref API-bmhash-union-from</code>
00667 - <code>\ref API-bmhash-intersect-from</code>
00668 - <code>\ref API-bmhash-bits</code>
00669 - <code>\ref API-bmhash-range</code>
00670 - <code>\ref API-bmhash-entries</code>
00671 
00672 \section API-bmhash-init veil_init_bitmap_hash(text, text)
00673 \code
00674 function veil_init_bitmap_hash(text, text) returns bool
00675 \endcode
00676 Creates, or resets the ranges of, a bitmap hash.
00677 
00678 \section API-bmhash-clear veil_clear_bitmap_hash(text)
00679 \code
00680 function veil_clear_bitmap_hash(text) returns bool
00681 \endcode
00682 Clear all bits in a bitmap hash.
00683 
00684 \section API-bmhash-from veil_bitmap_from_hash(text, text, text)
00685 \code
00686 function veil_bitmap_from_hash(text, text, text) returns text
00687 \endcode
00688 Generate a reference to a specific bitmap in a bitmap hash.
00689 
00690 \section API-bmhash-testbit veil_bitmap_hash_testbit(text, text, int4)
00691 \code
00692 function veil_bitmap_hash_testbit(text, text, int4) returns bool
00693 \endcode
00694 Test a specific bit in a bitmap hash.
00695 
00696 \section API-bmhash-setbit veil_bitmap_hash_setbit(text, text, int4)
00697 \code
00698 function veil_bitmap_hash_setbit(text, text, int4) returns bool
00699 \endcode
00700 Set a specific bit in a bitmap hash.
00701 
00702 \section API-bmhash-clearbit veil_bitmap_hash_clearbit(text, text, int4)
00703 \code
00704 function veil_bitmap_hash_clearbit(text, text, int4) returns bool
00705 \endcode
00706 Clear a specific bit in a bitmap hash.
00707 
00708 \section API-bmhash-union-into veil_union_into_bitmap_hash(text, text, text)
00709 \code
00710 function veil_union_into_bitmap_hash(text, text, text) returns bool
00711 \endcode
00712 Union a specified bitmap from a hash with a bitmap, with the result in
00713 the bitmap hash.  This is a faster shortcut for:
00714 
00715 <code>
00716 veil_bitmap_union(veil_bitmap_from_hash(&lt;bitmap_hash>, &lt;key>), &lt;bitmap>)
00717 </code>.
00718 
00719 \section API-bmhash-union-from veil_union_from_bitmap_hash(text, text, text)
00720 \code
00721 function veil_union_from_bitmap_hash(text, text, text) returns bool
00722 \endcode
00723 Union a bitmap with a specified bitmap from a hash, with the result in
00724 the bitmap.  This is a faster shortcut for:
00725 
00726 <code>
00727 veil_bitmap_union(&lt;bitmap>, veil_bitmap_from_hash(&lt;bitmap_array>, &lt;key>))
00728 </code>.
00729 
00730 \section API-bmhash-intersect-from veil_intersect_from_bitmap_hash(text, text, text)
00731 \code
00732 function veil_intersect_from_bitmap_hash(text, text, text) returns bool
00733 \endcode
00734 Intersect a bitmap with a specified bitmap from a hash, with the result in
00735 the bitmap.  This is a faster shortcut for:
00736 
00737 <code>
00738 veil_bitmap_intersect(&lt;bitmap>, veil_bitmap_from_hash(&lt;bitmap_array>, &lt;key>))
00739 </code>.
00740 
00741 \section API-bmhash-bits veil_bitmap_hash_bits(text, text)
00742 \code
00743 function veil_bitmap_hash_bits(text, text) returns setof int4
00744 \endcode
00745 Show all bits in the specific bitmap within a hash.  This is primarily
00746 intended for interactive use when developing and debugging Veil-based
00747 systems.
00748 
00749 \section API-bmhash-range veil_bitmap_hash_range(text)
00750 \code
00751 function veil_bitmap_hash_range(text) returns veil_range_t
00752 \endcode
00753 Show the range of all bitmaps in the hash.  Primarily intended for
00754 interactive use. 
00755 
00756 \section API-bmhash-entries veil_bitmap_hash_entries(text)
00757 \code
00758 function veil_bitmap_hash_entries(text) returns setof text
00759 \endcode
00760 Show every key in the hash.  Primarily intended for interactive use.
00761 
00762 Next: \ref API-int-arrays
00763 */
00764 /*! \page API-int-arrays Integer Arrays
00765 Integer arrays are used to store simple mappings of keys to values.  In
00766 the Veil demo (\ref demo-sec) they are used to record the extra privilege
00767 required to access person_details and project_details of each
00768 detail_type: the integer array being used to map the detail_type_id to
00769 the privilege_id.
00770 
00771 Note that integer array elements cannot be null.
00772 
00773 The following functions comprise the Veil int arrays API:
00774 
00775 - <code>\ref API-intarray-init</code>
00776 - <code>\ref API-intarray-clear</code>
00777 - <code>\ref API-intarray-set</code>
00778 - <code>\ref API-intarray-get</code>
00779 
00780 \section API-intarray-init veil_init_int4array(text, text)
00781 \code
00782 function veil_init_int4array(text, text) returns bool
00783 \endcode
00784 Creates, or resets the ranges of, an int array.
00785 
00786 \section API-intarray-clear veil_clear_int4array(text)
00787 \code
00788 function veil_clear_int4array(text) returns bool
00789 \endcode
00790 Clears (zeroes) an int array.
00791 
00792 \section API-intarray-set veil_int4array_set(text, int4, int4)
00793 \code
00794 function veil_int4array_set(text, int4, int4) returns int4
00795 \endcode
00796 Set the value of an element in an int array.
00797 
00798 \section API-intarray-get veil_int4array_get(text, int4)
00799 \code
00800 function veil_int4array_get(text, int4) returns int4
00801 \endcode
00802 Get the value of an element from an int array.
00803 
00804 Next: \ref API-control
00805 */
00806 /*! \page API-control Veil Control Functions
00807 Veil generally requires no management.  The exception to this is when
00808 you wish to reset shared variables.  You may wish to do this because
00809 your underlying security definitions have changed, or because you have
00810 added new features.  In this case, you may use veil_perform_reset() to
00811 re-initialise your shared variables.  This function replaces the current
00812 set of shared variables with a new set in a transaction-safe manner.
00813 All current transactions will complete with the old set of variables in
00814 place.  All subsequent transactions will see the new set.
00815 
00816 The following functions comprise the Veil control functions API:
00817 
00818 - <code>\ref API-control-init</code>
00819 - <code>\ref API-control-reset</code>
00820 - <code>\ref API-control-force</code>
00821 - <code>\ref API-version</code>
00822 
00823 \section API-control-init veil_init(bool)
00824 \code
00825 function veil_init(bool) returns bool
00826 \endcode
00827 This function must be redefined by the application.  The default
00828 installed version simply raises an error telling you to redefine it.
00829 See \ref Implementation for a more detailed description of this function.
00830 
00831 \section API-control-reset veil_perform_reset()
00832 \code
00833 function veil_perform_reset() returns bool
00834 \endcode
00835 This is used to reset Veil's shared variables.  It causes veil_init() to
00836 be called.
00837 
00838 \section API-control-force veil_force_reset(bool)
00839 \code
00840 function veil_force_reset() returns bool
00841 \endcode
00842 In the event of veil_perform_reset() failing to complete and leaving
00843 shared variables in a state of limbo, this function may be called to
00844 force the reset.  After forcing the reset, this function raises a panic
00845 which will reset the database server.  Use this at your peril.
00846 
00847 \section API-version veil_version()
00848 \code
00849 function veil_version() returns text
00850 \endcode
00851 This function returns a string describing the installed version of
00852 veil.
00853 
00854 Next: \ref Building
00855 
00856 */
00857 /*! \page Building Building a Veil-based secure database
00858 \section Build-sec Building a Veil-based secure database
00859 
00860 This section describes the steps necessary to secure a database using
00861 Veil.  The steps are:
00862 - \ref Policy
00863 - \ref Schemas
00864 - \ref Design
00865 - \ref Implementation
00866 - \ref Implementation2
00867 - \ref Implementation3
00868 - \ref Implementation4
00869 - \ref Testing
00870 
00871 \subsection Policy Determine your Policies
00872 
00873 You must identify which security contexts exist for your application,
00874 and how privileges should be assigned to users in those contexts.  You
00875 must also figure out how privileges, roles, and the assignment of roles
00876 to users are to be managed.  You must identify each object that is to be
00877 protected by Veil, identify the security contexts applicable for that
00878 object, and determine the privileges that will apply to each object in
00879 each possible mode of use.  Use the Veil demo application (\ref
00880 demo-sec) as a guide.
00881 
00882 For data access controls, typically you will want specific privileges
00883 for select, insert, update and delete on each table.  You may also want
00884 separate admin privileges that allow you to grant those rights.
00885 
00886 At the functional level, you will probably have an execute privilege for
00887 each callable function, and you will probably want similar privileges
00888 for individual applications and components of applications.  Eg, to
00889 allow the user to execute the role_manager component of admintool, you
00890 would probably create a privilege called
00891 <code>exec_admintool_roleman</code>.
00892 
00893 The hardest part of this is figuring out how you will securely manage
00894 these privileges.  A useful, minimal policy is to not allow anyone to
00895 assign a role that they themselves have not been assigned.
00896 
00897 \subsection Schemas Design Your Database-Level Security
00898 
00899 Veil operates within the security provided by PostgreSQL.  If you wish
00900 to use Veil to protect underlying tables, then those tables must not be
00901 directly accessible to the user.  Also, the Veil functions themselves,
00902 as they provide privileged operations, must not be accessible to user
00903 accounts. 
00904 
00905 A sensible basic division of schema responsibilities would be as follows:
00906 
00907 - An "owner" user will own the underlying objects (tables, views,
00908   functions, etc) that are to be secured.  Access to these objects will
00909   be granted only to "Veil".  The "owner" user will connect only when
00910   the underlying objects are to be modified.  No-one but a DBA will ever
00911   connect to this account, and generally, the password for this account
00912   should be disabled.
00913 
00914 - A "Veil" user will own all secured views and access functions (see
00915   \ref over-views).  Access to these objects will be granted to the
00916   "Accessor" user.  Like the "owner" user, this user should not be
00917   directly used except by DBAs performing maintenance.  It will also own
00918   the Veil API, ie this is the account where Veil itself will be
00919   installed.  Direct access to Veil API functions should not be granted
00920   to other users.  If access to a specific function is needed, it should
00921   be wrapped in a local function to which access may then be granted.
00922  
00923 - "Accessor" users are the primary point of contact.  These must have no
00924   direct access to the underlying objects owned by owner.  They will have
00925   access only to the secured views and access functions.  All
00926   applications may connect to these user accounts.
00927 
00928 \subsection Design Design Your Access Functions
00929 
00930 Provide a high-level view of the workings of each access function.  You
00931 will need this in order to figure out what session and shared variables
00932 you will need.  The following is part of the design from the Veil demo
00933 application:
00934 \verbatim
00935 Access Functions are required for:
00936 - Global context only (lookup-data, eg privileges, roles, etc)
00937 - Personal and Global Context (personal data, persons, assignments, etc)
00938 - Project and Global (projects, project_details)
00939 - All 3 (assignments)
00940 
00941 Determining privilege in Global Context:
00942 
00943 User has priv X, if X is in role_privileges for any role R, that has
00944 been assigned to the user.
00945 
00946 Role privileges are essentially static so may be loaded into memory as a
00947 shared variable.  When the user connects, the privileges associated with
00948 their roles may be loaded into a session variable.
00949 
00950 Shared initialisation code:
00951   role_privs ::= shared array of privilege bitmaps indexed by role.
00952   Populate role_privs with:
00953     select bitmap_array_setbit(role_privs, role_id, privilege_id)
00954     from   role_privileges;
00955 
00956 Connection initialisation code:
00957   global_privs ::= session privileges bitmap
00958   Clear global_privs and then initialise with:
00959     select bitmap_union(global_privs, role_privs[role_id])
00960     from   person_roles
00961     where  person_id = connected_user;
00962 
00963 i_have_global_priv(x):
00964   return bitmap_testbit(global_privs, x);
00965 
00966 \endverbatim 
00967 
00968 This gives us the basic structure of each function, and identifies what
00969 must be provided by session and system initialisation to support those
00970 functions.  It also allows us to identify the overhead that Veil imposes.
00971 
00972 In the case above, there is a connect-time overhead of one extra query
00973 to load the global_privs bitmap.  This is probably a quite acceptable
00974 overhead as typically each user will have relatively few roles.
00975 
00976 If the overhead of any of this seems too significant there are
00977 essentially 4 options:
00978 - Simplify the design.
00979 - Defer the overhead until it is absolutely necessary.  This can be done
00980   with connection functions where we may be able to defer the overhead
00981   of loading relational context data until the time that we first need
00982   it.
00983 - Implement a caching solution (check out pgmemcache).  Using an
00984   in-memory cache will save data set-up queries from having to be
00985   repeated.  This is pretty complex though and may require you to write
00986   code in C.
00987 - Suffer the performance hit.
00988 
00989 \subsection Implementation Implement the Initialisation Function
00990 
00991 The initialisation function \ref API-control-init is a critical
00992 function and must be defined.  It will be called by Veil, when the first
00993 in-built Veil function is invoked.  It is responsible for three distinct
00994 tasks:
00995 
00996 - Initialisation of session variables
00997 - Initialisation of shared variables
00998 - Re-initialisation of variables during reset
00999 
01000 The boolean parameter to veil_init will be false on initial session
01001 startup, and true when performing a reset (\ref API-control-reset).
01002 
01003 Shared variables are created using \ref API-variables-share.  This
01004 returns a boolean result describing whether the variable already
01005 existed.  If so, and we are not performing a reset, the current session
01006 need not initialise it.
01007 
01008 Session variables are simply created by referring to them.  It is worth
01009 creating and initialising all session variables to "fix" their data
01010 types.  This will prevent other functions from misusing them.
01011 
01012 If the boolean parameter to veil_init is true, then we are performing a
01013 memory reset, and all shared variables should be re-initialised.  A
01014 memory reset will be performed whenever underlying, essentially static,
01015 data has been modified.  For example, when new privileges have been
01016 added, we must rebuild all privilege bitmaps to accommodate the new
01017 values.
01018 
01019 \subsection Implementation2 Implement the Connection Functions
01020 
01021 The connection functions have to authenticate the connecting user, and
01022 then initialise the user's session.  
01023 
01024 Authentication should use a secure process in which no plaintext
01025 passwords are ever sent across the wire.  Veil does not provide
01026 authentication services.  For your security needs you should probably
01027 check out pgcrypto.
01028 
01029 Initialising a user session is generally a matter of initialising
01030 bitmaps that describe the user's base privileges, and may also involve
01031 setting up bitmap hashes of their relational privileges.  Take a look at
01032 the demo (\ref demo-sec) for a working example of this.
01033 
01034 \subsection Implementation3 Implement the Access Functions
01035 
01036 Access functions provide the low-level access controls to individual
01037 records.  As such their performance is critical.  It is generally better
01038 to make the connection functions to more work, and the access functions
01039 less.  Bear in mind that if you perform a query that returns 10,000 rows
01040 from a table, your access function for that view is going to be called
01041 10,000 times.  It must be as fast as possible.
01042 
01043 When dealing with relational contexts, it is not always possible to keep
01044 all privileges for every conceivable relationship in memory.  When this
01045 happens, your access function will have to perform a query itself to
01046 load the specific data into memory.  If your application requires this,
01047 you should: 
01048 
01049 - Ensure that each such query is as simple and efficient as possible 
01050 - Cache your results in some way
01051 
01052 You may be able to trade-off between the overhead of connection
01053 functions and that of access functions.  For instance if you have a
01054 relational security context based upon a tree of relationships, you may
01055 be able to load all but the lowest level branches of the tree at connect
01056 time.  The access function then has only to load the lowest level branch
01057 of data at access time, rather than having to perform a full tree-walk.
01058 
01059 Caching can be very effective, particularly for nested loop joins.  If
01060 you are joining A with B, and they both have the same access rules, once
01061 the necessary privilege to access a record in A has been determined and
01062 cached, we will be able to use the cached privileges when checking for
01063 matching records in B (ie we can avoid repeating the fetch).
01064 
01065 \subsection Implementation4 Implement the views and instead-of triggers
01066 
01067 This is the final stage of implementation.  For every base table you
01068 must create a secured view and a set of instead-of triggers for insert,
01069 update and delete.  Refer to the demo (\ref demo-sec) for details of
01070 this.
01071 
01072 \subsection Testing Testing
01073 
01074 Be sure to test it all.  Specifically, test to ensure that failed
01075 connections do not provide any privileges, and to ensure that all
01076 privileges assigned to highly privileged users are cleared when a more
01077 lowly privileged user takes over a connection.  Also ensure that
01078 the underlying tables and raw veil functions are not accessible from
01079 user accounts.
01080 
01081 \section Automation Automatic code generation 
01082 
01083 Note that the bulk of the code in a Veil application is in the
01084 definition of secured views and instead-of triggers, and that this code
01085 is all very similar.  Consider using a code-generation tool to implement
01086 this.  A suitable code-generator for Veil may be provided in subsequent
01087 releases.
01088 
01089 Next: \ref Demo
01090 
01091 */
01092 /*! \page Demo A Full Example Application: The Veil Demo
01093 \section demo-sec The Veil Demo Application
01094 
01095 The Veil demo application serves two purposes:
01096 - it provides a demonstration of Veil-based access controls;
01097 - it provides a working example of how to build a secured system using Veil.
01098 
01099 This section covers the following topics:
01100 
01101 - \ref demo-install
01102 - \subpage demo-model
01103 - \subpage demo-security
01104 - \subpage demo-explore
01105 - \subpage demo-code
01106 - \subpage demo-uninstall
01107 
01108 \subsection demo-install Installing the Veil demo
01109 
01110 From the Veil installation directory run: 
01111 \verbatim
01112 make demo
01113 \endverbatim
01114 
01115 This will create a demo database called veildemo, along with three user
01116 accounts: vdemo_owner, vdemo_veil and vdemo_user.
01117 
01118 NOTE THAT THE VDEMO_VEIL USER IS CREATED WITH SUPERUSER PRIVILEGES.  YOU
01119 SHOULD TAKE STEPS TO LOCK DOWN ACCESS TO THIS ACCOUNT.
01120 
01121 If the make fails, it will probably be because:
01122 - your default postgres account does not have superuser privileges;
01123 - you have a more secure postgres server than is usual.  
01124 
01125 To build the demo database you need a postgres superuser account named
01126 the same as your OS account, and you need to be able to connect to this
01127 and the veil demo accounts without explicitly providing passwords.
01128 
01129 If your pg_hba.conf requires password authentication even for local
01130 connections you will need to add lines like this to your .pgpass file:
01131 \verbatim
01132 localhost:5432:veildemo:vdemo_veil:vdemo_veil
01133 localhost:5432:veildemo:vdemo_owner:vdemo_owner
01134 localhost:5432:veildemo:vdemo_user:vdemo_user
01135 \endverbatim
01136 
01137 You should probably change the password to the vdemo_veil account as
01138 this, necessarily, is created as a superuser account.
01139 
01140 Next: \ref demo-model
01141 
01142 */
01143 /*! \page demo-model The Demo Database ERD, Tables and Views
01144 \section demo-erd The Demo Database ERD
01145 
01146 \image html veil_demo.png "The Veil Demo Database" width=10cm
01147 
01148 \section demo-tables Table Descriptions
01149 
01150 \subsection demo-privs Privileges
01151 
01152 This table describes each privilege.  A privilege is a right to do
01153 something.  Most privileges are concerned with providing access to
01154 data.  For each table, "X" there are 4 data privileges, SELECT_X, UPDATE_X,
01155 INSERT_X and DELETE_X.  There are separate privileges to provide access
01156 to project and person details, and there is a single function privilege,
01157 <code>can_connect</code>.
01158 
01159 \subsection demo-roles Roles
01160 
01161 A role is a named collection of privileges.  Privileges are assigned to
01162 roles through role_privileges.  Roles exist to reduce the number of
01163 individual privileges that have to be assigned to users, etc.  Instead
01164 of assigning twenty or more privileges, we assign a single role that
01165 contains those privileges.
01166 
01167 In this application there is a special role, <code>Personal
01168 Context</code> that contains the set of privileges that apply to all
01169 users in their personal context.  This role does not need to be
01170 explicitly assigned to users, and should probably never be explicitly
01171 assigned.
01172 
01173 Assignments of roles in the global context are made through
01174 person_roles, and in the project (relational) context through
01175 assignments.
01176 
01177 \subsection demo-role-privs Role_Privileges
01178 
01179 Role privileges describe the set of privileges for each role.
01180 
01181 \subsection demo-role-roles Role_Roles
01182 
01183 This is currently unused in the Veil demo application.  Role roles
01184 provides the means to assign roles to other roles.  This allows new
01185 roles to be created as combinations of existing roles.  The use of this
01186 table is currently left as an exercise for the reader.
01187 
01188 \subsection demo-persons Persons
01189 
01190 This describes each person.  A person is someone who owns data and who
01191 may connect to the database.  This table should contain authentication
01192 information etc.  In actuality it just maps a name to a person_id.
01193 
01194 \subsection demo-projects Projects
01195 
01196 A project represents a real-world project, to which many persons may be
01197 assigned to work.
01198 
01199 \subsection demo-person-roles Person_Roles
01200 
01201 This table describes the which roles have been assigned to users in the
01202 global context.
01203 
01204 \subsection demo-assignments Assignments
01205 
01206 This describes the roles that have been assigned to a person on a
01207 specific project.  Assignments provide privilege to a user in the
01208 project context.
01209 
01210 \subsection demo-detail_types Detail_Types
01211 
01212 This is a lookup-table that describes general-purpose attributes that
01213 may be assigned to persons or project.  An example of an attribute for a
01214 person might be birth-date.  For a project it might be inception date.
01215 This allows new attributes to be recorded for persons, projects, etc
01216 without having to add columns to the table.
01217 
01218 Each detail_type has a required_privilege field.  This identifies the
01219 privilege that a user must have in order to be able to see attributes of
01220 the specific type.
01221 
01222 \subsection demo-person_details Person_Details
01223 
01224 These are instances of specific attributes for specific persons.
01225 
01226 \subsection demo-project-details Project_Details
01227 
01228 These are instances of specific attributes for specific projects.
01229 
01230 \section Demo-Views The Demo Application's Helper Views
01231 
01232 Getting security right is difficult.  The Veil demo provides a number of
01233 views that help you view the privileges you have in each context.
01234 
01235 - my_global_privs shows you the privileges you have in the global
01236   context
01237 - my_personal_privs shows you the privileges you have in the
01238   personal context
01239 - my_project_privs shows you the privileges you have for each project
01240   in the project context
01241 - my_privs shows you all your privileges in all contexts
01242 - my_projects shows you all the projects to which you have been assigned
01243 
01244 Using these views, access control mysteries may be more easily tracked
01245 down.
01246 
01247 Next: \ref demo-security
01248 
01249 */
01250 /*! \page demo-security The Demo Database Security Model
01251 \section demo-secmodel The Demo Database Security Model
01252 
01253 The Veil demo has three security contexts.
01254 
01255 - Personal Context applies to personal data that is owned by the
01256   connected user.  All users have the same privileges in personal
01257   context, as defined by the role <code>Personal Context</code>.
01258 - Global Context applies equally to every record in a table.  If a user
01259   has <code>SELECT_X</code> privilege in the global context, they will
01260   be able to select every record in <code>X</code>, regardless of
01261   ownership.  Privileges in global context are assigned through
01262   <code>person_roles</code>.
01263 - Project Context is a relational context and applies to project data.
01264   If you are assigned a role on a project, you will be given specific
01265   access to certain project tables.  The roles you have been assigned
01266   will define your access rights.
01267 
01268 The following sections identify which tables may be accessed in which
01269 contexts.
01270 
01271 \subsection demo-global-context The Global Context
01272 The global context applies to all tables.  All privilege checking
01273 functions will always look for privileges in the global context.
01274 
01275 \subsection demo-personal-context Personal Context
01276 The following tables may be accessed using rights assigned in the
01277 personal context:
01278 - persons
01279 - assignments
01280 - person_details
01281 
01282 \subsubsection demo-project-context Project Context
01283 The following tables may be accessed using rights assigned in the
01284 project context:
01285 - projects
01286 - assignments
01287 - project_details
01288 
01289 Next: \ref demo-explore
01290 
01291 */
01292 /*! \page demo-explore Exploring the Demo
01293 \section demo-use Exploring the Demo
01294 \subsection demo-connect Accessing the Demo Database
01295 Using your favourite tool connect to the database <code>veildemo</code>
01296 as the user <code>vdemo_user</code>.
01297 
01298 You will be able to see all of the demo views, both the secured views and
01299 the helpers.  But you will not initially be able to see any records:
01300 each view will appear to contain no data.  To gain some privileges you
01301 must identify yourself using the <code>connect_person()</code> function.
01302 
01303 There are 6 persons in the demo.  You may connect as any of them and see
01304 different subsets of data.  The persons are
01305 
01306 - 1 Deb (the DBA).  Deb has global privileges on everything.  She needs
01307   them as she is the DBA.
01308 - 2 Pat (the PM).  Pat has the manager role globally, and is the project
01309   manager of project 102.  Pat can see all but the most confidential
01310   personal data, and all data about her project.
01311 - 3 Derick (the director).  Derick can see all personal and project
01312   data.  He is also the project manager for project 101, the secret
01313   project.
01314 - 4 Will (the worker).  Will has been assigned to both projects.  He has
01315   minimal privileges and cannot access project confidential data.
01316 - 5 Wilma (the worker).  Will has been assigned to project 101.  She has
01317   minimal privileges and cannot access project confidential data.
01318 - 6 Fred (the fired DBA).  Fred has all of the privileges of Deb, except
01319   for can_connect privilege.  This prevents Fred from being able to do
01320   anything.
01321 
01322 Here is a sample session, showing the different access enjoyed by
01323 different users.
01324 
01325 \verbatim
01326 veildemo=> select connect_person(4);
01327  connect_person 
01328 ----------------
01329  t
01330 (1 row)
01331 
01332 veildemo=> select * from persons;
01333  person_id |    person_name    
01334 -----------+-------------------
01335          4 | Will (the worker)
01336 (1 row)
01337 
01338 veildemo=> select * from person_details;
01339  person_id | detail_type_id |    value     
01340 -----------+----------------+--------------
01341          4 |           1003 | 20050105
01342          4 |           1002 | Employee
01343          4 |           1004 | 30,000
01344          4 |           1005 | 19660102
01345          4 |           1006 | 123456789
01346          4 |           1007 | Subservience
01347 (6 rows)
01348 
01349 veildemo=> select * from project_details;
01350  project_id | detail_type_id |  value   
01351 ------------+----------------+----------
01352         102 |           1001 | 20050101
01353         102 |           1002 | Ongoing
01354 (2 rows)
01355 
01356 veildemo=> select connect_person(2);
01357  connect_person 
01358 ----------------
01359  t
01360 (1 row)
01361 
01362 veildemo=> select * from person_details;
01363  person_id | detail_type_id |       value       
01364 -----------+----------------+-------------------
01365          1 |           1003 | 20050102
01366          2 |           1003 | 20050103
01367          3 |           1003 | 20050104
01368          4 |           1003 | 20050105
01369          5 |           1003 | 20050106
01370          6 |           1003 | 20050107
01371          1 |           1002 | Employee
01372          2 |           1002 | Employee
01373          3 |           1002 | Employee
01374          4 |           1002 | Employee
01375          5 |           1002 | Employee
01376          6 |           1002 | Terminated
01377          2 |           1004 | 50,000
01378          1 |           1005 | 19610102
01379          2 |           1005 | 19600102
01380          3 |           1005 | 19650102
01381          4 |           1005 | 19660102
01382          5 |           1005 | 19670102
01383          2 |           1006 | 123456789
01384          1 |           1007 | Oracle, C, SQL
01385          2 |           1007 | Soft peoply-stuff
01386          3 |           1007 | None at all
01387          4 |           1007 | Subservience
01388          5 |           1007 | Subservience
01389 (24 rows)
01390 
01391 veildemo=> select * from project_details;
01392  project_id | detail_type_id |  value   
01393 ------------+----------------+----------
01394         102 |           1001 | 20050101
01395         102 |           1002 | Ongoing
01396         102 |           1008 | $100,000
01397 (3 rows)
01398 
01399 veildemo=>
01400 
01401 \endverbatim
01402 
01403 Next: \ref demo-code
01404 
01405 */
01406 /*! \page demo-code The Demo Code
01407 \dontinclude funcs.sql
01408 \section demo-codesec The Code
01409 \subsection demo-code-veil-init veil_init(bool)
01410 
01411 This function is called at the start of each session, and whenever
01412 \ref API-control-reset is called.  The parameter, doing_reset, is
01413 false when called to initialise a session and true when called from
01414 veil_perform_reset().
01415 
01416 This definition replaces the standard default, do-nothing,
01417 implementation that is shipped with Veil (see \ref API-control-init).
01418 
01419 \skip veil_init(bool)
01420 \until veil_share(''det_types_privs'')
01421 
01422 The first task of veil_init() is to declare a set of Veil shared
01423 variables.  This is done by calling \ref API-variables-share.  This function
01424 returns true if the variable already exists, and creates the variable
01425 and returns false, if not.
01426 
01427 These variables are defined as shared because they will be identical for
01428 each session.  Making them shared means that only when session has to
01429 deal with the overhead of their initialisation.
01430 
01431 \until end if;
01432 
01433 We then check whether the shared variables must be initialised.  We will
01434 initialise them if they have not already been initialised by another
01435 session, or if we are performing a reset (see \ref API-control-reset).
01436 
01437 Each variable is initialised in its own way.  
01438 
01439 Ranges are set by a single call to \ref API-basic-init-range.  Ranges are
01440 used to create bitmap and array types of a suitable size.
01441 
01442 Int4Arrays are used to record mappings of one integer to another.  In
01443 the demo, they are used to record the mapping of detail_type_id to
01444 required_privilege_id.  We use this variable so that we can look-up the
01445 privilege required to access a given project_detail or person_detail
01446 without having to explicitly fetch from attribute_detail_types.
01447 
01448 Int4Arrays are initialised by a call to \ref API-intarray-init, and
01449 are populated by calling \ref API-intarray-set for each value to
01450 be recorded.  Note that rather than using a cursor to loop through each
01451 detail_type record, we use select count().  This requires less code and
01452 has the same effect.
01453 
01454 We use a BitmapArray to record the set of privileges for each role.  Its
01455 initialisation and population is handled in much the same way as
01456 described above for Int4Arrays, using the functions \ref
01457 API-bmarray-init and \ref API-bmarray-setbit.
01458 
01459 \until end;
01460 
01461 The final section of code defines and initialises a set of session
01462 variables.  These are defined here to avoid getting undefined variable
01463 errors from any access function that may be called before an
01464 authenticated connection has been established.
01465 
01466 Note that this and all Veil related functions are defined with
01467 <code>security definer</code> attributes.  This means that the function
01468 will be executed with the privileges of the function's owner, rather
01469 than those of the invoker.  This is absolutely critical as the invoker
01470 must have no privileges on the base objects, or on the raw Veil
01471 functions themselves.  The only access to objects protected by Veil must
01472 be through user-defined functions and views.
01473 
01474 \subsection demo-code-connect-person connect_person(int4)
01475 
01476 This function is used to establish a connection from a specific person.
01477 In a real application this function would be provided with some form of
01478 authentication token for the user.  For the sake of simplicity the demo
01479 allows unauthenticated connection requests.
01480 
01481 \skip connect_person(int4)
01482 \until end;
01483 
01484 This function identifies the user, ensures that they have can_connect
01485 privilege.  It initialises the global_context bitmap to contain the
01486 union of all privileges for each role the person is assigned through
01487 person_roles.  It also sets up a bitmap hash containing a bitmap of
01488 privileges for each project to which the person is assigned.
01489 
01490 \subsection demo-code-global-priv i_have_global_priv(int4)
01491 
01492 This function is used to determine whether a user has a specified
01493 privilege in the global context.  It tests that the user is connected
01494 using <code>veil_int4_get()</code>, and then checks whether the
01495 specified privilege is present in the <code>global_context</code>
01496 bitmap.
01497 
01498 \skip function i_have_global_priv(int4)
01499 \until security definer;
01500 
01501 The following example shows this function in use by the secured view,
01502 <code>privileges</code>:
01503 
01504 \dontinclude views.sql
01505 \skip create view privileges
01506 \until i_have_global_priv(10004);
01507 
01508 The privileges used above are <code>select_privileges</code> (10001),
01509 <code>insert_privileges</code> (10002), <code>update_privileges</code>
01510 (10003), and <code>delete_privileges</code> (10004).
01511 
01512 \subsection demo-code-personal-priv i_have_personal_priv(int4, int4)
01513 
01514 This function determines whether a user has a specified privilege to a
01515 specified user's data, in the global or personal contexts.  It performs
01516 the same tests as for <code>i_have_global_context()</code>.  If the user
01517 does not have access in the global context, and the connected user is
01518 the same user as the owner of the data we are looking at, then we test
01519 whether the specified privilege exists in the <code>role_privs</code>
01520 bitmap array for the <code>Personal Context</code> role.
01521 
01522 \dontinclude funcs.sql
01523 \skip function i_have_personal_priv(int4, int4)
01524 \until end;
01525 
01526 Here is an example of this function in use from the persons secured view:
01527 
01528 \dontinclude views.sql
01529 \skip create view persons
01530 \until i_have_personal_priv(10013, person_id);
01531 
01532 \subsection demo-code-project-priv i_have_project_priv(int4, int4)
01533 This function determines whether a user has a specified privilege in the
01534 global or project contexts.  If the user does not have the global
01535 privilege, we check whether they have the privilege defined in the
01536 project_context BitmapHash.
01537 
01538 \dontinclude funcs.sql
01539 \skip function i_have_project_priv(int4, int4)
01540 \until security definer;
01541 
01542 Here is an example of this function in use from the instead-of insert
01543 trigger for the projects secured view:
01544 
01545 \dontinclude views.sql
01546 \skip create rule ii_projects 
01547 \until i_have_project_priv(10018, new.project_id);
01548 
01549 \subsection demo-code-proj-pers-priv i_have_proj_or_pers_priv(int4, int4, int4)
01550 This function checks all privileges.  It starts with the cheapest check
01551 first, and short-circuits as soon as a privilege is found.
01552 
01553 \dontinclude funcs.sql
01554 \skip function i_have_proj_or_pers_priv(int4, int4, int4)
01555 \until security definer;
01556 
01557 Here is an example of this function in use from the instead-of update
01558 trigger for the assignments secured view:
01559 
01560 \dontinclude views.sql
01561 \skip create rule ii_assignments 
01562 \until i_have_proj_or_pers_priv(10027, old.project_id, old.person_id);
01563 
01564 \subsection demo-code-pers-detail-priv i_have_person_detail_priv(int4, int4)
01565 This function is used to determine which types of person details are
01566 accessible to each user.  This provides distinct access controls to each
01567 attribute that may be recorded for a person.
01568 
01569 \dontinclude funcs.sql
01570 \skip function i_have_person_detail_priv(int4, int4)
01571 \until security definer;
01572 
01573 The function is shown in use, below, in the instead-of delete trigger
01574 for person_details.  Note that two distinct access functions are being
01575 used here.
01576 
01577 \dontinclude views.sql
01578 \skip create rule id_person_details
01579 \until i_have_person_detail_priv(old.detail_type_id, old.person_id);
01580 
01581 Next: \ref demo-uninstall
01582 
01583 */
01584 /*! \page demo-uninstall Removing The Demo Database
01585 \section demo-clean-up Removing The Demo Database
01586 From the Veil installation directory run: 
01587 \verbatim
01588 make dropdemo
01589 \endverbatim
01590 
01591 This will drop the database veildemo, and the users vdemo_owner,
01592 vdemo_veil and vdemo_user.
01593 
01594 Next: \ref Management
01595 
01596 */
01597 /*! \page Management Managing Privileges, etc
01598 \section Management-sec Managing Privileges, etc
01599 The management of privileges and their assignments to roles, persons,
01600 etc are the key to securing a veil-based application.  It is therefore
01601 vital that privilege assignment is itself a privileged operation.
01602 
01603 The veil demo does not provide an example of how to do this, and this
01604 section does little more than raise the issue.
01605 
01606 IT IS VITAL THAT YOU CAREFULLY LIMIT HOW PRIVILEGES ARE MANIPULATED AND
01607 ASSIGNED!
01608 
01609 Here are some possible rules of thumb that you may wish to apply:
01610 
01611 - give only the most senior and trusted users the ability to assign
01612   privileges;
01613 - allow only the DBAs to create privileges;
01614 - allow only 1 or 2 security administrators to manage roles;
01615 - allow roles or privileges to be assigned only by users that have both
01616   the "assign_privileges"/"assign_roles" privileges, and that themselves
01617   have the privilege or role they are assigning;
01618 - consider having an admin privilege for each table and only allow users
01619   to assign privileges on X if they have "admin_x" privilege;
01620 - limit the users who have access to the role/privilege management
01621   functions, and use function-level privileges to enforce this;
01622 - audit/log all assignments of privileges and roles;
01623 - send email to the security administrator whenever role_privileges are
01624   manipulated and when roles granting high-level privileges are granted.
01625 
01626 Next: \ref Esoteria
01627 
01628 */
01629 /*! \page Esoteria Exotic and Esoteric uses of Veil
01630 
01631 \section Esoteria-sec Exotic and Esoteric uses of Veil
01632 Actually this is neither exotic nor particularly esoteric.  The title is
01633 simply wishful thinking on the author's part.
01634 \subsection layered-sessions Multi-Layered Connections
01635 So far we have considered access controls based only on the user.  If we
01636 wish to be more paranoid, and perhaps we should, we may also consider
01637 limiting the access rights of each application.
01638 
01639 This might mean that reporting applications would have no ability to
01640 update data, that financial applications would have no access to
01641 personnel data, and that personnel apps would have no access to business
01642 data.
01643 
01644 This can be done in addition to the user-level checks, so that even if I
01645 have DBA privilege, I can not subvert the personnel reporting tools to
01646 modify financial data.
01647 
01648 All access functions would check the service's privileges in addition to
01649 the user's before allowing any operation.
01650 
01651 This could be implemented with a connect_service() function that would
01652 be called only once per session and that *must* be called prior to
01653 connecting any users.  Alternatively, the connected service could be
01654 inferred from the account to which the service is connected.
01655 
01656 \subsection columns Column-Level Access Controls
01657 
01658 Although veil is primarily intended for row-based access controls,
01659 column-based is also possible.  If this is required it may be better to
01660 use a highly normalised data model where columns are converted instead
01661 into attributes, much like the person_details and project_details tables
01662 from the demo application (\ref demo-sec).
01663 
01664 If this is not possible then defining access_views that only show
01665 certain columns can be done something like this:
01666 
01667 \verbatim
01668 create view wibble(key, col1, col2, col3) as
01669 select key, 
01670        case when have_col_priv(100001) then col1 else null end,
01671        case when have_col_priv(100002) then col2 else null end,
01672        case when have_col_priv(100003) then col3 else null end
01673 where  have_row_priv(1000);
01674 \endverbatim
01675 
01676 The instead-of triggers for this are left as an exercise.
01677 
01678 Next: \ref install
01679 
01680 */
01681 /*! \page install Installation and Configuration
01682 \section install_sec Installation
01683 \subsection Get Getting Veil
01684 Veil can be downloaded as a gzipped tarball from
01685 http://pgfoundry.org/projects/veil/
01686 \subsection Pre-requisites Pre-requisites
01687 You must have a copy of the Postgresql header files available in order
01688 to build Veil.  This will probably mean that you need a full Postgres
01689 source tree available.
01690 \subsection build-sub Building Veil
01691 Unpack the tarball.  Configure Veil for your platform using configure.
01692 Use the --help option to configure for more information.  You will
01693 probably have to manually specify the path for your postgresql source
01694 tree using --with-pgincludedir=&le.path>.
01695 
01696 Build the veil shared library, and possibly documents, using make or
01697 make all.
01698 \verbatim
01699 $ tar xvzf veil-<VERSION>tar.gz
01700 . . .
01701 $ ./configure
01702 . . .
01703 $ make all
01704 \endverbatim
01705 \subsection Install Installing Veil
01706 As the postgres, pgsql, or root user, run make install.
01707 \verbatim
01708 make install
01709 \endverbatim
01710 If you are running Veil version 0.9.2 or greater against Postgres
01711 version 8.2 or greater, you should update postgresql.conf to define
01712 shared_preload_libraries to reference the installed version of veil.so
01713 Running "make install" will prompt you to do this.  For more information
01714 on Veil's cooperation with Postgres see \ref configuration.
01715 
01716 Two files are installed by the install target, the veil.so shared
01717 library, and the veil_interface.sql SQL script which creates the veil
01718 functions using the shared library.  Docs may also be installed
01719 depending upon the options you specified to configure.
01720 
01721 The shared library itself is installed in $pglibdir, and the sql script
01722 in $pgsharedir, both as identified by configure.
01723 \subsection Build_Notes Build Notes
01724 The Veil makefile tries to be helpful.  Use "make help" or "make list"
01725 for a list of the targets that make knows how to build.
01726 
01727 The build system deliberately avoids using make recursively.  Search the
01728 Web for "Recursive Make Considered Harmful" for the reasons why.  This
01729 makes the construction of the build system a little different from what
01730 you may be used to.  This may or may not turn out to be a good thing.
01731 \ref Feedback "Feedback" is welcomed.
01732 
01733 \subsection Regression Regression Tests
01734 Veil comes with a built-in regression test suite.  Use "make regress" to
01735 run this.  You will need superuser access to Postgres in order to create
01736 the regression test database.  The regression test assumes you will have
01737 a postgres superuser account named the same as your OS account.  If
01738 pg_hba.conf disallows "trust"ed access locally, then you will need to
01739 provide a password for this account in your .pgpass file (see postgres
01740 documentation for details).
01741 
01742 The regression tests are all contained within the regress directory and
01743 are run by the regress.sh shell script.  Use the -h option to get
01744 fairly detailed help.
01745 
01746 The Veil regression tests automatically use the veil_trial.so shared
01747 library if appropriate (based upon veil and postgres versions and
01748 whether veil.so is configured as a shared_preload_library (\ref
01749 configuration).
01750 
01751 \subsection Demodb_install Demo Database
01752 As with the regression tests, you will need to be a privileged database
01753 user to be able to create the demo database.  For more on installing the
01754 demo database see \ref demo-install.
01755 
01756 \section configuration Configuration
01757 From version 0.9.2 of Veil and version 8.2 of Postgres, Veil cooperates
01758 with Postgres over its shared memory usage.  A non-cooperating version
01759 of Veil is also built (\ref trialversion), which may be used to try
01760 out Veil if you are in a situation where you cannot modify
01761 postgresql.conf or restart the Postgres server.
01762 
01763 To configure Veil, the following lines should be added to your
01764 postgresql.conf:
01765 \code
01766 shared_preload_libraries = '<path to shared library>/veil.so' 
01767 
01768 custom_variable_classes = 'veil'
01769 
01770 #veil.dbs_in_cluster = 1
01771 #veil.shared_hash_elems = 32
01772 #veil.shmem_context_size = 16384
01773 \endcode
01774 
01775 The three configuration options, commented out above, are:
01776 - dbs_in_cluster
01777   The number of databases, within the database cluster, that
01778   will use Veil.  Each such database will be allocated 2 chunks of
01779   shared memory (of shmem_context_size), and a single LWLock.
01780   It defaults to 1.
01781 
01782 - shared_hash_elems
01783   This describes how large a hash table should be created for veil
01784   shared variables.  It defaults to 32.  If you have more than about 20
01785   shared variables you may want to increase this to improve
01786   performance.  This setting does not limit the number of variables that
01787   may be defined, it just limits how efficiently they may be accessed.
01788 
01789 - shmem_context_size
01790   This sets an upper limit on the amount of shared memory for a single
01791   Veil shared memory context (there will be two of these).  It defaults 
01792   to 16K.  Increase this if you have many shared memory structures.
01793 
01794 \section trialversion Trial Version
01795 From version 0.9.2 of Veil and version 8.2 of Postgres the veil.so
01796 shared library cooperates with the Postgres server over the reservation
01797 and allocation of shared memory.  This requires that the postgresql.conf
01798 file be modified as described in (\ref configuration) and that postgres
01799 be stopped and restarted.
01800 
01801 A trial version of the veil shared library, veil_trial.so is
01802 automatically created when veil is built.  This version of the shared
01803 library does not require modifications to postgresql.conf and does not
01804 require the database to be restarted.  Note that the veil regression tests
01805 will be run in this mode if postgres has not been configured for Veil.
01806 
01807 \subsection Debugging Debugging
01808 If you encounter problems with Veil, you may want to try building with
01809 debug enabled.  Define the variable VEIL_DEBUG on the make command line
01810 to add extra debug code to the executable:
01811 \verbatim
01812 $ make clean; make VEIL_DEBUG=1 all
01813 \endverbatim
01814 
01815 This is a new feature and not yet fully formed but is worth trying if
01816 Veil appears to be misbehaving.  If any of the debug code encounters a
01817 problem, ERRORs will be raised.
01818 
01819 Next: \ref History
01820 
01821 */
01822 /*! \page History History and Compatibility
01823 \section past Changes History
01824 \subsection v9_6 Version 0.9.6 (2008-02-06)
01825 This release has minor changes to support PostgreSQL 8.3.
01826 
01827 \subsection v9_5 Version 0.9.5 (2007-07-31)
01828 This is a bugifx release, fixing a memory allocation bug in the use of 
01829 bitmap_refs.  There are also fixes for minor typos, etc.
01830 
01831 \subsection v9_4 Version 0.9.4 (2007-02-21)
01832 This is a bugifx release, providing:
01833  - fix for major bug with recursive handling of spi connect, etc;
01834  - improvement to session initialisation code to do more up-front work
01835    in ensure_init();
01836  - safer initialisation of malloc'd data structures;
01837  - improved error messages for shared memory exhaustion cases;
01838  - addition of debug code including canaries in data structures;
01839  - improvement to autoconf to better support Debian GNU/Linux, and OSX;
01840  - improvement to autoconf/make for handling paths containing spaces;
01841  - improvement to regression tests to better support OSX;
01842  - removal of spurious debug warning messages.
01843 
01844 \subsection v9_3 Version 0.9.3 (2006-10-31) 
01845 This version uses the new Postgres API for reserving shared memory for
01846 add-ins.  It also allows the number of Veil-enabled databases for a
01847 cluster to be configured, and refactors much of the shared memory code.
01848 A small fix for the Darwin makefile was also made.
01849 
01850 \subsection v9_2 Version 0.9.2 (2006-10-01) 
01851 This version was released to coincide with Postgres 8.2beta1 and first
01852 made use of new Postgres APIs to allow Veil to be a good Postgres
01853 citizen.  
01854 
01855 With prior versions of Veil, or prior versions of Postgres, Veil steals
01856 from Postgres the shared memory that it requires.  This can lead to the
01857 exhaustion of Postgres shared memory.
01858 
01859 Unfortunately, the Postgres API for shared memory reservation had to
01860 change follwing 8.2.beta1, and this version of Veil is therefore deprecated.
01861 
01862 \subsection v9_1 Version 0.9.1 (2006-07-04)
01863 This release fixed a small number of bugs and deficiencies:
01864 - major error in veil_perform_reset that prevented proper use of the two
01865 interdependant shared memory contexts
01866 - minor improvements in the build process to "configure" and friends
01867 - minor documentation improvements
01868 
01869 \subsection v9_0 Version 0.9.0  (2005-10-04) 
01870 This was the first public alpha release of Veil.
01871 
01872 \section forecast Change Forecast
01873 If no major bugs are found in 0.9.6 within 2 months of its release date,
01874 it will be re-released as 0.9.8 Beta.  The previous target was no bugs
01875 within 6 months of the release of 0.9.5
01876 
01877 Once reports of general satisfaction with Veil have been received from a
01878 reasonable number of distinct sources, Veil will be promoted to version
01879 1.0 Stable.
01880 
01881 New versions will be released with each new major version of PostgreSQL.
01882 
01883 \section compatibility Supported versions of Postgres
01884 <TABLE>
01885   <TR>
01886     <TD rowspan=2>Veil version</TD>
01887     <TD colspan=6>Postgres Version</TD>
01888   </TR>
01889   <TR>
01890     <TD>7.4</TD>
01891     <TD>8.0</TD>
01892     <TD>8.1</TD>
01893     <TD>8.2beta1</TD>
01894     <TD>8.2</TD>
01895     <TD>8.3</TD>
01896   </TR>
01897   <TR>
01898     <TD>0.9.0 Alpha</TD>
01899     <TD>1</TD>
01900     <TD>1</TD>
01901     <TD>1</TD>
01902     <TD>-</TD>
01903     <TD>-</TD>
01904     <TD>-</TD>
01905   </TR>
01906   <TR>
01907     <TD>0.9.1 Alpha</TD>
01908     <TD>1</TD>
01909     <TD>1</TD>
01910     <TD>1</TD>
01911     <TD>-</TD>
01912     <TD>-</TD>
01913     <TD>-</TD>
01914   </TR>
01915   <TR>
01916     <TD>0.9.2 Alpha</TD>
01917     <TD>-</TD>
01918     <TD>1</TD>
01919     <TD>1</TD>
01920     <TD>2</TD>
01921     <TD>-</TD>
01922     <TD>-</TD>
01923   </TR>
01924   <TR>
01925     <TD>0.9.3 Alpha</TD>
01926     <TD>-</TD>
01927     <TD>1</TD>
01928     <TD>1</TD>
01929     <TD>-</TD>
01930     <TD>3</TD>
01931     <TD>-</TD>
01932   </TR>
01933   <TR>
01934     <TD>0.9.4 Alpha</TD>
01935     <TD>-</TD>
01936     <TD>1</TD>
01937     <TD>1</TD>
01938     <TD>-</TD>
01939     <TD>3</TD>
01940     <TD>-</TD>
01941   </TR>
01942   <TR>
01943     <TD>0.9.5 Alpha</TD>
01944     <TD>-</TD>
01945     <TD>1</TD>
01946     <TD>1</TD>
01947     <TD>-</TD>
01948     <TD>3</TD>
01949     <TD>-</TD>
01950   </TR>
01951   <TR>
01952     <TD>0.9.6 Alpha</TD>
01953     <TD>-</TD>
01954     <TD>1</TD>
01955     <TD>1</TD>
01956     <TD>-</TD>
01957     <TD>3</TD>
01958     <TD>3</TD>
01959   </TR>
01960 </TABLE>
01961 Notes:
01962 
01963 1) These combinations of Veil and Postgres provide no configuration
01964    options for shared memory.  Veil's shared memory may be exhausted by
01965    too many requests for large shared objects.  Furthermore, Postgres'
01966    own shared memory may be easily exhausted by creating too many
01967    Veil-using databases within a cluster.
01968 
01969 2) This version is deprecated
01970 
01971 3) These combinations of Veil and Postgres provide full configuration
01972    options for shared memory usage, and Veil cooperates with Postgres
01973    for the allocation of such memory meaning that it is not possible to
01974    use Veil to exhaust Postgres' shared memory.  This is the minimum
01975    Veil configuration recommended for production use.
01976 
01977 \section platforms Supported Platforms
01978 Veil should be buildable on any platform supported by PostgreSQL, but
01979 not all have been tried.  Please provide feedback on problems and
01980 successes to \ref Feedback "the author" so that these lists may be
01981 updated.
01982 
01983 The following platforms have been tried and verified:
01984 - Linux (Intel)
01985 - OSX
01986 
01987 The following platforms are expected to work but have not been
01988 verified:
01989 - BeOS
01990 - BSD/OS
01991 - DGUX
01992 - FreeBSD (ELF systems)
01993 - HPUX
01994 - Irix
01995 - Linux (non-intel)
01996 - NetBSD (ELF systems)
01997 - OpenBSD (ELF systems)
01998 - OSF
01999 - SCO
02000 - Solaris
02001 - Sun/OS
02002 - SVR4
02003 - Univel
02004 - Unixware
02005 
02006 
02007 The following platforms are expected to have build problems:
02008 - Aix
02009   Try modifying makefiles/Makefile.aix.  The line:
02010 \verbatim
02011 %$(DLSUFFIX): %.o %$(EXPSUFF)
02012 \endverbatim
02013 should probably read
02014 \verbatim
02015 %$(DLSUFFIX):
02016 \endverbatim
02017 and in the commands that follow, "$<" should probably be substituted
02018 with "$^".
02019 - Cygwin
02020   Try modifying makefiles/Makefile.cygwin.  The line:
02021 \verbatim
02022 %.dll: %.o
02023 \endverbatim
02024 should probably read
02025 \verbatim
02026 %.dll:
02027 \endverbatim
02028 and in the commands that follow, "$<" should probably be substituted
02029 with "$^".
02030 - FreeBSD (Non-ELF systems)
02031   Try modifying the non-ELF code in makefiles/Makefile.freebsd 
02032 - NetBSD (Non-ELF systems)
02033   Try modifying the non-ELF code in makefiles/Makefile.netbsd 
02034 - OpenBSD (Non-ELF systems)
02035   Try modifying the non-ELF code in makefiles/Makefile.openbsd 
02036 - QNX
02037   Sorry, I have no idea how to build for this.
02038 - Ultrix
02039   Sorry, I have no idea how to build for this.
02040 - Windows
02041   Sorry again.
02042 
02043 
02044 Next: \ref Feedback
02045 
02046 */
02047 /*! \page Feedback Bugs and Feedback
02048 \section Feedback Bugs and Feedback
02049 For general feedback, to start and follow discussions, etc please join
02050 the veil-general@pgfoundry.org mailing list.
02051 
02052 If you wish to report a bug or request a feature, please do so using the
02053 appropriate Tracker at http://pgfoundry.org/projects/veil
02054 
02055 If you wish to contact the author offlist, you can find him at 
02056 http://bloodnok.com/Marc.Munro
02057 
02058 Next: \ref Performance
02059 
02060 */
02061 /*! \page Performance Performance
02062 \section perf Performance
02063 Attempts to benchmark veil using pgbench have not been very successful.
02064 It seems that the overhead of veil is small enough that it is
02065 overshadowed by the level of "noise" within pgbench.
02066 
02067 Based on this inability to properly benchmark veil, the author is going
02068 to claim that "it performs well".
02069 
02070 To put this into perspective, if your access functions do not require
02071 extra fetches to be performed in order to establish your access rights,
02072 you are unlikely to notice or be able to measure any performance hit
02073 from veil.
02074 
02075 If anyone can provide good statistical evidence of a performance hit,
02076 the author would be most pleased to hear from you.
02077 
02078 Next: \ref Credits
02079 
02080 */
02081 /*! \page Credits Credits
02082 \section Credits
02083 The Entity Relationship Diagram in section \ref demo-erd was produced
02084 automatically from an XML definition of the demo tables, using Autograph
02085 from CF Consulting.  Thanks to Colin Fox for allowing its use.
02086 
02087 Much of the build system is based upon that for Slony-I.  Thanks to Jan
02088 Wieck and all of the Slony-I team for providing a great model upon which
02089 to build.
02090 
02091 Thanks to the PostgreSQL core team for providing PostgreSQL.
02092 
02093 Thanks to pgfoundry for providing a home for this project.
02094 */
02095 

Generated on Tue Mar 11 10:20:03 2008 for Veil by  doxygen 1.5.4