Veil2 provides session management functions for both dedicated and shared database connections. It is up to you or your application to ensure that the session protocols are followed. If they are not, the user will have access to no data at all, or access to data based on another user's access rights.

By calling the appropriate session management functions with appropriate authentication tokens, a Veil2 session will be created. This causes session parameters to be set up in secure temporary tables from which they can be quickly retrieved. These session parameters include session privileges with one record for each scope in which the user has privileges.

The set of privileges in each scope is stored in a single bitmap. This is a space-efficient array of numbered bits, with each bit indicating the presence or absence of a privilege. Tests for the presence of a privilege in a bitmap are very fast.

At the start of each session, the user's privileges are determined based upon the roles that have been assigned to them and the contexts of those role assignments. This is a highly optimized process, using pre-built, cached, bitmaps and materialized views. These caches and materialized views are automatically updated as needed.

Each privilege assigned to a user acts within a scope that depends on the context in which it was assigned. Some scopes will allow all records in a table to be seen or manipulated, and some will allow large, small or smaller subsets of data to be seen.

As stated above, the set of privileges in each scope is stored in a bitmap, and tests for the presence of a privilege in the bitmap are very fast. The security rules for a relation will typically be defined something like this (from the veil2_demo extension):

alter table demo.projects enable row level security;

create policy projects__select
    on demo.projects
   for select
 using (   veil2.i_have_global_priv(25)
        or veil2.i_have_priv_in_scope(25, 3, corp_id)
        or veil2.i_have_priv_in_scope(25, 4, org_id)
        or veil2.i_have_priv_in_scope(25, 5, project_id));
	

Each of the test functions is checking whether the user has the privilege, select projects (privilege 25), to view the current record. Tests are made in global scope, then corp scope (scope type 3) of the owning corp, then org scope (scope type 4) of the owning org, and finally in project scope (scope type 5) of the project itself. Each of these tests causes a different bitmap in the users session privileges to be checked.

Although having so many tests performed for each record returned might seem like a significant overhead, in fact it is very small compared with the cost of retrieving the record in the first place and will often be effectively unmeasurable.

Note that you should not rely solely on your VPD (Virtual Private Database) implementation to limit the number of records returned from queries to your users. Your application should be constructing where-clauses that only return records that your user is entitled to see. That is, your Veil2 implementation should act as a final back-stop safety check and not as a (hidden) part of your system's functionality.

There are 2 reasons for this:

Every table and view is given its own individual security definition. For tables, they will be much as shown above but will include definitions for insert, update and delete as well as select.

Views are secured in a similar way, but with the privilege testing functions defined in the view itself. Sometimes using views can improve the performance of the privilege tests as they can be incorporated more deeply within the view, meaning that the tests do not have to be executed for every row used by the view's query.

The Veil2-protected database needs to know which user is accessing it all times. It provides a session-management protocol for use from web applications. Your web application will have to provide handling of this session management protocol. Generally this will be handled as triggers or hooks into the database connection pool management.

Veil2 has its own view of what roles should do and what they should look like. If your own system uses roles for its existing access control purposes, you will have to somehow integrate your system's role requirements with those of Veil2. You essentially have two choices:

For every type of security context/scope that you wish to provide, you will need to provide a link from your existing tables back to Veil2. This will be handled with triggers and FK-constraints. There are examples of how this may be done in the demos.

All of your users must be associated with Veil2 accessors (users who access your database), and any existing credentials must be migrated. Again this can be handled by triggers and FK-constraints, and the demos provide examples.

You will be applying access controls to each relation in your system. Some of them may benefit from data denormalizations to improve the performance of the security tests. Typically you may want to add ownership columns to some of your tables so that ownership can be determined without the need for extra joins. If an access control function has to perform extra queries for each row returned, performance is likely to suffer.

You may need to implement a new authentication system for users. Or the built-in bcrypt implementation may be enough.