idnits 2.17.1 draft-ietf-cat-gaa-cbind-00.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): ---------------------------------------------------------------------------- ** Cannot find the required boilerplate sections (Copyright, IPR, etc.) in this document. Expected boilerplate is as follows today (2024-03-28) according to https://trustee.ietf.org/license-info : IETF Trust Legal Provisions of 28-dec-2009, Section 6.a: This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79. IETF Trust Legal Provisions of 28-dec-2009, Section 6.b(i), paragraph 2: Copyright (c) 2024 IETF Trust and the persons identified as the document authors. All rights reserved. IETF Trust Legal Provisions of 28-dec-2009, Section 6.b(i), paragraph 3: This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- ** Missing expiration date. The document expiration date should appear on the first and last page. ** The document seems to lack a 1id_guidelines paragraph about Internet-Drafts being working documents. ** The document seems to lack a 1id_guidelines paragraph about the list of current Internet-Drafts. ** The document seems to lack a 1id_guidelines paragraph about the list of Shadow Directories. ** 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 1349 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 4 instances of too long lines in the document, the longest one being 119 characters in excess of 72. ** There are 3 instances 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 913: '...eck_access_rights, /* IN, OPTIONAL */...' RFC 2119 keyword, line 914: '...a_options /* IN, OPTIONAL */...' RFC 2119 keyword, line 1235: '...on_access_rights /* IN, OPTIONAL */);...' Miscellaneous warnings: ---------------------------------------------------------------------------- == Line 116 has weird spacing: '..._struct gaa_t...' == Line 121 has weird spacing: '...ist_ptr next...' == Line 143 has weird spacing: '..._struct gaa_t...' == Line 146 has weird spacing: '...ata_ptr tag;...' == Line 159 has weird spacing: '..._struct gaa_t...' == (36 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 (August 07, 1998) is 9365 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? '0' on line 385 looks like a reference -- Missing reference section? '3' on line 390 looks like a reference -- Missing reference section? '4' on line 390 looks like a reference -- Missing reference section? '31' on line 390 looks like a reference -- Missing reference section? '1' on line 1273 looks like a reference -- Missing reference section? '2' on line 1276 looks like a reference Summary: 13 errors (**), 0 flaws (~~), 8 warnings (==), 9 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 February 1999 USC/Information Sciences Institute 4 draft-ietf-cat-gaa-cbind-00.txt August 07, 1998 6 Generic Authorization and Access control 7 Application Program Interface 8 C-bindings 10 0. Status Of this Document 12 This document is an Internet-Draft. Internet-Drafts are working 13 documents of the Internet Engineering Task Force (IETF), its 14 areas, and its working groups. Note that other groups may also 15 distribute working documents as Internet-Drafts. 17 Internet-Drafts are draft documents valid for a maximum of six 18 months and may be updated, replaced, or obsoleted by other 19 documents at any time. It is inappropriate to use Internet-Drafts 20 as reference material or to cite them other than as 21 "work in progress." 23 To view the entire list of current Internet-Drafts, please check 24 the "1id-abstracts.txt" listing contained in the Internet-Drafts 25 Shadow Directories on ftp.is.co.za (Africa), ftp.nordu.net 26 (Northern Europe), ftp.nis.garr.it (Southern Europe), munnari.oz.au 27 (Pacific Rim), ftp.ietf.org (US East Coast), or ftp.isi.edu 28 (US West Coast). 30 1. Abstract 32 The Generic Authorization and Access control Application Programming 33 Interface (GAA API) provides access control services to calling 34 applications. 35 It facilitates access control decisions for applications and allows 36 applications to discover access control policies associated with a 37 targeted resource. The GAA API is usable by multiple applications 38 supporting different kinds of protected objects. 39 The GAA API design supports: 41 - a variety of security mechanisms based on public or secret key 42 cryptosystems 43 - different authorization models 44 - heterogeneous security policies 45 - various access rights 47 This document specifies C language bindings for the GAA API, which 48 is described at a language-independent conceptual level in 49 draft-ietf-cat-acc-cntrl-frmw-00.txt 51 2. The GAA API data types and calling conventions 53 The data types describe only fields that must be provided by all 55 Ryutov/Neuman Expires February 1999 57 GAA API implementations. Individual implementations may provide 58 additional fields for internal use within GAA API routines. 60 2.1. Integer types 62 The GAA API defines the following integer data type: 64 uint32 32-bit unsigned integer 66 2.2. String and similar data 68 Certain data items used by the GAA API may be regarded as a character 69 strings, e.g. principal name or specification of security mechanism. 70 The data of this kind is passed between the GAA API and application 71 using the gaa_data_ptr data type, which is a pointer to a gaa_data 72 structure. 74 2.2.1 gaa_data data structure 76 The gaa_data type is a structure containing the following fields: 78 length 79 Contains the total number of bytes in the datum. 81 data 82 Contains a pointer to the actual datum. 84 typedef struct gaa_data_struct gaa_data, *gaa_data_ptr; 86 struct gaa_data_struct { 87 int length; 88 char *data; 89 }; 91 2.2.2. gaa_tag_value_list data structure 93 Some data items used by the GAA API may be regarded as a linked list 94 of tag:value character elements. For example, a pointer to a list of 95 tag:value character strings is passed to the gaa_check_authorithation 96 routine via the gaa_options parameter. 97 The data of this kind is passed between the GAA API and the 98 application using the gaa_tag_value_list_ptr data type, which is a 99 pointer to a gaa_tag_value_list structure. 101 The gaa_tag_value_list type is a structure containing the following 102 fields: 104 tag 105 A character string, which identifies how the character string stored 106 in the "value" field should be interpreted by the GAA API. 108 value 109 Contains a pointer to the element of the type gaa_data. 111 Ryutov/Neuman Expires February 1999 113 next 114 A pointer to the next element in the list. 116 typedef struct gaa_tag_value_list_struct gaa_tag_value_list, 117 *gaa_tag_value_list_ptr; 118 struct gaa_tag_value_list_struct { 119 gaa_data_ptr tag; 120 gaa_data_ptr value; 121 gaa_tag_value_list_ptr next; 122 }; 124 2.2.3. gaa_tag_vector and gaa_tag_vector_list data structures 126 Some data items used by the GAA API may be regarded as a linked list 127 of tag:vector elements. For example, a pointer to a list of tag:vector 128 elements is passed to the gaa_check_authorithation routine via the 129 check_access_rights parameter. 130 The data of this kind is passed between the GAA API and the 131 application using the gaa_tag_vector_list_ptr data type, which is a 132 pointer to a gaa_tag_vector_list structure. 134 The gaa_tag_vector type is a structure containing the following 135 fields: 137 tag 138 Denotes how bits in the "vector" field are to be interpreted. 140 vector 141 Contains an integer of type uint32 143 typedef struct gaa_tag_vector_struct gaa_tag_vector, 144 *gaa_tag_vector_ptr; 145 struct gaa_tag_vector_struct { 146 gaa_data_ptr tag; 147 uint32 vector; 148 }; 150 The gaa_tag_vector_list type is a structure containing the 151 following fields: 153 element 154 Contains a pointer to the element of type gaa_tag_vector 156 next 157 Contains a pointer to the next element in the list 159 typedef struct gaa_tag_vector_list_struct gaa_tag_vector_list, 160 *gaa_tag_vector_list_ptr; 162 struct gaa_tag_vector_list_struct { 163 gaa_tag_vector_ptr element; 164 gaa_tag_vector_list_ptr next; 165 }; 167 2.3. Opaque data types 169 Ryutov/Neuman Expires February 1999 171 Some data items are considered opaque to the GAA API, because their 172 internal data structure has no significance to the GAA API, e.g. 173 actual mechanism-specific credentials. 174 Opaque data is passed between the GAA API and the application using 175 the gaa_buffer_ptr data type, which is a pointer to a gaa_buffer 176 structure. 178 The gaa_buffer type is a structure containing the following fields: 180 length 181 Contains the total number of bytes in the datum 183 value 184 Contains a pointer to the actual datum 186 typedef struct gaa_buffer_struct gaa_buffer, *gaa_buffer_ptr; 188 struct gaa_buffer_struct { 189 size_t length; 190 void *value; 191 }; 193 2.4. GAA API Access Control List data structures 195 Certain GAA API procedures take parameters of the type gaa_acl_ptr, 196 which is a pointer to a gaa_acl structure. 198 gaa_acl data type contains a complete ACL, made up of a list of 199 entry fields of type gaa_acl_entry. GAA_ACL_UNBOUND defines the value 200 of the unbound ACL handle. 202 2.4.1. gaa_acl data structure 204 The gaa_acl type is a structure containing the following fields: 206 object_name 207 Contains a name of an object with which the ACL is associated. 208 The name of the object is from the application-specific name space. 209 The object_name field is evaluated by GAA API routine when checking 210 credentials of the type gaa_authorized_cred to determine if the 211 object_name for which the ACL is being examined is listed in the set 212 of those objects which can be accessed by the grantee. 213 Whether this field should be present in the gaa_acl data structure 214 is not clear. If we decide not to include this field, we should 215 provide a means for deciding if the targeted object is included in 216 the list of objects accessible by the grantee. 218 acl_entries 219 A pointer to a list of ACL entries, each of type gaa_acl_entry 221 typedef struct gaa_acl_struct gaa_acl, *gaa_acl_ptr; 223 Ryutov/Neuman Expires February 1999 225 struct gaa_acl_struct { 226 gaa_data_ptr object_name; 227 gaa_acl_entry_ptr acl_entries; 228 }; 230 2.4.2. gaa_acl_entry data structure 232 The gaa_acl_entry type is a structure containing the following 233 fields: 235 type 236 Indicates whether the ACL entry grants or denies access. 237 If type = GAA_GRANT, the entry specifies positive rights. 238 If type = GAA_DENY, the entry specifies negative rights. Entries of 239 this type must not have any conditions, so GAA_NO_CONDITIONS 240 value is stored in the condition field. 242 principals 243 A pointer to a structure of the type gaa_principal_list, which 244 contains list of principals. Principals can be aggregated into a 245 single ACL entry when the same set of access rights and conditions 246 applies to all of them. 248 access_rights 249 A pointer to a linked list of structures of the type 250 gaa_acl_access_rights_set. 251 Each set indicates access rights named with the same tag. 252 For example, consider the following user-level 253 representation of an ACL entry: 255 USER kerberos.v5 joe@ISI.EDU < FILE : read > 257 < FILE : write 258 ACCOUNT: withdraw > time_window : 7AM-7PM 259 time_day : Mon-Fri time_day : Mon-Fri 260 < FILE : execute 261 ACCOUNT : deposit 262 ACCOUNT : transfer > location : *.isi.edu; 264 The first access rights set consists of FILE : read, FILE : write 265 and FILE : execute. 266 The second one consists of ACCOUNT : withdraw, ACCOUNT : deposit and 267 ACCOUNT : transfer. 269 conditions 270 A pointer to a list of structures of the type gaa_conditions, which 271 contains all different conditions that are present in the ACL entry. 272 In the example of an ACL entry given above, the condition list 273 contains three conditions: time_window : 7AM-7PM, time_day : Mon-Fri 274 and location : *.isi.edu. 276 next 278 Ryutov/Neuman Expires February 1999 280 A pointer to the next ACL entry 282 typedef enum { 283 GAA_GRANT, 284 GAA_DENY 285 } gaa_entry_type; 287 typedef struct gaa_acl_entry_struct gaa_acl_entry, 288 *gaa_acl_entry_ptr; 290 struct gaa_acl_entry_struct { 291 gaa_entry_type type; 292 gaa_principal_list_ptr principals; 293 gaa_access_rights_set_ptr access_rights; 294 gaa_conditions_ptr conditions; 295 gaa_acl_entry_ptr next; 296 }; 298 2.4.3. gaa_principal and gaa_principal_list data structures 300 The gaa_principal type is a structure containing the following 301 fields: 303 type 304 Specifies the type of principal: GAA_USER, GAA_GROUP, GAA_HOST, 305 GAA_APPLICATION or GAA_ANYBODY. 307 mech_type 308 Contains principal naming method, which specifies the type of the 309 security mechanism used to obtain authenticated subject's identity, 310 e.g. Kerberos.V5, DCE. 311 If type = GAA_ANYBODY, mech_type and name fields are assigned value 312 GAA_NO_DATA. 314 name 315 Contains principal name, which specifies authenticated subject's 316 identity, e.g. joe@ISI.EDU. 318 typedef enum { 319 GAA_USER , 320 GAA_GROUP , 321 GAA_HOST , 322 GAA_APPLICATION , 323 GAA_ANYBODY 324 } gaa_principal_type; 326 typedef struct gaa_principal_struct gaa_principal, 327 *gaa_principal_ptr; 329 struct gaa_principal_struct { 330 gaa_principal_type type; 331 gaa_data_ptr mech_type; 333 Ryutov/Neuman Expires February 1999 335 gaa_data_ptr name; 336 }; 338 The gaa_principal_list type is a structure containing the following 339 fields: 341 principal 342 A pointer to the gaa_principal structure 344 next 345 A pointer to the next principal in the ACL entry 347 typedef struct gaa_principal_list_struct gaa_principal_list, 348 *gaa_principal_list_ptr; 349 struct gaa_principal_list_struct { 350 gaa_principal_ptr principal; 351 gaa_principal_ptr next; 352 }; 354 2.4.4. gaa_access_rights_set data structure 356 The gaa_access_rights_set type is a structure containing the 357 following fields: 359 rights 360 A pointer to a structure of the type gaa_tag_vector. 361 In the example of an ACL entry given in the section 2.4.2, the 362 gaa_tag_vector structure, corresponding to the first access rights 363 set, will have "FILE" value in the "tag " field and 1110...0 in 364 the "vector" field. 365 The first set bit stands for "read", the second one for "write" and 366 the third one for "execute". 367 The gaa_tag_vector structure, corresponding to the second access 368 rights set, will have "ACCOUNT" value in the "tag" field and 1110...0 369 in the "vector" field. The first set bit stands for "withdraw", the 370 second one for "deposit" and the third one for "transfer". 372 mask 373 An array containing GAA_NUM_ACCESS_RIGHTS pointers to a list of 374 structures of type gaa_condition_mask. Each gaa_condition_mask 375 structure contains a pointer to particular condition associated with 376 the granted right and a pointer to the next structure of the type 377 gaa_condition_mask. 378 mask[i], were index "i" corresponds to a bit in the bit-vector, is 379 set to GAA_NO_CONDITIONS for all denied rights and granted rights 380 with no associated conditions. 381 In the example of an ACL entry given in the section 2.4.2, lets consider 382 mask structure for the first access rights set. 383 The access rights set will have "FILE" value in the "tag" field and 384 1110...0 in the "vector" field of "rights" element. 385 mask[0] (corresponding to "read" access right) will be set to 386 GAA_NO_CONDITIONS, since "read" has no conditions. 388 Ryutov/Neuman Expires February 1999 390 mask[3], mask[4],..., mask[31] will be also set to GAA_NO_CONDITIONS. 391 mask[1] (corresponding to "write" access right) will point to the list 392 of gaa_condition_mask, which has two elements. 393 The first element will have a pointer to the condition 394 time_window : 7AM-7PM in the "condition" field, the second element 395 will have a pointer to the condition time_day : Mon-Fri in the 396 "condition" field. 397 mask[2] (corresponding to "execute" access right) will point to the 398 list of gaa_condition_mask, which has just one element with 399 a pointer to the condition location : *.isi.edu in the "condition" 400 field. 402 next 403 A pointer to the next set of access rights in the ACL entry. 405 typedef struct gaa_condition_mask_struct gaa_condition_mask, 406 *gaa_condition_mask_ptr; 407 struct gaa_condition_mask_struct { 408 gaa_conditions_ptr condition; 409 gaa_condition_mask_ptr next; 410 } ; 412 typedef struct gaa_access_rights_set_struct gaa_access_rights_set, 413 *gaa_access_rights_set_ptr; 414 struct gaa_access_rights_set_struct { 415 gaa_tag_vector_ptr rights; 416 gaa_condition_mask_ptr mask[GAA_NUM_ACCESS_RIGHTS]; 417 gaa_access_rights_set_ptr next; 418 }; 420 2.4.5. gaa_conditions data structure 422 This structure defines a specific policies under which access 423 rights are granted. It lists all conditions that have been encountered 424 in the ACL entry. The mapping between access rights and corresponding 425 condition sets is defined via gaa_condition_mask structure. 427 The gaa_conditions type is a structure containing the following 428 fields: 430 type 431 Type defines the type of condition and which evaluation 432 function will be invoked to evaluate it. 434 value 435 Value represents a set of parameters for the condition evaluation 436 function. The meaning of the parameters and their relationships 437 depend on how the evaluation function interprets them. 439 flags 440 Flags indicate if condition was evaluated/not evaluated, 441 satisfied/not satisfied, or must be enforced. 443 Ryutov/Neuman Expires February 1999 445 next 446 A pointer to the next condition in the ACL entry. 448 typdef struct gaa_conditions_struct gaa_conditions, 449 *gaa_conditions_ptr; 451 struct gaa_conditions_struct { 452 gaa_data_ptr type; 453 gaa_data_ptr value; 454 uint32 flags; 455 gaa_conditions_ptr next; 456 }; 458 2.5 GAA API Security Context data structures 460 The security context is a GAA API data structure, which is passed 461 as an argument to the GAA API. It stores information relevant to 462 access control. 464 2.5.1 gaa_sec_context data structure 466 The gaa_sec_context type is a structure containing the following 467 fields: 469 identity_cred 470 A pointer to a list of structures of the type gaa_identity_cred 472 authr_cred 473 A pointer to a list of structures of the type gaa_authrized_cred 475 group_membership 476 A pointer to a list of structures of the type gaa_identity_cred, 477 which specifies that the grantee is a member of only listed groups 479 group_non_membership 480 A pointer to a list of structures of the type gaa_identity_cred, 481 which specifies that the grantee is NOT a member of the listed groups 483 attributes 484 A pointer to a list of structures of the type gaa_attributes, which 485 contains miscellaneous attributes attached to the grantee, e.g. age 486 of the grantee, grantee security clearance. 488 unevl_cred 489 A pointer to a list of structures of type gaa_unevaluated_cred. 491 connection_state 492 Contains a mechanism-specific representation of per-connection 493 context, some of the data stored here include keyblocks, addresses. 495 condition_evaluation 496 Specific condition evaluation function called by GAA API if there are 498 Ryutov/Neuman Expires February 1999 500 application-specific conditions. 501 Generic (understood by the GAA API) conditions are evaluated by the 502 GAA API internal functions. 504 pull_cred 505 This function is called when additional credentials are required. 506 It obtains the necessary credentials and then cred_evaluate 507 function is invoked. This process can be recursive. 509 cred_evaluate 510 This specific function is invoked to parse the contents of the 511 acquired credentials into the GAA API internal form and evaluate them. 513 typedef struct gaa_sec_context_struct gaa_sec_context, 514 *gaa_sec_context_ptr 515 struct gaa_sec_context_struct { 516 gaa_identity_cred_ptr identity_cred; 517 gaa_authrized_cred_ptr authr_cred; 518 gaa_identity_cred_ptr group_membership; 519 gaa_identity_cred_ptr group_non_membership; 520 gaa_attributes_ptr attributes; 521 gaa_unevaluated_cred_ptr unevl_cred; 522 gaa_buffer_ptr connection_state; 524 void 525 (*condition_evaluation)(gaa_sec_context_ptr, va_list ap); 527 void 528 (*pull_cred)(gaa_sec_context_ptr, va_list ap); 530 void 531 (*cred_evaluate)(gaa_sec_context_ptr, va_list ap); 532 }; 534 2.5.2. gaa_identity_cred data structure 536 A gaa_identity_cred structure is composed of a set of identity 537 credentials. Identity credentials describe a set of mechanism-specific 538 principals, and give their holder the ability to act as any of those 539 principals. Each of the identity credentials contains information 540 needed to authenticate a single principal. 542 The gaa_identity type is a structure containing the following fields: 544 principal 545 A pointer to a structure of the type gaa_principal 547 conditions 548 A pointer to a list of structures of the type gaa_conditions, which lists 549 restrictions placed on the identity, e.g. validity time periods 551 mech_spec_cred 552 Contains a handle to the actual mechanism-specific identity credential 554 Ryutov/Neuman Expires February 1999 556 next 557 Contains a pointer to the next identity credential 559 typedef struct gaa_identity_cred_struct gaa_identity_cred, 560 *gaa_identity_cred_ptr; 561 struct gaa_identity_cred_struct { 562 gaa_principal_ptr principal; 563 gaa_conditions_ptr conditions; 564 gaa_buffer_ptr mech_spec_cred; 565 gaa_identity_cred_ptr next; 566 }; 568 2.5.3 gaa_authorized_cred data structure 570 This type of credentials used when individuals grant delegated 571 credential or generate a capability. 573 grantor 574 Specifies a principal who issued the credential 576 grantee 577 Specifies a principal for whom the credential was issued 579 objects 580 A pointer to a linked list of structures of the type gaa_data, which 581 contains a list of objects which may be accessed by the grantee. 582 Object names are from the application-specific name space. 584 access_rights 585 A pointer to a linked list of structures of the type 586 gaa_acl_access_rights_set. Each structure indicates granted access 587 rights. 589 conditions 590 A pointer to a list of structures of the type gaa_conditions, 591 which lists restrictions placed on the authorized credentials 593 mech_spec_cred 594 Contains a handle to the actual mechanism-specific authorized 595 credential 597 next 598 Contains a pointer to the next authorized credential belonging to the 599 same grantee 601 typedef struct gaa_authorized_cred_struct gaa_authorized_cred, 602 *gaa_authorized_cred_ptr; 603 struct gaa_authorized_cred_struct{ 604 gaa_principal_ptr grantor; 605 gaa_principal_ptr grantee; 606 gaa_data_list_ptr objects; 607 gaa_access_rights_set_ptr access_rights; 608 gaa_conditions_ptr conditions; 609 gaa_buffer_ptr mech_spec_cred; 611 Ryutov/Neuman Expires February 1999 613 gaa_authorized_cred_ptr next; 614 }; 616 2.5.4. gaa_attributes data structure 618 The gaa_attributes type is a structure containing the following 619 fields: 621 mech_type 622 Security mechanism used to obtain the credential 624 type 625 Type is used to define the type of attribute 627 value 628 Represents actual attribute contents 630 conditions 631 A pointer to a list of structures of the type gaa_conditions, 632 which lists restrictions placed on the attribute credentials 634 mech_spec_cred 635 Contains a handle to the actual mechanism-specific attribute 636 credential 638 next 639 Contains a pointer to the next attributes credential belonging to 640 the same grantee. 642 typedef struct gaa_attributes_struct gaa_attributes, 643 *gaa_attributes_ptr; 644 struct gaa_attributes_struct { 645 gaa_data_ptr mech_type; 646 gaa_data_ptr type; 647 gaa_data_ptr value; 648 gaa_conditions_ptr conditions; 649 gaa_buffer_ptr mech_spec_cred; 650 gaa_attributes_ptr next; 651 }; 653 2.5.5. gaa_unevaluated_cred data structure 655 Evaluation of the acquired credentials can be defferd till the 656 credential is actually needed. Unevaluated credentials are stored in 657 the gaa_unevaluated_cred data structure. 659 The gaa_unevaluated_cred type is a structure containing the following 660 fields: 662 cred_type 663 Specifies credential type: GAA_IDENTITY, GAA_GROUP_MEMB, 664 GAA_GROUP_NON_MEMB, GAA_AUTHORIZED, and GAA_ATTRIBUTES. 666 Ryutov/Neuman Expires February 1999 668 grantor 669 Specifies a principal who issued the credential 671 grantee 672 Specifies a principal for whom the credential was issued 674 mech_type 675 Specifies security mechanism used to obtain the credential 677 mech_spec_cred 678 Contains a handle to the actual mechanism-specific authorization 679 credential 681 cred_verification 682 This pointer to the credential verification function for upcall is 683 added by the application or transport 685 next 686 Contains a pointer to the next unevaluated credential belonging to 687 the same subject. 689 typedef enum { 690 GAA_IDENTITY , 691 GAA_GROUP_MEMB , 692 GAA_GROUP_NON_MEMB , 693 GAA_AUTHORIZED , 694 GAA_ATTRIBUTES 695 } gaa_cred_type; 697 typedef struct gaa_unevaluated_cred_struct gaa_unevaluated_cred, 698 *gaa_unevaluated_cred; 699 struct gaa_unevaluated_cred_struct { 700 gaa_cred_type cred_type; 701 gaa_principal_ptr grantor; 702 gaa_principal_ptr grantee; 703 gaa_buffer_ptr mech_spec_cred; 704 void (*cred_verification)(gaa_sec_context_ptr, va_list ap); 705 gaa_unevaluated_cred_ptr next; 706 }; 708 2.6 GAA API answer data structure 710 The gaa_check_authorization function returns various information to 711 the application for further evaluation in the gaa_answer data 712 structure. 714 The gaa_answer type is a structure containing the following fields: 716 valid_time 717 A pointer to a structure of type gaa_time_period. It specifies the 718 time period during which the authorization is granted and 720 Ryutov/Neuman Expires February 1999 722 is returned as a condition to be checked by the application. 723 Expiration time is calculated by the GAA API, based on: 724 - time-related conditions in the ACL matching entries 725 - restrictions in the attributes, identity, authorization and 726 group membership credentials 728 granted_raccess_rights 729 A pointer to a linked list of structures of the type 730 gaa_acl_access_rights_set 732 conditions 733 A pointer to a list of structures of type gaa_conditions, 734 which lists all different conditions for the granted access rights 736 required_sec_attributes 737 Contains a pointer to a gaa_value_type_list structure, which 738 contains information about additional security attributes required, 739 e.g. group membership or authorized credentials. 741 typedef struct gaa_time_period_struct gaa_time_period, 742 *gaa_time_period_ptr; 743 struct gaa_time_period_struct{ 744 time_t start_time; /* NULL for unconstrained start time */ 745 time_t end_time; /* NULL for unconstrained end time */ 746 }; 748 typedef struct gaa_answer_struct gaa_answer, *gaa_answer_ptr; 750 struct gaa_answer_struct{ 751 gaa_time_period_ptr valid_time; 752 gaa_access_rights_set_ptr granted_access_rights; 753 gaa_conditions_ptr conditions; 754 gaa_tag_value_list_ptr required_sec_attributes 755 }; 757 3. Memory allocation 759 Storage for data returned to the application by a GAA API routine 760 using gaa_buffer_ptr, gaa_tag_value_list_ptr, gaa_tag_vector_list 761 is allocated by the GAA API routines. The application may clear this 762 storage by invoking the gaa_release_buffer, gaa_release_tag_value_list 763 and gaa_release_tag_vector_list routines. 764 Allocation of the gaa_buffer, gaa_tag_value_list, gaa_tag_vector_list 765 and gaa_sec_context structures is always the responsibility of the 766 application. 768 4. Status codes 770 One or two status codes are returned by each GAA API routine. Two 771 distinct sorts of status codes are returned. These are the GAA API 772 status codes and mechanism-specific status codes. 774 4.1 The GAA API status codes 776 Ryutov/Neuman Expires February 1999 778 GAA API routines return GAA API status codes as their gaa_error_code 779 function value. These codes indicate errors that are independent of 780 the underlying mechanisms. The errors that can be indicated via a 781 GAA API status code are either generic API routine errors (errors that 782 are defined in the GAA API specification) or calling errors (errors 783 that are specific to these language bindings). 785 4.2 Mechanism-specific status codes 787 GAA API routines return a minor_status parameter, which is used to 788 indicate specialized errors from the underlying mechanisms or 789 provide additional information about GAA API errors. 790 The GAA status code GAA_FAILURE is used to indicate that the 791 underlying mechanism detected an error for which no specific GAA 792 status code is defined. The mechanism status code will provide more 793 details about the error. 795 5. GAA API routine descriptions 797 This section lists the functions performed by each of the GAA API 798 routines and discusses their major parameters, describing how they 799 are to be passed to the routines. 801 5.1 gaa_get_object_acl routine 803 Purpose: 805 The gaa_get_object_acl function is called to obtain a handle to an 806 object ACL. 808 Parameters: 810 minor_status mechanism-specific status code 812 object 813 Reference to the object to be accessed. The identifier for the object 814 is from an application-specific name space and is opaque to the 815 GAA API. 817 authr_db 818 Pointer to an application-specific authorization database 820 retrieve 821 Upcall function for the retrieval of the object ACL. 822 The application maintains authorization information in a form 823 understood by the application. It can be stored in a file, database, 824 directory service or in some other way. The upcall function provided 825 for the GAA API retrieves the ACL and translates it into the internal 826 GAA API representation. 828 acl_handle 829 A pointer to a handle bound to the ACL that is the subjects 830 of examination. 831 An unbound handle has the value GAA_ACL_UNBOUND. 833 Ryutov/Neuman Expires February 1999 835 Function value: 837 GAA status code: 839 GAA_FAILURE Failure, see minor_status for more information 841 gaa_error_code 842 gaa_get_object_acl(int* minor_status, /* OUT */ 843 gaa_data_ptr object, /* IN */ 844 gaa_data_ptr authr_db, /* IN */ 845 void*(*retrieve)(gaa_data_ptr object, 846 gaa_data_ptr authr_db, 847 ...) /* IN */ 848 gaa_acl_list_ptr* acl_handle , /* OUT */); 850 5.2 gaa_check_authorization routine 852 Purpose: 854 The gaa_check_authorization function tells the application whether 855 the requested access rights are authorized, or if additional 856 application-specific checks are required. 858 Parameters: 860 minor_status 861 Mechanism specific status code 863 acl_handle 864 A handle to the ACL, returned by the gaa_get_object_acl routine 866 sec_context 867 Principal's security context 869 check_access_rights 870 List of access rights for authorization. This argument is optional. 872 detailed_answer 873 Contains various information for further evaluation by the application 875 gaa_options 876 Describes the behavior of the GAA API and specifies how the other 877 arguments should be interpreted. For example, type of the ACL: ordered 878 or unordered. Depending on this type corresponding ACL evaluation 879 algorithm will be used by the GAA API. This argument is optional. 881 detailed_answer 882 Contains various information for further evaluation by the application 884 Function value: 886 GAA status code: 888 GAA_FAILURE 890 Ryutov/Neuman Expires February 1999 892 Failure, see minor_status for more information 894 GAA_NO_CONTEXT 895 No valid security context was supplied 897 GAA_AUTHORIZED 898 Is returned if all requested operations are authorized 900 GAA_NOT_AUTHORIZED 901 Is returned if at least one operation is not authorized 903 GAA_ADDITIONAL_CHECKS_REQIRED 904 Is returned if there are some unevaluated conditions and additional 905 application-specific checks are needed or if continuous valuation 906 of the conditions is required. 908 gaa_error_code 909 gaa_check_authorization 910 (int* minor_status, /* OUT */ 911 gaa_sec_context_ptr sec_context, /* IN&OUT */ 912 gaa_acl_list_ptr acl_handle, /* IN */ 913 gaa_tag_vector_list_ptr check_access_rights, /* IN, OPTIONAL */ 914 gaa_tag_value_list_ptr gaa_options /* IN, OPTIONAL */ 915 gaa_answer_struct_ptr detailed_answer /* OUT */ 916 ); 918 5.3 gaa_allocate_sec_context routine 920 Purpose: 921 Allocate a security context data structure and assign default values 923 Parameters: 925 minor_status 926 Mechanism specific status code 928 acl_handle 929 A handle bound to a pointer to the security context structure 931 Function value: 933 GAA API status code: 935 GAA_SUCCESS 936 Successful completion 938 GAA_FAILURE 939 Failure, see minor_status for more information 941 gaa_error_code 942 gaa_allocate_sec_context 943 (int* minor_status, /* OUT */ 944 gaa_sec_context_ptr* sec_context_handle /* IN&OUT */); 946 Ryutov/Neuman Expires February 1999 948 5.4 gaa_release_sec_context routine 950 Purpose: 952 Delete a security context. The gaa_delete_sec_context routine will 953 delete the local data structures associated with the specified 954 security context. 956 Parameters: 958 minor_status 959 Mechanism specific status code 961 sec_context_handle 962 A handle bound to a pointer to the security context structure 964 Function value: 966 GAA status code: 968 GAA_SUCCESS 969 Successful completion 971 GAA_FAILURE 972 Failure, see minor_status for more information 974 gaa_error_code 975 gaa_release_sec_context 976 (int* minor_status, /* OUT */ 977 gaa_sec_context_ptr* sec_context_handle /* IN */) 979 5.5 gaa_allocate_buffer routine 981 Purpose: 982 Allocate a gaa_buffer data structure and assign default 983 values 985 Parameters: 987 minor_status 988 Mechanism-specific status code 990 buffer 991 Pointer to allocated memory for gaa_buffer structure 993 Function value: 995 GAA status code: 997 GAA_SUCCESS 998 Successful completion 1000 GAA_FAILURE 1002 Ryutov/Neuman Expires February 1999 1004 Failure, see minor_status for more information 1006 GAA_NO_BUFFER 1007 No valid buffer was supplied 1009 gaa_error_code 1010 gaa_allocate_buffer 1011 (int* minor_status, /* OUT */ 1012 gaa_buffer_ptr* buffer /* IN */); 1014 5.6 gaa_release_buffer routine 1016 Purpose: 1018 Free storage associated with a buffer format name. The storage must 1019 have been allocated by a GAA API routine. In addition to freeing the 1020 associated storage, the routine will zero the length field in the 1021 buffer parameter. 1023 Parameters: 1025 minor_status 1026 Mechanism-specific status code 1028 Ryutov/Neuman Expires February 1999 1030 buffer 1031 The storage associated with the buffer will be deleted. 1032 The gaa_buffer object will not be freed, but its length field will 1033 be zeroed. 1035 Function value: 1037 GAA status code: 1039 GAA_SUCCESS 1040 Successful completion 1042 GAA_FAILURE 1043 Failure, see minor_status for more information 1045 GAA_NO_BUFFER 1046 No valid buffer was supplied 1048 gaa_error_code 1049 gaa_release_buffer (int * minor_status, /* OUT */ 1050 gaa_buffer_ptr buffer /* IN */); 1052 5.7 gaa_allocate_tag_value_list routine 1054 Purpose: 1055 Allocate a gaa_tag_value_list data structure and assign default values 1057 Ryutov/Neuman Expires February 1999 1059 Parameters: 1061 minor_status 1062 Mechanism-specific status code 1064 buffer 1065 Pointer to allocated memory for gaa_tag_value_list structure 1067 Function value: 1069 GAA status code: 1071 GAA_SUCCESS 1072 Successful completion 1074 GAA_FAILURE 1075 Failure, see minor_status for more information 1077 GAA_NO_BUFFER 1078 No valid buffer was supplied 1080 gaa_error_code 1081 gaa_allocate_tag_value_list 1082 (int* minor_status, /* OUT */ 1083 gaa_tag_value_list_ptr* buffer /* IN */); 1085 5.8 gaa_release_tag_value_list routine 1087 Purpose: 1088 Free storage associated with a buffer 1090 Parameters: 1092 minor_status 1093 Mechanism-specific status code 1095 buffer 1096 The storage associated with the buffer will be deleted 1098 Function value: 1100 GAA status code: 1102 GAA_SUCCESS 1103 Successful completion 1105 GAA_FAILURE 1106 Failure, see minor_status for more information 1108 GAA_NO_BUFFER 1109 No valid buffer was supplied 1111 gaa_error_code 1113 Ryutov/Neuman Expires February 1999 1115 gaa_release_buffer 1116 (int* minor_status, /* OUT */ 1117 gaa_tag_value_list_ptr* buffer /* IN */); 1119 5.9 gaa_allocate_tag_vector_list routine 1121 Purpose: 1122 Allocate a gaa_tag_vector_list data structure and assign default 1123 values 1125 Parameters: 1127 minor_status 1128 Mechanism-specific status code 1130 buffer 1131 Pointer to allocated memory for gaa_tag_vector_list structure 1133 Function value: 1135 GAA status code: 1137 GAA_SUCCESS 1138 Successful completion 1140 GAA_FAILURE 1142 Failure, see minor_status for more information 1144 GAA_NO_BUFFER 1145 No valid buffer was supplied 1147 gaa_error_code 1148 gaa_allocate_tag_vector_list 1149 (int * minor_status, /* OUT */ 1150 gaa_tag_vector_list_ptr* buffer /* IN */); 1152 5.10 gaa_release_tag_vector_list routine 1154 Purpose: 1155 Free storage associated with a buffer 1157 Parameters: 1159 minor_status 1160 Mechanism-specific status code 1162 buffer 1163 The storage associated with the buffer will be deleted 1165 Function value: 1167 Ryutov/Neuman Expires February 1999 1169 GAA status code: 1171 GAA_SUCCESS 1172 Successful completion 1174 GAA_FAILURE 1175 Failure, see minor_status for more information 1177 GAA_NO_BUFFER 1178 No valid buffer was supplied 1180 gaa_error_code 1181 gaa_release_tag_vector_list 1182 (int* minor_status, /* OUT */ 1183 gaa_tag_vector_ptr* buffer /* IN */); 1185 5.11 gaa_parse_acl routine 1187 Purpose: 1188 Parse the ASCII file in the pre-defined format described in 1189 draft-ietf-cat-acc-cntrl-frmw-00.txt into the GAA API internal ACL 1190 structures. 1192 Parameters: 1194 minor_status 1195 Mechanism-specific status code 1197 acl_file_handle 1198 A pointer to an ASCII file containing an ACL for the object in 1199 the pre-defined format 1201 acl_handle 1202 A handle to the gaa_acl structure 1204 application_access_rights 1205 A pointer to the list of application-specific names for access 1206 rights. GAA API uses it to build bit-vectors for internal access 1207 rights representation. 1208 This parameter is optional. It is not required if the ACL contains 1209 bit-vector representation of the access rights, for example: 1211 USER kerberos.v5 joe@ISI.EDU 1212 < FILE : 1100000000000000000000000000000000 > time_window : 7AM-7PM 1213 time_day : Mon-Fri 1214 < ACCOUNT : 1100000000000000000000000000000000 >location : *.isi.edu ; 1216 In this case the value is set to GAA_NO_TAG_VALUE_LIST. 1218 Function value: 1220 GAA status code: 1222 GAA_SUCCESS 1223 Successful completion 1225 Ryutov/Neuman Expires February 1999 1227 GAA_FAILURE 1228 Failure, see minor_status for more information 1230 gaa_error_code 1231 gaa_parse_acl 1232 (int * minor_status, /* OUT */ 1233 FILE *acl_file_handle, /* IN */ 1234 gaa_acl_ptr* acl_handle, /* IN&OUT */ 1235 gaa_tag_value_list_ptr application_access_rights /* IN, OPTIONAL */); 1237 6. The GAA API constants 1239 The following constants are used in GAA API calls and structures, 1240 this list is not complete: 1242 #define GAA_NO_BUFFER ((gaa_buffer_ptr) 0) 1243 #define GAA_EMPTY_BUFFER {0, NULL} 1244 #define GAA_NO_DATA ((gaa_data_ptr)0) 1245 #define GAA_NO_TAG_VALUE_LIST ((gaa_tag_value_list_ptr)0) 1247 #define GAA_ACL_UNBOUND ((gaa_acl_ptr)0) 1248 #define NO_EACL_ENTRY ((gaa_acl_entry_ptr) 0) 1249 #define NO_PRINCIPALS ((gaa_acl_principal_list_ptr) 0) 1250 #define NO_ACCESS_RIGHTS ((gaa_acl_access_rights_set_ptr) 0) 1251 #define GAA_NO_CONDITIONS ((gaa_conditions_ptr)0) 1253 7. The GAA API flags 1255 Flags are 32 bits. 1257 Condition flags: 1259 #define COND_FLG_EVALUATED 0x80000000 1260 #define COND_FLG_SATISFIED 0x40000000 1261 #define COND_FLG_ENFORCE 0x20000000 1263 Flags from 0x10000000 to 0x00000001 are reserved. 1265 8. Acknowledgments 1267 Gene Tsudik, Brian Tung, Bapa Rao, Ilia Ovsiannikov and the Xerox IS 1268 team have contributed to discussion of ideas and material in this 1269 draft. 1271 9. References 1273 [1] Linn, J., "Generic Security Service Application Program 1274 Interface", RFC 1508, Geer Zolot Associate, September 1993. 1276 [2] Wray, ., "Generic Security Service Application Program 1277 Interface V2 - C bindings", Internet draft, May 1997. 1279 10. Authors' Addresses 1281 Ryutov/Neuman Expires February 1999 1283 Tatyana Ryutov 1284 Clifford Neuman 1285 USC/Information Sciences Institute 1286 4676 Admiralty Way Suite 1001 1287 Marina del Rey, CA 90292-6695 1288 Phone: +1 310 822 1511 1289 E-Mail: {tryutov, bcn}@isi.edu