INTERNET-DRAFT                        Tatyana Ryutov
CAT Working Group                     Clifford Neuman
Expires January 2001                  USC/Information Sciences Institute
draft-ietf-cat-gaa-cbind-04.txt       July 11, 2000

Generic Authorization and Access control Application Program Interface
                       C-bindings

0. Status Of this Document

This document is an Internet-Draft and is in full conformance
with all provisions of Section 10 of RFC2026.

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."

The list of current Internet-Drafts can be accessed at
http://www.ietf.org/ietf/1id-abstracts.txt

The list of Internet-Draft Shadow Directories can be accessed at
http://www.ietf.org/shadow.html.

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-04.txt


2. Design approach

We propose a pseudo-object-oriented approach inspired by the programming
style used in [3].
This approach provides an organized representation of the GAA-API concepts and
entities. It defines an encapsulating interface for mapping of particular
GAA-API implementation to the standardized GAA-API entities.
Objects are represented as pointers to pseudo-class structures.
Throughout this draft we use term "class" to refer to a pseudo-class, which is
implemented using C structures and imitate object-oriented design.

2.1. The abstract class

The abstract class describes concepts common across class implementations,
including object creation, initialization, deletion, methods and
attributes.
Concrete class instances define data for attributes and code for class's methods.
We define three abstract classes: gaa, gaa_policy and gaa_sc.
The general structure of each abstract class is depicted in Figure 1.

2.1.1. The abstract class data structure

The abstract class data structure contains the following fields:

abstract_class_method
The abstract_class_method is a pointer to the abstract_class_method data structure.
This field is present in each GAA-API class.

abstract class attributes
The abstract class attributes represent a set of data variables, which are
elaborated by the specific instances of a GAA-API class.

abstract_class_new(abstract_class_method_ptr method,
                   abstract_class_ptr       *class,
                   gaa_handle_ptr            arglist)

The abstract_class_new method creates a new class. Implementation-dependent
information for class creation is supplied using arglist parameter. This method
is present in each GAA-API class.

abstract_class_set(abstract_class_method_ptr  method,
                   abstract_class_ptr         class,
                   gaa_handle_ptr             arglist)

The abstract_class_set initializes appropriate fields of the abstract_class_method
structure (attributes and methods).
Implementation-dependent information needed to appropriately initialize the
class values is supplied using arglist parameter. This method is present in
each GAA-API class.

abstract_class_free(abstract_class_ptr class,
                    gaa_handle_ptr     arglist)

The abstract_class_free frees the class structure. Depending on the configuration,
this will free the underlying data object. This method is present in each GAA-API
class.

abstract class methods
The abstract class methods are handles to the respective C functions, which
implement the remaining class methods. Some of the handles can be NULL if not
implemented. The abstract class methods differ across GAA-API classes.

2.1.2. The abstract class method data structure

The abstract class method structure contains the following fields:

type
The type is the numeric type of the abstract class method. This field is present in
each GAA-API class.

name
The name is a textual representation of the abstract class method of type  "type".
This field is present in each GAA-API class.

abstract class method attributes
The abstract class method attributes are handles to the respective C functions,
which implement the remaining methods of the abstract class method data structure.
Some of the handles can be NULL if not implemented. The abstract class methods
differ across GAA-API class method data structures.

create()
The create method creates a new instance of class method structure of type "type".
This method is present in each GAA-API class method data structure.

destroy()
The destroy frees class method structure of type "type". This method is present in
each GAA-API class method data structure.

The abstract class method methods are handles to the respective C functions, which
implement the methods. Some of them can be NULL if not implemented.

-------------------------------------------------------         -----------------------
|            abstract class                           |         |abstract class method|
|     (gaa, gaa_policy and gaa_sc)                    |         |---------------------|
|-----------------------------------------------------|         |     attributes      |
|           attributes                                |         |                     |
|                                                     |points to| int   type          |
|abstract_class_method  *method ----------------------|-------->| char *name          |
| abstract class attributes                           |         | abstract class      |
|-----------------------------------------------------|         | method attributes   |
|             methods                                 |         |---------------------|
|                                                     |         |      methods        |
|abstract_class_new(abstract_class_method_ptr method, |         |                     |
|                   abstract_class_ptr       *class,  |         | create()            |
|                   gaa_handle_ptr            arglist)|         | destroy()           |
|                                                     |         |                     |
|abstract_class_set(abstract_class_method_ptr method, |         |abstract class method|
|                   abstract_class_ptr        class,  |         |methods              |
|                   gaa_handle_ptr            arglist)|         -------^--------------
|                                                     |                ||
|abstract_class_free(abstract_class_ptr class,        |                || maps to
|                    gaa_handle_ptr     arglist)      |                ||
|                                                     |                ||
|      abstract class methods                         |                ||
-------------------------------------------------------                ||
                                     ----------------------------------||-
                                     |      concrete class method        |
                                     |-----------------------------------|
                                     |         attributes                |
                                     |                                   |
                                     | type = concrete_type              |
                                     | name = concrete_name              |
                                     |                                   |
                                     | concrete class attributes         |
                                     |-----------------------------------|
                                     |          methods                  |
                                     |                                   |
                                     | concrete_create()                 |
                                     | concrete_destroy()                |
                                     |                                   |
                                     | concrete class methods            |
                                     ------------------------------------

                              Figure 1.


2.2. Concrete class method

The concrete class method contains concrete values for the abstract
class method attributes and methods, which are initialized by the
abstract_class_set function.

3. The GAA-API data types and calling conventions

