.
contact contact

B.08.10 / Release Notes / Item Access

Enhanced Item Level Security

 
.
  Contents:

Overview

The item level security functionality allows restricting access on selected items at the database and/or dataset level, depending on the access privileges of a database account. This allows to enhance the security of existing applications with no or minimal code changes.

A typical use would be to limit access on items with sensitive information, such as credit card numbers, social security numbers or salary figures to those database users that are member of a dedicated security group, whereas all other users only get to see empty or masked values when reading the respective item contents.


Configuration

The rules for item level access control are configured with dbutil script commands and stored inside the database catalog.

Item access rules may be configured for selected datasets or for the whole database or both. Rules at the dataset level take precedence over rules at the database level.

Item access rules may also either be general or specific to database security groups. General rules apply to all users. Group specific rules apply to users which are member of those groups. Group specific rules take precedence over general rules. If a user is member of multiple groups for which access rules are configured, the "most restrictive" access is granted, unless an "allow" rule overrides this.

Item access rules use a set of keywords to define the desired access rights: MASKED, NOUPDATE, ALLOWED.

  • The MASKED keyword changes the DBGET behavior to return a modified copy of the item content to the application; one of several different functions for "masking" the item content may be specified with the MASKED keyword, the default is to return an empty field, blanks for string items and (unsigned) zero for numeric items.

    The MASKED keyword also changes the DBUPDATE behavior to silently ignore the modified value returned by DBGET, if the application passes the masked value back to the server as part of a subsequent DBUPDATE call. This is intended to avoid accidental modification of the data while still allowing update of the item. For array items this is evaluated for each element separately.

  • The NOUPDATE keyword changes the DBUPDATE behavior to (silently) discard all changes to the specified item. No error is returned, the update just keeps the previous item value in the database. The NOUPDATE option is typically used in conjunction with MASKED.

  • The ALLOWED keyword specifies unrestricted item access for DBGET and DBUPDATE operations. It is useful for defining access rules that take precedence over other existing rules (e.g. set specific rule overriding database-wide rule).
The following "mask functions" are available with MASKED and string items:
  • cover(x,m,n) keeps the leading m and trailing n characters of the item contents visible (m >= 0, n >= 0) and replaces each character in between with character x. The item is considered left-justified and trailing blanks are ignored.

    For example: cover(X,1,2) on 123456 results in 1XXX56

  • part(x,m,n) keeps the leading m and trailing n characters of the item content visible (m >= 0, n >= 0) and replaces the characters in between with a sinngle character x. The item is considered left-justified and trailing blanks are ignored.

    For example: part(*,1,2) on 123456 results in 1*56

  • left(x,n) keeps the leading part of the item content. If n is positive, the n leftmost characters are kept. If n is negative, all but the trailing n characters are kept. The item is considered left-justified and trailing blanks are ignored.

    For example:
    left(*,2) on 123456 results in 12*
    left(*,-2) on 123456 results in 1234*

  • right(x,n) keeps the trailing part of the item content. If n is positive, the n rightmost characters are kept. If n is negative, all but the leading n characters are kept. The item is considered left-justified and trailing blanks are ignored.

    For example:
    right(*,2) on 123456 results in *56
    right(*,-2) on 123456 results in *3456

  • set(text) shows the string "text" if the item content is non-blank. The text is truncated as necessary if it exceeds the item size.

    For example:
    set(PRESENT) on 123456 results in PRESENT
    set(PRESENT) on an empty field results in an empty field

If none of the above functions is specified with the MASKED keyword, string item contents are changed to blanks, numeric items to zero.


Backwards Compatibility

Configuring and using item access rules requires an internal database catalog table "sysitemproperty" that did not exist in previous versions of Eloquence. For databases created on older Eloquence versions, it is necessary to upgrade the catalog tables with the "upgrade database" command in dbutil before configuring any item access rules is possible.

After upgrading the database catalog tables, such databases may no longer be fully compatible with older Eloquence versions. Using the database volume files with an older Eloquence version or transferring such a database to an older Eloquence version with dbstore/dbrestore results in the item access rules being "ignored" by the older server version (and potentially corrupting the item access rules if the database structure is changed with an older server version). Furthermore, the old dbdumpcat and dbutil programs may not be able to work with those databases in all cases.

