idnits 2.17.1 draft-ietf-cat-gssv2-cbind-07.txt: -(16): Line appears to be too long, but this could be caused by non-ascii characters in UTF-8 encoding -(21): Line appears to be too long, but this could be caused by non-ascii characters in UTF-8 encoding -(3406): Line appears to be too long, but this could be caused by non-ascii characters in UTF-8 encoding -(3408): Line appears to be too long, but this could be caused by non-ascii characters in UTF-8 encoding -(3409): Line appears to be too long, but this could be caused by non-ascii characters in UTF-8 encoding Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** Cannot find the required boilerplate sections (Copyright, IPR, etc.) in this document. Expected boilerplate is as follows today (2024-04-25) according to https://trustee.ietf.org/license-info : IETF Trust Legal Provisions of 28-dec-2009, Section 6.a: This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79. IETF Trust Legal Provisions of 28-dec-2009, Section 6.b(i), paragraph 2: Copyright (c) 2024 IETF Trust and the persons identified as the document authors. All rights reserved. IETF Trust Legal Provisions of 28-dec-2009, Section 6.b(i), paragraph 3: This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- ** Missing expiration date. The document expiration date should appear on the first and last page. ** The document seems to lack a 1id_guidelines paragraph about Internet-Drafts being working documents. ** The document seems to lack a 1id_guidelines paragraph about 6 months document validity. ** The document seems to lack a 1id_guidelines paragraph about the list of current Internet-Drafts. ** The document seems to lack a 1id_guidelines paragraph about the list of Shadow Directories. ** The document is more than 15 pages and seems to lack a Table of Contents. == There are 5 instances of lines with non-ascii characters in the document. == No 'Intended status' indicated for this document; assuming Proposed Standard == The page length should not exceed 58 lines per page, but there was 100 longer pages, the longest (page 2) being 64 lines Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack a Security Considerations section. ** The document seems to lack an IANA Considerations section. (See Section 2.2 of https://www.ietf.org/id-info/checklist for how to handle the case when there are no actions for IANA.) ** The document seems to lack separate sections for Informative/Normative References. All references will be assumed normative when checking for downward references. ** There are 289 instances of too long lines in the document, the longest one being 2 characters in excess of 72. ** The abstract seems to contain references ([GSSAPI]), which it shouldn't. Please replace those with straight textual mentions of the documents in question. Miscellaneous warnings: ---------------------------------------------------------------------------- == Line 1315 has weird spacing: '..._handle gss...' == Line 1325 has weird spacing: '..._handle gss_c...' == Line 1333 has weird spacing: '..._buffer buff...' == Line 1336 has weird spacing: '...indings chann...' == Line 1543 has weird spacing: '...d. One reaso...' == (26 more instances...) -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (August 7, 1998) is 9393 days in the past. Is this intentional? -- Found something which looks like a code comment -- if you have code sections in the document, please surround them with '' and '' lines. Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) ** Obsolete normative reference: RFC 2078 (ref. 'GSSAPI') (Obsoleted by RFC 2743) -- Possible downref: Non-RFC (?) normative reference: ref. 'XOM' Summary: 13 errors (**), 0 flaws (~~), 9 warnings (==), 4 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 1 Internet Draft J. Wray 2 Common Authentication Technology Working Group Iris Associates 3 August 7, 1998 5 Generic Security Service API Version 2 : C-bindings 7 1. STATUS OF THIS MEMO 9 This document is an Internet Draft. Internet Drafts are working 10 documents of the Internet Engineering Task Force (IETF), its Areas, 11 and its Working Groups. Note that other groups may also distribute 12 working documents as Internet Drafts. Internet Drafts are draft 13 documents valid for a maximum of six months. Internet Drafts may be 14 updated, replaced, or obsoleted by other documents at any time. It 15 is not appropriate to use Internet Drafts as reference material or to 16 cite them other than as a �working draft� or �work in progress.� 17 Please check the I-D abstract listing contained in each Internet 18 Draft directory to learn the current status of this or any other 19 Internet Draft. 21 Comments on this document should be sent to �cat-ietf@mit.edu�, the 22 IETF Common Authentication Technology WG discussion list. 24 2. ABSTRACT 26 This draft document specifies C language bindings for Version 2 of 27 the Generic Security Service Application Program Interface (GSSAPI), 28 which is described at a language-independent conceptual level in 29 other drafts [GSSAPI]. It revises RFC-1509, making specific 30 incremental changes in response to implementation experience and 31 liaison requests. It is intended, therefore, that this draft or a 32 successor version thereof will become the basis for subsequent 33 progression of the GSS-API specification on the standards track. 35 The Generic Security Service Application Programming Interface 36 provides security services to its callers, and is intended for 37 implementation atop a variety of underlying cryptographic mechanisms. 38 Typically, GSSAPI callers will be application protocols into which 39 security enhancements are integrated through invocation of services 40 provided by the GSSAPI. The GSSAPI allows a caller application to 41 authenticate a principal identity associated with a peer application, 42 to delegate rights to a peer, and to apply security services such as 43 confidentiality and integrity on a per-message basis. 45 Wray [Page 1 of 101] 46 3. INTRODUCTION 48 The Generic Security Service Application Programming Interface 49 [GSSAPI] provides security services to calling applications. It 50 allows a communicating application to authenticate the user 51 associated with another application, to delegate rights to another 52 application, and to apply security services such as confidentiality 53 and integrity on a per-message basis. 55 There are four stages to using the GSSAPI: 57 a) The application acquires a set of credentials with which 58 it may prove its identity to other processes. The 59 application's credentials vouch for its global identity, 60 which may or may not be related to any local username 61 under which it may be running. 63 b) A pair of communicating applications establish a joint 64 security context using their credentials. The security 65 context is a pair of GSSAPI data structures that contain 66 shared state information, which is required in order that 67 per-message security services may be provided. Examples 68 of state that might be shared between applications 69 as part of a security context are cryptographic keys, and 70 message sequence numbers. As part of the establishment of 71 a security context, the context initiator is authenticated 72 to the responder, and may require that the responder is 73 authenticated in turn. The initiator may optionally give 74 the responder the right to initiate further security 75 contexts, acting as an agent or delegate of the initiator. 76 This transfer of rights is termed delegation, and is 77 achieved by creating a set of credentials, similar to 78 those used by the initiating application, but which may 79 be used by the responder. 81 To establish and maintain the shared information that makes 82 up the security context, certain GSSAPI calls will return a 83 token data structure, which is an opaque data type that may 84 contain cryptographically protected data. The caller of 85 such a GSSAPI routine is responsible for transferring the 86 token to the peer application, encapsulated if necessary in 87 an application-application protocol. On receipt of such 88 a token, the peer application should pass it to a 89 corresponding GSSAPI routine which will decode the token 90 and extract the information, updating the security context 91 state information accordingly. 93 c) Per-message services are invoked to apply either: 95 integrity and data origin authentication, or 97 confidentiality, integrity and data origin authentication 99 Wray [Page 2 of 101] 100 to application data, which are treated by GSSAPI as arbitrary 101 octet-strings. An application transmitting a message that it 102 wishes to protect will call the appropriate GSSAPI routine 103 (gss_get_mic or gss_wrap) to apply protection, specifying the 104 appropriate security context, and send the resulting token to 105 the receiving application. The receiver will pass the 106 received token (and, in the case of data protected by 107 gss_get_mic, the accompanying message-data) to the 108 corresponding decoding routine (gss_verify_mic or gss_unwrap) 109 to remove the protection and validate the data. 111 d) At the completion of a communications session (which may 112 extend across several transport connections), each 113 application calls a GSSAPI routine to delete the security 114 context. Multiple contexts may also be used (either 115 successively or simultaneously) within a single communications 116 association, at the option of the applications. 118 4. GSSAPI ROUTINES 120 This section lists the routines that make up the GSSAPI, and offers a 121 brief description of the purpose of each routine. Detailed 122 descriptions of each routine are listed in alphabetical order in 123 section 7. 125 Table 4-1 GSSAPI Credential-management Routines 127 Routine Section Function 128 ------- ------- -------- 129 gss_acquire_cred 7.2 Assume a global identity; Obtain 130 a GSSAPI credential handle for 131 pre-existing credentials. 132 gss_add_cred 7.3 Construct credentials 133 incrementally 134 gss_inquire_cred 7.21 Obtain information about a 135 credential 136 gss_inquire_cred_by_mech 7.22 Obtain per-mechanism information 137 about a credential. 138 gss_release_cred 7.27 Discard a credential handle. 140 Wray [Page 3 of 101] 141 Table 4-2 GSSAPI Context-Level Routines 143 Routine Section Function 144 ------- ------- -------- 145 gss_init_sec_context 7.19 Initiate a security context with 146 a peer application 147 gss_accept_sec_context 7.1 Accept a security context 148 initiated by a 149 peer application 150 gss_delete_sec_context 7.9 Discard a security context 151 gss_process_context_token 7.25 Process a token on a security 152 context from a peer application 153 gss_context_time 7.7 Determine for how long a context 154 will remain valid 155 gss_inquire_context 7.20 Obtain information about a 156 security context 157 gss_wrap_size_limit 7.34 Determine token-size limit for 158 gss_wrap on a context 159 gss_export_sec_context 7.14 Transfer a security context to 160 another process 161 gss_import_sec_context 7.17 Import a transferred context 163 Table 4-3 GSSAPI Per-message Routines 165 Routine Section Function 166 ------- ------- -------- 167 gss_get_mic 7.15 Calculate a cryptographic message 168 integrity code (MIC) for a 169 message; integrity service 170 gss_verify_mic 7.32 Check a MIC against a message; 171 verify integrity of a received 172 message 173 gss_wrap 7.33 Attach a MIC to a message, and 174 optionally encrypt the message 175 content; 176 confidentiality service 177 gss_unwrap 7.31 Verify a message with attached 178 MIC, and decrypt message content 179 if necessary. 181 Table 4-4 GSSAPI Name manipulation Routines 183 Routine Section Function 184 ------- ------- -------- 185 gss_import_name 7.16 Convert a contiguous string name 186 to internal-form 187 gss_display_name 7.10 Convert internal-form name to 188 text 189 gss_compare_name 7.6 Compare two internal-form names 191 Wray [Page 4 of 101] 192 gss_release_name 7.28 Discard an internal-form name 193 gss_inquire_names_for_mech 7.24 List the name-types supported by 194 the specified mechanism 195 gss_inquire_mechs_for_name 7.23 List mechanisms that support the 196 specified name-type 197 gss_canonicalize_name 7.5 Convert an internal name to an MN 198 gss_export_name 7.13 Convert an MN to export form 199 gss_duplicate_name 7.12 Create a copy of an internal name 201 Table 4-5 GSSAPI Miscellaneous Routines 203 Routine Section Function 204 ------- ------- -------- 205 gss_add_oid_set_member 7.4 Add an object identifier to 206 a set 207 gss_display_status 7.11 Convert a GSSAPI status code 208 to text 209 gss_indicate_mechs 7.18 Determine available underlying 210 authentication mechanisms 211 gss_release_buffer 7.26 Discard a buffer 212 gss_release_oid_set 7.29 Discard a set of object 213 identifiers 214 gss_create_empty_oid_set 7.8 Create a set containing no 215 object identifiers 216 gss_test_oid_set_member 7.30 Determines whether an object 217 identifier is a member of a set. 219 Individual GSSAPI implementations may augment these routines by 220 providing additional mechanism-specific routines if required 221 functionality is not available from the generic forms. Applications 222 are encouraged to use the generic routines wherever possible on 223 portability grounds. 225 5. DATA TYPES AND CALLING CONVENTIONS 227 The following conventions are used by the GSSAPI C-language bindings: 229 5.1. Integer types 231 GSSAPI uses the following integer data type: 233 OM_uint32 32-bit unsigned integer 235 Where guaranteed minimum bit-count is important, this portable data 236 type is used by the GSSAPI routine definitions. Individual GSSAPI 237 implementations will include appropriate typedef definitions to map 238 this type onto a built-in data type. If the platform supports the 239 X/Open xom.h header file, the OM_uint32 definition contained therein 240 should be used; the GSSAPI header file in Appendix A contains logic 241 that will detect the prior inclusion of xom.h, and will not attempt 243 Wray [Page 5 of 101] 244 to re-declare OM_uint32. If the X/Open header file is not available 245 on the platform, the GSSAPI implementation should use the smallest 246 natural unsigned integer type that provides at least 32 bits of 247 precision. 249 5.2. String and similar data 251 Many of the GSSAPI routines take arguments and return values that 252 describe contiguous octet-strings. All such data is passed between 253 the GSSAPI and the caller using the gss_buffer_t data type. This 254 data type is a pointer to a buffer descriptor, which consists of a 255 length field that contains the total number of bytes in the datum, 256 and a value field which contains a pointer to the actual datum: 258 typedef struct gss_buffer_desc_struct { 259 size_t length; 260 void *value; 261 } gss_buffer_desc, *gss_buffer_t; 263 Storage for data returned to the application by a GSSAPI routine 264 using the gss_buffer_t conventions is allocated by the GSSAPI 265 routine. The application may free this storage by invoking the 266 gss_release_buffer routine. Allocation of the gss_buffer_desc object 267 is always the responsibility of the application; unused 268 gss_buffer_desc objects may be initialized to the value 269 GSS_C_EMPTY_BUFFER. 271 5.2.1. Opaque data types 273 Certain multiple-word data items are considered opaque data types at 274 the GSSAPI, because their internal structure has no significance 275 either to the GSSAPI or to the caller. Examples of such opaque data 276 types are the input_token parameter to gss_init_sec_context (which is 277 opaque to the caller), and the input_message parameter to gss_wrap 278 (which is opaque to the GSSAPI). Opaque data is passed between the 279 GSSAPI and the application using the gss_buffer_t datatype. 281 5.2.2. Character strings 283 Certain multiple-word data items may be regarded as simple ISO 284 Latin-1 character strings. Examples are the printable strings passed 285 to gss_import_name via the input_name_buffer parameter. Some GSSAPI 286 routines also return character strings. All such character strings 287 are passed between the application and the GSSAPI implementation 288 using the gss_buffer_t datatype, which is a pointer to a 289 gss_buffer_desc object. 291 When a gss_buffer_desc object describes a printable string, the 292 length field of the gss_buffer_desc should only count printable 293 characters within the string. In particular, a trailing NUL 294 character should NOT be included in the length count, nor should 296 Wray [Page 6 of 101] 297 either the GSSAPI implementation or the application assume the 298 presence of an uncounted trailing NUL. 300 5.3. Object Identifiers 302 Certain GSSAPI procedures take parameters of the type gss_OID, or 303 Object identifier. This is a type containing ISO-defined 304 tree-structured values, and is used by the GSSAPI caller to select an 305 underlying security mechanism and to specify namespaces. A value of 306 type gss_OID has the following structure: 308 typedef struct gss_OID_desc_struct { 309 OM_uint32 length; 310 void *elements; 311 } gss_OID_desc, *gss_OID; 313 The elements field of this structure points to the first byte of an 314 octet string containing the ASN.1 BER encoding of the value portion 315 of the normal BER TLV encoding of the gss_OID. The length field 316 contains the number of bytes in this value. For example, the gss_OID 317 value corresponding to {iso(1) identified-organization(3) 318 icd-ecma(12) member-company(2) dec(1011) cryptoAlgorithms(7) 319 DASS(5)}, meaning the DASS X.509 authentication mechanism, has a 320 length field of 7 and an elements field pointing to seven octets 321 containing the following octal values: 53,14,2,207,163,7,5. GSSAPI 322 implementations should provide constant gss_OID values to allow 323 applications to request any supported mechanism, although 324 applications are encouraged on portability grounds to accept the 325 default mechanism. gss_OID values should also be provided to allow 326 applications to specify particular name types (see section 5.10). 327 Applications should treat gss_OID_desc values returned by GSSAPI 328 routines as read-only. In particular, the application should not 329 attempt to deallocate them with free(). The gss_OID_desc datatype is 330 equivalent to the X/Open OM_object_identifier datatype[XOM]. 332 5.4. Object Identifier Sets 334 Certain GSSAPI procedures take parameters of the type gss_OID_set. 335 This type 336 represents one or more object identifiers (section 5.3). A 337 gss_OID_set object has the following structure: 339 typedef struct gss_OID_set_desc_struct { 340 size_t count; 341 gss_OID elements; 342 } gss_OID_set_desc, *gss_OID_set; 344 The count field contains the number of OIDs within the set. The 345 elements field is a pointer to an array of gss_OID_desc objects, each 346 of which describes a single OID. gss_OID_set values are used to name 347 the available mechanisms supported by the GSSAPI, to request the use 348 of specific mechanisms, and to indicate which mechanisms a given 349 credential supports. 351 Wray [Page 7 of 101] 352 All OID sets returned to the application by GSSAPI are dynamic 353 objects (the gss_OID_set_desc, the "elements" array of the set, and 354 the "elements" array of each member OID are all dynamically 355 allocated), and this storage must be deallocated by the application 356 using the gss_release_oid_set() routine. 358 5.5. Credentials 360 A credential handle is a caller-opaque atomic datum that identifies a 361 GSSAPI credential data structure. It is represented by the 362 caller-opaque type gss_cred_id_t, which should be implemented as a 363 pointer or arithmetic type. If a pointer implementation is chosen, 364 care must be taken to ensure that two gss_cred_id_t values may be 365 compared with the == operator. 367 GSSAPI credentials can contain mechanism-specific principal 368 authentication data for multiple mechanisms. A GSSAPI credential is 369 composed of a set of credential-elements, each of which is applicable 370 to a single mechanism. A credential may contain at most one 371 credential-element for each supported mechanism. A credential-element 372 identifies the data needed by a single mechanism to authenticate a 373 single principal, and conceptually contains two credential-references 374 that describe the actual mechanism-specific authentication data, one 375 to be used by GSSAPI for initiating contexts, and one to be used for 376 accepting contexts. For mechanisms that do not distinguish between 377 acceptor and initiator credentials, both references would point to 378 the same underlying mechanism-specific authentication data. 380 Credentials describe a set of mechanism-specific principals, and give 381 their holder the ability to act as any of those principals. All 382 principal identities asserted by a single GSSAPI credential should 383 belong to the same entity, although enforcement of this property is 384 an implementation-specific matter. The GSSAPI does not make the 385 actual credentials available to applications; instead a credential 386 handle is used to identify a particular credential, held internally 387 by GSSAPI. The combination of GSSAPI credential handle and mechanism 388 identifies the principal whose identity will be asserted by the 389 credential when used with that mechanism. 391 The gss_init_sec_context and gss_accept_sec_context routines allow 392 the value GSS_C_NO_CREDENTIAL to be specified as their credential 393 handle parameter. This special credential-handle indicates a desire 394 by the application to act as a default principal. While individual 395 GSSAPI implementations are free to determine such default behavior as 396 appropriate to the mechanism, the following default behavior by these 397 routines is recommended for portability: 399 gss_init_sec_context 401 1) If there is only a single principal capable of initiating 402 security contexts for the chosen mechanism that the 403 application is authorized to act on behalf of, then that 404 principal shall be used, otherwise 406 Wray [Page 8 of 101] 407 2) If the platform maintains a concept of a default 408 network-identity for the chosen mechanism, and if the 409 application is authorized to act on behalf of that 410 identity for the purpose of initiating security contexts, 411 then the principal corresponding to that identity shall 412 be used, otherwise 414 3) If the platform maintains a concept of a default local 415 identity, and provides a means to map local identities 416 into network-identities for the chosen mechanism, and 417 if the application is authorized to act on behalf of 418 the network-identity image of the default local 419 identity for the purpose of initiating security contexts 420 using the chosen mechanism, then the principal 421 corresponding to that identity shall be used, otherwise 423 4) A user-configurable default identity should be used. 425 gss_accept_sec_context 427 1) If there is only a single authorized principal identity 428 capable of accepting security contexts for the chosen 429 mechanism, then that principal shall be used, otherwise 431 2) If the mechanism can determine the identity of the 432 target principal by examining the context-establishment 433 token, and if the accepting application is authorized to 434 act as that principal for the purpose of accepting security 435 contexts using the chosen mechanism, then that principal 436 identity shall be used, otherwise 438 3) If the mechanism supports context acceptance by any 439 principal, and if mutual authentication was not requested, 440 any principal that the application is authorized to accept 441 security contexts under using the chosen mechanism may be 442 used, otherwise 444 4)A user-configurable default identity shall be used. 446 The purpose of the above rules is to allow security contexts to be 447 established by both initiator and acceptor using the default behavior 448 wherever possible. Applications requesting default behavior are 449 likely to be more portable across mechanisms and platforms than ones 450 that use gss_acquire_cred to request a specific identity. 452 5.6. Contexts 454 The gss_ctx_id_t data type contains a caller-opaque atomic value that 455 identifies one end of a GSSAPI security context. It should be 456 implemented as a pointer or arithmetic type. If a pointer type is 457 chosen, care should be taken to ensure that two gss_ctx_id_t values 458 may be compared with the == operator. 460 Wray [Page 9 of 101] 461 The security context holds state information about each end of a peer 462 communication, including cryptographic state information. 464 5.7. Authentication tokens 466 A token is a caller-opaque type that GSSAPI uses to maintain 467 synchronization between the context data structures at each end of a 468 GSSAPI security context. The token is a cryptographically protected 469 octet-string, generated by the underlying mechanism at one end of a 470 GSSAPI security context for use by the peer mechanism at the other 471 end. Encapsulation (if required) and transfer of the token are the 472 responsibility of the peer applications. A token is passed between 473 the GSSAPI and the application using the gss_buffer_t conventions. 475 5.8. Interprocess tokens 477 Certain GSSAPI routines are intended to transfer data between 478 processes in multi-process programs. These routines use a 479 caller-opaque octet-string, generated by the GSSAPI in one process 480 for use by the GSSAPI in another process. The calling application is 481 responsible for transferring such tokens between processes in an 482 OS-specific manner. Note that, while GSSAPI implementors are 483 encouraged to avoid placing sensitive information within interprocess 484 tokens, or to cryptographically protect them, many implementations 485 will be unable to avoid placing key material or other sensitive data 486 within them. It is the application's responsibility to ensure that 487 interprocess tokens are protected in transit, and transferred only to 488 processes that are trustworthy. An interprocess token is passed 489 between the GSSAPI and the application using the gss_buffer_t 490 conventions. 492 5.9. Status values 494 Every GSSAPI routine returns two distinct values to report status 495 information to the caller: GSS status codes and Mechanism status 496 codes. 498 5.9.1. GSS status codes 500 GSSAPI routines return GSS status codes as their OM_uint32 function 501 value. These codes indicate errors that are independent of the 502 underlying mechanism(s) used to provide the security service. The 503 errors that can be indicated via a GSS status code are either generic 504 API routine errors (errors that are defined in the GSS-API 505 specification) or calling errors (errors that are specific to these 506 language bindings). 508 A GSS status code can indicate a single fatal generic API error from 509 the routine and a single calling error. In addition, supplementary 511 Wray [Page 10 of 101] 512 status information may be indicated via the setting of bits in the 513 supplementary info field of a GSS status code. 515 These errors are encoded into the 32-bit GSS status code as follows: 517 MSB LSB 518 |------------------------------------------------------------| 519 | Calling Error | Routine Error | Supplementary Info | 520 |------------------------------------------------------------| 521 Bit 31 24 23 16 15 0 523 Hence if a GSS-API routine returns a GSS status code whose upper 16 524 bits contain a non-zero value, the call failed. If the calling error 525 field is non-zero, the invoking application's call of the routine was 526 erroneous. Calling errors are defined in table 5-1. If the routine 527 error field is non-zero, the routine failed for one of the 528 routine-specific reasons listed below in table 5-2. Whether or not 529 the upper 16 bits indicate a failure or a success, the routine may 530 indicate additional information by setting bits in the supplementary 531 info field of the status code. The meaning of individual bits is 532 listed below in table 5-3. 534 Table 5-1 Calling Errors 536 Name Value in field Meaning 537 ---- -------------- ------- 538 GSS_S_CALL_INACCESSIBLE_READ 1 A required input parameter 539 could not be read 540 GSS_S_CALL_INACCESSIBLE_WRITE 2 A required output parameter 541 could not be written. 542 GSS_S_CALL_BAD_STRUCTURE 3 A parameter was malformed 544 Table 5-2 Routine Errors 546 Name Value in field Meaning 547 ---- -------------- ------- 548 GSS_S_BAD_MECH 1 An unsupported mechanism 549 was requested 550 GSS_S_BAD_NAME 2 An invalid name was 551 supplied 552 GSS_S_BAD_NAMETYPE 3 A supplied name was of an 553 unsupported type 554 GSS_S_BAD_BINDINGS 4 Incorrect channel bindings 555 were supplied 556 GSS_S_BAD_STATUS 5 An invalid status code was 557 supplied 558 GSS_S_BAD_MIC GSS_S_BAD_SIG 6 A token had an invalid MIC 559 GSS_S_NO_CRED 7 No credentials were 560 supplied, or the 561 credentials were 562 unavailable or 563 inaccessible. 565 Wray [Page 11 of 101] 566 GSS_S_NO_CONTEXT 8 No context has been 567 established 568 GSS_S_DEFECTIVE_TOKEN 9 A token was invalid 569 GSS_S_DEFECTIVE_CREDENTIAL 10 A credential was invalid 570 GSS_S_CREDENTIALS_EXPIRED 11 The referenced credentials 571 have expired 572 GSS_S_CONTEXT_EXPIRED 12 The context has expired 573 GSS_S_FAILURE 13 Miscellaneous failure (see 574 text) 575 GSS_S_BAD_QOP 14 The quality-of-protection 576 requested could not be 577 provided 578 GSS_S_UNAUTHORIZED 15 The operation is forbidden 579 by local security policy 580 GSS_S_UNAVAILABLE 16 The operation or option is 581 unavailable 582 GSS_S_DUPLICATE_ELEMENT 17 The requested credential 583 element already exists 584 GSS_S_NAME_NOT_MN 18 The provided name was not a 585 mechanism name 587 Table 5-3 Supplementary Status Bits 589 Name Bit Number Meaning 590 ---- ---------- ------- 591 GSS_S_CONTINUE_NEEDED 0 (LSB) Returned only by 592 gss_init_sec_context or 593 gss_accept_sec_context. The 594 routine must be called again 595 to complete its function. 596 See routine documentation for 597 detailed description 598 GSS_S_DUPLICATE_TOKEN 1 The token was a duplicate of 599 an earlier token 600 GSS_S_OLD_TOKEN 2 The token's validity period 601 has expired 602 GSS_S_UNSEQ_TOKEN 3 A later token has already been 603 processed 604 GSS_S_GAP_TOKEN 4 An expected per-message token 605 was not received 607 The routine documentation also uses the name GSS_S_COMPLETE, which is 608 a zero value, to indicate an absence of any API errors or 609 supplementary information bits. 611 All GSS_S_xxx symbols equate to complete OM_uint32 status codes, 612 rather than to bitfield values. For example, the actual value of the 613 symbol GSS_S_BAD_NAMETYPE (value 3 in the routine error field) is 614 3<<16. 615 The macros GSS_CALLING_ERROR(), GSS_ROUTINE_ERROR() and 616 GSS_SUPPLEMENTARY_INFO() are provided, each of which takes a GSS 617 status code and removes all but the relevant field. For example, the 619 Wray [Page 12 of 101] 620 value obtained by applying GSS_ROUTINE_ERROR to a status code removes 621 the calling errors and supplementary info fields, leaving only the 622 routine errors field. The values delivered by these macros may be 623 directly compared with a GSS_S_xxx symbol of the appropriate type. 624 The macro GSS_ERROR() is also provided, which when applied to a GSS 625 status code returns a non-zero value if the status code indicated a 626 calling or routine error, and a zero value otherwise. All macros 627 defined by GSS-API evaluate their argument(s) exactly once. 629 A GSS-API implementation may choose to signal calling errors in a 630 platform-specific manner instead of, or in addition to the routine 631 value; routine errors and supplementary info should be returned via 632 major status values only. 634 The GSS major status code GSS_S_FAILURE is used to indicate that the 635 underlying mechanism detected an error for which no specific GSS 636 status code is defined. The mechanism-specific status code will 637 provide more details about the error. 639 5.9.2. Mechanism-specific status codes 641 GSS-API routines return a minor_status parameter, which is used to 642 indicate specialized errors from the underlying security mechanism. 643 This parameter may contain a single mechanism-specific error, 644 indicated by a OM_uint32 value. 646 The minor_status parameter will always be set by a GSS-API routine, 647 even if it returns a calling error or one of the generic API errors 648 indicated above as fatal, although most other output parameters may 649 remain unset in such cases. However, output parameters that are 650 expected to return pointers to storage allocated by a routine must 651 always be set by the routine, even in the event of an error, although 652 in such cases the GSS-API routine may elect to set the returned 653 parameter value to NULL to indicate that no storage was actually 654 allocated. Any length field associated with such pointers (as in a 655 gss_buffer_desc structure) should also be set to zero in such cases. 657 5.10.Names 659 A name is used to identify a person or entity. GSS-API authenticates 660 the relationship between a name and the entity claiming the name. 662 Since different authentication mechanisms may employ different 663 namespaces for identifying their principals, GSSAPI's naming support 664 is necessarily complex in multi-mechanism environments (or even in 665 some single-mechanism environments where the underlying mechanism 666 supports multiple namespaces). 668 Two distinct representations are defined for names: 670 An internal form. This is the GSSAPI "native" format for names, 671 represented by the implementation-specific gss_name_t type. 673 Wray [Page 13 of 101] 674 It is opaque to GSSAPI callers. A single gss_name_t object 675 may contain multiple names from different namespaces, but 676 all names should refer to the same entity. An example of 677 such an internal name would be the name returned from a 678 call to the gss_inquire_cred routine, when applied to a 679 credential containing credential elements for multiple 680 authentication mechanisms employing different namespaces. 681 This gss_name_t object will contain a distinct name for the 682 entity for each authentication mechanism. 684 For GSSAPI implementations supporting multiple namespaces, 685 objects of type gss_name_t must contain sufficient 686 information to determine the namespace to which each 687 primitive name belongs. 689 Mechanism-specific contiguous octet-string forms. A format 690 capable of containing a single name (from a single 691 namespace). Contiguous string names are always accompanied 692 by an object identifier specifying the namespace to which 693 the name belongs, and their format is dependent on the 694 authentication mechanism that employs the name. Many, but 695 not all, contiguous string names will be printable, and may 696 therefore be used by GSSAPI applications for communication 697 with their users. 699 Routines (gss_import_name and gss_display_name) are provided to 700 convert names between contiguous string representations and the 701 internal gss_name_t type. gss_import_name may support multiple 702 syntaxes for each supported namespace, allowing users the freedom to 703 choose a preferred name representation. gss_display_name should use 704 an implementation-chosen printable syntax for each supported 705 name-type. 707 If an application calls gss_display_name(), passing the internal name 708 resulting from a call to gss_import_name(), there is no guarantee 709 the the resulting contiguous string name will be the same as the 710 original imported string name. Nor do name-space identifiers 711 necessarily survive unchanged after a journey through the internal 712 name-form. An example of this might be a mechanism that 713 authenticates X.500 names, but provides an algorithmic mapping of 714 Internet DNS names into X.500. That mechanism's implementation of 715 gss_import_name() might, when presented with a DNS name, generate an 716 internal name that contained both the original DNS name and the 717 equivalent X.500 name. Alternatively, it might only store the X.500 718 name. In the latter case, gss_display_name() would most likely 719 generate a printable X.500 name, rather than the original DNS name. 721 The process of authentication delivers to the context acceptor an 722 internal name. Since this name has been authenticated by a single 723 mechanism, it contains only a single name (even if the internal name 724 presented by the context initiator to gss_init_sec_context had 725 multiple components). Such names are termed internal mechanism 726 names, or "MN"s and the names emitted by gss_accept_sec_context() are 727 always of this type. Since some applications may require MNs without 728 wanting to incur the overhead of an authentication operation, a 730 Wray [Page 14 of 101] 731 second function, gss_canonicalize_name(), is provided to convert a 732 general internal name into an MN. 734 Comparison of internal-form names may be accomplished via the 735 gss_compare_name() routine, which returns true if the two names being 736 compared refer to the same entity. This removes the need for the 737 application program to understand the syntaxes of the various 738 printable names that a given GSS-API implementation may support. 739 Since GSSAPI assumes that all primitive names contained within a 740 given internal name refer to the same entity, gss_compare_name() can 741 return true if the two names have at least one primitive name in 742 common. If the implementation embodies knowledge of equivalence 743 relationships between names taken from different namespaces, this 744 knowledge may also allow successful comparison of internal names 745 containing no overlapping primitive elements. 747 When used in large access control lists, the overhead of invoking 748 gss_import_name() and gss_compare_name() on each name from the ACL 749 may be prohibitive. As an alternative way of supporting this case, 750 GSSAPI defines a special form of the contiguous string name which may 751 be compared directly (e.g. with memcmp()). Contigous names suitable 752 for comparison are generated by the gss_export_name() routine, which 753 requires an MN as input. Exported names may be re-imported by the 754 gss_import_name() routine, and the resulting internal name will also 755 be an MN. The gss_OID constant GSS_C_NT_EXPORT_NAME indentifies the 756 "export name" type, and the value of this constant is given in 757 Appendix A. Structurally, an exported name object consists of a 758 header containing an OID identifying the mechanism that authenticated 759 the name, and a trailer containing the name itself, where the syntax 760 of the trailer is defined by the individual mechanism specification. 761 The precise format of an export name is defined in the 762 language-independent GSSAPI specification [GSSAPI]. 764 Note that the results obtained by using gss_compare_name() will in 765 general be different from those obtained by invoking 766 gss_canonicalize_name() and gss_export_name(), and then comparing the 767 exported names. The first series of operation determines whether two 768 (unauthenticated) names identify the same principal; the second 769 whether a particular mechanism would authenticate them as the same 770 principal. These two operations will in general give the same 771 results only for MNs. 773 The gss_name_t datatype should be implemented as a pointer type. To 774 allow the compiler to aid the application programmer by performing 775 type-checking, the use of (void *) is discouraged. A pointer to an 776 implementation-defined type is the preferred choice. 778 Storage is allocated by routines that return gss_name_t values. A 779 procedure, gss_release_name, is provided to free storage associated 780 with an internal-form name. 782 5.11.Channel Bindings 784 Wray [Page 15 of 101] 785 GSS-API supports the use of user-specified tags to identify a given 786 context to the peer application. These tags are intended to be used 787 to identify the particular communications channel that carries the 788 context. Channel bindings are communicated to the GSS-API using the 789 following structure: 791 typedef struct gss_channel_bindings_struct { 792 OM_uint32 initiator_addrtype; 793 gss_buffer_desc initiator_address; 794 OM_uint32 acceptor_addrtype; 795 gss_buffer_desc acceptor_address; 796 gss_buffer_desc application_data; 797 } *gss_channel_bindings_t; 799 The initiator_addrtype and acceptor_addrtype fields denote the type 800 of addresses contained in the initiator_address and acceptor_address 801 buffers. The address type should be one of the following: 803 GSS_C_AF_UNSPEC Unspecified address type 804 GSS_C_AF_LOCAL Host-local address type 805 GSS_C_AF_INET Internet address type (e.g. IP) 806 GSS_C_AF_IMPLINK ARPAnet IMP address type 807 GSS_C_AF_PUP pup protocols (eg BSP) address type 808 GSS_C_AF_CHAOS MIT CHAOS protocol address type 809 GSS_C_AF_NS XEROX NS address type 810 GSS_C_AF_NBS nbs address type 811 GSS_C_AF_ECMA ECMA address type 812 GSS_C_AF_DATAKIT datakit protocols address type 813 GSS_C_AF_CCITT CCITT protocols 814 GSS_C_AF_SNA IBM SNA address type 815 GSS_C_AF_DECnet DECnet address type 816 GSS_C_AF_DLI Direct data link interface address type 817 GSS_C_AF_LAT LAT address type 818 GSS_C_AF_HYLINK NSC Hyperchannel address type 819 GSS_C_AF_APPLETALK AppleTalk address type 820 GSS_C_AF_BSC BISYNC 2780/3780 address type 821 GSS_C_AF_DSS Distributed system services address type 822 GSS_C_AF_OSI OSI TP4 address type 823 GSS_C_AF_X25 X.25 824 GSS_C_AF_NULLADDR No address specified 826 Note that these symbols name address families rather than specific 827 addressing formats. For address families that contain several 828 alternative address forms, the initiator_address and acceptor_address 829 fields must contain sufficient information to determine which address 830 form is used. When not otherwise specified, addresses should be 831 specified in network byte-order (that is, native byte-ordering for 832 the address family). 834 Conceptually, the GSS-API concatenates the initiator_addrtype, 835 initiator_address, acceptor_addrtype, acceptor_address and 836 application_data to form an octet string. The mechanism calculates a 837 MIC over this octet string, and binds the MIC to the context 838 establishment token emitted by gss_init_sec_context. The same 839 bindings are presented by the context acceptor to 841 Wray [Page 16 of 101] 842 gss_accept_sec_context, and a MIC is calculated in the same way. The 843 calculated MIC is compared with that found in the token, and if the 844 MICs differ, gss_accept_sec_context will return a GSS_S_BAD_BINDINGS 845 error, and the context will not be established. Some mechanisms may 846 include the actual channel binding data in the token (rather than 847 just a MIC); applications should therefore not use confidential data 848 as channel-binding components. 850 Individual mechanisms may impose additional constraints on addresses 851 and address types that may appear in channel bindings. For example, 852 a mechanism may verify that the initiator_address field of the 853 channel bindings presented to gss_init_sec_context contains the 854 correct network address of the host system. Portable applications 855 should therefore ensure that they either provide correct information 856 for the address fields, or omit addressing information, specifying 857 GSS_C_AF_NULLADDR as the address-types. 859 5.12.Optional parameters 860 Various parameters are described as optional. This means that they 861 follow a convention whereby a default value may be requested. The 862 following conventions are used for omitted parameters. These 863 conventions apply only to those parameters that are explicitly 864 documented as optional. 866 5.12.1. gss_buffer_t types 868 Specify GSS_C_NO_BUFFER as a value. For an input parameter this 869 signifies that default behavior is requested, while for an output 870 parameter it indicates that the information that would be returned 871 via the parameter is not required by the application. 873 5.12.2. Integer types (input) 875 Individual parameter documentation lists values to be used to 876 indicate default actions. 878 5.12.3. Integer types (output) 880 Specify NULL as the value for the pointer. 882 5.12.4. Pointer types 884 Specify NULL as the value. 886 5.12.5. Object IDs 888 Specify GSS_C_NO_OID as the value. 890 Wray [Page 17 of 101] 891 5.12.6. Object ID Sets 893 Specify GSS_C_NO_OID_SET as the value. 895 5.12.7. Channel Bindings 897 Specify GSS_C_NO_CHANNEL_BINDINGS to indicate that channel bindings 898 are not to be used. 900 6. ADDITIONAL CONTROLS 902 This section discusses the optional services that a context initiator 903 may request of the GSS-API at context establishment. Each of these 904 services is requested by setting a flag in the req_flags input 905 parameter to gss_init_sec_context. 907 The optional services currently defined are: 909 Delegation - The (usually temporary) transfer of rights from 910 initiator to acceptor, enabling the acceptor to authenticate 911 itself as an agent of the initiator. 913 Mutual Authentication - In addition to the initiator 914 authenticating its identity to the context acceptor, the 915 context acceptor should also authenticate itself to the 916 initiator. 918 Replay detection - In addition to providing message integrity 919 services, gss_get_mic and gss_wrap should include message 920 numbering information to enable gss_verify_mic and gss_unwrap 921 to detect if a message has been duplicated. 923 Out-of-sequence detection - In addition to providing message 924 integrity services, gss_get_mic and gss_wrap should include 925 message sequencing information to enable gss_verify_mic and 926 gss_unwrap to detect if a message has been received out of 927 sequence. 929 Anonymous authentication - The establishment of the security 930 context should not reveal the initiator's identity to the 931 context acceptor. 933 Any currently undefined bits within such flag arguments should be 934 ignored by GSS-API implementations when presented by an application, 935 and should be set to zero when returned to the application by the 936 GSS-API implementation. 938 Some mechanisms may not support all optional services, and some 939 mechanisms may only support some services in conjunction with others. 940 Both gss_init_sec_context and gss_accept_sec_context inform the 941 applications which services will be available from the context when 942 the establishment phase is complete, via the ret_flags output 944 Wray [Page 18 of 101] 945 parameter. In general, if the security mechanism is capable of 946 providing a requested service, it should do so, even if additional 947 services must be enabled in order to provide the requested service. 948 If the mechanism is incapable of providing a requested service, it 949 should proceed without the service, leaving the application to abort 950 the context establishment process if it considers the requested 951 service to be mandatory. 953 Some mechanisms may specify that support for some services is 954 optional, and that implementors of the mechanism need not provide it. 955 This is most commonly true of the confidentiality service, often 956 because of legal restrictions on the use of data-encryption, but may 957 apply to any of the services. Such mechanisms are required to send 958 at least one token from acceptor to initiator during context 959 establishment when the initiator indicates a desire to use such a 960 service, so that the initiating GSSAPI can correctly indicate whether 961 the service is supported by the acceptor's GSSAPI. 963 6.1. Delegation 965 The GSS-API allows delegation to be controlled by the initiating 966 application via a boolean parameter to gss_init_sec_context(), the 967 routine that establishes a security context. Some mechanisms do not 968 support delegation, and for such mechanisms attempts by an 969 application to enable delegation are ignored. 971 The acceptor of a security context for which the initiator enabled 972 delegation will receive (via the delegated_cred_handle parameter of 973 gss_accept_sec_context) a credential handle that contains the 974 delegated identity, and this credential handle may be used to 975 initiate subsequent GSSAPI security contexts as an agent or delegate 976 of the initiator. If the original initiator's identity is "A" and 977 the delegate's identity is "B", then, depending on the underlying 978 mechanism, the identity embodied by the delegated credential may be 979 either "A" or "B acting for A". 981 For many mechanisms that support delegation, a simple boolean does 982 not provide enough control. Examples of additional aspects of 983 delegation control that a mechanism might provide to an application 984 are duration of delegation, network addresses from which delegation 985 is valid, and constraints on the tasks that may be performed by a 986 delegate. Such controls are presently outside the scope of the 987 GSS-API. GSS-API implementations supporting mechanisms offering 988 additional controls should provide extension routines that allow 989 these controls to be exercised (perhaps by modifying the initiator's 990 GSS-API credential prior to its use in establishing a context). 991 However, the simple delegation control provided by GSS-API should 992 always be able to over-ride other mechanism-specific delegation 993 controls - If the application instructs gss_init_sec_context() that 994 delegation is not desired, then the implementation must not permit 995 delegation to occur. This is an exception to the general rule that a 996 mechanism may enable services even if they are not requested - 997 delegation may only be provided at the explicit request of the 998 application. 1000 Wray [Page 19 of 101] 1001 6.2. Mutual authentication 1003 Usually, a context acceptor will require that a context initiator 1004 authenticate itself so that the acceptor may make an access-control 1005 decision prior to performing a service for the initiator. In some 1006 cases, the initiator may also request that the acceptor authenticate 1007 itself. GSS-API allows the initiating application to request this 1008 mutual authentication service by setting a flag when calling 1009 gss_init_sec_context. 1011 The initiating application is informed as to whether or not the 1012 context acceptor has authenticated itself. Note that some mechanisms 1013 may not support mutual authentication, and other mechanisms may 1014 always perform mutual authentication, whether or not the initiating 1015 application requests it. In particular, mutual authentication my be 1016 required by some mechanisms in order to support replay or 1017 out-of-sequence message detection, and for such mechanisms a request 1018 for either of these services will automatically enable mutual 1019 authentication. 1021 6.3. Replay and out-of-sequence detection 1023 The GSS-API may provide detection of mis-ordered message once a 1024 security context has been established. Protection may be applied to 1025 messages by either application, by calling either gss_get_mic or 1026 gss_wrap, and verified by the peer application by calling 1027 gss_verify_mic or gss_unwrap. 1029 gss_get_mic calculates a cryptographic MIC over an application 1030 message, and returns that MIC in a token. The application should 1031 pass both the token and the message to the peer application, which 1032 presents them to gss_verify_mic. 1034 gss_wrap calculates a cryptographic MIC of an application message, 1035 and places both the MIC and the message inside a single token. The 1036 Application should pass the token to the peer application, which 1037 presents it to gss_unwrap to extract the message and verify the MIC. 1039 Either pair of routines may be capable of detecting out-of-sequence 1040 message delivery, or duplication of messages. Details of such 1041 mis-ordered messages are indicated through supplementary status bits 1042 in the major status code returned by gss_verify_mic or gss_unwrap. 1043 The relevant supplementary bits are: 1045 GSS_S_DUPLICATE_TOKEN - The token is a duplicate of one that has 1046 already been received and processed. Only 1047 contexts that claim to provide replay detection 1048 may set this bit. 1049 GSS_S_OLD_TOKEN - The token is too old to determine whether or 1050 not it is a duplicate. Contexts supporting 1051 out-of-sequence detection but not replay 1052 detection should always set this bit if 1053 GSS_S_UNSEQ_TOKEN is set; contexts that support 1054 replay detection should only set this bit if the 1056 Wray [Page 20 of 101] 1057 token is so old that it cannot be checked for 1058 duplication. 1059 GSS_S_UNSEQ_TOKEN - A later token has already been processed. 1060 GSS_S_GAP_TOKEN - An earlier token has not yet been received. 1062 A mechanism need not maintain a list of all tokens that have been 1063 processed in order to support these status codes. A typical 1064 mechanism might retain information about only the most recent "N" 1065 tokens processed, allowing it to distinguish duplicates and missing 1066 tokens within the most recent "N" messages; the receipt of a token 1067 older than the most recent "N" would result in a GSS_S_OLD_TOKEN 1068 status. 1070 6.4. Anonymous Authentication 1072 In certain situations, an application may wish to initiate the 1073 authentication process to authenticate a peer, without revealing its 1074 own identity. As an example, consider an application providing 1075 access to a database containing medical information, and offering 1076 unrestricted access to the service. A client of such a service might 1077 wish to authenticate the service (in order to establish trust in any 1078 information retrieved from it), but might not wish the service to be 1079 able to obtain the client's identity (perhaps due to privacy concerns 1080 about the specific inquiries, or perhaps simply to avoid being placed 1081 on mailing-lists). 1083 In normal use of the GSS-API, the initiator's identity is made 1084 available to the acceptor as a result of the context establishment 1085 process. However, context initiators may request that their identity 1086 not be revealed to the context acceptor. Many mechanisms do not 1087 support anonymous authentication, and for such mechanisms the request 1088 will not be honored. An authentication token will be still be 1089 generated, but the application is always informed if a requested 1090 service is unavailable, and has the option to abort context 1091 establishment if anonymity is valued above the other security 1092 services that would require a context to be established. 1094 In addition to informing the application that a context is 1095 established anonymously (via the ret_flags outputs from 1096 gss_init_sec_context and gss_accept_sec_context), the optional 1097 src_name output from gss_accept_sec_context and gss_inquire_context 1098 will, for such contexts, return a reserved internal-form name, 1099 defined by the implementation. 1101 When presented to gss_display_name, this reserved internal-form name 1102 will result in a printable name that is syntactically distinguishable 1103 from any valid principal name supported by the implementation, 1104 associated with a name-type object identifier with the value 1105 GSS_C_NT_ANONYMOUS, whose value us given in Appendix A. The 1106 printable form of an anonymous name should be chosen such that it 1107 implies anonymity, since this name may appear in, for example, audit 1108 logs. For example, the string "" might be a good choice, 1109 if no valid printable names supported by the implementation can begin 1110 with "<" and end with ">". 1112 Wray [Page 21 of 101] 1113 6.5. Confidentiality 1115 If a context supports the confidentiality service, gss_wrap may be 1116 used to encrypt application messages. Messages are selectively 1117 encrypted, under the control of the conf_req_flag input parameter to 1118 gss_wrap. 1120 6.6. Inter-process context transfer 1122 GSSAPI V2 provides routines (gss_export_sec_context and 1123 gss_import_sec_context) which allow a security context to be 1124 transferred between processes on a single machine. The most common 1125 use for such a feature is a client-server design where the server is 1126 implemented as a single process that accepts incoming security 1127 contexts, which then launches child processes to deal with the data 1128 on these contexts. In such a design, the child processes must have 1129 access to the security context data structure created within the 1130 parent by its call to gss_accept_sec_context so that they can use 1131 per-message protection services and delete the security context when 1132 the communication session ends. 1134 Since the security context data structure is expected to contain 1135 sequencing information, it is impractical in general to share a 1136 context between processes. Thus GSSAPI provides a call 1137 (gss_export_sec_context) that the process which currently owns the 1138 context can call to declare that it has no intention to use the 1139 context subsequently, and to create an inter-process token containing 1140 information needed by the adopting process to successfully import the 1141 context. After successful completion of gss_export_sec_context, the 1142 original security context is made inaccessible to the calling process 1143 by GSSAPI, and any context handles referring to this context are no 1144 longer valid. The originating process transfers the inter-process 1145 token to the adopting process, which passes it to 1146 gss_import_sec_context, and a fresh gss_ctx_id_t is created such that 1147 it is functionally identical to the original context. 1149 The inter-process token may contain sensitive data from the original 1150 security context (including cryptographic keys). Applications using 1151 inter-process tokens to transfer security contexts must take 1152 appropriate steps to protect these tokens in transit. 1154 Implementations are not required to support the inter-process 1155 transfer of security contexts. The ability to transfer a security 1156 context is indicated when the context is created, by 1157 gss_init_sec_context or gss_accept_sec_context setting the 1158 GSS_C_TRANS_FLAG bit in their ret_flags parameter. 1160 6.7. The use of incomplete contexts 1162 Some mechanisms may allow the per-message services to be used before 1163 the context establishment process is complete. For example, a 1165 Wray [Page 22 of 101] 1166 mechanism may include sufficient information in its initial 1167 context-level token for the context acceptor to immediately decode 1168 messages protected with gss_wrap or gss_get_mic. For such a 1169 mechanism, the initiating application need not wait until subsequent 1170 context-level tokens have been sent and received before invoking the 1171 per-message protection services. 1173 The ability of a context to provide per-message services in advance 1174 of complete context establishment is indicated by the setting of the 1175 GSS_C_PROT_READY_FLAG bit in the ret_flags parameter from 1176 gss_init_sec_context and gss_accept_sec_context. Applications wishing 1177 to use per-message protection services on partially-established 1178 contexts should check this flag before attempting to invoke gss_wrap 1179 or gss_get_mic. 1181 7. GSS-API routine descriptions 1183 In addition to the explicit major status codes documented here, the 1184 code GSS_S_FAILURE may be returned by any routine, indicating an 1185 implementation-specific or mechanism-specific error condition, 1186 further details of which are reported via the minor_status parameter. 1188 Wray [Page 23 of 101] 1189 7.1. gss_accept_sec_context 1191 OM_uint32 gss_accept_sec_context ( 1192 OM_uint32 *minor_status, 1193 gss_ctx_id_t *context_handle, 1194 const gss_cred_id_t acceptor_cred_handle, 1195 const gss_buffer_t input_token_buffer, 1196 const gss_channel_bindings_t input_chan_bindings, 1197 const gss_name_t *src_name, 1198 gss_OID *mech_type, 1199 gss_buffer_t output_token, 1200 OM_uint32 *ret_flags, 1201 OM_uint32 *time_rec, 1202 gss_cred_id_t *delegated_cred_handle) 1204 Purpose: 1206 Allows a remotely initiated security context between the application 1207 and a remote peer to be established. The routine may return a 1208 output_token which should be transferred to the peer application, 1209 where the peer application will present it to gss_init_sec_context. 1210 If no token need be sent, gss_accept_sec_context will indicate this 1211 by setting the length field of the output_token argument to zero. To 1212 complete the context establishment, one or more reply tokens may be 1213 required from the peer application; if so, gss_accept_sec_context 1214 will return a status flag of GSS_S_CONTINUE_NEEDED, in which case it 1215 should be called again when the reply token is received from the peer 1216 application, passing the token to gss_accept_sec_context via the 1217 input_token parameters. 1219 Portable applications should be constructed to use the token length 1220 and return status to determine whether a token needs to be sent or 1221 waited for. Thus a typical portable caller should always invoke 1222 gss_accept_sec_context within a loop: 1224 gss_ctx_id_t context_hdl = GSS_C_NO_CONTEXT; 1226 do { 1227 receive_token_from_peer(input_token); 1228 maj_stat = gss_accept_sec_context(&min_stat, 1229 &context_hdl, 1230 cred_hdl, 1231 input_token, 1232 input_bindings, 1233 &client_name, 1234 &mech_type, 1235 output_token, 1236 &ret_flags, 1237 &time_rec, 1238 &deleg_cred); 1239 if (GSS_ERROR(maj_stat)) { 1240 report_error(maj_stat, min_stat); 1241 }; 1242 if (output_token->length != 0) { 1243 send_token_to_peer(output_token); 1245 Wray [Page 24 of 101] 1246 gss_release_buffer(&min_stat, output_token); 1247 }; 1248 if (GSS_ERROR(maj_stat)) { 1249 if (context_hdl != GSS_C_NO_CONTEXT) 1250 gss_delete_sec_context(&min_stat, 1251 &context_hdl, 1252 GSS_C_NO_BUFFER); 1253 break; 1254 }; 1255 } while (maj_stat & GSS_S_CONTINUE_NEEDED); 1257 Whenever the routine returns a major status that includes the value 1258 GSS_S_CONTINUE_NEEDED, the context is not fully established and the 1259 following restrictions apply to the output parameters: 1261 The value returned via the time_rec parameter is undefined 1262 Unless the accompanying ret_flags parameter contains the bit 1263 GSS_C_PROT_READY_FLAG, indicating that per-message services may be 1264 applied in advance of a successful completion status, the value 1265 returned via the mech_type parameter may be undefined until the 1266 routine returns a major status value of GSS_S_COMPLETE. 1268 The values of the GSS_C_DELEG_FLAG, 1269 GSS_C_MUTUAL_FLAG,GSS_C_REPLAY_FLAG, GSS_C_SEQUENCE_FLAG, 1270 GSS_C_CONF_FLAG,GSS_C_INTEG_FLAG and GSS_C_ANON_FLAG bits returned 1271 via the ret_flags parameter should contain the values that the 1272 implementation expects would be valid if context establishment were 1273 to succeed. 1275 The values of the GSS_C_PROT_READY_FLAG and GSS_C_TRANS_FLAG bits 1276 within ret_flags should indicate the actual state at the time 1277 gss_accept_sec_context returns, whether or not the context is fully 1278 established. 1280 Although this requires that GSSAPI implementations set the 1281 GSS_C_PROT_READY_FLAG in the final ret_flags returned to a caller 1282 (i.e. when accompanied by a GSS_S_COMPLETE status code), applications 1283 should not rely on this behavior as the flag was not defined in 1284 Version 1 of the GSSAPI. Instead, applications should be prepared to 1285 use per-message services after a successful context establishment, 1286 according to the GSS_C_INTEG_FLAG and GSS_C_CONF_FLAG values. 1288 All other bits within the ret_flags argument should be set to zero. 1289 While the routine returns GSS_S_CONTINUE_NEEDED, the values returned 1290 via the ret_flags argument indicate the services that the 1291 implementation expects to be available from the established context. 1293 If the initial call of gss_accept_sec_context() fails, the 1294 implementation should not create a context object, and should leave 1295 the value of the context_handle parameter set to GSS_C_NO_CONTEXT to 1296 indicate this. In the event of a failure on a subsequent call, the 1297 implementation is permitted to delete the "half-built" security 1298 context (in which case it should set the context_handle parameter to 1299 GSS_C_NO_CONTEXT), but the preferred behavior is to leave the 1301 Wray [Page 25 of 101] 1302 security context (and the context_handle parameter) untouched for the 1303 application to delete (using gss_delete_sec_context). 1305 During context establishment, the informational status bits 1306 GSS_S_OLD_TOKEN and GSS_S_DUPLICATE_TOKEN indicate fatal errors, and 1307 GSSAPI mechanisms should always return them in association with a 1308 routine error of GSS_S_FAILURE. This requirement for pairing did not 1309 exist in version 1 of the GSSAPI specification, so applications that 1310 wish to run over version 1 implementations must special-case these 1311 codes. 1313 Parameters: 1315 context_handle gss_ctx_id_t, read/modify 1316 context handle for new context. Supply 1317 GSS_C_NO_CONTEXT for first call; use value 1318 returned in subsequent calls. Once 1319 gss_accept_sec_context() has returned a 1320 value via this parameter, resources have 1321 been assigned to the corresponding context, 1322 and must be freed by the application after 1323 use with a call to gss_delete_sec_context(). 1325 acceptor_cred_handle gss_cred_id_t, read 1326 Credential handle claimed by context 1327 acceptor. Specify GSS_C_NO_CREDENTIAL to 1328 accept the context as a default principal. 1329 If GSS_C_NO_CREDENTIAL is specified, but 1330 no default acceptor principal is defined, 1331 GSS_S_NO_CRED will be returned. 1333 input_token_buffer buffer, opaque, read 1334 token obtained from remote application. 1336 input_chan_bindings channel bindings, read, optional 1337 Application-specified bindings. Allows 1338 application to securely bind channel 1339 identification information to the security 1340 context. If channel bindings are not 1341 used, specify GSS_C_NO_CHANNEL_BINDINGS. 1343 src_name gss_name_t, modify, optional 1344 Authenticated name of context initiator. 1345 After use, this name should be deallocated 1346 by passing it to gss_release_name(). If 1347 not required, specify NULL. 1349 mech_type Object ID, modify, optional 1350 Security mechanism used. The returned 1351 OID value will be a pointer into static 1352 storage, and should be treated as read-only 1353 by the caller (in particular, it does not 1354 need to be freed). If not required, specify 1355 NULL. 1357 Wray [Page 26 of 101] 1358 output_token buffer, opaque, modify 1359 Token to be passed to peer application. If 1360 the length field of the returned token 1361 buffer is 0, then no token need be passed 1362 to the peer application. If a non-zero 1363 length field is returned, the associated 1364 storage must be freed after use by the 1365 application with a call to 1366 gss_release_buffer(). 1368 ret_flags bit-mask, modify, optional 1369 Contains various independent flags, each of 1370 which indicates that the context supports a 1371 specific service option. If not needed, 1372 specify NULL. Symbolic names are 1373 provided for each flag, and the symbolic 1374 names corresponding to the required flags 1375 should be logically-ANDed with the ret_flags 1376 value to test whether a given option is 1377 supported by the context. The flags are: 1378 GSS_C_DELEG_FLAG 1379 True - Delegated credentials are available 1380 via the delegated_cred_handle 1381 parameter 1382 False - No credentials were delegated 1383 GSS_C_MUTUAL_FLAG 1384 True - Remote peer asked for mutual 1385 authentication 1386 False - Remote peer did not ask for mutual 1387 authentication 1388 GSS_C_REPLAY_FLAG 1389 True - replay of protected messages 1390 will be detected 1391 False - replayed messages will not be 1392 detected 1393 GSS_C_SEQUENCE_FLAG 1394 True - out-of-sequence protected 1395 messages will be detected 1396 False - out-of-sequence messages will not 1397 be detected 1398 GSS_C_CONF_FLAG 1399 True - Confidentiality service may be 1400 invoked by calling the gss_wrap 1401 routine 1402 False - No confidentiality service (via 1403 gss_wrap) available. gss_wrap will 1404 provide message encapsulation, 1405 data-origin authentication and 1406 integrity services only. 1407 GSS_C_INTEG_FLAG 1408 True - Integrity service may be invoked by 1409 calling either gss_get_mic or 1410 gss_wrap routines. 1411 False - Per-message integrity service 1413 Wray [Page 27 of 101] 1414 unavailable. 1415 GSS_C_ANON_FLAG 1416 True - The initiator does not wish to 1417 be authenticated; the src_name 1418 parameter (if requested) contains 1419 an anonymous internal name. 1420 False - The initiator has been 1421 authenticated normally. 1422 GSS_C_PROT_READY_FLAG 1423 True - Protection services (as specified 1424 by the states of the GSS_C_CONF_FLAG 1425 and GSS_C_INTEG_FLAG) are available 1426 if the accompanying major status 1427 return value is either GSS_S_COMPLETE 1428 or GSS_S_CONTINUE_NEEDED. 1429 False - Protection services (as specified 1430 by the states of the GSS_C_CONF_FLAG 1431 and GSS_C_INTEG_FLAG) are available 1432 only if the accompanying major status 1433 return value is GSS_S_COMPLETE. 1434 GSS_C_TRANS_FLAG 1435 True - The resultant security context may 1436 be transferred to other processes via 1437 a call to gss_export_sec_context(). 1438 False - The security context is not 1439 transferrable. 1440 All other bits should be set to zero. 1442 time_rec Integer, modify, optional 1443 number of seconds for which the context 1444 will remain valid. Specify NULL if 1445 not required. 1447 delegated_cred_handle 1448 gss_cred_id_t, modify, optional 1449 credential handle for credentials received 1450 from context initiator. Only valid if 1451 deleg_flag in ret_flags is true, in which 1452 case an explicit credential handle 1453 (i.e. not GSS_C_NO_CREDENTIAL) will be 1454 returned; if deleg_flag is false, 1455 gss_accept_context() will set this parameter 1456 to GSS_C_NO_CREDENTIAL. If a credential 1457 handle is returned, the associated resources 1458 must be released by the application after use 1459 with a call to gss_release_cred(). Specify 1460 NULL if not required. 1462 minor_status Integer, modify 1463 Mechanism specific status code. 1465 Function value: GSS status code 1467 GSS_S_COMPLETE Successful completion 1469 Wray [Page 28 of 101] 1470 GSS_S_CONTINUE_NEEDED Indicates that a token from the peer 1471 application is required to complete the 1472 context, and that gss_accept_sec_context 1473 must be called again with that token. 1475 GSS_S_DEFECTIVE_TOKEN Indicates that consistency checks performed 1476 on the input_token failed. 1478 GSS_S_DEFECTIVE_CREDENTIAL Indicates that consistency checks 1479 performed on the credential failed. 1481 GSS_S_NO_CRED The supplied credentials were not valid for 1482 context acceptance, or the credential handle 1483 did not reference any credentials. 1485 GSS_S_CREDENTIALS_EXPIRED The referenced credentials have expired. 1487 GSS_S_BAD_BINDINGS The input_token contains different channel 1488 bindings to those specified via the 1489 input_chan_bindings parameter. 1491 GSS_S_NO_CONTEXT Indicates that the supplied context handle did 1492 not refer to a valid context. 1494 GSS_S_BAD_SIG The input_token contains an invalid MIC. 1496 GSS_S_OLD_TOKEN The input_token was too old. This is a fatal 1497 error during context establishment. 1499 GSS_S_DUPLICATE_TOKEN The input_token is valid, but is a duplicate 1500 of a token already processed. This is a 1501 fatal error during context establishment. 1503 GSS_S_BAD_MECH The received token specified a mechanism that is 1504 not supported by the implementation or the 1505 provided credential. 1507 Wray [Page 29 of 101] 1508 7.2. gss_acquire_cred 1510 OM_uint32 gss_acquire_cred ( 1511 OM_uint32 *minor_status, 1512 const gss_name_t desired_name, 1513 OM_uint32 time_req, 1514 const gss_OID_set desired_mechs, 1515 gss_cred_usage_t cred_usage, 1516 gss_cred_id_t *output_cred_handle, 1517 gss_OID_set *actual_mechs, 1518 OM_uint32 *time_rec) 1520 Purpose: 1522 Allows an application to acquire a handle for a pre-existing 1523 credential by name. GSS-API implementations must impose a local 1524 access-control policy on callers of this routine to prevent 1525 unauthorized callers from acquiring credentials to which they are not 1526 entitled. This routine is not intended to provide a "login to the 1527 network" function, as such a function would involve the creation of 1528 new credentials rather than merely acquiring a handle to existing 1529 credentials. Such functions, if required, should be defined in 1530 implementation-specific extensions to the API. 1532 If desired_name is GSS_C_NO_NAME, the call is interpreted as a 1533 request for a credential handle that will invoke default behavior 1534 when passed to gss_init_sec_context() (if cred_usage is 1535 GSS_C_INITIATE or GSS_C_BOTH) or gss_accept_sec_context() (if 1536 cred_usage is GSS_C_ACCEPT or GSS_C_BOTH). 1538 Mechanisms should honor the desired_mechs parameter, and return a 1539 credential that is suitable to use only with the requested 1540 mechanisms. An exception to this is the case where one underlying 1541 credential element can be shared by multiple mechanisms; in this case 1542 it is permissible for an implementation to indicate all mechanisms 1543 with which the credential element may be used. One reason for this 1544 recommendation is to allow the application to specify an empty set of 1545 desired mechanisms in order to create an "empty" credential, which 1546 may then be tailored as desired with gss_add_cred(). 1548 This routine is expected to be used primarily by context acceptors, 1549 since implementations are likely to provide mechanism-specific ways 1550 of obtaining GSS-API initiator credentials from the system login 1551 process. Some implementations may therefore not support the 1552 acquisition of GSS_C_INITIATE or GSS_C_BOTH credentials via 1553 gss_acquire_cred for any name other than GSS_C_NO_NAME, or a name 1554 produced by applying either gss_inquire_cred to a valid credential, 1555 or gss_inquire_context to an active context. 1557 If credential acquisition is time-consuming for a mechanism, the 1558 mechanism may choose to delay the actual acquisition until the 1559 credential is required (e.g. by gss_init_sec_context or 1560 gss_accept_sec_context). Such mechanism-specific implementation 1561 decisions should be invisible to the calling application; thus a call 1563 Wray [Page 30 of 101] 1564 of gss_inquire_cred immediately following the call of 1565 gss_acquire_cred must return valid credential data, and may therefore 1566 incur the overhead of a deferred credential acquisition. 1568 Parameters: 1570 desired_name gss_name_t, read 1571 Name of principal whose credential 1572 should be acquired 1574 time_req Integer, read, optional 1575 number of seconds that credentials 1576 should remain valid. Specify GSS_C_INDEFINITE 1577 to request that the credentials have the maximum 1578 permitted lifetime. 1580 desired_mechs Set of Object IDs, read, optional 1581 set of underlying security mechanisms that 1582 may be used. GSS_C_NO_OID_SET may be used 1583 to obtain an implementation-specific default. 1585 cred_usage gss_cred_usage_t, read 1586 GSS_C_BOTH - Credentials may be used 1587 either to initiate or accept 1588 security contexts. 1589 GSS_C_INITIATE - Credentials will only be 1590 used to initiate security contexts. 1591 GSS_C_ACCEPT - Credentials will only be used to 1592 accept security contexts. 1594 output_cred_handle gss_cred_id_t, modify 1595 The returned credential handle. Resources 1596 associated with this credential handle must 1597 be released by the application after use 1598 with a call to gss_release_cred(). 1600 actual_mechs Set of Object IDs, modify, optional 1601 The set of mechanisms for which the 1602 credential is valid. Storage associated 1603 with the returned OID-set must be released by 1604 the application after use with a call to 1605 gss_release_oid_set(). Specify NULL if not 1606 required. 1608 time_rec Integer, modify, optional 1609 Actual number of seconds for which the 1610 returned credentials will remain valid. If the 1611 implementation does not support expiration of 1612 credentials, the value GSS_C_INDEFINITE will 1613 be returned. Specify NULL if not required 1615 minor_status Integer, modify 1616 Mechanism specific status code. 1618 Function value: GSS status code 1620 Wray [Page 31 of 101] 1621 GSS_S_COMPLETE Successful completion 1623 GSS_S_BAD_MECH Unavailable mechanism requested 1625 GSS_S_BAD_NAMETYPE Type contained within desired_name parameter 1626 is not supported 1628 GSS_S_BAD_NAME Value supplied for desired_name parameter is ill 1629 formed. 1631 GSS_S_CREDENTIALS_EXPIRED The credentials could not be acquired 1632 Because they have expired. 1634 GSS_S_NO_CRED No credentials were found for the specified name. 1636 Wray [Page 32 of 101] 1637 7.3. gss_add_cred 1639 OM_uint32 gss_add_cred ( 1640 OM_uint32 *minor_status, 1641 const gss_cred_id_t input_cred_handle, 1642 const gss_name_t desired_name, 1643 const gss_OID desired_mech, 1644 gss_cred_usage_t cred_usage, 1645 OM_uint32 initiator_time_req, 1646 OM_uint32 acceptor_time_req, 1647 gss_cred_id_t *output_cred_handle, 1648 gss_OID_set *actual_mechs, 1649 OM_uint32 *initiator_time_rec, 1650 OM_uint32 *acceptor_time_rec) 1652 Purpose: 1654 Adds a credential-element to a credential. The credential-element is 1655 identified by the name of the principal to which it refers. GSSAPI 1656 implementations must impose a local access-control policy on callers 1657 of this routine to prevent unauthorized callers from acquiring 1658 credential-elements to which they are not entitled. This routine is 1659 not intended to provide a "login to the network" function, as such a 1660 function would involve the creation of new mechanism-specific 1661 authentication data, rather than merely acquiring a GSSAPI handle to 1662 existing data. Such functions, if required, should be defined in 1663 implementation-specific extensions to the API. 1665 If desired_name is GSS_C_NO_NAME, the call is interpreted as a 1666 request to add a credential element that will invoke default behavior 1667 when passed to gss_init_sec_context() (if cred_usage is 1668 GSS_C_INITIATE or GSS_C_BOTH) or gss_accept_sec_context() (if 1669 cred_usage is GSS_C_ACCEPT or GSS_C_BOTH). 1671 This routine is expected to be used primarily by context acceptors, 1672 since implementations are likely to provide mechanism-specific ways 1673 of obtaining GSS-API initiator credentials from the system login 1674 process. Some implementations may therefore not support the 1675 acquisition of GSS_C_INITIATE or GSS_C_BOTH credentials via 1676 gss_acquire_cred for any name other than GSS_C_NO_NAME, or a name 1677 produced by applying either gss_inquire_cred to a valid credential, 1678 or gss_inquire_context to an active context. 1680 If credential acquisition is time-consuming for a mechanism, the 1681 mechanism may choose to delay the actual acquisition until the 1682 credential is required (e.g. by gss_init_sec_context or 1683 gss_accept_sec_context). Such mechanism-specific implementation 1684 decisions should be invisible to the calling application; thus a call 1685 of gss_inquire_cred immediately following the call of gss_add_cred 1686 must return valid credential data, and may therefore incur the 1687 overhead of a deferred credential acquisition. 1689 This routine can be used to either compose a new credential 1690 containing all credential-elements of the original in addition to the 1691 newly-acquire credential-element, or to add the new 1693 Wray [Page 33 of 101] 1694 credential-element to an existing credential. If NULL is specified 1695 for the output_cred_handle parameter argument, the new 1696 credential-element will be added to the credential identified by 1697 input_cred_handle; if a valid pointer is specified for the 1698 output_cred_handle parameter, a new credential handle will be 1699 created. 1701 If GSS_C_NO_CREDENTIAL is specified as the input_cred_handle, 1702 gss_add_cred will compose a credential (and set the 1703 output_cred_handle parameter accordingly) based on default behavior. 1704 That is, the call will have the same effect as if the application had 1705 first made a call to gss_acquire_cred(), specifying the same usage 1706 and passing GSS_C_NO_NAME as the desired_name parameter to obtain an 1707 explicit credential handle embodying default behavior, passed this 1708 credential handle to gss_add_cred(), and finally called 1709 gss_release_cred() on the first credential handle. 1711 If GSS_C_NO_CREDENTIAL is specified as the input_cred_handle 1712 parameter, a non-NULL output_cred_handle must be supplied. 1714 Parameters: 1716 minor_status Integer, modify 1717 Mechanism specific status code. 1719 input_cred_handle gss_cred_id_t, read, optional 1720 The credential to which a credential-element 1721 will be added. If GSS_C_NO_CREDENTIAL is 1722 specified, the routine will compose the new 1723 credential based on default behavior (see 1724 description above). Note that, while the 1725 credential-handle is not modified by 1726 gss_add_cred(), the underlying credential 1727 will be modified if output_credential_handle 1728 is NULL. 1730 desired_name gss_name_t, read. 1731 Name of principal whose credential 1732 should be acquired. 1734 desired_mech Object ID, read 1735 Underlying security mechanism with which the 1736 credential may be used. 1738 cred_usage gss_cred_usage_t, read 1739 GSS_C_BOTH - Credential may be used 1740 either to initiate or accept 1741 security contexts. 1742 GSS_C_INITIATE - Credential will only be 1743 used to initiate security 1744 contexts. 1745 GSS_C_ACCEPT - Credential will only be used to 1746 accept security contexts. 1748 initiator_time_req Integer, read, optional 1750 Wray [Page 34 of 101] 1751 number of seconds that the credential 1752 should remain valid for initiating security 1753 contexts. This argument is ignored if the 1754 composed credentials are of type GSS_C_ACCEPT. 1755 Specify GSS_C_INDEFINITE to request that the 1756 credentials have the maximum permitted 1757 initiator lifetime. 1759 acceptor_time_req Integer, read, optional 1760 number of seconds that the credential 1761 should remain valid for accepting security 1762 contexts. This argument is ignored if the 1763 composed credentials are of type GSS_C_INITIATE. 1764 Specify GSS_C_INDEFINITE to request that the 1765 credentials have the maximum permitted initiator 1766 lifetime. 1768 output_cred_handle gss_cred_id_t, modify, optional 1769 The returned credential handle, containing 1770 the new credential-element and all the 1771 credential-elements from input_cred_handle. 1772 If a valid pointer to a gss_cred_id_t is 1773 supplied for this parameter, gss_add_cred 1774 creates a new credential handle containing all 1775 credential-elements from the input_cred_handle 1776 and the newly acquired credential-element; if 1777 NULL is specified for this parameter, the newly 1778 acquired credential-element will be added 1779 to the credential identified by input_cred_handle. 1781 The resources associated with any credential 1782 handle returned via this parameter must be 1783 released by the application after use with a 1784 call to gss_release_cred(). 1786 actual_mechs Set of Object IDs, modify, optional 1787 The complete set of mechanisms for which 1788 the new credential is valid. Storage for 1789 the returned OID-set must be freed by the 1790 application after use with a call to 1791 gss_release_oid_set(). Specify NULL if 1792 not required. 1794 initiator_time_rec Integer, modify, optional 1795 Actual number of seconds for which the 1796 returned credentials will remain valid for 1797 initiating contexts using the specified 1798 mechanism. If the implementation or mechanism 1799 does not support expiration of credentials, the 1800 value GSS_C_INDEFINITE will be returned. Specify 1801 NULL if not required 1803 acceptor_time_rec Integer, modify, optional 1804 Actual number of seconds for which the 1805 returned credentials will remain valid for 1807 Wray [Page 35 of 101] 1808 accepting security contexts using the specified 1809 mechanism. If the implementation or mechanism 1810 does not support expiration of credentials, the 1811 value GSS_C_INDEFINITE will be returned. Specify 1812 NULL if not required 1814 Function value: GSS status code 1816 GSS_S_COMPLETE Successful completion 1818 GSS_S_BAD_MECH Unavailable mechanism requested 1820 GSS_S_BAD_NAMETYPE Type contained within desired_name parameter 1821 is not supported 1823 GSS_S_BAD_NAME Value supplied for desired_name parameter is 1824 ill-formed. 1826 GSS_S_DUPLICATE_ELEMENT The credential already contains an element 1827 for the requested mechanism with overlapping 1828 usage and validity period. 1830 GSS_S_CREDENTIALS_EXPIRED The required credentials could not be 1831 added because they have expired. 1833 GSS_S_NO_CRED No credentials were found for the specified name. 1835 Wray [Page 36 of 101] 1836 7.4. gss_add_oid_set_member 1838 OM_uint32 gss_add_oid_set_member ( 1839 OM_uint32 *minor_status, 1840 const gss_OID member_oid, 1841 gss_OID_set *oid_set) 1843 Purpose: 1845 Add an Object Identifier to an Object Identifier set. This routine 1846 is intended for use in conjunction with gss_create_empty_oid_set when 1847 constructing a set of mechanism OIDs for input to gss_acquire_cred. 1848 The oid_set parameter must refer to an OID-set that was created by 1849 GSSAPI (e.g. a set returned by gss_create_empty_oid_set()). GSSAPI 1850 creates a copy of the member_oid and inserts this copy into the set, 1851 expanding the storage allocated to the OID-set's elements array if 1852 necessary. The routine may add the new member OID anywhere within 1853 the elements array, and implementations should verify that the new 1854 member_oid is not already contained within the elements array; if the 1855 member_oid is already present, the oid_set should remain unchanged. 1857 Parameters: 1859 minor_status Integer, modify 1860 Mechanism specific status code 1862 member_oid Object ID, read 1863 The object identifier to copied into 1864 the set. 1866 oid_set Set of Object ID, modify 1867 The set in which the object identifier 1868 should be inserted. 1870 Function value: GSS status code 1872 GSS_S_COMPLETE Successful completion 1874 Wray [Page 37 of 101] 1875 7.5. gss_canonicalize_name 1877 OM_uint32 gss_canonicalize_name ( 1878 OM_uint32 *minor_status, 1879 const gss_name_t input_name, 1880 const gss_OID mech_type, 1881 gss_name_t *output_name) 1883 Purpose: 1885 Generate a canonical mechanism name (MN) from an arbitrary internal 1886 name. The mechanism name is the name that would be returned to a 1887 context acceptor on successful authentication of a context where the 1888 initiator used the input_name in a successful call to 1889 gss_acquire_cred, specifying an OID set containing as its 1890 only member, followed by a call to gss_init_sec_context, specifying 1891 as the authentication mechanism. 1893 Parameters: 1895 minor_status Integer, modify 1896 Mechanism specific status code 1898 input_name gss_name_t, read 1899 The name for which a canonical form is 1900 desired 1902 mech_type Object ID, read 1903 The authentication mechanism for which the 1904 canonical form of the name is desired. The 1905 desired mechanism must be specified explicitly; 1906 no default is provided. 1908 output_name gss_name_t, modify 1909 The resultant canonical name. Storage 1910 associated with this name must be freed by 1911 the application after use with a call to 1912 gss_release_name(). 1914 Function value: GSS status code 1916 GSS_S_COMPLETE Successful completion. 1918 GSS_S_BAD_MECH The identified mechanism is not supported. 1920 GSS_S_BAD_NAMETYPE The provided internal name contains no elements 1921 that could be processed by the specified 1922 mechanism. 1924 GSS_S_BAD_NAME The provided internal name was ill-formed. 1926 Wray [Page 38 of 101] 1927 7.6. gss_compare_name 1929 OM_uint32 gss_compare_name ( 1930 OM_uint32 *minor_status, 1931 const gss_name_t name1, 1932 const gss_name_t name2, 1933 int *name_equal) 1935 Purpose: 1937 Allows an application to compare two internal-form names to determine 1938 whether they refer to the same entity. 1940 If either name presented to gss_compare_name denotes an anonymous 1941 principal, the routines should indicate that the two names do not 1942 refer to the same identity. 1944 Parameters: 1946 minor_status Integer, modify 1947 Mechanism specific status code. 1949 name1 gss_name_t, read 1950 internal-form name 1952 name2 gss_name_t, read 1953 internal-form name 1955 name_equal boolean, modify 1956 non-zero - names refer to same entity 1957 zero - names refer to different entities 1958 (strictly, the names are not known 1959 to refer to the same identity). 1961 Function value: GSS status code 1963 GSS_S_COMPLETE Successful completion 1965 GSS_S_BAD_NAMETYPE The two names were of incomparable types. 1967 GSS_S_BAD_NAME One or both of name1 or name2 was ill-formed. 1969 Wray [Page 39 of 101] 1970 7.7. gss_context_time 1972 OM_uint32 gss_context_time ( 1973 OM_uint32 *minor_status, 1974 const gss_ctx_id_t context_handle, 1975 OM_uint32 *time_rec) 1977 Purpose: 1979 Determines the number of seconds for which the specified context will 1980 remain valid. 1982 Parameters: 1984 minor_status Integer, modify 1985 Implementation specific status code. 1987 context_handle gss_ctx_id_t, read 1988 Identifies the context to be interrogated. 1990 time_rec Integer, modify 1991 Number of seconds that the context will remain 1992 valid. If the context has already expired, 1993 zero will be returned. 1995 Function value: GSS status code 1997 GSS_S_COMPLETE Successful completion 1999 GSS_S_CONTEXT_EXPIRED The context has already expired 2001 GSS_S_NO_CONTEXT The context_handle parameter did not identify 2002 a valid context 2004 Wray [Page 40 of 101] 2005 7.8. gss_create_empty_oid_set 2007 OM_uint32 gss_create_empty_oid_set ( 2008 OM_uint32 *minor_status, 2009 gss_OID_set *oid_set) 2011 Purpose: 2013 Create an object-identifier set containing no object identifiers, to 2014 which members may be subsequently added using the 2015 gss_add_oid_set_member() routine. These routines are intended to be 2016 used to construct sets of mechanism object identifiers, for input to 2017 gss_acquire_cred. 2019 Parameters: 2021 minor_status Integer, modify 2022 Mechanism specific status code 2024 oid_set Set of Object IDs, modify 2025 The empty object identifier set. 2026 The routine will allocate the 2027 gss_OID_set_desc object, which the 2028 application must free after use with 2029 a call to gss_release_oid_set(). 2031 Function value: GSS status code 2033 GSS_S_COMPLETE Successful completion 2035 Wray [Page 41 of 101] 2036 7.9. gss_delete_sec_context 2038 OM_uint32 gss_delete_sec_context ( 2039 OM_uint32 *minor_status, 2040 gss_ctx_id_t *context_handle, 2041 gss_buffer_t output_token) 2043 Purpose: 2045 Delete a security context. gss_delete_sec_context will delete the 2046 local data structures associated with the specified security context, 2047 and may generate an output_token, which when passed to the peer 2048 gss_process_context_token will instruct it to do likewise. If no 2049 token is required by the mechanism, the GSS-API should set the length 2050 field of the output_token (if provided) to zero. No further security 2051 services may be obtained using the context specified by 2052 context_handle. 2054 In addition to deleting established security contexts, 2055 gss_delete_sec_context must also be able to delete "half-built" 2056 security contexts resulting from an incomplete sequence of 2057 gss_init_sec_context()/gss_accept_sec_context() calls. 2059 The output_token parameter is retained for compatibility with version 2060 1 of the GSS-API. It is recommended that both peer applications 2061 invoke gss_delete_sec_context passing the value GSS_C_NO_BUFFER for 2062 the output_token parameter, indicating that no token is required, and 2063 that gss_delete_sec_context should simply delete local context data 2064 structures. If the application does pass a valid buffer to 2065 gss_delete_sec_context, mechanisms are encouraged to return a 2066 zero-length token, indicating that no peer action is necessary, and 2067 that no token should be transferred by the application. 2069 Parameters: 2071 minor_status Integer, modify 2072 Mechanism specific status code. 2074 context_handle gss_ctx_id_t, modify 2075 context handle identifying context to delete. 2076 After deleting the context, the GSSAPI will set 2077 this context handle to GSS_C_NO_CONTEXT. 2079 output_token buffer, opaque, modify, optional 2080 token to be sent to remote application to 2081 instruct it to also delete the context. It 2082 is recommended that applications specify 2083 GSS_C_NO_BUFFER for this parameter, requesting 2084 local deletion only. If a buffer parameter is 2085 provided by the application, the mechanism may 2086 return a token in it; mechanisms that implement 2087 only local deletion should set the length field of 2088 this token to zero to indicate to the application 2089 that no token is to be sent to the peer. 2091 Wray [Page 42 of 101] 2092 Function value: GSS status code 2094 GSS_S_COMPLETE Successful completion 2096 GSS_S_NO_CONTEXT No valid context was supplied 2098 Wray [Page 43 of 101] 2099 7.10.gss_display_name 2101 OM_uint32 gss_display_name ( 2102 OM_uint32 *minor_status, 2103 const gss_name_t input_name, 2104 gss_buffer_t output_name_buffer, 2105 gss_OID *output_name_type) 2107 Purpose: 2109 Allows an application to obtain a textual representation of an opaque 2110 internal-form name for display purposes. The syntax of a printable 2111 name is defined by the GSS-API implementation. 2113 If input_name denotes an anonymous principal, the implementation 2114 should return the gss_OID value GSS_C_NT_ANONYMOUS as the 2115 output_name_type, and a textual name that is syntactically distinct 2116 from all valid supported printable names in output_name_buffer. 2118 If input_name was created by a call to gss_import_name, specifying 2119 GSS_C_NO_OID as the name-type, implementations that employ lazy 2120 conversion between name types may return GSS_C_NO_OID via the 2121 output_name_type parameter. 2123 Parameters: 2125 minor_status Integer, modify 2126 Mechanism specific status code. 2128 input_name gss_name_t, read 2129 name to be displayed 2131 output_name_buffer buffer, character-string, modify 2132 buffer to receive textual name string. 2133 The application must free storage associated 2134 with this name after use with a call to 2135 gss_release_buffer(). 2137 output_name_type Object ID, modify, optional 2138 The type of the returned name. The returned 2139 gss_OID will be a pointer into static storage, 2140 and should be treated as read-only by the caller 2141 (in particular, the application should not attempt 2142 to free it). Specify NULL if not required. 2144 Function value: GSS status code 2146 GSS_S_COMPLETE Successful completion 2148 GSS_S_BAD_NAME input_name was ill-formed 2150 Wray [Page 44 of 101] 2151 7.11.gss_display_status 2153 OM_uint32 gss_display_status ( 2154 OM_uint32 *minor_status, 2155 OM_uint32 status_value, 2156 int status_type, 2157 const gss_OID mech_type, 2158 OM_uint32 *message_context, 2159 gss_buffer_t status_string) 2161 Purpose: 2163 Allows an application to obtain a textual representation of a GSS-API 2164 status code, for display to the user or for logging purposes. Since 2165 some status values may indicate multiple conditions, applications may 2166 need to call gss_display_status multiple times, each call generating 2167 a single text string. The message_context parameter is used by 2168 gss_display_status to store state information about which error 2169 messages have already been extracted from a given status_value; 2170 message_context must be initialized to 0 by the application prior to 2171 the first call, and gss_display_status will return a non-zero value 2172 in this parameter if there are further messages to extract. 2174 The message_context parameter contains all state information required 2175 by gss_display_status in order to extract further messages from the 2176 status_value; even when a non-zero value is returned in this 2177 parameter, the application is not required to call gss_display_status 2178 again unless subsequent messages are desired. The following code 2179 extracts all messages from a given status code and prints them to 2180 stderr: 2182 OM_uint32 message_context; 2183 OM_uint32 status_code; 2184 OM_uint32 maj_status; 2185 OM_uint32 min_status; 2186 gss_buffer_desc status_string; 2188 ... 2190 message_context = 0; 2192 do { 2194 maj_status = gss_display_status ( 2195 &min_status, 2196 status_code, 2197 GSS_C_GSS_CODE, 2198 GSS_C_NO_OID, 2199 &message_context, 2200 &status_string) 2202 fprintf(stderr, 2203 "%.*s\n", 2204 (int)status_string.length, 2206 Wray [Page 45 of 101] 2207 (char *)status_string.value); 2209 gss_release_buffer(&min_status, &status_string); 2211 } while (message_context != 0); 2213 Parameters: 2215 minor_status Integer, modify 2216 Mechanism specific status code. 2218 status_value Integer, read 2219 Status value to be converted 2221 status_type Integer, read 2222 GSS_C_GSS_CODE - status_value is a GSS status 2223 code 2225 GSS_C_MECH_CODE - status_value is a mechanism 2226 status code 2228 mech_type Object ID, read, optional 2229 Underlying mechanism (used to interpret a 2230 minor status value) Supply GSS_C_NO_OID to 2231 obtain the system default. 2233 message_context Integer, read/modify 2234 Should be initialized to zero by the 2235 application prior to the first call. 2236 On return from gss_display_status(), 2237 a non-zero status_value parameter indicates 2238 that additional messages may be extracted 2239 from the status code via subsequent calls 2240 to gss_display_status(), passing the same 2241 status_value, status_type, mech_type, and 2242 message_context parameters. 2244 status_string buffer, character string, modify 2245 textual interpretation of the status_value. 2246 Storage associated with this parameter must 2247 be freed by the application after use with 2248 a call to gss_release_buffer(). 2250 Function value: GSS status code 2252 GSS_S_COMPLETE Successful completion 2254 GSS_S_BAD_MECH Indicates that translation in accordance with 2255 an unsupported mechanism type was requested 2257 GSS_S_BAD_STATUS The status value was not recognized, or the 2258 status type was neither GSS_C_GSS_CODE nor 2259 GSS_C_MECH_CODE. 2261 Wray [Page 46 of 101] 2262 7.12.gss_duplicate_name 2264 OM_uint32 gss_duplicate_name ( 2265 OM_uint32 *minor_status, 2266 const gss_name_t src_name, 2267 gss_name_t *dest_name) 2269 Purpose: 2271 Create an exact duplicate of the existing internal name src_name. 2272 The new dest_name will be independent of src_name (i.e. src_name and 2273 dest_name must both be released, and the release of one shall not 2274 affect the validity of the other). 2276 Parameters: 2278 minor_status Integer, modify 2279 Mechanism specific status code. 2281 src_name gss_name_t, read 2282 internal name to be duplicated. 2284 dest_name gss_name_t, modify 2285 The resultant copy of . 2286 Storage associated with this name must 2287 be freed by the application after use 2288 with a call to gss_release_name(). 2290 Function value: GSS status code 2292 GSS_S_COMPLETE Successful completion 2294 GSS_S_BAD_NAME The src_name parameter was ill-formed. 2296 Wray [Page 47 of 101] 2297 7.13.gss_export_name 2299 OM_uint32 gss_export_name ( 2300 OM_uint32 *minor_status, 2301 const gss_name_t input_name, 2302 gss_buffer_t exported_name) 2304 Purpose: 2306 To produce a canonical contiguous string representation of a 2307 mechanism name (MN), suitable for direct comparison (e.g. with 2308 memcmp) for use in authorization functions (e.g. matching entries in 2309 an access-control list). 2310 The parameter must specify a valid MN (i.e. an internal 2311 name generated by gss_accept_sec_context or by 2312 gss_canonicalize_name). 2314 Parameters: 2316 minor_status Integer, modify 2317 Mechanism specific status code 2319 input_name gss_name_t, read 2320 The MN to be exported 2322 exported_name gss_buffer_t, octet-string, modify 2323 The canonical contiguous string form of 2324 . Storage associated with 2325 this string must freed by the application 2326 after use with gss_release_buffer(). 2328 Function value: GSS status code 2330 GSS_S_COMPLETE Successful completion 2332 GSS_S_NAME_NOT_MN The provided internal name was not a mechanism 2333 name. 2335 GSS_S_BAD_NAME The provided internal name was ill-formed. 2337 GSS_S_BAD_NAMETYPE The internal name was of a type not supported 2338 by the GSSAPI implementation. 2340 Wray [Page 48 of 101] 2341 7.14.gss_export_sec_context 2343 OM_uint32 gss_export_sec_context ( 2344 OM_uint32 *minor_status, 2345 gss_ctx_id_t *context_handle, 2346 gss_buffer_t interprocess_token) 2348 Purpose: 2350 Provided to support the sharing of work between multiple processes. 2351 This routine will typically be used by the context-acceptor, in an 2352 application where a single process receives incoming connection 2353 requests and accepts security contexts over them, then passes the 2354 established context to one or more other processes for message 2355 exchange. gss_export_sec_context() deactivates the security context 2356 for the calling process and creates an interprocess token which, when 2357 passed to gss_import_sec_context in another process, will re-activate 2358 the context in the second process. Only a single instantiation of a 2359 given context may be active at any one time; a subsequent attempt by 2360 a context exporter to access the exported security context will fail. 2362 The implementation may constrain the set of processes by which the 2363 interprocess token may be imported, either as a function of local 2364 security policy, or as a result of implementation decisions. For 2365 example, some implementations may constrain contexts to be passed 2366 only between processes that run under the same account, or which are 2367 part of the same process group. 2369 The interprocess token may contain security-sensitive information 2370 (for example cryptographic keys). While mechanisms are encouraged to 2371 either avoid placing such sensitive information within interprocess 2372 tokens, or to encrypt the token before returning it to the 2373 application, in a typical object-library GSSAPI implementation this 2374 may not be possible. Thus the application must take care to protect 2375 the interprocess token, and ensure that any process to which the 2376 token is transferred is trustworthy. 2378 If creation of the interprocess token is succesful, the 2379 implementation shall deallocate all process-wide resources associated 2380 with the security context, and set the context_handle to 2381 GSS_C_NO_CONTEXT. In the event of an error that makes it impossible 2382 to complete the export of the security context, the implementation 2383 must not return an interprocess token, and should strive to leave the 2384 security context referenced by the context_handle parameter 2385 untouched. If this is impossible, it is permissible for the 2386 implementation to delete the security context, providing it also sets 2387 the context_handle parameter to GSS_C_NO_CONTEXT. 2389 Parameters: 2391 minor_status Integer, modify 2392 Mechanism specific status code 2394 context_handle gss_ctx_id_t, modify 2395 context handle identifying the context to 2397 Wray [Page 49 of 101] 2398 transfer. 2400 interprocess_token buffer, opaque, modify 2401 token to be transferred to target process. 2402 Storage associated with this token must be 2403 freed by the application after use with a 2404 call to gss_release_buffer(). 2406 Function value: GSS status code 2408 GSS_S_COMPLETE Successful completion 2410 GSS_S_CONTEXT_EXPIRED The context has expired 2412 GSS_S_NO_CONTEXT The context was invalid 2414 GSS_S_UNAVAILABLE The operation is not supported. 2416 Wray [Page 50 of 101] 2417 7.15.gss_get_mic 2419 OM_uint32 gss_get_mic ( 2420 OM_uint32 *minor_status, 2421 const gss_ctx_id_t context_handle, 2422 gss_qop_t qop_req, 2423 const gss_buffer_t message_buffer, 2424 gss_buffer_t msg_token) 2426 Purpose: 2428 Generates a cryptographic MIC for the supplied message, and places 2429 the MIC in a token for transfer to the peer application. The qop_req 2430 parameter allows a choice between several cryptographic algorithms, 2431 if supported by the chosen mechanism. 2433 Since some application-level protocols may wish to use tokens emitted 2434 by gss_wrap() to provide "secure framing", implementations must 2435 support derivation of MICs from zero-length messages. 2437 Parameters: 2439 minor_status Integer, modify 2440 Implementation specific status code. 2442 context_handle gss_ctx_id_t, read 2443 identifies the context on which the message 2444 will be sent 2446 qop_req gss_qop_t, read, optional 2447 Specifies requested quality of protection. 2448 Callers are encouraged, on portability grounds, 2449 to accept the default quality of protection 2450 offered by the chosen mechanism, which may be 2451 requested by specifying GSS_C_QOP_DEFAULT for 2452 this parameter. If an unsupported protection 2453 strength is requested, gss_get_mic will return a 2454 major_status of GSS_S_BAD_QOP. 2456 message_buffer buffer, opaque, read 2457 message to be protected 2459 msg_token buffer, opaque, modify 2460 buffer to receive token. The application must 2461 free storage associated with this buffer after 2462 use with a call to gss_release_buffer(). 2464 Function value: GSS status code 2466 GSS_S_COMPLETE Successful completion 2468 GSS_S_CONTEXT_EXPIRED The context has already expired 2470 GSS_S_NO_CONTEXT The context_handle parameter did not identify 2472 Wray [Page 51 of 101] 2473 a valid context 2475 GSS_S_BAD_QOP The specified QOP is not supported by the 2476 mechanism. 2478 Wray [Page 52 of 101] 2479 7.16.gss_import_name 2481 OM_uint32 gss_import_name ( 2482 OM_uint32 *minor_status, 2483 const gss_buffer_t input_name_buffer, 2484 const gss_OID input_name_type, 2485 gss_name_t *output_name) 2487 Purpose: 2489 Convert a contiguous string name to internal form. In general, the 2490 internal name returned (via the parameter) will not be 2491 an MN; the exception to this is if the indicates 2492 that the contiguous string provided via the 2493 parameter is of type GSS_C_NT_EXPORT_NAME, in which case the returned 2494 internal name will be an MN for the mechanism that exported the name. 2496 Parameters: 2498 minor_status Integer, modify 2499 Mechanism specific status code 2501 input_name_buffer buffer, octet-string, read 2502 buffer containing contiguous string name to convert 2504 input_name_type Object ID, read, optional 2505 Object ID specifying type of printable 2506 name. Applications may specify either 2507 GSS_C_NO_OID to use a mechanism-specific 2508 default printable syntax, or an OID recognized 2509 by the GSS-API implementation to name a 2510 specific namespace. 2512 output_name gss_name_t, modify 2513 returned name in internal form. Storage 2514 associated with this name must be freed 2515 by the application after use with a call 2516 to gss_release_name(). 2518 Function value: GSS status code 2520 GSS_S_COMPLETE Successful completion 2522 GSS_S_BAD_NAMETYPE The input_name_type was unrecognized 2524 GSS_S_BAD_NAME The input_name parameter could not be interpreted 2525 as a name of the specified type 2527 GSS_S_BAD_MECH The input name-type was GSS_C_NT_EXPORT_NAME, 2528 but the mechanism contained within the 2529 input-name is not supported 2531 Wray [Page 53 of 101] 2532 7.17.gss_import_sec_context 2534 OM_uint32 gss_import_sec_context ( 2535 OM_uint32 *minor_status, 2536 const gss_buffer_t interprocess_token, 2537 gss_ctx_id_t *context_handle) 2539 Purpose: 2541 Allows a process to import a security context established by another 2542 process. A given interprocess token may be imported only once. See 2543 gss_export_sec_context. 2545 Parameters: 2547 minor_status Integer, modify 2548 Mechanism specific status code 2550 interprocess_token buffer, opaque, modify 2551 token received from exporting process 2553 context_handle gss_ctx_id_t, modify 2554 context handle of newly reactivated context. 2555 Resources associated with this context handle 2556 must be released by the application after use 2557 with a call to gss_delete_sec_context(). 2559 Function value: GSS status code 2561 GSS_S_COMPLETE Successful completion. 2563 GSS_S_NO_CONTEXT The token did not contain a valid context 2564 reference. 2566 GSS_S_DEFECTIVE_TOKEN The token was invalid. 2568 GSS_S_UNAVAILABLE The operation is unavailable. 2570 GSS_S_UNAUTHORIZED Local policy prevents the import of this context 2571 by the current process. 2573 Wray [Page 54 of 101] 2574 7.18.gss_indicate_mechs 2576 OM_uint32 gss_indicate_mechs ( 2577 OM_uint32 *minor_status, 2578 gss_OID_set *mech_set) 2580 Purpose: 2582 Allows an application to determine which underlying security 2583 mechanisms are available. 2585 Parameters: 2587 minor_status Integer, modify 2588 Mechanism specific status code. 2590 mech_set set of Object IDs, modify 2591 set of implementation-supported mechanisms. 2592 The returned gss_OID_set value will be a 2593 dynamically-allocated OID set, that should 2594 be released by the caller after use with a 2595 call to gss_release_oid_set(). 2597 Function value: GSS status code 2599 GSS_S_COMPLETE Successful completion 2601 Wray [Page 55 of 101] 2602 7.19.gss_init_sec_context 2604 OM_uint32 gss_init_sec_context ( 2605 OM_uint32 *minor_status, 2606 const gss_cred_id_t initiator_cred_handle, 2607 gss_ctx_id_t *context_handle,\ 2608 const gss_name_t target_name, 2609 const gss_OID mech_type, 2610 OM_uint32 req_flags, 2611 OM_uint32 time_req, 2612 const gss_channel_bindings_t input_chan_bindings, 2613 const gss_buffer_t input_token 2614 gss_OID *actual_mech_type, 2615 gss_buffer_t output_token, 2616 OM_uint32 *ret_flags, 2617 OM_uint32 *time_rec ) 2619 Purpose: 2621 Initiates the establishment of a security context between the 2622 application and a remote peer. Initially, the input_token parameter 2623 should be specified either as GSS_C_NO_BUFFER, or as a pointer to a 2624 gss_buffer_desc object whose length field contains the value zero. 2625 The routine may return a output_token which should be transferred to 2626 the peer application, where the peer application will present it to 2627 gss_accept_sec_context. If no token need be sent, 2628 gss_init_sec_context will indicate this by setting the length field 2629 of the output_token argument to zero. To complete the context 2630 establishment, one or more reply tokens may be required from the peer 2631 application; if so, gss_init_sec_context will return a status 2632 containing the supplementary information bit GSS_S_CONTINUE_NEEDED. 2633 In this case, gss_init_sec_context should be called again when the 2634 reply token is received from the peer application, passing the reply 2635 token to gss_init_sec_context via the input_token parameters. 2637 Portable applications should be constructed to use the token length 2638 and return status to determine whether a token needs to be sent or 2639 waited for. Thus a typical portable caller should always invoke 2640 gss_init_sec_context within a loop: 2642 int context_established = 0; 2643 gss_ctx_id_t context_hdl = GSS_C_NO_CONTEXT; 2644 ... 2645 input_token->length = 0; 2647 while (!context_established) { 2648 maj_stat = gss_init_sec_context(&min_stat, 2649 cred_hdl, 2650 &context_hdl, 2651 target_name, 2652 desired_mech, 2653 desired_services, 2654 desired_time, 2656 Wray [Page 56 of 101] 2657 input_bindings, 2658 input_token, 2659 &actual_mech, 2660 output_token, 2661 &actual_services, 2662 &actual_time); 2663 if (GSS_ERROR(maj_stat)) { 2664 report_error(maj_stat, min_stat); 2665 }; 2667 if (output_token->length != 0) { 2668 send_token_to_peer(output_token); 2669 gss_release_buffer(&min_stat, output_token) 2670 }; 2671 if (GSS_ERROR(maj_stat)) { 2673 if (context_hdl != GSS_C_NO_CONTEXT) 2674 gss_delete_sec_context(&min_stat, 2675 &context_hdl, 2676 GSS_C_NO_BUFFER); 2677 break; 2678 }; 2679 if (maj_stat & GSS_S_CONTINUE_NEEDED) { 2680 receive_token_from_peer(input_token); 2681 } else { 2682 context_established = 1; 2683 }; 2684 }; 2686 Whenever the routine returns a major status that includes the value 2687 GSS_S_CONTINUE_NEEDED, the context is not fully established and the 2688 following restrictions apply to the output parameters: 2690 The value returned via the time_rec parameter is undefined 2691 Unless the accompanying ret_flags parameter contains the bit 2692 GSS_C_PROT_READY_FLAG, indicating that per-message services may 2693 be applied in advance of a successful completion status, the 2694 value returned via the actual_mech_type parameter is undefined 2695 until the routine returns a major status value of 2696 GSS_S_COMPLETE. 2698 The values of the GSS_C_DELEG_FLAG, GSS_C_MUTUAL_FLAG, 2699 GSS_C_REPLAY_FLAG, GSS_C_SEQUENCE_FLAG, GSS_C_CONF_FLAG, 2700 GSS_C_INTEG_FLAG and GSS_C_ANON_FLAG bits returned via the 2701 ret_flags parameter should contain the values that the 2702 implementation expects would be valid if context establishment 2703 were to succeed. In particular, if the application has 2704 requested a service such as delegation or anonymous 2705 authentication via the req_flags argument, and such a service 2706 is unavailable from the underlying mechanism, 2707 gss_init_sec_context should generate a token that will not 2708 provide the service, and indicate via the ret_flags argument 2709 that the service will not be supported. The application may 2710 choose to abort the context establishment by calling 2711 gss_delete_sec_context (if it cannot continue in the absence 2713 Wray [Page 57 of 101] 2714 of the service), or it may choose to transmit the token 2715 and continue context establishment (if the service was merely 2716 desired but not mandatory). 2718 The values of the GSS_C_PROT_READY_FLAG and GSS_C_TRANS_FLAG 2719 bits within ret_flags should indicate the actual state at the 2720 time gss_init_sec_context returns, whether or not the context 2721 is fully established. 2723 GSSAPI implementations that support per-message protection 2724 are encouraged to set the GSS_C_PROT_READY_FLAG in the final 2725 ret_flags returned to a caller (i.e. when accompanied by a 2726 GSS_S_COMPLETE status code). However, applications should not 2727 rely on this behavior as the flag was not defined in Version 1 2728 of the GSSAPI. Instead, applications should determine what 2729 per-message services are available after a successful context 2730 establishment according to the GSS_C_INTEG_FLAG and 2731 GSS_C_CONF_FLAG values. 2733 All other bits within the ret_flags argument should be set 2734 to zero. 2736 If the initial call of gss_init_sec_context() fails, the 2737 implementation should not create a context object, and should leave 2738 the value of the context_handle parameter set to GSS_C_NO_CONTEXT to 2739 indicate this. In the event of a failure on a subsequent call, the 2740 implementation is permitted to delete the "half-built" security 2741 context (in which case it should set the context_handle parameter to 2742 GSS_C_NO_CONTEXT), but the preferred behavior is to leave the 2743 security context untouched for the application to delete (using 2744 gss_delete_sec_context). 2746 During context establishment, the informational status bits 2747 GSS_S_OLD_TOKEN and GSS_S_DUPLICATE_TOKEN indicate fatal errors, and 2748 GSSAPI mechanisms should always return them in association with a 2749 routine error of GSS_S_FAILURE. This requirement for pairing did not 2750 exist in version 1 of the GSSAPI specification, so applications that 2751 wish to run over version 1 implementations must special-case these 2752 codes. 2754 Parameters: 2756 minor_status Integer, modify 2757 Mechanism specific status code. 2759 initiator_cred_handle gss_cred_id_t, read, optional 2760 handle for credentials claimed. Supply 2761 GSS_C_NO_CREDENTIAL to act as a default 2762 initiator principal. If no default 2763 initiator is defined, the function will 2764 return GSS_S_NO_CRED. 2766 context_handle gss_ctx_id_t, read/modify 2767 context handle for new context. Supply 2769 Wray [Page 58 of 101] 2770 GSS_C_NO_CONTEXT for first call; use value 2771 returned by first call in continuation calls. 2772 Resources associated with this context-handle 2773 must be released by the application after use 2774 with a call to gss_delete_sec_context(). 2776 target_name gss_name_t, read 2777 Name of target 2779 mech_type OID, read, optional 2780 Object ID of desired mechanism. Supply 2781 GSS_C_NO_OID to obtain an implementation 2782 specific default 2784 req_flags bit-mask, read 2785 Contains various independent flags, each of 2786 which requests that the context support a 2787 specific service option. Symbolic 2788 names are provided for each flag, and the 2789 symbolic names corresponding to the required 2790 flags should be logically-ORed 2791 together to form the bit-mask value. The 2792 flags are: 2794 GSS_C_DELEG_FLAG 2795 True - Delegate credentials to remote peer 2796 False - Don't delegate 2798 GSS_C_MUTUAL_FLAG 2799 True - Request that remote peer 2800 authenticate itself 2801 False - Authenticate self to remote peer 2802 only 2804 GSS_C_REPLAY_FLAG 2805 True - Enable replay detection for 2806 messages protected with gss_wrap 2807 or gss_get_mic 2808 False - Don't attempt to detect 2809 replayed messages 2811 GSS_C_SEQUENCE_FLAG 2812 True - Enable detection of out-of-sequence 2813 protected messages 2814 False - Don't attempt to detect 2815 out-of-sequence messages 2817 GSS_C_ANON_FLAG 2818 True - Do not reveal the initiator's 2819 identity to the acceptor. 2820 False - Authenticate normally. 2822 time_req Integer, read, optional 2823 Desired number of seconds for which context 2824 should remain valid. Supply 0 to request a 2826 Wray [Page 59 of 101] 2827 default validity period. 2829 input_chan_bindings channel bindings, read, optional 2830 Application-specified bindings. Allows 2831 application to securely bind channel 2832 identification information to the security 2833 context. Specify GSS_C_NO_CHANNEL_BINDINGS 2834 if channel bindings are not used. 2836 input_token buffer, opaque, read, optional (see text) 2837 Token received from peer application. 2838 Supply GSS_C_NO_BUFFER, or a pointer to 2839 a buffer containing the value GSS_C_EMPTY_BUFFER 2840 on initial call. 2842 actual_mech_type OID, modify, optional 2843 Actual mechanism used. The OID returned via 2844 this parameter will be a pointer to static 2845 storage that should be treated as read-only; 2846 In particular the application should not attempt 2847 to free it. Specify NULL if not required. 2849 output_token buffer, opaque, modify 2850 token to be sent to peer application. If 2851 the length field of the returned buffer is 2852 zero, no token need be sent to the peer 2853 application. Storage associated with this 2854 buffer must be freed by the application 2855 after use with a call to gss_release_buffer(). 2857 ret_flags bit-mask, modify, optional 2858 Contains various independent flags, each of which 2859 indicates that the context supports a specific 2860 service option. Specify NULL if not 2861 required. Symbolic names are provided 2862 for each flag, and the symbolic names 2863 corresponding to the required flags should be 2864 logically-ANDed with the ret_flags value to test 2865 whether a given option is supported by the 2866 context. The flags are: 2868 GSS_C_DELEG_FLAG 2869 True - Credentials were delegated to 2870 the remote peer 2871 False - No credentials were delegated 2873 GSS_C_MUTUAL_FLAG 2874 True - The remote peer has authenticated 2875 itself. 2876 False - Remote peer has not authenticated 2877 itself. 2879 GSS_C_REPLAY_FLAG 2880 True - replay of protected messages 2881 will be detected 2883 Wray [Page 60 of 101] 2884 False - replayed messages will not be 2885 detected 2887 GSS_C_SEQUENCE_FLAG 2888 True - out-of-sequence protected 2889 messages will be detected 2890 False - out-of-sequence messages will 2891 not be detected 2893 GSS_C_CONF_FLAG 2894 True - Confidentiality service may be 2895 invoked by calling gss_wrap routine 2896 False - No confidentiality service (via 2897 gss_wrap) available. gss_wrap will 2898 provide message encapsulation, 2899 data-origin authentication and 2900 integrity services only. 2902 GSS_C_INTEG_FLAG 2903 True - Integrity service may be invoked by 2904 calling either gss_get_mic or gss_wrap 2905 routines. 2906 False - Per-message integrity service 2907 unavailable. 2909 GSS_C_ANON_FLAG 2910 True - The initiator's identity has not been 2911 revealed, and will not be revealed if 2912 any emitted token is passed to the 2913 acceptor. 2914 False - The initiator's identity has been or 2915 will be authenticated normally. 2917 GSS_C_PROT_READY_FLAG 2918 True - Protection services (as specified 2919 by the states of the GSS_C_CONF_FLAG 2920 and GSS_C_INTEG_FLAG) are available for 2921 use if the accompanying major status 2922 return value is either GSS_S_COMPLETE or 2923 GSS_S_CONTINUE_NEEDED. 2924 False - Protection services (as specified 2925 by the states of the GSS_C_CONF_FLAG 2926 and GSS_C_INTEG_FLAG) are available 2927 only if the accompanying major status 2928 return value is GSS_S_COMPLETE. 2930 GSS_C_TRANS_FLAG 2931 True - The resultant security context may 2932 be transferred to other processes via 2933 a call to gss_export_sec_context(). 2934 False - The security context is not 2935 transferrable. 2937 All other bits should be set to zero. 2939 Wray [Page 61 of 101] 2940 time_rec Integer, modify, optional 2941 number of seconds for which the context 2942 will remain valid. If the implementation does 2943 not support context expiration, the value 2944 GSS_C_INDEFINITE will be returned. Specify 2945 NULL if not required. 2947 Function value: GSS status code 2949 GSS_S_COMPLETE Successful completion 2951 GSS_S_CONTINUE_NEEDED Indicates that a token from the peer 2952 application is required to complete the 2953 context, and that gss_init_sec_context 2954 must be called again with that token. 2956 GSS_S_DEFECTIVE_TOKEN Indicates that consistency checks performed 2957 on the input_token failed 2959 GSS_S_DEFECTIVE_CREDENTIAL Indicates that consistency checks 2960 performed on the credential failed. 2962 GSS_S_NO_CRED The supplied credentials were not valid for 2963 context initiation, or the credential handle 2964 did not reference any credentials. 2966 GSS_S_CREDENTIALS_EXPIRED The referenced credentials have expired 2968 GSS_S_BAD_BINDINGS The input_token contains different channel 2969 bindings to those specified via the 2970 input_chan_bindings parameter 2972 GSS_S_BAD_SIG The input_token contains an invalid MIC, or a MIC 2973 that could not be verified 2975 GSS_S_OLD_TOKEN The input_token was too old. This is a fatal 2976 error during context establishment 2978 GSS_S_DUPLICATE_TOKEN The input_token is valid, but is a duplicate 2979 of a token already processed. This is a 2980 fatal error during context establishment. 2982 GSS_S_NO_CONTEXT Indicates that the supplied context handle did 2983 not refer to a valid context 2985 GSS_S_BAD_NAMETYPE The provided target_name parameter contained an 2986 invalid or unsupported type of name 2988 GSS_S_BAD_NAME The provided target_name parameter was ill-formed. 2990 GSS_S_BAD_MECH The specified mechanism is not supported by the 2991 provided credential, or is unrecognized by the 2992 implementation. 2994 Wray [Page 62 of 101] 2995 7.20.gss_inquire_context 2997 OM_uint32 gss_inquire_context ( 2998 OM_uint32 *minor_status, 2999 const gss_ctx_id_t context_handle, 3000 gss_name_t *src_name, 3001 gss_name_t *targ_name, 3002 OM_uint32 *lifetime_rec, 3003 gss_OID *mech_type, 3004 OM_uint32 *ctx_flags, 3005 int *locally_initiated, 3006 int *open ) 3008 Purpose: 3010 Obtains information about a security context. The caller must 3011 already have obtained a handle that refers to the context, although 3012 the context need not be fully established. 3014 Parameters: 3016 minor_status Integer, modify 3017 Mechanism specific status code 3019 context_handle gss_ctx_id_t, read 3020 A handle that refers to the security context. 3022 src_name gss_name_t, modify, optional 3023 The name of the context initiator. 3024 If the context was established using anonymous 3025 authentication, and if the application invoking 3026 gss_inquire_context is the context acceptor, 3027 an anonymous name will be returned. Storage 3028 associated with this name must be freed by the 3029 application after use with a call to 3030 gss_release_name(). Specify NULL if not 3031 required. 3033 targ_name gss_name_t, modify, optional 3034 The name of the context acceptor. 3035 Storage associated with this name must be 3036 freed by the application after use with a call 3037 to gss_release_name(). If the context acceptor 3038 did not authenticate itself, and if the initiator 3039 did not specify a target name in its call to 3040 gss_init_sec_contect(), the value GSS_C_NO_NAME 3041 will be returned. Specify NULL if not required. 3043 lifetime_rec Integer, modify, optional 3044 The number of seconds for which the context 3045 will remain valid. If the context has 3046 expired, this parameter will be set to zero. 3047 If the implementation does not support 3048 context expiration, the value 3049 GSS_C_INDEFINITE will be returned. Specify 3051 Wray [Page 63 of 101] 3052 NULL if not required. 3054 mech_type gss_OID, modify, optional 3055 The security mechanism providing the 3056 context. The returned OID will be a 3057 pointer to static storage that should 3058 be treated as read-only by the application; 3059 in particular the application should not 3060 attempt to free it. Specify NULL if not 3061 required. 3063 ctx_flags bit-mask, modify, optional 3064 Contains various independent flags, each of 3065 which indicates that the context supports 3066 (or is expected to support, if ctx_open is 3067 false) a specific service option. If not 3068 needed, specify NULL. Symbolic names are 3069 provided for each flag, and the symbolic names 3070 corresponding to the required flags 3071 should be logically-ANDed with the ret_flags 3072 value to test whether a given option is 3073 supported by the context. The flags are: 3075 GSS_C_DELEG_FLAG 3076 True - Credentials were delegated from 3077 the initiator to the acceptor. 3078 False - No credentials were delegated 3080 GSS_C_MUTUAL_FLAG 3081 True - The acceptor was authenticated 3082 to the initiator 3083 False - The acceptor did not authenticate 3084 itself. 3086 GSS_C_REPLAY_FLAG 3087 True - replay of protected messages 3088 will be detected 3089 False - replayed messages will not be 3090 detected 3092 GSS_C_SEQUENCE_FLAG 3093 True - out-of-sequence protected 3094 messages will be detected 3095 False - out-of-sequence messages will not 3096 be detected 3098 GSS_C_CONF_FLAG 3099 True - Confidentiality service may be invoked 3100 by calling gss_wrap routine 3101 False - No confidentiality service (via 3102 gss_wrap) available. gss_wrap will 3103 provide message encapsulation, 3104 data-origin authentication and 3105 integrity services only. 3107 Wray [Page 64 of 101] 3108 GSS_C_INTEG_FLAG 3109 True - Integrity service may be invoked by 3110 calling either gss_get_mic or gss_wrap 3111 routines. 3112 False - Per-message integrity service 3113 unavailable. 3115 GSS_C_ANON_FLAG 3116 True - The initiator's identity will not 3117 be revealed to the acceptor. 3118 The src_name parameter (if 3119 requested) contains an anonymous 3120 internal name. 3121 False - The initiator has been 3122 authenticated normally. 3124 GSS_C_PROT_READY_FLAG 3125 True - Protection services (as specified 3126 by the states of the GSS_C_CONF_FLAG 3127 and GSS_C_INTEG_FLAG) are available 3128 for use. 3129 False - Protection services (as specified 3130 by the states of the GSS_C_CONF_FLAG 3131 and GSS_C_INTEG_FLAG) are available 3132 only if the context is fully 3133 established (i.e. if the open parameter 3134 is non-zero). 3136 GSS_C_TRANS_FLAG 3137 True - The resultant security context may 3138 be transferred to other processes via 3139 a call to gss_export_sec_context(). 3140 False - The security context is not 3141 transferrable. 3143 locally_initiated Boolean, modify 3144 Non-zero if the invoking application is the 3145 context initiator. 3146 Specify NULL if not required. 3148 open Boolean, modify 3149 Non-zero if the context is fully established; 3150 Zero if a context-establishment token 3151 is expected from the peer application. 3152 Specify NULL if not required. 3154 Function value: GSS status code 3156 GSS_S_COMPLETE Successful completion 3158 GSS_S_NO_CONTEXT The referenced context could not be accessed. 3160 Wray [Page 65 of 101] 3161 7.21.gss_inquire_cred 3163 OM_uint32 gss_inquire_cred ( 3164 OM_uint32 *minor_status, 3165 const gss_cred_id_t cred_handle, 3166 gss_name_t *name, 3167 OM_uint32 *lifetime, 3168 gss_cred_usage_t *cred_usage, 3169 gss_OID_set *mechanisms ) 3171 Purpose: 3173 Obtains information about a credential. 3175 Parameters: 3177 minor_status Integer, modify 3178 Mechanism specific status code 3180 cred_handle gss_cred_id_t, read 3181 A handle that refers to the target credential. 3182 Specify GSS_C_NO_CREDENTIAL to inquire about 3183 the default initiator principal. 3185 name gss_name_t, modify, optional 3186 The name whose identity the credential asserts. 3187 Storage associated with this name should be freed 3188 by the application after use with a call to 3189 gss_release_name(). Specify NULL if not required. 3191 lifetime Integer, modify, optional 3192 The number of seconds for which the credential 3193 will remain valid. If the credential has 3194 expired, this parameter will be set to zero. 3195 If the implementation does not support 3196 credential expiration, the value 3197 GSS_C_INDEFINITE will be returned. Specify 3198 NULL if not required. 3200 cred_usage gss_cred_usage_t, modify, optional 3201 How the credential may be used. One of the 3202 following: 3203 GSS_C_INITIATE 3204 GSS_C_ACCEPT 3205 GSS_C_BOTH 3206 Specify NULL if not required. 3208 mechanisms gss_OID_set, modify, optional 3209 Set of mechanisms supported by the credential. 3210 Storage associated with this OID set must be 3211 freed by the application after use with a call 3212 to gss_release_oid_set(). Specify NULL if not 3213 required. 3215 Function value: GSS status code 3217 Wray [Page 66 of 101] 3218 GSS_S_COMPLETE Successful completion 3220 GSS_S_NO_CRED The referenced credentials could not be accessed. 3222 GSS_S_DEFECTIVE_CREDENTIAL The referenced credentials were invalid. 3224 GSS_S_CREDENTIALS_EXPIRED The referenced credentials have expired. 3225 If the lifetime parameter was not passed as NULL, 3226 it will be set to 0. 3228 Wray [Page 67 of 101] 3229 7.22.gss_inquire_cred_by_mech 3231 OM_uint32 gss_inquire_cred_by_mech ( 3232 OM_uint32 *minor_status, 3233 const gss_cred_id_t cred_handle, 3234 const gss_OID mech_type, 3235 gss_name_t *name, 3236 OM_uint32 *initiator_lifetime, 3237 OM_uint32 *acceptor_lifetime, 3238 gss_cred_usage_t *cred_usage ) 3240 Purpose: 3242 Obtains per-mechanism information about a credential. 3244 Parameters: 3246 minor_status Integer, modify 3247 Mechanism specific status code 3249 cred_handle gss_cred_id_t, read 3250 A handle that refers to the target credential. 3251 Specify GSS_C_NO_CREDENTIAL to inquire about 3252 the default initiator principal. 3254 mech_type gss_OID, read 3255 The mechanism for which information should be 3256 returned. 3258 name gss_name_t, modify, optional 3259 The name whose identity the credential asserts. 3260 Storage associated with this name must be 3261 freed by the application after use with a call 3262 to gss_release_name(). Specify NULL if not 3263 required. 3265 initiator_lifetime Integer, modify, optional 3266 The number of seconds for which the credential 3267 will remain capable of initiating security contexts 3268 under the specified mechanism. If the credential 3269 can no longer be used to initiate contexts, or if 3270 the credential usage for this mechanism is 3271 GSS_C_ACCEPT, this parameter will be set to zero. 3272 If the implementation does not support expiration 3273 of initiator credentials, the value 3274 GSS_C_INDEFINITE will be returned. Specify NULL 3275 if not required. 3277 acceptor_lifetime Integer, modify, optional 3278 The number of seconds for which the credential 3279 will remain capable of accepting security contexts 3280 under the specified mechanism. If the credential 3281 can no longer be used to accept contexts, or if 3282 the credential usage for this mechanism is 3284 Wray [Page 68 of 101] 3285 GSS_C_INITIATE, this parameter will be set to zero. 3287 If the implementation does not support expiration 3288 of acceptor credentials, the value GSS_C_INDEFINITE 3289 will be returned. Specify NULL if not required. 3291 cred_usage gss_cred_usage_t, modify, optional 3292 How the credential may be used with the specified 3293 mechanism. One of the following: 3294 GSS_C_INITIATE 3295 GSS_C_ACCEPT 3296 GSS_C_BOTH 3297 Specify NULL if not required. 3299 Function value: GSS status code 3301 GSS_S_COMPLETE Successful completion 3303 GSS_S_NO_CRED The referenced credentials could not be accessed. 3305 GSS_S_DEFECTIVE_CREDENTIAL The referenced credentials were invalid. 3307 GSS_S_CREDENTIALS_EXPIRED The referenced credentials have expired. 3308 If the lifetime parameter was not passed as NULL, 3309 it will be set to 0. 3311 Wray [Page 69 of 101] 3312 7.23.gss_inquire_mechs_for_name 3314 OM_uint32 gss_inquire_mechs_for_name ( 3315 OM_uint32 *minor_status, 3316 const gss_name_t input_name, 3317 gss_OID_set *mech_types ) 3319 Purpose: 3321 Returns the set of mechanisms supported by the GSSAPI implementation 3322 that may be able to process the specified name. 3324 Each mechanism returned will recognize at least one element within 3325 the name. It is permissible for this routine to be implemented 3326 within a mechanism-independent GSSAPI layer, using the type 3327 information contained within the presented name, and based on 3328 registration information provided by individual mechanism 3329 implementations. This means that the returned mech_types set may 3330 indicate that a particular mechanism will understand the name when in 3331 fact it would refuse to accept the name as input to 3332 gss_canonicalize_name, gss_init_sec_context, gss_acquire_cred or 3333 gss_add_cred (due to some property of the specific name, as opposed 3334 to the name type). Thus this routine should be used only as a 3335 pre-filter for a call to a subsequent mechanism-specific routine. 3337 Parameters: 3339 minor_status Integer, modify 3340 Implementation specific status code. 3342 input_name gss_name_t, read 3343 The name to which the inquiry relates. 3345 mech_types gss_OID_set, modify 3346 Set of mechanisms that may support the 3347 specified name. The returned OID set 3348 must be freed by the caller after use 3349 with a call to gss_release_oid_set(). 3351 Function value: GSS status code 3353 GSS_S_COMPLETE Successful completion 3355 GSS_S_BAD_NAME The input_name parameter was ill-formed. 3357 GSS_S_BAD_NAMETYPE The input_name parameter contained an invalid or 3358 unsupported type of name 3360 Wray [Page 70 of 101] 3361 7.24.gss_inquire_names_for_mech 3363 OM_uint32 gss_inquire_names_for_mech ( 3364 OM_uint32 *minor_status, 3365 const gss_OID mechanism, 3366 gss_OID_set *name_types) 3368 Purpose: 3370 Returns the set of nametypes supported by the specified mechanism. 3372 Parameters: 3374 minor_status Integer, modify 3375 Implementation specific status code. 3377 mechanism gss_OID, read 3378 The mechanism to be interrogated. 3380 name_types gss_OID_set, modify 3381 Set of name-types supported by the specified 3382 mechanism. The returned OID set must be 3383 freed by the application after use with a 3384 call to gss_release_oid_set(). 3386 Function value: GSS status code 3388 GSS_S_COMPLETE Successful completion 3390 Wray [Page 71 of 101] 3391 7.25.gss_process_context_token 3393 OM_uint32 gss_process_context_token ( 3394 OM_uint32 *minor_status, 3395 const gss_ctx_id_t context_handle, 3396 const gss_buffer_t token_buffer) 3398 Purpose: 3400 Provides a way to pass an asynchronous token to the security service. 3401 Most context-level tokens are emitted and processed synchronously by 3402 gss_init_sec_context and gss_accept_sec_context, and the application 3403 is informed as to whether further tokens are expected by the 3404 GSS_C_CONTINUE_NEEDED major status bit. Occasionally, a mechanism 3405 may need to emit a context-level token at a point when the peer 3406 entity is not expecting a token. For example, the initiator�s final 3407 call to gss_init_sec_context may emit a token and return a status of 3408 GSS_S_COMPLETE, but the acceptor�s call to gss_accept_sec_context may 3409 fail. The acceptor�s mechanism may wish to send a token containing 3410 an error indication to the initiator, but the initiator is not 3411 expecting a token at this point, believing that the context is fully 3412 established. Gss_process_context_token provides a way to pass such a 3413 token to the mechanism at any time. 3415 Parameters: 3417 minor_status Integer, modify 3418 Implementation specific status code. 3420 context_handle gss_ctx_id_t, read 3421 context handle of context on which token is to 3422 be processed 3424 token_buffer buffer, opaque, read 3425 token to process 3427 Function value: GSS status code 3429 GSS_S_COMPLETE Successful completion 3431 GSS_S_DEFECTIVE_TOKEN Indicates that consistency checks performed 3432 on the token failed 3434 GSS_S_NO_CONTEXT The context_handle did not refer to a valid context 3436 Wray [Page 72 of 101] 3437 7.26.gss_release_buffer 3439 OM_uint32 gss_release_buffer ( 3440 OM_uint32 *minor_status, 3441 gss_buffer_t buffer) 3443 Purpose: 3445 Free storage associated with a buffer. The storage must have been 3446 allocated by a GSS-API routine. In addition to freeing the 3447 associated storage, the routine will zero the length field in the 3448 descriptor to which the buffer parameter refers, and implementations 3449 are encouraged to additionally set the pointer field in the 3450 descriptor to NULL. Any buffer object returned by a GSSAPI routine 3451 may be passed to gss_release_buffer (even if there is no storage 3452 associated with the buffer). 3454 Parameters: 3456 minor_status Integer, modify 3457 Mechanism specific status code 3459 buffer buffer, modify 3460 The storage associated with the buffer will be 3461 deleted. The gss_buffer_desc object will not 3462 be freed, but its length field will be zeroed. 3464 Function value: GSS status code 3466 GSS_S_COMPLETE Successful completion 3468 Wray [Page 73 of 101] 3469 7.27.gss_release_cred 3471 OM_uint32 gss_release_cred ( 3472 OM_uint32 *minor_status, 3473 gss_cred_id_t *cred_handle) 3475 Purpose: 3477 Informs GSS-API that the specified credential handle is no longer 3478 required by the application, and frees associated resources. 3479 Implementations are encouraged to set the cred_handle to 3480 GSS_C_NO_CREDENTIAL on successful completion of this call. 3482 Parameters: 3484 cred_handle gss_cred_id_t, modify, optional 3485 Opaque handle identifying credential 3486 to be released. If GSS_C_NO_CREDENTIAL 3487 is supplied, the routine will complete 3488 successfully, but will do nothing. 3490 minor_status Integer, modify 3491 Mechanism specific status code. 3493 Function value: GSS status code 3495 GSS_S_COMPLETE Successful completion 3497 GSS_S_NO_CRED Credentials could not be accessed. 3499 Wray [Page 74 of 101] 3500 7.28.gss_release_name 3502 OM_uint32 gss_release_name ( 3503 OM_uint32 *minor_status, 3504 gss_name_t *name) 3506 Purpose: 3508 Free GSSAPI-allocated storage associated with an internal-form name. 3509 Implementations are encouraged to set the name to GSS_C_NO_NAME on 3510 successful completion of this call. 3512 Parameters: 3514 minor_status Integer, modify 3515 Mechanism specific status code 3517 name gss_name_t, modify 3518 The name to be deleted 3520 Function value: GSS status code 3522 GSS_S_COMPLETE Successful completion 3524 GSS_S_BAD_NAME The name parameter did not contain a valid name 3526 Wray [Page 75 of 101] 3527 7.29.gss_release_oid_set 3529 OM_uint32 gss_release_oid_set ( 3530 OM_uint32 *minor_status, 3531 gss_OID_set *set) 3533 Purpose: 3535 Free storage associated with a GSSAPI-generated gss_OID_set object. 3536 The set parameter must refer to an OID-set that was returned from a 3537 GSSAPI routine. gss_release_oid_set() will free the storage 3538 associated with each individual member OID, the OID set's elements 3539 array, and the gss_OID_set_desc. 3541 Implementations are encouraged to set the gss_OID_set parameter to 3542 GSS_C_NO_OID_SET on successful completion of this routine. 3544 Parameters: 3546 minor_status Integer, modify 3547 Mechanism specific status code 3549 set Set of Object IDs, modify 3550 The storage associated with the gss_OID_set 3551 will be deleted. 3553 Function value: GSS status code 3555 GSS_S_COMPLETE Successful completion 3557 Wray [Page 76 of 101] 3558 7.30.gss_test_oid_set_member 3560 OM_uint32 gss_test_oid_set_member ( 3561 OM_uint32 *minor_status, 3562 const gss_OID member, 3563 const gss_OID_set set, 3564 int *present) 3566 Purpose: 3568 Interrogate an Object Identifier set to determine whether a specified 3569 Object Identifier is a member. This routine is intended to be used 3570 with OID sets returned by gss_indicate_mechs(), gss_acquire_cred(), 3571 and gss_inquire_cred(), but will also work with user-generated sets. 3573 Parameters: 3575 minor_status Integer, modify 3576 Mechanism specific status code 3578 member Object ID, read 3579 The object identifier whose presence 3580 is to be tested. 3582 set Set of Object ID, read 3583 The Object Identifier set. 3585 present Boolean, modify 3586 non-zero if the specified OID is a member 3587 of the set, zero if not. 3589 Function value: GSS status code 3591 GSS_S_COMPLETE Successful completion 3593 Wray [Page 77 of 101] 3594 7.31.gss_unwrap 3596 OM_uint32 gss_unwrap ( 3597 OM_uint32 *minor_status, 3598 const gss_ctx_id_t context_handle, 3599 const gss_buffer_t input_message_buffer, 3600 gss_buffer_t output_message_buffer, 3601 int *conf_state, 3602 gss_qop_t *qop_state) 3604 Purpose: 3606 Converts a message previously protected by gss_wrap back to a usable 3607 form, verifying the embedded MIC. The conf_state parameter indicates 3608 whether the message was encrypted; the qop_state parameter indicates 3609 the strength of protection that was used to provide the 3610 confidentiality and integrity services. 3612 Since some application-level protocols may wish to use tokens emitted 3613 by gss_wrap() to provide "secure framing", implementations must 3614 support the wrapping and unwrapping of zero-length messages. 3616 Parameters: 3618 minor_status Integer, modify 3619 Mechanism specific status code. 3621 context_handle gss_ctx_id_t, read 3622 Identifies the context on which the message 3623 arrived 3625 input_message_buffer buffer, opaque, read 3626 protected message 3628 output_message_buffer buffer, opaque, modify 3629 Buffer to receive unwrapped message. 3630 Storage associated with this buffer must 3631 be freed by the application after use use 3632 with a call to gss_release_buffer(). 3634 conf_state boolean, modify, optional 3635 Non-zero - Confidentiality and integrity 3636 protection were used 3637 Zero - Integrity service only was used 3638 Specify NULL if not required 3640 qop_state gss_qop_t, modify, optional 3641 Quality of protection provided. 3642 Specify NULL if not required 3644 Function value: GSS status code 3646 GSS_S_COMPLETE Successful completion 3648 GSS_S_DEFECTIVE_TOKEN The token failed consistency checks 3650 Wray [Page 78 of 101] 3651 GSS_S_BAD_SIG The MIC was incorrect 3653 GSS_S_DUPLICATE_TOKEN The token was valid, and contained a correct 3654 MIC for the message, but it had already been 3655 processed 3657 GSS_S_OLD_TOKEN The token was valid, and contained a correct MIC 3658 for the message, but it is too old to check for 3659 duplication. 3661 GSS_S_UNSEQ_TOKEN The token was valid, and contained a correct MIC 3662 for the message, but has been verified out of 3663 sequence; a later token has already been 3664 received. 3666 GSS_S_GAP_TOKEN The token was valid, and contained a correct MIC 3667 for the message, but has been verified out of 3668 sequence; an earlier expected token has not yet 3669 been received. 3671 GSS_S_CONTEXT_EXPIRED The context has already expired 3673 GSS_S_NO_CONTEXT The context_handle parameter did not identify 3674 a valid context 3676 Wray [Page 79 of 101] 3677 7.32.gss_verify_mic 3679 OM_uint32 gss_verify_mic ( 3680 OM_uint32 *minor_status, 3681 const gss_ctx_id_t context_handle, 3682 const gss_buffer_t message_buffer, 3683 const gss_buffer_t token_buffer, 3684 gss_qop_t *qop_state) 3686 Purpose: 3688 Verifies that a cryptographic MIC, contained in the token parameter, 3689 fits the supplied message. The qop_state parameter allows a message 3690 recipient to determine the strength of protection that was applied to 3691 the message. 3693 Since some application-level protocols may wish to use tokens emitted 3694 by gss_wrap() to provide "secure framing", implementations must 3695 support the calculation and verification of MICs over zero-length 3696 messages. 3698 Parameters: 3700 minor_status Integer, modify 3701 Mechanism specific status code. 3703 context_handle gss_ctx_id_t, read 3704 Identifies the context on which the message 3705 arrived 3707 message_buffer buffer, opaque, read 3708 Message to be verified 3710 token_buffer buffer, opaque, read 3711 Token associated with message 3713 qop_state gss_qop_t, modify, optional 3714 quality of protection gained from MIC 3715 Specify NULL if not required 3717 Function value: GSS status code 3719 GSS_S_COMPLETE Successful completion 3721 GSS_S_DEFECTIVE_TOKEN The token failed consistency checks 3723 GSS_S_BAD_SIG The MIC was incorrect 3725 GSS_S_DUPLICATE_TOKEN The token was valid, and contained a correct 3726 MIC for the message, but it had already been 3727 processed 3729 GSS_S_OLD_TOKEN The token was valid, and contained a correct MIC 3730 for the message, but it is too old to check for 3731 duplication. 3733 Wray [Page 80 of 101] 3734 GSS_S_UNSEQ_TOKEN The token was valid, and contained a correct MIC 3735 for the message, but has been verified out of 3736 sequence; a later token has already been received. 3738 GSS_S_GAP_TOKEN The token was valid, and contained a correct MIC 3739 for the message, but has been verified out of 3740 sequence; an earlier expected token has not yet 3741 been received. 3743 GSS_S_CONTEXT_EXPIRED The context has already expired 3745 GSS_S_NO_CONTEXT The context_handle parameter did not identify a 3746 valid context 3748 Wray [Page 81 of 101] 3749 7.33.gss_wrap 3751 OM_uint32 gss_wrap ( 3752 OM_uint32 *minor_status, 3753 const gss_ctx_id_t context_handle, 3754 int conf_req_flag, 3755 gss_qop_t qop_req 3756 const gss_buffer_t input_message_buffer, 3757 int *conf_state, 3758 gss_buffer_t output_message_buffer ) 3760 Purpose: 3762 Attaches a cryptographic MIC and optionally encrypts the specified 3763 input_message. The output_message contains both the MIC and the 3764 message. The qop_req parameter allows a choice between several 3765 cryptographic algorithms, if supported by the chosen mechanism. 3767 Since some application-level protocols may wish to use tokens emitted 3768 by gss_wrap() to provide "secure framing", implementations must 3769 support the wrapping of zero-length messages. 3771 Parameters: 3773 minor_status Integer, modify 3774 Mechanism specific status code. 3776 context_handle gss_ctx_id_t, read 3777 Identifies the context on which the message 3778 will be sent 3780 conf_req_flag boolean, read 3781 Non-zero - Both confidentiality and integrity 3782 services are requested 3783 Zero - Only integrity service is requested 3785 qop_req gss_qop_t, read, optional 3786 Specifies required quality of protection. A 3787 mechanism-specific default may be requested by 3788 setting qop_req to GSS_C_QOP_DEFAULT. If an 3789 unsupported protection strength is requested, 3790 gss_wrap will return a major_status of 3791 GSS_S_BAD_QOP. 3793 input_message_buffer buffer, opaque, read 3794 Message to be protected 3796 conf_state boolean, modify, optional 3797 Non-zero - Confidentiality, data origin 3798 authentication and integrity 3799 services have been applied 3800 Zero - Integrity and data origin services only 3801 has been applied. 3802 Specify NULL if not required 3804 Wray [Page 82 of 101] 3805 output_message_buffer buffer, opaque, modify 3806 Buffer to receive protected message. 3807 Storage associated with this message must 3808 be freed by the application after use with 3809 a call to gss_release_buffer(). 3811 Function value: GSS status code 3813 GSS_S_COMPLETE Successful completion 3815 GSS_S_CONTEXT_EXPIRED The context has already expired 3817 GSS_S_NO_CONTEXT The context_handle parameter did not identify a 3818 valid context 3820 GSS_S_BAD_QOP The specified QOP is not supported by the 3821 mechanism. 3823 Wray [Page 83 of 101] 3824 7.34.gss_wrap_size_limit 3826 OM_uint32 gss_wrap_size_limit ( 3827 OM_uint32 *minor_status, 3828 const gss_ctx_id_t context_handle, 3829 int conf_req_flag, 3830 gss_qop_t qop_req, 3831 OM_uint32 req_output_size, 3832 OM_uint32 *max_input_size) 3834 Purpose: 3836 Allows an application to determine the maximum message size that, if 3837 presented to gss_wrap with the same conf_req_flag and qop_req 3838 parameters, will result in an output token containing no more than 3839 req_output_size bytes. 3841 This call is intended for use by applications that communicate over 3842 protocols that impose a maximum message size. It enables the 3843 application to fragment messages prior to applying protection. 3845 GSSAPI implementations are recommended but not required to detect 3846 invalid QOP values when gss_wrap_size_limit() is called. This routine 3847 guarantees only a maximum message size, not the availability of 3848 specific QOP values for message protection. 3850 Successful completion of this call does not guarantee that gss_wrap 3851 will be able to protect a message of length max_input_size bytes, 3852 since this ability may depend on the availability of system resources 3853 at the time that gss_wrap is called. However, if the implementation 3854 itself imposes an upper limit on the length of messages that may be 3855 processed by gss_wrap, the implementation should not return a value 3856 via max_input_bytes that is greater than this length. 3858 Parameters: 3860 minor_status Integer, modify 3861 Mechanism specific status code 3863 context_handle gss_ctx_id_t, read 3864 A handle that refers to the security over 3865 which the messages will be sent. 3867 conf_req_flag Boolean, read 3868 Indicates whether gss_wrap will be asked 3869 to apply confidentiality protection in 3870 addition to integrity protection. See 3871 the routine description for gss_wrap 3872 for more details. 3874 qop_req gss_qop_t, read 3875 Indicates the level of protection that 3876 gss_wrap will be asked to provide. See 3877 the routine description for gss_wrap for 3878 more details. 3880 Wray [Page 84 of 101] 3881 req_output_size Integer, read 3882 The desired maximum size for tokens emitted 3883 by gss_wrap. 3885 max_input_size Integer, modify 3886 The maximum input message size that may 3887 be presented to gss_wrap in order to 3888 guarantee that the emitted token shall 3889 be no larger than req_output_size bytes. 3891 Function value: GSS status code 3893 GSS_S_COMPLETE Successful completion 3895 GSS_S_NO_CONTEXT The referenced context could not be accessed. 3897 GSS_S_CONTEXT_EXPIRED The context has expired. 3899 GSS_S_BAD_QOP The specified QOP is not supported by the 3900 mechanism. 3902 Wray [Page 85 of 101] 3903 APPENDIX A. GSS-API C header file gssapi.h 3905 C-language GSS-API implementations should include a copy of the 3906 following header-file. 3908 #ifndef GSSAPI_H_ 3909 #define GSSAPI_H_ 3911 /* 3912 * First, include stddef.h to get size_t defined. 3913 */ 3914 #include 3916 /* 3917 * If the platform supports the xom.h header file, it should be 3918 * included here. 3919 */ 3920 #include 3922 /* 3923 * Now define the three implementation-dependent types. 3924 */ 3925 typedef gss_ctx_id_t; 3926 typedef gss_cred_id_t; 3927 typedef gss_name_t; 3929 /* 3930 * The following type must be defined as the smallest natural 3931 * unsigned integer supported by the platform that has at least 3932 * 32 bits of precision. 3933 */ 3934 typedef gss_uint32; 3936 #ifdef OM_STRING 3937 /* 3938 * We have included the xom.h header file. Verify that OM_uint32 3939 * is defined correctly. 3940 */ 3942 #if sizeof(gss_uint32) != sizeof(OM_uint32) 3943 #error Incompatible definition of OM_uint32 from xom.h 3944 #endif 3946 typedef OM_object_identifier gss_OID_desc, *gss_OID; 3948 #else 3950 /* 3951 * We can't use X/Open definitions, so roll our own. 3952 */ 3954 Wray [Page 86 of 101] 3955 typedef gss_uint32 OM_uint32; 3957 typedef struct gss_OID_desc_struct { 3958 OM_uint32 length; 3959 void *elements; 3960 } gss_OID_desc, *gss_OID; 3962 #endif 3964 typedef struct gss_OID_set_desc_struct { 3965 size_t count; 3966 gss_OID elements; 3967 } gss_OID_set_desc, *gss_OID_set; 3969 typedef struct gss_buffer_desc_struct { 3970 size_t length; 3971 void *value; 3972 } gss_buffer_desc, *gss_buffer_t; 3974 typedef struct gss_channel_bindings_struct { 3975 OM_uint32 initiator_addrtype; 3976 gss_buffer_desc initiator_address; 3977 OM_uint32 acceptor_addrtype; 3978 gss_buffer_desc acceptor_address; 3979 gss_buffer_desc application_data; 3980 } *gss_channel_bindings_t; 3982 /* 3983 * For now, define a QOP-type as an OM_uint32 3984 */ 3985 typedef OM_uint32 gss_qop_t; 3987 typedef int gss_cred_usage_t; 3989 /* 3990 * Flag bits for context-level services. 3991 */ 3992 #define GSS_C_DELEG_FLAG 1 3993 #define GSS_C_MUTUAL_FLAG 2 3994 #define GSS_C_REPLAY_FLAG 4 3995 #define GSS_C_SEQUENCE_FLAG 8 3996 #define GSS_C_CONF_FLAG 16 3997 #define GSS_C_INTEG_FLAG 32 3998 #define GSS_C_ANON_FLAG 64 3999 #define GSS_C_PROT_READY_FLAG 128 4000 #define GSS_C_TRANS_FLAG 256 4002 /* 4003 * Credential usage options 4004 */ 4005 #define GSS_C_BOTH 0 4006 #define GSS_C_INITIATE 1 4007 #define GSS_C_ACCEPT 2 4009 Wray [Page 87 of 101] 4010 /* 4011 * Status code types for gss_display_status 4012 */ 4013 #define GSS_C_GSS_CODE 1 4014 #define GSS_C_MECH_CODE 2 4016 /* 4017 * The constant definitions for channel-bindings address families 4018 */ 4019 #define GSS_C_AF_UNSPEC 0 4020 #define GSS_C_AF_LOCAL 1 4021 #define GSS_C_AF_INET 2 4022 #define GSS_C_AF_IMPLINK 3 4023 #define GSS_C_AF_PUP 4 4024 #define GSS_C_AF_CHAOS 5 4025 #define GSS_C_AF_NS 6 4026 #define GSS_C_AF_NBS 7 4027 #define GSS_C_AF_ECMA 8 4028 #define GSS_C_AF_DATAKIT 9 4029 #define GSS_C_AF_CCITT 10 4030 #define GSS_C_AF_SNA 11 4031 #define GSS_C_AF_DECnet 12 4032 #define GSS_C_AF_DLI 13 4033 #define GSS_C_AF_LAT 14 4034 #define GSS_C_AF_HYLINK 15 4035 #define GSS_C_AF_APPLETALK 16 4036 #define GSS_C_AF_BSC 17 4037 #define GSS_C_AF_DSS 18 4038 #define GSS_C_AF_OSI 19 4039 #define GSS_C_AF_X25 21 4041 #define GSS_C_AF_NULLADDR 255 4043 /* 4044 * Various Null values 4045 */ 4046 #define GSS_C_NO_NAME ((gss_name_t) 0) 4047 #define GSS_C_NO_BUFFER ((gss_buffer_t) 0) 4048 #define GSS_C_NO_OID ((gss_OID) 0) 4049 #define GSS_C_NO_OID_SET ((gss_OID_set) 0) 4050 #define GSS_C_NO_CONTEXT ((gss_ctx_id_t) 0) 4051 #define GSS_C_NO_CREDENTIAL ((gss_cred_id_t) 0) 4052 #define GSS_C_NO_CHANNEL_BINDINGS ((gss_channel_bindings_t) 0) 4053 #define GSS_C_EMPTY_BUFFER {0, NULL} 4055 /* 4056 * Some alternate names for a couple of the above 4057 * values. These are defined for V1 compatibility. 4058 */ 4059 #define GSS_C_NULL_OID GSS_C_NO_OID 4060 #define GSS_C_NULL_OID_SET GSS_C_NO_OID_SET 4062 /* 4063 * Define the default Quality of Protection for per-message 4064 * services. Note that an implementation that offers multiple 4066 Wray [Page 88 of 101] 4067 * levels of QOP may define GSS_C_QOP_DEFAULT to be either zero 4068 * (as done here) to mean "default protection", or to a specific 4069 * explicit QOP value. However, a value of 0 should always be 4070 * interpreted by a GSSAPI implementation as a request for the 4071 * default protection level. 4072 */ 4073 #define GSS_C_QOP_DEFAULT 0 4075 /* 4076 * Expiration time of 2^32-1 seconds means infinite lifetime for a 4077 * credential or security context 4078 */ 4079 #define GSS_C_INDEFINITE 0xfffffffful 4081 /* 4082 * The implementation must reserve static storage for a 4083 * gss_OID_desc object containing the value 4084 * {10, (void *)"\x2a\x86\x48\x86\xf7\x12" 4085 * "\x01\x02\x01\x01"}, 4086 * corresponding to an object-identifier value of 4087 * {iso(1) member-body(2) United States(840) mit(113554) 4088 * infosys(1) gssapi(2) generic(1) user_name(1)}. The constant 4089 * GSS_C_NT_USER_NAME should be initialized to point 4090 * to that gss_OID_desc. 4091 */ 4092 extern gss_OID GSS_C_NT_USER_NAME; 4094 /* 4095 * The implementation must reserve static storage for a 4096 * gss_OID_desc object containing the value 4097 * {10, (void *)"\x2a\x86\x48\x86\xf7\x12" 4098 * "\x01\x02\x01\x02"}, 4099 * corresponding to an object-identifier value of 4100 * {iso(1) member-body(2) United States(840) mit(113554) 4101 * infosys(1) gssapi(2) generic(1) machine_uid_name(2)}. 4102 * The constant GSS_C_NT_MACHINE_UID_NAME should be 4103 * initialized to point to that gss_OID_desc. 4104 */ 4105 extern gss_OID GSS_C_NT_MACHINE_UID_NAME; 4107 /* 4108 * The implementation must reserve static storage for a 4109 * gss_OID_desc object containing the value 4110 * {10, (void *)"\x2a\x86\x48\x86\xf7\x12" 4111 * "\x01\x02\x01\x03"}, 4112 * corresponding to an object-identifier value of 4113 * {iso(1) member-body(2) United States(840) mit(113554) 4114 * infosys(1) gssapi(2) generic(1) string_uid_name(3)}. 4115 * The constant GSS_C_NT_STRING_UID_NAME should be 4116 * initialized to point to that gss_OID_desc. 4117 */ 4118 extern gss_OID GSS_C_NT_STRING_UID_NAME; 4120 /* 4121 * The implementation must reserve static storage for a 4123 Wray [Page 89 of 101] 4124 * gss_OID_desc object containing the value 4125 * {6, (void *)"\x2b\x06\x01\x05\x06\x02"}, 4126 * corresponding to an object-identifier value of 4127 * {iso(1) org(3) dod(6) internet(1) security(5) 4128 * nametypes(6) gss-host-based-services(2)). The constant 4129 * GSS_C_NT_HOSTBASED_SERVICE_X should be initialized to point 4130 * to that gss_OID_desc. This is a deprecated OID value, and 4131 * implementations wishing to support hostbased-service names 4132 * should instead use the GSS_C_NT_HOSTBASED_SERVICE OID, 4133 * defined below, to identify such names; 4134 * GSS_C_NT_HOSTBASED_SERVICE_X should be accepted a synonym 4135 * for GSS_C_NT_HOSTBASED_SERVICE when presented as an input 4136 * parameter, but should not be emitted by GSSAPI 4137 * implementations 4138 */ 4139 extern gss_OID GSS_C_NT_HOSTBASED_SERVICE_X; 4141 /* 4142 * The implementation must reserve static storage for a 4143 * gss_OID_desc object containing the value 4144 * {10, (void *)"\x2a\x86\x48\x86\xf7\x12" 4145 * "\x01\x02\x01\x04"}, corresponding to an 4146 * object-identifier value of {iso(1) member-body(2) 4147 * Unites States(840) mit(113554) infosys(1) gssapi(2) 4148 * generic(1) service_name(4)}. The constant 4149 * GSS_C_NT_HOSTBASED_SERVICE should be initialized 4150 * to point to that gss_OID_desc. 4151 */ 4152 extern gss_OID GSS_C_NT_HOSTBASED_SERVICE; 4154 /* 4155 * The implementation must reserve static storage for a 4156 * gss_OID_desc object containing the value 4157 * {6, (void *)"\x2b\x06\01\x05\x06\x03"}, 4158 * corresponding to an object identifier value of 4159 * {1(iso), 3(org), 6(dod), 1(internet), 5(security), 4160 * 6(nametypes), 3(gss-anonymous-name)}. The constant 4161 * and GSS_C_NT_ANONYMOUS should be initialized to point 4162 * to that gss_OID_desc. 4163 */ 4164 extern gss_OID GSS_C_NT_ANONYMOUS; 4166 /* 4167 * The implementation must reserve static storage for a 4168 * gss_OID_desc object containing the value 4169 * {6, (void *)"\x2b\x06\x01\x05\x06\x04"}, 4170 * corresponding to an object-identifier value of 4171 * {1(iso), 3(org), 6(dod), 1(internet), 5(security), 4172 * 6(nametypes), 4(gss-api-exported-name)}. The constant 4173 * GSS_C_NT_EXPORT_NAME should be initialized to point 4174 * to that gss_OID_desc. 4175 */ 4176 extern gss_OID GSS_C_NT_EXPORT_NAME; 4178 Wray [Page 90 of 101] 4179 /* Major status codes */ 4181 #define GSS_S_COMPLETE 0 4183 /* 4184 * Some "helper" definitions to make the status code macros obvious. 4185 */ 4186 #define GSS_C_CALLING_ERROR_OFFSET 24 4187 #define GSS_C_ROUTINE_ERROR_OFFSET 16 4188 #define GSS_C_SUPPLEMENTARY_OFFSET 0 4189 #define GSS_C_CALLING_ERROR_MASK 0377ul 4190 #define GSS_C_ROUTINE_ERROR_MASK 0377ul 4191 #define GSS_C_SUPPLEMENTARY_MASK 0177777ul 4193 /* 4194 * The macros that test status codes for error conditions. 4195 * Note that the GSS_ERROR() macro has changed slightly from 4196 * the V1 GSSAPI so that it now evaluates its argument 4197 * only once. 4198 */ 4199 #define GSS_CALLING_ERROR(x) \ 4200 (x & (GSS_C_CALLING_ERROR_MASK << GSS_C_CALLING_ERROR_OFFSET)) 4201 #define GSS_ROUTINE_ERROR(x) \ 4202 (x & (GSS_C_ROUTINE_ERROR_MASK << GSS_C_ROUTINE_ERROR_OFFSET)) 4203 #define GSS_SUPPLEMENTARY_INFO(x) \ 4204 (x & (GSS_C_SUPPLEMENTARY_MASK << GSS_C_SUPPLEMENTARY_OFFSET)) 4205 #define GSS_ERROR(x) \ 4206 (x & ((GSS_C_CALLING_ERROR_MASK << GSS_C_CALLING_ERROR_OFFSET) | \ 4207 (GSS_C_ROUTINE_ERROR_MASK << GSS_C_ROUTINE_ERROR_OFFSET))) 4209 /* 4210 * Now the actual status code definitions 4211 */ 4213 /* 4214 * Calling errors: 4215 */ 4216 #define GSS_S_CALL_INACCESSIBLE_READ \ 4217 (1ul << GSS_C_CALLING_ERROR_OFFSET) 4218 #define GSS_S_CALL_INACCESSIBLE_WRITE \ 4219 (2ul << GSS_C_CALLING_ERROR_OFFSET) 4220 #define GSS_S_CALL_BAD_STRUCTURE \ 4221 (3ul << GSS_C_CALLING_ERROR_OFFSET) 4223 /* 4224 * Routine errors: 4225 */ 4226 #define GSS_S_BAD_MECH (1ul << 4227 GSS_C_ROUTINE_ERROR_OFFSET) 4228 #define GSS_S_BAD_NAME (2ul << 4229 GSS_C_ROUTINE_ERROR_OFFSET) 4230 #define GSS_S_BAD_NAMETYPE (3ul << 4231 GSS_C_ROUTINE_ERROR_OFFSET) 4233 Wray [Page 91 of 101] 4234 #define GSS_S_BAD_BINDINGS (4ul << 4235 GSS_C_ROUTINE_ERROR_OFFSET) 4236 #define GSS_S_BAD_STATUS (5ul << 4237 GSS_C_ROUTINE_ERROR_OFFSET) 4238 #define GSS_S_BAD_SIG (6ul << 4239 GSS_C_ROUTINE_ERROR_OFFSET) 4240 #define GSS_S_BAD_MIC GSS_S_BAD_SIG 4241 #define GSS_S_NO_CRED (7ul << 4242 GSS_C_ROUTINE_ERROR_OFFSET) 4243 #define GSS_S_NO_CONTEXT (8ul << 4244 GSS_C_ROUTINE_ERROR_OFFSET) 4245 #define GSS_S_DEFECTIVE_TOKEN (9ul << 4246 GSS_C_ROUTINE_ERROR_OFFSET) 4247 #define GSS_S_DEFECTIVE_CREDENTIAL (10ul << 4248 GSS_C_ROUTINE_ERROR_OFFSET) 4249 #define GSS_S_CREDENTIALS_EXPIRED (11ul << 4250 GSS_C_ROUTINE_ERROR_OFFSET) 4251 #define GSS_S_CONTEXT_EXPIRED (12ul << 4252 GSS_C_ROUTINE_ERROR_OFFSET) 4253 #define GSS_S_FAILURE (13ul << 4254 GSS_C_ROUTINE_ERROR_OFFSET) 4255 #define GSS_S_BAD_QOP (14ul << 4256 GSS_C_ROUTINE_ERROR_OFFSET) 4257 #define GSS_S_UNAUTHORIZED (15ul << 4258 GSS_C_ROUTINE_ERROR_OFFSET) 4259 #define GSS_S_UNAVAILABLE (16ul << 4260 GSS_C_ROUTINE_ERROR_OFFSET) 4261 #define GSS_S_DUPLICATE_ELEMENT (17ul << 4262 GSS_C_ROUTINE_ERROR_OFFSET) 4263 #define GSS_S_NAME_NOT_MN (18ul << 4264 GSS_C_ROUTINE_ERROR_OFFSET) 4266 /* 4267 * Supplementary info bits: 4268 */ 4269 #define GSS_S_CONTINUE_NEEDED \ 4270 (1ul << (GSS_C_SUPPLEMENTARY_OFFSET + 0)) 4271 #define GSS_S_DUPLICATE_TOKEN \ 4272 (1ul << (GSS_C_SUPPLEMENTARY_OFFSET + 1)) 4273 #define GSS_S_OLD_TOKEN \ 4274 (1ul << (GSS_C_SUPPLEMENTARY_OFFSET + 2)) 4275 #define GSS_S_UNSEQ_TOKEN \ 4276 (1ul << (GSS_C_SUPPLEMENTARY_OFFSET + 3)) 4277 #define GSS_S_GAP_TOKEN \ 4278 (1ul << (GSS_C_SUPPLEMENTARY_OFFSET + 4)) 4280 /* 4281 * Finally, function prototypes for the GSS-API routines. 4282 */ 4284 OM_uint32 gss_acquire_cred 4285 (OM_uint32 , /* minor_status */ 4286 const gss_name_t, /* desired_name */ 4287 OM_uint32, /* time_req */ 4288 const gss_OID_set, /* desired_mechs */ 4290 Wray [Page 92 of 101] 4291 gss_cred_usage_t, /* cred_usage */ 4292 gss_cred_id_t , /* output_cred_handle */ 4293 gss_OID_set , /* actual_mechs */ 4294 OM_uint32 * /* time_rec */ 4295 ); 4297 OM_uint32 gss_release_cred 4298 (OM_uint32 , /* minor_status */ 4299 gss_cred_id_t * /* cred_handle */ 4300 ); 4302 OM_uint32 gss_init_sec_context 4303 (OM_uint32 , /* minor_status */ 4304 const gss_cred_id_t, /* initiator_cred_handle */ 4305 gss_ctx_id_t , /* context_handle */ 4306 const gss_name_t, /* target_name */ 4307 const gss_OID, /* mech_type */ 4308 OM_uint32, /* req_flags */ 4309 OM_uint32, /* time_req */ 4310 const gss_channel_bindings_t, 4311 /* input_chan_bindings */ 4312 const gss_buffer_t, /* input_token */ 4313 gss_OID , /* actual_mech_type */ 4314 gss_buffer_t, /* output_token */ 4315 OM_uint32 , /* ret_flags */ 4316 OM_uint32 * /* time_rec */ 4317 ); 4319 OM_uint32 gss_accept_sec_context 4320 (OM_uint32 , /* minor_status */ 4321 gss_ctx_id_t , /* context_handle */ 4322 const gss_cred_id_t, /* acceptor_cred_handle */ 4323 const gss_buffer_t, /* input_token_buffer */ 4324 const gss_channel_bindings_t, 4325 /* input_chan_bindings */ 4326 gss_name_t , /* src_name */ 4327 gss_OID , /* mech_type */ 4328 gss_buffer_t, /* output_token */ 4329 OM_uint32 , /* ret_flags */ 4330 OM_uint32 , /* time_rec */ 4331 gss_cred_id_t * /* delegated_cred_handle */ 4332 ); 4334 OM_uint32 gss_process_context_token 4335 (OM_uint32 , /* minor_status */ 4336 const gss_ctx_id_t, /* context_handle */ 4337 const gss_buffer_t /* token_buffer */ 4338 ); 4340 OM_uint32 gss_delete_sec_context 4341 (OM_uint32 , /* minor_status */ 4342 gss_ctx_id_t , /* context_handle */ 4343 gss_buffer_t /* output_token */ 4344 ); 4346 Wray [Page 93 of 101] 4347 OM_uint32 gss_context_time 4348 (OM_uint32 , /* minor_status */ 4349 const gss_ctx_id_t, /* context_handle */ 4350 OM_uint32 * /* time_rec */ 4351 ); 4353 OM_uint32 gss_get_mic 4354 (OM_uint32 , /* minor_status */ 4355 const gss_ctx_id_t, /* context_handle */ 4356 gss_qop_t, /* qop_req */ 4357 const gss_buffer_t, /* message_buffer */ 4358 gss_buffer_t /* message_token */ 4359 ); 4361 OM_uint32 gss_verify_mic 4362 (OM_uint32 , /* minor_status */ 4363 const gss_ctx_id_t, /* context_handle */ 4364 const gss_buffer_t, /* message_buffer */ 4365 const gss_buffer_t, /* token_buffer */ 4366 gss_qop_t * /* qop_state */ 4367 ); 4369 OM_uint32 gss_wrap 4370 (OM_uint32 , /* minor_status */ 4371 const gss_ctx_id_t, /* context_handle */ 4372 int, /* conf_req_flag */ 4373 gss_qop_t, /* qop_req */ 4374 const gss_buffer_t, /* input_message_buffer */ 4375 int , /* conf_state */ 4376 gss_buffer_t /* output_message_buffer */ 4377 ); 4379 OM_uint32 gss_unwrap 4380 (OM_uint32 , /* minor_status */ 4381 const gss_ctx_id_t, /* context_handle */ 4382 const gss_buffer_t, /* input_message_buffer */ 4383 gss_buffer_t, /* output_message_buffer */ 4384 int , /* conf_state */ 4385 gss_qop_t * /* qop_state */ 4386 ); 4388 OM_uint32 gss_display_status 4389 (OM_uint32 , /* minor_status */ 4390 OM_uint32, /* status_value */ 4391 int, /* status_type */ 4392 const gss_OID, /* mech_type */ 4393 OM_uint32 , /* message_context */ 4394 gss_buffer_t /* status_string */ 4395 ); 4397 OM_uint32 gss_indicate_mechs 4399 Wray [Page 94 of 101] 4400 (OM_uint32 , /* minor_status */ 4401 gss_OID_set * /* mech_set */ 4402 ); 4404 OM_uint32 gss_compare_name 4405 (OM_uint32 , /* minor_status */ 4406 const gss_name_t, /* name1 */ 4407 const gss_name_t, /* name2 */ 4408 int * /* name_equal */ 4409 ); 4411 OM_uint32 gss_display_name 4412 (OM_uint32 , /* minor_status */ 4413 const gss_name_t, /* input_name */ 4414 gss_buffer_t, /* output_name_buffer */ 4415 gss_OID * /* output_name_type */ 4416 ); 4418 OM_uint32 gss_import_name 4419 (OM_uint32 , /* minor_status */ 4420 const gss_buffer_t, /* input_name_buffer */ 4421 const gss_OID, /* input_name_type */ 4422 gss_name_t * /* output_name */ 4423 ); 4425 OM_uint32 gss_export_name 4426 (OM_uint32, /* minor_status */ 4427 const gss_name_t, /* input_name */ 4428 gss_buffer_t /* exported_name */ 4429 ); 4431 OM_uint32 gss_release_name 4432 (OM_uint32 *, /* minor_status */ 4433 gss_name_t * /* input_name */ 4434 ); 4436 OM_uint32 gss_release_buffer 4437 (OM_uint32 , /* minor_status */ 4438 gss_buffer_t /* buffer */ 4439 ); 4441 OM_uint32 gss_release_oid_set 4442 (OM_uint32 , /* minor_status */ 4443 gss_OID_set * /* set */ 4444 ); 4446 OM_uint32 gss_inquire_cred 4447 (OM_uint32 , /* minor_status */ 4448 const gss_cred_id_t, /* cred_handle */ 4449 gss_name_t , /* name */ 4450 OM_uint32 , /* lifetime */ 4451 gss_cred_usage_t , /* cred_usage */ 4452 gss_OID_set * /* mechanisms */ 4453 ); 4455 Wray [Page 95 of 101] 4456 OM_uint32 gss_inquire_context ( 4457 OM_uint32 , /* minor_status */ 4458 const gss_ctx_id_t, /* context_handle */ 4459 gss_name_t , /* src_name */ 4460 gss_name_t , /* targ_name */ 4461 OM_uint32 , /* lifetime_rec */ 4462 gss_OID , /* mech_type */ 4463 OM_uint32 , /* ctx_flags */ 4464 int , /* locally_initiated */ 4465 int * /* open */ 4466 ); 4468 OM_uint32 gss_wrap_size_limit ( 4469 OM_uint32 , /* minor_status */ 4470 const gss_ctx_id_t, /* context_handle */ 4471 int, /* conf_req_flag */ 4472 gss_qop_t, /* qop_req */ 4473 OM_uint32, /* req_output_size */ 4474 OM_uint32 * /* max_input_size */ 4475 ); 4477 OM_uint32 gss_add_cred ( 4478 OM_uint32 , /* minor_status */ 4479 const gss_cred_id_t, /* input_cred_handle */ 4480 const gss_name_t, /* desired_name */ 4481 const gss_OID, /* desired_mech */ 4482 gss_cred_usage_t, /* cred_usage */ 4483 OM_uint32, /* initiator_time_req */ 4484 OM_uint32, /* acceptor_time_req */ 4485 gss_cred_id_t , /* output_cred_handle */ 4486 gss_OID_set , /* actual_mechs */ 4487 OM_uint32 , /* initiator_time_rec */ 4488 OM_uint32 * /* acceptor_time_rec */ 4489 ); 4491 OM_uint32 gss_inquire_cred_by_mech ( 4492 OM_uint32 , /* minor_status */ 4493 const gss_cred_id_t, /* cred_handle */ 4494 const gss_OID, /* mech_type */ 4495 gss_name_t , /* name */ 4496 OM_uint32 , /* initiator_lifetime */ 4497 OM_uint32 , /* acceptor_lifetime */ 4498 gss_cred_usage_t * /* cred_usage */ 4499 ); 4501 OM_uint32 gss_export_sec_context ( 4502 OM_uint32 , /* minor_status */ 4503 gss_ctx_id_t , /* context_handle */ 4504 gss_buffer_t /* interprocess_token */ 4505 ); 4507 OM_uint32 gss_import_sec_context ( 4508 OM_uint32 , /* minor_status */ 4509 const gss_buffer_t, /* interprocess_token */ 4510 gss_ctx_id_t * /* context_handle */ 4512 Wray [Page 96 of 101] 4513 ); 4515 OM_uint32 gss_create_empty_oid_set ( 4516 OM_uint32 , /* minor_status */ 4517 gss_OID_set * /* oid_set */ 4518 ); 4520 OM_uint32 gss_add_oid_set_member ( 4521 OM_uint32 , /* minor_status */ 4522 const gss_OID, /* member_oid */ 4523 gss_OID_set * /* oid_set */ 4524 ); 4526 OM_uint32 gss_test_oid_set_member ( 4527 OM_uint32 , /* minor_status */ 4528 const gss_OID, /* member */ 4529 const gss_OID_set, /* set */ 4530 int * /* present */ 4531 ); 4533 OM_uint32 gss_inquire_names_for_mech ( 4534 OM_uint32 , /* minor_status */ 4535 const gss_OID, /* mechanism */ 4536 gss_OID_set * /* name_types */ 4537 ); 4539 OM_uint32 gss_inquire_mechs_for_name ( 4540 OM_uint32 , /* minor_status */ 4541 const gss_name_t, /* input_name */ 4542 gss_OID_set * /* mech_types */ 4543 ); 4545 OM_uint32 gss_canonicalize_name ( 4546 OM_uint32 , /* minor_status */ 4547 const gss_name_t, /* input_name */ 4548 const gss_OID, /* mech_type */ 4549 gss_name_t * /* output_name */ 4550 ); 4552 OM_uint32 gss_duplicate_name ( 4553 OM_uint32 , /* minor_status */ 4554 const gss_name_t, /* src_name */ 4555 gss_name_t * /* dest_name */ 4556 ); 4558 /* 4559 * The following routines are obsolete variants of gss_get_mic, 4560 * gss_verify_mic, gss_wrap and gss_unwrap. They should be 4561 * provided by GSSAPI V2 implementations for backwards 4562 * compatibility with V1 applications. Distinct entrypoints 4563 * (as opposed to #defines) should be provided, both to allow 4564 * GSSAPI V1 applications to link against GSSAPI V2 implementations, 4565 * and to retain the slight parameter type differences between the 4566 * obsolete versions of these routines and their current forms. 4567 */ 4569 Wray [Page 97 of 101] 4570 OM_uint32 gss_sign 4571 (OM_uint32 , /* minor_status */ 4572 gss_ctx_id_t, /* context_handle */ 4573 int, /* qop_req */ 4574 gss_buffer_t, /* message_buffer */ 4575 gss_buffer_t /* message_token */ 4576 ); 4578 OM_uint32 gss_verify 4579 (OM_uint32 , /* minor_status */ 4580 gss_ctx_id_t, /* context_handle */ 4581 gss_buffer_t, /* message_buffer */ 4582 gss_buffer_t, /* token_buffer */ 4583 int * /* qop_state */ 4584 ); 4586 OM_uint32 gss_seal 4587 (OM_uint32 , /* minor_status */ 4588 gss_ctx_id_t, /* context_handle */ 4589 int, /* conf_req_flag */ 4590 int, /* qop_req */ 4591 gss_buffer_t, /* input_message_buffer */ 4592 int , /* conf_state */ 4593 gss_buffer_t /* output_message_buffer */ 4594 ); 4596 OM_uint32 gss_unseal 4597 (OM_uint32 , /* minor_status */ 4598 gss_ctx_id_t, /* context_handle */ 4599 gss_buffer_t, /* input_message_buffer */ 4600 gss_buffer_t, /* output_message_buffer */ 4601 int , /* conf_state */ 4602 int * /* qop_state */ 4603 ); 4605 #endif /* GSSAPI_H_ */ 4607 APPENDIX B. Additional constraints for application binary portability 4609 The purpose of this C-bindings document is to encourage source-level 4610 portability of applications across GSS-API implementations on 4611 different platforms and atop different mechanisms. Additional goals 4612 that have not been explicitly addressed by this document are 4613 link-time and run-time portability. 4615 Wray [Page 98 of 101] 4616 Link-time portability provides the ability to compile an application 4617 against one implementation of GSS-API, and then link it against a 4618 different implementation on the same platform. It is a stricter 4619 requirement than source-level portability. 4621 Run-time portability differs from link-time portability only on those 4622 platforms that implement dynamically loadable GSS-API 4623 implementations, but do not offer load-time symbol resolution. On 4624 such platforms, run-time portability is a stricter requirement than 4625 link-time portability, and will typically include the precise 4626 placement of the various GSS-API routines within library entrypoint 4627 vectors. 4629 Individual platforms will impose their own rules that must be 4630 followed to achieve link-time (and run-time, if different) 4631 portability. In order to ensure either form of binary portability, 4632 an ABI specification must be written for GSS-API implementations on 4633 that platform. However, it is recognized that there are some issues 4634 that are likely to be common to all such ABI specifications. This 4635 appendix is intended to be a repository for such common issues, and 4636 contains some suggestions that individual ABI specifications may 4637 choose to reference. Since machine architectures vary greatly, it may 4638 not be possible or desirable to follow these suggestions on all 4639 platforms. 4641 B.1. Pointers 4643 While ANSI-C provides a single pointer type for each declared type, 4644 plus a single (void *) type, some platforms (notably those using 4645 segmented memory architectures) augment this with various modified 4646 pointer types (e.g. far pointers, near pointers). These language 4647 bindings assume ANSI-C, and thus do not address such non-standard 4648 implementations. GSS-API implementations for such platforms must 4649 choose an appropriate memory model, and should use it consistently 4650 throughout. For example, if a memory model is chosen that requires 4651 the use of far pointers when passing routine parameters, then far 4652 pointers should also be used within the structures defined by 4653 GSS-API. 4655 B.2. Internal structure alignment 4657 GSS-API defines several data-structures containing differently-sized 4658 fields. An ABI specification should include a detailed description 4659 of how the fields of such structures are aligned, and if there is any 4660 internal padding in these data structures. The use of compiler 4661 defaults for the platform is recommended. 4663 B.3. Handle types 4665 The C bindings specify that the gss_cred_id_t and gss_ctx_id_t types 4666 should be implemented as either pointer or arithmetic types, and that 4667 if pointer types are used, care should be taken to ensure that two 4669 Wray [Page 99 of 101] 4670 handles may be compared with the == operator. Note that ANSI-C does 4671 not guarantee that two pointer values may be compared with the == 4672 operator unless either the two pointers point to members of a single 4673 array, or at least one of the pointers contains a NULL value. 4675 For binary portability, additional constraints are required. The 4676 following is an attempt at defining platform-independent constraints. 4678 The size of the handle type must be the same as sizeof(void *), using 4679 the appropriate memory model. 4681 The == operator for the chosen type must be a simple bit-wise 4682 comparison. That is, for two in-memory handle objects h1 and h2, the 4683 boolean value of the expression 4685 (h1 == h2) 4687 should always be the same as the boolean value of the expression 4689 (memcmp(&h1, &h2, sizeof(h1)) == 0) 4691 The actual use of the type (void *) for handle types is discouraged, 4692 not for binary portability reasons, but since it effectively disables 4693 much of the compile-time type-checking that the compiler can 4694 otherwise perform, and is therefore not "programmer-friendly". If a 4695 pointer implementation is desired, and if the platform's 4696 implementation of pointers permits, the handles should be implemented 4697 as pointers to distinct implementation-defined types. 4699 B.4. The gss_name_t type 4701 The gss_name_t type, representing the internal name object, should be 4702 implemented as a pointer type. The use of the (void *) type is 4703 discouraged as it does not allow the compiler to perform strong 4704 type-checking. However, the pointer type chosen should be of the 4705 same size as the (void *) type. Provided this rule is obeyed, ABI 4706 specifications need not further constrain the implementation of 4707 gss_name_t objects. 4709 B.5. The int and size_t types 4711 Some platforms may support differently sized implementations of the 4712 "int" and "size_t" types, perhaps chosen through compiler switches, 4713 and perhaps dependent on memory model. An ABI specification for such 4714 a platform should include required implementations for these types. 4715 It is recommended that the default implementation (for the chosen 4716 memory model, if appropriate) is chosen. 4718 B.6. Procedure-calling conventions 4720 Some platforms support a variety of different binary conventions for 4721 calling procedures. Such conventions cover things like the format of 4723 Wray [Page 100 of 101] 4724 the stack frame, the order in which the routine parameters are pushed 4725 onto the stack, whether or not a parameter count is pushed onto the 4726 stack, whether some argument(s) or return values are to be passed in 4727 registers, and whether the called routine or the caller is 4728 responsible for removing the stack frame on return. For such 4729 platforms, an ABI specification should specify which calling 4730 convention is to be used for GSSAPI implementations. 4732 REFERENCES 4734 [GSSAPI] J. Linn, "Generic Security Service 4735 Application Program Interface, Version 2", 4736 RFC2078. 4738 [XOM] OSI Object Management API Specification, 4739 Version 2.0 t", X.400 API Association & 4740 X/Open Company Limited, August 24, 1990 4741 Specification of datatypes and routines for 4742 manipulating information objects. 4744 AUTHOR'S ADDRESS 4746 John Wray Internet email: John_Wray@Iris.com 4747 Iris Associates Telephone: +1-978-392-6689 4748 5 Technology Park Drive, 4749 Westford, MA 01886 4750 USA 4752 Wray [Page 101 of 101]