idnits 2.17.1 draft-ietf-cat-rfc2078bis-04.txt: 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 -- however, there's a paragraph with a matching beginning. Boilerplate error? ** The document seems to lack a 1id_guidelines paragraph about the list of current Internet-Drafts. ** The document seems to lack a 1id_guidelines paragraph about the list of Shadow Directories. ** The document is more than 15 pages and seems to lack a Table of Contents. == No 'Intended status' indicated for this document; assuming Proposed Standard == The page length should not exceed 58 lines per page, but there was 99 longer pages, the longest (page 25) being 63 lines == It seems as if not all pages are separated by form feeds - found 0 form feeds but 100 pages Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack an Introduction section. ** The document seems to lack a Security Considerations section. ** The document seems to lack an IANA Considerations section. (See Section 2.2 of https://www.ietf.org/id-info/checklist for how to handle the case when there are no actions for IANA.) ** The abstract seems to contain references ([APPLICATION0], [RFC-2203], [ISO-7498-2], [RFC-1507], [ISOIEC-8824], [RFC-1964], [RFC-1508], [ISOIEC-8825], [RFC-1509], [RFC-2025], [RFC-2078]), which it shouldn't. Please replace those with straight textual mentions of the documents in question. Miscellaneous warnings: ---------------------------------------------------------------------------- == Line 1254 has weird spacing: '...t_token pro...' == Line 1292 has weird spacing: '...or_mech indi...' == Line 1294 has weird spacing: '...or_name indi...' == Line 3854 has weird spacing: '... ... zz expor...' -- 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 (23 April 1998) is 9499 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) -- Missing reference section? 'RFC-2078' on line 4201 looks like a reference -- Missing reference section? 'ISO-7498-2' on line 4177 looks like a reference -- Missing reference section? 'RFC-1964' on line 4195 looks like a reference -- Missing reference section? 'RFC-2025' on line 4198 looks like a reference -- Missing reference section? 'RFC-2203' on line 4204 looks like a reference -- Missing reference section? 'ISOIEC-8825' on line 4183 looks like a reference -- Missing reference section? 'ISOIEC-8824' on line 4180 looks like a reference -- Missing reference section? 'RFC-1507' on line 4186 looks like a reference -- Missing reference section? 'APPLICATION 0' on line 3778 looks like a reference -- Missing reference section? 'RFC-1509' on line 4192 looks like a reference -- Missing reference section? 'RFC-1508' on line 4227 looks like a reference Summary: 11 errors (**), 0 flaws (~~), 7 warnings (==), 13 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Internet-Draft J. Linn 3 IETF Common Authentication Technology WG RSA Laboratories 4 23 April 1998 6 Generic Security Service Application Program Interface 7 Version 2, Update 1 9 STATUS OF THIS MEMO 11 This document is an Internet-Draft. Internet-Drafts are working 12 documents of the Internet Engineering Task Force (IETF), its areas, 13 and its working groups. Note that other groups may also distribute 14 working documents as Internet-Drafts. 16 Internet-Drafts are draft documents valid for a maximum of six months 17 and may be updated, replaced, or obsoleted by other documents at any 18 time. It is inappropriate to use Internet- Drafts as reference 19 material or to cite them other than as ``work in progress.'' 21 To view the entire list of current Internet-Drafts, please check 22 the "1id-abstracts.txt" listing contained in the Internet-Drafts 23 Shadow Directories on ftp.is.co.za (Africa), ftp.nordu.net 24 (Northern Europe), ftp.nis.garr.it (Southern Europe), munnari.oz.au 25 (Pacific Rim), ftp.ietf.org (US East Coast), or ftp.isi.edu 26 (US West Coast). 28 Comments on this document should be sent to "cat-ietf@mit.edu", the 29 IETF Common Authentication Technology WG discussion list. 31 ABSTRACT 33 The Generic Security Service Application Program Interface (GSS-API), 34 Version 2, as defined in [RFC-2078], provides security services to 35 callers in a generic fashion, supportable with a range of underlying 36 mechanisms and technologies and hence allowing source-level 37 portability of applications to different environments. This 38 specification defines GSS-API services and primitives at a level 39 independent of underlying mechanism and programming language 40 environment, and is to be complemented by other, related 41 specifications: 43 documents defining specific parameter bindings for particular 44 language environments 46 documents defining token formats, protocols, and procedures to be 47 implemented in order to realize GSS-API services atop particular 48 security mechanisms 50 This Internet-Draft revises [RFC-2078], making specific, incremental 51 changes in response to implementation experience and liaison 52 requests. It is intended, therefore, that this draft or a successor 53 version thereto will become the basis for subsequent progression of 54 the GSS-API specification on the standards track. 56 1: GSS-API Characteristics and Concepts 58 GSS-API operates in the following paradigm. A typical GSS-API caller 59 is itself a communications protocol, calling on GSS-API in order to 60 protect its communications with authentication, integrity, and/or 61 confidentiality security services. A GSS-API caller accepts tokens 62 provided to it by its local GSS-API implementation and transfers the 63 tokens to a peer on a remote system; that peer passes the received 64 tokens to its local GSS-API implementation for processing. The 65 security services available through GSS-API in this fashion are 66 implementable (and have been implemented) over a range of underlying 67 mechanisms based on secret-key and public-key cryptographic 68 technologies. 70 The GSS-API separates the operations of initializing a security 71 context between peers, achieving peer entity authentication 72 (GSS_Init_sec_context() and GSS_Accept_sec_context() calls), from the 73 operations of providing per-message data origin authentication and 74 data integrity protection (GSS_GetMIC() and GSS_VerifyMIC() calls) 75 for messages subsequently transferred in conjunction with that 76 context. (The definition for the peer entity authentication service, 77 and other definitions used in this document, corresponds to that 78 provided in [ISO-7498-2].) When establishing a security context, the 79 GSS-API enables a context initiator to optionally permit its 80 credentials to be delegated, meaning that the context acceptor may 81 initiate further security contexts on behalf of the initiating 82 caller. Per-message GSS_Wrap() and GSS_Unwrap() calls provide the 83 data origin authentication and data integrity services which 84 GSS_GetMIC() and GSS_VerifyMIC() offer, and also support selection of 85 confidentiality services as a caller option. Additional calls provide 86 supportive functions to the GSS-API's users. 88 The following paragraphs provide an example illustrating the 89 dataflows involved in use of the GSS-API by a client and server in a 90 mechanism-independent fashion, establishing a security context and 91 transferring a protected message. The example assumes that credential 92 acquisition has already been completed. The example also assumes 93 that the underlying authentication technology is capable of 94 authenticating a client to a server using elements carried within a 95 single token, and of authenticating the server to the client (mutual 96 authentication) with a single returned token; this assumption holds 97 for some presently-documented CAT mechanisms but is not necessarily 98 true for other cryptographic technologies and associated protocols. 100 The client calls GSS_Init_sec_context() to establish a security 101 context to the server identified by targ_name, and elects to set the 102 mutual_req_flag so that mutual authentication is performed in the 103 course of context establishment. GSS_Init_sec_context() returns an 104 output_token to be passed to the server, and indicates 105 GSS_S_CONTINUE_NEEDED status pending completion of the mutual 106 authentication sequence. Had mutual_req_flag not been set, the 107 initial call to GSS_Init_sec_context() would have returned 108 GSS_S_COMPLETE status. The client sends the output_token to the 109 server. 111 The server passes the received token as the input_token parameter to 112 GSS_Accept_sec_context(). GSS_Accept_sec_context indicates 113 GSS_S_COMPLETE status, provides the client's authenticated identity 114 in the src_name result, and provides an output_token to be passed to 115 the client. The server sends the output_token to the client. 117 The client passes the received token as the input_token parameter to 118 a successor call to GSS_Init_sec_context(), which processes data 119 included in the token in order to achieve mutual authentication from 120 the client's viewpoint. This call to GSS_Init_sec_context() returns 121 GSS_S_COMPLETE status, indicating successful mutual authentication 122 and the completion of context establishment for this example. 124 The client generates a data message and passes it to GSS_Wrap(). 125 GSS_Wrap() performs data origin authentication, data integrity, and 126 (optionally) confidentiality processing on the message and 127 encapsulates the result into output_message, indicating 128 GSS_S_COMPLETE status. The client sends the output_message to the 129 server. 131 The server passes the received message to GSS_Unwrap(). GSS_Unwrap() 132 inverts the encapsulation performed by GSS_Wrap(), deciphers the 133 message if the optional confidentiality feature was applied, and 134 validates the data origin authentication and data integrity checking 135 quantities. GSS_Unwrap() indicates successful validation by returning 136 GSS_S_COMPLETE status along with the resultant output_message. 138 For purposes of this example, we assume that the server knows by 139 out-of-band means that this context will have no further use after 140 one protected message is transferred from client to server. Given 141 this premise, the server now calls GSS_Delete_sec_context() to flush 142 context-level information. Optionally, the server-side application 143 may provide a token buffer to GSS_Delete_sec_context(), to receive a 144 context_token to be transferred to the client in order to request 145 that client-side context-level information be deleted. 147 If a context_token is transferred, the client passes the 148 context_token to GSS_Process_context_token(), which returns 149 GSS_S_COMPLETE status after deleting context-level information at the 150 client system. 152 The GSS-API design assumes and addresses several basic goals, 153 including: 155 Mechanism independence: The GSS-API defines an interface to 156 cryptographically implemented strong authentication and other 157 security services at a generic level which is independent of 158 particular underlying mechanisms. For example, GSS-API-provided 159 services have been implemented using secret-key technologies 160 (e.g., Kerberos, per [RFC-1964]) and with public-key approaches 161 (e.g., SPKM, per [RFC-2025]). 163 Protocol environment independence: The GSS-API is independent of 164 the communications protocol suites with which it is employed, 165 permitting use in a broad range of protocol environments. In 166 appropriate environments, an intermediate implementation "veneer" 167 which is oriented to a particular communication protocol may be 168 interposed between applications which call that protocol and the 169 GSS-API (e.g., as defined in [RFC-2203] for Open Network Computing 170 Remote Procedure Call (RPC)), thereby invoking GSS-API facilities 171 in conjunction with that protocol's communications invocations. 173 Protocol association independence: The GSS-API's security context 174 construct is independent of communications protocol association 175 constructs. This characteristic allows a single GSS-API 176 implementation to be utilized by a variety of invoking protocol 177 modules on behalf of those modules' calling applications. GSS-API 178 services can also be invoked directly by applications, wholly 179 independent of protocol associations. 181 Suitability to a range of implementation placements: GSS-API 182 clients are not constrained to reside within any Trusted Computing 183 Base (TCB) perimeter defined on a system where the GSS-API is 184 implemented; security services are specified in a manner suitable 185 to both intra-TCB and extra-TCB callers. 187 1.1: GSS-API Constructs 189 This section describes the basic elements comprising the GSS-API. 191 1.1.1: Credentials 193 1.1.1.1: Credential Constructs and Concepts 195 Credentials provide the prerequisites which permit GSS-API peers to 196 establish security contexts with each other. A caller may designate 197 that the credential elements which are to be applied for context 198 initiation or acceptance be selected by default. Alternately, those 199 GSS-API callers which need to make explicit selection of particular 200 credentials structures may make references to those credentials 201 through GSS-API-provided credential handles ("cred_handles"). In all 202 cases, callers' credential references are indirect, mediated by GSS- 203 API implementations and not requiring callers to access the selected 204 credential elements. 206 A single credential structure may be used to initiate outbound 207 contexts and to accept inbound contexts. Callers needing to operate 208 in only one of these modes may designate this fact when credentials 209 are acquired for use, allowing underlying mechanisms to optimize 210 their processing and storage requirements. The credential elements 211 defined by a particular mechanism may contain multiple cryptographic 212 keys, e.g., to enable authentication and message encryption to be 213 performed with different algorithms. 215 A GSS-API credential structure may contain multiple credential 216 elements, each containing mechanism-specific information for a 217 particular underlying mechanism (mech_type), but the set of elements 218 within a given credential structure represent a common entity. A 219 credential structure's contents will vary depending on the set of 220 mech_types supported by a particular GSS-API implementation. Each 221 credential element identifies the data needed by its mechanism in 222 order to establish contexts on behalf of a particular principal, and 223 may contain separate credential references for use in context 224 initiation and context acceptance. Multiple credential elements 225 within a given credential having overlapping combinations of 226 mechanism, usage mode, and validity period are not permitted. 228 Commonly, a single mech_type will be used for all security contexts 229 established by a particular initiator to a particular target. A major 230 motivation for supporting credential sets representing multiple 231 mech_types is to allow initiators on systems which are equipped to 232 handle multiple types to initiate contexts to targets on other 233 systems which can accommodate only a subset of the set supported at 234 the initiator's system. 236 1.1.1.2: Credential Management 238 It is the responsibility of underlying system-specific mechanisms and 239 OS functions below the GSS-API to ensure that the ability to acquire 240 and use credentials associated with a given identity is constrained 241 to appropriate processes within a system. This responsibility should 242 be taken seriously by implementors, as the ability for an entity to 243 utilize a principal's credentials is equivalent to the entity's 244 ability to successfully assert that principal's identity. 246 Once a set of GSS-API credentials is established, the transferability 247 of that credentials set to other processes or analogous constructs 248 within a system is a local matter, not defined by the GSS-API. An 249 example local policy would be one in which any credentials received 250 as a result of login to a given user account, or of delegation of 251 rights to that account, are accessible by, or transferable to, 252 processes running under that account. 254 The credential establishment process (particularly when performed on 255 behalf of users rather than server processes) is likely to require 256 access to passwords or other quantities which should be protected 257 locally and exposed for the shortest time possible. As a result, it 258 will often be appropriate for preliminary credential establishment to 259 be performed through local means at user login time, with the 260 result(s) cached for subsequent reference. These preliminary 261 credentials would be set aside (in a system-specific fashion) for 262 subsequent use, either: 264 to be accessed by an invocation of the GSS-API GSS_Acquire_cred() 265 call, returning an explicit handle to reference that credential 267 to comprise default credential elements to be installed, and to be 268 used when default credential behavior is requested on behalf of a 269 process 271 1.1.1.3: Default Credential Resolution 273 The GSS_Init_sec_context() and GSS_Accept_sec_context() routines 274 allow the value GSS_C_NO_CREDENTIAL to be specified as their 275 credential handle parameter. This special credential-handle 276 indicates a desire by the application to act as a default principal. 277 In support of application portability, support for the default 278 resolution behavior described below for initiator credentials 279 (GSS_Init_sec_context() usage) is mandated; support for the default 280 resolution behavior described below for acceptor credentials 281 (GSS_Accept_sec_context() usage) is recommended. If default 282 credential resolution fails, GSS_S_NO_CRED status is to be returned. 284 GSS_Init_sec_context: 286 (i) If there is only a single principal capable of initiating 287 security contexts that the application is authorized to act on 288 behalf of, then that principal shall be used, otherwise 290 (ii) If the platform maintains a concept of a default network- 291 identity, and if the application is authorized to act on behalf 292 of that identity for the purpose of initiating security 293 contexts, then the principal corresponding to that identity 294 shall be used, otherwise 296 (iii) If the platform maintains a concept of a default local 297 identity, and provides a means to map local identities into 298 network-identities, and if the application is authorized to act 299 on behalf of the network-identity image of the default local 300 identity for the purpose of initiating security contexts, then 301 the principal corresponding to that identity shall be used, 302 otherwise 304 (iv) A user-configurable default identity should be used. 306 GSS_Accept_sec_context: 308 (i) If there is only a single authorized principal identity 309 capable of accepting security contexts, then that principal 310 shall be used, otherwise 312 (ii) If the mechanism can determine the identity of the target 313 principal by examining the context-establishment token, and if 314 the accepting application is authorized to act as that 315 principal for the purpose of accepting security contexts, then 316 that principal identity shall be used, otherwise 318 (iii) If the mechanism supports context acceptance by any 319 principal, and mutual authentication was not requested, any 320 principal that the application is authorized to accept security 321 contexts under may be used, otherwise 323 (iv) A user-configurable default identity shall be used. 325 The purpose of the above rules is to allow security contexts to be 326 established by both initiator and acceptor using the default behavior 327 wherever possible. Applications requesting default behavior are 328 likely to be more portable across mechanisms and platforms than those 329 that use GSS_Acquire_cred() to request a specific identity. 331 1.1.2: Tokens 333 Tokens are data elements transferred between GSS-API callers, and are 334 divided into two classes. Context-level tokens are exchanged in order 335 to establish and manage a security context between peers. Per-message 336 tokens relate to an established context and are exchanged to provide 337 protective security services (i.e., data origin authentication, 338 integrity, and optional confidentiality) for corresponding data 339 messages. 341 The first context-level token obtained from GSS_Init_sec_context() is 342 required to indicate at its very beginning a globally-interpretable 343 mechanism identifier, i.e., an Object Identifier (OID) of the 344 security mechanism. The remaining part of this token as well as the 345 whole content of all other tokens are specific to the particular 346 underlying mechanism used to support the GSS-API. Section 3.1 of this 347 document provides, for designers of GSS-API mechanisms, the 348 description of the header of the first context-level token which is 349 then followed by mechanism-specific information. 351 Tokens' contents are opaque from the viewpoint of GSS-API callers. 352 They are generated within the GSS-API implementation at an end 353 system, provided to a GSS-API caller to be transferred to the peer 354 GSS-API caller at a remote end system, and processed by the GSS-API 355 implementation at that remote end system. Tokens may be output by 356 GSS-API calls (and should be transferred to GSS-API peers) whether or 357 not the calls' status indicators indicate successful completion. 358 Zero-length tokens are never returned by GSS routines for transfer to 359 a peer. Token transfer may take place in an in-band manner, 360 integrated into the same protocol stream used by the GSS-API callers 361 for other data transfers, or in an out-of-band manner across a 362 logically separate channel. 364 Different GSS-API tokens are used for different purposes (e.g., 365 context initiation, context acceptance, protected message data on an 366 established context), and it is the responsibility of a GSS-API 367 caller receiving tokens to distinguish their types, associate them 368 with corresponding security contexts, and pass them to appropriate 369 GSS-API processing routines. Depending on the caller protocol 370 environment, this distinction may be accomplished in several ways. 372 The following examples illustrate means through which tokens' types 373 may be distinguished: 375 - implicit tagging based on state information (e.g., all tokens on 376 a new association are considered to be context establishment 377 tokens until context establishment is completed, at which point 378 all tokens are considered to be wrapped data objects for that 379 context), 381 - explicit tagging at the caller protocol level, 383 - a hybrid of these approaches. 385 Commonly, the encapsulated data within a token includes internal 386 mechanism-specific tagging information, enabling mechanism-level 387 processing modules to distinguish tokens used within the mechanism 388 for different purposes. Such internal mechanism-level tagging is 389 recommended to mechanism designers, and enables mechanisms to 390 determine whether a caller has passed a particular token for 391 processing by an inappropriate GSS-API routine. 393 Development of GSS-API mechanisms based on a particular underlying 394 cryptographic technique and protocol (i.e., conformant to a specific 395 GSS-API mechanism definition) does not necessarily imply that GSS-API 396 callers using that GSS-API mechanism will be able to interoperate 397 with peers invoking the same technique and protocol outside the GSS- 398 API paradigm, or with peers implementing a different GSS-API 399 mechanism based on the same underlying technology. The format of 400 GSS-API tokens defined in conjunction with a particular mechanism, 401 and the techniques used to integrate those tokens into callers' 402 protocols, may not be interoperable with the tokens used by non-GSS- 403 API callers of the same underlying technique. 405 1.1.3: Security Contexts 407 Security contexts are established between peers, using credentials 408 established locally in conjunction with each peer or received by 409 peers via delegation. Multiple contexts may exist simultaneously 410 between a pair of peers, using the same or different sets of 411 credentials. Coexistence of multiple contexts using different 412 credentials allows graceful rollover when credentials expire. 413 Distinction among multiple contexts based on the same credentials 414 serves applications by distinguishing different message streams in a 415 security sense. 417 The GSS-API is independent of underlying protocols and addressing 418 structure, and depends on its callers to transport GSS-API-provided 419 data elements. As a result of these factors, it is a caller 420 responsibility to parse communicated messages, separating GSS-API- 421 related data elements from caller-provided data. The GSS-API is 422 independent of connection vs. connectionless orientation of the 423 underlying communications service. 425 No correlation between security context and communications protocol 426 association is dictated. (The optional channel binding facility, 427 discussed in Section 1.1.6 of this document, represents an 428 intentional exception to this rule, supporting additional protection 429 features within GSS-API supporting mechanisms.) This separation 430 allows the GSS-API to be used in a wide range of communications 431 environments, and also simplifies the calling sequences of the 432 individual calls. In many cases (depending on underlying security 433 protocol, associated mechanism, and availability of cached 434 information), the state information required for context setup can be 435 sent concurrently with initial signed user data, without interposing 436 additional message exchanges. Messages may be protected and 437 transferred in both directions on an established GSS-API security 438 context concurrently; protection of messages in one direction does 439 not interfere with protection of messages in the reverse direction. 441 GSS-API implementations are expected to retain inquirable context 442 data on a context until the context is released by a caller, even 443 after the context has expired, although underlying cryptographic data 444 elements may be deleted after expiration in order to limit their 445 exposure. 447 1.1.4: Mechanism Types 449 In order to successfully establish a security context with a target 450 peer, it is necessary to identify an appropriate underlying mechanism 451 type (mech_type) which both initiator and target peers support. The 452 definition of a mechanism embodies not only the use of a particular 453 cryptographic technology (or a hybrid or choice among alternative 454 cryptographic technologies), but also definition of the syntax and 455 semantics of data element exchanges which that mechanism will employ 456 in order to support security services. 458 It is recommended that callers initiating contexts specify the 459 "default" mech_type value, allowing system-specific functions within 460 or invoked by the GSS-API implementation to select the appropriate 461 mech_type, but callers may direct that a particular mech_type be 462 employed when necessary. 464 For GSS-API purposes, the phrase "negotiating mechanism" refers to a 465 mechanism which itself performs negotiation in order to select a 466 concrete mechanism which is shared between peers and is then used for 467 context establishment. Only those mechanisms which are defined in 468 their specifications as negotiating mechanisms are to yield selected 469 mechanisms with different identifier values than the value which is 470 input by a GSS-API caller, except for the case of a caller requesting 471 the "default" mech_type. 473 The means for identifying a shared mech_type to establish a security 474 context with a peer will vary in different environments and 475 circumstances; examples include (but are not limited to): 477 use of a fixed mech_type, defined by configuration, within an 478 environment 480 syntactic convention on a target-specific basis, through 481 examination of a target's name 483 lookup of a target's name in a naming service or other database in 484 order to identify mech_types supported by that target 485 explicit negotiation between GSS-API callers in advance of 486 security context setup 488 use of a negotiating mechanism 490 When transferred between GSS-API peers, mech_type specifiers (per 491 Section 3 of this document, represented as Object Identifiers (OIDs)) 492 serve to qualify the interpretation of associated tokens. (The 493 structure and encoding of Object Identifiers is defined in [ISOIEC- 494 8824] and [ISOIEC-8825].) Use of hierarchically structured OIDs 495 serves to preclude ambiguous interpretation of mech_type specifiers. 496 The OID representing the DASS ([RFC-1507]) MechType, for example, is 497 1.3.12.2.1011.7.5, and that of the Kerberos V5 mechanism ([RFC- 498 1964]), having been advanced to the level of Proposed Standard, is 499 1.2.840.113554.1.2.2. 501 1.1.5: Naming 503 The GSS-API avoids prescribing naming structures, treating the names 504 which are transferred across the interface in order to initiate and 505 accept security contexts as opaque objects. This approach supports 506 the GSS-API's goal of implementability atop a range of underlying 507 security mechanisms, recognizing the fact that different mechanisms 508 process and authenticate names which are presented in different 509 forms. Generalized services offering translation functions among 510 arbitrary sets of naming environments are outside the scope of the 511 GSS-API; availability and use of local conversion functions to 512 translate among the naming formats supported within a given end 513 system is anticipated. 515 Different classes of name representations are used in conjunction 516 with different GSS-API parameters: 518 - Internal form (denoted in this document by INTERNAL NAME), 519 opaque to callers and defined by individual GSS-API 520 implementations. GSS-API implementations supporting multiple 521 namespace types must maintain internal tags to disambiguate the 522 interpretation of particular names. A Mechanism Name (MN) is a 523 special case of INTERNAL NAME, guaranteed to contain elements 524 corresponding to one and only one mechanism; calls which are 525 guaranteed to emit MNs or which require MNs as input are so 526 identified within this specification. 528 - Contiguous string ("flat") form (denoted in this document by 529 OCTET STRING); accompanied by OID tags identifying the namespace 530 to which they correspond. Depending on tag value, flat names may 531 or may not be printable strings for direct acceptance from and 532 presentation to users. Tagging of flat names allows GSS-API 533 callers and underlying GSS-API mechanisms to disambiguate name 534 types and to determine whether an associated name's type is one 535 which they are capable of processing, avoiding aliasing problems 536 which could result from misinterpreting a name of one type as a 537 name of another type. 539 - The GSS-API Exported Name Object, a special case of flat name 540 designated by a reserved OID value, carries a canonicalized form 541 of a name suitable for binary comparisons. 543 In addition to providing means for names to be tagged with types, 544 this specification defines primitives to support a level of naming 545 environment independence for certain calling applications. To provide 546 basic services oriented towards the requirements of callers which 547 need not themselves interpret the internal syntax and semantics of 548 names, GSS-API calls for name comparison (GSS_Compare_name()), 549 human-readable display (GSS_Display_name()), input conversion 550 (GSS_Import_name()), internal name deallocation (GSS_Release_name()), 551 and internal name duplication (GSS_Duplicate_name()) functions are 552 defined. (It is anticipated that these proposed GSS-API calls will be 553 implemented in many end systems based on system-specific name 554 manipulation primitives already extant within those end systems; 555 inclusion within the GSS-API is intended to offer GSS-API callers a 556 portable means to perform specific operations, supportive of 557 authorization and audit requirements, on authenticated names.) 559 GSS_Import_name() implementations can, where appropriate, support 560 more than one printable syntax corresponding to a given namespace 561 (e.g., alternative printable representations for X.500 Distinguished 562 Names), allowing flexibility for their callers to select among 563 alternative representations. GSS_Display_name() implementations 564 output a printable syntax selected as appropriate to their 565 operational environments; this selection is a local matter. Callers 566 desiring portability across alternative printable syntaxes should 567 refrain from implementing comparisons based on printable name forms 568 and should instead use the GSS_Compare_name() call to determine 569 whether or not one internal-format name matches another. 571 When used in large access control lists, the overhead of invoking 572 GSS_Import_name() and GSS_Compare_name() on each name from the ACL 573 may be prohibitive. As an alternative way of supporting this case, 574 GSS-API defines a special form of the contiguous string name which 575 may be compared directly (e.g., with memcmp()). Contiguous names 576 suitable for comparison are generated by the GSS_Export_name() 577 routine, which requires an MN as input. Exported names may be re- 578 imported by the GSS_Import_name() routine, and the resulting internal 579 name will also be an MN. The symbolic constant GSS_C_NT_EXPORT_NAME 580 identifies the "export name" type. Structurally, an exported name 581 object consists of a header containing an OID identifying the 582 mechanism that authenticated the name, and a trailer containing the 583 name itself, where the syntax of the trailer is defined by the 584 individual mechanism specification. The precise format of an 585 exported name is defined in Section 3.2 of this specification. 587 Note that the results obtained by using GSS_Compare_name() will in 588 general be different from those obtained by invoking 589 GSS_Canonicalize_name() and GSS_Export_name(), and then comparing the 590 exported names. The first series of operation determines whether two 591 (unauthenticated) names identify the same principal; the second 592 whether a particular mechanism would authenticate them as the same 593 principal. These two operations will in general give the same 594 results only for MNs. 596 The following diagram illustrates the intended dataflow among name- 597 related GSS-API processing routines. 599 GSS-API library defaults 600 | 601 | 602 V text, for 603 text --------------> internal_name (IN) -----------> display only 604 import_name() / display_name() 605 / 606 / 607 / 608 accept_sec_context() / 609 | / 610 | / 611 | / canonicalize_name() 612 | / 613 | / 614 | / 615 | / 616 | / 617 | | 618 V V <--------------------- 619 single mechanism import_name() exported name: flat 620 internal_name (MN) binary "blob" usable 621 ----------------------> for access control 622 export_name() 624 1.1.6: Channel Bindings 626 The GSS-API accommodates the concept of caller-provided channel 627 binding ("chan_binding") information. Channel bindings are used to 628 strengthen the quality with which peer entity authentication is 629 provided during context establishment, by limiting the scope within 630 which an intercepted context establishment token can be reused by an 631 attacker. Specifically, they enable GSS-API callers to bind the 632 establishment of a security context to relevant characteristics 633 (e.g., addresses, transformed representations of encryption keys) of 634 the underlying communications channel, of protection mechanisms 635 applied to that communications channel, and to application-specific 636 data. 638 The caller initiating a security context must determine the 639 appropriate channel binding values to provide as input to the 640 GSS_Init_sec_context() call, and consistent values must be provided 641 to GSS_Accept_sec_context() by the context's target, in order for 642 both peers' GSS-API mechanisms to validate that received tokens 643 possess correct channel-related characteristics. Use or non-use of 644 the GSS-API channel binding facility is a caller option. GSS-API 645 mechanisms can operate in an environment where NULL channel bindings 646 are presented; mechanism implementors are encouraged, but not 647 required, to make use of caller-provided channel binding data within 648 their mechanisms. Callers should not assume that underlying 649 mechanisms provide confidentiality protection for channel binding 650 information. 652 When non-NULL channel bindings are provided by callers, certain 653 mechanisms can offer enhanced security value by interpreting the 654 bindings' content (rather than simply representing those bindings, or 655 integrity check values computed on them, within tokens) and will 656 therefore depend on presentation of specific data in a defined 657 format. To this end, agreements among mechanism implementors are 658 defining conventional interpretations for the contents of channel 659 binding arguments, including address specifiers (with content 660 dependent on communications protocol environment) for context 661 initiators and acceptors. (These conventions are being incorporated 662 in GSS-API mechanism specifications and into the GSS-API C language 663 bindings specification.) In order for GSS-API callers to be portable 664 across multiple mechanisms and achieve the full security 665 functionality which each mechanism can provide, it is strongly 666 recommended that GSS-API callers provide channel bindings consistent 667 with these conventions and those of the networking environment in 668 which they operate. 670 1.2: GSS-API Features and Issues 672 This section describes aspects of GSS-API operations, of the security 673 services which the GSS-API provides, and provides commentary on 674 design issues. 676 1.2.1: Status Reporting and Optional Service Support 678 1.2.1.1: Status Reporting 680 Each GSS-API call provides two status return values. Major_status 681 values provide a mechanism-independent indication of call status 682 (e.g., GSS_S_COMPLETE, GSS_S_FAILURE, GSS_S_CONTINUE_NEEDED), 683 sufficient to drive normal control flow within the caller in a 684 generic fashion. Table 1 summarizes the defined major_status return 685 codes in tabular fashion. 687 Sequencing-related informatory major_status codes 688 (GSS_S_DUPLICATE_TOKEN, GSS_S_OLD_TOKEN, GSS_S_UNSEQ_TOKEN, and 689 GSS_S_GAP_TOKEN) can be indicated in conjunction with either 690 GSS_S_COMPLETE or GSS_S_FAILURE status for GSS-API per-message calls. 691 For context establishment calls, these sequencing-related codes will 692 be indicated only in conjunction with GSS_S_FAILURE status (never in 693 conjunction with GSS_S_COMPLETE or GSS_S_CONTINUE_NEEDED), and, 694 therefore, always correspond to fatal failures if encountered during 695 the context establishment phase. 697 Table 1: GSS-API Major Status Codes 699 FATAL ERROR CODES 701 GSS_S_BAD_BINDINGS channel binding mismatch 702 GSS_S_BAD_MECH unsupported mechanism requested 703 GSS_S_BAD_NAME invalid name provided 704 GSS_S_BAD_NAMETYPE name of unsupported type provided 705 GSS_S_BAD_STATUS invalid input status selector 706 GSS_S_BAD_SIG token had invalid integrity check 707 GSS_S_BAD_MIC preferred alias for GSS_S_BAD_SIG 708 GSS_S_CONTEXT_EXPIRED specified security context expired 709 GSS_S_CREDENTIALS_EXPIRED expired credentials detected 710 GSS_S_DEFECTIVE_CREDENTIAL defective credential detected 711 GSS_S_DEFECTIVE_TOKEN defective token detected 712 GSS_S_FAILURE failure, unspecified at GSS-API 713 level 714 GSS_S_NO_CONTEXT no valid security context specified 715 GSS_S_NO_CRED no valid credentials provided 716 GSS_S_BAD_QOP unsupported QOP value 717 GSS_S_UNAUTHORIZED operation unauthorized 718 GSS_S_UNAVAILABLE operation unavailable 719 GSS_S_DUPLICATE_ELEMENT duplicate credential element requested 720 GSS_S_NAME_NOT_MN name contains multi-mechanism elements 722 INFORMATORY STATUS CODES 724 GSS_S_COMPLETE normal completion 725 GSS_S_CONTINUE_NEEDED continuation call to routine 726 required 727 GSS_S_DUPLICATE_TOKEN duplicate per-message token 728 detected 729 GSS_S_OLD_TOKEN timed-out per-message token 730 detected 731 GSS_S_UNSEQ_TOKEN reordered (early) per-message token 732 detected 733 GSS_S_GAP_TOKEN skipped predecessor token(s) 734 detected 736 Minor_status provides more detailed status information which may 737 include status codes specific to the underlying security mechanism. 738 Minor_status values are not specified in this document. 740 GSS_S_CONTINUE_NEEDED major_status returns, and optional message 741 outputs, are provided in GSS_Init_sec_context() and 742 GSS_Accept_sec_context() calls so that different mechanisms' 743 employment of different numbers of messages within their 744 authentication sequences need not be reflected in separate code paths 745 within calling applications. Instead, such cases are accommodated 746 with sequences of continuation calls to GSS_Init_sec_context() and 747 GSS_Accept_sec_context(). The same facility is used to encapsulate 748 mutual authentication within the GSS-API's context initiation calls. 750 For mech_types which require interactions with third-party servers in 751 order to establish a security context, GSS-API context establishment 752 calls may block pending completion of such third-party interactions. 753 On the other hand, no GSS-API calls pend on serialized interactions 754 with GSS-API peer entities. As a result, local GSS-API status 755 returns cannot reflect unpredictable or asynchronous exceptions 756 occurring at remote peers, and reflection of such status information 757 is a caller responsibility outside the GSS-API. 759 1.2.1.2: Optional Service Support 761 A context initiator may request various optional services at context 762 establishment time. Each of these services is requested by setting a 763 flag in the req_flags input parameter to GSS_Init_sec_context(). 765 The optional services currently defined are: 767 - Delegation - The (usually temporary) transfer of rights from 768 initiator to acceptor, enabling the acceptor to authenticate 769 itself as an agent of the initiator. 771 - Mutual Authentication - In addition to the initiator 772 authenticating its identity to the context acceptor, the context 773 acceptor should also authenticate itself to the initiator. 775 - Replay detection - In addition to providing message integrity 776 services, GSS_GetMIC() and GSS_Wrap() should include message 777 numbering information to enable GSS_VerifyMIC() and GSS_Unwrap() 778 to detect if a message has been duplicated. 780 - Out-of-sequence detection - In addition to providing message 781 integrity services, GSS_GetMIC() and GSS_Wrap() should include 782 message sequencing information to enable GSS_VerifyMIC() and 783 GSS_Unwrap() to detect if a message has been received out of 784 sequence. 786 - Anonymous authentication - The establishment of the security 787 context should not reveal the initiator's identity to the 788 context acceptor. 790 Any currently undefined bits within such flag arguments should be 791 ignored by GSS-API implementations when presented by an application, 792 and should be set to zero when returned to the application by the 793 GSS-API implementation. 795 Some mechanisms may not support all optional services, and some 796 mechanisms may only support some services in conjunction with others. 797 Both GSS_Init_sec_context() and GSS_Accept_sec_context() inform the 798 applications which services will be available from the context when 799 the establishment phase is complete, via the ret_flags output 800 parameter. In general, if the security mechanism is capable of 801 providing a requested service, it should do so, even if additional 802 services must be enabled in order to provide the requested service. 803 If the mechanism is incapable of providing a requested service, it 804 should proceed without the service, leaving the application to abort 805 the context establishment process if it considers the requested 806 service to be mandatory. 808 Some mechanisms may specify that support for some services is 809 optional, and that implementors of the mechanism need not provide it. 810 This is most commonly true of the confidentiality service, often 811 because of legal restrictions on the use of data-encryption, but may 812 apply to any of the services. Such mechanisms are required to send 813 at least one token from acceptor to initiator during context 814 establishment when the initiator indicates a desire to use such a 815 service, so that the initiating GSS-API can correctly indicate 816 whether the service is supported by the acceptor's GSS-API. 818 1.2.2: Per-Message Security Service Availability 820 When a context is established, two flags are returned to indicate the 821 set of per-message protection security services which will be 822 available on the context: 824 the integ_avail flag indicates whether per-message integrity and 825 data origin authentication services are available 827 the conf_avail flag indicates whether per-message confidentiality 828 services are available, and will never be returned TRUE unless the 829 integ_avail flag is also returned TRUE 831 GSS-API callers desiring per-message security services should 832 check the values of these flags at context establishment time, and 833 must be aware that a returned FALSE value for integ_avail means 834 that invocation of GSS_GetMIC() or GSS_Wrap() primitives on the 835 associated context will apply no cryptographic protection to user 836 data messages. 838 The GSS-API per-message integrity and data origin authentication 839 services provide assurance to a receiving caller that protection was 840 applied to a message by the caller's peer on the security context, 841 corresponding to the entity named at context initiation. The GSS-API 842 per-message confidentiality service provides assurance to a sending 843 caller that the message's content is protected from access by 844 entities other than the context's named peer. 846 The GSS-API per-message protection service primitives, as the 847 category name implies, are oriented to operation at the granularity 848 of protocol data units. They perform cryptographic operations on the 849 data units, transfer cryptographic control information in tokens, 850 and, in the case of GSS_Wrap(), encapsulate the protected data unit. 851 As such, these primitives are not oriented to efficient data 852 protection for stream-paradigm protocols (e.g., Telnet) if 853 cryptography must be applied on an octet-by-octet basis. 855 1.2.3: Per-Message Replay Detection and Sequencing 857 Certain underlying mech_types offer support for replay detection 858 and/or sequencing of messages transferred on the contexts they 859 support. These optionally-selectable protection features are distinct 860 from replay detection and sequencing features applied to the context 861 establishment operation itself; the presence or absence of context- 862 level replay or sequencing features is wholly a function of the 863 underlying mech_type's capabilities, and is not selected or omitted 864 as a caller option. 866 The caller initiating a context provides flags (replay_det_req_flag 867 and sequence_req_flag) to specify whether the use of per-message 868 replay detection and sequencing features is desired on the context 869 being established. The GSS-API implementation at the initiator system 870 can determine whether these features are supported (and whether they 871 are optionally selectable) as a function of the selected mechanism, 872 without need for bilateral negotiation with the target. When enabled, 873 these features provide recipients with indicators as a result of 874 GSS-API processing of incoming messages, identifying whether those 875 messages were detected as duplicates or out-of-sequence. Detection of 876 such events does not prevent a suspect message from being provided to 877 a recipient; the appropriate course of action on a suspect message is 878 a matter of caller policy. 880 The semantics of the replay detection and sequencing services applied 881 to received messages, as visible across the interface which the GSS- 882 API provides to its clients, are as follows: 884 When replay_det_state is TRUE, the possible major_status returns for 885 well-formed and correctly signed messages are as follows: 887 1. GSS_S_COMPLETE, without concurrent indication of 888 GSS_S_DUPLICATE_TOKEN or GSS_S_OLD_TOKEN, indicates that the 889 message was within the window (of time or sequence space) allowing 890 replay events to be detected, and that the message was not a 891 replay of a previously-processed message within that window. 893 2. GSS_S_DUPLICATE_TOKEN indicates that the cryptographic 894 checkvalue on the received message was correct, but that the 895 message was recognized as a duplicate of a previously-processed 896 message. In addition to identifying duplicated tokens originated 897 by a context's peer, this status may also be used to identify 898 reflected copies of locally-generated tokens; it is recommended 899 that mechanism designers include within their protocols facilities 900 to detect and report such tokens. 902 3. GSS_S_OLD_TOKEN indicates that the cryptographic checkvalue on 903 the received message was correct, but that the message is too old 904 to be checked for duplication. 906 When sequence_state is TRUE, the possible major_status returns for 907 well-formed and correctly signed messages are as follows: 909 1. GSS_S_COMPLETE, without concurrent indication of 910 GSS_S_DUPLICATE_TOKEN, GSS_S_OLD_TOKEN, GSS_S_UNSEQ_TOKEN, or 911 GSS_S_GAP_TOKEN, indicates that the message was within the window 912 (of time or sequence space) allowing replay events to be detected, 913 that the message was not a replay of a previously-processed 914 message within that window, and that no predecessor sequenced 915 messages are missing relative to the last received message (if 916 any) processed on the context with a correct cryptographic 917 checkvalue. 919 2. GSS_S_DUPLICATE_TOKEN indicates that the integrity check value 920 on the received message was correct, but that the message was 921 recognized as a duplicate of a previously-processed message. In 922 addition to identifying duplicated tokens originated by a 923 context's peer, this status may also be used to identify reflected 924 copies of locally-generated tokens; it is recommended that 925 mechanism designers include within their protocols facilities to 926 detect and report such tokens. 928 3. GSS_S_OLD_TOKEN indicates that the integrity check value on the 929 received message was correct, but that the token is too old to be 930 checked for duplication. 932 4. GSS_S_UNSEQ_TOKEN indicates that the cryptographic checkvalue 933 on the received message was correct, but that it is earlier in a 934 sequenced stream than a message already processed on the context. 935 [Note: Mechanisms can be architected to provide a stricter form of 936 sequencing service, delivering particular messages to recipients 937 only after all predecessor messages in an ordered stream have been 938 delivered. This type of support is incompatible with the GSS-API 939 paradigm in which recipients receive all messages, whether in 940 order or not, and provide them (one at a time, without intra-GSS- 941 API message buffering) to GSS-API routines for validation. GSS- 942 API facilities provide supportive functions, aiding clients to 943 achieve strict message stream integrity in an efficient manner in 944 conjunction with sequencing provisions in communications 945 protocols, but the GSS-API does not offer this level of message 946 stream integrity service by itself.] 948 5. GSS_S_GAP_TOKEN indicates that the cryptographic checkvalue on 949 the received message was correct, but that one or more predecessor 950 sequenced messages have not been successfully processed relative 951 to the last received message (if any) processed on the context 952 with a correct cryptographic checkvalue. 954 As the message stream integrity features (especially sequencing) may 955 interfere with certain applications' intended communications 956 paradigms, and since support for such features is likely to be 957 resource intensive, it is highly recommended that mech_types 958 supporting these features allow them to be activated selectively on 959 initiator request when a context is established. A context initiator 960 and target are provided with corresponding indicators 961 (replay_det_state and sequence_state), signifying whether these 962 features are active on a given context. 964 An example mech_type supporting per-message replay detection could 965 (when replay_det_state is TRUE) implement the feature as follows: The 966 underlying mechanism would insert timestamps in data elements output 967 by GSS_GetMIC() and GSS_Wrap(), and would maintain (within a time- 968 limited window) a cache (qualified by originator-recipient pair) 969 identifying received data elements processed by GSS_VerifyMIC() and 970 GSS_Unwrap(). When this feature is active, exception status returns 971 (GSS_S_DUPLICATE_TOKEN, GSS_S_OLD_TOKEN) will be provided when 972 GSS_VerifyMIC() or GSS_Unwrap() is presented with a message which is 973 either a detected duplicate of a prior message or which is too old to 974 validate against a cache of recently received messages. 976 1.2.4: Quality of Protection 978 Some mech_types provide their users with fine granularity control 979 over the means used to provide per-message protection, allowing 980 callers to trade off security processing overhead dynamically against 981 the protection requirements of particular messages. A per-message 982 quality-of-protection parameter (analogous to quality-of-service, or 983 QOS) selects among different QOP options supported by that mechanism. 984 On context establishment for a multi-QOP mech_type, context-level 985 data provides the prerequisite data for a range of protection 986 qualities. 988 It is expected that the majority of callers will not wish to exert 989 explicit mechanism-specific QOP control and will therefore request 990 selection of a default QOP. Definitions of, and choices among, non- 991 default QOP values are mechanism-specific, and no ordered sequences 992 of QOP values can be assumed equivalent across different mechanisms. 993 Meaningful use of non-default QOP values demands that callers be 994 familiar with the QOP definitions of an underlying mechanism or 995 mechanisms, and is therefore a non-portable construct. The 996 GSS_S_BAD_QOP major_status value is defined in order to indicate that 997 a provided QOP value is unsupported for a security context, most 998 likely because that value is unrecognized by the underlying 999 mechanism. 1001 In the interests of interoperability, mechanisms which allow optional 1002 support of particular QOP values shall satisfy one of the following 1003 conditions. Either: 1005 (i) All implementations of the mechanism are required to be 1006 capable of processing messages protected using any QOP value, 1007 regardless of whether they can apply protection corresponding to 1008 that QOP, or 1010 (ii) The set of mutually-supported receiver QOP values must be 1011 determined during context establishment, and messages may be 1012 protected by either peer using only QOP values from this 1013 mutually-supported set. 1015 NOTE: (i) is just a special-case of (ii), where implementations are 1016 required to support all QOP values on receipt. 1018 1.2.5: Anonymity Support 1020 In certain situations or environments, an application may wish to 1021 authenticate a peer and/or protect communications using GSS-API per- 1022 message services without revealing its own identity. For example, 1023 consider an application which provides read access to a research 1024 database, and which permits queries by arbitrary requestors. A 1025 client of such a service might wish to authenticate the service, to 1026 establish trust in the information received from it, but might not 1027 wish to disclose its identity to the service for privacy reasons. 1029 In ordinary GSS-API usage, a context initiator's identity is made 1030 available to the context acceptor as part of the context 1031 establishment process. To provide for anonymity support, a facility 1032 (input anon_req_flag to GSS_Init_sec_context()) is provided through 1033 which context initiators may request that their identity not be 1034 provided to the context acceptor. Mechanisms are not required to 1035 honor this request, but a caller will be informed (via returned 1036 anon_state indicator from GSS_Init_sec_context()) whether or not the 1037 request is honored. Note that authentication as the anonymous 1038 principal does not necessarily imply that credentials are not 1039 required in order to establish a context. 1041 Section 4.5 of this document defines the Object Identifier value used 1042 to identify an anonymous principal. 1044 Four possible combinations of anon_state and mutual_state are 1045 possible, with the following results: 1047 anon_state == FALSE, mutual_state == FALSE: initiator 1048 authenticated to target. 1050 anon_state == FALSE, mutual_state == TRUE: initiator authenticated 1051 to target, target authenticated to initiator. 1053 anon_state == TRUE, mutual_state == FALSE: initiator authenticated 1054 as anonymous principal to target. 1056 anon_state == TRUE, mutual_state == TRUE: initiator authenticated 1057 as anonymous principal to target, target authenticated to 1058 initiator. 1060 1.2.6: Initialization 1062 No initialization calls (i.e., calls which must be invoked prior to 1063 invocation of other facilities in the interface) are defined in GSS- 1064 API. As an implication of this fact, GSS-API implementations must 1065 themselves be self-initializing. 1067 1.2.7: Per-Message Protection During Context Establishment 1069 A facility is defined in GSS-V2 to enable protection and buffering of 1070 data messages for later transfer while a security context's 1071 establishment is in GSS_S_CONTINUE_NEEDED status, to be used in cases 1072 where the caller side already possesses the necessary session key to 1073 enable this processing. Specifically, a new state Boolean, called 1074 prot_ready_state, is added to the set of information returned by 1075 GSS_Init_sec_context(), GSS_Accept_sec_context(), and 1076 GSS_Inquire_context(). 1078 For context establishment calls, this state Boolean is valid and 1079 interpretable when the associated major_status is either 1080 GSS_S_CONTINUE_NEEDED, or GSS_S_COMPLETE. Callers of GSS-API (both 1081 initiators and acceptors) can assume that per-message protection (via 1082 GSS_Wrap(), GSS_Unwrap(), GSS_GetMIC() and GSS_VerifyMIC()) is 1083 available and ready for use if either: prot_ready_state == TRUE, or 1084 major_status == GSS_S_COMPLETE, though mutual authentication (if 1085 requested) cannot be guaranteed until GSS_S_COMPLETE is returned. 1087 callers, who need not even know of the existence of prot_ready_state, 1088 and who will get the expected behavior from GSS_S_COMPLETE, but who 1089 will not be able to use per-message protection before GSS_S_COMPLETE 1090 is returned. 1092 prot_ready_state before completion of context establishment (indeed, 1093 some mechanisms will not evolve usable message protection keys, 1094 especially at the context acceptor, before context establishment is 1095 complete). It is expected but not required that GSS-V2 mechanisms 1096 will return TRUE prot_ready_state upon completion of context 1097 establishment if they support per-message protection at all (however 1098 GSS-V2 applications should not assume that TRUE prot_ready_state will 1099 always be returned together with the GSS_S_COMPLETE major_status, 1100 since GSS-V2 implementations may continue to support GSS-V1 mechanism 1101 code, which will never return TRUE prot_ready_state). 1103 When prot_ready_state is returned TRUE, mechanisms shall also set 1104 those context service indicator flags (deleg_state, mutual_state, 1105 replay_det_state, sequence_state, anon_state, trans_state, 1106 conf_avail, integ_avail) which represent facilities confirmed, at 1107 that time, to be available on the context being established. In 1108 situations where prot_ready_state is returned before GSS_S_COMPLETE, 1109 it is possible that additional facilities may be confirmed and 1110 subsequently indicated when GSS_S_COMPLETE is returned. 1112 1.2.8: Implementation Robustness 1114 This section recommends aspects of GSS-API implementation behavior in 1115 the interests of overall robustness. 1117 Invocation of GSS-API calls is to incur no undocumented side effects 1118 visible at the GSS-API level. 1120 If a token is presented for processing on a GSS-API security context 1121 and that token generates a fatal error in processing or is otherwise 1122 determined to be invalid for that context, the context's state should 1123 not be disrupted for purposes of processing subsequent valid tokens. 1125 Certain local conditions at a GSS-API implementation (e.g., 1126 unavailability of memory) may preclude, temporarily or permanently, 1127 the successful processing of tokens on a GSS-API security context, 1128 typically generating GSS_S_FAILURE major_status returns along with 1129 locally-significant minor_status. For robust operation under such 1130 conditions, the following recommendations are made: 1132 Failing calls should free any memory they allocate, so that callers 1133 may retry without causing further loss of resources. 1135 Failure of an individual call on an established context should not 1136 preclude subsequent calls from succeeding on the same context. 1138 Whenever possible, it should be possible for 1139 GSS_Delete_sec_context() calls to be successfully processed even if 1140 other calls cannot succeed, thereby enabling context-related 1141 resources to be released. 1143 A failure of GSS_GetMIC() or GSS_Wrap() due to an attempt to use an 1144 unsupported QOP will not interfere with context validity, nor shall 1145 such a failure impact the ability of the application to subsequently 1146 invoke GSS_GetMIC() or GSS_Wrap() using a supported QOP. Any state 1147 information concerning sequencing of outgoing messages shall be 1148 unchanged by an unsuccesful call of GSS_GetMIC() or GSS_Wrap(). 1150 1.2.9: Delegation 1152 The GSS-API allows delegation to be controlled by the initiating 1153 application via a Boolean parameter to GSS_Init_sec_context(), the 1154 routine that establishes a security context. Some mechanisms do not 1155 support delegation, and for such mechanisms attempts by an 1156 application to enable delegation are ignored. 1158 The acceptor of a security context for which the initiator enabled 1159 delegation will receive (via the delegated_cred_handle parameter of 1160 GSS_Accept_sec_context()) a credential handle that contains the 1161 delegated identity, and this credential handle may be used to 1162 initiate subsequent GSS-API security contexts as an agent or delegate 1163 of the initiator. If the original initiator's identity is "A" and 1164 the delegate's identity is "B", then, depending on the underlying 1165 mechanism, the identity embodied by the delegated credential may be 1166 either "A" or "B acting for A". 1168 For many mechanisms that support delegation, a simple Boolean does 1169 not provide enough control. Examples of additional aspects of 1170 delegation control that a mechanism might provide to an application 1171 are duration of delegation, network addresses from which delegation 1172 is valid, and constraints on the tasks that may be performed by a 1173 delegate. Such controls are presently outside the scope of the GSS- 1174 API. GSS-API implementations supporting mechanisms offering 1175 additional controls should provide extension routines that allow 1176 these controls to be exercised (perhaps by modifying the initiator's 1177 GSS-API credential prior to its use in establishing a context). 1178 However, the simple delegation control provided by GSS-API should 1179 always be able to over-ride other mechanism-specific delegation 1180 controls; if the application instructs GSS_Init_sec_context() that 1181 delegation is not desired, then the implementation must not permit 1182 delegation to occur. This is an exception to the general rule that a 1183 mechanism may enable services even if they are not requested; 1184 delegation may only be provided at the explicit request of the 1185 application. 1187 1.2.10: Interprocess Context Transfer 1189 GSS-API V2 provides routines (GSS_Export_sec_context() and 1190 GSS_Import_sec_context()) which allow a security context to be 1191 transferred between processes on a single machine. The most common 1192 use for such a feature is a client-server design where the server is 1193 implemented as a single process that accepts incoming security 1194 contexts, which then launches child processes to deal with the data 1195 on these contexts. In such a design, the child processes must have 1196 access to the security context data structure created within the 1197 parent by its call to GSS_Accept_sec_context() so that they can use 1198 per-message protection services and delete the security context when 1199 the communication session ends. 1201 Since the security context data structure is expected to contain 1202 sequencing information, it is impractical in general to share a 1203 context between processes. Thus GSS-API provides a call 1204 (GSS_Export_sec_context()) that the process which currently owns the 1205 context can call to declare that it has no intention to use the 1206 context subsequently, and to create an inter-process token containing 1207 information needed by the adopting process to successfully import the 1208 context. After successful completion of this call, the original 1209 security context is made inaccessible to the calling process by GSS- 1210 API, and any context handles referring to this context are no longer 1211 valid. The originating process transfers the inter-process token to 1212 the adopting process, which passes it to GSS_Import_sec_context(), 1213 and a fresh context handle is created such that it is functionally 1214 identical to the original context. 1216 The inter-process token may contain sensitive data from the original 1217 security context (including cryptographic keys). Applications using 1218 inter-process tokens to transfer security contexts must take 1219 appropriate steps to protect these tokens in transit. 1220 Implementations are not required to support the inter-process 1221 transfer of security contexts. The ability to transfer a security 1222 context is indicated when the context is created, by 1223 GSS_Init_sec_context() or GSS_Accept_sec_context() indicating a TRUE 1224 trans_state return value. 1226 2: Interface Descriptions 1228 This section describes the GSS-API's service interface, dividing the 1229 set of calls offered into four groups. Credential management calls 1230 are related to the acquisition and release of credentials by 1231 principals. Context-level calls are related to the management of 1232 security contexts between principals. Per-message calls are related 1233 to the protection of individual messages on established security 1234 contexts. Support calls provide ancillary functions useful to GSS-API 1235 callers. Table 2 groups and summarizes the calls in tabular fashion. 1237 Table 2: GSS-API Calls 1239 CREDENTIAL MANAGEMENT 1241 GSS_Acquire_cred acquire credentials for use 1242 GSS_Release_cred release credentials after use 1243 GSS_Inquire_cred display information about 1244 credentials 1245 GSS_Add_cred construct credentials incrementally 1246 GSS_Inquire_cred_by_mech display per-mechanism credential 1247 information 1249 CONTEXT-LEVEL CALLS 1251 GSS_Init_sec_context initiate outbound security context 1252 GSS_Accept_sec_context accept inbound security context 1253 GSS_Delete_sec_context flush context when no longer needed 1254 GSS_Process_context_token process received control token on 1255 context 1256 GSS_Context_time indicate validity time remaining on 1257 context 1258 GSS_Inquire_context display information about context 1259 GSS_Wrap_size_limit determine GSS_Wrap token size limit 1260 GSS_Export_sec_context transfer context to other process 1261 GSS_Import_sec_context import transferred context 1263 PER-MESSAGE CALLS 1265 GSS_GetMIC apply integrity check, receive as 1266 token separate from message 1267 GSS_VerifyMIC validate integrity check token 1268 along with message 1269 GSS_Wrap sign, optionally encrypt, 1270 encapsulate 1271 GSS_Unwrap decapsulate, decrypt if needed, 1272 validate integrity check 1274 SUPPORT CALLS 1276 GSS_Display_status translate status codes to printable 1277 form 1278 GSS_Indicate_mechs indicate mech_types supported on 1279 local system 1280 GSS_Compare_name compare two names for equality 1281 GSS_Display_name translate name to printable form 1282 GSS_Import_name convert printable name to 1283 normalized form 1284 GSS_Release_name free storage of normalized-form 1285 name 1286 GSS_Release_buffer free storage of general GSS-allocated 1287 object 1288 GSS_Release_OID_set free storage of OID set object 1289 GSS_Create_empty_OID_set create empty OID set 1290 GSS_Add_OID_set_member add member to OID set 1291 GSS_Test_OID_set_member test if OID is member of OID set 1292 GSS_Inquire_names_for_mech indicate name types supported by 1293 mechanism 1294 GSS_Inquire_mechs_for_name indicates mechanisms supporting name 1295 type 1296 GSS_Canonicalize_name translate name to per-mechanism form 1297 GSS_Export_name externalize per-mechanism name 1298 GSS_Duplicate_name duplicate name object 1300 2.1: Credential management calls 1302 These GSS-API calls provide functions related to the management of 1303 credentials. Their characterization with regard to whether or not 1304 they may block pending exchanges with other network entities (e.g., 1305 directories or authentication servers) depends in part on OS-specific 1306 (extra-GSS-API) issues, so is not specified in this document. 1308 The GSS_Acquire_cred() call is defined within the GSS-API in support 1309 of application portability, with a particular orientation towards 1310 support of portable server applications. It is recognized that (for 1311 certain systems and mechanisms) credentials for interactive users may 1312 be managed differently from credentials for server processes; in such 1313 environments, it is the GSS-API implementation's responsibility to 1314 distinguish these cases and the procedures for making this 1315 distinction are a local matter. The GSS_Release_cred() call provides 1316 a means for callers to indicate to the GSS-API that use of a 1317 credentials structure is no longer required. The GSS_Inquire_cred() 1318 call allows callers to determine information about a credentials 1319 structure. The GSS_Add_cred() call enables callers to append 1320 elements to an existing credential structure, allowing iterative 1321 construction of a multi-mechanism credential. The 1322 GSS_Inquire_cred_by_mech() call enables callers to extract per- 1323 mechanism information describing a credentials structure. 1325 2.1.1: GSS_Acquire_cred call 1327 Inputs: 1329 o desired_name INTERNAL NAME, -- NULL requests locally-determined 1330 -- default 1332 o lifetime_req INTEGER, -- in seconds; 0 requests default 1334 o desired_mechs SET OF OBJECT IDENTIFIER, -- empty set requests 1335 -- system-selected default 1337 o cred_usage INTEGER -- 0=INITIATE-AND-ACCEPT, 1=INITIATE-ONLY, 1338 -- 2=ACCEPT-ONLY 1340 Outputs: 1342 o major_status INTEGER, 1344 o minor_status INTEGER, 1346 o output_cred_handle CREDENTIAL HANDLE, -- if returned non-NULL, 1347 -- caller must release with GSS_Release_cred() 1349 o actual_mechs SET OF OBJECT IDENTIFIER, -- if returned non-NULL, 1350 -- caller must release with GSS_Release_oid_set() 1352 o lifetime_rec INTEGER -- in seconds, or reserved value for 1353 -- INDEFINITE 1355 Return major_status codes: 1357 o GSS_S_COMPLETE indicates that requested credentials were 1358 successfully established, for the duration indicated in 1359 lifetime_rec, suitable for the usage requested in cred_usage, 1360 for the set of mech_types indicated in actual_mechs, and that 1361 those credentials can be referenced for subsequent use with 1362 the handle returned in output_cred_handle. 1364 o GSS_S_BAD_MECH indicates that a mech_type unsupported by the 1365 GSS-API implementation type was requested, causing the 1366 credential establishment operation to fail. 1368 o GSS_S_BAD_NAMETYPE indicates that the provided desired_name is 1369 uninterpretable or of a type unsupported by the applicable 1370 underlying GSS-API mechanism(s), so no credentials could be 1371 established for the accompanying desired_name. 1373 o GSS_S_BAD_NAME indicates that the provided desired_name is 1374 inconsistent in terms of internally-incorporated type specifier 1375 information, so no credentials could be established for the 1376 accompanying desired_name. 1378 o GSS_S_CREDENTIALS_EXPIRED indicates that underlying credential 1379 elements corresponding to the requested desired_name have 1380 expired, so requested credentials could not be established. 1382 o GSS_S_NO_CRED indicates that no credential elements corresponding 1383 to the requested desired_name and usage could be accessed, so 1384 requested credentials could not be established. In particular, 1385 this status should be returned upon temporary user-fixable 1386 conditions preventing successful credential establishment and 1387 upon lack of authorization to establish and use credentials 1388 associated with the identity named in the input desired_name 1389 argument. 1391 o GSS_S_FAILURE indicates that credential establishment failed 1392 for reasons unspecified at the GSS-API level. 1394 GSS_Acquire_cred() is used to acquire credentials so that a principal 1395 can (as a function of the input cred_usage parameter) initiate and/or 1396 accept security contexts under the identity represented by the 1397 desired_name input argument. On successful completion, the returned 1398 output_cred_handle result provides a handle for subsequent references 1399 to the acquired credentials. Typically, single-user client processes 1400 requesting that default credential behavior be applied for context 1401 establishment purposes will have no need to invoke this call. 1403 A caller may provide the value NULL (GSS_C_NO_NAME) for desired_name, 1404 which will be interpreted as a request for a credential handle that 1405 will invoke default behavior when passed to GSS_Init_sec_context(), 1406 if cred_usage is GSS_C_INITIATE or GSS_C_BOTH, or 1407 GSS_Accept_sec_context(), if cred_usage is GSS_C_ACCEPT or 1408 GSS_C_BOTH. It is possible that multiple pre-established credentials 1409 may exist for the same principal identity (for example, as a result 1410 of multiple user login sessions) when GSS_Acquire_cred() is called; 1411 the means used in such cases to select a specific credential are 1412 local matters. The input lifetime_req argument to GSS_Acquire_cred() 1413 may provide useful information for local GSS-API implementations to 1414 employ in making this disambiguation in a manner which will best 1415 satisfy a caller's intent. 1417 This routine is expected to be used primarily by context acceptors, 1418 since implementations are likely to provide mechanism-specific ways 1419 of obtaining GSS-API initiator credentials from the system login 1420 process. Some implementations may therefore not support the 1421 acquisition of GSS_C_INITIATE or GSS_C_BOTH credentials via 1422 GSS_Acquire_cred() for any name other than GSS_C_NO_NAME, or a name 1423 resulting from applying GSS_Inquire_context() to an active context, 1424 or a name resulting from applying GSS_Inquire_cred() against a 1425 credential handle corresponding to default behavior. It is important 1426 to recognize that the explicit name which is yielded by resolving a 1427 default reference may change over time, e.g., as a result of local 1428 credential element management operations outside GSS-API; once 1429 resolved, however, the value of such an explicit name will remain 1430 constant. 1432 The lifetime_rec result indicates the length of time for which the 1433 acquired credentials will be valid, as an offset from the present. A 1434 mechanism may return a reserved value indicating INDEFINITE if no 1435 constraints on credential lifetime are imposed. A caller of 1436 GSS_Acquire_cred() can request a length of time for which acquired 1437 credentials are to be valid (lifetime_req argument), beginning at the 1438 present, or can request credentials with a default validity interval. 1439 (Requests for postdated credentials are not supported within the 1440 GSS-API.) Certain mechanisms and implementations may bind in 1441 credential validity period specifiers at a point preliminary to 1442 invocation of the GSS_Acquire_cred() call (e.g., in conjunction with 1443 user login procedures). As a result, callers requesting non-default 1444 values for lifetime_req must recognize that such requests cannot 1445 always be honored and must be prepared to accommodate the use of 1446 returned credentials with different lifetimes as indicated in 1447 lifetime_rec. 1449 The caller of GSS_Acquire_cred() can explicitly specify a set of 1450 mech_types which are to be accommodated in the returned credentials 1451 (desired_mechs argument), or can request credentials for a system- 1452 defined default set of mech_types. Selection of the system-specified 1453 default set is recommended in the interests of application 1454 portability. The actual_mechs return value may be interrogated by the 1455 caller to determine the set of mechanisms with which the returned 1456 credentials may be used. 1458 2.1.2: GSS_Release_cred call 1460 Input: 1462 o cred_handle CREDENTIAL HANDLE -- if GSS_C_NO_CREDENTIAL 1463 -- is specified, the call will complete successfully, but 1464 -- will have no effect; no credential elements will be 1465 -- released. 1467 Outputs: 1469 o major_status INTEGER, 1471 o minor_status INTEGER 1473 Return major_status codes: 1475 o GSS_S_COMPLETE indicates that the credentials referenced by the 1476 input cred_handle were released for purposes of subsequent 1477 access by the caller. The effect on other processes which may 1478 be authorized shared access to such credentials is a local 1479 matter. 1481 o GSS_S_NO_CRED indicates that no release operation was 1482 performed, either because the input cred_handle was invalid or 1483 because the caller lacks authorization to access the 1484 referenced credentials. 1486 o GSS_S_FAILURE indicates that the release operation failed for 1487 reasons unspecified at the GSS-API level. 1489 Provides a means for a caller to explicitly request that credentials 1490 be released when their use is no longer required. Note that system- 1491 specific credential management functions are also likely to exist, 1492 for example to assure that credentials shared among processes are 1493 properly deleted when all affected processes terminate, even if no 1494 explicit release requests are issued by those processes. Given the 1495 fact that multiple callers are not precluded from gaining authorized 1496 access to the same credentials, invocation of GSS_Release_cred() 1497 cannot be assumed to delete a particular set of credentials on a 1498 system-wide basis. 1500 2.1.3: GSS_Inquire_cred call 1502 Input: 1504 o cred_handle CREDENTIAL HANDLE -- if GSS_C_NO_CREDENTIAL 1505 -- specified, default initiator credentials are queried 1507 Outputs: 1509 o major_status INTEGER, 1510 o minor_status INTEGER, 1512 o cred_name INTERNAL NAME, -- caller must release with 1513 -- GSS_Release_name() 1515 o lifetime_rec INTEGER -- in seconds, or reserved value for 1516 -- INDEFINITE 1518 o cred_usage INTEGER, -- 0=INITIATE-AND-ACCEPT, 1=INITIATE-ONLY, 1519 -- 2=ACCEPT-ONLY 1521 o mech_set SET OF OBJECT IDENTIFIER -- caller must release 1522 -- with GSS_Release_oid_set() 1524 Return major_status codes: 1526 o GSS_S_COMPLETE indicates that the credentials referenced by the 1527 input cred_handle argument were valid, and that the output 1528 cred_name, lifetime_rec, and cred_usage values represent, 1529 respectively, the credentials' associated principal name, 1530 remaining lifetime, suitable usage modes, and supported 1531 mechanism types. 1533 o GSS_S_NO_CRED indicates that no information could be returned 1534 about the referenced credentials, either because the input 1535 cred_handle was invalid or because the caller lacks 1536 authorization to access the referenced credentials. 1538 o GSS_S_DEFECTIVE_CREDENTIAL indicates that the referenced 1539 credentials are invalid. 1541 o GSS_S_CREDENTIALS_EXPIRED indicates that the referenced 1542 credentials have expired. 1544 o GSS_S_FAILURE indicates that the operation failed for 1545 reasons unspecified at the GSS-API level. 1547 The GSS_Inquire_cred() call is defined primarily for the use of those 1548 callers which request use of default credential behavior rather than 1549 acquiring credentials explicitly with GSS_Acquire_cred(). It enables 1550 callers to determine a credential structure's associated principal 1551 name, remaining validity period, usability for security context 1552 initiation and/or acceptance, and supported mechanisms. 1554 For a multi-mechanism credential, the returned "lifetime" specifier 1555 indicates the shortest lifetime of any of the mechanisms' elements in 1556 the credential (for either context initiation or acceptance 1557 purposes). 1559 GSS_Inquire_cred() should indicate INITIATE-AND-ACCEPT for 1560 "cred_usage" if both of the following conditions hold: 1562 (1) there exists in the credential an element which allows 1563 context initiation using some mechanism 1565 (2) there exists in the credential an element which allows 1566 context acceptance using some mechanism (allowably, but not 1567 necessarily, one of the same mechanism(s) qualifying for (1)). 1569 If condition (1) holds but not condition (2), GSS_Inquire_cred() 1570 should indicate INITIATE-ONLY for "cred_usage". If condition (2) 1571 holds but not condition (1), GSS_Inquire_cred() should indicate 1572 ACCEPT-ONLY for "cred_usage". 1574 Callers requiring finer disambiguation among available combinations 1575 of lifetimes, usage modes, and mechanisms should call the 1576 GSS_Inquire_cred_by_mech() routine, passing that routine one of the 1577 mech OIDs returned by GSS_Inquire_cred(). 1579 2.1.4: GSS_Add_cred call 1581 Inputs: 1583 o input_cred_handle CREDENTIAL HANDLE -- handle to credential 1584 -- structure created with prior GSS_Acquire_cred() or 1585 -- GSS_Add_cred() call; see text for definition of behavior 1586 -- when GSS_C_NO_CREDENTIAL provided. 1588 o desired_name INTERNAL NAME 1590 o initiator_time_req INTEGER -- in seconds; 0 requests default 1592 o acceptor_time_req INTEGER -- in seconds; 0 requests default 1594 o desired_mech OBJECT IDENTIFIER 1596 o cred_usage INTEGER -- 0=INITIATE-AND-ACCEPT, 1=INITIATE-ONLY, 1597 -- 2=ACCEPT-ONLY 1599 Outputs: 1601 o major_status INTEGER, 1603 o minor_status INTEGER, 1605 o output_cred_handle CREDENTIAL HANDLE, -- NULL to request that 1606 -- credential elements be added "in place" to the credential 1607 -- structure identified by input_cred_handle, 1608 -- non-NULL pointer to request that 1609 -- a new credential structure and handle be created. 1610 -- if credential handle returned, caller must release with 1611 -- GSS_Release_cred() 1613 o actual_mechs SET OF OBJECT IDENTIFIER, -- if returned, caller must 1614 -- release with GSS_Release_oid_set() 1616 o initiator_time_rec INTEGER -- in seconds, or reserved value for 1617 -- INDEFINITE 1619 o acceptor_time_rec INTEGER -- in seconds, or reserved value for 1620 -- INDEFINITE 1622 o cred_usage INTEGER, -- 0=INITIATE-AND-ACCEPT, 1=INITIATE-ONLY, 1623 -- 2=ACCEPT-ONLY 1625 o mech_set SET OF OBJECT IDENTIFIER -- full set of mechanisms 1626 -- supported by resulting credential. 1628 Return major_status codes: 1630 o GSS_S_COMPLETE indicates that the credentials referenced by 1631 the input_cred_handle argument were valid, and that the 1632 resulting credential from GSS_Add_cred() is valid for the 1633 durations indicated in initiator_time_rec and acceptor_time_rec, 1634 suitable for the usage requested in cred_usage, and for the 1635 mechanisms indicated in actual_mechs. 1637 o GSS_S_DUPLICATE_ELEMENT indicates that the input desired_mech 1638 specified a mechanism for which the referenced credential 1639 already contained a credential element with overlapping cred_usage 1640 and validity time specifiers. 1642 o GSS_S_BAD_MECH indicates that the input desired_mech specified 1643 a mechanism unsupported by the GSS-API implementation, causing 1644 the GSS_Add_cred() operation to fail. 1646 o GSS_S_BAD_NAMETYPE indicates that the provided desired_name 1647 is uninterpretable or of a type unsupported by the applicable 1648 underlying GSS-API mechanism(s), so the GSS_Add_cred() operation 1649 could not be performed for that name. 1651 o GSS_S_BAD_NAME indicates that the provided desired_name is 1652 inconsistent in terms of internally-incorporated type specifier 1653 information, so the GSS_Add_cred() operation could not be 1654 performed for that name. 1656 o GSS_S_NO_CRED indicates that the input_cred_handle referenced 1657 invalid or inaccessible credentials. In particular, 1658 this status should be returned upon temporary user-fixable 1659 conditions preventing successful credential establishment or 1660 upon lack of authorization to establish or use credentials 1661 representing the requested identity. 1663 o GSS_S_CREDENTIALS_EXPIRED indicates that referenced credential 1664 elements have expired, so the GSS_Add_cred() operation could 1665 not be performed. 1667 o GSS_S_FAILURE indicates that the operation failed for 1668 reasons unspecified at the GSS-API level. 1670 GSS_Add_cred() enables callers to construct credentials iteratively 1671 by adding credential elements in successive operations, corresponding 1672 to different mechanisms. This offers particular value in multi- 1673 mechanism environments, as the major_status and minor_status values 1674 returned on each iteration are individually visible and can therefore 1675 be interpreted unambiguously on a per-mechanism basis. A credential 1676 element is identified by the name of the principal to which it 1677 refers. GSS-API implementations must impose a local access control 1678 policy on callers of this routine to prevent unauthorized callers 1679 from acquiring credential elements to which they are not entitled. 1680 This routine is not intended to provide a ``login to the network'' 1681 function, as such a function would involve the creation of new 1682 mechanism-specific authentication data, rather than merely acquiring 1683 a GSS-API handle to existing data. Such functions, if required, 1684 should be defined in implementation-specific extension routines. 1686 If credential acquisition is time-consuming for a mechanism, the 1687 mechanism may choose to delay the actual acquisition until the 1688 credential is required (e.g. by GSS_Init_sec_context() or 1689 GSS_Accept_sec_context()). Such mechanism-specific implementation 1690 decisions should be invisible to the calling application; thus a call 1691 of GSS_Inquire_cred() immediately following the call of 1692 GSS_Acquire_cred() must return valid credential data, and may 1693 therefore incur the overhead of a deferred credential acquisition. 1695 If GSS_C_NO_CREDENTIAL is specified as input_cred_handle, a non-NULL 1696 output_cred_handle must be supplied. For the case of 1697 GSS_C_NO_CREDENTIAL as input_cred_handle, GSS_Add_cred() will create 1698 the credential referenced by its output_cred_handle based on default 1699 behavior. That is, the call will have the same effect as if the 1700 caller had previously called GSS_Acquire_cred(), specifying the same 1701 usage and passing GSS_C_NO_NAME as the desired_name parameter 1702 (thereby obtaining an explicit credential handle corresponding to 1703 default behavior), had passed that credential handle to 1704 GSS_Add_cred(), and had finally called GSS_Release_cred() on the 1705 credential handle received from GSS_Acquire_cred(). 1707 This routine is expected to be used primarily by context acceptors, 1708 since implementations are likely to provide mechanism-specific ways 1709 of obtaining GSS-API initiator credentials from the system login 1710 process. Some implementations may therefore not support the 1711 acquisition of GSS_C_INITIATE or GSS_C_BOTH credentials via 1712 GSS_Acquire_cred() for any name other than GSS_C_NO_NAME, or a name 1713 resulting from applying GSS_Inquire_context() to an active context, 1714 or a name resulting from applying GSS_Inquire_cred() against a 1715 credential handle corresponding to default behavior. It is important 1716 to recognize that the explicit name which is yielded by resolving a 1717 default reference may change over time, e.g., as a result of local 1718 credential element management operations outside GSS-API; once 1719 resolved, however, the value of such an explicit name will remain 1720 constant. 1722 A caller may provide the value NULL (GSS_C_NO_NAME) for desired_name, 1723 which will be interpreted as a request for a credential handle that 1724 will invoke default behavior when passed to GSS_Init_sec_context(), 1725 if cred_usage is GSS_C_INITIATE or GSS_C_BOTH, or 1726 GSS_Accept_sec_context(), if cred_usage is GSS_C_ACCEPT or 1727 GSS_C_BOTH. 1729 The same input desired_name, or default reference, should be used on 1730 all GSS_Acquire_cred() and GSS_Add_cred() calls corresponding to a 1731 particular credential. 1733 2.1.5: GSS_Inquire_cred_by_mech call 1735 Inputs: 1737 o cred_handle CREDENTIAL HANDLE -- if GSS_C_NO_CREDENTIAL 1738 -- specified, default initiator credentials are queried 1740 o mech_type OBJECT IDENTIFIER -- specific mechanism for 1741 -- which credentials are being queried 1743 Outputs: 1745 o major_status INTEGER, 1747 o minor_status INTEGER, 1749 o cred_name INTERNAL NAME, -- guaranteed to be MN; caller must 1750 -- release with GSS_Release_name() 1751 o lifetime_rec_initiate INTEGER -- in seconds, or reserved value for 1752 -- INDEFINITE 1754 o lifetime_rec_accept INTEGER -- in seconds, or reserved value for 1755 -- INDEFINITE 1757 o cred_usage INTEGER, -- 0=INITIATE-AND-ACCEPT, 1=INITIATE-ONLY, 1758 -- 2=ACCEPT-ONLY 1760 Return major_status codes: 1762 o GSS_S_COMPLETE indicates that the credentials referenced by the 1763 input cred_handle argument were valid, that the mechanism 1764 indicated by the input mech_type was represented with elements 1765 within those credentials, and that the output cred_name, 1766 lifetime_rec_initiate, lifetime_rec_accept, and cred_usage values 1767 represent, respectively, the credentials' associated principal 1768 name, remaining lifetimes, and suitable usage modes. 1770 o GSS_S_NO_CRED indicates that no information could be returned 1771 about the referenced credentials, either because the input 1772 cred_handle was invalid or because the caller lacks 1773 authorization to access the referenced credentials. 1775 o GSS_S_DEFECTIVE_CREDENTIAL indicates that the referenced 1776 credentials are invalid. 1778 o GSS_S_CREDENTIALS_EXPIRED indicates that the referenced 1779 credentials have expired. 1781 o GSS_S_BAD_MECH indicates that the referenced credentials do not 1782 contain elements for the requested mechanism. 1784 o GSS_S_FAILURE indicates that the operation failed for reasons 1785 unspecified at the GSS-API level. 1787 The GSS_Inquire_cred_by_mech() call enables callers in multi- 1788 mechanism environments to acquire specific data about available 1789 combinations of lifetimes, usage modes, and mechanisms within a 1790 credential structure. The lifetime_rec_initiate result indicates the 1791 available lifetime for context initiation purposes; the 1792 lifetime_rec_accept result indicates the available lifetime for 1793 context acceptance purposes. 1795 2.2: Context-level calls 1797 This group of calls is devoted to the establishment and management of 1798 security contexts between peers. A context's initiator calls 1799 GSS_Init_sec_context(), resulting in generation of a token which the 1800 caller passes to the target. At the target, that token is passed to 1801 GSS_Accept_sec_context(). Depending on the underlying mech_type and 1802 specified options, additional token exchanges may be performed in the 1803 course of context establishment; such exchanges are accommodated by 1804 GSS_S_CONTINUE_NEEDED status returns from GSS_Init_sec_context() and 1805 GSS_Accept_sec_context(). 1807 Either party to an established context may invoke 1808 GSS_Delete_sec_context() to flush context information when a context 1809 is no longer required. GSS_Process_context_token() is used to process 1810 received tokens carrying context-level control information. 1811 GSS_Context_time() allows a caller to determine the length of time 1812 for which an established context will remain valid. 1813 GSS_Inquire_context() returns status information describing context 1814 characteristics. GSS_Wrap_size_limit() allows a caller to determine 1815 the size of a token which will be generated by a GSS_Wrap() 1816 operation. GSS_Export_sec_context() and GSS_Import_sec_context() 1817 enable transfer of active contexts between processes on an end 1818 system. 1820 2.2.1: GSS_Init_sec_context call 1822 Inputs: 1824 o claimant_cred_handle CREDENTIAL HANDLE, -- NULL specifies "use 1825 -- default" 1827 o input_context_handle CONTEXT HANDLE, -- 0 specifies "none assigned 1828 -- yet" 1830 o targ_name INTERNAL NAME, 1832 o mech_type OBJECT IDENTIFIER, -- NULL parameter specifies "use 1833 -- default" 1835 o deleg_req_flag BOOLEAN, 1837 o mutual_req_flag BOOLEAN, 1839 o replay_det_req_flag BOOLEAN, 1841 o sequence_req_flag BOOLEAN, 1843 o anon_req_flag BOOLEAN, 1845 o conf_req_flag BOOLEAN, 1846 o integ_req_flag BOOLEAN, 1848 o lifetime_req INTEGER, -- 0 specifies default lifetime 1850 o chan_bindings OCTET STRING, 1852 o input_token OCTET STRING -- NULL or token received from target 1854 Outputs: 1856 o major_status INTEGER, 1858 o minor_status INTEGER, 1860 o output_context_handle CONTEXT HANDLE, -- once returned non-NULL, 1861 -- caller must release with GSS_Delete_sec_context() 1863 o mech_type OBJECT IDENTIFIER, -- actual mechanism always 1864 -- indicated, never NULL; caller should treat as read-only 1865 -- and should not attempt to release 1867 o output_token OCTET STRING, -- NULL or token to pass to context 1868 -- target; caller must release with GSS_Release_buffer() 1870 o deleg_state BOOLEAN, 1872 o mutual_state BOOLEAN, 1874 o replay_det_state BOOLEAN, 1876 o sequence_state BOOLEAN, 1878 o anon_state BOOLEAN, 1880 o trans_state BOOLEAN, 1882 o prot_ready_state BOOLEAN, -- see Section 1.2.7 1884 o conf_avail BOOLEAN, 1886 o integ_avail BOOLEAN, 1888 o lifetime_rec INTEGER -- in seconds, or reserved value for 1889 -- INDEFINITE 1891 This call may block pending network interactions for those mech_types 1892 in which an authentication server or other network entity must be 1893 consulted on behalf of a context initiator in order to generate an 1894 output_token suitable for presentation to a specified target. 1896 Return major_status codes: 1898 o GSS_S_COMPLETE indicates that context-level information was 1899 successfully initialized, and that the returned output_token 1900 will provide sufficient information for the target to perform 1901 per-message processing on the newly-established context. 1903 o GSS_S_CONTINUE_NEEDED indicates that control information in the 1904 returned output_token must be sent to the target, and that a 1905 reply must be received and passed as the input_token argument 1906 to a continuation call to GSS_Init_sec_context(), before 1907 per-message processing can be performed in conjunction with 1908 this context. 1910 o GSS_S_DEFECTIVE_TOKEN indicates that consistency checks 1911 performed on the input_token failed, preventing further 1912 processing from being performed based on that token. 1914 o GSS_S_DEFECTIVE_CREDENTIAL indicates that consistency checks 1915 performed on the credential structure referenced by 1916 claimant_cred_handle failed, preventing further processing from 1917 being performed using that credential structure. 1919 o GSS_S_BAD_SIG (GSS_S_BAD_MIC) indicates that the received 1920 input_token contains an incorrect integrity check, so 1921 context setup cannot be accomplished. 1923 o GSS_S_NO_CRED indicates that no context was established, 1924 either because the input cred_handle was invalid, because the 1925 referenced credentials are valid for context acceptor use 1926 only, because the caller lacks authorization to access the 1927 referenced credentials, or because the resolution of default 1928 credentials failed. 1930 o GSS_S_CREDENTIALS_EXPIRED indicates that the credentials 1931 provided through the input claimant_cred_handle argument are no 1932 longer valid, so context establishment cannot be completed. 1934 o GSS_S_BAD_BINDINGS indicates that a mismatch between the 1935 caller-provided chan_bindings and those extracted from the 1936 input_token was detected, signifying a security-relevant 1937 event and preventing context establishment. (This result will 1938 be returned by GSS_Init_sec_context() only for contexts where 1939 mutual_state is TRUE.) 1941 o GSS_S_OLD_TOKEN indicates that the input_token is too old to 1942 be checked for integrity. This is a fatal error during context 1943 establishment. 1945 o GSS_S_DUPLICATE_TOKEN indicates that the input token has a 1946 correct integrity check, but is a duplicate of a token already 1947 processed. This is a fatal error during context establishment. 1949 o GSS_S_NO_CONTEXT indicates that no valid context was recognized 1950 for the input context_handle provided; this major status will 1951 be returned only for successor calls following GSS_S_CONTINUE_ 1952 NEEDED status returns. 1954 o GSS_S_BAD_NAMETYPE indicates that the provided targ_name is 1955 of a type uninterpretable or unsupported by the applicable 1956 underlying GSS-API mechanism(s), so context establishment 1957 cannot be completed. 1959 o GSS_S_BAD_NAME indicates that the provided targ_name is 1960 inconsistent in terms of internally-incorporated type specifier 1961 information, so context establishment cannot be accomplished. 1963 o GSS_S_BAD_MECH indicates receipt of a context establishment token 1964 or of a caller request specifying a mechanism unsupported by 1965 the local system or with the caller's active credentials 1967 o GSS_S_FAILURE indicates that context setup could not be 1968 accomplished for reasons unspecified at the GSS-API level, and 1969 that no interface-defined recovery action is available. 1971 This routine is used by a context initiator, and ordinarily emits one 1972 (or, for the case of a multi-step exchange, more than one) 1973 output_token suitable for use by the target within the selected 1974 mech_type's protocol. Using information in the credentials structure 1975 referenced by claimant_cred_handle, GSS_Init_sec_context() 1976 initializes the data structures required to establish a security 1977 context with target targ_name. 1979 The targ_name may be any valid INTERNAL NAME; it need not be an MN. 1980 In addition to support for other name types, it is recommended (newly 1981 as of GSS-V2, Update 1) that mechanisms be able to accept 1982 GSS_C_NO_NAME as an input type for targ_name. While recommended, 1983 such support is not required, and it is recognized that not all 1984 mechanisms can construct tokens without explicitly naming the context 1985 target, even when mutual authentication of the target is not 1986 obtained. Callers wishing to make use of this facility and concerned 1987 with portability should be aware that support for GSS_C_NO_NAME as 1988 input targ_name type is unlikely to be provided within mechanism 1989 definitions specified prior to GSS-V2, Update 1. 1991 The claimant_cred_handle must correspond to the same valid 1992 credentials structure on the initial call to GSS_Init_sec_context() 1993 and on any successor calls resulting from GSS_S_CONTINUE_NEEDED 1994 status returns; different protocol sequences modeled by the 1995 GSS_S_CONTINUE_NEEDED facility will require access to credentials at 1996 different points in the context establishment sequence. 1998 The input_context_handle argument is 0, specifying "not yet 1999 assigned", on the first GSS_Init_sec_context() call relating to a 2000 given context. If successful (i.e., if accompanied by major_status 2001 GSS_S_COMPLETE or GSS_S_CONTINUE_NEEDED), and only if successful, the 2002 initial GSS_Init_sec_context() call returns a non-zero 2003 output_context_handle for use in future references to this context. 2004 Once a non-zero output_context_handle has been returned, GSS-API 2005 callers should call GSS_Delete_sec_context() to release context- 2006 related resources if errors occur in later phases of context 2007 establishment, or when an established context is no longer required. 2008 If GSS_Init_sec_context() is passed the handle of a context which is 2009 already fully established, GSS_S_FAILURE status is returned. 2011 When continuation attempts to GSS_Init_sec_context() are needed to 2012 perform context establishment, the previously-returned non-zero 2013 handle value is entered into the input_context_handle argument and 2014 will be echoed in the returned output_context_handle argument. On 2015 such continuation attempts (and only on continuation attempts) the 2016 input_token value is used, to provide the token returned from the 2017 context's target. 2019 The chan_bindings argument is used by the caller to provide 2020 information binding the security context to security-related 2021 characteristics (e.g., addresses, cryptographic keys) of the 2022 underlying communications channel. See Section 1.1.6 of this document 2023 for more discussion of this argument's usage. 2025 The input_token argument contains a message received from the target, 2026 and is significant only on a call to GSS_Init_sec_context() which 2027 follows a previous return indicating GSS_S_CONTINUE_NEEDED 2028 major_status. 2030 It is the caller's responsibility to establish a communications path 2031 to the target, and to transmit any returned output_token (independent 2032 of the accompanying returned major_status value) to the target over 2033 that path. The output_token can, however, be transmitted along with 2034 the first application-provided input message to be processed by 2035 GSS_GetMIC() or GSS_Wrap() in conjunction with a successfully- 2036 established context. 2038 The initiator may request various context-level functions through 2039 input flags: the deleg_req_flag requests delegation of access rights, 2040 the mutual_req_flag requests mutual authentication, the 2041 replay_det_req_flag requests that replay detection features be 2042 applied to messages transferred on the established context, and the 2043 sequence_req_flag requests that sequencing be enforced. (See Section 2044 1.2.3 for more information on replay detection and sequencing 2045 features.) The anon_req_flag requests that the initiator's identity 2046 not be transferred within tokens to be sent to the acceptor. The 2047 conf_req_flag and integ_req_flag provide informatory inputs to the 2048 GSS-API implementation as to whether, respectively, per-message 2049 confidentiality and per-message integrity services will be required 2050 on the context. 2052 Not all of the optionally-requestable features will be available in 2053 all underlying mech_types. The corresponding return state values 2054 deleg_state, mutual_state, replay_det_state, and sequence_state 2055 indicate, as a function of mech_type processing capabilities and 2056 initiator-provided input flags, the set of features which will be 2057 active on the context. The returned trans_state value indicates 2058 whether the context is transferable to other processes through use of 2059 GSS_Export_sec_context(). These state indicators' values are 2060 undefined unless either the routine's major_status indicates 2061 GSS_S_COMPLETE, or TRUE prot_ready_state is returned along with 2062 GSS_S_CONTINUE_NEEDED major_status; for the latter case, it is 2063 possible that additional features, not confirmed or indicated along 2064 with TRUE prot_ready_state, will be confirmed and indicated when 2065 GSS_S_COMPLETE is subsequently returned. 2067 The returned anon_state and prot_ready_state values are significant 2068 for both GSS_S_COMPLETE and GSS_S_CONTINUE_NEEDED major_status 2069 returns from GSS_Init_sec_context(). When anon_state is returned 2070 TRUE, this indicates that neither the current token nor its 2071 predecessors delivers or has delivered the initiator's identity. 2072 Callers wishing to perform context establishment only if anonymity 2073 support is provided should transfer a returned token from 2074 GSS_Init_sec_context() to the peer only if it is accompanied by a 2075 TRUE anon_state indicator. When prot_ready_state is returned TRUE in 2076 conjunction with GSS_S_CONTINUE_NEEDED major_status, this indicates 2077 that per-message protection operations may be applied on the context: 2078 see Section 1.2.7 for further discussion of this facility. 2080 Failure to provide the precise set of features requested by the 2081 caller does not cause context establishment to fail; it is the 2082 caller's prerogative to delete the context if the feature set 2083 provided is unsuitable for the caller's use. 2085 The returned mech_type value indicates the specific mechanism 2086 employed on the context; it will never indicate the value for 2087 "default". A valid mech_type result must be returned along with a 2088 GSS_S_COMPLETE status return; GSS-API implementations may (but are 2089 not required to) also return mech_type along with predecessor calls 2090 indicating GSS_S_CONTINUE_NEEDED status. For the case of mechanisms 2091 which themselves perform negotiation, the returned mech_type result 2092 may indicate selection of a mechanism identified by an OID different 2093 than that passed in the input mech_type argument, and the returned 2094 value may change between successive calls returning 2095 GSS_S_CONTINUE_NEEDED and the final call returning GSS_S_COMPLETE. 2097 The conf_avail return value indicates whether the context supports 2098 per-message confidentiality services, and so informs the caller 2099 whether or not a request for encryption through the conf_req_flag 2100 input to GSS_Wrap() can be honored. In similar fashion, the 2101 integ_avail return value indicates whether per-message integrity 2102 services are available (through either GSS_GetMIC() or GSS_Wrap()) on 2103 the established context. These state indicators' values are undefined 2104 unless either the routine's major_status indicates GSS_S_COMPLETE, or 2105 TRUE prot_ready_state is returned along with GSS_S_CONTINUE_NEEDED 2106 major_status. 2108 The lifetime_req input specifies a desired upper bound for the 2109 lifetime of the context to be established, with a value of 0 used to 2110 request a default lifetime. The lifetime_rec return value indicates 2111 the length of time for which the context will be valid, expressed as 2112 an offset from the present; depending on mechanism capabilities, 2113 credential lifetimes, and local policy, it may not correspond to the 2114 value requested in lifetime_req. If no constraints on context 2115 lifetime are imposed, this may be indicated by returning a reserved 2116 value representing INDEFINITE lifetime_req. The value of lifetime_rec 2117 is undefined unless the routine's major_status indicates 2118 GSS_S_COMPLETE. 2120 If the mutual_state is TRUE, this fact will be reflected within the 2121 output_token. A call to GSS_Accept_sec_context() at the target in 2122 conjunction with such a context will return a token, to be processed 2123 by a continuation call to GSS_Init_sec_context(), in order to achieve 2124 mutual authentication. 2126 2.2.2: GSS_Accept_sec_context call 2128 Inputs: 2130 o acceptor_cred_handle CREDENTIAL HANDLE, -- NULL specifies 2131 -- "use default" 2133 o input_context_handle CONTEXT HANDLE, -- 0 specifies 2134 -- "not yet assigned" 2135 o chan_bindings OCTET STRING, 2137 o input_token OCTET STRING 2139 Outputs: 2141 o major_status INTEGER, 2143 o minor_status INTEGER, 2145 o src_name INTERNAL NAME, -- guaranteed to be MN 2146 -- once returned, caller must release with GSS_Release_name() 2148 o mech_type OBJECT IDENTIFIER, -- caller should treat as 2149 -- read-only; does not need to be released 2151 o output_context_handle CONTEXT HANDLE, -- once returned 2152 -- non-NULL in context establishment sequence, caller 2153 -- must release with GSS_Delete_sec_context() 2155 o deleg_state BOOLEAN, 2157 o mutual_state BOOLEAN, 2159 o replay_det_state BOOLEAN, 2161 o sequence_state BOOLEAN, 2163 o anon_state BOOLEAN, 2165 o trans_state BOOLEAN, 2167 o prot_ready_state BOOLEAN, -- see Section 1.2.7 for discussion 2169 o conf_avail BOOLEAN, 2171 o integ_avail BOOLEAN, 2173 o lifetime_rec INTEGER, -- in seconds, or reserved value for 2174 -- INDEFINITE 2176 o delegated_cred_handle CREDENTIAL HANDLE, -- if returned non-NULL, 2177 -- caller must release with GSS_Release_cred() 2179 o output_token OCTET STRING -- NULL or token to pass to context 2180 -- initiator; if returned non-NULL, caller must release with 2181 -- GSS_Release_buffer() 2182 This call may block pending network interactions for those mech_types 2183 in which a directory service or other network entity must be 2184 consulted on behalf of a context acceptor in order to validate a 2185 received input_token. 2187 Return major_status codes: 2189 o GSS_S_COMPLETE indicates that context-level data structures 2190 were successfully initialized, and that per-message processing 2191 can now be performed in conjunction with this context. 2193 o GSS_S_CONTINUE_NEEDED indicates that control information in the 2194 returned output_token must be sent to the initiator, and that 2195 a response must be received and passed as the input_token 2196 argument to a continuation call to GSS_Accept_sec_context(), 2197 before per-message processing can be performed in conjunction 2198 with this context. 2200 o GSS_S_DEFECTIVE_TOKEN indicates that consistency checks performed 2201 on the input_token failed, preventing further processing from 2202 being performed based on that token. 2204 o GSS_S_DEFECTIVE_CREDENTIAL indicates that consistency checks 2205 performed on the credential structure referenced by 2206 acceptor_cred_handle failed, preventing further processing from 2207 being performed using that credential structure. 2209 o GSS_S_BAD_SIG (GSS_S_BAD_MIC) indicates that the received 2210 input_token contains an incorrect integrity check, so context 2211 setup cannot be accomplished. 2213 o GSS_S_DUPLICATE_TOKEN indicates that the integrity check on the 2214 received input_token was correct, but that the input_token 2215 was recognized as a duplicate of an input_token already 2216 processed. No new context is established. 2218 o GSS_S_OLD_TOKEN indicates that the integrity check on the received 2219 input_token was correct, but that the input_token is too old 2220 to be checked for duplication against previously-processed 2221 input_tokens. No new context is established. 2223 o GSS_S_NO_CRED indicates that no context was established, either 2224 because the input cred_handle was invalid, because the 2225 referenced credentials are valid for context initiator use 2226 only, because the caller lacks authorization to access the 2227 referenced credentials, or because the procedure for default 2228 credential resolution failed. 2230 o GSS_S_CREDENTIALS_EXPIRED indicates that the credentials provided 2231 through the input acceptor_cred_handle argument are no 2232 longer valid, so context establishment cannot be completed. 2234 o GSS_S_BAD_BINDINGS indicates that a mismatch between the 2235 caller-provided chan_bindings and those extracted from the 2236 input_token was detected, signifying a security-relevant 2237 event and preventing context establishment. 2239 o GSS_S_NO_CONTEXT indicates that no valid context was recognized 2240 for the input context_handle provided; this major status will 2241 be returned only for successor calls following GSS_S_CONTINUE_ 2242 NEEDED status returns. 2244 o GSS_S_BAD_MECH indicates receipt of a context establishment token 2245 specifying a mechanism unsupported by the local system or with 2246 the caller's active credentials. 2248 o GSS_S_FAILURE indicates that context setup could not be 2249 accomplished for reasons unspecified at the GSS-API level, and 2250 that no interface-defined recovery action is available. 2252 The GSS_Accept_sec_context() routine is used by a context target. 2253 Using information in the credentials structure referenced by the 2254 input acceptor_cred_handle, it verifies the incoming input_token and 2255 (following the successful completion of a context establishment 2256 sequence) returns the authenticated src_name and the mech_type used. 2257 The returned src_name is guaranteed to be an MN, processed by the 2258 mechanism under which the context was established. The 2259 acceptor_cred_handle must correspond to the same valid credentials 2260 structure on the initial call to GSS_Accept_sec_context() and on any 2261 successor calls resulting from GSS_S_CONTINUE_NEEDED status returns; 2262 different protocol sequences modeled by the GSS_S_CONTINUE_NEEDED 2263 mechanism will require access to credentials at different points in 2264 the context establishment sequence. 2266 The input_context_handle argument is 0, specifying "not yet 2267 assigned", on the first GSS_Accept_sec_context() call relating to a 2268 given context. If successful (i.e., if accompanied by major_status 2269 GSS_S_COMPLETE or GSS_S_CONTINUE_NEEDED), and only if successful, the 2270 initial GSS_Accept_sec_context() call returns a non-zero 2271 output_context_handle for use in future references to this context. 2272 Once a non-zero output_context_handle has been returned, GSS-API 2273 callers should call GSS_Delete_sec_context() to release context- 2274 related resources if errors occur in later phases of context 2275 establishment, or when an established context is no longer required. 2276 If GSS_Accept_sec_context() is passed the handle of a context which 2277 is already fully established, GSS_S_FAILURE status is returned. 2279 The chan_bindings argument is used by the caller to provide 2280 information binding the security context to security-related 2281 characteristics (e.g., addresses, cryptographic keys) of the 2282 underlying communications channel. See Section 1.1.6 of this document 2283 for more discussion of this argument's usage. 2285 The returned state results (deleg_state, mutual_state, 2286 replay_det_state, sequence_state, anon_state, trans_state, and 2287 prot_ready_state) reflect the same information as described for 2288 GSS_Init_sec_context(), and their values are significant under the 2289 same return state conditions. 2291 The conf_avail return value indicates whether the context supports 2292 per-message confidentiality services, and so informs the caller 2293 whether or not a request for encryption through the conf_req_flag 2294 input to GSS_Wrap() can be honored. In similar fashion, the 2295 integ_avail return value indicates whether per-message integrity 2296 services are available (through either GSS_GetMIC() or GSS_Wrap()) 2297 on the established context. These values are significant under the 2298 same return state conditions as described under 2299 GSS_Init_sec_context(). 2301 The lifetime_rec return value is significant only in conjunction with 2302 GSS_S_COMPLETE major_status, and indicates the length of time for 2303 which the context will be valid, expressed as an offset from the 2304 present. 2306 The returned mech_type value indicates the specific mechanism 2307 employed on the context; it will never indicate the value for 2308 "default". A valid mech_type result must be returned whenever 2309 GSS_S_COMPLETE status is indicated; GSS-API implementations may (but 2310 are not required to) also return mech_type along with predecessor 2311 calls indicating GSS_S_CONTINUE_NEEDED status. For the case of 2312 mechanisms which themselves perform negotiation, the returned 2313 mech_type result may indicate selection of a mechanism identified by 2314 an OID different than that passed in the input mech_type argument, 2315 and the returned value may change between successive calls returning 2316 GSS_S_CONTINUE_NEEDED and the final call returning GSS_S_COMPLETE. 2318 The delegated_cred_handle result is significant only when deleg_state 2319 is TRUE, and provides a means for the target to reference the 2320 delegated credentials. The output_token result, when non-NULL, 2321 provides a context-level token to be returned to the context 2322 initiator to continue a multi-step context establishment sequence. As 2323 noted with GSS_Init_sec_context(), any returned token should be 2324 transferred to the context's peer (in this case, the context 2325 initiator), independent of the value of the accompanying returned 2326 major_status. 2328 Note: A target must be able to distinguish a context-level 2329 input_token, which is passed to GSS_Accept_sec_context(), from the 2330 per-message data elements passed to GSS_VerifyMIC() or GSS_Unwrap(). 2331 These data elements may arrive in a single application message, and 2332 GSS_Accept_sec_context() must be performed before per-message 2333 processing can be performed successfully. 2335 2.2.3: GSS_Delete_sec_context call 2337 Input: 2339 o context_handle CONTEXT HANDLE 2341 Outputs: 2343 o major_status INTEGER, 2345 o minor_status INTEGER, 2347 o output_context_token OCTET STRING 2349 Return major_status codes: 2351 o GSS_S_COMPLETE indicates that the context was recognized, and that 2352 relevant context-specific information was flushed. If the caller 2353 provides a non-null buffer to receive an output_context_token, and 2354 the mechanism returns a non-NULL token into that buffer, the 2355 returned output_context_token is ready for transfer to the 2356 context's peer. 2358 o GSS_S_NO_CONTEXT indicates that no valid context was recognized 2359 for the input context_handle provided, so no deletion was 2360 performed. 2362 o GSS_S_FAILURE indicates that the context is recognized, but 2363 that the GSS_Delete_sec_context() operation could not be 2364 performed for reasons unspecified at the GSS-API level. 2366 This call can be made by either peer in a security context, to flush 2367 context-specific information. Once a non-zero output_context_handle 2368 has been returned by context establishment calls, GSS-API callers 2369 should call GSS_Delete_sec_context() to release context-related 2370 resources if errors occur in later phases of context establishment, 2371 or when an established context is no longer required. This call may 2372 block pending network interactions for mech_types in which active 2373 notification must be made to a central server when a security context 2374 is to be deleted. 2376 If a non-null output_context_token parameter is provided by the 2377 caller, an output_context_token may be returned to the caller. If an 2378 output_context_token is provided to the caller, it can be passed to 2379 the context's peer to inform the peer's GSS-API implementation that 2380 the peer's corresponding context information can also be flushed. 2381 (Once a context is established, the peers involved are expected to 2382 retain cached credential and context-related information until the 2383 information's expiration time is reached or until a 2384 GSS_Delete_sec_context() call is made.) 2386 The facility for context_token usage to signal context deletion is 2387 retained for compatibility with GSS-API Version 1. For current 2388 usage, it is recommended that both peers to a context invoke 2389 GSS_Delete_sec_context() independently, passing a null 2390 output_context_token buffer to indicate that no context_token is 2391 required. Implementations of GSS_Delete_sec_context() should delete 2392 relevant locally-stored context information. 2394 Attempts to perform per-message processing on a deleted context will 2395 result in error returns. 2397 2.2.4: GSS_Process_context_token call 2399 Inputs: 2401 o context_handle CONTEXT HANDLE, 2403 o input_context_token OCTET STRING 2405 Outputs: 2407 o major_status INTEGER, 2409 o minor_status INTEGER, 2411 Return major_status codes: 2413 o GSS_S_COMPLETE indicates that the input_context_token was 2414 successfully processed in conjunction with the context 2415 referenced by context_handle. 2417 o GSS_S_DEFECTIVE_TOKEN indicates that consistency checks 2418 performed on the received context_token failed, preventing 2419 further processing from being performed with that token. 2421 o GSS_S_NO_CONTEXT indicates that no valid context was recognized 2422 for the input context_handle provided. 2424 o GSS_S_FAILURE indicates that the context is recognized, but 2425 that the GSS_Process_context_token() operation could not be 2426 performed for reasons unspecified at the GSS-API level. 2428 This call is used to process context_tokens received from a peer once 2429 a context has been established, with corresponding impact on 2430 context-level state information. One use for this facility is 2431 processing of the context_tokens generated by 2432 GSS_Delete_sec_context(); GSS_Process_context_token() will not block 2433 pending network interactions for that purpose. Another use is to 2434 process tokens indicating remote-peer context establishment failures 2435 after the point where the local GSS-API implementation has already 2436 indicated GSS_S_COMPLETE status. 2438 2.2.5: GSS_Context_time call 2440 Input: 2442 o context_handle CONTEXT HANDLE, 2444 Outputs: 2446 o major_status INTEGER, 2448 o minor_status INTEGER, 2450 o lifetime_rec INTEGER -- in seconds, or reserved value for 2451 -- INDEFINITE 2453 Return major_status codes: 2455 o GSS_S_COMPLETE indicates that the referenced context is valid, 2456 and will remain valid for the amount of time indicated in 2457 lifetime_rec. 2459 o GSS_S_CONTEXT_EXPIRED indicates that data items related to the 2460 referenced context have expired. 2462 o GSS_S_NO_CONTEXT indicates that no valid context was recognized 2463 for the input context_handle provided. 2465 o GSS_S_FAILURE indicates that the requested operation failed for 2466 reasons unspecified at the GSS-API level. 2468 This call is used to determine the amount of time for which a 2469 currently established context will remain valid. 2471 2.2.6: GSS_Inquire_context call 2472 Input: 2474 o context_handle CONTEXT HANDLE, 2476 Outputs: 2478 o major_status INTEGER, 2480 o minor_status INTEGER, 2482 o src_name INTERNAL NAME, -- name of context initiator, 2483 -- guaranteed to be MN; 2484 -- caller must release with GSS_Release_name() if returned 2486 o targ_name INTERNAL NAME, -- name of context target, 2487 -- guaranteed to be MN; 2488 -- caller must release with GSS_Release_name() if returned 2490 o lifetime_rec INTEGER -- in seconds, or reserved value for 2491 -- INDEFINITE or EXPIRED 2493 o mech_type OBJECT IDENTIFIER, -- the mechanism supporting this 2494 -- security context; caller should treat as read-only and not 2495 -- attempt to release 2497 o deleg_state BOOLEAN, 2499 o mutual_state BOOLEAN, 2501 o replay_det_state BOOLEAN, 2503 o sequence_state BOOLEAN, 2505 o anon_state BOOLEAN, 2507 o trans_state BOOLEAN, 2509 o prot_ready_state BOOLEAN, 2511 o conf_avail BOOLEAN, 2513 o integ_avail BOOLEAN, 2515 o locally_initiated BOOLEAN, -- TRUE if initiator, FALSE if acceptor 2517 o open BOOLEAN, -- TRUE if context fully established, FALSE 2518 -- if partly established (in CONTINUE_NEEDED state) 2519 Return major_status codes: 2521 o GSS_S_COMPLETE indicates that the referenced context is valid 2522 and that lifetime_rec, mech_type, 2523 deleg_state, mutual_state, replay_det_state, sequence_state, 2524 anon_state, trans_state, prot_ready_state, conf_avail, 2525 integ_avail, locally_initiated, and open return values describe the 2526 corresponding characteristics of the context. If open is TRUE, 2527 src_name and targ_name are valid in addition to the values 2528 listed above. 2530 o GSS_S_NO_CONTEXT indicates that no valid context was recognized 2531 for the input context_handle provided. Return values other than 2532 major_status and minor_status are undefined. 2534 o GSS_S_FAILURE indicates that the requested operation failed for 2535 reasons unspecified at the GSS-API level. Return values other than 2536 major_status and minor_status are undefined. 2538 This call is used to extract information describing characteristics 2539 of a security context. Note that GSS-API implementations are 2540 expected to retain inquirable context data on a context until the 2541 context is released by a caller, even after the context has expired, 2542 although underlying cryptographic data elements may be deleted after 2543 expiration in order to limit their exposure. 2545 2.2.7: GSS_Wrap_size_limit call 2547 Inputs: 2549 o context_handle CONTEXT HANDLE, 2551 o conf_req_flag BOOLEAN, 2553 o qop INTEGER, 2555 o output_size INTEGER 2557 Outputs: 2559 o major_status INTEGER, 2561 o minor_status INTEGER, 2563 o max_input_size INTEGER 2565 Return major_status codes: 2567 o GSS_S_COMPLETE indicates a successful token size determination: 2568 an input message with a length in octets equal to the 2569 returned max_input_size value will, when passed to GSS_Wrap() 2570 for processing on the context identified by the context_handle 2571 parameter with the confidentiality request state as provided in 2572 conf_req_flag and with the quality of protection specifier provided 2573 in the qop parameter, yield an output token no larger than the 2574 value of the provided output_size parameter. 2576 o GSS_S_CONTEXT_EXPIRED indicates that the provided input 2577 context_handle is recognized, but that the referenced context has 2578 expired. Return values other than major_status and minor_status 2579 are undefined. 2581 o GSS_S_NO_CONTEXT indicates that no valid context was recognized 2582 for the input context_handle provided. Return values other than 2583 major_status and minor_status are undefined. 2585 o GSS_S_BAD_QOP indicates that the provided QOP value is not 2586 recognized or supported for the context. 2588 o GSS_S_FAILURE indicates that the requested operation failed for 2589 reasons unspecified at the GSS-API level. Return values other than 2590 major_status and minor_status are undefined. 2592 This call is used to determine the largest input datum which may be 2593 passed to GSS_Wrap() without yielding an output token larger than a 2594 caller-specified value. 2596 2.2.8: GSS_Export_sec_context call 2598 Inputs: 2600 o context_handle CONTEXT HANDLE 2602 Outputs: 2604 o major_status INTEGER, 2606 o minor_status INTEGER, 2608 o interprocess_token OCTET STRING -- caller must release 2609 -- with GSS_Release_buffer() 2611 Return major_status codes: 2613 o GSS_S_COMPLETE indicates that the referenced context has been 2614 successfully exported to a representation in the interprocess_token, 2615 and is no longer available for use by the caller. 2617 o GSS_S_UNAVAILABLE indicates that the context export facility 2618 is not available for use on the referenced context. (This status 2619 should occur only for contexts for which the trans_state value is 2620 FALSE.) Return values other than major_status and minor_status are 2621 undefined. 2623 o GSS_S_CONTEXT_EXPIRED indicates that the provided input 2624 context_handle is recognized, but that the referenced context has 2625 expired. Return values other than major_status and minor_status 2626 are undefined. 2628 o GSS_S_NO_CONTEXT indicates that no valid context was recognized 2629 for the input context_handle provided. Return values other than 2630 major_status and minor_status are undefined. 2632 o GSS_S_FAILURE indicates that the requested operation failed for 2633 reasons unspecified at the GSS-API level. Return values other than 2634 major_status and minor_status are undefined. 2636 This call generates an interprocess token for transfer to another 2637 process within an end system, in order to transfer control of a 2638 security context to that process. The recipient of the interprocess 2639 token will call GSS_Import_sec_context() to accept the transfer. The 2640 GSS_Export_sec_context() operation is defined for use only with 2641 security contexts which are fully and successfully established (i.e., 2642 those for which GSS_Init_sec_context() and GSS_Accept_sec_context() 2643 have returned GSS_S_COMPLETE major_status). 2645 A successful GSS_Export_sec_context() operation deactivates the 2646 security context for the calling process; for this case, the GSS-API 2647 implementation shall deallocate all process-wide resources associated 2648 with the security context and shall set the context_handle to 2649 GSS_C_NO_CONTEXT. In the event of an error that makes it impossible 2650 to complete export of the security context, the GSS-API 2651 implementation must not return an interprocess token and should 2652 strive to leave the security context referenced by the context_handle 2653 untouched. If this is impossible, it is permissible for the 2654 implementation to delete the security context, provided that it also 2655 sets te context_handle parameter to GSS_C_NO_CONTEXT. 2657 Portable callers must not assume that a given interprocess token can 2658 be imported by GSS_Import_sec_context() more than once, thereby 2659 creating multiple instantiations of a single context. GSS-API 2660 implementations may detect and reject attempted multiple imports, but 2661 are not required to do so. 2663 The internal representation contained within the interprocess token 2664 is an implementation-defined local matter. Interprocess tokens 2665 cannot be assumed to be transferable across different GSS-API 2666 implementations. 2668 It is recommended that GSS-API implementations adopt policies suited 2669 to their operational environments in order to define the set of 2670 processes eligible to import a context, but specific constraints in 2671 this area are local matters. Candidate examples include transfers 2672 between processes operating on behalf of the same user identity, or 2673 processes comprising a common job. However, it may be impossible to 2674 enforce such policies in some implementations. 2676 In support of the above goals, implementations may protect the 2677 transferred context data by using cryptography to protect data within 2678 the interprocess token, or by using interprocess tokens as a means to 2679 reference local interprocess communication facilities (protected by 2680 other means) rather than storing the context data directly within the 2681 tokens. 2683 Transfer of an open context may, for certain mechanisms and 2684 implementations, reveal data about the credential which was used to 2685 establish the context. Callers should, therefore, be cautious about 2686 the trustworthiness of processes to which they transfer contexts. 2687 Although the GSS-API implementation may provide its own set of 2688 protections over the exported context, the caller is responsible for 2689 protecting the interprocess token from disclosure, and for taking 2690 care that the context is transferred to an appropriate destination 2691 process. 2693 2.2.9: GSS_Import_sec_context call 2695 Inputs: 2697 o interprocess_token OCTET STRING 2699 Outputs: 2701 o major_status INTEGER, 2703 o minor_status INTEGER, 2705 o context_handle CONTEXT HANDLE -- if successfully returned, 2706 -- caller must release with GSS_Delete_sec_context() 2708 Return major_status codes: 2710 o GSS_S_COMPLETE indicates that the context represented by the 2711 input interprocess_token has been successfully transferred to 2712 the caller, and is available for future use via the output 2713 context_handle. 2715 o GSS_S_NO_CONTEXT indicates that the context represented by the 2716 input interprocess_token was invalid. Return values other than 2717 major_status and minor_status are undefined. 2719 o GSS_S_DEFECTIVE_TOKEN indicates that the input interprocess_token 2720 was defective. Return values other than major_status and 2721 minor_status are undefined. 2723 o GSS_S_UNAVAILABLE indicates that the context import facility 2724 is not available for use on the referenced context. Return values 2725 other than major_status and minor_status are undefined. 2727 o GSS_S_UNAUTHORIZED indicates that the context represented by 2728 the input interprocess_token is unauthorized for transfer to the 2729 caller. Return values other than major_status and minor_status 2730 are undefined. 2732 o GSS_S_FAILURE indicates that the requested operation failed for 2733 reasons unspecified at the GSS-API level. Return values other than 2734 major_status and minor_status are undefined. 2736 This call processes an interprocess token generated by 2737 GSS_Export_sec_context(), making the transferred context available 2738 for use by the caller. After a successful GSS_Import_sec_context() 2739 operation, the imported context is available for use by the importing 2740 process. In particular, the imported context is usable for all per- 2741 message operations and may be deleted or exported by its importer. 2742 The inability to receive delegated credentials through 2743 gss_import_sec_context() precludes establishment of new contexts 2744 based on information delegated to the importer's end system within 2745 the context which is being imported, unless those delegated 2746 credentials are obtained through separate routines (e.g., XGSS-API 2747 calls) outside the GSS-V2 definition. 2749 For further discussion of the security and authorization issues 2750 regarding this call, please see the discussion in Section 2.2.8. 2752 2.3: Per-message calls 2754 This group of calls is used to perform per-message protection 2755 processing on an established security context. None of these calls 2756 block pending network interactions. These calls may be invoked by a 2757 context's initiator or by the context's target. The four members of 2758 this group should be considered as two pairs; the output from 2759 GSS_GetMIC() is properly input to GSS_VerifyMIC(), and the output 2760 from GSS_Wrap() is properly input to GSS_Unwrap(). 2762 GSS_GetMIC() and GSS_VerifyMIC() support data origin authentication 2763 and data integrity services. When GSS_GetMIC() is invoked on an input 2764 message, it yields a per-message token containing data items which 2765 allow underlying mechanisms to provide the specified security 2766 services. The original message, along with the generated per-message 2767 token, is passed to the remote peer; these two data elements are 2768 processed by GSS_VerifyMIC(), which validates the message in 2769 conjunction with the separate token. 2771 GSS_Wrap() and GSS_Unwrap() support caller-requested confidentiality 2772 in addition to the data origin authentication and data integrity 2773 services offered by GSS_GetMIC() and GSS_VerifyMIC(). GSS_Wrap() 2774 outputs a single data element, encapsulating optionally enciphered 2775 user data as well as associated token data items. The data element 2776 output from GSS_Wrap() is passed to the remote peer and processed by 2777 GSS_Unwrap() at that system. GSS_Unwrap() combines decipherment (as 2778 required) with validation of data items related to authentication and 2779 integrity. 2781 Although zero-length tokens are never returned by GSS calls for 2782 transfer to a context's peer, a zero-length object may be passed by a 2783 caller into GSS_Wrap(), in which case the corresponding peer calling 2784 GSS_Unwrap() on the transferred token will receive a zero-length 2785 object as output from GSS_Unwrap(). Similarly, GSS_GetMIC() can be 2786 called on an empty object, yielding a MIC which GSS_VerifyMIC() will 2787 successfully verify against the active security context in 2788 conjunction with a zero-length object. 2790 2.3.1: GSS_GetMIC call 2792 Note: This call is functionally equivalent to the GSS_Sign call as 2793 defined in previous versions of this specification. In the interests 2794 of backward compatibility, it is recommended that implementations 2795 support this function under both names for the present; future 2796 references to this function as GSS_Sign are deprecated. 2798 Inputs: 2800 o context_handle CONTEXT HANDLE, 2802 o qop_req INTEGER, -- 0 specifies default QOP 2804 o message OCTET STRING 2806 Outputs: 2808 o major_status INTEGER, 2810 o minor_status INTEGER, 2812 o per_msg_token OCTET STRING -- caller must release 2813 -- with GSS_Release_buffer() 2815 Return major_status codes: 2817 o GSS_S_COMPLETE indicates that an integrity check, suitable for an 2818 established security context, was successfully applied and 2819 that the message and corresponding per_msg_token are ready 2820 for transmission. 2822 o GSS_S_CONTEXT_EXPIRED indicates that context-related data 2823 items have expired, so that the requested operation cannot be 2824 performed. 2826 o GSS_S_NO_CONTEXT indicates that no context was recognized 2827 for the input context_handle provided. 2829 o GSS_S_BAD_QOP indicates that the provided QOP value is not 2830 recognized or supported for the context. 2832 o GSS_S_FAILURE indicates that the context is recognized, but 2833 that the requested operation could not be performed for 2834 reasons unspecified at the GSS-API level. 2836 Using the security context referenced by context_handle, apply an 2837 integrity check to the input message (along with timestamps and/or 2838 other data included in support of mech_type-specific mechanisms) and 2839 return the result in per_msg_token. The qop_req parameter, 2840 interpretation of which is discussed in Section 1.2.4, allows 2841 quality-of-protection control. The caller passes the message and the 2842 per_msg_token to the target. 2844 The GSS_GetMIC() function completes before the message and 2845 per_msg_token is sent to the peer; successful application of 2846 GSS_GetMIC() does not guarantee that a corresponding GSS_VerifyMIC() 2847 has been (or can necessarily be) performed successfully when the 2848 message arrives at the destination. 2850 Mechanisms which do not support per-message protection services 2851 should return GSS_S_FAILURE if this routine is called. 2853 2.3.2: GSS_VerifyMIC call 2855 Note: This call is functionally equivalent to the GSS_Verify call as 2856 defined in previous versions of this specification. In the interests 2857 of backward compatibility, it is recommended that implementations 2858 support this function under both names for the present; future 2859 references to this function as GSS_Verify are deprecated. 2861 Inputs: 2863 o context_handle CONTEXT HANDLE, 2865 o message OCTET STRING, 2867 o per_msg_token OCTET STRING 2869 Outputs: 2871 o qop_state INTEGER, 2873 o major_status INTEGER, 2875 o minor_status INTEGER, 2877 Return major_status codes: 2879 o GSS_S_COMPLETE indicates that the message was successfully 2880 verified. 2882 o GSS_S_DEFECTIVE_TOKEN indicates that consistency checks performed 2883 on the received per_msg_token failed, preventing 2884 further processing from being performed with that token. 2886 o GSS_S_BAD_SIG (GSS_S_BAD_MIC) indicates that the received 2887 per_msg_token contains an incorrect integrity check for the 2888 message. 2890 o GSS_S_DUPLICATE_TOKEN, GSS_S_OLD_TOKEN, GSS_S_UNSEQ_TOKEN, 2891 and GSS_S_GAP_TOKEN values appear in conjunction with the 2892 optional per-message replay detection features described 2893 in Section 1.2.3; their semantics are described in that section. 2895 o GSS_S_CONTEXT_EXPIRED indicates that context-related data 2896 items have expired, so that the requested operation cannot be 2897 performed. 2899 o GSS_S_NO_CONTEXT indicates that no context was recognized 2900 for the input context_handle provided. 2902 o GSS_S_FAILURE indicates that the context is recognized, but 2903 that the GSS_VerifyMIC() operation could not be performed for 2904 reasons unspecified at the GSS-API level. 2906 Using the security context referenced by context_handle, verify that 2907 the input per_msg_token contains an appropriate integrity check for 2908 the input message, and apply any active replay detection or 2909 sequencing features. Returns an indication of the quality-of- 2910 protection applied to the processed message in the qop_state result. 2912 Mechanisms which do not support per-message protection services 2913 should return GSS_S_FAILURE if this routine is called. 2915 2.3.3: GSS_Wrap call 2917 Note: This call is functionally equivalent to the GSS_Seal call as 2918 defined in previous versions of this specification. In the interests 2919 of backward compatibility, it is recommended that implementations 2920 support this function under both names for the present; future 2921 references to this function as GSS_Seal are deprecated. 2923 Inputs: 2925 o context_handle CONTEXT HANDLE, 2927 o conf_req_flag BOOLEAN, 2929 o qop_req INTEGER, -- 0 specifies default QOP 2931 o input_message OCTET STRING 2933 Outputs: 2935 o major_status INTEGER, 2937 o minor_status INTEGER, 2939 o conf_state BOOLEAN, 2941 o output_message OCTET STRING -- caller must release with 2942 -- GSS_Release_buffer() 2944 Return major_status codes: 2946 o GSS_S_COMPLETE indicates that the input_message was successfully 2947 processed and that the output_message is ready for 2948 transmission. 2950 o GSS_S_CONTEXT_EXPIRED indicates that context-related data 2951 items have expired, so that the requested operation cannot be 2952 performed. 2954 o GSS_S_NO_CONTEXT indicates that no context was recognized 2955 for the input context_handle provided. 2957 o GSS_S_BAD_QOP indicates that the provided QOP value is not 2958 recognized or supported for the context. 2960 o GSS_S_FAILURE indicates that the context is recognized, but 2961 that the GSS_Wrap() operation could not be performed for 2962 reasons unspecified at the GSS-API level. 2964 Performs the data origin authentication and data integrity functions 2965 of GSS_GetMIC(). If the input conf_req_flag is TRUE, requests that 2966 confidentiality be applied to the input_message. Confidentiality may 2967 not be supported in all mech_types or by all implementations; the 2968 returned conf_state flag indicates whether confidentiality was 2969 provided for the input_message. The qop_req parameter, interpretation 2970 of which is discussed in Section 1.2.4, allows quality-of-protection 2971 control. 2973 In all cases, the GSS_Wrap() call yields a single output_message data 2974 element containing (optionally enciphered) user data as well as 2975 control information. 2977 Mechanisms which do not support per-message protection services 2978 should return GSS_S_FAILURE if this routine is called. 2980 2.3.4: GSS_Unwrap call 2982 Note: This call is functionally equivalent to the GSS_Unseal call as 2983 defined in previous versions of this specification. In the interests 2984 of backward compatibility, it is recommended that implementations 2985 support this function under both names for the present; future 2986 references to this function as GSS_Unseal are deprecated. 2988 Inputs: 2990 o context_handle CONTEXT HANDLE, 2992 o input_message OCTET STRING 2994 Outputs: 2996 o conf_state BOOLEAN, 2998 o qop_state INTEGER, 2999 o major_status INTEGER, 3001 o minor_status INTEGER, 3003 o output_message OCTET STRING -- caller must release with 3004 -- GSS_Release_buffer() 3006 Return major_status codes: 3008 o GSS_S_COMPLETE indicates that the input_message was 3009 successfully processed and that the resulting output_message is 3010 available. 3012 o GSS_S_DEFECTIVE_TOKEN indicates that consistency checks performed 3013 on the per_msg_token extracted from the input_message 3014 failed, preventing further processing from being performed. 3016 o GSS_S_BAD_SIG (GSS_S_BAD_MIC) indicates that an incorrect 3017 integrity check was detected for the message. 3019 o GSS_S_DUPLICATE_TOKEN, GSS_S_OLD_TOKEN, GSS_S_UNSEQ_TOKEN, 3020 and GSS_S_GAP_TOKEN values appear in conjunction with the 3021 optional per-message replay detection features described 3022 in Section 1.2.3; their semantics are described in that section. 3024 o GSS_S_CONTEXT_EXPIRED indicates that context-related data 3025 items have expired, so that the requested operation cannot be 3026 performed. 3028 o GSS_S_NO_CONTEXT indicates that no context was recognized 3029 for the input context_handle provided. 3031 o GSS_S_FAILURE indicates that the context is recognized, but 3032 that the GSS_Unwrap() operation could not be performed for 3033 reasons unspecified at the GSS-API level. 3035 Processes a data element generated (and optionally enciphered) by 3036 GSS_Wrap(), provided as input_message. The returned conf_state value 3037 indicates whether confidentiality was applied to the input_message. 3038 If conf_state is TRUE, GSS_Unwrap() has deciphered the input_message. 3039 Returns an indication of the quality-of-protection applied to the 3040 processed message in the qop_state result. GSS_Unwrap() performs the 3041 data integrity and data origin authentication checking functions of 3042 GSS_VerifyMIC() on the plaintext data. Plaintext data is returned in 3043 output_message. 3045 Mechanisms which do not support per-message protection services 3046 should return GSS_S_FAILURE if this routine is called. 3048 2.4: Support calls 3050 This group of calls provides support functions useful to GSS-API 3051 callers, independent of the state of established contexts. Their 3052 characterization with regard to blocking or non-blocking status in 3053 terms of network interactions is unspecified. 3055 2.4.1: GSS_Display_status call 3057 Inputs: 3059 o status_value INTEGER, -- GSS-API major_status or minor_status 3060 -- return value 3062 o status_type INTEGER, -- 1 if major_status, 2 if minor_status 3064 o mech_type OBJECT IDENTIFIER -- mech_type to be used for 3065 -- minor_status translation 3067 Outputs: 3069 o major_status INTEGER, 3071 o minor_status INTEGER, 3073 o status_string_set SET OF OCTET STRING -- required calls for 3074 -- release by caller are specific to language bindings 3076 Return major_status codes: 3078 o GSS_S_COMPLETE indicates that a valid printable status 3079 representation (possibly representing more than one status event 3080 encoded within the status_value) is available in the returned 3081 status_string_set. 3083 o GSS_S_BAD_MECH indicates that translation in accordance with an 3084 unsupported mech_type was requested, so translation could not 3085 be performed. 3087 o GSS_S_BAD_STATUS indicates that the input status_value was 3088 invalid, or that the input status_type carried a value other 3089 than 1 or 2, so translation could not be performed. 3091 o GSS_S_FAILURE indicates that the requested operation could not 3092 be performed for reasons unspecified at the GSS-API level. 3094 Provides a means for callers to translate GSS-API-returned major and 3095 minor status codes into printable string representations. Note: some 3096 language bindings may employ an iterative approach in order to emit 3097 successive status components; this approach is acceptable but not 3098 required for conformance with the current specification. 3100 Although not contemplated in [RFC-2078], it has been observed that 3101 some existing GSS-API implementations return GSS_S_CONTINUE_NEEDED 3102 status when iterating through successive messages returned from 3103 GSS_Display_status(). This behavior is deprecated; 3104 GSS_S_CONTINUE_NEEDED should be returned only by 3105 GSS_Init_sec_context() and GSS_Accept_sec_context(). For maximal 3106 portability, however, it is recommended that defensive callers be 3107 able to accept and ignore GSS_S_CONTINUE_NEEDED status if indicated 3108 by GSS_Display_status() or any other call other than 3109 GSS_Init_sec_context() or GSS_Accept_sec_context(). 3111 2.4.2: GSS_Indicate_mechs call 3113 Input: 3115 o (none) 3117 Outputs: 3119 o major_status INTEGER, 3121 o minor_status INTEGER, 3123 o mech_set SET OF OBJECT IDENTIFIER -- caller must release 3124 -- with GSS_Release_oid_set() 3126 Return major_status codes: 3128 o GSS_S_COMPLETE indicates that a set of available mechanisms has 3129 been returned in mech_set. 3131 o GSS_S_FAILURE indicates that the requested operation could not 3132 be performed for reasons unspecified at the GSS-API level. 3134 Allows callers to determine the set of mechanism types available on 3135 the local system. This call is intended for support of specialized 3136 callers who need to request non-default mech_type sets from GSS-API 3137 calls which accept input mechanism type specifiers. 3139 2.4.3: GSS_Compare_name call 3141 Inputs: 3143 o name1 INTERNAL NAME, 3144 o name2 INTERNAL NAME 3146 Outputs: 3148 o major_status INTEGER, 3150 o minor_status INTEGER, 3152 o name_equal BOOLEAN 3154 Return major_status codes: 3156 o GSS_S_COMPLETE indicates that name1 and name2 were comparable, 3157 and that the name_equal result indicates whether name1 and 3158 name2 represent the same entity. 3160 o GSS_S_BAD_NAMETYPE indicates that 3161 the two input names' types are different and incomparable, so that 3162 the comparison operation could not be completed. 3164 o GSS_S_BAD_NAME indicates that one or both of the input names 3165 was ill-formed in terms of its internal type specifier, so 3166 the comparison operation could not be completed. 3168 o GSS_S_FAILURE indicates that the call's operation could not 3169 be performed for reasons unspecified at the GSS-API level. 3171 Allows callers to compare two internal name representations to 3172 determine whether they refer to the same entity. If either name 3173 presented to GSS_Compare_name() denotes an anonymous principal, 3174 GSS_Compare_name() shall indicate FALSE. It is not required that 3175 either or both inputs name1 and name2 be MNs; for some 3176 implementations and cases, GSS_S_BAD_NAMETYPE may be returned, 3177 indicating name incomparability, for the case where neither input 3178 name is an MN. 3180 2.4.4: GSS_Display_name call 3182 Inputs: 3184 o name INTERNAL NAME 3186 Outputs: 3188 o major_status INTEGER, 3190 o minor_status INTEGER, 3191 o name_string OCTET STRING, -- caller must release 3192 -- with GSS_Release_buffer() 3194 o name_type OBJECT IDENTIFIER -- caller should treat 3195 -- as read-only; does not need to be released 3197 Return major_status codes: 3199 o GSS_S_COMPLETE indicates that a valid printable name 3200 representation is available in the returned name_string. 3202 o GSS_S_BAD_NAME indicates that the contents of the provided name 3203 were inconsistent with the internally-indicated name type, so 3204 no printable representation could be generated. 3206 o GSS_S_FAILURE indicates that the requested operation could not 3207 be performed for reasons unspecified at the GSS-API level. 3209 Allows callers to translate an internal name representation into a 3210 printable form with associated namespace type descriptor. The syntax 3211 of the printable form is a local matter. 3213 If the input name represents an anonymous identity, a reserved value 3214 (GSS_C_NT_ANONYMOUS) shall be returned for name_type. 3216 The GSS_C_NO_OID name type is to be returned only when the 3217 corresponding internal name was created through import with 3218 GSS_C_NO_OID. It is acceptable for mechanisms to normalize names 3219 imported with GSS_C_NO_OID into other supported types and, therefore, 3220 to display them with types other than GSS_C_NO_OID. 3222 2.4.5: GSS_Import_name call 3224 Inputs: 3226 o input_name_string OCTET STRING, 3228 o input_name_type OBJECT IDENTIFIER 3230 Outputs: 3232 o major_status INTEGER, 3234 o minor_status INTEGER, 3236 o output_name INTERNAL NAME -- caller must release with 3237 -- GSS_Release_name() 3238 Return major_status codes: 3240 o GSS_S_COMPLETE indicates that a valid name representation is 3241 output in output_name and described by the type value in 3242 output_name_type. 3244 o GSS_S_BAD_NAMETYPE indicates that the input_name_type is 3245 unsupported by the applicable underlying GSS-API mechanism(s), 3246 so the import operation could not be completed. 3248 o GSS_S_BAD_NAME indicates that the provided input_name_string 3249 is ill-formed in terms of the input_name_type, so the import 3250 operation could not be completed. 3252 o GSS_S_BAD_MECH indicates that the input presented for import was 3253 an exported name object and that its enclosed mechanism type was not 3254 recognized or was unsupported by the GSS-API implementation. 3256 o GSS_S_FAILURE indicates that the requested operation could not 3257 be performed for reasons unspecified at the GSS-API level. 3259 Allows callers to provide a name representation as a contiguous octet 3260 string, designate the type of namespace in conjunction with which it 3261 should be parsed, and convert that representation to an internal form 3262 suitable for input to other GSS-API routines. The syntax of the 3263 input_name_string is defined in conjunction with its associated name 3264 type; depending on the input_name_type, the associated 3265 input_name_string may or may not be a printable string. If the 3266 input_name_type's value is GSS_C_NO_OID, a mechanism-specific default 3267 printable syntax (which shall be specified in the corresponding GSS- 3268 V2 mechanism specification) is assumed for the input_name_string; 3269 other input_name_type values as registered by GSS-API implementations 3270 can be used to indicate specific non-default name syntaxes. Note: The 3271 input_name_type argument serves to describe and qualify the 3272 interpretation of the associated input_name_string; it does not 3273 specify the data type of the returned output_name. 3275 If a mechanism claims support for a particular name type, its 3276 GSS_Import_name() operation shall be able to accept all possible 3277 values conformant to the external name syntax as defined for that 3278 name type. These imported values may correspond to: 3280 (1) locally registered entities (for which credentials may be 3281 acquired), 3283 (2) non-local entities (for which local credentials cannot be 3284 acquired, but which may be referenced as targets of initiated 3285 security contexts or initiators of accepted security contexts), 3286 or to 3288 (3) neither of the above. 3290 Determination of whether a particular name belongs to class (1), (2), 3291 or (3) as described above is not guaranteed to be performed by the 3292 GSS_Import_name() function. 3294 The internal name generated by a GSS_Import_name() operation may be a 3295 single-mechanism MN, and is likely to be an MN within a single- 3296 mechanism implementation, but portable callers must not depend on 3297 this property (and must not, therefore, assume that the output from 3298 GSS_Import_name() can be passed directly to GSS_Export_name() without 3299 first being processed through GSS_Canonicalize_name()). 3301 2.4.6: GSS_Release_name call 3303 Inputs: 3305 o name INTERNAL NAME 3307 Outputs: 3309 o major_status INTEGER, 3311 o minor_status INTEGER 3313 Return major_status codes: 3315 o GSS_S_COMPLETE indicates that the storage associated with the 3316 input name was successfully released. 3318 o GSS_S_BAD_NAME indicates that the input name argument did not 3319 contain a valid name. 3321 o GSS_S_FAILURE indicates that the requested operation could not 3322 be performed for reasons unspecified at the GSS-API level. 3324 Allows callers to release the storage associated with an internal 3325 name representation. This call's specific behavior depends on the 3326 language and programming environment within which a GSS-API 3327 implementation operates, and is therefore detailed within applicable 3328 bindings specifications; in particular, implementation and invocation 3329 of this call may be superfluous (and may be omitted) within bindings 3330 where memory management is automatic. 3332 2.4.7: GSS_Release_buffer call 3333 Inputs: 3335 o buffer OCTET STRING 3337 Outputs: 3339 o major_status INTEGER, 3341 o minor_status INTEGER 3343 Return major_status codes: 3345 o GSS_S_COMPLETE indicates that the storage associated with the 3346 input buffer was successfully released. 3348 o GSS_S_FAILURE indicates that the requested operation could not 3349 be performed for reasons unspecified at the GSS-API level. 3351 Allows callers to release the storage associated with an OCTET STRING 3352 buffer allocated by another GSS-API call. This call's specific 3353 behavior depends on the language and programming environment within 3354 which a GSS-API implementation operates, and is therefore detailed 3355 within applicable bindings specifications; in particular, 3356 implementation and invocation of this call may be superfluous (and 3357 may be omitted) within bindings where memory management is automatic. 3359 2.4.8: GSS_Release_OID_set call 3361 Inputs: 3363 o buffer SET OF OBJECT IDENTIFIER 3365 Outputs: 3367 o major_status INTEGER, 3369 o minor_status INTEGER 3371 Return major_status codes: 3373 o GSS_S_COMPLETE indicates that the storage associated with the 3374 input object identifier set was successfully released. 3376 o GSS_S_FAILURE indicates that the requested operation could not 3377 be performed for reasons unspecified at the GSS-API level. 3379 Allows callers to release the storage associated with an object 3380 identifier set object allocated by another GSS-API call. This call's 3381 specific behavior depends on the language and programming environment 3382 within which a GSS-API implementation operates, and is therefore 3383 detailed within applicable bindings specifications; in particular, 3384 implementation and invocation of this call may be superfluous (and 3385 may be omitted) within bindings where memory management is automatic. 3387 2.4.9: GSS_Create_empty_OID_set call 3389 Inputs: 3391 o (none) 3393 Outputs: 3395 o major_status INTEGER, 3397 o minor_status INTEGER, 3399 o oid_set SET OF OBJECT IDENTIFIER -- caller must release 3400 -- with GSS_Release_oid_set() 3402 Return major_status codes: 3404 o GSS_S_COMPLETE indicates successful completion 3406 o GSS_S_FAILURE indicates that the operation failed 3408 Creates an object identifier set containing no object identifiers, to 3409 which members may be subsequently added using the 3410 GSS_Add_OID_set_member() routine. These routines are intended to be 3411 used to construct sets of mechanism object identifiers, for input to 3412 GSS_Acquire_cred(). 3414 2.4.10: GSS_Add_OID_set_member call 3416 Inputs: 3418 o member_oid OBJECT IDENTIFIER, 3420 o oid_set SET OF OBJECT IDENTIFIER 3422 Outputs: 3424 o major_status INTEGER, 3426 o minor_status INTEGER, 3427 Return major_status codes: 3429 o GSS_S_COMPLETE indicates successful completion 3431 o GSS_S_FAILURE indicates that the operation failed 3433 Adds an Object Identifier to an Object Identifier set. This routine 3434 is intended for use in conjunction with GSS_Create_empty_OID_set() 3435 when constructing a set of mechanism OIDs for input to 3436 GSS_Acquire_cred(). 3438 2.4.11: GSS_Test_OID_set_member call 3440 Inputs: 3442 o member OBJECT IDENTIFIER, 3444 o set SET OF OBJECT IDENTIFIER 3446 Outputs: 3448 o major_status INTEGER, 3450 o minor_status INTEGER, 3452 o present BOOLEAN 3454 Return major_status codes: 3456 o GSS_S_COMPLETE indicates successful completion 3458 o GSS_S_FAILURE indicates that the operation failed 3460 Interrogates an Object Identifier set to determine whether a 3461 specified Object Identifier is a member. This routine is intended to 3462 be used with OID sets returned by GSS_Indicate_mechs(), 3463 GSS_Acquire_cred(), and GSS_Inquire_cred(). 3465 2.4.12: GSS_Inquire_names_for_mech call 3467 Input: 3469 o input_mech_type OBJECT IDENTIFIER, -- mechanism type 3471 Outputs: 3473 o major_status INTEGER, 3475 o minor_status INTEGER, 3477 o name_type_set SET OF OBJECT IDENTIFIER -- caller must release 3478 -- with GSS_Release_oid_set() 3480 Return major_status codes: 3482 o GSS_S_COMPLETE indicates that the output name_type_set contains 3483 a list of name types which are supported by the locally available 3484 mechanism identified by input_mech_type. 3486 o GSS_S_BAD_MECH indicates that the mechanism identified by 3487 input_mech_type was unsupported within the local implementation, 3488 causing the query to fail. 3490 o GSS_S_FAILURE indicates that the requested operation could not 3491 be performed for reasons unspecified at the GSS-API level. 3493 Allows callers to determine the set of name types which are 3494 supportable by a specific locally-available mechanism. 3496 2.4.13: GSS_Inquire_mechs_for_name call 3498 Inputs: 3500 o input_name INTERNAL NAME, 3502 Outputs: 3504 o major_status INTEGER, 3506 o minor_status INTEGER, 3508 o mech_types SET OF OBJECT IDENTIFIER -- caller must release 3509 -- with GSS_Release_oid_set() 3511 Return major_status codes: 3513 o GSS_S_COMPLETE indicates that a set of object identifiers, 3514 corresponding to the set of mechanisms suitable for processing 3515 the input_name, is available in mech_types. 3517 o GSS_S_BAD_NAME indicates that the input_name was ill-formed 3518 and could not be processed. 3520 o GSS_S_BAD_NAMETYPE indicates that the input_name parameter 3521 contained an invalid name type or a name type unsupported 3522 by the GSS-API implementation. 3524 o GSS_S_FAILURE indicates that the requested operation could not 3525 be performed for reasons unspecified at the GSS-API level. 3527 This routine returns the mechanism set with which the input_name may 3528 be processed. 3530 Each mechanism returned will recognize at least one element within 3531 the name. It is permissible for this routine to be implemented within 3532 a mechanism-independent GSS-API layer, using the type information 3533 contained within the presented name, and based on registration 3534 information provided by individual mechanism implementations. This 3535 means that the returned mech_types result may indicate that a 3536 particular mechanism will understand a particular name when in fact 3537 it would refuse to accept that name as input to 3538 GSS_Canonicalize_name(), GSS_Init_sec_context(), GSS_Acquire_cred(), 3539 or GSS_Add_cred(), due to some property of the particular name rather 3540 than a property of the name type. Thus, this routine should be used 3541 only as a pre-filter for a call to a subsequent mechanism-specific 3542 routine. 3544 2.4.14: GSS_Canonicalize_name call 3546 Inputs: 3548 o input_name INTERNAL NAME, 3550 o mech_type OBJECT IDENTIFIER -- must be explicit mechanism, 3551 -- not "default" specifier or identifier of negotiating mechanism 3553 Outputs: 3555 o major_status INTEGER, 3557 o minor_status INTEGER, 3559 o output_name INTERNAL NAME -- caller must release with 3560 -- GSS_Release_name() 3562 Return major_status codes: 3564 o GSS_S_COMPLETE indicates that a mechanism-specific reduction of 3565 the input_name, as processed by the mechanism identified by 3566 mech_type, is available in output_name. 3568 o GSS_S_BAD_MECH indicates that the identified mechanism is 3569 unsupported for this operation; this may correspond either to 3570 a mechanism wholly unsupported by the local GSS-API implementation 3571 or to a negotiating mechanism with which the canonicalization 3572 operation cannot be performed. 3574 o GSS_S_BAD_NAMETYPE indicates that the input name does not 3575 contain an element with suitable type for processing by the 3576 identified mechanism. 3578 o GSS_S_BAD_NAME indicates that the input name contains an 3579 element with suitable type for processing by the identified 3580 mechanism, but that this element could not be processed 3581 successfully. 3583 o GSS_S_FAILURE indicates that the requested operation could not 3584 be performed for reasons unspecified at the GSS-API level. 3586 This routine reduces a GSS-API internal name input_name, which may in 3587 general contain elements corresponding to multiple mechanisms, to a 3588 mechanism-specific Mechanism Name (MN) output_name by applying the 3589 translations corresponding to the mechanism identified by mech_type. 3590 The contents of input_name are unaffected by the 3591 GSS_Canonicalize_name() operation. References to output_name will 3592 remain valid until output_name is released, independent of whether or 3593 not input_name is subsequently released. 3595 2.4.15: GSS_Export_name call 3597 Inputs: 3599 o input_name INTERNAL NAME, -- required to be MN 3601 Outputs: 3603 o major_status INTEGER, 3605 o minor_status INTEGER, 3607 o output_name OCTET STRING -- caller must release 3608 -- with GSS_Release_buffer() 3610 Return major_status codes: 3612 o GSS_S_COMPLETE indicates that a flat representation of the 3613 input name is available in output_name. 3615 o GSS_S_NAME_NOT_MN indicates that the input name contained 3616 elements corresponding to multiple mechanisms, so cannot 3617 be exported into a single-mechanism flat form. 3619 o GSS_S_BAD_NAME indicates that the input name was an MN, 3620 but could not be processed. 3622 o GSS_S_BAD_NAMETYPE indicates that the input name was an MN, 3623 but that its type is unsupported by the GSS-API implementation. 3625 o GSS_S_FAILURE indicates that the requested operation could not 3626 be performed for reasons unspecified at the GSS-API level. 3628 This routine creates a flat name representation, suitable for 3629 bytewise comparison or for input to GSS_Import_name() in conjunction 3630 with the reserved GSS-API Exported Name Object OID, from a internal- 3631 form Mechanism Name (MN) as emitted, e.g., by GSS_Canonicalize_name() 3632 or GSS_Accept_sec_context(). 3634 The emitted GSS-API Exported Name Object is self-describing; no 3635 associated parameter-level OID need be emitted by this call. This 3636 flat representation consists of a mechanism-independent wrapper 3637 layer, defined in Section 3.2 of this document, enclosing a 3638 mechanism-defined name representation. 3640 In all cases, the flat name output by GSS_Export_name() to correspond 3641 to a particular input MN must be invariant over time within a 3642 particular installation. 3644 The GSS_S_NAME_NOT_MN status code is provided to enable 3645 implementations to reject input names which are not MNs. It is not, 3646 however, required for purposes of conformance to this specification 3647 that all non-MN input names must necessarily be rejected. 3649 2.4.16: GSS_Duplicate_name call 3651 Inputs: 3653 o src_name INTERNAL NAME 3655 Outputs: 3657 o major_status INTEGER, 3659 o minor_status INTEGER, 3661 o dest_name INTERNAL NAME -- caller must release 3662 -- with GSS_Release_name() 3663 Return major_status codes: 3665 o GSS_S_COMPLETE indicates that dest_name references an internal 3666 name object containing the same name as passed to src_name. 3668 o GSS_S_BAD_NAME indicates that the input name was invalid. 3670 o GSS_S_FAILURE indicates that the requested operation could not 3671 be performed for reasons unspecified at the GSS-API level. 3673 This routine takes input internal name src_name, and returns another 3674 reference (dest_name) to that name which can be used even if src_name 3675 is later freed. (Note: This may be implemented by copying or through 3676 use of reference counts.) 3678 3: Data Structure Definitions for GSS-V2 Usage 3680 Subsections of this section define, for interoperability and 3681 portability purposes, certain data structures for use with GSS-V2. 3683 3.1: Mechanism-Independent Token Format 3685 This section specifies a mechanism-independent level of encapsulating 3686 representation for the initial token of a GSS-API context 3687 establishment sequence, incorporating an identifier of the mechanism 3688 type to be used on that context and enabling tokens to be interpreted 3689 unambiguously at GSS-API peers. Use of this format is required for 3690 initial context establishment tokens of Internet standards-track 3691 GSS-API mechanisms; use in non-initial tokens is optional. 3693 The encoding format for the token tag is derived from ASN.1 and DER 3694 (per illustrative ASN.1 syntax included later within this 3695 subsection), but its concrete representation is defined directly in 3696 terms of octets rather than at the ASN.1 level in order to facilitate 3697 interoperable implementation without use of general ASN.1 processing 3698 code. The token tag consists of the following elements, in order: 3700 1. 0x60 -- Tag for [APPLICATION 0] SEQUENCE; indicates that 3701 -- constructed form, definite length encoding follows. 3703 2. Token length octets, specifying length of subsequent data 3704 (i.e., the summed lengths of elements 3-5 in this list, and of 3705 the mechanism-defined token object following the tag). 3706 This element comprises a variable number of octets: 3708 2a. If the indicated value is less than 128, it shall be 3709 represented in a single octet with bit 8 (high order) 3710 set to "0" and the remaining bits representing the value. 3712 2b. If the indicated value is 128 or more, it shall be 3713 represented in two or more octets, with bit 8 of the first 3714 octet set to "1" and the remaining bits of the first octet 3715 specifying the number of additional octets. The subsequent 3716 octets carry the value, 8 bits per octet, most significant 3717 digit first. The minimum number of octets shall be used to 3718 encode the length (i.e., no octets representing leading zeros 3719 shall be included within the length encoding). 3721 3. 0x06 -- Tag for OBJECT IDENTIFIER 3723 4. Object identifier length -- length (number of octets) of 3724 -- the encoded object identifier contained in element 5, 3725 -- encoded per rules as described in 2a. and 2b. above. 3727 5. Object identifier octets -- variable number of octets, 3728 -- encoded per ASN.1 BER rules: 3730 5a. The first octet contains the sum of two values: (1) the 3731 top-level object identifier component, multiplied by 40 3732 (decimal), and (2) the second-level object identifier 3733 component. This special case is the only point within an 3734 object identifier encoding where a single octet represents 3735 contents of more than one component. 3737 5b. Subsequent octets, if required, encode successively-lower 3738 components in the represented object identifier. A component's 3739 encoding may span multiple octets, encoding 7 bits per octet 3740 (most significant bits first) and with bit 8 set to "1" on 3741 all but the final octet in the component's encoding. The 3742 minimum number of octets shall be used to encode each component 3743 (i.e., no octets representing leading zeros shall be included 3744 within a component's encoding). 3746 (Note: In many implementations, elements 3-5 may be stored and 3747 referenced as a contiguous string constant.) 3749 The token tag is immediately followed by a mechanism-defined token 3750 object. Note that no independent size specifier intervenes following 3751 the object identifier value to indicate the size of the mechanism- 3752 defined token object. While ASN.1 usage within mechanism-defined 3753 tokens is permitted, there is no requirement that the mechanism- 3754 specific innerContextToken, innerMsgToken, and sealedUserData data 3755 elements must employ ASN.1 BER/DER encoding conventions. 3757 The following ASN.1 syntax is included for descriptive purposes only, 3758 to illustrate structural relationships among token and tag objects. 3759 For interoperability purposes, token and tag encoding shall be 3760 performed using the concrete encoding procedures described earlier in 3761 this subsection. 3763 GSS-API DEFINITIONS ::= 3765 BEGIN 3767 MechType ::= OBJECT IDENTIFIER 3768 -- data structure definitions 3770 -- callers must be able to distinguish among 3771 -- InitialContextToken, SubsequentContextToken, 3772 -- PerMsgToken, and SealedMessage data elements 3773 -- based on the usage in which they occur 3775 InitialContextToken ::= 3776 -- option indication (delegation, etc.) indicated within 3777 -- mechanism-specific token 3778 [APPLICATION 0] IMPLICIT SEQUENCE { 3779 thisMech MechType, 3780 innerContextToken ANY DEFINED BY thisMech 3781 -- contents mechanism-specific 3782 -- ASN.1 structure not required 3783 } 3785 SubsequentContextToken ::= innerContextToken ANY 3786 -- interpretation based on predecessor InitialContextToken 3787 -- ASN.1 structure not required 3789 PerMsgToken ::= 3790 -- as emitted by GSS_GetMIC and processed by GSS_VerifyMIC 3791 -- ASN.1 structure not required 3792 innerMsgToken ANY 3794 SealedMessage ::= 3795 -- as emitted by GSS_Wrap and processed by GSS_Unwrap 3796 -- includes internal, mechanism-defined indicator 3797 -- of whether or not encrypted 3798 -- ASN.1 structure not required 3799 sealedUserData ANY 3801 END 3803 3.2: Mechanism-Independent Exported Name Object Format 3805 This section specifies a mechanism-independent level of encapsulating 3806 representation for names exported via the GSS_Export_name() call, 3807 including an object identifier representing the exporting mechanism. 3808 The format of names encapsulated via this representation shall be 3809 defined within individual mechanism drafts. The Object Identifier 3810 value to indicate names of this type is defined in Section 4.7 of 3811 this document. 3813 No name type OID is included in this mechanism-independent level of 3814 format definition, since (depending on individual mechanism 3815 specifications) the enclosed name may be implicitly typed or may be 3816 explicitly typed using a means other than OID encoding. 3818 The bytes within MECH_OID_LEN and NAME_LEN elements are represented 3819 most significant byte first (equivalently, in IP network byte order). 3821 Length Name Description 3823 2 TOK_ID Token Identifier 3824 For exported name objects, this 3825 must be hex 04 01. 3826 2 MECH_OID_LEN Length of the Mechanism OID 3827 MECH_OID_LEN MECH_OID Mechanism OID, in DER 3828 4 NAME_LEN Length of name 3829 NAME_LEN NAME Exported name; format defined in 3830 applicable mechanism draft. 3832 A concrete example of the contents of an exported name object, 3833 derived from the Kerberos Version 5 mechanism, is as follows: 3835 04 01 00 0B 06 09 2A 86 48 86 F7 12 01 02 02 hx xx xx xl pp qq ... zz 3837 04 01 mandatory token identifier 3839 00 0B 2-byte length of the immediately following DER-encoded 3840 ASN.1 value of type OID, most significant octet first 3842 06 09 2A 86 48 86 F7 12 01 02 02 DER-encoded ASN.1 value 3843 of type OID; Kerberos V5 3844 mechanism OID indicates 3845 Kerberos V5 exported name 3847 in Detail: 06 Identifier octet (6=OID) 3848 09 Length octet(s) 3849 2A 86 48 86 F7 12 01 02 02 Content octet(s) 3851 hx xx xx xl 4-byte length of the immediately following exported 3852 name blob, most significant octet first 3854 pp qq ... zz exported name blob of specified length, 3855 bits and bytes specified in the 3856 (Kerberos 5) GSS-API v2 mechanism spec 3858 4: Name Type Definitions 3860 This section includes definitions for name types and associated 3861 syntaxes which are defined in a mechanism-independent fashion at the 3862 GSS-API level rather than being defined in individual mechanism 3863 specifications. 3865 4.1: Host-Based Service Name Form 3867 This name form shall be represented by the Object Identifier: 3869 {iso(1) member-body(2) United States(840) mit(113554) infosys(1) 3870 "gssapi(2) generic(1) service_name(4)}. 3872 The recommended symbolic name for this type is 3873 "GSS_C_NT_HOSTBASED_SERVICE". 3875 For reasons of compatibility with existing implementations, it is 3876 recommended that this OID be used rather than the alternate value as 3877 included in [RFC-2078]: 3879 {1(iso), 3(org), 6(dod), 1(internet), 5(security), 6(nametypes), 3880 2(gss-host-based-services)} 3882 While it is not recommended that this alternate value be emitted on 3883 output by GSS implementations, it is recommended that it be accepted 3884 on input as equivalent to the recommended value. 3886 This name type is used to represent services associated with host 3887 computers. Support for this name form is recommended to mechanism 3888 designers in the interests of portability, but is not mandated by 3889 this specification. This name form is constructed using two elements, 3890 "service" and "hostname", as follows: 3892 service@hostname 3894 When a reference to a name of this type is resolved, the "hostname" 3895 may (as an example implementation strategy) be canonicalized by 3896 attempting a DNS lookup and using the fully-qualified domain name 3897 which is returned, or by using the "hostname" as provided if the DNS 3898 lookup fails. The canonicalization operation also maps the host's 3899 name into lower-case characters. 3901 The "hostname" element may be omitted. If no "@" separator is 3902 included, the entire name is interpreted as the service specifier, 3903 with the "hostname" defaulted to the canonicalized name of the local 3904 host. 3906 Documents specifying means for GSS integration into a particular 3907 protocol should state either: 3909 (a) that a specific IANA-registered name associated with that 3910 protocol shall be used for the "service" element (this admits, if 3911 needed, the possibility that a single name can be registered and 3912 shared among a related set of protocols), or 3914 (b) that the generic name "host" shall be used for the "service" 3915 element, or 3917 (c) that, for that protocol, fallback in specified order (a, then 3918 b) or (b, then a) shall be applied. 3920 IANA registration of specific names per (a) should be handled in 3921 accordance with the "Specification Required" assignment policy, 3922 defined as of draft-iesg-iana-considerations-02 as follows: "Values 3923 and their meaning must be documented in an RFC or other available 3924 reference, in sufficient detail so that interoperability between 3925 independent implementations is possible." 3927 4.2: User Name Form 3929 This name form shall be represented by the Object Identifier {iso(1) 3930 member-body(2) United States(840) mit(113554) infosys(1) gssapi(2) 3931 generic(1) user_name(1)}. The recommended mechanism-independent 3932 symbolic name for this type is "GSS_C_NT_USER_NAME". (Note: the same 3933 name form and OID is defined within the Kerberos V5 GSS-API 3934 mechanism, but the symbolic name recommended there begins with a 3935 "GSS_KRB5_NT_" prefix.) 3937 This name type is used to indicate a named user on a local system. 3938 Its syntax and interpretation may be OS-specific. This name form is 3939 constructed as: 3941 username 3943 4.3: Machine UID Form 3945 This name form shall be represented by the Object Identifier {iso(1) 3946 member-body(2) United States(840) mit(113554) infosys(1) gssapi(2) 3947 generic(1) machine_uid_name(2)}. The recommended mechanism- 3948 independent symbolic name for this type is 3949 "GSS_C_NT_MACHINE_UID_NAME". (Note: the same name form and OID is 3950 defined within the Kerberos V5 GSS-API mechanism, but the symbolic 3951 name recommended there begins with a "GSS_KRB5_NT_" prefix.) 3953 This name type is used to indicate a numeric user identifier 3954 corresponding to a user on a local system. Its interpretation is 3955 OS-specific. The gss_buffer_desc representing a name of this type 3956 should contain a locally-significant user ID, represented in host 3957 byte order. The GSS_Import_name() operation resolves this uid into a 3958 username, which is then treated as the User Name Form. 3960 4.4: String UID Form 3962 This name form shall be represented by the Object Identifier {iso(1) 3963 member-body(2) United States(840) mit(113554) infosys(1) gssapi(2) 3964 generic(1) string_uid_name(3)}. The recommended symbolic name for 3965 this type is "GSS_C_NT_STRING_UID_NAME". (Note: the same name form 3966 and OID is defined within the Kerberos V5 GSS-API mechanism, but the 3967 symbolic name recommended there begins with a "GSS_KRB5_NT_" prefix.) 3969 This name type is used to indicate a string of digits representing 3970 the numeric user identifier of a user on a local system. Its 3971 interpretation is OS-specific. This name type is similar to the 3972 Machine UID Form, except that the buffer contains a string 3973 representing the user ID. 3975 4.5: Anonymous Nametype 3977 The following Object Identifier value is provided as a means to 3978 identify anonymous names, and can be compared against in order to 3979 determine, in a mechanism-independent fashion, whether a name refers 3980 to an anonymous principal: 3982 {1(iso), 3(org), 6(dod), 1(internet), 5(security), 6(nametypes), 3983 3(gss-anonymous-name)} 3985 The recommended symbolic name corresponding to this definition is 3986 GSS_C_NT_ANONYMOUS. 3988 4.6: GSS_C_NO_OID 3990 The recommended symbolic name GSS_C_NO_OID corresponds to a null 3991 input value instead of an actual object identifier. Where specified, 3992 it indicates interpretation of an associated name based on a 3993 mechanism-specific default printable syntax. 3995 4.7: Exported Name Object 3997 Name objects of the Mechanism-Independent Exported Name Object type, 3998 as defined in Section 3.2 of this document, will be identified with 3999 the following Object Identifier: 4001 {1(iso), 3(org), 6(dod), 1(internet), 5(security), 6(nametypes), 4002 4(gss-api-exported-name)} 4004 The recommended symbolic name corresponding to this definition is 4005 GSS_C_NT_EXPORT_NAME. 4007 4.8: GSS_C_NO_NAME 4009 The recommended symbolic name GSS_C_NO_NAME indicates that no name is 4010 being passed within a particular value of a parameter used for the 4011 purpose of transferring names. Note: GSS_C_NO_NAME is not an actual 4012 name type, and is not represented by an OID; its acceptability in 4013 lieu of an actual name is confined to specific calls 4014 (GSS_Acquire_cred(), GSS_Add_cred(), and GSS_Init_sec_context()) with 4015 usages as identified within this specification. 4017 5: Mechanism-Specific Example Scenarios 4019 This section provides illustrative overviews of the use of various 4020 candidate mechanism types to support the GSS-API. These discussions 4021 are intended primarily for readers familiar with specific security 4022 technologies, demonstrating how GSS-API functions can be used and 4023 implemented by candidate underlying mechanisms. They should not be 4024 regarded as constrictive to implementations or as defining the only 4025 means through which GSS-API functions can be realized with a 4026 particular underlying technology, and do not demonstrate all GSS-API 4027 features with each technology. 4029 5.1: Kerberos V5, single-TGT 4031 OS-specific login functions yield a TGT to the local realm Kerberos 4032 server; TGT is placed in a credentials structure for the client. 4033 Client calls GSS_Acquire_cred() to acquire a cred_handle in order to 4034 reference the credentials for use in establishing security contexts. 4036 Client calls GSS_Init_sec_context(). If the requested service is 4037 located in a different realm, GSS_Init_sec_context() gets the 4038 necessary TGT/key pairs needed to traverse the path from local to 4039 target realm; these data are placed in the owner's TGT cache. After 4040 any needed remote realm resolution, GSS_Init_sec_context() yields a 4041 service ticket to the requested service with a corresponding session 4042 key; these data are stored in conjunction with the context. GSS-API 4043 code sends KRB_TGS_REQ request(s) and receives KRB_TGS_REP 4044 response(s) (in the successful case) or KRB_ERROR. 4046 Assuming success, GSS_Init_sec_context() builds a Kerberos-formatted 4047 KRB_AP_REQ message, and returns it in output_token. The client sends 4048 the output_token to the service. 4050 The service passes the received token as the input_token argument to 4051 GSS_Accept_sec_context(), which verifies the authenticator, provides 4052 the service with the client's authenticated name, and returns an 4053 output_context_handle. 4055 Both parties now hold the session key associated with the service 4056 ticket, and can use this key in subsequent GSS_GetMIC(), 4057 GSS_VerifyMIC(), GSS_Wrap(), and GSS_Unwrap() operations. 4059 5.2: Kerberos V5, double-TGT 4061 TGT acquisition as above. 4063 Note: To avoid unnecessary frequent invocations of error paths when 4064 implementing the GSS-API atop Kerberos V5, it seems appropriate to 4065 represent "single-TGT K-V5" and "double-TGT K-V5" with separate 4066 mech_types, and this discussion makes that assumption. 4068 Based on the (specified or defaulted) mech_type, 4069 GSS_Init_sec_context() determines that the double-TGT protocol 4070 should be employed for the specified target. GSS_Init_sec_context() 4071 returns GSS_S_CONTINUE_NEEDED major_status, and its returned 4072 output_token contains a request to the service for the service's TGT. 4073 (If a service TGT with suitably long remaining lifetime already 4074 exists in a cache, it may be usable, obviating the need for this 4075 step.) The client passes the output_token to the service. Note: this 4076 scenario illustrates a different use for the GSS_S_CONTINUE_NEEDED 4077 status return facility than for support of mutual authentication; 4078 note that both uses can coexist as successive operations within a 4079 single context establishment operation. 4081 The service passes the received token as the input_token argument to 4082 GSS_Accept_sec_context(), which recognizes it as a request for TGT. 4083 (Note that current Kerberos V5 defines no intra-protocol mechanism to 4084 represent such a request.) GSS_Accept_sec_context() returns 4085 GSS_S_CONTINUE_NEEDED major_status and provides the service's TGT in 4086 its output_token. The service sends the output_token to the client. 4088 The client passes the received token as the input_token argument to a 4089 continuation of GSS_Init_sec_context(). GSS_Init_sec_context() caches 4090 the received service TGT and uses it as part of a service ticket 4091 request to the Kerberos authentication server, storing the returned 4092 service ticket and session key in conjunction with the context. 4093 GSS_Init_sec_context() builds a Kerberos-formatted authenticator, and 4094 returns it in output_token along with GSS_S_COMPLETE return 4095 major_status. The client sends the output_token to the service. 4097 Service passes the received token as the input_token argument to a 4098 continuation call to GSS_Accept_sec_context(). 4099 GSS_Accept_sec_context() verifies the authenticator, provides the 4100 service with the client's authenticated name, and returns 4101 major_status GSS_S_COMPLETE. 4103 GSS_GetMIC(), GSS_VerifyMIC(), GSS_Wrap(), and GSS_Unwrap() as 4104 above. 4106 5.3: X.509 Authentication Framework 4108 This example illustrates use of the GSS-API in conjunction with 4109 public-key mechanisms, consistent with the X.509 Directory 4110 Authentication Framework. 4112 The GSS_Acquire_cred() call establishes a credentials structure, 4113 making the client's private key accessible for use on behalf of the 4114 client. 4116 The client calls GSS_Init_sec_context(), which interrogates the 4117 Directory to acquire (and validate) a chain of public-key 4118 certificates, thereby collecting the public key of the service. The 4119 certificate validation operation determines that suitable integrity 4120 checks were applied by trusted authorities and that those 4121 certificates have not expired. GSS_Init_sec_context() generates a 4122 secret key for use in per-message protection operations on the 4123 context, and enciphers that secret key under the service's public 4124 key. 4126 The enciphered secret key, along with an authenticator quantity 4127 signed with the client's private key, is included in the output_token 4128 from GSS_Init_sec_context(). The output_token also carries a 4129 certification path, consisting of a certificate chain leading from 4130 the service to the client; a variant approach would defer this path 4131 resolution to be performed by the service instead of being asserted 4132 by the client. The client application sends the output_token to the 4133 service. 4135 The service passes the received token as the input_token argument to 4136 GSS_Accept_sec_context(). GSS_Accept_sec_context() validates the 4137 certification path, and as a result determines a certified binding 4138 between the client's distinguished name and the client's public key. 4139 Given that public key, GSS_Accept_sec_context() can process the 4140 input_token's authenticator quantity and verify that the client's 4141 private key was used to sign the input_token. At this point, the 4142 client is authenticated to the service. The service uses its private 4143 key to decipher the enciphered secret key provided to it for per- 4144 message protection operations on the context. 4146 The client calls GSS_GetMIC() or GSS_Wrap() on a data message, which 4147 causes per-message authentication, integrity, and (optional) 4148 confidentiality facilities to be applied to that message. The service 4149 uses the context's shared secret key to perform corresponding 4150 GSS_VerifyMIC() and GSS_Unwrap() calls. 4152 6: Security Considerations 4154 Security issues are discussed throughout this memo. 4156 7: Related Activities 4158 In order to implement the GSS-API atop existing, emerging, and future 4159 security mechanisms: 4161 object identifiers must be assigned to candidate GSS-API 4162 mechanisms and the name types which they support 4164 concrete data element formats and processing procedures must be 4165 defined for candidate mechanisms 4167 Calling applications must implement formatting conventions which will 4168 enable them to distinguish GSS-API tokens from other data carried in 4169 their application protocols. 4171 Concrete language bindings are required for the programming 4172 environments in which the GSS-API is to be employed, as [RFC-1509] 4173 defines for the C programming language and GSS-V1. 4175 8: Referenced Documents 4177 [ISO-7498-2] International Standard ISO 7498-2-1988(E), Security 4178 Architecture. 4180 [ISOIEC-8824] ISO/IEC 8824, "Specification of Abstract Syntax 4181 Notation One (ASN.1)". 4183 [ISOIEC-8825] ISO/IEC 8825, "Specification of Basic Encoding Rules 4184 for Abstract Syntax Notation One (ASN.1)".) 4186 [RFC-1507]: C. Kaufman, "DASS: Distributed Authentication Security 4187 Service", RFC 1507. 4189 [RFC-1508]: J. Linn, "Generic Security Service Application Program 4190 Interface", RFC 1508. 4192 [RFC-1509]: J. Wray, "Generic Security Service API: C-bindings", RFC 4193 1509. 4195 [RFC-1964]: J. Linn, "The Kerberos Version 5 GSS-API Mechanism", RFC 4196 1964. 4198 [RFC-2025]: C. Adams, "The Simple Public-Key GSS-API Mechanism 4199 (SPKM)", RFC 2025. 4201 [RFC-2078]: J. Linn, "Generic Security Service Application Program 4202 Interface, Version 2", RFC 2078. 4204 [RFC-2203]: M. Eisler, A. Chiu, L. Ling, "RPCSEC_GSS Protocol 4205 Specification", RFC 2203. 4207 APPENDIX A 4209 MECHANISM DESIGN CONSTRAINTS 4211 The following constraints on GSS-API mechanism designs are adopted in 4212 response to observed caller protocol requirements, and adherence thereto 4213 is anticipated in subsequent descriptions of GSS-API mechanisms to be 4214 documented in standards-track Internet specifications. 4216 It is strongly recommended that mechanisms offering per-message 4217 protection services also offer at least one of the replay detection and 4218 sequencing services, as mechanisms offering neither of the latter will 4219 fail to satisfy recognized requirements of certain candidate caller 4220 protocols. 4222 APPENDIX B 4224 COMPATIBILITY WITH GSS-V1 4226 It is the intent of this document to define an interface and procedures 4227 which preserve compatibility between GSS-V1 [RFC-1508] callers and GSS- 4228 V2 providers. All calls defined in GSS-V1 are preserved, and it has 4229 been a goal that GSS-V1 callers should be able to operate atop GSS-V2 4230 provider implementations. Certain detailed changes, summarized in this 4231 section, have been made in order to resolve omissions identified in 4232 GSS-V1. 4234 The following GSS-V1 constructs, while supported within GSS-V2, are 4235 deprecated: 4237 Names for per-message processing routines: GSS_Seal() deprecated in 4238 favor of GSS_Wrap(); GSS_Sign() deprecated in favor of 4239 GSS_GetMIC(); GSS_Unseal() deprecated in favor of GSS_Unwrap(); 4240 GSS_Verify() deprecated in favor of GSS_VerifyMIC(). 4242 GSS_Delete_sec_context() facility for context_token usage, allowing 4243 mechanisms to signal context deletion, is retained for 4244 compatibility with GSS-V1. For current usage, it is recommended 4245 that both peers to a context invoke GSS_Delete_sec_context() 4246 independently, passing a null output_context_token buffer to 4247 indicate that no context_token is required. Implementations of 4248 GSS_Delete_sec_context() should delete relevant locally-stored 4249 context information. 4251 This GSS-V2 specification adds the following calls which are not present 4252 in GSS-V1: 4254 Credential management calls: GSS_Add_cred(), 4255 GSS_Inquire_cred_by_mech(). 4257 Context-level calls: GSS_Inquire_context(), GSS_Wrap_size_limit(), 4258 GSS_Export_sec_context(), GSS_Import_sec_context(). 4260 Per-message calls: No new calls. Existing calls have been renamed. 4262 Support calls: GSS_Create_empty_OID_set(), 4263 GSS_Add_OID_set_member(), GSS_Test_OID_set_member(), 4264 GSS_Inquire_names_for_mech(), GSS_Inquire_mechs_for_name(), 4265 GSS_Canonicalize_name(), GSS_Export_name(), GSS_Duplicate_name(). 4267 This GSS-V2 specification introduces three new facilities applicable to 4268 security contexts, indicated using the following context state values 4269 which are not present in GSS-V1: 4271 anon_state, set TRUE to indicate that a context's initiator is 4272 anonymous from the viewpoint of the target; Section 1.2.5 of this 4273 specification provides a summary description of the GSS-V2 4274 anonymity support facility, support and use of which is optional. 4276 prot_ready_state, set TRUE to indicate that a context may be used 4277 for per-message protection before final completion of context 4278 establishment; Section 1.2.7 of this specification provides a 4279 summary description of the GSS-V2 facility enabling mechanisms to 4280 selectively permit per-message protection during context 4281 establishment, support and use of which is optional. 4283 trans_state, set TRUE to indicate that a context is transferable to 4284 another process using the GSS-V2 GSS_Export_sec_context() facility. 4286 These state values are represented (at the C bindings level) in 4287 positions within a bit vector which are unused in GSS-V1, and may be 4288 safely ignored by GSS-V1 callers. 4290 Relative to GSS-V1, GSS-V2 provides additional guidance to GSS-API 4291 implementors in the following areas: implementation robustness, 4292 credential management, behavior in multi-mechanism configurations, 4293 naming support, and inclusion of optional sequencing services. The 4294 token tagging facility as defined in GSS-V2, Section 3.1, is now 4295 described directly in terms of octets to facilitate interoperable 4296 implementation without general ASN.1 processing code; the corresponding 4297 ASN.1 syntax, included for descriptive purposes, is unchanged from that 4298 in GSS-V1. For use in conjunction with added naming support facilities, 4299 a new Exported Name Object construct is added. Additional name types 4300 are introduced in Section 4. 4302 This GSS-V2 specification adds the following major_status values which 4303 are not defined in GSS-V1: 4305 GSS_S_BAD_QOP unsupported QOP value 4306 GSS_S_UNAUTHORIZED operation unauthorized 4307 GSS_S_UNAVAILABLE operation unavailable 4308 GSS_S_DUPLICATE_ELEMENT duplicate credential element 4309 requested 4310 GSS_S_NAME_NOT_MN name contains multi-mechanism 4311 elements 4312 GSS_S_GAP_TOKEN skipped predecessor token(s) 4313 detected 4315 Of these added status codes, only two values are defined to be 4316 returnable by calls existing in GSS-V1: GSS_S_BAD_QOP (returnable by 4317 GSS_GetMIC() and GSS_Wrap()), and GSS_S_GAP_TOKEN (returnable by 4318 GSS_VerifyMIC() and GSS_Unwrap()). 4320 Additionally, GSS-V2 descriptions of certain calls present in GSS-V1 4321 have been updated to allow return of additional major_status values from 4322 the set as defined in GSS-V1: GSS_Inquire_cred() has 4323 GSS_S_DEFECTIVE_CREDENTIAL and GSS_S_CREDENTIALS_EXPIRED defined as 4324 returnable, GSS_Init_sec_context() has GSS_S_OLD_TOKEN, 4325 GSS_S_DUPLICATE_TOKEN, and GSS_S_BAD_MECH defined as returnable, and 4326 GSS_Accept_sec_context() has GSS_S_BAD_MECH defined as returnable. 4328 APPENDIX C 4330 CHANGES RELATIVE TO RFC-2078 4332 This document incorporates a number of changes relative to RFC-2078, 4333 made primarily in response to implementation experience, for purposes of 4334 alignment with the GSS-V2 C language bindings document, and to add 4335 informative clarification. This section summarizes technical changes 4336 incorporated. 4338 General: 4340 Clarified usage of object release routines, and incorporated 4341 statement that some may be omitted within certain operating 4342 environments. 4344 Removed GSS_Release_OID, GSS_OID_to_str(), and GSS_Str_to_OID() 4345 routines. 4347 Clarified circumstances under which zero-length tokens may validly 4348 exist as inputs and outputs to/from GSS-API calls. 4350 Added GSS_S_BAD_MIC status code as alias for GSS_S_BAD_SIG. 4352 For GSS_Display_status(), deferred to language bindings the choice 4353 of whether to return multiple status values in parallel or via 4354 iteration, and added commentary deprecating return of 4355 GSS_S_CONTINUE_NEEDED. 4357 Adapted and incorporated clarifying material on optional service 4358 support, delegation, and interprocess context transfer from C 4359 bindings document. 4361 Added and updated references to related documents, and to current 4362 status of cited Kerberos mechanism OID. 4364 Added general statement about GSS-API calls having no side effects 4365 visible at the GSS-API level. 4367 Context-related (including per-message protection issues): 4369 Clarified GSS_Delete_sec_context() usage for partially-established 4370 contexts. 4372 Added clarification on GSS_Export_sec_context() and 4373 GSS_Import_sec_context() behavior and context usage following an 4374 export-import sequence. 4376 Added informatory conf_req, integ_req inputs to 4377 GSS_Init_sec_context(). 4379 Stated that GSS_S_FAILURE is to be returned if 4380 GSS_Init_sec_context() or GSS_Accept_sec_context() is passed the 4381 handle of a context which is already fully established. 4383 Re GSS_Inquire_sec_context(), stated that src_name and targ_name 4384 are not returned until GSS_S_COMPLETE status is reached; removed 4385 use of GSS_S_CONTEXT_EXPIRED status code (replacing with EXPIRED 4386 lifetime return value); stated requirement to retain inquirable 4387 data until context released by caller; added result value 4388 indicating whether or not context is fully open. 4390 Added discussion of interoperability conditions for mechanisms 4391 permitting optional support of QOPs. Removed reference to 4392 structured QOP elements in GSS_Verify_MIC(). 4394 Added discussion of use of GSS_S_DUPLICATE_TOKEN status to indicate 4395 reflected per-message tokens. 4397 Clarified use of informational sequencing codes from per-message 4398 protection calls in conjunction with GSS_S_COMPLETE and 4399 GSS_S_FAILURE major_status returns, adjusting status code 4400 descriptions accordingly. 4402 Added specific statements about impact of GSS_GetMIC() and 4403 GSS_Wrap() failures on context state information, and generalized 4404 existing statements about impact of processing failures on received 4405 per-message tokens. 4407 For GSS_Init_sec_context() and GSS_Accept_sec_context(), permitted 4408 returned mech_type to be valid before GSS_S_COMPLETE, recognizing 4409 that the value may change on successive continuation calls in the 4410 negotiated mechanism case. 4412 Deleted GSS_S_CONTEXT_EXPIRED status from GSS_Import_sec_context(). 4414 Added conf_req_flag input to GSS_Wrap_size_limit(). 4416 Stated requirement for mechanisms' support of per-message 4417 protection services to be usable concurrently in both directions on 4418 a context. 4420 Credential-related: 4422 For GSS_Acquire_cred() and GSS_Add_cred(), aligned with C bindings 4423 statement of likely non-support for INITIATE or BOTH credentials if 4424 input name is neither empty nor a name resulting from applying 4425 GSS_Inquire_cred() against the default credential. Further, stated 4426 that an explicit name returned by GSS_Inquire_context() should also 4427 be accepted. Added commentary about potentially time-variant 4428 results of default resolution and attendant implications. Aligned 4429 with C bindings re behavior when GSS_C_NO_NAME provided for 4430 desired_name. 4432 Added GSS_S_CREDENTIALS_EXPIRED as returnable major_status for 4433 GSS_Acquire_cred(), GSS_Add_cred(), also specifying GSS_S_NO_CRED 4434 as appropriate return for temporary, user-fixable credential 4435 unavailability. GSS_Acquire_cred() and GSS_Add_cred() are also to 4436 return GSS_S_NO_CRED if an authorization failure is encountered 4437 upon credential acquisition. 4439 Removed GSS_S_CREDENTIALS_EXPIRED status return from per-message 4440 protection, GSS_Context_time(), and GSS_Inquire_context() calls. 4442 For GSS_Add_cred(), aligned with C bindings' description of 4443 behavior when addition of elements to the default credential is 4444 requested. 4446 Upgraded recommended default credential resolution algorithm to 4447 status of requirement for initiator credentials. 4449 For GSS_Release_cred(), GSS_Inquire_cred(), and 4450 GSS_Inquire_cred_by_mech(), clarified behavior for input 4451 GSS_C_NO_CREDENTIAL. 4453 Name-related: 4455 Aligned GSS_Inquire_mechs_for_name() description with C bindings. 4457 Removed GSS_S_BAD_NAMETYPE status return from GSS_Duplicate_name(), 4458 GSS_Display_name(); constrained its applicability for 4459 GSS_Compare_name(). 4461 Aligned with C bindings statement re GSS_Import_name() behavior 4462 with GSS_C_NO_OID input name type, and stated that GSS-V2 mechanism 4463 specifications are to define processing procedures applicable to 4464 their mechanisms. Also clarified GSS_C_NO_OID usage with 4465 GSS_Display_name(). 4467 Downgraded reference to name canonicalization via DNS lookup to an 4468 example. 4470 For GSS_Canonicalize_name(), stated that neither negotiated 4471 mechanisms nor the default mechanism are supported input mech_types 4472 for this operation, and specified GSS_S_BAD_MECH status to be 4473 returned in this case. Clarified that the GSS_Canonicalize_name() 4474 operation is non-destructive to its input name. 4476 Clarified semantics of GSS_C_NT_USER_NAME name type. 4478 Added descriptions of additional name types. Also added discussion 4479 of GSS_C_NO_NAME and its constrained usage with specific GSS calls. 4481 Adapted and incorporated C bindings discussion about name 4482 comparisons with exported name objects. 4484 Added recommendation to mechanism designers for support of host- 4485 based service name type, deferring any requirement statement to 4486 individual mechanism specifications. Added discussion of host- 4487 based service's service name element and proposed approach for IANA 4488 registration policy therefor. 4490 Clarified byte ordering within exported name object. Stated that 4491 GSS_S_BAD_MECH is to be returned if, in the course of attempted 4492 import of an exported name object, the name object's enclosed 4493 mechanism type is unrecognized or unsupported. 4495 Stated that mechanisms may optionally accept GSS_C_NO_NAME as an 4496 input target name to GSS_Init_sec_context(), with comment that such 4497 support is unlikely within mechanisms predating GSS-V2, Update 1. 4499 AUTHOR'S ADDRESS 4501 John Linn 4502 RSA Laboratories East 4503 20 Crosby Drive 4504 Bedford, MA 01730 USA 4505 +1 781.687.7817 4507 E-mail: linn@rsa.com 4508 TABLE OF CONTENTS 4510 1: GSS-API Characteristics and Concepts 4511 1.1: GSS-API Constructs 4512 1.1.1: Credentials 4513 1.1.1.1: Credential Constructs and Concepts 4514 1.1.1.2: Credential Management 4515 1.1.1.3: Default Credential Resolution 4516 1.1.2: Tokens 4517 1.1.3: Security Contexts 4518 1.1.4: Mechanism Types 4519 1.1.5: Naming 4520 1.1.6: Channel Bindings 4521 1.2: GSS-API Features and Issues 4522 1.2.1: Status Reporting 4523 1.2.2: Per-Message Security Service Availability 4524 1.2.3: Per-Message Replay Detection and Sequencing 4525 1.2.4: Quality of Protection 4526 1.2.5: Anonymity Support 4527 1.2.6: Initialization 4528 1.2.7: Per-Message Protection During Context Establishment 4529 1.2.8: Implementation Robustness 4530 2: Interface Descriptions 4531 2.1: Credential management calls 4532 2.1.1: GSS_Acquire_cred call 4533 2.1.2: GSS_Release_cred call 4534 2.1.3: GSS_Inquire_cred call 4535 2.1.4: GSS_Add_cred call 4536 2.1.5: GSS_Inquire_cred_by_mech call 4537 2.2: Context-level calls 4538 2.2.1: GSS_Init_sec_context call 4539 2.2.2: GSS_Accept_sec_context call 4540 2.2.3: GSS_Delete_sec_context call 4541 2.2.4: GSS_Process_context_token call 4542 2.2.5: GSS_Context_time call 4543 2.2.6: GSS_Inquire_context call 4544 2.2.7: GSS_Wrap_size_limit call 4545 2.2.8: GSS_Export_sec_context call 4546 2.2.9: GSS_Import_sec_context call 4547 2.3: Per-message calls 4548 2.3.1: GSS_GetMIC call 4549 2.3.2: GSS_VerifyMIC call 4550 2.3.3: GSS_Wrap call 4551 2.3.4: GSS_Unwrap call 4552 2.4: Support calls 4553 2.4.1: GSS_Display_status call 4554 2.4.2: GSS_Indicate_mechs call 4555 2.4.3: GSS_Compare_name call 4556 2.4.4: GSS_Display_name call 4557 2.4.5: GSS_Import_name call 4558 2.4.6: GSS_Release_name call 4559 2.4.7: GSS_Release_buffer call 4560 2.4.8: GSS_Release_OID_set call 4561 2.4.9: GSS_Create_empty_OID_set call 4562 2.4.10: GSS_Add_OID_set_member call 4563 2.4.11: GSS_Test_OID_set_member call 4564 2.4.12: GSS_Inquire_names_for_mech call 4565 2.4.13: GSS_Inquire_mechs_for_name call 4566 2.4.14: GSS_Canonicalize_name call 4567 2.4.15: GSS_Export_name call 4568 2.4.16: GSS_Duplicate_name call 4569 3: Data Structure Definitions for GSS-V2 Usage 4570 3.1: Mechanism-Independent Token Format 4571 3.2: Mechanism-Independent Exported Name Object Format 4572 4: Name Type Definitions 4573 4.1: Host-Based Service Name Form 4574 4.2: User Name Form 4575 4.3: Machine UID Form 4576 4.4: String UID Form 4577 5: Mechanism-Specific Example Scenarios 4578 5.1: Kerberos V5, single-TGT 4579 5.2: Kerberos V5, double-TGT 4580 5.3: X.509 Authentication Framework 4581 6: Security Considerations 4582 7: Related Activities 4583 8: Referenced Documents 4584 Appendix A: Mechanism Design Constraints 4585 Appendix B: Compatibility with GSS-V1 4586 Appendix C: Changes Relative to RFC-2078