idnits 2.17.1 draft-ietf-cat-gssv2-cbind-09.txt: -(3309): 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 is 1 instance 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 103 longer pages, the longest (page 88) being 64 lines Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** 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 287 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 1278 has weird spacing: '..._handle gss...' == Line 1288 has weird spacing: '..._handle gss_c...' == Line 1296 has weird spacing: '..._buffer buff...' == Line 1299 has weird spacing: '...indings chann...' == Line 1547 has weird spacing: '..._handle gss_c...' == (25 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 (February 10, 1999) is 9206 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: 12 errors (**), 0 flaws (~~), 9 warnings (==), 4 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Internet Draft J. Wray 3 Common Authentication Technology Working Group Iris Associates 4 February 10, 1999 6 Generic Security Service API Version 2 : C-bindings 8 1. STATUS OF THIS MEMO 10 This document is an Internet Draft. Internet Drafts are working 11 documents of the Internet Engineering Task Force (IETF), its Areas, 12 and its Working Groups. Note that other groups may also distribute 13 working documents as Internet Drafts. Internet Drafts are draft 14 documents valid for a maximum of six months. Internet Drafts may be 15 updated, replaced, or obsoleted by other documents at any time. It 16 is not appropriate to use Internet Drafts as reference material or to 17 cite them other than as a "working draft" or "work in progress." 18 Please check the I-D abstract listing contained in each Internet 19 Draft directory to learn the current status of this or any other 20 Internet Draft. 22 Comments on this document should be sent to "cat-ietf@mit.edu", the 23 IETF Common Authentication Technology WG discussion list. 25 2. ABSTRACT 27 This draft document specifies C language bindings for Version 2 of 28 the Generic Security Service Application Program Interface (GSS-API), 29 which is described at a language-independent conceptual level in 30 other drafts [GSSAPI]. It revises RFC-1509, making specific 31 incremental changes in response to implementation experience and 32 liaison requests. It is intended, therefore, that this draft or a 33 successor version thereof will become the basis for subsequent 34 progression of the GSS-API specification on the standards track. 36 The Generic Security Service Application Programming Interface 37 provides security services to its callers, and is intended for 38 implementation atop a variety of underlying cryptographic mechanisms. 39 Typically, GSS-API callers will be application protocols into which 40 security enhancements are integrated through invocation of services 41 provided by the GSS-API. The GSS-API allows a caller application to 42 authenticate a principal identity associated with a peer application, 43 to delegate rights to a peer, and to apply security services such as 44 confidentiality and integrity on a per-message basis. 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 GSS-API: 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 GSS-API 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 GSS-API 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 GSS-API 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 GSS-API 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 98 to application data, which are treated by GSS-API as arbitrary 99 octet-strings. An application transmitting a message that it 100 wishes to protect will call the appropriate GSS-API routine 101 (gss_get_mic or gss_wrap) to apply protection, specifying the 102 appropriate security context, and send the resulting token to 103 the receiving application. The receiver will pass the 104 received token (and, in the case of data protected by 105 gss_get_mic, the accompanying message-data) to the 106 corresponding decoding routine (gss_verify_mic or gss_unwrap) 107 to remove the protection and validate the data. 109 d) At the completion of a communications session (which may 110 extend across several transport connections), each 111 application calls a GSS-API routine to delete the security 112 context. Multiple contexts may also be used (either 113 successively or simultaneously) within a single communications 114 association, at the option of the applications. 116 4. GSS-API ROUTINES 118 This section lists the routines that make up the GSS-API, and offers 119 a brief description of the purpose of each routine. Detailed 120 descriptions of each routine are listed in alphabetical order in 121 section 7. 123 Table 4-1 GSS-API Credential-management Routines 125 Routine Section Function 126 ------- ------- -------- 127 gss_acquire_cred 7.2 Assume a global identity; Obtain 128 a GSS-API credential handle for 129 pre-existing credentials. 130 gss_add_cred 7.3 Construct credentials 131 incrementally 132 gss_inquire_cred 7.21 Obtain information about a 133 credential 134 gss_inquire_cred_by_mech 7.22 Obtain per-mechanism information 135 about a credential. 136 gss_release_cred 7.27 Discard a credential handle. 138 Table 4-2 GSS-API Context-Level Routines 140 Routine Section Function 141 ------- ------- -------- 142 gss_init_sec_context 7.19 Initiate a security context with 143 a peer application 144 gss_accept_sec_context 7.1 Accept a security context 145 initiated by a 146 peer application 147 gss_delete_sec_context 7.9 Discard a security context 148 gss_process_context_token 7.25 Process a token on a security 149 context from a peer application 150 gss_context_time 7.7 Determine for how long a context 151 will remain valid 152 gss_inquire_context 7.20 Obtain information about a 153 security context 154 gss_wrap_size_limit 7.34 Determine token-size limit for 155 gss_wrap on a context 156 gss_export_sec_context 7.14 Transfer a security context to 157 another process 158 gss_import_sec_context 7.17 Import a transferred context 160 Table 4-3 GSS-API Per-message Routines 162 Routine Section Function 163 ------- ------- -------- 164 gss_get_mic 7.15 Calculate a cryptographic message 165 integrity code (MIC) for a 166 message; integrity service 167 gss_verify_mic 7.32 Check a MIC against a message; 168 verify integrity of a received 169 message 170 gss_wrap 7.33 Attach a MIC to a message, and 171 optionally encrypt the message 172 content; 173 confidentiality service 174 gss_unwrap 7.31 Verify a message with attached 175 MIC, and decrypt message content 176 if necessary. 178 Table 4-4 GSS-API Name manipulation Routines 180 Routine Section Function 181 ------- ------- -------- 182 gss_import_name 7.16 Convert a contiguous string name 183 to internal-form 184 gss_display_name 7.10 Convert internal-form name to 185 text 186 gss_compare_name 7.6 Compare two internal-form names 187 gss_release_name 7.28 Discard an internal-form name 188 gss_inquire_names_for_mech 7.24 List the name-types supported by 189 the specified mechanism 190 gss_inquire_mechs_for_name 7.23 List mechanisms that support the 191 specified name-type 192 gss_canonicalize_name 7.5 Convert an internal name to an MN 193 gss_export_name 7.13 Convert an MN to export form 194 gss_duplicate_name 7.12 Create a copy of an internal name 196 Table 4-5 GSS-API Miscellaneous Routines 198 Routine Section Function 199 ------- ------- -------- 200 gss_add_oid_set_member 7.4 Add an object identifier to 201 a set 202 gss_display_status 7.11 Convert a GSS-API status code 203 to text 204 gss_indicate_mechs 7.18 Determine available underlying 205 authentication mechanisms 206 gss_release_buffer 7.26 Discard a buffer 207 gss_release_oid_set 7.29 Discard a set of object 208 identifiers 209 gss_create_empty_oid_set 7.8 Create a set containing no 210 object identifiers 211 gss_test_oid_set_member 7.30 Determines whether an object 212 identifier is a member of a set. 214 Individual GSS-API implementations may augment these routines by 215 providing additional mechanism-specific routines if required 216 functionality is not available from the generic forms. Applications 217 are encouraged to use the generic routines wherever possible on 218 portability grounds. 220 5. DATA TYPES AND CALLING CONVENTIONS 222 The following conventions are used by the GSS-API C-language 223 bindings: 225 5.1. Integer types 227 GSS-API uses the following integer data type: 229 OM_uint32 32-bit unsigned integer 231 Where guaranteed minimum bit-count is important, this portable data 232 type is used by the GSS-API routine definitions. Individual GSS-API 233 implementations will include appropriate typedef definitions to map 234 this type onto a built-in data type. If the platform supports the 235 X/Open xom.h header file, the OM_uint32 definition contained therein 236 should be used; the GSS-API header file in Appendix A contains logic 237 that will detect the prior inclusion of xom.h, and will not attempt 238 to re-declare OM_uint32. If the X/Open header file is not available 239 on the platform, the GSS-API implementation should use the smallest 240 natural unsigned integer type that provides at least 32 bits of 241 precision. 243 5.2. String and similar data 245 Many of the GSS-API routines take arguments and return values that 246 describe contiguous octet-strings. All such data is passed between 247 the GSS-API and the caller using the gss_buffer_t data type. This 248 data type is a pointer to a buffer descriptor, which consists of a 249 length field that contains the total number of bytes in the datum, 250 and a value field which contains a pointer to the actual datum: 252 typedef struct gss_buffer_desc_struct { 253 size_t length; 254 void *value; 255 } gss_buffer_desc, *gss_buffer_t; 257 Storage for data returned to the application by a GSS-API routine 258 using the gss_buffer_t conventions is allocated by the GSS-API 259 routine. The application may free this storage by invoking the 260 gss_release_buffer routine. Allocation of the gss_buffer_desc object 261 is always the responsibility of the application; unused 262 gss_buffer_desc objects may be initialized to the value 263 GSS_C_EMPTY_BUFFER. 265 5.2.1. Opaque data types 267 Certain multiple-word data items are considered opaque data types at 268 the GSS-API, because their internal structure has no significance 269 either to the GSS-API or to the caller. Examples of such opaque data 270 types are the input_token parameter to gss_init_sec_context (which is 271 opaque to the caller), and the input_message parameter to gss_wrap 272 (which is opaque to the GSS-API). Opaque data is passed between the 273 GSS-API and the application using the gss_buffer_t datatype. 275 5.2.2. Character strings 277 Certain multiple-word data items may be regarded as simple ISO 278 Latin-1 character strings. Examples are the printable strings passed 279 to gss_import_name via the input_name_buffer parameter. Some GSS-API 280 routines also return character strings. All such character strings 281 are passed between the application and the GSS-API implementation 282 using the gss_buffer_t datatype, which is a pointer to a 283 gss_buffer_desc object. 285 When a gss_buffer_desc object describes a printable string, the 286 length field of the gss_buffer_desc should only count printable 287 characters within the string. In particular, a trailing NUL 288 character should NOT be included in the length count, nor should 289 either the GSS-API implementation or the application assume the 290 presence of an uncounted trailing NUL. 292 5.3. Object Identifiers 294 Certain GSS-API procedures take parameters of the type gss_OID, or 295 Object identifier. This is a type containing ISO-defined 296 tree-structured values, and is used by the GSS-API caller to select 297 an underlying security mechanism and to specify namespaces. A value 298 of type gss_OID has the following structure: 300 typedef struct gss_OID_desc_struct { 301 OM_uint32 length; 302 void *elements; 303 } gss_OID_desc, *gss_OID; 305 The elements field of this structure points to the first byte of an 306 octet string containing the ASN.1 BER encoding of the value portion 307 of the normal BER TLV encoding of the gss_OID. The length field 308 contains the number of bytes in this value. For example, the gss_OID 309 value corresponding to {iso(1) identified-organization(3) 310 icd-ecma(12) member-company(2) dec(1011) cryptoAlgorithms(7) 311 DASS(5)}, meaning the DASS X.509 authentication mechanism, has a 312 length field of 7 and an elements field pointing to seven octets 313 containing the following octal values: 53,14,2,207,163,7,5. GSS-API 314 implementations should provide constant gss_OID values to allow 315 applications to request any supported mechanism, although 316 applications are encouraged on portability grounds to accept the 317 default mechanism. gss_OID values should also be provided to allow 318 applications to specify particular name types (see section 5.10). 319 Applications should treat gss_OID_desc values returned by GSS-API 320 routines as read-only. In particular, the application should not 321 attempt to deallocate them with free(). The gss_OID_desc datatype is 322 equivalent to the X/Open OM_object_identifier datatype[XOM]. 324 5.4. Object Identifier Sets 326 Certain GSS-API procedures take parameters of the type gss_OID_set. 327 This type 328 represents one or more object identifiers (section 5.3). A 329 gss_OID_set object has the following structure: 331 typedef struct gss_OID_set_desc_struct { 332 size_t count; 333 gss_OID elements; 334 } gss_OID_set_desc, *gss_OID_set; 336 The count field contains the number of OIDs within the set. The 337 elements field is a pointer to an array of gss_OID_desc objects, each 338 of which describes a single OID. gss_OID_set values are used to name 339 the available mechanisms supported by the GSS-API, to request the use 340 of specific mechanisms, and to indicate which mechanisms a given 341 credential supports. 343 All OID sets returned to the application by GSS-API are dynamic 344 objects (the gss_OID_set_desc, the "elements" array of the set, and 345 the "elements" array of each member OID are all dynamically 346 allocated), and this storage must be deallocated by the application 347 using the gss_release_oid_set() routine. 349 5.5. Credentials 351 A credential handle is a caller-opaque atomic datum that identifies a 352 GSS-API credential data structure. It is represented by the 353 caller-opaque type gss_cred_id_t, which should be implemented as a 354 pointer or arithmetic type. If a pointer implementation is chosen, 355 care must be taken to ensure that two gss_cred_id_t values may be 356 compared with the == operator. 358 GSS-API credentials can contain mechanism-specific principal 359 authentication data for multiple mechanisms. A GSS-API credential is 360 composed of a set of credential-elements, each of which is applicable 361 to a single mechanism. A credential may contain at most one 362 credential-element for each supported mechanism. A credential-element 363 identifies the data needed by a single mechanism to authenticate a 364 single principal, and conceptually contains two credential-references 365 that describe the actual mechanism-specific authentication data, one 366 to be used by GSS-API for initiating contexts, and one to be used 367 for accepting contexts. For mechanisms that do not distinguish 368 between acceptor and initiator credentials, both references would 369 point to the same underlying mechanism-specific authentication data. 371 Credentials describe a set of mechanism-specific principals, and give 372 their holder the ability to act as any of those principals. All 373 principal identities asserted by a single GSS-API credential should 374 belong to the same entity, although enforcement of this property is 375 an implementation-specific matter. The GSS-API does not make the 376 actual credentials available to applications; instead a credential 377 handle is used to identify a particular credential, held internally 378 by GSS-API. The combination of GSS-API credential handle and 379 mechanism identifies the principal whose identity will be asserted by 380 the credential when used with that mechanism. 382 The gss_init_sec_context and gss_accept_sec_context routines allow 383 the value GSS_C_NO_CREDENTIAL to be specified as their credential 384 handle parameter. This special credential-handle indicates a desire 385 by the application to act as a default principal. While individual 386 GSS-API implementations are free to determine such default behavior 387 as appropriate to the mechanism, the following default behavior by 388 these routines is recommended for portability: 390 gss_init_sec_context 392 1) If there is only a single principal capable of initiating 393 security contexts for the chosen mechanism that the 394 application is authorized to act on behalf of, then that 395 principal shall be used, otherwise 396 2) If the platform maintains a concept of a default 397 network-identity for the chosen mechanism, and if the 398 application is authorized to act on behalf of that 399 identity for the purpose of initiating security contexts, 400 then the principal corresponding to that identity shall 401 be used, otherwise 403 3) If the platform maintains a concept of a default local 404 identity, and provides a means to map local identities 405 into network-identities for the chosen mechanism, and 406 if the application is authorized to act on behalf of 407 the network-identity image of the default local 408 identity for the purpose of initiating security contexts 409 using the chosen mechanism, then the principal 410 corresponding to that identity shall be used, otherwise 412 4) A user-configurable default identity should be used. 414 gss_accept_sec_context 416 1) If there is only a single authorized principal identity 417 capable of accepting security contexts for the chosen 418 mechanism, then that principal shall be used, otherwise 420 2) If the mechanism can determine the identity of the 421 target principal by examining the context-establishment 422 token, and if the accepting application is authorized to 423 act as that principal for the purpose of accepting security 424 contexts using the chosen mechanism, then that principal 425 identity shall be used, otherwise 427 3) If the mechanism supports context acceptance by any 428 principal, and if mutual authentication was not requested, 429 any principal that the application is authorized to accept 430 security contexts under using the chosen mechanism may be 431 used, otherwise 433 4)A user-configurable default identity shall be used. 435 The purpose of the above rules is to allow security contexts to be 436 established by both initiator and acceptor using the default behavior 437 wherever possible. Applications requesting default behavior are 438 likely to be more portable across mechanisms and platforms than ones 439 that use gss_acquire_cred to request a specific identity. 441 5.6. Contexts 443 The gss_ctx_id_t data type contains a caller-opaque atomic value that 444 identifies one end of a GSS-API security context. It should be 445 implemented as a pointer or arithmetic type. If a pointer type is 446 chosen, care should be taken to ensure that two gss_ctx_id_t values 447 may be compared with the == operator. 449 The security context holds state information about each end of a peer 450 communication, including cryptographic state information. 452 5.7. Authentication tokens 454 A token is a caller-opaque type that GSS-API uses to maintain 455 synchronization between the context data structures at each end of a 456 GSS-API security context. The token is a cryptographically protected 457 octet-string, generated by the underlying mechanism at one end of a 458 GSS-API security context for use by the peer mechanism at the other 459 end. Encapsulation (if required) and transfer of the token are the 460 responsibility of the peer applications. A token is passed between 461 the GSS-API and the application using the gss_buffer_t conventions. 463 5.8. Interprocess tokens 465 Certain GSS-API routines are intended to transfer data between 466 processes in multi-process programs. These routines use a 467 caller-opaque octet-string, generated by the GSS-API in one process 468 for use by the GSS-API in another process. The calling application 469 is responsible for transferring such tokens between processes in an 470 OS-specific manner. Note that, while GSS-API implementors are 471 encouraged to avoid placing sensitive information within interprocess 472 tokens, or to cryptographically protect them, many implementations 473 will be unable to avoid placing key material or other sensitive data 474 within them. It is the application's responsibility to ensure that 475 interprocess tokens are protected in transit, and transferred only to 476 processes that are trustworthy. An interprocess token is passed 477 between the GSS-API and the application using the gss_buffer_t 478 conventions. 480 5.9. Status values 482 Every GSS-API routine returns two distinct values to report status 483 information to the caller: GSS status codes and Mechanism status 484 codes. 486 5.9.1. GSS status codes 488 GSS-API routines return GSS status codes as their OM_uint32 function 489 value. These codes indicate errors that are independent of the 490 underlying mechanism(s) used to provide the security service. The 491 errors that can be indicated via a GSS status code are either generic 492 API routine errors (errors that are defined in the GSS-API 493 specification) or calling errors (errors that are specific to these 494 language bindings). 496 A GSS status code can indicate a single fatal generic API error from 497 the routine and a single calling error. In addition, supplementary 498 status information may be indicated via the setting of bits in the 499 supplementary info field of a GSS status code. 501 These errors are encoded into the 32-bit GSS status code as follows: 503 MSB LSB 504 |------------------------------------------------------------| 505 | Calling Error | Routine Error | Supplementary Info | 506 |------------------------------------------------------------| 507 Bit 31 24 23 16 15 0 509 Hence if a GSS-API routine returns a GSS status code whose upper 16 510 bits contain a non-zero value, the call failed. If the calling error 511 field is non-zero, the invoking application's call of the routine was 512 erroneous. Calling errors are defined in table 5-1. If the routine 513 error field is non-zero, the routine failed for one of the 514 routine-specific reasons listed below in table 5-2. Whether or not 515 the upper 16 bits indicate a failure or a success, the routine may 516 indicate additional information by setting bits in the supplementary 517 info field of the status code. The meaning of individual bits is 518 listed below in table 5-3. 520 Table 5-1 Calling Errors 522 Name Value in field Meaning 523 ---- -------------- ------- 524 GSS_S_CALL_INACCESSIBLE_READ 1 A required input parameter 525 could not be read 526 GSS_S_CALL_INACCESSIBLE_WRITE 2 A required output parameter 527 could not be written. 528 GSS_S_CALL_BAD_STRUCTURE 3 A parameter was malformed 530 Table 5-2 Routine Errors 532 Name Value in field Meaning 533 ---- -------------- ------- 534 GSS_S_BAD_MECH 1 An unsupported mechanism 535 was requested 536 GSS_S_BAD_NAME 2 An invalid name was 537 supplied 538 GSS_S_BAD_NAMETYPE 3 A supplied name was of an 539 unsupported type 540 GSS_S_BAD_BINDINGS 4 Incorrect channel bindings 541 were supplied 542 GSS_S_BAD_STATUS 5 An invalid status code was 543 supplied 544 GSS_S_BAD_MIC GSS_S_BAD_SIG 6 A token had an invalid MIC 545 GSS_S_NO_CRED 7 No credentials were 546 supplied, or the 547 credentials were 548 unavailable or 549 inaccessible. 551 GSS_S_NO_CONTEXT 8 No context has been 552 established 553 GSS_S_DEFECTIVE_TOKEN 9 A token was invalid 554 GSS_S_DEFECTIVE_CREDENTIAL 10 A credential was invalid 555 GSS_S_CREDENTIALS_EXPIRED 11 The referenced credentials 556 have expired 557 GSS_S_CONTEXT_EXPIRED 12 The context has expired 558 GSS_S_FAILURE 13 Miscellaneous failure (see 559 text) 560 GSS_S_BAD_QOP 14 The quality-of-protection 561 requested could not be 562 provided 563 GSS_S_UNAUTHORIZED 15 The operation is forbidden 564 by local security policy 565 GSS_S_UNAVAILABLE 16 The operation or option is 566 unavailable 567 GSS_S_DUPLICATE_ELEMENT 17 The requested credential 568 element already exists 569 GSS_S_NAME_NOT_MN 18 The provided name was not a 570 mechanism name 572 Table 5-3 Supplementary Status Bits 574 Name Bit Number Meaning 575 ---- ---------- ------- 576 GSS_S_CONTINUE_NEEDED 0 (LSB) Returned only by 577 gss_init_sec_context or 578 gss_accept_sec_context. The 579 routine must be called again 580 to complete its function. 581 See routine documentation for 582 detailed description 583 GSS_S_DUPLICATE_TOKEN 1 The token was a duplicate of 584 an earlier token 585 GSS_S_OLD_TOKEN 2 The token's validity period 586 has expired 587 GSS_S_UNSEQ_TOKEN 3 A later token has already been 588 processed 589 GSS_S_GAP_TOKEN 4 An expected per-message token 590 was not received 592 The routine documentation also uses the name GSS_S_COMPLETE, which is 593 a zero value, to indicate an absence of any API errors or 594 supplementary information bits. 596 All GSS_S_xxx symbols equate to complete OM_uint32 status codes, 597 rather than to bitfield values. For example, the actual value of the 598 symbol GSS_S_BAD_NAMETYPE (value 3 in the routine error field) is 599 3<<16. 600 The macros GSS_CALLING_ERROR(), GSS_ROUTINE_ERROR() and 601 GSS_SUPPLEMENTARY_INFO() are provided, each of which takes a GSS 602 status code and removes all but the relevant field. For example, the 603 value obtained by applying GSS_ROUTINE_ERROR to a status code removes 604 the calling errors and supplementary info fields, leaving only the 605 routine errors field. The values delivered by these macros may be 606 directly compared with a GSS_S_xxx symbol of the appropriate type. 607 The macro GSS_ERROR() is also provided, which when applied to a GSS 608 status code returns a non-zero value if the status code indicated a 609 calling or routine error, and a zero value otherwise. All macros 610 defined by GSS-API evaluate their argument(s) exactly once. 612 A GSS-API implementation may choose to signal calling errors in a 613 platform-specific manner instead of, or in addition to the routine 614 value; routine errors and supplementary info should be returned via 615 major status values only. 617 The GSS major status code GSS_S_FAILURE is used to indicate that the 618 underlying mechanism detected an error for which no specific GSS 619 status code is defined. The mechanism-specific status code will 620 provide more details about the error. 622 5.9.2. Mechanism-specific status codes 624 GSS-API routines return a minor_status parameter, which is used to 625 indicate specialized errors from the underlying security mechanism. 626 This parameter may contain a single mechanism-specific error, 627 indicated by a OM_uint32 value. 629 The minor_status parameter will always be set by a GSS-API routine, 630 even if it returns a calling error or one of the generic API errors 631 indicated above as fatal, although most other output parameters may 632 remain unset in such cases. However, output parameters that are 633 expected to return pointers to storage allocated by a routine must 634 always be set by the routine, even in the event of an error, although 635 in such cases the GSS-API routine may elect to set the returned 636 parameter value to NULL to indicate that no storage was actually 637 allocated. Any length field associated with such pointers (as in a 638 gss_buffer_desc structure) should also be set to zero in such cases. 640 5.10.Names 642 A name is used to identify a person or entity. GSS-API authenticates 643 the relationship between a name and the entity claiming the name. 645 Since different authentication mechanisms may employ different 646 namespaces for identifying their principals, GSSAPI's naming support 647 is necessarily complex in multi-mechanism environments (or even in 648 some single-mechanism environments where the underlying mechanism 649 supports multiple namespaces). 651 Two distinct representations are defined for names: 653 An internal form. This is the GSS-API "native" format for names, 654 represented by the implementation-specific gss_name_t type. 656 It is opaque to GSS-API callers. A single gss_name_t object 657 may contain multiple names from different namespaces, but 658 all names should refer to the same entity. An example of 659 such an internal name would be the name returned from a 660 call to the gss_inquire_cred routine, when applied to a 661 credential containing credential elements for multiple 662 authentication mechanisms employing different namespaces. 663 This gss_name_t object will contain a distinct name for the 664 entity for each authentication mechanism. 666 For GSS-API implementations supporting multiple namespaces, 667 objects of type gss_name_t must contain sufficient 668 information to determine the namespace to which each 669 primitive name belongs. 671 Mechanism-specific contiguous octet-string forms. A format 672 capable of containing a single name (from a single 673 namespace). Contiguous string names are always accompanied 674 by an object identifier specifying the namespace to which 675 the name belongs, and their format is dependent on the 676 authentication mechanism that employs the name. Many, but 677 not all, contiguous string names will be printable, and may 678 therefore be used by GSS-API applications for communication 679 with their users. 681 Routines (gss_import_name and gss_display_name) are provided to 682 convert names between contiguous string representations and the 683 internal gss_name_t type. gss_import_name may support multiple 684 syntaxes for each supported namespace, allowing users the freedom to 685 choose a preferred name representation. gss_display_name should use 686 an implementation-chosen printable syntax for each supported 687 name-type. 689 If an application calls gss_display_name(), passing the internal name 690 resulting from a call to gss_import_name(), there is no guarantee 691 the the resulting contiguous string name will be the same as the 692 original imported string name. Nor do name-space identifiers 693 necessarily survive unchanged after a journey through the internal 694 name-form. An example of this might be a mechanism that 695 authenticates X.500 names, but provides an algorithmic mapping of 696 Internet DNS names into X.500. That mechanism's implementation of 697 gss_import_name() might, when presented with a DNS name, generate an 698 internal name that contained both the original DNS name and the 699 equivalent X.500 name. Alternatively, it might only store the X.500 700 name. In the latter case, gss_display_name() would most likely 701 generate a printable X.500 name, rather than the original DNS name. 703 The process of authentication delivers to the context acceptor an 704 internal name. Since this name has been authenticated by a single 705 mechanism, it contains only a single name (even if the internal name 706 presented by the context initiator to gss_init_sec_context had 707 multiple components). Such names are termed internal mechanism 708 names, or "MN"s and the names emitted by gss_accept_sec_context() are 709 always of this type. Since some applications may require MNs without 710 wanting to incur the overhead of an authentication operation, a 711 second function, gss_canonicalize_name(), is provided to convert a 712 general internal name into an MN. 714 Comparison of internal-form names may be accomplished via the 715 gss_compare_name() routine, which returns true if the two names being 716 compared refer to the same entity. This removes the need for the 717 application program to understand the syntaxes of the various 718 printable names that a given GSS-API implementation may support. 719 Since GSS-API assumes that all primitive names contained within a 720 given internal name refer to the same entity, gss_compare_name() can 721 return true if the two names have at least one primitive name in 722 common. If the implementation embodies knowledge of equivalence 723 relationships between names taken from different namespaces, this 724 knowledge may also allow successful comparison of internal names 725 containing no overlapping primitive elements. 727 When used in large access control lists, the overhead of invoking 728 gss_import_name() and gss_compare_name() on each name from the ACL 729 may be prohibitive. As an alternative way of supporting this case, 730 GSS-API defines a special form of the contiguous string name which 731 may be compared directly (e.g. with memcmp()). Contigous names 732 suitable for comparison are generated by the gss_export_name() 733 routine, which requires an MN as input. Exported names may be 734 re-imported by the gss_import_name() routine, and the resulting 735 internal name will also be an MN. The gss_OID constant 736 GSS_C_NT_EXPORT_NAME indentifies the "export name" type, and the 737 value of this constant is given in Appendix A. Structurally, an 738 exported name object consists of a header containing an OID 739 identifying the mechanism that authenticated the name, and a trailer 740 containing the name itself, where the syntax of the trailer is 741 defined by the individual mechanism specification. The precise 742 format of an export name is defined in the language-independent 743 GSS-API specification [GSSAPI]. 745 Note that the results obtained by using gss_compare_name() will in 746 general be different from those obtained by invoking 747 gss_canonicalize_name() and gss_export_name(), and then comparing the 748 exported names. The first series of operation determines whether two 749 (unauthenticated) names identify the same principal; the second 750 whether a particular mechanism would authenticate them as the same 751 principal. These two operations will in general give the same 752 results only for MNs. 754 The gss_name_t datatype should be implemented as a pointer type. To 755 allow the compiler to aid the application programmer by performing 756 type-checking, the use of (void *) is discouraged. A pointer to an 757 implementation-defined type is the preferred choice. 759 Storage is allocated by routines that return gss_name_t values. A 760 procedure, gss_release_name, is provided to free storage associated 761 with an internal-form name. 763 5.11.Channel Bindings 764 GSS-API supports the use of user-specified tags to identify a given 765 context to the peer application. These tags are intended to be used 766 to identify the particular communications channel that carries the 767 context. Channel bindings are communicated to the GSS-API using the 768 following structure: 770 typedef struct gss_channel_bindings_struct { 771 OM_uint32 initiator_addrtype; 772 gss_buffer_desc initiator_address; 773 OM_uint32 acceptor_addrtype; 774 gss_buffer_desc acceptor_address; 775 gss_buffer_desc application_data; 776 } *gss_channel_bindings_t; 778 The initiator_addrtype and acceptor_addrtype fields denote the type 779 of addresses contained in the initiator_address and acceptor_address 780 buffers. The address type should be one of the following: 782 GSS_C_AF_UNSPEC Unspecified address type 783 GSS_C_AF_LOCAL Host-local address type 784 GSS_C_AF_INET Internet address type (e.g. IP) 785 GSS_C_AF_IMPLINK ARPAnet IMP address type 786 GSS_C_AF_PUP pup protocols (eg BSP) address type 787 GSS_C_AF_CHAOS MIT CHAOS protocol address type 788 GSS_C_AF_NS XEROX NS address type 789 GSS_C_AF_NBS nbs address type 790 GSS_C_AF_ECMA ECMA address type 791 GSS_C_AF_DATAKIT datakit protocols address type 792 GSS_C_AF_CCITT CCITT protocols 793 GSS_C_AF_SNA IBM SNA address type 794 GSS_C_AF_DECnet DECnet address type 795 GSS_C_AF_DLI Direct data link interface address type 796 GSS_C_AF_LAT LAT address type 797 GSS_C_AF_HYLINK NSC Hyperchannel address type 798 GSS_C_AF_APPLETALK AppleTalk address type 799 GSS_C_AF_BSC BISYNC 2780/3780 address type 800 GSS_C_AF_DSS Distributed system services address type 801 GSS_C_AF_OSI OSI TP4 address type 802 GSS_C_AF_X25 X.25 803 GSS_C_AF_NULLADDR No address specified 805 Note that these symbols name address families rather than specific 806 addressing formats. For address families that contain several 807 alternative address forms, the initiator_address and acceptor_address 808 fields must contain sufficient information to determine which address 809 form is used. When not otherwise specified, addresses should be 810 specified in network byte-order (that is, native byte-ordering for 811 the address family). 813 Conceptually, the GSS-API concatenates the initiator_addrtype, 814 initiator_address, acceptor_addrtype, acceptor_address and 815 application_data to form an octet string. The mechanism calculates a 816 MIC over this octet string, and binds the MIC to the context 817 establishment token emitted by gss_init_sec_context. The same 818 bindings are presented by the context acceptor to 819 gss_accept_sec_context, and a MIC is calculated in the same way. The 820 calculated MIC is compared with that found in the token, and if the 821 MICs differ, gss_accept_sec_context will return a GSS_S_BAD_BINDINGS 822 error, and the context will not be established. Some mechanisms may 823 include the actual channel binding data in the token (rather than 824 just a MIC); applications should therefore not use confidential data 825 as channel-binding components. 827 Individual mechanisms may impose additional constraints on addresses 828 and address types that may appear in channel bindings. For example, 829 a mechanism may verify that the initiator_address field of the 830 channel bindings presented to gss_init_sec_context contains the 831 correct network address of the host system. Portable applications 832 should therefore ensure that they either provide correct information 833 for the address fields, or omit addressing information, specifying 834 GSS_C_AF_NULLADDR as the address-types. 836 5.12.Optional parameters 837 Various parameters are described as optional. This means that they 838 follow a convention whereby a default value may be requested. The 839 following conventions are used for omitted parameters. These 840 conventions apply only to those parameters that are explicitly 841 documented as optional. 843 5.12.1. gss_buffer_t types 845 Specify GSS_C_NO_BUFFER as a value. For an input parameter this 846 signifies that default behavior is requested, while for an output 847 parameter it indicates that the information that would be returned 848 via the parameter is not required by the application. 850 5.12.2. Integer types (input) 852 Individual parameter documentation lists values to be used to 853 indicate default actions. 855 5.12.3. Integer types (output) 857 Specify NULL as the value for the pointer. 859 5.12.4. Pointer types 861 Specify NULL as the value. 863 5.12.5. Object IDs 865 Specify GSS_C_NO_OID as the value. 867 5.12.6. Object ID Sets 869 Specify GSS_C_NO_OID_SET as the value. 871 5.12.7. Channel Bindings 873 Specify GSS_C_NO_CHANNEL_BINDINGS to indicate that channel bindings 874 are not to be used. 876 6. ADDITIONAL CONTROLS 878 This section discusses the optional services that a context initiator 879 may request of the GSS-API at context establishment. Each of these 880 services is requested by setting a flag in the req_flags input 881 parameter to gss_init_sec_context. 883 The optional services currently defined are: 885 Delegation - The (usually temporary) transfer of rights from 886 initiator to acceptor, enabling the acceptor to authenticate 887 itself as an agent of the initiator. 889 Mutual Authentication - In addition to the initiator 890 authenticating its identity to the context acceptor, the 891 context acceptor should also authenticate itself to the 892 initiator. 894 Replay detection - In addition to providing message integrity 895 services, gss_get_mic and gss_wrap should include message 896 numbering information to enable gss_verify_mic and gss_unwrap 897 to detect if a message has been duplicated. 899 Out-of-sequence detection - In addition to providing message 900 integrity services, gss_get_mic and gss_wrap should include 901 message sequencing information to enable gss_verify_mic and 902 gss_unwrap to detect if a message has been received out of 903 sequence. 905 Anonymous authentication - The establishment of the security 906 context should not reveal the initiator's identity to the 907 context acceptor. 909 Any currently undefined bits within such flag arguments should be 910 ignored by GSS-API implementations when presented by an application, 911 and should be set to zero when returned to the application by the 912 GSS-API implementation. 914 Some mechanisms may not support all optional services, and some 915 mechanisms may only support some services in conjunction with others. 916 Both gss_init_sec_context and gss_accept_sec_context inform the 917 applications which services will be available from the context when 918 the establishment phase is complete, via the ret_flags output 919 parameter. In general, if the security mechanism is capable of 920 providing a requested service, it should do so, even if additional 921 services must be enabled in order to provide the requested service. 922 If the mechanism is incapable of providing a requested service, it 923 should proceed without the service, leaving the application to abort 924 the context establishment process if it considers the requested 925 service to be mandatory. 927 Some mechanisms may specify that support for some services is 928 optional, and that implementors of the mechanism need not provide it. 929 This is most commonly true of the confidentiality service, often 930 because of legal restrictions on the use of data-encryption, but may 931 apply to any of the services. Such mechanisms are required to send 932 at least one token from acceptor to initiator during context 933 establishment when the initiator indicates a desire to use such a 934 service, so that the initiating GSS-API can correctly indicate 935 whether the service is supported by the acceptor's GSS-API. 937 6.1. Delegation 939 The GSS-API allows delegation to be controlled by the initiating 940 application via a boolean parameter to gss_init_sec_context(), the 941 routine that establishes a security context. Some mechanisms do not 942 support delegation, and for such mechanisms attempts by an 943 application to enable delegation are ignored. 945 The acceptor of a security context for which the initiator enabled 946 delegation will receive (via the delegated_cred_handle parameter of 947 gss_accept_sec_context) a credential handle that contains the 948 delegated identity, and this credential handle may be used to 949 initiate subsequent GSS-API security contexts as an agent or delegate 950 of the initiator. If the original initiator's identity is "A" and 951 the delegate's identity is "B", then, depending on the underlying 952 mechanism, the identity embodied by the delegated credential may be 953 either "A" or "B acting for A". 955 For many mechanisms that support delegation, a simple boolean does 956 not provide enough control. Examples of additional aspects of 957 delegation control that a mechanism might provide to an application 958 are duration of delegation, network addresses from which delegation 959 is valid, and constraints on the tasks that may be performed by a 960 delegate. Such controls are presently outside the scope of the 961 GSS-API. GSS-API implementations supporting mechanisms offering 962 additional controls should provide extension routines that allow 963 these controls to be exercised (perhaps by modifying the initiator's 964 GSS-API credential prior to its use in establishing a context). 965 However, the simple delegation control provided by GSS-API should 966 always be able to over-ride other mechanism-specific delegation 967 controls - If the application instructs gss_init_sec_context() that 968 delegation is not desired, then the implementation must not permit 969 delegation to occur. This is an exception to the general rule that a 970 mechanism may enable services even if they are not requested - 971 delegation may only be provided at the explicit request of the 972 application. 974 6.2. Mutual authentication 976 Usually, a context acceptor will require that a context initiator 977 authenticate itself so that the acceptor may make an access-control 978 decision prior to performing a service for the initiator. In some 979 cases, the initiator may also request that the acceptor authenticate 980 itself. GSS-API allows the initiating application to request this 981 mutual authentication service by setting a flag when calling 982 gss_init_sec_context. 984 The initiating application is informed as to whether or not the 985 context acceptor has authenticated itself. Note that some mechanisms 986 may not support mutual authentication, and other mechanisms may 987 always perform mutual authentication, whether or not the initiating 988 application requests it. In particular, mutual authentication my be 989 required by some mechanisms in order to support replay or 990 out-of-sequence message detection, and for such mechanisms a request 991 for either of these services will automatically enable mutual 992 authentication. 994 6.3. Replay and out-of-sequence detection 996 The GSS-API may provide detection of mis-ordered message once a 997 security context has been established. Protection may be applied to 998 messages by either application, by calling either gss_get_mic or 999 gss_wrap, and verified by the peer application by calling 1000 gss_verify_mic or gss_unwrap. 1002 gss_get_mic calculates a cryptographic MIC over an application 1003 message, and returns that MIC in a token. The application should 1004 pass both the token and the message to the peer application, which 1005 presents them to gss_verify_mic. 1007 gss_wrap calculates a cryptographic MIC of an application message, 1008 and places both the MIC and the message inside a single token. The 1009 Application should pass the token to the peer application, which 1010 presents it to gss_unwrap to extract the message and verify the MIC. 1012 Either pair of routines may be capable of detecting out-of-sequence 1013 message delivery, or duplication of messages. Details of such 1014 mis-ordered messages are indicated through supplementary status bits 1015 in the major status code returned by gss_verify_mic or gss_unwrap. 1016 The relevant supplementary bits are: 1018 GSS_S_DUPLICATE_TOKEN - The token is a duplicate of one that has 1019 already been received and processed. Only 1020 contexts that claim to provide replay detection 1021 may set this bit. 1022 GSS_S_OLD_TOKEN - The token is too old to determine whether or 1023 not it is a duplicate. Contexts supporting 1024 out-of-sequence detection but not replay 1025 detection should always set this bit if 1026 GSS_S_UNSEQ_TOKEN is set; contexts that support 1027 replay detection should only set this bit if the 1028 token is so old that it cannot be checked for 1029 duplication. 1030 GSS_S_UNSEQ_TOKEN - A later token has already been processed. 1031 GSS_S_GAP_TOKEN - An earlier token has not yet been received. 1033 A mechanism need not maintain a list of all tokens that have been 1034 processed in order to support these status codes. A typical 1035 mechanism might retain information about only the most recent "N" 1036 tokens processed, allowing it to distinguish duplicates and missing 1037 tokens within the most recent "N" messages; the receipt of a token 1038 older than the most recent "N" would result in a GSS_S_OLD_TOKEN 1039 status. 1041 6.4. Anonymous Authentication 1043 In certain situations, an application may wish to initiate the 1044 authentication process to authenticate a peer, without revealing its 1045 own identity. As an example, consider an application providing 1046 access to a database containing medical information, and offering 1047 unrestricted access to the service. A client of such a service might 1048 wish to authenticate the service (in order to establish trust in any 1049 information retrieved from it), but might not wish the service to be 1050 able to obtain the client's identity (perhaps due to privacy concerns 1051 about the specific inquiries, or perhaps simply to avoid being placed 1052 on mailing-lists). 1054 In normal use of the GSS-API, the initiator's identity is made 1055 available to the acceptor as a result of the context establishment 1056 process. However, context initiators may request that their identity 1057 not be revealed to the context acceptor. Many mechanisms do not 1058 support anonymous authentication, and for such mechanisms the request 1059 will not be honored. An authentication token will be still be 1060 generated, but the application is always informed if a requested 1061 service is unavailable, and has the option to abort context 1062 establishment if anonymity is valued above the other security 1063 services that would require a context to be established. 1065 In addition to informing the application that a context is 1066 established anonymously (via the ret_flags outputs from 1067 gss_init_sec_context and gss_accept_sec_context), the optional 1068 src_name output from gss_accept_sec_context and gss_inquire_context 1069 will, for such contexts, return a reserved internal-form name, 1070 defined by the implementation. 1072 When presented to gss_display_name, this reserved internal-form name 1073 will result in a printable name that is syntactically distinguishable 1074 from any valid principal name supported by the implementation, 1075 associated with a name-type object identifier with the value 1076 GSS_C_NT_ANONYMOUS, whose value us given in Appendix A. The 1077 printable form of an anonymous name should be chosen such that it 1078 implies anonymity, since this name may appear in, for example, audit 1079 logs. For example, the string "" might be a good choice, 1080 if no valid printable names supported by the implementation can begin 1081 with "<" and end with ">". 1083 6.5. Confidentiality 1085 If a context supports the confidentiality service, gss_wrap may be 1086 used to encrypt application messages. Messages are selectively 1087 encrypted, under the control of the conf_req_flag input parameter to 1088 gss_wrap. 1090 6.6. Inter-process context transfer 1092 GSS-API V2 provides routines (gss_export_sec_context and 1093 gss_import_sec_context) which allow a security context to be 1094 transferred between processes on a single machine. The most common 1095 use for such a feature is a client-server design where the server is 1096 implemented as a single process that accepts incoming security 1097 contexts, which then launches child processes to deal with the data 1098 on these contexts. In such a design, the child processes must have 1099 access to the security context data structure created within the 1100 parent by its call to gss_accept_sec_context so that they can use 1101 per-message protection services and delete the security context when 1102 the communication session ends. 1104 Since the security context data structure is expected to contain 1105 sequencing information, it is impractical in general to share a 1106 context between processes. Thus GSS-API provides a call 1107 (gss_export_sec_context) that the process which currently owns the 1108 context can call to declare that it has no intention to use the 1109 context subsequently, and to create an inter-process token containing 1110 information needed by the adopting process to successfully import the 1111 context. After successful completion of gss_export_sec_context, the 1112 original security context is made inaccessible to the calling process 1113 by GSS-API, and any context handles referring to this context are no 1114 longer valid. The originating process transfers the inter-process 1115 token to the adopting process, which passes it to 1116 gss_import_sec_context, and a fresh gss_ctx_id_t is created such that 1117 it is functionally identical to the original context. 1119 The inter-process token may contain sensitive data from the original 1120 security context (including cryptographic keys). Applications using 1121 inter-process tokens to transfer security contexts must take 1122 appropriate steps to protect these tokens in transit. 1124 Implementations are not required to support the inter-process 1125 transfer of security contexts. The ability to transfer a security 1126 context is indicated when the context is created, by 1127 gss_init_sec_context or gss_accept_sec_context setting the 1128 GSS_C_TRANS_FLAG bit in their ret_flags parameter. 1130 6.7. The use of incomplete contexts 1132 Some mechanisms may allow the per-message services to be used before 1133 the context establishment process is complete. For example, a 1134 mechanism may include sufficient information in its initial 1135 context-level token for the context acceptor to immediately decode 1136 messages protected with gss_wrap or gss_get_mic. For such a 1137 mechanism, the initiating application need not wait until subsequent 1138 context-level tokens have been sent and received before invoking the 1139 per-message protection services. 1141 The ability of a context to provide per-message services in advance 1142 of complete context establishment is indicated by the setting of the 1143 GSS_C_PROT_READY_FLAG bit in the ret_flags parameter from 1144 gss_init_sec_context and gss_accept_sec_context. Applications wishing 1145 to use per-message protection services on partially-established 1146 contexts should check this flag before attempting to invoke gss_wrap 1147 or gss_get_mic. 1149 7. GSS-API routine descriptions 1151 In addition to the explicit major status codes documented here, the 1152 code GSS_S_FAILURE may be returned by any routine, indicating an 1153 implementation-specific or mechanism-specific error condition, 1154 further details of which are reported via the minor_status parameter. 1156 7.1. gss_accept_sec_context 1158 OM_uint32 gss_accept_sec_context ( 1159 OM_uint32 *minor_status, 1160 gss_ctx_id_t *context_handle, 1161 const gss_cred_id_t acceptor_cred_handle, 1162 const gss_buffer_t input_token_buffer, 1163 const gss_channel_bindings_t input_chan_bindings, 1164 const gss_name_t *src_name, 1165 gss_OID *mech_type, 1166 gss_buffer_t output_token, 1167 OM_uint32 *ret_flags, 1168 OM_uint32 *time_rec, 1169 gss_cred_id_t *delegated_cred_handle) 1171 Purpose: 1173 Allows a remotely initiated security context between the application 1174 and a remote peer to be established. The routine may return a 1175 output_token which should be transferred to the peer application, 1176 where the peer application will present it to gss_init_sec_context. 1177 If no token need be sent, gss_accept_sec_context will indicate this 1178 by setting the length field of the output_token argument to zero. To 1179 complete the context establishment, one or more reply tokens may be 1180 required from the peer application; if so, gss_accept_sec_context 1181 will return a status flag of GSS_S_CONTINUE_NEEDED, in which case it 1182 should be called again when the reply token is received from the peer 1183 application, passing the token to gss_accept_sec_context via the 1184 input_token parameters. 1186 Portable applications should be constructed to use the token length 1187 and return status to determine whether a token needs to be sent or 1188 waited for. Thus a typical portable caller should always invoke 1189 gss_accept_sec_context within a loop: 1191 gss_ctx_id_t context_hdl = GSS_C_NO_CONTEXT; 1193 do { 1194 receive_token_from_peer(input_token); 1195 maj_stat = gss_accept_sec_context(&min_stat, 1196 &context_hdl, 1197 cred_hdl, 1198 input_token, 1199 input_bindings, 1200 &client_name, 1201 &mech_type, 1202 output_token, 1203 &ret_flags, 1204 &time_rec, 1205 &deleg_cred); 1206 if (GSS_ERROR(maj_stat)) { 1207 report_error(maj_stat, min_stat); 1208 }; 1209 if (output_token->length != 0) { 1210 send_token_to_peer(output_token); 1211 gss_release_buffer(&min_stat, output_token); 1212 }; 1213 if (GSS_ERROR(maj_stat)) { 1214 if (context_hdl != GSS_C_NO_CONTEXT) 1215 gss_delete_sec_context(&min_stat, 1216 &context_hdl, 1217 GSS_C_NO_BUFFER); 1218 break; 1219 }; 1220 } while (maj_stat & GSS_S_CONTINUE_NEEDED); 1222 Whenever the routine returns a major status that includes the value 1223 GSS_S_CONTINUE_NEEDED, the context is not fully established and the 1224 following restrictions apply to the output parameters: 1226 The value returned via the time_rec parameter is undefined 1227 Unless the accompanying ret_flags parameter contains the bit 1228 GSS_C_PROT_READY_FLAG, indicating that per-message services may be 1229 applied in advance of a successful completion status, the value 1230 returned via the mech_type parameter may be undefined until the 1231 routine returns a major status value of GSS_S_COMPLETE. 1233 The values of the GSS_C_DELEG_FLAG, 1234 GSS_C_MUTUAL_FLAG,GSS_C_REPLAY_FLAG, GSS_C_SEQUENCE_FLAG, 1235 GSS_C_CONF_FLAG,GSS_C_INTEG_FLAG and GSS_C_ANON_FLAG bits returned 1236 via the ret_flags parameter should contain the values that the 1237 implementation expects would be valid if context establishment were 1238 to succeed. 1240 The values of the GSS_C_PROT_READY_FLAG and GSS_C_TRANS_FLAG bits 1241 within ret_flags should indicate the actual state at the time 1242 gss_accept_sec_context returns, whether or not the context is fully 1243 established. 1245 Although this requires that GSS-API implementations set the 1246 GSS_C_PROT_READY_FLAG in the final ret_flags returned to a caller 1247 (i.e. when accompanied by a GSS_S_COMPLETE status code), applications 1248 should not rely on this behavior as the flag was not defined in 1249 Version 1 of the GSS-API. Instead, applications should be prepared to 1250 use per-message services after a successful context establishment, 1251 according to the GSS_C_INTEG_FLAG and GSS_C_CONF_FLAG values. 1253 All other bits within the ret_flags argument should be set to zero. 1254 While the routine returns GSS_S_CONTINUE_NEEDED, the values returned 1255 via the ret_flags argument indicate the services that the 1256 implementation expects to be available from the established context. 1258 If the initial call of gss_accept_sec_context() fails, the 1259 implementation should not create a context object, and should leave 1260 the value of the context_handle parameter set to GSS_C_NO_CONTEXT to 1261 indicate this. In the event of a failure on a subsequent call, the 1262 implementation is permitted to delete the "half-built" security 1263 context (in which case it should set the context_handle parameter to 1264 GSS_C_NO_CONTEXT), but the preferred behavior is to leave the 1265 security context (and the context_handle parameter) untouched for the 1266 application to delete (using gss_delete_sec_context). 1268 During context establishment, the informational status bits 1269 GSS_S_OLD_TOKEN and GSS_S_DUPLICATE_TOKEN indicate fatal errors, and 1270 GSS-API mechanisms should always return them in association with a 1271 routine error of GSS_S_FAILURE. This requirement for pairing did not 1272 exist in version 1 of the GSS-API specification, so applications that 1273 wish to run over version 1 implementations must special-case these 1274 codes. 1276 Parameters: 1278 context_handle gss_ctx_id_t, read/modify 1279 context handle for new context. Supply 1280 GSS_C_NO_CONTEXT for first call; use value 1281 returned in subsequent calls. Once 1282 gss_accept_sec_context() has returned a 1283 value via this parameter, resources have 1284 been assigned to the corresponding context, 1285 and must be freed by the application after 1286 use with a call to gss_delete_sec_context(). 1288 acceptor_cred_handle gss_cred_id_t, read 1289 Credential handle claimed by context 1290 acceptor. Specify GSS_C_NO_CREDENTIAL to 1291 accept the context as a default principal. 1292 If GSS_C_NO_CREDENTIAL is specified, but 1293 no default acceptor principal is defined, 1294 GSS_S_NO_CRED will be returned. 1296 input_token_buffer buffer, opaque, read 1297 token obtained from remote application. 1299 input_chan_bindings channel bindings, read, optional 1300 Application-specified bindings. Allows 1301 application to securely bind channel 1302 identification information to the security 1303 context. If channel bindings are not 1304 used, specify GSS_C_NO_CHANNEL_BINDINGS. 1306 src_name gss_name_t, modify, optional 1307 Authenticated name of context initiator. 1308 After use, this name should be deallocated 1309 by passing it to gss_release_name(). If 1310 not required, specify NULL. 1312 mech_type Object ID, modify, optional 1313 Security mechanism used. The returned 1314 OID value will be a pointer into static 1315 storage, and should be treated as read-only 1316 by the caller (in particular, it does not 1317 need to be freed). If not required, specify 1318 NULL. 1320 output_token buffer, opaque, modify 1321 Token to be passed to peer application. If 1322 the length field of the returned token 1323 buffer is 0, then no token need be passed 1324 to the peer application. If a non-zero 1325 length field is returned, the associated 1326 storage must be freed after use by the 1327 application with a call to 1328 gss_release_buffer(). 1330 ret_flags bit-mask, modify, optional 1331 Contains various independent flags, each of 1332 which indicates that the context supports a 1333 specific service option. If not needed, 1334 specify NULL. Symbolic names are 1335 provided for each flag, and the symbolic 1336 names corresponding to the required flags 1337 should be logically-ANDed with the ret_flags 1338 value to test whether a given option is 1339 supported by the context. The flags are: 1340 GSS_C_DELEG_FLAG 1341 True - Delegated credentials are available 1342 via the delegated_cred_handle 1343 parameter 1344 False - No credentials were delegated 1345 GSS_C_MUTUAL_FLAG 1346 True - Remote peer asked for mutual 1347 authentication 1348 False - Remote peer did not ask for mutual 1349 authentication 1350 GSS_C_REPLAY_FLAG 1351 True - replay of protected messages 1352 will be detected 1353 False - replayed messages will not be 1354 detected 1355 GSS_C_SEQUENCE_FLAG 1356 True - out-of-sequence protected 1357 messages will be detected 1358 False - out-of-sequence messages will not 1359 be detected 1360 GSS_C_CONF_FLAG 1361 True - Confidentiality service may be 1362 invoked by calling the gss_wrap 1363 routine 1364 False - No confidentiality service (via 1365 gss_wrap) available. gss_wrap will 1366 provide message encapsulation, 1367 data-origin authentication and 1368 integrity services only. 1369 GSS_C_INTEG_FLAG 1370 True - Integrity service may be invoked by 1371 calling either gss_get_mic or 1372 gss_wrap routines. 1373 False - Per-message integrity service 1374 unavailable. 1375 GSS_C_ANON_FLAG 1376 True - The initiator does not wish to 1377 be authenticated; the src_name 1378 parameter (if requested) contains 1379 an anonymous internal name. 1380 False - The initiator has been 1381 authenticated normally. 1382 GSS_C_PROT_READY_FLAG 1383 True - Protection services (as specified 1384 by the states of the GSS_C_CONF_FLAG 1385 and GSS_C_INTEG_FLAG) are available 1386 if the accompanying major status 1387 return value is either GSS_S_COMPLETE 1388 or GSS_S_CONTINUE_NEEDED. 1389 False - Protection services (as specified 1390 by the states of the GSS_C_CONF_FLAG 1391 and GSS_C_INTEG_FLAG) are available 1392 only if the accompanying major status 1393 return value is GSS_S_COMPLETE. 1394 GSS_C_TRANS_FLAG 1395 True - The resultant security context may 1396 be transferred to other processes via 1397 a call to gss_export_sec_context(). 1398 False - The security context is not 1399 transferrable. 1400 All other bits should be set to zero. 1402 time_rec Integer, modify, optional 1403 number of seconds for which the context 1404 will remain valid. Specify NULL if 1405 not required. 1407 delegated_cred_handle 1408 gss_cred_id_t, modify, optional 1409 credential handle for credentials received 1410 from context initiator. Only valid if 1411 deleg_flag in ret_flags is true, in which 1412 case an explicit credential handle 1413 (i.e. not GSS_C_NO_CREDENTIAL) will be 1414 returned; if deleg_flag is false, 1415 gss_accept_context() will set this parameter 1416 to GSS_C_NO_CREDENTIAL. If a credential 1417 handle is returned, the associated resources 1418 must be released by the application after use 1419 with a call to gss_release_cred(). Specify 1420 NULL if not required. 1422 minor_status Integer, modify 1423 Mechanism specific status code. 1425 Function value: GSS status code 1427 GSS_S_COMPLETE Successful completion 1428 GSS_S_CONTINUE_NEEDED Indicates that a token from the peer 1429 application is required to complete the 1430 context, and that gss_accept_sec_context 1431 must be called again with that token. 1433 GSS_S_DEFECTIVE_TOKEN Indicates that consistency checks performed 1434 on the input_token failed. 1436 GSS_S_DEFECTIVE_CREDENTIAL Indicates that consistency checks 1437 performed on the credential failed. 1439 GSS_S_NO_CRED The supplied credentials were not valid for 1440 context acceptance, or the credential handle 1441 did not reference any credentials. 1443 GSS_S_CREDENTIALS_EXPIRED The referenced credentials have expired. 1445 GSS_S_BAD_BINDINGS The input_token contains different channel 1446 bindings to those specified via the 1447 input_chan_bindings parameter. 1449 GSS_S_NO_CONTEXT Indicates that the supplied context handle did 1450 not refer to a valid context. 1452 GSS_S_BAD_SIG The input_token contains an invalid MIC. 1454 GSS_S_OLD_TOKEN The input_token was too old. This is a fatal 1455 error during context establishment. 1457 GSS_S_DUPLICATE_TOKEN The input_token is valid, but is a duplicate 1458 of a token already processed. This is a 1459 fatal error during context establishment. 1461 GSS_S_BAD_MECH The received token specified a mechanism that is 1462 not supported by the implementation or the 1463 provided credential. 1465 7.2. gss_acquire_cred 1467 OM_uint32 gss_acquire_cred ( 1468 OM_uint32 *minor_status, 1469 const gss_name_t desired_name, 1470 OM_uint32 time_req, 1471 const gss_OID_set desired_mechs, 1472 gss_cred_usage_t cred_usage, 1473 gss_cred_id_t *output_cred_handle, 1474 gss_OID_set *actual_mechs, 1475 OM_uint32 *time_rec) 1477 Purpose: 1479 Allows an application to acquire a handle for a pre-existing 1480 credential by name. GSS-API implementations must impose a local 1481 access-control policy on callers of this routine to prevent 1482 unauthorized callers from acquiring credentials to which they are not 1483 entitled. This routine is not intended to provide a "login to the 1484 network" function, as such a function would involve the creation of 1485 new credentials rather than merely acquiring a handle to existing 1486 credentials. Such functions, if required, should be defined in 1487 implementation-specific extensions to the API. 1489 If desired_name is GSS_C_NO_NAME, the call is interpreted as a 1490 request for a credential handle that will invoke default behavior 1491 when passed to gss_init_sec_context() (if cred_usage is 1492 GSS_C_INITIATE or GSS_C_BOTH) or gss_accept_sec_context() (if 1493 cred_usage is GSS_C_ACCEPT or GSS_C_BOTH). 1495 Mechanisms should honor the desired_mechs parameter, and return a 1496 credential that is suitable to use only with the requested 1497 mechanisms. An exception to this is the case where one underlying 1498 credential element can be shared by multiple mechanisms; in this case 1499 it is permissible for an implementation to indicate all mechanisms 1500 with which the credential element may be used. If desired_mechs is 1501 an empty set, behavior is undefined. 1503 This routine is expected to be used primarily by context acceptors, 1504 since implementations are likely to provide mechanism-specific ways 1505 of obtaining GSS-API initiator credentials from the system login 1506 process. Some implementations may therefore not support the 1507 acquisition of GSS_C_INITIATE or GSS_C_BOTH credentials via 1508 gss_acquire_cred for any name other than GSS_C_NO_NAME, or a name 1509 produced by applying either gss_inquire_cred to a valid credential, 1510 or gss_inquire_context to an active context. 1512 If credential acquisition is time-consuming for a mechanism, the 1513 mechanism may choose to delay the actual acquisition until the 1514 credential is required (e.g. by gss_init_sec_context or 1515 gss_accept_sec_context). Such mechanism-specific implementation 1516 decisions should be invisible to the calling application; thus a call 1517 of gss_inquire_cred immediately following the call of 1518 gss_acquire_cred must return valid credential data, and may therefore 1519 incur the overhead of a deferred credential acquisition. 1521 Parameters: 1523 desired_name gss_name_t, read 1524 Name of principal whose credential 1525 should be acquired 1527 time_req Integer, read, optional 1528 number of seconds that credentials 1529 should remain valid. Specify GSS_C_INDEFINITE 1530 to request that the credentials have the maximum 1531 permitted lifetime. 1533 desired_mechs Set of Object IDs, read, optional 1534 set of underlying security mechanisms that 1535 may be used. GSS_C_NO_OID_SET may be used 1536 to obtain an implementation-specific default. 1538 cred_usage gss_cred_usage_t, read 1539 GSS_C_BOTH - Credentials may be used 1540 either to initiate or accept 1541 security contexts. 1542 GSS_C_INITIATE - Credentials will only be 1543 used to initiate security contexts. 1544 GSS_C_ACCEPT - Credentials will only be used to 1545 accept security contexts. 1547 output_cred_handle gss_cred_id_t, modify 1548 The returned credential handle. Resources 1549 associated with this credential handle must 1550 be released by the application after use 1551 with a call to gss_release_cred(). 1553 actual_mechs Set of Object IDs, modify, optional 1554 The set of mechanisms for which the 1555 credential is valid. Storage associated 1556 with the returned OID-set must be released by 1557 the application after use with a call to 1558 gss_release_oid_set(). Specify NULL if not 1559 required. 1561 time_rec Integer, modify, optional 1562 Actual number of seconds for which the 1563 returned credentials will remain valid. If the 1564 implementation does not support expiration of 1565 credentials, the value GSS_C_INDEFINITE will 1566 be returned. Specify NULL if not required 1568 minor_status Integer, modify 1569 Mechanism specific status code. 1571 Function value: GSS status code 1572 GSS_S_COMPLETE Successful completion 1574 GSS_S_BAD_MECH Unavailable mechanism requested 1576 GSS_S_BAD_NAMETYPE Type contained within desired_name parameter 1577 is not supported 1579 GSS_S_BAD_NAME Value supplied for desired_name parameter is ill 1580 formed. 1582 GSS_S_CREDENTIALS_EXPIRED The credentials could not be acquired 1583 Because they have expired. 1585 GSS_S_NO_CRED No credentials were found for the specified name. 1587 7.3. gss_add_cred 1589 OM_uint32 gss_add_cred ( 1590 OM_uint32 *minor_status, 1591 const gss_cred_id_t input_cred_handle, 1592 const gss_name_t desired_name, 1593 const gss_OID desired_mech, 1594 gss_cred_usage_t cred_usage, 1595 OM_uint32 initiator_time_req, 1596 OM_uint32 acceptor_time_req, 1597 gss_cred_id_t *output_cred_handle, 1598 gss_OID_set *actual_mechs, 1599 OM_uint32 *initiator_time_rec, 1600 OM_uint32 *acceptor_time_rec) 1602 Purpose: 1604 Adds a credential-element to a credential. The credential-element is 1605 identified by the name of the principal to which it refers. GSS-API 1606 implementations must impose a local access-control policy on callers 1607 of this routine to prevent unauthorized callers from acquiring 1608 credential-elements to which they are not entitled. This routine is 1609 not intended to provide a "login to the network" function, as such a 1610 function would involve the creation of new mechanism-specific 1611 authentication data, rather than merely acquiring a GSS-API handle to 1612 existing data. Such functions, if required, should be defined in 1613 implementation-specific extensions to the API. 1615 If desired_name is GSS_C_NO_NAME, the call is interpreted as a 1616 request to add a credential element that will invoke default behavior 1617 when passed to gss_init_sec_context() (if cred_usage is 1618 GSS_C_INITIATE or GSS_C_BOTH) or gss_accept_sec_context() (if 1619 cred_usage is GSS_C_ACCEPT or GSS_C_BOTH). 1621 This routine is expected to be used primarily by context acceptors, 1622 since implementations are likely to provide mechanism-specific ways 1623 of obtaining GSS-API initiator credentials from the system login 1624 process. Some implementations may therefore not support the 1625 acquisition of GSS_C_INITIATE or GSS_C_BOTH credentials via 1626 gss_acquire_cred for any name other than GSS_C_NO_NAME, or a name 1627 produced by applying either gss_inquire_cred to a valid credential, 1628 or gss_inquire_context to an active context. 1630 If credential acquisition is time-consuming for a mechanism, the 1631 mechanism may choose to delay the actual acquisition until the 1632 credential is required (e.g. by gss_init_sec_context or 1633 gss_accept_sec_context). Such mechanism-specific implementation 1634 decisions should be invisible to the calling application; thus a call 1635 of gss_inquire_cred immediately following the call of gss_add_cred 1636 must return valid credential data, and may therefore incur the 1637 overhead of a deferred credential acquisition. 1639 This routine can be used to either compose a new credential 1640 containing all credential-elements of the original in addition to the 1641 newly-acquire credential-element, or to add the new 1642 credential-element to an existing credential. If NULL is specified 1643 for the output_cred_handle parameter argument, the new 1644 credential-element will be added to the credential identified by 1645 input_cred_handle; if a valid pointer is specified for the 1646 output_cred_handle parameter, a new credential handle will be 1647 created. 1649 If GSS_C_NO_CREDENTIAL is specified as the input_cred_handle, 1650 gss_add_cred will compose a credential (and set the 1651 output_cred_handle parameter accordingly) based on default behavior. 1652 That is, the call will have the same effect as if the application had 1653 first made a call to gss_acquire_cred(), specifying the same usage 1654 and passing GSS_C_NO_NAME as the desired_name parameter to obtain an 1655 explicit credential handle embodying default behavior, passed this 1656 credential handle to gss_add_cred(), and finally called 1657 gss_release_cred() on the first credential handle. 1659 If GSS_C_NO_CREDENTIAL is specified as the input_cred_handle 1660 parameter, a non-NULL output_cred_handle must be supplied. 1662 Parameters: 1664 minor_status Integer, modify 1665 Mechanism specific status code. 1667 input_cred_handle gss_cred_id_t, read, optional 1668 The credential to which a credential-element 1669 will be added. If GSS_C_NO_CREDENTIAL is 1670 specified, the routine will compose the new 1671 credential based on default behavior (see 1672 description above). Note that, while the 1673 credential-handle is not modified by 1674 gss_add_cred(), the underlying credential 1675 will be modified if output_credential_handle 1676 is NULL. 1678 desired_name gss_name_t, read. 1679 Name of principal whose credential 1680 should be acquired. 1682 desired_mech Object ID, read 1683 Underlying security mechanism with which the 1684 credential may be used. 1686 cred_usage gss_cred_usage_t, read 1687 GSS_C_BOTH - Credential may be used 1688 either to initiate or accept 1689 security contexts. 1690 GSS_C_INITIATE - Credential will only be 1691 used to initiate security 1692 contexts. 1693 GSS_C_ACCEPT - Credential will only be used to 1694 accept security contexts. 1696 initiator_time_req Integer, read, optional 1697 number of seconds that the credential 1698 should remain valid for initiating security 1699 contexts. This argument is ignored if the 1700 composed credentials are of type GSS_C_ACCEPT. 1701 Specify GSS_C_INDEFINITE to request that the 1702 credentials have the maximum permitted 1703 initiator lifetime. 1705 acceptor_time_req Integer, read, optional 1706 number of seconds that the credential 1707 should remain valid for accepting security 1708 contexts. This argument is ignored if the 1709 composed credentials are of type GSS_C_INITIATE. 1710 Specify GSS_C_INDEFINITE to request that the 1711 credentials have the maximum permitted initiator 1712 lifetime. 1714 output_cred_handle gss_cred_id_t, modify, optional 1715 The returned credential handle, containing 1716 the new credential-element and all the 1717 credential-elements from input_cred_handle. 1718 If a valid pointer to a gss_cred_id_t is 1719 supplied for this parameter, gss_add_cred 1720 creates a new credential handle containing all 1721 credential-elements from the input_cred_handle 1722 and the newly acquired credential-element; if 1723 NULL is specified for this parameter, the newly 1724 acquired credential-element will be added 1725 to the credential identified by input_cred_handle. 1727 The resources associated with any credential 1728 handle returned via this parameter must be 1729 released by the application after use with a 1730 call to gss_release_cred(). 1732 actual_mechs Set of Object IDs, modify, optional 1733 The complete set of mechanisms for which 1734 the new credential is valid. Storage for 1735 the returned OID-set must be freed by the 1736 application after use with a call to 1737 gss_release_oid_set(). Specify NULL if 1738 not required. 1740 initiator_time_rec Integer, modify, optional 1741 Actual number of seconds for which the 1742 returned credentials will remain valid for 1743 initiating contexts using the specified 1744 mechanism. If the implementation or mechanism 1745 does not support expiration of credentials, the 1746 value GSS_C_INDEFINITE will be returned. Specify 1747 NULL if not required 1749 acceptor_time_rec Integer, modify, optional 1750 Actual number of seconds for which the 1751 returned credentials will remain valid for 1752 accepting security contexts using the specified 1753 mechanism. If the implementation or mechanism 1754 does not support expiration of credentials, the 1755 value GSS_C_INDEFINITE will be returned. Specify 1756 NULL if not required 1758 Function value: GSS status code 1760 GSS_S_COMPLETE Successful completion 1762 GSS_S_BAD_MECH Unavailable mechanism requested 1764 GSS_S_BAD_NAMETYPE Type contained within desired_name parameter 1765 is not supported 1767 GSS_S_BAD_NAME Value supplied for desired_name parameter is 1768 ill-formed. 1770 GSS_S_DUPLICATE_ELEMENT The credential already contains an element 1771 for the requested mechanism with overlapping 1772 usage and validity period. 1774 GSS_S_CREDENTIALS_EXPIRED The required credentials could not be 1775 added because they have expired. 1777 GSS_S_NO_CRED No credentials were found for the specified name. 1779 7.4. gss_add_oid_set_member 1781 OM_uint32 gss_add_oid_set_member ( 1782 OM_uint32 *minor_status, 1783 const gss_OID member_oid, 1784 gss_OID_set *oid_set) 1786 Purpose: 1788 Add an Object Identifier to an Object Identifier set. This routine 1789 is intended for use in conjunction with gss_create_empty_oid_set when 1790 constructing a set of mechanism OIDs for input to gss_acquire_cred. 1791 The oid_set parameter must refer to an OID-set that was created by 1792 GSS-API (e.g. a set returned by gss_create_empty_oid_set()). GSS-API 1793 creates a copy of the member_oid and inserts this copy into the set, 1794 expanding the storage allocated to the OID-set's elements array if 1795 necessary. The routine may add the new member OID anywhere within 1796 the elements array, and implementations should verify that the new 1797 member_oid is not already contained within the elements array; if the 1798 member_oid is already present, the oid_set should remain unchanged. 1800 Parameters: 1802 minor_status Integer, modify 1803 Mechanism specific status code 1805 member_oid Object ID, read 1806 The object identifier to copied into 1807 the set. 1809 oid_set Set of Object ID, modify 1810 The set in which the object identifier 1811 should be inserted. 1813 Function value: GSS status code 1815 GSS_S_COMPLETE Successful completion 1816 7.5. gss_canonicalize_name 1818 OM_uint32 gss_canonicalize_name ( 1819 OM_uint32 *minor_status, 1820 const gss_name_t input_name, 1821 const gss_OID mech_type, 1822 gss_name_t *output_name) 1824 Purpose: 1826 Generate a canonical mechanism name (MN) from an arbitrary internal 1827 name. The mechanism name is the name that would be returned to a 1828 context acceptor on successful authentication of a context where the 1829 initiator used the input_name in a successful call to 1830 gss_acquire_cred, specifying an OID set containing as its 1831 only member, followed by a call to gss_init_sec_context, specifying 1832 as the authentication mechanism. 1834 Parameters: 1836 minor_status Integer, modify 1837 Mechanism specific status code 1839 input_name gss_name_t, read 1840 The name for which a canonical form is 1841 desired 1843 mech_type Object ID, read 1844 The authentication mechanism for which the 1845 canonical form of the name is desired. The 1846 desired mechanism must be specified explicitly; 1847 no default is provided. 1849 output_name gss_name_t, modify 1850 The resultant canonical name. Storage 1851 associated with this name must be freed by 1852 the application after use with a call to 1853 gss_release_name(). 1855 Function value: GSS status code 1857 GSS_S_COMPLETE Successful completion. 1859 GSS_S_BAD_MECH The identified mechanism is not supported. 1861 GSS_S_BAD_NAMETYPE The provided internal name contains no elements 1862 that could be processed by the specified 1863 mechanism. 1865 GSS_S_BAD_NAME The provided internal name was ill-formed. 1867 7.6. gss_compare_name 1869 OM_uint32 gss_compare_name ( 1870 OM_uint32 *minor_status, 1871 const gss_name_t name1, 1872 const gss_name_t name2, 1873 int *name_equal) 1875 Purpose: 1877 Allows an application to compare two internal-form names to determine 1878 whether they refer to the same entity. 1880 If either name presented to gss_compare_name denotes an anonymous 1881 principal, the routines should indicate that the two names do not 1882 refer to the same identity. 1884 Parameters: 1886 minor_status Integer, modify 1887 Mechanism specific status code. 1889 name1 gss_name_t, read 1890 internal-form name 1892 name2 gss_name_t, read 1893 internal-form name 1895 name_equal boolean, modify 1896 non-zero - names refer to same entity 1897 zero - names refer to different entities 1898 (strictly, the names are not known 1899 to refer to the same identity). 1901 Function value: GSS status code 1903 GSS_S_COMPLETE Successful completion 1905 GSS_S_BAD_NAMETYPE The two names were of incomparable types. 1907 GSS_S_BAD_NAME One or both of name1 or name2 was ill-formed. 1909 7.7. gss_context_time 1911 OM_uint32 gss_context_time ( 1912 OM_uint32 *minor_status, 1913 const gss_ctx_id_t context_handle, 1914 OM_uint32 *time_rec) 1916 Purpose: 1918 Determines the number of seconds for which the specified context will 1919 remain valid. 1921 Parameters: 1923 minor_status Integer, modify 1924 Implementation specific status code. 1926 context_handle gss_ctx_id_t, read 1927 Identifies the context to be interrogated. 1929 time_rec Integer, modify 1930 Number of seconds that the context will remain 1931 valid. If the context has already expired, 1932 zero will be returned. 1934 Function value: GSS status code 1936 GSS_S_COMPLETE Successful completion 1938 GSS_S_CONTEXT_EXPIRED The context has already expired 1940 GSS_S_NO_CONTEXT The context_handle parameter did not identify 1941 a valid context 1942 7.8. gss_create_empty_oid_set 1944 OM_uint32 gss_create_empty_oid_set ( 1945 OM_uint32 *minor_status, 1946 gss_OID_set *oid_set) 1948 Purpose: 1950 Create an object-identifier set containing no object identifiers, to 1951 which members may be subsequently added using the 1952 gss_add_oid_set_member() routine. These routines are intended to be 1953 used to construct sets of mechanism object identifiers, for input to 1954 gss_acquire_cred. 1956 Parameters: 1958 minor_status Integer, modify 1959 Mechanism specific status code 1961 oid_set Set of Object IDs, modify 1962 The empty object identifier set. 1963 The routine will allocate the 1964 gss_OID_set_desc object, which the 1965 application must free after use with 1966 a call to gss_release_oid_set(). 1968 Function value: GSS status code 1970 GSS_S_COMPLETE Successful completion 1971 7.9. gss_delete_sec_context 1973 OM_uint32 gss_delete_sec_context ( 1974 OM_uint32 *minor_status, 1975 gss_ctx_id_t *context_handle, 1976 gss_buffer_t output_token) 1978 Purpose: 1980 Delete a security context. gss_delete_sec_context will delete the 1981 local data structures associated with the specified security context, 1982 and may generate an output_token, which when passed to the peer 1983 gss_process_context_token will instruct it to do likewise. If no 1984 token is required by the mechanism, the GSS-API should set the length 1985 field of the output_token (if provided) to zero. No further security 1986 services may be obtained using the context specified by 1987 context_handle. 1989 In addition to deleting established security contexts, 1990 gss_delete_sec_context must also be able to delete "half-built" 1991 security contexts resulting from an incomplete sequence of 1992 gss_init_sec_context()/gss_accept_sec_context() calls. 1994 The output_token parameter is retained for compatibility with version 1995 1 of the GSS-API. It is recommended that both peer applications 1996 invoke gss_delete_sec_context passing the value GSS_C_NO_BUFFER for 1997 the output_token parameter, indicating that no token is required, and 1998 that gss_delete_sec_context should simply delete local context data 1999 structures. If the application does pass a valid buffer to 2000 gss_delete_sec_context, mechanisms are encouraged to return a 2001 zero-length token, indicating that no peer action is necessary, and 2002 that no token should be transferred by the application. 2004 Parameters: 2006 minor_status Integer, modify 2007 Mechanism specific status code. 2009 context_handle gss_ctx_id_t, modify 2010 context handle identifying context to delete. 2011 After deleting the context, the GSS-API will set 2012 this context handle to GSS_C_NO_CONTEXT. 2014 output_token buffer, opaque, modify, optional 2015 token to be sent to remote application to 2016 instruct it to also delete the context. It 2017 is recommended that applications specify 2018 GSS_C_NO_BUFFER for this parameter, requesting 2019 local deletion only. If a buffer parameter is 2020 provided by the application, the mechanism may 2021 return a token in it; mechanisms that implement 2022 only local deletion should set the length field of 2023 this token to zero to indicate to the application 2024 that no token is to be sent to the peer. 2026 Function value: GSS status code 2028 GSS_S_COMPLETE Successful completion 2030 GSS_S_NO_CONTEXT No valid context was supplied 2031 7.10.gss_display_name 2033 OM_uint32 gss_display_name ( 2034 OM_uint32 *minor_status, 2035 const gss_name_t input_name, 2036 gss_buffer_t output_name_buffer, 2037 gss_OID *output_name_type) 2039 Purpose: 2041 Allows an application to obtain a textual representation of an opaque 2042 internal-form name for display purposes. The syntax of a printable 2043 name is defined by the GSS-API implementation. 2045 If input_name denotes an anonymous principal, the implementation 2046 should return the gss_OID value GSS_C_NT_ANONYMOUS as the 2047 output_name_type, and a textual name that is syntactically distinct 2048 from all valid supported printable names in output_name_buffer. 2050 If input_name was created by a call to gss_import_name, specifying 2051 GSS_C_NO_OID as the name-type, implementations that employ lazy 2052 conversion between name types may return GSS_C_NO_OID via the 2053 output_name_type parameter. 2055 Parameters: 2057 minor_status Integer, modify 2058 Mechanism specific status code. 2060 input_name gss_name_t, read 2061 name to be displayed 2063 output_name_buffer buffer, character-string, modify 2064 buffer to receive textual name string. 2065 The application must free storage associated 2066 with this name after use with a call to 2067 gss_release_buffer(). 2069 output_name_type Object ID, modify, optional 2070 The type of the returned name. The returned 2071 gss_OID will be a pointer into static storage, 2072 and should be treated as read-only by the caller 2073 (in particular, the application should not attempt 2074 to free it). Specify NULL if not required. 2076 Function value: GSS status code 2078 GSS_S_COMPLETE Successful completion 2080 GSS_S_BAD_NAME input_name was ill-formed 2081 7.11.gss_display_status 2083 OM_uint32 gss_display_status ( 2084 OM_uint32 *minor_status, 2085 OM_uint32 status_value, 2086 int status_type, 2087 const gss_OID mech_type, 2088 OM_uint32 *message_context, 2089 gss_buffer_t status_string) 2091 Purpose: 2093 Allows an application to obtain a textual representation of a GSS-API 2094 status code, for display to the user or for logging purposes. Since 2095 some status values may indicate multiple conditions, applications may 2096 need to call gss_display_status multiple times, each call generating 2097 a single text string. The message_context parameter is used by 2098 gss_display_status to store state information about which error 2099 messages have already been extracted from a given status_value; 2100 message_context must be initialized to 0 by the application prior to 2101 the first call, and gss_display_status will return a non-zero value 2102 in this parameter if there are further messages to extract. 2104 The message_context parameter contains all state information required 2105 by gss_display_status in order to extract further messages from the 2106 status_value; even when a non-zero value is returned in this 2107 parameter, the application is not required to call gss_display_status 2108 again unless subsequent messages are desired. The following code 2109 extracts all messages from a given status code and prints them to 2110 stderr: 2112 OM_uint32 message_context; 2113 OM_uint32 status_code; 2114 OM_uint32 maj_status; 2115 OM_uint32 min_status; 2116 gss_buffer_desc status_string; 2118 ... 2120 message_context = 0; 2122 do { 2124 maj_status = gss_display_status ( 2125 &min_status, 2126 status_code, 2127 GSS_C_GSS_CODE, 2128 GSS_C_NO_OID, 2129 &message_context, 2130 &status_string) 2132 fprintf(stderr, 2133 "%.*s\n", 2134 (int)status_string.length, 2135 (char *)status_string.value); 2137 gss_release_buffer(&min_status, &status_string); 2139 } while (message_context != 0); 2141 Parameters: 2143 minor_status Integer, modify 2144 Mechanism specific status code. 2146 status_value Integer, read 2147 Status value to be converted 2149 status_type Integer, read 2150 GSS_C_GSS_CODE - status_value is a GSS status 2151 code 2153 GSS_C_MECH_CODE - status_value is a mechanism 2154 status code 2156 mech_type Object ID, read, optional 2157 Underlying mechanism (used to interpret a 2158 minor status value) Supply GSS_C_NO_OID to 2159 obtain the system default. 2161 message_context Integer, read/modify 2162 Should be initialized to zero by the 2163 application prior to the first call. 2164 On return from gss_display_status(), 2165 a non-zero status_value parameter indicates 2166 that additional messages may be extracted 2167 from the status code via subsequent calls 2168 to gss_display_status(), passing the same 2169 status_value, status_type, mech_type, and 2170 message_context parameters. 2172 status_string buffer, character string, modify 2173 textual interpretation of the status_value. 2174 Storage associated with this parameter must 2175 be freed by the application after use with 2176 a call to gss_release_buffer(). 2178 Function value: GSS status code 2180 GSS_S_COMPLETE Successful completion 2182 GSS_S_BAD_MECH Indicates that translation in accordance with 2183 an unsupported mechanism type was requested 2185 GSS_S_BAD_STATUS The status value was not recognized, or the 2186 status type was neither GSS_C_GSS_CODE nor 2187 GSS_C_MECH_CODE. 2189 7.12.gss_duplicate_name 2191 OM_uint32 gss_duplicate_name ( 2192 OM_uint32 *minor_status, 2193 const gss_name_t src_name, 2194 gss_name_t *dest_name) 2196 Purpose: 2198 Create an exact duplicate of the existing internal name src_name. 2199 The new dest_name will be independent of src_name (i.e. src_name and 2200 dest_name must both be released, and the release of one shall not 2201 affect the validity of the other). 2203 Parameters: 2205 minor_status Integer, modify 2206 Mechanism specific status code. 2208 src_name gss_name_t, read 2209 internal name to be duplicated. 2211 dest_name gss_name_t, modify 2212 The resultant copy of . 2213 Storage associated with this name must 2214 be freed by the application after use 2215 with a call to gss_release_name(). 2217 Function value: GSS status code 2219 GSS_S_COMPLETE Successful completion 2221 GSS_S_BAD_NAME The src_name parameter was ill-formed. 2223 7.13.gss_export_name 2225 OM_uint32 gss_export_name ( 2226 OM_uint32 *minor_status, 2227 const gss_name_t input_name, 2228 gss_buffer_t exported_name) 2230 Purpose: 2232 To produce a canonical contiguous string representation of a 2233 mechanism name (MN), suitable for direct comparison (e.g. with 2234 memcmp) for use in authorization functions (e.g. matching entries in 2235 an access-control list). 2236 The parameter must specify a valid MN (i.e. an internal 2237 name generated by gss_accept_sec_context or by 2238 gss_canonicalize_name). 2240 Parameters: 2242 minor_status Integer, modify 2243 Mechanism specific status code 2245 input_name gss_name_t, read 2246 The MN to be exported 2248 exported_name gss_buffer_t, octet-string, modify 2249 The canonical contiguous string form of 2250 . Storage associated with 2251 this string must freed by the application 2252 after use with gss_release_buffer(). 2254 Function value: GSS status code 2256 GSS_S_COMPLETE Successful completion 2258 GSS_S_NAME_NOT_MN The provided internal name was not a mechanism 2259 name. 2261 GSS_S_BAD_NAME The provided internal name was ill-formed. 2263 GSS_S_BAD_NAMETYPE The internal name was of a type not supported 2264 by the GSS-API implementation. 2266 7.14.gss_export_sec_context 2268 OM_uint32 gss_export_sec_context ( 2269 OM_uint32 *minor_status, 2270 gss_ctx_id_t *context_handle, 2271 gss_buffer_t interprocess_token) 2273 Purpose: 2275 Provided to support the sharing of work between multiple processes. 2276 This routine will typically be used by the context-acceptor, in an 2277 application where a single process receives incoming connection 2278 requests and accepts security contexts over them, then passes the 2279 established context to one or more other processes for message 2280 exchange. gss_export_sec_context() deactivates the security context 2281 for the calling process and creates an interprocess token which, when 2282 passed to gss_import_sec_context in another process, will re-activate 2283 the context in the second process. Only a single instantiation of a 2284 given context may be active at any one time; a subsequent attempt by 2285 a context exporter to access the exported security context will fail. 2287 The implementation may constrain the set of processes by which the 2288 interprocess token may be imported, either as a function of local 2289 security policy, or as a result of implementation decisions. For 2290 example, some implementations may constrain contexts to be passed 2291 only between processes that run under the same account, or which are 2292 part of the same process group. 2294 The interprocess token may contain security-sensitive information 2295 (for example cryptographic keys). While mechanisms are encouraged to 2296 either avoid placing such sensitive information within interprocess 2297 tokens, or to encrypt the token before returning it to the 2298 application, in a typical object-library GSS-API implementation this 2299 may not be possible. Thus the application must take care to protect 2300 the interprocess token, and ensure that any process to which the 2301 token is transferred is trustworthy. 2303 If creation of the interprocess token is succesful, the 2304 implementation shall deallocate all process-wide resources associated 2305 with the security context, and set the context_handle to 2306 GSS_C_NO_CONTEXT. In the event of an error that makes it impossible 2307 to complete the export of the security context, the implementation 2308 must not return an interprocess token, and should strive to leave the 2309 security context referenced by the context_handle parameter 2310 untouched. If this is impossible, it is permissible for the 2311 implementation to delete the security context, providing it also sets 2312 the context_handle parameter to GSS_C_NO_CONTEXT. 2314 Parameters: 2316 minor_status Integer, modify 2317 Mechanism specific status code 2319 context_handle gss_ctx_id_t, modify 2320 context handle identifying the context to 2321 transfer. 2323 interprocess_token buffer, opaque, modify 2324 token to be transferred to target process. 2325 Storage associated with this token must be 2326 freed by the application after use with a 2327 call to gss_release_buffer(). 2329 Function value: GSS status code 2331 GSS_S_COMPLETE Successful completion 2333 GSS_S_CONTEXT_EXPIRED The context has expired 2335 GSS_S_NO_CONTEXT The context was invalid 2337 GSS_S_UNAVAILABLE The operation is not supported. 2339 7.15.gss_get_mic 2341 OM_uint32 gss_get_mic ( 2342 OM_uint32 *minor_status, 2343 const gss_ctx_id_t context_handle, 2344 gss_qop_t qop_req, 2345 const gss_buffer_t message_buffer, 2346 gss_buffer_t msg_token) 2348 Purpose: 2350 Generates a cryptographic MIC for the supplied message, and places 2351 the MIC in a token for transfer to the peer application. The qop_req 2352 parameter allows a choice between several cryptographic algorithms, 2353 if supported by the chosen mechanism. 2355 Since some application-level protocols may wish to use tokens emitted 2356 by gss_wrap() to provide "secure framing", implementations must 2357 support derivation of MICs from zero-length messages. 2359 Parameters: 2361 minor_status Integer, modify 2362 Implementation specific status code. 2364 context_handle gss_ctx_id_t, read 2365 identifies the context on which the message 2366 will be sent 2368 qop_req gss_qop_t, read, optional 2369 Specifies requested quality of protection. 2370 Callers are encouraged, on portability grounds, 2371 to accept the default quality of protection 2372 offered by the chosen mechanism, which may be 2373 requested by specifying GSS_C_QOP_DEFAULT for 2374 this parameter. If an unsupported protection 2375 strength is requested, gss_get_mic will return a 2376 major_status of GSS_S_BAD_QOP. 2378 message_buffer buffer, opaque, read 2379 message to be protected 2381 msg_token buffer, opaque, modify 2382 buffer to receive token. The application must 2383 free storage associated with this buffer after 2384 use with a call to gss_release_buffer(). 2386 Function value: GSS status code 2388 GSS_S_COMPLETE Successful completion 2390 GSS_S_CONTEXT_EXPIRED The context has already expired 2392 GSS_S_NO_CONTEXT The context_handle parameter did not identify 2393 a valid context 2395 GSS_S_BAD_QOP The specified QOP is not supported by the 2396 mechanism. 2398 7.16.gss_import_name 2400 OM_uint32 gss_import_name ( 2401 OM_uint32 *minor_status, 2402 const gss_buffer_t input_name_buffer, 2403 const gss_OID input_name_type, 2404 gss_name_t *output_name) 2406 Purpose: 2408 Convert a contiguous string name to internal form. In general, the 2409 internal name returned (via the parameter) will not be 2410 an MN; the exception to this is if the indicates 2411 that the contiguous string provided via the 2412 parameter is of type GSS_C_NT_EXPORT_NAME, in which case the returned 2413 internal name will be an MN for the mechanism that exported the name. 2415 Parameters: 2417 minor_status Integer, modify 2418 Mechanism specific status code 2420 input_name_buffer buffer, octet-string, read 2421 buffer containing contiguous string name to convert 2423 input_name_type Object ID, read, optional 2424 Object ID specifying type of printable 2425 name. Applications may specify either 2426 GSS_C_NO_OID to use a mechanism-specific 2427 default printable syntax, or an OID recognized 2428 by the GSS-API implementation to name a 2429 specific namespace. 2431 output_name gss_name_t, modify 2432 returned name in internal form. Storage 2433 associated with this name must be freed 2434 by the application after use with a call 2435 to gss_release_name(). 2437 Function value: GSS status code 2439 GSS_S_COMPLETE Successful completion 2441 GSS_S_BAD_NAMETYPE The input_name_type was unrecognized 2443 GSS_S_BAD_NAME The input_name parameter could not be interpreted 2444 as a name of the specified type 2446 GSS_S_BAD_MECH The input name-type was GSS_C_NT_EXPORT_NAME, 2447 but the mechanism contained within the 2448 input-name is not supported 2449 7.17.gss_import_sec_context 2451 OM_uint32 gss_import_sec_context ( 2452 OM_uint32 *minor_status, 2453 const gss_buffer_t interprocess_token, 2454 gss_ctx_id_t *context_handle) 2456 Purpose: 2458 Allows a process to import a security context established by another 2459 process. A given interprocess token may be imported only once. See 2460 gss_export_sec_context. 2462 Parameters: 2464 minor_status Integer, modify 2465 Mechanism specific status code 2467 interprocess_token buffer, opaque, modify 2468 token received from exporting process 2470 context_handle gss_ctx_id_t, modify 2471 context handle of newly reactivated context. 2472 Resources associated with this context handle 2473 must be released by the application after use 2474 with a call to gss_delete_sec_context(). 2476 Function value: GSS status code 2478 GSS_S_COMPLETE Successful completion. 2480 GSS_S_NO_CONTEXT The token did not contain a valid context 2481 reference. 2483 GSS_S_DEFECTIVE_TOKEN The token was invalid. 2485 GSS_S_UNAVAILABLE The operation is unavailable. 2487 GSS_S_UNAUTHORIZED Local policy prevents the import of this context 2488 by the current process. 2490 7.18.gss_indicate_mechs 2492 OM_uint32 gss_indicate_mechs ( 2493 OM_uint32 *minor_status, 2494 gss_OID_set *mech_set) 2496 Purpose: 2498 Allows an application to determine which underlying security 2499 mechanisms are available. 2501 Parameters: 2503 minor_status Integer, modify 2504 Mechanism specific status code. 2506 mech_set set of Object IDs, modify 2507 set of implementation-supported mechanisms. 2508 The returned gss_OID_set value will be a 2509 dynamically-allocated OID set, that should 2510 be released by the caller after use with a 2511 call to gss_release_oid_set(). 2513 Function value: GSS status code 2515 GSS_S_COMPLETE Successful completion 2516 7.19.gss_init_sec_context 2518 OM_uint32 gss_init_sec_context ( 2519 OM_uint32 *minor_status, 2520 const gss_cred_id_t initiator_cred_handle, 2521 gss_ctx_id_t *context_handle,\ 2522 const gss_name_t target_name, 2523 const gss_OID mech_type, 2524 OM_uint32 req_flags, 2525 OM_uint32 time_req, 2526 const gss_channel_bindings_t input_chan_bindings, 2527 const gss_buffer_t input_token 2528 gss_OID *actual_mech_type, 2529 gss_buffer_t output_token, 2530 OM_uint32 *ret_flags, 2531 OM_uint32 *time_rec ) 2533 Purpose: 2535 Initiates the establishment of a security context between the 2536 application and a remote peer. Initially, the input_token parameter 2537 should be specified either as GSS_C_NO_BUFFER, or as a pointer to a 2538 gss_buffer_desc object whose length field contains the value zero. 2539 The routine may return a output_token which should be transferred to 2540 the peer application, where the peer application will present it to 2541 gss_accept_sec_context. If no token need be sent, 2542 gss_init_sec_context will indicate this by setting the length field 2543 of the output_token argument to zero. To complete the context 2544 establishment, one or more reply tokens may be required from the peer 2545 application; if so, gss_init_sec_context will return a status 2546 containing the supplementary information bit GSS_S_CONTINUE_NEEDED. 2547 In this case, gss_init_sec_context should be called again when the 2548 reply token is received from the peer application, passing the reply 2549 token to gss_init_sec_context via the input_token parameters. 2551 Portable applications should be constructed to use the token length 2552 and return status to determine whether a token needs to be sent or 2553 waited for. Thus a typical portable caller should always invoke 2554 gss_init_sec_context within a loop: 2556 int context_established = 0; 2557 gss_ctx_id_t context_hdl = GSS_C_NO_CONTEXT; 2558 ... 2559 input_token->length = 0; 2561 while (!context_established) { 2562 maj_stat = gss_init_sec_context(&min_stat, 2563 cred_hdl, 2564 &context_hdl, 2565 target_name, 2566 desired_mech, 2567 desired_services, 2568 desired_time, 2569 input_bindings, 2570 input_token, 2571 &actual_mech, 2572 output_token, 2573 &actual_services, 2574 &actual_time); 2575 if (GSS_ERROR(maj_stat)) { 2576 report_error(maj_stat, min_stat); 2577 }; 2579 if (output_token->length != 0) { 2580 send_token_to_peer(output_token); 2581 gss_release_buffer(&min_stat, output_token) 2582 }; 2583 if (GSS_ERROR(maj_stat)) { 2585 if (context_hdl != GSS_C_NO_CONTEXT) 2586 gss_delete_sec_context(&min_stat, 2587 &context_hdl, 2588 GSS_C_NO_BUFFER); 2589 break; 2590 }; 2591 if (maj_stat & GSS_S_CONTINUE_NEEDED) { 2592 receive_token_from_peer(input_token); 2593 } else { 2594 context_established = 1; 2595 }; 2596 }; 2598 Whenever the routine returns a major status that includes the value 2599 GSS_S_CONTINUE_NEEDED, the context is not fully established and the 2600 following restrictions apply to the output parameters: 2602 The value returned via the time_rec parameter is undefined 2603 Unless the accompanying ret_flags parameter contains the bit 2604 GSS_C_PROT_READY_FLAG, indicating that per-message services may 2605 be applied in advance of a successful completion status, the 2606 value returned via the actual_mech_type parameter is undefined 2607 until the routine returns a major status value of 2608 GSS_S_COMPLETE. 2610 The values of the GSS_C_DELEG_FLAG, GSS_C_MUTUAL_FLAG, 2611 GSS_C_REPLAY_FLAG, GSS_C_SEQUENCE_FLAG, GSS_C_CONF_FLAG, 2612 GSS_C_INTEG_FLAG and GSS_C_ANON_FLAG bits returned via the 2613 ret_flags parameter should contain the values that the 2614 implementation expects would be valid if context establishment 2615 were to succeed. In particular, if the application has 2616 requested a service such as delegation or anonymous 2617 authentication via the req_flags argument, and such a service 2618 is unavailable from the underlying mechanism, 2619 gss_init_sec_context should generate a token that will not 2620 provide the service, and indicate via the ret_flags argument 2621 that the service will not be supported. The application may 2622 choose to abort the context establishment by calling 2623 gss_delete_sec_context (if it cannot continue in the absence 2624 of the service), or it may choose to transmit the token 2625 and continue context establishment (if the service was merely 2626 desired but not mandatory). 2628 The values of the GSS_C_PROT_READY_FLAG and GSS_C_TRANS_FLAG 2629 bits within ret_flags should indicate the actual state at the 2630 time gss_init_sec_context returns, whether or not the context 2631 is fully established. 2633 GSS-API implementations that support per-message protection 2634 are encouraged to set the GSS_C_PROT_READY_FLAG in the final 2635 ret_flags returned to a caller (i.e. when accompanied by a 2636 GSS_S_COMPLETE status code). However, applications should not 2637 rely on this behavior as the flag was not defined in Version 1 2638 of the GSS-API. Instead, applications should determine what 2639 per-message services are available after a successful context 2640 establishment according to the GSS_C_INTEG_FLAG and 2641 GSS_C_CONF_FLAG values. 2643 All other bits within the ret_flags argument should be set 2644 to zero. 2646 If the initial call of gss_init_sec_context() fails, the 2647 implementation should not create a context object, and should leave 2648 the value of the context_handle parameter set to GSS_C_NO_CONTEXT to 2649 indicate this. In the event of a failure on a subsequent call, the 2650 implementation is permitted to delete the "half-built" security 2651 context (in which case it should set the context_handle parameter to 2652 GSS_C_NO_CONTEXT), but the preferred behavior is to leave the 2653 security context untouched for the application to delete (using 2654 gss_delete_sec_context). 2656 During context establishment, the informational status bits 2657 GSS_S_OLD_TOKEN and GSS_S_DUPLICATE_TOKEN indicate fatal errors, and 2658 GSS-API mechanisms should always return them in association with a 2659 routine error of GSS_S_FAILURE. This requirement for pairing did not 2660 exist in version 1 of the GSS-API specification, so applications that 2661 wish to run over version 1 implementations must special-case these 2662 codes. 2664 Parameters: 2666 minor_status Integer, modify 2667 Mechanism specific status code. 2669 initiator_cred_handle gss_cred_id_t, read, optional 2670 handle for credentials claimed. Supply 2671 GSS_C_NO_CREDENTIAL to act as a default 2672 initiator principal. If no default 2673 initiator is defined, the function will 2674 return GSS_S_NO_CRED. 2676 context_handle gss_ctx_id_t, read/modify 2677 context handle for new context. Supply 2678 GSS_C_NO_CONTEXT for first call; use value 2679 returned by first call in continuation calls. 2680 Resources associated with this context-handle 2681 must be released by the application after use 2682 with a call to gss_delete_sec_context(). 2684 target_name gss_name_t, read 2685 Name of target 2687 mech_type OID, read, optional 2688 Object ID of desired mechanism. Supply 2689 GSS_C_NO_OID to obtain an implementation 2690 specific default 2692 req_flags bit-mask, read 2693 Contains various independent flags, each of 2694 which requests that the context support a 2695 specific service option. Symbolic 2696 names are provided for each flag, and the 2697 symbolic names corresponding to the required 2698 flags should be logically-ORed 2699 together to form the bit-mask value. The 2700 flags are: 2702 GSS_C_DELEG_FLAG 2703 True - Delegate credentials to remote peer 2704 False - Don't delegate 2706 GSS_C_MUTUAL_FLAG 2707 True - Request that remote peer 2708 authenticate itself 2709 False - Authenticate self to remote peer 2710 only 2712 GSS_C_REPLAY_FLAG 2713 True - Enable replay detection for 2714 messages protected with gss_wrap 2715 or gss_get_mic 2716 False - Don't attempt to detect 2717 replayed messages 2719 GSS_C_SEQUENCE_FLAG 2720 True - Enable detection of out-of-sequence 2721 protected messages 2722 False - Don't attempt to detect 2723 out-of-sequence messages 2725 GSS_C_CONF_FLAG 2726 True - Request that confidentiality service 2727 be made available (via gss_wrap) 2728 False - No per-message confidentiality service 2729 is required. 2731 GSS_C_INTEG_FLAG 2732 True - Request that integrity service be 2733 made available (via gss_wrap or 2734 gss_get_mic) 2735 False - No per-message integrity service 2736 is required. 2738 GSS_C_ANON_FLAG 2739 True - Do not reveal the initiator's 2740 identity to the acceptor. 2741 False - Authenticate normally. 2743 time_req Integer, read, optional 2744 Desired number of seconds for which context 2745 should remain valid. Supply 0 to request a 2746 default validity period. 2748 input_chan_bindings channel bindings, read, optional 2749 Application-specified bindings. Allows 2750 application to securely bind channel 2751 identification information to the security 2752 context. Specify GSS_C_NO_CHANNEL_BINDINGS 2753 if channel bindings are not used. 2755 input_token buffer, opaque, read, optional (see text) 2756 Token received from peer application. 2757 Supply GSS_C_NO_BUFFER, or a pointer to 2758 a buffer containing the value GSS_C_EMPTY_BUFFER 2759 on initial call. 2761 actual_mech_type OID, modify, optional 2762 Actual mechanism used. The OID returned via 2763 this parameter will be a pointer to static 2764 storage that should be treated as read-only; 2765 In particular the application should not attempt 2766 to free it. Specify NULL if not required. 2768 output_token buffer, opaque, modify 2769 token to be sent to peer application. If 2770 the length field of the returned buffer is 2771 zero, no token need be sent to the peer 2772 application. Storage associated with this 2773 buffer must be freed by the application 2774 after use with a call to gss_release_buffer(). 2776 ret_flags bit-mask, modify, optional 2777 Contains various independent flags, each of which 2778 indicates that the context supports a specific 2779 service option. Specify NULL if not 2780 required. Symbolic names are provided 2781 for each flag, and the symbolic names 2782 corresponding to the required flags should be 2783 logically-ANDed with the ret_flags value to test 2784 whether a given option is supported by the 2785 context. The flags are: 2787 GSS_C_DELEG_FLAG 2788 True - Credentials were delegated to 2789 the remote peer 2790 False - No credentials were delegated 2792 GSS_C_MUTUAL_FLAG 2793 True - The remote peer has authenticated 2794 itself. 2795 False - Remote peer has not authenticated 2796 itself. 2798 GSS_C_REPLAY_FLAG 2799 True - replay of protected messages 2800 will be detected 2801 False - replayed messages will not be 2802 detected 2804 GSS_C_SEQUENCE_FLAG 2805 True - out-of-sequence protected 2806 messages will be detected 2807 False - out-of-sequence messages will 2808 not be detected 2810 GSS_C_CONF_FLAG 2811 True - Confidentiality service may be 2812 invoked by calling gss_wrap routine 2813 False - No confidentiality service (via 2814 gss_wrap) available. gss_wrap will 2815 provide message encapsulation, 2816 data-origin authentication and 2817 integrity services only. 2819 GSS_C_INTEG_FLAG 2820 True - Integrity service may be invoked by 2821 calling either gss_get_mic or gss_wrap 2822 routines. 2823 False - Per-message integrity service 2824 unavailable. 2826 GSS_C_ANON_FLAG 2827 True - The initiator's identity has not been 2828 revealed, and will not be revealed if 2829 any emitted token is passed to the 2830 acceptor. 2831 False - The initiator's identity has been or 2832 will be authenticated normally. 2834 GSS_C_PROT_READY_FLAG 2835 True - Protection services (as specified 2836 by the states of the GSS_C_CONF_FLAG 2837 and GSS_C_INTEG_FLAG) are available for 2838 use if the accompanying major status 2839 return value is either GSS_S_COMPLETE or 2840 GSS_S_CONTINUE_NEEDED. 2841 False - Protection services (as specified 2842 by the states of the GSS_C_CONF_FLAG 2843 and GSS_C_INTEG_FLAG) are available 2844 only if the accompanying major status 2845 return value is GSS_S_COMPLETE. 2847 GSS_C_TRANS_FLAG 2848 True - The resultant security context may 2849 be transferred to other processes via 2850 a call to gss_export_sec_context(). 2851 False - The security context is not 2852 transferrable. 2854 All other bits should be set to zero. 2856 time_rec Integer, modify, optional 2857 number of seconds for which the context 2858 will remain valid. If the implementation does 2859 not support context expiration, the value 2860 GSS_C_INDEFINITE will be returned. Specify 2861 NULL if not required. 2863 Function value: GSS status code 2865 GSS_S_COMPLETE Successful completion 2867 GSS_S_CONTINUE_NEEDED Indicates that a token from the peer 2868 application is required to complete the 2869 context, and that gss_init_sec_context 2870 must be called again with that token. 2872 GSS_S_DEFECTIVE_TOKEN Indicates that consistency checks performed 2873 on the input_token failed 2875 GSS_S_DEFECTIVE_CREDENTIAL Indicates that consistency checks 2876 performed on the credential failed. 2878 GSS_S_NO_CRED The supplied credentials were not valid for 2879 context initiation, or the credential handle 2880 did not reference any credentials. 2882 GSS_S_CREDENTIALS_EXPIRED The referenced credentials have expired 2884 GSS_S_BAD_BINDINGS The input_token contains different channel 2885 bindings to those specified via the 2886 input_chan_bindings parameter 2888 GSS_S_BAD_SIG The input_token contains an invalid MIC, or a MIC 2889 that could not be verified 2891 GSS_S_OLD_TOKEN The input_token was too old. This is a fatal 2892 error during context establishment 2894 GSS_S_DUPLICATE_TOKEN The input_token is valid, but is a duplicate 2895 of a token already processed. This is a 2896 fatal error during context establishment. 2898 GSS_S_NO_CONTEXT Indicates that the supplied context handle did 2899 not refer to a valid context 2901 GSS_S_BAD_NAMETYPE The provided target_name parameter contained an 2902 invalid or unsupported type of name 2904 GSS_S_BAD_NAME The provided target_name parameter was ill-formed. 2906 GSS_S_BAD_MECH The specified mechanism is not supported by the 2907 provided credential, or is unrecognized by the 2908 implementation. 2910 7.20.gss_inquire_context 2912 OM_uint32 gss_inquire_context ( 2913 OM_uint32 *minor_status, 2914 const gss_ctx_id_t context_handle, 2915 gss_name_t *src_name, 2916 gss_name_t *targ_name, 2917 OM_uint32 *lifetime_rec, 2918 gss_OID *mech_type, 2919 OM_uint32 *ctx_flags, 2920 int *locally_initiated, 2921 int *open ) 2923 Purpose: 2925 Obtains information about a security context. The caller must 2926 already have obtained a handle that refers to the context, although 2927 the context need not be fully established. 2929 Parameters: 2931 minor_status Integer, modify 2932 Mechanism specific status code 2934 context_handle gss_ctx_id_t, read 2935 A handle that refers to the security context. 2937 src_name gss_name_t, modify, optional 2938 The name of the context initiator. 2939 If the context was established using anonymous 2940 authentication, and if the application invoking 2941 gss_inquire_context is the context acceptor, 2942 an anonymous name will be returned. Storage 2943 associated with this name must be freed by the 2944 application after use with a call to 2945 gss_release_name(). Specify NULL if not 2946 required. 2948 targ_name gss_name_t, modify, optional 2949 The name of the context acceptor. 2950 Storage associated with this name must be 2951 freed by the application after use with a call 2952 to gss_release_name(). If the context acceptor 2953 did not authenticate itself, and if the initiator 2954 did not specify a target name in its call to 2955 gss_init_sec_contect(), the value GSS_C_NO_NAME 2956 will be returned. Specify NULL if not required. 2958 lifetime_rec Integer, modify, optional 2959 The number of seconds for which the context 2960 will remain valid. If the context has 2961 expired, this parameter will be set to zero. 2962 If the implementation does not support 2963 context expiration, the value 2964 GSS_C_INDEFINITE will be returned. Specify 2965 NULL if not required. 2967 mech_type gss_OID, modify, optional 2968 The security mechanism providing the 2969 context. The returned OID will be a 2970 pointer to static storage that should 2971 be treated as read-only by the application; 2972 in particular the application should not 2973 attempt to free it. Specify NULL if not 2974 required. 2976 ctx_flags bit-mask, modify, optional 2977 Contains various independent flags, each of 2978 which indicates that the context supports 2979 (or is expected to support, if ctx_open is 2980 false) a specific service option. If not 2981 needed, specify NULL. Symbolic names are 2982 provided for each flag, and the symbolic names 2983 corresponding to the required flags 2984 should be logically-ANDed with the ret_flags 2985 value to test whether a given option is 2986 supported by the context. The flags are: 2988 GSS_C_DELEG_FLAG 2989 True - Credentials were delegated from 2990 the initiator to the acceptor. 2991 False - No credentials were delegated 2993 GSS_C_MUTUAL_FLAG 2994 True - The acceptor was authenticated 2995 to the initiator 2996 False - The acceptor did not authenticate 2997 itself. 2999 GSS_C_REPLAY_FLAG 3000 True - replay of protected messages 3001 will be detected 3002 False - replayed messages will not be 3003 detected 3005 GSS_C_SEQUENCE_FLAG 3006 True - out-of-sequence protected 3007 messages will be detected 3008 False - out-of-sequence messages will not 3009 be detected 3011 GSS_C_CONF_FLAG 3012 True - Confidentiality service may be invoked 3013 by calling gss_wrap routine 3014 False - No confidentiality service (via 3015 gss_wrap) available. gss_wrap will 3016 provide message encapsulation, 3017 data-origin authentication and 3018 integrity services only. 3020 GSS_C_INTEG_FLAG 3021 True - Integrity service may be invoked by 3022 calling either gss_get_mic or gss_wrap 3023 routines. 3024 False - Per-message integrity service 3025 unavailable. 3027 GSS_C_ANON_FLAG 3028 True - The initiator's identity will not 3029 be revealed to the acceptor. 3030 The src_name parameter (if 3031 requested) contains an anonymous 3032 internal name. 3033 False - The initiator has been 3034 authenticated normally. 3036 GSS_C_PROT_READY_FLAG 3037 True - Protection services (as specified 3038 by the states of the GSS_C_CONF_FLAG 3039 and GSS_C_INTEG_FLAG) are available 3040 for use. 3041 False - Protection services (as specified 3042 by the states of the GSS_C_CONF_FLAG 3043 and GSS_C_INTEG_FLAG) are available 3044 only if the context is fully 3045 established (i.e. if the open parameter 3046 is non-zero). 3048 GSS_C_TRANS_FLAG 3049 True - The resultant security context may 3050 be transferred to other processes via 3051 a call to gss_export_sec_context(). 3052 False - The security context is not 3053 transferrable. 3055 locally_initiated Boolean, modify 3056 Non-zero if the invoking application is the 3057 context initiator. 3058 Specify NULL if not required. 3060 open Boolean, modify 3061 Non-zero if the context is fully established; 3062 Zero if a context-establishment token 3063 is expected from the peer application. 3064 Specify NULL if not required. 3066 Function value: GSS status code 3068 GSS_S_COMPLETE Successful completion 3070 GSS_S_NO_CONTEXT The referenced context could not be accessed. 3072 7.21.gss_inquire_cred 3074 OM_uint32 gss_inquire_cred ( 3075 OM_uint32 *minor_status, 3076 const gss_cred_id_t cred_handle, 3077 gss_name_t *name, 3078 OM_uint32 *lifetime, 3079 gss_cred_usage_t *cred_usage, 3080 gss_OID_set *mechanisms ) 3082 Purpose: 3084 Obtains information about a credential. 3086 Parameters: 3088 minor_status Integer, modify 3089 Mechanism specific status code 3091 cred_handle gss_cred_id_t, read 3092 A handle that refers to the target credential. 3093 Specify GSS_C_NO_CREDENTIAL to inquire about 3094 the default initiator principal. 3096 name gss_name_t, modify, optional 3097 The name whose identity the credential asserts. 3098 Storage associated with this name should be freed 3099 by the application after use with a call to 3100 gss_release_name(). Specify NULL if not required. 3102 lifetime Integer, modify, optional 3103 The number of seconds for which the credential 3104 will remain valid. If the credential has 3105 expired, this parameter will be set to zero. 3106 If the implementation does not support 3107 credential expiration, the value 3108 GSS_C_INDEFINITE will be returned. Specify 3109 NULL if not required. 3111 cred_usage gss_cred_usage_t, modify, optional 3112 How the credential may be used. One of the 3113 following: 3114 GSS_C_INITIATE 3115 GSS_C_ACCEPT 3116 GSS_C_BOTH 3117 Specify NULL if not required. 3119 mechanisms gss_OID_set, modify, optional 3120 Set of mechanisms supported by the credential. 3121 Storage associated with this OID set must be 3122 freed by the application after use with a call 3123 to gss_release_oid_set(). Specify NULL if not 3124 required. 3126 Function value: GSS status code 3127 GSS_S_COMPLETE Successful completion 3129 GSS_S_NO_CRED The referenced credentials could not be accessed. 3131 GSS_S_DEFECTIVE_CREDENTIAL The referenced credentials were invalid. 3133 GSS_S_CREDENTIALS_EXPIRED The referenced credentials have expired. 3134 If the lifetime parameter was not passed as NULL, 3135 it will be set to 0. 3137 7.22.gss_inquire_cred_by_mech 3139 OM_uint32 gss_inquire_cred_by_mech ( 3140 OM_uint32 *minor_status, 3141 const gss_cred_id_t cred_handle, 3142 const gss_OID mech_type, 3143 gss_name_t *name, 3144 OM_uint32 *initiator_lifetime, 3145 OM_uint32 *acceptor_lifetime, 3146 gss_cred_usage_t *cred_usage ) 3148 Purpose: 3150 Obtains per-mechanism information about a credential. 3152 Parameters: 3154 minor_status Integer, modify 3155 Mechanism specific status code 3157 cred_handle gss_cred_id_t, read 3158 A handle that refers to the target credential. 3159 Specify GSS_C_NO_CREDENTIAL to inquire about 3160 the default initiator principal. 3162 mech_type gss_OID, read 3163 The mechanism for which information should be 3164 returned. 3166 name gss_name_t, modify, optional 3167 The name whose identity the credential asserts. 3168 Storage associated with this name must be 3169 freed by the application after use with a call 3170 to gss_release_name(). Specify NULL if not 3171 required. 3173 initiator_lifetime Integer, modify, optional 3174 The number of seconds for which the credential 3175 will remain capable of initiating security contexts 3176 under the specified mechanism. If the credential 3177 can no longer be used to initiate contexts, or if 3178 the credential usage for this mechanism is 3179 GSS_C_ACCEPT, this parameter will be set to zero. 3180 If the implementation does not support expiration 3181 of initiator credentials, the value 3182 GSS_C_INDEFINITE will be returned. Specify NULL 3183 if not required. 3185 acceptor_lifetime Integer, modify, optional 3186 The number of seconds for which the credential 3187 will remain capable of accepting security contexts 3188 under the specified mechanism. If the credential 3189 can no longer be used to accept contexts, or if 3190 the credential usage for this mechanism is 3191 GSS_C_INITIATE, this parameter will be set to zero. 3193 If the implementation does not support expiration 3194 of acceptor credentials, the value GSS_C_INDEFINITE 3195 will be returned. Specify NULL if not required. 3197 cred_usage gss_cred_usage_t, modify, optional 3198 How the credential may be used with the specified 3199 mechanism. One of the following: 3200 GSS_C_INITIATE 3201 GSS_C_ACCEPT 3202 GSS_C_BOTH 3203 Specify NULL if not required. 3205 Function value: GSS status code 3207 GSS_S_COMPLETE Successful completion 3209 GSS_S_NO_CRED The referenced credentials could not be accessed. 3211 GSS_S_DEFECTIVE_CREDENTIAL The referenced credentials were invalid. 3213 GSS_S_CREDENTIALS_EXPIRED The referenced credentials have expired. 3214 If the lifetime parameter was not passed as NULL, 3215 it will be set to 0. 3217 7.23.gss_inquire_mechs_for_name 3219 OM_uint32 gss_inquire_mechs_for_name ( 3220 OM_uint32 *minor_status, 3221 const gss_name_t input_name, 3222 gss_OID_set *mech_types ) 3224 Purpose: 3226 Returns the set of mechanisms supported by the GSS-API implementation 3227 that may be able to process the specified name. 3229 Each mechanism returned will recognize at least one element within 3230 the name. It is permissible for this routine to be implemented 3231 within a mechanism-independent GSS-API layer, using the type 3232 information contained within the presented name, and based on 3233 registration information provided by individual mechanism 3234 implementations. This means that the returned mech_types set may 3235 indicate that a particular mechanism will understand the name when in 3236 fact it would refuse to accept the name as input to 3237 gss_canonicalize_name, gss_init_sec_context, gss_acquire_cred or 3238 gss_add_cred (due to some property of the specific name, as opposed 3239 to the name type). Thus this routine should be used only as a 3240 pre-filter for a call to a subsequent mechanism-specific routine. 3242 Parameters: 3244 minor_status Integer, modify 3245 Implementation specific status code. 3247 input_name gss_name_t, read 3248 The name to which the inquiry relates. 3250 mech_types gss_OID_set, modify 3251 Set of mechanisms that may support the 3252 specified name. The returned OID set 3253 must be freed by the caller after use 3254 with a call to gss_release_oid_set(). 3256 Function value: GSS status code 3258 GSS_S_COMPLETE Successful completion 3260 GSS_S_BAD_NAME The input_name parameter was ill-formed. 3262 GSS_S_BAD_NAMETYPE The input_name parameter contained an invalid or 3263 unsupported type of name 3264 7.24.gss_inquire_names_for_mech 3266 OM_uint32 gss_inquire_names_for_mech ( 3267 OM_uint32 *minor_status, 3268 const gss_OID mechanism, 3269 gss_OID_set *name_types) 3271 Purpose: 3273 Returns the set of nametypes supported by the specified mechanism. 3275 Parameters: 3277 minor_status Integer, modify 3278 Implementation specific status code. 3280 mechanism gss_OID, read 3281 The mechanism to be interrogated. 3283 name_types gss_OID_set, modify 3284 Set of name-types supported by the specified 3285 mechanism. The returned OID set must be 3286 freed by the application after use with a 3287 call to gss_release_oid_set(). 3289 Function value: GSS status code 3291 GSS_S_COMPLETE Successful completion 3292 7.25.gss_process_context_token 3294 OM_uint32 gss_process_context_token ( 3295 OM_uint32 *minor_status, 3296 const gss_ctx_id_t context_handle, 3297 const gss_buffer_t token_buffer) 3299 Purpose: 3301 Provides a way to pass an asynchronous token to the security service. 3302 Most context-level tokens are emitted and processed synchronously by 3303 gss_init_sec_context and gss_accept_sec_context, and the application 3304 is informed as to whether further tokens are expected by the 3305 GSS_C_CONTINUE_NEEDED major status bit. Occasionally, a mechanism 3306 may need to emit a context-level token at a point when the peer 3307 entity is not expecting a token. For example, the initiator's final 3308 call to gss_init_sec_context may emit a token and return a status of 3309 GSS_S_COMPLETE, but the acceptor�s call to gss_accept_sec_context may 3310 fail. The acceptor's mechanism may wish to send a token containing 3311 an error indication to the initiator, but the initiator is not 3312 expecting a token at this point, believing that the context is fully 3313 established. Gss_process_context_token provides a way to pass such a 3314 token to the mechanism at any time. 3316 Parameters: 3318 minor_status Integer, modify 3319 Implementation specific status code. 3321 context_handle gss_ctx_id_t, read 3322 context handle of context on which token is to 3323 be processed 3325 token_buffer buffer, opaque, read 3326 token to process 3328 Function value: GSS status code 3330 GSS_S_COMPLETE Successful completion 3332 GSS_S_DEFECTIVE_TOKEN Indicates that consistency checks performed 3333 on the token failed 3335 GSS_S_NO_CONTEXT The context_handle did not refer to a valid context 3336 7.26.gss_release_buffer 3338 OM_uint32 gss_release_buffer ( 3339 OM_uint32 *minor_status, 3340 gss_buffer_t buffer) 3342 Purpose: 3344 Free storage associated with a buffer. The storage must have been 3345 allocated by a GSS-API routine. In addition to freeing the 3346 associated storage, the routine will zero the length field in the 3347 descriptor to which the buffer parameter refers, and implementations 3348 are encouraged to additionally set the pointer field in the 3349 descriptor to NULL. Any buffer object returned by a GSS-API routine 3350 may be passed to gss_release_buffer (even if there is no storage 3351 associated with the buffer). 3353 Parameters: 3355 minor_status Integer, modify 3356 Mechanism specific status code 3358 buffer buffer, modify 3359 The storage associated with the buffer will be 3360 deleted. The gss_buffer_desc object will not 3361 be freed, but its length field will be zeroed. 3363 Function value: GSS status code 3365 GSS_S_COMPLETE Successful completion 3366 7.27.gss_release_cred 3368 OM_uint32 gss_release_cred ( 3369 OM_uint32 *minor_status, 3370 gss_cred_id_t *cred_handle) 3372 Purpose: 3374 Informs GSS-API that the specified credential handle is no longer 3375 required by the application, and frees associated resources. 3376 Implementations are encouraged to set the cred_handle to 3377 GSS_C_NO_CREDENTIAL on successful completion of this call. 3379 Parameters: 3381 cred_handle gss_cred_id_t, modify, optional 3382 Opaque handle identifying credential 3383 to be released. If GSS_C_NO_CREDENTIAL 3384 is supplied, the routine will complete 3385 successfully, but will do nothing. 3387 minor_status Integer, modify 3388 Mechanism specific status code. 3390 Function value: GSS status code 3392 GSS_S_COMPLETE Successful completion 3394 GSS_S_NO_CRED Credentials could not be accessed. 3396 7.28.gss_release_name 3398 OM_uint32 gss_release_name ( 3399 OM_uint32 *minor_status, 3400 gss_name_t *name) 3402 Purpose: 3404 Free GSSAPI-allocated storage associated with an internal-form name. 3405 Implementations are encouraged to set the name to GSS_C_NO_NAME on 3406 successful completion of this call. 3408 Parameters: 3410 minor_status Integer, modify 3411 Mechanism specific status code 3413 name gss_name_t, modify 3414 The name to be deleted 3416 Function value: GSS status code 3418 GSS_S_COMPLETE Successful completion 3420 GSS_S_BAD_NAME The name parameter did not contain a valid name 3421 7.29.gss_release_oid_set 3423 OM_uint32 gss_release_oid_set ( 3424 OM_uint32 *minor_status, 3425 gss_OID_set *set) 3427 Purpose: 3429 Free storage associated with a GSSAPI-generated gss_OID_set object. 3430 The set parameter must refer to an OID-set that was returned from a 3431 GSS-API routine. gss_release_oid_set() will free the storage 3432 associated with each individual member OID, the OID set's elements 3433 array, and the gss_OID_set_desc. 3435 Implementations are encouraged to set the gss_OID_set parameter to 3436 GSS_C_NO_OID_SET on successful completion of this routine. 3438 Parameters: 3440 minor_status Integer, modify 3441 Mechanism specific status code 3443 set Set of Object IDs, modify 3444 The storage associated with the gss_OID_set 3445 will be deleted. 3447 Function value: GSS status code 3449 GSS_S_COMPLETE Successful completion 3450 7.30.gss_test_oid_set_member 3452 OM_uint32 gss_test_oid_set_member ( 3453 OM_uint32 *minor_status, 3454 const gss_OID member, 3455 const gss_OID_set set, 3456 int *present) 3458 Purpose: 3460 Interrogate an Object Identifier set to determine whether a specified 3461 Object Identifier is a member. This routine is intended to be used 3462 with OID sets returned by gss_indicate_mechs(), gss_acquire_cred(), 3463 and gss_inquire_cred(), but will also work with user-generated sets. 3465 Parameters: 3467 minor_status Integer, modify 3468 Mechanism specific status code 3470 member Object ID, read 3471 The object identifier whose presence 3472 is to be tested. 3474 set Set of Object ID, read 3475 The Object Identifier set. 3477 present Boolean, modify 3478 non-zero if the specified OID is a member 3479 of the set, zero if not. 3481 Function value: GSS status code 3483 GSS_S_COMPLETE Successful completion 3484 7.31.gss_unwrap 3486 OM_uint32 gss_unwrap ( 3487 OM_uint32 *minor_status, 3488 const gss_ctx_id_t context_handle, 3489 const gss_buffer_t input_message_buffer, 3490 gss_buffer_t output_message_buffer, 3491 int *conf_state, 3492 gss_qop_t *qop_state) 3494 Purpose: 3496 Converts a message previously protected by gss_wrap back to a usable 3497 form, verifying the embedded MIC. The conf_state parameter indicates 3498 whether the message was encrypted; the qop_state parameter indicates 3499 the strength of protection that was used to provide the 3500 confidentiality and integrity services. 3502 Since some application-level protocols may wish to use tokens emitted 3503 by gss_wrap() to provide "secure framing", implementations must 3504 support the wrapping and unwrapping of zero-length messages. 3506 Parameters: 3508 minor_status Integer, modify 3509 Mechanism specific status code. 3511 context_handle gss_ctx_id_t, read 3512 Identifies the context on which the message 3513 arrived 3515 input_message_buffer buffer, opaque, read 3516 protected message 3518 output_message_buffer buffer, opaque, modify 3519 Buffer to receive unwrapped message. 3520 Storage associated with this buffer must 3521 be freed by the application after use use 3522 with a call to gss_release_buffer(). 3524 conf_state boolean, modify, optional 3525 Non-zero - Confidentiality and integrity 3526 protection were used 3527 Zero - Integrity service only was used 3528 Specify NULL if not required 3530 qop_state gss_qop_t, modify, optional 3531 Quality of protection provided. 3532 Specify NULL if not required 3534 Function value: GSS status code 3536 GSS_S_COMPLETE Successful completion 3538 GSS_S_DEFECTIVE_TOKEN The token failed consistency checks 3539 GSS_S_BAD_SIG The MIC was incorrect 3541 GSS_S_DUPLICATE_TOKEN The token was valid, and contained a correct 3542 MIC for the message, but it had already been 3543 processed 3545 GSS_S_OLD_TOKEN The token was valid, and contained a correct MIC 3546 for the message, but it is too old to check for 3547 duplication. 3549 GSS_S_UNSEQ_TOKEN The token was valid, and contained a correct MIC 3550 for the message, but has been verified out of 3551 sequence; a later token has already been 3552 received. 3554 GSS_S_GAP_TOKEN The token was valid, and contained a correct MIC 3555 for the message, but has been verified out of 3556 sequence; an earlier expected token has not yet 3557 been received. 3559 GSS_S_CONTEXT_EXPIRED The context has already expired 3561 GSS_S_NO_CONTEXT The context_handle parameter did not identify 3562 a valid context 3563 7.32.gss_verify_mic 3565 OM_uint32 gss_verify_mic ( 3566 OM_uint32 *minor_status, 3567 const gss_ctx_id_t context_handle, 3568 const gss_buffer_t message_buffer, 3569 const gss_buffer_t token_buffer, 3570 gss_qop_t *qop_state) 3572 Purpose: 3574 Verifies that a cryptographic MIC, contained in the token parameter, 3575 fits the supplied message. The qop_state parameter allows a message 3576 recipient to determine the strength of protection that was applied to 3577 the message. 3579 Since some application-level protocols may wish to use tokens emitted 3580 by gss_wrap() to provide "secure framing", implementations must 3581 support the calculation and verification of MICs over zero-length 3582 messages. 3584 Parameters: 3586 minor_status Integer, modify 3587 Mechanism specific status code. 3589 context_handle gss_ctx_id_t, read 3590 Identifies the context on which the message 3591 arrived 3593 message_buffer buffer, opaque, read 3594 Message to be verified 3596 token_buffer buffer, opaque, read 3597 Token associated with message 3599 qop_state gss_qop_t, modify, optional 3600 quality of protection gained from MIC 3601 Specify NULL if not required 3603 Function value: GSS status code 3605 GSS_S_COMPLETE Successful completion 3607 GSS_S_DEFECTIVE_TOKEN The token failed consistency checks 3609 GSS_S_BAD_SIG The MIC was incorrect 3611 GSS_S_DUPLICATE_TOKEN The token was valid, and contained a correct 3612 MIC for the message, but it had already been 3613 processed 3615 GSS_S_OLD_TOKEN The token was valid, and contained a correct MIC 3616 for the message, but it is too old to check for 3617 duplication. 3619 GSS_S_UNSEQ_TOKEN The token was valid, and contained a correct MIC 3620 for the message, but has been verified out of 3621 sequence; a later token has already been received. 3623 GSS_S_GAP_TOKEN The token was valid, and contained a correct MIC 3624 for the message, but has been verified out of 3625 sequence; an earlier expected token has not yet 3626 been received. 3628 GSS_S_CONTEXT_EXPIRED The context has already expired 3630 GSS_S_NO_CONTEXT The context_handle parameter did not identify a 3631 valid context 3632 7.33.gss_wrap 3634 OM_uint32 gss_wrap ( 3635 OM_uint32 *minor_status, 3636 const gss_ctx_id_t context_handle, 3637 int conf_req_flag, 3638 gss_qop_t qop_req 3639 const gss_buffer_t input_message_buffer, 3640 int *conf_state, 3641 gss_buffer_t output_message_buffer ) 3643 Purpose: 3645 Attaches a cryptographic MIC and optionally encrypts the specified 3646 input_message. The output_message contains both the MIC and the 3647 message. The qop_req parameter allows a choice between several 3648 cryptographic algorithms, if supported by the chosen mechanism. 3650 Since some application-level protocols may wish to use tokens emitted 3651 by gss_wrap() to provide "secure framing", implementations must 3652 support the wrapping of zero-length messages. 3654 Parameters: 3656 minor_status Integer, modify 3657 Mechanism specific status code. 3659 context_handle gss_ctx_id_t, read 3660 Identifies the context on which the message 3661 will be sent 3663 conf_req_flag boolean, read 3664 Non-zero - Both confidentiality and integrity 3665 services are requested 3666 Zero - Only integrity service is requested 3668 qop_req gss_qop_t, read, optional 3669 Specifies required quality of protection. A 3670 mechanism-specific default may be requested by 3671 setting qop_req to GSS_C_QOP_DEFAULT. If an 3672 unsupported protection strength is requested, 3673 gss_wrap will return a major_status of 3674 GSS_S_BAD_QOP. 3676 input_message_buffer buffer, opaque, read 3677 Message to be protected 3679 conf_state boolean, modify, optional 3680 Non-zero - Confidentiality, data origin 3681 authentication and integrity 3682 services have been applied 3683 Zero - Integrity and data origin services only 3684 has been applied. 3685 Specify NULL if not required 3686 output_message_buffer buffer, opaque, modify 3687 Buffer to receive protected message. 3688 Storage associated with this message must 3689 be freed by the application after use with 3690 a call to gss_release_buffer(). 3692 Function value: GSS status code 3694 GSS_S_COMPLETE Successful completion 3696 GSS_S_CONTEXT_EXPIRED The context has already expired 3698 GSS_S_NO_CONTEXT The context_handle parameter did not identify a 3699 valid context 3701 GSS_S_BAD_QOP The specified QOP is not supported by the 3702 mechanism. 3704 7.34.gss_wrap_size_limit 3706 OM_uint32 gss_wrap_size_limit ( 3707 OM_uint32 *minor_status, 3708 const gss_ctx_id_t context_handle, 3709 int conf_req_flag, 3710 gss_qop_t qop_req, 3711 OM_uint32 req_output_size, 3712 OM_uint32 *max_input_size) 3714 Purpose: 3716 Allows an application to determine the maximum message size that, if 3717 presented to gss_wrap with the same conf_req_flag and qop_req 3718 parameters, will result in an output token containing no more than 3719 req_output_size bytes. 3721 This call is intended for use by applications that communicate over 3722 protocols that impose a maximum message size. It enables the 3723 application to fragment messages prior to applying protection. 3725 GSS-API implementations are recommended but not required to detect 3726 invalid QOP values when gss_wrap_size_limit() is called. This routine 3727 guarantees only a maximum message size, not the availability of 3728 specific QOP values for message protection. 3730 Successful completion of this call does not guarantee that gss_wrap 3731 will be able to protect a message of length max_input_size bytes, 3732 since this ability may depend on the availability of system resources 3733 at the time that gss_wrap is called. However, if the implementation 3734 itself imposes an upper limit on the length of messages that may be 3735 processed by gss_wrap, the implementation should not return a value 3736 via max_input_bytes that is greater than this length. 3738 Parameters: 3740 minor_status Integer, modify 3741 Mechanism specific status code 3743 context_handle gss_ctx_id_t, read 3744 A handle that refers to the security over 3745 which the messages will be sent. 3747 conf_req_flag Boolean, read 3748 Indicates whether gss_wrap will be asked 3749 to apply confidentiality protection in 3750 addition to integrity protection. See 3751 the routine description for gss_wrap 3752 for more details. 3754 qop_req gss_qop_t, read 3755 Indicates the level of protection that 3756 gss_wrap will be asked to provide. See 3757 the routine description for gss_wrap for 3758 more details. 3760 req_output_size Integer, read 3761 The desired maximum size for tokens emitted 3762 by gss_wrap. 3764 max_input_size Integer, modify 3765 The maximum input message size that may 3766 be presented to gss_wrap in order to 3767 guarantee that the emitted token shall 3768 be no larger than req_output_size bytes. 3770 Function value: GSS status code 3772 GSS_S_COMPLETE Successful completion 3774 GSS_S_NO_CONTEXT The referenced context could not be accessed. 3776 GSS_S_CONTEXT_EXPIRED The context has expired. 3778 GSS_S_BAD_QOP The specified QOP is not supported by the 3779 mechanism. 3781 8. SECURITY CONSIDERATIONS 3783 This document specifies a service interface for security facilities 3784 and services; as such, security considerations appear throughout the 3785 specification. Nonetheless, it is appropriate to summarize certain 3786 specific points relevant to GSS-API implementors and calling 3787 applications. Usage of the GSS-API interface does not in itself 3788 provide security services or assurance; instead, these attributes are 3789 dependent on the underlying mechanism(s) which support a GSS-API 3790 implementation. Callers must be attentive to the requests made to 3791 GSS-API calls and to the status indicators returned by GSS-API, as 3792 these specify the security service characteristics which GSS-API will 3793 provide. When the interprocess context transfer facility is used, 3794 appropriate local controls should be applied to constrain access to 3795 interprocess tokens and to the sensitive data which they contain. 3797 APPENDIX A. GSS-API C header file gssapi.h 3799 C-language GSS-API implementations should include a copy of the 3800 following header-file. 3802 #ifndef GSSAPI_H_ 3803 #define GSSAPI_H_ 3805 /* 3806 * First, include stddef.h to get size_t defined. 3807 */ 3808 #include 3810 /* 3811 * If the platform supports the xom.h header file, it should be 3812 * included here. 3813 */ 3814 #include 3816 /* 3817 * Now define the three implementation-dependent types. 3818 */ 3819 typedef gss_ctx_id_t; 3820 typedef gss_cred_id_t; 3821 typedef gss_name_t; 3823 /* 3824 * The following type must be defined as the smallest natural 3825 * unsigned integer supported by the platform that has at least 3826 * 32 bits of precision. 3827 */ 3828 typedef gss_uint32; 3829 #ifdef OM_STRING 3830 /* 3831 * We have included the xom.h header file. Verify that OM_uint32 3832 * is defined correctly. 3833 */ 3835 #if sizeof(gss_uint32) != sizeof(OM_uint32) 3836 #error Incompatible definition of OM_uint32 from xom.h 3837 #endif 3839 typedef OM_object_identifier gss_OID_desc, *gss_OID; 3841 #else 3843 /* 3844 * We can't use X/Open definitions, so roll our own. 3845 */ 3847 typedef gss_uint32 OM_uint32; 3849 typedef struct gss_OID_desc_struct { 3850 OM_uint32 length; 3851 void *elements; 3852 } gss_OID_desc, *gss_OID; 3854 #endif 3856 typedef struct gss_OID_set_desc_struct { 3857 size_t count; 3858 gss_OID elements; 3859 } gss_OID_set_desc, *gss_OID_set; 3861 typedef struct gss_buffer_desc_struct { 3862 size_t length; 3863 void *value; 3864 } gss_buffer_desc, *gss_buffer_t; 3866 typedef struct gss_channel_bindings_struct { 3867 OM_uint32 initiator_addrtype; 3868 gss_buffer_desc initiator_address; 3869 OM_uint32 acceptor_addrtype; 3870 gss_buffer_desc acceptor_address; 3871 gss_buffer_desc application_data; 3872 } *gss_channel_bindings_t; 3874 /* 3875 * For now, define a QOP-type as an OM_uint32 3876 */ 3877 typedef OM_uint32 gss_qop_t; 3879 typedef int gss_cred_usage_t; 3881 /* 3882 * Flag bits for context-level services. 3883 */ 3884 #define GSS_C_DELEG_FLAG 1 3885 #define GSS_C_MUTUAL_FLAG 2 3886 #define GSS_C_REPLAY_FLAG 4 3887 #define GSS_C_SEQUENCE_FLAG 8 3888 #define GSS_C_CONF_FLAG 16 3889 #define GSS_C_INTEG_FLAG 32 3890 #define GSS_C_ANON_FLAG 64 3891 #define GSS_C_PROT_READY_FLAG 128 3892 #define GSS_C_TRANS_FLAG 256 3894 /* 3895 * Credential usage options 3896 */ 3897 #define GSS_C_BOTH 0 3898 #define GSS_C_INITIATE 1 3899 #define GSS_C_ACCEPT 2 3901 /* 3902 * Status code types for gss_display_status 3903 */ 3904 #define GSS_C_GSS_CODE 1 3905 #define GSS_C_MECH_CODE 2 3907 /* 3908 * The constant definitions for channel-bindings address families 3909 */ 3910 #define GSS_C_AF_UNSPEC 0 3911 #define GSS_C_AF_LOCAL 1 3912 #define GSS_C_AF_INET 2 3913 #define GSS_C_AF_IMPLINK 3 3914 #define GSS_C_AF_PUP 4 3915 #define GSS_C_AF_CHAOS 5 3916 #define GSS_C_AF_NS 6 3917 #define GSS_C_AF_NBS 7 3918 #define GSS_C_AF_ECMA 8 3919 #define GSS_C_AF_DATAKIT 9 3920 #define GSS_C_AF_CCITT 10 3921 #define GSS_C_AF_SNA 11 3922 #define GSS_C_AF_DECnet 12 3923 #define GSS_C_AF_DLI 13 3924 #define GSS_C_AF_LAT 14 3925 #define GSS_C_AF_HYLINK 15 3926 #define GSS_C_AF_APPLETALK 16 3927 #define GSS_C_AF_BSC 17 3928 #define GSS_C_AF_DSS 18 3929 #define GSS_C_AF_OSI 19 3930 #define GSS_C_AF_X25 21 3932 #define GSS_C_AF_NULLADDR 255 3934 /* 3935 * Various Null values 3936 */ 3937 #define GSS_C_NO_NAME ((gss_name_t) 0) 3938 #define GSS_C_NO_BUFFER ((gss_buffer_t) 0) 3939 #define GSS_C_NO_OID ((gss_OID) 0) 3940 #define GSS_C_NO_OID_SET ((gss_OID_set) 0) 3941 #define GSS_C_NO_CONTEXT ((gss_ctx_id_t) 0) 3942 #define GSS_C_NO_CREDENTIAL ((gss_cred_id_t) 0) 3943 #define GSS_C_NO_CHANNEL_BINDINGS ((gss_channel_bindings_t) 0) 3944 #define GSS_C_EMPTY_BUFFER {0, NULL} 3946 /* 3947 * Some alternate names for a couple of the above 3948 * values. These are defined for V1 compatibility. 3949 */ 3950 #define GSS_C_NULL_OID GSS_C_NO_OID 3951 #define GSS_C_NULL_OID_SET GSS_C_NO_OID_SET 3953 /* 3954 * Define the default Quality of Protection for per-message 3955 * services. Note that an implementation that offers multiple 3956 * levels of QOP may define GSS_C_QOP_DEFAULT to be either zero 3957 * (as done here) to mean "default protection", or to a specific 3958 * explicit QOP value. However, a value of 0 should always be 3959 * interpreted by a GSS-API implementation as a request for the 3960 * default protection level. 3961 */ 3962 #define GSS_C_QOP_DEFAULT 0 3964 /* 3965 * Expiration time of 2^32-1 seconds means infinite lifetime for a 3966 * credential or security context 3967 */ 3968 #define GSS_C_INDEFINITE 0xfffffffful 3970 /* 3971 * The implementation must reserve static storage for a 3972 * gss_OID_desc object containing the value 3973 * {10, (void *)"\x2a\x86\x48\x86\xf7\x12" 3974 * "\x01\x02\x01\x01"}, 3975 * corresponding to an object-identifier value of 3976 * {iso(1) member-body(2) United States(840) mit(113554) 3977 * infosys(1) gssapi(2) generic(1) user_name(1)}. The constant 3978 * GSS_C_NT_USER_NAME should be initialized to point 3979 * to that gss_OID_desc. 3980 */ 3981 extern gss_OID GSS_C_NT_USER_NAME; 3983 /* 3984 * The implementation must reserve static storage for a 3985 * gss_OID_desc object containing the value 3986 * {10, (void *)"\x2a\x86\x48\x86\xf7\x12" 3987 * "\x01\x02\x01\x02"}, 3988 * corresponding to an object-identifier value of 3989 * {iso(1) member-body(2) United States(840) mit(113554) 3990 * infosys(1) gssapi(2) generic(1) machine_uid_name(2)}. 3991 * The constant GSS_C_NT_MACHINE_UID_NAME should be 3992 * initialized to point to that gss_OID_desc. 3994 */ 3995 extern gss_OID GSS_C_NT_MACHINE_UID_NAME; 3997 /* 3998 * The implementation must reserve static storage for a 3999 * gss_OID_desc object containing the value 4000 * {10, (void *)"\x2a\x86\x48\x86\xf7\x12" 4001 * "\x01\x02\x01\x03"}, 4002 * corresponding to an object-identifier value of 4003 * {iso(1) member-body(2) United States(840) mit(113554) 4004 * infosys(1) gssapi(2) generic(1) string_uid_name(3)}. 4005 * The constant GSS_C_NT_STRING_UID_NAME should be 4006 * initialized to point to that gss_OID_desc. 4007 */ 4008 extern gss_OID GSS_C_NT_STRING_UID_NAME; 4010 /* 4011 * The implementation must reserve static storage for a 4012 * gss_OID_desc object containing the value 4013 * {6, (void *)"\x2b\x06\x01\x05\x06\x02"}, 4014 * corresponding to an object-identifier value of 4015 * {iso(1) org(3) dod(6) internet(1) security(5) 4016 * nametypes(6) gss-host-based-services(2)). The constant 4017 * GSS_C_NT_HOSTBASED_SERVICE_X should be initialized to point 4018 * to that gss_OID_desc. This is a deprecated OID value, and 4019 * implementations wishing to support hostbased-service names 4020 * should instead use the GSS_C_NT_HOSTBASED_SERVICE OID, 4021 * defined below, to identify such names; 4022 * GSS_C_NT_HOSTBASED_SERVICE_X should be accepted a synonym 4023 * for GSS_C_NT_HOSTBASED_SERVICE when presented as an input 4024 * parameter, but should not be emitted by GSS-API 4025 * implementations 4026 */ 4027 extern gss_OID GSS_C_NT_HOSTBASED_SERVICE_X; 4029 /* 4030 * The implementation must reserve static storage for a 4031 * gss_OID_desc object containing the value 4032 * {10, (void *)"\x2a\x86\x48\x86\xf7\x12" 4033 * "\x01\x02\x01\x04"}, corresponding to an 4034 * object-identifier value of {iso(1) member-body(2) 4035 * Unites States(840) mit(113554) infosys(1) gssapi(2) 4036 * generic(1) service_name(4)}. The constant 4037 * GSS_C_NT_HOSTBASED_SERVICE should be initialized 4038 * to point to that gss_OID_desc. 4039 */ 4040 extern gss_OID GSS_C_NT_HOSTBASED_SERVICE; 4042 /* 4043 * The implementation must reserve static storage for a 4044 * gss_OID_desc object containing the value 4045 * {6, (void *)"\x2b\x06\01\x05\x06\x03"}, 4046 * corresponding to an object identifier value of 4047 * {1(iso), 3(org), 6(dod), 1(internet), 5(security), 4048 * 6(nametypes), 3(gss-anonymous-name)}. The constant 4049 * and GSS_C_NT_ANONYMOUS should be initialized to point 4050 * to that gss_OID_desc. 4051 */ 4052 extern gss_OID GSS_C_NT_ANONYMOUS; 4054 /* 4055 * The implementation must reserve static storage for a 4056 * gss_OID_desc object containing the value 4057 * {6, (void *)"\x2b\x06\x01\x05\x06\x04"}, 4058 * corresponding to an object-identifier value of 4059 * {1(iso), 3(org), 6(dod), 1(internet), 5(security), 4060 * 6(nametypes), 4(gss-api-exported-name)}. The constant 4061 * GSS_C_NT_EXPORT_NAME should be initialized to point 4062 * to that gss_OID_desc. 4063 */ 4064 extern gss_OID GSS_C_NT_EXPORT_NAME; 4066 /* Major status codes */ 4068 #define GSS_S_COMPLETE 0 4070 /* 4071 * Some "helper" definitions to make the status code macros obvious. 4072 */ 4073 #define GSS_C_CALLING_ERROR_OFFSET 24 4074 #define GSS_C_ROUTINE_ERROR_OFFSET 16 4075 #define GSS_C_SUPPLEMENTARY_OFFSET 0 4076 #define GSS_C_CALLING_ERROR_MASK 0377ul 4077 #define GSS_C_ROUTINE_ERROR_MASK 0377ul 4078 #define GSS_C_SUPPLEMENTARY_MASK 0177777ul 4080 /* 4081 * The macros that test status codes for error conditions. 4082 * Note that the GSS_ERROR() macro has changed slightly from 4083 * the V1 GSS-API so that it now evaluates its argument 4084 * only once. 4085 */ 4086 #define GSS_CALLING_ERROR(x) \ 4087 (x & (GSS_C_CALLING_ERROR_MASK << GSS_C_CALLING_ERROR_OFFSET)) 4088 #define GSS_ROUTINE_ERROR(x) \ 4089 (x & (GSS_C_ROUTINE_ERROR_MASK << GSS_C_ROUTINE_ERROR_OFFSET)) 4090 #define GSS_SUPPLEMENTARY_INFO(x) \ 4091 (x & (GSS_C_SUPPLEMENTARY_MASK << GSS_C_SUPPLEMENTARY_OFFSET)) 4092 #define GSS_ERROR(x) \ 4093 (x & ((GSS_C_CALLING_ERROR_MASK << GSS_C_CALLING_ERROR_OFFSET) | \ 4094 (GSS_C_ROUTINE_ERROR_MASK << GSS_C_ROUTINE_ERROR_OFFSET))) 4096 /* 4097 * Now the actual status code definitions 4098 */ 4100 /* 4101 * Calling errors: 4103 */ 4104 #define GSS_S_CALL_INACCESSIBLE_READ \ 4105 (1ul << GSS_C_CALLING_ERROR_OFFSET) 4106 #define GSS_S_CALL_INACCESSIBLE_WRITE \ 4107 (2ul << GSS_C_CALLING_ERROR_OFFSET) 4108 #define GSS_S_CALL_BAD_STRUCTURE \ 4109 (3ul << GSS_C_CALLING_ERROR_OFFSET) 4111 /* 4112 * Routine errors: 4113 */ 4114 #define GSS_S_BAD_MECH (1ul << 4115 GSS_C_ROUTINE_ERROR_OFFSET) 4116 #define GSS_S_BAD_NAME (2ul << 4117 GSS_C_ROUTINE_ERROR_OFFSET) 4118 #define GSS_S_BAD_NAMETYPE (3ul << 4119 GSS_C_ROUTINE_ERROR_OFFSET) 4120 #define GSS_S_BAD_BINDINGS (4ul << 4121 GSS_C_ROUTINE_ERROR_OFFSET) 4122 #define GSS_S_BAD_STATUS (5ul << 4123 GSS_C_ROUTINE_ERROR_OFFSET) 4124 #define GSS_S_BAD_SIG (6ul << 4125 GSS_C_ROUTINE_ERROR_OFFSET) 4126 #define GSS_S_BAD_MIC GSS_S_BAD_SIG 4127 #define GSS_S_NO_CRED (7ul << 4128 GSS_C_ROUTINE_ERROR_OFFSET) 4129 #define GSS_S_NO_CONTEXT (8ul << 4130 GSS_C_ROUTINE_ERROR_OFFSET) 4131 #define GSS_S_DEFECTIVE_TOKEN (9ul << 4132 GSS_C_ROUTINE_ERROR_OFFSET) 4133 #define GSS_S_DEFECTIVE_CREDENTIAL (10ul << 4134 GSS_C_ROUTINE_ERROR_OFFSET) 4135 #define GSS_S_CREDENTIALS_EXPIRED (11ul << 4136 GSS_C_ROUTINE_ERROR_OFFSET) 4137 #define GSS_S_CONTEXT_EXPIRED (12ul << 4138 GSS_C_ROUTINE_ERROR_OFFSET) 4139 #define GSS_S_FAILURE (13ul << 4140 GSS_C_ROUTINE_ERROR_OFFSET) 4141 #define GSS_S_BAD_QOP (14ul << 4142 GSS_C_ROUTINE_ERROR_OFFSET) 4143 #define GSS_S_UNAUTHORIZED (15ul << 4144 GSS_C_ROUTINE_ERROR_OFFSET) 4145 #define GSS_S_UNAVAILABLE (16ul << 4146 GSS_C_ROUTINE_ERROR_OFFSET) 4147 #define GSS_S_DUPLICATE_ELEMENT (17ul << 4148 GSS_C_ROUTINE_ERROR_OFFSET) 4149 #define GSS_S_NAME_NOT_MN (18ul << 4150 GSS_C_ROUTINE_ERROR_OFFSET) 4152 /* 4153 * Supplementary info bits: 4154 */ 4155 #define GSS_S_CONTINUE_NEEDED \ 4156 (1ul << (GSS_C_SUPPLEMENTARY_OFFSET + 0)) 4157 #define GSS_S_DUPLICATE_TOKEN \ 4158 (1ul << (GSS_C_SUPPLEMENTARY_OFFSET + 1)) 4159 #define GSS_S_OLD_TOKEN \ 4160 (1ul << (GSS_C_SUPPLEMENTARY_OFFSET + 2)) 4161 #define GSS_S_UNSEQ_TOKEN \ 4162 (1ul << (GSS_C_SUPPLEMENTARY_OFFSET + 3)) 4163 #define GSS_S_GAP_TOKEN \ 4164 (1ul << (GSS_C_SUPPLEMENTARY_OFFSET + 4)) 4166 /* 4167 * Finally, function prototypes for the GSS-API routines. 4168 */ 4170 OM_uint32 gss_acquire_cred 4171 (OM_uint32 , /* minor_status */ 4172 const gss_name_t, /* desired_name */ 4173 OM_uint32, /* time_req */ 4174 const gss_OID_set, /* desired_mechs */ 4175 gss_cred_usage_t, /* cred_usage */ 4176 gss_cred_id_t , /* output_cred_handle */ 4177 gss_OID_set , /* actual_mechs */ 4178 OM_uint32 * /* time_rec */ 4179 ); 4181 OM_uint32 gss_release_cred 4182 (OM_uint32 , /* minor_status */ 4183 gss_cred_id_t * /* cred_handle */ 4184 ); 4186 OM_uint32 gss_init_sec_context 4187 (OM_uint32 , /* minor_status */ 4188 const gss_cred_id_t, /* initiator_cred_handle */ 4189 gss_ctx_id_t , /* context_handle */ 4190 const gss_name_t, /* target_name */ 4191 const gss_OID, /* mech_type */ 4192 OM_uint32, /* req_flags */ 4193 OM_uint32, /* time_req */ 4194 const gss_channel_bindings_t, 4195 /* input_chan_bindings */ 4196 const gss_buffer_t, /* input_token */ 4197 gss_OID , /* actual_mech_type */ 4198 gss_buffer_t, /* output_token */ 4199 OM_uint32 , /* ret_flags */ 4200 OM_uint32 * /* time_rec */ 4201 ); 4203 OM_uint32 gss_accept_sec_context 4204 (OM_uint32 , /* minor_status */ 4205 gss_ctx_id_t , /* context_handle */ 4206 const gss_cred_id_t, /* acceptor_cred_handle */ 4207 const gss_buffer_t, /* input_token_buffer */ 4208 const gss_channel_bindings_t, 4209 /* input_chan_bindings */ 4210 gss_name_t , /* src_name */ 4211 gss_OID , /* mech_type */ 4212 gss_buffer_t, /* output_token */ 4213 OM_uint32 , /* ret_flags */ 4214 OM_uint32 , /* time_rec */ 4215 gss_cred_id_t * /* delegated_cred_handle */ 4216 ); 4218 OM_uint32 gss_process_context_token 4219 (OM_uint32 , /* minor_status */ 4220 const gss_ctx_id_t, /* context_handle */ 4221 const gss_buffer_t /* token_buffer */ 4222 ); 4224 OM_uint32 gss_delete_sec_context 4225 (OM_uint32 , /* minor_status */ 4226 gss_ctx_id_t , /* context_handle */ 4227 gss_buffer_t /* output_token */ 4228 ); 4230 OM_uint32 gss_context_time 4231 (OM_uint32 , /* minor_status */ 4232 const gss_ctx_id_t, /* context_handle */ 4233 OM_uint32 * /* time_rec */ 4234 ); 4236 OM_uint32 gss_get_mic 4237 (OM_uint32 , /* minor_status */ 4238 const gss_ctx_id_t, /* context_handle */ 4239 gss_qop_t, /* qop_req */ 4240 const gss_buffer_t, /* message_buffer */ 4241 gss_buffer_t /* message_token */ 4242 ); 4244 OM_uint32 gss_verify_mic 4245 (OM_uint32 , /* minor_status */ 4246 const gss_ctx_id_t, /* context_handle */ 4247 const gss_buffer_t, /* message_buffer */ 4248 const gss_buffer_t, /* token_buffer */ 4249 gss_qop_t * /* qop_state */ 4250 ); 4252 OM_uint32 gss_wrap 4253 (OM_uint32 , /* minor_status */ 4254 const gss_ctx_id_t, /* context_handle */ 4255 int, /* conf_req_flag */ 4256 gss_qop_t, /* qop_req */ 4257 const gss_buffer_t, /* input_message_buffer */ 4258 int , /* conf_state */ 4259 gss_buffer_t /* output_message_buffer */ 4260 ); 4262 OM_uint32 gss_unwrap 4263 (OM_uint32 , /* minor_status */ 4264 const gss_ctx_id_t, /* context_handle */ 4265 const gss_buffer_t, /* input_message_buffer */ 4266 gss_buffer_t, /* output_message_buffer */ 4267 int , /* conf_state */ 4268 gss_qop_t * /* qop_state */ 4269 ); 4271 OM_uint32 gss_display_status 4272 (OM_uint32 , /* minor_status */ 4273 OM_uint32, /* status_value */ 4274 int, /* status_type */ 4275 const gss_OID, /* mech_type */ 4276 OM_uint32 , /* message_context */ 4277 gss_buffer_t /* status_string */ 4278 ); 4280 OM_uint32 gss_indicate_mechs 4281 (OM_uint32 , /* minor_status */ 4282 gss_OID_set * /* mech_set */ 4283 ); 4285 OM_uint32 gss_compare_name 4286 (OM_uint32 , /* minor_status */ 4287 const gss_name_t, /* name1 */ 4288 const gss_name_t, /* name2 */ 4289 int * /* name_equal */ 4290 ); 4292 OM_uint32 gss_display_name 4293 (OM_uint32 , /* minor_status */ 4294 const gss_name_t, /* input_name */ 4295 gss_buffer_t, /* output_name_buffer */ 4296 gss_OID * /* output_name_type */ 4297 ); 4299 OM_uint32 gss_import_name 4300 (OM_uint32 , /* minor_status */ 4301 const gss_buffer_t, /* input_name_buffer */ 4302 const gss_OID, /* input_name_type */ 4303 gss_name_t * /* output_name */ 4304 ); 4306 OM_uint32 gss_export_name 4307 (OM_uint32, /* minor_status */ 4308 const gss_name_t, /* input_name */ 4309 gss_buffer_t /* exported_name */ 4310 ); 4312 OM_uint32 gss_release_name 4313 (OM_uint32 *, /* minor_status */ 4314 gss_name_t * /* input_name */ 4315 ); 4317 OM_uint32 gss_release_buffer 4318 (OM_uint32 , /* minor_status */ 4319 gss_buffer_t /* buffer */ 4320 ); 4322 OM_uint32 gss_release_oid_set 4323 (OM_uint32 , /* minor_status */ 4324 gss_OID_set * /* set */ 4325 ); 4327 OM_uint32 gss_inquire_cred 4328 (OM_uint32 , /* minor_status */ 4329 const gss_cred_id_t, /* cred_handle */ 4330 gss_name_t , /* name */ 4331 OM_uint32 , /* lifetime */ 4332 gss_cred_usage_t , /* cred_usage */ 4333 gss_OID_set * /* mechanisms */ 4334 ); 4336 OM_uint32 gss_inquire_context ( 4337 OM_uint32 , /* minor_status */ 4338 const gss_ctx_id_t, /* context_handle */ 4339 gss_name_t , /* src_name */ 4340 gss_name_t , /* targ_name */ 4341 OM_uint32 , /* lifetime_rec */ 4342 gss_OID , /* mech_type */ 4343 OM_uint32 , /* ctx_flags */ 4344 int , /* locally_initiated */ 4345 int * /* open */ 4346 ); 4348 OM_uint32 gss_wrap_size_limit ( 4349 OM_uint32 , /* minor_status */ 4350 const gss_ctx_id_t, /* context_handle */ 4351 int, /* conf_req_flag */ 4352 gss_qop_t, /* qop_req */ 4353 OM_uint32, /* req_output_size */ 4354 OM_uint32 * /* max_input_size */ 4355 ); 4357 OM_uint32 gss_add_cred ( 4358 OM_uint32 , /* minor_status */ 4359 const gss_cred_id_t, /* input_cred_handle */ 4360 const gss_name_t, /* desired_name */ 4361 const gss_OID, /* desired_mech */ 4362 gss_cred_usage_t, /* cred_usage */ 4363 OM_uint32, /* initiator_time_req */ 4364 OM_uint32, /* acceptor_time_req */ 4365 gss_cred_id_t , /* output_cred_handle */ 4366 gss_OID_set , /* actual_mechs */ 4367 OM_uint32 , /* initiator_time_rec */ 4368 OM_uint32 * /* acceptor_time_rec */ 4369 ); 4371 OM_uint32 gss_inquire_cred_by_mech ( 4372 OM_uint32 , /* minor_status */ 4373 const gss_cred_id_t, /* cred_handle */ 4374 const gss_OID, /* mech_type */ 4375 gss_name_t , /* name */ 4376 OM_uint32 , /* initiator_lifetime */ 4377 OM_uint32 , /* acceptor_lifetime */ 4378 gss_cred_usage_t * /* cred_usage */ 4379 ); 4381 OM_uint32 gss_export_sec_context ( 4382 OM_uint32 , /* minor_status */ 4383 gss_ctx_id_t , /* context_handle */ 4384 gss_buffer_t /* interprocess_token */ 4385 ); 4387 OM_uint32 gss_import_sec_context ( 4388 OM_uint32 , /* minor_status */ 4389 const gss_buffer_t, /* interprocess_token */ 4390 gss_ctx_id_t * /* context_handle */ 4391 ); 4393 OM_uint32 gss_create_empty_oid_set ( 4394 OM_uint32 , /* minor_status */ 4395 gss_OID_set * /* oid_set */ 4396 ); 4398 OM_uint32 gss_add_oid_set_member ( 4399 OM_uint32 , /* minor_status */ 4400 const gss_OID, /* member_oid */ 4401 gss_OID_set * /* oid_set */ 4402 ); 4404 OM_uint32 gss_test_oid_set_member ( 4405 OM_uint32 , /* minor_status */ 4406 const gss_OID, /* member */ 4407 const gss_OID_set, /* set */ 4408 int * /* present */ 4409 ); 4411 OM_uint32 gss_inquire_names_for_mech ( 4412 OM_uint32 , /* minor_status */ 4413 const gss_OID, /* mechanism */ 4414 gss_OID_set * /* name_types */ 4415 ); 4417 OM_uint32 gss_inquire_mechs_for_name ( 4418 OM_uint32 , /* minor_status */ 4419 const gss_name_t, /* input_name */ 4420 gss_OID_set * /* mech_types */ 4421 ); 4423 OM_uint32 gss_canonicalize_name ( 4424 OM_uint32 , /* minor_status */ 4425 const gss_name_t, /* input_name */ 4426 const gss_OID, /* mech_type */ 4427 gss_name_t * /* output_name */ 4428 ); 4429 OM_uint32 gss_duplicate_name ( 4430 OM_uint32 , /* minor_status */ 4431 const gss_name_t, /* src_name */ 4432 gss_name_t * /* dest_name */ 4433 ); 4435 /* 4436 * The following routines are obsolete variants of gss_get_mic, 4437 * gss_verify_mic, gss_wrap and gss_unwrap. They should be 4438 * provided by GSS-API V2 implementations for backwards 4439 * compatibility with V1 applications. Distinct entrypoints 4440 * (as opposed to #defines) should be provided, both to allow 4441 * GSS-API V1 applications to link against GSS-API V2 4442 implementations, 4443 * and to retain the slight parameter type differences between the 4444 * obsolete versions of these routines and their current forms. 4445 */ 4447 OM_uint32 gss_sign 4448 (OM_uint32 , /* minor_status */ 4449 gss_ctx_id_t, /* context_handle */ 4450 int, /* qop_req */ 4451 gss_buffer_t, /* message_buffer */ 4452 gss_buffer_t /* message_token */ 4453 ); 4455 OM_uint32 gss_verify 4456 (OM_uint32 , /* minor_status */ 4457 gss_ctx_id_t, /* context_handle */ 4458 gss_buffer_t, /* message_buffer */ 4459 gss_buffer_t, /* token_buffer */ 4460 int * /* qop_state */ 4461 ); 4463 OM_uint32 gss_seal 4464 (OM_uint32 , /* minor_status */ 4465 gss_ctx_id_t, /* context_handle */ 4466 int, /* conf_req_flag */ 4467 int, /* qop_req */ 4468 gss_buffer_t, /* input_message_buffer */ 4469 int , /* conf_state */ 4470 gss_buffer_t /* output_message_buffer */ 4471 ); 4473 OM_uint32 gss_unseal 4474 (OM_uint32 , /* minor_status */ 4475 gss_ctx_id_t, /* context_handle */ 4476 gss_buffer_t, /* input_message_buffer */ 4477 gss_buffer_t, /* output_message_buffer */ 4478 int , /* conf_state */ 4479 int * /* qop_state */ 4480 ); 4481 #endif /* GSSAPI_H_ */ 4483 APPENDIX B. Additional constraints for application binary portability 4485 The purpose of this C-bindings document is to encourage source-level 4486 portability of applications across GSS-API implementations on 4487 different platforms and atop different mechanisms. Additional goals 4488 that have not been explicitly addressed by this document are 4489 link-time and run-time portability. 4491 Link-time portability provides the ability to compile an application 4492 against one implementation of GSS-API, and then link it against a 4493 different implementation on the same platform. It is a stricter 4494 requirement than source-level portability. 4496 Run-time portability differs from link-time portability only on those 4497 platforms that implement dynamically loadable GSS-API 4498 implementations, but do not offer load-time symbol resolution. On 4499 such platforms, run-time portability is a stricter requirement than 4500 link-time portability, and will typically include the precise 4501 placement of the various GSS-API routines within library entrypoint 4502 vectors. 4504 Individual platforms will impose their own rules that must be 4505 followed to achieve link-time (and run-time, if different) 4506 portability. In order to ensure either form of binary portability, 4507 an ABI specification must be written for GSS-API implementations on 4508 that platform. However, it is recognized that there are some issues 4509 that are likely to be common to all such ABI specifications. This 4510 appendix is intended to be a repository for such common issues, and 4511 contains some suggestions that individual ABI specifications may 4512 choose to reference. Since machine architectures vary greatly, it may 4513 not be possible or desirable to follow these suggestions on all 4514 platforms. 4516 B.1. Pointers 4518 While ANSI-C provides a single pointer type for each declared type, 4519 plus a single (void *) type, some platforms (notably those using 4520 segmented memory architectures) augment this with various modified 4521 pointer types (e.g. far pointers, near pointers). These language 4522 bindings assume ANSI-C, and thus do not address such non-standard 4523 implementations. GSS-API implementations for such platforms must 4524 choose an appropriate memory model, and should use it consistently 4525 throughout. For example, if a memory model is chosen that requires 4526 the use of far pointers when passing routine parameters, then far 4527 pointers should also be used within the structures defined by 4528 GSS-API. 4530 B.2. Internal structure alignment 4532 GSS-API defines several data-structures containing differently-sized 4533 fields. An ABI specification should include a detailed description 4534 of how the fields of such structures are aligned, and if there is any 4535 internal padding in these data structures. The use of compiler 4536 defaults for the platform is recommended. 4538 B.3. Handle types 4540 The C bindings specify that the gss_cred_id_t and gss_ctx_id_t types 4541 should be implemented as either pointer or arithmetic types, and that 4542 if pointer types are used, care should be taken to ensure that two 4543 handles may be compared with the == operator. Note that ANSI-C does 4544 not guarantee that two pointer values may be compared with the == 4545 operator unless either the two pointers point to members of a single 4546 array, or at least one of the pointers contains a NULL value. 4548 For binary portability, additional constraints are required. The 4549 following is an attempt at defining platform-independent constraints. 4551 The size of the handle type must be the same as sizeof(void *), using 4552 the appropriate memory model. 4554 The == operator for the chosen type must be a simple bit-wise 4555 comparison. That is, for two in-memory handle objects h1 and h2, the 4556 boolean value of the expression 4558 (h1 == h2) 4560 should always be the same as the boolean value of the expression 4562 (memcmp(&h1, &h2, sizeof(h1)) == 0) 4564 The actual use of the type (void *) for handle types is discouraged, 4565 not for binary portability reasons, but since it effectively disables 4566 much of the compile-time type-checking that the compiler can 4567 otherwise perform, and is therefore not "programmer-friendly". If a 4568 pointer implementation is desired, and if the platform's 4569 implementation of pointers permits, the handles should be implemented 4570 as pointers to distinct implementation-defined types. 4572 B.4. The gss_name_t type 4574 The gss_name_t type, representing the internal name object, should be 4575 implemented as a pointer type. The use of the (void *) type is 4576 discouraged as it does not allow the compiler to perform strong 4577 type-checking. However, the pointer type chosen should be of the 4578 same size as the (void *) type. Provided this rule is obeyed, ABI 4579 specifications need not further constrain the implementation of 4580 gss_name_t objects. 4582 B.5. The int and size_t types 4584 Some platforms may support differently sized implementations of the 4585 "int" and "size_t" types, perhaps chosen through compiler switches, 4586 and perhaps dependent on memory model. An ABI specification for such 4587 a platform should include required implementations for these types. 4588 It is recommended that the default implementation (for the chosen 4589 memory model, if appropriate) is chosen. 4591 B.6. Procedure-calling conventions 4593 Some platforms support a variety of different binary conventions for 4594 calling procedures. Such conventions cover things like the format of 4595 the stack frame, the order in which the routine parameters are pushed 4596 onto the stack, whether or not a parameter count is pushed onto the 4597 stack, whether some argument(s) or return values are to be passed in 4598 registers, and whether the called routine or the caller is 4599 responsible for removing the stack frame on return. For such 4600 platforms, an ABI specification should specify which calling 4601 convention is to be used for GSS-API implementations. 4603 REFERENCES 4605 [GSSAPI] J. Linn, "Generic Security Service 4606 Application Program Interface, Version 2", 4607 RFC2078. 4609 [XOM] OSI Object Management API Specification, 4610 Version 2.0 t", X.400 API Association & 4611 X/Open Company Limited, August 24, 1990 4612 Specification of datatypes and routines for 4613 manipulating information objects. 4615 AUTHOR'S ADDRESS 4617 John Wray Internet email: John_Wray@Iris.com 4618 Iris Associates Telephone: +1-978-392-6689 4619 5 Technology Park Drive, 4620 Westford, MA 01886 4621 USA