Please note that there is no "downgrade database" command in dbutil.


dbutil script syntax

All commands below are only valid inside a database context:
DATABASE "example";
The following command upgrades the database catalog for databases created on older Eloquence versions (see "Compatibility" above):
UPGRADE DATABASE;
The following commands may be used to maintain item access rules:
SET ITEM ACCESS ON ItemName [ IN SetName ]
TO MASKED [ MaskFunction ] [,NOUPDATE] [ FOR GroupList ] ;

SET ITEM ACCESS ON ItemName [ IN SetName ]
TO ALLOWED [,NOUPDATE] [ FOR GroupList ] ;

UNSET ITEM ACCESS ON ItemName [ IN SetName ]
[ FOR { GroupList | ALL } ] ;
Where
  • ItemName specifies the item name (optionally enclosed in quotes)

  • SetName specifies the set name (optionally enclosed in quotes)

  • MaskFunction is one of
    • "cover(x,m,n)" with m >=0 and n >= 0 and x = some character (e.g. *)
    • "part(x,m,n)" with m >=0 and n >= 0 and x = some character
    • "left(x,n)" with x = some character
    • "right(x,n)" with x = some character
    • "set(text)" with text = some string (e.g. -is set-)

  • GroupList is a list of quoted group names, separated by a comma
If a SetName is specified, the item access rule is specific to this data set. If not specified, it applies as a default to all data sets that use this item.

Examples:

set item access on salary 
  to masked, noupdate;
set item access on salary 
  to allowed for "supervisor";

set item access on salary in payroll-info
  to masked, noupdate;
set item access on salary in payroll-info 
  to allowed for "supervisor";

set item access on "ccard#" 
  to masked "set(available)", noupdate;
set item access on "ccard#" 
  to masked "cover(X,0,4)" 
  for "agents";
set item access on "ccard#"
  to allowed
  for "billing";

set item access on "ccard#" in customers
  to masked "set(available)", noupdate;
set item access on "ccard#" in customers
  to "cover(X,0,4)" 
  for "agents";
set item access on "ccard#" in customers
  to allowed 
  for "billing";

unset item access on zipcode;
unset item access on zipcode for all;
unset item access on zipcode in customers for "group";

database catalog table

The item access rules configured with dbutil script commands are maintained in the catalog table "sysitemproperty" for the respective database. They may be reviewed with dbdumpcat as needed (e.g. to help troubleshooting).

For example:

$ dbdumpcat -t 12 sampledb

-------------------------------------------------------
#12 sysitemproperty (5 entries)
-------------------------------------------------------
|gid |tableid|colid|type|flags   |data  	      |
-------------------------------------------------------
|0   |0      |74   |1	|06000000|set(available)      |
|3   |0      |74   |1	|02000000|cover(X,0,4)        |
|4   |0      |74   |1	|00000000|		      |
|5   |101    |65   |1	|00000000|		      |
|6   |101    |65   |1	|02000000|		      |
-------------------------------------------------------

The catalog tables "sysgroup", "systables" and "syscolumns" contain additional details on the values of the "gid", "tableid", and "colid" columns, for example the textual names of the respective entities.

Note that gid=0 denotes access rules not specific to a group and that tableid=0 denotes access rules not specific to a data set.


Examples

Below is an example for using the enhanced item level security.

Consider you have a database containing a sensitive item called credit-card-no in several datasets and you want to restrict the access in the following way: members of the billing department should have full access, members of the "agents" group should be able to only see the rightmost 4 characters of the item and also be able change the item to a new value with DBUPDATE. All other users should only see the word "available", if the item contains a non-blank value, and should not be able to change it to a new value with dbupdate.

The following dbutil commands configure the above behavior:

DATABASE "sampledb";

SET ITEM ACCESS ON credit-card-no
  TO MASKED "set(available)", NOUPDATE;
SET ITEM ACCESS ON credit-card-no
  TO MASKED "cover(*,0,4)" FOR "agents";
SET ITEM ACCESS ON credit-card-no
  TO ALLOWED FOR "billing";
The example above assumes that (only) the users of the billing department are configured as members of the database security group "billing".

Members of the "agents" group are unable to view the unmasked item contents, but are allowed to change it to a new value with DBUPDATE (with the single exception that they will not be able to change it to the masked value itself).

