acps_spi(3)						     Library Functions Manual						       acps_spi(3)

NAME

       acps_spi:  acpm_getenvattrs(),  acpm_getobj(), acpm_getobjattrs(), acpm_getop(), acpm_getopattrs(), acpm_getsubattrs(), acpm_getsubcreds(),
       acpm_getsubid() - ACPS Service Provider Interface

SYNOPSIS

       [flag]... file... [library]...

DESCRIPTION

       The ACPS Service Provider Interface makes it possible to define a custom module that responds to access control requests.  This	module	is
       typically written either to enforce a custom policy, or to interface to another system that defines such a policy.  By creating this module
       and inserting an appropriate entry into the file, all access control requests made by applications that support the Access  Control  Policy
       Switch will automatically be routed to the module, without modifying the applications.

       The  service  provider (module) interface is primarily composed of a well-defined routine that each module must provide and a set of helper
       routines provided by the switch to encode and decode information into the opaque handle.

       The single interface provided by each module is defined as follows:

       The handle contains all of the request information.  The argv argument contains an array of elements, each representing an argument  speci-
       fied  in  the  ACPS configuration file entry for the module (see below).  The module return values match exactly the API return values with
       the option of an additional value indicating that no access information is available for the given request

       In order for the module to retrieve information from the handle about the access control request, the switch provides the following set	of
       helper routines to extract the desired information, described in

       Note  that  these routines are very similar to the API routines except that the multi-value attributes are returned as a linked list rather
       than requiring individual routines.  The practical reason for this is that it allows greater flexibility in manipulating the attribute data
       based on the needs of the module.

       In  the	same  way  that  an application can retrieve the credential requested by a module, (see acps_api(3)), the module has the following
       interface to encode this information into the handle:

       A module would typically use this in the event that the application did not present the required  credential.   It  is  expected  that  the
       application will add the necessary information and repeat the call to

RETURN VALUE

       The values returned by the ACPS SPI (as well as the ACPS API) are defined in acps(3).

EXAMPLES

       The following example illustrates a sample policy module that enforces the policy:

	      "users Ron, Ren, and Bill may read or write the password object"

       #include <acps_spi.h>
       #include <stdio.h>

       extern int acpm_checkauth(acp_handle_t h, int argc, const char **argv)
       {
	   char *user;
	   char *operation;
	   char *object;
	   char *buf;
	   int retval;

	   // get the user
	   if((retval = acpm_getsubid(h, buf, &user)) != ACPS_SUCCESS)
	       return retval;
	   if(strcmp(buf, ACPS_ID_NAME) != 0) // type validation
	       return ACPS_GEN_ERROR;

	   // get the operation
	   if((retval=acpm_getop(h, buf, &operation)) != ACPS_SUCCESS)
	       return retval;
	   if(strcmp(buf, ACPS_OP_DOTHEIRARCHICAL) != 0)
	       return ACPS_GEN_ERROR;

	   // get the object
	   if((retval = acpm_getobj(h, buf, &object)) != ACPS_SUCCESS)
	       return retval;
	   if(strcmp(buf, ACPS_OBJ_GENERIC) != 0)
	       return ACPS_GEN_ERROR;

	   // evaluate primitives against policy
	   if(	(   (strcmp(user, "Ron") == 0)
		 || (strcmp(user, "Ren") == 0)
		 || (strcmp(user, "Bill") == 0))
	      &&(   (strcmp(operation, "read") == 0)
		 || (strcmp(operation, "write") == 0))
	      &&(strcmp(object, "password"))) {
		    return ACPS_ALLOW;
	   }
	   else {
		return ACPS_DENY;
	   }
       }

SEE ALSO

       acps(3), acps_api(3).

																       acps_spi(3)