idnits 2.17.1 draft-ietf-cat-gaa-cbind-04.txt: ** The Abstract section seems to be numbered Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** Looks like you're using RFC 2026 boilerplate. This must be updated to follow RFC 3978/3979, as updated by RFC 4748. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- ** The document is more than 15 pages and seems to lack a Table of Contents. == No 'Intended status' indicated for this document; assuming Proposed Standard == The page length should not exceed 58 lines per page, but there was 1 longer page, the longest (page 1) being 1713 lines Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack an Introduction section. ** The document seems to lack a Security Considerations section. ** The document seems to lack an IANA Considerations section. (See Section 2.2 of https://www.ietf.org/id-info/checklist for how to handle the case when there are no actions for IANA.) ** There are 68 instances of weird spacing in the document. Is it really formatted ragged-right, rather than justified? ** There are 190 instances of too long lines in the document, the longest one being 15 characters in excess of 72. ** There is 1 instance of lines with control characters in the document. ** The document seems to lack a both a reference to RFC 2119 and the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. RFC 2119 keyword, line 1090: '...r arglist /* IN & OUT, OPTIONAL */);...' RFC 2119 keyword, line 1119: '...ptr arglist /* IN & OUT, OPTIONAL */);...' RFC 2119 keyword, line 1207: '... gaa_options, /* IN, OPTIONAL */...' Miscellaneous warnings: ---------------------------------------------------------------------------- == Line 98 has weird spacing: '...hod_ptr metho...' == Line 154 has weird spacing: '...to| int type...' == Line 201 has weird spacing: '...er only to th...' == Line 393 has weird spacing: '..._struct gaa,...' == Line 400 has weird spacing: '...hod_ptr metho...' == (63 more instances...) -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (July 11, 2000) is 8691 days in the past. Is this intentional? -- Found something which looks like a code comment -- if you have code sections in the document, please surround them with '' and '' lines. Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) -- Missing reference section? '3' on line 1661 looks like a reference -- Missing reference section? '1' on line 1655 looks like a reference -- Missing reference section? '2' on line 1658 looks like a reference -- Missing reference section? '4' on line 1664 looks like a reference Summary: 10 errors (**), 0 flaws (~~), 8 warnings (==), 7 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 1 INTERNET-DRAFT Tatyana Ryutov 2 CAT Working Group Clifford Neuman 3 Expires January 2001 USC/Information Sciences Institute 4 draft-ietf-cat-gaa-cbind-04.txt July 11, 2000 6 Generic Authorization and Access control Application Program Interface 7 C-bindings 9 0. Status Of this Document 11 This document is an Internet-Draft and is in full conformance 12 with all provisions of Section 10 of RFC2026. 14 Internet-Drafts are working documents of the Internet Engineering 15 Task Force (IETF), its areas, and its working groups. Note that 16 other groups may also distribute working documents as Internet-Drafts. 18 Internet-Drafts are draft documents valid for a maximum of six 19 months and may be updated, replaced, or obsoleted by other 20 documents at any time. It is inappropriate to use Internet-Drafts 21 as reference material or to cite them other than as 22 "work in progress." 24 The list of current Internet-Drafts can be accessed at 25 http://www.ietf.org/ietf/1id-abstracts.txt 27 The list of Internet-Draft Shadow Directories can be accessed at 28 http://www.ietf.org/shadow.html. 30 To view the entire list of current Internet-Drafts, please check 31 the "1id-abstracts.txt" listing contained in the Internet-Drafts 32 Shadow Directories on ftp.is.co.za (Africa), ftp.nordu.net 33 (Northern Europe), ftp.nis.garr.it (Southern Europe), munnari.oz.au 34 (Pacific Rim), ftp.ietf.org (US East Coast), or ftp.isi.edu 35 (US West Coast). 37 1. Abstract 39 The Generic Authorization and Access control Application Programming 40 Interface (GAA-API) provides access control services to calling 41 applications. 42 It facilitates access control decisions for applications and allows 43 applications to discover access control policies associated with a 44 targeted resource. The GAA-API is usable by multiple applications 45 supporting different kinds of protected objects. 46 The GAA-API design supports: 48 - a variety of security mechanisms based on public or secret key 49 cryptosystems 50 - different authorization models 51 - heterogeneous security policies 52 - various access rights 54 This document specifies C language bindings for the GAA-API, which 55 is described at a language-independent conceptual level in 56 draft-ietf-cat-acc-cntrl-frmw-04.txt 58 2. Design approach 60 We propose a pseudo-object-oriented approach inspired by the programming 61 style used in [3]. 62 This approach provides an organized representation of the GAA-API concepts and 63 entities. It defines an encapsulating interface for mapping of particular 64 GAA-API implementation to the standardized GAA-API entities. 65 Objects are represented as pointers to pseudo-class structures. 66 Throughout this draft we use term "class" to refer to a pseudo-class, which is 67 implemented using C structures and imitate object-oriented design. 69 2.1. The abstract class 71 The abstract class describes concepts common across class implementations, 72 including object creation, initialization, deletion, methods and 73 attributes. 74 Concrete class instances define data for attributes and code for class's methods. 75 We define three abstract classes: gaa, gaa_policy and gaa_sc. 76 The general structure of each abstract class is depicted in Figure 1. 78 2.1.1. The abstract class data structure 80 The abstract class data structure contains the following fields: 82 abstract_class_method 83 The abstract_class_method is a pointer to the abstract_class_method data structure. 84 This field is present in each GAA-API class. 86 abstract class attributes 87 The abstract class attributes represent a set of data variables, which are 88 elaborated by the specific instances of a GAA-API class. 90 abstract_class_new(abstract_class_method_ptr method, 91 abstract_class_ptr *class, 92 gaa_handle_ptr arglist) 94 The abstract_class_new method creates a new class. Implementation-dependent 95 information for class creation is supplied using arglist parameter. This method 96 is present in each GAA-API class. 98 abstract_class_set(abstract_class_method_ptr method, 99 abstract_class_ptr class, 100 gaa_handle_ptr arglist) 102 The abstract_class_set initializes appropriate fields of the abstract_class_method 103 structure (attributes and methods). 104 Implementation-dependent information needed to appropriately initialize the 105 class values is supplied using arglist parameter. This method is present in 106 each GAA-API class. 108 abstract_class_free(abstract_class_ptr class, 109 gaa_handle_ptr arglist) 111 The abstract_class_free frees the class structure. Depending on the configuration, 112 this will free the underlying data object. This method is present in each GAA-API 113 class. 115 abstract class methods 116 The abstract class methods are handles to the respective C functions, which 117 implement the remaining class methods. Some of the handles can be NULL if not 118 implemented. The abstract class methods differ across GAA-API classes. 120 2.1.2. The abstract class method data structure 122 The abstract class method structure contains the following fields: 124 type 125 The type is the numeric type of the abstract class method. This field is present in 126 each GAA-API class. 128 name 129 The name is a textual representation of the abstract class method of type "type". 130 This field is present in each GAA-API class. 132 abstract class method attributes 133 The abstract class method attributes are handles to the respective C functions, 134 which implement the remaining methods of the abstract class method data structure. 135 Some of the handles can be NULL if not implemented. The abstract class methods 136 differ across GAA-API class method data structures. 138 create() 139 The create method creates a new instance of class method structure of type "type". 140 This method is present in each GAA-API class method data structure. 142 destroy() 143 The destroy frees class method structure of type "type". This method is present in 144 each GAA-API class method data structure. 146 The abstract class method methods are handles to the respective C functions, which 147 implement the methods. Some of them can be NULL if not implemented. 149 ------------------------------------------------------- ----------------------- 150 | abstract class | |abstract class method| 151 | (gaa, gaa_policy and gaa_sc) | |---------------------| 152 |-----------------------------------------------------| | attributes | 153 | attributes | | | 154 | |points to| int type | 155 |abstract_class_method *method ----------------------|-------->| char *name | 156 | abstract class attributes | | abstract class | 157 |-----------------------------------------------------| | method attributes | 158 | methods | |---------------------| 159 | | | methods | 160 |abstract_class_new(abstract_class_method_ptr method, | | | 161 | abstract_class_ptr *class, | | create() | 162 | gaa_handle_ptr arglist)| | destroy() | 163 | | | | 164 |abstract_class_set(abstract_class_method_ptr method, | |abstract class method| 165 | abstract_class_ptr class, | |methods | 166 | gaa_handle_ptr arglist)| -------^-------------- 167 | | || 168 |abstract_class_free(abstract_class_ptr class, | || maps to 169 | gaa_handle_ptr arglist) | || 170 | | || 171 | abstract class methods | || 172 ------------------------------------------------------- || 173 ----------------------------------||- 174 | concrete class method | 175 |-----------------------------------| 176 | attributes | 177 | | 178 | type = concrete_type | 179 | name = concrete_name | 180 | | 181 | concrete class attributes | 182 |-----------------------------------| 183 | methods | 184 | | 185 | concrete_create() | 186 | concrete_destroy() | 187 | | 188 | concrete class methods | 189 ------------------------------------ 191 Figure 1. 193 2.2. Concrete class method 195 The concrete class method contains concrete values for the abstract 196 class method attributes and methods, which are initialized by the 197 abstract_class_set function. 199 3. The GAA-API data types and calling conventions 201 The data types described in this specification refer only to the fields 202 that must be provided by all conforming GAA-API implementations. Individual 203 implementations may provide additional fields for internal use within the 204 GAA-API routines. 206 3.1. Opaque data 208 Some data items are considered opaque to the GAA-API, because their 209 internal data structure has no significance to the GAA-API or the calling 210 application, e.g. actual mechanism-specific credentials. 212 3.1.1. Byte buffer 214 This type of data is passed between the GAA-API and the caller using 215 a byte buffer referenced by the gaa_buffer_ptr data type, which is a 216 pointer to a gaa_buffer structure. 218 The gaa_buffer type is a buffer descriptor containing the following fields: 220 length 221 The length contains the total number of bytes that the data occupies. 223 value 224 The value contains a pointer to the actual data. 226 typedef struct gaa_buffer_struct gaa_buffer, 227 *gaa_buffer_ptr, 228 gaa_options, 229 *gaa_options_ptr; 231 struct gaa_buffer_struct { 232 size_t length; 233 void *value; 234 }; 236 3.1.2. Implementation-specific data 238 A number of GAA-API routines need to receive implementation-specific 239 arguments and return implementation-specific values. 240 The structure of the passed and returned information varies for different 241 implementations, which makes it difficult to standardize the structure. 242 Data of this type may be regarded as an opaque handle to the 243 implementation-specific data structure and are passed between the GAA-API 244 and caller using the gaa_handle_ptr data structure. 246 unsigned long gaa_handle_ptr 248 Allocation, release and maintenance routines of the underling structure 249 are GAA-API implementation-specific and are not defined in this specification. 251 3.2. Character data 253 Certain data items used by the GAA-API may be regarded as a character 254 strings, e.g., string-encoded tokens for passing object and authorization 255 database identifiers. The data of this kind is passed between the GAA-API and 256 caller using the gaa_string_data data type, which is a pointer to 257 '\0' terminated C character array: 259 typedef char *gaa_string_data; 261 3.3. Ordered list data 263 Certain data items used by the GAA-API may be regarded as an ordered list of 264 data items, e.g., a list of identity credentials. Data of this type are passed 265 between the GAA-API and a caller using the gaa_list_ptr data structure. 267 unsigned long gaa_list_ptr 269 List allocation, release and maintenance routines are GAA-API implementation 270 specific and are not defined in this specification. 271 A possible candidate for implementation of this data type can be STACK 272 structure defined in [3]. 274 3.4. The GAA-API constants 276 The following constants are used in GAA-API calls and structures: 278 GAA_C_YES 0 (indicates authorization) is returned if all 279 requested operations are authorized. 281 GAA_C_NO 1 (indicates denial of authorization) is returned 282 if at least one operation is not authorized. 284 GAA_C_MAYBE 2 (indicates a need for additional checks) is 285 returned if there are some unevaluated conditions 286 and additional application specific checks are needed, 287 or continuous evaluation is required. 289 3.5. The GAA-API flags 291 Flags are 32 bits. 293 Condition flags: 295 COND_FLG_EVALUATED 0x01 condition has been evaluated 296 COND_FLG_MET 0x10 condition has been met 297 COND_FLG_ENFORCE 0x100 condition has to be enforced 299 3.6. Status codes 301 The GAA-API routines return a status code of type gaa_status. 303 unsigned long gaa_status 305 Encapsulated in the returned status code are major and minor status codes. 306 Each of them has a value range equivalent to 16 bit unsigned integer values. 307 The major codes indicate errors that are independent of the underlying mechanisms. 308 The errors that can be indicated via a GAA-API major status code are generic API 309 routine errors (errors that are defined in this specification). 311 The minor code is implementation-dependent and is used to indicate specialized 312 errors from the underlying mechanisms or provide additional information about 313 the GAA-API errors. 315 GAA_S_SUCCESS 0 Successful completion. 317 GAA_S_FAILURE 3 The underlying mechanism detected an 318 error for which no specific GAA-API 319 status code is defined. The minor code 320 provides details about the error. 322 GAA_S_INVALID_LIST_HNDL 4 The handle supplied does not point to a 323 valid gaa_list structure. 325 GAA_S_INVALID_GAA_HNDL 5 The handle supplied does not point to a 326 valid gaa structure. 328 GAA_S_INVALID_GAA_METHOD_HNDL 6 The handle supplied does not point to a 329 valid gaa_method structure. 331 GAA_S_INVALID_ANSWER_HNDL 7 The handle supplied does not point to a 332 valid gaa_answer structure. 334 GAA_S_INVALID_POLICY_HNDL 10 The handle supplied does not point to a 335 valid gaa_policy structure. 337 GAA_S_INVALID_POLICY_METHOD_HNDL 11 The handle supplied does not point to a 338 valid gaa_policy_method structure. 340 GAA_S_INVALID_SC_HNDL 12 The handle supplied does not point to a 341 valid gaa_sc structure. 343 GAA_S_INVALID_SC_METHOD_HNDL 13 The handle supplied does not point to a 344 valid gaa_sc_method structure. 346 GAA_S_INVALID_POLICY_ENTRY_HNDL 15 The handle supplied does not point to a 347 valid gaa_policy_entry structure 349 GAA_S_INVALID_CONDITION_HNDL 16 The handle supplied does not point to a 350 valid gaa_condition structure. 352 GAA_S_INVALID_RIGHT_HNDL 17 The handle supplied does not point to a 353 valid gaa_right structure. 355 GAA_S_INVALID_STRING_DATA_HNDL 18 The handle supplied does not point to a 356 valid gaa_string_data structure. 358 GAA_S_INVALID_OPTIONS_HNDL 19 The handle supplied does not point to a 359 valid gaa_options structure. 361 GAA_S_INVALID_BUFFER_HNDL 20 The handle supplied does not point to a 362 valid gaa_buffer structure. 364 GAA_S_INVALID_ATTRIBUTE_HNDL 21 The handle supplied does not point to a 365 valid gaa_attribute structure. 367 GAA_S_INVALID_AUTHR_CRED_HNDL 22 The handle supplied does not point to a 368 valid gaa_authr_cred structure. 370 GAA_S_INVALID_UNEVAL_CRED_HNDL 23 The handle supplied does not point to a 371 valid gaa_uneval_cred structure. 373 GAA_S_UNIMPLEMENTED_FUNCTION 24 The function is not supported by 374 underlying implementation. 376 GAA_S_NO_MATCHING_ENTRIES 25 No matching policy entries have been 377 found for the requested right. 379 GAA_S_POLICY_PARSING_FAILURE 26 Indicates an error during policy 380 parsing. 382 GAA_S_POLICY_RETRIEVING_FAILURE 27 Indicates an error during policy 383 retrieval process. 385 3.7. GAA-API data structures 387 3.7.1. gaa_struct data structure 389 The gaa_struct structure implements the gaa abstract class. 390 See section 2 for explanation of the meaning of the fields 391 method, gaa_new, gaa_set and gaa_free. 393 typedef struct gaa_struct gaa, 394 *gaa_ptr; 396 struct gaa_struct 397 { 398 /* attributes */ 400 gaa_method_ptr method; 402 /* methods */ 404 gaa_status (*gaa_new)(gaa_method_ptr method, 405 gaa_ptr *gaa, 406 gaa_handle_ptr arglist); 408 gaa_status (*gaa_set)(gaa_method_ptr method, 409 gaa_ptr gaa, 410 gaa_handle_ptr arglist); 412 gaa_status (*gaa_free)(gaa_ptr gaa, 413 gaa_handle_ptr arglist); 414 }; 416 3.7.2. gaa_method_struct data structure 418 The gaa_method_struct structure implements the gaa abstract class method. 419 The structure contains information about behavior of the GAA_API evaluation 420 routines. 422 The gaa_method_struct structure contains the following fields: 424 condition_evaluation 425 The condition_evaluation is a handle to an application-specific condition 426 evaluation function provided by the calling application. The function is 427 called by GAA-API if there are application-specific conditions. Generic 428 (understood by the GAA-API) conditions are evaluated by the GAA-API internal 429 functions. 431 calculate_validity_time 432 The calculate_validity_time is a handle to an implementation-specific function 433 provided by the calling application. The function is called by the GAA-API to 434 set the authorization validity time period in the gaa_answer data structure, see 435 section 3.8. 437 See section 2 for explanation of the meaning of the fields type, 438 name, create and destroy. 440 typedef struct gaa_method_struct gaa_method, 441 *gaa_method_ptr; 443 struct gaa_method_struct 444 { 445 /* attributes */ 447 int type; 448 char *name; 450 /* methods */ 452 gaa_status (*condition_evaluation)(); 453 gaa_status (*calculate_validity_time)(); 454 gaa_status (*create)(); 455 gaa_status (*destroy)(); 456 }; 458 3.7.3. gaa_policy_struct data structure 460 The gaa_struct structure implements the gaa_policy abstract class. 461 The gaa_policy_struct structure contains the following fields: 463 policy 464 The policy is a pointer to the byte buffer, containing the authorization policy 465 in application-specific format. 467 matching_entries 468 The matching_entries is a pointer to an ordered list of elements of type 469 gaa_policy_entry_ptr returned by the get_matching_entries function, see next 470 section. 472 See section 2 for explanation of the meaning of the fields 473 method, gaa_policy_new, gaa_policy_set and gaa_policy_free. 475 typedef struct gaa_policy_struct gaa_policy, 476 *gaa_policy_ptr; 478 struct gaa_policy_struct 479 { 480 /* attributes */ 482 gaa_policy_method_ptr method; 483 gaa_buffer_ptr policy; 484 gaa_list_ptr /* gaa_policy_entry_ptr */ matching_entries; 486 /* methods */ 488 gaa_status (*gaa_policy_new)(gaa_policy_method_ptr method, 489 gaa_policy_ptr *policy, 490 gaa_handle_ptr arglist); 492 gaa_status (*gaa_policy_set)(gaa_policy_method_ptr method, 493 gaa_policy_ptr policy, 494 gaa_handle_ptr arglist); 496 gaa_status (*gaa_policy_free)(gaa_policy_ptr policy, 497 gaa_handle_ptr arglist); 499 }; 501 3.7.4. gaa_policy_method_struct data structure 503 The gaa_policy_method_struct structure implements the gaa_policy abstract 504 class method. The gaa_policy_method_struct structure contains the following 505 fields: 507 eval 508 The eval specifies a policy evaluation approach: based on the order, based on 509 priority or unordered. The default value is the ordered policy evaluation. 511 get_matching_entries 512 The get_matching_entries is a handle to an application-specific function for 513 retrieval of the matching entries. The function looks through the policy in 514 application-specific format and finds policies associated with the requested_right. 515 Then these right-specific policies are translated to the gaa_policy_entry_ptr 516 and as the result, the function returns an ordered list of elements of type 517 gaa_policy_entry_ptr (see section 3.7.5.), which are then evaluated by the GAA_API 518 routines. 520 Return value: 522 GAA_S_SUCCESS 523 GAA_S_INVALID_POLICY_HNDL 524 GAA_S_NO_MATCHING_ENTRIES 526 retrieve 527 The retrieve is a handle to an application-specific function for the retrieval of 528 the object authorization policy. The application maintains authorization 529 information in a form understood by the application. It can be stored in a file, 530 database, directory service or in some other way. The upcall function provided for 531 the GAA-API retrieves this information. 533 Return value: 535 GAA_S_SUCCES 536 GAA_S_FAILURE 537 GAA_S_POLICY_RETRIEVING_FAILURE 538 GAA_S_POLICY_PARSING_FAILURE 540 See section 2 for explanation of the meaning of the fields: type, 541 name, create and destroy. 543 typedef enum { 544 GAA_ORDERED_EVAL , 545 GAA_PRIORITY_EVAL , 546 GAA_UNORDERED_EVAL 547 } gaa_eval_type; 549 typedef struct gaa_policy_method_struct gaa_policy_method, 550 *gaa_policy_method_ptr; 552 struct gaa_policy_method_struct 553 { 554 /* attributes */ 556 int type; 557 char *name; 558 gaa_eval_type eval; 560 /* methods */ 562 gaa_status (*get_matching_entries)(gaa_buffer_ptr policy, /* IN */ 563 gaa_right_ptr requested_right, /* IN */ 564 gaa_list_ptr *matching_entries /* OUT */); 566 gaa_status (*retrieve)(gaa_string_data object, /* IN */ 567 gaa_string_data policy_db, /* IN */ 568 gaa_buffer_ptr *buffer, ... ); /* OUT */ 570 gaa_status (*create)(); 571 gaa_status (*destroy)(); 572 }; 574 3.7.5. gaa_policy_entry_struct data structure 576 The gaa_policy_entry_struct structure contains the following fields: 578 num 579 The num indicates entry number in the policy. It is used by the GAA_API 580 evaluation routines. 582 priority 583 The priority specifies the priority of this entry. It is used by the GAA_API 584 evaluation routines. 586 rights 587 The rights is pointer to a linked list of elements of the type gaa_right_ptr. 588 Each element indicates granted or denied access rights. 590 typedef struct gaa_policy_entry_struct gaa_policy_entry, 591 *gaa_policy_entry_ptr; 593 struct gaa_policy_entry_struct { 594 int num; 595 int priority; 596 gaa_list_ptr /* gaa_right_ptr */ rights; 597 }; 599 3.7.6. gaa_right_struct data structure 601 The gaa_right_struct structure contains the following fields: 603 type 604 The type defines the type of the token. 606 authority 607 The authority indicates the authority responsible for defining the 608 value within the token type. 610 value 611 The value indicates the value of the token. The name space for the 612 value is defined by the authority field. 614 conditions 615 The conditions is a pointer to an ordered list of elements of type gaa_condition_ptr. 616 It contains a list of pointers to conditions associated with the right. 618 typedef struct gaa_right_struct gaa_right, 619 *gaa_right_ptr; 620 struct gaa_right_struct { 621 gaa_string_data type; 622 gaa_string_data authority; 623 gaa_string_data value; 624 gaa_list_ptr /* gaa_condition_ptr */ conditions; 625 }; 627 3.7.7. gaa_condition_struct data structure 629 The gaa_condition_struct structure contains the following fields: 631 type 632 The type defines the type of the token. 634 authority 635 The authority indicates the authority responsible for defining the 636 value within the token type. 638 value 639 The value indicates the value of the token. The name space for the 640 value is defined by the authority field. 642 conditions 643 The condition is a pointer to an ordered list of elements of type gaa_condition_ptr. 644 It contains a list of pointers to conditions associated with the right. 646 status 647 The status contains flags, indicating if the condition evaluation status. 649 typedef struct gaa_condition_struct gaa_condition, 650 *gaa_condition_ptr; 652 struct gaa_condition_struct { 653 gaa_string_data type; 654 gaa_string_data authority; 655 gaa_string_data value; 656 unsigned long status; 657 }; 659 3.7.8. gaa_sec_attrb_struct data structure 661 The gaa_sec_attrb_struct structure contains the following fields: 663 type 664 The type defines the type of the token. 666 authority 667 The authority indicates the authority responsible for defining the 668 value within the token type. 670 value 671 The value indicates the value of the token. The name space for the 672 value is defined by the authority field. 674 struct gaa_sec_attrb_struct { 675 gaa_string_data type; 676 gaa_string_data authority; 677 gaa_string_data value; 678 }; 680 3.7.9. GAA-API Security Context data structures 682 The gaa_sc_struct structure implements the gaa_sc abstract class, which 683 stores information relevant to access control. 685 3.7.9.1. gaa_sc_struct data structure 687 The gaa_sc_struct structure contains the following fields: 689 sc 690 The sc is a pointer to a byte buffer, containing the mechanism-specific 691 security context structure. 693 identity_cred 694 The identity_cred is a pointer to an ordered list of elements of the type 695 gaa_identity_cred_ptr, containing principal's identity credentials. It is 696 returned by the get_identity_cred function, see next section. 698 authr_cred 699 The authr_cred is a pointer to an ordered list of elements of the 700 type gaa_authr_cred_ptr, containing principal's authorization credentials. 701 It is returned by the get_authr_cred function, see next section. 703 group_membership 704 The group_membership is a pointer to an ordered list of elements of the 705 type gaa_identity_cred_ptr, which specifies that the grantee is a member of 706 only the listed groups. It is returned by the get_group_membership_cred function, 707 see next section. 709 group_non_membership 710 The group_non_membership is a pointer to an ordered list of elements of 711 the type gaa_identity_cred_ptr, which specifies that the grantee is NOT a 712 member of the listed groups. It is returned by the get_group_non_membership_cred 713 function, see next section. 715 attributes 716 The attributes is a pointer to an ordered list of elements of the type 717 gaa_attribute_ptr, which contains miscellaneous attributes attached to 718 the grantee, e.g., age or security clearance. 720 uneval_cred 721 The uneval_cred is a pointer to an ordered list of elements of type 722 gaa_uneval_cred_ptr, containing unevaluated credentials of different types. 723 It is returned by the get_uneval_cred function, see next section. 725 connection_state 726 The connection_state is a pointer to a byte buffer, containing a 727 mechanism-specific representation of per-connection context, some of the 728 data stored here include keyblocks and addresses. 730 See section 2 for explanation of the meaning of the fields 731 method, gaa_sc_new, gaa_sc_set and gaa_sc_free. 733 typedef struct gaa_sc_struct gaa_sc, 734 *gaa_sc_ptr; 735 struct gaa_sc_struct 736 { 737 /* attributes */ 739 gaa_sc_method_ptr method; 740 gaa_buffer_ptr sc; 742 gaa_list_ptr /* gaa_identity_cred_ptr */ identity_cred; 743 gaa_list_ptr /* gaa_authr_cred_ptr */ authr_cred; 744 gaa_list_ptr /* gaa_identity_cred_ptr */ group_membership_cred; 745 gaa_list_ptr /* gaa_identity_cred_ptr */ group_non_membership_cred; 746 gaa_list_ptr /* gaa_attribute_ptr */ attributes; 747 gaa_list_ptr /* gaa_uneval_cred_ptr */ uneval_cred; 749 gaa_buffer_ptr connection_state; 751 /* methods */ 753 gaa_status (*gaa_sc_new)(gaa_sc_method_ptr method, 754 gaa_sc_ptr *sc, 755 gaa_handle_ptr arglist); 757 gaa_status (*gaa_sc_set)(gaa_sc_method_ptr method, 758 gaa_sc_ptr sc, 759 gaa_handle_ptr arglist); 761 gaa_status (*gaa_sc_free)(gaa_sc_ptr sc, 762 gaa_handle_ptr arglist); 763 }; 765 3.7.9.2. gaa_sc_method_struct data structure 767 The gaa_sc_method_struct structure implements the gaa_sc abstract class method. 768 The gaa_sc_method_struct structure contains the following fields: 770 get_identity_cred 771 The get_identity_cred is a handle to an application-specific function, which 772 translates mechanism-specific credentials to the GAA_API internal structure. 773 It returns an ordered list of elements of type gaa_identity_cred_ptr 774 see section 3.7.9.3, can be NULL if not implemented. 776 get_authr_cred 777 The get_authr_cred is a handle to an application-specific function, which 778 translates mechanism-specific credentials to the GAA_API internal structure. 779 It returns an ordered list of elements of type gaa_authr_cred_ptr see 780 section 3.7.9.4, can be NULL if not implemented. 782 get_group_membership_cred 783 The get_group_membership_cred is a handle to an application-specific function, 784 which translates mechanism-specific credentials to the GAA-API internal structure. 785 It returns an ordered list of elements of type gaa_identity_cred_ptr see 786 section 3.7.9.3, can be NULL if not implemented. 788 get_group_non_membership_cred 789 The get_group_non_membership_cred is a handle to an application-specific 790 function, which translates mechanism-specific credentials to the GAA API 791 internal structure. It returns an ordered list of elements of type 792 gaa_identity_cred_ptr see section 3.7.9.3, can be NULL if not implemented. 794 get_attributes 795 The get_attributes is a handle to an application-specific function, which 796 translates mechanism-specific credentials to the GAA API internal structure. 797 It returns an ordered list of elements of type gaa_attribute_ptr see 798 section 3.7.9.5, can be NULL if not implemented. 800 get_uneval_cred 801 The get_uneval_cred is a handle to an application-specific function, which 802 translates mechanism-specific credentials to the GAA-API internal structure. 803 It returns an ordered list of objects of type gaa_uneval_cred_ptr see 804 section 3.7.9.6, can be NULL if not implemented. 806 pull_cred 807 The pull_cred is a handle to an application-specific function, which is called 808 when additional credentials are required. It obtains the necessary credentials and 809 then cred_evaluate function is invoked. This process can be recursive. 811 cred_evaluate 812 The cred_evaluate is a handle to an application-specific function, which parses 813 the contents of the acquired credentials into the GAA-API internal form and 814 evaluate them. 816 See section 2 for explanation of the meaning of the fields type, 817 name, create and destroy. 819 typedef struct gaa_sc_method_struct gaa_sc_method, 820 *gaa_sc_method_ptr; 822 struct gaa_sc_method_struct 823 { 824 /* attributes */ 826 int type; 827 char *name; 829 /* methods */ 831 gaa_list_ptr /* gaa_identity_cred_ptr */ 832 (*get_identity_cred)(); 833 gaa_list_ptr /* gaa_authr_cred_ptr */ 834 (*get_authr_cred)(); 835 gaa_list_ptr /* gaa_identity_cred_ptr */ 836 (*get_group_membership_cred)(); 837 gaa_list_ptr /* gaa_identity_cred_ptr */ 838 (*get_group_non_membership_cred)(); 839 gaa_list_ptr /* gaa_attribute_ptr */ 840 (*get_attributes)(); 841 gaa_list_ptr /* gaa_uneval_cred_ptr */ 842 (*get_uneval_cred)(); 844 void 845 (*condition_evaluation)(); 847 void 848 (*pull_cred)(); 850 void 851 (*cred_evaluate)(); 853 gaa_status (*create)(); 854 gaa_status (*destroy)(); 855 }; 857 3.7.9.3. gaa_identity_cred_struct data structure 859 The gaa_identity_cred_struct structure is composed of a set of identity 860 credentials. 861 Credentials identify the principal on whose behalf the request is performed. 862 Identity credentials describe a set of mechanism-specific principals, and 863 give their holder the ability to act as any of those principals. Each of 864 the identity credentials contains information needed to authenticate a single 865 principal. 867 The gaa_identity_cred_struct structure contains the following fields: 869 principal 870 The principal identifies an entity on whose behalf the request is performed. 872 grantor 873 The grantor identifies an entity who issued the credential. 875 conditions 876 The conditions is pointer to an ordered list of elements of the type 877 gaa_condition_ptr, which lists restrictions placed on the identity, 878 e.g., validity time periods. 880 mech_spec_cred 881 The mech_spec_cred is a handle to the actual mechanism-specific identity 882 credential. 884 typedef struct gaa_identity_cred_struct gaa_identity_cred, 885 *gaa_identity_cred_ptr; 887 struct gaa_identity_cred_struct { 888 gaa_sec_attrb_ptr grantor; 889 gaa_sec_attrb_ptr principal; 890 gaa_list_ptr /* gaa_condition_ptr */ conditions; 891 gaa_buffer_ptr mech_spec_cred; 892 }; 894 3.7.9.4. gaa_authr_cred_struct data structure 896 The gaa_authr_cred_struct structure contains the following fields: 898 grantee 899 The grantee identifies an entity for whom the credential was issued. 901 grantor 902 The grantor identifies an entity who issued the credential. 904 objects 905 The object is a pointer to a byte buffer, containing a list of object 906 references to the application-level objects accessible by the 907 grantee, e.g. files or hosts. Object references are from the 908 application-specific name space. 910 access_rights 911 The access_rights is pointer to a linked list of elements of the 912 type gaa_right_ptr. Each element indicate granted or denied access rights. 914 conditions 915 The conditions is a pointer to an ordered list of elements of the type 916 gaa_condition_ptr, which lists restrictions placed on the authorization 917 credential. 919 mech_spec_cred 920 The mech_spec_cred is a handle to the actual mechanism-specific authorization 921 credential. 923 typedef struct gaa_authr_cred_struct gaa_authr_cred, 924 *gaa_authr_cred_ptr; 926 struct gaa_authr_cred_struct{ 927 gaa_sec_attrb_ptr grantor; 928 gaa_sec_attrb_ptr grantee; 929 gaa_buffer objects; 930 gaa_list_ptr /* gaa_right_ptr */ access_rights; 931 gaa_buffer_ptr mech_spec_cred; 932 }; 934 3.7.9.5. gaa_attribute_struct data structure 936 The gaa_attribute_struct structure contains the following fields: 938 type 939 The type defines the type of the token. 941 authority 942 The authority indicates the authority responsible for defining the 943 value within the token type. 945 value 946 The value indicates the value of the token. The name space for the 947 value is defined by the authority field. 949 conditions 950 The conditions is a pointer to an ordered list of elements of the 951 type gaa_condition_ptr, containing pointers to conditions placed 952 on the attribute credential. 954 mech_spec_cred 955 Contains a handle to the actual mechanism specific attribute 956 credential 958 typedef struct gaa_attribute_struct gaa_attribute, 959 *gaa_attribute_ptr; 961 struct gaa_attribute_struct { 962 gaa_string_data type; 963 gaa_string_data authority; 964 gaa_string_data value; 965 gaa_list_ptr /* gaa_condition_ptr */ conditions; 966 gaa_buffer_ptr mech_spec_cred; 967 }; 969 3.7.9.6. gaa_uneval_cred_struct data structure 971 Evaluation of the acquired credentials can be deferred till the 972 credential is actually needed. Unevaluated credentials are stored in 973 the gaa_uneval_cred_struct data structure. 975 The gaa_uneval_cred_struct structure contains the following 976 fields: 978 cred_type 979 Specifies credential type: GAA_IDENTITY, GAA_GROUP_MEMB, 980 GAA_GROUP_NON_MEMB, GAA_AUTHORIZED, and GAA_ATTRIBUTES. 982 grantee 983 The grantee identifies an entity for whom the credential was issued. 985 grantor 986 The grantor identifies an entity who issued the credential. 988 mech_type 989 The mech_type specifies security mechanism used to obtain the credential. 991 mech_spec_cred 992 The mech_spec_cred is a handle to the actual mechanism-specific credential. 994 cred_verification 995 The cred_verification is a handle to an mechanism-specific credential 996 verification function. It is added to the gaa_uneval_cred structure 997 the by the calling application or transport. 999 typedef enum { 1000 GAA_IDENTITY , 1001 GAA_GROUP_MEMB , 1002 GAA_GROUP_NON_MEMB , 1003 GAA_AUTHORIZED , 1004 GAA_ATTRIBUTES 1005 } gaa_cred_type; 1007 typedef struct gaa_uneval_cred_struct gaa_uneval_cred, 1008 *gaa_uneval_cred; 1010 struct gaa_uneval_cred_struct { 1011 gaa_cred_type cred_type; 1012 gaa_sec_attrb_ptr grantor; 1013 gaa_sec_attrb_ptr grantee; 1014 gaa_string_data mech_type; 1015 gaa_buffer_ptr mech_spec_cred; 1016 void (*cred_verification )(); 1017 }; 1019 3.7.10. GAA-API answer data structure 1021 The gaa_check_authorization function returns various information to 1022 the application for further evaluation in the gaa_answer data 1023 structure. 1025 The gaa_answer_struct structure contains the following fields: 1027 valid_time 1028 The valid_time is a pointer to a structure of type gaa_time_period. 1029 It specifies the time period during which the authorization is granted 1030 and is returned as a condition to be checked by the application. 1032 rights 1033 The rights is a pointer to an ordered list of structures of the type 1034 gaa_right_ptr, which lists granted rights and corresponding 1035 conditions, if any. 1037 typedef struct gaa_time_period_struct gaa_time_period, 1038 *gaa_time_period_ptr; 1039 struct gaa_time_period_struct{ 1040 time_t start_time; /* NULL for unconstrained start time */ 1041 time_t end_time; /* NULL for unconstrained end time */ 1042 }; 1044 typedef struct gaa_answer_struct gaa_answer, 1045 *gaa_answer_ptr; 1047 struct gaa_answer_struct 1048 { 1049 gaa_time_period_ptr valid_time; 1050 gaa_list_ptr /* gaa_right_ptr */ rights; 1051 }; 1053 4. GAA-API routine descriptions 1055 This section describes each of the GAA-API routines and discusses 1056 their major parameters and how they are to be passed to the routines. 1058 4.1. gaa_initialize routine 1060 Purpose: 1061 The gaa_initialize must be called before any other GAA API function. 1062 It initializes the GAA API structures, defines behavior of the gaa evaluation 1063 routines. 1065 Parameters: 1067 method 1068 A handle to the implementation-specific gaa method structure, which 1069 implements concrete gaa class, see section 2. 1071 gaa 1072 A handle to the gaa structure. 1074 arglist 1075 A handle to an implementation-specific structure, containing 1076 initialization information. Can be used to return implementation-specific 1077 output information. 1079 Return value: 1080 GAA_S_SUCCESS 1081 GAA_S_FAILURE 1082 GAA_S_INVALID_GAA_HNDL 1083 GAA_S_INVALID_GAA_METHOD_HNDL 1085 Synopsis: 1087 gaa_status 1088 gaa_initialize(gaa_method_ptr method, /* IN */ 1089 gaa_ptr *gaa, /* OUT */ 1090 gaa_handle_ptr arglist /* IN & OUT, OPTIONAL */); 1092 4.2. gaa_cleanup routine 1094 Purpose: 1095 The gaa_cleanup cleans up internal GAA API structures allocated and initialized 1096 using the gaa_initialize function. The calling application should call gaa_cleanup 1097 to free memory and internal implementation state before exiting. 1099 Parameters: 1101 gaa 1102 A handle to a pointer the gaa structure. 1104 arglist 1105 A handle to an implementation-specific structure, containing 1106 clean up information. Can be used to return implementation-specific 1107 output information. 1109 Return value: 1111 GAA_SUCCESS 1112 GAA_FAILURE 1113 GAA_S_INVALID_GAA_HNDL 1115 Synopsis: 1117 gaa_status 1118 gaa_cleanup(gaa_ptr gaa, /* IN */ 1119 gaa_handle_ptr arglist /* IN & OUT, OPTIONAL */); 1121 4.3. gaa_get_object_policy_info routine 1123 Purpose: 1124 The gaa_get_object_policy_info function is called to obtain security 1125 policy information associated with the object. 1127 Parameters: 1129 object 1130 Reference to the object to be accessed. The identifier for the object 1131 is from an application-specific name space and is opaque to the 1132 GAA-API. 1134 policy_db 1135 Reference to an application-specific authorization database, containing 1136 access control information for the target object. 1138 policy_handle 1139 A pointer to a handle to gaa_policy structure, containing the security 1140 policy associated with the targeted object 1142 Return value: 1144 GAA_S_SUCCESS 1145 GAA_S_FAILURE 1146 GAA_S_INVALID_GAA_POLICY_HNDL 1147 GAA_S_INVALID_GAA_METHOD_HNDL 1148 GAA_S_UNIMPLEMENTED_FUNCTION 1149 GAA_S_INVALID_GAA_POLICY_HNDL 1150 GAA_S_INVALID_GAA_ANSWER_HNDL 1152 Synopsis: 1154 gaa_status 1155 gaa_get_object_policy_info(gaa_string_data object, /* IN */ 1156 gaa_string_data policy_db, /* IN */ 1157 gaa_policy_ptr policy_handle /* OUT */) 1159 4.4. gaa_check_authorization routine 1161 Purpose: 1162 The gaa_check_authorization function tells the application whether 1163 the requested access rights are authorized, or if additional 1164 application specific checks are required. 1166 Parameters: 1168 policy_handle 1169 A handle to the gaa_policy structure, returned by the 1170 gaa_get_object_policy_info routine. 1172 gaa 1173 A handle to the gaa structure. 1175 sc 1176 A handle to the principal's security context. 1178 check_access_rights 1179 Ordered list of access rights for authorization. 1181 gaa_options 1182 The optional argument, containing parameters for parameterized operation. 1184 detailed_answer 1185 Contains various information for further evaluation by the application. 1187 Return value: 1189 GAA_YES 1190 GAA_NO 1191 GAA_MAYBE 1192 GAA_S_FAILURE 1193 GAA_S_INVALID_ACCESS_RIGHTS_HNDL 1194 GAA_S_INVALID_GAA_POLICY_HNDL 1195 GAA_S_INVALID_GAA_ANSWER_HNDL 1196 GAA_S_INVALID_POLICY_METHOD_HNDL 1197 GAA_S_NO_MATCHING_ENTRIES 1198 GAA_S_UNIMPLEMENTED_FUNCTION 1200 Synopsis: 1202 gaa_status 1203 gaa_check_authorization 1204 (gaa_ptr gaa, /* IN&OUT */ 1205 gaa_sc_ptr sc, /* IN&OUT */ 1206 gaa_policy_ptr policy_handle, /* IN */ 1207 gaa_options_ptr gaa_options, /* IN, OPTIONAL */ 1208 gaa_list_ptr /* gaa_right_ptr */ check_access_rights /* IN */ 1209 gaa_answer_ptr *detailed_answer /* OUT */ 1210 ); 1212 4.5. gaa_inquire_object_policy_info routine 1214 Purpose: 1215 The gaa_inquire_object_policy_info routine allows calling application 1216 to discover a particular user's rights on an object. 1218 Parameters: 1220 gaa 1221 A handle to the gaa structure. 1223 sc 1224 A handle to the principal's security context. 1226 policy_handle 1227 A handle to the gaa_policy structure, returned by the 1228 gaa_get_object_policy_info routine. 1230 out_rights 1231 A handle to the ordered list of elements of type gaa_right_ptr, which 1232 contains list of rights that the principal is granted or denied. 1234 Return value: 1236 GAA_SUCCESS 1237 GAA_FAILURE 1238 GAA_S_SUCCESS 1239 GAA_S_FAILURE 1240 GAA_S_INVALID_ACCESS_RIGHTS_HNDL 1241 GAA_S_INVALID_GAA_POLICY_HNDL 1242 GAA_S_INVALID_GAA_ANSWER_HNDL 1243 GAA_S_INVALID_POLICY_METHOD_HNDL 1244 GAA_S_UNIMPLEMENTED_FUNCTION 1245 GAA_S_NO_MATCHING_ENTRIES 1247 Synopsis: 1249 gaa_status 1250 gaa_inquire_policy_info 1251 (gaa_ptr gaa, /* IN&OUT */ 1252 gaa_sc_ptr sc, /* IN&OUT */ 1253 gaa_policy_ptr policy_handle, /* IN */ 1254 gaa_list_ptr *out_rights /* OUT */); 1256 5. GAA-API support routines 1258 5.1. Allocation routines 1260 5.1.1. gaa_allocate_buffer routine 1262 Purpose: 1263 Allocate a gaa_buffer data structure and assign default values. 1265 Parameters: 1267 buffer 1268 Pointer to the allocated memory for gaa_buffer structure will be returned. 1270 Return value: 1272 GAA_S_SUCCESS 1273 GAA_S_FAILURE 1274 GAA_S_INVALID_BUFFER_HNDL 1276 Synopsis: 1278 gaa_status 1279 gaa_allocate_buffer(gaa_buffer_ptr *buffer /* OUT */); 1281 5.1.2. gaa_allocate_answer routine 1283 Purpose: 1284 Allocate a gaa_answer data structure and assign default values. 1286 Parameters: 1288 buffer 1289 A handle to the allocated memory for gaa_answer structure will be returned. 1291 Return value: 1293 GAA_S_SUCCESS 1294 GAA_S_FAILURE 1295 GAA_S_INVALID_ANSWER_HNDL 1297 Synopsis: 1299 gaa_status 1300 gaa_allocate_answer(gaa_answer_ptr *buffer /* OUT */); 1302 5.1.3. gaa_allocate_condition routine 1304 Purpose: 1305 Allocate a gaa_condition data structure and assign default values. 1307 Parameters: 1309 buffer 1310 A handle to the allocated memory for gaa_condition structure will be returned. 1312 Return value: 1314 GAA_S_SUCCESS 1315 GAA_S_FAILURE 1316 GAA_S_INVALID_CONDITION_HNDL 1318 Synopsis: 1320 gaa_status 1321 gaa_allocate_condition(gaa_condition_ptr *buffer /* OUT */); 1323 5.1.4. gaa_allocate_right routine 1325 Purpose: 1326 Allocate a gaa_right data structure and assign default values. 1328 Parameters: 1330 buffer 1331 A handle to the allocated memory for gaa_right structure will be returned. 1333 Return value: 1335 GAA_S_SUCCESS 1336 GAA_S_FAILURE 1337 GAA_S_INVALID_RIGHT_HNDL 1339 Synopsis: 1341 gaa_status 1342 gaa_allocate_right (gaa_right_ptr *buffer /* OUT */); 1344 5.1.5. gaa_allocate_sec_attrb routine 1346 Purpose: 1347 Allocate a gaa_sec_attrb data structure and assign default values. 1349 Parameters: 1351 buffer 1352 A handle to the allocated memory for gaa_sec_attrb structure will be returned. 1354 Return value: 1356 GAA_S_SUCCESS 1357 GAA_S_FAILURE 1358 GAA_S_INVALID_SEC_ATTRB_HNDL 1360 Synopsis: 1362 gaa_status 1363 gaa_allocate_sec_attrb (gaa_sec_attrb_ptr *buffer /* IN */); 1365 5.1.6. gaa_allocate_identity_cred routine 1367 Purpose: 1368 Allocate a gaa_identity_cred data structure and assign default values. 1370 Parameters: 1372 buffer 1373 A handle to the allocated memory for gaa_identity_cred structure will be returned. 1375 Return value: 1377 GAA_S_SUCCESS 1378 GAA_S_FAILURE 1379 GAA_S_INVALID_IDENTITY_CRED_HNDL 1381 Synopsis: 1383 gaa_status 1384 gaa_allocate_identity_cred(gaa_identity_cred_ptr *buffer /* OUT */); 1386 5.1.7. gaa_allocate_authr_cred routine 1388 Purpose: 1389 Allocate a gaa_authr_cred data structure and assign default values. 1391 Parameters: 1393 buffer 1394 A handle to the allocated memory for gaa_authr_cred structure will be returned. 1396 Return value: 1398 GAA_S_SUCCESS 1399 GAA_S_FAILURE 1400 GAA_S_INVALID_AUTHR_CRED_HNDL 1402 Synopsis: 1404 gaa_status 1405 gaa_allocate_authr_cred(gaa_authr_cred_ptr *buffer /* OUT */); 1407 5.1.8. gaa_allocate_uneval_cred routine 1409 Purpose: 1410 Allocate a gaa_uneval_cred data structure and assign default values. 1412 Parameters: 1414 buffer 1415 A handle to the allocated memory for gaa_uneval_cred structure will be returned. 1417 Return value: 1419 GAA_S_SUCCESS 1420 GAA_S_FAILURE 1421 GAA_S_INVALID_UNEVAL_CRED_HNDL 1423 Synopsis: 1425 gaa_status 1426 gaa_allocate_uneval_cred(gaa_uneval_cred_ptr *buffer /* OUT */); 1428 5.1.9. gaa_allocate_attribute routine 1430 Purpose: 1431 Allocate a gaa_attribute data structure and assign default values. 1433 Parameters: 1435 buffer 1436 A handle to the allocated memory for gaa_attribute structure will be returned. 1438 Return value: 1440 GAA_S_SUCCESS 1441 GAA_S_FAILURE 1442 GAA_S_INVALID_ATTRIBUTE_HNDL 1444 Synopsis: 1446 gaa_status 1447 gaa_allocate_attribute_cred(gaa_attribute_ptr *buffer /* OUT */); 1449 5.1.10. gaa_allocate_policy_entry routine 1451 Purpose: 1452 Allocate a gaa_policy_entry data structure and assign default values. 1454 Parameters: 1456 buffer 1457 A handle to the allocated memory for gaa_policy_entry structure will be 1458 returned. 1460 Return value: 1462 GAA_S_SUCCESS 1463 GAA_S_FAILURE 1464 GAA_S_INVALID_POLICY_ENTRY_HNDL 1466 Synopsis: 1468 gaa_status 1469 gaa_allocate_policy_entry(gaa_policy_entry_ptr *buffer /* OUT */); 1471 5.2. Release routines 1473 5.2.1. gaa_free_buffer routine 1475 Purpose: 1476 Free storage associated with a buffer. 1478 Parameters: 1480 buffer 1481 The storage associated with the buffer will be freed. 1483 Return value: 1484 none 1486 Synopsis: 1488 void 1489 gaa_free_buffer(gaa_answer_ptr buffer /* IN */); 1491 5.2.2. gaa_free_answer routine 1493 Purpose: 1494 Free storage associated with a buffer. 1496 Parameters: 1498 buffer 1499 The storage associated with the buffer will be freed. 1501 Return value: 1502 none 1504 Synopsis: 1506 void 1507 gaa_free_answer(gaa_answer_ptr buffer/* IN */); 1509 5.2.3. gaa_free_policy_entry routine 1511 Purpose: 1512 Free storage associated with a buffer. 1514 Parameters: 1516 buffer 1517 The storage associated with the buffer will be freed. 1519 Return value: 1520 none 1522 Synopsis: 1524 void 1525 gaa_free_policy_entry (gaa_policy_entry_ptr buffer/* IN */); 1527 5.2.4. gaa_free_identity_cred routine 1529 Purpose: 1530 Free storage associated with a buffer. 1532 Parameters: 1534 buffer 1535 The storage associated with the buffer will be freed. 1537 Return value: 1538 none 1540 Synopsis: 1542 void 1543 gaa_free_identity_cred(gaa_identity_cred_ptr buffer /* IN */); 1545 5.2.5. gaa_free_right routine 1547 Purpose: 1548 Free storage associated with a buffer. 1550 Parameters: 1552 buffer 1553 The storage associated with the buffer will be freed. 1555 Return value: 1556 none 1558 Synopsis: 1560 void 1561 gaa_free_right (gaa_right_ptr buffer /* IN */); 1563 5.2.6. gaa_free_condition routine 1565 Purpose: 1566 Free storage associated with a buffer. 1568 Parameters: 1570 buffer 1571 The storage associated with the buffer will be freed. 1573 Return value: 1574 none 1576 Synopsis: 1578 void 1579 gaa_free_condition(gaa_condition_ptr condition /* IN */); 1581 5.2.7. gaa_free_sec_attrb routine 1583 Purpose: 1584 Free storage associated with a buffer. 1586 Parameters: 1588 buffer 1589 The storage associated with the buffer will be freed. 1591 Return value: 1592 none 1594 Synopsis: 1596 void 1597 gaa_free_sec_attrb (gaa_sec_attrb_ptr buffer /* IN */); 1599 5.2.8. gaa_free_authr_cred routine 1601 Purpose: 1602 Free storage associated with a buffer. 1604 Parameters: 1606 buffer 1607 The storage associated with the buffer will be freed. 1609 Return value: 1610 none 1612 Synopsis: 1614 void 1615 gaa_free_authr_cred(gaa_authr_cred_ptr buffer /* IN */); 1617 5.2.9. gaa_free_uneval_cred routine 1619 Purpose: 1620 Free storage associated with a buffer. 1622 Parameters: 1624 buffer 1625 The storage associated with the buffer will be freed. 1627 Return value: 1628 none 1630 Synopsis: 1632 void 1633 gaa_free_uneval_cred (gaa_uneval_cred_ptr buffer /* IN */); 1635 5.2.10. gaa_free_attribute routine 1637 Purpose: 1638 Free storage associated with a buffer. 1640 Parameters: 1642 buffer 1643 The storage associated with the buffer will be freed. 1645 Return value: 1646 none 1648 Synopsis: 1650 void 1651 gaa_free_attribute(gaa_attribute_ptr buffer /* IN */); 1653 6. References 1655 [1] Linn, J., "Generic Security Service Application Program 1656 Interface", RFC 1508, Geer Zolot Associate, September 1993. 1658 [2] Wray, "Generic Security Service Application Program 1659 Interface V2 - C bindings", Internet draft, May 1997. 1661 [3] T J Hudson, E A Young 1662 SSLeay http://www.livjm.ac.uk/tools/ssleay/ 1664 [4] DASCOM Authorization API draft 1.0 1665 http://www.dascom.com 1667 7. Acknowledgments 1669 Carl Kesselman and Douglas Engert have contributed to discussion 1670 of the ideas and material in this specification. 1672 8. Authors' Addresses 1674 Tatyana Ryutov 1675 Clifford Neuman 1676 USC/Information Sciences Institute 1677 4676 Admiralty Way Suite 1001 1678 Marina del Rey, CA 90292-6695 1679 Phone: +1 310 822 1511 1680 E-Mail: {tryutov, bcn}@isi.edu