Tatyana Ryutov
`INTERNET-DRAFT
`Clifford Neuman
`CAT Working Group
`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
`
`EMC v. IV
`IPR2017-00338
`Ex. 1012
`1
`
`

`

`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
`
`2
`
`

`

`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.
`
`3
`
`

`

`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;
`
`4
`
`

`

`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
`
`5
`
`

`

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

`

`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
`
`7
`
`

`

`} 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;
`
`};
`
`8
`
`

`

`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
`
`9
`
`

`

`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
`
`10
`
`

`

`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
`
`11
`
`

`

`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 */);
`
`12
`
`

`

`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
`
`13
`
`

`

`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
`
`14
`
`

`

`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 */);
`
`15
`
`

`

`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. */
`-1 /* (indicating a need for additional checks) is
`if there are some unevaluated conditions and
`application-specific checks are needed, or
`evaluation is required. */
`
`#define GAA_MAYBE
`returned
`additional
`continuous
`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
`
`16
`
`

`

`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
`
`17
`
`