[Search] [txt|pdf|bibtex] [Tracker] [WG] [Email] [Nits]

Versions: 00 01 02 03 04 05                                             
INTERNET-DRAFT                        Tatyana Ryutov
CAT Working Group                     Clifford Neuman
Expires February 1999                 USC/Information Sciences Institute
draft-ietf-cat-gaa-cbind-00.txt       August 07, 1998



       Generic Authorization and Access control
                Application Program Interface
                       C-bindings

0. Status Of this Document

This document is an Internet-Draft. Internet-Drafts are working
documents of the Internet Engineering Task Force (IETF), its
areas, and its working groups. Note that other groups may also
distribute working documents as Internet-Drafts.

Internet-Drafts are draft documents valid for a maximum of six
months and may be updated, replaced, or obsoleted by other
documents at any time. It is inappropriate to use Internet-Drafts
as reference material or to cite them other than as
"work in progress."

To view the entire list of current Internet-Drafts, please check
the "1id-abstracts.txt" listing contained in the Internet-Drafts
Shadow Directories on ftp.is.co.za (Africa), ftp.nordu.net
(Northern Europe), ftp.nis.garr.it (Southern Europe), munnari.oz.au
(Pacific Rim), ftp.ietf.org (US East Coast), or ftp.isi.edu
(US West Coast).

1. Abstract

The Generic Authorization and Access control Application Programming
Interface (GAA API) provides access control services to calling
applications.
It facilitates access control decisions for applications and allows
applications to discover access control policies associated with a
targeted resource. The GAA API is usable by multiple applications
supporting different kinds of protected objects.
The GAA API design supports:

- a variety of security mechanisms based on public or secret key
  cryptosystems
- different authorization models
- heterogeneous security policies
- various access rights

This document specifies C language bindings for the GAA API, which
is described at a language-independent conceptual level in
draft-ietf-cat-acc-cntrl-frmw-00.txt


2. The GAA API data types and calling conventions

The data types describe only fields that must be provided by all

Ryutov/Neuman                               Expires February 1999

GAA API implementations.  Individual implementations may provide
additional fields for internal use within GAA API routines.

2.1. Integer types

The GAA API defines the following integer data type:

uint32   32-bit unsigned integer

2.2. String and similar data

Certain data items used by the GAA API may be regarded as a character
strings, e.g. principal name or specification of security mechanism.
The data of this kind is passed between the GAA API and application
using the gaa_data_ptr data type, which is a pointer to a gaa_data
structure.

2.2.1 gaa_data data structure

The gaa_data type is a structure containing the following fields:

length
Contains the total number of bytes in the datum.

data
Contains a pointer to the actual datum.

typedef struct gaa_data_struct gaa_data, *gaa_data_ptr;

struct gaa_data_struct {
    int length;
    char *data;
};

2.2.2. gaa_tag_value_list data structure

Some data items used by the GAA API may be regarded as a linked list
of tag:value character elements. For example, a pointer to a list of
tag:value character strings is passed to the gaa_check_authorithation
routine via the gaa_options parameter.
The data of this kind is passed between the GAA API and the
application using the gaa_tag_value_list_ptr data type, which is a
pointer to a gaa_tag_value_list structure.

The gaa_tag_value_list type is a structure containing the following
fields:

tag
A character string, which identifies how the character string stored
in the "value" field should be interpreted by the GAA API.

value
Contains a pointer to the element of the type gaa_data.



Ryutov/Neuman                               Expires February 1999

next
A pointer to the next element in the list.

typedef struct gaa_tag_value_list_struct  gaa_tag_value_list,
                                         *gaa_tag_value_list_ptr;
struct gaa_tag_value_list_struct {
   gaa_data_ptr             tag;
   gaa_data_ptr             value;
   gaa_tag_value_list_ptr   next;
};

2.2.3. gaa_tag_vector and gaa_tag_vector_list data structures

Some data items used by the GAA API may be regarded as a linked list
of tag:vector elements. For example, a pointer to a list of tag:vector
elements is passed to the gaa_check_authorithation routine via the
check_access_rights parameter.
The data of this kind is passed between the GAA API and the
application using the gaa_tag_vector_list_ptr data type, which is a
pointer to a gaa_tag_vector_list structure.

The gaa_tag_vector type is a structure containing the following
fields:

tag
Denotes how bits in the "vector" field are to be interpreted.

vector
Contains an integer of type uint32

typedef struct gaa_tag_vector_struct  gaa_tag_vector,
                                     *gaa_tag_vector_ptr;
