Writing Apps HOWTO

Dazuko alone simply adds file access control capabilities to your kernel. However, to make use of these capabilities you need an application that will interact with Dazuko. This document guides you though the Dazuko interface, allowing a developer to build an application to take advantage of Dazuko and implement 3rd party file access control.

Dazuko currently has interfaces implemented in C, Java, Perl, Python, Lua, and PHP. Please look in the respective example_<language> directories for example programs utilizing these interfaces. The interface has been implemented to be the same for all languages (except for minor differences to allow for a natural feel in the language).

Since version 2.0.0 of Dazuko, the provided C interface has been as follows:

registration function

int dazukoRegister(const char *groupName, const char *mode);

configuration functions

int dazukoSetAccessMask(unsigned long accessMask);
int dazukoAddIncludePath(const char *path);
int dazukoAddExcludePath(const char *path);
int dazukoRemoveAllPaths(void);

file access control functions

int dazukoGetAccess(struct dazuko_access **acc);
int dazukoReturnAccess(struct dazuko_access **acc);

unregistration function

int dazukoUnregister(void);

access structure

struct dazuko_access
{
     int deny;
     int event;
     char set_event;
     int flags;
     char set_flags;
     int mode;
     char set_mode;
     int uid;
     char set_uid;
     int pid;
     char set_pid;
     char *filename;
     char set_filename;
     unsigned long file_size;
     char set_file_size;
     int file_uid;
     char set_file_uid;
     int file_gid;
     char set_file_gid;
     int file_mode;
     char set_file_mode;
     int file_device;
     char set_file_device;
};

A thread-safe version of the interface is also available. The functions are the same except that they end with _TS and take an addition dazuko_id_t argument. Please see the example_mt.c program for details.

When interfacing with Dazuko, there are 4 things that an application will do:

1. register your application with Dazuko
2. set various Dazuko configuration options
3. listen for file access events and allow or deny the accesses
4. unregister with Dazuko

Each of these items will be discussed along with actual C code snippets to give you an idea of how it works. In order to have access to the Dazuko inteface you must include the dazukoio.h file:

#include "dazukoio.h"

You will also need to include the dazukoio.c and dazukoio_compat12.c files into your project for compiling. You should take a look at the accompanying example program (example.c) to see a working application. All Dazuko interface functions return 0 on success.

1. register your application with Dazuko

Registering with Dazuko is very simple. It is done with the dazukoRegister function:

if (dazukoRegister("My Group Name", "r+") != 0)
     printf("error registering\n");

Dazuko supports different applications simultaneously (cascading) and groups them by name. Each different application should use its own group name, however multiple instances of the same application should use the same group name. This allows you to have many instances working together simultaneouly in order to take advantage of your multi-processing operating system. If this function fails, then Dazuko is not correctly loaded. Please refer to the installation instructions.

The second parameter specifies the mode in which the application will interact with Dazuko. There are currently two modes available, read-only "r" and read-write "r+". The read-only mode allows an application to receive all accesses but does not give the application an opportunity to decide if the access should be allowed or not. Applications that only deal with collecting information (specialized loggers, for example) will never need to determine if the access should be allowed. The benefit of using the read-only mode is that the responsibilities of the application have been reduced, not requiring an answer to every access. Applications that do not require access control are encouraged to use this mode.

Read-write mode is the mode that has always been supported by Dazuko. Each time an application receives an access, it must reply whether or not the access should be allowed. Access control applications must use this mode. Section 3 will explain these responsibilities in more detail.

2. set various Dazuko configuration options

Each configuration option is set using a specific Dazuko function. The various options that are available are to: 1) set the access mask (any combination of various accesses that should be intercepted), 2) set the include paths (the paths from which file accesses will be handled), 3) set exclude paths (paths within the include paths that should not be handled) and 4) clear all set paths. Examples will now be given showing how to set the different configuration options.

To set the access mask (in this case to intercept all possible file access types):

if (dazukoSetAccessMask(ON_OPEN
          | ON_CLOSE
          | ON_CLOSE_MODIFIED
          | ON_EXEC
          | ON_UNLINK
          | ON_RMDIR) != 0)
{
     printf("error setting access mask\n");
}

To add an include path (in this case /home/):

if (dazukoAddIncludePath("/home/") != 0)
     printf("error adding include path\n");

You can have multiple include paths, but you must add each path separately. Dazuko does not have a limit on the number of include paths. Keep in mind that all sub-directories of an include path are also included.

To add an exclude path (in this case /home/foo/):

if (dazukoAddExcludePath("/home/foo/") != 0)
     printf("error adding exclude path\n");

You can have multiple exclude paths, but you must add each path separately. Dazuko does not have a limit on the number of exclude paths. Keep in mind that all sub-directories of an exclude path are also excluded. Exclude paths are considered superior rules to include paths. That means if you add an include path that is within an exclude path, the file accesses in the directory will still be excluded.

To remove all set paths:

if (dazukoRemoveAllPaths() != 0)
     printf("error removing all paths\n");

3. listen for file access events and allow or deny the accesses

Once you have added an include path and some sort of access mask, the responsibilities put on your application become very great! At this point the kernel will assume that you are taking responsibility for file access control. For each file access that meets the access mask and include path constraints, the kernel will wait for your application to approve the access. This is done in a passive manner. The application must request an access event and will block until the kernel has one to give. Then the kernel will give the action event to the application. The application must decide if the access should be allowed or not and then reply to the kernel if the access should be allowed or not. The application should then request another access event and so on...

Once an application has set some configuration options with Dazuko, the kernel will assume the application is ready to take on its responsibility. If the application does not do its job of requesting an access event, the kernel will patiently wait (forever if necessary) until the application finally does request a file. For this reason it is important to understand that as long as an application is registerd with Dazuko, it should be requesting an access event. The entire system could be relying on it.

Applications that have registered in read-only mode have a reduced set of responsibilities. Although it is important that the application is always requesting an access event, in read-only mode the kernel does not wait for a response. This relieves half of the responsibilities of the application, but also only allows the application to collect information. Applications that will not be doing access control are encouraged to use read-only mode.

To request an access event:

struct dazuko_access *acc;

if (dazukoGetAccess(&acc) != 0)
     printf("error getting access event\n");

Once you have an access event, you can investigate the various attributes of the access. These attributes were filled in by the kernel into the dazuko_access structure. Attributes which were not acquired (or are not valid for this particular access) have their corresponding set_ flag set to 0, otherwise 1. The dazuko_access structure can be seen at the top of this page.

If registered in read-write mode, the job of your application is to clear or set the deny flag if access should or should not be allowed, respectively. Then the application must give the dazuko_access struct back to the kernel.

Even applications registered in read-only mode should return the access. The dazuko_access structure was allocated when dazukoGetAccess was called. Returning the access will free up this memory, even if in read-only mode nothing is truly returned to the kernel. It is also good practice to return access events, rather than trying to free the structure yourself.

To return an access event to the kernel:

acc->deny = 0; /* allow access */

if (dazukoReturnAccess(&acc) != 0)
     printf("error returning access event\n");

4. unregister with Dazuko

When your application no longer wishes to handle file access control, it must unregister with Dazuko. This will relieve the application of its big responsibilities. Even in read-only mode it is critical that an application properly unregisters.

if (dazukoUnregister() != 0)
     printf("error unregistering\n");