idnits 2.17.1 draft-ietf-cat-gaa-cbind-05.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 2137 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 104 instances of weird spacing in the document. Is it really formatted ragged-right, rather than justified? ** There are 155 instances of too long lines in the document, the longest one being 10 characters in excess of 72. ** There are 11 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 737: '... *params /* IN & OUT, OPTIONAL */);...' Miscellaneous warnings: ---------------------------------------------------------------------------- == Line 211 has weird spacing: '... int prior...' == Line 212 has weird spacing: '... int num; ...' == Line 213 has weird spacing: '...ght_ptr right...' == Line 215 has weird spacing: '..._struct gaa_p...' == Line 238 has weird spacing: '...ht_type type;...' == (99 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 (November 22, 2000) is 8549 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? '1' on line 2093 looks like a reference -- Missing reference section? '2' on line 2096 looks like a reference -- Missing reference section? '3' on line 2099 looks like a reference -- Missing reference section? '4' on line 2102 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 April 2001 Laura Pearlman 4 draft-ietf-cat-gaa-cbind-05.txt USC/Information Sciences Institute 5 November 22, 2000 7 Generic Authorization and Access control Application Program Interface 8 C-bindings 10 0. Status Of this Document 12 This document is an Internet-Draft and is in full conformance 13 with all provisions of Section 10 of RFC2026. 15 Internet-Drafts are working documents of the Internet Engineering 16 Task Force (IETF), its areas, and its working groups. Note that 17 other groups may also distribute working documents as Internet-Drafts. 19 Internet-Drafts are draft documents valid for a maximum of six 20 months and may be updated, replaced, or obsoleted by other 21 documents at any time. It is inappropriate to use Internet-Drafts 22 as reference material or to cite them other than as 23 "work in progress." 25 The list of current Internet-Drafts can be accessed at 26 http://www.ietf.org/ietf/1id-abstracts.txt 28 The list of Internet-Draft Shadow Directories can be accessed at 29 http://www.ietf.org/shadow.html. 31 To view the entire list of current Internet-Drafts, please check 32 the "1id-abstracts.txt" listing contained in the Internet-Drafts 33 Shadow Directories on ftp.is.co.za (Africa), ftp.nordu.net 34 (Northern Europe), ftp.nis.garr.it (Southern Europe), munnari.oz.au 35 (Pacific Rim), ftp.ietf.org (US East Coast), or ftp.isi.edu 36 (US West Coast). 38 1. Abstract 40 The Generic Authorization and Access control Application Programming 41 Interface (GAA-API) provides access control services to calling 42 applications. It facilitates access control decisions for 43 applications and allows applications to discover access control 44 policies associated with a targeted resource. The GAA-API is usable by 45 multiple applications 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-05.txt 58 2. GAA-API concepts and typical usage 60 A simple GAA application will do the following: 62 a) Perform some initialization at the beginning to create a gaa control 63 structure and security context. 65 The gaa control structure (type gaa_ptr) includes information about 66 callback routines (to be used to evaluate conditions, find policy 67 information, etc.). Callback routines may be installed in this structure 68 by the GAA-API implementation itself (when the gaa_ptr structure is 69 created) or explicitly by the application (at any time). 71 The security context (type gaa_sc_ptr) contains information about the 72 current user's credentials. Credentials may be added to this structure 73 by the GAA-API implementation itself (in the course of evaluating 74 conditions) or explicitly by the application (at any time). 76 b) Each time the application receives a request, it will determine 77 what rights are necessary to fulfill that request and then call 78 GAA-API routines to create a list of requested rights, find the 79 relevant policy, and determine whether or not the policy grants 80 those rights. 82 Each requested right is of type gaa_request_right, which includes 83 a value and defining authority (the authority determines the namespace 84 of the value). The list of requested rights is created with the 85 gaa_new_req_rightlist function, and rights are added to the list with 86 gaa_add_request_right. A request right may also include a list 87 of options (additional information about the request, to be used 88 as hints when evaluating conditions); the gaa_add_option function 89 may be used to add options to a request right. 91 A policy is an ordered list of policy rights. A policy right 92 consists of a type (pos_access_right for a right that's explicitly 93 allowed; neg_access_right for a right that's explicitly denied), 94 a value and defining authority, and a list of conditions under 95 which the policy right applies. 97 A condition consists of a type (e.g,. user identity, time of day, etc.), 98 a value and a defining authority (which determines the namespace of the 99 value). In a typical request, the policy will be retrieved with 100 gaa_get_object_policy_info. 102 The gaa_check_authorization function is used to determine whether the 103 requested rights are granted or denied by the policy. This function 104 evaluates each requested right (finding the relevant policy rights and 105 calling the appropriate condition-evaluation callback routines to see 106 whether they apply) and then aggregates the results: if all requested 107 rights are granted, gaa_check_authorization returns GAA_C_YES; if any 108 requested right is denied, it returns GAA_C_NO; otherwise, it returns 109 GAA_C_MAYBE. A detailed answer structure is also returned, including 110 the relevant policy information. 112 c) When the application is finished using GAA-API, it will call cleanup 113 routines to release resources. 115 3. GAA-API data types 117 3.1. Character data 119 Certain data items used by the GAA-API may be regarded as a character 120 strings, e.g., string-encoded tokens for passing object and 121 authorization database identifiers. The data of this kind is passed 122 between the GAA-API and caller using the gaa_string_data data type, 123 which is a pointer to a null-terminated character array: 125 typedef char *gaa_string_data; 127 3.2. GAA-API status codes 129 Most GAA-API functions return a value of type gaa_status: 131 unsigned long gaa_status; 133 Encapsulated in the returned status code are major and minor status 134 codes. Each of them has a value range equivalent to 16 bit unsigned 135 integer values. The major code is in low 16 bits, the minor code is 136 in high 16 bits. The major codes indicate errors that are independent 137 of the underlying mechanisms. The errors that can be indicated via a 138 GAA-API major status code are generic API routine errors (errors that 139 are defined in this specification). 141 The minor code is implementation-dependent and is used to indicate 142 specialized errors from the underlying mechanisms or provide 143 additional information about the GAA-API errors. 145 A list of GAA-API status codes and their values appears in 146 section 5 of this document. 148 3.3. Application-opaque data types 150 3.3.1. The gaa control structure 152 The gaa control structure (which includes information about the behavior 153 of GAA-API) is opaque to the application: 155 typedef struct gaaint_gaa *gaa_ptr; 157 and is maintained using the callback-registering functions described 158 in section 4.3. 160 3.3.2. The security context 162 The gaa security context (which includes information about a user's 163 credentials) is opaque to the application: 165 typedef struct gaaint_sc *gaa_sc_ptr; 167 and is maintained using the credential-handling functions described in 168 section 4.1.2. 170 3.3.3. List data structures 172 Certain data items used by the GAA-API may be regarded as an ordered list of 173 data items, e.g., a list of request rights. These lists are represented 174 by the opaque gaa_list_ptr data type; individual entries in these lists 175 are represented by the opaque gaa_list_entry_ptr data type: 177 typedef struct gaaint_list *gaa_list_ptr; 178 typedef struct gaaint_list_entry *gaa_list_entry_ptr; 180 The functions described in section 4.6 are used to examine and free 181 lists and list entries. 183 3.4 Policy data structures 185 3.4.1 gaa_policy 187 The gaa_policy structure describes a policy: 189 struct gaa_policy_struct { 190 void *raw_policy; /* raw policy representation */ 191 gaa_list_ptr entries; /* list of gaa_policy_entry_ptr */ 192 gaa_freefunc freeraw; /* function to free raw_policy */ 193 struct gaaint_policy *intrl; /* internal data */ 194 }; 195 typedef struct gaa_policy_struct gaa_policy, *gaa_policy_ptr; 197 The raw_policy field is an application-specific representation of the 198 policy. It may be null, or it may contain, for example, a textual 199 representation of the policy or the address of a policy server to 200 query. The entries field is an ordered list of GAA-API policy rights. 201 If freeraw field is non-null, that function is called to free the 202 raw_policy entry when the policy structure is freed. The intrl field 203 is internal to the GAA-API implementation and should be ignored by the 204 application. 206 3.4.2 gaa_policy_entry 208 The gaa_policy_entry structure describes a policy entry: 210 struct gaa_policy_entry_struct { 211 int priority; /* entry priority */ 212 int num; /* entry number (for order within priority) */ 213 gaa_policy_right_ptr right; /* what this entry grants (or denies) */ 214 }; 215 typedef struct gaa_policy_entry_struct gaa_policy_entry, 216 *gaa_policy_entry_ptr; 218 The priority and num fields are used to order the entries in a policy 219 (lower-numbered priorities come before higher-numbered priorities; 220 within a priority, lower-numbered entries come before higher-numbered 221 ones). The right field indicates the right that is granted or denied 222 by this policy entry. 224 3.4.3. gaa_policy_right and gaa_right_type 226 The gaa_right_type enumeration distinguishes positive policy rights 227 (rights which are explicitly granted) from negative policy rights 228 (rights which are explicitly denied): 230 typedef enum { 231 pos_access_right, 232 neg_access_right 233 } gaa_right_type; 235 The gaa_policy_right structure describes a policy right: 237 struct gaa_policy_right_struct { 238 gaa_right_type type; /* positive or negative */ 239 gaa_string_data authority; /* defining authority */ 240 void *value; /* within namespace defined by authority */ 241 gaa_list_ptr conditions; /* list of gaa_condition_ptr describing 242 the conditions that must be met */ 243 struct gaaint_policy_right *intrl; /* internal data */ 244 }; 246 typedef struct gaa_policy_right_struct gaa_policy_right, 247 *gaa_policy_right_ptr; 249 The type field defines the type of the policy (pos_access_right 250 indicates that the policy grants this right; neg_access_right 251 indicates that the policy denies it). 253 The authority field indicates the authority responsible for defining 254 the value. The value field is a representation of the value (or values) of 255 the right, within the namespace defined by the authority. 257 The conditions field is a pointer to an ordered list of elements of 258 type gaa_condition_ptr. It contains a list of pointers to conditions 259 associated with the right. 261 The intrl field is internal to the GAA-API implementation and should 262 be ignored by the application. 264 3.4.4. gaa_condition 266 The gaa_condition structure describes a condition: 268 struct gaa_condition_struct { 269 gaa_string_data type; /* condition type */ 270 gaa_string_data authority; /* defining authority */ 271 gaa_string_data value; /* within namespace defined by authority */ 272 unsigned long status; /* GAA_COND_EVALUATED, GAA_COND_MET, etc. */ 273 struct gaaint_cond *intrl; /* internal data */ 274 }; 275 typedef struct gaa_condition_struct gaa_condition, *gaa_condition_ptr; 277 The type field defines the type of condition (e.g. user_id, time, etc.). 278 The authority field indicates the authority responsible for defining the 279 value (e.g. kerberos, x509, etc.). The value field is the condition value 280 (e.g. a username) within the namespace defined by the authority. 282 The status field contains flags indicating whether the condition has 283 been evaluated and/or met. 285 The intrl field is internal to the GAA-API implementation and should 286 be ignored by the application. 288 3.5 Request rights 290 Request rights are similar to, but different from, policy rights. 291 Request rights do not have a "type" element (as it makes no sense 292 to request a negative right) or conditions. And while the value of 293 a policy right can represent multiple rights, the value of a request 294 right can represent only a single right. 296 3.5.1. gaa_request_right 298 The gaa_request_right structure describes a requested right: 300 struct gaa_request_right_struct { 301 gaa_string_data authority;/* defining authority */ 302 void *value; /* within namespace defined 303 by authority */ 304 gaa_list_ptr options; /* list of gaa_request_option */ 305 struct gaaint_request_right *intrl; /* internal data */ 306 }; 308 typedef struct gaa_request_right_struct gaa_request_right, 309 *gaa_request_right_ptr; 311 The authority field indicates the authority responsible for defining 312 the value. The value field is a representation of the value of the right, 313 within the namespace defined by the authority. 315 The options field is a list of elements of type gaa_request_option. 316 It contains a list of pointers to parameters associated with the 317 request right. 319 The intrl field is internal to the GAA-API implementation and should 320 be ignored by the application. 322 3.5.2 gaa_request_option 324 The gaa_request_option stucture is used to provide hints for condition 325 evaluation functions. When an authorization request is made to 326 GAA-API, the condition-evaluation functions are passed a pointer to 327 the requested right, which may contain a list of options. The 328 condition-evaluation function can then look through the list of 329 options to find any that are relevant. For example, if a condition 330 requires that "file size must be less than 10k", then a 331 condition-evaluation function for that condition could check to see 332 whether there was a "file size" option in the request (if there was, 333 the function can return yes or no based on the option's value; if 334 there wasn't, that function must return maybe). 336 struct gaa_request_option { 337 gaa_string_data type; /* option type */ 338 gaa_string_data authority; /* defining authority */ 339 gaa_string_data value; /* within namespace defined 340 by authority */ 341 struct gaaint_request_option *intrl; /* internal data */ 342 }; 344 The type field defines the type of the option. The authority field 345 indicates the authority responsible for defining the value, and the 346 value indicates the value of the token (within the namespace defined 347 by the authority field). 349 The intrl field is internal to the GAA-API implementation and should 350 be ignored by the application. 352 3.6 Credentials 354 GAA-API recognizes several types of credentials, which it maintains 355 in a common credential structure. 357 3.6.1. gaa_cred_type 359 The gaa_cred_type enumeration describes the different types of 360 credentials: 362 typedef enum { 363 GAA_IDENTITY, /* user identity */ 364 GAA_GROUP_MEMB, /* group membership */ 365 GAA_GROUP_NON_MEMB, /* group non-membership */ 366 GAA_AUTHORIZED, /* authorized credential (capability) */ 367 GAA_ATTRIBUTES, /* attribute credential */ 368 GAA_UNEVAL, /* unevaluated (raw) credential */ 369 GAA_ANY 370 } gaa_cred_type; 372 3.6.2. gaa_principal 374 The gaa_principal structure describes a principal (an authenticated 375 entity): 377 struct gaa_principal_struct { 378 gaa_cred_type type; /* credential type */ 379 gaa_string_data authority; /* defining meaning of token value */ 380 gaa_string_data value; /* value (in namespace defined 381 by authority) */ 382 }; 383 typedef struct gaa_principal_struct gaa_principal, *gaa_principal_ptr; 385 The type entry indicates the credential type (identity, group, etc.). 386 The authority field indicates the defining authority (e.g. kerberos, 387 x509), and the value field indicates the value within the namespace 388 defined by the authority. 390 3.6.3 gaa_cred 392 The gaa_cred structure is the GAA-API credential data type: 394 struct gaa_cred_struct { 395 gaa_cred_type type; 396 gaa_principal_ptr grantor; 397 gaa_principal_ptr principal; 398 void *mech_spec_cred; /* raw credential */ 399 struct gaaint_mechinfo *mechinfo; /* functions to handle raw creds */ 400 union { 401 gaa_identity_info_ptr id_info; 402 gaa_authr_info_ptr authr_info; 403 gaa_attribute_ptr attr_info; 404 } info; 405 }; 407 typedef struct gaa_cred_struct gaa_cred, *gaa_cred_ptr; 409 The type field indicates the type of credential. The grantor field 410 should list the entity that granted the credential. The principal 411 field should list the entity that the credential is for. The 412 mech_spec_cred field is the raw, mechanism-specific credential. 413 The mechinfo field is a pointer to an application-opaque list of 414 callback functions to be used on this credential and should be ignored 415 by the application. The meaning of the info field depends on the 416 credential type; if the type is GAA_IDENTITY, GAA_GROUP_MEMB, or 417 GAA_GROUP_NON_MEMB, then the id_info field should be filled in. If 418 the type is GAA_AUTHORIZED, then the authr_info field should be filled 419 in. If the type is GAA_ATTRIBUTES, the attr_info field should be filled in. 421 3.6.4. gaa_identity_info 423 The gaa_identity_info structure is composed of information specific to 424 identity credentials: 426 struct gaa_identity_info_struct { 427 gaa_list_ptr conditions; /* list of gaa_condition_ptr describing 428 validity constraints */ 429 }; 431 typedef struct gaa_identity_info_struct gaa_identity_info, 432 *gaa_identity_info_ptr; 434 The conditions field is a pointer to an ordered list of elements of 435 the type gaa_condition_ptr, which lists restrictions placed on the 436 identity, e.g., validity time periods. 438 Note: the gaa_identity_info structure doesn't contain any "identity" 439 information, because that information is kept in the common area 440 of the gaa_cred structure. 442 3.6.5. gaa_authr_info 444 The gaa_authr_info structure contains information specific to 445 authorized credentials (capabilities): 447 struct gaa_authr_info_struct { 448 void *objects; 449 gaa_list_ptr /* gaa_policy_right_ptr */ access_rights; 450 gaa_freefunc free_objects; 451 }; 452 typedef struct gaa_authr_info_struct gaa_authr_info, *gaa_authr_info_ptr; 454 The objects field is a list of object references to the application-level 455 objects accessible by the grantee, e.g. files or hosts. Object references 456 are from the application-specific name space. 458 The access_rights field is a pointer to a list of elements of the 459 type gaa_right_ptr. Each element indicate granted or denied access rights. 461 The free_objects field is a pointer to a function to be called to free 462 the objects field when the gaa_authr_info structure is freed. This 463 field may be 0, in which case no function will be called. 465 3.6.6 gaa_attribute_info 467 The gaa_attribute_info structure contains information specific to 468 attribute credentials (credentials that certify that the bearer 469 has some specific attribute): 471 struct gaa_attribute_info_struct { 472 gaa_string_data type; 473 gaa_string_data authority; 474 gaa_string_data value; 475 gaa_list_ptr /* gaa_condition_ptr */ conditions; 476 }; 478 typedef struct gaa_attribute_info_struct gaa_attribute_info, 479 *gaa_attribute_info_ptr; 481 The type entry indicates the attribute type (e.g. height, birthdate, 482 etc.). The authority field indicates the defining authority, and the 483 value field indicates the value within the namespace defined by the 484 authority. The conditions field is a list of conditions that must be 485 met in order for the credential to be considered valid. 487 3.7 Authorization answer structure 489 The gaa_check_authorization function fills in a detailed answer structure. 491 3.7.1 gaa_time_period 493 The gaa_time_period structure describes a time period: 495 struct gaa_time_period_struct { 496 time_t start_time; /* NULL for unconstrained start time */ 497 time_t end_time; /* NULL for unconstrained end time */ 498 }; 499 typedef struct gaa_time_period_struct gaa_time_period, 500 *gaa_time_period_ptr; 502 3.7.2 gaa_answer 504 The gaa_answer structure is the detailed answer from gaa_check_authorization: 506 struct gaa_answer_struct 507 { 508 gaa_time_period_ptr valid_time; 509 gaa_list_ptr /* gaa_right_ptr */ rights; 510 }; 511 typedef struct gaa_answer_struct gaa_answer, *gaa_answer_ptr; 513 If the answer was GAA_C_YES, valid_time is the time period for which 514 the answer is valid. The rights field is a list of policy rights that 515 were relevant to the request, with the appropriate evaluated/met flags 516 filled in. 518 3.8 Function and callback types 520 GAA-API makes heavy use of callback functions. The GAA-API callback 521 registration model includes three things for each type of callback: a 522 function (or set of related functions), an application-controlled 523 parameter (opaque to the GAA implementation) that is passed to the 524 function(s) each time they are called (to be used to provide operating 525 parameters and/or maintain state information), and a function to be 526 used to free that application-controlled parameter when the 527 application determines that the callback will no longer be needed. 529 3.8.1 gaa_freefunc 531 The gaa_freefunc type is used for a function to be used to free arbitrary data. 533 typedef void (*gaa_freefunc)(void *data); 535 3.8.2 Condition-evaluation callbacks 537 3.8.2.1. gaa_cond_eval_func 539 typedef gaa_status (*gaa_cond_eval_func)(gaa_ptr gaa, 540 gaa_sc_ptr sc, 541 gaa_condition_ptr condition, 542 gaa_time_period_ptr valid_time, 543 gaa_list_ptr req_options, 544 gaa_status *output_flags, 545 void *params); 547 A function of this type should accept the gaa, sc, and condition 548 arguments as input (the condition argument being the condition to 549 evaluate, and the gaa and sc arguments used to find other callback 550 functions and credentials). The req_options argument is an input 551 list of gaa_request_option options that the condition may examine 552 if it chooses to, and the params argument is the optional callback 553 parameter (see gaa_new_cond_eval_callback in section 4.3.1.1). 555 The output_flags and valid_time arguments are output parameters. 556 The function should set output_flags to the appropriate combination of 557 the GAA_COND_FLG_EVALUATED, GAA_COND_FLG_MET, and GAA_COND_FLG_ENFORCE 558 flags. 559 It should interpret the valid_time 560 pointer as an output parameter (if the condition imposes time 561 restrictions, the callback function should set the beginning and 562 ending times to whatever the condition restricts them to). 564 Functions of this type are used by gaa_check_authorization (see 565 section 4.2.3.1), gaa_check_condition (see section 4.4.3.1), and 566 gaa_inquire_policy_info (see section 4.2.3.2). 568 3.8.2.2. gaa_cond_eval_callback_ptr 570 typedef struct gaaint_cond_eval_callback *gaa_cond_eval_callback_ptr; 572 This is an application-opaque structure to represent a condition evaluation 573 callback. 575 Note: section 4.3.1 describes functions to create and register 576 condition-evaluation callbacks. 578 3.8.3 Functions to manipulate raw (mechanism-specific) credentials 580 3.8.3.1. gaa_cred_pull_func type 582 typedef int (*gaa_cred_pull_func)(gaa_ptr gaa, 583 gaa_sc_ptr sc, 584 gaa_cred_type which, 585 void *params); 587 A function of this type should pull raw credentials of the type 588 specified by "which" (or all types, if "which" is GAA_ANY) and add 589 them to the security context sc. The function may use the gaa to find 590 other callbacks if appropriate. The params argument is the optional 591 callback-specific parameter (see gaa_add_mech_info in section 4.3.2). 592 Functions of this type are called by gaa_pull_creds (see section 4.4.3.2). 594 3.8.3.2. gaa_cred_eval_func type 596 typedef int (*gaa_cred_eval_func)(gaa_ptr gaa, 597 gaa_sc_ptr sc, 598 gaa_cred_ptr cred, 599 void *raw, 600 void *params); 602 A function of this type should take a raw mechanism-specific credential 603 and fill in the appropriate values in the credential cred (in the process, 604 it should create one of the credential entries in the cred->info union). 605 The gaa and sc arguments are input arguments, and "params" is the optional 606 callback-specific parameter (see gaa_add_mech_info in section 4.3.2). 607 Functions of this type are called by gaa_new_cred (see section 4.1.2.2) to 608 evaluate credentials. 610 3.8.3.3. gaa_cred_verify_func type 612 typedef int (*gaa_cred_verify_func)(gaa_cred_ptr cred, 613 void *params); 615 A function of this type should take an evaluated gaa credential and 616 verify that it is still valid (i.e. that the raw credential is still 617 valid and still corresponds to the values listed for its grantor, 618 principal, etc.). The "params" argument is the optional 619 callback-specific parameter (see gaa_add_mech_info in section 4.3.2). 620 Functions of this type are used by gaa_verify_cred (see section 4.4.3.3). 622 3.8.4. Callback to get policy information 624 typedef int (*gaa_getpolicy_func)(gaa_ptr gaa, 625 gaa_policy_ptr *policy, 626 gaa_string_data object, 627 void *params); 629 A function of this type should take a gaa pointer, an object name, and an 630 optional pointer to application-specific parameters, and create an output 631 policy structure containing all the policy information that relates to 632 that object. 634 The getpolicy callback is registered with gaa_set_getpolicy_callback 635 (see section 4.3.3) and used by gaa_get_object_policy_info (see section 636 4.2.2). 638 3.8.5 Functions to override GAA default behavior 640 Each GAA-API implementation has default internal representations of 641 policy right values and request right values and a default function to 642 determine which policy rights match a request right. Most 643 applications can simply use these defaults (and ignore everything in 644 this section); however, GAA-API provides callbacks to override them. 646 3.8.5.1 Callback to find the subset of a policy that applies to 647 a requested right. 649 typedef int (*gaa_matchrights_func)(gaa_ptr gaa, 650 gaa_policy_ptr inpolicy, 651 gaa_request_right_ptr right, 652 gaa_policy_ptr outpolicy, 653 void *params); 655 A function of this type should take a gaa pointer, an input policy 656 (inpolicy), and an input requested right, and fill in an output 657 policy with those entries from the input policy (in the same order) 658 that apply to the requested right. The gaa_set_matchrights_callback 659 function (see section 4.3.4) is used to set this callback. 661 3.8.5.2. Function types associated with the internal representation 662 of right values ("valinfo" functions). These callbacks are registered 663 using gaa_add_authinfo (see section 4.3.5). 665 3.8.5.2.1. gaa_copyval_func 667 typedef gaa_status (*gaa_copyval_func)(void **newval, 668 gaa_string_data authority, 669 void *oldval, 670 void *params); 672 Functions of this type should take a defining authority, a right value 673 ("oldval"), and optional callback parameters ("params"), and create a 674 new value ("newval") that's a duplicate of the original value ("oldval"). 676 3.8.5.2.2. gaa_string2val_func 678 typedef gaa_status (*gaa_string2val_func)(void **val, 679 gaa_string_data authority, 680 gaa_string_data valstr, 681 void *params); 683 Functions of this type should take a defining authority, an input 684 string ("valstr"), and optional callback parameters ("params"), and 685 create a new value ("val") containing an internal representation of 686 that string. 688 3.8.5.2.3. gaa_val2string_func 690 typedef char *(*gaa_val2string_func)(gaa_string_data authority, 691 void *val, 692 gaa_string_data buf, 693 int bsize, 694 void *params); 696 Functions of this type should take a defining authority, a right value 697 ("val"), a buffer ("buf") of size bsize, and optional callback 698 parameters ("params"), and return a character-string representation of 699 that value. These functions are not required to write the 700 character-string representation into the supplied buffer. 702 3.8.5.2.4. gaa_valmatch_func 704 typedef int (*gaa_valmatch_func)(gaa_string_data authority, 705 void *rval, 706 void *pval, 707 void *params); 709 Functions of this type should take a defining authority, an input 710 request right ("rval"), and input policy right ("pval"), and optional 711 callback parameters ("params"), and return 1 if the request right 712 matches the policy right and 0 otherwise. 714 3.8.5.2.5. gaa_valinfo_ptr 716 The gaa_valinfo_ptr is an application-opaque data type used to register 717 functions of the types described in this section as callbacks: 719 typedef struct gaaint_valinfo *gaa_valinfo_ptr; 721 4. GAA-API functions 723 Unless otherwise noted, all GAA-API routines return GAA_S_SUCCESS on 724 success and one of the error codes defined in section 5 on failure. 726 4.1 Initialization functions 728 4.1.1 gaa_initialize 730 The gaa_initialize function must be called before any other GAA-API function. 731 It initializes the GAA-API structures and sets up the default behavior 732 of GAA-API routines. (The default behaviors can be modified later using 733 the GAA-API callback registration routines in section 4.3). 735 gaa_status 736 gaa_initialize(gaa_ptr *gaa, /* OUT */ 737 void *params /* IN & OUT, OPTIONAL */); 739 Parameters: 740 gaa 741 A pointer to the gaa structure that will be allocated an initialized. 743 params 744 A handle to an implementation-specific structure, containing 745 initialization information. Can be used to return 746 implementation-specific output information. 748 A gaa structure created with gaa_initialize should later be freed 749 using gaa_cleanup (see section 4.8). 751 4.1.2 Routines to keep track of credentials 753 The security context contains information about credentials. An 754 application will typically create a security context with gaa_new_sc, 755 then create credentials with gaa_new_cred and add them to the 756 security context with gaa_add_cred. 758 4.1.2.1. gaa_new_sc 760 The gaa_new_sc routine allocates an empty gaa_sc data structure. 762 gaa_status 763 gaa_new_sc(gaa_sc_ptr *sc /* OUT */); 765 Parameters: 766 sc 767 A pointer to the security context to be allocated. 769 A structure created using this function should be freed using gaa_free_sc 770 (see section 4.8). 772 4.1.2.2. gaa_new_cred 774 The gaa_new_cred routine creates a new credential and fills it in with 775 appropriate values. 777 gaa_status gaa_new_cred (gaa_ptr gaa, 778 gaa_sc_ptr sc, 779 gaa_cred_ptr *cred, 780 gaa_string_data mech_type, 781 void *mech_spec_cred, 782 gaa_cred_type cred_type, 783 int evaluate, 784 gaa_status *estat) 786 Parameters: 787 gaa input gaa pointer 788 sc input security context 789 mech_type input credential mechanism type 790 mech_spec_cred input raw credential 791 cred_type input credential type (identity, group, etc.). 792 evaluate input flag -- if nonzero, the credential is 793 evaluated (i.e. the appropriate cond_eval callback 794 is called) 795 estat output -- if evaluate and estat are both nonzero, 796 then estat is set to the return value of the 797 cond_eval function. 799 A credential created using this function should be freed with 800 gaa_free_cred (see section 4.8). 802 4.1.2.3 gaa_add_cred 804 The gaa_add_cred routine adds a credential to a security context. 806 gaa_status gaa_add_cred (gaa_ptr gaa, 807 gaaint_sc_ptr sc, 808 gaa_cred_ptr cred) 810 Add a credential to a security context. 812 Parameters: 813 gaa input gaa pointer 814 sc input/output security context. 815 cred input credential to add 817 4.2. Functions to evaluate an authorization request. 819 There are three steps to checking an authorization request: creating 820 a list of requested rights to represent the request, finding the 821 policy relevant to the request, and calling a routine to check the 822 requested rights against the policy. 824 4.2.1. Functions to build the list of requested rights 826 4.2.1.1. gaa_new_req_rightlist 828 The gaa_new_req_rightlist function creates an empty list of requested 829 rights: 831 gaa_list_ptr gaa_new_req_rightlist (int freerights) 833 Parameters: 834 freerights input flag to control the behavior of gaa_list_free 835 when (and if) it is called to free this list. If 836 this flag is 0, then gaa_list_free will free only 837 the list itself, not any of the rights in the list. 838 If freerights is nonzero, then both the list and all 839 the rights contained in it will be freed. 841 Return values: 842 on success, returns an empty list. 843 on failure, returns 0. 845 4.2.1.2. gaa_new_request_right 847 The gaa_new_request_right function allocates a new request right 848 structure and fill it in with the specified values. 850 gaa_status gaa_new_request_right (gaa_ptr gaa, 851 gaa_request_right_ptr *right, 852 gaa_string_data authority, 853 gaa_string_data val) 855 Parameters: 856 right output right pointer 857 authority input authority 858 val input string representation of value 860 Request rights created with this routine should be freed with 861 gaa_free_request_right(). 863 Note: some applications that use callbacks to override the GAA-API 864 implementation's default internal representation of right values 865 may wish to use gaa_new_request_right_rawval (see section 4.7.7) 866 instead of this function. 868 4.2.1.3. gaa_add_option 870 The gaa_add_option function adds an option to a request right. It 871 may be called several times to add more than one option to a right. 873 gaa_status gaa_add_option ( gaa_request_right_ptr right, 874 gaa_string_data type, 875 gaa_string_data authority, 876 void *value, 877 gaa_freefunc freeval) 879 Add an option to a request right. 881 Parameters: 882 right input/output right 883 type input option type 884 authority input option authority 885 value input option value 886 freeval optional input function to free value when the option 887 is freed (which will happen automatically when right is 888 freed with gaa_free_request_right(). 890 4.2.1.4. gaa_add_request_right 892 The gaa_add_request_right function adds a request right to a list. 894 gaa_status gaa_add_request_right (gaa_list_ptr rightlist, 895 gaa_request_right_ptr right) 897 Parameters: 898 rightlist input/output list to add right to 899 right input right to add. 901 4.2.2. Function to retrieve policy information 903 The gaa_get_object_policy_info function retrieves policy information 904 for an object. This function calls the installed getpolicy callback. 906 gaa_status gaa_get_object_policy_info ( gaa_string_data object, 907 gaa_ptr gaa, 908 gaa_policy_ptr *policy) 910 Parameters: 911 object input object to get policy for 912 gaa input gaa pointer 913 policy output policy to create 915 4.2.3. Functions to make access control decisions. 917 4.2.3.1. gaa_check_authorization 919 The gaa_check_authorization function checks whether the requested 920 rights are authorized under the specified policy. 922 gaa_status gaa_check_authorization (gaa_ptr gaa, 923 gaa_sc_ptr sc, 924 gaa_policy_ptr policy, 925 gaa_list_ptr req_rights, 926 gaa_answer_ptr answer ) 928 Parameters: 929 gaa input gaa pointer 930 sc input security context 931 policy input policy 932 req_rights input list of requested rights 933 answer output detailed answer -- lists all matching policy 934 rights and associated conditions, with flags set to 935 indicate whether each condition was evaluated and/or 936 met. If the result is GAA_C_YES, then the answer 937 includes the time period for which the result is valid 938 (if the start or end time is 0, that time is 939 indefinite). Before being passed to this function, the 940 answer structure should be created with 941 gaa_new_answer (see section 4.7.3). 943 Return values: 944 GAA_C_YES Access is granted to all requested 945 rights. 946 GAA_C_NO Access is denied for at least one 947 requested right. 948 GAA_C_MAYBE Access is not explicitly denied for any 949 requested right, but there is at least 950 one requested right that GAA cannot 951 decide. 952 GAA_S_INVALID_ARG sc, policy, answer, or gaa is null 953 GAA_S_NO_MATCHING_ENTRIES The list of requested rights is empty. 955 This function makes use of several callback routines -- the GAA-API 956 matchrights callback to determine the subset of the policy that applies 957 to the requested rights, and cond_eval callbacks to evaluate specific 958 conditions. The matchrights callback is also likely to use the valmatch 959 function from the appropriate authinfo callback(s) to determine whether 960 a specific request right matches a specific policy right. 962 4.2.3.2. gaa_inquire_policy_info 964 The gaa_inquire_policy_info function returns the subset of the input 965 policy that applies to the individual identified with the specified 966 security context. This is the union of the set of rights that do not 967 have any identity conditions with the set of rights whose identity 968 conditions all match the individual. 970 gaa_status gaa_inquire_policy_info ( gaa_ptr gaa, 971 gaa_sc_ptr sc, 972 gaa_policy_ptr policy, 973 gaa_list_ptr *out_rights ) 975 Parameters: 976 gaa input gaa pointer 977 sc input security context 978 policy input policy 979 out_rights output list of policy rights 981 The list returned in out_rights should be freed with gaa_list_free 982 (see section 4.6.4). 984 4.3. Functions to register callbacks with GAA-API. 986 4.3.1. Functions to register condition-evaluation callbacks. 988 A condition-evaluation callback is created using 989 gaa_new_cond_eval_callback and associated with a condition 990 type/authority pair using gaa_add_cond_eval_callback. 992 See section 3.8.2 for descriptions of the data types used by these 993 functions. 995 4.3.1.1. gaa_new_cond_eval_callback 997 The gaa_new_cond_eval_callback function creates a condition evaluation 998 callback. If the callback is later installed with 999 gaa_add_cond_eval_callback(), then it will be used (when appropriate) 1000 by gaa_check_authorization() and gaa_inquire_policy_info() to evaluate 1001 conditions. 1003 gaa_status gaa_new_cond_eval_callback (gaa_cond_eval_callback_ptr *cb, 1004 gaa_cond_eval_func func, 1005 void params, 1006 gaa_freefunc freeparams) 1008 Parameters: 1009 cb output callback to create. 1010 func input callback function. 1011 params input callback params -- will be passed to func whenever 1012 it's called. 1013 freeparams input function to free params when cb is freed. 1015 A callback created with this function should be freed with 1016 gaa_free_cond_eval_callback(). If a callback is added to a gaa 1017 structure with gaa_add_cond_eval_callback(), it will be freed 1018 automatically when the gaa structure is freed with gaa_free_gaa(). 1020 4.3.1.2. gaa_add_cond_eval_callback 1022 The gaa_add_cond_eval_callback function adds a condition evaluation 1023 callback, associated with the specified type and authority. 1025 gaa_status gaa_add_cond_eval_callback (gaa_ptr gaa, 1026 gaa_cond_eval_callback_ptr cb, 1027 gaa_string_data type, 1028 gaa_string_data authority, 1029 int is_idcred) 1031 Parameters: 1032 gaa input/output gaa pointer 1033 cb input condition evaluation callback (should be a 1034 callback created with gaa_new_cond_eval_callback()). 1035 type input condition type to associate this callback with 1036 authority input condition authority to associate this callback 1037 with 1038 is_idcred input flag -- if nonzero, then 1039 gaa_inquire_policy_info (see section 4.2.3.2) will 1040 interpret conditions with this type and authority 1041 as identity conditions. 1043 When gaa_check_authorization() or gaa_inquire_policy_info() 1044 searches for a callback routine for a condition, it first looks for 1045 a callback that was installed with the same type and authority as 1046 the condition. If no match is found, it searches for a callback 1047 with the same authority and a null type. If no match is found, it 1048 searches for a callback with the same type and a null authority. If 1049 no match is found, it searches for a callback with null type and 1050 authority. 1052 4.3.2. Function to register callbacks to deal with mechanism-specific 1053 credentials. 1055 The gaa_add_mech_info function creates and adds a mechinfo callback, 1056 which consists of routines to pull additional credentials, evaluate 1057 raw credentials, verify credentials, and free raw credentials. This 1058 callback can either be associated with a specific mechanism type, or 1059 can be installed as a default to be used when no other mechinfo 1060 callback matches the requested mechanism type. 1062 See section 3.8.3 for descriptions of the data types used by this 1063 function. 1065 gaa_status gaa_add_mech_info (gaa_ptr gaa, 1066 gaa_string_data mech_type, 1067 gaa_cred_pull_func cred_pull, 1068 gaa_cred_eval_func cred_eval, 1069 gaa_cred_verify_func cred_verify, 1070 gaa_freefunc cred_free, 1071 void *params, 1072 gaa_freefunc freeparams) 1074 Parameters: 1075 gaa input/output gaa pointer 1076 mech_type input mechanism type 1077 cred_pull input cred_pull callback. Used by gaa_pull_creds() to 1078 pull additional credentials. 1079 cred_eval input cred_eval callback. Used by gaa_new_cred() to 1080 evaluate a raw credential (translate it into a gaa 1081 identity, group, etc. credential). 1082 cred_verify input cred_verify callback. Used by gaa_verify_cred() 1083 to verify the raw credential (check that it's still 1084 valid). 1085 cred_free input cred_free callback. Used by gaa_free_cred() to 1086 free the raw credential. 1087 params input mechinfo parameter -- passed as an argument to 1088 cred_pull, cred_eval, and cred_verify whenever 1089 they're called. 1090 freeparam input freeparam function -- called to free params when 1091 the gaa pointer is freed. 1093 4.3.3. Function to set the callback routine to get object policy information. 1095 The gaa_set_getpolicy_callback function sets the gaa getpolicy 1096 callback, which is used by gaa_get_object_policy_info (see section 1097 4.2.2) to create a policy structure containing the policy information 1098 associated with an object. 1100 gaa_status gaa_set_getpolicy_callback (gaa_ptr gaa, 1101 gaa_getpolicy_func func, 1102 void *param, 1103 gaa_freefunc freefunc) 1105 Parameters: 1106 gaa input/output gaa pointer 1107 func input getpolicy function 1108 param input getpolicy parameter (to be passed to func whenever 1109 it's called). 1110 freefunc input function to be used to free param when the gaa 1111 pointer is freed. 1113 4.3.4. Function to override GAA-API's internal function to determine 1114 what subset of a policy is relevant to a request. 1116 Each GAA-API implementation has an internal function to 1117 compare a list of requested rights with a policy to determine 1118 which policy entries are relevant to the request. The 1119 gaa_set_matchrights_callback function is used to replace this 1120 internal function with one specified by the application. See 1121 section 3.8.5 for a description of the gaa_matchrights_func 1122 data type. 1124 gaa_status gaa_set_matchrights_callback (gaa_ptr gaa, 1125 gaa_matchrights_func func, 1126 void *param, 1127 gaa_freefunc freefunc) 1129 Parameters: 1130 gaa input/output gaa pointer 1131 func input matchrights function 1132 param input getpolicy parameter (to be passed to func whenever 1133 it's called). 1134 freefunc input function to be used to free param when the gaa 1135 pointer is freed. 1137 4.3.5. Functions to override the default internal representation of 1138 policy right and request right values. 1140 Each GAA-API implementation has internal functions to translate string 1141 representations of policy right and request right values into its own 1142 internal representation, to compare policy right and request right 1143 values, to copy those values, and to express them as character 1144 strings. An application may replace those internal functions 1145 by using gaa_new_valinfo (to create callback structures consisting 1146 of groups of functions) and gaa_add_authinfo (to associate these 1147 callback structures with specific authorities). 1149 See section 3.8.5 for descriptions of the data types used in 1150 these functions. 1152 4.3.5.1. gaa_new_valinfo 1154 The gaa_new_valinfo function allocates a new valinfo structure and 1155 fill it in with the specified callback functions. 1157 gaa_status gaa_new_valinfo (gaa_valinfo_ptr *valinfo, 1158 gaa_copyval_func copyval, 1159 gaa_string2val_func newval, 1160 gaa_freefunc freeval, 1161 gaa_val2string_func val2str) 1163 Parameters: 1164 valinfo output valinfo pointer 1165 copyval input copyval callback function. This callback is used by 1166 gaa_check_authorization() and gaa_inquire_policy_info() 1167 to create new policy entries. 1168 newval optional input newval callback function. This callback is 1169 used by gaa_new_policy_right() and 1170 gaa_new_request_right() to translate a string value into 1171 the appropriate internal representation. 1172 freeval optional input freeval callback function. This callback 1173 is used by gaa_free_request_right() and 1174 gaa_free_policy_right() to free right values. 1175 val2str optional input val2str callback function. This callback 1176 is used by gaa_request_rightval_string() and 1177 gaa_policy_rightval_string() to translate a right value 1178 into a string. 1180 4.3.5.2. gaa_add_authinfo 1182 The gaa_add_authinfo function adds an authinfo callback. This callback 1183 will be used to interpret and compare policy right values for rights 1184 with the specified defining authority. 1186 gaa_status gaa_add_authinfo (gaa_ptr gaa, 1187 char *authority, 1188 gaa_valinfo_ptr pvinfo, 1189 gaa_valinfo_ptr rvinfo, 1190 gaa_valmatch_func match, 1191 void *params, 1192 gaa_freefunc freeparams) 1193 gaa_add_authinfo(). 1195 Parameters: 1196 gaa input/output gaa pointer 1197 authority optional input authority that this callback applies 1198 to. If authority is null, this is considered the 1199 default authinfo callback for any authority that does 1200 not have a specific authinfo callback. 1201 pvinfo input valinfo callback (see gaa_new_valinfo()) to be 1202 used for policy rights with this authority. 1203 rvinfo input valinfo callback (see gaa_new_valinfo()) to be 1204 used for request rights with this authority. 1205 match input callback function that takes a policy right and 1206 a request right, and determines whether the values 1207 match. 1208 params optional input callback parameters passed to 1209 pvinfo->copyval, rvinfo->copyval, pvinfo->newval, 1210 rvinfo->newval, pvinfo->val2str, rvinfo->val2str, and 1211 match whenever they're called. 1212 freeparams optional input function to free params when the gaa 1213 structure is freed. 1215 4.4. Functions used primarily within GAA-API callback routines. 1217 4.4.1. Functions used to build credentials (used primarily 1218 within mechanism-specific cred_eval callback routines -- see sections 1219 3.8.3.2 and 4.3.2). 1221 4.4.1.1. gaa_new_principal 1223 The gaa_new_principal creates a new gaa_principal (for use within a 1224 gaa_cred structure) and fills it in with the specified values. 1226 gaa_status gaa_new_principal (gaa_sec_principal_ptr *princ, 1227 gaa_cred_type type, 1228 gaa_string_data authority, 1229 gaa_string_data value) 1231 Parameters: 1232 princ output gaa_principal to create 1233 type input credential type 1234 authority input authority 1235 value input value 1237 A gaa_principal created using this function should be freed with 1238 gaa_free_principal(). This will happen automatically if it's part 1239 of a credential freed with gaa_free_cred(). 1241 4.4.1.2. gaa_new_identity_info 1243 The gaa_new_identity_info function creates an identity_info structure 1244 (to be used as part of a GAA_IDENTITY, GAA_GROUP_MEMB, or 1245 GAA_GROUP_NON_MEMB credential -- see section 3.6). 1247 gaa_status gaa_new_identity_info (gaa_ptr gaa, 1248 gaa_identity_info_ptr *info) 1250 Parameters: 1251 gaa input 1252 info output identity info to create. 1254 A gaa_identity_info created using this function should be freed with 1255 gaa_free_identity_info(). This will happen automatically if it's part 1256 of a credential freed with gaa_free_cred(). 1258 4.4.1.3. gaa_new_attribute_info 1260 The gaa_new_attribute_info function creates a new attribute_info 1261 structure (to be used as part of a GAA_ATTRIBUTES credential -- see 1262 section 3.6). 1264 gaa_status gaa_new_attribute_info (gaa_ptr gaa, 1265 gaa_attribute_info_ptr *info, 1266 gaa_string_data type, 1267 gaa_string_data authority, 1268 gaa_string_data value) 1269 Parameters: 1270 gaa input gaa pointer 1271 info output structure to create 1272 type input attribute type 1273 authority input attribute authority 1274 value input attribute value 1276 A structure created using this routine should be freed with 1277 gaa_free_attribute_info(). This will happen automatically if this 1278 structure is part of a credential freed with gaa_free_cred(). 1280 4.4.1.4. gaa_new_authr_info 1282 The gaa_new_authr_info function creates a new attribute_info 1283 structure (to be used as part of a GAA_AUTHORIZED credential -- see 1284 section 3.6). 1286 gaa_status gaa_new_authr_info (gaa_ptr gaa, 1287 gaa_authr_info_ptr *info, 1288 void *objects, 1289 gaa_freefunc free_objects) 1290 Parameters: 1291 gaa input gaa pointer 1292 info output structure to create 1293 objects input objects to store in info 1294 free_objects input function to be used to free objects when info 1295 is freed. 1297 A gaa_authr_info created using this function should be freed with 1298 gaa_free_authr_info(). This will happen automatically if it's part 1299 of a credential freed with gaa_free_cred(). 1301 4.4.1.5. gaa_add_authr_right 1303 The gaa_add_authr_right function adds a right to a GAA_AUTHORIZED credential 1305 gaa_status gaa_add_authr_right (gaa_cred_ptr cred, 1306 gaa_policy_right_ptr right) 1308 Parameters: 1309 cred input/output condition to add right to 1310 right input right 1312 If cred is freed with gaa_free_cred, the right will be be freed at 1313 the same time. 1315 4.4.1.6 gaa_add_cred_condition 1317 The gaa_add_cred_condition function adds a condition to a credential. 1318 The credential must be one of the credential types that accepts 1319 conditions (see section 3.6). 1321 gaa_status gaa_add_cred_condition (gaa_cred_ptr cred, 1322 gaa_condition_ptr cond) 1323 Parameters: 1324 cred input/output credential to add condition to 1325 cond input condition to add. 1327 Note: If the credential is freed with gaa_free_cred(), the condition will 1328 be freed at the same time. 1330 4.4.2. Functions used to build policies (used primarily within 1331 gaa_getpolicy callback functions -- see sections 3.8.4 and 4.2.2). 1333 To build a policy, first create it (with gaa_new_policy), then 1334 create policy rights (with gaa_new_policy_right, possibly 1335 adding conditions with gaa_add_condition) and add them with 1336 gaa_add_policy_entry. 1338 4.4.2.1. gaa_new_policy 1340 The gaa_new_policy function creates a new policy structure. 1342 gaa_status gaa_new_policy (gaa_policy_ptr *policy, 1343 void *raw_policy, 1344 gaa_freefunc freeraw) 1346 Parameters: 1347 policy output policy to create 1348 raw_policy optional input raw policy 1349 freeraw optional input function to free raw_policy when 1350 policy is freed. 1352 A policy structure allocated by this function should be freed with 1353 gaa_free_policy(). 1355 4.4.2.2. gaa_new_policy_right 1357 The gaa_new_policy_right function creates a new policy right. 1359 gaa_status gaa_new_policy_right (gaa_ptr gaa, 1360 gaa_policy_right_ptr *right, 1361 gaa_right_type type, 1362 gaa_string_data authority, 1363 gaa_string_data val) 1365 Parameters: 1366 gaa input gaa pointer 1367 right output policy right to create 1368 type input right type (pos_access_right or neg_access_right) 1369 authority input right authority 1370 val input string representation of right value 1372 Note: some applications that use callbacks to override the GAA-API 1373 implementation's default internal representation of right values 1374 may wish to use gaa_new_policy_right_rawval (see section 4.7.6) 1375 instead of this function. 1377 4.4.2.3. gaa_add_condition 1379 The gaa_add_condition function adds a condition to a policy right. 1381 gaa_status gaa_add_condition (gaa_policy_right_ptr right, 1382 gaa_condition_ptr condition) 1384 Parameters: 1385 right input right to add 1386 condition input/output condition to add right to. 1388 4.4.2.4. gaa_add_policy_entry 1390 The gaa_add_policy_entry function adds a policy entry to a policy. 1392 gaa_status gaa_add_policy_entry (gaa_policy_ptr policy, 1393 gaa_policy_right_ptr right, 1394 int priority, 1395 int num) 1396 Parameters: 1397 policy input/output policy 1398 right input right to add 1399 priority input entry priority 1400 num input entry number (for order within priority) 1402 4.4.3. Functions used primarily in condition-evaluation callbacks. 1404 4.4.3.1. gaa_check_condition 1406 The gaa_check_condition function checks a single condition. This 1407 utility function is meant to be used in cond_eval callbacks, when 1408 evaluating conditions recursively. 1410 gaa_status gaa_check_condition (gaa_ptr gaa, 1411 gaa_sc_ptr sc, 1412 gaa_condition_ptr cond, 1413 gaa_time_period_ptr vtp, 1414 int *ynm, 1415 gaa_list_ptr option) 1417 Parameters: 1418 gaa input gaa pointer 1419 cond input condition to evaluate 1420 vtp output valid time period 1421 ynm output answer -- set to GAA_C_YES, GAA_C_NO, or 1422 GAA_C_MAYBE 1423 options optional input list (of type gaa_request_option) of 1424 request options 1426 4.4.3.2. gaa_pull_creds 1428 The gaa_pull_creds function locates and call the appropriate callback 1429 function to pull additional credentials for the specified mechanism 1430 type (or if no mechanism type was specified, call the cred_pull 1431 callback functions for all mechanism types), and add the new 1432 credentials to the security context. 1434 gaa_status gaa_pull_creds (gaa_ptr gaa, 1435 gaa_sc_ptr sc, 1436 gaa_cred_type which, 1437 gaa_string_data mech_type) 1439 Parameters: 1440 gaa input gaa pointer 1441 sc input/output security context 1442 which input what type of credential to pull (identity, group, 1443 etc.) 1444 mech_type which mechanism type to pull (or all of them, if 0) 1446 4.4.3.3. gaa_verify_cred 1448 The gaa_verify_cred function calls the appropriate mechanism-specific 1449 cred_verify function to verify the credential. 1451 gaa_status gaa_verify_cred (gaa_cred_ptr cred) 1453 Parameters: 1454 cred input credential to verify 1456 4.4.3.4. gaa_getcreds 1458 The gaa_getcreds function finds credentials of the specified type in 1459 the security context. 1461 gaa_status gaa_getcreds (gaa_ptr gaa, 1462 gaa_sc_ptr sc, 1463 gaa_list_ptr *credlist, 1464 gaa_cred_type which) 1466 Parameters: 1467 gaa input gaa pointer 1468 sc input security context 1469 credlist input/output credential list 1470 which input desired credential type 1472 4.4.4. Functions for use in gaa_matchrights callback functions. 1474 4.4.4.1. gaa_match_rights 1476 gaa_status gaa_match_rights (gaa_ptr gaa, 1477 gaa_request_right_ptr rright, 1478 gaa_policy_right_ptr pright, 1479 int *match) 1481 Determines whether a request right matches a policy right. If the two 1482 rights do not have the same authority, they don't match. If they do, 1483 then the valmatch callback appropriate to that authority is called to 1484 determine whether they match or not. This utility function is meant to 1485 be used in GAA matchrights callback functions. 1487 Parameters: 1488 gaa input gaa pointer 1489 rright input request right 1490 pright input policy right 1491 match output -- set to 1 if they match, 0 if they don't 1493 4.4.5. Function for use by all callback functions 1495 gaa_status gaa_set_callback_err (gaa_string_data err) 1497 Set the gaa thread-specific callback error string. 1499 Parameters: 1500 err input string to set the callback error to. 1502 4.5. String functions 1504 These functions return character string representations of values. 1506 4.5.1 gaa_get_err 1508 The gaa_get_err function returns the gaa thread-specific error string. 1510 gaa_string_data gaa_get_err ( ) 1512 4.5.2. gaa_get_callback_err 1514 The gaa_get_callback_err function returns the gaa thread-specific 1515 callback error string. 1517 gaa_string_data gaa_get_callback_err ( ) 1519 4.5.3. gaa_request_rightval_string 1521 The gaa_request_rightval_string function converts the value of a 1522 request right into a string. 1524 gaa_string_data gaa_request_rightval_string (gaa_ptr gaa, 1525 gaa_string_data authority, 1526 void *val, 1527 char *buf, 1528 int bsize) 1530 Parameters: 1531 gaa input gaa pointer 1532 authority input authority 1533 val input value 1534 buf input buffer -- should be large enough to hold the 1535 resulting string 1536 bsize input size of buf 1538 Note: If a val2str callback function was installed for this authority 1539 (see section 4.3.5), then that function is used to do the conversion. 1540 Calling gaa_request_rightval_string may or may not result in the 1541 result string being written into buf, depending on the behavior of the 1542 callback function. 1544 4.5.4 gaa_policy_rightval_string 1546 The gaa_policy_rightval_string function converts the value of a 1547 policy right into a string. 1549 gaa_string_data gaa_policy_rightval_string (gaa_ptr gaa, 1550 gaa_string_data authority, 1551 void *val, 1552 char *buf, 1553 int bsize) 1555 Parameters: 1556 gaa input gaa pointer 1557 authority input authority 1558 val input value 1559 buf input buffer -- should be large enough to hold the 1560 resulting string 1562 bsize input size of buf 1564 Note: If a val2str callback function was installed for this authority 1565 (see section 4.3.5), then that function is used to do the conversion. 1566 Calling gaa_request_rightval_string may or may not result in the 1567 result string being written into buf, depending on the behavior of the 1568 callback function. 1570 4.6. List functions 1572 4.6.1. gaa_list_first 1574 The gaa_list_first function finds the first entry in a list. 1576 gaa_list_entry_ptr gaa_list_first (gaa_list_ptr list) 1578 Parameters: 1579 list input list 1581 Return values: 1582 first list entry 1583 0 list was null 1585 4.6.2. gaa_list_next 1587 The gaa_list_next function finds the next entry in a list. 1589 gaa_list_entry_ptr gaa_list_next (gaa_list_entry_ptr entry) 1591 Parameters: 1592 entry input list entry 1594 Return values: 1595 next list entry 1596 0 entry was null 1598 4.6.3. gaa_list_entry_value 1600 The gaa_list_entry_value function finds the data in a list entry. 1602 void * gaa_list_entry_value (gaa_list_entry_ptr entry) 1604 Parameters: 1605 entry input list entry 1607 Return values: 1608 data from list entry 1609 0 entry was null 1611 4.6.4. gaa_list_free 1613 The gaa_list_free function frees a list and all its entries. 1615 void gaa_list_free (gaa_list_ptr list) 1617 Parameters: 1618 list list to free 1620 Note: 1621 If, when the list was created, a function was specified to free 1622 the list's entries, that function will be called to free the 1623 data associated with each list entry. 1625 4.7. Miscellaneous functions 1627 4.7.1. gaa_new_condition 1629 The gaa_new_condition function allocates a new gaa_condition structure 1630 and fills in the specified values. 1632 gaa_status gaa_new_condition (gaa_condition_ptr *cond, 1633 gaa_string_data type, 1634 gaa_string_data authority, 1635 gaa_string_data value) 1637 Parameters: 1638 cond output condition 1639 type input condition type 1640 authority input condition authority 1641 value input condition value 1643 Conditions allocated with this function should be freed with 1644 gaa_free_condition(). 1646 4.7.2. gaa_new_gaa 1648 The gaa_new_gaa function creates a new gaa structure. 1650 gaa_status gaa_new_gaa (gaa_ptr * gaa) 1652 Parameters: 1653 gaa output gaa pointer to create. 1655 A gaa structure created using this function should be freed with 1656 gaa_free_gaa. 1658 4.7.3. gaa_new_answer 1660 The gaa_new_answer function creates a new answer structure (suitable 1661 for use in a call to gaa_check_authorization()). 1663 gaa_status gaa_new_answer (gaa_answer_ptr *answer) 1665 Parameters: 1666 answer output answer structure to create 1668 A structure created with this function should be freed with 1669 gaa_free_answer(). 1671 4.7.4. gaa_clear_policy 1673 The gaa_clear_policy function clears a policy structure (and free all 1674 its entries). 1676 void gaa_clear_policy (gaa_policy_ptr policy) 1678 Parameters: 1679 policy input/output policy to clear 1681 4.7.5. gaa_init_policy 1683 The gaa_init_policy function initializes a policy structure. 1685 gaa_status gaa_init_policy (gaa_policy_ptr policy) 1687 Parameters: 1688 policy input/output policy to initialize 1690 4.7.6. gaa_new_policy_right_rawval 1692 The gaa_new_policy_right_rawval function is an alternative form of 1693 gaa_new_policy_right. It's intended for use by applications that 1694 have overriden the default GAA-API internal representation of 1695 right values and that wish to set those values directly rather 1696 than translating them from character strings. 1698 gaa_status gaa_new_policy_right_rawval (gaa_ptr gaa, 1699 gaa_policy_right_ptr *right, 1700 gaa_right_type type, 1701 gaa_string_data authority, 1702 void *val) 1704 Parameters: 1705 gaa input gaa pointer 1706 right output right pointer 1707 type input right type (pos_access_right or neg_access_right) 1708 authority input authority 1709 val input value 1711 Policy rights created with this routine should be freed with 1712 gaa_free_policy_right(). 1714 4.7.7. gaa_new_request_right_rawval 1716 The gaa_new_request_right_rawval function is an alternative form of 1717 gaa_new_request_right. It's intended for use by applications that 1718 have overriden the default GAA-API internal representation of 1719 right values and that wish to set those values directly rather 1720 than translating them from character strings. 1722 gaa_status gaa_new_request_right_rawval (gaa_ptr gaa, 1723 gaa_request_right_ptr *right, 1724 gaa_string_data authority, 1725 void *value) 1727 Parameters: 1728 gaa input gaa pointer 1729 right output right pointer 1730 authority input authority 1731 val input value 1733 Request rights created with this routine should be freed with 1734 gaa_free_request_right(). 1736 4.8. Functions to release resources. 1738 The functions in this section free GAA-API data structures. 1740 void gaa_free_answer (gaa_answe_ptrr answer) 1741 Frees an answer structure and its component policy rights. 1743 void gaa_free_policy (gaa_policy_ptr policy) 1744 Frees a policy structure and all its entries. 1746 void gaa_free_policy_entry (gaa_policy_entry_ptr ent) 1747 Frees a policy entry and its associated right. 1749 Note: If a policy was created using gaa_new_policy() or 1750 initialized using gaa_init_policy(), then this function will be 1751 called by gaa_free_policy() when the policy is freed. 1753 void gaa_free_policy_right (gaa_policy_right_ptr right) 1754 Free a policy right. 1756 Note: If a policy was created with gaa_new_policy() or initialized 1757 with gaa_init_policy() and is freed with gaa_free_policy(), then this 1758 function will be called to free all associated policy rights when 1759 the policy is freed. 1761 void gaa_free_cred (gaa_cred_ptr cred) 1762 Free a credential and its components. 1764 Note: This function calls the mechanism-specific cred_free callback 1765 function to free the raw credential. 1766 This function is automatically called to free any credential that's part 1767 of a security context being freed with gaa_free_sc(). 1769 void gaa_free_principal (gaa_principal_ptr princ) 1770 Frees a gaa_principal. 1772 Note: If a gaa_principal structure is the principal or grantor in 1773 a gaa_cred structure, then this gaa_free_cred will call this function 1774 to free that gaa_pricincipal structure when the credential is 1775 freed. 1777 void gaa_free_attribute_info (gaa_attribute_info_ptr info) 1778 Free an attribute_info structure and its components. 1780 Note: If a GAA_ATTRIBUTE credential is freed with gaa_free_cred(), 1781 this function will be called automatically to free the associated 1782 attribute info. 1784 void gaa_free_authr_info (gaa_authr_info_ptr info) 1785 Free a gaa_authr_info structure (and its components). 1787 Note: If a GAA_AUTHORIZED credential is freed with gaa_free_cred(), 1788 this function will be called automatically to free the associated 1789 authorization info. 1791 void gaa_free_identity_info (gaa_identity_info_ptr info) 1792 Free a gaa_identity_info structure (and its components). 1794 Note: If a GAA_IDENTITY, GAA_GROUP_MEMB, or GAA_GROUP_NON_MEMB 1795 credential is freed with gaa_free_cred(), this function will be 1796 called automatically to free the associated identity info. 1798 void gaa_free_condition (gaa_condition_ptr cond) 1799 Free a condition (and all its components). 1801 void gaa_free_gaa (gaa_ptr gaa) 1802 Free a gaa structure and its components. 1804 void gaa_free_request_right (gaa_request_right_ptr right) 1805 Free a request right (and all its components). 1807 void gaa_free_sc (gaa_sc_ptr sc) 1808 Free a gaa security context and its components. 1810 void gaa_free_cond_eval_callback (gaa_cond_eval_callback_ptr cb) 1811 Free a condition evaluation callback structure. 1813 Note: if a callback is installed in a gaa structure, then gaa_free() 1814 will call this function to free the callback when the gaa structure 1815 is free. 1817 void gaa_free_valinfo (gaa_valinfo_ptr valinfo) 1818 Free a valinfo structure and its components. 1820 Note: 1821 If a valinfo structure is installed in a gaa structure as 1822 a callback, then this function will be called automatically 1823 to free that valinfo structure when the gaa structure is freed. 1825 void gaa_cleanup (gaa_ptr gaa, void *params) 1826 Cleans up internal GAA API structures allocated and initialized 1827 using the gaa_initialize function. The gaa and params arguments 1828 should be the same as those passed to gaa_initialize. 1830 5. Status codes 1832 The GAA-API routines return a status code of type gaa_status. 1834 Encapsulated in the returned status code are major and minor status 1835 codes. Each of them has a value range equivalent to 16 bit unsigned 1836 integer values. The major code is in low 16 bits, the minor code is 1837 in high 16 bits. The major codes indicate errors that are independent 1838 of the underlying mechanisms. The errors that can be indicated via a 1839 GAA-API major status code are generic API routine errors (errors that 1840 are defined in this specification). 1842 The minor code is implementation-dependent and is used to indicate specialized 1843 errors from the underlying mechanisms or provide additional information about 1844 the GAA-API errors. 1846 GAA_S_SUCCESS 0 Successful completion. 1848 GAA_C_YES 0 An authorization request is granted. 1850 GAA_C_NO 1 An authorization request is denied. 1852 GAA_C_MAYBE 2 An authorization request has not 1853 been evaluated. 1855 GAA_S_FAILURE 3 The underlying mechanism detected an 1856 error for which no specific GAA-API 1857 status code is defined. 1859 GAA_S_INVALID_STRING_DATA_HNDL 4 The handle supplied does not point 1860 to a valid gaa_string_data structure. 1862 GAA_S_INVALID_LIST_HNDL 5 The handle supplied does not point 1863 to a valid gaa_list structure. 1865 GAA_S_INVALID_GAA_HNDL 6 The handle supplied does not point 1866 to a valid gaa structure. 1868 GAA_S_INVALID_POLICY_ENTRY_HNDL 7 The handle supplied does not point 1869 to a valid gaa_policy_entry structure. 1871 GAA_S_INVALID_POLICY_HNDL 8 The handle supplied does not point 1872 to a valid gaa_policy structure. 1874 GAA_S_INVALID_SC_HNDL 9 The handle supplied does not point 1875 to a valid gaa_sc structure. 1877 GAA_S_INVALID_ANSWER_HNDL 10 The handle supplied does not point 1878 to a valid gaa_answer structure. 1880 GAA_S_INVALID_REQUEST_RIGHT_HNDL 11 The handle supplied does not point 1881 to a valid gaa_request_right 1882 structure. 1884 GAA_S_INVALID_POLICY_RIGHT_HNDL 12 The handle supplied does not point 1885 to a valid gaa_policy_right 1886 structure. 1888 GAA_S_INVALID_CONDITION_HNDL 13 The handle supplied does not point 1889 to a valid gaa_condition structure. 1891 GAA_S_INVALID_OPTIONS_HNDL 14 The handle supplied does not point 1892 to a valid gaa_options structure. 1894 GAA_S_INVALID_IDENTITY_INFO_HNDL 15 The handle supplied does not point 1895 to a valid gaa_uneval_cred structure. 1897 GAA_S_INVALID_AUTHR_INFO_HNDL 16 The handle supplied does not point 1898 to a valid gaa_authr_cred structure. 1900 GAA_S_INVALID_PRINCIPAL_HNDL 17 The handle supplied does not point 1901 to a valid gaa_principal structure. 1903 GAA_S_INVALID_ATTRIBUTE_HNDL 18 The handle supplied does not point 1904 to a valid gaa_attribute structure. 1906 GAA_S_UNIMPLEMENTED_FUNCTION 19 The function is not supported by 1907 the underlying implementation. 1909 GAA_S_NO_MATCHING_ENTRIES 20 No matching policy entries have been 1910 found for the requested right. 1912 GAA_S_POLICY_PARSING_FAILURE 21 Indicates an error during policy 1913 parsing. 1915 GAA_S_POLICY_RETRIEVING_FAILURE 22 Indicates an error during policy 1916 retrieval process. 1918 GAA_S_INVALID_ARG 23 One or more arguments was invalid. 1920 GAA_S_UNKNOWN_CRED_TYPE 24 The cred_type of a credential is 1921 invalid 1923 GAA_S_UNKNOWN_MECHANISM 25 No mechanism-specific callback 1924 functions were found for this 1925 credential mechanism 1927 GAA_S_NO_CRED_PULL_CALLBACK 26 An attempt was made to pull 1928 credentials, but no cred_pull 1929 callback had been registered 1930 for this mechanism. 1932 GAA_S_NO_AUTHINFO_CALLBACK 27 No authinfo callback has been 1933 registered for this authority. 1935 GAA_S_NO_NEWVAL_CALLBACK 28 No newval callback has been 1936 registered for this authority. 1938 GAA_S_NO_GETPOLICY_CALLBACK 29 No getpolicy callback has been 1939 registered. 1941 GAA_S_NO_MATCHRIGHTS_CALLBACK 30 No matchrights callback has been 1942 registered. 1944 GAA_S_INVALID_IDENTITY_CRED 31 The credential's cred_type and 1945 principal's cred_type do not match. 1947 GAA_S_BAD_CALLBACK_RETURN 32 A callback routine returned an error. 1949 GAA_S_INTERNAL_ERR 33 There was a GAA internal error. 1951 GAA_S_SYSTEM_ERR 34 There was a system error. 1953 GAA_S_CRED_PULL_FAILURE 35 There was a problem pulling 1954 credentials. 1956 GAA_S_CRED_EVAL_FAILURE 36 There was a problem evaluating 1957 credentials 1959 GAA_S_CRED_VERIFY_FAILURE 37 There was a problem verifying 1960 credentials. 1962 GAA_S_CONFIG_ERR 38 There was a configuration error. 1964 6. The GAA-API flags 1966 Flags are 32 bits. 1968 Condition flags: 1970 COND_FLG_EVALUATED 0x01 condition has been evaluated 1971 COND_FLG_MET 0x10 condition has been met 1972 COND_FLG_ENFORCE 0x100 condition has to be enforced 1974 7. The GAA-API usage example 1976 This section provides an example of a simple application which 1977 calls the GAA-API routines. 1979 #include "gaa.h" 1981 struct my_right { 1982 char *authority; 1983 char *value; 1984 }; 1986 struct my_request { 1987 char *object; 1988 struct my_right *my_rights; 1989 }; 1991 main() 1992 { 1993 gaa_ptr gaa = 0; 1994 void *client_raw_creds; 1995 char *cred_mechanism; 1997 gaa_init(&gaa, 0); 1998 ... 1999 process_session(gaa, client_raw_creds, cred_mechanism); 2000 ... 2001 gaa_cleanup(&gaa, 0); 2002 } 2004 /* 2005 * process_session() -- sample function to process several gaa 2006 * requests under the same credentials. 2007 * Arguments: 2008 * gaa - input gaa pointer 2009 * client_raw_creds - input raw credentials of client. 2010 * cred_mechanism - name of mechanism for client credentials 2011 * (e.g. gss-api). 2012 * Return values: 2013 * 0 success 2014 * -1 failure 2015 * 2016 * This function calls two application-specific functions: 2017 * get_my_request, to get a request from the client, and 2018 * process_request, to do whatever the request is if 2019 * authorization has been granted. 2020 * 2021 * Note: this example function doesn't clean up after itself on errors. 2022 */ 2023 process_session(gaa_ptr gaa, void *client_raw_creds, char *cred_mechanism) 2024 { 2025 gaa_status status; 2026 gaa_sc_ptr sc = 0; 2027 gaa_policy_ptr policy = 0; 2028 struct my_request *myreq; 2029 struct my_right *myright; 2030 gaa_list_ptr list = 0; 2031 gaa_cred_ptr cred = 0; 2032 gaa_answer_ptr answer = 0; 2033 gaa_request_right_ptr right = 0; 2035 /* First initialize the security context */ 2036 if (gaa_new_sc(&sc) != GAA_S_SUCCESS) 2037 return(-1); 2038 if (gaa_new_cred(gaa, sc, &cred, cred_mechanism, client_raw_creds, 2039 GAA_IDENTITY, 1, 0) != GAA_S_SUCCESS) 2040 return(-1); 2041 if (gaa_add_cred(gaa, sc, cred) != GAA_S_SUCCESS) 2042 return(-1); 2044 while (myreq = get_my_request()) { 2045 /* Find the appropriate policy for the object specified in the request */ 2046 if ((status = gaa_get_object_policy_info(myreq->object, gaa, 2047 &policy)) != GAA_S_SUCCESS) 2048 return(-1); 2050 /* Next, build the list of requested rights */ 2051 if ((list = gaa_new_req_rightlist()) == 0) 2052 return(-1); 2053 for (myright = myreq->my_rights; myright->value; myright++) { 2054 if ((status = gaa_new_request_right(gaa, &right, myright->authority, 2055 myright->value)) != GAA_S_SUCCESS) 2056 return(-1); 2057 if ((status = gaa_add_request_right(list, right)) != GAA_S_SUCCESS) 2058 return(-1); 2059 } 2061 /* Now check to see whether the request is authorized */ 2062 if ((status = gaa_new_answer(&answer)) != GAA_S_SUCCESS) 2063 return(-1); 2065 switch (gaa_check_authorization(gaa, sc, policy, list, answer)) 2066 { 2067 case GAA_C_YES: 2068 printf("request authorized\n"); 2069 process_request(myreq); 2070 break; 2071 case GAA_C_NO: 2072 printf("request denied\n"); 2073 break; 2074 case GAA_C_MAYBE: 2075 printf("request undetermined\n"); 2076 break; 2077 default: 2078 fprintf(stderr, "error determining request authorizaton: %s\n", 2079 gaa_get_err()); 2080 break; 2081 } 2083 /* Finally, clean up after this request. */ 2084 gaa_list_free(list); 2085 gaa_free_answer(answer); 2086 } 2087 gaa_free_sc(sc); 2088 return(0); 2089 } 2091 8. References 2093 [1] Linn, J., "Generic Security Service Application Program 2094 Interface", RFC 1508, Geer Zolot Associate, September 1993. 2096 [2] Wray, "Generic Security Service Application Program 2097 Interface V2 - C bindings", Internet draft, May 1997. 2099 [3] T J Hudson, E A Young 2100 SSLeay http://www.livjm.ac.uk/tools/ssleay/ 2102 [4] DASCOM Authorization API draft 1.0 2103 http://www.dascom.com 2105 9. Acknowledgments 2107 Carl Kesselman and Douglas Engert have contributed to discussion 2108 of the ideas and material in this specification. 2110 10. Authors' Addresses 2112 Tatyana Ryutov 2113 Clifford Neuman 2114 Laura Pearlman 2115 USC/Information Sciences Institute 2116 4676 Admiralty Way Suite 1001 2117 Marina del Rey, CA 90292-6695 2118 Phone: +1 310 822 1511 2119 E-Mail: {tryutov, bcn, laura}@isi.edu