struct gaa_tag_vector_struct {
    gaa_data_ptr   tag;
    uint32         vector;
};

The gaa_tag_vector_list type is a structure containing the
following fields:

element
Contains a pointer to the element of type gaa_tag_vector

next
Contains a pointer to the next element in the list

typedef struct gaa_tag_vector_list_struct  gaa_tag_vector_list,
                                          *gaa_tag_vector_list_ptr;

struct gaa_tag_vector_list_struct {
   gaa_tag_vector_ptr       element;
   gaa_tag_vector_list_ptr  next;
};

2.3. Opaque data types

Ryutov/Neuman                               Expires February 1999

Some data items are considered opaque to the GAA API, because their
internal data structure has no significance to the GAA API, e.g.
actual mechanism-specific credentials.
Opaque data is passed between the GAA API and the application using
the gaa_buffer_ptr data type, which is a pointer to a gaa_buffer
structure.

The gaa_buffer type is a structure containing the following fields:

length
Contains the total number of bytes in the datum

value
Contains a pointer to the actual datum

typedef struct gaa_buffer_struct gaa_buffer, *gaa_buffer_ptr;

struct gaa_buffer_struct {
size_t     length;
void      *value;
};


2.4. GAA API Access Control List data structures

Certain GAA API procedures take parameters of the type gaa_acl_ptr,
which is a pointer to a gaa_acl structure.

gaa_acl data type contains a complete ACL, made up of a list of
entry fields of type gaa_acl_entry. GAA_ACL_UNBOUND defines the value
of the unbound ACL handle.


2.4.1. gaa_acl data structure

The gaa_acl type is a structure containing the following fields:

object_name
Contains a name of an object with which the ACL is associated.
The name of the object is from the application-specific name space.
The object_name field is evaluated by GAA API routine when checking
credentials of the type gaa_authorized_cred to determine if the
object_name for which the ACL is being examined is listed in the set
of those objects which can be accessed by the grantee.
Whether this field should be present in the gaa_acl data structure
is not clear. If we decide not to include this field, we should
provide a means for deciding if the targeted object is included in
the list of objects accessible by the grantee.


acl_entries
A pointer to a list of ACL entries, each of type gaa_acl_entry

typedef struct gaa_acl_struct gaa_acl, *gaa_acl_ptr;


Ryutov/Neuman                               Expires February 1999

struct gaa_acl_struct {
gaa_data_ptr            object_name;
gaa_acl_entry_ptr       acl_entries;
};


2.4.2. gaa_acl_entry data structure

The gaa_acl_entry type is a structure containing the following
fields:

type
Indicates whether the ACL entry grants or denies access.
If type = GAA_GRANT, the entry specifies positive rights.
If type = GAA_DENY, the entry specifies negative rights. Entries of
this type must not have any conditions, so GAA_NO_CONDITIONS
value is stored in the condition field.

principals
A pointer to a structure of the type gaa_principal_list, which
contains list of principals. Principals can be aggregated into a
single ACL entry when the same set of access rights and conditions
applies to all of them.

access_rights
A pointer to a linked list of structures of the type
gaa_acl_access_rights_set.
Each set indicates access rights named with the same tag.
For example, consider the following user-level
representation of an ACL entry:

USER kerberos.v5 joe@ISI.EDU < FILE : read >

                             < FILE : write
                               ACCOUNT: withdraw > time_window : 7AM-7PM
                                                   time_day : Mon-Fri                                                                                                        time_day : Mon-Fri
                             < FILE : execute
                               ACCOUNT : deposit
                               ACCOUNT : transfer > location : *.isi.edu;

The first access rights set consists of FILE : read, FILE : write
and FILE : execute.
The second one consists of ACCOUNT : withdraw, ACCOUNT : deposit and
ACCOUNT : transfer.

conditions
A pointer to a list of structures of the type gaa_conditions, which
contains all different conditions that are present in the ACL entry.
In the example of an ACL entry given above, the condition list
contains three conditions: time_window : 7AM-7PM, time_day : Mon-Fri
and location : *.isi.edu.


next

Ryutov/Neuman                               Expires February 1999

A pointer to the next ACL entry

typedef enum {
      GAA_GRANT,
      GAA_DENY
} gaa_entry_type;


typedef struct gaa_acl_entry_struct  gaa_acl_entry,
                                    *gaa_acl_entry_ptr;

struct gaa_acl_entry_struct {
   gaa_entry_type             type;
   gaa_principal_list_ptr     principals;
   gaa_access_rights_set_ptr  access_rights;
   gaa_conditions_ptr         conditions;
   gaa_acl_entry_ptr          next;
};


