The Casbah Project: APIs and Reference Manual: Developer's Release 1
PrevThe Casbah Project: Security in Casbah 

Access Modes

Access modes must be CaUInt8 objects. Each bit corresponds to a particular access mode, and different modes can be placed into the same object by an OR operation.[1]

Table 2. Access Modes

Name

Bit Mask

Abbreviation

Description

Read

1

r

Read an object's contents. Also must be able to list what is inside a CaDict or CaList.

Write

2

w

Write or modify an object's contents. For CaDicts and CaLists this means the ability to completely overwrite the object. The write mode does not apply to modifying individual elements, such as removing or adding elements to a CaDict or CaList.

Use in path

4

u

Allows this object to be used in a path. This mode only applies to CaDicts and CaLists. Without this access mode granted you cannot access any object contained in the CaDict or CaList.

Execute

8

e

Allows script or method object to be executed. Objects which are not scripts or methods must ignore this mode.

Become-user / Join-group

16

s

This mode can be used on any type of object and alters the current user's access information. See FOO.

Remove from parent CaList or CaDict

32

d

This mode grants access to remove this item from its parent CaList or CaDict. Without this mode granted, a user must not be able to remove this object from its parent, even if they have write access for the parent object.

Add to CaList or CaDict

64

a

This mode grants access to add new elements to the CaList or CaDict.

To make using these modes convienent, the following groups of modes must also be supplied.

Table 3. Shorthand Access Modes

Shorthand

Modes

read

ru

write

wuda

execute

ue

add

uwa

delete

wud

Become-user/Join-group

Casbah supports "setuid" execution to a much higher (and more powerful) extent than the traditional Unix operating system. When the 's' mode bit is set in an ACL for a user or a group, that user or group is added to the current user's identity. This must be done only for script/method execution. All users and groups named in the ACL with the 's' mode bit set must be added to the user's identity. After the script/method has completed executing, the users and groups which had been added to the user's identity must be removed. If the user was already a member of a group which had been added to his identity through the "s" mode bit, he should still remain a member of that group after the script has been executed. In other words, after the method/script has completed, the user's identity must be exactly the same as before it began.[2]

ACL Format

ACLs must be applied to CaDicts only. ACLs may be inherited through aquisition. An ACL itself is a CaDict object, where the key for an entry is the string "user@realm", and the value is another CaDict, allowing individual entries in an ACL list to themselves be controlled by an ACL. The mode bits must be placed in the second CaDict under the key "mode".

Example 1. ACL

{
"@" => {"mode" => 0},
"user@users" => {"mode" => 127 },
"@admins" => {"mode" => 127,
"__cb_acl__" => " {
"@" => {"mode" => 0},
"@admins" => {"mode" => 127},
}
},
}

In the there are three ACL entries. The first denies all users access to the object, effectively canceling any ACL entries higher in the hierachy. The second entry grants "joe" in the realm "@users" full access to this object. The last entry is more complex. It grants any user in the realm "admins" full access to this object. It also prevents anyone from being able to modify this ACL entry by denying all users in all realms access to modify the ACL entry, and by then granting access to any user in "@admins" the ability to modify the entry.

ACLs are placed on a CaDict by creating a CaDict inside of the object __cb_acl__. In the case of a Casbah object this is done by creating a member of the object named __cb_acl__. ACLs must not be placed on scalars. In order to protect a scalar use "__cb_value__". See Casbah Access Model for more information.

User and Real Names

Usernames may contain any character in any character set, as all strings are UTF-8 or UTF-16 Unicode strings, except for the following characters:

[:, /, @]

Usernames must not begin with the string "--". These are reserved for internal use by the authentication system and Cairo.

Realms may contain any character in any character set except for the following characters:

[:, @]

Users

Usernames may contain any character in any character set except for the following ASCII/UTF-8 characters:

[:, /, @]

A realm must store its users in a CaDict named "users". This CaDict must be stored directly inside the realm.

The "users" table must use the username as the key and a CaDict as the value which holds other key/value pairs for other information. The subtable for a user's information may contain the following keys:

Table 4. User Information Keys

Name

Datatype

Meaning

full-name

CaString

The user's full name, a string which could be presented to the user: instead of "joe", "Joe Brown".

password

CaString

The user's password. This should be a heavy-weight CaString allowing an ACL setting to protect the password. This password is the result from encryptPassword().

home-table

CaSymLink

A pointer to the user's "home table". This can either be read or used directly to access their home table.

Groups

Groups may contain any character in any character set except for the following ASCII/UTF-8 characters:

[:, /, @]

Groups are denoted by the form "user:group" where user is a string that may be 0 or more characters long. Groups may be used in place of the username in an ACL. For example, "joe" could have the group "friends". If "joe" was in the realm "students", the group's offical full name would be "joe:friends@students".[3]

Each user must be allowed to create and manage their own groups. These groups must be stored in the realm's object instance under the name "groups". The group name must be "user:group", so the group "joe:friends" must be stored in the realm's object instance under "groups/joe:friends". System groups, (those managed by a realm's owner/manager/administrator) must have a 0 length user name. These system groups must be stored in the realm's object instance inside the member variable "groups". For instance, the system group ":users" must be stored at "groups/:users". (In other words, user groups and system groups are stored in the same location in the same namespace.)

Groups are stored in a CaDict. This CaDict must contain two members, "users" and "groups". The value for each of these keys must be a CaList of CaStrings. Any user which is a member of a group must go in that group's "users" list. Any group which is a member of a group must go in that group's "groups" list. The lists may hold their elements in any order.

A realm may setup ACLs so that a user cannot modify his own group list. However, the realm must provide the ability to modify the group list through a "become-user" method which has privlages to edit the group list.[4]

Notes

[1]

In FOO below, "parent" means the parent of the object that the ACL belongs to, and "object" means the object that the ACL belongs to.

[2]

We recommend the use of a linked list of identity structures to make the necessary changes to user identities quick and easy.

struct user_ident
{
char *name;
char *realm;
char **groups;
int ngroups;
int malloc_groups;

struct user_ident *prev;
};

void supp_ident(struct user_ident **cident, char *_name, char *_realm,
char **_groups, int _ngroups)
{
struct user_ident *n;

n = (struct user_ident*)malloc(sizeof(struct user_ident));
memcpy(n,*cident,sizeof(struct user_ident));
n->malloc_groups = 0;
n->prev = *cident;
*cident = n;

if (_name && _realm)
{
n->name = _name;
n->realm = _realm;
}

if (_groups && _ngroups > 0)
{
n->groups = (char**)malloc((n->ngroups + _ngroups) * sizeof(char*));
memcpy(n->groups, n->prev->groups, n->ngroups * sizeof(char*));
memcpy(n->groups + n->ngroups, _groups, _ngroups * sizeof(char*));
n->ngroups += _groups;
n->malloc_groups = 0;
}
}

void unsupp_ident(struct user_ident **cident)
{
struct user_ident *n;
if ((*cident)->malloc_groups)
free((*cident)->groups);
n = (*cident)->prev;
free(*cident);
*cident = n;
}

[3]

This group notation is similar to AFS.

[4]

During authentication a user will have all of his group membership information loaded into memory for fast access. However, Cairo should subscribe to updates for the user's realm's group table. This way, should the user be added or deleted from a group, his group membership in memory can be updated immediately. This feature is not required, however it is strongly recommended that a Cairo server implement it.

PrevHome 
The Casbah Project: Security in CasbahUp