INTERNET-DRAFT                        Tatyana Ryutov
CAT Working Group                     Clifford Neuman
Expires January 2000                  USC/Information Sciences Institute                     
draft-ietf-cat-gaa-cbind-02.txt       June 24, 1999                
                                            


Generic Authorization and Access control Application Program Interface C-bindings

0. Status Of this Document This document is an Internet-Draft. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF), its areas, and its working groups. Note that other groups may also distribute working documents as Internet-Drafts. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." To view the entire list of current Internet-Drafts, please check the "1id-abstracts.txt" listing contained in the Internet-Drafts Shadow Directories on ftp.is.co.za (Africa), ftp.nordu.net (Northern Europe), ftp.nis.garr.it (Southern Europe), munnari.oz.au (Pacific Rim), ftp.ietf.org (US East Coast), or ftp.isi.edu (US West Coast). 1. Abstract The Generic Authorization and Access control Application Programming Interface (GAA API) provides access control services to calling applications. It facilitates access control decisions for applications and allows applications to discover access control policies associated with a targeted resource. The GAA API is usable by multiple applications supporting different kinds of protected objects. The GAA API design supports: - a variety of security mechanisms based on public or secret key cryptosystems - different authorization models - heterogeneous security policies - various access rights This document specifies C language bindings for the GAA API, which is described at a language-independent conceptual level in draft-ietf-cat-acc-cntrl-frmw-02.txt 2. The GAA API data types and calling conventions The data types describe only fields that must be provided by all GAA API implementations. Individual implementations may provide additional fields for internal use within the GAA API routines. 2.1. Integer types The GAA API defines the following integer data type: uint32 32-bit unsigned integer 2.2. Opaque data types Some data items are considered opaque to the GAA API, because their internal data structure has no significance to the GAA API, e.g. actual mechanism-specific credentials. Opaque data is passed between the GAA API and the application using the gaa_buffer_ptr data type, which is a pointer to a gaa_buffer structure. The gaa_buffer type is a structure containing the following fields: length Contains the total number of bytes in the datum value Contains a pointer to the actual datum typedef struct gaa_buffer_struct gaa_buffer, *gaa_buffer_ptr; struct gaa_buffer_struct { size_t length; void *value; }; Certain data items used by the GAA API may be regarded as a character strings. The data of this kind is passed between the GAA API and application using the gaa_data_ptr data type, which is a pointer to void: typedef void *gaa_data; 2.3. gaa_policy data structure Some data items used by the GAA API may be regarded as a linked list of type:authority:value character elements. The data of this kind is passed between the GAA API and the application using the gaa_security_attribute_list_ptr data type, which is a pointer to a gaa_security_attribute_list structure. The gaa_security_attribute_list type is a structure containing the following fields: type A pointer to the element of the type gaa_data, which defines the type of the security attribute. authority A pointer to the element of the type gaa_data, which indicates the authority responsible for defining the value within the attribute type. value A pointer to the element of the type gaa_data, wich indicates the value of the security attribute. next A pointer to the next element in the list. typedef struct gaa_policy_struct gaa_policy, *gaa_policy_ptr; struct gaa_security_attribute_list_struct { gaa_data type; gaa_data authority; gaa_data_ value; gaa_rights_ptr rights; gaa_policy_ptr next; }; struct gaa_rights_struct { gaa_data type; gaa_data authority; gaa_data value; gaa_cond_bindings_ptr cond_bindings; gaa_rights_ptr next; }; struct gaa_cond_bindings_struct { gaa_conditions_ptr condition; gaa_cond_bindings_ptr next; }; struct gaa_conditions_struct { gaa_data type; gaa_data authority; gaa_data value; uint32 status; gaa_conditions_ptr next; }; 2.4 GAA API Security Context data structures The security context is a GAA API data structure, which is passed as an argument to the GAA API. It stores information relevant to access control. 2.4.1 gaa_sec_context data structure The gaa_sec_context type is a structure containing the following fields: identity_cred A pointer to a list of structures of the type gaa_identity_cred authr_cred A pointer to a list of structures of the type gaa_authrized_cred group_membership A pointer to a list of structures of the type gaa_identity_cred, which specifies that the grantee is a member of only listed groups group_non_membership A pointer to a list of structures of the type gaa_identity_cred, which specifies that the grantee is NOT a member of the listed groups attributes A pointer to a list of structures of the type gaa_attributes, which contains miscellaneous attributes attached to the grantee, e.g. age of the grantee, grantee's security clearance. unevl_cred A pointer to a list of structures of type gaa_unevaluated_cred. connection_state Contains a mechanism-specific representation of per-connection context, some of the data stored here include keyblocks, addresses. condition_evaluation Specific condition evaluation function called by GAA API if there are application-specific conditions. Generic (understood by the GAA API) conditions are evaluated by the GAA API internal functions. pull_cred This function is called when additional credentials are required. It obtains the necessary credentials and then cred_evaluate function is invoked. This process can be recursive. cred_evaluate This specific function is invoked to parse the contents of the acquired credentials into the GAA API internal form and evaluate them. typedef struct gaa_sec_context_struct gaa_sec_context, *gaa_sec_context_ptr struct gaa_sec_context_struct { gaa_identity_cred_ptr identity_cred; gaa_authr_cred_ptr authr_cred; gaa_identity_cred_ptr group_membership; gaa_identity_cred_ptr group_non_membership; gaa_attributes_ptr attributes; gaa_uneval_cred_ptr unevl_cred; gaa_buffer_ptr connection_state; void (*condition_evaluation)(gaa_sec_context_ptr, va_list ap); void (*pull_cred)(gaa_sec_context_ptr, va_list ap); void (*cred_evaluate)(gaa_sec_context_ptr, va_list ap); }; 2.4.2. gaa_identity_cred data structure A gaa_identity_cred structure is composed of a set of identity credentials. Identity credentials describe a set of mechanism-specific principals, and give their holder the ability to act as any of those principals. Each of the identity credentials contains information needed to authenticate a single principal. The gaa_identity type is a structure containing the following fields: principal A pointer to a structure of the type gaa_security_attribute_list conditions A pointer to a list of structures of the type gaa_security_attribute_list_ptr, which lists restrictions placed on the identity, e.g. validity time periods mech_spec_cred Contains a handle to the actual mechanism-specific identity credential next Contains a pointer to the next identity credential typedef struct gaa_identity_cred_struct gaa_identity_cred, *gaa_identity_cred_ptr; struct gaa_identity_cred_struct { gaa_principals_ptr principal; gaa_conditions_ptr conditions; gaa_buffer_ptr mech_spec_cred; gaa_identity_cred_ptr next; }; 2.4.3 gaa_authorized_cred data structure This type of credentials used when individuals grant delegated credential or generate a capability. grantor Specifies a principal who issued the credential grantee Specifies a principal for whom the credential was issued objects A pointer to a linked list of structures of the type gaa_data, which contains a list of objects which may be accessed by the grantee. Object names are from the application-specific name space. access_rights A pointer to a linked list of structures of the type gaa_security_attribute_list_set. Each structure indicates granted access rights. conditions A pointer to a list of structures of the type gaa_security_attribute_list, which lists restrictions placed on the authorized credentials mech_spec_cred Contains a handle to the actual mechanism-specific authorized credential next Contains a pointer to the next authorized credential belonging to the same grantee typedef struct gaa_authorized_cred_struct gaa_authorized_cred, *gaa_authorized_cred_ptr; struct gaa_authr_cred_struct{ gaa_principals_ptr grantor; gaa_principals_ptr grantee; gaa_data objects; gaa_rights_ptr access_rights; gaa_buffer_ptr mech_spec_cred; gaa_authr_cred_ptr next; }; 2.4.4. gaa_attributes data structure The gaa_attributes type is a structure containing the following fields: mech_type Security mechanism used to obtain the credential type Type is used to define the type of attribute value Represents actual attribute contents conditions A pointer to a list of structures of the type gaa_security_attribute_list, which lists restrictions placed on the attribute credentials mech_spec_cred Contains a handle to the actual mechanism-specific attribute credential next Contains a pointer to the next attributes credential belonging to the same grantee. typedef struct gaa_attributes_struct gaa_attributes, *gaa_attributes_ptr; struct gaa_attributes_struct { gaa_data mech_type; gaa_data type; gaa_data value; gaa_cond_bindings_ptr conditions; gaa_buffer_ptr mech_spec_cred; gaa_attributes_ptr next; }; 2.4.5. gaa_unevaluated_cred data structure Evaluation of the acquired credentials can be defferd till the credential is actually needed. Unevaluated credentials are stored in the gaa_unevaluated_cred data structure. The gaa_unevaluated_cred type is a structure containing the following fields: cred_type Specifies credential type: GAA_IDENTITY, GAA_GROUP_MEMB, GAA_GROUP_NON_MEMB, GAA_AUTHORIZED, and GAA_ATTRIBUTES. grantor Specifies a principal who issued the credential grantee Specifies a principal for whom the credential was issued mech_type Specifies security mechanism used to obtain the credential mech_spec_cred Contains a handle to the actual mechanism-specific authorization credential cred_verification This pointer to the credential verification function for upcall is added by the application or transport next Contains a pointer to the next unevaluated credential belonging to the same subject. typedef enum { GAA_IDENTITY , GAA_GROUP_MEMB , GAA_GROUP_NON_MEMB , GAA_AUTHORIZED , GAA_ATTRIBUTES } gaa_cred_type; typedef struct gaa_uneval_cred_struct gaa_uneval_cred, *gaa_uneval_cred; struct gaa_uneval_cred_struct { gaa_cred_type cred_type; gaa_principals_ptr grantor; gaa_principals_ptr grantee; gaa_buffer_ptr mech_spec_cred; void (*cred_verification )(gaa_sec_context_ptr, va_list ap); gaa_uneval_cred_ptr next; }; 2.5 GAA API answer data structure The gaa_check_authorization function returns various information to the application for further evaluation in the gaa_answer data structure. The gaa_answer type is a structure containing the following fields: valid_time A pointer to a structure of type gaa_time_period. It specifies the time period during which the authorization is granted and is returned as a condition to be checked by the application. granted_raccess_rights A pointer to a linked list of structures of the type gaa_security_attribute_list_set conditions A pointer to a list of structures of type gaa_security_attribute_list, which lists all different conditions for the granted access rights required_sec_attributes Contains a pointer to a gaa_value_type_list structure, which contains information about additional security attributes required, e.g. group membership or authorized credentials. typedef struct gaa_time_period_struct gaa_time_period, *gaa_time_period_ptr; struct gaa_time_period_struct{ time_t start_time; /* NULL for unconstrained start time */ time_t end_time; /* NULL for unconstrained end time */ }; typedef struct gaa_answer_struct gaa_answer, *gaa_answer_ptr; struct gaa_answer_struct{ gaa_time_period_ptr valid_time; gaa_rights_ptr rights; }; 3. Memory allocation Storage for data returned to the application by a GAA API routine using gaa_buffer_ptr, gaa_security_attribute_list_ptr, is allocated by the GAA API routines. The application may clear this storage by invoking the gaa_release_buffer, gaa_release_sec_attributes_list and routines. Allocation of the gaa_buffer, gaa_security_attribute_list, and gaa_sec_context structures is always the responsibility of the application. 4. Status codes One or two status codes are returned by each GAA API routine. Two distinct sorts of status codes are returned. These are the GAA API status codes and mechanism-specific status codes. 4.1 The GAA API status codes GAA API routines return GAA API status codes as their gaa_error_code function value. These codes indicate errors that are independent of the underlying mechanisms. The errors that can be indicated via a GAA API status code are either generic API routine errors (errors that are defined in the GAA API specification) or calling errors (errors that are specific to these language bindings). 4.2 Mechanism-specific status codes GAA API routines return a minor_status parameter, which is used to indicate specialized errors from the underlying mechanisms or provide additional information about GAA API errors. The GAA status code GAA_FAILURE is used to indicate that the underlying mechanism detected an error for which no specific GAA status code is defined. The mechanism status code will provide more details about the error. 5. GAA API routine descriptions This section lists the functions performed by each of the GAA API routines and discusses their major parameters, describing how they are to be passed to the routines. 5.1 gaa_get_object_policy_info routine Purpose: The gaa_get_object_policy_info function is called to obtain security policy information associated with the object. In the ACL-based systems, this information represents object ACLs, in the capability-based systems, this information may contain a list of authorities allowed to grant capabilities. Parameters: minor_status mechanism-specific status code object Reference to the object to be accessed. The identifier for the object is from an application-specific name space and is opaque to the GAA API. authr_db Pointer to an application-specific authorization database retrieve Upcall function for the retrieval of the object ACL. The application maintains authorization information in a form understood by the application. It can be stored in a file, database, directory service or in some other way. The upcall function provided for the GAA API retrieves this information. attrbt_list_handle A pointer to a handle bound to the sequence of security attributes which constitute the security policy associated with the targeted object An unbound handle has the value GAA_SEC_ATTRBTS_UNBOUND. Function value: GAA status code: GAA_FAILURE Failure, see minor_status for more information gaa_error_code gaa_get_object_policy_info(uint32* minor_status, /* OUT */ gaa_data object, /* IN */ gaa_data authr_db, /* IN */ void*(*retrieve)(gaa_data object, gaa_data authr_db, ...), /* IN */ gaa_policy_ptr* policy /* OUT */, ...); 5.2 gaa_check_authorization routine Purpose: The gaa_check_authorization function tells the application whether the requested access rights are authorized, or if additional application-specific checks are required. Parameters: minor_status Mechanism specific status code attrbt_list_handle A handle to the list of security attributes, returned by the gaa_get_object_policy_info routine sec_context Principal's security context check_access_rights List of access rights for authorization. detailed_answer Contains various information for further evaluation by the application gaa_options Describes the behavior of the GAA API and specifies how the other arguments should be interpreted. detailed_answer Contains various information for further evaluation by the application Function value: GAA status code: GAA_FAILURE Failure, see minor_status for more information GAA_NO_CONTEXT No valid security context was supplied GAA_AUTHORIZED Is returned if all requested operations are authorized GAA_NOT_AUTHORIZED Is returned if at least one operation is not authorized GAA_ADDITIONAL_CHECKS_REQIRED Is returned if there are some unevaluated conditions and additional application-specific checks are needed or if continuous valuation of the conditions is required. gaa_error_code gaa_check_authorization (uint32 *minor_status, /* OUT */ gaa_sec_context_ptr sec_context, /* IN&OUT */ gaa_policy_ptr policy_handle, /* IN */ gaa_rights_ptr check_access_rights, /* IN */ gaa_options_ptr gaa_options, /* IN, OPTIONAL */ gaa_answer_ptr *detailed_answer /* OUT */ ); 5.3 gaa_inquire_object_policy_info routine Purpose: The gaa_inquire_object_policy_info function allows application to discover access control policies associated with the target object. Parameters: minor_status Mechanism specific status code attrbt_list_handle A handle to the list of security attributes, returned by the gaa_get_object_policy_info routine sec_context Principal's security context Function value: GAA status code: GAA_FAILURE Failure, see minor_status for more information GAA_NO_CONTEXT No valid security context was supplied gaa_error_code gaa_inquire_object_policy_info (uint32 *minor_status, /* OUT */ gaa_sec_context_ptr sec_context, /* IN&OUT */ gaa_policy_ptr policy_handle, /* IN */ gaa_rights_ptr *rights /* OUT */ ); 5.4 gaa_allocate_sec_context routine Purpose: Allocate a security context data structure and assign default values Parameters: minor_status Mechanism specific status code attrbt_list_handle A handle bound to a pointer to the security context structure Function value: GAA API status code: GAA_SUCCESS Successful completion GAA_FAILURE Failure, see minor_status for more information gaa_error_code gaa_allocate_sec_context (int* minor_status, /* OUT */ gaa_sec_context_ptr* sec_context_handle /* IN&OUT */); 5.5 gaa_release_sec_context routine Purpose: Delete a security context. The gaa_delete_sec_context routine will delete the local data structures associated with the specified security context. Parameters: minor_status Mechanism specific status code sec_context_handle A handle bound to a pointer to the security context structure Function value: GAA status code: GAA_SUCCESS Successful completion GAA_FAILURE Failure, see minor_status for more information gaa_error_code gaa_release_sec_context (int* minor_status, /* OUT */ gaa_sec_context_ptr* sec_context_handle /* IN */) 5.6 gaa_allocate_buffer routine Purpose: Allocate a gaa_buffer data structure and assign default values Parameters: minor_status Mechanism-specific status code buffer Pointer to allocated memory for gaa_buffer structure Function value: GAA status code: GAA_SUCCESS Successful completion GAA_FAILURE Failure, see minor_status for more information GAA_NO_BUFFER No valid buffer was supplied gaa_error_code gaa_allocate_buffer (int* minor_status, /* OUT */ gaa_buffer_ptr* buffer /* IN */); 5.7 gaa_release_buffer routine Purpose: Free storage associated with a buffer format name. The storage must have been allocated by a GAA API routine. In addition to freeing the associated storage, the routine will zero the length field in the buffer parameter. Parameters: minor_status Mechanism-specific status code buffer The storage associated with the buffer will be deleted. The gaa_buffer object will not be freed, but its length field will be zeroed. Function value: GAA status code: GAA_SUCCESS Successful completion GAA_FAILURE Failure, see minor_status for more information GAA_NO_BUFFER No valid buffer was supplied gaa_error_code gaa_release_buffer (int * minor_status, /* OUT */ gaa_buffer_ptr buffer /* IN */); 5.8 gaa_allocate_sec_attributes_list routine Purpose: Allocate a gaa_security_attribute_list data structure and assign default values Parameters: minor_status Mechanism-specific status code buffer Pointer to allocated memory for gaa_security_attribute_list structure Function value: GAA status code: GAA_SUCCESS Successful completion GAA_FAILURE Failure, see minor_status for more information GAA_NO_BUFFER No valid buffer was supplied gaa_error_code gaa_allocate_sec_attributes_list (int* minor_status, /* OUT */ gaa_security_attribute_list_ptr* buffer /* IN */); 5.9 gaa_release_sec_attributes_list routine Purpose: Free storage associated with a buffer Parameters: minor_status Mechanism-specific status code buffer The storage associated with the buffer will be deleted Function value: GAA status code: GAA_SUCCESS Successful completion GAA_FAILURE Failure, see minor_status for more information GAA_NO_BUFFER No valid buffer was supplied gaa_error_code gaa_release_buffer (int* minor_status, /* OUT */ gaa_security_attribute_list_ptr* buffer /* IN */); 6. The GAA API constants The following constants are used in GAA API calls and structures, this list is not complete: #define GAA_NO_OPTIONS ((gaa_options_ptr)0) #define GAA_NO_BUFFER ((gaa_buffer_ptr)0) #define GAA_EMPTY_BUFFER {0, NULL} #define GAA_NO_DATA ((gaa_name) 0) #define GAA_NO_SEC_CONTEXT ((gaa_sec_context_ptr)0) #define GAA_SEC_ATTRBTS_UNBOUND ((gaa_sec_attribute_list_ptr)0) #define GAA_NO_PRINCIPALS ((gaa_principals_ptr)0) #define GAA_NO_RIGHTS ((gaa_rights_ptr) 0) #define GAA_NO_CONDITIONS ((gaa_conditions_ptr)0) #define GAA_NO_COND_BINDINGS ((gaa_cond_bindings_ptr)0) #define GAA_NO_UNEVAL_CRED ((gaa_uneval_cred_ptr)0) #define GAA_NO_ANSWER ((gaa_answer_ptr)0) #define GAA_NO_IDENTITY_CRED ((gaa_identity_cred_ptr)0) #define GAA_NO_AUTHORIZATION_CRED ((gaa_authr_cred_ptr)0) #define GAA_NO_ATTRIBUTES ((gaa_attributes_ptr)0) #define GAA_YES 0 /* (indicating authorization) is returned if all requested operations are authorized. */ #define GAA_NO 1 /* (indicating denial of authorization) is returned if at least one operation is not authorized. */ #define GAA_MAYBE -1 /* (indicating 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. */ 7. The GAA API flags Flags are 32 bits. Condition flags: #define COND_FLG_EVALUATED 0x01 /* condition has been evaluated */ #define COND_FLG_MET 0x10 /* condition has been met */ #define COND_FLG_ENFORCE 0x100 /* condition has to be enforced */ 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. 10. 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