2.4.3. gaa_principal and gaa_principal_list data structures

The gaa_principal type is a structure containing the following
fields:

type
Specifies the type of principal: GAA_USER, GAA_GROUP, GAA_HOST,
GAA_APPLICATION or GAA_ANYBODY.

mech_type
Contains principal naming method, which specifies the type of the
security mechanism used to obtain authenticated subject's identity,
e.g. Kerberos.V5, DCE.
If type = GAA_ANYBODY, mech_type and name fields are assigned value
GAA_NO_DATA.

name
Contains principal name, which specifies authenticated subject's
identity, e.g. joe@ISI.EDU.

typedef enum  {
      GAA_USER        ,
      GAA_GROUP       ,
      GAA_HOST        ,
      GAA_APPLICATION ,
      GAA_ANYBODY
} gaa_principal_type;


typedef struct  gaa_principal_struct   gaa_principal,
                                      *gaa_principal_ptr;

struct  gaa_principal_struct {
   gaa_principal_type    type;
   gaa_data_ptr          mech_type;

Ryutov/Neuman                               Expires February 1999

   gaa_data_ptr          name;
};


The gaa_principal_list type is a structure containing the following
fields:

principal
A pointer to the gaa_principal structure

next
A pointer to the next principal in the ACL entry

typedef struct  gaa_principal_list_struct  gaa_principal_list,
                                          *gaa_principal_list_ptr;
struct gaa_principal_list_struct {
gaa_principal_ptr     principal;
gaa_principal_ptr     next;
};


2.4.4. gaa_access_rights_set data structure

The gaa_access_rights_set type is a structure containing the
following fields:

rights
A pointer to a structure of the type gaa_tag_vector.
In the example of an ACL entry given in the section 2.4.2, the
gaa_tag_vector structure, corresponding to the first access rights
set, will have "FILE" value in the "tag " field and 1110...0 in
the "vector" field.
The first set bit stands for "read", the second one for "write" and
the third one for "execute".
The gaa_tag_vector structure, corresponding to the second access
rights set, will have "ACCOUNT" value in the "tag" field and 1110...0
in the "vector" field. The first set bit stands for "withdraw", the
second  one for "deposit" and the third one for "transfer".


mask
An array containing GAA_NUM_ACCESS_RIGHTS pointers to a list of
structures of type gaa_condition_mask. Each gaa_condition_mask
structure contains a pointer to particular condition associated with
the granted right and a pointer to the next structure of the type
gaa_condition_mask.
mask[i], were index "i" corresponds to a bit in the bit-vector, is
set to GAA_NO_CONDITIONS for all denied rights and granted rights
with no associated conditions.
In the example of an ACL entry given in the section 2.4.2, lets consider
mask structure for the first access rights set.
The access rights set will have "FILE" value in the "tag" field and
1110...0 in the "vector" field of "rights" element.
mask[0] (corresponding to "read" access right) will be set to
GAA_NO_CONDITIONS, since "read" has no conditions.

Ryutov/Neuman                               Expires February 1999

mask[3], mask[4],..., mask[31] will be also set to GAA_NO_CONDITIONS.
mask[1] (corresponding to "write" access right) will point to the list
of gaa_condition_mask, which has two elements.
The first element will have a pointer to the condition
time_window : 7AM-7PM in the "condition" field, the second element
will have a pointer to the condition time_day : Mon-Fri in the
"condition" field.
mask[2] (corresponding to "execute" access right) will point to the
list of gaa_condition_mask, which has just one element with
a pointer to the condition location : *.isi.edu in the "condition"
field.

next
A pointer to the next set of access rights in the ACL entry.


typedef  struct  gaa_condition_mask_struct  gaa_condition_mask,
                                           *gaa_condition_mask_ptr;
struct  gaa_condition_mask_struct {
   gaa_conditions_ptr      condition;
   gaa_condition_mask_ptr  next;
} ;


typedef  struct gaa_access_rights_set_struct  gaa_access_rights_set,
                                         *gaa_access_rights_set_ptr;
struct gaa_access_rights_set_struct {
   gaa_tag_vector_ptr          rights;
   gaa_condition_mask_ptr      mask[GAA_NUM_ACCESS_RIGHTS];
   gaa_access_rights_set_ptr   next;
};


2.4.5. gaa_conditions data structure

This structure defines a specific policies under which access
rights are granted. It lists all conditions that have been encountered
in the ACL entry. The mapping between access rights and corresponding
condition sets is defined via gaa_condition_mask structure.

