3 — Authorization Library

[Previous] [Next] [Contents] [Index]

This chapter describes the Authorization Library.

NOTE: If you are unfamiliar with NetCrusader/Web authorization concepts such as NetCrusader Access Control Lists (ACLs), see the NetCrusader/Web Overview Guide.

This chapter includes the following sections:

3.1 Authorization Library Overview
3.2 Interface Description

3.1 Authorization Library Overview

The Authorization Library is a set of C functions that an application developer calls to check whether or not a user has the application's permission to access a particular object. In addition, it allows the developer to construct application-specific ACL models for protecting sets of application objects that have differing access requirements.

The following diagram shows the logical location of the Authorization Library with respect to other server elements.

Figure 3-1: Authorization Library Logical Relationships



The Security Adapter performs initial authentication and authorization checks and places information identifying the requesting user in the server's control structure. When the user program receives control, it calls the UUL to obtain the user's identity in the form of credentials handle.

The UUL obtains the credentials for the user from the NetCrusader Security Server and returns them to the user program. The user program then calls the Authorization Library to perform authorization checking.

Notice that you use NetCrusader Commander to manage the ACL database for this particular server, as well as for managing user information in the NetCrusader Security Server.

The Security Adapter assumes that each application will contain a hierarchy of application-specific objects. Access control is specified on each object in the hierarchy using NetCrusader ACLs (for a definition of NetCrusader ACLs, refer to the NetCrusader/Web Overview Guide).

3.1.1 Setting Up the X.500 Server and NetCrusader Registry Entries

Before you can use the Authorization Library to perform actual authorization checks, you must make sure that the following entries exist for all users to be mapped:

For instructions for creating these entries, refer to the Commander online help.

3.1.2 Building Applications

Applications built to use the Authorization Library need access to the include files installed in <install_directory>/include, where install_directory is the directory in which the Security Adapter package is installed.

In addition, applications need to link to the follow libraries:

3.1.3 Application Module Initialization and Termination

The steps involved in using the Authorization Library are:

  1. Initialize the Security Adapter authorization functions using authz_module_init().

  2. Define any application-specific ACL models using authz_module_register().

  3. Start the authorization server using authz_module_start().

  4. Call the desired UUL and Authorization Library functions to validate user access to the application's objects.

  5. Terminate the authorization server using authz_module_terminate().

Before an application can begin using the Authorization Library to perform authorization tasks, it must initialize the Security Adapter authorization functions by calling authz_module_init(). This call submits the application name and a path to a DLL that implements the application's netc_list_objects() call (Section 3.1.4).

Once the application has completed the definition of any ACL models using authz_model_register() (Section 3.1.5 on page 32), it calls authz_module_start(). If the application has not registered any new models, the Security Adapter uses the default NetCrusader ACL model.

If a program written to use the Authorization Library calls authz_module_init() without calling authz_module_start(), requests for HTML pages will return the error message document contains no data.

3.1.4 Defining Application Objects

Every application that uses the Authorization Library must implement a shared library (DLL for Windows NT) that allows the application to be managed by Commander. This shared library must contain two entry point functions: netc_list_objects() and netc_free_list_objects().

The application passes the name of the shared library to the Security Adapter by calling the Authorization Library call authz_module_init().

Windows NT: If you need to do special application-related processing in DllMain(), you may need to implement netc_list_objects() and netc_free_list_objects() in a separate shared library that is only called when needed and does not remain in memory.

NOTE: If using Visual C++, make sure you add netc_list_objects() and netc_free_list_objects() to the list of exported functions in the <projectname>.def file.

For more information on netc_list_objects() and netc_free_list_objects(), see the description of the interface starting on page 35.

3.1.5 Defining ACL Models

NOTE: You must be familiar with the material on NetCrusader authorization and ACLs presented in the NetCrusader/Web Overview Guide.

By default, objects protected by the NetCrusader/Web Security Adapter use the default NetCrusader ACL model (Section 3.1.5.2). The default NetCrusader ACL model contains access control permissions for read, write, execute, list, traverse, mount, and unmount operations. This palette of access control permissions applies primarily to an application that serves secure web documents.