The data types described in this specification refer only  to the fields
that must be provided by all conforming GAA-API implementations. Individual
implementations may provide additional fields for internal use within the
GAA-API routines.

3.1. Opaque data

Some data items are considered opaque to the GAA-API, because their
internal data structure has no significance to the GAA-API or the calling
application, e.g. actual mechanism-specific credentials.

3.1.1. Byte buffer

This type of data is passed between the GAA-API and the caller using
a byte buffer referenced by the gaa_buffer_ptr data type, which is a
pointer to a gaa_buffer structure.

The gaa_buffer type is a buffer descriptor containing the following fields:

length
The length contains the total number of bytes that the data occupies.

value
The value contains a pointer to the actual data.

typedef struct gaa_buffer_struct gaa_buffer,
                                *gaa_buffer_ptr,
                                 gaa_options,
                                *gaa_options_ptr;

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

3.1.2. Implementation-specific data

A number of GAA-API routines need to receive implementation-specific
arguments and return implementation-specific values.
The structure of the passed and returned information varies for different
implementations, which makes it difficult to standardize the structure.
Data of this type may be regarded as an opaque handle to the
implementation-specific data structure and are passed between the GAA-API
and caller using the gaa_handle_ptr data structure.

unsigned long gaa_handle_ptr

Allocation, release and maintenance routines of the underling structure
are GAA-API implementation-specific and are not defined in this specification.

3.2. Character data

Certain data items used by the GAA-API may be regarded as a character
strings, e.g., string-encoded tokens for passing object and authorization
database identifiers. The data of this kind is passed between the GAA-API and
caller using the gaa_string_data data type, which is a pointer to
 '\0' terminated C character array:

typedef char *gaa_string_data;


3.3. Ordered list data

Certain data items used by the GAA-API may be regarded as an ordered list of
data items, e.g., a list of identity credentials. Data of this type are passed
between the GAA-API and a caller using the gaa_list_ptr data structure.

unsigned long gaa_list_ptr

List allocation, release and maintenance routines are GAA-API implementation
specific and are not defined in this specification.
A possible candidate for implementation of this data type can be STACK
structure defined in [3].

3.4. The GAA-API constants

The following constants are used in GAA-API calls and structures:

  GAA_C_YES       0 (indicates authorization) is returned if all
                    requested operations are authorized.

  GAA_C_NO        1 (indicates denial of authorization) is returned
                    if at least one operation is not authorized.

  GAA_C_MAYBE     2 (indicates a need for additional checks) is
                    returned if there are some unevaluated conditions
                    and additional application specific checks are needed,
                    or continuous evaluation is required.

3.5. The GAA-API flags

Flags are 32 bits.

Condition flags:

  COND_FLG_EVALUATED    0x01  condition has been evaluated
  COND_FLG_MET          0x10  condition has been met
  COND_FLG_ENFORCE      0x100 condition has to be enforced


3.6. Status codes

The GAA-API routines return a status code of type gaa_status.

unsigned long gaa_status

Encapsulated in the returned status code are major and minor status codes.
Each of them has a value range equivalent to 16 bit unsigned integer values.
The major codes indicate errors that are independent of the underlying mechanisms.
The errors that can be indicated via a GAA-API major status code are generic API
routine errors (errors that are defined in this specification).

The minor code is implementation-dependent and is used to indicate specialized
errors from the underlying mechanisms or provide additional information about
the GAA-API errors.


  GAA_S_SUCCESS                      0   Successful completion.

  GAA_S_FAILURE                      3   The underlying mechanism detected an
                                         error for which no specific GAA-API
                                         status code is defined. The minor code
                                         provides details about the error.

  GAA_S_INVALID_LIST_HNDL            4   The handle supplied does not point to a
                                         valid gaa_list structure.

  GAA_S_INVALID_GAA_HNDL             5   The handle supplied does not point to a
                                         valid gaa structure.

  GAA_S_INVALID_GAA_METHOD_HNDL      6   The handle supplied does not point to a
                                         valid gaa_method structure.

  GAA_S_INVALID_ANSWER_HNDL          7   The handle supplied does not point to a
                                         valid gaa_answer structure.

  GAA_S_INVALID_POLICY_HNDL          10  The handle supplied does not point to a
                                         valid gaa_policy structure.

  GAA_S_INVALID_POLICY_METHOD_HNDL   11  The handle supplied does not point to a
                                         valid gaa_policy_method structure.

  GAA_S_INVALID_SC_HNDL              12  The handle supplied does not point to a
                                         valid gaa_sc structure.

  GAA_S_INVALID_SC_METHOD_HNDL       13  The handle supplied does not point to a
                                         valid gaa_sc_method structure.

  GAA_S_INVALID_POLICY_ENTRY_HNDL    15  The handle supplied does not point to a
                                         valid gaa_policy_entry structure

  GAA_S_INVALID_CONDITION_HNDL       16  The handle supplied does not point to a
                                         valid gaa_condition structure.

  GAA_S_INVALID_RIGHT_HNDL           17  The handle supplied does not point to a
                                         valid gaa_right structure.

  GAA_S_INVALID_STRING_DATA_HNDL     18  The handle supplied does not point to a
                                         valid gaa_string_data structure.

  GAA_S_INVALID_OPTIONS_HNDL         19  The handle supplied does not point to a
                                         valid gaa_options structure.

  GAA_S_INVALID_BUFFER_HNDL          20  The handle supplied does not point to a
                                         valid gaa_buffer structure.

  GAA_S_INVALID_ATTRIBUTE_HNDL       21  The handle supplied does not point to a
                                         valid gaa_attribute structure.

  GAA_S_INVALID_AUTHR_CRED_HNDL      22  The handle supplied does not point to a
                                         valid gaa_authr_cred structure.

  GAA_S_INVALID_UNEVAL_CRED_HNDL     23  The handle supplied does not point to a
                                         valid gaa_uneval_cred structure.

  GAA_S_UNIMPLEMENTED_FUNCTION       24  The function is not supported by
                                         underlying implementation.

  GAA_S_NO_MATCHING_ENTRIES          25  No matching policy entries have been
                                         found for the requested right.

  GAA_S_POLICY_PARSING_FAILURE       26  Indicates an error during policy
                                         parsing.

  GAA_S_POLICY_RETRIEVING_FAILURE    27  Indicates an error during policy
                                         retrieval process.