The gaa_conditions type is a structure containing the following
fields:

type
Type defines the type of condition and which evaluation
function will be invoked to evaluate it.

value
Value represents a set of parameters for the condition evaluation
function. The meaning of the parameters and their relationships
depend on how the evaluation function interprets them.

flags
Flags indicate if condition was evaluated/not evaluated,
satisfied/not satisfied, or must be enforced.

Ryutov/Neuman                               Expires February 1999


next
A pointer to the next condition in the ACL entry.


typdef struct gaa_conditions_struct gaa_conditions,
                                   *gaa_conditions_ptr;

struct gaa_conditions_struct {
   gaa_data_ptr        type;
   gaa_data_ptr        value;
   uint32              flags;
   gaa_conditions_ptr  next;
};


2.5 GAA API Security Context data structures

The security context is a GAA API data structure, which is passed
as an argument to the GAA API. It stores information relevant to
access control.

2.5.1 gaa_sec_context data structure

The gaa_sec_context type is a structure containing the following
fields:

identity_cred
A pointer to a list of structures of the type gaa_identity_cred

authr_cred
A pointer to a list of structures of the type gaa_authrized_cred

group_membership
A pointer to a list of structures of the type gaa_identity_cred,
which specifies that the grantee is a member of only listed groups

group_non_membership
A pointer to a list of structures of the type gaa_identity_cred,
which specifies that the grantee is NOT a member of the listed groups

attributes
A pointer to a list of structures of the type gaa_attributes, which
contains miscellaneous attributes attached to the grantee, e.g. age
of the grantee, grantee security clearance.

unevl_cred
A pointer to a list of structures of type gaa_unevaluated_cred.

connection_state
Contains a mechanism-specific representation of per-connection
context, some of the data stored here include keyblocks, addresses.

condition_evaluation
Specific condition evaluation function called by GAA API if there are

Ryutov/Neuman                               Expires February 1999

application-specific conditions.
Generic (understood by the GAA API) conditions are evaluated by the
GAA API internal functions.

pull_cred
This function is called when additional credentials are required.
It obtains the necessary credentials and then cred_evaluate
function is invoked. This process can be recursive.

cred_evaluate
This specific function is invoked to parse the contents of the
acquired credentials into the GAA API internal form and evaluate them.

typedef struct gaa_sec_context_struct  gaa_sec_context,
                                      *gaa_sec_context_ptr
struct gaa_sec_context_struct {
   gaa_identity_cred_ptr     identity_cred;
   gaa_authrized_cred_ptr    authr_cred;
   gaa_identity_cred_ptr     group_membership;
   gaa_identity_cred_ptr     group_non_membership;
   gaa_attributes_ptr        attributes;
   gaa_unevaluated_cred_ptr  unevl_cred;
   gaa_buffer_ptr            connection_state;

   void
   (*condition_evaluation)(gaa_sec_context_ptr, va_list ap);

   void
   (*pull_cred)(gaa_sec_context_ptr, va_list ap);

   void
   (*cred_evaluate)(gaa_sec_context_ptr, va_list ap);
};


2.5.2. gaa_identity_cred data structure

A gaa_identity_cred structure is composed of a set of identity
credentials. Identity credentials describe a set of mechanism-specific
principals, and give their holder the ability to act as any of those
principals. Each of the identity credentials contains information
needed to authenticate a single principal.

The gaa_identity type is a structure containing the following fields:

principal
A pointer to a structure of the type gaa_principal

conditions
A pointer to a list of structures of the type gaa_conditions, which lists
restrictions placed on the identity, e.g. validity time periods

mech_spec_cred
Contains a handle to the actual mechanism-specific identity credential


Ryutov/Neuman                               Expires February 1999

next
Contains a pointer to the next identity credential

typedef struct gaa_identity_cred_struct  gaa_identity_cred,
                                        *gaa_identity_cred_ptr;
struct gaa_identity_cred_struct {
   gaa_principal_ptr        principal;
   gaa_conditions_ptr       conditions;
   gaa_buffer_ptr           mech_spec_cred;
   gaa_identity_cred_ptr    next;
};


2.5.3 gaa_authorized_cred data structure

This type of credentials used when individuals grant delegated
credential or generate a capability.

grantor
Specifies a principal who issued the credential

grantee
Specifies a principal for whom the credential was issued

objects
A pointer to a linked list of structures of the type gaa_data, which
contains a list of objects which may be accessed by the grantee.
Object names are from the application-specific name space.

access_rights
A pointer to a linked list of structures of the type
gaa_acl_access_rights_set. Each structure indicates granted access
rights.

