idnits 2.17.1 draft-ietf-cat-gaa-cbind-03.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 1154 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 20 instances of too long lines in the document, the longest one being 22 characters in excess of 72. ** 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 906: '... gaa_options, /* IN, OPTIONAL */...' Miscellaneous warnings: ---------------------------------------------------------------------------- == Line 93 has weird spacing: '..._method funct...' == Line 114 has weird spacing: '... | int type...' == Line 206 has weird spacing: '..._struct gaa,...' == Line 213 has weird spacing: '...hod_ptr metho...' == Line 221 has weird spacing: '...gaa_ptr gaa);...' == (34 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 (March 9, 2000) is 8804 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 1113 looks like a reference -- Missing reference section? '1' on line 1107 looks like a reference -- Missing reference section? '2' on line 1110 looks like a reference Summary: 8 errors (**), 0 flaws (~~), 8 warnings (==), 6 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 September 2000 USC/Information Sciences Institute 4 draft-ietf-cat-gaa-cbind-03.txt March 9, 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-03.txt 58 2. Approach 60 We propose an "object-oriented" approach inspired by the programming 61 style in [3]. It allows for better integration of application specific 62 modules with the GAA API. 63 We define three "classes": gaa, gaa_policy and gaa_sc. 64 The general structure of each class is depicted in Figure 1. 66 2.1. The class data structure 68 The class structure contains the following fields: 70 method 71 A pointer to the class method structure. 73 class_new(class_method*, class_ptr*) 74 creates a new class. 76 class_set(class_method*, class_ptr*) 77 sets appropriate fields of the class_method structure (attributes and methods). 79 class_free(class*) 80 frees the class structure. Depending on the configuration, this will free the 81 underlying data object. 83 2.2. "abstract" class_method data structure 85 The "abstract" class_method structure contains the following fields: 87 type 88 is the numeric type of the class_method. 90 name 91 is a textual representation of the method "type". 93 The class_method function pointers point to the respective 94 implementation specific function methods. Some of them can be NULL 95 if not implemented. 97 create() 98 creates a new class of type "type". 100 destroy() 101 frees class structure of type "type". 103 2.3. Implementation specific class_method data structure 105 This structure contains concrete values for the "abstract" 106 class_method attributes and methods which are set by the class_set 107 function. 109 ------------------------------- ------------------------------ 110 | class | | "abstract" class_method | 111 | (gaa, gaa_policy or gaa_sc) | |----------------------------| 112 |-----------------------------| | attributes | 113 | attributes | | | 114 | | | int type | 115 | class_method *method -----|----->| char *name | 116 | class specific attributes | | class specific attributes | 117 |-----------------------------| |----------------------------| 118 | methods | | methods | 119 | | | | 120 | class_new(class_method*, | | create() | 121 | class_ptr*) | | destroy() | 122 | class_set(class_method*, | | class specific methods | 123 | class*) | --------------^--------------- 124 | class_free(class*) | | 125 ------------------------------- | 126 --------------|--------------- 127 | implementation specific | 128 | class method | 129 |----------------------------| 130 | attributes | 131 | | 132 | type=implem_specific_type | 133 | name=implem_specific_name | 134 | implementation specific | 135 | attributes | 136 |----------------------------| 137 | methods | 138 | | 139 | implem_specific_create() | 140 | implem_specific_destroy() | 141 ------------------------------ 143 Figure 1. 145 3. The GAA API data types and calling conventions 147 The data types describe only fields that must be provided by all 148 GAA API implementations. Individual implementations may provide 149 additional fields for internal use within the GAA API routines. 151 3.1. Integer types 153 The GAA API defines the following integer data type: 155 uint32 32-bit unsigned integer 157 3.2. Opaque data types 159 Some data items are considered opaque to the GAA API, because their 160 internal data structure has no significance to the GAA API, e.g. 161 actual mechanism-specific credentials. 162 Opaque data is passed between the GAA API and the application using 163 the gaa_buffer_ptr data type, which is a pointer to a gaa_buffer 164 structure. 166 The gaa_buffer type is a structure containing the following fields: 168 length 169 Contains the total number of bytes in the datum 171 value 172 Contains a pointer to the actual datum 174 typedef struct gaa_buffer_struct gaa_buffer, 175 *gaa_buffer_ptr, 176 gaa_options, 177 *gaa_options_ptr; 179 struct gaa_buffer_struct { 180 size_t length; 181 void *value; 182 }; 184 3.3. Character data types 186 Certain data items used by the GAA API may be regarded as a character 187 strings. The data of this kind is passed between the GAA API and 188 application using the gaa_data data type, which is a pointer to void: 190 typedef char *gaa_data; 192 3.4. Ordered list types 194 Certain data items used by the GAA API may be regarded as an ordered list of 195 objects. In this draft we refer to them as gaa_STACK data structure. 196 The implementation of the ordered list can be application specific. 197 A possible candidate for this type of data can be STACK structure in [3]. 199 3.5. gaa_struct data structure 201 The gaa_struct structure is passed as an argument to the GAA API. It contains 202 information about behavior of the gaa evaluation routines. 203 See section 2 for explanation of the meaning of the fields 204 method, gaa_new, gaa_set and gaa_free. 206 typedef struct gaa_struct gaa, 207 *gaa_ptr; 209 struct gaa_struct 210 { 211 /* attributes */ 213 gaa_method_ptr method; 215 /* methods */ 217 gaa_error_code (*gaa_new)(gaa_ptr method, 218 gaa_ptr *gaa); 219 gaa_error_code (*gaa_set)(gaa_method_ptr method, 220 gaa_ptr gaa); 221 gaa_error_code (*gaa_free)(gaa_ptr gaa); 222 }; 224 3.6. gaa_method_struct data structure 226 The gaa_method_struct structure contains the following fields: 228 condition_evaluation 229 Specific condition evaluation function called by GAA API if there are 230 application-specific conditions. Generic (understood by the GAA API) conditions 231 are evaluated by the GAA API internal functions. 233 See section 2 for explanation of the meaning of the fields type, 234 method, create and destroy. 236 typedef struct gaa_method_struct gaa_method, 237 *gaa_method_ptr; 239 struct gaa_method_struct 240 { 241 /* attributes */ 243 int type; 244 char *name; 246 /* methods */ 248 gaa_error_code (*condition_evaluation)(gaa_policy_ptr policy, 249 gaa_sc_ptr sc, 250 gaa_options_ptr options); 251 gaa_error_code (*create)(); 252 gaa_error_code (*destroy)(); 253 }; 255 3.7. gaa_policy_struct data structure 257 The gaa_policy_struct structure contains the following fields: 259 policy 260 a pointer to memory which holds the application specific policy 261 structure 263 See section 2 for explanation of the meaning of the fields 264 method, gaa_policy_new, gaa_policy_set and gaa_policy_free. 266 typedef struct gaa_policy_struct gaa_policy, 267 *gaa_policy_ptr; 269 struct gaa_policy_struct 270 { 271 /* attributes */ 273 gaa_policy_method_ptr method; 274 gaa_buffer_ptr policy; 275 /* methods */ 277 gaa_error_code (*gaa_policy_new)(gaa_policy_method_ptr method, 278 gaa_policy_ptr *policy); 280 gaa_error_code (*gaa_policy_set)(gaa_policy_method_ptr method, 281 gaa_policy_ptr policy); 283 gaa_error_code (*gaa_policy_free)(gaa_policy_ptr policy); 284 }; 286 3.8. gaa_policy_method_struct data structure 288 The gaa_policy_method_struct structure contains the following fields: 290 eval_method 291 defines a method for policy evaluation. 292 The default value is ordered policy evaluation. 294 get_matching_entries 295 implementation specific function for retrieval of the matching entries. 296 It returns an ordered list of objects of type gaa_policy_entry_ptr (see 297 section 3.9.), which are then evaluated by the gaa routines. 299 retrieve 300 application specific function for the retrieval of the object authorization 301 information. The application maintains authorization information in 302 a form understood by the application. It can be stored in a file, 303 database, directory service or in some other way. The upcall 304 function provided for the GAA API retrieves this information. 306 See section 2 for explanation of the meaning of the fields: type, 307 method, create and destroy. 309 typedef struct gaa_policy_method_struct gaa_policy_method, 310 *gaa_policy_method_ptr; 312 struct gaa_policy_method_struct 313 { 314 /* attributes */ 316 int type; 317 char *name; 318 int eval_method; /* default ordered */ 320 /* methods */ 322 gaa_STACK_ptr /* gaa_policy_entry_ptr */ 323 (*get_matching_entries) (gaa_buffer_ptr policy, 324 gaa_STACK_ptr /* gaa_right_ptr */ requested_rights); 326 gaa_buffer_ptr(*retrieve)(uint32* minor_status, /* OUT */ 327 gaa_data object, /* IN */ 328 gaa_data policy_db, ... ); /* IN */ 330 gaa_error_code (*create)(); 331 gaa_error_code (*destroy)(); 332 }; 334 3.9. gaa_policy_entry_struct data structure 336 The gaa_policy_entrr_struct structure contains the following fields: 338 num 339 entry number in the policy 341 priority 342 specifies the priority of this entry 344 rights 345 A pointer to a linked list of structures of the type gaa_right_ptr. 346 Each structure indicates granted or denied access rights. 348 typedef struct gaa_policy_entry_struct gaa_policy_entry, 349 *gaa_policy_entry_ptr; 351 struct gaa_policy_entry_struct { 352 int num; 353 int priority; 354 gaa_STACK_ptr /* gaa_right_ptr */ rights; 355 }; 357 3.10. gaa_right_struct data structure 359 The gaa_right_struct structure contains the following fields: 361 type 362 An element of the type char*, which defines the type of the token. 363 Allowed token types are pos_access_rights and neg_access_rights. 365 authority 366 An element of the type char*, which indicates the authority 367 responsible for defining the value within the attribute type. 369 value 370 An element of the type char*, which indicates the value of the 371 right. The name space for the value is defined by 372 the "authority" field. 374 conditions 375 A pointer to an ordered list of objects of type gaa_condition_ptr. 376 It contains a list of pointers to conditions associated with the right. 378 typedef struct gaa_right_struct gaa_right, 379 *gaa_right_ptr; 380 struct gaa_right_struct { 381 char* type; 382 char* authority; 383 char* value; 384 gaa_STACK_ptr /* gaa_condition_ptr */ conditions; 385 }; 387 3.11. gaa_condition_struct 389 The gaa_condition_struct structure contains the following fields: 391 type 392 An element of the type char*, which defines the type of the condition. 394 authority 395 An element of the type char*, which indicates the authority 396 responsible for defining the value within the attribute type. 398 value 399 An element of the type char*, which indicates the value of the 400 security attribute. The name space for the value is defined by 401 the "authority" field. 403 status 404 Flags, indicating if the condition was evaluated or not evaluated, 405 if evaluated marked as met, not met or further evaluation or 406 enforcement is required. 408 typedef struct gaa_condition_struct gaa_condition, 409 *gaa_condition_ptr; 411 struct gaa_condition_struct { 412 char* type; 413 char* authority; 414 char* value; 415 uint32 status; 416 }; 418 3.12. gaa_sec_attrb_struct data structure 420 The gaa_sec_attrb_struct structure contains the following fields: 422 type 423 An element of the type char*, which defines the type of the security 424 attribute. 426 authority 427 An element of the type char*, which indicates the authority 428 responsible for defining the value within the attribute type. 430 value 431 An element of the type char*, which indicates the value of the 432 security attribute. The name space for the value is defined by 433 the "authority" field. 435 struct gaa_sec_attrb_struct { 436 char* type; 437 char* authority; 438 char* value; 439 }; 441 3.13. GAA API Security Context data structures 443 The security context is a GAA API data structure, which is passed 444 as an argument to the GAA API. It stores information relevant to 445 access control. 447 3.13.1. gaa_sc_struct data structure 449 The gaa_sc_struct structure contains the following fields: 451 sc 452 a pointer to memory which holds the mechanism specific security 453 context structure 455 identity_cred 456 A pointer to an ordered list of structures of the type gaa_identity_cred 458 authr_cred 459 A pointer to an ordered list of structures of the type gaa_authr_cred 461 group_membership 462 A pointer to an ordered list of structures of the type gaa_identity_cred, 463 which specifies that the grantee is a member of only listed groups 465 group_non_membership 466 A pointer to an ordered list of structures of the type gaa_identity_cred, 467 which specifies that the grantee is NOT a member of the listed groups 469 attributes 470 A pointer to an ordered list of structures of the type gaa_attributes, which 471 contains miscellaneous attributes attached to the grantee, e.g. age 472 of the grantee, grantee's security clearance. 474 unevl_cred 475 A pointer to an ordered list of structures of type gaa_uneval_cred. 477 connection_state 478 Contains a mechanism-specific representation of per-connection 479 context, some of the data stored here include keyblocks, addresses. 481 pull_cred 482 This function is called when additional credentials are required. 483 It obtains the necessary credentials and then cred_evaluate 484 function is invoked. This process can be recursive. 486 cred_evaluate 487 This specific function is invoked to parse the contents of the 488 acquired credentials into the GAA API internal form and evaluate them. 490 See section 2 for explanation of the meaning of the fields 491 method, gaa_sc_new, gaa_sc_set and gaa_sc_free. 493 typedef struct gaa_sc_struct gaa_sc, 494 *gaa_sc_ptr; 496 struct gaa_sc_struct 497 { 498 /* attributes */ 500 gaa_sc_method_ptr method; 501 gaa_buffer_ptr sc; 503 gaa_STACK_ptr /* gaa_identity_cred_ptr */ identity_cred; 504 gaa_STACK_ptr /* gaa_authr_cred_ptr */ authr_cred; 505 gaa_STACK_ptr /* gaa_identity_cred_ptr */ group_membership_cred; 506 gaa_STACK_ptr /* gaa_identity_cred_ptr */ group_non_membership_cred; 507 gaa_STACK_ptr /* gaa_attribute_ptr */ attributes; 508 gaa_STACK_ptr /* gaa_uneval_cred_ptr */ unevl_cred; 510 /* methods */ 512 gaa_error_code (*gaa_sc_new)(gaa_sc_method_ptr method, 513 gaa_sc_ptr *sc); 515 gaa_error_code (*gaa_sc_set)(gaa_sc_method_ptr method, 516 gaa_sc_ptr sc); 518 gaa_error_code (*gaa_sc_free)(gaa_sc_ptr sc); 519 }; 521 3.13.2. gaa_sc_method_struct data structure 523 The gaa_sc_method_struct structure contains the following fields: 525 get_identity_cred 526 application specific function which translates mechanism specific 527 credentials to the gaa internal structure. It returns an ordered 528 list of objects of type gaa_identity_cred_ptr see section 3.13.3, 529 can be NULL if not implemented. 531 get_authr_cred 532 application specific function which translates mechanism 533 specific credentials to the gaa internal structure. It returns 534 an ordered list of objects of type gaa_authr_cred_ptr see 535 section 3.13.4, 537 get_group_membership_cred 538 application specific function which translates mechanism 539 specific credentials to the gaa internal structure. It returns an 540 ordered list of objects of type gaa_group_membership_cred_ptr see 541 section 3.13.5, can be NULL if not implemented. 543 get_group_non_membership_cred 544 application specific function which translates mechanism 545 specific credentials to the gaa internal structure. It returns 546 an ordered list of objects of type gaa_group_non_membership_cred_ptr 547 see section 3.13.6, can be NULL if not implemented. 549 get_attributes 550 application specific function which translates mechanism 551 specific credentials to the gaa internal structure. It returns 552 an ordered list of objects of type gaa_attribute_ptr see section 3.13.7, 553 can be NULL if not implemented. 555 get_uneval_cred 556 application specific function which translates mechanism 557 specific credentials to the gaa internal structure. It returns an 558 ordered list of objects of type gaa_uneval_cred_ptr see section 3.13.8, 559 can be NULL if not implemented. 561 See section 2 for explanation of the meaning of the fields type, 562 method, create and destroy. 564 typedef struct gaa_sc_method_struct gaa_sc_method, 565 *gaa_sc_method_ptr; 567 struct gaa_sc_method_struct 568 { 569 /* attributes */ 571 int type; 572 char *name; 574 /* methods */ 576 gaa_STACK_ptr /* gaa_identity_cred_ptr */ 577 (*get_identity_cred)(gaa_sc_ptr sc); 578 gaa_STACK_ptr /* gaa_authr_cred_ptr */ 579 (*get_authr_cred)(gaa_sc_ptr sc); 580 gaa_STACK_ptr /* gaa_identity_cred_ptr */ 581 (*get_group_membership_cred)(gaa_sc_ptr sc); 582 gaa_STACK_ptr /* gaa_identity_cred_ptr */ 583 (*get_group_non_membership_cred)(gaa_sc_ptr sc); 584 gaa_STACK_ptr /* gaa_attribute_ptr */ 585 (*get_attributes)(gaa_sc_ptr sc); 586 gaa_STACK_ptr /* gaa_uneval_cred_ptr */ 587 (*get_unevl_cred)(gaa_sc_ptr sc); 589 gaa_error_code (*create)(); 590 gaa_error_code (*destroy)(); 591 }; 593 3.13.3. gaa_identity_cred_struct data structure 595 A gaa_identity_cred_struct structure is composed of a set of identity 596 credentials. Identity credentials describe a set of mechanism specific 597 principals, and give their holder the ability to act as any of those 598 principals. Each of the identity credentials contains information 599 needed to authenticate a single principal. 601 The gaa_identity_cred_struct structure contains the following fields: 603 principal 604 A pointer to a structure of the type gaa_sec_attrb_list 606 conditions 607 A pointer to an ordered list of objects of the type 608 gaa_sec_attrb_ptr, 609 which lists restrictions placed on the identity, e.g. validity time periods 611 mech_spec_cred 612 Contains a handle to the actual mechanism specific identity credential 614 typedef struct gaa_identity_cred_struct gaa_identity_cred, 615 *gaa_identity_cred_ptr; 617 struct gaa_identity_cred_struct { 618 gaa_sec_attrb_ptr principal; 619 gaa_STACK_ptr /* gaa_condition_ptr */ conditions; 620 gaa_buffer_ptr mech_spec_cred; 621 }; 623 3.13.4. gaa_authr_cred_struct data structure 625 The gaa_authr_cred_struct structure contains the following fields: 627 grantor 628 Specifies a principal who issued the credential 630 grantee 631 Specifies a principal for whom the credential was issued 633 objects 634 A pointer to a linked list of structures of the type gaa_data, which 635 contains a list of objects, which may be accessed by the grantee. 636 Object names are from the application-specific name space. 638 access_rights 639 A pointer to a linked list of structures of the type gaa_right_ptr. 640 Each structure indicates granted or denied access rights. 642 conditions 643 A pointer to an ordered list of objects of the type gaa_sec_attrb_ptr, 644 which lists restrictions placed on the authorized credentials 646 mech_spec_cred 647 Contains a handle to the actual mechanism-specific authorized 648 credential 650 typedef struct gaa_authr_cred_struct gaa_authr_cred, 651 *gaa_authr_cred_ptr; 653 struct gaa_authr_cred_struct{ 654 gaa_sec_attrb_ptr grantor; 655 gaa_sec_attrb_ptr grantee; 656 gaa_buffer objects; 657 gaa_STACK_ptr /* gaa_right_ptr */ access_rights; 658 gaa_buffer_ptr mech_spec_cred; 659 }; 661 3.13.5. gaa_attribute_struct data structure 663 The gaa_attribute_struct structure contains the following fields: 665 mech_type 666 Security mechanism used to obtain the attribute 668 type 669 Type is used to define the type of attribute 671 value 672 Represents actual attribute contents 674 conditions 675 A pointer to an ordered list of objects of the type gaa_condition_ptr. 676 It contains pointers to conditions placed on the attribute credentials. 678 mech_spec_cred 679 Contains a handle to the actual mechanism specific attribute 680 credential 682 typedef struct gaa_attribute_struct gaa_attribute, 683 *gaa_attribute_ptr; 685 struct gaa_attribute_struct { 686 char* mech_type; 687 char* type; 688 char* value; 689 gaa_STACK_ptr /* gaa_condition_ptr */ conditions; 690 gaa_buffer_ptr mech_spec_cred; 691 }; 693 3.13.6. gaa_uneval_cred_struct data structure 695 Evaluation of the acquired credentials can be defferd till the 696 credential is actually needed. Unevaluated credentials are stored in 697 the gaa_uneval_cred_struct data structure. 699 The gaa_uneval_cred_struct structure contains the following 700 fields: 702 cred_type 703 Specifies credential type: GAA_IDENTITY, GAA_GROUP_MEMB, 704 GAA_GROUP_NON_MEMB, GAA_AUTHORIZED, and GAA_ATTRIBUTES. 706 grantor 707 Specifies a principal who issued the credential 709 grantee 710 Specifies a principal for whom the credential was issued 712 mech_type 713 Specifies security mechanism used to obtain the credential 715 mech_spec_cred 716 Contains a handle to the actual mechanism-specific authorization 717 credential 719 cred_verification 720 This pointer to the credential verification function for upcall is 721 added by the application or transport 723 typedef enum { 724 GAA_IDENTITY , 725 GAA_GROUP_MEMB , 726 GAA_GROUP_NON_MEMB , 727 GAA_AUTHORIZED , 728 GAA_ATTRIBUTES 729 } gaa_cred_type; 731 typedef struct gaa_uneval_cred_struct gaa_uneval_cred, 732 *gaa_uneval_cred; 734 struct gaa_uneval_cred_struct { 735 gaa_cred_type cred_type; 736 gaa_sec_attrb_ptr grantor; 737 gaa_sec_attrb_ptr grantee; 738 gaa_buffer_ptr mech_spec_cred; 739 void (*cred_verification )(gaa_ptr, va_list ap); 740 }; 742 3.13.7. GAA API answer data structure 744 The gaa_check_authorization function returns various information to 745 the application for further evaluation in the gaa_answer data 746 structure. 748 The gaa_answer_struct structure contains the following fields: 750 valid_time 751 A pointer to a structure of type gaa_time_period. It specifies the 752 time period during which the authorization is granted and 753 is returned as a condition to be checked by the application. 755 rights 756 A pointer to an ordered list of structures of the type 757 gaa_right_ptr listing granted rights and corresponding conditions, if any. 759 typedef struct gaa_time_period_struct gaa_time_period, 760 *gaa_time_period_ptr; 761 struct gaa_time_period_struct{ 762 time_t start_time; /* NULL for unconstrained start time */ 763 time_t end_time; /* NULL for unconstrained end time */ 764 }; 766 typedef struct gaa_answer_struct gaa_answer, 767 *gaa_answer_ptr; 769 struct gaa_answer_struct 770 { 771 gaa_time_period_ptr valid_time; 772 gaa_STACK_ptr /* gaa_right_ptr */ rights; 773 }; 775 4. Status codes 777 One or two status codes are returned by each GAA API routine. Two 778 distinct sorts of status codes are returned. These are the GAA API 779 status codes and mechanism specific status codes. 781 4.1. The GAA API status codes 783 GAA API routines return GAA API status codes as their gaa_error_code 784 function value. These codes indicate errors that are independent of 785 the underlying mechanisms. The errors that can be indicated via a 786 GAA API status code are either generic API routine errors (errors that 787 are defined in the GAA API specification) or calling errors (errors 788 that are specific to these language bindings). 790 4.2. Mechanism specific status codes 792 GAA API routines return a minor_status parameter, which is used to 793 indicate specialized errors from the underlying mechanisms or 794 provide additional information about GAA API errors. 795 The GAA status code GAA_FAILURE is used to indicate that the 796 underlying mechanism detected an error for which no specific GAA 797 status code is defined. The mechanism status code will provide more 798 details about the error. 800 5. GAA API routine descriptions 802 This section lists the functions performed by each of the GAA API 803 routines and discusses their major parameters, describing how they 804 are to be passed to the routines. 806 5.1. gaa_get_object_policy_info routine 808 Purpose: 810 The gaa_get_object_policy_info function is called to obtain security 811 policy information associated with the object. 813 Parameters: 815 minor_status 816 mechanism specific status code 818 object 819 Reference to the object to be accessed. The identifier for the object 820 is from an application specific name space and is opaque to the 821 GAA API. 823 authr_db 824 Pointer to an application specific authorization database 826 policy_hadle 827 A pointer to a handle bound to the sequence of security attributes 828 which constitute the security policy associated with the targeted object 829 An unbound handle has the value GAA_UNBOUND. 831 Function value: 833 GAA status code: 835 GAA_SUCCESS 836 Successful completion 838 GAA_FAILURE Failure, see minor_status for more information 840 gaa_error_code 841 gaa_get_object_policy_info(uint32* minor_status, /* OUT */ 842 gaa_data object, /* IN */ 843 gaa_data policy_db, /* IN */ 844 gaa_policy_ptr policy /* OUT */); 846 5.2. gaa_check_authorization routine 848 Purpose: 850 The gaa_check_authorization function tells the application whether 851 the requested access rights are authorized, or if additional 852 application specific checks are required. 854 Parameters: 856 minor_status 857 Mechanism specific status code 859 policy_handle 860 A handle to the gaa_policy structure, returned by the 861 gaa_get_object_policy_info routine 863 gaa 864 A handle to the gaa structure 866 sc 867 A handle to the principal's security context 869 check_access_rights 870 Ordered list of access rights for authorization. 872 gaa_options 873 This argument contains parameters for parameterized operation. 875 detailed_answer 876 Contains various information for further evaluation by the application 878 Function value: 880 GAA status code: 882 GAA_FAILURE 883 Failure, see minor_status for more information 885 GAA_NO_CONTEXT 886 No valid security context was supplied 888 GAA_YES 889 (indicates authorization) is returned if all requested operations are authorized. 891 GAA_NO 892 (indicates denial of authorization) is returned if at least one operation is 893 not authorized. 895 GAA_MAYBE 896 (indicates a need for additional checks) is returned if there are some unevaluated 897 conditions and additional application specific checks are needed, or continuous 898 evaluation is required. 900 gaa_error_code 901 gaa_check_authorization 902 (uint32 *minor_status, /* OUT */ 903 gaa_ptr gaa, /* IN&OUT */ 904 gaa_sc_ptr sc, /* IN&OUT */ 905 gaa_policy_ptr policy_handle, /* IN */ 906 gaa_options_ptr gaa_options, /* IN, OPTIONAL */ 907 gaa_STACK_ptr /* gaa_right_ptr */ check_access_rights /* IN */ 908 gaa_answer_ptr *detailed_answer /* OUT */ 909 ); 911 5.3. gaa_inquire_object_policy_info routine 913 Purpose: 915 The gaa_inquire_object_policy_info function allows application 916 to discover a particular user's rights on an object. 918 Parameters: 920 minor_status 921 Mechanism specific status code 923 gaa 924 A handle to the gaa structure 926 sc 927 A handle to the principal's security context 929 policy_handle 930 A handle to the gaa_policy structure, returned by the 931 gaa_get_object_policy_info routine 933 rights 934 A handle to the ordered list of objects of type gaa_right_ptr, which 935 contains list of rights that the principal is granted or denied. 937 Function value: 939 GAA status code: 941 GAA_SUCCESS 942 Successful completion 944 GAA_FAILURE 945 Failure, see minor_status for more information 947 GAA_NO_CONTEXT 948 No valid security context was supplied 950 gaa_error_code 951 gaa_inquire_policy_info 952 (uint32 *minor_status, /* OUT */ 953 gaa_ptr gaa, /* IN&OUT */ 954 gaa_sc_ptr sc, /* IN&OUT */ 955 gaa_policy_ptr policy_handle, /* IN */ 956 gaa_STACK_ptr /* gaa_policy_entry_ptr */ *rights /* OUT */ 957 ); 959 5.4. gaa_allocate_buffer routine 961 Purpose: 962 Allocate a gaa_buffer data structure and assign default values 964 Parameters: 966 buffer 967 Pointer to allocated memory for gaa_buffer structure 969 Function value: 971 GAA status code: 973 GAA_SUCCESS 974 Successful completion 976 GAA_FAILURE 977 Failure 979 gaa_error_code 980 gaa_allocate_buffer 981 (gaa_buffer_ptr* buffer /* IN */); 983 5.5. gaa_release_buffer routine 985 Purpose: 987 Free storage associated with a buffer format name. The storage must 988 have been allocated by a GAA API routine. In addition to freeing the 989 associated storage, the routine will zero the length field in the 990 buffer parameter. 992 Parameters: 994 minor_status 995 Mechanism specific status code 997 buffer 998 The storage associated with the buffer will be deleted. 999 The gaa_buffer object will not be freed, but its length field will 1000 be zeroed. 1002 Function value: 1004 GAA status code: 1006 GAA_SUCCESS 1007 Successful completion 1009 GAA_FAILURE 1010 Failure, see minor_status for more information 1012 GAA_NO_BUFFER 1013 No valid buffer was supplied 1015 gaa_error_code 1016 gaa_release_buffer (uint32* minor_status, /* OUT */ 1017 gaa_buffer_ptr buffer /* IN */); 1019 5.6. gaa_allocate_answer routine 1021 Purpose: 1022 Allocate a gaa_answer data structure and assign default values 1024 Parameters: 1026 buffer 1027 Pointer to allocated memory for gaa_buffer structure 1029 Function value: 1031 GAA status code: 1033 GAA_SUCCESS 1034 Successful completion 1036 GAA_FAILURE 1037 Failure 1039 gaa_error_code 1040 gaa_allocate_answer 1041 (gaa_answer_ptr* buffer /* IN */); 1043 5.7. gaa_release_answer 1045 Free storage associated with a buffer 1047 Parameters: 1049 minor_status 1050 Mechanism specific status code 1052 buffer 1053 The storage associated with the buffer will be deleted 1055 Function value: 1057 GAA status code: 1059 GAA_SUCCESS 1060 Successful completion 1062 GAA_FAILURE 1063 Failure, see minor_status for more information 1065 GAA_NO_BUFFER 1066 No valid buffer was supplied 1068 gaa_error_code 1069 gaa_release_answer(uint32 *minor_status, 1070 gaa_answer_ptr *buffer) 1072 6. The GAA API constants 1074 The following constants are used in GAA API calls and structures, 1075 this list is not complete: 1077 #define GAA_NO_OPTIONS ((gaa_options_ptr)0) 1078 #define GAA_NO_BUFFER ((gaa_buffer_ptr)0) 1079 #define GAA_EMPTY_BUFFER {0, NULL} 1080 #define GAA_NO_DATA ((gaa_data) 0) 1081 #define GAA_NO_SEC_CONTEXT ((gaa_sc_ptr)0) 1082 #define GAA_NO_RIGHTS ((gaa_right_ptr) 0) 1083 #define GAA_NO_ANSWER ((gaa_answer_ptr)0) 1085 #define GAA_YES 0 (indicates authorization) is returned if all 1086 requested operations are authorized. 1088 #define GAA_NO 1 (indicates denial of authorization) is returned 1089 if at least one operation is not authorized. 1091 #define GAA_MAYBE -1 (indicates a need for additional checks) is 1092 returned if there are some unevaluated conditions 1093 and additional application specific checks are needed, 1094 or continuous evaluation is required. 1095 7. The GAA API flags 1097 Flags are 32 bits. 1099 Condition flags: 1101 #define COND_FLG_EVALUATED 0x01 condition has been evaluated 1102 #define COND_FLG_MET 0x10 condition has been met 1103 #define COND_FLG_ENFORCE 0x100 condition has to be enforced 1105 8. References 1107 [1] Linn, J., "Generic Security Service Application Program 1108 Interface", RFC 1508, Geer Zolot Associate, September 1993. 1110 [2] Wray, "Generic Security Service Application Program 1111 Interface V2 - C bindings", Internet draft, May 1997. 1113 [3] T J Hudson, E A Young 1114 SSLeay http://www.livjm.ac.uk/tools/ssleay/ 1116 9. Acknowledgments 1118 Carl Kesselman and Douglas Engert have contributed to discussion 1119 of ideas and material in this draft. 1121 10. Authors' Addresses 1123 Tatyana Ryutov 1124 Clifford Neuman 1125 USC/Information Sciences Institute 1126 4676 Admiralty Way Suite 1001 1127 Marina del Rey, CA 90292-6695 1128 Phone: +1 310 822 1511 1129 E-Mail: {tryutov, bcn}@isi.edu