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