conditions
A pointer to a list of structures of the type gaa_conditions,
which lists restrictions placed on the authorized credentials

mech_spec_cred
Contains a handle to the actual mechanism-specific authorized
credential

next
Contains a pointer to the next authorized credential belonging to the
same grantee

typedef struct gaa_authorized_cred_struct  gaa_authorized_cred,
                                          *gaa_authorized_cred_ptr;
struct gaa_authorized_cred_struct{
   gaa_principal_ptr         grantor;
   gaa_principal_ptr         grantee;
   gaa_data_list_ptr         objects;
   gaa_access_rights_set_ptr access_rights;
   gaa_conditions_ptr        conditions;
   gaa_buffer_ptr            mech_spec_cred;

Ryutov/Neuman                               Expires February 1999

   gaa_authorized_cred_ptr   next;
};


2.5.4.  gaa_attributes data structure

The gaa_attributes type is a structure containing the following
fields:

mech_type
Security mechanism used to obtain the credential

type
Type is used to define the type of attribute

value
Represents actual attribute contents

conditions
A pointer to a list of structures of the type gaa_conditions,
which lists restrictions placed on the attribute credentials

mech_spec_cred
Contains a handle to the actual mechanism-specific attribute
credential

next
Contains a pointer to the next attributes credential belonging to
the same grantee.


typedef struct gaa_attributes_struct  gaa_attributes,
                                     *gaa_attributes_ptr;
struct gaa_attributes_struct {
   gaa_data_ptr          mech_type;
   gaa_data_ptr          type;
   gaa_data_ptr          value;
   gaa_conditions_ptr    conditions;
   gaa_buffer_ptr        mech_spec_cred;
   gaa_attributes_ptr    next;
};


2.5.5. gaa_unevaluated_cred data structure

Evaluation of the acquired credentials can be defferd till the
credential is actually needed. Unevaluated credentials are stored in
the gaa_unevaluated_cred data structure.

The gaa_unevaluated_cred type is a structure containing the following
fields:

cred_type
Specifies credential type: GAA_IDENTITY, GAA_GROUP_MEMB,
GAA_GROUP_NON_MEMB, GAA_AUTHORIZED, and GAA_ATTRIBUTES.

Ryutov/Neuman                               Expires February 1999


grantor
Specifies a principal who issued the credential

grantee
Specifies a principal for whom the credential was issued

mech_type
Specifies security mechanism used to obtain the credential

mech_spec_cred
Contains a handle to the actual mechanism-specific authorization
credential

cred_verification
This pointer to the credential verification function for upcall is
added by the application or transport

next
Contains a pointer to the next unevaluated credential belonging to
the same subject.


typedef enum  {
      GAA_IDENTITY        ,
      GAA_GROUP_MEMB      ,
      GAA_GROUP_NON_MEMB  ,
      GAA_AUTHORIZED      ,
      GAA_ATTRIBUTES
 } gaa_cred_type;


typedef struct gaa_unevaluated_cred_struct   gaa_unevaluated_cred,
                                            *gaa_unevaluated_cred;
struct gaa_unevaluated_cred_struct {
gaa_cred_type              cred_type;
gaa_principal_ptr          grantor;
gaa_principal_ptr          grantee;
gaa_buffer_ptr             mech_spec_cred;
void (*cred_verification)(gaa_sec_context_ptr, va_list ap);
gaa_unevaluated_cred_ptr   next;
};


2.6 GAA API answer data structure

The gaa_check_authorization function returns various information to
the application for further evaluation in the gaa_answer data
structure.

The gaa_answer type is a structure containing the following fields:

valid_time
A pointer to a structure of type gaa_time_period. It specifies the
time period during which the authorization is granted and

Ryutov/Neuman                               Expires February 1999

is returned as a condition to be checked by the application.
Expiration time is calculated by the GAA API, based on:
  - time-related conditions in the ACL matching entries
  - restrictions in the attributes, identity, authorization and
    group membership credentials

granted_raccess_rights
A pointer to a linked list of structures of the type
gaa_acl_access_rights_set

conditions
A pointer to a list of structures of type gaa_conditions,
which lists all different conditions for the granted access rights

required_sec_attributes
Contains a pointer to a gaa_value_type_list structure, which
contains information about additional security attributes required,
e.g. group membership or authorized credentials.

typedef struct gaa_time_period_struct  gaa_time_period,
                                      *gaa_time_period_ptr;
