INTERNET-DRAFT Tatyana Ryutov CAT Working Group Clifford Neuman Expires February 1999 USC/Information Sciences Institute draft-ietf-cat-gaa-cbind-00.txt August 07, 1998 Generic Authorization and Access control Application Program Interface C-bindings 0. Status Of this Document This document is an Internet-Draft. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF), its areas, and its working groups. Note that other groups may also distribute working documents as Internet-Drafts. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." To view the entire list of current Internet-Drafts, please check the "1id-abstracts.txt" listing contained in the Internet-Drafts Shadow Directories on ftp.is.co.za (Africa), ftp.nordu.net (Northern Europe), ftp.nis.garr.it (Southern Europe), munnari.oz.au (Pacific Rim), ftp.ietf.org (US East Coast), or ftp.isi.edu (US West Coast). 1. Abstract The Generic Authorization and Access control Application Programming Interface (GAA API) provides access control services to calling applications. It facilitates access control decisions for applications and allows applications to discover access control policies associated with a targeted resource. The GAA API is usable by multiple applications supporting different kinds of protected objects. The GAA API design supports: - a variety of security mechanisms based on public or secret key cryptosystems - different authorization models - heterogeneous security policies - various access rights This document specifies C language bindings for the GAA API, which is described at a language-independent conceptual level in draft-ietf-cat-acc-cntrl-frmw-00.txt 2. The GAA API data types and calling conventions The data types describe only fields that must be provided by all Ryutov/Neuman Expires February 1999 GAA API implementations. Individual implementations may provide additional fields for internal use within GAA API routines. 2.1. Integer types The GAA API defines the following integer data type: uint32 32-bit unsigned integer 2.2. String and similar data Certain data items used by the GAA API may be regarded as a character strings, e.g. principal name or specification of security mechanism. The data of this kind is passed between the GAA API and application using the gaa_data_ptr data type, which is a pointer to a gaa_data structure. 2.2.1 gaa_data data structure The gaa_data type is a structure containing the following fields: length Contains the total number of bytes in the datum. data Contains a pointer to the actual datum. typedef struct gaa_data_struct gaa_data, *gaa_data_ptr; struct gaa_data_struct { int length; char *data; }; 2.2.2. gaa_tag_value_list data structure Some data items used by the GAA API may be regarded as a linked list of tag:value character elements. For example, a pointer to a list of tag:value character strings is passed to the gaa_check_authorithation routine via the gaa_options parameter. The data of this kind is passed between the GAA API and the application using the gaa_tag_value_list_ptr data type, which is a pointer to a gaa_tag_value_list structure. The gaa_tag_value_list type is a structure containing the following fields: tag A character string, which identifies how the character string stored in the "value" field should be interpreted by the GAA API. value Contains a pointer to the element of the type gaa_data. Ryutov/Neuman Expires February 1999 next A pointer to the next element in the list. typedef struct gaa_tag_value_list_struct gaa_tag_value_list, *gaa_tag_value_list_ptr; struct gaa_tag_value_list_struct { gaa_data_ptr tag; gaa_data_ptr value; gaa_tag_value_list_ptr next; }; 2.2.3. gaa_tag_vector and gaa_tag_vector_list data structures Some data items used by the GAA API may be regarded as a linked list of tag:vector elements. For example, a pointer to a list of tag:vector elements is passed to the gaa_check_authorithation routine via the check_access_rights parameter. The data of this kind is passed between the GAA API and the application using the gaa_tag_vector_list_ptr data type, which is a pointer to a gaa_tag_vector_list structure. The gaa_tag_vector type is a structure containing the following fields: tag Denotes how bits in the "vector" field are to be interpreted. vector Contains an integer of type uint32 typedef struct gaa_tag_vector_struct gaa_tag_vector, *gaa_tag_vector_ptr; struct gaa_tag_vector_struct { gaa_data_ptr tag; uint32 vector; }; The gaa_tag_vector_list type is a structure containing the following fields: element Contains a pointer to the element of type gaa_tag_vector next Contains a pointer to the next element in the list typedef struct gaa_tag_vector_list_struct gaa_tag_vector_list, *gaa_tag_vector_list_ptr; struct gaa_tag_vector_list_struct { gaa_tag_vector_ptr element; gaa_tag_vector_list_ptr next; }; 2.3. Opaque data types Ryutov/Neuman Expires February 1999 Some data items are considered opaque to the GAA API, because their internal data structure has no significance to the GAA API, e.g. actual mechanism-specific credentials. Opaque data is passed between the GAA API and the application using the gaa_buffer_ptr data type, which is a pointer to a gaa_buffer structure. The gaa_buffer type is a structure containing the following fields: length Contains the total number of bytes in the datum value Contains a pointer to the actual datum typedef struct gaa_buffer_struct gaa_buffer, *gaa_buffer_ptr; struct gaa_buffer_struct { size_t length; void *value; }; 2.4. GAA API Access Control List data structures Certain GAA API procedures take parameters of the type gaa_acl_ptr, which is a pointer to a gaa_acl structure. gaa_acl data type contains a complete ACL, made up of a list of entry fields of type gaa_acl_entry. GAA_ACL_UNBOUND defines the value of the unbound ACL handle. 2.4.1. gaa_acl data structure The gaa_acl type is a structure containing the following fields: object_name Contains a name of an object with which the ACL is associated. The name of the object is from the application-specific name space. The object_name field is evaluated by GAA API routine when checking credentials of the type gaa_authorized_cred to determine if the object_name for which the ACL is being examined is listed in the set of those objects which can be accessed by the grantee. Whether this field should be present in the gaa_acl data structure is not clear. If we decide not to include this field, we should provide a means for deciding if the targeted object is included in the list of objects accessible by the grantee. acl_entries A pointer to a list of ACL entries, each of type gaa_acl_entry typedef struct gaa_acl_struct gaa_acl, *gaa_acl_ptr; Ryutov/Neuman Expires February 1999 struct gaa_acl_struct { gaa_data_ptr object_name; gaa_acl_entry_ptr acl_entries; }; 2.4.2. gaa_acl_entry data structure The gaa_acl_entry type is a structure containing the following fields: type Indicates whether the ACL entry grants or denies access. If type = GAA_GRANT, the entry specifies positive rights. If type = GAA_DENY, the entry specifies negative rights. Entries of this type must not have any conditions, so GAA_NO_CONDITIONS value is stored in the condition field. principals A pointer to a structure of the type gaa_principal_list, which contains list of principals. Principals can be aggregated into a single ACL entry when the same set of access rights and conditions applies to all of them. access_rights A pointer to a linked list of structures of the type gaa_acl_access_rights_set. Each set indicates access rights named with the same tag. For example, consider the following user-level representation of an ACL entry: USER kerberos.v5 joe@ISI.EDU < FILE : read > < FILE : write ACCOUNT: withdraw > time_window : 7AM-7PM time_day : Mon-Fri time_day : Mon-Fri < FILE : execute ACCOUNT : deposit ACCOUNT : transfer > location : *.isi.edu; The first access rights set consists of FILE : read, FILE : write and FILE : execute. The second one consists of ACCOUNT : withdraw, ACCOUNT : deposit and ACCOUNT : transfer. conditions A pointer to a list of structures of the type gaa_conditions, which contains all different conditions that are present in the ACL entry. In the example of an ACL entry given above, the condition list contains three conditions: time_window : 7AM-7PM, time_day : Mon-Fri and location : *.isi.edu. next Ryutov/Neuman Expires February 1999 A pointer to the next ACL entry typedef enum { GAA_GRANT, GAA_DENY } gaa_entry_type; typedef struct gaa_acl_entry_struct gaa_acl_entry, *gaa_acl_entry_ptr; struct gaa_acl_entry_struct { gaa_entry_type type; gaa_principal_list_ptr principals; gaa_access_rights_set_ptr access_rights; gaa_conditions_ptr conditions; gaa_acl_entry_ptr next; }; 2.4.3. gaa_principal and gaa_principal_list data structures The gaa_principal type is a structure containing the following fields: type Specifies the type of principal: GAA_USER, GAA_GROUP, GAA_HOST, GAA_APPLICATION or GAA_ANYBODY. mech_type Contains principal naming method, which specifies the type of the security mechanism used to obtain authenticated subject's identity, e.g. Kerberos.V5, DCE. If type = GAA_ANYBODY, mech_type and name fields are assigned value GAA_NO_DATA. name Contains principal name, which specifies authenticated subject's identity, e.g. joe@ISI.EDU. typedef enum { GAA_USER , GAA_GROUP , GAA_HOST , GAA_APPLICATION , GAA_ANYBODY } gaa_principal_type; typedef struct gaa_principal_struct gaa_principal, *gaa_principal_ptr; struct gaa_principal_struct { gaa_principal_type type; gaa_data_ptr mech_type; Ryutov/Neuman Expires February 1999 gaa_data_ptr name; }; The gaa_principal_list type is a structure containing the following fields: principal A pointer to the gaa_principal structure next A pointer to the next principal in the ACL entry typedef struct gaa_principal_list_struct gaa_principal_list, *gaa_principal_list_ptr; struct gaa_principal_list_struct { gaa_principal_ptr principal; gaa_principal_ptr next; }; 2.4.4. gaa_access_rights_set data structure The gaa_access_rights_set type is a structure containing the following fields: rights A pointer to a structure of the type gaa_tag_vector. In the example of an ACL entry given in the section 2.4.2, the gaa_tag_vector structure, corresponding to the first access rights set, will have "FILE" value in the "tag " field and 1110...0 in the "vector" field. The first set bit stands for "read", the second one for "write" and the third one for "execute". The gaa_tag_vector structure, corresponding to the second access rights set, will have "ACCOUNT" value in the "tag" field and 1110...0 in the "vector" field. The first set bit stands for "withdraw", the second one for "deposit" and the third one for "transfer". mask An array containing GAA_NUM_ACCESS_RIGHTS pointers to a list of structures of type gaa_condition_mask. Each gaa_condition_mask structure contains a pointer to particular condition associated with the granted right and a pointer to the next structure of the type gaa_condition_mask. mask[i], were index "i" corresponds to a bit in the bit-vector, is set to GAA_NO_CONDITIONS for all denied rights and granted rights with no associated conditions. In the example of an ACL entry given in the section 2.4.2, lets consider mask structure for the first access rights set. The access rights set will have "FILE" value in the "tag" field and 1110...0 in the "vector" field of "rights" element. mask[0] (corresponding to "read" access right) will be set to GAA_NO_CONDITIONS, since "read" has no conditions. Ryutov/Neuman Expires February 1999 mask[3], mask[4],..., mask[31] will be also set to GAA_NO_CONDITIONS. mask[1] (corresponding to "write" access right) will point to the list of gaa_condition_mask, which has two elements. The first element will have a pointer to the condition time_window : 7AM-7PM in the "condition" field, the second element will have a pointer to the condition time_day : Mon-Fri in the "condition" field. mask[2] (corresponding to "execute" access right) will point to the list of gaa_condition_mask, which has just one element with a pointer to the condition location : *.isi.edu in the "condition" field. next A pointer to the next set of access rights in the ACL entry. typedef struct gaa_condition_mask_struct gaa_condition_mask, *gaa_condition_mask_ptr; struct gaa_condition_mask_struct { gaa_conditions_ptr condition; gaa_condition_mask_ptr next; } ; typedef struct gaa_access_rights_set_struct gaa_access_rights_set, *gaa_access_rights_set_ptr; struct gaa_access_rights_set_struct { gaa_tag_vector_ptr rights; gaa_condition_mask_ptr mask[GAA_NUM_ACCESS_RIGHTS]; gaa_access_rights_set_ptr next; }; 2.4.5. gaa_conditions data structure This structure defines a specific policies under which access rights are granted. It lists all conditions that have been encountered in the ACL entry. The mapping between access rights and corresponding condition sets is defined via gaa_condition_mask structure. The gaa_conditions type is a structure containing the following fields: type Type defines the type of condition and which evaluation function will be invoked to evaluate it. value Value represents a set of parameters for the condition evaluation function. The meaning of the parameters and their relationships depend on how the evaluation function interprets them. flags Flags indicate if condition was evaluated/not evaluated, satisfied/not satisfied, or must be enforced. Ryutov/Neuman Expires February 1999 next A pointer to the next condition in the ACL entry. typdef struct gaa_conditions_struct gaa_conditions, *gaa_conditions_ptr; struct gaa_conditions_struct { gaa_data_ptr type; gaa_data_ptr value; uint32 flags; gaa_conditions_ptr next; }; 2.5 GAA API Security Context data structures The security context is a GAA API data structure, which is passed as an argument to the GAA API. It stores information relevant to access control. 2.5.1 gaa_sec_context data structure The gaa_sec_context type is a structure containing the following fields: identity_cred A pointer to a list of structures of the type gaa_identity_cred authr_cred A pointer to a list of structures of the type gaa_authrized_cred group_membership A pointer to a list of structures of the type gaa_identity_cred, which specifies that the grantee is a member of only listed groups group_non_membership A pointer to a list of structures of the type gaa_identity_cred, which specifies that the grantee is NOT a member of the listed groups attributes A pointer to a list of structures of the type gaa_attributes, which contains miscellaneous attributes attached to the grantee, e.g. age of the grantee, grantee security clearance. unevl_cred A pointer to a list of structures of type gaa_unevaluated_cred. connection_state Contains a mechanism-specific representation of per-connection context, some of the data stored here include keyblocks, addresses. condition_evaluation Specific condition evaluation function called by GAA API if there are Ryutov/Neuman Expires February 1999 application-specific conditions. Generic (understood by the GAA API) conditions are evaluated by the GAA API internal functions. pull_cred This function is called when additional credentials are required. It obtains the necessary credentials and then cred_evaluate function is invoked. This process can be recursive. cred_evaluate This specific function is invoked to parse the contents of the acquired credentials into the GAA API internal form and evaluate them. typedef struct gaa_sec_context_struct gaa_sec_context, *gaa_sec_context_ptr struct gaa_sec_context_struct { gaa_identity_cred_ptr identity_cred; gaa_authrized_cred_ptr authr_cred; gaa_identity_cred_ptr group_membership; gaa_identity_cred_ptr group_non_membership; gaa_attributes_ptr attributes; gaa_unevaluated_cred_ptr unevl_cred; gaa_buffer_ptr connection_state; void (*condition_evaluation)(gaa_sec_context_ptr, va_list ap); void (*pull_cred)(gaa_sec_context_ptr, va_list ap); void (*cred_evaluate)(gaa_sec_context_ptr, va_list ap); }; 2.5.2. gaa_identity_cred data structure A gaa_identity_cred structure is composed of a set of identity credentials. Identity credentials describe a set of mechanism-specific principals, and give their holder the ability to act as any of those principals. Each of the identity credentials contains information needed to authenticate a single principal. The gaa_identity type is a structure containing the following fields: principal A pointer to a structure of the type gaa_principal conditions A pointer to a list of structures of the type gaa_conditions, which lists restrictions placed on the identity, e.g. validity time periods mech_spec_cred Contains a handle to the actual mechanism-specific identity credential Ryutov/Neuman Expires February 1999 next Contains a pointer to the next identity credential typedef struct gaa_identity_cred_struct gaa_identity_cred, *gaa_identity_cred_ptr; struct gaa_identity_cred_struct { gaa_principal_ptr principal; gaa_conditions_ptr conditions; gaa_buffer_ptr mech_spec_cred; gaa_identity_cred_ptr next; }; 2.5.3 gaa_authorized_cred data structure This type of credentials used when individuals grant delegated credential or generate a capability. grantor Specifies a principal who issued the credential grantee Specifies a principal for whom the credential was issued objects A pointer to a linked list of structures of the type gaa_data, which contains a list of objects which may be accessed by the grantee. Object names are from the application-specific name space. access_rights A pointer to a linked list of structures of the type gaa_acl_access_rights_set. Each structure indicates granted access rights. conditions A pointer to a list of structures of the type gaa_conditions, which lists restrictions placed on the authorized credentials mech_spec_cred Contains a handle to the actual mechanism-specific authorized credential next Contains a pointer to the next authorized credential belonging to the same grantee typedef struct gaa_authorized_cred_struct gaa_authorized_cred, *gaa_authorized_cred_ptr; struct gaa_authorized_cred_struct{ gaa_principal_ptr grantor; gaa_principal_ptr grantee; gaa_data_list_ptr objects; gaa_access_rights_set_ptr access_rights; gaa_conditions_ptr conditions; gaa_buffer_ptr mech_spec_cred; Ryutov/Neuman Expires February 1999 gaa_authorized_cred_ptr next; }; 2.5.4. gaa_attributes data structure The gaa_attributes type is a structure containing the following fields: mech_type Security mechanism used to obtain the credential type Type is used to define the type of attribute value Represents actual attribute contents conditions A pointer to a list of structures of the type gaa_conditions, which lists restrictions placed on the attribute credentials mech_spec_cred Contains a handle to the actual mechanism-specific attribute credential next Contains a pointer to the next attributes credential belonging to the same grantee. typedef struct gaa_attributes_struct gaa_attributes, *gaa_attributes_ptr; struct gaa_attributes_struct { gaa_data_ptr mech_type; gaa_data_ptr type; gaa_data_ptr value; gaa_conditions_ptr conditions; gaa_buffer_ptr mech_spec_cred; gaa_attributes_ptr next; }; 2.5.5. gaa_unevaluated_cred data structure Evaluation of the acquired credentials can be defferd till the credential is actually needed. Unevaluated credentials are stored in the gaa_unevaluated_cred data structure. The gaa_unevaluated_cred type is a structure containing the following fields: cred_type Specifies credential type: GAA_IDENTITY, GAA_GROUP_MEMB, GAA_GROUP_NON_MEMB, GAA_AUTHORIZED, and GAA_ATTRIBUTES. Ryutov/Neuman Expires February 1999 grantor Specifies a principal who issued the credential grantee Specifies a principal for whom the credential was issued mech_type Specifies security mechanism used to obtain the credential mech_spec_cred Contains a handle to the actual mechanism-specific authorization credential cred_verification This pointer to the credential verification function for upcall is added by the application or transport next Contains a pointer to the next unevaluated credential belonging to the same subject. typedef enum { GAA_IDENTITY , GAA_GROUP_MEMB , GAA_GROUP_NON_MEMB , GAA_AUTHORIZED , GAA_ATTRIBUTES } gaa_cred_type; typedef struct gaa_unevaluated_cred_struct gaa_unevaluated_cred, *gaa_unevaluated_cred; struct gaa_unevaluated_cred_struct { gaa_cred_type cred_type; gaa_principal_ptr grantor; gaa_principal_ptr grantee; gaa_buffer_ptr mech_spec_cred; void (*cred_verification)(gaa_sec_context_ptr, va_list ap); gaa_unevaluated_cred_ptr next; }; 2.6 GAA API answer data structure The gaa_check_authorization function returns various information to the application for further evaluation in the gaa_answer data structure. The gaa_answer type is a structure containing the following fields: valid_time A pointer to a structure of type gaa_time_period. It specifies the time period during which the authorization is granted and Ryutov/Neuman Expires February 1999 is returned as a condition to be checked by the application. Expiration time is calculated by the GAA API, based on: - time-related conditions in the ACL matching entries - restrictions in the attributes, identity, authorization and group membership credentials granted_raccess_rights A pointer to a linked list of structures of the type gaa_acl_access_rights_set conditions A pointer to a list of structures of type gaa_conditions, which lists all different conditions for the granted access rights required_sec_attributes Contains a pointer to a gaa_value_type_list structure, which contains information about additional security attributes required, e.g. group membership or authorized credentials. typedef struct gaa_time_period_struct gaa_time_period, *gaa_time_period_ptr; struct gaa_time_period_struct{ time_t start_time; /* NULL for unconstrained start time */ time_t end_time; /* NULL for unconstrained end time */ }; typedef struct gaa_answer_struct gaa_answer, *gaa_answer_ptr; struct gaa_answer_struct{ gaa_time_period_ptr valid_time; gaa_access_rights_set_ptr granted_access_rights; gaa_conditions_ptr conditions; gaa_tag_value_list_ptr required_sec_attributes }; 3. Memory allocation Storage for data returned to the application by a GAA API routine using gaa_buffer_ptr, gaa_tag_value_list_ptr, gaa_tag_vector_list is allocated by the GAA API routines. The application may clear this storage by invoking the gaa_release_buffer, gaa_release_tag_value_list and gaa_release_tag_vector_list routines. Allocation of the gaa_buffer, gaa_tag_value_list, gaa_tag_vector_list and gaa_sec_context structures is always the responsibility of the application. 4. Status codes One or two status codes are returned by each GAA API routine. Two distinct sorts of status codes are returned. These are the GAA API status codes and mechanism-specific status codes. 4.1 The GAA API status codes Ryutov/Neuman Expires February 1999 GAA API routines return GAA API status codes as their gaa_error_code function value. These codes indicate errors that are independent of the underlying mechanisms. The errors that can be indicated via a GAA API status code are either generic API routine errors (errors that are defined in the GAA API specification) or calling errors (errors that are specific to these language bindings). 4.2 Mechanism-specific status codes GAA API routines return a minor_status parameter, which is used to indicate specialized errors from the underlying mechanisms or provide additional information about GAA API errors. The GAA status code GAA_FAILURE is used to indicate that the underlying mechanism detected an error for which no specific GAA status code is defined. The mechanism status code will provide more details about the error. 5. GAA API routine descriptions This section lists the functions performed by each of the GAA API routines and discusses their major parameters, describing how they are to be passed to the routines. 5.1 gaa_get_object_acl routine Purpose: The gaa_get_object_acl function is called to obtain a handle to an object ACL. Parameters: minor_status mechanism-specific status code object Reference to the object to be accessed. The identifier for the object is from an application-specific name space and is opaque to the GAA API. authr_db Pointer to an application-specific authorization database retrieve Upcall function for the retrieval of the object ACL. The application maintains authorization information in a form understood by the application. It can be stored in a file, database, directory service or in some other way. The upcall function provided for the GAA API retrieves the ACL and translates it into the internal GAA API representation. acl_handle A pointer to a handle bound to the ACL that is the subjects of examination. An unbound handle has the value GAA_ACL_UNBOUND. Ryutov/Neuman Expires February 1999 Function value: GAA status code: GAA_FAILURE Failure, see minor_status for more information gaa_error_code gaa_get_object_acl(int* minor_status, /* OUT */ gaa_data_ptr object, /* IN */ gaa_data_ptr authr_db, /* IN */ void*(*retrieve)(gaa_data_ptr object, gaa_data_ptr authr_db, ...) /* IN */ gaa_acl_list_ptr* acl_handle , /* OUT */); 5.2 gaa_check_authorization routine Purpose: The gaa_check_authorization function tells the application whether the requested access rights are authorized, or if additional application-specific checks are required. Parameters: minor_status Mechanism specific status code acl_handle A handle to the ACL, returned by the gaa_get_object_acl routine sec_context Principal's security context check_access_rights List of access rights for authorization. This argument is optional. detailed_answer Contains various information for further evaluation by the application gaa_options Describes the behavior of the GAA API and specifies how the other arguments should be interpreted. For example, type of the ACL: ordered or unordered. Depending on this type corresponding ACL evaluation algorithm will be used by the GAA API. This argument is optional. detailed_answer Contains various information for further evaluation by the application Function value: GAA status code: GAA_FAILURE Ryutov/Neuman Expires February 1999 Failure, see minor_status for more information GAA_NO_CONTEXT No valid security context was supplied GAA_AUTHORIZED Is returned if all requested operations are authorized GAA_NOT_AUTHORIZED Is returned if at least one operation is not authorized GAA_ADDITIONAL_CHECKS_REQIRED Is returned if there are some unevaluated conditions and additional application-specific checks are needed or if continuous valuation of the conditions is required. gaa_error_code gaa_check_authorization (int* minor_status, /* OUT */ gaa_sec_context_ptr sec_context, /* IN&OUT */ gaa_acl_list_ptr acl_handle, /* IN */ gaa_tag_vector_list_ptr check_access_rights, /* IN, OPTIONAL */ gaa_tag_value_list_ptr gaa_options /* IN, OPTIONAL */ gaa_answer_struct_ptr detailed_answer /* OUT */ ); 5.3 gaa_allocate_sec_context routine Purpose: Allocate a security context data structure and assign default values Parameters: minor_status Mechanism specific status code acl_handle A handle bound to a pointer to the security context structure Function value: GAA API status code: GAA_SUCCESS Successful completion GAA_FAILURE Failure, see minor_status for more information gaa_error_code gaa_allocate_sec_context (int* minor_status, /* OUT */ gaa_sec_context_ptr* sec_context_handle /* IN&OUT */); Ryutov/Neuman Expires February 1999 5.4 gaa_release_sec_context routine Purpose: Delete a security context. The gaa_delete_sec_context routine will delete the local data structures associated with the specified security context. Parameters: minor_status Mechanism specific status code sec_context_handle A handle bound to a pointer to the security context structure Function value: GAA status code: GAA_SUCCESS Successful completion GAA_FAILURE Failure, see minor_status for more information gaa_error_code gaa_release_sec_context (int* minor_status, /* OUT */ gaa_sec_context_ptr* sec_context_handle /* IN */) 5.5 gaa_allocate_buffer routine Purpose: Allocate a gaa_buffer data structure and assign default values Parameters: minor_status Mechanism-specific status code buffer Pointer to allocated memory for gaa_buffer structure Function value: GAA status code: GAA_SUCCESS Successful completion GAA_FAILURE Ryutov/Neuman Expires February 1999 Failure, see minor_status for more information GAA_NO_BUFFER No valid buffer was supplied gaa_error_code gaa_allocate_buffer (int* minor_status, /* OUT */ gaa_buffer_ptr* buffer /* IN */); 5.6 gaa_release_buffer routine Purpose: Free storage associated with a buffer format name. The storage must have been allocated by a GAA API routine. In addition to freeing the associated storage, the routine will zero the length field in the buffer parameter. Parameters: minor_status Mechanism-specific status code Ryutov/Neuman Expires February 1999 buffer The storage associated with the buffer will be deleted. The gaa_buffer object will not be freed, but its length field will be zeroed. Function value: GAA status code: GAA_SUCCESS Successful completion GAA_FAILURE Failure, see minor_status for more information GAA_NO_BUFFER No valid buffer was supplied gaa_error_code gaa_release_buffer (int * minor_status, /* OUT */ gaa_buffer_ptr buffer /* IN */); 5.7 gaa_allocate_tag_value_list routine Purpose: Allocate a gaa_tag_value_list data structure and assign default values Ryutov/Neuman Expires February 1999 Parameters: minor_status Mechanism-specific status code buffer Pointer to allocated memory for gaa_tag_value_list structure Function value: GAA status code: GAA_SUCCESS Successful completion GAA_FAILURE Failure, see minor_status for more information GAA_NO_BUFFER No valid buffer was supplied gaa_error_code gaa_allocate_tag_value_list (int* minor_status, /* OUT */ gaa_tag_value_list_ptr* buffer /* IN */); 5.8 gaa_release_tag_value_list routine Purpose: Free storage associated with a buffer Parameters: minor_status Mechanism-specific status code buffer The storage associated with the buffer will be deleted Function value: GAA status code: GAA_SUCCESS Successful completion GAA_FAILURE Failure, see minor_status for more information GAA_NO_BUFFER No valid buffer was supplied gaa_error_code Ryutov/Neuman Expires February 1999 gaa_release_buffer (int* minor_status, /* OUT */ gaa_tag_value_list_ptr* buffer /* IN */); 5.9 gaa_allocate_tag_vector_list routine Purpose: Allocate a gaa_tag_vector_list data structure and assign default values Parameters: minor_status Mechanism-specific status code buffer Pointer to allocated memory for gaa_tag_vector_list structure Function value: GAA status code: GAA_SUCCESS Successful completion GAA_FAILURE Failure, see minor_status for more information GAA_NO_BUFFER No valid buffer was supplied gaa_error_code gaa_allocate_tag_vector_list (int * minor_status, /* OUT */ gaa_tag_vector_list_ptr* buffer /* IN */); 5.10 gaa_release_tag_vector_list routine Purpose: Free storage associated with a buffer Parameters: minor_status Mechanism-specific status code buffer The storage associated with the buffer will be deleted Function value: Ryutov/Neuman Expires February 1999 GAA status code: GAA_SUCCESS Successful completion GAA_FAILURE Failure, see minor_status for more information GAA_NO_BUFFER No valid buffer was supplied gaa_error_code gaa_release_tag_vector_list (int* minor_status, /* OUT */ gaa_tag_vector_ptr* buffer /* IN */); 5.11 gaa_parse_acl routine Purpose: Parse the ASCII file in the pre-defined format described in draft-ietf-cat-acc-cntrl-frmw-00.txt into the GAA API internal ACL structures. Parameters: minor_status Mechanism-specific status code acl_file_handle A pointer to an ASCII file containing an ACL for the object in the pre-defined format acl_handle A handle to the gaa_acl structure application_access_rights A pointer to the list of application-specific names for access rights. GAA API uses it to build bit-vectors for internal access rights representation. This parameter is optional. It is not required if the ACL contains bit-vector representation of the access rights, for example: USER kerberos.v5 joe@ISI.EDU < FILE : 1100000000000000000000000000000000 > time_window : 7AM-7PM time_day : Mon-Fri < ACCOUNT : 1100000000000000000000000000000000 >location : *.isi.edu ; In this case the value is set to GAA_NO_TAG_VALUE_LIST. Function value: GAA status code: GAA_SUCCESS Successful completion Ryutov/Neuman Expires February 1999 GAA_FAILURE Failure, see minor_status for more information gaa_error_code gaa_parse_acl (int * minor_status, /* OUT */ FILE *acl_file_handle, /* IN */ gaa_acl_ptr* acl_handle, /* IN&OUT */ gaa_tag_value_list_ptr application_access_rights /* IN, OPTIONAL */); 6. The GAA API constants The following constants are used in GAA API calls and structures, this list is not complete: #define GAA_NO_BUFFER ((gaa_buffer_ptr) 0) #define GAA_EMPTY_BUFFER {0, NULL} #define GAA_NO_DATA ((gaa_data_ptr)0) #define GAA_NO_TAG_VALUE_LIST ((gaa_tag_value_list_ptr)0) #define GAA_ACL_UNBOUND ((gaa_acl_ptr)0) #define NO_EACL_ENTRY ((gaa_acl_entry_ptr) 0) #define NO_PRINCIPALS ((gaa_acl_principal_list_ptr) 0) #define NO_ACCESS_RIGHTS ((gaa_acl_access_rights_set_ptr) 0) #define GAA_NO_CONDITIONS ((gaa_conditions_ptr)0) 7. The GAA API flags Flags are 32 bits. Condition flags: #define COND_FLG_EVALUATED 0x80000000 #define COND_FLG_SATISFIED 0x40000000 #define COND_FLG_ENFORCE 0x20000000 Flags from 0x10000000 to 0x00000001 are reserved. 8. Acknowledgments Gene Tsudik, Brian Tung, Bapa Rao, Ilia Ovsiannikov and the Xerox IS team have contributed to discussion of ideas and material in this draft. 9. References [1] Linn, J., "Generic Security Service Application Program Interface", RFC 1508, Geer Zolot Associate, September 1993. [2] Wray, ., "Generic Security Service Application Program Interface V2 - C bindings", Internet draft, May 1997. 10. Authors' Addresses Ryutov/Neuman Expires February 1999 Tatyana Ryutov Clifford Neuman USC/Information Sciences Institute 4676 Admiralty Way Suite 1001 Marina del Rey, CA 90292-6695 Phone: +1 310 822 1511 E-Mail: {tryutov, bcn}@isi.edu
Datatracker
Report a datatracker bug
draft-ietf-cat-gaa-cbind-00
Internet-Draft
| Document | Document type |
This is an older version of an Internet-Draft whose latest revision state is "Expired".
Expired & archived
|
|
|---|---|---|---|
| Select version | |||
| Compare versions | |||
| Author | |||
| RFC stream |
|
||
| Other formats | |||
| Additional resources | Mailing list discussion |