INTERNET-DRAFT Tatyana Ryutov CAT Working Group Clifford Neuman Expires April 2001 Laura Pearlman draft-ietf-cat-gaa-cbind-05.txt USC/Information Sciences Institute November 22, 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-05.txt 2. GAA-API concepts and typical usage A simple GAA application will do the following: a) Perform some initialization at the beginning to create a gaa control structure and security context. The gaa control structure (type gaa_ptr) includes information about callback routines (to be used to evaluate conditions, find policy information, etc.). Callback routines may be installed in this structure by the GAA-API implementation itself (when the gaa_ptr structure is created) or explicitly by the application (at any time). The security context (type gaa_sc_ptr) contains information about the current user's credentials. Credentials may be added to this structure by the GAA-API implementation itself (in the course of evaluating conditions) or explicitly by the application (at any time). b) Each time the application receives a request, it will determine what rights are necessary to fulfill that request and then call GAA-API routines to create a list of requested rights, find the relevant policy, and determine whether or not the policy grants those rights. Each requested right is of type gaa_request_right, which includes a value and defining authority (the authority determines the namespace of the value). The list of requested rights is created with the gaa_new_req_rightlist function, and rights are added to the list with gaa_add_request_right. A request right may also include a list of options (additional information about the request, to be used as hints when evaluating conditions); the gaa_add_option function may be used to add options to a request right. A policy is an ordered list of policy rights. A policy right consists of a type (pos_access_right for a right that's explicitly allowed; neg_access_right for a right that's explicitly denied), a value and defining authority, and a list of conditions under which the policy right applies. A condition consists of a type (e.g,. user identity, time of day, etc.), a value and a defining authority (which determines the namespace of the value). In a typical request, the policy will be retrieved with gaa_get_object_policy_info. The gaa_check_authorization function is used to determine whether the requested rights are granted or denied by the policy. This function evaluates each requested right (finding the relevant policy rights and calling the appropriate condition-evaluation callback routines to see whether they apply) and then aggregates the results: if all requested rights are granted, gaa_check_authorization returns GAA_C_YES; if any requested right is denied, it returns GAA_C_NO; otherwise, it returns GAA_C_MAYBE. A detailed answer structure is also returned, including the relevant policy information. c) When the application is finished using GAA-API, it will call cleanup routines to release resources. 3. GAA-API data types 3.1. 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 a null-terminated character array: typedef char *gaa_string_data; 3.2. GAA-API status codes Most GAA-API functions return a value 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 code is in low 16 bits, the minor code is in high 16 bits. 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. A list of GAA-API status codes and their values appears in section 5 of this document. 3.3. Application-opaque data types 3.3.1. The gaa control structure The gaa control structure (which includes information about the behavior of GAA-API) is opaque to the application: typedef struct gaaint_gaa *gaa_ptr; and is maintained using the callback-registering functions described in section 4.3. 3.3.2. The security context The gaa security context (which includes information about a user's credentials) is opaque to the application: typedef struct gaaint_sc *gaa_sc_ptr; and is maintained using the credential-handling functions described in section 4.1.2. 3.3.3. List data structures Certain data items used by the GAA-API may be regarded as an ordered list of data items, e.g., a list of request rights. These lists are represented by the opaque gaa_list_ptr data type; individual entries in these lists are represented by the opaque gaa_list_entry_ptr data type: typedef struct gaaint_list *gaa_list_ptr; typedef struct gaaint_list_entry *gaa_list_entry_ptr; The functions described in section 4.6 are used to examine and free lists and list entries. 3.4 Policy data structures 3.4.1 gaa_policy The gaa_policy structure describes a policy: struct gaa_policy_struct { void *raw_policy; /* raw policy representation */ gaa_list_ptr entries; /* list of gaa_policy_entry_ptr */ gaa_freefunc freeraw; /* function to free raw_policy */ struct gaaint_policy *intrl; /* internal data */ }; typedef struct gaa_policy_struct gaa_policy, *gaa_policy_ptr; The raw_policy field is an application-specific representation of the policy. It may be null, or it may contain, for example, a textual representation of the policy or the address of a policy server to query. The entries field is an ordered list of GAA-API policy rights. If freeraw field is non-null, that function is called to free the raw_policy entry when the policy structure is freed. The intrl field is internal to the GAA-API implementation and should be ignored by the application. 3.4.2 gaa_policy_entry The gaa_policy_entry structure describes a policy entry: struct gaa_policy_entry_struct { int priority; /* entry priority */ int num; /* entry number (for order within priority) */ gaa_policy_right_ptr right; /* what this entry grants (or denies) */ }; typedef struct gaa_policy_entry_struct gaa_policy_entry, *gaa_policy_entry_ptr; The priority and num fields are used to order the entries in a policy (lower-numbered priorities come before higher-numbered priorities; within a priority, lower-numbered entries come before higher-numbered ones). The right field indicates the right that is granted or denied by this policy entry. 3.4.3. gaa_policy_right and gaa_right_type The gaa_right_type enumeration distinguishes positive policy rights (rights which are explicitly granted) from negative policy rights (rights which are explicitly denied): typedef enum { pos_access_right, neg_access_right } gaa_right_type; The gaa_policy_right structure describes a policy right: struct gaa_policy_right_struct { gaa_right_type type; /* positive or negative */ gaa_string_data authority; /* defining authority */ void *value; /* within namespace defined by authority */ gaa_list_ptr conditions; /* list of gaa_condition_ptr describing the conditions that must be met */ struct gaaint_policy_right *intrl; /* internal data */ }; typedef struct gaa_policy_right_struct gaa_policy_right, *gaa_policy_right_ptr; The type field defines the type of the policy (pos_access_right indicates that the policy grants this right; neg_access_right indicates that the policy denies it). The authority field indicates the authority responsible for defining the value. The value field is a representation of the value (or values) of the right, within the namespace defined by the authority. The conditions field 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. The intrl field is internal to the GAA-API implementation and should be ignored by the application. 3.4.4. gaa_condition The gaa_condition structure describes a condition: struct gaa_condition_struct { gaa_string_data type; /* condition type */ gaa_string_data authority; /* defining authority */ gaa_string_data value; /* within namespace defined by authority */ unsigned long status; /* GAA_COND_EVALUATED, GAA_COND_MET, etc. */ struct gaaint_cond *intrl; /* internal data */ }; typedef struct gaa_condition_struct gaa_condition, *gaa_condition_ptr; The type field defines the type of condition (e.g. user_id, time, etc.). The authority field indicates the authority responsible for defining the value (e.g. kerberos, x509, etc.). The value field is the condition value (e.g. a username) within the namespace defined by the authority. The status field contains flags indicating whether the condition has been evaluated and/or met. The intrl field is internal to the GAA-API implementation and should be ignored by the application. 3.5 Request rights Request rights are similar to, but different from, policy rights. Request rights do not have a "type" element (as it makes no sense to request a negative right) or conditions. And while the value of a policy right can represent multiple rights, the value of a request right can represent only a single right. 3.5.1. gaa_request_right The gaa_request_right structure describes a requested right: struct gaa_request_right_struct { gaa_string_data authority;/* defining authority */ void *value; /* within namespace defined by authority */ gaa_list_ptr options; /* list of gaa_request_option */ struct gaaint_request_right *intrl; /* internal data */ }; typedef struct gaa_request_right_struct gaa_request_right, *gaa_request_right_ptr; The authority field indicates the authority responsible for defining the value. The value field is a representation of the value of the right, within the namespace defined by the authority. The options field is a list of elements of type gaa_request_option. It contains a list of pointers to parameters associated with the request right. The intrl field is internal to the GAA-API implementation and should be ignored by the application. 3.5.2 gaa_request_option The gaa_request_option stucture is used to provide hints for condition evaluation functions. When an authorization request is made to GAA-API, the condition-evaluation functions are passed a pointer to the requested right, which may contain a list of options. The condition-evaluation function can then look through the list of options to find any that are relevant. For example, if a condition requires that "file size must be less than 10k", then a condition-evaluation function for that condition could check to see whether there was a "file size" option in the request (if there was, the function can return yes or no based on the option's value; if there wasn't, that function must return maybe). struct gaa_request_option { gaa_string_data type; /* option type */ gaa_string_data authority; /* defining authority */ gaa_string_data value; /* within namespace defined by authority */ struct gaaint_request_option *intrl; /* internal data */ }; The type field defines the type of the option. The authority field indicates the authority responsible for defining the value, and the value indicates the value of the token (within the namespace defined by the authority field). The intrl field is internal to the GAA-API implementation and should be ignored by the application. 3.6 Credentials GAA-API recognizes several types of credentials, which it maintains in a common credential structure. 3.6.1. gaa_cred_type The gaa_cred_type enumeration describes the different types of credentials: typedef enum { GAA_IDENTITY, /* user identity */ GAA_GROUP_MEMB, /* group membership */ GAA_GROUP_NON_MEMB, /* group non-membership */ GAA_AUTHORIZED, /* authorized credential (capability) */ GAA_ATTRIBUTES, /* attribute credential */ GAA_UNEVAL, /* unevaluated (raw) credential */ GAA_ANY } gaa_cred_type; 3.6.2. gaa_principal The gaa_principal structure describes a principal (an authenticated entity): struct gaa_principal_struct { gaa_cred_type type; /* credential type */ gaa_string_data authority; /* defining meaning of token value */ gaa_string_data value; /* value (in namespace defined by authority) */ }; typedef struct gaa_principal_struct gaa_principal, *gaa_principal_ptr; The type entry indicates the credential type (identity, group, etc.). The authority field indicates the defining authority (e.g. kerberos, x509), and the value field indicates the value within the namespace defined by the authority. 3.6.3 gaa_cred The gaa_cred structure is the GAA-API credential data type: struct gaa_cred_struct { gaa_cred_type type; gaa_principal_ptr grantor; gaa_principal_ptr principal; void *mech_spec_cred; /* raw credential */ struct gaaint_mechinfo *mechinfo; /* functions to handle raw creds */ union { gaa_identity_info_ptr id_info; gaa_authr_info_ptr authr_info; gaa_attribute_ptr attr_info; } info; }; typedef struct gaa_cred_struct gaa_cred, *gaa_cred_ptr; The type field indicates the type of credential. The grantor field should list the entity that granted the credential. The principal field should list the entity that the credential is for. The mech_spec_cred field is the raw, mechanism-specific credential. The mechinfo field is a pointer to an application-opaque list of callback functions to be used on this credential and should be ignored by the application. The meaning of the info field depends on the credential type; if the type is GAA_IDENTITY, GAA_GROUP_MEMB, or GAA_GROUP_NON_MEMB, then the id_info field should be filled in. If the type is GAA_AUTHORIZED, then the authr_info field should be filled in. If the type is GAA_ATTRIBUTES, the attr_info field should be filled in. 3.6.4. gaa_identity_info The gaa_identity_info structure is composed of information specific to identity credentials: struct gaa_identity_info_struct { gaa_list_ptr conditions; /* list of gaa_condition_ptr describing validity constraints */ }; typedef struct gaa_identity_info_struct gaa_identity_info, *gaa_identity_info_ptr; The conditions field is a 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. Note: the gaa_identity_info structure doesn't contain any "identity" information, because that information is kept in the common area of the gaa_cred structure. 3.6.5. gaa_authr_info The gaa_authr_info structure contains information specific to authorized credentials (capabilities): struct gaa_authr_info_struct { void *objects; gaa_list_ptr /* gaa_policy_right_ptr */ access_rights; gaa_freefunc free_objects; }; typedef struct gaa_authr_info_struct gaa_authr_info, *gaa_authr_info_ptr; The objects field is 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. The access_rights field is a pointer to a list of elements of the type gaa_right_ptr. Each element indicate granted or denied access rights. The free_objects field is a pointer to a function to be called to free the objects field when the gaa_authr_info structure is freed. This field may be 0, in which case no function will be called. 3.6.6 gaa_attribute_info The gaa_attribute_info structure contains information specific to attribute credentials (credentials that certify that the bearer has some specific attribute): struct gaa_attribute_info_struct { gaa_string_data type; gaa_string_data authority; gaa_string_data value; gaa_list_ptr /* gaa_condition_ptr */ conditions; }; typedef struct gaa_attribute_info_struct gaa_attribute_info, *gaa_attribute_info_ptr; The type entry indicates the attribute type (e.g. height, birthdate, etc.). The authority field indicates the defining authority, and the value field indicates the value within the namespace defined by the authority. The conditions field is a list of conditions that must be met in order for the credential to be considered valid. 3.7 Authorization answer structure The gaa_check_authorization function fills in a detailed answer structure. 3.7.1 gaa_time_period The gaa_time_period structure describes a time period: 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_time_period_struct gaa_time_period, *gaa_time_period_ptr; 3.7.2 gaa_answer The gaa_answer structure is the detailed answer from gaa_check_authorization: struct gaa_answer_struct { gaa_time_period_ptr valid_time; gaa_list_ptr /* gaa_right_ptr */ rights; }; typedef struct gaa_answer_struct gaa_answer, *gaa_answer_ptr; If the answer was GAA_C_YES, valid_time is the time period for which the answer is valid. The rights field is a list of policy rights that were relevant to the request, with the appropriate evaluated/met flags filled in. 3.8 Function and callback types GAA-API makes heavy use of callback functions. The GAA-API callback registration model includes three things for each type of callback: a function (or set of related functions), an application-controlled parameter (opaque to the GAA implementation) that is passed to the function(s) each time they are called (to be used to provide operating parameters and/or maintain state information), and a function to be used to free that application-controlled parameter when the application determines that the callback will no longer be needed. 3.8.1 gaa_freefunc The gaa_freefunc type is used for a function to be used to free arbitrary data. typedef void (*gaa_freefunc)(void *data); 3.8.2 Condition-evaluation callbacks 3.8.2.1. gaa_cond_eval_func typedef gaa_status (*gaa_cond_eval_func)(gaa_ptr gaa, gaa_sc_ptr sc, gaa_condition_ptr condition, gaa_time_period_ptr valid_time, gaa_list_ptr req_options, gaa_status *output_flags, void *params); A function of this type should accept the gaa, sc, and condition arguments as input (the condition argument being the condition to evaluate, and the gaa and sc arguments used to find other callback functions and credentials). The req_options argument is an input list of gaa_request_option options that the condition may examine if it chooses to, and the params argument is the optional callback parameter (see gaa_new_cond_eval_callback in section 4.3.1.1). The output_flags and valid_time arguments are output parameters. The function should set output_flags to the appropriate combination of the GAA_COND_FLG_EVALUATED, GAA_COND_FLG_MET, and GAA_COND_FLG_ENFORCE flags. It should interpret the valid_time pointer as an output parameter (if the condition imposes time restrictions, the callback function should set the beginning and ending times to whatever the condition restricts them to). Functions of this type are used by gaa_check_authorization (see section 4.2.3.1), gaa_check_condition (see section 4.4.3.1), and gaa_inquire_policy_info (see section 4.2.3.2). 3.8.2.2. gaa_cond_eval_callback_ptr typedef struct gaaint_cond_eval_callback *gaa_cond_eval_callback_ptr; This is an application-opaque structure to represent a condition evaluation callback. Note: section 4.3.1 describes functions to create and register condition-evaluation callbacks. 3.8.3 Functions to manipulate raw (mechanism-specific) credentials 3.8.3.1. gaa_cred_pull_func type typedef int (*gaa_cred_pull_func)(gaa_ptr gaa, gaa_sc_ptr sc, gaa_cred_type which, void *params); A function of this type should pull raw credentials of the type specified by "which" (or all types, if "which" is GAA_ANY) and add them to the security context sc. The function may use the gaa to find other callbacks if appropriate. The params argument is the optional callback-specific parameter (see gaa_add_mech_info in section 4.3.2). Functions of this type are called by gaa_pull_creds (see section 4.4.3.2). 3.8.3.2. gaa_cred_eval_func type typedef int (*gaa_cred_eval_func)(gaa_ptr gaa, gaa_sc_ptr sc, gaa_cred_ptr cred, void *raw, void *params); A function of this type should take a raw mechanism-specific credential and fill in the appropriate values in the credential cred (in the process, it should create one of the credential entries in the cred->info union). The gaa and sc arguments are input arguments, and "params" is the optional callback-specific parameter (see gaa_add_mech_info in section 4.3.2). Functions of this type are called by gaa_new_cred (see section 4.1.2.2) to evaluate credentials. 3.8.3.3. gaa_cred_verify_func type typedef int (*gaa_cred_verify_func)(gaa_cred_ptr cred, void *params); A function of this type should take an evaluated gaa credential and verify that it is still valid (i.e. that the raw credential is still valid and still corresponds to the values listed for its grantor, principal, etc.). The "params" argument is the optional callback-specific parameter (see gaa_add_mech_info in section 4.3.2). Functions of this type are used by gaa_verify_cred (see section 4.4.3.3). 3.8.4. Callback to get policy information typedef int (*gaa_getpolicy_func)(gaa_ptr gaa, gaa_policy_ptr *policy, gaa_string_data object, void *params); A function of this type should take a gaa pointer, an object name, and an optional pointer to application-specific parameters, and create an output policy structure containing all the policy information that relates to that object. The getpolicy callback is registered with gaa_set_getpolicy_callback (see section 4.3.3) and used by gaa_get_object_policy_info (see section 4.2.2). 3.8.5 Functions to override GAA default behavior Each GAA-API implementation has default internal representations of policy right values and request right values and a default function to determine which policy rights match a request right. Most applications can simply use these defaults (and ignore everything in this section); however, GAA-API provides callbacks to override them. 3.8.5.1 Callback to find the subset of a policy that applies to a requested right. typedef int (*gaa_matchrights_func)(gaa_ptr gaa, gaa_policy_ptr inpolicy, gaa_request_right_ptr right, gaa_policy_ptr outpolicy, void *params); A function of this type should take a gaa pointer, an input policy (inpolicy), and an input requested right, and fill in an output policy with those entries from the input policy (in the same order) that apply to the requested right. The gaa_set_matchrights_callback function (see section 4.3.4) is used to set this callback. 3.8.5.2. Function types associated with the internal representation of right values ("valinfo" functions). These callbacks are registered using gaa_add_authinfo (see section 4.3.5). 3.8.5.2.1. gaa_copyval_func typedef gaa_status (*gaa_copyval_func)(void **newval, gaa_string_data authority, void *oldval, void *params); Functions of this type should take a defining authority, a right value ("oldval"), and optional callback parameters ("params"), and create a new value ("newval") that's a duplicate of the original value ("oldval"). 3.8.5.2.2. gaa_string2val_func typedef gaa_status (*gaa_string2val_func)(void **val, gaa_string_data authority, gaa_string_data valstr, void *params); Functions of this type should take a defining authority, an input string ("valstr"), and optional callback parameters ("params"), and create a new value ("val") containing an internal representation of that string. 3.8.5.2.3. gaa_val2string_func typedef char *(*gaa_val2string_func)(gaa_string_data authority, void *val, gaa_string_data buf, int bsize, void *params); Functions of this type should take a defining authority, a right value ("val"), a buffer ("buf") of size bsize, and optional callback parameters ("params"), and return a character-string representation of that value. These functions are not required to write the character-string representation into the supplied buffer. 3.8.5.2.4. gaa_valmatch_func typedef int (*gaa_valmatch_func)(gaa_string_data authority, void *rval, void *pval, void *params); Functions of this type should take a defining authority, an input request right ("rval"), and input policy right ("pval"), and optional callback parameters ("params"), and return 1 if the request right matches the policy right and 0 otherwise. 3.8.5.2.5. gaa_valinfo_ptr The gaa_valinfo_ptr is an application-opaque data type used to register functions of the types described in this section as callbacks: typedef struct gaaint_valinfo *gaa_valinfo_ptr; 4. GAA-API functions Unless otherwise noted, all GAA-API routines return GAA_S_SUCCESS on success and one of the error codes defined in section 5 on failure. 4.1 Initialization functions 4.1.1 gaa_initialize The gaa_initialize function must be called before any other GAA-API function. It initializes the GAA-API structures and sets up the default behavior of GAA-API routines. (The default behaviors can be modified later using the GAA-API callback registration routines in section 4.3). gaa_status gaa_initialize(gaa_ptr *gaa, /* OUT */ void *params /* IN & OUT, OPTIONAL */); Parameters: gaa A pointer to the gaa structure that will be allocated an initialized. params A handle to an implementation-specific structure, containing initialization information. Can be used to return implementation-specific output information. A gaa structure created with gaa_initialize should later be freed using gaa_cleanup (see section 4.8). 4.1.2 Routines to keep track of credentials The security context contains information about credentials. An application will typically create a security context with gaa_new_sc, then create credentials with gaa_new_cred and add them to the security context with gaa_add_cred. 4.1.2.1. gaa_new_sc The gaa_new_sc routine allocates an empty gaa_sc data structure. gaa_status gaa_new_sc(gaa_sc_ptr *sc /* OUT */); Parameters: sc A pointer to the security context to be allocated. A structure created using this function should be freed using gaa_free_sc (see section 4.8). 4.1.2.2. gaa_new_cred The gaa_new_cred routine creates a new credential and fills it in with appropriate values. gaa_status gaa_new_cred (gaa_ptr gaa, gaa_sc_ptr sc, gaa_cred_ptr *cred, gaa_string_data mech_type, void *mech_spec_cred, gaa_cred_type cred_type, int evaluate, gaa_status *estat) Parameters: gaa input gaa pointer sc input security context mech_type input credential mechanism type mech_spec_cred input raw credential cred_type input credential type (identity, group, etc.). evaluate input flag -- if nonzero, the credential is evaluated (i.e. the appropriate cond_eval callback is called) estat output -- if evaluate and estat are both nonzero, then estat is set to the return value of the cond_eval function. A credential created using this function should be freed with gaa_free_cred (see section 4.8). 4.1.2.3 gaa_add_cred The gaa_add_cred routine adds a credential to a security context. gaa_status gaa_add_cred (gaa_ptr gaa, gaaint_sc_ptr sc, gaa_cred_ptr cred) Add a credential to a security context. Parameters: gaa input gaa pointer sc input/output security context. cred input credential to add 4.2. Functions to evaluate an authorization request. There are three steps to checking an authorization request: creating a list of requested rights to represent the request, finding the policy relevant to the request, and calling a routine to check the requested rights against the policy. 4.2.1. Functions to build the list of requested rights 4.2.1.1. gaa_new_req_rightlist The gaa_new_req_rightlist function creates an empty list of requested rights: gaa_list_ptr gaa_new_req_rightlist (int freerights) Parameters: freerights input flag to control the behavior of gaa_list_free when (and if) it is called to free this list. If this flag is 0, then gaa_list_free will free only the list itself, not any of the rights in the list. If freerights is nonzero, then both the list and all the rights contained in it will be freed. Return values: on success, returns an empty list. on failure, returns 0. 4.2.1.2. gaa_new_request_right The gaa_new_request_right function allocates a new request right structure and fill it in with the specified values. gaa_status gaa_new_request_right (gaa_ptr gaa, gaa_request_right_ptr *right, gaa_string_data authority, gaa_string_data val) Parameters: right output right pointer authority input authority val input string representation of value Request rights created with this routine should be freed with gaa_free_request_right(). Note: some applications that use callbacks to override the GAA-API implementation's default internal representation of right values may wish to use gaa_new_request_right_rawval (see section 4.7.7) instead of this function. 4.2.1.3. gaa_add_option The gaa_add_option function adds an option to a request right. It may be called several times to add more than one option to a right. gaa_status gaa_add_option ( gaa_request_right_ptr right, gaa_string_data type, gaa_string_data authority, void *value, gaa_freefunc freeval) Add an option to a request right. Parameters: right input/output right type input option type authority input option authority value input option value freeval optional input function to free value when the option is freed (which will happen automatically when right is freed with gaa_free_request_right(). 4.2.1.4. gaa_add_request_right The gaa_add_request_right function adds a request right to a list. gaa_status gaa_add_request_right (gaa_list_ptr rightlist, gaa_request_right_ptr right) Parameters: rightlist input/output list to add right to right input right to add. 4.2.2. Function to retrieve policy information The gaa_get_object_policy_info function retrieves policy information for an object. This function calls the installed getpolicy callback. gaa_status gaa_get_object_policy_info ( gaa_string_data object, gaa_ptr gaa, gaa_policy_ptr *policy) Parameters: object input object to get policy for gaa input gaa pointer policy output policy to create 4.2.3. Functions to make access control decisions. 4.2.3.1. gaa_check_authorization The gaa_check_authorization function checks whether the requested rights are authorized under the specified policy. gaa_status gaa_check_authorization (gaa_ptr gaa, gaa_sc_ptr sc, gaa_policy_ptr policy, gaa_list_ptr req_rights, gaa_answer_ptr answer ) Parameters: gaa input gaa pointer sc input security context policy input policy req_rights input list of requested rights answer output detailed answer -- lists all matching policy rights and associated conditions, with flags set to indicate whether each condition was evaluated and/or met. If the result is GAA_C_YES, then the answer includes the time period for which the result is valid (if the start or end time is 0, that time is indefinite). Before being passed to this function, the answer structure should be created with gaa_new_answer (see section 4.7.3). Return values: GAA_C_YES Access is granted to all requested rights. GAA_C_NO Access is denied for at least one requested right. GAA_C_MAYBE Access is not explicitly denied for any requested right, but there is at least one requested right that GAA cannot decide. GAA_S_INVALID_ARG sc, policy, answer, or gaa is null GAA_S_NO_MATCHING_ENTRIES The list of requested rights is empty. This function makes use of several callback routines -- the GAA-API matchrights callback to determine the subset of the policy that applies to the requested rights, and cond_eval callbacks to evaluate specific conditions. The matchrights callback is also likely to use the valmatch function from the appropriate authinfo callback(s) to determine whether a specific request right matches a specific policy right. 4.2.3.2. gaa_inquire_policy_info The gaa_inquire_policy_info function returns the subset of the input policy that applies to the individual identified with the specified security context. This is the union of the set of rights that do not have any identity conditions with the set of rights whose identity conditions all match the individual. gaa_status gaa_inquire_policy_info ( gaa_ptr gaa, gaa_sc_ptr sc, gaa_policy_ptr policy, gaa_list_ptr *out_rights ) Parameters: gaa input gaa pointer sc input security context policy input policy out_rights output list of policy rights The list returned in out_rights should be freed with gaa_list_free (see section 4.6.4). 4.3. Functions to register callbacks with GAA-API. 4.3.1. Functions to register condition-evaluation callbacks. A condition-evaluation callback is created using gaa_new_cond_eval_callback and associated with a condition type/authority pair using gaa_add_cond_eval_callback. See section 3.8.2 for descriptions of the data types used by these functions. 4.3.1.1. gaa_new_cond_eval_callback The gaa_new_cond_eval_callback function creates a condition evaluation callback. If the callback is later installed with gaa_add_cond_eval_callback(), then it will be used (when appropriate) by gaa_check_authorization() and gaa_inquire_policy_info() to evaluate conditions. gaa_status gaa_new_cond_eval_callback (gaa_cond_eval_callback_ptr *cb, gaa_cond_eval_func func, void params, gaa_freefunc freeparams) Parameters: cb output callback to create. func input callback function. params input callback params -- will be passed to func whenever it's called. freeparams input function to free params when cb is freed. A callback created with this function should be freed with gaa_free_cond_eval_callback(). If a callback is added to a gaa structure with gaa_add_cond_eval_callback(), it will be freed automatically when the gaa structure is freed with gaa_free_gaa(). 4.3.1.2. gaa_add_cond_eval_callback The gaa_add_cond_eval_callback function adds a condition evaluation callback, associated with the specified type and authority. gaa_status gaa_add_cond_eval_callback (gaa_ptr gaa, gaa_cond_eval_callback_ptr cb, gaa_string_data type, gaa_string_data authority, int is_idcred) Parameters: gaa input/output gaa pointer cb input condition evaluation callback (should be a callback created with gaa_new_cond_eval_callback()). type input condition type to associate this callback with authority input condition authority to associate this callback with is_idcred input flag -- if nonzero, then gaa_inquire_policy_info (see section 4.2.3.2) will interpret conditions with this type and authority as identity conditions. When gaa_check_authorization() or gaa_inquire_policy_info() searches for a callback routine for a condition, it first looks for a callback that was installed with the same type and authority as the condition. If no match is found, it searches for a callback with the same authority and a null type. If no match is found, it searches for a callback with the same type and a null authority. If no match is found, it searches for a callback with null type and authority. 4.3.2. Function to register callbacks to deal with mechanism-specific credentials. The gaa_add_mech_info function creates and adds a mechinfo callback, which consists of routines to pull additional credentials, evaluate raw credentials, verify credentials, and free raw credentials. This callback can either be associated with a specific mechanism type, or can be installed as a default to be used when no other mechinfo callback matches the requested mechanism type. See section 3.8.3 for descriptions of the data types used by this function. gaa_status gaa_add_mech_info (gaa_ptr gaa, gaa_string_data mech_type, gaa_cred_pull_func cred_pull, gaa_cred_eval_func cred_eval, gaa_cred_verify_func cred_verify, gaa_freefunc cred_free, void *params, gaa_freefunc freeparams) Parameters: gaa input/output gaa pointer mech_type input mechanism type cred_pull input cred_pull callback. Used by gaa_pull_creds() to pull additional credentials. cred_eval input cred_eval callback. Used by gaa_new_cred() to evaluate a raw credential (translate it into a gaa identity, group, etc. credential). cred_verify input cred_verify callback. Used by gaa_verify_cred() to verify the raw credential (check that it's still valid). cred_free input cred_free callback. Used by gaa_free_cred() to free the raw credential. params input mechinfo parameter -- passed as an argument to cred_pull, cred_eval, and cred_verify whenever they're called. freeparam input freeparam function -- called to free params when the gaa pointer is freed. 4.3.3. Function to set the callback routine to get object policy information. The gaa_set_getpolicy_callback function sets the gaa getpolicy callback, which is used by gaa_get_object_policy_info (see section 4.2.2) to create a policy structure containing the policy information associated with an object. gaa_status gaa_set_getpolicy_callback (gaa_ptr gaa, gaa_getpolicy_func func, void *param, gaa_freefunc freefunc) Parameters: gaa input/output gaa pointer func input getpolicy function param input getpolicy parameter (to be passed to func whenever it's called). freefunc input function to be used to free param when the gaa pointer is freed. 4.3.4. Function to override GAA-API's internal function to determine what subset of a policy is relevant to a request. Each GAA-API implementation has an internal function to compare a list of requested rights with a policy to determine which policy entries are relevant to the request. The gaa_set_matchrights_callback function is used to replace this internal function with one specified by the application. See section 3.8.5 for a description of the gaa_matchrights_func data type. gaa_status gaa_set_matchrights_callback (gaa_ptr gaa, gaa_matchrights_func func, void *param, gaa_freefunc freefunc) Parameters: gaa input/output gaa pointer func input matchrights function param input getpolicy parameter (to be passed to func whenever it's called). freefunc input function to be used to free param when the gaa pointer is freed. 4.3.5. Functions to override the default internal representation of policy right and request right values. Each GAA-API implementation has internal functions to translate string representations of policy right and request right values into its own internal representation, to compare policy right and request right values, to copy those values, and to express them as character strings. An application may replace those internal functions by using gaa_new_valinfo (to create callback structures consisting of groups of functions) and gaa_add_authinfo (to associate these callback structures with specific authorities). See section 3.8.5 for descriptions of the data types used in these functions. 4.3.5.1. gaa_new_valinfo The gaa_new_valinfo function allocates a new valinfo structure and fill it in with the specified callback functions. gaa_status gaa_new_valinfo (gaa_valinfo_ptr *valinfo, gaa_copyval_func copyval, gaa_string2val_func newval, gaa_freefunc freeval, gaa_val2string_func val2str) Parameters: valinfo output valinfo pointer copyval input copyval callback function. This callback is used by gaa_check_authorization() and gaa_inquire_policy_info() to create new policy entries. newval optional input newval callback function. This callback is used by gaa_new_policy_right() and gaa_new_request_right() to translate a string value into the appropriate internal representation. freeval optional input freeval callback function. This callback is used by gaa_free_request_right() and gaa_free_policy_right() to free right values. val2str optional input val2str callback function. This callback is used by gaa_request_rightval_string() and gaa_policy_rightval_string() to translate a right value into a string. 4.3.5.2. gaa_add_authinfo The gaa_add_authinfo function adds an authinfo callback. This callback will be used to interpret and compare policy right values for rights with the specified defining authority. gaa_status gaa_add_authinfo (gaa_ptr gaa, char *authority, gaa_valinfo_ptr pvinfo, gaa_valinfo_ptr rvinfo, gaa_valmatch_func match, void *params, gaa_freefunc freeparams) gaa_add_authinfo(). Parameters: gaa input/output gaa pointer authority optional input authority that this callback applies to. If authority is null, this is considered the default authinfo callback for any authority that does not have a specific authinfo callback. pvinfo input valinfo callback (see gaa_new_valinfo()) to be used for policy rights with this authority. rvinfo input valinfo callback (see gaa_new_valinfo()) to be used for request rights with this authority. match input callback function that takes a policy right and a request right, and determines whether the values match. params optional input callback parameters passed to pvinfo->copyval, rvinfo->copyval, pvinfo->newval, rvinfo->newval, pvinfo->val2str, rvinfo->val2str, and match whenever they're called. freeparams optional input function to free params when the gaa structure is freed. 4.4. Functions used primarily within GAA-API callback routines. 4.4.1. Functions used to build credentials (used primarily within mechanism-specific cred_eval callback routines -- see sections 3.8.3.2 and 4.3.2). 4.4.1.1. gaa_new_principal The gaa_new_principal creates a new gaa_principal (for use within a gaa_cred structure) and fills it in with the specified values. gaa_status gaa_new_principal (gaa_sec_principal_ptr *princ, gaa_cred_type type, gaa_string_data authority, gaa_string_data value) Parameters: princ output gaa_principal to create type input credential type authority input authority value input value A gaa_principal created using this function should be freed with gaa_free_principal(). This will happen automatically if it's part of a credential freed with gaa_free_cred(). 4.4.1.2. gaa_new_identity_info The gaa_new_identity_info function creates an identity_info structure (to be used as part of a GAA_IDENTITY, GAA_GROUP_MEMB, or GAA_GROUP_NON_MEMB credential -- see section 3.6). gaa_status gaa_new_identity_info (gaa_ptr gaa, gaa_identity_info_ptr *info) Parameters: gaa input info output identity info to create. A gaa_identity_info created using this function should be freed with gaa_free_identity_info(). This will happen automatically if it's part of a credential freed with gaa_free_cred(). 4.4.1.3. gaa_new_attribute_info The gaa_new_attribute_info function creates a new attribute_info structure (to be used as part of a GAA_ATTRIBUTES credential -- see section 3.6). gaa_status gaa_new_attribute_info (gaa_ptr gaa, gaa_attribute_info_ptr *info, gaa_string_data type, gaa_string_data authority, gaa_string_data value) Parameters: gaa input gaa pointer info output structure to create type input attribute type authority input attribute authority value input attribute value A structure created using this routine should be freed with gaa_free_attribute_info(). This will happen automatically if this structure is part of a credential freed with gaa_free_cred(). 4.4.1.4. gaa_new_authr_info The gaa_new_authr_info function creates a new attribute_info structure (to be used as part of a GAA_AUTHORIZED credential -- see section 3.6). gaa_status gaa_new_authr_info (gaa_ptr gaa, gaa_authr_info_ptr *info, void *objects, gaa_freefunc free_objects) Parameters: gaa input gaa pointer info output structure to create objects input objects to store in info free_objects input function to be used to free objects when info is freed. A gaa_authr_info created using this function should be freed with gaa_free_authr_info(). This will happen automatically if it's part of a credential freed with gaa_free_cred(). 4.4.1.5. gaa_add_authr_right The gaa_add_authr_right function adds a right to a GAA_AUTHORIZED credential gaa_status gaa_add_authr_right (gaa_cred_ptr cred, gaa_policy_right_ptr right) Parameters: cred input/output condition to add right to right input right If cred is freed with gaa_free_cred, the right will be be freed at the same time. 4.4.1.6 gaa_add_cred_condition The gaa_add_cred_condition function adds a condition to a credential. The credential must be one of the credential types that accepts conditions (see section 3.6). gaa_status gaa_add_cred_condition (gaa_cred_ptr cred, gaa_condition_ptr cond) Parameters: cred input/output credential to add condition to cond input condition to add. Note: If the credential is freed with gaa_free_cred(), the condition will be freed at the same time. 4.4.2. Functions used to build policies (used primarily within gaa_getpolicy callback functions -- see sections 3.8.4 and 4.2.2). To build a policy, first create it (with gaa_new_policy), then create policy rights (with gaa_new_policy_right, possibly adding conditions with gaa_add_condition) and add them with gaa_add_policy_entry. 4.4.2.1. gaa_new_policy The gaa_new_policy function creates a new policy structure. gaa_status gaa_new_policy (gaa_policy_ptr *policy, void *raw_policy, gaa_freefunc freeraw) Parameters: policy output policy to create raw_policy optional input raw policy freeraw optional input function to free raw_policy when policy is freed. A policy structure allocated by this function should be freed with gaa_free_policy(). 4.4.2.2. gaa_new_policy_right The gaa_new_policy_right function creates a new policy right. gaa_status gaa_new_policy_right (gaa_ptr gaa, gaa_policy_right_ptr *right, gaa_right_type type, gaa_string_data authority, gaa_string_data val) Parameters: gaa input gaa pointer right output policy right to create type input right type (pos_access_right or neg_access_right) authority input right authority val input string representation of right value Note: some applications that use callbacks to override the GAA-API implementation's default internal representation of right values may wish to use gaa_new_policy_right_rawval (see section 4.7.6) instead of this function. 4.4.2.3. gaa_add_condition The gaa_add_condition function adds a condition to a policy right. gaa_status gaa_add_condition (gaa_policy_right_ptr right, gaa_condition_ptr condition) Parameters: right input right to add condition input/output condition to add right to. 4.4.2.4. gaa_add_policy_entry The gaa_add_policy_entry function adds a policy entry to a policy. gaa_status gaa_add_policy_entry (gaa_policy_ptr policy, gaa_policy_right_ptr right, int priority, int num) Parameters: policy input/output policy right input right to add priority input entry priority num input entry number (for order within priority) 4.4.3. Functions used primarily in condition-evaluation callbacks. 4.4.3.1. gaa_check_condition The gaa_check_condition function checks a single condition. This utility function is meant to be used in cond_eval callbacks, when evaluating conditions recursively. gaa_status gaa_check_condition (gaa_ptr gaa, gaa_sc_ptr sc, gaa_condition_ptr cond, gaa_time_period_ptr vtp, int *ynm, gaa_list_ptr option) Parameters: gaa input gaa pointer cond input condition to evaluate vtp output valid time period ynm output answer -- set to GAA_C_YES, GAA_C_NO, or GAA_C_MAYBE options optional input list (of type gaa_request_option) of request options 4.4.3.2. gaa_pull_creds The gaa_pull_creds function locates and call the appropriate callback function to pull additional credentials for the specified mechanism type (or if no mechanism type was specified, call the cred_pull callback functions for all mechanism types), and add the new credentials to the security context. gaa_status gaa_pull_creds (gaa_ptr gaa, gaa_sc_ptr sc, gaa_cred_type which, gaa_string_data mech_type) Parameters: gaa input gaa pointer sc input/output security context which input what type of credential to pull (identity, group, etc.) mech_type which mechanism type to pull (or all of them, if 0) 4.4.3.3. gaa_verify_cred The gaa_verify_cred function calls the appropriate mechanism-specific cred_verify function to verify the credential. gaa_status gaa_verify_cred (gaa_cred_ptr cred) Parameters: cred input credential to verify 4.4.3.4. gaa_getcreds The gaa_getcreds function finds credentials of the specified type in the security context. gaa_status gaa_getcreds (gaa_ptr gaa, gaa_sc_ptr sc, gaa_list_ptr *credlist, gaa_cred_type which) Parameters: gaa input gaa pointer sc input security context credlist input/output credential list which input desired credential type 4.4.4. Functions for use in gaa_matchrights callback functions. 4.4.4.1. gaa_match_rights gaa_status gaa_match_rights (gaa_ptr gaa, gaa_request_right_ptr rright, gaa_policy_right_ptr pright, int *match) Determines whether a request right matches a policy right. If the two rights do not have the same authority, they don't match. If they do, then the valmatch callback appropriate to that authority is called to determine whether they match or not. This utility function is meant to be used in GAA matchrights callback functions. Parameters: gaa input gaa pointer rright input request right pright input policy right match output -- set to 1 if they match, 0 if they don't 4.4.5. Function for use by all callback functions gaa_status gaa_set_callback_err (gaa_string_data err) Set the gaa thread-specific callback error string. Parameters: err input string to set the callback error to. 4.5. String functions These functions return character string representations of values. 4.5.1 gaa_get_err The gaa_get_err function returns the gaa thread-specific error string. gaa_string_data gaa_get_err ( ) 4.5.2. gaa_get_callback_err The gaa_get_callback_err function returns the gaa thread-specific callback error string. gaa_string_data gaa_get_callback_err ( ) 4.5.3. gaa_request_rightval_string The gaa_request_rightval_string function converts the value of a request right into a string. gaa_string_data gaa_request_rightval_string (gaa_ptr gaa, gaa_string_data authority, void *val, char *buf, int bsize) Parameters: gaa input gaa pointer authority input authority val input value buf input buffer -- should be large enough to hold the resulting string bsize input size of buf Note: If a val2str callback function was installed for this authority (see section 4.3.5), then that function is used to do the conversion. Calling gaa_request_rightval_string may or may not result in the result string being written into buf, depending on the behavior of the callback function. 4.5.4 gaa_policy_rightval_string The gaa_policy_rightval_string function converts the value of a policy right into a string. gaa_string_data gaa_policy_rightval_string (gaa_ptr gaa, gaa_string_data authority, void *val, char *buf, int bsize) Parameters: gaa input gaa pointer authority input authority val input value buf input buffer -- should be large enough to hold the resulting string bsize input size of buf Note: If a val2str callback function was installed for this authority (see section 4.3.5), then that function is used to do the conversion. Calling gaa_request_rightval_string may or may not result in the result string being written into buf, depending on the behavior of the callback function. 4.6. List functions 4.6.1. gaa_list_first The gaa_list_first function finds the first entry in a list. gaa_list_entry_ptr gaa_list_first (gaa_list_ptr list) Parameters: list input list Return values: first list entry 0 list was null 4.6.2. gaa_list_next The gaa_list_next function finds the next entry in a list. gaa_list_entry_ptr gaa_list_next (gaa_list_entry_ptr entry) Parameters: entry input list entry Return values: next list entry 0 entry was null 4.6.3. gaa_list_entry_value The gaa_list_entry_value function finds the data in a list entry. void * gaa_list_entry_value (gaa_list_entry_ptr entry) Parameters: entry input list entry Return values: data from list entry 0 entry was null 4.6.4. gaa_list_free The gaa_list_free function frees a list and all its entries. void gaa_list_free (gaa_list_ptr list) Parameters: list list to free Note: If, when the list was created, a function was specified to free the list's entries, that function will be called to free the data associated with each list entry. 4.7. Miscellaneous functions 4.7.1. gaa_new_condition The gaa_new_condition function allocates a new gaa_condition structure and fills in the specified values. gaa_status gaa_new_condition (gaa_condition_ptr *cond, gaa_string_data type, gaa_string_data authority, gaa_string_data value) Parameters: cond output condition type input condition type authority input condition authority value input condition value Conditions allocated with this function should be freed with gaa_free_condition(). 4.7.2. gaa_new_gaa The gaa_new_gaa function creates a new gaa structure. gaa_status gaa_new_gaa (gaa_ptr * gaa) Parameters: gaa output gaa pointer to create. A gaa structure created using this function should be freed with gaa_free_gaa. 4.7.3. gaa_new_answer The gaa_new_answer function creates a new answer structure (suitable for use in a call to gaa_check_authorization()). gaa_status gaa_new_answer (gaa_answer_ptr *answer) Parameters: answer output answer structure to create A structure created with this function should be freed with gaa_free_answer(). 4.7.4. gaa_clear_policy The gaa_clear_policy function clears a policy structure (and free all its entries). void gaa_clear_policy (gaa_policy_ptr policy) Parameters: policy input/output policy to clear 4.7.5. gaa_init_policy The gaa_init_policy function initializes a policy structure. gaa_status gaa_init_policy (gaa_policy_ptr policy) Parameters: policy input/output policy to initialize 4.7.6. gaa_new_policy_right_rawval The gaa_new_policy_right_rawval function is an alternative form of gaa_new_policy_right. It's intended for use by applications that have overriden the default GAA-API internal representation of right values and that wish to set those values directly rather than translating them from character strings. gaa_status gaa_new_policy_right_rawval (gaa_ptr gaa, gaa_policy_right_ptr *right, gaa_right_type type, gaa_string_data authority, void *val) Parameters: gaa input gaa pointer right output right pointer type input right type (pos_access_right or neg_access_right) authority input authority val input value Policy rights created with this routine should be freed with gaa_free_policy_right(). 4.7.7. gaa_new_request_right_rawval The gaa_new_request_right_rawval function is an alternative form of gaa_new_request_right. It's intended for use by applications that have overriden the default GAA-API internal representation of right values and that wish to set those values directly rather than translating them from character strings. gaa_status gaa_new_request_right_rawval (gaa_ptr gaa, gaa_request_right_ptr *right, gaa_string_data authority, void *value) Parameters: gaa input gaa pointer right output right pointer authority input authority val input value Request rights created with this routine should be freed with gaa_free_request_right(). 4.8. Functions to release resources. The functions in this section free GAA-API data structures. void gaa_free_answer (gaa_answe_ptrr answer) Frees an answer structure and its component policy rights. void gaa_free_policy (gaa_policy_ptr policy) Frees a policy structure and all its entries. void gaa_free_policy_entry (gaa_policy_entry_ptr ent) Frees a policy entry and its associated right. Note: If a policy was created using gaa_new_policy() or initialized using gaa_init_policy(), then this function will be called by gaa_free_policy() when the policy is freed. void gaa_free_policy_right (gaa_policy_right_ptr right) Free a policy right. Note: If a policy was created with gaa_new_policy() or initialized with gaa_init_policy() and is freed with gaa_free_policy(), then this function will be called to free all associated policy rights when the policy is freed. void gaa_free_cred (gaa_cred_ptr cred) Free a credential and its components. Note: This function calls the mechanism-specific cred_free callback function to free the raw credential. This function is automatically called to free any credential that's part of a security context being freed with gaa_free_sc(). void gaa_free_principal (gaa_principal_ptr princ) Frees a gaa_principal. Note: If a gaa_principal structure is the principal or grantor in a gaa_cred structure, then this gaa_free_cred will call this function to free that gaa_pricincipal structure when the credential is freed. void gaa_free_attribute_info (gaa_attribute_info_ptr info) Free an attribute_info structure and its components. Note: If a GAA_ATTRIBUTE credential is freed with gaa_free_cred(), this function will be called automatically to free the associated attribute info. void gaa_free_authr_info (gaa_authr_info_ptr info) Free a gaa_authr_info structure (and its components). Note: If a GAA_AUTHORIZED credential is freed with gaa_free_cred(), this function will be called automatically to free the associated authorization info. void gaa_free_identity_info (gaa_identity_info_ptr info) Free a gaa_identity_info structure (and its components). Note: If a GAA_IDENTITY, GAA_GROUP_MEMB, or GAA_GROUP_NON_MEMB credential is freed with gaa_free_cred(), this function will be called automatically to free the associated identity info. void gaa_free_condition (gaa_condition_ptr cond) Free a condition (and all its components). void gaa_free_gaa (gaa_ptr gaa) Free a gaa structure and its components. void gaa_free_request_right (gaa_request_right_ptr right) Free a request right (and all its components). void gaa_free_sc (gaa_sc_ptr sc) Free a gaa security context and its components. void gaa_free_cond_eval_callback (gaa_cond_eval_callback_ptr cb) Free a condition evaluation callback structure. Note: if a callback is installed in a gaa structure, then gaa_free() will call this function to free the callback when the gaa structure is free. void gaa_free_valinfo (gaa_valinfo_ptr valinfo) Free a valinfo structure and its components. Note: If a valinfo structure is installed in a gaa structure as a callback, then this function will be called automatically to free that valinfo structure when the gaa structure is freed. void gaa_cleanup (gaa_ptr gaa, void *params) Cleans up internal GAA API structures allocated and initialized using the gaa_initialize function. The gaa and params arguments should be the same as those passed to gaa_initialize. 5. Status codes The GAA-API routines return a status code of type 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 code is in low 16 bits, the minor code is in high 16 bits. 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_C_YES 0 An authorization request is granted. GAA_C_NO 1 An authorization request is denied. GAA_C_MAYBE 2 An authorization request has not been evaluated. GAA_S_FAILURE 3 The underlying mechanism detected an error for which no specific GAA-API status code is defined. GAA_S_INVALID_STRING_DATA_HNDL 4 The handle supplied does not point to a valid gaa_string_data structure. GAA_S_INVALID_LIST_HNDL 5 The handle supplied does not point to a valid gaa_list structure. GAA_S_INVALID_GAA_HNDL 6 The handle supplied does not point to a valid gaa structure. GAA_S_INVALID_POLICY_ENTRY_HNDL 7 The handle supplied does not point to a valid gaa_policy_entry structure. GAA_S_INVALID_POLICY_HNDL 8 The handle supplied does not point to a valid gaa_policy structure. GAA_S_INVALID_SC_HNDL 9 The handle supplied does not point to a valid gaa_sc structure. GAA_S_INVALID_ANSWER_HNDL 10 The handle supplied does not point to a valid gaa_answer structure. GAA_S_INVALID_REQUEST_RIGHT_HNDL 11 The handle supplied does not point to a valid gaa_request_right structure. GAA_S_INVALID_POLICY_RIGHT_HNDL 12 The handle supplied does not point to a valid gaa_policy_right structure. GAA_S_INVALID_CONDITION_HNDL 13 The handle supplied does not point to a valid gaa_condition structure. GAA_S_INVALID_OPTIONS_HNDL 14 The handle supplied does not point to a valid gaa_options structure. GAA_S_INVALID_IDENTITY_INFO_HNDL 15 The handle supplied does not point to a valid gaa_uneval_cred structure. GAA_S_INVALID_AUTHR_INFO_HNDL 16 The handle supplied does not point to a valid gaa_authr_cred structure. GAA_S_INVALID_PRINCIPAL_HNDL 17 The handle supplied does not point to a valid gaa_principal structure. GAA_S_INVALID_ATTRIBUTE_HNDL 18 The handle supplied does not point to a valid gaa_attribute structure. GAA_S_UNIMPLEMENTED_FUNCTION 19 The function is not supported by the underlying implementation. GAA_S_NO_MATCHING_ENTRIES 20 No matching policy entries have been found for the requested right. GAA_S_POLICY_PARSING_FAILURE 21 Indicates an error during policy parsing. GAA_S_POLICY_RETRIEVING_FAILURE 22 Indicates an error during policy retrieval process. GAA_S_INVALID_ARG 23 One or more arguments was invalid. GAA_S_UNKNOWN_CRED_TYPE 24 The cred_type of a credential is invalid GAA_S_UNKNOWN_MECHANISM 25 No mechanism-specific callback functions were found for this credential mechanism GAA_S_NO_CRED_PULL_CALLBACK 26 An attempt was made to pull credentials, but no cred_pull callback had been registered for this mechanism. GAA_S_NO_AUTHINFO_CALLBACK 27 No authinfo callback has been registered for this authority. GAA_S_NO_NEWVAL_CALLBACK 28 No newval callback has been registered for this authority. GAA_S_NO_GETPOLICY_CALLBACK 29 No getpolicy callback has been registered. GAA_S_NO_MATCHRIGHTS_CALLBACK 30 No matchrights callback has been registered. GAA_S_INVALID_IDENTITY_CRED 31 The credential's cred_type and principal's cred_type do not match. GAA_S_BAD_CALLBACK_RETURN 32 A callback routine returned an error. GAA_S_INTERNAL_ERR 33 There was a GAA internal error. GAA_S_SYSTEM_ERR 34 There was a system error. GAA_S_CRED_PULL_FAILURE 35 There was a problem pulling credentials. GAA_S_CRED_EVAL_FAILURE 36 There was a problem evaluating credentials GAA_S_CRED_VERIFY_FAILURE 37 There was a problem verifying credentials. GAA_S_CONFIG_ERR 38 There was a configuration error. 6. 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 7. The GAA-API usage example This section provides an example of a simple application which calls the GAA-API routines. #include "gaa.h" struct my_right { char *authority; char *value; }; struct my_request { char *object; struct my_right *my_rights; }; main() { gaa_ptr gaa = 0; void *client_raw_creds; char *cred_mechanism; gaa_init(&gaa, 0); ... process_session(gaa, client_raw_creds, cred_mechanism); ... gaa_cleanup(&gaa, 0); } /* * process_session() -- sample function to process several gaa * requests under the same credentials. * Arguments: * gaa - input gaa pointer * client_raw_creds - input raw credentials of client. * cred_mechanism - name of mechanism for client credentials * (e.g. gss-api). * Return values: * 0 success * -1 failure * * This function calls two application-specific functions: * get_my_request, to get a request from the client, and * process_request, to do whatever the request is if * authorization has been granted. * * Note: this example function doesn't clean up after itself on errors. */ process_session(gaa_ptr gaa, void *client_raw_creds, char *cred_mechanism) { gaa_status status; gaa_sc_ptr sc = 0; gaa_policy_ptr policy = 0; struct my_request *myreq; struct my_right *myright; gaa_list_ptr list = 0; gaa_cred_ptr cred = 0; gaa_answer_ptr answer = 0; gaa_request_right_ptr right = 0; /* First initialize the security context */ if (gaa_new_sc(&sc) != GAA_S_SUCCESS) return(-1); if (gaa_new_cred(gaa, sc, &cred, cred_mechanism, client_raw_creds, GAA_IDENTITY, 1, 0) != GAA_S_SUCCESS) return(-1); if (gaa_add_cred(gaa, sc, cred) != GAA_S_SUCCESS) return(-1); while (myreq = get_my_request()) { /* Find the appropriate policy for the object specified in the request */ if ((status = gaa_get_object_policy_info(myreq->object, gaa, &policy)) != GAA_S_SUCCESS) return(-1); /* Next, build the list of requested rights */ if ((list = gaa_new_req_rightlist()) == 0) return(-1); for (myright = myreq->my_rights; myright->value; myright++) { if ((status = gaa_new_request_right(gaa, &right, myright->authority, myright->value)) != GAA_S_SUCCESS) return(-1); if ((status = gaa_add_request_right(list, right)) != GAA_S_SUCCESS) return(-1); } /* Now check to see whether the request is authorized */ if ((status = gaa_new_answer(&answer)) != GAA_S_SUCCESS) return(-1); switch (gaa_check_authorization(gaa, sc, policy, list, answer)) { case GAA_C_YES: printf("request authorized\n"); process_request(myreq); break; case GAA_C_NO: printf("request denied\n"); break; case GAA_C_MAYBE: printf("request undetermined\n"); break; default: fprintf(stderr, "error determining request authorizaton: %s\n", gaa_get_err()); break; } /* Finally, clean up after this request. */ gaa_list_free(list); gaa_free_answer(answer); } gaa_free_sc(sc); return(0); } 8. 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 9. Acknowledgments Carl Kesselman and Douglas Engert have contributed to discussion of the ideas and material in this specification. 10. Authors' Addresses Tatyana Ryutov Clifford Neuman Laura Pearlman USC/Information Sciences Institute 4676 Admiralty Way Suite 1001 Marina del Rey, CA 90292-6695 Phone: +1 310 822 1511 E-Mail: {tryutov, bcn, laura}@isi.edu