To further refine the access rules for a specific data set called "payment-log" so not even the agents or billing users are able to change the item value with DBUPDATE a data set specific rule may be used. The following dbutil commands configure these additional rules:

DATABASE "sampledb";

SET ITEM ACCESS ON credit-card-no IN payment-log
  TO MASKED "set(available)", NOUPDATE;
SET ITEM ACCESS ON credit-card-no IN payment-log
  TO MASKED "cover(*,0,4)", NOUPDATE FOR "agents";
SET ITEM ACCESS ON credit-card-no IN payment-log
  TO ALLOWED, NOUPDATE for "billing";
Please note that the NOUPDATE option only applies to item content changes performed with a DBUPDATE call. It does not prevent changes resulting from a sequence of DBDELETE and DBPUT calls.


Potential Pitfalls

When preparing to use item level access rules in production, we recommend to carefully check that your configuration works as intended and that the applications are compatible with the access rules.

The following paragraphs discuss a number of potential pitfalls that you might encounter when implementing item access rules.

Updating MASKED items
By configuring a MASKED rule for an item, you do not only limit the read access for the users that the rule applies to. You also change the dbupdate behavior, even if NOUPDATE is not specified. This is to prevent an application from overwriting an entry with the masked item value by accident when using a dbupdate after a dbget that returned masked item contents to the client buffer.

For example, if an access rule is effective for a user in such a way that the user only gets blanked (or zeroed) item contents from the database server, then this user will not be able to change the item value to all blanks (or zeros) with a subsequent dbupdate.

Note, however, that preventing the accidental write-back of the masked value into the database ONLY works for the DBUPDATE call. If your application uses a sequence of DBDELETE and DBPUT calls to update existing database records, there is no such protection and the use of MASKED items would silently damage your database contents. Check your application behavior very carefully before using MASKED items in productive environments.

Users in multiple groups
When configuring item access rules for specific groups, keep in mind whether your database has users with membership in multiple groups or not.

If a user is member of more than one security group, the most restrictive access rule will apply, unless there is an "allow" rule that overrides the other access rules.

The following table shows the access rules sorted by precedence:

  1. ALLOWED
  2. MASKED,NOUPDATE
  3. MASKED
  4. NOUPDATE
Please keep in mind that data set specific rules still override unspecific rules.

If you have multiple competing MASKED (or MASKED,NOUPDATE) rules for a given user because the user is member of multiple groups, the associated masking functions (if any are specified) have no influence on the selection of the effective access rule.

Using MASKED for key or search items

When configuring MASKED rules for items that are used as a key in master sets and/or search items in detail sets, you should pay special attention to testing the compatibility of your tools and applications.

While DBGET (mode 7) and DBFIND behave "as usual" when passing the (unmasked) item value as argument, the application might not be prepared to handle the masked item value returned by the DBGET (mode 7) or subsequent DBGET calls (mode 5 or 6) following the DBFIND.

One such example is the FIND command in query3k, which does not work properly when used with MASKED key or search items as part of the selection criteria (no matter if the masked or unmasked item values are specified with the FIND command).

Downgrading Eloquence

As mentioned in the section "Compatibility", the item level access rules are stored in a database catalog table "sysitemproperty" that did not exist in Eloquence versions before B.08.10.

When attempting to use a database using item level access rules with an older version of the Eloquence database server, the item level access rules are not applied. When restructuring the database, the item access rules in the database structure might be corrupted, which could result in unexpected behavior when restored to a newer server release that supports item access rules. The incompatible database catalog version might also potentially cause issues when using tools like dbdumpcat or dbutil that could complain about the unkown "sysitemproperty" catalog table.

It is recommended to remove all item access rules before restoring a database to an Eloquence version before B.08.10. These rules are not effective with older Eloquence database versions and stale access rules are not be a problem when upgrading to B.08.10 subsequently.

A reasonable efficient supported procedure for downgrading a database to an older Eloquence version is thus to save the schema with prschema and to binary export the data with dbbexp. The resulting files are then used on the old Eloquence version to create the database from the schema file and import each dataset with dbctl bimport.


 
 
.
 
 
  Privacy | Webmaster | Terms of use | Impressum Revision:  2010-08-31  
  Copyright © 2010 Marxmeier Software AG