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(<bitmap>, veil_bitmap_from_array(<bitmap_array>, <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(<bitmap>, veil_bitmap_from_array(<bitmap_array>, <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(<bitmap_hash>, <key>), <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(<bitmap>, veil_bitmap_from_hash(<bitmap_array>, <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(<bitmap>, veil_bitmap_from_hash(<bitmap_array>, <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