In the meantime, here's what I've come up with. First off, I'm developing this in a CGI prototype environment, so here's a user authentication function. This function will take a single XML tag which has the CGI environment as attributes of the tag (which is how I'm handling the CGI environment in wftk, of course.) It returns NULL if the user is not authenticated (either the user is wrong or the wrong password is given); otherwise it loads the user from the user repository and returns the XML structure of the user. If NULL is returned, it emits a user authentication header to stdout. Presumptuous, but it will work in the prototype just fine. XML * user_authenticate (XML * cgi_environment, const char * realm); Next we have some basic stuff for getting users and such. The user_exists function simply checks the repository to see whether a named user is in there. Then there are get and save functions for users. These come in two varieties: the plain-vanilla just gets/saves a user, but the "auth" variety checks the current user's permissions to ensure that the operation is allowed. int user_exists (const char *username); XML * user_get (const char * username); int user_save (XML * user); XML * user_auth_get (const char * username, XML * current_user); int user_auth_save (XML * user, XML * current_user); And then the same stuff for groups. int group_exists (const char *groupname); XML * group_get (const char * groupname); int group_save (XML * group); XML * group_auth_get (const char * groupname, XML * current_user); int group_auth_save (XML * group, XML * current_user); We need functions to manipulate group contents: to add a user, we use user_join and to remove a user, we use user_leave. Adding and removing objects should really be considered granting and revoking permissions, so that is reflected in the nomenclature. And finally, we have functions to link and unlink groups to one another. int user_join (XML * user, XML * group); int user_leave (XML * user, XML * group); int object_grant (XML * user_or_group, const char * class, const char * object, const char * permission); int object_revoke (XML * user_or_group, const char * class, const char * object, const char * permission); int group_include (XML * outgroup, XML * ingroup, const char * permission); int group_unlink (XML * outgroup, XML * ingroup, const char * permission); And finally, we have a function which is basically the whole point of the exercise: user_perm queries the user's permission to a given object. This assumes that the user is already loaded. Note that in cases where user and group information is loaded and cached, some method will be necessary for invalidating cached permission information. That can come later, of course. We have a variant on user_perm called user_perm_group where we don't have an object class or name, just a group which owns it. Otherwise it works the same. int user_perm (XML * user, const char * class, const char * object, const char * permission); int user_perm_group (XML * user, const char * groupname, const char * permission); Well, in retrospect that wasn't very final. I also need some functionality to list objects and permissions. XML * user_list (XML * user, const char * class, const char * object, const char * permission); void user_expand (XML * list_or_group); void user_expandall (XML * list_or_group); 10/1/00 A quick little recursive function to find all the groups in which a user is a member. And the converse, too, but in two flavors: one just returns keys, the other more information than that. void user_groups_list (XML * user, XML * holder, const char * permission); void group_users_list (XML * group, XML * holder, const char * permission); void group_users_list_detailed (XML * group, XML * holder, const char * permission); #endif OK, so we've defined what we're doing -- now how are we going to do it? I thought you'd never ask. #include #include #include #include "user.h" #include "../localdefs.h" /* ------------------------------------------------------------------ */ /* user.c */ /* This implements the user and group API for wftk. */ /* ------------------------------------------------------------------ */ OK, here goes. Follow the links below to see implementations. In this implementation, anyway, checking for the existence of a user or a group is as simple as checking the repository directory for the named file. int user_exists(const char * user) { char buf[1024]; FILE * file; sprintf (buf, "%s%s", USER_REPOSITORY, user); file = fopen (buf, "r"); if (file) { fclose (file); return 1; } return 0; } int group_exists(const char * group) { char buf[1024]; FILE * file; sprintf (buf, "%s%s", GROUP_REPOSITORY, group); file = fopen (buf, "r"); if (file) { fclose (file); return 1; } return 0; } Given the simplicity of the xmlapi, most of this is pretty easy. However, the fact that we're using the user module to authorize access to users makes it interestingly recursive. But looking at the auth versions of the get and save functions, we can see an excellent example of how to use the module. XML * user_get (const char * username) { char buf[1024]; FILE * file; XML * ret; if (!strcmp (username, "anonymous")) { ret = xml_create ("user"); xml_set (ret, "name", "anonymous"); return (ret); } sprintf (buf, "%s%s.xml", USER_REPOSITORY, username); file = fopen (buf, "r"); if (!file) return NULL; ret = xml_read (file); fclose (file); return (ret); } int user_save (XML * user) { char buf[1024]; FILE * file; sprintf (buf, "%s%s.xml", USER_REPOSITORY, xml_attrval (user, "name")); file = fopen (buf, "w+"); if (!file) return 1; xml_write (file, user); fclose (file); return (0); } XML * group_get (const char * groupname) { char buf[1024]; FILE * file; XML * ret; sprintf (buf, "%s%s.xml", GROUP_REPOSITORY, groupname); file = fopen (buf, "r"); if (!file) { ret = xml_create ("group"); xml_set (ret, "name", groupname); return (ret); } ret = xml_read (file); fclose (file); return (ret); } int group_save (XML * group) { char buf[1024]; FILE * file; sprintf (buf, "%s%s.xml", GROUP_REPOSITORY, xml_attrval (group, "name")); file = fopen (buf, "w+"); if (!file) return 1; xml_write (file, group); fclose (file); return (0); } These are simply some extremely simple wrappers around the xmlapi functionality used to make the specified changes. When a user joins a group, then a link is made in both directions. Just in case the join is redundant (in either direction) we scan both user and group for membership before appending the link.

Note that this only affects structures in memory; the calling app has to know when to save both structures back to the repository. Note further that there is absolutely no locking going on here. Eventually we might want to address this issue in some way (otherwise it will eventually cause us to wish that we had already addressed it...) int user_join (XML * user, XML * group) { XML * child; child = xml_firstelem (group); while (child) { if (!strcmp (child->name, "user")) if (!strcmp (xml_attrval (child, "name"), xml_attrval (user, "name"))) goto ensure_group; child = xml_nextelem (child); } child = xml_create ("user"); xml_set (child, "name", xml_attrval (user, "name")); xml_append (group, child); ensure_group: child = xml_firstelem (user); while (child) { if (!strcmp (child->name, "group")) if (!strcmp (xml_attrval (child, "name"), xml_attrval (group, "name"))) return 0; child = xml_nextelem (child); } child = xml_create ("group"); xml_set (child, "name", xml_attrval (group, "name")); xml_append (user, child); return 0; } When a user leaves a group, then, the links in both directions must be removed. int user_leave (XML * user, XML * group) { XML * child; child = xml_firstelem (group); while (child) { if (!strcmp (child->name, "user")) { if (!strcmp (xml_attrval (child, "name"), xml_attrval (user, "name"))) { xml_delete (child); child = xml_firstelem (group); } } child = xml_nextelem (child); } child = xml_firstelem (user); while (child) { if (!strcmp (child->name, "group")) { if (!strcmp (xml_attrval (child, "name"), xml_attrval (group, "name"))) { xml_delete (child); child = xml_firstelem (user); } } child = xml_nextelem (child); } } Permission granting is an easier task, since object inclusion only goes one way (there is no object repository; groups know that they hold objects, but the objects have to ask.)

Note that we don't really care whether we're given a user or a group to add the permission to; they work the same way, and the xmlapi doesn't care. int object_grant (XML * user_or_group, const char * class, const char * object, const char * permission) { XML * child; child = xml_firstelem (user_or_group); while (child) { if (!strcmp (child->name, "object")) if (!strcmp (xml_attrval (child, "class"), class) #^7#^7 !strcmp (xml_attrval (child, "object"), object) #^7#^7 !strcmp (xml_attrval (child, "permission"), permission)) return 0; child = xml_nextelem (child); } child = xml_create ("object"); xml_set (child, "class", class); xml_set (child, "object", object); xml_set (child, "permission", permission); xml_append (user_or_group, child); return 0; } Revocation is a little different. If a NULL is passed in for object or for permission, it matches anything. (You can't do the same for classes. Sorry.)