3.7. GAA-API data structures

3.7.1. gaa_struct data structure

The gaa_struct structure implements the gaa abstract class.
See section 2 for explanation of the meaning of the fields
method, gaa_new, gaa_set and gaa_free.

typedef struct gaa_struct  gaa,
                          *gaa_ptr;

struct gaa_struct
{
  /* attributes */

  gaa_method_ptr  method;

  /* methods */

  gaa_status (*gaa_new)(gaa_method_ptr  method,
                        gaa_ptr        *gaa,
                        gaa_handle_ptr  arglist);

  gaa_status (*gaa_set)(gaa_method_ptr  method,
                        gaa_ptr         gaa,
                        gaa_handle_ptr  arglist);

  gaa_status (*gaa_free)(gaa_ptr         gaa,
                         gaa_handle_ptr  arglist);
};

3.7.2. gaa_method_struct data structure

The gaa_method_struct structure implements the gaa abstract class method.
The structure contains information about behavior of the GAA_API evaluation
routines.

The gaa_method_struct structure contains the following fields:

condition_evaluation
The condition_evaluation is a handle to an application-specific condition
evaluation function provided by the calling application. The function is
called by GAA-API if there are application-specific conditions. Generic
(understood by the GAA-API) conditions are evaluated by the GAA-API internal
functions.

calculate_validity_time
The calculate_validity_time is a handle to an implementation-specific function
provided by the calling application. The function is called by the GAA-API to
set the authorization validity time period in the gaa_answer data structure, see
section 3.8.

See section 2 for explanation of the meaning of the fields type,
name, create and destroy.

typedef struct gaa_method_struct  gaa_method,
                                 *gaa_method_ptr;

struct gaa_method_struct
{
 /* attributes */

  int   type;
  char *name;

 /* methods */

  gaa_status (*condition_evaluation)();
  gaa_status (*calculate_validity_time)();
  gaa_status (*create)();
  gaa_status (*destroy)();
};

3.7.3. gaa_policy_struct data structure

The gaa_struct structure implements the gaa_policy abstract class.
The gaa_policy_struct structure contains the following fields:

policy
The policy is a pointer to the byte buffer, containing the authorization policy
in application-specific format.

matching_entries
The matching_entries is a pointer to an ordered list of elements of type
gaa_policy_entry_ptr returned by the get_matching_entries function, see next
section.

See section 2 for explanation of the meaning of the fields
method, gaa_policy_new, gaa_policy_set and gaa_policy_free.

typedef struct gaa_policy_struct  gaa_policy,
                                 *gaa_policy_ptr;

struct gaa_policy_struct
{
  /* attributes */

  gaa_policy_method_ptr  method;
  gaa_buffer_ptr         policy;
  gaa_list_ptr /* gaa_policy_entry_ptr  */ matching_entries;

  /* methods */

  gaa_status (*gaa_policy_new)(gaa_policy_method_ptr method,
                               gaa_policy_ptr       *policy,
                               gaa_handle_ptr        arglist);

  gaa_status (*gaa_policy_set)(gaa_policy_method_ptr method,
                               gaa_policy_ptr        policy,
                               gaa_handle_ptr        arglist);

  gaa_status (*gaa_policy_free)(gaa_policy_ptr policy,
                                gaa_handle_ptr arglist);

};

3.7.4. gaa_policy_method_struct data structure

The gaa_policy_method_struct structure implements the gaa_policy abstract
class method. The gaa_policy_method_struct structure contains the following
fields:

eval
The eval specifies a policy evaluation approach: based on the order, based on
priority or unordered. The default value is the ordered policy evaluation.

get_matching_entries
The get_matching_entries is a handle to an application-specific function for
retrieval of the matching entries. The function looks through the policy in
application-specific format and finds policies associated with the requested_right.
Then these right-specific policies are translated to the gaa_policy_entry_ptr
and as the result, the function returns an ordered list of elements of type
gaa_policy_entry_ptr (see section 3.7.5.), which are then evaluated by the GAA_API
routines.

Return value:

 GAA_S_SUCCESS
 GAA_S_INVALID_POLICY_HNDL
 GAA_S_NO_MATCHING_ENTRIES

retrieve
The retrieve is a handle to an application-specific function for the retrieval of
the object authorization policy. 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 this information.

Return value:

 GAA_S_SUCCES
 GAA_S_FAILURE
 GAA_S_POLICY_RETRIEVING_FAILURE
 GAA_S_POLICY_PARSING_FAILURE

See section 2 for explanation of the meaning of the fields: type,
name, create and destroy.

typedef enum  {
 GAA_ORDERED_EVAL  ,
 GAA_PRIORITY_EVAL ,
 GAA_UNORDERED_EVAL
 } gaa_eval_type;