An application developer can choose to use the default NetCrusader ACL model to protect objects within the application. If, however, this model is not sufficient to properly represent the types of permissions that apply to an object, then the developer can define a new ACL model for that object by calling authz_model_register().

The authz_model_register() call allows a developer to specify a new palette of access control permissions that apply to a subtree in the application's object hierarchy. The developer specifies the point in the object hierarchy where the new model takes effect (subtree root), the permissions for the model, and a default ACL to set on the root of the subtree the first time the model is created.

The Security Adapter stores the model information in the ACL model database located in <installation directory>/netc_authz/<server name>/model.db. You should back this file up.

3.1.5.1 Multiple ACL Models and Traverse

If you apply multiple models to an object tree, and an ACL check for an object protected by a model for which Traverse is enabled spans a portion of the tree protected by a model for which Traverse is not enabled, the Authorization Library assumes that Traverse is allowed for all directories protected by the latter model.

3.1.5.2 Default NetCrusader ACL Model

If an application fails to specify a new ACL model, it will inherit the default NetCrusader ACL Model. The default NetCrusader ACL model defines the following permissions:

Table 3-1: Default NetCrusader ACL Model

Abbreviation Name Description Value
r
read

netc_perm_read

0x0010

w
write

netc_perm_write

0x0020

x
execute

netc_perm_execute

0x0040

m
mount

netc_perm_mount

0x0080

u
unmount

netc_perm_unmount

0x0100

l
list

netc_perm_list

0x0200

T
traverse

netc_perm_traverse

0x0400

In addition, the Authorization Library reserves the following four permissions:

Table 3-2: Default NetCrusader ACL Model Reserved Permissions

Abbreviation Name Description Value
c
ACL control

netc_perm_control

0x0001

t
ACL test

netc_perm_test

0x0002

I
Inherited ACL

netc_perm_inherited

0x0004

D
Delete real ACL

netc_perm_del_acl

0x0008

3.1.5.3 Default ACL Settings

If the application fails to specify default ACL settings for any model root, the Security Adapter applies the following root ACL settings: 

unauthenticated     netc_perm_read, netc_perm_traverse
any_other           netc_perm_read, netc_perm_traverse
wccs-admin (group)  <all permissions>

3.1.6 Checking Access Permissions

The Authorization Library provides two calls that an application can use to check a user's access permissions on an object:

Both of these calls take an input handle that identifies the user. The application obtains this handle by calling uul_get_credentials() (page 19).

These calls also enforce Traverse permissions if the model specifies the traverse feature. If a model specifies the traverse feature, then calling authz_acl_authorized() or authz_acl_permissions() require that the user have traverse permission for all objects in the object path.

3.2 Interface Description

This section describes the functions that make up the Authorization Library. Functions are listed in alphabetical order.

authz_acl_authorized()
authz_acl_permissions()
authz_free_acl_list()
authz_list_real_acls()
authz_model_register()
authz_module_init()
authz_module_start()
authz_module_terminate()
netc_list_objects()
netc_free_list_objects()

authz_acl_authorized()

The authz_acl_authorized() call allows an application to check whether a user has a particular type of access to an object. Each type of access is specified by a bit in the desired_access bit mask (for example read, write, execute, etc.).

Signature 

#include <authz.h>


int authz_acl_authorized (
     module_handle_t      module_handle,
     uul_creds_ptr        huser, 
     char *               object_name, 
     unsigned long        desired_access,		
     unsigned long *      status);

Parameters

IN/OUT Parameter Description
IN

module_handle

A module handle obtained by calling the authz_module_init() function.

IN

huser

A handle that identifies the user. The application obtains this handle from the Universal User Library uul_get_credentials() call (page 19).

IN

object_name

The pathname of the object on which access is being checked, beginning with / for the document root.

IN

desired_access

A bit mask, as defined by authz_model_register(), that specifies the type of access that the application requires of the user for the object.

OUT

status

Error status code.

Returns

This function returns TRUE if the desired access is allowed by the object or FALSE otherwise.

Error Codes

Error Code Description
error_status_ok

The function completed successfully.

authz_acl_permissions()

The authz_acl_permissions() call allows an application to retrieve the complete set of permissions that a particular user has to an object. The permissions are represented using a bit mask, with each permission represented as a particular bit in the bit mask.

