One document matched: draft-ietf-cat-gaa-cbind-01.txt
Differences from draft-ietf-cat-gaa-cbind-00.txt
INTERNET-DRAFT Tatyana Ryutov
CAT Working Group Clifford Neuman
Expires May 1999 USC/Information Sciences Institute
draft-ietf-cat-gaa-cbind-01.txt November 17, 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-01.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. String and similar data
Certain data items used by the GAA API may be regarded as a character
strings, e.g. security attribute type or specification of defining authority.
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_security_attribute_list 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_security_attribute_list_struct gaa_security_attribute_list,
*gaa_security_attribute_list_ptr;
struct gaa_security_attribute_list_struct {
gaa_data_ptr type;
gaa_data_ptr authority;
gaa_data_ptr value;
gaa_security_attribute_list_ptr next;
};
2.3. 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;
};
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_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.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_security_attribute_list_ptr principal;
gaa_security_attribute_list_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_authorized_cred_struct{
gaa_security_attribute_list_ptr grantor;
gaa_security_attribute_list_ptr grantee;
gaa_data_list_ptr objects;
gaa_security_attribute_list_ptr access_rights;
gaa_security_attribute_list_ptr conditions;
gaa_buffer_ptr mech_spec_cred;
gaa_authorized_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_ptr mech_type;
gaa_data_ptr type;
gaa_data_ptr value;
gaa_security_attribute_list_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_unevaluated_cred_struct gaa_unevaluated_cred,
*gaa_unevaluated_cred;
struct gaa_unevaluated_cred_struct {
gaa_cred_type cred_type;
gaa_security_attribute_list_ptr grantor;
gaa_security_attribute_list_ptr grantee;
gaa_buffer_ptr mech_spec_cred;
void (*cred_verification)(gaa_sec_context_ptr, va_list ap);
gaa_unevaluated_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_access_rights_set_ptr granted_access_rights;
gaa_security_attribute_list_ptr conditions;
gaa_security_attribute_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_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(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* attrbt_list_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
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
(int* minor_status, /* OUT */
gaa_sec_context_ptr sec_context, /* IN&OUT */
gaa_acl_list_ptr attrbt_list_handle, /* IN */
gaa_tag_vector_list_ptr check_access_rights, /* IN */
gaa_security_attribute_list_ptr gaa_options /* IN, OPTIONAL */
gaa_answer_struct_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
(int* minor_status, /* OUT */
gaa_sec_context_ptr sec_context, /* IN&OUT */
gaa_acl_list_ptr attrbt_list_handle, /* IN */
);
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_BUFFER ((gaa_buffer_ptr) 0)
#define GAA_EMPTY_BUFFER {0, NULL}
#define GAA_NO_DATA ((gaa_data_ptr)0)
#define GAA_SEC_ATTRBTS_UNBOUND ((gaa_security_attribute_list_ptr_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. 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
| PAFTECH AB 2003-2026 | 2026-04-23 06:03:59 |