struct gaa_time_period_struct{
   time_t    start_time; /* NULL for unconstrained start time */
   time_t    end_time;   /* NULL for unconstrained end time */
};


typedef struct gaa_answer_struct gaa_answer, *gaa_answer_ptr;

struct gaa_answer_struct{
   gaa_time_period_ptr        valid_time;
   gaa_access_rights_set_ptr  granted_access_rights;
   gaa_conditions_ptr         conditions;
   gaa_tag_value_list_ptr     required_sec_attributes
};

3. Memory allocation

Storage for data returned to the application by a GAA API routine
using gaa_buffer_ptr,  gaa_tag_value_list_ptr, gaa_tag_vector_list
is allocated by the GAA API routines. The application may clear this
storage by invoking the gaa_release_buffer, gaa_release_tag_value_list
and gaa_release_tag_vector_list routines.
Allocation of the gaa_buffer, gaa_tag_value_list, gaa_tag_vector_list
and gaa_sec_context structures is always the responsibility of the
application.

4. Status codes

One or two status codes are returned by each GAA API routine.  Two
distinct sorts of status codes are returned. These are the GAA API
status codes and mechanism-specific status codes.

4.1 The GAA API status codes


Ryutov/Neuman                               Expires February 1999

GAA API routines return GAA API status codes as their gaa_error_code
function value. These codes indicate errors that are independent of
the underlying mechanisms. The errors that can be indicated via a
GAA API status code are either generic API routine errors (errors that
are defined in the GAA API specification) or calling errors (errors
that are specific to these language bindings).

4.2 Mechanism-specific status codes

GAA API routines return a minor_status parameter, which is used to
indicate specialized errors from the underlying mechanisms or
provide additional information about GAA API errors.
The GAA status code GAA_FAILURE is used to indicate that the
underlying mechanism detected an error for which no specific GAA
status code is defined. The mechanism status code will provide more
details about the error.

5. GAA API routine descriptions

This section lists the functions performed by each of the GAA API
routines and discusses their major parameters, describing how they
are to be passed to the routines.

5.1 gaa_get_object_acl routine

Purpose:

The gaa_get_object_acl function is called to obtain a handle to an
object ACL.

Parameters:

minor_status  mechanism-specific status code

object
Reference to the object to be accessed. The identifier for the object
is from an application-specific name space and is opaque to the
GAA API.

authr_db
Pointer to an application-specific authorization database

retrieve
Upcall function for the retrieval of the object ACL.
The application maintains authorization information in a form
understood by the application. It can be stored in a file, database,
directory service or in some other way. The upcall function provided
for the GAA API retrieves the ACL and translates it into the internal
GAA API representation.

acl_handle
A pointer to a handle bound to the ACL that is the subjects
of examination.
An unbound handle has the value GAA_ACL_UNBOUND.


Ryutov/Neuman                               Expires February 1999

Function value:

GAA status code:

GAA_FAILURE    Failure, see minor_status for more information

gaa_error_code
gaa_get_object_acl(int*               minor_status, /* OUT */
                   gaa_data_ptr       object,       /* IN  */
                   gaa_data_ptr       authr_db,     /* IN  */
                   void*(*retrieve)(gaa_data_ptr  object,
                                    gaa_data_ptr  authr_db,
                                    ...)           /* IN  */
                   gaa_acl_list_ptr*  acl_handle , /* OUT */);


5.2 gaa_check_authorization routine

Purpose:

The gaa_check_authorization function tells the application whether
the requested access rights are authorized, or if additional
application-specific checks are required.

Parameters:

minor_status
Mechanism specific status code

acl_handle
A handle to the ACL, returned by the gaa_get_object_acl routine

sec_context
Principal's security context

check_access_rights
List of access rights for authorization. This argument is optional.

detailed_answer
Contains various information for further evaluation by the application

gaa_options
Describes the behavior of the GAA API and specifies how the other
arguments should be interpreted. For example, type of the ACL: ordered
or unordered. Depending on this type corresponding ACL evaluation
algorithm will be used by the GAA API. This argument is optional.

detailed_answer
Contains various information for further evaluation by the application

Function value:

GAA status code:

GAA_FAILURE

Ryutov/Neuman                               Expires February 1999

Failure, see minor_status for more information

GAA_NO_CONTEXT
No valid security context was supplied

GAA_AUTHORIZED
Is returned if all requested operations are authorized

GAA_NOT_AUTHORIZED
Is returned if at least one operation is not authorized

GAA_ADDITIONAL_CHECKS_REQIRED
Is returned if there are some unevaluated conditions and additional
application-specific checks are needed or if continuous valuation
of the conditions is required.