Signature 

#include <authz.h>


unsigned long authz_acl_permissions (
     module_handle_t     module_handle,
     uul_creds_ptr       huser, 
     char *              object_name
     unsigned long       *status);

Parameters

IN/OUT Parameter Description
IN

module_handle

A module handle obtained by calling the authz_module_init() function.

IN

huser

A handle that identifies the user. The application obtains this handle from the Universal User Library uul_get_credentials() call (page 19).

IN

object_name

The name of the object on which access is being checked.

OUT

status

Error status code.

Returns

This function returns a bit mask (defined by the authz_model_register() call) indicating the user's permissions for the specified object.

Error Codes

Error Code Description
error_status_ok

The function completed successfully.

authz_free_acl_list()

The auth_free_acl_list() call frees the memory associated with an ACL list.

Signature 

#include <authz.h>


unsigned long authz_free_acl_list(
     acl_list_t  **    aclList);

Parameters

IN/OUT Parameter Description
IN

aclList

An ACL list returned by the authz_list_real_acls() call.

Returns

None.

authz_list_real_acls()

The auth_list_real_acls() call retrieves a list of object names that have real (explicit, or non-inherited) ACLs.

Signature 

#include <authz.h>


unsigned long authz_list_real_acls(
     module_handle_t    module_handle
     acl_list_t  **     aclList,
     unsigned long *    status);

Parameters

IN/OUT Parameter Description
IN

module_handle

A module handle obtained by calling the authz_module_init() function.

IN

aclList

A pointer to a linked list of acl_list_t structures that gets returned by this call.

OUT

status

Error status

Returns

This function returns the number of real ACLs in the list. If the function completes successfully, it returns error_status_ok. Otherwise it returns an error status.

Error Codes

Error Code Description
error_status_ok

No error.

authz_model_register()

The authz_model_register() call creates a new ACL model that applies to a portion of the application object tree.

You must call authz_model_register() between authz_module_init() and authz_module_start().

Signature 

#include <authz.h>


unsigned long authz_model_register(
     module_handle_t     module_handle,
     char *              model_root, 
     permission_def_t    model_definition[ ],
     unsigned long       traverse_perm,
     char *              defaul_acl[ ]);

Parameters

IN/OUT Parameter Description
IN

module_handle

A module handle obtained by calling the authz_module_init() function.

IN

model_root

The name of the object where this ACL model takes effect within the object hierarchy. A value of NULL or "/" specifies the root of the object hierarchy.

IN

model_definition

An array of permission_def_t structures that specify the permissions that comprise the ACL model. A value of NULL specifies the default NetCrusader ACL model definition.

No permission_def_t structure included in the model_definition[] array may contain the reserved bits 0x1, 0x2, 0x4, and 0x8 or the reserved names c, t, I, and D. These bits and names correspond to the control, text, Inherited, and Delete permissions, which are automatically included in all ACL models.

IN

traverse_perm

A bit mask that specifies the traverse permission for this model. If this value is non-zero, traverse checks will be applied to objects controlled by this model.

IN

default_acl

An array of strings that represent the default ACL to be applied to the root object (subtree root) for this model. A value of NULL specifies the default settings for the default NetCrusader ACL model.

Usage

An ACL model is a set of individually settable permissions specified by the model_definition parameter. The model_definition parameter is simply an array of permission structures, where each structure describes an individual permission. The permission structure is made up of a permission name, a permission description (displayed by NetCrusader Commander), and an access bit mask. The array is terminated by a permission definition structure that specifies a NULL pointer for the permission name.

The access bit mask specifies one or more bits in the ACL that can be set or cleared using NetCrusader Commander to grant or remove a permission.

No permission structure included in the model_definition[] array may contain the reserved bits 0x1, 0x2, 0x4, and 0x8 or the reserved names c, t, I, and D. These bits and names correspond to the control, text, Inherited, and Delete permissions, which are automatically included in all ACL models.

The default_acl parameter specifies the initial ACL settings (default ACL) on the model_root. The default ACL consists of a list of character strings, each string corresponding to an entry on the ACL. Specifying a NULL pointer terminates the list. Each entry has the following syntax:

<ACL type>:[<ACL identifier>:]<permissions>

where:

Example 

  permission_def_t my_model_perms[] = {
    { "a", "administrative permission", 0x00000040 },
    { "u", "user permission", 0x00000010 },
    { "x", "traverse permission", 0x00000020},
    { NULL, NULL, 0}
  };


  char *my_model_default_acl[] = {
    "group:plugin-admin:act",
    "foreign_user:/.../far_away_cell/kevin:rxctT"
    "any_other:ut",
    NULL
  };


  authz_model_register(
          my_extension,                    /* Module handle */
          NULL,                            /* Model root */
          my_model_perms,                  /* Permissions */
          0x20,                            /* Traversal perm */
          my_model_default_acl);           /* Default settings */

Returns

This function returns error_status_ok on success or an error_status otherwise.

Error Codes

Error Code Description
error_status_ok

No error.

authz_s_no_memory

The call was unable to allocate memory.

authz_s_reserved_permission_used

The model attempted to use a reserved permission in a permission definition.

authz_module_init()

The authz_module_init() call returns a handle that can be used to identify this application module to the Security Adapter in later calls.

Signature 

#include <authz.h>


module_handle_t authz_module_init (
     char *               module_name,
     char *               module_path,
     char *               module_unique_id,
     netc_authz_flags_t   flags
     unsigned long *      status);

Parameters

IN/OUT Parameter Description
IN

module_name

The name of this application module.

IN

module_path

The path name of the shared library implementing this module.

IN

module_unique_id

A unique string supplied by the application developer to differentiate this application from others with the same name. This allows the same application to re-register, but prevents two applications with the same name from running.

IN

flags

A bitmask of flags controlling the behavior of the Authorization Library for this application. Currently flags can be set to:

OUT

status

Error status code.

Returns

This function returns a module handle on success or NULL otherwise.

Error Codes

Error Code Description
error_status_ok

No error.

authz_s_no_memory

The call was unable to allocate memory.

authz_s_application_name_in_use

The module name was already in use by another application.

authz_module_start()

The authz_model_start() call initializes Security Adapter authorization service for a particular module.

Signature 

#include <authz.h>


unsigned long authz_module_start(
     module_handle_t    module_handle);

Parameters

IN/OUT Parameter Description
IN

module_handle

A module handle obtained by calling the authz_module_init() function.

Returns

This function returns error_status_ok on success or an error_status otherwise.

Error Codes

Error Code Description
error_status_ok

No error.

authz_s_no_memory

The call was unable to allocate memory.

authz_s_acl_cellname_missing

You failed to specify fully qualified names (including the cell name) for the foreign_user, foreign_group, and foreign_other ACL entry types.

authz_s_malformed_default_acl_entry

A model's default ACL entry contained an invalid ACL type.

Usage

This call causes any model settings to take effect and sets the default ACL on any model root that doesn't currently have a real ACL.

If no models has been registered for the root of the object hierarchy, this call sets the root to use the NetCrusader default ACL model.

Changing the model settings across invocations of the application deletes any ACLs created using the previous model settings and applies new default ACLs.

authz_module_terminate()

The authz_module_terminate() call shuts down the Security Adapter authorization service for a particular module. It frees any state and memory associated with the module_handle parameter.

Signature 

#include <authz.h>


unsigned long authz_module_start(
     module_handle_t     module_handle);

Parameters

IN/OUT Parameter Description
IN

module_handle

A module handle obtained by calling the authz_module_init() function.

Returns

This function returns error_status_ok on success or an error_status otherwise.

Error Codes

Error Code Description
error_status_ok

No error.

netc_list_objects()

The netc_list_objects() routine is invoked by the Security Adapter to retrieve a list of application objects for Commander to display.

Signature 

#include <netc_list.h>


typedef struct object_list_s_t 
{
    struct object_list_s_t *pNext;
    char *Object;                   /* Object name */
    void *Reserved;                 /* Reserved for future use */
} object_list_t;


unsigned long  netc_list_objects(
     char *AppName,
     char *Path,
     object_list_t **ObjectList);

Parameters

IN/OUT Parameter Description
IN

AppName

The application name as specified in the authz_module_init() function.

IN