typedef struct gaa_policy_method_struct  gaa_policy_method,
                                        *gaa_policy_method_ptr;

struct gaa_policy_method_struct
{
  /* attributes */

  int            type;
  char          *name;
  gaa_eval_type  eval;

  /* methods */

  gaa_status (*get_matching_entries)(gaa_buffer_ptr policy,           /* IN  */
                                     gaa_right_ptr  requested_right,  /* IN  */
                                     gaa_list_ptr  *matching_entries  /* OUT */);

  gaa_status (*retrieve)(gaa_string_data  object,         /* IN  */
                         gaa_string_data  policy_db,      /* IN  */
                         gaa_buffer_ptr  *buffer, ... );  /* OUT  */

  gaa_status (*create)();
  gaa_status (*destroy)();
};


3.7.5. gaa_policy_entry_struct data structure

The gaa_policy_entry_struct structure contains the following fields:

num
The num indicates entry number in the policy. It is used by the GAA_API
evaluation routines.

priority
The priority specifies the priority of this entry. It is used by the GAA_API
evaluation routines.

rights
The rights is pointer to a linked list of elements of the type gaa_right_ptr.
Each element indicates granted or denied access rights.

typedef struct gaa_policy_entry_struct  gaa_policy_entry,
                                       *gaa_policy_entry_ptr;

struct gaa_policy_entry_struct {
   int  num;
   int  priority;
   gaa_list_ptr /* gaa_right_ptr */ rights;
};


3.7.6. gaa_right_struct data structure

The gaa_right_struct structure contains the following fields:

type
The type defines the type of the token.

authority
The authority indicates the authority responsible for defining the
value within the token type.

value
The value indicates the value of the token. The name space for the
value is defined by the authority field.

conditions
The conditions is a pointer to an ordered list of elements of type gaa_condition_ptr.
It contains a list of pointers to conditions associated with the right.

typedef struct gaa_right_struct  gaa_right,
                                *gaa_right_ptr;
struct gaa_right_struct {
   gaa_string_data  type;
   gaa_string_data  authority;
   gaa_string_data  value;
   gaa_list_ptr /* gaa_condition_ptr */ conditions;
};


3.7.7. gaa_condition_struct data structure

The gaa_condition_struct  structure contains the following fields:

type
The type defines the type of the token.

authority
The authority indicates the authority responsible for defining the
value within the token type.

value
The value indicates the value of the token. The name space for the
value is defined by the authority field.

conditions
The condition is a pointer to an ordered list of elements of type gaa_condition_ptr.
It contains a list of pointers to conditions associated with the right.

status
The status contains flags, indicating if the condition evaluation status.

typedef struct gaa_condition_struct  gaa_condition,
                                    *gaa_condition_ptr;

struct gaa_condition_struct {
   gaa_string_data  type;
   gaa_string_data  authority;
   gaa_string_data  value;
   unsigned long    status;
};


3.7.8. gaa_sec_attrb_struct data structure

The gaa_sec_attrb_struct structure contains the following fields:

type
The type defines the type of the token.

authority
The authority indicates the authority responsible for defining the
value within the token type.

value
The value indicates the value of the token. The name space for the
value is defined by the authority field.

struct gaa_sec_attrb_struct {
   gaa_string_data  type;
   gaa_string_data  authority;
   gaa_string_data  value;
};

3.7.9. GAA-API Security Context data structures

The gaa_sc_struct structure implements the gaa_sc abstract class, which
stores information relevant to access control.

3.7.9.1. gaa_sc_struct data structure

The gaa_sc_struct structure contains the following fields:

sc
The sc is a pointer to a byte buffer, containing the mechanism-specific
security context structure.

identity_cred
The identity_cred is a pointer to an ordered list of elements of the type
gaa_identity_cred_ptr, containing principal's identity credentials. It is
returned by the get_identity_cred function, see next section.

authr_cred
The authr_cred is a pointer to an ordered list of elements of the
type gaa_authr_cred_ptr, containing principal's authorization credentials.
It is returned by the get_authr_cred function, see next section.

group_membership
The group_membership is a pointer to an ordered list of elements of the
type gaa_identity_cred_ptr, which specifies that the grantee is a member of
only the listed groups. It is returned by the get_group_membership_cred function,
see next section.

group_non_membership
The group_non_membership is a pointer to an ordered list of elements of
the type gaa_identity_cred_ptr, which specifies that the grantee is NOT a
member of the listed groups. It is returned by the get_group_non_membership_cred
function, see next section.

attributes
The attributes is a pointer to an ordered list of elements of the type
gaa_attribute_ptr, which contains miscellaneous attributes attached to
the grantee, e.g., age or security clearance.

uneval_cred
The uneval_cred is a pointer to an ordered list of elements of type
gaa_uneval_cred_ptr, containing unevaluated credentials of different types.
It is returned by the get_uneval_cred function, see next section.

connection_state
The connection_state is a pointer to a byte buffer, containing a
mechanism-specific representation of per-connection context, some of the
data stored here include keyblocks and addresses.

See section 2 for explanation of the meaning of the fields
method, gaa_sc_new, gaa_sc_set and gaa_sc_free.

typedef struct gaa_sc_struct  gaa_sc,
                             *gaa_sc_ptr;
struct gaa_sc_struct
{
 /* attributes */

  gaa_sc_method_ptr  method;
  gaa_buffer_ptr     sc;

