acps_api(3)

NAME

acps_api: acps_addenvattr(), acps_addobjattr(), acps_addopattr(), acps_addsubattr(), acps_addsubcred(), acps_checkauth(), acps_end(), acps_setobj(), acps_setop(), acps_setsubid(), acps_start() — ACPS Application Programming Interface

SYNOPSIS

#include <acps.h>

#include <acps_api.h>

cc [flag]... file... -lacps [library]...

int acps_addenvattr( acp_handle_t h, char *type, char *attr);

int acps_addobjattr( acp_handle_t h, char *type, char *attr);

int acps_addopattr( acp_handle_t h, char *type, char *attr);

int acps_addsubattr( acp_handle_t h, char *type, char *attr);

int acps_addsubcred( acp_handle_t h, char *type, char *attr);

int acps_checkauth( acp_handle_t h);

int acps_end( acp_handle_t h);

int acps_setobj( acp_handle_t h, char *type, char *object);

int acps_setop( acp_handle_t h, char *type, char *operation);

int acps_setsubid( acp_handle_t h, char *type, char *ident);

int acps_start( acp_handle_t h);

DESCRIPTION

The ACPS Application Programming Interface (API) defines a set of functions that an application writer can use to perform an access control check. This check is typically used to determine whether a particular user has access to a resource.

The ACPS API provides both a simplified interface for requesting an access check and a more flexible interface that allows an application to specify additional access control attributes. For both interfaces, the basic access control request takes the form:

Is subject X allowed to perform operation Y on object Z?

This request is formed using different functions depending on the application requirements.

Simplified Interface

In the simplified interface, this basic question is represented as follows:

int acps_simplecheckauth(char *ident, char *operation, char *object);

For a typical request, this query returns either ACPS_ALLOW or ACPS_DENY based on the policy represented in the configured modules. This will suffice for many applications, but the query makes several simplifying assumptions about the types of representations used for the user identity, operation, and object. Specifically for this request, the identity is assumed to be a username (ACPS_ID_NAME), the operation a typical HP-UX operation string (ACPS_OP_DOTHEIRARCHICAL), and the object a generic string (ACPS_OBJ_GENERIC). For more information on these types, see acps(3).

Detailed Interfaces

For the more complex requests, the query takes the forms described in SYNOPSIS: acps_addenvattr(), acps_addobjattr(), acps_addopattr(), acps_addsubattr(), acps_addsubcred(), acps_checkauth(), acps_end(), acps_setobj(), acps_setop(), acps_setsubid(), acps_start().

There are a few major components to this set of interfaces.

The acps_start() and acps_end() functions are used for memory allocation and deallocation to maintain state between the calls. The acp_handle_t_t that is passed to each call is a pointer to an opaque data structure. The memory for this structure is allocated as part of the call to acps_start() and freed in acps_end().

The subsequent calls to to acps_setX() and acps_addX() essentially encode information into the handle in preparation for a call to acps_checkauth(). The five pieces of information encoded are as follows:

Identity: Subject identification (for example a username, uid, or X.500 DN) and associated attributes (for example, role, groups).
Credentials: Subject credentials (for example, a password and/or Kerberos token).
Operation: Operation and associated attributes.
Object: Object and associated attributes.
Environment: Environment attributes (for example, compartment ID, processor usage, and so forth).

For this information the acps_setX() interfaces encode a single value into the handle. Subsequent calls to the same interface will overwrite the previously written value. This is in contrast to the acps_addX() interfaces that append the value to a chain of values. The acps_setX() interfaces are used for the values that uniquely identify an access control request. The acps_addX() interfaces are used for credentials and attributes, of which any number may be present.

The call to acps_checkauth() triggers an authorization request to be marshaled to the back-end modules based on the ACPS configuration. The backend modules are able to retrieve the information stored in the handle as indicated in acps_spi(3).

One additional interface not shown in the above code fragment is the following optional interface that an application may choose to call if it receives ACPS_NEED_AUTHENTICATION from the acps_checkauth() call:

char *acps_getreqcred(acp_handle_t h); 

This function returns a string that indicates the type of credential that the policy requires. It is expected that an application may use this interface to request additional credentials from the user (when needed). The application can then add the credentials to the handle using acps_addsubcred() and then re-call acps_checkauth.

The ACPS API only accept strings encoded in the C locale.

RETURN VALUE

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

EXAMPLES

The following example illustrates the use of of the simplified interface in a sample application:

#include <stdio.h>
#include <libacps_api.h>

int
main(int argc, char **argv)
{
   int ret;

   if(argc != 4) {
        fprintf(stderr, "Usage:  chkauth username operation object\n");
        exit(1);
   }

   ret = acps_simplecheckauth(argv[1], argv[2], argv[3]);

   if(ret == ACPS_ALLOW) {
        printf("Access Allowed\n");
   }
   else if(ret == ACPS_DENY) {
        printf("Access Denied\n");
   }
   else {
        printf("Error returned: %d\n", ret);
   }

   return ret;
}

acps_api(3)

Technical documentation

» Table of Contents

» Index