1 2 3 4 5 6 7Network Working Group J. Wray 8Request for Comments: 2744 Iris Associates 9Obsoletes: 1509 January 2000 10Category: Standards Track 11 12 13 Generic Security Service API Version 2 : C-bindings 14 15Status of this Memo 16 17 This document specifies an Internet standards track protocol for the 18 Internet community, and requests discussion and suggestions for 19 improvements. Please refer to the current edition of the "Internet 20 Official Protocol Standards" (STD 1) for the standardization state 21 and status of this protocol. Distribution of this memo is unlimited. 22 23Copyright Notice 24 25 Copyright (C) The Internet Society (2000). All Rights Reserved. 26 27Abstract 28 29 This document specifies C language bindings for Version 2, Update 1 30 of the Generic Security Service Application Program Interface (GSS- 31 API), which is described at a language-independent conceptual level 32 in RFC-2743 [GSSAPI]. It obsoletes RFC-1509, making specific 33 incremental changes in response to implementation experience and 34 liaison requests. It is intended, therefore, that this memo or a 35 successor version thereof will become the basis for subsequent 36 progression of the GSS-API specification on the standards track. 37 38 The Generic Security Service Application Programming Interface 39 provides security services to its callers, and is intended for 40 implementation atop a variety of underlying cryptographic mechanisms. 41 Typically, GSS-API callers will be application protocols into which 42 security enhancements are integrated through invocation of services 43 provided by the GSS-API. The GSS-API allows a caller application to 44 authenticate a principal identity associated with a peer application, 45 to delegate rights to a peer, and to apply security services such as 46 confidentiality and integrity on a per-message basis. 47 48 49 50 51 52 53 54 55 56 57 58Wray Standards Track [Page 1] 59 60RFC 2744 GSS-API V2: C-bindings January 2000 61 62 631. Introduction 64 65 The Generic Security Service Application Programming Interface 66 [GSSAPI] provides security services to calling applications. It 67 allows a communicating application to authenticate the user 68 associated with another application, to delegate rights to another 69 application, and to apply security services such as confidentiality 70 and integrity on a per-message basis. 71 72 There are four stages to using the GSS-API: 73 74 a) The application acquires a set of credentials with which it may 75 prove its identity to other processes. The application's 76 credentials vouch for its global identity, which may or may not be 77 related to any local username under which it may be running. 78 79 b) A pair of communicating applications establish a joint security 80 context using their credentials. The security context is a pair 81 of GSS-API data structures that contain shared state information, 82 which is required in order that per-message security services may 83 be provided. Examples of state that might be shared between 84 applications as part of a security context are cryptographic keys, 85 and message sequence numbers. As part of the establishment of a 86 security context, the context initiator is authenticated to the 87 responder, and may require that the responder is authenticated in 88 turn. The initiator may optionally give the responder the right 89 to initiate further security contexts, acting as an agent or 90 delegate of the initiator. This transfer of rights is termed 91 delegation, and is achieved by creating a set of credentials, 92 similar to those used by the initiating application, but which may 93 be used by the responder. 94 95 To establish and maintain the shared information that makes up the 96 security context, certain GSS-API calls will return a token data 97 structure, which is an opaque data type that may contain 98 cryptographically protected data. The caller of such a GSS-API 99 routine is responsible for transferring the token to the peer 100 application, encapsulated if necessary in an application- 101 application protocol. On receipt of such a token, the peer 102 application should pass it to a corresponding GSS-API routine 103 which will decode the token and extract the information, updating 104 the security context state information accordingly. 105 106 107 108 109 110 111 112 113 114Wray Standards Track [Page 2] 115 116RFC 2744 GSS-API V2: C-bindings January 2000 117 118 119 c) Per-message services are invoked to apply either: 120 121 integrity and data origin authentication, or confidentiality, 122 integrity and data origin authentication to application data, 123 which are treated by GSS-API as arbitrary octet-strings. An 124 application transmitting a message that it wishes to protect will 125 call the appropriate GSS-API routine (gss_get_mic or gss_wrap) to 126 apply protection, specifying the appropriate security context, and 127 send the resulting token to the receiving application. The 128 receiver will pass the received token (and, in the case of data 129 protected by gss_get_mic, the accompanying message-data) to the 130 corresponding decoding routine (gss_verify_mic or gss_unwrap) to 131 remove the protection and validate the data. 132 133 d) At the completion of a communications session (which may extend 134 across several transport connections), each application calls a 135 GSS-API routine to delete the security context. Multiple contexts 136 may also be used (either successively or simultaneously) within a 137 single communications association, at the option of the 138 applications. 139 1402. GSS-API Routines 141 142 This section lists the routines that make up the GSS-API, and 143 offers a brief description of the purpose of each routine. 144 Detailed descriptions of each routine are listed in alphabetical 145 order in section 5. 146 147 Table 2-1 GSS-API Credential-management Routines 148 149 Routine Section Function 150 ------- ------- -------- 151 gss_acquire_cred 5.2 Assume a global identity; Obtain 152 a GSS-API credential handle for 153 pre-existing credentials. 154 gss_add_cred 5.3 Construct credentials 155 incrementally 156 gss_inquire_cred 5.21 Obtain information about a 157 credential 158 gss_inquire_cred_by_mech 5.22 Obtain per-mechanism information 159 about a credential. 160 gss_release_cred 5.27 Discard a credential handle. 161 162 163 164 165 166 167 168 169 170Wray Standards Track [Page 3] 171 172RFC 2744 GSS-API V2: C-bindings January 2000 173 174 175 Table 2-2 GSS-API Context-Level Routines 176 177 Routine Section Function 178 ------- ------- -------- 179 gss_init_sec_context 5.19 Initiate a security context with 180 a peer application 181 gss_accept_sec_context 5.1 Accept a security context 182 initiated by a 183 peer application 184 gss_delete_sec_context 5.9 Discard a security context 185 gss_process_context_token 5.25 Process a token on a security 186 context from a peer application 187 gss_context_time 5.7 Determine for how long a context 188 will remain valid 189 gss_inquire_context 5.20 Obtain information about a 190 security context 191 gss_wrap_size_limit 5.34 Determine token-size limit for 192 gss_wrap on a context 193 gss_export_sec_context 5.14 Transfer a security context to 194 another process 195 gss_import_sec_context 5.17 Import a transferred context 196 197 198 Table 2-3 GSS-API Per-message Routines 199 200 Routine Section Function 201 ------- ------- -------- 202 gss_get_mic 5.15 Calculate a cryptographic message 203 integrity code (MIC) for a 204 message; integrity service 205 gss_verify_mic 5.32 Check a MIC against a message; 206 verify integrity of a received 207 message 208 gss_wrap 5.33 Attach a MIC to a message, and 209 optionally encrypt the message 210 content; 211 confidentiality service 212 gss_unwrap 5.31 Verify a message with attached 213 MIC, and decrypt message content 214 if necessary. 215 216 217 218 219 220 221 222 223 224 225 226Wray Standards Track [Page 4] 227 228RFC 2744 GSS-API V2: C-bindings January 2000 229 230 231 Table 2-4 GSS-API Name manipulation Routines 232 233 Routine Section Function 234 ------- ------- -------- 235 gss_import_name 5.16 Convert a contiguous string name 236 to internal-form 237 gss_display_name 5.10 Convert internal-form name to 238 text 239 gss_compare_name 5.6 Compare two internal-form names 240 241 gss_release_name 5.28 Discard an internal-form name 242 gss_inquire_names_for_mech 5.24 List the name-types supported by 243 the specified mechanism 244 gss_inquire_mechs_for_name 5.23 List mechanisms that support the 245 specified name-type 246 gss_canonicalize_name 5.5 Convert an internal name to an MN 247 gss_export_name 5.13 Convert an MN to export form 248 gss_duplicate_name 5.12 Create a copy of an internal name 249 250 251 Table 2-5 GSS-API Miscellaneous Routines 252 253 Routine Section Function 254 ------- ------- -------- 255 gss_add_oid_set_member 5.4 Add an object identifier to 256 a set 257 gss_display_status 5.11 Convert a GSS-API status code 258 to text 259 gss_indicate_mechs 5.18 Determine available underlying 260 authentication mechanisms 261 gss_release_buffer 5.26 Discard a buffer 262 gss_release_oid_set 5.29 Discard a set of object 263 identifiers 264 gss_create_empty_oid_set 5.8 Create a set containing no 265 object identifiers 266 gss_test_oid_set_member 5.30 Determines whether an object 267 identifier is a member of a set. 268 269 Individual GSS-API implementations may augment these routines by 270 providing additional mechanism-specific routines if required 271 functionality is not available from the generic forms. Applications 272 are encouraged to use the generic routines wherever possible on 273 portability grounds. 274 275 276 277 278 279 280 281 282Wray Standards Track [Page 5] 283 284RFC 2744 GSS-API V2: C-bindings January 2000 285 286 2873. Data Types and Calling Conventions 288 289 The following conventions are used by the GSS-API C-language 290 bindings: 291 2923.1. Integer types 293 294 GSS-API uses the following integer data type: 295 296 OM_uint32 32-bit unsigned integer 297 298 Where guaranteed minimum bit-count is important, this portable data 299 type is used by the GSS-API routine definitions. Individual GSS-API 300 implementations will include appropriate typedef definitions to map 301 this type onto a built-in data type. If the platform supports the 302 X/Open xom.h header file, the OM_uint32 definition contained therein 303 should be used; the GSS-API header file in Appendix A contains logic 304 that will detect the prior inclusion of xom.h, and will not attempt 305 to re-declare OM_uint32. If the X/Open header file is not available 306 on the platform, the GSS-API implementation should use the smallest 307 natural unsigned integer type that provides at least 32 bits of 308 precision. 309 3103.2. String and similar data 311 312 Many of the GSS-API routines take arguments and return values that 313 describe contiguous octet-strings. All such data is passed between 314 the GSS-API and the caller using the gss_buffer_t data type. This 315 data type is a pointer to a buffer descriptor, which consists of a 316 length field that contains the total number of bytes in the datum, 317 and a value field which contains a pointer to the actual datum: 318 319 typedef struct gss_buffer_desc_struct { 320 size_t length; 321 void *value; 322 } gss_buffer_desc, *gss_buffer_t; 323 324 Storage for data returned to the application by a GSS-API routine 325 using the gss_buffer_t conventions is allocated by the GSS-API 326 routine. The application may free this storage by invoking the 327 gss_release_buffer routine. Allocation of the gss_buffer_desc object 328 is always the responsibility of the application; unused 329 gss_buffer_desc objects may be initialized to the value 330 GSS_C_EMPTY_BUFFER. 331 332 333 334 335 336 337 338Wray Standards Track [Page 6] 339 340RFC 2744 GSS-API V2: C-bindings January 2000 341 342 3433.2.1. Opaque data types 344 345 Certain multiple-word data items are considered opaque data types at 346 the GSS-API, because their internal structure has no significance 347 either to the GSS-API or to the caller. Examples of such opaque data 348 types are the input_token parameter to gss_init_sec_context (which is 349 opaque to the caller), and the input_message parameter to gss_wrap 350 (which is opaque to the GSS-API). Opaque data is passed between the 351 GSS-API and the application using the gss_buffer_t datatype. 352 3533.2.2. Character strings 354 355 Certain multiple-word data items may be regarded as simple ISO 356 Latin-1 character strings. Examples are the printable strings passed 357 to gss_import_name via the input_name_buffer parameter. Some GSS-API 358 routines also return character strings. All such character strings 359 are passed between the application and the GSS-API implementation 360 using the gss_buffer_t datatype, which is a pointer to a 361 gss_buffer_desc object. 362 363 When a gss_buffer_desc object describes a printable string, the 364 length field of the gss_buffer_desc should only count printable 365 characters within the string. In particular, a trailing NUL 366 character should NOT be included in the length count, nor should 367 either the GSS-API implementation or the application assume the 368 presence of an uncounted trailing NUL. 369 3703.3. Object Identifiers 371 372 Certain GSS-API procedures take parameters of the type gss_OID, or 373 Object identifier. This is a type containing ISO-defined tree- 374 structured values, and is used by the GSS-API caller to select an 375 underlying security mechanism and to specify namespaces. A value of 376 type gss_OID has the following structure: 377 378 typedef struct gss_OID_desc_struct { 379 OM_uint32 length; 380 void *elements; 381 } gss_OID_desc, *gss_OID; 382 383 The elements field of this structure points to the first byte of an 384 octet string containing the ASN.1 BER encoding of the value portion 385 of the normal BER TLV encoding of the gss_OID. The length field 386 contains the number of bytes in this value. For example, the gss_OID 387 value corresponding to {iso(1) identified-organization(3) icd- 388 ecma(12) member-company(2) dec(1011) cryptoAlgorithms(7) DASS(5)}, 389 meaning the DASS X.509 authentication mechanism, has a length field 390 of 7 and an elements field pointing to seven octets containing the 391 392 393 394Wray Standards Track [Page 7] 395 396RFC 2744 GSS-API V2: C-bindings January 2000 397 398 399 following octal values: 53,14,2,207,163,7,5. GSS-API implementations 400 should provide constant gss_OID values to allow applications to 401 request any supported mechanism, although applications are encouraged 402 on portability grounds to accept the default mechanism. gss_OID 403 values should also be provided to allow applications to specify 404 particular name types (see section 3.10). Applications should treat 405 gss_OID_desc values returned by GSS-API routines as read-only. In 406 particular, the application should not attempt to deallocate them 407 with free(). The gss_OID_desc datatype is equivalent to the X/Open 408 OM_object_identifier datatype[XOM]. 409 4103.4. Object Identifier Sets 411 412 Certain GSS-API procedures take parameters of the type gss_OID_set. 413 This type represents one or more object identifiers (section 2.3). A 414 gss_OID_set object has the following structure: 415 416 typedef struct gss_OID_set_desc_struct { 417 size_t count; 418 gss_OID elements; 419 } gss_OID_set_desc, *gss_OID_set; 420 421 The count field contains the number of OIDs within the set. The 422 elements field is a pointer to an array of gss_OID_desc objects, each 423 of which describes a single OID. gss_OID_set values are used to name 424 the available mechanisms supported by the GSS-API, to request the use 425 of specific mechanisms, and to indicate which mechanisms a given 426 credential supports. 427 428 All OID sets returned to the application by GSS-API are dynamic 429 objects (the gss_OID_set_desc, the "elements" array of the set, and 430 the "elements" array of each member OID are all dynamically 431 allocated), and this storage must be deallocated by the application 432 using the gss_release_oid_set() routine. 433 4343.5. Credentials 435 436 A credential handle is a caller-opaque atomic datum that identifies a 437 GSS-API credential data structure. It is represented by the caller- 438 opaque type gss_cred_id_t, which should be implemented as a pointer 439 or arithmetic type. If a pointer implementation is chosen, care must 440 be taken to ensure that two gss_cred_id_t values may be compared with 441 the == operator. 442 443 GSS-API credentials can contain mechanism-specific principal 444 authentication data for multiple mechanisms. A GSS-API credential is 445 composed of a set of credential-elements, each of which is applicable 446 to a single mechanism. A credential may contain at most one 447 448 449 450Wray Standards Track [Page 8] 451 452RFC 2744 GSS-API V2: C-bindings January 2000 453 454 455 credential-element for each supported mechanism. A credential-element 456 identifies the data needed by a single mechanism to authenticate a 457 single principal, and conceptually contains two credential-references 458 that describe the actual mechanism-specific authentication data, one 459 to be used by GSS-API for initiating contexts, and one to be used 460 for accepting contexts. For mechanisms that do not distinguish 461 between acceptor and initiator credentials, both references would 462 point to the same underlying mechanism-specific authentication data. 463 464 Credentials describe a set of mechanism-specific principals, and give 465 their holder the ability to act as any of those principals. All 466 principal identities asserted by a single GSS-API credential should 467 belong to the same entity, although enforcement of this property is 468 an implementation-specific matter. The GSS-API does not make the 469 actual credentials available to applications; instead a credential 470 handle is used to identify a particular credential, held internally 471 by GSS-API. The combination of GSS-API credential handle and 472 mechanism identifies the principal whose identity will be asserted by 473 the credential when used with that mechanism. 474 475 The gss_init_sec_context and gss_accept_sec_context routines allow 476 the value GSS_C_NO_CREDENTIAL to be specified as their credential 477 handle parameter. This special credential-handle indicates a desire 478 by the application to act as a default principal. While individual 479 GSS-API implementations are free to determine such default behavior 480 as appropriate to the mechanism, the following default behavior by 481 these routines is recommended for portability: 482 483 gss_init_sec_context 484 485 1) If there is only a single principal capable of initiating 486 security contexts for the chosen mechanism that the application 487 is authorized to act on behalf of, then that principal shall be 488 used, otherwise 489 490 2) If the platform maintains a concept of a default network- 491 identity for the chosen mechanism, and if the application is 492 authorized to act on behalf of that identity for the purpose of 493 initiating security contexts, then the principal corresponding 494 to that identity shall be used, otherwise 495 496 3) If the platform maintains a concept of a default local 497 identity, and provides a means to map local identities into 498 network-identities for the chosen mechanism, and if the 499 application is authorized to act on behalf of the network- 500 identity image of the default local identity for the purpose of 501 502 503 504 505 506Wray Standards Track [Page 9] 507 508RFC 2744 GSS-API V2: C-bindings January 2000 509 510 511 initiating security contexts using the chosen mechanism, then 512 the principal corresponding to that identity shall be used, 513 otherwise 514 515 4) A user-configurable default identity should be used. 516 517 gss_accept_sec_context 518 519 1) If there is only a single authorized principal identity capable 520 of accepting security contexts for the chosen mechanism, then 521 that principal shall be used, otherwise 522 523 2) If the mechanism can determine the identity of the target 524 principal by examining the context-establishment token, and if 525 the accepting application is authorized to act as that 526 principal for the purpose of accepting security contexts using 527 the chosen mechanism, then that principal identity shall be 528 used, otherwise 529 530 3) If the mechanism supports context acceptance by any principal, 531 and if mutual authentication was not requested, any principal 532 that the application is authorized to accept security contexts 533 under using the chosen mechanism may be used, otherwise 534 535 4)A user-configurable default identity shall be used. 536 537 The purpose of the above rules is to allow security contexts to be 538 established by both initiator and acceptor using the default behavior 539 wherever possible. Applications requesting default behavior are 540 likely to be more portable across mechanisms and platforms than ones 541 that use gss_acquire_cred to request a specific identity. 542 5433.6. Contexts 544 545 The gss_ctx_id_t data type contains a caller-opaque atomic value that 546 identifies one end of a GSS-API security context. It should be 547 implemented as a pointer or arithmetic type. If a pointer type is 548 chosen, care should be taken to ensure that two gss_ctx_id_t values 549 may be compared with the == operator. 550 551 The security context holds state information about each end of a peer 552 communication, including cryptographic state information. 553 554 555 556 557 558 559 560 561 562Wray Standards Track [Page 10] 563 564RFC 2744 GSS-API V2: C-bindings January 2000 565 566 5673.7. Authentication tokens 568 569 A token is a caller-opaque type that GSS-API uses to maintain 570 synchronization between the context data structures at each end of a 571 GSS-API security context. The token is a cryptographically protected 572 octet-string, generated by the underlying mechanism at one end of a 573 GSS-API security context for use by the peer mechanism at the other 574 end. Encapsulation (if required) and transfer of the token are the 575 responsibility of the peer applications. A token is passed between 576 the GSS-API and the application using the gss_buffer_t conventions. 577 5783.8. Interprocess tokens 579 580 Certain GSS-API routines are intended to transfer data between 581 processes in multi-process programs. These routines use a caller- 582 opaque octet-string, generated by the GSS-API in one process for use 583 by the GSS-API in another process. The calling application is 584 responsible for transferring such tokens between processes in an OS- 585 specific manner. Note that, while GSS-API implementors are 586 encouraged to avoid placing sensitive information within interprocess 587 tokens, or to cryptographically protect them, many implementations 588 will be unable to avoid placing key material or other sensitive data 589 within them. It is the application's responsibility to ensure that 590 interprocess tokens are protected in transit, and transferred only to 591 processes that are trustworthy. An interprocess token is passed 592 between the GSS-API and the application using the gss_buffer_t 593 conventions. 594 5953.9. Status values 596 597 Every GSS-API routine returns two distinct values to report status 598 information to the caller: GSS status codes and Mechanism status 599 codes. 600 6013.9.1. GSS status codes 602 603 GSS-API routines return GSS status codes as their OM_uint32 function 604 value. These codes indicate errors that are independent of the 605 underlying mechanism(s) used to provide the security service. The 606 errors that can be indicated via a GSS status code are either generic 607 API routine errors (errors that are defined in the GSS-API 608 specification) or calling errors (errors that are specific to these 609 language bindings). 610 611 A GSS status code can indicate a single fatal generic API error from 612 the routine and a single calling error. In addition, supplementary 613 status information may be indicated via the setting of bits in the 614 supplementary info field of a GSS status code. 615 616 617 618Wray Standards Track [Page 11] 619 620RFC 2744 GSS-API V2: C-bindings January 2000 621 622 623 These errors are encoded into the 32-bit GSS status code as follows: 624 625 MSB LSB 626 |------------------------------------------------------------| 627 | Calling Error | Routine Error | Supplementary Info | 628 |------------------------------------------------------------| 629 Bit 31 24 23 16 15 0 630 631 Hence if a GSS-API routine returns a GSS status code whose upper 16 632 bits contain a non-zero value, the call failed. If the calling error 633 field is non-zero, the invoking application's call of the routine was 634 erroneous. Calling errors are defined in table 5-1. If the routine 635 error field is non-zero, the routine failed for one of the routine- 636 specific reasons listed below in table 5-2. Whether or not the upper 637 16 bits indicate a failure or a success, the routine may indicate 638 additional information by setting bits in the supplementary info 639 field of the status code. The meaning of individual bits is listed 640 below in table 5-3. 641 642 Table 3-1 Calling Errors 643 644 Name Value in field Meaning 645 ---- -------------- ------- 646 GSS_S_CALL_INACCESSIBLE_READ 1 A required input parameter 647 could not be read 648 GSS_S_CALL_INACCESSIBLE_WRITE 2 A required output parameter 649 could not be written. 650 GSS_S_CALL_BAD_STRUCTURE 3 A parameter was malformed 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 672 673 674Wray Standards Track [Page 12] 675 676RFC 2744 GSS-API V2: C-bindings January 2000 677 678 679 Table 3-2 Routine Errors 680 681 Name Value in field Meaning 682 ---- -------------- ------- 683 GSS_S_BAD_MECH 1 An unsupported mechanism 684 was requested 685 GSS_S_BAD_NAME 2 An invalid name was 686 supplied 687 GSS_S_BAD_NAMETYPE 3 A supplied name was of an 688 unsupported type 689 GSS_S_BAD_BINDINGS 4 Incorrect channel bindings 690 were supplied 691 GSS_S_BAD_STATUS 5 An invalid status code was 692 supplied 693 GSS_S_BAD_MIC GSS_S_BAD_SIG 6 A token had an invalid MIC 694 GSS_S_NO_CRED 7 No credentials were 695 supplied, or the 696 credentials were 697 unavailable or 698 inaccessible. 699 GSS_S_NO_CONTEXT 8 No context has been 700 established 701 GSS_S_DEFECTIVE_TOKEN 9 A token was invalid 702 GSS_S_DEFECTIVE_CREDENTIAL 10 A credential was invalid 703 GSS_S_CREDENTIALS_EXPIRED 11 The referenced credentials 704 have expired 705 GSS_S_CONTEXT_EXPIRED 12 The context has expired 706 GSS_S_FAILURE 13 Miscellaneous failure (see 707 text) 708 GSS_S_BAD_QOP 14 The quality-of-protection 709 requested could not be 710 provided 711 GSS_S_UNAUTHORIZED 15 The operation is forbidden 712 by local security policy 713 GSS_S_UNAVAILABLE 16 The operation or option is 714 unavailable 715 GSS_S_DUPLICATE_ELEMENT 17 The requested credential 716 element already exists 717 GSS_S_NAME_NOT_MN 18 The provided name was not a 718 mechanism name 719 720 721 722 723 724 725 726 727 728 729 730Wray Standards Track [Page 13] 731 732RFC 2744 GSS-API V2: C-bindings January 2000 733 734 735 Table 3-3 Supplementary Status Bits 736 737 Name Bit Number Meaning 738 ---- ---------- ------- 739 GSS_S_CONTINUE_NEEDED 0 (LSB) Returned only by 740 gss_init_sec_context or 741 gss_accept_sec_context. The 742 routine must be called again 743 to complete its function. 744 See routine documentation for 745 detailed description 746 GSS_S_DUPLICATE_TOKEN 1 The token was a duplicate of 747 an earlier token 748 GSS_S_OLD_TOKEN 2 The token's validity period 749 has expired 750 GSS_S_UNSEQ_TOKEN 3 A later token has already been 751 processed 752 GSS_S_GAP_TOKEN 4 An expected per-message token 753 was not received 754 755 The routine documentation also uses the name GSS_S_COMPLETE, which is 756 a zero value, to indicate an absence of any API errors or 757 supplementary information bits. 758 759 All GSS_S_xxx symbols equate to complete OM_uint32 status codes, 760 rather than to bitfield values. For example, the actual value of the 761 symbol GSS_S_BAD_NAMETYPE (value 3 in the routine error field) is 762 3<<16. The macros GSS_CALLING_ERROR(), GSS_ROUTINE_ERROR() and 763 GSS_SUPPLEMENTARY_INFO() are provided, each of which takes a GSS 764 status code and removes all but the relevant field. For example, the 765 value obtained by applying GSS_ROUTINE_ERROR to a status code removes 766 the calling errors and supplementary info fields, leaving only the 767 routine errors field. The values delivered by these macros may be 768 directly compared with a GSS_S_xxx symbol of the appropriate type. 769 The macro GSS_ERROR() is also provided, which when applied to a GSS 770 status code returns a non-zero value if the status code indicated a 771 calling or routine error, and a zero value otherwise. All macros 772 defined by GSS-API evaluate their argument(s) exactly once. 773 774 A GSS-API implementation may choose to signal calling errors in a 775 platform-specific manner instead of, or in addition to the routine 776 value; routine errors and supplementary info should be returned via 777 major status values only. 778 779 The GSS major status code GSS_S_FAILURE is used to indicate that the 780 underlying mechanism detected an error for which no specific GSS 781 status code is defined. The mechanism-specific status code will 782 provide more details about the error. 783 784 785 786Wray Standards Track [Page 14] 787 788RFC 2744 GSS-API V2: C-bindings January 2000 789 790 7913.9.2. Mechanism-specific status codes 792 793 GSS-API routines return a minor_status parameter, which is used to 794 indicate specialized errors from the underlying security mechanism. 795 This parameter may contain a single mechanism-specific error, 796 indicated by a OM_uint32 value. 797 798 The minor_status parameter will always be set by a GSS-API routine, 799 even if it returns a calling error or one of the generic API errors 800 indicated above as fatal, although most other output parameters may 801 remain unset in such cases. However, output parameters that are 802 expected to return pointers to storage allocated by a routine must 803 always be set by the routine, even in the event of an error, although 804 in such cases the GSS-API routine may elect to set the returned 805 parameter value to NULL to indicate that no storage was actually 806 allocated. Any length field associated with such pointers (as in a 807 gss_buffer_desc structure) should also be set to zero in such cases. 808 8093.10. Names 810 811 A name is used to identify a person or entity. GSS-API authenticates 812 the relationship between a name and the entity claiming the name. 813 814 Since different authentication mechanisms may employ different 815 namespaces for identifying their principals, GSSAPI's naming support 816 is necessarily complex in multi-mechanism environments (or even in 817 some single-mechanism environments where the underlying mechanism 818 supports multiple namespaces). 819 820 Two distinct representations are defined for names: 821 822 An internal form. This is the GSS-API "native" format for names, 823 represented by the implementation-specific gss_name_t type. It is 824 opaque to GSS-API callers. A single gss_name_t object may contain 825 multiple names from different namespaces, but all names should 826 refer to the same entity. An example of such an internal name 827 would be the name returned from a call to the gss_inquire_cred 828 routine, when applied to a credential containing credential 829 elements for multiple authentication mechanisms employing 830 different namespaces. This gss_name_t object will contain a 831 distinct name for the entity for each authentication mechanism. 832 833 For GSS-API implementations supporting multiple namespaces, 834 objects of type gss_name_t must contain sufficient information to 835 determine the namespace to which each primitive name belongs. 836 837 838 839 840 841 842Wray Standards Track [Page 15] 843 844RFC 2744 GSS-API V2: C-bindings January 2000 845 846 847 Mechanism-specific contiguous octet-string forms. A format 848 capable of containing a single name (from a single namespace). 849 Contiguous string names are always accompanied by an object 850 identifier specifying the namespace to which the name belongs, and 851 their format is dependent on the authentication mechanism that 852 employs the name. Many, but not all, contiguous string names will 853 be printable, and may therefore be used by GSS-API applications 854 for communication with their users. 855 856 Routines (gss_import_name and gss_display_name) are provided to 857 convert names between contiguous string representations and the 858 internal gss_name_t type. gss_import_name may support multiple 859 syntaxes for each supported namespace, allowing users the freedom to 860 choose a preferred name representation. gss_display_name should use 861 an implementation-chosen printable syntax for each supported name- 862 type. 863 864 If an application calls gss_display_name(), passing the internal name 865 resulting from a call to gss_import_name(), there is no guarantee the 866 the resulting contiguous string name will be the same as the original 867 imported string name. Nor do name-space identifiers necessarily 868 survive unchanged after a journey through the internal name-form. An 869 example of this might be a mechanism that authenticates X.500 names, 870 but provides an algorithmic mapping of Internet DNS names into X.500. 871 That mechanism's implementation of gss_import_name() might, when 872 presented with a DNS name, generate an internal name that contained 873 both the original DNS name and the equivalent X.500 name. 874 Alternatively, it might only store the X.500 name. In the latter 875 case, gss_display_name() would most likely generate a printable X.500 876 name, rather than the original DNS name. 877 878 The process of authentication delivers to the context acceptor an 879 internal name. Since this name has been authenticated by a single 880 mechanism, it contains only a single name (even if the internal name 881 presented by the context initiator to gss_init_sec_context had 882 multiple components). Such names are termed internal mechanism 883 names, or "MN"s and the names emitted by gss_accept_sec_context() are 884 always of this type. Since some applications may require MNs without 885 wanting to incur the overhead of an authentication operation, a 886 second function, gss_canonicalize_name(), is provided to convert a 887 general internal name into an MN. 888 889 Comparison of internal-form names may be accomplished via the 890 gss_compare_name() routine, which returns true if the two names being 891 compared refer to the same entity. This removes the need for the 892 application program to understand the syntaxes of the various 893 printable names that a given GSS-API implementation may support. 894 Since GSS-API assumes that all primitive names contained within a 895 896 897 898Wray Standards Track [Page 16] 899 900RFC 2744 GSS-API V2: C-bindings January 2000 901 902 903 given internal name refer to the same entity, gss_compare_name() can 904 return true if the two names have at least one primitive name in 905 common. If the implementation embodies knowledge of equivalence 906 relationships between names taken from different namespaces, this 907 knowledge may also allow successful comparison of internal names 908 containing no overlapping primitive elements. 909 910 When used in large access control lists, the overhead of invoking 911 gss_import_name() and gss_compare_name() on each name from the ACL 912 may be prohibitive. As an alternative way of supporting this case, 913 GSS-API defines a special form of the contiguous string name which 914 may be compared directly (e.g. with memcmp()). Contiguous names 915 suitable for comparison are generated by the gss_export_name() 916 routine, which requires an MN as input. Exported names may be re- 917 imported by the gss_import_name() routine, and the resulting internal 918 name will also be an MN. The gss_OID constant GSS_C_NT_EXPORT_NAME 919 indentifies the "export name" type, and the value of this constant is 920 given in Appendix A. Structurally, an exported name object consists 921 of a header containing an OID identifying the mechanism that 922 authenticated the name, and a trailer containing the name itself, 923 where the syntax of the trailer is defined by the individual 924 mechanism specification. The precise format of an export name is 925 defined in the language-independent GSS-API specification [GSSAPI]. 926 927 Note that the results obtained by using gss_compare_name() will in 928 general be different from those obtained by invoking 929 gss_canonicalize_name() and gss_export_name(), and then comparing the 930 exported names. The first series of operation determines whether two 931 (unauthenticated) names identify the same principal; the second 932 whether a particular mechanism would authenticate them as the same 933 principal. These two operations will in general give the same 934 results only for MNs. 935 936 The gss_name_t datatype should be implemented as a pointer type. To 937 allow the compiler to aid the application programmer by performing 938 type-checking, the use of (void *) is discouraged. A pointer to an 939 implementation-defined type is the preferred choice. 940 941 Storage is allocated by routines that return gss_name_t values. A 942 procedure, gss_release_name, is provided to free storage associated 943 with an internal-form name. 944 945 946 947 948 949 950 951 952 953 954Wray Standards Track [Page 17] 955 956RFC 2744 GSS-API V2: C-bindings January 2000 957 958 9593.11. Channel Bindings 960 961 GSS-API supports the use of user-specified tags to identify a given 962 context to the peer application. These tags are intended to be used 963 to identify the particular communications channel that carries the 964 context. Channel bindings are communicated to the GSS-API using the 965 following structure: 966 967 typedef struct gss_channel_bindings_struct { 968 OM_uint32 initiator_addrtype; 969 gss_buffer_desc initiator_address; 970 OM_uint32 acceptor_addrtype; 971 gss_buffer_desc acceptor_address; 972 gss_buffer_desc application_data; 973 } *gss_channel_bindings_t; 974 975 The initiator_addrtype and acceptor_addrtype fields denote the type 976 of addresses contained in the initiator_address and acceptor_address 977 buffers. The address type should be one of the following: 978 979 GSS_C_AF_UNSPEC Unspecified address type 980 GSS_C_AF_LOCAL Host-local address type 981 GSS_C_AF_INET Internet address type (e.g. IP) 982 GSS_C_AF_IMPLINK ARPAnet IMP address type 983 GSS_C_AF_PUP pup protocols (eg BSP) address type 984 GSS_C_AF_CHAOS MIT CHAOS protocol address type 985 GSS_C_AF_NS XEROX NS address type 986 GSS_C_AF_NBS nbs address type 987 GSS_C_AF_ECMA ECMA address type 988 GSS_C_AF_DATAKIT datakit protocols address type 989 GSS_C_AF_CCITT CCITT protocols 990 GSS_C_AF_SNA IBM SNA address type 991 GSS_C_AF_DECnet DECnet address type 992 GSS_C_AF_DLI Direct data link interface address type 993 GSS_C_AF_LAT LAT address type 994 GSS_C_AF_HYLINK NSC Hyperchannel address type 995 GSS_C_AF_APPLETALK AppleTalk address type 996 GSS_C_AF_BSC BISYNC 2780/3780 address type 997 GSS_C_AF_DSS Distributed system services address type 998 GSS_C_AF_OSI OSI TP4 address type 999 GSS_C_AF_X25 X.25 1000 GSS_C_AF_NULLADDR No address specified 1001 1002 Note that these symbols name address families rather than specific 1003 addressing formats. For address families that contain several 1004 alternative address forms, the initiator_address and acceptor_address 1005 fields must contain sufficient information to determine which address 1006 1007 1008 1009 1010Wray Standards Track [Page 18] 1011 1012RFC 2744 GSS-API V2: C-bindings January 2000 1013 1014 1015 form is used. When not otherwise specified, addresses should be 1016 specified in network byte-order (that is, native byte-ordering for 1017 the address family). 1018 1019 Conceptually, the GSS-API concatenates the initiator_addrtype, 1020 initiator_address, acceptor_addrtype, acceptor_address and 1021 application_data to form an octet string. The mechanism calculates a 1022 MIC over this octet string, and binds the MIC to the context 1023 establishment token emitted by gss_init_sec_context. The same 1024 bindings are presented by the context acceptor to 1025 gss_accept_sec_context, and a MIC is calculated in the same way. The 1026 calculated MIC is compared with that found in the token, and if the 1027 MICs differ, gss_accept_sec_context will return a GSS_S_BAD_BINDINGS 1028 error, and the context will not be established. Some mechanisms may 1029 include the actual channel binding data in the token (rather than 1030 just a MIC); applications should therefore not use confidential data 1031 as channel-binding components. 1032 1033 Individual mechanisms may impose additional constraints on addresses 1034 and address types that may appear in channel bindings. For example, 1035 a mechanism may verify that the initiator_address field of the 1036 channel bindings presented to gss_init_sec_context contains the 1037 correct network address of the host system. Portable applications 1038 should therefore ensure that they either provide correct information 1039 for the address fields, or omit addressing information, specifying 1040 GSS_C_AF_NULLADDR as the address-types. 1041 10423.12. Optional parameters 1043 1044 Various parameters are described as optional. This means that they 1045 follow a convention whereby a default value may be requested. The 1046 following conventions are used for omitted parameters. These 1047 conventions apply only to those parameters that are explicitly 1048 documented as optional. 1049 10503.12.1. gss_buffer_t types 1051 1052 Specify GSS_C_NO_BUFFER as a value. For an input parameter this 1053 signifies that default behavior is requested, while for an output 1054 parameter it indicates that the information that would be returned 1055 via the parameter is not required by the application. 1056 10573.12.2. Integer types (input) 1058 1059 Individual parameter documentation lists values to be used to 1060 indicate default actions. 1061 1062 1063 1064 1065 1066Wray Standards Track [Page 19] 1067 1068RFC 2744 GSS-API V2: C-bindings January 2000 1069 1070 10713.12.3. Integer types (output) 1072 1073 Specify NULL as the value for the pointer. 1074 10753.12.4. Pointer types 1076 1077 Specify NULL as the value. 1078 10793.12.5. Object IDs 1080 1081 Specify GSS_C_NO_OID as the value. 1082 10833.12.6. Object ID Sets 1084 1085 Specify GSS_C_NO_OID_SET as the value. 1086 10873.12.7. Channel Bindings 1088 1089 Specify GSS_C_NO_CHANNEL_BINDINGS to indicate that channel bindings 1090 are not to be used. 1091 10924. Additional Controls 1093 1094 This section discusses the optional services that a context initiator 1095 may request of the GSS-API at context establishment. Each of these 1096 services is requested by setting a flag in the req_flags input 1097 parameter to gss_init_sec_context. 1098 1099 The optional services currently defined are: 1100 1101 Delegation - The (usually temporary) transfer of rights from 1102 initiator to acceptor, enabling the acceptor to authenticate 1103 itself as an agent of the initiator. 1104 1105 Mutual Authentication - In addition to the initiator authenticating 1106 its identity to the context acceptor, the context acceptor should 1107 also authenticate itself to the initiator. 1108 1109 Replay detection - In addition to providing message integrity 1110 services, gss_get_mic and gss_wrap should include message 1111 numbering information to enable gss_verify_mic and gss_unwrap to 1112 detect if a message has been duplicated. 1113 1114 Out-of-sequence detection - In addition to providing message 1115 integrity services, gss_get_mic and gss_wrap should include 1116 message sequencing information to enable gss_verify_mic and 1117 gss_unwrap to detect if a message has been received out of 1118 sequence. 1119 1120 1121 1122Wray Standards Track [Page 20] 1123 1124RFC 2744 GSS-API V2: C-bindings January 2000 1125 1126 1127 Anonymous authentication - The establishment of the security context 1128 should not reveal the initiator's identity to the context 1129 acceptor. 1130 1131 Any currently undefined bits within such flag arguments should be 1132 ignored by GSS-API implementations when presented by an application, 1133 and should be set to zero when returned to the application by the 1134 GSS-API implementation. 1135 1136 Some mechanisms may not support all optional services, and some 1137 mechanisms may only support some services in conjunction with others. 1138 Both gss_init_sec_context and gss_accept_sec_context inform the 1139 applications which services will be available from the context when 1140 the establishment phase is complete, via the ret_flags output 1141 parameter. In general, if the security mechanism is capable of 1142 providing a requested service, it should do so, even if additional 1143 services must be enabled in order to provide the requested service. 1144 If the mechanism is incapable of providing a requested service, it 1145 should proceed without the service, leaving the application to abort 1146 the context establishment process if it considers the requested 1147 service to be mandatory. 1148 1149 Some mechanisms may specify that support for some services is 1150 optional, and that implementors of the mechanism need not provide it. 1151 This is most commonly true of the confidentiality service, often 1152 because of legal restrictions on the use of data-encryption, but may 1153 apply to any of the services. Such mechanisms are required to send 1154 at least one token from acceptor to initiator during context 1155 establishment when the initiator indicates a desire to use such a 1156 service, so that the initiating GSS-API can correctly indicate 1157 whether the service is supported by the acceptor's GSS-API. 1158 11594.1. Delegation 1160 1161 The GSS-API allows delegation to be controlled by the initiating 1162 application via a boolean parameter to gss_init_sec_context(), the 1163 routine that establishes a security context. Some mechanisms do not 1164 support delegation, and for such mechanisms attempts by an 1165 application to enable delegation are ignored. 1166 1167 The acceptor of a security context for which the initiator enabled 1168 delegation will receive (via the delegated_cred_handle parameter of 1169 gss_accept_sec_context) a credential handle that contains the 1170 delegated identity, and this credential handle may be used to 1171 initiate subsequent GSS-API security contexts as an agent or delegate 1172 of the initiator. If the original initiator's identity is "A" and 1173 the delegate's identity is "B", then, depending on the underlying 1174 mechanism, the identity embodied by the delegated credential may be 1175 1176 1177 1178Wray Standards Track [Page 21] 1179 1180RFC 2744 GSS-API V2: C-bindings January 2000 1181 1182 1183 either "A" or "B acting for A". 1184 1185 For many mechanisms that support delegation, a simple boolean does 1186 not provide enough control. Examples of additional aspects of 1187 delegation control that a mechanism might provide to an application 1188 are duration of delegation, network addresses from which delegation 1189 is valid, and constraints on the tasks that may be performed by a 1190 delegate. Such controls are presently outside the scope of the GSS- 1191 API. GSS-API implementations supporting mechanisms offering 1192 additional controls should provide extension routines that allow 1193 these controls to be exercised (perhaps by modifying the initiator's 1194 GSS-API credential prior to its use in establishing a context). 1195 However, the simple delegation control provided by GSS-API should 1196 always be able to over-ride other mechanism-specific delegation 1197 controls - If the application instructs gss_init_sec_context() that 1198 delegation is not desired, then the implementation must not permit 1199 delegation to occur. This is an exception to the general rule that a 1200 mechanism may enable services even if they are not requested - 1201 delegation may only be provided at the explicit request of the 1202 application. 1203 12044.2. Mutual authentication 1205 1206 Usually, a context acceptor will require that a context initiator 1207 authenticate itself so that the acceptor may make an access-control 1208 decision prior to performing a service for the initiator. In some 1209 cases, the initiator may also request that the acceptor authenticate 1210 itself. GSS-API allows the initiating application to request this 1211 mutual authentication service by setting a flag when calling 1212 gss_init_sec_context. 1213 1214 The initiating application is informed as to whether or not the 1215 context acceptor has authenticated itself. Note that some mechanisms 1216 may not support mutual authentication, and other mechanisms may 1217 always perform mutual authentication, whether or not the initiating 1218 application requests it. In particular, mutual authentication my be 1219 required by some mechanisms in order to support replay or out-of- 1220 sequence message detection, and for such mechanisms a request for 1221 either of these services will automatically enable mutual 1222 authentication. 1223 1224 1225 1226 1227 1228 1229 1230 1231 1232 1233 1234Wray Standards Track [Page 22] 1235 1236RFC 2744 GSS-API V2: C-bindings January 2000 1237 1238 12394.3. Replay and out-of-sequence detection 1240 1241 The GSS-API may provide detection of mis-ordered message once a 1242 security context has been established. Protection may be applied to 1243 messages by either application, by calling either gss_get_mic or 1244 gss_wrap, and verified by the peer application by calling 1245 gss_verify_mic or gss_unwrap. 1246 1247 gss_get_mic calculates a cryptographic MIC over an application 1248 message, and returns that MIC in a token. The application should 1249 pass both the token and the message to the peer application, which 1250 presents them to gss_verify_mic. 1251 1252 gss_wrap calculates a cryptographic MIC of an application message, 1253 and places both the MIC and the message inside a single token. The 1254 Application should pass the token to the peer application, which 1255 presents it to gss_unwrap to extract the message and verify the MIC. 1256 1257 Either pair of routines may be capable of detecting out-of-sequence 1258 message delivery, or duplication of messages. Details of such mis- 1259 ordered messages are indicated through supplementary status bits in 1260 the major status code returned by gss_verify_mic or gss_unwrap. The 1261 relevant supplementary bits are: 1262 1263 GSS_S_DUPLICATE_TOKEN - The token is a duplicate of one that has 1264 already been received and processed. Only 1265 contexts that claim to provide replay detection 1266 may set this bit. 1267 GSS_S_OLD_TOKEN - The token is too old to determine whether or 1268 not it is a duplicate. Contexts supporting 1269 out-of-sequence detection but not replay 1270 detection should always set this bit if 1271 GSS_S_UNSEQ_TOKEN is set; contexts that support 1272 replay detection should only set this bit if the 1273 token is so old that it cannot be checked for 1274 duplication. 1275 GSS_S_UNSEQ_TOKEN - A later token has already been processed. 1276 GSS_S_GAP_TOKEN - An earlier token has not yet been received. 1277 1278 A mechanism need not maintain a list of all tokens that have been 1279 processed in order to support these status codes. A typical 1280 mechanism might retain information about only the most recent "N" 1281 tokens processed, allowing it to distinguish duplicates and missing 1282 tokens within the most recent "N" messages; the receipt of a token 1283 older than the most recent "N" would result in a GSS_S_OLD_TOKEN 1284 status. 1285 1286 1287 1288 1289 1290Wray Standards Track [Page 23] 1291 1292RFC 2744 GSS-API V2: C-bindings January 2000 1293 1294 12954.4. Anonymous Authentication 1296 1297 In certain situations, an application may wish to initiate the 1298 authentication process to authenticate a peer, without revealing its 1299 own identity. As an example, consider an application providing 1300 access to a database containing medical information, and offering 1301 unrestricted access to the service. A client of such a service might 1302 wish to authenticate the service (in order to establish trust in any 1303 information retrieved from it), but might not wish the service to be 1304 able to obtain the client's identity (perhaps due to privacy concerns 1305 about the specific inquiries, or perhaps simply to avoid being placed 1306 on mailing-lists). 1307 1308 In normal use of the GSS-API, the initiator's identity is made 1309 available to the acceptor as a result of the context establishment 1310 process. However, context initiators may request that their identity 1311 not be revealed to the context acceptor. Many mechanisms do not 1312 support anonymous authentication, and for such mechanisms the request 1313 will not be honored. An authentication token will be still be 1314 generated, but the application is always informed if a requested 1315 service is unavailable, and has the option to abort context 1316 establishment if anonymity is valued above the other security 1317 services that would require a context to be established. 1318 1319 In addition to informing the application that a context is 1320 established anonymously (via the ret_flags outputs from 1321 gss_init_sec_context and gss_accept_sec_context), the optional 1322 src_name output from gss_accept_sec_context and gss_inquire_context 1323 will, for such contexts, return a reserved internal-form name, 1324 defined by the implementation. 1325 1326 When presented to gss_display_name, this reserved internal-form name 1327 will result in a printable name that is syntactically distinguishable 1328 from any valid principal name supported by the implementation, 1329 associated with a name-type object identifier with the value 1330 GSS_C_NT_ANONYMOUS, whose value us given in Appendix A. The 1331 printable form of an anonymous name should be chosen such that it 1332 implies anonymity, since this name may appear in, for example, audit 1333 logs. For example, the string "<anonymous>" might be a good choice, 1334 if no valid printable names supported by the implementation can begin 1335 with "<" and end with ">". 1336 13374.5. Confidentiality 1338 1339 If a context supports the confidentiality service, gss_wrap may be 1340 used to encrypt application messages. Messages are selectively 1341 encrypted, under the control of the conf_req_flag input parameter to 1342 gss_wrap. 1343 1344 1345 1346Wray Standards Track [Page 24] 1347 1348RFC 2744 GSS-API V2: C-bindings January 2000 1349 1350 13514.6. Inter-process context transfer 1352 1353 GSS-API V2 provides routines (gss_export_sec_context and 1354 gss_import_sec_context) which allow a security context to be 1355 transferred between processes on a single machine. The most common 1356 use for such a feature is a client-server design where the server is 1357 implemented as a single process that accepts incoming security 1358 contexts, which then launches child processes to deal with the data 1359 on these contexts. In such a design, the child processes must have 1360 access to the security context data structure created within the 1361 parent by its call to gss_accept_sec_context so that they can use 1362 per-message protection services and delete the security context when 1363 the communication session ends. 1364 1365 Since the security context data structure is expected to contain 1366 sequencing information, it is impractical in general to share a 1367 context between processes. Thus GSS-API provides a call 1368 (gss_export_sec_context) that the process which currently owns the 1369 context can call to declare that it has no intention to use the 1370 context subsequently, and to create an inter-process token containing 1371 information needed by the adopting process to successfully import the 1372 context. After successful completion of gss_export_sec_context, the 1373 original security context is made inaccessible to the calling process 1374 by GSS-API, and any context handles referring to this context are no 1375 longer valid. The originating process transfers the inter-process 1376 token to the adopting process, which passes it to 1377 gss_import_sec_context, and a fresh gss_ctx_id_t is created such that 1378 it is functionally identical to the original context. 1379 1380 The inter-process token may contain sensitive data from the original 1381 security context (including cryptographic keys). Applications using 1382 inter-process tokens to transfer security contexts must take 1383 appropriate steps to protect these tokens in transit. 1384 1385 Implementations are not required to support the inter-process 1386 transfer of security contexts. The ability to transfer a security 1387 context is indicated when the context is created, by 1388 gss_init_sec_context or gss_accept_sec_context setting the 1389 GSS_C_TRANS_FLAG bit in their ret_flags parameter. 1390 13914.7. The use of incomplete contexts 1392 1393 Some mechanisms may allow the per-message services to be used before 1394 the context establishment process is complete. For example, a 1395 mechanism may include sufficient information in its initial context- 1396 level token for the context acceptor to immediately decode messages 1397 protected with gss_wrap or gss_get_mic. For such a mechanism, the 1398 initiating application need not wait until subsequent context-level 1399 1400 1401 1402Wray Standards Track [Page 25] 1403 1404RFC 2744 GSS-API V2: C-bindings January 2000 1405 1406 1407 tokens have been sent and received before invoking the per-message 1408 protection services. 1409 1410 The ability of a context to provide per-message services in advance 1411 of complete context establishment is indicated by the setting of the 1412 GSS_C_PROT_READY_FLAG bit in the ret_flags parameter from 1413 gss_init_sec_context and gss_accept_sec_context. Applications wishing 1414 to use per-message protection services on partially-established 1415 contexts should check this flag before attempting to invoke gss_wrap 1416 or gss_get_mic. 1417 14185. GSS-API Routine Descriptions 1419 1420 In addition to the explicit major status codes documented here, the 1421 code GSS_S_FAILURE may be returned by any routine, indicating an 1422 implementation-specific or mechanism-specific error condition, 1423 further details of which are reported via the minor_status parameter. 1424 14255.1. gss_accept_sec_context 1426 1427 OM_uint32 gss_accept_sec_context ( 1428 OM_uint32 *minor_status, 1429 gss_ctx_id_t *context_handle, 1430 const gss_cred_id_t acceptor_cred_handle, 1431 const gss_buffer_t input_token_buffer, 1432 const gss_channel_bindings_t input_chan_bindings, 1433 const gss_name_t *src_name, 1434 gss_OID *mech_type, 1435 gss_buffer_t output_token, 1436 OM_uint32 *ret_flags, 1437 OM_uint32 *time_rec, 1438 gss_cred_id_t *delegated_cred_handle) 1439 1440 Purpose: 1441 1442 Allows a remotely initiated security context between the application 1443 and a remote peer to be established. The routine may return a 1444 output_token which should be transferred to the peer application, 1445 where the peer application will present it to gss_init_sec_context. 1446 If no token need be sent, gss_accept_sec_context will indicate this 1447 by setting the length field of the output_token argument to zero. To 1448 complete the context establishment, one or more reply tokens may be 1449 required from the peer application; if so, gss_accept_sec_context 1450 will return a status flag of GSS_S_CONTINUE_NEEDED, in which case it 1451 should be called again when the reply token is received from the peer 1452 application, passing the token to gss_accept_sec_context via the 1453 input_token parameters. 1454 1455 1456 1457 1458Wray Standards Track [Page 26] 1459 1460RFC 2744 GSS-API V2: C-bindings January 2000 1461 1462 1463 Portable applications should be constructed to use the token length 1464 and return status to determine whether a token needs to be sent or 1465 waited for. Thus a typical portable caller should always invoke 1466 gss_accept_sec_context within a loop: 1467 1468 gss_ctx_id_t context_hdl = GSS_C_NO_CONTEXT; 1469 1470 do { 1471 receive_token_from_peer(input_token); 1472 maj_stat = gss_accept_sec_context(&min_stat, 1473 &context_hdl, 1474 cred_hdl, 1475 input_token, 1476 input_bindings, 1477 &client_name, 1478 &mech_type, 1479 output_token, 1480 &ret_flags, 1481 &time_rec, 1482 &deleg_cred); 1483 if (GSS_ERROR(maj_stat)) { 1484 report_error(maj_stat, min_stat); 1485 }; 1486 if (output_token->length != 0) { 1487 send_token_to_peer(output_token); 1488 1489 gss_release_buffer(&min_stat, output_token); 1490 }; 1491 if (GSS_ERROR(maj_stat)) { 1492 if (context_hdl != GSS_C_NO_CONTEXT) 1493 gss_delete_sec_context(&min_stat, 1494 &context_hdl, 1495 GSS_C_NO_BUFFER); 1496 break; 1497 }; 1498 } while (maj_stat & GSS_S_CONTINUE_NEEDED); 1499 1500 Whenever the routine returns a major status that includes the value 1501 GSS_S_CONTINUE_NEEDED, the context is not fully established and the 1502 following restrictions apply to the output parameters: 1503 1504 The value returned via the time_rec parameter is undefined Unless the 1505 accompanying ret_flags parameter contains the bit 1506 GSS_C_PROT_READY_FLAG, indicating that per-message services may be 1507 applied in advance of a successful completion status, the value 1508 returned via the mech_type parameter may be undefined until the 1509 routine returns a major status value of GSS_S_COMPLETE. 1510 1511 1512 1513 1514Wray Standards Track [Page 27] 1515 1516RFC 2744 GSS-API V2: C-bindings January 2000 1517 1518 1519 The values of the GSS_C_DELEG_FLAG, 1520 GSS_C_MUTUAL_FLAG,GSS_C_REPLAY_FLAG, GSS_C_SEQUENCE_FLAG, 1521 GSS_C_CONF_FLAG,GSS_C_INTEG_FLAG and GSS_C_ANON_FLAG bits returned 1522 via the ret_flags parameter should contain the values that the 1523 implementation expects would be valid if context establishment were 1524 to succeed. 1525 1526 The values of the GSS_C_PROT_READY_FLAG and GSS_C_TRANS_FLAG bits 1527 within ret_flags should indicate the actual state at the time 1528 gss_accept_sec_context returns, whether or not the context is fully 1529 established. 1530 1531 Although this requires that GSS-API implementations set the 1532 GSS_C_PROT_READY_FLAG in the final ret_flags returned to a caller 1533 (i.e. when accompanied by a GSS_S_COMPLETE status code), applications 1534 should not rely on this behavior as the flag was not defined in 1535 Version 1 of the GSS-API. Instead, applications should be prepared to 1536 use per-message services after a successful context establishment, 1537 according to the GSS_C_INTEG_FLAG and GSS_C_CONF_FLAG values. 1538 1539 All other bits within the ret_flags argument should be set to zero. 1540 While the routine returns GSS_S_CONTINUE_NEEDED, the values returned 1541 via the ret_flags argument indicate the services that the 1542 implementation expects to be available from the established context. 1543 1544 If the initial call of gss_accept_sec_context() fails, the 1545 implementation should not create a context object, and should leave 1546 the value of the context_handle parameter set to GSS_C_NO_CONTEXT to 1547 indicate this. In the event of a failure on a subsequent call, the 1548 implementation is permitted to delete the "half-built" security 1549 context (in which case it should set the context_handle parameter to 1550 GSS_C_NO_CONTEXT), but the preferred behavior is to leave the 1551 security context (and the context_handle parameter) untouched for the 1552 application to delete (using gss_delete_sec_context). 1553 1554 During context establishment, the informational status bits 1555 GSS_S_OLD_TOKEN and GSS_S_DUPLICATE_TOKEN indicate fatal errors, and 1556 GSS-API mechanisms should always return them in association with a 1557 routine error of GSS_S_FAILURE. This requirement for pairing did not 1558 exist in version 1 of the GSS-API specification, so applications that 1559 wish to run over version 1 implementations must special-case these 1560 codes. 1561 1562 1563 1564 1565 1566 1567 1568 1569 1570Wray Standards Track [Page 28] 1571 1572RFC 2744 GSS-API V2: C-bindings January 2000 1573 1574 1575 Parameters: 1576 1577 context_handle gss_ctx_id_t, read/modify context handle for new 1578 context. Supply GSS_C_NO_CONTEXT for first 1579 call; use value returned in subsequent calls. 1580 Once gss_accept_sec_context() has returned a 1581 value via this parameter, resources have been 1582 assigned to the corresponding context, and must 1583 be freed by the application after use with a 1584 call to gss_delete_sec_context(). 1585 1586 1587 acceptor_cred_handle gss_cred_id_t, read Credential handle claimed 1588 by context acceptor. Specify 1589 GSS_C_NO_CREDENTIAL to accept the context as a 1590 default principal. If GSS_C_NO_CREDENTIAL is 1591 specified, but no default acceptor principal is 1592 defined, GSS_S_NO_CRED will be returned. 1593 1594 input_token_buffer buffer, opaque, read token obtained from remote 1595 application. 1596 1597 input_chan_bindings channel bindings, read, optional Application- 1598 specified bindings. Allows application to 1599 securely bind channel identification information 1600 to the security context. If channel bindings 1601 are not used, specify GSS_C_NO_CHANNEL_BINDINGS. 1602 1603 src_name gss_name_t, modify, optional Authenticated name 1604 of context initiator. After use, this name 1605 should be deallocated by passing it to 1606 gss_release_name(). If not required, specify 1607 NULL. 1608 1609 mech_type Object ID, modify, optional Security mechanism 1610 used. The returned OID value will be a pointer 1611 into static storage, and should be treated as 1612 read-only by the caller (in particular, it does 1613 not need to be freed). If not required, specify 1614 NULL. 1615 1616 output_token buffer, opaque, modify Token to be passed to 1617 peer application. If the length field of the 1618 returned token buffer is 0, then no token need 1619 be passed to the peer application. If a non- 1620 zero length field is returned, the associated 1621 storage must be freed after use by the 1622 application with a call to gss_release_buffer(). 1623 1624 1625 1626Wray Standards Track [Page 29] 1627 1628RFC 2744 GSS-API V2: C-bindings January 2000 1629 1630 1631 ret_flags bit-mask, modify, optional Contains various 1632 independent flags, each of which indicates that 1633 the context supports a specific service option. 1634 If not needed, specify NULL. Symbolic names are 1635 provided for each flag, and the symbolic names 1636 corresponding to the required flags should be 1637 logically-ANDed with the ret_flags value to test 1638 whether a given option is supported by the 1639 context. The flags are: 1640 GSS_C_DELEG_FLAG 1641 True - Delegated credentials are available 1642 via the delegated_cred_handle 1643 parameter 1644 False - No credentials were delegated 1645 GSS_C_MUTUAL_FLAG 1646 True - Remote peer asked for mutual 1647 authentication 1648 False - Remote peer did not ask for mutual 1649 authentication 1650 GSS_C_REPLAY_FLAG 1651 True - replay of protected messages 1652 will be detected 1653 False - replayed messages will not be 1654 detected 1655 GSS_C_SEQUENCE_FLAG 1656 True - out-of-sequence protected 1657 messages will be detected 1658 False - out-of-sequence messages will not 1659 be detected 1660 GSS_C_CONF_FLAG 1661 True - Confidentiality service may be 1662 invoked by calling the gss_wrap 1663 routine 1664 False - No confidentiality service (via 1665 gss_wrap) available. gss_wrap will 1666 provide message encapsulation, 1667 data-origin authentication and 1668 integrity services only. 1669 GSS_C_INTEG_FLAG 1670 True - Integrity service may be invoked by 1671 calling either gss_get_mic or 1672 gss_wrap routines. 1673 False - Per-message integrity service 1674 unavailable. 1675 GSS_C_ANON_FLAG 1676 True - The initiator does not wish to 1677 be authenticated; the src_name 1678 parameter (if requested) contains 1679 1680 1681 1682Wray Standards Track [Page 30] 1683 1684RFC 2744 GSS-API V2: C-bindings January 2000 1685 1686 1687 an anonymous internal name. 1688 False - The initiator has been 1689 authenticated normally. 1690 GSS_C_PROT_READY_FLAG 1691 True - Protection services (as specified 1692 by the states of the GSS_C_CONF_FLAG 1693 and GSS_C_INTEG_FLAG) are available 1694 if the accompanying major status 1695 return value is either GSS_S_COMPLETE 1696 or GSS_S_CONTINUE_NEEDED. 1697 False - Protection services (as specified 1698 by the states of the GSS_C_CONF_FLAG 1699 and GSS_C_INTEG_FLAG) are available 1700 only if the accompanying major status 1701 return value is GSS_S_COMPLETE. 1702 GSS_C_TRANS_FLAG 1703 True - The resultant security context may 1704 be transferred to other processes via 1705 a call to gss_export_sec_context(). 1706 False - The security context is not 1707 transferable. 1708 All other bits should be set to zero. 1709 1710 time_rec Integer, modify, optional 1711 number of seconds for which the context will 1712 remain valid. Specify NULL if not required. 1713 1714 delegated_cred_handle 1715 gss_cred_id_t, modify, optional credential 1716 handle for credentials received from context 1717 initiator. Only valid if deleg_flag in 1718 ret_flags is true, in which case an explicit 1719 credential handle (i.e. not GSS_C_NO_CREDENTIAL) 1720 will be returned; if deleg_flag is false, 1721 gss_accept_context() will set this parameter to 1722 GSS_C_NO_CREDENTIAL. If a credential handle is 1723 returned, the associated resources must be 1724 released by the application after use with a 1725 call to gss_release_cred(). Specify NULL if not 1726 required. 1727 1728 minor_status Integer, modify 1729 Mechanism specific status code. 1730 1731 GSS_S_CONTINUE_NEEDED Indicates that a token from the peer 1732 application is required to complete the 1733 context, and that gss_accept_sec_context must 1734 be called again with that token. 1735 1736 1737 1738Wray Standards Track [Page 31] 1739 1740RFC 2744 GSS-API V2: C-bindings January 2000 1741 1742 1743 GSS_S_DEFECTIVE_TOKEN Indicates that consistency checks performed on 1744 the input_token failed. 1745 1746 GSS_S_DEFECTIVE_CREDENTIAL Indicates that consistency checks 1747 performed on the credential failed. 1748 1749 GSS_S_NO_CRED The supplied credentials were not valid for context 1750 acceptance, or the credential handle did not 1751 reference any credentials. 1752 1753 GSS_S_CREDENTIALS_EXPIRED The referenced credentials have expired. 1754 1755 GSS_S_BAD_BINDINGS The input_token contains different channel 1756 bindings to those specified via the 1757 input_chan_bindings parameter. 1758 1759 GSS_S_NO_CONTEXT Indicates that the supplied context handle did not 1760 refer to a valid context. 1761 1762 GSS_S_BAD_SIG The input_token contains an invalid MIC. 1763 1764 GSS_S_OLD_TOKEN The input_token was too old. This is a fatal error 1765 during context establishment. 1766 1767 GSS_S_DUPLICATE_TOKEN The input_token is valid, but is a duplicate of 1768 a token already processed. This is a fatal 1769 error during context establishment. 1770 1771 GSS_S_BAD_MECH The received token specified a mechanism that is 1772 not supported by the implementation or the 1773 provided credential. 1774 17755.2. gss_acquire_cred 1776 1777 OM_uint32 gss_acquire_cred ( 1778 OM_uint32 *minor_status, 1779 const gss_name_t desired_name, 1780 OM_uint32 time_req, 1781 const gss_OID_set desired_mechs, 1782 gss_cred_usage_t cred_usage, 1783 gss_cred_id_t *output_cred_handle, 1784 gss_OID_set *actual_mechs, 1785 OM_uint32 *time_rec) 1786 1787 1788 1789 1790 1791 1792 1793 1794Wray Standards Track [Page 32] 1795 1796RFC 2744 GSS-API V2: C-bindings January 2000 1797 1798 1799 Purpose: 1800 1801 Allows an application to acquire a handle for a pre-existing 1802 credential by name. GSS-API implementations must impose a local 1803 access-control policy on callers of this routine to prevent 1804 unauthorized callers from acquiring credentials to which they are not 1805 entitled. This routine is not intended to provide a "login to the 1806 network" function, as such a function would involve the creation of 1807 new credentials rather than merely acquiring a handle to existing 1808 credentials. Such functions, if required, should be defined in 1809 implementation-specific extensions to the API. 1810 1811 If desired_name is GSS_C_NO_NAME, the call is interpreted as a 1812 request for a credential handle that will invoke default behavior 1813 when passed to gss_init_sec_context() (if cred_usage is 1814 GSS_C_INITIATE or GSS_C_BOTH) or gss_accept_sec_context() (if 1815 cred_usage is GSS_C_ACCEPT or GSS_C_BOTH). 1816 1817 Mechanisms should honor the desired_mechs parameter, and return a 1818 credential that is suitable to use only with the requested 1819 mechanisms. An exception to this is the case where one underlying 1820 credential element can be shared by multiple mechanisms; in this case 1821 it is permissible for an implementation to indicate all mechanisms 1822 with which the credential element may be used. If desired_mechs is 1823 an empty set, behavior is undefined. 1824 1825 This routine is expected to be used primarily by context acceptors, 1826 since implementations are likely to provide mechanism-specific ways 1827 of obtaining GSS-API initiator credentials from the system login 1828 process. Some implementations may therefore not support the 1829 acquisition of GSS_C_INITIATE or GSS_C_BOTH credentials via 1830 gss_acquire_cred for any name other than GSS_C_NO_NAME, or a name 1831 produced by applying either gss_inquire_cred to a valid credential, 1832 or gss_inquire_context to an active context. 1833 1834 If credential acquisition is time-consuming for a mechanism, the 1835 mechanism may choose to delay the actual acquisition until the 1836 credential is required (e.g. by gss_init_sec_context or 1837 gss_accept_sec_context). Such mechanism-specific implementation 1838 decisions should be invisible to the calling application; thus a call 1839 of gss_inquire_cred immediately following the call of 1840 gss_acquire_cred must return valid credential data, and may therefore 1841 incur the overhead of a deferred credential acquisition. 1842 1843 1844 1845 1846 1847 1848 1849 1850Wray Standards Track [Page 33] 1851 1852RFC 2744 GSS-API V2: C-bindings January 2000 1853 1854 1855 Parameters: 1856 1857 desired_name gss_name_t, read 1858 Name of principal whose credential 1859 should be acquired 1860 1861 time_req Integer, read, optional 1862 number of seconds that credentials 1863 should remain valid. Specify GSS_C_INDEFINITE 1864 to request that the credentials have the maximum 1865 permitted lifetime. 1866 1867 desired_mechs Set of Object IDs, read, optional 1868 set of underlying security mechanisms that 1869 may be used. GSS_C_NO_OID_SET may be used 1870 to obtain an implementation-specific default. 1871 1872 cred_usage gss_cred_usage_t, read 1873 GSS_C_BOTH - Credentials may be used 1874 either to initiate or accept 1875 security contexts. 1876 GSS_C_INITIATE - Credentials will only be 1877 used to initiate security contexts. 1878 GSS_C_ACCEPT - Credentials will only be used to 1879 accept security contexts. 1880 1881 output_cred_handle gss_cred_id_t, modify 1882 The returned credential handle. Resources 1883 associated with this credential handle must 1884 be released by the application after use 1885 with a call to gss_release_cred(). 1886 1887 actual_mechs Set of Object IDs, modify, optional 1888 The set of mechanisms for which the 1889 credential is valid. Storage associated 1890 with the returned OID-set must be released by 1891 the application after use with a call to 1892 gss_release_oid_set(). Specify NULL if not 1893 required. 1894 1895 time_rec Integer, modify, optional 1896 Actual number of seconds for which the 1897 returned credentials will remain valid. If the 1898 implementation does not support expiration of 1899 credentials, the value GSS_C_INDEFINITE will 1900 be returned. Specify NULL if not required 1901 1902 1903 1904 1905 1906Wray Standards Track [Page 34] 1907 1908RFC 2744 GSS-API V2: C-bindings January 2000 1909 1910 1911 minor_status Integer, modify 1912 Mechanism specific status code. 1913 1914 Function value: GSS status code 1915 1916 GSS_S_COMPLETE Successful completion 1917 1918 GSS_S_BAD_MECH Unavailable mechanism requested 1919 1920 GSS_S_BAD_NAMETYPE Type contained within desired_name parameter 1921 is not supported 1922 1923 GSS_S_BAD_NAME Value supplied for desired_name parameter is ill 1924 formed. 1925 1926 GSS_S_CREDENTIALS_EXPIRED The credentials could not be acquired 1927 Because they have expired. 1928 1929 GSS_S_NO_CRED No credentials were found for the specified name. 1930 19315.3. gss_add_cred 1932 1933 OM_uint32 gss_add_cred ( 1934 OM_uint32 *minor_status, 1935 const gss_cred_id_t input_cred_handle, 1936 const gss_name_t desired_name, 1937 const gss_OID desired_mech, 1938 gss_cred_usage_t cred_usage, 1939 OM_uint32 initiator_time_req, 1940 OM_uint32 acceptor_time_req, 1941 gss_cred_id_t *output_cred_handle, 1942 gss_OID_set *actual_mechs, 1943 OM_uint32 *initiator_time_rec, 1944 OM_uint32 *acceptor_time_rec) 1945 1946 Purpose: 1947 1948 Adds a credential-element to a credential. The credential-element is 1949 identified by the name of the principal to which it refers. GSS-API 1950 implementations must impose a local access-control policy on callers 1951 of this routine to prevent unauthorized callers from acquiring 1952 credential-elements to which they are not entitled. This routine is 1953 not intended to provide a "login to the network" function, as such a 1954 function would involve the creation of new mechanism-specific 1955 authentication data, rather than merely acquiring a GSS-API handle to 1956 existing data. Such functions, if required, should be defined in 1957 implementation-specific extensions to the API. 1958 1959 1960 1961 1962Wray Standards Track [Page 35] 1963 1964RFC 2744 GSS-API V2: C-bindings January 2000 1965 1966 1967 If desired_name is GSS_C_NO_NAME, the call is interpreted as a 1968 request to add a credential element that will invoke default behavior 1969 when passed to gss_init_sec_context() (if cred_usage is 1970 GSS_C_INITIATE or GSS_C_BOTH) or gss_accept_sec_context() (if 1971 cred_usage is GSS_C_ACCEPT or GSS_C_BOTH). 1972 1973 This routine is expected to be used primarily by context acceptors, 1974 since implementations are likely to provide mechanism-specific ways 1975 of obtaining GSS-API initiator credentials from the system login 1976 process. Some implementations may therefore not support the 1977 acquisition of GSS_C_INITIATE or GSS_C_BOTH credentials via 1978 gss_acquire_cred for any name other than GSS_C_NO_NAME, or a name 1979 produced by applying either gss_inquire_cred to a valid credential, 1980 or gss_inquire_context to an active context. 1981 1982 If credential acquisition is time-consuming for a mechanism, the 1983 mechanism may choose to delay the actual acquisition until the 1984 credential is required (e.g. by gss_init_sec_context or 1985 gss_accept_sec_context). Such mechanism-specific implementation 1986 decisions should be invisible to the calling application; thus a call 1987 of gss_inquire_cred immediately following the call of gss_add_cred 1988 must return valid credential data, and may therefore incur the 1989 overhead of a deferred credential acquisition. 1990 1991 This routine can be used to either compose a new credential 1992 containing all credential-elements of the original in addition to the 1993 newly-acquire credential-element, or to add the new credential- 1994 element to an existing credential. If NULL is specified for the 1995 output_cred_handle parameter argument, the new credential-element 1996 will be added to the credential identified by input_cred_handle; if a 1997 valid pointer is specified for the output_cred_handle parameter, a 1998 new credential handle will be created. 1999 2000 If GSS_C_NO_CREDENTIAL is specified as the input_cred_handle, 2001 gss_add_cred will compose a credential (and set the 2002 output_cred_handle parameter accordingly) based on default behavior. 2003 That is, the call will have the same effect as if the application had 2004 first made a call to gss_acquire_cred(), specifying the same usage 2005 and passing GSS_C_NO_NAME as the desired_name parameter to obtain an 2006 explicit credential handle embodying default behavior, passed this 2007 credential handle to gss_add_cred(), and finally called 2008 gss_release_cred() on the first credential handle. 2009 2010 If GSS_C_NO_CREDENTIAL is specified as the input_cred_handle 2011 parameter, a non-NULL output_cred_handle must be supplied. 2012 2013 2014 2015 2016 2017 2018Wray Standards Track [Page 36] 2019 2020RFC 2744 GSS-API V2: C-bindings January 2000 2021 2022 2023 Parameters: 2024 2025 minor_status Integer, modify 2026 Mechanism specific status code. 2027 2028 input_cred_handle gss_cred_id_t, read, optional 2029 The credential to which a credential-element 2030 will be added. If GSS_C_NO_CREDENTIAL is 2031 specified, the routine will compose the new 2032 credential based on default behavior (see 2033 description above). Note that, while the 2034 credential-handle is not modified by 2035 gss_add_cred(), the underlying credential 2036 will be modified if output_credential_handle 2037 is NULL. 2038 2039 desired_name gss_name_t, read. 2040 Name of principal whose credential 2041 should be acquired. 2042 2043 desired_mech Object ID, read 2044 Underlying security mechanism with which the 2045 credential may be used. 2046 2047 cred_usage gss_cred_usage_t, read 2048 GSS_C_BOTH - Credential may be used 2049 either to initiate or accept 2050 security contexts. 2051 GSS_C_INITIATE - Credential will only be 2052 used to initiate security 2053 contexts. 2054 GSS_C_ACCEPT - Credential will only be used to 2055 accept security contexts. 2056 2057 initiator_time_req Integer, read, optional 2058 number of seconds that the credential 2059 should remain valid for initiating security 2060 contexts. This argument is ignored if the 2061 composed credentials are of type GSS_C_ACCEPT. 2062 Specify GSS_C_INDEFINITE to request that the 2063 credentials have the maximum permitted 2064 initiator lifetime. 2065 2066 acceptor_time_req Integer, read, optional 2067 number of seconds that the credential 2068 should remain valid for accepting security 2069 contexts. This argument is ignored if the 2070 composed credentials are of type GSS_C_INITIATE. 2071 2072 2073 2074Wray Standards Track [Page 37] 2075 2076RFC 2744 GSS-API V2: C-bindings January 2000 2077 2078 2079 Specify GSS_C_INDEFINITE to request that the 2080 credentials have the maximum permitted initiator 2081 lifetime. 2082 2083 output_cred_handle gss_cred_id_t, modify, optional 2084 The returned credential handle, containing 2085 the new credential-element and all the 2086 credential-elements from input_cred_handle. 2087 If a valid pointer to a gss_cred_id_t is 2088 supplied for this parameter, gss_add_cred 2089 creates a new credential handle containing all 2090 credential-elements from the input_cred_handle 2091 and the newly acquired credential-element; if 2092 NULL is specified for this parameter, the newly 2093 acquired credential-element will be added 2094 to the credential identified by input_cred_handle. 2095 2096 The resources associated with any credential 2097 handle returned via this parameter must be 2098 released by the application after use with a 2099 call to gss_release_cred(). 2100 2101 actual_mechs Set of Object IDs, modify, optional 2102 The complete set of mechanisms for which 2103 the new credential is valid. Storage for 2104 the returned OID-set must be freed by the 2105 application after use with a call to 2106 gss_release_oid_set(). Specify NULL if 2107 not required. 2108 2109 initiator_time_rec Integer, modify, optional 2110 Actual number of seconds for which the 2111 returned credentials will remain valid for 2112 initiating contexts using the specified 2113 mechanism. If the implementation or mechanism 2114 does not support expiration of credentials, the 2115 value GSS_C_INDEFINITE will be returned. Specify 2116 NULL if not required 2117 2118 acceptor_time_rec Integer, modify, optional 2119 Actual number of seconds for which the 2120 returned credentials will remain valid for 2121 accepting security contexts using the specified 2122 mechanism. If the implementation or mechanism 2123 does not support expiration of credentials, the 2124 value GSS_C_INDEFINITE will be returned. Specify 2125 NULL if not required 2126 2127 2128 2129 2130Wray Standards Track [Page 38] 2131 2132RFC 2744 GSS-API V2: C-bindings January 2000 2133 2134 2135 Function value: GSS status code 2136 2137 GSS_S_COMPLETE Successful completion 2138 2139 GSS_S_BAD_MECH Unavailable mechanism requested 2140 2141 GSS_S_BAD_NAMETYPE Type contained within desired_name parameter 2142 is not supported 2143 2144 GSS_S_BAD_NAME Value supplied for desired_name parameter is 2145 ill-formed. 2146 2147 GSS_S_DUPLICATE_ELEMENT The credential already contains an element 2148 for the requested mechanism with overlapping 2149 usage and validity period. 2150 2151 GSS_S_CREDENTIALS_EXPIRED The required credentials could not be 2152 added because they have expired. 2153 2154 GSS_S_NO_CRED No credentials were found for the specified name. 2155 21565.4. gss_add_oid_set_member 2157 2158 OM_uint32 gss_add_oid_set_member ( 2159 OM_uint32 *minor_status, 2160 const gss_OID member_oid, 2161 gss_OID_set *oid_set) 2162 2163 Purpose: 2164 2165 Add an Object Identifier to an Object Identifier set. This routine 2166 is intended for use in conjunction with gss_create_empty_oid_set when 2167 constructing a set of mechanism OIDs for input to gss_acquire_cred. 2168 The oid_set parameter must refer to an OID-set that was created by 2169 GSS-API (e.g. a set returned by gss_create_empty_oid_set()). GSS-API 2170 creates a copy of the member_oid and inserts this copy into the set, 2171 expanding the storage allocated to the OID-set's elements array if 2172 necessary. The routine may add the new member OID anywhere within 2173 the elements array, and implementations should verify that the new 2174 member_oid is not already contained within the elements array; if the 2175 member_oid is already present, the oid_set should remain unchanged. 2176 2177 Parameters: 2178 2179 minor_status Integer, modify 2180 Mechanism specific status code 2181 2182 2183 2184 2185 2186Wray Standards Track [Page 39] 2187 2188RFC 2744 GSS-API V2: C-bindings January 2000 2189 2190 2191 member_oid Object ID, read 2192 The object identifier to copied into 2193 the set. 2194 2195 oid_set Set of Object ID, modify 2196 The set in which the object identifier 2197 should be inserted. 2198 2199 Function value: GSS status code 2200 2201 GSS_S_COMPLETE Successful completion 2202 22035.5. gss_canonicalize_name 2204 2205 OM_uint32 gss_canonicalize_name ( 2206 OM_uint32 *minor_status, 2207 const gss_name_t input_name, 2208 const gss_OID mech_type, 2209 gss_name_t *output_name) 2210 2211 Purpose: 2212 2213 Generate a canonical mechanism name (MN) from an arbitrary internal 2214 name. The mechanism name is the name that would be returned to a 2215 context acceptor on successful authentication of a context where the 2216 initiator used the input_name in a successful call to 2217 gss_acquire_cred, specifying an OID set containing <mech_type> as its 2218 only member, followed by a call to gss_init_sec_context, specifying 2219 <mech_type> as the authentication mechanism. 2220 2221 Parameters: 2222 2223 minor_status Integer, modify 2224 Mechanism specific status code 2225 2226 input_name gss_name_t, read 2227 The name for which a canonical form is 2228 desired 2229 2230 mech_type Object ID, read 2231 The authentication mechanism for which the 2232 canonical form of the name is desired. The 2233 desired mechanism must be specified explicitly; 2234 no default is provided. 2235 2236 2237 2238 2239 2240 2241 2242Wray Standards Track [Page 40] 2243 2244RFC 2744 GSS-API V2: C-bindings January 2000 2245 2246 2247 output_name gss_name_t, modify 2248 The resultant canonical name. Storage 2249 associated with this name must be freed by 2250 the application after use with a call to 2251 gss_release_name(). 2252 2253 Function value: GSS status code 2254 2255 GSS_S_COMPLETE Successful completion. 2256 2257 GSS_S_BAD_MECH The identified mechanism is not supported. 2258 2259 GSS_S_BAD_NAMETYPE The provided internal name contains no elements 2260 that could be processed by the specified 2261 mechanism. 2262 2263 GSS_S_BAD_NAME The provided internal name was ill-formed. 2264 22655.6. gss_compare_name 2266 2267 OM_uint32 gss_compare_name ( 2268 OM_uint32 *minor_status, 2269 const gss_name_t name1, 2270 const gss_name_t name2, 2271 int *name_equal) 2272 2273 Purpose: 2274 2275 Allows an application to compare two internal-form names to determine 2276 whether they refer to the same entity. 2277 2278 If either name presented to gss_compare_name denotes an anonymous 2279 principal, the routines should indicate that the two names do not 2280 refer to the same identity. 2281 2282 Parameters: 2283 2284 minor_status Integer, modify 2285 Mechanism specific status code. 2286 2287 name1 gss_name_t, read 2288 internal-form name 2289 2290 name2 gss_name_t, read 2291 internal-form name 2292 2293 2294 2295 2296 2297 2298Wray Standards Track [Page 41] 2299 2300RFC 2744 GSS-API V2: C-bindings January 2000 2301 2302 2303 name_equal boolean, modify 2304 non-zero - names refer to same entity 2305 zero - names refer to different entities 2306 (strictly, the names are not known 2307 to refer to the same identity). 2308 2309 Function value: GSS status code 2310 2311 GSS_S_COMPLETE Successful completion 2312 2313 GSS_S_BAD_NAMETYPE The two names were of incomparable types. 2314 2315 GSS_S_BAD_NAME One or both of name1 or name2 was ill-formed. 2316 23175.7. gss_context_time 2318 2319 OM_uint32 gss_context_time ( 2320 OM_uint32 *minor_status, 2321 const gss_ctx_id_t context_handle, 2322 OM_uint32 *time_rec) 2323 2324 Purpose: 2325 2326 Determines the number of seconds for which the specified context will 2327 remain valid. 2328 2329 Parameters: 2330 2331 minor_status Integer, modify 2332 Implementation specific status code. 2333 2334 context_handle gss_ctx_id_t, read 2335 Identifies the context to be interrogated. 2336 2337 time_rec Integer, modify 2338 Number of seconds that the context will remain 2339 valid. If the context has already expired, 2340 zero will be returned. 2341 2342 Function value: GSS status code 2343 2344 GSS_S_COMPLETE Successful completion 2345 2346 GSS_S_CONTEXT_EXPIRED The context has already expired 2347 2348 GSS_S_NO_CONTEXT The context_handle parameter did not identify 2349 a valid context 2350 2351 2352 2353 2354Wray Standards Track [Page 42] 2355 2356RFC 2744 GSS-API V2: C-bindings January 2000 2357 2358 23595.8. gss_create_empty_oid_set 2360 2361 OM_uint32 gss_create_empty_oid_set ( 2362 OM_uint32 *minor_status, 2363 gss_OID_set *oid_set) 2364 2365 Purpose: 2366 2367 Create an object-identifier set containing no object identifiers, to 2368 which members may be subsequently added using the 2369 gss_add_oid_set_member() routine. These routines are intended to be 2370 used to construct sets of mechanism object identifiers, for input to 2371 gss_acquire_cred. 2372 2373 Parameters: 2374 2375 minor_status Integer, modify 2376 Mechanism specific status code 2377 2378 oid_set Set of Object IDs, modify 2379 The empty object identifier set. 2380 The routine will allocate the 2381 gss_OID_set_desc object, which the 2382 application must free after use with 2383 a call to gss_release_oid_set(). 2384 2385 Function value: GSS status code 2386 2387 GSS_S_COMPLETE Successful completion 2388 23895.9. gss_delete_sec_context 2390 2391 OM_uint32 gss_delete_sec_context ( 2392 OM_uint32 *minor_status, 2393 gss_ctx_id_t *context_handle, 2394 gss_buffer_t output_token) 2395 2396 Purpose: 2397 2398 Delete a security context. gss_delete_sec_context will delete the 2399 local data structures associated with the specified security context, 2400 and may generate an output_token, which when passed to the peer 2401 gss_process_context_token will instruct it to do likewise. If no 2402 token is required by the mechanism, the GSS-API should set the length 2403 field of the output_token (if provided) to zero. No further security 2404 services may be obtained using the context specified by 2405 context_handle. 2406 2407 2408 2409 2410Wray Standards Track [Page 43] 2411 2412RFC 2744 GSS-API V2: C-bindings January 2000 2413 2414 2415 In addition to deleting established security contexts, 2416 gss_delete_sec_context must also be able to delete "half-built" 2417 security contexts resulting from an incomplete sequence of 2418 gss_init_sec_context()/gss_accept_sec_context() calls. 2419 2420 The output_token parameter is retained for compatibility with version 2421 1 of the GSS-API. It is recommended that both peer applications 2422 invoke gss_delete_sec_context passing the value GSS_C_NO_BUFFER for 2423 the output_token parameter, indicating that no token is required, and 2424 that gss_delete_sec_context should simply delete local context data 2425 structures. If the application does pass a valid buffer to 2426 gss_delete_sec_context, mechanisms are encouraged to return a zero- 2427 length token, indicating that no peer action is necessary, and that 2428 no token should be transferred by the application. 2429 2430 Parameters: 2431 2432 minor_status Integer, modify 2433 Mechanism specific status code. 2434 2435 context_handle gss_ctx_id_t, modify 2436 context handle identifying context to delete. 2437 After deleting the context, the GSS-API will set 2438 this context handle to GSS_C_NO_CONTEXT. 2439 2440 output_token buffer, opaque, modify, optional 2441 token to be sent to remote application to 2442 instruct it to also delete the context. It 2443 is recommended that applications specify 2444 GSS_C_NO_BUFFER for this parameter, requesting 2445 local deletion only. If a buffer parameter is 2446 provided by the application, the mechanism may 2447 return a token in it; mechanisms that implement 2448 only local deletion should set the length field of 2449 this token to zero to indicate to the application 2450 that no token is to be sent to the peer. 2451 2452 Function value: GSS status code 2453 2454 GSS_S_COMPLETE Successful completion 2455 2456 GSS_S_NO_CONTEXT No valid context was supplied 2457 2458 2459 2460 2461 2462 2463 2464 2465 2466Wray Standards Track [Page 44] 2467 2468RFC 2744 GSS-API V2: C-bindings January 2000 2469 2470 24715.10.gss_display_name 2472 2473 OM_uint32 gss_display_name ( 2474 OM_uint32 *minor_status, 2475 const gss_name_t input_name, 2476 gss_buffer_t output_name_buffer, 2477 gss_OID *output_name_type) 2478 2479 Purpose: 2480 2481 Allows an application to obtain a textual representation of an opaque 2482 internal-form name for display purposes. The syntax of a printable 2483 name is defined by the GSS-API implementation. 2484 2485 If input_name denotes an anonymous principal, the implementation 2486 should return the gss_OID value GSS_C_NT_ANONYMOUS as the 2487 output_name_type, and a textual name that is syntactically distinct 2488 from all valid supported printable names in output_name_buffer. 2489 2490 If input_name was created by a call to gss_import_name, specifying 2491 GSS_C_NO_OID as the name-type, implementations that employ lazy 2492 conversion between name types may return GSS_C_NO_OID via the 2493 output_name_type parameter. 2494 2495 Parameters: 2496 2497 minor_status Integer, modify 2498 Mechanism specific status code. 2499 2500 input_name gss_name_t, read 2501 name to be displayed 2502 2503 output_name_buffer buffer, character-string, modify 2504 buffer to receive textual name string. 2505 The application must free storage associated 2506 with this name after use with a call to 2507 gss_release_buffer(). 2508 2509 output_name_type Object ID, modify, optional 2510 The type of the returned name. The returned 2511 gss_OID will be a pointer into static storage, 2512 and should be treated as read-only by the caller 2513 (in particular, the application should not attempt 2514 to free it). Specify NULL if not required. 2515 2516 2517 2518 2519 2520 2521 2522Wray Standards Track [Page 45] 2523 2524RFC 2744 GSS-API V2: C-bindings January 2000 2525 2526 2527 Function value: GSS status code 2528 2529 GSS_S_COMPLETE Successful completion 2530 2531 GSS_S_BAD_NAME input_name was ill-formed 2532 25335.11.gss_display_status 2534 2535 OM_uint32 gss_display_status ( 2536 OM_uint32 *minor_status, 2537 OM_uint32 status_value, 2538 int status_type, 2539 const gss_OID mech_type, 2540 OM_uint32 *message_context, 2541 gss_buffer_t status_string) 2542 2543 Purpose: 2544 2545 Allows an application to obtain a textual representation of a GSS-API 2546 status code, for display to the user or for logging purposes. Since 2547 some status values may indicate multiple conditions, applications may 2548 need to call gss_display_status multiple times, each call generating 2549 a single text string. The message_context parameter is used by 2550 gss_display_status to store state information about which error 2551 messages have already been extracted from a given status_value; 2552 message_context must be initialized to 0 by the application prior to 2553 the first call, and gss_display_status will return a non-zero value 2554 in this parameter if there are further messages to extract. 2555 2556 The message_context parameter contains all state information required 2557 by gss_display_status in order to extract further messages from the 2558 status_value; even when a non-zero value is returned in this 2559 parameter, the application is not required to call gss_display_status 2560 again unless subsequent messages are desired. The following code 2561 extracts all messages from a given status code and prints them to 2562 stderr: 2563 2564 OM_uint32 message_context; 2565 OM_uint32 status_code; 2566 OM_uint32 maj_status; 2567 OM_uint32 min_status; 2568 gss_buffer_desc status_string; 2569 2570 ... 2571 2572 message_context = 0; 2573 2574 do { 2575 2576 2577 2578Wray Standards Track [Page 46] 2579 2580RFC 2744 GSS-API V2: C-bindings January 2000 2581 2582 2583 maj_status = gss_display_status ( 2584 &min_status, 2585 status_code, 2586 GSS_C_GSS_CODE, 2587 GSS_C_NO_OID, 2588 &message_context, 2589 &status_string) 2590 2591 fprintf(stderr, 2592 "%.*s\n", 2593 (int)status_string.length, 2594 2595 (char *)status_string.value); 2596 2597 gss_release_buffer(&min_status, &status_string); 2598 2599 } while (message_context != 0); 2600 2601 2602 Parameters: 2603 2604 minor_status Integer, modify 2605 Mechanism specific status code. 2606 2607 status_value Integer, read 2608 Status value to be converted 2609 2610 status_type Integer, read 2611 GSS_C_GSS_CODE - status_value is a GSS status 2612 code 2613 2614 GSS_C_MECH_CODE - status_value is a mechanism 2615 status code 2616 2617 mech_type Object ID, read, optional 2618 Underlying mechanism (used to interpret a 2619 minor status value) Supply GSS_C_NO_OID to 2620 obtain the system default. 2621 2622 message_context Integer, read/modify 2623 Should be initialized to zero by the 2624 application prior to the first call. 2625 On return from gss_display_status(), 2626 a non-zero status_value parameter indicates 2627 that additional messages may be extracted 2628 from the status code via subsequent calls 2629 2630 2631 2632 2633 2634Wray Standards Track [Page 47] 2635 2636RFC 2744 GSS-API V2: C-bindings January 2000 2637 2638 2639 to gss_display_status(), passing the same 2640 status_value, status_type, mech_type, and 2641 message_context parameters. 2642 2643 status_string buffer, character string, modify 2644 textual interpretation of the status_value. 2645 Storage associated with this parameter must 2646 be freed by the application after use with 2647 a call to gss_release_buffer(). 2648 2649 Function value: GSS status code 2650 2651 GSS_S_COMPLETE Successful completion 2652 2653 GSS_S_BAD_MECH Indicates that translation in accordance with 2654 an unsupported mechanism type was requested 2655 2656 GSS_S_BAD_STATUS The status value was not recognized, or the 2657 status type was neither GSS_C_GSS_CODE nor 2658 GSS_C_MECH_CODE. 2659 26605.12. gss_duplicate_name 2661 2662 OM_uint32 gss_duplicate_name ( 2663 OM_uint32 *minor_status, 2664 const gss_name_t src_name, 2665 gss_name_t *dest_name) 2666 2667 Purpose: 2668 2669 Create an exact duplicate of the existing internal name src_name. 2670 The new dest_name will be independent of src_name (i.e. src_name and 2671 dest_name must both be released, and the release of one shall not 2672 affect the validity of the other). 2673 2674 Parameters: 2675 2676 minor_status Integer, modify 2677 Mechanism specific status code. 2678 2679 src_name gss_name_t, read 2680 internal name to be duplicated. 2681 2682 dest_name gss_name_t, modify 2683 The resultant copy of <src_name>. 2684 Storage associated with this name must 2685 be freed by the application after use 2686 with a call to gss_release_name(). 2687 2688 2689 2690Wray Standards Track [Page 48] 2691 2692RFC 2744 GSS-API V2: C-bindings January 2000 2693 2694 2695 Function value: GSS status code 2696 2697 GSS_S_COMPLETE Successful completion 2698 2699 GSS_S_BAD_NAME The src_name parameter was ill-formed. 2700 27015.13. gss_export_name 2702 2703 OM_uint32 gss_export_name ( 2704 OM_uint32 *minor_status, 2705 const gss_name_t input_name, 2706 gss_buffer_t exported_name) 2707 2708 Purpose: 2709 2710 To produce a canonical contiguous string representation of a 2711 mechanism name (MN), suitable for direct comparison (e.g. with 2712 memcmp) for use in authorization functions (e.g. matching entries in 2713 an access-control list). The <input_name> parameter must specify a 2714 valid MN (i.e. an internal name generated by gss_accept_sec_context 2715 or by gss_canonicalize_name). 2716 2717 Parameters: 2718 2719 minor_status Integer, modify 2720 Mechanism specific status code 2721 2722 input_name gss_name_t, read 2723 The MN to be exported 2724 2725 exported_name gss_buffer_t, octet-string, modify 2726 The canonical contiguous string form of 2727 <input_name>. Storage associated with 2728 this string must freed by the application 2729 after use with gss_release_buffer(). 2730 2731 Function value: GSS status code 2732 2733 GSS_S_COMPLETE Successful completion 2734 2735 GSS_S_NAME_NOT_MN The provided internal name was not a mechanism 2736 name. 2737 2738 GSS_S_BAD_NAME The provided internal name was ill-formed. 2739 2740 GSS_S_BAD_NAMETYPE The internal name was of a type not supported 2741 by the GSS-API implementation. 2742 2743 2744 2745 2746Wray Standards Track [Page 49] 2747 2748RFC 2744 GSS-API V2: C-bindings January 2000 2749 2750 27515.14. gss_export_sec_context 2752 2753 OM_uint32 gss_export_sec_context ( 2754 OM_uint32 *minor_status, 2755 gss_ctx_id_t *context_handle, 2756 gss_buffer_t interprocess_token) 2757 2758 Purpose: 2759 2760 Provided to support the sharing of work between multiple processes. 2761 This routine will typically be used by the context-acceptor, in an 2762 application where a single process receives incoming connection 2763 requests and accepts security contexts over them, then passes the 2764 established context to one or more other processes for message 2765 exchange. gss_export_sec_context() deactivates the security context 2766 for the calling process and creates an interprocess token which, when 2767 passed to gss_import_sec_context in another process, will re-activate 2768 the context in the second process. Only a single instantiation of a 2769 given context may be active at any one time; a subsequent attempt by 2770 a context exporter to access the exported security context will fail. 2771 2772 The implementation may constrain the set of processes by which the 2773 interprocess token may be imported, either as a function of local 2774 security policy, or as a result of implementation decisions. For 2775 example, some implementations may constrain contexts to be passed 2776 only between processes that run under the same account, or which are 2777 part of the same process group. 2778 2779 The interprocess token may contain security-sensitive information 2780 (for example cryptographic keys). While mechanisms are encouraged to 2781 either avoid placing such sensitive information within interprocess 2782 tokens, or to encrypt the token before returning it to the 2783 application, in a typical object-library GSS-API implementation this 2784 may not be possible. Thus the application must take care to protect 2785 the interprocess token, and ensure that any process to which the 2786 token is transferred is trustworthy. 2787 2788 If creation of the interprocess token is successful, the 2789 implementation shall deallocate all process-wide resources associated 2790 with the security context, and set the context_handle to 2791 GSS_C_NO_CONTEXT. In the event of an error that makes it impossible 2792 to complete the export of the security context, the implementation 2793 must not return an interprocess token, and should strive to leave the 2794 security context referenced by the context_handle parameter 2795 untouched. If this is impossible, it is permissible for the 2796 implementation to delete the security context, providing it also sets 2797 the context_handle parameter to GSS_C_NO_CONTEXT. 2798 2799 2800 2801 2802Wray Standards Track [Page 50] 2803 2804RFC 2744 GSS-API V2: C-bindings January 2000 2805 2806 2807 Parameters: 2808 2809 minor_status Integer, modify 2810 Mechanism specific status code 2811 2812 context_handle gss_ctx_id_t, modify 2813 context handle identifying the context to 2814 transfer. 2815 2816 interprocess_token buffer, opaque, modify 2817 token to be transferred to target process. 2818 Storage associated with this token must be 2819 freed by the application after use with a 2820 call to gss_release_buffer(). 2821 2822 Function value: GSS status code 2823 2824 GSS_S_COMPLETE Successful completion 2825 2826 GSS_S_CONTEXT_EXPIRED The context has expired 2827 2828 GSS_S_NO_CONTEXT The context was invalid 2829 2830 GSS_S_UNAVAILABLE The operation is not supported. 2831 28325.15. gss_get_mic 2833 2834 OM_uint32 gss_get_mic ( 2835 OM_uint32 *minor_status, 2836 const gss_ctx_id_t context_handle, 2837 gss_qop_t qop_req, 2838 const gss_buffer_t message_buffer, 2839 gss_buffer_t msg_token) 2840 2841 Purpose: 2842 2843 Generates a cryptographic MIC for the supplied message, and places 2844 the MIC in a token for transfer to the peer application. The qop_req 2845 parameter allows a choice between several cryptographic algorithms, 2846 if supported by the chosen mechanism. 2847 2848 Since some application-level protocols may wish to use tokens emitted 2849 by gss_wrap() to provide "secure framing", implementations must 2850 support derivation of MICs from zero-length messages. 2851 2852 2853 2854 2855 2856 2857 2858Wray Standards Track [Page 51] 2859 2860RFC 2744 GSS-API V2: C-bindings January 2000 2861 2862 2863 Parameters: 2864 2865 minor_status Integer, modify 2866 Implementation specific status code. 2867 2868 context_handle gss_ctx_id_t, read 2869 identifies the context on which the message 2870 will be sent 2871 2872 qop_req gss_qop_t, read, optional 2873 Specifies requested quality of protection. 2874 Callers are encouraged, on portability grounds, 2875 to accept the default quality of protection 2876 offered by the chosen mechanism, which may be 2877 requested by specifying GSS_C_QOP_DEFAULT for 2878 this parameter. If an unsupported protection 2879 strength is requested, gss_get_mic will return a 2880 major_status of GSS_S_BAD_QOP. 2881 2882 message_buffer buffer, opaque, read 2883 message to be protected 2884 2885 msg_token buffer, opaque, modify 2886 buffer to receive token. The application must 2887 free storage associated with this buffer after 2888 use with a call to gss_release_buffer(). 2889 2890 Function value: GSS status code 2891 2892 GSS_S_COMPLETE Successful completion 2893 2894 GSS_S_CONTEXT_EXPIRED The context has already expired 2895 2896 GSS_S_NO_CONTEXT The context_handle parameter did not identify 2897 a valid context 2898 2899 GSS_S_BAD_QOP The specified QOP is not supported by the 2900 mechanism. 2901 29025.16. gss_import_name 2903 2904 OM_uint32 gss_import_name ( 2905 OM_uint32 *minor_status, 2906 const gss_buffer_t input_name_buffer, 2907 const gss_OID input_name_type, 2908 gss_name_t *output_name) 2909 2910 2911 2912 2913 2914Wray Standards Track [Page 52] 2915 2916RFC 2744 GSS-API V2: C-bindings January 2000 2917 2918 2919 Purpose: 2920 2921 Convert a contiguous string name to internal form. In general, the 2922 internal name returned (via the <output_name> parameter) will not be 2923 an MN; the exception to this is if the <input_name_type> indicates 2924 that the contiguous string provided via the <input_name_buffer> 2925 parameter is of type GSS_C_NT_EXPORT_NAME, in which case the returned 2926 internal name will be an MN for the mechanism that exported the name. 2927 2928 Parameters: 2929 2930 minor_status Integer, modify 2931 Mechanism specific status code 2932 2933 input_name_buffer buffer, octet-string, read 2934 buffer containing contiguous string name to convert 2935 2936 input_name_type Object ID, read, optional 2937 Object ID specifying type of printable 2938 name. Applications may specify either 2939 GSS_C_NO_OID to use a mechanism-specific 2940 default printable syntax, or an OID recognized 2941 by the GSS-API implementation to name a 2942 specific namespace. 2943 2944 output_name gss_name_t, modify 2945 returned name in internal form. Storage 2946 associated with this name must be freed 2947 by the application after use with a call 2948 to gss_release_name(). 2949 2950 Function value: GSS status code 2951 2952 GSS_S_COMPLETE Successful completion 2953 2954 GSS_S_BAD_NAMETYPE The input_name_type was unrecognized 2955 2956 GSS_S_BAD_NAME The input_name parameter could not be interpreted 2957 as a name of the specified type 2958 2959 GSS_S_BAD_MECH The input name-type was GSS_C_NT_EXPORT_NAME, 2960 but the mechanism contained within the 2961 input-name is not supported 2962 2963 2964 2965 2966 2967 2968 2969 2970Wray Standards Track [Page 53] 2971 2972RFC 2744 GSS-API V2: C-bindings January 2000 2973 2974 29755.17. gss_import_sec_context 2976 2977 OM_uint32 gss_import_sec_context ( 2978 OM_uint32 *minor_status, 2979 const gss_buffer_t interprocess_token, 2980 gss_ctx_id_t *context_handle) 2981 2982 Purpose: 2983 2984 Allows a process to import a security context established by another 2985 process. A given interprocess token may be imported only once. See 2986 gss_export_sec_context. 2987 2988 Parameters: 2989 2990 minor_status Integer, modify 2991 Mechanism specific status code 2992 2993 interprocess_token buffer, opaque, modify 2994 token received from exporting process 2995 2996 context_handle gss_ctx_id_t, modify 2997 context handle of newly reactivated context. 2998 Resources associated with this context handle 2999 must be released by the application after use 3000 with a call to gss_delete_sec_context(). 3001 3002 Function value: GSS status code 3003 3004 GSS_S_COMPLETE Successful completion. 3005 3006 GSS_S_NO_CONTEXT The token did not contain a valid context 3007 reference. 3008 3009 GSS_S_DEFECTIVE_TOKEN The token was invalid. 3010 3011 GSS_S_UNAVAILABLE The operation is unavailable. 3012 3013 GSS_S_UNAUTHORIZED Local policy prevents the import of this context 3014 by the current process. 3015 30165.18. gss_indicate_mechs 3017 3018 OM_uint32 gss_indicate_mechs ( 3019 OM_uint32 *minor_status, 3020 gss_OID_set *mech_set) 3021 3022 3023 3024 3025 3026Wray Standards Track [Page 54] 3027 3028RFC 2744 GSS-API V2: C-bindings January 2000 3029 3030 3031 Purpose: 3032 3033 Allows an application to determine which underlying security 3034 mechanisms are available. 3035 3036 Parameters: 3037 3038 minor_status Integer, modify 3039 Mechanism specific status code. 3040 3041 mech_set set of Object IDs, modify 3042 set of implementation-supported mechanisms. 3043 The returned gss_OID_set value will be a 3044 dynamically-allocated OID set, that should 3045 be released by the caller after use with a 3046 call to gss_release_oid_set(). 3047 3048 Function value: GSS status code 3049 3050 GSS_S_COMPLETE Successful completion 3051 30525.19. gss_init_sec_context 3053 3054 OM_uint32 gss_init_sec_context ( 3055 OM_uint32 *minor_status, 3056 const gss_cred_id_t initiator_cred_handle, 3057 gss_ctx_id_t *context_handle,\ 3058 const gss_name_t target_name, 3059 const gss_OID mech_type, 3060 OM_uint32 req_flags, 3061 OM_uint32 time_req, 3062 const gss_channel_bindings_t input_chan_bindings, 3063 const gss_buffer_t input_token 3064 gss_OID *actual_mech_type, 3065 gss_buffer_t output_token, 3066 OM_uint32 *ret_flags, 3067 OM_uint32 *time_rec ) 3068 3069 Purpose: 3070 3071 Initiates the establishment of a security context between the 3072 application and a remote peer. Initially, the input_token parameter 3073 should be specified either as GSS_C_NO_BUFFER, or as a pointer to a 3074 gss_buffer_desc object whose length field contains the value zero. 3075 The routine may return a output_token which should be transferred to 3076 the peer application, where the peer application will present it to 3077 gss_accept_sec_context. If no token need be sent, 3078 gss_init_sec_context will indicate this by setting the length field 3079 3080 3081 3082Wray Standards Track [Page 55] 3083 3084RFC 2744 GSS-API V2: C-bindings January 2000 3085 3086 3087 of the output_token argument to zero. To complete the context 3088 establishment, one or more reply tokens may be required from the peer 3089 application; if so, gss_init_sec_context will return a status 3090 containing the supplementary information bit GSS_S_CONTINUE_NEEDED. 3091 In this case, gss_init_sec_context should be called again when the 3092 reply token is received from the peer application, passing the reply 3093 token to gss_init_sec_context via the input_token parameters. 3094 3095 Portable applications should be constructed to use the token length 3096 and return status to determine whether a token needs to be sent or 3097 waited for. Thus a typical portable caller should always invoke 3098 gss_init_sec_context within a loop: 3099 3100 int context_established = 0; 3101 gss_ctx_id_t context_hdl = GSS_C_NO_CONTEXT; 3102 ... 3103 input_token->length = 0; 3104 3105 while (!context_established) { 3106 maj_stat = gss_init_sec_context(&min_stat, 3107 cred_hdl, 3108 &context_hdl, 3109 target_name, 3110 desired_mech, 3111 desired_services, 3112 desired_time, 3113 input_bindings, 3114 input_token, 3115 &actual_mech, 3116 output_token, 3117 &actual_services, 3118 &actual_time); 3119 if (GSS_ERROR(maj_stat)) { 3120 report_error(maj_stat, min_stat); 3121 }; 3122 3123 if (output_token->length != 0) { 3124 send_token_to_peer(output_token); 3125 gss_release_buffer(&min_stat, output_token) 3126 }; 3127 if (GSS_ERROR(maj_stat)) { 3128 3129 if (context_hdl != GSS_C_NO_CONTEXT) 3130 gss_delete_sec_context(&min_stat, 3131 &context_hdl, 3132 GSS_C_NO_BUFFER); 3133 break; 3134 }; 3135 3136 3137 3138Wray Standards Track [Page 56] 3139 3140RFC 2744 GSS-API V2: C-bindings January 2000 3141 3142 3143 if (maj_stat & GSS_S_CONTINUE_NEEDED) { 3144 receive_token_from_peer(input_token); 3145 } else { 3146 context_established = 1; 3147 }; 3148 }; 3149 3150 Whenever the routine returns a major status that includes the value 3151 GSS_S_CONTINUE_NEEDED, the context is not fully established and the 3152 following restrictions apply to the output parameters: 3153 3154 The value returned via the time_rec parameter is undefined Unless 3155 the accompanying ret_flags parameter contains the bit 3156 GSS_C_PROT_READY_FLAG, indicating that per-message services may be 3157 applied in advance of a successful completion status, the value 3158 returned via the actual_mech_type parameter is undefined until the 3159 routine returns a major status value of GSS_S_COMPLETE. 3160 3161 The values of the GSS_C_DELEG_FLAG, GSS_C_MUTUAL_FLAG, 3162 GSS_C_REPLAY_FLAG, GSS_C_SEQUENCE_FLAG, GSS_C_CONF_FLAG, 3163 GSS_C_INTEG_FLAG and GSS_C_ANON_FLAG bits returned via the 3164 ret_flags parameter should contain the values that the 3165 implementation expects would be valid if context establishment 3166 were to succeed. In particular, if the application has requested 3167 a service such as delegation or anonymous authentication via the 3168 req_flags argument, and such a service is unavailable from the 3169 underlying mechanism, gss_init_sec_context should generate a token 3170 that will not provide the service, and indicate via the ret_flags 3171 argument that the service will not be supported. The application 3172 may choose to abort the context establishment by calling 3173 gss_delete_sec_context (if it cannot continue in the absence of 3174 the service), or it may choose to transmit the token and continue 3175 context establishment (if the service was merely desired but not 3176 mandatory). 3177 3178 The values of the GSS_C_PROT_READY_FLAG and GSS_C_TRANS_FLAG bits 3179 within ret_flags should indicate the actual state at the time 3180 gss_init_sec_context returns, whether or not the context is fully 3181 established. 3182 3183 GSS-API implementations that support per-message protection are 3184 encouraged to set the GSS_C_PROT_READY_FLAG in the final ret_flags 3185 returned to a caller (i.e. when accompanied by a GSS_S_COMPLETE 3186 status code). However, applications should not rely on this 3187 behavior as the flag was not defined in Version 1 of the GSS-API. 3188 Instead, applications should determine what per-message services 3189 are available after a successful context establishment according 3190 to the GSS_C_INTEG_FLAG and GSS_C_CONF_FLAG values. 3191 3192 3193 3194Wray Standards Track [Page 57] 3195 3196RFC 2744 GSS-API V2: C-bindings January 2000 3197 3198 3199 All other bits within the ret_flags argument should be set to 3200 zero. 3201 3202 If the initial call of gss_init_sec_context() fails, the 3203 implementation should not create a context object, and should leave 3204 the value of the context_handle parameter set to GSS_C_NO_CONTEXT to 3205 indicate this. In the event of a failure on a subsequent call, the 3206 implementation is permitted to delete the "half-built" security 3207 context (in which case it should set the context_handle parameter to 3208 GSS_C_NO_CONTEXT), but the preferred behavior is to leave the 3209 security context untouched for the application to delete (using 3210 gss_delete_sec_context). 3211 3212 During context establishment, the informational status bits 3213 GSS_S_OLD_TOKEN and GSS_S_DUPLICATE_TOKEN indicate fatal errors, and 3214 GSS-API mechanisms should always return them in association with a 3215 routine error of GSS_S_FAILURE. This requirement for pairing did not 3216 exist in version 1 of the GSS-API specification, so applications that 3217 wish to run over version 1 implementations must special-case these 3218 codes. 3219 3220 Parameters: 3221 3222 minor_status Integer, modify 3223 Mechanism specific status code. 3224 3225 initiator_cred_handle gss_cred_id_t, read, optional 3226 handle for credentials claimed. Supply 3227 GSS_C_NO_CREDENTIAL to act as a default 3228 initiator principal. If no default 3229 initiator is defined, the function will 3230 return GSS_S_NO_CRED. 3231 3232 context_handle gss_ctx_id_t, read/modify 3233 context handle for new context. Supply 3234 GSS_C_NO_CONTEXT for first call; use value 3235 returned by first call in continuation calls. 3236 Resources associated with this context-handle 3237 must be released by the application after use 3238 with a call to gss_delete_sec_context(). 3239 3240 target_name gss_name_t, read 3241 Name of target 3242 3243 mech_type OID, read, optional 3244 Object ID of desired mechanism. Supply 3245 GSS_C_NO_OID to obtain an implementation 3246 specific default 3247 3248 3249 3250Wray Standards Track [Page 58] 3251 3252RFC 2744 GSS-API V2: C-bindings January 2000 3253 3254 3255 req_flags bit-mask, read 3256 Contains various independent flags, each of 3257 which requests that the context support a 3258 specific service option. Symbolic 3259 names are provided for each flag, and the 3260 symbolic names corresponding to the required 3261 flags should be logically-ORed 3262 together to form the bit-mask value. The 3263 flags are: 3264 3265 GSS_C_DELEG_FLAG 3266 True - Delegate credentials to remote peer 3267 False - Don't delegate 3268 3269 GSS_C_MUTUAL_FLAG 3270 True - Request that remote peer 3271 authenticate itself 3272 False - Authenticate self to remote peer 3273 only 3274 3275 GSS_C_REPLAY_FLAG 3276 True - Enable replay detection for 3277 messages protected with gss_wrap 3278 or gss_get_mic 3279 False - Don't attempt to detect 3280 replayed messages 3281 3282 GSS_C_SEQUENCE_FLAG 3283 True - Enable detection of out-of-sequence 3284 protected messages 3285 False - Don't attempt to detect 3286 out-of-sequence messages 3287 3288 GSS_C_CONF_FLAG 3289 True - Request that confidentiality service 3290 be made available (via gss_wrap) 3291 False - No per-message confidentiality service 3292 is required. 3293 3294 GSS_C_INTEG_FLAG 3295 True - Request that integrity service be 3296 made available (via gss_wrap or 3297 gss_get_mic) 3298 False - No per-message integrity service 3299 is required. 3300 3301 3302 3303 3304 3305 3306Wray Standards Track [Page 59] 3307 3308RFC 2744 GSS-API V2: C-bindings January 2000 3309 3310 3311 GSS_C_ANON_FLAG 3312 True - Do not reveal the initiator's 3313 identity to the acceptor. 3314 False - Authenticate normally. 3315 3316 time_req Integer, read, optional 3317 Desired number of seconds for which context 3318 should remain valid. Supply 0 to request a 3319 default validity period. 3320 3321 input_chan_bindings channel bindings, read, optional 3322 Application-specified bindings. Allows 3323 application to securely bind channel 3324 identification information to the security 3325 context. Specify GSS_C_NO_CHANNEL_BINDINGS 3326 if channel bindings are not used. 3327 3328 input_token buffer, opaque, read, optional (see text) 3329 Token received from peer application. 3330 Supply GSS_C_NO_BUFFER, or a pointer to 3331 a buffer containing the value GSS_C_EMPTY_BUFFER 3332 on initial call. 3333 3334 actual_mech_type OID, modify, optional 3335 Actual mechanism used. The OID returned via 3336 this parameter will be a pointer to static 3337 storage that should be treated as read-only; 3338 In particular the application should not attempt 3339 to free it. Specify NULL if not required. 3340 3341 output_token buffer, opaque, modify 3342 token to be sent to peer application. If 3343 the length field of the returned buffer is 3344 zero, no token need be sent to the peer 3345 application. Storage associated with this 3346 buffer must be freed by the application 3347 after use with a call to gss_release_buffer(). 3348 3349 ret_flags bit-mask, modify, optional 3350 Contains various independent flags, each of which 3351 indicates that the context supports a specific 3352 service option. Specify NULL if not 3353 required. Symbolic names are provided 3354 for each flag, and the symbolic names 3355 corresponding to the required flags should be 3356 logically-ANDed with the ret_flags value to test 3357 whether a given option is supported by the 3358 context. The flags are: 3359 3360 3361 3362Wray Standards Track [Page 60] 3363 3364RFC 2744 GSS-API V2: C-bindings January 2000 3365 3366 3367 GSS_C_DELEG_FLAG 3368 True - Credentials were delegated to 3369 the remote peer 3370 False - No credentials were delegated 3371 3372 GSS_C_MUTUAL_FLAG 3373 True - The remote peer has authenticated 3374 itself. 3375 False - Remote peer has not authenticated 3376 itself. 3377 3378 GSS_C_REPLAY_FLAG 3379 True - replay of protected messages 3380 will be detected 3381 False - replayed messages will not be 3382 detected 3383 3384 GSS_C_SEQUENCE_FLAG 3385 True - out-of-sequence protected 3386 messages will be detected 3387 False - out-of-sequence messages will 3388 not be detected 3389 3390 GSS_C_CONF_FLAG 3391 True - Confidentiality service may be 3392 invoked by calling gss_wrap routine 3393 False - No confidentiality service (via 3394 gss_wrap) available. gss_wrap will 3395 provide message encapsulation, 3396 data-origin authentication and 3397 integrity services only. 3398 3399 GSS_C_INTEG_FLAG 3400 True - Integrity service may be invoked by 3401 calling either gss_get_mic or gss_wrap 3402 routines. 3403 False - Per-message integrity service 3404 unavailable. 3405 3406 GSS_C_ANON_FLAG 3407 True - The initiator's identity has not been 3408 revealed, and will not be revealed if 3409 any emitted token is passed to the 3410 acceptor. 3411 False - The initiator's identity has been or 3412 will be authenticated normally. 3413 3414 GSS_C_PROT_READY_FLAG 3415 3416 3417 3418Wray Standards Track [Page 61] 3419 3420RFC 2744 GSS-API V2: C-bindings January 2000 3421 3422 3423 True - Protection services (as specified 3424 by the states of the GSS_C_CONF_FLAG 3425 and GSS_C_INTEG_FLAG) are available for 3426 use if the accompanying major status 3427 return value is either GSS_S_COMPLETE or 3428 GSS_S_CONTINUE_NEEDED. 3429 False - Protection services (as specified 3430 by the states of the GSS_C_CONF_FLAG 3431 and GSS_C_INTEG_FLAG) are available 3432 only if the accompanying major status 3433 return value is GSS_S_COMPLETE. 3434 3435 GSS_C_TRANS_FLAG 3436 True - The resultant security context may 3437 be transferred to other processes via 3438 a call to gss_export_sec_context(). 3439 False - The security context is not 3440 transferable. 3441 3442 All other bits should be set to zero. 3443 3444 time_rec Integer, modify, optional 3445 number of seconds for which the context 3446 will remain valid. If the implementation does 3447 not support context expiration, the value 3448 GSS_C_INDEFINITE will be returned. Specify 3449 NULL if not required. 3450 3451 Function value: GSS status code 3452 3453 GSS_S_COMPLETE Successful completion 3454 3455 GSS_S_CONTINUE_NEEDED Indicates that a token from the peer 3456 application is required to complete the 3457 context, and that gss_init_sec_context 3458 must be called again with that token. 3459 3460 GSS_S_DEFECTIVE_TOKEN Indicates that consistency checks performed 3461 on the input_token failed 3462 3463 GSS_S_DEFECTIVE_CREDENTIAL Indicates that consistency checks 3464 performed on the credential failed. 3465 3466 GSS_S_NO_CRED The supplied credentials were not valid for 3467 context initiation, or the credential handle 3468 did not reference any credentials. 3469 3470 GSS_S_CREDENTIALS_EXPIRED The referenced credentials have expired 3471 3472 3473 3474Wray Standards Track [Page 62] 3475 3476RFC 2744 GSS-API V2: C-bindings January 2000 3477 3478 3479 GSS_S_BAD_BINDINGS The input_token contains different channel 3480 bindings to those specified via the 3481 input_chan_bindings parameter 3482 3483 GSS_S_BAD_SIG The input_token contains an invalid MIC, or a MIC 3484 that could not be verified 3485 3486 GSS_S_OLD_TOKEN The input_token was too old. This is a fatal 3487 error during context establishment 3488 3489 GSS_S_DUPLICATE_TOKEN The input_token is valid, but is a duplicate 3490 of a token already processed. This is a 3491 fatal error during context establishment. 3492 3493 GSS_S_NO_CONTEXT Indicates that the supplied context handle did 3494 not refer to a valid context 3495 3496 GSS_S_BAD_NAMETYPE The provided target_name parameter contained an 3497 invalid or unsupported type of name 3498 3499 GSS_S_BAD_NAME The provided target_name parameter was ill-formed. 3500 3501 GSS_S_BAD_MECH The specified mechanism is not supported by the 3502 provided credential, or is unrecognized by the 3503 implementation. 3504 35055.20. gss_inquire_context 3506 3507 OM_uint32 gss_inquire_context ( 3508 OM_uint32 *minor_status, 3509 const gss_ctx_id_t context_handle, 3510 gss_name_t *src_name, 3511 gss_name_t *targ_name, 3512 OM_uint32 *lifetime_rec, 3513 gss_OID *mech_type, 3514 OM_uint32 *ctx_flags, 3515 int *locally_initiated, 3516 int *open ) 3517 3518 Purpose: 3519 3520 Obtains information about a security context. The caller must 3521 already have obtained a handle that refers to the context, although 3522 the context need not be fully established. 3523 3524 3525 3526 3527 3528 3529 3530Wray Standards Track [Page 63] 3531 3532RFC 2744 GSS-API V2: C-bindings January 2000 3533 3534 3535 Parameters: 3536 3537 minor_status Integer, modify 3538 Mechanism specific status code 3539 3540 context_handle gss_ctx_id_t, read 3541 A handle that refers to the security context. 3542 3543 src_name gss_name_t, modify, optional 3544 The name of the context initiator. 3545 If the context was established using anonymous 3546 authentication, and if the application invoking 3547 gss_inquire_context is the context acceptor, 3548 an anonymous name will be returned. Storage 3549 associated with this name must be freed by the 3550 application after use with a call to 3551 gss_release_name(). Specify NULL if not 3552 required. 3553 3554 targ_name gss_name_t, modify, optional 3555 The name of the context acceptor. 3556 Storage associated with this name must be 3557 freed by the application after use with a call 3558 to gss_release_name(). If the context acceptor 3559 did not authenticate itself, and if the initiator 3560 did not specify a target name in its call to 3561 gss_init_sec_context(), the value GSS_C_NO_NAME 3562 will be returned. Specify NULL if not required. 3563 3564 lifetime_rec Integer, modify, optional 3565 The number of seconds for which the context 3566 will remain valid. If the context has 3567 expired, this parameter will be set to zero. 3568 If the implementation does not support 3569 context expiration, the value 3570 GSS_C_INDEFINITE will be returned. Specify 3571 NULL if not required. 3572 3573 mech_type gss_OID, modify, optional 3574 The security mechanism providing the 3575 context. The returned OID will be a 3576 pointer to static storage that should 3577 be treated as read-only by the application; 3578 in particular the application should not 3579 attempt to free it. Specify NULL if not 3580 required. 3581 3582 3583 3584 3585 3586Wray Standards Track [Page 64] 3587 3588RFC 2744 GSS-API V2: C-bindings January 2000 3589 3590 3591 ctx_flags bit-mask, modify, optional 3592 Contains various independent flags, each of 3593 which indicates that the context supports 3594 (or is expected to support, if ctx_open is 3595 false) a specific service option. If not 3596 needed, specify NULL. Symbolic names are 3597 provided for each flag, and the symbolic names 3598 corresponding to the required flags 3599 should be logically-ANDed with the ret_flags 3600 value to test whether a given option is 3601 supported by the context. The flags are: 3602 3603 GSS_C_DELEG_FLAG 3604 True - Credentials were delegated from 3605 the initiator to the acceptor. 3606 False - No credentials were delegated 3607 3608 GSS_C_MUTUAL_FLAG 3609 True - The acceptor was authenticated 3610 to the initiator 3611 False - The acceptor did not authenticate 3612 itself. 3613 3614 GSS_C_REPLAY_FLAG 3615 True - replay of protected messages 3616 will be detected 3617 False - replayed messages will not be 3618 detected 3619 3620 GSS_C_SEQUENCE_FLAG 3621 True - out-of-sequence protected 3622 messages will be detected 3623 False - out-of-sequence messages will not 3624 be detected 3625 3626 GSS_C_CONF_FLAG 3627 True - Confidentiality service may be invoked 3628 by calling gss_wrap routine 3629 False - No confidentiality service (via 3630 gss_wrap) available. gss_wrap will 3631 provide message encapsulation, 3632 data-origin authentication and 3633 integrity services only. 3634 3635 GSS_C_INTEG_FLAG 3636 True - Integrity service may be invoked by 3637 calling either gss_get_mic or gss_wrap 3638 routines. 3639 3640 3641 3642Wray Standards Track [Page 65] 3643 3644RFC 2744 GSS-API V2: C-bindings January 2000 3645 3646 3647 False - Per-message integrity service 3648 unavailable. 3649 3650 GSS_C_ANON_FLAG 3651 True - The initiator's identity will not 3652 be revealed to the acceptor. 3653 The src_name parameter (if 3654 requested) contains an anonymous 3655 internal name. 3656 False - The initiator has been 3657 authenticated normally. 3658 3659 GSS_C_PROT_READY_FLAG 3660 True - Protection services (as specified 3661 by the states of the GSS_C_CONF_FLAG 3662 and GSS_C_INTEG_FLAG) are available 3663 for use. 3664 False - Protection services (as specified 3665 by the states of the GSS_C_CONF_FLAG 3666 and GSS_C_INTEG_FLAG) are available 3667 only if the context is fully 3668 established (i.e. if the open parameter 3669 is non-zero). 3670 3671 GSS_C_TRANS_FLAG 3672 True - The resultant security context may 3673 be transferred to other processes via 3674 a call to gss_export_sec_context(). 3675 False - The security context is not 3676 transferable. 3677 3678 locally_initiated Boolean, modify 3679 Non-zero if the invoking application is the 3680 context initiator. 3681 Specify NULL if not required. 3682 3683 open Boolean, modify 3684 Non-zero if the context is fully established; 3685 Zero if a context-establishment token 3686 is expected from the peer application. 3687 Specify NULL if not required. 3688 3689 Function value: GSS status code 3690 3691 GSS_S_COMPLETE Successful completion 3692 3693 GSS_S_NO_CONTEXT The referenced context could not be accessed. 3694 3695 3696 3697 3698Wray Standards Track [Page 66] 3699 3700RFC 2744 GSS-API V2: C-bindings January 2000 3701 3702 37035.21. gss_inquire_cred 3704 3705 OM_uint32 gss_inquire_cred ( 3706 OM_uint32 *minor_status, 3707 const gss_cred_id_t cred_handle, 3708 gss_name_t *name, 3709 OM_uint32 *lifetime, 3710 gss_cred_usage_t *cred_usage, 3711 gss_OID_set *mechanisms ) 3712 3713 Purpose: 3714 3715 Obtains information about a credential. 3716 3717 Parameters: 3718 3719 minor_status Integer, modify 3720 Mechanism specific status code 3721 3722 cred_handle gss_cred_id_t, read 3723 A handle that refers to the target credential. 3724 Specify GSS_C_NO_CREDENTIAL to inquire about 3725 the default initiator principal. 3726 3727 name gss_name_t, modify, optional 3728 The name whose identity the credential asserts. 3729 Storage associated with this name should be freed 3730 by the application after use with a call to 3731 gss_release_name(). Specify NULL if not required. 3732 3733 lifetime Integer, modify, optional 3734 The number of seconds for which the credential 3735 will remain valid. If the credential has 3736 expired, this parameter will be set to zero. 3737 If the implementation does not support 3738 credential expiration, the value 3739 GSS_C_INDEFINITE will be returned. Specify 3740 NULL if not required. 3741 3742 cred_usage gss_cred_usage_t, modify, optional 3743 How the credential may be used. One of the 3744 following: 3745 GSS_C_INITIATE 3746 GSS_C_ACCEPT 3747 GSS_C_BOTH 3748 Specify NULL if not required. 3749 3750 3751 3752 3753 3754Wray Standards Track [Page 67] 3755 3756RFC 2744 GSS-API V2: C-bindings January 2000 3757 3758 3759 mechanisms gss_OID_set, modify, optional 3760 Set of mechanisms supported by the credential. 3761 Storage associated with this OID set must be 3762 freed by the application after use with a call 3763 to gss_release_oid_set(). Specify NULL if not 3764 required. 3765 3766 Function value: GSS status code 3767 3768 GSS_S_COMPLETE Successful completion 3769 3770 GSS_S_NO_CRED The referenced credentials could not be accessed. 3771 3772 GSS_S_DEFECTIVE_CREDENTIAL The referenced credentials were invalid. 3773 3774 GSS_S_CREDENTIALS_EXPIRED The referenced credentials have expired. 3775 If the lifetime parameter was not passed as NULL, 3776 it will be set to 0. 3777 37785.22. gss_inquire_cred_by_mech 3779 3780 OM_uint32 gss_inquire_cred_by_mech ( 3781 OM_uint32 *minor_status, 3782 const gss_cred_id_t cred_handle, 3783 const gss_OID mech_type, 3784 gss_name_t *name, 3785 OM_uint32 *initiator_lifetime, 3786 OM_uint32 *acceptor_lifetime, 3787 gss_cred_usage_t *cred_usage ) 3788 3789 Purpose: 3790 3791 Obtains per-mechanism information about a credential. 3792 3793 Parameters: 3794 3795 minor_status Integer, modify 3796 Mechanism specific status code 3797 3798 cred_handle gss_cred_id_t, read 3799 A handle that refers to the target credential. 3800 Specify GSS_C_NO_CREDENTIAL to inquire about 3801 the default initiator principal. 3802 3803 mech_type gss_OID, read 3804 The mechanism for which information should be 3805 returned. 3806 3807 3808 3809 3810Wray Standards Track [Page 68] 3811 3812RFC 2744 GSS-API V2: C-bindings January 2000 3813 3814 3815 name gss_name_t, modify, optional 3816 The name whose identity the credential asserts. 3817 Storage associated with this name must be 3818 freed by the application after use with a call 3819 to gss_release_name(). Specify NULL if not 3820 required. 3821 3822 initiator_lifetime Integer, modify, optional 3823 The number of seconds for which the credential 3824 will remain capable of initiating security contexts 3825 under the specified mechanism. If the credential 3826 can no longer be used to initiate contexts, or if 3827 the credential usage for this mechanism is 3828 GSS_C_ACCEPT, this parameter will be set to zero. 3829 If the implementation does not support expiration 3830 of initiator credentials, the value 3831 GSS_C_INDEFINITE will be returned. Specify NULL 3832 if not required. 3833 3834 acceptor_lifetime Integer, modify, optional 3835 The number of seconds for which the credential 3836 will remain capable of accepting security contexts 3837 under the specified mechanism. If the credential 3838 can no longer be used to accept contexts, or if 3839 the credential usage for this mechanism is 3840 GSS_C_INITIATE, this parameter will be set to zero. 3841 3842 If the implementation does not support expiration 3843 of acceptor credentials, the value GSS_C_INDEFINITE 3844 will be returned. Specify NULL if not required. 3845 3846 cred_usage gss_cred_usage_t, modify, optional 3847 How the credential may be used with the specified 3848 mechanism. One of the following: 3849 GSS_C_INITIATE 3850 GSS_C_ACCEPT 3851 GSS_C_BOTH 3852 Specify NULL if not required. 3853 3854 Function value: GSS status code 3855 3856 GSS_S_COMPLETE Successful completion 3857 3858 GSS_S_NO_CRED The referenced credentials could not be accessed. 3859 3860 GSS_S_DEFECTIVE_CREDENTIAL The referenced credentials were invalid. 3861 3862 3863 3864 3865 3866Wray Standards Track [Page 69] 3867 3868RFC 2744 GSS-API V2: C-bindings January 2000 3869 3870 3871 GSS_S_CREDENTIALS_EXPIRED The referenced credentials have expired. 3872 If the lifetime parameter was not passed as NULL, 3873 it will be set to 0. 3874 38755.23. gss_inquire_mechs_for_name 3876 3877 OM_uint32 gss_inquire_mechs_for_name ( 3878 OM_uint32 *minor_status, 3879 const gss_name_t input_name, 3880 gss_OID_set *mech_types ) 3881 3882 Purpose: 3883 3884 Returns the set of mechanisms supported by the GSS-API implementation 3885 that may be able to process the specified name. 3886 3887 Each mechanism returned will recognize at least one element within 3888 the name. It is permissible for this routine to be implemented 3889 within a mechanism-independent GSS-API layer, using the type 3890 information contained within the presented name, and based on 3891 registration information provided by individual mechanism 3892 implementations. This means that the returned mech_types set may 3893 indicate that a particular mechanism will understand the name when in 3894 fact it would refuse to accept the name as input to 3895 gss_canonicalize_name, gss_init_sec_context, gss_acquire_cred or 3896 gss_add_cred (due to some property of the specific name, as opposed 3897 to the name type). Thus this routine should be used only as a pre- 3898 filter for a call to a subsequent mechanism-specific routine. 3899 3900 Parameters: 3901 3902 minor_status Integer, modify 3903 Implementation specific status code. 3904 3905 input_name gss_name_t, read 3906 The name to which the inquiry relates. 3907 3908 mech_types gss_OID_set, modify 3909 Set of mechanisms that may support the 3910 specified name. The returned OID set 3911 must be freed by the caller after use 3912 with a call to gss_release_oid_set(). 3913 3914 Function value: GSS status code 3915 3916 GSS_S_COMPLETE Successful completion 3917 3918 GSS_S_BAD_NAME The input_name parameter was ill-formed. 3919 3920 3921 3922Wray Standards Track [Page 70] 3923 3924RFC 2744 GSS-API V2: C-bindings January 2000 3925 3926 3927 GSS_S_BAD_NAMETYPE The input_name parameter contained an invalid or 3928 unsupported type of name 3929 39305.24. gss_inquire_names_for_mech 3931 3932 OM_uint32 gss_inquire_names_for_mech ( 3933 OM_uint32 *minor_status, 3934 const gss_OID mechanism, 3935 gss_OID_set *name_types) 3936 3937 Purpose: 3938 3939 Returns the set of nametypes supported by the specified mechanism. 3940 3941 Parameters: 3942 3943 minor_status Integer, modify 3944 Implementation specific status code. 3945 3946 mechanism gss_OID, read 3947 The mechanism to be interrogated. 3948 3949 name_types gss_OID_set, modify 3950 Set of name-types supported by the specified 3951 mechanism. The returned OID set must be 3952 freed by the application after use with a 3953 call to gss_release_oid_set(). 3954 3955 Function value: GSS status code 3956 3957 GSS_S_COMPLETE Successful completion 3958 39595.25. gss_process_context_token 3960 3961 OM_uint32 gss_process_context_token ( 3962 OM_uint32 *minor_status, 3963 const gss_ctx_id_t context_handle, 3964 const gss_buffer_t token_buffer) 3965 3966 Purpose: 3967 3968 Provides a way to pass an asynchronous token to the security service. 3969 Most context-level tokens are emitted and processed synchronously by 3970 gss_init_sec_context and gss_accept_sec_context, and the application 3971 is informed as to whether further tokens are expected by the 3972 GSS_C_CONTINUE_NEEDED major status bit. Occasionally, a mechanism 3973 may need to emit a context-level token at a point when the peer 3974 entity is not expecting a token. For example, the initiator's final 3975 3976 3977 3978Wray Standards Track [Page 71] 3979 3980RFC 2744 GSS-API V2: C-bindings January 2000 3981 3982 3983 call to gss_init_sec_context may emit a token and return a status of 3984 GSS_S_COMPLETE, but the acceptor's call to gss_accept_sec_context may 3985 fail. The acceptor's mechanism may wish to send a token containing 3986 an error indication to the initiator, but the initiator is not 3987 expecting a token at this point, believing that the context is fully 3988 established. Gss_process_context_token provides a way to pass such a 3989 token to the mechanism at any time. 3990 3991 Parameters: 3992 3993 minor_status Integer, modify 3994 Implementation specific status code. 3995 3996 context_handle gss_ctx_id_t, read 3997 context handle of context on which token is to 3998 be processed 3999 4000 token_buffer buffer, opaque, read 4001 token to process 4002 4003 Function value: GSS status code 4004 4005 GSS_S_COMPLETE Successful completion 4006 4007 GSS_S_DEFECTIVE_TOKEN Indicates that consistency checks performed 4008 on the token failed 4009 4010 GSS_S_NO_CONTEXT The context_handle did not refer to a valid context 4011 40125.26. gss_release_buffer 4013 4014 OM_uint32 gss_release_buffer ( 4015 OM_uint32 *minor_status, 4016 gss_buffer_t buffer) 4017 4018 Purpose: 4019 4020 Free storage associated with a buffer. The storage must have been 4021 allocated by a GSS-API routine. In addition to freeing the 4022 associated storage, the routine will zero the length field in the 4023 descriptor to which the buffer parameter refers, and implementations 4024 are encouraged to additionally set the pointer field in the 4025 descriptor to NULL. Any buffer object returned by a GSS-API routine 4026 may be passed to gss_release_buffer (even if there is no storage 4027 associated with the buffer). 4028 4029 4030 4031 4032 4033 4034Wray Standards Track [Page 72] 4035 4036RFC 2744 GSS-API V2: C-bindings January 2000 4037 4038 4039 Parameters: 4040 4041 minor_status Integer, modify 4042 Mechanism specific status code 4043 4044 buffer buffer, modify 4045 The storage associated with the buffer will be 4046 deleted. The gss_buffer_desc object will not 4047 be freed, but its length field will be zeroed. 4048 4049 4050 Function value: GSS status code 4051 4052 GSS_S_COMPLETE Successful completion 4053 40545.27. gss_release_cred 4055 4056 OM_uint32 gss_release_cred ( 4057 OM_uint32 *minor_status, 4058 gss_cred_id_t *cred_handle) 4059 4060 Purpose: 4061 4062 Informs GSS-API that the specified credential handle is no longer 4063 required by the application, and frees associated resources. 4064 Implementations are encouraged to set the cred_handle to 4065 GSS_C_NO_CREDENTIAL on successful completion of this call. 4066 4067 Parameters: 4068 4069 cred_handle gss_cred_id_t, modify, optional 4070 Opaque handle identifying credential 4071 to be released. If GSS_C_NO_CREDENTIAL 4072 is supplied, the routine will complete 4073 successfully, but will do nothing. 4074 4075 minor_status Integer, modify 4076 Mechanism specific status code. 4077 4078 Function value: GSS status code 4079 4080 GSS_S_COMPLETE Successful completion 4081 4082 GSS_S_NO_CRED Credentials could not be accessed. 4083 4084 4085 4086 4087 4088 4089 4090Wray Standards Track [Page 73] 4091 4092RFC 2744 GSS-API V2: C-bindings January 2000 4093 4094 40955.28. gss_release_name 4096 4097 OM_uint32 gss_release_name ( 4098 OM_uint32 *minor_status, 4099 gss_name_t *name) 4100 4101 Purpose: 4102 4103 Free GSSAPI-allocated storage associated with an internal-form name. 4104 Implementations are encouraged to set the name to GSS_C_NO_NAME on 4105 successful completion of this call. 4106 4107 Parameters: 4108 4109 minor_status Integer, modify 4110 Mechanism specific status code 4111 4112 name gss_name_t, modify 4113 The name to be deleted 4114 4115 Function value: GSS status code 4116 4117 GSS_S_COMPLETE Successful completion 4118 4119 GSS_S_BAD_NAME The name parameter did not contain a valid name 4120 41215.29. gss_release_oid_set 4122 4123 OM_uint32 gss_release_oid_set ( 4124 OM_uint32 *minor_status, 4125 gss_OID_set *set) 4126 4127 Purpose: 4128 4129 Free storage associated with a GSSAPI-generated gss_OID_set object. 4130 The set parameter must refer to an OID-set that was returned from a 4131 GSS-API routine. gss_release_oid_set() will free the storage 4132 associated with each individual member OID, the OID set's elements 4133 array, and the gss_OID_set_desc. 4134 4135 Implementations are encouraged to set the gss_OID_set parameter to 4136 GSS_C_NO_OID_SET on successful completion of this routine. 4137 4138 Parameters: 4139 4140 minor_status Integer, modify 4141 Mechanism specific status code 4142 4143 4144 4145 4146Wray Standards Track [Page 74] 4147 4148RFC 2744 GSS-API V2: C-bindings January 2000 4149 4150 4151 set Set of Object IDs, modify 4152 The storage associated with the gss_OID_set 4153 will be deleted. 4154 4155 Function value: GSS status code 4156 4157 GSS_S_COMPLETE Successful completion 4158 41595.30. gss_test_oid_set_member 4160 4161 OM_uint32 gss_test_oid_set_member ( 4162 OM_uint32 *minor_status, 4163 const gss_OID member, 4164 const gss_OID_set set, 4165 int *present) 4166 4167 Purpose: 4168 4169 Interrogate an Object Identifier set to determine whether a specified 4170 Object Identifier is a member. This routine is intended to be used 4171 with OID sets returned by gss_indicate_mechs(), gss_acquire_cred(), 4172 and gss_inquire_cred(), but will also work with user-generated sets. 4173 4174 Parameters: 4175 4176 minor_status Integer, modify 4177 Mechanism specific status code 4178 4179 member Object ID, read 4180 The object identifier whose presence 4181 is to be tested. 4182 4183 set Set of Object ID, read 4184 The Object Identifier set. 4185 4186 present Boolean, modify 4187 non-zero if the specified OID is a member 4188 of the set, zero if not. 4189 4190 Function value: GSS status code 4191 4192 GSS_S_COMPLETE Successful completion 4193 4194 4195 4196 4197 4198 4199 4200 4201 4202Wray Standards Track [Page 75] 4203 4204RFC 2744 GSS-API V2: C-bindings January 2000 4205 4206 42075.31. gss_unwrap 4208 4209 OM_uint32 gss_unwrap ( 4210 OM_uint32 *minor_status, 4211 const gss_ctx_id_t context_handle, 4212 const gss_buffer_t input_message_buffer, 4213 gss_buffer_t output_message_buffer, 4214 int *conf_state, 4215 gss_qop_t *qop_state) 4216 4217 Purpose: 4218 4219 Converts a message previously protected by gss_wrap back to a usable 4220 form, verifying the embedded MIC. The conf_state parameter indicates 4221 whether the message was encrypted; the qop_state parameter indicates 4222 the strength of protection that was used to provide the 4223 confidentiality and integrity services. 4224 4225 Since some application-level protocols may wish to use tokens emitted 4226 by gss_wrap() to provide "secure framing", implementations must 4227 support the wrapping and unwrapping of zero-length messages. 4228 4229 Parameters: 4230 4231 minor_status Integer, modify 4232 Mechanism specific status code. 4233 4234 context_handle gss_ctx_id_t, read 4235 Identifies the context on which the message 4236 arrived 4237 4238 input_message_buffer buffer, opaque, read 4239 protected message 4240 4241 output_message_buffer buffer, opaque, modify 4242 Buffer to receive unwrapped message. 4243 Storage associated with this buffer must 4244 be freed by the application after use use 4245 with a call to gss_release_buffer(). 4246 4247 conf_state boolean, modify, optional 4248 Non-zero - Confidentiality and integrity 4249 protection were used 4250 Zero - Integrity service only was used 4251 Specify NULL if not required 4252 4253 4254 4255 4256 4257 4258Wray Standards Track [Page 76] 4259 4260RFC 2744 GSS-API V2: C-bindings January 2000 4261 4262 4263 qop_state gss_qop_t, modify, optional 4264 Quality of protection provided. 4265 Specify NULL if not required 4266 4267 Function value: GSS status code 4268 4269 GSS_S_COMPLETE Successful completion 4270 4271 GSS_S_DEFECTIVE_TOKEN The token failed consistency checks 4272 4273 GSS_S_BAD_SIG The MIC was incorrect 4274 4275 GSS_S_DUPLICATE_TOKEN The token was valid, and contained a correct 4276 MIC for the message, but it had already been 4277 processed 4278 4279 GSS_S_OLD_TOKEN The token was valid, and contained a correct MIC 4280 for the message, but it is too old to check for 4281 duplication. 4282 4283 GSS_S_UNSEQ_TOKEN The token was valid, and contained a correct MIC 4284 for the message, but has been verified out of 4285 sequence; a later token has already been 4286 received. 4287 4288 GSS_S_GAP_TOKEN The token was valid, and contained a correct MIC 4289 for the message, but has been verified out of 4290 sequence; an earlier expected token has not yet 4291 been received. 4292 4293 GSS_S_CONTEXT_EXPIRED The context has already expired 4294 4295 GSS_S_NO_CONTEXT The context_handle parameter did not identify 4296 a valid context 4297 42985.32. gss_verify_mic 4299 4300 OM_uint32 gss_verify_mic ( 4301 OM_uint32 *minor_status, 4302 const gss_ctx_id_t context_handle, 4303 const gss_buffer_t message_buffer, 4304 const gss_buffer_t token_buffer, 4305 gss_qop_t *qop_state) 4306 4307 4308 4309 4310 4311 4312 4313 4314Wray Standards Track [Page 77] 4315 4316RFC 2744 GSS-API V2: C-bindings January 2000 4317 4318 4319 Purpose: 4320 4321 Verifies that a cryptographic MIC, contained in the token parameter, 4322 fits the supplied message. The qop_state parameter allows a message 4323 recipient to determine the strength of protection that was applied to 4324 the message. 4325 4326 Since some application-level protocols may wish to use tokens emitted 4327 by gss_wrap() to provide "secure framing", implementations must 4328 support the calculation and verification of MICs over zero-length 4329 messages. 4330 4331 Parameters: 4332 4333 minor_status Integer, modify 4334 Mechanism specific status code. 4335 4336 context_handle gss_ctx_id_t, read 4337 Identifies the context on which the message 4338 arrived 4339 4340 message_buffer buffer, opaque, read 4341 Message to be verified 4342 4343 token_buffer buffer, opaque, read 4344 Token associated with message 4345 4346 qop_state gss_qop_t, modify, optional 4347 quality of protection gained from MIC 4348 Specify NULL if not required 4349 4350 Function value: GSS status code 4351 4352 GSS_S_COMPLETE Successful completion 4353 4354 GSS_S_DEFECTIVE_TOKEN The token failed consistency checks 4355 4356 GSS_S_BAD_SIG The MIC was incorrect 4357 4358 GSS_S_DUPLICATE_TOKEN The token was valid, and contained a correct 4359 MIC for the message, but it had already been 4360 processed 4361 4362 GSS_S_OLD_TOKEN The token was valid, and contained a correct MIC 4363 for the message, but it is too old to check for 4364 duplication. 4365 4366 4367 4368 4369 4370Wray Standards Track [Page 78] 4371 4372RFC 2744 GSS-API V2: C-bindings January 2000 4373 4374 4375 GSS_S_UNSEQ_TOKEN The token was valid, and contained a correct MIC 4376 for the message, but has been verified out of 4377 sequence; a later token has already been received. 4378 4379 GSS_S_GAP_TOKEN The token was valid, and contained a correct MIC 4380 for the message, but has been verified out of 4381 sequence; an earlier expected token has not yet 4382 been received. 4383 4384 GSS_S_CONTEXT_EXPIRED The context has already expired 4385 4386 GSS_S_NO_CONTEXT The context_handle parameter did not identify a 4387 valid context 4388 43895.33. gss_wrap 4390 4391 OM_uint32 gss_wrap ( 4392 OM_uint32 *minor_status, 4393 const gss_ctx_id_t context_handle, 4394 int conf_req_flag, 4395 gss_qop_t qop_req 4396 const gss_buffer_t input_message_buffer, 4397 int *conf_state, 4398 gss_buffer_t output_message_buffer ) 4399 4400 Purpose: 4401 4402 Attaches a cryptographic MIC and optionally encrypts the specified 4403 input_message. The output_message contains both the MIC and the 4404 message. The qop_req parameter allows a choice between several 4405 cryptographic algorithms, if supported by the chosen mechanism. 4406 4407 Since some application-level protocols may wish to use tokens emitted 4408 by gss_wrap() to provide "secure framing", implementations must 4409 support the wrapping of zero-length messages. 4410 4411 Parameters: 4412 4413 minor_status Integer, modify 4414 Mechanism specific status code. 4415 4416 context_handle gss_ctx_id_t, read 4417 Identifies the context on which the message 4418 will be sent 4419 4420 4421 4422 4423 4424 4425 4426Wray Standards Track [Page 79] 4427 4428RFC 2744 GSS-API V2: C-bindings January 2000 4429 4430 4431 conf_req_flag boolean, read 4432 Non-zero - Both confidentiality and integrity 4433 services are requested 4434 Zero - Only integrity service is requested 4435 4436 qop_req gss_qop_t, read, optional 4437 Specifies required quality of protection. A 4438 mechanism-specific default may be requested by 4439 setting qop_req to GSS_C_QOP_DEFAULT. If an 4440 unsupported protection strength is requested, 4441 gss_wrap will return a major_status of 4442 GSS_S_BAD_QOP. 4443 4444 input_message_buffer buffer, opaque, read 4445 Message to be protected 4446 4447 conf_state boolean, modify, optional 4448 Non-zero - Confidentiality, data origin 4449 authentication and integrity 4450 services have been applied 4451 Zero - Integrity and data origin services only 4452 has been applied. 4453 Specify NULL if not required 4454 4455 output_message_buffer buffer, opaque, modify 4456 Buffer to receive protected message. 4457 Storage associated with this message must 4458 be freed by the application after use with 4459 a call to gss_release_buffer(). 4460 4461 Function value: GSS status code 4462 4463 GSS_S_COMPLETE Successful completion 4464 4465 GSS_S_CONTEXT_EXPIRED The context has already expired 4466 4467 GSS_S_NO_CONTEXT The context_handle parameter did not identify a 4468 valid context 4469 4470 GSS_S_BAD_QOP The specified QOP is not supported by the 4471 mechanism. 4472 4473 4474 4475 4476 4477 4478 4479 4480 4481 4482Wray Standards Track [Page 80] 4483 4484RFC 2744 GSS-API V2: C-bindings January 2000 4485 4486 44875.34. gss_wrap_size_limit 4488 4489 OM_uint32 gss_wrap_size_limit ( 4490 OM_uint32 *minor_status, 4491 const gss_ctx_id_t context_handle, 4492 int conf_req_flag, 4493 gss_qop_t qop_req, 4494 OM_uint32 req_output_size, 4495 OM_uint32 *max_input_size) 4496 4497 Purpose: 4498 4499 Allows an application to determine the maximum message size that, if 4500 presented to gss_wrap with the same conf_req_flag and qop_req 4501 parameters, will result in an output token containing no more than 4502 req_output_size bytes. 4503 4504 This call is intended for use by applications that communicate over 4505 protocols that impose a maximum message size. It enables the 4506 application to fragment messages prior to applying protection. 4507 4508 GSS-API implementations are recommended but not required to detect 4509 invalid QOP values when gss_wrap_size_limit() is called. This routine 4510 guarantees only a maximum message size, not the availability of 4511 specific QOP values for message protection. 4512 4513 Successful completion of this call does not guarantee that gss_wrap 4514 will be able to protect a message of length max_input_size bytes, 4515 since this ability may depend on the availability of system resources 4516 at the time that gss_wrap is called. However, if the implementation 4517 itself imposes an upper limit on the length of messages that may be 4518 processed by gss_wrap, the implementation should not return a value 4519 via max_input_bytes that is greater than this length. 4520 4521 Parameters: 4522 4523 minor_status Integer, modify 4524 Mechanism specific status code 4525 4526 context_handle gss_ctx_id_t, read 4527 A handle that refers to the security over 4528 which the messages will be sent. 4529 4530 conf_req_flag Boolean, read 4531 Indicates whether gss_wrap will be asked 4532 to apply confidentiality protection in 4533 4534 4535 4536 4537 4538Wray Standards Track [Page 81] 4539 4540RFC 2744 GSS-API V2: C-bindings January 2000 4541 4542 4543 addition to integrity protection. See 4544 the routine description for gss_wrap 4545 for more details. 4546 4547 qop_req gss_qop_t, read 4548 Indicates the level of protection that 4549 gss_wrap will be asked to provide. See 4550 the routine description for gss_wrap for 4551 more details. 4552 4553 req_output_size Integer, read 4554 The desired maximum size for tokens emitted 4555 by gss_wrap. 4556 4557 max_input_size Integer, modify 4558 The maximum input message size that may 4559 be presented to gss_wrap in order to 4560 guarantee that the emitted token shall 4561 be no larger than req_output_size bytes. 4562 4563 Function value: GSS status code 4564 4565 GSS_S_COMPLETE Successful completion 4566 4567 GSS_S_NO_CONTEXT The referenced context could not be accessed. 4568 4569 GSS_S_CONTEXT_EXPIRED The context has expired. 4570 4571 GSS_S_BAD_QOP The specified QOP is not supported by the 4572 mechanism. 4573 45746. Security Considerations 4575 4576 This document specifies a service interface for security facilities 4577 and services; as such, security considerations appear throughout the 4578 specification. Nonetheless, it is appropriate to summarize certain 4579 specific points relevant to GSS-API implementors and calling 4580 applications. Usage of the GSS-API interface does not in itself 4581 provide security services or assurance; instead, these attributes are 4582 dependent on the underlying mechanism(s) which support a GSS-API 4583 implementation. Callers must be attentive to the requests made to 4584 GSS-API calls and to the status indicators returned by GSS-API, as 4585 these specify the security service characteristics which GSS-API will 4586 provide. When the interprocess context transfer facility is used, 4587 appropriate local controls should be applied to constrain access to 4588 interprocess tokens and to the sensitive data which they contain. 4589 4590 4591 4592 4593 4594Wray Standards Track [Page 82] 4595 4596RFC 2744 GSS-API V2: C-bindings January 2000 4597 4598 4599 Appendix A. GSS-API C header file gssapi.h 4600 4601 C-language GSS-API implementations should include a copy of the 4602 following header-file. 4603 4604 #ifndef GSSAPI_H_ 4605 #define GSSAPI_H_ 4606 4607 4608 4609 /* 4610 * First, include stddef.h to get size_t defined. 4611 */ 4612 #include <stddef.h> 4613 4614 /* 4615 * If the platform supports the xom.h header file, it should be 4616 * included here. 4617 */ 4618 #include <xom.h> 4619 4620 4621 /* 4622 * Now define the three implementation-dependent types. 4623 */ 4624 typedef <platform-specific> gss_ctx_id_t; 4625 typedef <platform-specific> gss_cred_id_t; 4626 typedef <platform-specific> gss_name_t; 4627 4628 /* 4629 * The following type must be defined as the smallest natural 4630 * unsigned integer supported by the platform that has at least 4631 * 32 bits of precision. 4632 */ 4633 typedef <platform-specific> gss_uint32; 4634 4635 4636 #ifdef OM_STRING 4637 /* 4638 * We have included the xom.h header file. Verify that OM_uint32 4639 * is defined correctly. 4640 */ 4641 4642 #if sizeof(gss_uint32) != sizeof(OM_uint32) 4643 #error Incompatible definition of OM_uint32 from xom.h 4644 #endif 4645 4646 typedef OM_object_identifier gss_OID_desc, *gss_OID; 4647 4648 4649 4650Wray Standards Track [Page 83] 4651 4652RFC 2744 GSS-API V2: C-bindings January 2000 4653 4654 4655 #else 4656 4657 /* 4658 * We can't use X/Open definitions, so roll our own. 4659 */ 4660 4661 typedef gss_uint32 OM_uint32; 4662 4663 typedef struct gss_OID_desc_struct { 4664 OM_uint32 length; 4665 void *elements; 4666 } gss_OID_desc, *gss_OID; 4667 4668 #endif 4669 4670 typedef struct gss_OID_set_desc_struct { 4671 size_t count; 4672 gss_OID elements; 4673 } gss_OID_set_desc, *gss_OID_set; 4674 4675 typedef struct gss_buffer_desc_struct { 4676 size_t length; 4677 void *value; 4678 } gss_buffer_desc, *gss_buffer_t; 4679 4680 typedef struct gss_channel_bindings_struct { 4681 OM_uint32 initiator_addrtype; 4682 gss_buffer_desc initiator_address; 4683 OM_uint32 acceptor_addrtype; 4684 gss_buffer_desc acceptor_address; 4685 gss_buffer_desc application_data; 4686 } *gss_channel_bindings_t; 4687 4688 /* 4689 * For now, define a QOP-type as an OM_uint32 4690 */ 4691 typedef OM_uint32 gss_qop_t; 4692 4693 typedef int gss_cred_usage_t; 4694 4695 /* 4696 * Flag bits for context-level services. 4697 */ 4698 4699 4700 4701 4702 4703 4704 4705 4706Wray Standards Track [Page 84] 4707 4708RFC 2744 GSS-API V2: C-bindings January 2000 4709 4710 4711 #define GSS_C_DELEG_FLAG 1 4712 #define GSS_C_MUTUAL_FLAG 2 4713 #define GSS_C_REPLAY_FLAG 4 4714 #define GSS_C_SEQUENCE_FLAG 8 4715 #define GSS_C_CONF_FLAG 16 4716 #define GSS_C_INTEG_FLAG 32 4717 #define GSS_C_ANON_FLAG 64 4718 #define GSS_C_PROT_READY_FLAG 128 4719 #define GSS_C_TRANS_FLAG 256 4720 4721 /* 4722 * Credential usage options 4723 */ 4724 #define GSS_C_BOTH 0 4725 #define GSS_C_INITIATE 1 4726 #define GSS_C_ACCEPT 2 4727 4728 /* 4729 * Status code types for gss_display_status 4730 */ 4731 #define GSS_C_GSS_CODE 1 4732 #define GSS_C_MECH_CODE 2 4733 4734 /* 4735 * The constant definitions for channel-bindings address families 4736 */ 4737 #define GSS_C_AF_UNSPEC 0 4738 #define GSS_C_AF_LOCAL 1 4739 #define GSS_C_AF_INET 2 4740 #define GSS_C_AF_IMPLINK 3 4741 #define GSS_C_AF_PUP 4 4742 #define GSS_C_AF_CHAOS 5 4743 #define GSS_C_AF_NS 6 4744 #define GSS_C_AF_NBS 7 4745 #define GSS_C_AF_ECMA 8 4746 #define GSS_C_AF_DATAKIT 9 4747 #define GSS_C_AF_CCITT 10 4748 #define GSS_C_AF_SNA 11 4749 #define GSS_C_AF_DECnet 12 4750 #define GSS_C_AF_DLI 13 4751 #define GSS_C_AF_LAT 14 4752 #define GSS_C_AF_HYLINK 15 4753 #define GSS_C_AF_APPLETALK 16 4754 #define GSS_C_AF_BSC 17 4755 #define GSS_C_AF_DSS 18 4756 #define GSS_C_AF_OSI 19 4757 #define GSS_C_AF_X25 21 4758 4759 4760 4761 4762Wray Standards Track [Page 85] 4763 4764RFC 2744 GSS-API V2: C-bindings January 2000 4765 4766 4767 #define GSS_C_AF_NULLADDR 255 4768 4769 /* 4770 * Various Null values 4771 */ 4772 #define GSS_C_NO_NAME ((gss_name_t) 0) 4773 #define GSS_C_NO_BUFFER ((gss_buffer_t) 0) 4774 #define GSS_C_NO_OID ((gss_OID) 0) 4775 #define GSS_C_NO_OID_SET ((gss_OID_set) 0) 4776 #define GSS_C_NO_CONTEXT ((gss_ctx_id_t) 0) 4777 #define GSS_C_NO_CREDENTIAL ((gss_cred_id_t) 0) 4778 #define GSS_C_NO_CHANNEL_BINDINGS ((gss_channel_bindings_t) 0) 4779 #define GSS_C_EMPTY_BUFFER {0, NULL} 4780 4781 /* 4782 * Some alternate names for a couple of the above 4783 * values. These are defined for V1 compatibility. 4784 */ 4785 #define GSS_C_NULL_OID GSS_C_NO_OID 4786 #define GSS_C_NULL_OID_SET GSS_C_NO_OID_SET 4787 4788 /* 4789 * Define the default Quality of Protection for per-message 4790 * services. Note that an implementation that offers multiple 4791 * levels of QOP may define GSS_C_QOP_DEFAULT to be either zero 4792 * (as done here) to mean "default protection", or to a specific 4793 * explicit QOP value. However, a value of 0 should always be 4794 * interpreted by a GSS-API implementation as a request for the 4795 * default protection level. 4796 */ 4797 #define GSS_C_QOP_DEFAULT 0 4798 4799 /* 4800 * Expiration time of 2^32-1 seconds means infinite lifetime for a 4801 * credential or security context 4802 */ 4803 #define GSS_C_INDEFINITE 0xfffffffful 4804 4805 /* 4806 * The implementation must reserve static storage for a 4807 * gss_OID_desc object containing the value 4808 * {10, (void *)"\x2a\x86\x48\x86\xf7\x12" 4809 * "\x01\x02\x01\x01"}, 4810 * corresponding to an object-identifier value of 4811 * {iso(1) member-body(2) United States(840) mit(113554) 4812 * infosys(1) gssapi(2) generic(1) user_name(1)}. The constant 4813 * GSS_C_NT_USER_NAME should be initialized to point 4814 * to that gss_OID_desc. 4815 4816 4817 4818Wray Standards Track [Page 86] 4819 4820RFC 2744 GSS-API V2: C-bindings January 2000 4821 4822 4823 */ 4824 extern gss_OID GSS_C_NT_USER_NAME; 4825 4826 /* 4827 * The implementation must reserve static storage for a 4828 * gss_OID_desc object containing the value 4829 * {10, (void *)"\x2a\x86\x48\x86\xf7\x12" 4830 * "\x01\x02\x01\x02"}, 4831 * corresponding to an object-identifier value of 4832 * {iso(1) member-body(2) United States(840) mit(113554) 4833 * infosys(1) gssapi(2) generic(1) machine_uid_name(2)}. 4834 * The constant GSS_C_NT_MACHINE_UID_NAME should be 4835 * initialized to point to that gss_OID_desc. 4836 */ 4837 extern gss_OID GSS_C_NT_MACHINE_UID_NAME; 4838 4839 /* 4840 * The implementation must reserve static storage for a 4841 * gss_OID_desc object containing the value 4842 * {10, (void *)"\x2a\x86\x48\x86\xf7\x12" 4843 * "\x01\x02\x01\x03"}, 4844 * corresponding to an object-identifier value of 4845 * {iso(1) member-body(2) United States(840) mit(113554) 4846 * infosys(1) gssapi(2) generic(1) string_uid_name(3)}. 4847 * The constant GSS_C_NT_STRING_UID_NAME should be 4848 * initialized to point to that gss_OID_desc. 4849 */ 4850 extern gss_OID GSS_C_NT_STRING_UID_NAME; 4851 4852 /* 4853 * The implementation must reserve static storage for a 4854 * gss_OID_desc object containing the value 4855 * {6, (void *)"\x2b\x06\x01\x05\x06\x02"}, 4856 * corresponding to an object-identifier value of 4857 * {iso(1) org(3) dod(6) internet(1) security(5) 4858 * nametypes(6) gss-host-based-services(2)). The constant 4859 * GSS_C_NT_HOSTBASED_SERVICE_X should be initialized to point 4860 * to that gss_OID_desc. This is a deprecated OID value, and 4861 * implementations wishing to support hostbased-service names 4862 * should instead use the GSS_C_NT_HOSTBASED_SERVICE OID, 4863 * defined below, to identify such names; 4864 * GSS_C_NT_HOSTBASED_SERVICE_X should be accepted a synonym 4865 * for GSS_C_NT_HOSTBASED_SERVICE when presented as an input 4866 * parameter, but should not be emitted by GSS-API 4867 * implementations 4868 */ 4869 extern gss_OID GSS_C_NT_HOSTBASED_SERVICE_X; 4870 4871 4872 4873 4874Wray Standards Track [Page 87] 4875 4876RFC 2744 GSS-API V2: C-bindings January 2000 4877 4878 4879 /* 4880 * The implementation must reserve static storage for a 4881 * gss_OID_desc object containing the value 4882 * {10, (void *)"\x2a\x86\x48\x86\xf7\x12" 4883 * "\x01\x02\x01\x04"}, corresponding to an 4884 * object-identifier value of {iso(1) member-body(2) 4885 * Unites States(840) mit(113554) infosys(1) gssapi(2) 4886 * generic(1) service_name(4)}. The constant 4887 * GSS_C_NT_HOSTBASED_SERVICE should be initialized 4888 * to point to that gss_OID_desc. 4889 */ 4890 extern gss_OID GSS_C_NT_HOSTBASED_SERVICE; 4891 4892 /* 4893 * The implementation must reserve static storage for a 4894 * gss_OID_desc object containing the value 4895 * {6, (void *)"\x2b\x06\01\x05\x06\x03"}, 4896 * corresponding to an object identifier value of 4897 * {1(iso), 3(org), 6(dod), 1(internet), 5(security), 4898 * 6(nametypes), 3(gss-anonymous-name)}. The constant 4899 * and GSS_C_NT_ANONYMOUS should be initialized to point 4900 * to that gss_OID_desc. 4901 */ 4902 extern gss_OID GSS_C_NT_ANONYMOUS; 4903 4904 4905 /* 4906 * The implementation must reserve static storage for a 4907 * gss_OID_desc object containing the value 4908 * {6, (void *)"\x2b\x06\x01\x05\x06\x04"}, 4909 * corresponding to an object-identifier value of 4910 * {1(iso), 3(org), 6(dod), 1(internet), 5(security), 4911 * 6(nametypes), 4(gss-api-exported-name)}. The constant 4912 * GSS_C_NT_EXPORT_NAME should be initialized to point 4913 * to that gss_OID_desc. 4914 */ 4915 extern gss_OID GSS_C_NT_EXPORT_NAME; 4916 4917 4918 /* Major status codes */ 4919 4920 #define GSS_S_COMPLETE 0 4921 4922 /* 4923 * Some "helper" definitions to make the status code macros obvious. 4924 */ 4925 #define GSS_C_CALLING_ERROR_OFFSET 24 4926 #define GSS_C_ROUTINE_ERROR_OFFSET 16 4927 4928 4929 4930Wray Standards Track [Page 88] 4931 4932RFC 2744 GSS-API V2: C-bindings January 2000 4933 4934 4935 #define GSS_C_SUPPLEMENTARY_OFFSET 0 4936 #define GSS_C_CALLING_ERROR_MASK 0377ul 4937 #define GSS_C_ROUTINE_ERROR_MASK 0377ul 4938 #define GSS_C_SUPPLEMENTARY_MASK 0177777ul 4939 4940 /* 4941 * The macros that test status codes for error conditions. 4942 * Note that the GSS_ERROR() macro has changed slightly from 4943 * the V1 GSS-API so that it now evaluates its argument 4944 * only once. 4945 */ 4946 #define GSS_CALLING_ERROR(x) \ 4947 (x & (GSS_C_CALLING_ERROR_MASK << GSS_C_CALLING_ERROR_OFFSET)) 4948 #define GSS_ROUTINE_ERROR(x) \ 4949 (x & (GSS_C_ROUTINE_ERROR_MASK << GSS_C_ROUTINE_ERROR_OFFSET)) 4950 #define GSS_SUPPLEMENTARY_INFO(x) \ 4951 (x & (GSS_C_SUPPLEMENTARY_MASK << GSS_C_SUPPLEMENTARY_OFFSET)) 4952 #define GSS_ERROR(x) \ 4953 (x & ((GSS_C_CALLING_ERROR_MASK << GSS_C_CALLING_ERROR_OFFSET) | \ 4954 (GSS_C_ROUTINE_ERROR_MASK << GSS_C_ROUTINE_ERROR_OFFSET))) 4955 4956 /* 4957 * Now the actual status code definitions 4958 */ 4959 4960 /* 4961 * Calling errors: 4962 4963 */ 4964 #define GSS_S_CALL_INACCESSIBLE_READ \ 4965 (1ul << GSS_C_CALLING_ERROR_OFFSET) 4966 #define GSS_S_CALL_INACCESSIBLE_WRITE \ 4967 (2ul << GSS_C_CALLING_ERROR_OFFSET) 4968 #define GSS_S_CALL_BAD_STRUCTURE \ 4969 (3ul << GSS_C_CALLING_ERROR_OFFSET) 4970 4971 /* 4972 * Routine errors: 4973 */ 4974 #define GSS_S_BAD_MECH (1ul << 4975 GSS_C_ROUTINE_ERROR_OFFSET) 4976 #define GSS_S_BAD_NAME (2ul << 4977 GSS_C_ROUTINE_ERROR_OFFSET) 4978 #define GSS_S_BAD_NAMETYPE (3ul << 4979 GSS_C_ROUTINE_ERROR_OFFSET) 4980 #define GSS_S_BAD_BINDINGS (4ul << 4981 GSS_C_ROUTINE_ERROR_OFFSET) 4982 #define GSS_S_BAD_STATUS (5ul << 4983 4984 4985 4986Wray Standards Track [Page 89] 4987 4988RFC 2744 GSS-API V2: C-bindings January 2000 4989 4990 4991 GSS_C_ROUTINE_ERROR_OFFSET) 4992 #define GSS_S_BAD_SIG (6ul << 4993 GSS_C_ROUTINE_ERROR_OFFSET) 4994 #define GSS_S_BAD_MIC GSS_S_BAD_SIG 4995 #define GSS_S_NO_CRED (7ul << 4996 GSS_C_ROUTINE_ERROR_OFFSET) 4997 #define GSS_S_NO_CONTEXT (8ul << 4998 GSS_C_ROUTINE_ERROR_OFFSET) 4999 #define GSS_S_DEFECTIVE_TOKEN (9ul << 5000 GSS_C_ROUTINE_ERROR_OFFSET) 5001 #define GSS_S_DEFECTIVE_CREDENTIAL (10ul << 5002 GSS_C_ROUTINE_ERROR_OFFSET) 5003 #define GSS_S_CREDENTIALS_EXPIRED (11ul << 5004 GSS_C_ROUTINE_ERROR_OFFSET) 5005 #define GSS_S_CONTEXT_EXPIRED (12ul << 5006 GSS_C_ROUTINE_ERROR_OFFSET) 5007 #define GSS_S_FAILURE (13ul << 5008 GSS_C_ROUTINE_ERROR_OFFSET) 5009 #define GSS_S_BAD_QOP (14ul << 5010 GSS_C_ROUTINE_ERROR_OFFSET) 5011 #define GSS_S_UNAUTHORIZED (15ul << 5012 GSS_C_ROUTINE_ERROR_OFFSET) 5013 #define GSS_S_UNAVAILABLE (16ul << 5014 GSS_C_ROUTINE_ERROR_OFFSET) 5015 #define GSS_S_DUPLICATE_ELEMENT (17ul << 5016 GSS_C_ROUTINE_ERROR_OFFSET) 5017 #define GSS_S_NAME_NOT_MN (18ul << 5018 GSS_C_ROUTINE_ERROR_OFFSET) 5019 5020 /* 5021 * Supplementary info bits: 5022 */ 5023 #define GSS_S_CONTINUE_NEEDED \ 5024 (1ul << (GSS_C_SUPPLEMENTARY_OFFSET + 0)) 5025 #define GSS_S_DUPLICATE_TOKEN \ 5026 (1ul << (GSS_C_SUPPLEMENTARY_OFFSET + 1)) 5027 #define GSS_S_OLD_TOKEN \ 5028 (1ul << (GSS_C_SUPPLEMENTARY_OFFSET + 2)) 5029 #define GSS_S_UNSEQ_TOKEN \ 5030 (1ul << (GSS_C_SUPPLEMENTARY_OFFSET + 3)) 5031 #define GSS_S_GAP_TOKEN \ 5032 (1ul << (GSS_C_SUPPLEMENTARY_OFFSET + 4)) 5033 5034 /* 5035 * Finally, function prototypes for the GSS-API routines. 5036 */ 5037 5038 5039 5040 5041 5042Wray Standards Track [Page 90] 5043 5044RFC 2744 GSS-API V2: C-bindings January 2000 5045 5046 5047 OM_uint32 gss_acquire_cred 5048 (OM_uint32 , /* minor_status */ 5049 const gss_name_t, /* desired_name */ 5050 OM_uint32, /* time_req */ 5051 const gss_OID_set, /* desired_mechs */ 5052 gss_cred_usage_t, /* cred_usage */ 5053 gss_cred_id_t , /* output_cred_handle */ 5054 gss_OID_set , /* actual_mechs */ 5055 OM_uint32 * /* time_rec */ 5056 ); 5057 5058 OM_uint32 gss_release_cred 5059 (OM_uint32 , /* minor_status */ 5060 gss_cred_id_t * /* cred_handle */ 5061 ); 5062 5063 OM_uint32 gss_init_sec_context 5064 (OM_uint32 , /* minor_status */ 5065 const gss_cred_id_t, /* initiator_cred_handle */ 5066 gss_ctx_id_t , /* context_handle */ 5067 const gss_name_t, /* target_name */ 5068 const gss_OID, /* mech_type */ 5069 OM_uint32, /* req_flags */ 5070 OM_uint32, /* time_req */ 5071 const gss_channel_bindings_t, 5072 /* input_chan_bindings */ 5073 const gss_buffer_t, /* input_token */ 5074 gss_OID , /* actual_mech_type */ 5075 gss_buffer_t, /* output_token */ 5076 OM_uint32 , /* ret_flags */ 5077 OM_uint32 * /* time_rec */ 5078 ); 5079 5080 OM_uint32 gss_accept_sec_context 5081 (OM_uint32 , /* minor_status */ 5082 gss_ctx_id_t , /* context_handle */ 5083 const gss_cred_id_t, /* acceptor_cred_handle */ 5084 const gss_buffer_t, /* input_token_buffer */ 5085 const gss_channel_bindings_t, 5086 /* input_chan_bindings */ 5087 gss_name_t , /* src_name */ 5088 gss_OID , /* mech_type */ 5089 gss_buffer_t, /* output_token */ 5090 OM_uint32 , /* ret_flags */ 5091 OM_uint32 , /* time_rec */ 5092 gss_cred_id_t * /* delegated_cred_handle */ 5093 ); 5094 5095 5096 5097 5098Wray Standards Track [Page 91] 5099 5100RFC 2744 GSS-API V2: C-bindings January 2000 5101 5102 5103 OM_uint32 gss_process_context_token 5104 (OM_uint32 , /* minor_status */ 5105 const gss_ctx_id_t, /* context_handle */ 5106 const gss_buffer_t /* token_buffer */ 5107 ); 5108 5109 OM_uint32 gss_delete_sec_context 5110 (OM_uint32 , /* minor_status */ 5111 gss_ctx_id_t , /* context_handle */ 5112 gss_buffer_t /* output_token */ 5113 ); 5114 5115 OM_uint32 gss_context_time 5116 (OM_uint32 , /* minor_status */ 5117 const gss_ctx_id_t, /* context_handle */ 5118 OM_uint32 * /* time_rec */ 5119 ); 5120 5121 OM_uint32 gss_get_mic 5122 (OM_uint32 , /* minor_status */ 5123 const gss_ctx_id_t, /* context_handle */ 5124 gss_qop_t, /* qop_req */ 5125 const gss_buffer_t, /* message_buffer */ 5126 gss_buffer_t /* message_token */ 5127 ); 5128 5129 OM_uint32 gss_verify_mic 5130 (OM_uint32 , /* minor_status */ 5131 const gss_ctx_id_t, /* context_handle */ 5132 const gss_buffer_t, /* message_buffer */ 5133 const gss_buffer_t, /* token_buffer */ 5134 gss_qop_t * /* qop_state */ 5135 ); 5136 5137 OM_uint32 gss_wrap 5138 (OM_uint32 , /* minor_status */ 5139 const gss_ctx_id_t, /* context_handle */ 5140 int, /* conf_req_flag */ 5141 gss_qop_t, /* qop_req */ 5142 const gss_buffer_t, /* input_message_buffer */ 5143 int , /* conf_state */ 5144 gss_buffer_t /* output_message_buffer */ 5145 ); 5146 5147 5148 5149 5150 5151 5152 5153 5154Wray Standards Track [Page 92] 5155 5156RFC 2744 GSS-API V2: C-bindings January 2000 5157 5158 5159 OM_uint32 gss_unwrap 5160 (OM_uint32 , /* minor_status */ 5161 const gss_ctx_id_t, /* context_handle */ 5162 const gss_buffer_t, /* input_message_buffer */ 5163 gss_buffer_t, /* output_message_buffer */ 5164 int , /* conf_state */ 5165 gss_qop_t * /* qop_state */ 5166 ); 5167 5168 5169 5170 OM_uint32 gss_display_status 5171 (OM_uint32 , /* minor_status */ 5172 OM_uint32, /* status_value */ 5173 int, /* status_type */ 5174 const gss_OID, /* mech_type */ 5175 OM_uint32 , /* message_context */ 5176 gss_buffer_t /* status_string */ 5177 ); 5178 5179 OM_uint32 gss_indicate_mechs 5180 (OM_uint32 , /* minor_status */ 5181 gss_OID_set * /* mech_set */ 5182 ); 5183 5184 OM_uint32 gss_compare_name 5185 (OM_uint32 , /* minor_status */ 5186 const gss_name_t, /* name1 */ 5187 const gss_name_t, /* name2 */ 5188 int * /* name_equal */ 5189 ); 5190 5191 OM_uint32 gss_display_name 5192 (OM_uint32 , /* minor_status */ 5193 const gss_name_t, /* input_name */ 5194 gss_buffer_t, /* output_name_buffer */ 5195 gss_OID * /* output_name_type */ 5196 ); 5197 5198 OM_uint32 gss_import_name 5199 (OM_uint32 , /* minor_status */ 5200 const gss_buffer_t, /* input_name_buffer */ 5201 const gss_OID, /* input_name_type */ 5202 gss_name_t * /* output_name */ 5203 ); 5204 5205 5206 5207 5208 5209 5210Wray Standards Track [Page 93] 5211 5212RFC 2744 GSS-API V2: C-bindings January 2000 5213 5214 5215 OM_uint32 gss_export_name 5216 (OM_uint32, /* minor_status */ 5217 const gss_name_t, /* input_name */ 5218 gss_buffer_t /* exported_name */ 5219 ); 5220 5221 OM_uint32 gss_release_name 5222 (OM_uint32 *, /* minor_status */ 5223 gss_name_t * /* input_name */ 5224 ); 5225 5226 OM_uint32 gss_release_buffer 5227 (OM_uint32 , /* minor_status */ 5228 gss_buffer_t /* buffer */ 5229 ); 5230 5231 OM_uint32 gss_release_oid_set 5232 (OM_uint32 , /* minor_status */ 5233 gss_OID_set * /* set */ 5234 ); 5235 5236 OM_uint32 gss_inquire_cred 5237 (OM_uint32 , /* minor_status */ 5238 const gss_cred_id_t, /* cred_handle */ 5239 gss_name_t , /* name */ 5240 OM_uint32 , /* lifetime */ 5241 gss_cred_usage_t , /* cred_usage */ 5242 gss_OID_set * /* mechanisms */ 5243 ); 5244 5245 OM_uint32 gss_inquire_context ( 5246 OM_uint32 , /* minor_status */ 5247 const gss_ctx_id_t, /* context_handle */ 5248 gss_name_t , /* src_name */ 5249 gss_name_t , /* targ_name */ 5250 OM_uint32 , /* lifetime_rec */ 5251 gss_OID , /* mech_type */ 5252 OM_uint32 , /* ctx_flags */ 5253 int , /* locally_initiated */ 5254 int * /* open */ 5255 ); 5256 5257 5258 5259 5260 5261 5262 5263 5264 5265 5266Wray Standards Track [Page 94] 5267 5268RFC 2744 GSS-API V2: C-bindings January 2000 5269 5270 5271 OM_uint32 gss_wrap_size_limit ( 5272 OM_uint32 , /* minor_status */ 5273 const gss_ctx_id_t, /* context_handle */ 5274 int, /* conf_req_flag */ 5275 gss_qop_t, /* qop_req */ 5276 OM_uint32, /* req_output_size */ 5277 OM_uint32 * /* max_input_size */ 5278 ); 5279 5280 OM_uint32 gss_add_cred ( 5281 OM_uint32 , /* minor_status */ 5282 const gss_cred_id_t, /* input_cred_handle */ 5283 const gss_name_t, /* desired_name */ 5284 const gss_OID, /* desired_mech */ 5285 gss_cred_usage_t, /* cred_usage */ 5286 OM_uint32, /* initiator_time_req */ 5287 OM_uint32, /* acceptor_time_req */ 5288 gss_cred_id_t , /* output_cred_handle */ 5289 gss_OID_set , /* actual_mechs */ 5290 OM_uint32 , /* initiator_time_rec */ 5291 OM_uint32 * /* acceptor_time_rec */ 5292 ); 5293 5294 OM_uint32 gss_inquire_cred_by_mech ( 5295 OM_uint32 , /* minor_status */ 5296 const gss_cred_id_t, /* cred_handle */ 5297 const gss_OID, /* mech_type */ 5298 gss_name_t , /* name */ 5299 OM_uint32 , /* initiator_lifetime */ 5300 OM_uint32 , /* acceptor_lifetime */ 5301 gss_cred_usage_t * /* cred_usage */ 5302 ); 5303 5304 OM_uint32 gss_export_sec_context ( 5305 OM_uint32 , /* minor_status */ 5306 gss_ctx_id_t , /* context_handle */ 5307 gss_buffer_t /* interprocess_token */ 5308 ); 5309 5310 OM_uint32 gss_import_sec_context ( 5311 OM_uint32 , /* minor_status */ 5312 const gss_buffer_t, /* interprocess_token */ 5313 gss_ctx_id_t * /* context_handle */ 5314 ); 5315 5316 5317 5318 5319 5320 5321 5322Wray Standards Track [Page 95] 5323 5324RFC 2744 GSS-API V2: C-bindings January 2000 5325 5326 5327 OM_uint32 gss_create_empty_oid_set ( 5328 OM_uint32 , /* minor_status */ 5329 gss_OID_set * /* oid_set */ 5330 ); 5331 5332 OM_uint32 gss_add_oid_set_member ( 5333 OM_uint32 , /* minor_status */ 5334 const gss_OID, /* member_oid */ 5335 gss_OID_set * /* oid_set */ 5336 ); 5337 5338 OM_uint32 gss_test_oid_set_member ( 5339 OM_uint32 , /* minor_status */ 5340 const gss_OID, /* member */ 5341 const gss_OID_set, /* set */ 5342 int * /* present */ 5343 ); 5344 5345 OM_uint32 gss_inquire_names_for_mech ( 5346 OM_uint32 , /* minor_status */ 5347 const gss_OID, /* mechanism */ 5348 gss_OID_set * /* name_types */ 5349 ); 5350 5351 OM_uint32 gss_inquire_mechs_for_name ( 5352 OM_uint32 , /* minor_status */ 5353 const gss_name_t, /* input_name */ 5354 gss_OID_set * /* mech_types */ 5355 ); 5356 5357 OM_uint32 gss_canonicalize_name ( 5358 OM_uint32 , /* minor_status */ 5359 const gss_name_t, /* input_name */ 5360 const gss_OID, /* mech_type */ 5361 gss_name_t * /* output_name */ 5362 ); 5363 5364 OM_uint32 gss_duplicate_name ( 5365 OM_uint32 , /* minor_status */ 5366 const gss_name_t, /* src_name */ 5367 gss_name_t * /* dest_name */ 5368 ); 5369 5370 /* 5371 * The following routines are obsolete variants of gss_get_mic, 5372 * gss_verify_mic, gss_wrap and gss_unwrap. They should be 5373 * provided by GSS-API V2 implementations for backwards 5374 * compatibility with V1 applications. Distinct entrypoints 5375 5376 5377 5378Wray Standards Track [Page 96] 5379 5380RFC 2744 GSS-API V2: C-bindings January 2000 5381 5382 5383 * (as opposed to #defines) should be provided, both to allow 5384 * GSS-API V1 applications to link against GSS-API V2 5385 implementations, 5386 * and to retain the slight parameter type differences between the 5387 * obsolete versions of these routines and their current forms. 5388 */ 5389 5390 OM_uint32 gss_sign 5391 (OM_uint32 , /* minor_status */ 5392 gss_ctx_id_t, /* context_handle */ 5393 int, /* qop_req */ 5394 gss_buffer_t, /* message_buffer */ 5395 gss_buffer_t /* message_token */ 5396 ); 5397 5398 5399 OM_uint32 gss_verify 5400 (OM_uint32 , /* minor_status */ 5401 gss_ctx_id_t, /* context_handle */ 5402 gss_buffer_t, /* message_buffer */ 5403 gss_buffer_t, /* token_buffer */ 5404 int * /* qop_state */ 5405 ); 5406 5407 OM_uint32 gss_seal 5408 (OM_uint32 , /* minor_status */ 5409 gss_ctx_id_t, /* context_handle */ 5410 int, /* conf_req_flag */ 5411 int, /* qop_req */ 5412 gss_buffer_t, /* input_message_buffer */ 5413 int , /* conf_state */ 5414 gss_buffer_t /* output_message_buffer */ 5415 ); 5416 5417 5418 OM_uint32 gss_unseal 5419 (OM_uint32 , /* minor_status */ 5420 gss_ctx_id_t, /* context_handle */ 5421 gss_buffer_t, /* input_message_buffer */ 5422 gss_buffer_t, /* output_message_buffer */ 5423 int , /* conf_state */ 5424 int * /* qop_state */ 5425 ); 5426 5427 #endif /* GSSAPI_H_ */ 5428 5429 5430 5431 5432 5433 5434Wray Standards Track [Page 97] 5435 5436RFC 2744 GSS-API V2: C-bindings January 2000 5437 5438 5439Appendix B. Additional constraints for application binary portability 5440 5441 The purpose of this C-bindings document is to encourage source-level 5442 portability of applications across GSS-API implementations on 5443 different platforms and atop different mechanisms. Additional goals 5444 that have not been explicitly addressed by this document are link- 5445 time and run-time portability. 5446 5447 Link-time portability provides the ability to compile an application 5448 against one implementation of GSS-API, and then link it against a 5449 different implementation on the same platform. It is a stricter 5450 requirement than source-level portability. 5451 5452 Run-time portability differs from link-time portability only on those 5453 platforms that implement dynamically loadable GSS-API 5454 implementations, but do not offer load-time symbol resolution. On 5455 such platforms, run-time portability is a stricter requirement than 5456 link-time portability, and will typically include the precise 5457 placement of the various GSS-API routines within library entrypoint 5458 vectors. 5459 5460 Individual platforms will impose their own rules that must be 5461 followed to achieve link-time (and run-time, if different) 5462 portability. In order to ensure either form of binary portability, 5463 an ABI specification must be written for GSS-API implementations on 5464 that platform. However, it is recognized that there are some issues 5465 that are likely to be common to all such ABI specifications. This 5466 appendix is intended to be a repository for such common issues, and 5467 contains some suggestions that individual ABI specifications may 5468 choose to reference. Since machine architectures vary greatly, it may 5469 not be possible or desirable to follow these suggestions on all 5470 platforms. 5471 5472B.1. Pointers 5473 5474 While ANSI-C provides a single pointer type for each declared type, 5475 plus a single (void *) type, some platforms (notably those using 5476 segmented memory architectures) augment this with various modified 5477 pointer types (e.g. far pointers, near pointers). These language 5478 bindings assume ANSI-C, and thus do not address such non-standard 5479 implementations. GSS-API implementations for such platforms must 5480 choose an appropriate memory model, and should use it consistently 5481 throughout. For example, if a memory model is chosen that requires 5482 the use of far pointers when passing routine parameters, then far 5483 pointers should also be used within the structures defined by GSS- 5484 API. 5485 5486 5487 5488 5489 5490Wray Standards Track [Page 98] 5491 5492RFC 2744 GSS-API V2: C-bindings January 2000 5493 5494 5495B.2. Internal structure alignment 5496 5497 GSS-API defines several data-structures containing differently-sized 5498 fields. An ABI specification should include a detailed description 5499 of how the fields of such structures are aligned, and if there is any 5500 internal padding in these data structures. The use of compiler 5501 defaults for the platform is recommended. 5502 5503B.3. Handle types 5504 5505 The C bindings specify that the gss_cred_id_t and gss_ctx_id_t types 5506 should be implemented as either pointer or arithmetic types, and that 5507 if pointer types are used, care should be taken to ensure that two 5508 handles may be compared with the == operator. Note that ANSI-C does 5509 not guarantee that two pointer values may be compared with the == 5510 operator unless either the two pointers point to members of a single 5511 array, or at least one of the pointers contains a NULL value. 5512 5513 For binary portability, additional constraints are required. The 5514 following is an attempt at defining platform-independent constraints. 5515 5516 The size of the handle type must be the same as sizeof(void *), using 5517 the appropriate memory model. 5518 5519 The == operator for the chosen type must be a simple bit-wise 5520 comparison. That is, for two in-memory handle objects h1 and h2, the 5521 boolean value of the expression 5522 5523 (h1 == h2) 5524 5525 should always be the same as the boolean value of the expression 5526 5527 (memcmp(&h1, &h2, sizeof(h1)) == 0) 5528 5529 The actual use of the type (void *) for handle types is discouraged, 5530 not for binary portability reasons, but since it effectively disables 5531 much of the compile-time type-checking that the compiler can 5532 otherwise perform, and is therefore not "programmer-friendly". If a 5533 pointer implementation is desired, and if the platform's 5534 implementation of pointers permits, the handles should be implemented 5535 as pointers to distinct implementation-defined types. 5536 5537B.4. The gss_name_t type 5538 5539 The gss_name_t type, representing the internal name object, should be 5540 implemented as a pointer type. The use of the (void *) type is 5541 discouraged as it does not allow the compiler to perform strong 5542 type-checking. However, the pointer type chosen should be of the 5543 5544 5545 5546Wray Standards Track [Page 99] 5547 5548RFC 2744 GSS-API V2: C-bindings January 2000 5549 5550 5551 same size as the (void *) type. Provided this rule is obeyed, ABI 5552 specifications need not further constrain the implementation of 5553 gss_name_t objects. 5554 5555B.5. The int and size_t types 5556 5557 Some platforms may support differently sized implementations of the 5558 "int" and "size_t" types, perhaps chosen through compiler switches, 5559 and perhaps dependent on memory model. An ABI specification for such 5560 a platform should include required implementations for these types. 5561 It is recommended that the default implementation (for the chosen 5562 memory model, if appropriate) is chosen. 5563 5564B.6. Procedure-calling conventions 5565 5566 Some platforms support a variety of different binary conventions for 5567 calling procedures. Such conventions cover things like the format of 5568 the stack frame, the order in which the routine parameters are pushed 5569 onto the stack, whether or not a parameter count is pushed onto the 5570 stack, whether some argument(s) or return values are to be passed in 5571 registers, and whether the called routine or the caller is 5572 responsible for removing the stack frame on return. For such 5573 platforms, an ABI specification should specify which calling 5574 convention is to be used for GSS-API implementations. 5575 5576References 5577 5578 [GSSAPI] Linn, J., "Generic Security Service Application Program 5579 Interface Version 2, Update 1", RFC 2743, January 2000. 5580 5581 [XOM] OSI Object Management API Specification, Version 2.0 t", 5582 X.400 API Association & X/Open Company Limited, August 5583 24, 1990 Specification of datatypes and routines for 5584 manipulating information objects. 5585 5586Author's Address 5587 5588 John Wray 5589 Iris Associates 5590 5 Technology Park Drive, 5591 Westford, MA 01886 5592 USA 5593 5594 Phone: +1-978-392-6689 5595 EMail: John_Wray@Iris.com 5596 5597 5598 5599 5600 5601 5602Wray Standards Track [Page 100] 5603 5604RFC 2744 GSS-API V2: C-bindings January 2000 5605 5606 5607Full Copyright Statement 5608 5609 Copyright (C) The Internet Society (2000). All Rights Reserved. 5610 5611 This document and translations of it may be copied and furnished to 5612 others, and derivative works that comment on or otherwise explain it 5613 or assist in its implementation may be prepared, copied, published 5614 and distributed, in whole or in part, without restriction of any 5615 kind, provided that the above copyright notice and this paragraph are 5616 included on all such copies and derivative works. However, this 5617 document itself may not be modified in any way, such as by removing 5618 the copyright notice or references to the Internet Society or other 5619 Internet organizations, except as needed for the purpose of 5620 developing Internet standards in which case the procedures for 5621 copyrights defined in the Internet Standards process must be 5622 followed, or as required to translate it into languages other than 5623 English. 5624 5625 The limited permissions granted above are perpetual and will not be 5626 revoked by the Internet Society or its successors or assigns. 5627 5628 This document and the information contained herein is provided on an 5629 "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING 5630 TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING 5631 BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION 5632 HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF 5633 MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 5634 5635Acknowledgement 5636 5637 Funding for the RFC Editor function is currently provided by the 5638 Internet Society. 5639 5640 5641 5642 5643 5644 5645 5646 5647 5648 5649 5650 5651 5652 5653 5654 5655 5656 5657 5658Wray Standards Track [Page 101] 5659 5660