  gaa_list_ptr /* gaa_identity_cred_ptr */ identity_cred;
  gaa_list_ptr /* gaa_authr_cred_ptr    */ authr_cred;
  gaa_list_ptr /* gaa_identity_cred_ptr */ group_membership_cred;
  gaa_list_ptr /* gaa_identity_cred_ptr */ group_non_membership_cred;
  gaa_list_ptr /* gaa_attribute_ptr     */ attributes;
  gaa_list_ptr /* gaa_uneval_cred_ptr   */ uneval_cred;

  gaa_buffer_ptr connection_state;

/* methods */

  gaa_status (*gaa_sc_new)(gaa_sc_method_ptr method,
                           gaa_sc_ptr       *sc,
                           gaa_handle_ptr    arglist);

  gaa_status (*gaa_sc_set)(gaa_sc_method_ptr method,
                           gaa_sc_ptr        sc,
                           gaa_handle_ptr    arglist);

  gaa_status (*gaa_sc_free)(gaa_sc_ptr      sc,
                            gaa_handle_ptr  arglist);
};



3.7.9.2. gaa_sc_method_struct data structure

The gaa_sc_method_struct structure implements the gaa_sc abstract class method.
The gaa_sc_method_struct structure contains the following fields:

get_identity_cred
The get_identity_cred is a handle to an application-specific function, which
translates mechanism-specific credentials to the GAA_API internal structure.
It returns an ordered list of elements of type gaa_identity_cred_ptr
see section 3.7.9.3, can be NULL if not implemented.

get_authr_cred
The get_authr_cred is a handle to an application-specific function, which
translates mechanism-specific credentials to the GAA_API internal structure.
It returns an ordered list of elements of type gaa_authr_cred_ptr see
section 3.7.9.4, can be NULL if not implemented.

get_group_membership_cred
The get_group_membership_cred is a handle to an application-specific function,
which translates mechanism-specific credentials to the GAA-API internal structure.
It returns an  ordered list of elements of type gaa_identity_cred_ptr see
section 3.7.9.3, can be NULL if not implemented.

get_group_non_membership_cred
The get_group_non_membership_cred is a handle to an application-specific
function, which translates mechanism-specific credentials to the GAA API
internal structure. It returns an ordered list of elements of type
gaa_identity_cred_ptr see section 3.7.9.3, can be NULL if not implemented.

get_attributes
The get_attributes is a handle to an application-specific function, which
translates mechanism-specific credentials to the GAA API internal structure.
It returns an ordered list of elements of type gaa_attribute_ptr see
section 3.7.9.5, can be NULL if not implemented.

get_uneval_cred
The get_uneval_cred is a handle to an application-specific function, which
translates mechanism-specific credentials to the GAA-API internal structure.
It returns an ordered list of objects of type gaa_uneval_cred_ptr see
section 3.7.9.6, can be NULL if not implemented.

pull_cred
The pull_cred is a handle to an application-specific function, which 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
The cred_evaluate is a handle to an application-specific function, which parses
the contents of the acquired credentials into the GAA-API internal form and
evaluate them.

See section 2 for explanation of the meaning of the fields type,
name, create and destroy.

typedef struct gaa_sc_method_struct  gaa_sc_method,
                                    *gaa_sc_method_ptr;

struct gaa_sc_method_struct
{
  /* attributes */

  int   type;
  char *name;

  /* methods */

    gaa_list_ptr /* gaa_identity_cred_ptr */
                (*get_identity_cred)();
    gaa_list_ptr /* gaa_authr_cred_ptr    */
                (*get_authr_cred)();
    gaa_list_ptr /* gaa_identity_cred_ptr */
                (*get_group_membership_cred)();
    gaa_list_ptr /* gaa_identity_cred_ptr */
                (*get_group_non_membership_cred)();
    gaa_list_ptr /* gaa_attribute_ptr     */
                (*get_attributes)();
    gaa_list_ptr /* gaa_uneval_cred_ptr   */
                (*get_uneval_cred)();

   void
   (*condition_evaluation)();

   void
   (*pull_cred)();

   void
   (*cred_evaluate)();

    gaa_status (*create)();
    gaa_status (*destroy)();
};

3.7.9.3. gaa_identity_cred_struct data structure

The gaa_identity_cred_struct structure is composed of a set of identity
credentials.
Credentials identify the principal on whose behalf the request is performed.
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_cred_struct structure contains the following fields:

principal
The principal identifies an entity on whose behalf the request is performed.

grantor
The grantor identifies an entity who issued the credential.

conditions
The conditions is pointer to an ordered list of elements of the type
gaa_condition_ptr, which lists restrictions placed on the identity,
e.g., validity time periods.

mech_spec_cred
The mech_spec_cred is a handle to the actual mechanism-specific identity
credential.

typedef struct gaa_identity_cred_struct  gaa_identity_cred,
                                        *gaa_identity_cred_ptr;

struct gaa_identity_cred_struct {
   gaa_sec_attrb_ptr   grantor;
   gaa_sec_attrb_ptr   principal;
   gaa_list_ptr /* gaa_condition_ptr */  conditions;
   gaa_buffer_ptr      mech_spec_cred;
};



3.7.9.4. gaa_authr_cred_struct data structure

The gaa_authr_cred_struct structure contains the following fields:

grantee
The grantee identifies an entity for whom the credential was issued.

grantor
The grantor identifies an entity who issued the credential.

objects
The object is a pointer to a byte buffer, containing a list of object
references to the application-level objects accessible by the
grantee, e.g. files or hosts. Object references are from the
application-specific name space.