gaa_error_code
gaa_check_authorization
       (int*                    minor_status,         /* OUT          */
        gaa_sec_context_ptr     sec_context,          /* IN&OUT       */
        gaa_acl_list_ptr        acl_handle,           /* IN           */
        gaa_tag_vector_list_ptr check_access_rights,  /* IN, OPTIONAL */
        gaa_tag_value_list_ptr  gaa_options           /* IN, OPTIONAL */
        gaa_answer_struct_ptr   detailed_answer       /* OUT          */
       );


5.3 gaa_allocate_sec_context routine

Purpose:
Allocate a security context data structure and assign default values

Parameters:

minor_status
Mechanism specific status code

acl_handle
A handle bound to a pointer to the security context structure

Function value:

GAA API status code:

GAA_SUCCESS
Successful completion

GAA_FAILURE
Failure, see minor_status for more information

gaa_error_code
gaa_allocate_sec_context
              (int*                  minor_status,      /* OUT    */
               gaa_sec_context_ptr*  sec_context_handle /* IN&OUT */);

Ryutov/Neuman                               Expires February 1999


5.4 gaa_release_sec_context routine

Purpose:

Delete a security context. The gaa_delete_sec_context routine will
delete the local data structures associated with the specified
security context.

Parameters:

minor_status
Mechanism specific status code

sec_context_handle
A handle bound to a pointer to the security context structure

Function value:

GAA status code:

GAA_SUCCESS
Successful completion

GAA_FAILURE
Failure, see minor_status for more information

gaa_error_code
gaa_release_sec_context
           (int* minor_status,                      /* OUT */
            gaa_sec_context_ptr* sec_context_handle /* IN  */)


5.5 gaa_allocate_buffer routine

Purpose:
Allocate a gaa_buffer data structure and assign default
values

Parameters:

minor_status
Mechanism-specific status code

buffer
Pointer to allocated memory for gaa_buffer structure

Function value:

GAA status code:

GAA_SUCCESS
Successful completion

GAA_FAILURE

Ryutov/Neuman                               Expires February 1999

Failure, see minor_status for more information

GAA_NO_BUFFER
No valid buffer was supplied

gaa_error_code
gaa_allocate_buffer
        (int*                  minor_status, /* OUT */
         gaa_buffer_ptr*       buffer        /* IN  */);


5.6 gaa_release_buffer routine

Purpose:

Free storage associated with a buffer format name.  The storage must
have been allocated by a GAA API routine. In addition to freeing the
associated storage, the routine will zero the length field in the
buffer parameter.

Parameters:

minor_status
Mechanism-specific status code

Ryutov/Neuman                               Expires February 1999


buffer
The storage associated with the buffer will be deleted.
The gaa_buffer object will not be freed, but its length field will
be zeroed.

Function value:

GAA status code:

GAA_SUCCESS
Successful completion

GAA_FAILURE
Failure, see minor_status for more information

GAA_NO_BUFFER
No valid buffer was supplied

gaa_error_code
gaa_release_buffer (int *            minor_status, /* OUT */
                    gaa_buffer_ptr   buffer        /* IN */);


5.7 gaa_allocate_tag_value_list routine

Purpose:
Allocate a gaa_tag_value_list data structure and assign default values

Ryutov/Neuman                               Expires February 1999

Parameters:

minor_status
Mechanism-specific status code

buffer
Pointer to allocated memory for gaa_tag_value_list structure

Function value:

GAA status code:

GAA_SUCCESS
Successful completion

GAA_FAILURE
Failure, see minor_status for more information

GAA_NO_BUFFER
No valid buffer was supplied

gaa_error_code
gaa_allocate_tag_value_list
        (int*                    minor_status, /* OUT */
         gaa_tag_value_list_ptr* buffer        /* IN  */);



5.8 gaa_release_tag_value_list routine

Purpose:
Free storage associated with a buffer

Parameters:

minor_status
Mechanism-specific status code

buffer
The storage associated with the buffer will be deleted

Function value:

GAA status code:

GAA_SUCCESS
Successful completion

GAA_FAILURE
Failure, see minor_status for more information

GAA_NO_BUFFER
No valid buffer was supplied

gaa_error_code

Ryutov/Neuman                               Expires February 1999

gaa_release_buffer
        (int*                    minor_status, /* OUT */
         gaa_tag_value_list_ptr* buffer        /* IN  */);


5.9 gaa_allocate_tag_vector_list  routine

Purpose:
Allocate a gaa_tag_vector_list data structure and assign default
values

Parameters:

minor_status
Mechanism-specific status code

buffer
Pointer to allocated memory for gaa_tag_vector_list structure


Function value:

GAA status code:

GAA_SUCCESS
Successful completion

GAA_FAILURE

Failure, see minor_status for more information

GAA_NO_BUFFER
No valid buffer was supplied

gaa_error_code
gaa_allocate_tag_vector_list
     (int *  minor_status,            /* OUT */
      gaa_tag_vector_list_ptr* buffer /* IN  */);



5.10 gaa_release_tag_vector_list routine

Purpose:
Free storage associated with a buffer

Parameters:

minor_status
Mechanism-specific status code

buffer
The storage associated with the buffer will be deleted

Function value:

Ryutov/Neuman                               Expires February 1999

GAA status code:

GAA_SUCCESS
Successful completion

GAA_FAILURE
Failure, see minor_status for more information

GAA_NO_BUFFER
No valid buffer was supplied

gaa_error_code
gaa_release_tag_vector_list
             (int*  minor_status,       /* OUT */
              gaa_tag_vector_ptr* buffer /* IN  */);

5.11 gaa_parse_acl routine

Purpose:
Parse the ASCII file in the pre-defined format described in
draft-ietf-cat-acc-cntrl-frmw-00.txt into the GAA API internal ACL
structures.

Parameters:

minor_status
Mechanism-specific status code

acl_file_handle
A pointer to an ASCII file containing an ACL for the object in
the pre-defined format

acl_handle
A handle to the gaa_acl structure

application_access_rights
A pointer to the list of application-specific names for access
rights. GAA API uses it to build bit-vectors for internal access
rights representation.
This parameter is optional. It is not required if the ACL contains
bit-vector representation of the access rights, for example:

USER  kerberos.v5 joe@ISI.EDU
 < FILE : 1100000000000000000000000000000000 >   time_window : 7AM-7PM
                                                 time_day : Mon-Fri
 < ACCOUNT : 1100000000000000000000000000000000 >location : *.isi.edu ;

In this case the value is set to GAA_NO_TAG_VALUE_LIST.

Function value:

GAA status code:

GAA_SUCCESS
Successful completion

Ryutov/Neuman                               Expires February 1999

GAA_FAILURE
Failure, see minor_status for more information

gaa_error_code
gaa_parse_acl
 (int *  minor_status,                              /* OUT           */
  FILE                    *acl_file_handle,         /* IN            */
  gaa_acl_ptr*            acl_handle,               /* IN&OUT        */
  gaa_tag_value_list_ptr  application_access_rights /* IN, OPTIONAL  */);


6. The GAA API constants

The following constants are used in GAA API calls and structures,
this list is not complete:

#define GAA_NO_BUFFER             ((gaa_buffer_ptr) 0)
#define GAA_EMPTY_BUFFER          {0, NULL}
#define GAA_NO_DATA               ((gaa_data_ptr)0)
#define GAA_NO_TAG_VALUE_LIST     ((gaa_tag_value_list_ptr)0)

#define GAA_ACL_UNBOUND           ((gaa_acl_ptr)0)
#define NO_EACL_ENTRY             ((gaa_acl_entry_ptr) 0)
#define NO_PRINCIPALS             ((gaa_acl_principal_list_ptr) 0)
#define NO_ACCESS_RIGHTS          ((gaa_acl_access_rights_set_ptr) 0)
#define GAA_NO_CONDITIONS         ((gaa_conditions_ptr)0)

7. The GAA API flags

Flags are 32 bits.

Condition flags:

#define COND_FLG_EVALUATED        0x80000000
#define COND_FLG_SATISFIED        0x40000000
#define COND_FLG_ENFORCE          0x20000000

Flags from 0x10000000 to 0x00000001 are reserved.

8. Acknowledgments

Gene Tsudik, Brian Tung, Bapa Rao, Ilia Ovsiannikov and the Xerox IS
team have contributed to discussion of ideas and material in this
draft.

9. References

[1] Linn, J., "Generic Security Service Application Program
    Interface", RFC 1508, Geer Zolot Associate, September 1993.

[2] Wray, ., "Generic Security Service Application Program
    Interface V2 - C bindings", Internet draft, May 1997.


10. Authors' Addresses

Ryutov/Neuman                               Expires February 1999

Tatyana Ryutov
Clifford Neuman
USC/Information Sciences Institute
4676 Admiralty Way Suite 1001
Marina del Rey, CA 90292-6695
Phone: +1 310 822 1511
E-Mail: {tryutov, bcn}@isi.edu