Revocation is not recursive. That is, if I revoke viewer privilege for a user, one of the user's group memberships might still result in viewer privileges. I'm not sure if this is a bug or a feature, but it is at least documented. int object_revoke (XML * user_or_group, const char * class, const char * object, const char * permission) { XML * child; int ok; child = xml_firstelem (user_or_group); while (child) { if (!strcmp (child->name, "object") #^7#^7 !strcmp (xml_attrval (child, "class"), class)) { ok = 0; if (!object) ok = 1; if (!ok) if (!strcmp (xml_attrval (child, "object"), object)) ok = 1; if (ok) { ok = 0; if (!permission) ok = 1; if (!ok) if (!strcmp (xml_attrval (child, "permission"), permission)) ok = 1; if (ok) { xml_delete (child); child = xml_firstelem (user_or_group); } } } child = xml_nextelem (child); } } Group links are also two-way, and are decorated with the permission level being granted to the containing group. So these functions kind of combine the complexity of the other functions above.

Group inclusion int group_include (XML * outgroup, XML * ingroup, const char * permission) { XML * child; child = xml_firstelem (outgroup); while (child) { if (!strcmp (child->name, "group-include")) if (!strcmp (xml_attrval (child, "name"), xml_attrval (ingroup, "name")) #^7#^7 !strcmp (xml_attrval (child, "permission"), permission)) goto ensure_ingroup; child = xml_nextelem (child); } child = xml_create ("group-include"); xml_set (child, "name", xml_attrval (ingroup, "name")); xml_set (child, "permission", permission); xml_append (outgroup, child); ensure_ingroup: child = xml_firstelem (ingroup); while (child) { if (!strcmp (child->name, "group-included-by")) if (!strcmp (xml_attrval (child, "name"), xml_attrval (outgroup, "name")) #^7#^7 !strcmp (xml_attrval (child, "permission"), permission)) return 0; child = xml_nextelem (child); } child = xml_create ("group-included-by"); xml_set (child, "name", xml_attrval (outgroup, "name")); xml_set (child, "permission", permission); xml_append (ingroup, child); return 0; } As with object_revoke above, int group_unlink (XML * outgroup, XML * ingroup, const char * permission) { XML * child; int ok; child = xml_firstelem (outgroup); while (child) { if (!strcmp (child->name, "group-include") #^7#^7 !strcmp (xml_attrval (child, "name"), xml_attrval (ingroup, "name"))) { ok = 0; if (!permission) ok = 1; if (!ok) if (!strcmp (xml_attrval (child, "permission"), permission)) ok = 1; if (ok) { xml_delete (child); child = xml_firstelem (outgroup); } } child = xml_nextelem (child); } child = xml_firstelem (ingroup); while (child) { if (!strcmp (child->name, "group-included-by") #^7#^7 !strcmp (xml_attrval (child, "name"), xml_attrval (outgroup, "name"))) { ok = 0; if (!permission) ok = 1; if (!ok) if (!strcmp (xml_attrval (child, "permission"), permission)) ok = 1; if (ok) { xml_delete (child); child = xml_firstelem (ingroup); } } child = xml_nextelem (child); } } User authentication in the CGI environment is fairly straightforward; we take the WWW-Authenticate header from the environment, decode it, load the named user, and check the password. If there is no such header, if the user doesn't exist, or if the password doesn't match, then we emit a 403 response header, and return a NULL to the program. If all goes well, then we simply return the user structure which we loaded. XML * user_authenticate(XML * cgi_env, const char * realm) { XML * ret; char username[512]; char * password; _base64decode (username, xml_attrval (cgi_env, "HTTP_AUTHORIZATION") + 6); password = strchr (username, ':'); if (password) *password++ = '\0'; else password = ""; ret = user_get (username); if (ret) { if (!strcmp (password, xml_attrval (ret, "password"))) return (ret); xml_free (ret); } printf ("Status: 401 Authentication required\n"); printf ("WWW-Authenticate: BASIC realm=\"%s\"\n\n", realm); return NULL; } Base-64 encoding is pretty cool, when you look at it. It uses 64 printable characters; note that 64 is 2^6; that is, you can encode six bits of data in one base-64 character. Thus 24 bits of data is four characters, meaning that three bytes of binary data correspond to four base-64 characters. Decoding therefore naturally looks at four characters at a time; often the encoding will be padded with an '=' if there aren't three bytes of data, but that's not a particularly safe assumption to make while decoding.

Effectively what we're doing during this conversion is converting to base 2^24, then breaking things up into bytes. void _base64decode (char * buf, const char * encoded) { int bytes = 0; unsigned long chunk = 0; unsigned long remainder = 0; repeat: while (*encoded && bytes < 4) { if (*encoded == '=') chunk = chunk * 64; else if (*encoded > 96) chunk = chunk * 64 + (*encoded - 71); else if (*encoded > 64) chunk = chunk * 64 + (*encoded - 65); else if (*encoded > 47) chunk = chunk * 64 + (*encoded + 4); else if (*encoded == 43) chunk = chunk * 64 + 62; else if (*encoded == 47) chunk = chunk * 64 + 63; else chunk = chunk * 64; bytes ++; encoded ++; } bytes = 2; while (chunk > 0 #^7#^7 bytes > -1) { remainder = chunk % (1 << (bytes * 8)); *buf++ = (chunk - remainder) / (1 << (bytes * 8)); chunk = remainder; bytes--; } bytes = 0; if (*encoded) goto repeat; *buf = '\0'; } I nearly forgot to include this function in the API -- isn't that weird? Anyway, the whole point of all the preceding work is to be able to ask of a given user and a given object, whether the user has permission to a given action on that object. To determine this, we'll walk the user and group trees until we find the object (or don't) and a permission level which matches.

I've decided that rather than leave the permissions completely open to module interpretation, it will be simpler to define a couple right at the outset: "own" means automaticallly that the user gets any permission. "write" is greater than "view", and those two are the only official permissions defined. (I.e. if I have write permission, and the question is whether I may view an object, then the answer is always "yes". That might be a little too simple, but I think in practice it will work.)

Note that since permissions are completely arbitrary strings, a module is perfectly free to define anything at all as a permission. For the wftk, "activate" makes a lot of sense as a permission, for instance. It's just that the user module won't know anything special about those permissions.

This is by far our most complicated function.

There are three things which are "magic" about permissions. First is that permission "own" qualifies you for any permission. Second is that group "admin" has "own" on everything. Third is that everybody belongs to group "everybody", so that granting some privilege to group "everybody" makes that privilege public. And fourth (OK, so I thought up another one during subsequent development) -- as I was saying, fourth is that any permission at all is sufficient for "view". int user_perm (XML * user, const char * class, const char * object, const char * permission) { XML * group; XML * child; child = xml_firstelem (user); while (child) { if (!strcmp (child->name, "object")) { if (!strcmp (xml_attrval (child, "class"), class) #^7#^7 !strcmp (xml_attrval (child, "object"), object)) { if (_user_perm_cmp (xml_attrval (child, "permission"), permission)) return (1); } } else if (!strcmp (child->name, "group")) { if (!strcmp (xml_attrval (child, "name"), "admin")) return (1); group = group_get (xml_attrval (child, "name")); if (group) { if (user_perm (group, class, object, permission)) { xml_free (group); return (1); } xml_free (group); } } else if (!strcmp (child->name, "group-include")) { if (_user_perm_cmp (xml_attrval (child, "permission"), permission)) { group = group_get (xml_attrval (child, "name")); if (group) { if (user_perm (group, class, object, permission)) { xml_free (group); return (1); } xml_free (group); } } } child = xml_nextelem (child); } if (strcmp (user->name, "group") #^7#^7 strcmp (xml_attrval (user, "name"), "everybody")) { group = group_get ("everybody"); if (group) { if (user_perm (group, class, object, permission)) { xml_free (group); return (1); } xml_free (group); } } return (0); } Now the variant, user_perm_group, which just takes the name of a group which owns the object in question. (Thus having the named permission on the group will automatically count as having (at least) that permission on the object.) This saves a great deal of overhead if we can assume that objects always are owned by single groups, which works well for the task manager. int user_perm_group (XML * user, const char * groupname, const char * permission) { XML * group; XML * child; if (!strcmp (groupname, "everybody")) return (1); if (!strcmp (groupname, "")) return (1); child = xml_firstelem (user); while (child) { if (!strcmp (child->name, "group")) { if (!strcmp (xml_attrval (child, "name"), "admin")) return (1); if (!strcmp (xml_attrval (child, "name"), groupname)) return (1); group = group_get (xml_attrval (child, "name")); if (group) { if (user_perm_group (group, groupname, permission)) { xml_free (group); return (1); } xml_free (group); } } else if (!strcmp (child->name, "group-include")) { if (_user_perm_cmp (xml_attrval (child, "permission"), permission)) { if (!strcmp (xml_attrval (child, "name"), groupname)) return (1); group = group_get (xml_attrval (child, "name")); if (group) { if (user_perm_group (group, groupname, permission)) { xml_free (group); return (1); } xml_free (group); } } } child = xml_nextelem (child); } if (strcmp (user->name, "group") #^7#^7 strcmp (xml_attrval (user, "name"), "everybody")) { group = group_get ("everybody"); if (group) { if (user_perm_group (group, groupname, permission)) { xml_free (group); return (1); } xml_free (group); } } return (0); } OK, we need to mop up some details now. First, let's formalize that comparison between permissions: if the user has "own", then the user has any permission. If the permissions are the same, the user has permission. Otherwise, no permission. int _user_perm_cmp (const char * perm1, const char * permission) { if (!strcmp (perm1, "own")) return (1); if (!strcmp (perm1, permission)) return (1); if (!strcmp (permission, "view")) return (1); return (0); } Um... OK, that was all the help I needed, I guess. In order to present nice menus and show our neat-o little folder system, we want a listing facility. The first step in listing things is the user_list function, which (given a user or group) produces a <user_list> XML structure. As usual, if any of the strings is NULL, that counts as a wildcard. I'm also including "." as a wildcard, as I don't expect classes, objects, or permissions named "." would be very useful anyway. void _user_add_to_list (XML * ret, XML * user, const char * class, const char * object, const char * permission) { XML * child; XML * piece; int ok; child = xml_firstelem (user); while (child) { if (!strcmp (child->name, "object")) { if ((!strcmp (class, ".") || !strcmp (class, xml_attrval (child, "class"))) #^7#^7 (!strcmp (object, ".") || !strcmp (object, xml_attrval (child, "object"))) #^7#^7 (!strcmp (permission, ".") || _user_perm_cmp (xml_attrval (child, "permission"), permission))) { piece = xml_create ("object"); xml_set (piece, "class", xml_attrval (child, "class")); xml_set (piece, "object", xml_attrval (child, "object")); xml_set (piece, "permission", xml_attrval (child, "permission")); xml_append (ret, piece); } } else if (!strcmp (child->name, "group-include")) { if (!strcmp (permission, ".") || _user_perm_cmp (xml_attrval (child, "permission"), permission)) { piece = xml_create ("group-include"); xml_set (piece, "name", xml_attrval (child, "name")); xml_set (piece, "permission", xml_attrval (child, "permission")); xml_append (ret, piece); } } else if (!strcmp (child->name, "group")) { piece = group_get (xml_attrval (child, "name")); if (piece) { _user_add_to_list (ret, piece, class, object, permission); xml_free (piece); } } child = xml_nextelem (child); } } XML * user_list (XML * user, const char * class, const char * object, const char * permission) { XML * ret; ret = xml_create ("user_list"); _user_add_to_list (ret, user, class ? class : ".", object ? object : ".", permission ? permission : "."); return (ret); } The next trick is to be able to list the groups to which a user belongs (regardless of permission level). This stashes everything into a flat list, from which it can be printed or whatever. As there's nothing in our group structure that prevents cycles, this function is rather paranoid when adding something to the list -- it checks to make sure it's not already there. This will have the salacious effect of not looping forever if there is a cycle.

The optional permission allows us to get a list of groups to which a user has a certain permission level. Groups to which the user actually belongs count as 'own' permission. Thus objects in that group are owned by the user. void user_groups_list (XML * user, XML * holder, const char * permission) { XML * elem; XML * check; XML * newone; XML * group; if (!permission) permission = "view"; if (!*permission) permission = "view"; elem = xml_firstelem (user); while (elem) { if (!strcmp (elem->name, "group") || (!strcmp (elem->name, "group-include") && _user_perm_cmp (xml_attrval (elem, "permission"), permission))) { check = xml_firstelem (holder); while (check) { if (!strcmp (xml_attrval (check, "name"), xml_attrval (elem, "name"))) break; check = xml_nextelem (check); } if (!check) { group = group_get (xml_attrval (elem, "name")); if (group) { newone = xml_create ("group"); xml_set (newone, "name", xml_attrval (elem, "name")); xml_set (newone, "label", xml_attrval (elem, "label")); if (!*xml_attrval (newone, "label")) xml_set (newone, "label", xml_attrval (elem, "name")); xml_append (holder, newone); user_groups_list (group, holder, permission); } xml_free (group); } } elem = xml_nextelem (elem); } } To list users, we do pretty much the same thing as listing groups, except that we recurse along group-included-by instead of group-include. This recursion happens in this little helper function, which also tosses the groups visited into the list -- then our actual list routines can call this, and afterwards go through and delete those markers before returning the final list. void _group_users_search (XML * group, XML * holder, const char * permission) { XML * elem; XML * check; XML * newone; XML * othergroup; if (!permission) permission = "view"; if (!*permission) permission = "view"; elem = xml_firstelem (group); while (elem) { if (!strcmp (elem->name, "group-included-by") && _user_perm_cmp (xml_attrval (elem, "permission"), permission)) { check = xml_firstelem (holder); while (check) { if (!strcmp (check->name, "group") && !strcmp (xml_attrval (check, "name"), xml_attrval (elem, "name"))) break; check = xml_nextelem (check); } if (!check) { othergroup = group_get (xml_attrval (elem, "name")); if (othergroup) { newone = xml_create ("group"); xml_set (newone, "name", xml_attrval (elem, "name")); xml_append (holder, newone); _group_users_search (othergroup, holder, permission); } xml_free (othergroup); } } if (!strcmp (elem->name, "user")) { check = xml_firstelem (holder); while (check) { if (!strcmp (check->name, "user") && !strcmp (xml_attrval (check, "name"), xml_attrval (elem, "name"))) break; check = xml_nextelem (check); } if (!check) { newone = xml_create ("user"); xml_set (newone, "name", xml_attrval (elem, "name")); xml_append (holder, newone); } } elem = xml_nextelem (elem); } } So OK, let's define our actual functions now. void group_users_list (XML * group, XML * holder, const char * permission) { XML * elem; _group_users_search (group, holder, permission); elem = xml_firstelem (holder); while (elem) { if (!strcmp (elem->name, "group")) { xml_delete (elem); elem = xml_firstelem (holder); } else { elem = xml_nextelem (elem); } } } void group_users_list_detailed (XML * group, XML * holder, const char * permission) { XML * elem; XML * user; ATTR * attr; group_users_list (group, holder, permission); elem = xml_firstelem (holder); while (elem) { user = user_get (xml_attrval (elem, "name")); if (user) { attr = user->attrs; while (attr) { xml_set (elem, attr->name, attr->value); attr = attr->next; } xml_free (user); } elem = xml_nextelem (elem); } } So let's take a look at a fairly simple program which uses the user module. This will be a convenient little user maintenance utility and simultaneously serve as a good test case.

Usage will be as follows:
user[.exe] <command> <arguments>:

• newuser <username> <password>
• password <username> <password>
• auth <username> <password>
• newgroup <groupname>
• join <username> <groupname>
• leave <username> <groupname>
• grantuser <username> <class> <object> <privilege>
• revokeuser <username> <class> <object> <privilege>
• grantgroup <groupname> <class> <object> <privilege>
• revokegroup <groupname> <class> <object> <privilege>
• perm <user> <class> <object> <privilege>
• permgroup <user> <group> <privilege>
• user <username>
• listuser <username>
• group <groupname>
• groups <username> returns a list of groups
• users <username> returns a list of user keys for a group
• userlist <username> returns a list of user key:fullname:email for a group
• list <username> <class> <object> <permission>