access_rights
The access_rights is pointer to a linked list of elements of the
type gaa_right_ptr. Each element indicate granted or denied access rights.

conditions
The conditions is a pointer to an ordered list of elements of the type
gaa_condition_ptr, which lists restrictions placed on the authorization
credential.

mech_spec_cred
The mech_spec_cred is a handle to the actual mechanism-specific authorization
credential.

typedef struct gaa_authr_cred_struct  gaa_authr_cred,
                                     *gaa_authr_cred_ptr;

struct gaa_authr_cred_struct{
   gaa_sec_attrb_ptr   grantor;
   gaa_sec_attrb_ptr   grantee;
   gaa_buffer          objects;
   gaa_list_ptr /* gaa_right_ptr */ access_rights;
   gaa_buffer_ptr      mech_spec_cred;
};


3.7.9.5.  gaa_attribute_struct data structure

The gaa_attribute_struct structure contains the following fields:

type
The type defines the type of the token.

authority
The authority indicates the authority responsible for defining the
value within the token type.

value
The value indicates the value of the token. The name space for the
value is defined by the authority field.

conditions
The conditions is a pointer to an ordered list of elements of the
type gaa_condition_ptr, containing pointers to conditions placed
on the attribute credential.

mech_spec_cred
Contains a handle to the actual mechanism specific attribute
credential

typedef struct gaa_attribute_struct  gaa_attribute,
                                     *gaa_attribute_ptr;

struct gaa_attribute_struct {
   gaa_string_data  type;
   gaa_string_data  authority;
   gaa_string_data  value;
   gaa_list_ptr /* gaa_condition_ptr */  conditions;
   gaa_buffer_ptr   mech_spec_cred;
};


3.7.9.6. gaa_uneval_cred_struct data structure

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

The gaa_uneval_cred_struct structure contains the following
fields:

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

grantee
The grantee identifies an entity for whom the credential was issued.

grantor
The grantor identifies an entity who issued the credential.

mech_type
The mech_type specifies security mechanism used to obtain the credential.

mech_spec_cred
The mech_spec_cred is a handle to the actual mechanism-specific credential.

cred_verification
The cred_verification is a handle to an mechanism-specific credential
verification function. It is added to the gaa_uneval_cred structure
the by the calling application or transport.

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

typedef struct gaa_uneval_cred_struct   gaa_uneval_cred,
                                       *gaa_uneval_cred;

struct gaa_uneval_cred_struct {
   gaa_cred_type     cred_type;
   gaa_sec_attrb_ptr grantor;
   gaa_sec_attrb_ptr grantee;
   gaa_string_data   mech_type;
   gaa_buffer_ptr    mech_spec_cred;
   void (*cred_verification )();
};

3.7.10. 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_struct structure contains the following fields:

valid_time
The valid_time is a pointer to a structure of type gaa_time_period.
It specifies the time period during which the authorization is granted
and is returned as a condition to be checked by the application.

rights
The rights is a pointer to an ordered list of structures of the type
gaa_right_ptr, which lists granted rights and corresponding
conditions, if any.

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_list_ptr /* gaa_right_ptr */  rights;
};


4. GAA-API routine descriptions

This section describes each of the GAA-API routines and discusses
their major parameters and how they are to be passed to the routines.

4.1. gaa_initialize routine

Purpose:
The gaa_initialize must be called before any other GAA API function.
It initializes the GAA API structures, defines behavior of the gaa evaluation
routines.

Parameters:

method
A handle to the implementation-specific gaa method structure, which
implements concrete gaa class, see section 2.

gaa
A handle to the gaa structure.

arglist
A handle to an implementation-specific structure, containing
initialization information. Can be used to return implementation-specific
output information.

Return value:
         GAA_S_SUCCESS
         GAA_S_FAILURE
         GAA_S_INVALID_GAA_HNDL
         GAA_S_INVALID_GAA_METHOD_HNDL

Synopsis:

gaa_status
gaa_initialize(gaa_method_ptr  method,  /* IN  */
               gaa_ptr        *gaa,     /* OUT */
               gaa_handle_ptr  arglist  /* IN & OUT, OPTIONAL */);

4.2. gaa_cleanup routine

Purpose:
 The gaa_cleanup cleans up internal GAA API structures allocated and initialized
 using the gaa_initialize function. The calling application should call gaa_cleanup
 to free memory and internal implementation state before exiting.

Parameters:

gaa
A handle to a pointer the gaa structure.

arglist
A handle to an implementation-specific structure, containing
clean up information. Can be used to return implementation-specific
output information.

Return value:

       GAA_SUCCESS
       GAA_FAILURE
       GAA_S_INVALID_GAA_HNDL

Synopsis:

gaa_status
gaa_cleanup(gaa_ptr        gaa,    /* IN */
            gaa_handle_ptr arglist /* IN & OUT, OPTIONAL */);


4.3. gaa_get_object_policy_info routine

Purpose:
The gaa_get_object_policy_info function is called to obtain security
policy information associated with the object.

Parameters:

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.

policy_db
Reference to an application-specific authorization database, containing
access control information for the target object.

policy_handle
A pointer to a handle to gaa_policy structure, containing the security
policy associated with the targeted object

Return value:

 GAA_S_SUCCESS
 GAA_S_FAILURE
 GAA_S_INVALID_GAA_POLICY_HNDL
 GAA_S_INVALID_GAA_METHOD_HNDL
 GAA_S_UNIMPLEMENTED_FUNCTION
 GAA_S_INVALID_GAA_POLICY_HNDL
 GAA_S_INVALID_GAA_ANSWER_HNDL

