veil_mainpage.c

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

Generated on Fri Mar 12 08:38:37 2010 for Veil by  doxygen 1.5.6