Writing Apps HOWTO

Revision as of 21:13, 22 February 2009

DazukoFS 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 DazukoFS. This document guides you though the DazukoFS userspace library interface, allowing a developer to build an application to take advantage of DazukoFS and implement online userspace file access control.

Since version 3.0.0 of DazukoFS, the provided C interface has been as follows:

registration function

dazukofs_handle_t dazukofs_open(const char *gname, int flags);

file access control functions

int dazukofs_get_access(dazukofs_handle_t hndl, struct dazukofs_access *acc);
int dazukofs_return_access(dazukofs_handle_t hndl, struct dazukofs_access *acc);

utility function

int dazukofs_get_filename(struct dazukofs_access *acc, char *buf, size_t bufsiz);

unregistration function

int dazukofs_close(dazukofs_handle_t hndl, int flags);

dazukofs_access structure

struct dazukofs_access {
    int fd;
    int deny;
    unsigned long pid;
};

When interfacing with DazukoFS, there are 3 things that an application will do:

1. register your application with DazukoFS
2. listen for file access events and allow or deny the accesses
3. unregister with DazukoFS

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 DazukoFS inteface you must include the dazukofs.h header file:

#include "dazukofs.h"

You will also need to include the libdazukofs.so userspace library into your project for compiling. You should take a look at the accompanying test program (showfiles.c) to see a working application. With the exception of dazukofs_open(), all DazukoFS functions return 0 on success.

1. register your application with DazukoFS

Registering with DazukoFS is very simple. It is done with the dazukofs_open function:

dazukofs_handle_t hndl = dazukofs_open("My_Group_Name", DAZUKOFS_TRACK_GROUP);
if (!hndl)
    printf("error registering\n");

DazukoFS 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, DazukoFS is not correctly loaded. Please refer to the installation instructions.

The second parameter specifies any special flags that may want to be used. The flag DAZUKOFS_TRACK_GROUP tells DazukoFS that the group should be automatically removed if there are no more registered processes for that group. If this flag is not used, a registered process is required to correctly remove the group when file access control is no longer desired.

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

Once you have registered with DazukoFS, 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...

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 DazukoFS, it should be requesting an access event. The entire system could be relying on it. (Note: Even if no applications are registered, but the group still exists, DazukoFS will assume that file access control is still desired and wait for an application to register to that group.)

To request an access event:

struct dazukofs_access acc;
if (dazukofs_get_access(hndl, &acc) != 0)
    printf("error getting access event\n");

Once you have an access event, you also have an open file descriptor to the file being accessed. The file descriptor is in the "fd" field of the dazukofs_access structure. Using the file descriptor, your application can investigate the contents of the file being accessed.

A utility function dazukofs_get_filename() is available in case your application is interested in the filename of the file being accessed.

It is the job of your application to clear or set the deny flag if access should or should not be allowed, respectively. Then the application must give the dazukofs_access struct back to the kernel. Returning the access will also close the file descriptor.

To return an access event to the kernel:

acc.deny = 0; /* allow access */

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

3. unregister with DazukoFS

When your application no longer wishes to handle file access control, it must unregister with DazukoFS. This will relieve the application of its big responsibilities.

if (dazukofs_close(hndl, DAZUKOFS_REMOVE_GROUP) != 0)
     printf("error unregistering\n");

The DAZUKOFS_REMOVE_GROUP flag tells DazukoFS to remove the group. If other applications are registered with this group, their dazukofs_get_access() and dazukofs_return_access() will return errors (since the group no longer exists).