Synopsis:

gaa_status
gaa_get_object_policy_info(gaa_string_data  object,        /* IN  */
                           gaa_string_data  policy_db,     /* IN  */
                           gaa_policy_ptr   policy_handle  /* OUT */)


4.4. 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:

policy_handle
A handle to the gaa_policy structure, returned by the
gaa_get_object_policy_info routine.

gaa
A handle to the gaa structure.

sc
A handle to the principal's security context.

check_access_rights
Ordered list of access rights for authorization.

gaa_options
The optional argument, containing parameters for parameterized operation.

detailed_answer
Contains various information for further evaluation by the application.

Return value:

 GAA_YES
 GAA_NO
 GAA_MAYBE
 GAA_S_FAILURE
 GAA_S_INVALID_ACCESS_RIGHTS_HNDL
 GAA_S_INVALID_GAA_POLICY_HNDL
 GAA_S_INVALID_GAA_ANSWER_HNDL
 GAA_S_INVALID_POLICY_METHOD_HNDL
 GAA_S_NO_MATCHING_ENTRIES
 GAA_S_UNIMPLEMENTED_FUNCTION

Synopsis:

gaa_status
gaa_check_authorization
       (gaa_ptr            gaa,            /* IN&OUT */
        gaa_sc_ptr         sc,             /* IN&OUT */
        gaa_policy_ptr     policy_handle,  /* IN     */
        gaa_options_ptr    gaa_options,    /* IN, OPTIONAL */
        gaa_list_ptr /* gaa_right_ptr */  check_access_rights /* IN  */
        gaa_answer_ptr    *detailed_answer /* OUT    */
       );



4.5. gaa_inquire_object_policy_info routine

Purpose:
The gaa_inquire_object_policy_info routine allows  calling application
to discover a particular user's rights on an object.

Parameters:

gaa
A handle to the gaa structure.

sc
A handle to the principal's security context.

policy_handle
A handle to the gaa_policy structure, returned by the
gaa_get_object_policy_info routine.

out_rights
A handle to the ordered list of elements of type gaa_right_ptr, which
contains list of rights that the principal is granted or denied.

Return value:

 GAA_SUCCESS
 GAA_FAILURE
 GAA_S_SUCCESS
 GAA_S_FAILURE
 GAA_S_INVALID_ACCESS_RIGHTS_HNDL
 GAA_S_INVALID_GAA_POLICY_HNDL
 GAA_S_INVALID_GAA_ANSWER_HNDL
 GAA_S_INVALID_POLICY_METHOD_HNDL
 GAA_S_UNIMPLEMENTED_FUNCTION
 GAA_S_NO_MATCHING_ENTRIES

Synopsis:

gaa_status
gaa_inquire_policy_info
       (gaa_ptr         gaa,           /* IN&OUT */
        gaa_sc_ptr      sc,            /* IN&OUT */
        gaa_policy_ptr  policy_handle, /* IN     */
        gaa_list_ptr   *out_rights     /* OUT    */);


5. GAA-API support routines

5.1. Allocation routines

5.1.1. gaa_allocate_buffer routine

Purpose:
Allocate a gaa_buffer data structure and assign default values.

Parameters:

buffer
Pointer to the allocated memory for gaa_buffer structure will be returned.

Return value:

GAA_S_SUCCESS
GAA_S_FAILURE
GAA_S_INVALID_BUFFER_HNDL

Synopsis:

gaa_status
gaa_allocate_buffer(gaa_buffer_ptr *buffer /* OUT */);


5.1.2. gaa_allocate_answer routine

Purpose:
Allocate a gaa_answer data structure and assign default values.

Parameters:

buffer
A handle to the allocated memory for gaa_answer structure will be returned.

Return value:

GAA_S_SUCCESS
GAA_S_FAILURE
GAA_S_INVALID_ANSWER_HNDL

Synopsis:

gaa_status
gaa_allocate_answer(gaa_answer_ptr *buffer /* OUT */);


5.1.3. gaa_allocate_condition routine

Purpose:
Allocate a gaa_condition data structure and assign default values.

Parameters:

buffer
A handle to the allocated memory for gaa_condition structure will be returned.

Return value:

GAA_S_SUCCESS
GAA_S_FAILURE
GAA_S_INVALID_CONDITION_HNDL

Synopsis:

gaa_status
gaa_allocate_condition(gaa_condition_ptr *buffer /* OUT */);

5.1.4. gaa_allocate_right routine

Purpose:
Allocate a gaa_right data structure and assign default values.

Parameters:

buffer
A handle to the allocated memory for gaa_right structure will be returned.

Return value:

GAA_S_SUCCESS
GAA_S_FAILURE
GAA_S_INVALID_RIGHT_HNDL

Synopsis:

gaa_status
gaa_allocate_right (gaa_right_ptr *buffer /* OUT */);


5.1.5. gaa_allocate_sec_attrb routine

Purpose:
Allocate a gaa_sec_attrb data structure and assign default values.

Parameters:

buffer
A handle to the allocated memory for gaa_sec_attrb structure will be returned.

Return value:

GAA_S_SUCCESS
GAA_S_FAILURE
GAA_S_INVALID_SEC_ATTRB_HNDL

Synopsis:

gaa_status
gaa_allocate_sec_attrb (gaa_sec_attrb_ptr *buffer /* IN  */);

5.1.6. gaa_allocate_identity_cred routine

Purpose:
Allocate a gaa_identity_cred data structure and assign default values.

Parameters:

buffer
A handle to the allocated memory for gaa_identity_cred structure will be returned.

Return value:

GAA_S_SUCCESS
GAA_S_FAILURE
GAA_S_INVALID_IDENTITY_CRED_HNDL

Synopsis:

gaa_status
gaa_allocate_identity_cred(gaa_identity_cred_ptr *buffer /* OUT */);

5.1.7. gaa_allocate_authr_cred routine

Purpose:
Allocate a gaa_authr_cred data structure and assign default values.

Parameters:

buffer
A handle to the allocated memory for gaa_authr_cred structure will be returned.

Return value:

GAA_S_SUCCESS
GAA_S_FAILURE
GAA_S_INVALID_AUTHR_CRED_HNDL

Synopsis:

gaa_status
gaa_allocate_authr_cred(gaa_authr_cred_ptr *buffer /* OUT */);


5.1.8. gaa_allocate_uneval_cred routine

Purpose:
Allocate a gaa_uneval_cred data structure and assign default values.

Parameters:

buffer
A handle to the allocated memory for gaa_uneval_cred structure will be returned.

Return value:

GAA_S_SUCCESS
GAA_S_FAILURE
GAA_S_INVALID_UNEVAL_CRED_HNDL

Synopsis:

gaa_status
gaa_allocate_uneval_cred(gaa_uneval_cred_ptr *buffer /* OUT */);

5.1.9. gaa_allocate_attribute routine

Purpose:
Allocate a gaa_attribute data structure and assign default values.

Parameters:

buffer
A handle to the allocated memory for gaa_attribute structure will be returned.

Return value:

GAA_S_SUCCESS
GAA_S_FAILURE
GAA_S_INVALID_ATTRIBUTE_HNDL

Synopsis:

gaa_status
gaa_allocate_attribute_cred(gaa_attribute_ptr *buffer /* OUT */);

5.1.10. gaa_allocate_policy_entry routine

Purpose:
Allocate a gaa_policy_entry data structure and assign default values.

Parameters:

buffer
A handle to the allocated memory for gaa_policy_entry structure will be
returned.

Return value:

GAA_S_SUCCESS
GAA_S_FAILURE
GAA_S_INVALID_POLICY_ENTRY_HNDL

Synopsis:

gaa_status
gaa_allocate_policy_entry(gaa_policy_entry_ptr *buffer /* OUT */);


5.2. Release routines

5.2.1. gaa_free_buffer routine

Purpose:
Free storage associated with a buffer.

Parameters:

buffer
The storage associated with the buffer will be freed.

Return value:
none

Synopsis:

void
gaa_free_buffer(gaa_answer_ptr buffer /* IN */);


5.2.2. gaa_free_answer routine

Purpose:
Free storage associated with a buffer.

Parameters:

buffer
The storage associated with the buffer will be freed.

Return value:
none

Synopsis:

void
gaa_free_answer(gaa_answer_ptr buffer/* IN */);


5.2.3. gaa_free_policy_entry routine

Purpose:
Free storage associated with a buffer.

Parameters:

buffer
The storage associated with the buffer will be freed.

Return value:
none

Synopsis:

void
gaa_free_policy_entry (gaa_policy_entry_ptr buffer/* IN */);

5.2.4. gaa_free_identity_cred routine

Purpose:
Free storage associated with a buffer.

Parameters:

buffer
The storage associated with the buffer will be freed.

Return value:
none

Synopsis:

void
gaa_free_identity_cred(gaa_identity_cred_ptr buffer /* IN */);

5.2.5. gaa_free_right routine

Purpose:
Free storage associated with a buffer.

Parameters:

buffer
The storage associated with the buffer will be freed.

Return value:
none

Synopsis:

void
gaa_free_right (gaa_right_ptr buffer /* IN */);

5.2.6. gaa_free_condition routine

Purpose:
Free storage associated with a buffer.

Parameters:

buffer
The storage associated with the buffer will be freed.

Return value:
none

Synopsis:

void
gaa_free_condition(gaa_condition_ptr condition /* IN */);

5.2.7. gaa_free_sec_attrb routine

Purpose:
Free storage associated with a buffer.

Parameters:

buffer
The storage associated with the buffer will be freed.

Return value:
none

Synopsis:

void
gaa_free_sec_attrb (gaa_sec_attrb_ptr buffer /* IN */);

5.2.8. gaa_free_authr_cred routine

Purpose:
Free storage associated with a buffer.

Parameters:

buffer
The storage associated with the buffer will be freed.

Return value:
none

Synopsis:

void
gaa_free_authr_cred(gaa_authr_cred_ptr buffer /* IN */);


5.2.9. gaa_free_uneval_cred routine

Purpose:
Free storage associated with a buffer.

Parameters:

buffer
The storage associated with the buffer will be freed.

Return value:
none

Synopsis:

void
gaa_free_uneval_cred (gaa_uneval_cred_ptr buffer /* IN */);

5.2.10. gaa_free_attribute routine

Purpose:
Free storage associated with a buffer.

Parameters:

buffer
The storage associated with the buffer will be freed.

Return value:
none

Synopsis:

void
gaa_free_attribute(gaa_attribute_ptr buffer /* IN */);

6. 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.

[3] T J Hudson, E A Young
    SSLeay http://www.livjm.ac.uk/tools/ssleay/

[4] DASCOM Authorization API draft 1.0
    http://www.dascom.com

7. Acknowledgments

Carl Kesselman and Douglas Engert have contributed to discussion
of the ideas and material in this specification.

8. Authors' Addresses

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