Path

A pointer to an object to be enumerated.

OUT

ObjectList

A pointer to a linked list of named entries in the object.

Returns

The number of nodes in the returned linked list.

Usage

Each entry in the object list needs to follow the NetCrusader name formatting rules to differentiate directories from leaf nodes: 

directories                   <object>//


files or application object   <object>


html files                    <object>/

Example 

/*   example.c   */


#include <stdio.h>
#include <string.h>
#include <malloc.h>
#include "netc_list.h"


/*
 * Routine: add_node
 *
 * Purpose: Build the list using the given object template.
 */


void
add_node(object_list_t **ObjectList,
         char *objName)
{
    size_t size = 0;
    long i = 0;
    object_list_t *pCurrent = NULL;


    /* Set the object size; leave space for null. */


    size = strlen(objName)+1;


    /* Allocate the list node. */


    pCurrent = malloc(sizeof(object_list_t));


    /* Allocate and set the object. */


    pCurrent->Object = malloc(size);
    strcpy(pCurrent->Object, objName);


    /* Tack the new node onto the front of list. */


    pCurrent->pNext = *ObjectList;
    *ObjectList = pCurrent;
    return;
}


/*
 * Routine: netc_list_objects
 *
 * Purpose: Return a list of objects managed by the application,
 *          starting with the specified object path.
 *
 * Parameters:
 *          Path            Path of the target object (input)
 *
 *          ObjectList      List of objects (output)
 *
 * Return Value:
 *          Count of objects in object list.
 */


unsigned long DLL_EXPORT
netc_list_objects(char *AppName,
                  char *Path,
                  object_list_t **ObjectList)
{
    long count = 0;
    char object[512] = "";
    *ObjectList = NULL;


    /* Check for NULL path - Root object */


    if ((strcmp(Path, "") == 0) || (strcmp(Path, "/") == 0))
    {


        /* Path = NULL; make first level directory (grandparent). */


        strcpy(object, "grandparent//");
        add_node(ObjectList, object);
        count = 1;
    }
    else
    {
        /* Path != NULL */


        /* Children of '/grandparent' */


        if (strcmp(Path, "/grandparent") == 0)
        {
            strcpy(object, "parent//");
            add_node(ObjectList, object);
            strcpy(object, "aunt");
            add_node(ObjectList, object);
            strcpy(object, "uncle");
            add_node(ObjectList, object);
            count = 3;
        }


        /* Children of 'parent' */


        else if (strcmp(Path, "/grandparent/parent") == 0)
        {
            strcpy(object, "child//");
            add_node(ObjectList, object);
            strcpy(object, "sibling");
            add_node(ObjectList, object);
            count = 2;
        }
        /* Children of 'child' */


        else if (strcmp(Path, "/grandparent/parent/child") == 0)
        {
            strcpy(object, "grandchild");
            add_node(ObjectList, object);
            count = 1;
        }


    } /* end else */


    return(count);
}


/*
 * Routine: netc_free_list_objects
 *
 * Purpose: Free the list of objects allocated by the
 *          netc_list_objects() routine.
 *
 * Parameters:
 *          ObjectList      List of objects (input/output)
 *
 * Return Value:
 *          none
 */


void DLL_EXPORT
netc_free_list_objects(object_list_t **ObjectList)
{
    object_list_t *pCurrent = NULL;


    /* Loop through the list and free each node. */


    while (*ObjectList != NULL)
    {
        pCurrent = *ObjectList;
        *ObjectList = pCurrent->pNext;
        free(pCurrent->Object);
        free(pCurrent);
    }
    return;"
}

netc_free_list_objects()

When finished reading the list of objects, the Security Adapter calls netc_free_list_objects() to allow the application to free any memory consumed by the object list.

Signature 

#include <netc_list.h>


void netc_free_list_objects(
     object_list_t **ObjectList);

Parameters

IN/OUT Parameter Description
OUT

ObjectList

A pointer to the list of objects returned by a call to netc_list_objects().

Returns

This function has no return value.

[Previous] [Next] [Contents] [Index]

To make comments or ask for help, contact support@entegrity.com.

Copyright © 1997-2002 Entegrity Solutions Corporation & its subsidiaries