idnits 2.17.1 draft-ietf-cat-rfc2078bis-02.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-19) 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 93 longer pages, the longest (page 5) being 64 lines == It seems as if not all pages are separated by form feeds - found 0 form feeds but 94 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 1217 has weird spacing: '...t_token pro...' == Line 1255 has weird spacing: '...or_mech indi...' == Line 1257 has weird spacing: '...or_name indi...' == Line 3811 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 (29 January 1998) is 9577 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 4134 looks like a reference -- Missing reference section? 'ISO-7498-2' on line 4110 looks like a reference -- Missing reference section? 'RFC-1964' on line 4128 looks like a reference -- Missing reference section? 'RFC-2025' on line 4131 looks like a reference -- Missing reference section? 'RFC-2203' on line 4137 looks like a reference -- Missing reference section? 'ISOIEC-8825' on line 4116 looks like a reference -- Missing reference section? 'ISOIEC-8824' on line 4113 looks like a reference -- Missing reference section? 'RFC-1507' on line 4119 looks like a reference -- Missing reference section? 'APPLICATION 0' on line 3735 looks like a reference -- Missing reference section? 'RFC-1509' on line 4125 looks like a reference -- Missing reference section? 'RFC-1508' on line 4160 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 29 January 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 learn the current status of any Internet-Draft, please check the 22 ``1id-abstracts.txt'' listing contained in the Internet- Drafts 23 Shadow Directories on ds.internic.net (US East Coast), nic.nordu.net 24 (Europe), ftp.isi.edu (US West Coast), or munnari.oz.au (Pacific 25 Rim). 27 Comments on this document should be sent to "cat-ietf@mit.edu", the 28 IETF Common Authentication Technology WG discussion list. 30 ABSTRACT 32 The Generic Security Service Application Program Interface (GSS-API), 33 Version 2, as defined in [RFC-2078], provides security services to 34 callers in a generic fashion, supportable with a range of underlying 35 mechanisms and technologies and hence allowing source-level 36 portability of applications to different environments. This 37 specification defines GSS-API services and primitives at a level 38 independent of underlying mechanism and programming language 39 environment, and is to be complemented by other, related 40 specifications: 42 documents defining specific parameter bindings for particular 43 language environments 45 documents defining token formats, protocols, and procedures to be 46 implemented in order to realize GSS-API services atop particular 47 security mechanisms 49 This Internet-Draft revises [RFC-2078], making specific, incremental 50 changes in response to implementation experience and liaison 51 requests. It is intended, therefore, that this draft or a successor 52 version thereto will become the basis for subsequent progression of 53 the GSS-API specification on the standards track. 55 1: GSS-API Characteristics and Concepts 57 GSS-API operates in the following paradigm. A typical GSS-API caller 58 is itself a communications protocol, calling on GSS-API in order to 59 protect its communications with authentication, integrity, and/or 60 confidentiality security services. A GSS-API caller accepts tokens 61 provided to it by its local GSS-API implementation and transfers the 62 tokens to a peer on a remote system; that peer passes the received 63 tokens to its local GSS-API implementation for processing. The 64 security services available through GSS-API in this fashion are 65 implementable (and have been implemented) over a range of underlying 66 mechanisms based on secret-key and public-key cryptographic 67 technologies. 69 The GSS-API separates the operations of initializing a security 70 context between peers, achieving peer entity authentication 71 (GSS_Init_sec_context() and GSS_Accept_sec_context() calls), from the 72 operations of providing per-message data origin authentication and 73 data integrity protection (GSS_GetMIC() and GSS_VerifyMIC() calls) 74 for messages subsequently transferred in conjunction with that 75 context. (The definition for the peer entity authentication service, 76 and other definitions used in this document, corresponds to that 77 provided in [ISO-7498-2].) When establishing a security context, the 78 GSS-API enables a context initiator to optionally permit its 79 credentials to be delegated, meaning that the context acceptor may 80 initiate further security contexts on behalf of the initiating 81 caller. Per-message GSS_Wrap() and GSS_Unwrap() calls provide the 82 data origin authentication and data integrity services which 83 GSS_GetMIC() and GSS_VerifyMIC() offer, and also support selection of 84 confidentiality services as a caller option. Additional calls provide 85 supportive functions to the GSS-API's users. 87 The following paragraphs provide an example illustrating the 88 dataflows involved in use of the GSS-API by a client and server in a 89 mechanism-independent fashion, establishing a security context and 90 transferring a protected message. The example assumes that credential 91 acquisition has already been completed. The example also assumes 92 that the underlying authentication technology is capable of 93 authenticating a client to a server using elements carried within a 94 single token, and of authenticating the server to the client (mutual 95 authentication) with a single returned token; this assumption holds 96 for some presently-documented CAT mechanisms but is not necessarily 97 true for other cryptographic technologies and associated protocols. 99 The client calls GSS_Init_sec_context() to establish a security 100 context to the server identified by targ_name, and elects to set the 101 mutual_req_flag so that mutual authentication is performed in the 102 course of context establishment. GSS_Init_sec_context() returns an 103 output_token to be passed to the server, and indicates 104 GSS_S_CONTINUE_NEEDED status pending completion of the mutual 105 authentication sequence. Had mutual_req_flag not been set, the 106 initial call to GSS_Init_sec_context() would have returned 107 GSS_S_COMPLETE status. The client sends the output_token to the 108 server. 110 The server passes the received token as the input_token parameter to 111 GSS_Accept_sec_context(). GSS_Accept_sec_context indicates 112 GSS_S_COMPLETE status, provides the client's authenticated identity 113 in the src_name result, and provides an output_token to be passed to 114 the client. The server sends the output_token to the client. 116 The client passes the received token as the input_token parameter to 117 a successor call to GSS_Init_sec_context(), which processes data 118 included in the token in order to achieve mutual authentication from 119 the client's viewpoint. This call to GSS_Init_sec_context() returns 120 GSS_S_COMPLETE status, indicating successful mutual authentication 121 and the completion of context establishment for this example. 123 The client generates a data message and passes it to GSS_Wrap(). 124 GSS_Wrap() performs data origin authentication, data integrity, and 125 (optionally) confidentiality processing on the message and 126 encapsulates the result into output_message, indicating 127 GSS_S_COMPLETE status. The client sends the output_message to the 128 server. 130 The server passes the received message to GSS_Unwrap(). GSS_Unwrap() 131 inverts the encapsulation performed by GSS_Wrap(), deciphers the 132 message if the optional confidentiality feature was applied, and 133 validates the data origin authentication and data integrity checking 134 quantities. GSS_Unwrap() indicates successful validation by returning 135 GSS_S_COMPLETE status along with the resultant output_message. 137 For purposes of this example, we assume that the server knows by 138 out-of-band means that this context will have no further use after 139 one protected message is transferred from client to server. Given 140 this premise, the server now calls GSS_Delete_sec_context() to flush 141 context-level information. Optionally, the server-side application 142 may provide a token buffer to GSS_Delete_sec_context(), to receive a 143 context_token to be transferred to the client in order to request 144 that client-side context-level information be deleted. 146 If a context_token is transferred, the client passes the 147 context_token to GSS_Process_context_token(), which returns 148 GSS_S_COMPLETE status after deleting context-level information at the 149 client system. 151 The GSS-API design assumes and addresses several basic goals, 152 including: 154 Mechanism independence: The GSS-API defines an interface to 155 cryptographically implemented strong authentication and other 156 security services at a generic level which is independent of 157 particular underlying mechanisms. For example, GSS-API-provided 158 services have been implemented using secret-key technologies 159 (e.g., Kerberos, per [RFC-1964]) and with public-key approaches 160 (e.g., SPKM, per [RFC-2025]). 162 Protocol environment independence: The GSS-API is independent of 163 the communications protocol suites with which it is employed, 164 permitting use in a broad range of protocol environments. In 165 appropriate environments, an intermediate implementation "veneer" 166 which is oriented to a particular communication protocol may be 167 interposed between applications which call that protocol and the 168 GSS-API (e.g., as defined in [RFC-2203] for Open Network Computing 169 Remote Procedure Call (RPC)), thereby invoking GSS-API facilities 170 in conjunction with that protocol's communications invocations. 172 Protocol association independence: The GSS-API's security context 173 construct is independent of communications protocol association 174 constructs. This characteristic allows a single GSS-API 175 implementation to be utilized by a variety of invoking protocol 176 modules on behalf of those modules' calling applications. GSS-API 177 services can also be invoked directly by applications, wholly 178 independent of protocol associations. 180 Suitability to a range of implementation placements: GSS-API 181 clients are not constrained to reside within any Trusted Computing 182 Base (TCB) perimeter defined on a system where the GSS-API is 183 implemented; security services are specified in a manner suitable 184 to both intra-TCB and extra-TCB callers. 186 1.1: GSS-API Constructs 188 This section describes the basic elements comprising the GSS-API. 190 1.1.1: Credentials 192 1.1.1.1: Credential Constructs and Concepts 194 Credentials provide the prerequisites which permit GSS-API peers to 195 establish security contexts with each other. A caller may designate 196 that the credential elements which are to be applied for context 197 initiation or acceptance be selected by default. Alternately, those 198 GSS-API callers which need to make explicit selection of particular 199 credentials structures may make references to those credentials 200 through GSS-API-provided credential handles ("cred_handles"). In all 201 cases, callers' credential references are indirect, mediated by GSS- 202 API implementations and not requiring callers to access the selected 203 credential elements. 205 A single credential structure may be used to initiate outbound 206 contexts and to accept inbound contexts. Callers needing to operate 207 in only one of these modes may designate this fact when credentials 208 are acquired for use, allowing underlying mechanisms to optimize 209 their processing and storage requirements. The credential elements 210 defined by a particular mechanism may contain multiple cryptographic 211 keys, e.g., to enable authentication and message encryption to be 212 performed with different algorithms. 214 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. 438 GSS-API implementations are expected to retain inquirable context 439 data on a context until the context is released by a caller, even 440 after the context has expired, although underlying cryptographic data 441 elements may be deleted after expiration in order to limit their 442 exposure. 444 1.1.4: Mechanism Types 446 In order to successfully establish a security context with a target 447 peer, it is necessary to identify an appropriate underlying mechanism 448 type (mech_type) which both initiator and target peers support. The 449 definition of a mechanism embodies not only the use of a particular 450 cryptographic technology (or a hybrid or choice among alternative 451 cryptographic technologies), but also definition of the syntax and 452 semantics of data element exchanges which that mechanism will employ 453 in order to support security services. 455 It is recommended that callers initiating contexts specify the 456 "default" mech_type value, allowing system-specific functions within 457 or invoked by the GSS-API implementation to select the appropriate 458 mech_type, but callers may direct that a particular mech_type be 459 employed when necessary. 461 For GSS-API purposes, the phrase "negotiating mechanism" refers to a 462 mechanism which itself performs negotiation in order to select a 463 concrete mechanism which is shared between peers and is then used for 464 context establishment. Only those mechanisms which are defined in 465 their specifications as negotiating mechanisms are to yield selected 466 mechanisms with different identifier values than the value which is 467 input by a GSS-API caller, except for the case of a caller requesting 468 the "default" mech_type. 470 The means for identifying a shared mech_type to establish a security 471 context with a peer will vary in different environments and 472 circumstances; examples include (but are not limited to): 474 use of a fixed mech_type, defined by configuration, within an 475 environment 477 syntactic convention on a target-specific basis, through 478 examination of a target's name 480 lookup of a target's name in a naming service or other database in 481 order to identify mech_types supported by that target 483 explicit negotiation between GSS-API callers in advance of 484 security context setup 485 use of a negotiating mechanism 487 When transferred between GSS-API peers, mech_type specifiers (per 488 Section 3 of this document, represented as Object Identifiers (OIDs)) 489 serve to qualify the interpretation of associated tokens. (The 490 structure and encoding of Object Identifiers is defined in [ISOIEC- 491 8824] and [ISOIEC-8825].) Use of hierarchically structured OIDs 492 serves to preclude ambiguous interpretation of mech_type specifiers. 493 The OID representing the DASS ([RFC-1507]) MechType, for example, is 494 1.3.12.2.1011.7.5, and that of the Kerberos V5 mechanism ([RFC- 495 1964]), having been advanced to the level of Proposed Standard, is 496 1.2.840.113554.1.2.2. 498 1.1.5: Naming 500 The GSS-API avoids prescribing naming structures, treating the names 501 which are transferred across the interface in order to initiate and 502 accept security contexts as opaque objects. This approach supports 503 the GSS-API's goal of implementability atop a range of underlying 504 security mechanisms, recognizing the fact that different mechanisms 505 process and authenticate names which are presented in different 506 forms. Generalized services offering translation functions among 507 arbitrary sets of naming environments are outside the scope of the 508 GSS-API; availability and use of local conversion functions to 509 translate among the naming formats supported within a given end 510 system is anticipated. 512 Different classes of name representations are used in conjunction 513 with different GSS-API parameters: 515 - Internal form (denoted in this document by INTERNAL NAME), 516 opaque to callers and defined by individual GSS-API 517 implementations. GSS-API implementations supporting multiple 518 namespace types must maintain internal tags to disambiguate the 519 interpretation of particular names. A Mechanism Name (MN) is a 520 special case of INTERNAL NAME, guaranteed to contain elements 521 corresponding to one and only one mechanism; calls which are 522 guaranteed to emit MNs or which require MNs as input are so 523 identified within this specification. 525 - Contiguous string ("flat") form (denoted in this document by 526 OCTET STRING); accompanied by OID tags identifying the namespace 527 to which they correspond. Depending on tag value, flat names may 528 or may not be printable strings for direct acceptance from and 529 presentation to users. Tagging of flat names allows GSS-API 530 callers and underlying GSS-API mechanisms to disambiguate name 531 types and to determine whether an associated name's type is one 532 which they are capable of processing, avoiding aliasing problems 533 which could result from misinterpreting a name of one type as a 534 name of another type. 536 - The GSS-API Exported Name Object, a special case of flat name 537 designated by a reserved OID value, carries a canonicalized form 538 of a name suitable for binary comparisons. 540 In addition to providing means for names to be tagged with types, 541 this specification defines primitives to support a level of naming 542 environment independence for certain calling applications. To provide 543 basic services oriented towards the requirements of callers which 544 need not themselves interpret the internal syntax and semantics of 545 names, GSS-API calls for name comparison (GSS_Compare_name()), 546 human-readable display (GSS_Display_name()), input conversion 547 (GSS_Import_name()), internal name deallocation (GSS_Release_name()), 548 and internal name duplication (GSS_Duplicate_name()) functions are 549 defined. (It is anticipated that these proposed GSS-API calls will be 550 implemented in many end systems based on system-specific name 551 manipulation primitives already extant within those end systems; 552 inclusion within the GSS-API is intended to offer GSS-API callers a 553 portable means to perform specific operations, supportive of 554 authorization and audit requirements, on authenticated names.) 556 GSS_Import_name() implementations can, where appropriate, support 557 more than one printable syntax corresponding to a given namespace 558 (e.g., alternative printable representations for X.500 Distinguished 559 Names), allowing flexibility for their callers to select among 560 alternative representations. GSS_Display_name() implementations 561 output a printable syntax selected as appropriate to their 562 operational environments; this selection is a local matter. Callers 563 desiring portability across alternative printable syntaxes should 564 refrain from implementing comparisons based on printable name forms 565 and should instead use the GSS_Compare_name() call to determine 566 whether or not one internal-format name matches another. 568 When used in large access control lists, the overhead of invoking 569 GSS_Import_name() and GSS_Compare_name() on each name from the ACL 570 may be prohibitive. As an alternative way of supporting this case, 571 GSS-API defines a special form of the contiguous string name which 572 may be compared directly (e.g., with memcmp()). Contiguous names 573 suitable for comparison are generated by the GSS_Export_name() 574 routine, which requires an MN as input. Exported names may be re- 575 imported by the GSS_Import_name() routine, and the resulting internal 576 name will also be an MN. The symbolic constant GSS_C_NT_EXPORT_NAME 577 identifies the "export name" type. Structurally, an exported name 578 object consists of a header containing an OID identifying the 579 mechanism that authenticated the name, and a trailer containing the 580 name itself, where the syntax of the trailer is defined by the 581 individual mechanism specification. The precise format of an 582 exported name is defined in Section 3.2 of this specification. 584 Note that the results obtained by using GSS_Compare_name() will in 585 general be different from those obtained by invoking 586 GSS_Canonicalize_name() and GSS_Export_name(), and then comparing the 587 exported names. The first series of operation determines whether two 588 (unauthenticated) names identify the same principal; the second 589 whether a particular mechanism would authenticate them as the same 590 principal. These two operations will in general give the same 591 results only for MNs. 593 The following diagram illustrates the intended dataflow among name- 594 related GSS-API processing routines. 596 GSS-API library defaults 597 | 598 | 599 V text, for 600 text --------------> internal_name (IN) -----------> display only 601 import_name() / display_name() 602 / 603 / 604 / 605 accept_sec_context() / 606 | / 607 | / 608 | / canonicalize_name() 609 | / 610 | / 611 | / 612 | / 613 | / 614 | | 615 V V <--------------------- 616 single mechanism import_name() exported name: flat 617 internal_name (MN) binary "blob" usable 618 ----------------------> for access control 619 export_name() 621 1.1.6: Channel Bindings 623 The GSS-API accommodates the concept of caller-provided channel 624 binding ("chan_binding") information. Channel bindings are used to 625 strengthen the quality with which peer entity authentication is 626 provided during context establishment, by limiting the scope within 627 which an intercepted context establishment token can be reused by an 628 attacker. Specifically, they enable GSS-API callers to bind the 629 establishment of a security context to relevant characteristics 630 (e.g., addresses, transformed representations of encryption keys) of 631 the underlying communications channel, of protection mechanisms 632 applied to that communications channel, and to application-specific 633 data. 635 The caller initiating a security context must determine the 636 appropriate channel binding values to provide as input to the 637 GSS_Init_sec_context() call, and consistent values must be provided 638 to GSS_Accept_sec_context() by the context's target, in order for 639 both peers' GSS-API mechanisms to validate that received tokens 640 possess correct channel-related characteristics. Use or non-use of 641 the GSS-API channel binding facility is a caller option. GSS-API 642 mechanisms can operate in an environment where NULL channel bindings 643 are presented; mechanism implementors are encouraged, but not 644 required, to make use of caller-provided channel binding data within 645 their mechanisms. Callers should not assume that underlying 646 mechanisms provide confidentiality protection for channel binding 647 information. 649 When non-NULL channel bindings are provided by callers, certain 650 mechanisms can offer enhanced security value by interpreting the 651 bindings' content (rather than simply representing those bindings, or 652 integrity check values computed on them, within tokens) and will 653 therefore depend on presentation of specific data in a defined 654 format. To this end, agreements among mechanism implementors are 655 defining conventional interpretations for the contents of channel 656 binding arguments, including address specifiers (with content 657 dependent on communications protocol environment) for context 658 initiators and acceptors. (These conventions are being incorporated 659 in GSS-API mechanism specifications and into the GSS-API C language 660 bindings specification.) In order for GSS-API callers to be portable 661 across multiple mechanisms and achieve the full security 662 functionality which each mechanism can provide, it is strongly 663 recommended that GSS-API callers provide channel bindings consistent 664 with these conventions and those of the networking environment in 665 which they operate. 667 1.2: GSS-API Features and Issues 669 This section describes aspects of GSS-API operations, of the security 670 services which the GSS-API provides, and provides commentary on 671 design issues. 673 1.2.1: Status Reporting and Optional Service Support 675 1.2.1.1: Status Reporting 677 Each GSS-API call provides two status return values. Major_status 678 values provide a mechanism-independent indication of call status 679 (e.g., GSS_S_COMPLETE, GSS_S_FAILURE, GSS_S_CONTINUE_NEEDED), 680 sufficient to drive normal control flow within the caller in a 681 generic fashion. Table 1 summarizes the defined major_status return 682 codes in tabular fashion. 684 Sequencing-related informatory major_status codes 685 (GSS_S_DUPLICATE_TOKEN, GSS_S_OLD_TOKEN, GSS_S_UNSEQ_TOKEN, and 686 GSS_S_GAP_TOKEN) can be indicated in conjunction with either 687 GSS_S_COMPLETE or GSS_S_FAILURE status for GSS-API per-message calls. 688 For context establishment calls, these sequencing-related codes will 689 be indicated only in conjunction with GSS_S_FAILURE status (never in 690 conjunction with GSS_S_COMPLETE or GSS_S_CONTINUE_NEEDED), and, 691 therefore, always correspond to fatal failures if encountered during 692 the context establishment phase. 694 Table 1: GSS-API Major Status Codes 696 FATAL ERROR CODES 698 GSS_S_BAD_BINDINGS channel binding mismatch 699 GSS_S_BAD_MECH unsupported mechanism requested 700 GSS_S_BAD_NAME invalid name provided 701 GSS_S_BAD_NAMETYPE name of unsupported type provided 702 GSS_S_BAD_STATUS invalid input status selector 703 GSS_S_BAD_SIG token had invalid integrity check 704 GSS_S_BAD_MIC preferred alias for GSS_S_BAD_SIG 705 GSS_S_CONTEXT_EXPIRED specified security context expired 706 GSS_S_CREDENTIALS_EXPIRED expired credentials detected 707 GSS_S_DEFECTIVE_CREDENTIAL defective credential detected 708 GSS_S_DEFECTIVE_TOKEN defective token detected 709 GSS_S_FAILURE failure, unspecified at GSS-API 710 level 711 GSS_S_NO_CONTEXT no valid security context specified 712 GSS_S_NO_CRED no valid credentials provided 713 GSS_S_BAD_QOP unsupported QOP value 714 GSS_S_UNAUTHORIZED operation unauthorized 715 GSS_S_UNAVAILABLE operation unavailable 716 GSS_S_DUPLICATE_ELEMENT duplicate credential element requested 717 GSS_S_NAME_NOT_MN name contains multi-mechanism elements 719 INFORMATORY STATUS CODES 721 GSS_S_COMPLETE normal completion 722 GSS_S_CONTINUE_NEEDED continuation call to routine 723 required 724 GSS_S_DUPLICATE_TOKEN duplicate per-message token 725 detected 726 GSS_S_OLD_TOKEN timed-out per-message token 727 detected 728 GSS_S_UNSEQ_TOKEN reordered (early) per-message token 729 detected 730 GSS_S_GAP_TOKEN skipped predecessor token(s) 731 detected 733 Minor_status provides more detailed status information which may 734 include status codes specific to the underlying security mechanism. 735 Minor_status values are not specified in this document. 737 GSS_S_CONTINUE_NEEDED major_status returns, and optional message 738 outputs, are provided in GSS_Init_sec_context() and 739 GSS_Accept_sec_context() calls so that different mechanisms' 740 employment of different numbers of messages within their 741 authentication sequences need not be reflected in separate code paths 742 within calling applications. Instead, such cases are accommodated 743 with sequences of continuation calls to GSS_Init_sec_context() and 744 GSS_Accept_sec_context(). The same facility is used to encapsulate 745 mutual authentication within the GSS-API's context initiation calls. 747 For mech_types which require interactions with third-party servers in 748 order to establish a security context, GSS-API context establishment 749 calls may block pending completion of such third-party interactions. 750 On the other hand, no GSS-API calls pend on serialized interactions 751 with GSS-API peer entities. As a result, local GSS-API status 752 returns cannot reflect unpredictable or asynchronous exceptions 753 occurring at remote peers, and reflection of such status information 754 is a caller responsibility outside the GSS-API. 756 1.2.1.2: Optional Service Support 758 A context initiator may request various optional services at context 759 establishment time. Each of these services is requested by setting a 760 flag in the req_flags input parameter to GSS_Init_sec_context(). 762 The optional services currently defined are: 764 - Delegation - The (usually temporary) transfer of rights from 765 initiator to acceptor, enabling the acceptor to authenticate 766 itself as an agent of the initiator. 768 - Mutual Authentication - In addition to the initiator 769 authenticating its identity to the context acceptor, the context 770 acceptor should also authenticate itself to the initiator. 772 - Replay detection - In addition to providing message integrity 773 services, GSS_GetMIC() and GSS_Wrap() should include message 774 numbering information to enable GSS_VerifyMIC() and GSS_Unwrap() 775 to detect if a message has been duplicated. 777 - Out-of-sequence detection - In addition to providing message 778 integrity services, GSS_GetMIC() and GSS_Wrap() should include 779 message sequencing information to enable GSS_VerifyMIC() and 780 GSS_Unwrap() to detect if a message has been received out of 781 sequence. 783 - Anonymous authentication - The establishment of the security 784 context should not reveal the initiator's identity to the 785 context acceptor. 787 Any currently undefined bits within such flag arguments should be 788 ignored by GSS-API implementations when presented by an application, 789 and should be set to zero when returned to the application by the 790 GSS-API implementation. 792 Some mechanisms may not support all optional services, and some 793 mechanisms may only support some services in conjunction with others. 794 Both GSS_Init_sec_context() and GSS_Accept_sec_context() inform the 795 applications which services will be available from the context when 796 the establishment phase is complete, via the ret_flags output 797 parameter. In general, if the security mechanism is capable of 798 providing a requested service, it should do so, even if additional 799 services must be enabled in order to provide the requested service. 800 If the mechanism is incapable of providing a requested service, it 801 should proceed without the service, leaving the application to abort 802 the context establishment process if it considers the requested 803 service to be mandatory. 805 Some mechanisms may specify that support for some services is 806 optional, and that implementors of the mechanism need not provide it. 807 This is most commonly true of the confidentiality service, often 808 because of legal restrictions on the use of data-encryption, but may 809 apply to any of the services. Such mechanisms are required to send 810 at least one token from acceptor to initiator during context 811 establishment when the initiator indicates a desire to use such a 812 service, so that the initiating GSS-API can correctly indicate 813 whether the service is supported by the acceptor's GSS-API. 815 1.2.2: Per-Message Security Service Availability 817 When a context is established, two flags are returned to indicate the 818 set of per-message protection security services which will be 819 available on the context: 821 the integ_avail flag indicates whether per-message integrity and 822 data origin authentication services are available 824 the conf_avail flag indicates whether per-message confidentiality 825 services are available, and will never be returned TRUE unless the 826 integ_avail flag is also returned TRUE 828 GSS-API callers desiring per-message security services should 829 check the values of these flags at context establishment time, and 830 must be aware that a returned FALSE value for integ_avail means 831 that invocation of GSS_GetMIC() or GSS_Wrap() primitives on the 832 associated context will apply no cryptographic protection to user 833 data messages. 835 The GSS-API per-message integrity and data origin authentication 836 services provide assurance to a receiving caller that protection was 837 applied to a message by the caller's peer on the security context, 838 corresponding to the entity named at context initiation. The GSS-API 839 per-message confidentiality service provides assurance to a sending 840 caller that the message's content is protected from access by 841 entities other than the context's named peer. 843 The GSS-API per-message protection service primitives, as the 844 category name implies, are oriented to operation at the granularity 845 of protocol data units. They perform cryptographic operations on the 846 data units, transfer cryptographic control information in tokens, 847 and, in the case of GSS_Wrap(), encapsulate the protected data unit. 848 As such, these primitives are not oriented to efficient data 849 protection for stream-paradigm protocols (e.g., Telnet) if 850 cryptography must be applied on an octet-by-octet basis. 852 1.2.3: Per-Message Replay Detection and Sequencing 854 Certain underlying mech_types offer support for replay detection 855 and/or sequencing of messages transferred on the contexts they 856 support. These optionally-selectable protection features are distinct 857 from replay detection and sequencing features applied to the context 858 establishment operation itself; the presence or absence of context- 859 level replay or sequencing features is wholly a function of the 860 underlying mech_type's capabilities, and is not selected or omitted 861 as a caller option. 863 The caller initiating a context provides flags (replay_det_req_flag 864 and sequence_req_flag) to specify whether the use of per-message 865 replay detection and sequencing features is desired on the context 866 being established. The GSS-API implementation at the initiator system 867 can determine whether these features are supported (and whether they 868 are optionally selectable) as a function of mech_type, without need 869 for bilateral negotiation with the target. When enabled, these 870 features provide recipients with indicators as a result of GSS-API 871 processing of incoming messages, identifying whether those messages 872 were detected as duplicates or out-of-sequence. Detection of such 873 events does not prevent a suspect message from being provided to a 874 recipient; the appropriate course of action on a suspect message is a 875 matter of caller policy. 877 The semantics of the replay detection and sequencing services applied 878 to received messages, as visible across the interface which the GSS- 879 API provides to its clients, are as follows: 881 When replay_det_state is TRUE, the possible major_status returns for 882 well-formed and correctly signed messages are as follows: 884 1. GSS_S_COMPLETE indicates that the message was within the window 885 (of time or sequence space) allowing replay events to be detected, 886 and that the message was not a replay of a previously-processed 887 message within that window. 889 2. GSS_S_DUPLICATE_TOKEN indicates that the cryptographic 890 checkvalue on the received message was correct, but that the 891 message was recognized as a duplicate of a previously-processed 892 message. 894 3. GSS_S_OLD_TOKEN indicates that the cryptographic checkvalue on 895 the received message was correct, but that the message is too old 896 to be checked for duplication. 898 When sequence_state is TRUE, the possible major_status returns for 899 well-formed and correctly signed messages are as follows: 901 1. GSS_S_COMPLETE indicates that the message was within the window 902 (of time or sequence space) allowing replay events to be detected, 903 that the message was not a replay of a previously-processed 904 message within that window, and that no predecessor sequenced 905 messages are missing relative to the last received message (if 906 any) processed on the context with a correct cryptographic 907 checkvalue. 909 2. GSS_S_DUPLICATE_TOKEN indicates that the integrity check value 910 on the received message was correct, but that the message was 911 recognized as a duplicate of a previously-processed message. 913 3. GSS_S_OLD_TOKEN indicates that the integrity check value on the 914 received message was correct, but that the token is too old to be 915 checked for duplication. 917 4. GSS_S_UNSEQ_TOKEN indicates that the cryptographic checkvalue 918 on the received message was correct, but that it is earlier in a 919 sequenced stream than a message already processed on the context. 920 [Note: Mechanisms can be architected to provide a stricter form of 921 sequencing service, delivering particular messages to recipients 922 only after all predecessor messages in an ordered stream have been 923 delivered. This type of support is incompatible with the GSS-API 924 paradigm in which recipients receive all messages, whether in 925 order or not, and provide them (one at a time, without intra-GSS- 926 API message buffering) to GSS-API routines for validation. GSS- 927 API facilities provide supportive functions, aiding clients to 928 achieve strict message stream integrity in an efficient manner in 929 conjunction with sequencing provisions in communications 930 protocols, but the GSS-API does not offer this level of message 931 stream integrity service by itself.] 933 5. GSS_S_GAP_TOKEN indicates that the cryptographic checkvalue on 934 the received message was correct, but that one or more predecessor 935 sequenced messages have not been successfully processed relative 936 to the last received message (if any) processed on the context 937 with a correct cryptographic checkvalue. 939 As the message stream integrity features (especially sequencing) may 940 interfere with certain applications' intended communications 941 paradigms, and since support for such features is likely to be 942 resource intensive, it is highly recommended that mech_types 943 supporting these features allow them to be activated selectively on 944 initiator request when a context is established. A context initiator 945 and target are provided with corresponding indicators 946 (replay_det_state and sequence_state), signifying whether these 947 features are active on a given context. 949 An example mech_type supporting per-message replay detection could 950 (when replay_det_state is TRUE) implement the feature as follows: The 951 underlying mechanism would insert timestamps in data elements output 952 by GSS_GetMIC() and GSS_Wrap(), and would maintain (within a time- 953 limited window) a cache (qualified by originator-recipient pair) 954 identifying received data elements processed by GSS_VerifyMIC() and 955 GSS_Unwrap(). When this feature is active, exception status returns 956 (GSS_S_DUPLICATE_TOKEN, GSS_S_OLD_TOKEN) will be provided when 957 GSS_VerifyMIC() or GSS_Unwrap() is presented with a message which is 958 either a detected duplicate of a prior message or which is too old to 959 validate against a cache of recently received messages. 961 1.2.4: Quality of Protection 963 Some mech_types provide their users with fine granularity control 964 over the means used to provide per-message protection, allowing 965 callers to trade off security processing overhead dynamically against 966 the protection requirements of particular messages. A per-message 967 quality-of-protection parameter (analogous to quality-of-service, or 968 QOS) selects among different QOP options supported by that mechanism. 969 On context establishment for a multi-QOP mech_type, context-level 970 data provides the prerequisite data for a range of protection 971 qualities. 973 It is expected that the majority of callers will not wish to exert 974 explicit mechanism-specific QOP control and will therefore request 975 selection of a default QOP. Definitions of, and choices among, non- 976 default QOP values are mechanism-specific, and no ordered sequences 977 of QOP values can be assumed equivalent across different mechanisms. 978 Meaningful use of non-default QOP values demands that callers be 979 familiar with the QOP definitions of an underlying mechanism or 980 mechanisms, and is therefore a non-portable construct. The 981 GSS_S_BAD_QOP major_status value is defined in order to indicate that 982 a provided QOP value is unsupported for a security context, most 983 likely because that value is unrecognized by the underlying 984 mechanism. 986 1.2.5: Anonymity Support 988 In certain situations or environments, an application may wish to 989 authenticate a peer and/or protect communications using GSS-API per- 990 message services without revealing its own identity. For example, 991 consider an application which provides read access to a research 992 database, and which permits queries by arbitrary requestors. A 993 client of such a service might wish to authenticate the service, to 994 establish trust in the information received from it, but might not 995 wish to disclose its identity to the service for privacy reasons. 997 In ordinary GSS-API usage, a context initiator's identity is made 998 available to the context acceptor as part of the context 999 establishment process. To provide for anonymity support, a facility 1000 (input anon_req_flag to GSS_Init_sec_context()) is provided through 1001 which context initiators may request that their identity not be 1002 provided to the context acceptor. Mechanisms are not required to 1003 honor this request, but a caller will be informed (via returned 1004 anon_state indicator from GSS_Init_sec_context()) whether or not the 1005 request is honored. Note that authentication as the anonymous 1006 principal does not necessarily imply that credentials are not 1007 required in order to establish a context. 1009 Section 4.5 of this document defines the Object Identifier value used 1010 to identify an anonymous principal. 1012 Four possible combinations of anon_state and mutual_state are 1013 possible, with the following results: 1015 anon_state == FALSE, mutual_state == FALSE: initiator 1016 authenticated to target. 1018 anon_state == FALSE, mutual_state == TRUE: initiator authenticated 1019 to target, target authenticated to initiator. 1021 anon_state == TRUE, mutual_state == FALSE: initiator authenticated 1022 as anonymous principal to target. 1024 anon_state == TRUE, mutual_state == TRUE: initiator authenticated 1025 as anonymous principal to target, target authenticated to 1026 initiator. 1028 1.2.6: Initialization 1030 No initialization calls (i.e., calls which must be invoked prior to 1031 invocation of other facilities in the interface) are defined in GSS- 1032 API. As an implication of this fact, GSS-API implementations must 1033 themselves be self-initializing. 1035 1.2.7: Per-Message Protection During Context Establishment 1037 A facility is defined in GSS-V2 to enable protection and buffering of 1038 data messages for later transfer while a security context's 1039 establishment is in GSS_S_CONTINUE_NEEDED status, to be used in cases 1040 where the caller side already possesses the necessary session key to 1041 enable this processing. Specifically, a new state Boolean, called 1042 prot_ready_state, is added to the set of information returned by 1043 GSS_Init_sec_context(), GSS_Accept_sec_context(), and 1044 GSS_Inquire_context(). 1046 For context establishment calls, this state Boolean is valid and 1047 interpretable when the associated major_status is either 1048 GSS_S_CONTINUE_NEEDED, or GSS_S_COMPLETE. Callers of GSS-API (both 1049 initiators and acceptors) can assume that per-message protection (via 1050 GSS_Wrap(), GSS_Unwrap(), GSS_GetMIC() and GSS_VerifyMIC()) is 1051 available and ready for use if either: prot_ready_state == TRUE, or 1052 major_status == GSS_S_COMPLETE, though mutual authentication (if 1053 requested) cannot be guaranteed until GSS_S_COMPLETE is returned. 1055 This achieves full, transparent backward compatibility for GSS-API V1 1056 callers, who need not even know of the existence of prot_ready_state, 1057 and who will get the expected behavior from GSS_S_COMPLETE, but who 1058 will not be able to use per-message protection before GSS_S_COMPLETE 1059 is returned. 1061 It is not a requirement that GSS-V2 mechanisms ever return TRUE 1062 prot_ready_state before completion of context establishment (indeed, 1063 some mechanisms will not evolve usable message protection keys, 1064 especially at the context acceptor, before context establishment is 1065 complete). It is expected but not required that GSS-V2 mechanisms 1066 will return TRUE prot_ready_state upon completion of context 1067 establishment if they support per-message protection at all (however 1068 GSS-V2 applications should not assume that TRUE prot_ready_state will 1069 always be returned together with the GSS_S_COMPLETE major_status, 1070 since GSS-V2 implementations may continue to support GSS-V1 mechanism 1071 code, which will never return TRUE prot_ready_state). 1073 When prot_ready_state is returned TRUE, mechanisms shall also set 1074 those context service indicator flags (deleg_state, mutual_state, 1075 replay_det_state, sequence_state, anon_state, trans_state, 1076 conf_avail, integ_avail) which represent facilities confirmed, at 1077 that time, to be available on the context being established. In 1078 situations where prot_ready_state is returned before GSS_S_COMPLETE, 1079 it is possible that additional facilities may be confirmed and 1080 subsequently indicated when GSS_S_COMPLETE is returned. 1082 1.2.8: Implementation Robustness 1084 This section recommends aspects of GSS-API implementation behavior in 1085 the interests of overall robustness. 1087 Invocation of GSS-API calls is to incur no undocumented side effects 1088 visible at the GSS-API level. 1090 If a token is presented for processing on a GSS-API security context 1091 and that token is determined to be invalid for that context, the 1092 context's state should not be disrupted for purposes of processing 1093 subsequent valid tokens. 1095 Certain local conditions at a GSS-API implementation (e.g., 1096 unavailability of memory) may preclude, temporarily or permanently, 1097 the successful processing of tokens on a GSS-API security context, 1098 typically generating GSS_S_FAILURE major_status returns along with 1099 locally-significant minor_status. For robust operation under such 1100 conditions, the following recommendations are made: 1102 Failing calls should free any memory they allocate, so that callers 1103 may retry without causing further loss of resources. 1105 Failure of an individual call on an established context should not 1106 preclude subsequent calls from succeeding on the same context. 1108 Whenever possible, it should be possible for 1109 GSS_Delete_sec_context() calls to be successfully processed even if 1110 other calls cannot succeed, thereby enabling context-related 1111 resources to be released. 1113 1.2.9: Delegation 1115 The GSS-API allows delegation to be controlled by the initiating 1116 application via a Boolean parameter to GSS_Init_sec_context(), the 1117 routine that establishes a security context. Some mechanisms do not 1118 support delegation, and for such mechanisms attempts by an 1119 application to enable delegation are ignored. 1121 The acceptor of a security context for which the initiator enabled 1122 delegation will receive (via the delegated_cred_handle parameter of 1123 GSS_Accept_sec_context()) a credential handle that contains the 1124 delegated identity, and this credential handle may be used to 1125 initiate subsequent GSS-API security contexts as an agent or delegate 1126 of the initiator. If the original initiator's identity is "A" and 1127 the delegate's identity is "B", then, depending on the underlying 1128 mechanism, the identity embodied by the delegated credential may be 1129 either "A" or "B acting for A". 1131 For many mechanisms that support delegation, a simple Boolean does 1132 not provide enough control. Examples of additional aspects of 1133 delegation control that a mechanism might provide to an application 1134 are duration of delegation, network addresses from which delegation 1135 is valid, and constraints on the tasks that may be performed by a 1136 delegate. Such controls are presently outside the scope of the GSS- 1137 API. GSS-API implementations supporting mechanisms offering 1138 additional controls should provide extension routines that allow 1139 these controls to be exercised (perhaps by modifying the initiator's 1140 GSS-API credential prior to its use in establishing a context). 1141 However, the simple delegation control provided by GSS-API should 1142 always be able to over-ride other mechanism-specific delegation 1143 controls; if the application instructs GSS_Init_sec_context() that 1144 delegation is not desired, then the implementation must not permit 1145 delegation to occur. This is an exception to the general rule that a 1146 mechanism may enable services even if they are not requested; 1147 delegation may only be provided at the explicit request of the 1148 application. 1150 1.2.10: Interprocess Context Transfer 1152 GSS-API V2 provides routines (GSS_Export_sec_context() and 1153 GSS_Import_sec_context()) which allow a security context to be 1154 transferred between processes on a single machine. The most common 1155 use for such a feature is a client-server design where the server is 1156 implemented as a single process that accepts incoming security 1157 contexts, which then launches child processes to deal with the data 1158 on these contexts. In such a design, the child processes must have 1159 access to the security context data structure created within the 1160 parent by its call to GSS_Accept_sec_context() so that they can use 1161 per-message protection services and delete the security context when 1162 the communication session ends. 1164 Since the security context data structure is expected to contain 1165 sequencing information, it is impractical in general to share a 1166 context between processes. Thus GSS-API provides a call 1167 (GSS_Export_sec_context()) that the process which currently owns the 1168 context can call to declare that it has no intention to use the 1169 context subsequently, and to create an inter-process token containing 1170 information needed by the adopting process to successfully import the 1171 context. After successful completion of this call, the original 1172 security context is made inaccessible to the calling process by GSS- 1173 API, and any context handles referring to this context are no longer 1174 valid. The originating process transfers the inter-process token to 1175 the adopting process, which passes it to GSS_Import_sec_context(), 1176 and a fresh context handle is created such that it is functionally 1177 identical to the original context. 1179 The inter-process token may contain sensitive data from the original 1180 security context (including cryptographic keys). Applications using 1181 inter-process tokens to transfer security contexts must take 1182 appropriate steps to protect these tokens in transit. 1183 Implementations are not required to support the inter-process 1184 transfer of security contexts. The ability to transfer a security 1185 context is indicated when the context is created, by 1186 GSS_Init_sec_context() or GSS_Accept_sec_context() indicating a TRUE 1187 trans_state return value. 1189 2: Interface Descriptions 1191 This section describes the GSS-API's service interface, dividing the 1192 set of calls offered into four groups. Credential management calls 1193 are related to the acquisition and release of credentials by 1194 principals. Context-level calls are related to the management of 1195 security contexts between principals. Per-message calls are related 1196 to the protection of individual messages on established security 1197 contexts. Support calls provide ancillary functions useful to GSS-API 1198 callers. Table 2 groups and summarizes the calls in tabular fashion. 1200 Table 2: GSS-API Calls 1202 CREDENTIAL MANAGEMENT 1204 GSS_Acquire_cred acquire credentials for use 1205 GSS_Release_cred release credentials after use 1206 GSS_Inquire_cred display information about 1207 credentials 1208 GSS_Add_cred construct credentials incrementally 1209 GSS_Inquire_cred_by_mech display per-mechanism credential 1210 information 1212 CONTEXT-LEVEL CALLS 1214 GSS_Init_sec_context initiate outbound security context 1215 GSS_Accept_sec_context accept inbound security context 1216 GSS_Delete_sec_context flush context when no longer needed 1217 GSS_Process_context_token process received control token on 1218 context 1219 GSS_Context_time indicate validity time remaining on 1220 context 1221 GSS_Inquire_context display information about context 1222 GSS_Wrap_size_limit determine GSS_Wrap token size limit 1223 GSS_Export_sec_context transfer context to other process 1224 GSS_Import_sec_context import transferred context 1226 PER-MESSAGE CALLS 1228 GSS_GetMIC apply integrity check, receive as 1229 token separate from message 1230 GSS_VerifyMIC validate integrity check token 1231 along with message 1232 GSS_Wrap sign, optionally encrypt, 1233 encapsulate 1234 GSS_Unwrap decapsulate, decrypt if needed, 1235 validate integrity check 1237 SUPPORT CALLS 1239 GSS_Display_status translate status codes to printable 1240 form 1241 GSS_Indicate_mechs indicate mech_types supported on 1242 local system 1243 GSS_Compare_name compare two names for equality 1244 GSS_Display_name translate name to printable form 1245 GSS_Import_name convert printable name to 1246 normalized form 1247 GSS_Release_name free storage of normalized-form 1248 name 1249 GSS_Release_buffer free storage of general GSS-allocated 1250 object 1251 GSS_Release_OID_set free storage of OID set object 1252 GSS_Create_empty_OID_set create empty OID set 1253 GSS_Add_OID_set_member add member to OID set 1254 GSS_Test_OID_set_member test if OID is member of OID set 1255 GSS_Inquire_names_for_mech indicate name types supported by 1256 mechanism 1257 GSS_Inquire_mechs_for_name indicates mechanisms supporting name 1258 type 1259 GSS_Canonicalize_name translate name to per-mechanism form 1260 GSS_Export_name externalize per-mechanism name 1261 GSS_Duplicate_name duplicate name object 1263 2.1: Credential management calls 1264 These GSS-API calls provide functions related to the management of 1265 credentials. Their characterization with regard to whether or not 1266 they may block pending exchanges with other network entities (e.g., 1267 directories or authentication servers) depends in part on OS-specific 1268 (extra-GSS-API) issues, so is not specified in this document. 1270 The GSS_Acquire_cred() call is defined within the GSS-API in support 1271 of application portability, with a particular orientation towards 1272 support of portable server applications. It is recognized that (for 1273 certain systems and mechanisms) credentials for interactive users may 1274 be managed differently from credentials for server processes; in such 1275 environments, it is the GSS-API implementation's responsibility to 1276 distinguish these cases and the procedures for making this 1277 distinction are a local matter. The GSS_Release_cred() call provides 1278 a means for callers to indicate to the GSS-API that use of a 1279 credentials structure is no longer required. The GSS_Inquire_cred() 1280 call allows callers to determine information about a credentials 1281 structure. The GSS_Add_cred() call enables callers to append 1282 elements to an existing credential structure, allowing iterative 1283 construction of a multi-mechanism credential. The 1284 GSS_Inquire_cred_by_mech() call enables callers to extract per- 1285 mechanism information describing a credentials structure. 1287 2.1.1: GSS_Acquire_cred call 1289 Inputs: 1291 o desired_name INTERNAL NAME, -- NULL requests locally-determined 1292 -- default 1294 o lifetime_req INTEGER, -- in seconds; 0 requests default 1296 o desired_mechs SET OF OBJECT IDENTIFIER, -- empty set requests 1297 -- system-selected default 1299 o cred_usage INTEGER -- 0=INITIATE-AND-ACCEPT, 1=INITIATE-ONLY, 1300 -- 2=ACCEPT-ONLY 1302 Outputs: 1304 o major_status INTEGER, 1306 o minor_status INTEGER, 1308 o output_cred_handle CREDENTIAL HANDLE, -- if returned non-NULL, 1309 -- caller must release with GSS_Release_cred() 1311 o actual_mechs SET OF OBJECT IDENTIFIER, -- if returned non-NULL, 1312 -- caller must release with GSS_Release_oid_set() 1314 o lifetime_rec INTEGER -- in seconds, or reserved value for 1315 -- INDEFINITE 1317 Return major_status codes: 1319 o GSS_S_COMPLETE indicates that requested credentials were 1320 successfully established, for the duration indicated in 1321 lifetime_rec, suitable for the usage requested in cred_usage, 1322 for the set of mech_types indicated in actual_mechs, and that 1323 those credentials can be referenced for subsequent use with 1324 the handle returned in output_cred_handle. 1326 o GSS_S_BAD_MECH indicates that a mech_type unsupported by the 1327 GSS-API implementation type was requested, causing the 1328 credential establishment operation to fail. 1330 o GSS_S_BAD_NAMETYPE indicates that the provided desired_name is 1331 uninterpretable or of a type unsupported by the applicable 1332 underlying GSS-API mechanism(s), so no credentials could be 1333 established for the accompanying desired_name. 1335 o GSS_S_BAD_NAME indicates that the provided desired_name is 1336 inconsistent in terms of internally-incorporated type specifier 1337 information, so no credentials could be established for the 1338 accompanying desired_name. 1340 o GSS_S_CREDENTIALS_EXPIRED indicates that underlying credential 1341 elements corresponding to the requested desired_name have 1342 expired, so requested credentials could not be established. 1344 o GSS_S_NO_CRED indicates that no credential elements corresponding 1345 to the requested desired_name and usage could be accessed, so 1346 requested credentials could not be established. In particular, 1347 this status should be returned upon temporary user-fixable 1348 conditions preventing successful credential establishment and 1349 upon lack of authorization to establish and use credentials 1350 associated with the identity named in the input desired_name 1351 argument. 1353 o GSS_S_FAILURE indicates that credential establishment failed 1354 for reasons unspecified at the GSS-API level. 1356 GSS_Acquire_cred() is used to acquire credentials so that a principal 1357 can (as a function of the input cred_usage parameter) initiate and/or 1358 accept security contexts under the identity represented by the 1359 desired_name input argument. On successful completion, the returned 1360 output_cred_handle result provides a handle for subsequent references 1361 to the acquired credentials. Typically, single-user client processes 1362 requesting that default credential behavior be applied for context 1363 establishment purposes will have no need to invoke this call. 1365 A caller may provide the value NULL (GSS_C_NO_NAME) for desired_name, 1366 which will be interpreted as a request for a credential handle that 1367 will invoke default behavior when passed to GSS_Init_sec_context(), 1368 if cred_usage is GSS_C_INITIATE or GSS_C_BOTH, or 1369 GSS_Accept_sec_context(), if cred_usage is GSS_C_ACCEPT or 1370 GSS_C_BOTH. It is possible that multiple pre-established credentials 1371 may exist for the same principal identity (for example, as a result 1372 of multiple user login sessions) when GSS_Acquire_cred() is called; 1373 the means used in such cases to select a specific credential are 1374 local matters. The input lifetime_req argument to GSS_Acquire_cred() 1375 may provide useful information for local GSS-API implementations to 1376 employ in making this disambiguation in a manner which will best 1377 satisfy a caller's intent. 1379 This routine is expected to be used primarily by context acceptors, 1380 since implementations are likely to provide mechanism-specific ways 1381 of obtaining GSS-API initiator credentials from the system login 1382 process. Some implementations may therefore not support the 1383 acquisition of GSS_C_INITIATE or GSS_C_BOTH credentials via 1384 GSS_Acquire_cred() for any name other than GSS_C_NO_NAME, or a name 1385 resulting from applying GSS_Inquire_context() to an active context, 1386 or a name resulting from applying GSS_Inquire_cred() against a 1387 credential handle corresponding to default behavior. It is important 1388 to recognize that the explicit name which is yielded by resolution of 1389 a reference to "default" may change over time, e.g., as a result of 1390 local credential element management operations outside GSS-API. 1392 The lifetime_rec result indicates the length of time for which the 1393 acquired credentials will be valid, as an offset from the present. A 1394 mechanism may return a reserved value indicating INDEFINITE if no 1395 constraints on credential lifetime are imposed. A caller of 1396 GSS_Acquire_cred() can request a length of time for which acquired 1397 credentials are to be valid (lifetime_req argument), beginning at the 1398 present, or can request credentials with a default validity interval. 1399 (Requests for postdated credentials are not supported within the 1400 GSS-API.) Certain mechanisms and implementations may bind in 1401 credential validity period specifiers at a point preliminary to 1402 invocation of the GSS_Acquire_cred() call (e.g., in conjunction with 1403 user login procedures). As a result, callers requesting non-default 1404 values for lifetime_req must recognize that such requests cannot 1405 always be honored and must be prepared to accommodate the use of 1406 returned credentials with different lifetimes as indicated in 1407 lifetime_rec. 1409 The caller of GSS_Acquire_cred() can explicitly specify a set of 1410 mech_types which are to be accommodated in the returned credentials 1411 (desired_mechs argument), or can request credentials for a system- 1412 defined default set of mech_types. Selection of the system-specified 1413 default set is recommended in the interests of application 1414 portability. The actual_mechs return value may be interrogated by the 1415 caller to determine the set of mechanisms with which the returned 1416 credentials may be used. 1418 2.1.2: GSS_Release_cred call 1420 Input: 1422 o cred_handle CREDENTIAL HANDLE -- if GSS_C_NO_CREDENTIAL 1423 -- is specified, the call will complete successfully, but 1424 -- will have no effect; no credential elements will be 1425 -- released. 1427 Outputs: 1429 o major_status INTEGER, 1431 o minor_status INTEGER 1433 Return major_status codes: 1435 o GSS_S_COMPLETE indicates that the credentials referenced by the 1436 input cred_handle were released for purposes of subsequent 1437 access by the caller. The effect on other processes which may 1438 be authorized shared access to such credentials is a local 1439 matter. 1441 o GSS_S_NO_CRED indicates that no release operation was 1442 performed, either because the input cred_handle was invalid or 1443 because the caller lacks authorization to access the 1444 referenced credentials. 1446 o GSS_S_FAILURE indicates that the release operation failed for 1447 reasons unspecified at the GSS-API level. 1449 Provides a means for a caller to explicitly request that credentials 1450 be released when their use is no longer required. Note that system- 1451 specific credential management functions are also likely to exist, 1452 for example to assure that credentials shared among processes are 1453 properly deleted when all affected processes terminate, even if no 1454 explicit release requests are issued by those processes. Given the 1455 fact that multiple callers are not precluded from gaining authorized 1456 access to the same credentials, invocation of GSS_Release_cred() 1457 cannot be assumed to delete a particular set of credentials on a 1458 system-wide basis. 1460 2.1.3: GSS_Inquire_cred call 1462 Input: 1464 o cred_handle CREDENTIAL HANDLE -- if GSS_C_NO_CREDENTIAL 1465 -- specified, default initiator credentials are queried 1467 Outputs: 1469 o major_status INTEGER, 1471 o minor_status INTEGER, 1473 o cred_name INTERNAL NAME, -- caller must release with 1474 -- GSS_Release_name() 1476 o lifetime_rec INTEGER -- in seconds, or reserved value for 1477 -- INDEFINITE 1479 o cred_usage INTEGER, -- 0=INITIATE-AND-ACCEPT, 1=INITIATE-ONLY, 1480 -- 2=ACCEPT-ONLY 1482 o mech_set SET OF OBJECT IDENTIFIER -- caller must release 1483 -- with GSS_Release_oid_set() 1485 Return major_status codes: 1487 o GSS_S_COMPLETE indicates that the credentials referenced by the 1488 input cred_handle argument were valid, and that the output 1489 cred_name, lifetime_rec, and cred_usage values represent, 1490 respectively, the credentials' associated principal name, 1491 remaining lifetime, suitable usage modes, and supported 1492 mechanism types. 1494 o GSS_S_NO_CRED indicates that no information could be returned 1495 about the referenced credentials, either because the input 1496 cred_handle was invalid or because the caller lacks 1497 authorization to access the referenced credentials. 1499 o GSS_S_DEFECTIVE_CREDENTIAL indicates that the referenced 1500 credentials are invalid. 1502 o GSS_S_CREDENTIALS_EXPIRED indicates that the referenced 1503 credentials have expired. 1505 o GSS_S_FAILURE indicates that the operation failed for 1506 reasons unspecified at the GSS-API level. 1508 The GSS_Inquire_cred() call is defined primarily for the use of those 1509 callers which request use of default credential behavior rather than 1510 acquiring credentials explicitly with GSS_Acquire_cred(). It enables 1511 callers to determine a credential structure's associated principal 1512 name, remaining validity period, usability for security context 1513 initiation and/or acceptance, and supported mechanisms. 1515 For a multi-mechanism credential, the returned "lifetime" specifier 1516 indicates the shortest lifetime of any of the mechanisms' elements in 1517 the credential (for either context initiation or acceptance 1518 purposes). 1520 GSS_Inquire_cred() should indicate INITIATE-AND-ACCEPT for 1521 "cred_usage" if both of the following conditions hold: 1523 (1) there exists in the credential an element which allows 1524 context initiation using some mechanism 1526 (2) there exists in the credential an element which allows 1527 context acceptance using some mechanism (allowably, but not 1528 necessarily, one of the same mechanism(s) qualifying for (1)). 1530 If condition (1) holds but not condition (2), GSS_Inquire_cred() 1531 should indicate INITIATE-ONLY for "cred_usage". If condition (2) 1532 holds but not condition (1), GSS_Inquire_cred() should indicate 1533 ACCEPT-ONLY for "cred_usage". 1535 Callers requiring finer disambiguation among available combinations 1536 of lifetimes, usage modes, and mechanisms should call the 1537 GSS_Inquire_cred_by_mech() routine, passing that routine one of the 1538 mech OIDs returned by GSS_Inquire_cred(). 1540 2.1.4: GSS_Add_cred call 1542 Inputs: 1544 o input_cred_handle CREDENTIAL HANDLE -- handle to credential 1545 -- structure created with prior GSS_Acquire_cred() or 1546 -- GSS_Add_cred() call; see text for definition of behavior 1547 -- when GSS_C_NO_CREDENTIAL provided. 1549 o desired_name INTERNAL NAME 1551 o initiator_time_req INTEGER -- in seconds; 0 requests default 1552 o acceptor_time_req INTEGER -- in seconds; 0 requests default 1554 o desired_mech OBJECT IDENTIFIER 1556 o cred_usage INTEGER -- 0=INITIATE-AND-ACCEPT, 1=INITIATE-ONLY, 1557 -- 2=ACCEPT-ONLY 1559 Outputs: 1561 o major_status INTEGER, 1563 o minor_status INTEGER, 1565 o output_cred_handle CREDENTIAL HANDLE, -- NULL to request that 1566 -- credential elements be added "in place" to the credential 1567 -- structure identified by input_cred_handle, 1568 -- non-NULL pointer to request that 1569 -- a new credential structure and handle be created. 1570 -- if credential handle returned, caller must release with 1571 -- GSS_Release_cred() 1573 o actual_mechs SET OF OBJECT IDENTIFIER, -- if returned, caller must 1574 -- release with GSS_Release_oid_set() 1576 o initiator_time_rec INTEGER -- in seconds, or reserved value for 1577 -- INDEFINITE 1579 o acceptor_time_rec INTEGER -- in seconds, or reserved value for 1580 -- INDEFINITE 1582 o cred_usage INTEGER, -- 0=INITIATE-AND-ACCEPT, 1=INITIATE-ONLY, 1583 -- 2=ACCEPT-ONLY 1585 o mech_set SET OF OBJECT IDENTIFIER -- full set of mechanisms 1586 -- supported by resulting credential. 1588 Return major_status codes: 1590 o GSS_S_COMPLETE indicates that the credentials referenced by 1591 the input_cred_handle argument were valid, and that the 1592 resulting credential from GSS_Add_cred() is valid for the 1593 durations indicated in initiator_time_rec and acceptor_time_rec, 1594 suitable for the usage requested in cred_usage, and for the 1595 mechanisms indicated in actual_mechs. 1597 o GSS_S_DUPLICATE_ELEMENT indicates that the input desired_mech 1598 specified a mechanism for which the referenced credential 1599 already contained a credential element with overlapping cred_usage 1600 and validity time specifiers. 1602 o GSS_S_BAD_MECH indicates that the input desired_mech specified 1603 a mechanism unsupported by the GSS-API implementation, causing 1604 the GSS_Add_cred() operation to fail. 1606 o GSS_S_BAD_NAMETYPE indicates that the provided desired_name 1607 is uninterpretable or of a type unsupported by the applicable 1608 underlying GSS-API mechanism(s), so the GSS_Add_cred() operation 1609 could not be performed for that name. 1611 o GSS_S_BAD_NAME indicates that the provided desired_name is 1612 inconsistent in terms of internally-incorporated type specifier 1613 information, so the GSS_Add_cred() operation could not be 1614 performed for that name. 1616 o GSS_S_NO_CRED indicates that the input_cred_handle referenced 1617 invalid or inaccessible credentials. In particular, 1618 this status should be returned upon temporary user-fixable 1619 conditions preventing successful credential establishment or 1620 upon lack of authorization to establish or use credentials 1621 representing the requested identity. 1623 o GSS_S_CREDENTIALS_EXPIRED indicates that referenced credential 1624 elements have expired, so the GSS_Add_cred() operation could 1625 not be performed. 1627 o GSS_S_FAILURE indicates that the operation failed for 1628 reasons unspecified at the GSS-API level. 1630 GSS_Add_cred() enables callers to construct credentials iteratively 1631 by adding credential elements in successive operations, corresponding 1632 to different mechanisms. This offers particular value in multi- 1633 mechanism environments, as the major_status and minor_status values 1634 returned on each iteration are individually visible and can therefore 1635 be interpreted unambiguously on a per-mechanism basis. A credential 1636 element is identified by the name of the principal to which it 1637 refers. GSS-API implementations must impose a local access control 1638 policy on callers of this routine to prevent unauthorized callers 1639 from acquiring credential elements to which they are not entitled. 1640 This routine is not intended to provide a ``login to the network'' 1641 function, as such a function would involve the creation of new 1642 mechanism-specific authentication data, rather than merely acquiring 1643 a GSS-API handle to existing data. Such functions, if required, 1644 should be defined in implementation-specific extension routines. 1646 If credential acquisition is time-consuming for a mechanism, the 1647 mechanism may choose to delay the actual acquisition until the 1648 credential is required (e.g. by GSS_Init_sec_context() or 1649 GSS_Accept_sec_context()). Such mechanism-specific implementation 1650 decisions should be invisible to the calling application; thus a call 1651 of GSS_Inquire_cred() immediately following the call of 1652 GSS_Acquire_cred() must return valid credential data, and may 1653 therefore incur the overhead of a deferred credential acquisition. 1655 If GSS_C_NO_CREDENTIAL is specified as input_cred_handle, a non-NULL 1656 output_cred_handle must be supplied. For the case of 1657 GSS_C_NO_CREDENTIAL as input_cred_handle, GSS_Add_cred() will create 1658 the credential referenced by its output_cred_handle based on default 1659 behavior. That is, the call will have the same effect as if the 1660 caller had previously called GSS_Acquire_cred(), specifying the same 1661 usage and passing GSS_C_NO_NAME as the desired_name parameter 1662 (thereby obtaining an explicit credential handle corresponding to 1663 default behavior), had passed that credential handle to 1664 GSS_Add_cred(), and had finally called GSS_Release_cred() on the 1665 credential handle received from GSS_Acquire_cred(). 1667 This routine is expected to be used primarily by context acceptors, 1668 since implementations are likely to provide mechanism-specific ways 1669 of obtaining GSS-API initiator credentials from the system login 1670 process. Some implementations may therefore not support the 1671 acquisition of GSS_C_INITIATE or GSS_C_BOTH credentials via 1672 GSS_Acquire_cred() for any name other than GSS_C_NO_NAME, or a name 1673 resulting from applying GSS_Inquire_context() to an active context, 1674 or a name resulting from applying GSS_Inquire_cred() against a 1675 credential handle corresponding to default behavior. It is important 1676 to recognize that the explicit name which is yielded by resolution of 1677 a reference to "default" may change over time, e.g., as a result of 1678 local credential element management operations outside GSS-API. 1680 A caller may provide the value NULL (GSS_C_NO_NAME) for desired_name, 1681 which will be interpreted as a request for a credential handle that 1682 will invoke default behavior when passed to GSS_Init_sec_context(), 1683 if cred_usage is GSS_C_INITIATE or GSS_C_BOTH, or 1684 GSS_Accept_sec_context(), if cred_usage is GSS_C_ACCEPT or 1685 GSS_C_BOTH. 1687 The same input desired_name, or default reference, should be used on 1688 all GSS_Acquire_cred() and GSS_Add_cred() calls corresponding to a 1689 particular credential. 1691 2.1.5: GSS_Inquire_cred_by_mech call 1693 Inputs: 1695 o cred_handle CREDENTIAL HANDLE -- if GSS_C_NO_CREDENTIAL 1696 -- specified, default initiator credentials are queried 1698 o mech_type OBJECT IDENTIFIER -- specific mechanism for 1699 -- which credentials are being queried 1701 Outputs: 1703 o major_status INTEGER, 1705 o minor_status INTEGER, 1707 o cred_name INTERNAL NAME, -- guaranteed to be MN; caller must 1708 -- release with GSS_Release_name() 1710 o lifetime_rec_initiate INTEGER -- in seconds, or reserved value for 1711 -- INDEFINITE 1713 o lifetime_rec_accept INTEGER -- in seconds, or reserved value for 1714 -- INDEFINITE 1716 o cred_usage INTEGER, -- 0=INITIATE-AND-ACCEPT, 1=INITIATE-ONLY, 1717 -- 2=ACCEPT-ONLY 1719 Return major_status codes: 1721 o GSS_S_COMPLETE indicates that the credentials referenced by the 1722 input cred_handle argument were valid, that the mechanism 1723 indicated by the input mech_type was represented with elements 1724 within those credentials, and that the output cred_name, 1725 lifetime_rec_initiate, lifetime_rec_accept, and cred_usage values 1726 represent, respectively, the credentials' associated principal 1727 name, remaining lifetimes, and suitable usage modes. 1729 o GSS_S_NO_CRED indicates that no information could be returned 1730 about the referenced credentials, either because the input 1731 cred_handle was invalid or because the caller lacks 1732 authorization to access the referenced credentials. 1734 o GSS_S_DEFECTIVE_CREDENTIAL indicates that the referenced 1735 credentials are invalid. 1737 o GSS_S_CREDENTIALS_EXPIRED indicates that the referenced 1738 credentials have expired. 1740 o GSS_S_BAD_MECH indicates that the referenced credentials do not 1741 contain elements for the requested mechanism. 1743 o GSS_S_FAILURE indicates that the operation failed for reasons 1744 unspecified at the GSS-API level. 1746 The GSS_Inquire_cred_by_mech() call enables callers in multi- 1747 mechanism environments to acquire specific data about available 1748 combinations of lifetimes, usage modes, and mechanisms within a 1749 credential structure. The lifetime_rec_initiate result indicates the 1750 available lifetime for context initiation purposes; the 1751 lifetime_rec_accept result indicates the available lifetime for 1752 context acceptance purposes. 1754 2.2: Context-level calls 1756 This group of calls is devoted to the establishment and management of 1757 security contexts between peers. A context's initiator calls 1758 GSS_Init_sec_context(), resulting in generation of a token which the 1759 caller passes to the target. At the target, that token is passed to 1760 GSS_Accept_sec_context(). Depending on the underlying mech_type and 1761 specified options, additional token exchanges may be performed in the 1762 course of context establishment; such exchanges are accommodated by 1763 GSS_S_CONTINUE_NEEDED status returns from GSS_Init_sec_context() and 1764 GSS_Accept_sec_context(). 1766 Either party to an established context may invoke 1767 GSS_Delete_sec_context() to flush context information when a context 1768 is no longer required. GSS_Process_context_token() is used to process 1769 received tokens carrying context-level control information. 1770 GSS_Context_time() allows a caller to determine the length of time 1771 for which an established context will remain valid. 1772 GSS_Inquire_context() returns status information describing context 1773 characteristics. GSS_Wrap_size_limit() allows a caller to determine 1774 the size of a token which will be generated by a GSS_Wrap() 1775 operation. GSS_Export_sec_context() and GSS_Import_sec_context() 1776 enable transfer of active contexts between processes on an end 1777 system. 1779 2.2.1: GSS_Init_sec_context call 1781 Inputs: 1783 o claimant_cred_handle CREDENTIAL HANDLE, -- NULL specifies "use 1784 -- default" 1786 o input_context_handle CONTEXT HANDLE, -- 0 specifies "none assigned 1787 -- yet" 1789 o targ_name INTERNAL NAME, 1791 o mech_type OBJECT IDENTIFIER, -- NULL parameter specifies "use 1792 -- default" 1794 o deleg_req_flag BOOLEAN, 1796 o mutual_req_flag BOOLEAN, 1798 o replay_det_req_flag BOOLEAN, 1800 o sequence_req_flag BOOLEAN, 1802 o anon_req_flag BOOLEAN, 1804 o conf_req_flag BOOLEAN, 1806 o integ_req_flag BOOLEAN, 1808 o lifetime_req INTEGER, -- 0 specifies default lifetime 1810 o chan_bindings OCTET STRING, 1812 o input_token OCTET STRING -- NULL or token received from target 1814 Outputs: 1816 o major_status INTEGER, 1818 o minor_status INTEGER, 1820 o output_context_handle CONTEXT HANDLE, -- once returned non-NULL, 1821 -- caller must release with GSS_Delete_sec_context() 1823 o mech_type OBJECT IDENTIFIER, -- actual mechanism always 1824 -- indicated, never NULL; caller should treat as read-only 1825 -- and should not attempt to release 1827 o output_token OCTET STRING, -- NULL or token to pass to context 1828 -- target; caller must release with GSS_Release_buffer() 1830 o deleg_state BOOLEAN, 1832 o mutual_state BOOLEAN, 1834 o replay_det_state BOOLEAN, 1836 o sequence_state BOOLEAN, 1838 o anon_state BOOLEAN, 1839 o trans_state BOOLEAN, 1841 o prot_ready_state BOOLEAN, -- see Section 1.2.7 1843 o conf_avail BOOLEAN, 1845 o integ_avail BOOLEAN, 1847 o lifetime_rec INTEGER -- in seconds, or reserved value for 1848 -- INDEFINITE 1850 This call may block pending network interactions for those mech_types 1851 in which an authentication server or other network entity must be 1852 consulted on behalf of a context initiator in order to generate an 1853 output_token suitable for presentation to a specified target. 1855 Return major_status codes: 1857 o GSS_S_COMPLETE indicates that context-level information was 1858 successfully initialized, and that the returned output_token 1859 will provide sufficient information for the target to perform 1860 per-message processing on the newly-established context. 1862 o GSS_S_CONTINUE_NEEDED indicates that control information in the 1863 returned output_token must be sent to the target, and that a 1864 reply must be received and passed as the input_token argument 1865 to a continuation call to GSS_Init_sec_context(), before 1866 per-message processing can be performed in conjunction with 1867 this context. 1869 o GSS_S_DEFECTIVE_TOKEN indicates that consistency checks 1870 performed on the input_token failed, preventing further 1871 processing from being performed based on that token. 1873 o GSS_S_DEFECTIVE_CREDENTIAL indicates that consistency checks 1874 performed on the credential structure referenced by 1875 claimant_cred_handle failed, preventing further processing from 1876 being performed using that credential structure. 1878 o GSS_S_BAD_SIG (GSS_S_BAD_MIC) indicates that the received 1879 input_token contains an incorrect integrity check, so 1880 context setup cannot be accomplished. 1882 o GSS_S_NO_CRED indicates that no context was established, 1883 either because the input cred_handle was invalid, because the 1884 referenced credentials are valid for context acceptor use 1885 only, because the caller lacks authorization to access the 1886 referenced credentials, or because the resolution of default 1887 credentials failed. 1889 o GSS_S_CREDENTIALS_EXPIRED indicates that the credentials 1890 provided through the input claimant_cred_handle argument are no 1891 longer valid, so context establishment cannot be completed. 1893 o GSS_S_BAD_BINDINGS indicates that a mismatch between the 1894 caller-provided chan_bindings and those extracted from the 1895 input_token was detected, signifying a security-relevant 1896 event and preventing context establishment. (This result will 1897 be returned by GSS_Init_sec_context() only for contexts where 1898 mutual_state is TRUE.) 1900 o GSS_S_OLD_TOKEN indicates that the input_token is too old to 1901 be checked for integrity. This is a fatal error during context 1902 establishment. 1904 o GSS_S_DUPLICATE_TOKEN indicates that the input token has a 1905 correct integrity check, but is a duplicate of a token already 1906 processed. This is a fatal error during context establishment. 1908 o GSS_S_NO_CONTEXT indicates that no valid context was recognized 1909 for the input context_handle provided; this major status will 1910 be returned only for successor calls following GSS_S_CONTINUE_ 1911 NEEDED status returns. 1913 o GSS_S_BAD_NAMETYPE indicates that the provided targ_name is 1914 of a type uninterpretable or unsupported by the applicable 1915 underlying GSS-API mechanism(s), so context establishment 1916 cannot be completed. 1918 o GSS_S_BAD_NAME indicates that the provided targ_name is 1919 inconsistent in terms of internally-incorporated type specifier 1920 information, so context establishment cannot be accomplished. 1922 o GSS_S_BAD_MECH indicates receipt of a context establishment token 1923 or of a caller request specifying a mechanism unsupported by 1924 the local system or with the caller's active credentials 1926 o GSS_S_FAILURE indicates that context setup could not be 1927 accomplished for reasons unspecified at the GSS-API level, and 1928 that no interface-defined recovery action is available. 1930 This routine is used by a context initiator, and ordinarily emits one 1931 (or, for the case of a multi-step exchange, more than one) 1932 output_token suitable for use by the target within the selected 1933 mech_type's protocol. Using information in the credentials structure 1934 referenced by claimant_cred_handle, GSS_Init_sec_context() 1935 initializes the data structures required to establish a security 1936 context with target targ_name. 1938 The targ_name may be any valid INTERNAL NAME; it need not be an MN. 1939 In addition to support for other name types, it is recommended that 1940 mechanisms be able to accept GSS_C_NO_NAME as an input type for 1941 targ_name. While recommended, such support is not required, and it 1942 is recognized that not all mechanisms can construct tokens without 1943 explicitly naming the context target, even when mutual authentication 1944 of the target is not obtained. 1946 The claimant_cred_handle must correspond to the same valid 1947 credentials structure on the initial call to GSS_Init_sec_context() 1948 and on any successor calls resulting from GSS_S_CONTINUE_NEEDED 1949 status returns; different protocol sequences modeled by the 1950 GSS_S_CONTINUE_NEEDED facility will require access to credentials at 1951 different points in the context establishment sequence. 1953 The input_context_handle argument is 0, specifying "not yet 1954 assigned", on the first GSS_Init_sec_context() call relating to a 1955 given context. If successful (i.e., if accompanied by major_status 1956 GSS_S_COMPLETE or GSS_S_CONTINUE_NEEDED), and only if successful, the 1957 initial GSS_Init_sec_context() call returns a non-zero 1958 output_context_handle for use in future references to this context. 1959 Once a non-zero output_context_handle has been returned, GSS-API 1960 callers should call GSS_Delete_sec_context() to release context- 1961 related resources if errors occur in later phases of context 1962 establishment, or when an established context is no longer required. 1963 If GSS_Init_sec_context() is passed the handle of a context which is 1964 already fully established, GSS_S_FAILURE status is returned. 1966 When continuation attempts to GSS_Init_sec_context() are needed to 1967 perform context establishment, the previously-returned non-zero 1968 handle value is entered into the input_context_handle argument and 1969 will be echoed in the returned output_context_handle argument. On 1970 such continuation attempts (and only on continuation attempts) the 1971 input_token value is used, to provide the token returned from the 1972 context's target. 1974 The chan_bindings argument is used by the caller to provide 1975 information binding the security context to security-related 1976 characteristics (e.g., addresses, cryptographic keys) of the 1977 underlying communications channel. See Section 1.1.6 of this document 1978 for more discussion of this argument's usage. 1980 The input_token argument contains a message received from the target, 1981 and is significant only on a call to GSS_Init_sec_context() which 1982 follows a previous return indicating GSS_S_CONTINUE_NEEDED 1983 major_status. 1985 It is the caller's responsibility to establish a communications path 1986 to the target, and to transmit any returned output_token (independent 1987 of the accompanying returned major_status value) to the target over 1988 that path. The output_token can, however, be transmitted along with 1989 the first application-provided input message to be processed by 1990 GSS_GetMIC() or GSS_Wrap() in conjunction with a successfully- 1991 established context. 1993 The initiator may request various context-level functions through 1994 input flags: the deleg_req_flag requests delegation of access rights, 1995 the mutual_req_flag requests mutual authentication, the 1996 replay_det_req_flag requests that replay detection features be 1997 applied to messages transferred on the established context, and the 1998 sequence_req_flag requests that sequencing be enforced. (See Section 1999 1.2.3 for more information on replay detection and sequencing 2000 features.) The anon_req_flag requests that the initiator's identity 2001 not be transferred within tokens to be sent to the acceptor. The 2002 conf_req_flag and integ_req_flag provide informatory inputs to the 2003 GSS-API implementation as to whether, respectively, per-message 2004 confidentiality and per-message integrity services will be required 2005 on the context. 2007 Not all of the optionally-requestable features will be available in 2008 all underlying mech_types. The corresponding return state values 2009 deleg_state, mutual_state, replay_det_state, and sequence_state 2010 indicate, as a function of mech_type processing capabilities and 2011 initiator-provided input flags, the set of features which will be 2012 active on the context. The returned trans_state value indicates 2013 whether the context is transferable to other processes through use of 2014 GSS_Export_sec_context(). These state indicators' values are 2015 undefined unless either the routine's major_status indicates 2016 GSS_S_COMPLETE, or TRUE prot_ready_state is returned along with 2017 GSS_S_CONTINUE_NEEDED major_status; for the latter case, it is 2018 possible that additional features, not confirmed or indicated along 2019 with TRUE prot_ready_state, will be confirmed and indicated when 2020 GSS_S_COMPLETE is subsequently returned. 2022 The returned anon_state and prot_ready_state values are significant 2023 for both GSS_S_COMPLETE and GSS_S_CONTINUE_NEEDED major_status 2024 returns from GSS_Init_sec_context(). When anon_state is returned 2025 TRUE, this indicates that neither the current token nor its 2026 predecessors delivers or has delivered the initiator's identity. 2027 Callers wishing to perform context establishment only if anonymity 2028 support is provided should transfer a returned token from 2029 GSS_Init_sec_context() to the peer only if it is accompanied by a 2030 TRUE anon_state indicator. When prot_ready_state is returned TRUE in 2031 conjunction with GSS_S_CONTINUE_NEEDED major_status, this indicates 2032 that per-message protection operations may be applied on the context: 2033 see Section 1.2.7 for further discussion of this facility. 2035 Failure to provide the precise set of features requested by the 2036 caller does not cause context establishment to fail; it is the 2037 caller's prerogative to delete the context if the feature set 2038 provided is unsuitable for the caller's use. 2040 The returned mech_type value indicates the specific mechanism 2041 employed on the context; it will never indicate the value for 2042 "default". A valid mech_type result must be returned along with a 2043 GSS_S_COMPLETE status return; GSS-API implementations may (but are 2044 not required to) also return mech_type along with predecessor calls 2045 indicating GSS_S_CONTINUE_NEEDED status. For the case of mechanisms 2046 which themselves perform negotiation, the returned mech_type result 2047 may indicate selection of a mechanism identified by an OID different 2048 than that passed in the input mech_type argument, and the returned 2049 value may change between successive calls returning 2050 GSS_S_CONTINUE_NEEDED and the final call returning GSS_S_COMPLETE. 2052 The conf_avail return value indicates whether the context supports 2053 per-message confidentiality services, and so informs the caller 2054 whether or not a request for encryption through the conf_req_flag 2055 input to GSS_Wrap() can be honored. In similar fashion, the 2056 integ_avail return value indicates whether per-message integrity 2057 services are available (through either GSS_GetMIC() or GSS_Wrap()) on 2058 the established context. These state indicators' values are undefined 2059 unless either the routine's major_status indicates GSS_S_COMPLETE, or 2060 TRUE prot_ready_state is returned along with GSS_S_CONTINUE_NEEDED 2061 major_status. 2063 The lifetime_req input specifies a desired upper bound for the 2064 lifetime of the context to be established, with a value of 0 used to 2065 request a default lifetime. The lifetime_rec return value indicates 2066 the length of time for which the context will be valid, expressed as 2067 an offset from the present; depending on mechanism capabilities, 2068 credential lifetimes, and local policy, it may not correspond to the 2069 value requested in lifetime_req. If no constraints on context 2070 lifetime are imposed, this may be indicated by returning a reserved 2071 value representing INDEFINITE lifetime_req. The value of lifetime_rec 2072 is undefined unless the routine's major_status indicates 2073 GSS_S_COMPLETE. 2075 If the mutual_state is TRUE, this fact will be reflected within the 2076 output_token. A call to GSS_Accept_sec_context() at the target in 2077 conjunction with such a context will return a token, to be processed 2078 by a continuation call to GSS_Init_sec_context(), in order to achieve 2079 mutual authentication. 2081 2.2.2: GSS_Accept_sec_context call 2083 Inputs: 2085 o acceptor_cred_handle CREDENTIAL HANDLE, -- NULL specifies 2086 -- "use default" 2088 o input_context_handle CONTEXT HANDLE, -- 0 specifies 2089 -- "not yet assigned" 2091 o chan_bindings OCTET STRING, 2093 o input_token OCTET STRING 2095 Outputs: 2097 o major_status INTEGER, 2099 o minor_status INTEGER, 2101 o src_name INTERNAL NAME, -- guaranteed to be MN 2102 -- once returned, caller must release with GSS_Release_name() 2104 o mech_type OBJECT IDENTIFIER, -- caller should treat as 2105 -- read-only; does not need to be released 2107 o output_context_handle CONTEXT HANDLE, -- once returned 2108 -- non-NULL in context establishment sequence, caller 2109 -- must release with GSS_Delete_sec_context() 2111 o deleg_state BOOLEAN, 2113 o mutual_state BOOLEAN, 2115 o replay_det_state BOOLEAN, 2117 o sequence_state BOOLEAN, 2119 o anon_state BOOLEAN, 2121 o trans_state BOOLEAN, 2123 o prot_ready_state BOOLEAN, -- see Section 1.2.7 for discussion 2125 o conf_avail BOOLEAN, 2126 o integ_avail BOOLEAN, 2128 o lifetime_rec INTEGER, -- in seconds, or reserved value for 2129 -- INDEFINITE 2131 o delegated_cred_handle CREDENTIAL HANDLE, -- if returned non-NULL, 2132 -- caller must release with GSS_Release_cred() 2134 o output_token OCTET STRING -- NULL or token to pass to context 2135 -- initiator; if returned non-NULL, caller must release with 2136 -- GSS_Release_buffer() 2138 This call may block pending network interactions for those mech_types 2139 in which a directory service or other network entity must be 2140 consulted on behalf of a context acceptor in order to validate a 2141 received input_token. 2143 Return major_status codes: 2145 o GSS_S_COMPLETE indicates that context-level data structures 2146 were successfully initialized, and that per-message processing 2147 can now be performed in conjunction with this context. 2149 o GSS_S_CONTINUE_NEEDED indicates that control information in the 2150 returned output_token must be sent to the initiator, and that 2151 a response must be received and passed as the input_token 2152 argument to a continuation call to GSS_Accept_sec_context(), 2153 before per-message processing can be performed in conjunction 2154 with this context. 2156 o GSS_S_DEFECTIVE_TOKEN indicates that consistency checks performed 2157 on the input_token failed, preventing further processing from 2158 being performed based on that token. 2160 o GSS_S_DEFECTIVE_CREDENTIAL indicates that consistency checks 2161 performed on the credential structure referenced by 2162 acceptor_cred_handle failed, preventing further processing from 2163 being performed using that credential structure. 2165 o GSS_S_BAD_SIG (GSS_S_BAD_MIC) indicates that the received 2166 input_token contains an incorrect integrity check, so context 2167 setup cannot be accomplished. 2169 o GSS_S_DUPLICATE_TOKEN indicates that the integrity check on the 2170 received input_token was correct, but that the input_token 2171 was recognized as a duplicate of an input_token already 2172 processed. No new context is established. 2174 o GSS_S_OLD_TOKEN indicates that the integrity check on the received 2175 input_token was correct, but that the input_token is too old 2176 to be checked for duplication against previously-processed 2177 input_tokens. No new context is established. 2179 o GSS_S_NO_CRED indicates that no context was established, either 2180 because the input cred_handle was invalid, because the 2181 referenced credentials are valid for context initiator use 2182 only, because the caller lacks authorization to access the 2183 referenced credentials, or because the procedure for default 2184 credential resolution failed. 2186 o GSS_S_CREDENTIALS_EXPIRED indicates that the credentials provided 2187 through the input acceptor_cred_handle argument are no 2188 longer valid, so context establishment cannot be completed. 2190 o GSS_S_BAD_BINDINGS indicates that a mismatch between the 2191 caller-provided chan_bindings and those extracted from the 2192 input_token was detected, signifying a security-relevant 2193 event and preventing context establishment. 2195 o GSS_S_NO_CONTEXT indicates that no valid context was recognized 2196 for the input context_handle provided; this major status will 2197 be returned only for successor calls following GSS_S_CONTINUE_ 2198 NEEDED status returns. 2200 o GSS_S_BAD_MECH indicates receipt of a context establishment token 2201 specifying a mechanism unsupported by the local system or with 2202 the caller's active credentials. 2204 o GSS_S_FAILURE indicates that context setup could not be 2205 accomplished for reasons unspecified at the GSS-API level, and 2206 that no interface-defined recovery action is available. 2208 The GSS_Accept_sec_context() routine is used by a context target. 2209 Using information in the credentials structure referenced by the 2210 input acceptor_cred_handle, it verifies the incoming input_token and 2211 (following the successful completion of a context establishment 2212 sequence) returns the authenticated src_name and the mech_type used. 2213 The returned src_name is guaranteed to be an MN, processed by the 2214 mechanism under which the context was established. The 2215 acceptor_cred_handle must correspond to the same valid credentials 2216 structure on the initial call to GSS_Accept_sec_context() and on any 2217 successor calls resulting from GSS_S_CONTINUE_NEEDED status returns; 2218 different protocol sequences modeled by the GSS_S_CONTINUE_NEEDED 2219 mechanism will require access to credentials at different points in 2220 the context establishment sequence. 2222 The input_context_handle argument is 0, specifying "not yet 2223 assigned", on the first GSS_Accept_sec_context() call relating to a 2224 given context. If successful (i.e., if accompanied by major_status 2225 GSS_S_COMPLETE or GSS_S_CONTINUE_NEEDED), and only if successful, the 2226 initial GSS_Accept_sec_context() call returns a non-zero 2227 output_context_handle for use in future references to this context. 2228 Once a non-zero output_context_handle has been returned, GSS-API 2229 callers should call GSS_Delete_sec_context() to release context- 2230 related resources if errors occur in later phases of context 2231 establishment, or when an established context is no longer required. 2232 If GSS_Accept_sec_context() is passed the handle of a context which 2233 is already fully established, GSS_S_FAILURE status is returned. 2235 The chan_bindings argument is used by the caller to provide 2236 information binding the security context to security-related 2237 characteristics (e.g., addresses, cryptographic keys) of the 2238 underlying communications channel. See Section 1.1.6 of this document 2239 for more discussion of this argument's usage. 2241 The returned state results (deleg_state, mutual_state, 2242 replay_det_state, sequence_state, anon_state, trans_state, and 2243 prot_ready_state) reflect the same information as described for 2244 GSS_Init_sec_context(), and their values are significant under the 2245 same return state conditions. 2247 The conf_avail return value indicates whether the context supports 2248 per-message confidentiality services, and so informs the caller 2249 whether or not a request for encryption through the conf_req_flag 2250 input to GSS_Wrap() can be honored. In similar fashion, the 2251 integ_avail return value indicates whether per-message integrity 2252 services are available (through either GSS_GetMIC() or GSS_Wrap()) 2253 on the established context. These values are significant under the 2254 same return state conditions as described under 2255 GSS_Init_sec_context(). 2257 The lifetime_rec return value is significant only in conjunction with 2258 GSS_S_COMPLETE major_status, and indicates the length of time for 2259 which the context will be valid, expressed as an offset from the 2260 present. 2262 The returned mech_type value indicates the specific mechanism 2263 employed on the context; it will never indicate the value for 2264 "default". A valid mech_type result must be returned whenever 2265 GSS_S_COMPLETE status is indicated; GSS-API implementations may (but 2266 are not required to) also return mech_type along with predecessor 2267 calls indicating GSS_S_CONTINUE_NEEDED status. For the case of 2268 mechanisms which themselves perform negotiation, the returned 2269 mech_type result may indicate selection of a mechanism identified by 2270 an OID different than that passed in the input mech_type argument, 2271 and the returned value may change between successive calls returning 2272 GSS_S_CONTINUE_NEEDED and the final call returning GSS_S_COMPLETE. 2274 The delegated_cred_handle result is significant only when deleg_state 2275 is TRUE, and provides a means for the target to reference the 2276 delegated credentials. The output_token result, when non-NULL, 2277 provides a context-level token to be returned to the context 2278 initiator to continue a multi-step context establishment sequence. As 2279 noted with GSS_Init_sec_context(), any returned token should be 2280 transferred to the context's peer (in this case, the context 2281 initiator), independent of the value of the accompanying returned 2282 major_status. 2284 Note: A target must be able to distinguish a context-level 2285 input_token, which is passed to GSS_Accept_sec_context(), from the 2286 per-message data elements passed to GSS_VerifyMIC() or GSS_Unwrap(). 2287 These data elements may arrive in a single application message, and 2288 GSS_Accept_sec_context() must be performed before per-message 2289 processing can be performed successfully. 2291 2.2.3: GSS_Delete_sec_context call 2293 Input: 2295 o context_handle CONTEXT HANDLE 2297 Outputs: 2299 o major_status INTEGER, 2301 o minor_status INTEGER, 2303 o output_context_token OCTET STRING 2305 Return major_status codes: 2307 o GSS_S_COMPLETE indicates that the context was recognized, and that 2308 relevant context-specific information was flushed. If the caller 2309 provides a non-null buffer to receive an output_context_token, and 2310 the mechanism returns a non-NULL token into that buffer, the 2311 returned output_context_token is ready for transfer to the 2312 context's peer. 2314 o GSS_S_NO_CONTEXT indicates that no valid context was recognized 2315 for the input context_handle provided, so no deletion was 2316 performed. 2318 o GSS_S_FAILURE indicates that the context is recognized, but 2319 that the GSS_Delete_sec_context() operation could not be 2320 performed for reasons unspecified at the GSS-API level. 2322 This call can be made by either peer in a security context, to flush 2323 context-specific information. Once a non-zero output_context_handle 2324 has been returned by context establishment calls, GSS-API callers 2325 should call GSS_Delete_sec_context() to release context-related 2326 resources if errors occur in later phases of context establishment, 2327 or when an established context is no longer required. This call may 2328 block pending network interactions for mech_types in which active 2329 notification must be made to a central server when a security context 2330 is to be deleted. 2332 If a non-null output_context_token parameter is provided by the 2333 caller, an output_context_token may be returned to the caller. If an 2334 output_context_token is provided to the caller, it can be passed to 2335 the context's peer to inform the peer's GSS-API implementation that 2336 the peer's corresponding context information can also be flushed. 2337 (Once a context is established, the peers involved are expected to 2338 retain cached credential and context-related information until the 2339 information's expiration time is reached or until a 2340 GSS_Delete_sec_context() call is made.) 2342 The facility for context_token usage to signal context deletion is 2343 retained for compatibility with GSS-API Version 1. For current 2344 usage, it is recommended that both peers to a context invoke 2345 GSS_Delete_sec_context() independently, passing a null 2346 output_context_token buffer to indicate that no context_token is 2347 required. Implementations of GSS_Delete_sec_context() should delete 2348 relevant locally-stored context information. 2350 Attempts to perform per-message processing on a deleted context will 2351 result in error returns. 2353 2.2.4: GSS_Process_context_token call 2355 Inputs: 2357 o context_handle CONTEXT HANDLE, 2359 o input_context_token OCTET STRING 2361 Outputs: 2363 o major_status INTEGER, 2365 o minor_status INTEGER, 2366 Return major_status codes: 2368 o GSS_S_COMPLETE indicates that the input_context_token was 2369 successfully processed in conjunction with the context 2370 referenced by context_handle. 2372 o GSS_S_DEFECTIVE_TOKEN indicates that consistency checks 2373 performed on the received context_token failed, preventing 2374 further processing from being performed with that token. 2376 o GSS_S_NO_CONTEXT indicates that no valid context was recognized 2377 for the input context_handle provided. 2379 o GSS_S_FAILURE indicates that the context is recognized, but 2380 that the GSS_Process_context_token() operation could not be 2381 performed for reasons unspecified at the GSS-API level. 2383 This call is used to process context_tokens received from a peer once 2384 a context has been established, with corresponding impact on 2385 context-level state information. One use for this facility is 2386 processing of the context_tokens generated by 2387 GSS_Delete_sec_context(); GSS_Process_context_token() will not block 2388 pending network interactions for that purpose. Another use is to 2389 process tokens indicating remote-peer context establishment failures 2390 after the point where the local GSS-API implementation has already 2391 indicated GSS_S_COMPLETE status. 2393 2.2.5: GSS_Context_time call 2395 Input: 2397 o context_handle CONTEXT HANDLE, 2399 Outputs: 2401 o major_status INTEGER, 2403 o minor_status INTEGER, 2405 o lifetime_rec INTEGER -- in seconds, or reserved value for 2406 -- INDEFINITE 2408 Return major_status codes: 2410 o GSS_S_COMPLETE indicates that the referenced context is valid, 2411 and will remain valid for the amount of time indicated in 2412 lifetime_rec. 2414 o GSS_S_CONTEXT_EXPIRED indicates that data items related to the 2415 referenced context have expired. 2417 o GSS_S_NO_CONTEXT indicates that no valid context was recognized 2418 for the input context_handle provided. 2420 o GSS_S_FAILURE indicates that the requested operation failed for 2421 reasons unspecified at the GSS-API level. 2423 This call is used to determine the amount of time for which a 2424 currently established context will remain valid. 2426 2.2.6: GSS_Inquire_context call 2428 Input: 2430 o context_handle CONTEXT HANDLE, 2432 Outputs: 2434 o major_status INTEGER, 2436 o minor_status INTEGER, 2438 o src_name INTERNAL NAME, -- name of context initiator, 2439 -- guaranteed to be MN; 2440 -- caller must release with GSS_Release_name() if returned 2442 o targ_name INTERNAL NAME, -- name of context target, 2443 -- guaranteed to be MN; 2444 -- caller must release with GSS_Release_name() if returned 2446 o lifetime_rec INTEGER -- in seconds, or reserved value for 2447 -- INDEFINITE or EXPIRED 2449 o mech_type OBJECT IDENTIFIER, -- the mechanism supporting this 2450 -- security context; caller should treat as read-only and not 2451 -- attempt to release 2453 o deleg_state BOOLEAN, 2455 o mutual_state BOOLEAN, 2457 o replay_det_state BOOLEAN, 2459 o sequence_state BOOLEAN, 2461 o anon_state BOOLEAN, 2462 o trans_state BOOLEAN, 2464 o prot_ready_state BOOLEAN, 2466 o conf_avail BOOLEAN, 2468 o integ_avail BOOLEAN, 2470 o locally_initiated BOOLEAN, -- TRUE if initiator, FALSE if acceptor 2472 o open BOOLEAN, -- TRUE if context fully established, FALSE 2473 -- if partly established (in CONTINUE_NEEDED state) 2475 Return major_status codes: 2477 o GSS_S_COMPLETE indicates that the referenced context is valid 2478 and that lifetime_rec, mech_type, 2479 deleg_state, mutual_state, replay_det_state, sequence_state, 2480 anon_state, trans_state, prot_ready_state, conf_avail, 2481 integ_avail, locally_initiated, and open return values describe the 2482 corresponding characteristics of the context. If open is TRUE, 2483 src_name and targ_name are valid in addition to the values 2484 listed above. 2486 o GSS_S_NO_CONTEXT indicates that no valid context was recognized 2487 for the input context_handle provided. Return values other than 2488 major_status and minor_status are undefined. 2490 o GSS_S_FAILURE indicates that the requested operation failed for 2491 reasons unspecified at the GSS-API level. Return values other than 2492 major_status and minor_status are undefined. 2494 This call is used to extract information describing characteristics 2495 of a security context. Note that GSS-API implementations are 2496 expected to retain inquirable context data on a context until the 2497 context is released by a caller, even after the context has expired, 2498 although underlying cryptographic data elements may be deleted after 2499 expiration in order to limit their exposure. 2501 2.2.7: GSS_Wrap_size_limit call 2503 Inputs: 2505 o context_handle CONTEXT HANDLE, 2507 o qop INTEGER, 2509 o output_size INTEGER 2510 Outputs: 2512 o major_status INTEGER, 2514 o minor_status INTEGER, 2516 o max_input_size INTEGER 2518 Return major_status codes: 2520 o GSS_S_COMPLETE indicates a successful token size determination: 2521 an input message with a length in octets equal to the 2522 returned max_input_size value will, when passed to GSS_Wrap() 2523 for processing on the context identified by the context_handle 2524 parameter and with the quality of protection specifier provided 2525 in the qop parameter, yield an output token no larger than the 2526 value of the provided output_size parameter. 2528 o GSS_S_CONTEXT_EXPIRED indicates that the provided input 2529 context_handle is recognized, but that the referenced context has 2530 expired. Return values other than major_status and minor_status 2531 are undefined. 2533 o GSS_S_NO_CONTEXT indicates that no valid context was recognized 2534 for the input context_handle provided. Return values other than 2535 major_status and minor_status are undefined. 2537 o GSS_S_BAD_QOP indicates that the provided QOP value is not 2538 recognized or supported for the context. 2540 o GSS_S_FAILURE indicates that the requested operation failed for 2541 reasons unspecified at the GSS-API level. Return values other than 2542 major_status and minor_status are undefined. 2544 This call is used to determine the largest input datum which may be 2545 passed to GSS_Wrap() without yielding an output token larger than a 2546 caller-specified value. 2548 2.2.8: GSS_Export_sec_context call 2550 Inputs: 2552 o context_handle CONTEXT HANDLE 2554 Outputs: 2556 o major_status INTEGER, 2557 o minor_status INTEGER, 2559 o interprocess_token OCTET STRING -- caller must release 2560 -- with GSS_Release_buffer() 2562 Return major_status codes: 2564 o GSS_S_COMPLETE indicates that the referenced context has been 2565 successfully exported to a representation in the interprocess_token, 2566 and is no longer available for use by the caller. 2568 o GSS_S_UNAVAILABLE indicates that the context export facility 2569 is not available for use on the referenced context. (This status 2570 should occur only for contexts for which the trans_state value is 2571 FALSE.) Return values other than major_status and minor_status are 2572 undefined. 2574 o GSS_S_CONTEXT_EXPIRED indicates that the provided input 2575 context_handle is recognized, but that the referenced context has 2576 expired. Return values other than major_status and minor_status 2577 are undefined. 2579 o GSS_S_NO_CONTEXT indicates that no valid context was recognized 2580 for the input context_handle provided. Return values other than 2581 major_status and minor_status are undefined. 2583 o GSS_S_FAILURE indicates that the requested operation failed for 2584 reasons unspecified at the GSS-API level. Return values other than 2585 major_status and minor_status are undefined. 2587 This call generates an interprocess token for transfer to another 2588 process within an end system, in order to transfer control of a 2589 security context to that process. The recipient of the interprocess 2590 token will call GSS_Import_sec_context() to accept the transfer. The 2591 GSS_Export_sec_context() operation is defined for use only with 2592 security contexts which are fully and successfully established (i.e., 2593 those for which GSS_Init_sec_context() and GSS_Accept_sec_context() 2594 have returned GSS_S_COMPLETE major_status). 2596 A successful GSS_Export_sec_context() operation deactivates the 2597 security context for the calling process; for this case, the GSS-API 2598 implementation shall deallocate all process-wide resources associated 2599 with the security context and shall set the context_handle to 2600 GSS_C_NO_CONTEXT. In the event of an error that makes it impossible 2601 to complete export of the security context, the GSS-API 2602 implementation must not return an interprocess token and should 2603 strive to leave the security context referenced by the context_handle 2604 untouched. If this is impossible, it is permissible for the 2605 implementation to delete the security context, provided that it also 2606 sets te context_handle parameter to GSS_C_NO_CONTEXT. 2608 Portable callers must not assume that a given interprocess token can 2609 be imported by GSS_Import_sec_context() more than once, thereby 2610 creating multiple instantiations of a single context. GSS-API 2611 implementations may detect and reject attempted multiple imports, but 2612 are not required to do so. 2614 The internal representation contained within the interprocess token 2615 is an implementation-defined local matter. Interprocess tokens 2616 cannot be assumed to be transferable across different GSS-API 2617 implementations. 2619 It is recommended that GSS-API implementations adopt policies suited 2620 to their operational environments in order to define the set of 2621 processes eligible to import a context, but specific constraints in 2622 this area are local matters. Candidate examples include transfers 2623 between processes operating on behalf of the same user identity, or 2624 processes comprising a common job. However, it may be impossible to 2625 enforce such policies in some implementations. 2627 In support of the above goals, implementations may protect the 2628 transferred context data by using cryptography to protect data within 2629 the interprocess token, or by using interprocess tokens as a means to 2630 reference local interprocess communication facilities (protected by 2631 other means) rather than storing the context data directly within the 2632 tokens. 2634 Transfer of an open context may, for certain mechanisms and 2635 implementations, reveal data about the credential which was used to 2636 establish the context. Callers should, therefore, be cautious about 2637 the trustworthiness of processes to which they transfer contexts. 2638 Although the GSS-API implementation may provide its own set of 2639 protections over the exported context, the caller is responsible for 2640 protecting the interprocess token from disclosure, and for taking 2641 care that the context is transferred to an appropriate destination 2642 process. 2644 2.2.9: GSS_Import_sec_context call 2646 Inputs: 2648 o interprocess_token OCTET STRING 2650 Outputs: 2652 o major_status INTEGER, 2653 o minor_status INTEGER, 2655 o context_handle CONTEXT HANDLE -- if successfully returned, 2656 -- caller must release with GSS_Delete_sec_context() 2658 Return major_status codes: 2660 o GSS_S_COMPLETE indicates that the context represented by the 2661 input interprocess_token has been successfully transferred to 2662 the caller, and is available for future use via the output 2663 context_handle. 2665 o GSS_S_CONTEXT_EXPIRED indicates that the context represented by 2666 the input interprocess_token has expired. Return values other 2667 than major_status and minor_status are undefined. 2669 o GSS_S_NO_CONTEXT indicates that the context represented by the 2670 input interprocess_token was invalid. Return values other than 2671 major_status and minor_status are undefined. 2673 o GSS_S_DEFECTIVE_TOKEN indicates that the input interprocess_token 2674 was defective. Return values other than major_status and 2675 minor_status are undefined. 2677 o GSS_S_UNAVAILABLE indicates that the context import facility 2678 is not available for use on the referenced context. Return values 2679 other than major_status and minor_status are undefined. 2681 o GSS_S_UNAUTHORIZED indicates that the context represented by 2682 the input interprocess_token is unauthorized for transfer to the 2683 caller. Return values other than major_status and minor_status 2684 are undefined. 2686 o GSS_S_FAILURE indicates that the requested operation failed for 2687 reasons unspecified at the GSS-API level. Return values other than 2688 major_status and minor_status are undefined. 2690 This call processes an interprocess token generated by 2691 GSS_Export_sec_context(), making the transferred context available 2692 for use by the caller. After a successful GSS_Import_sec_context() 2693 operation, the imported context is available for use by the importing 2694 process. In particular, the imported context is usable for all per- 2695 message operations and may be deleted or exported by its importer. 2696 The inability to receive delegated credentials through 2697 gss_import_sec_context() precludes establishment of new contexts 2698 based on information delegated to the importer's end system within 2699 the context which is being imported, unless those delegated 2700 credentials are obtained through separate routines (e.g., XGSS-API 2701 calls) outside the GSS-V2 definition. 2703 For further discussion of the security and authorization issues 2704 regarding this call, please see the discussion in Section 2.2.8. 2706 2.3: Per-message calls 2708 This group of calls is used to perform per-message protection 2709 processing on an established security context. None of these calls 2710 block pending network interactions. These calls may be invoked by a 2711 context's initiator or by the context's target. The four members of 2712 this group should be considered as two pairs; the output from 2713 GSS_GetMIC() is properly input to GSS_VerifyMIC(), and the output 2714 from GSS_Wrap() is properly input to GSS_Unwrap(). 2716 GSS_GetMIC() and GSS_VerifyMIC() support data origin authentication 2717 and data integrity services. When GSS_GetMIC() is invoked on an input 2718 message, it yields a per-message token containing data items which 2719 allow underlying mechanisms to provide the specified security 2720 services. The original message, along with the generated per-message 2721 token, is passed to the remote peer; these two data elements are 2722 processed by GSS_VerifyMIC(), which validates the message in 2723 conjunction with the separate token. 2725 GSS_Wrap() and GSS_Unwrap() support caller-requested confidentiality 2726 in addition to the data origin authentication and data integrity 2727 services offered by GSS_GetMIC() and GSS_VerifyMIC(). GSS_Wrap() 2728 outputs a single data element, encapsulating optionally enciphered 2729 user data as well as associated token data items. The data element 2730 output from GSS_Wrap() is passed to the remote peer and processed by 2731 GSS_Unwrap() at that system. GSS_Unwrap() combines decipherment (as 2732 required) with validation of data items related to authentication and 2733 integrity. 2735 Although zero-length tokens are never returned by GSS calls for 2736 transfer to a context's peer, a zero-length object may be passed by a 2737 caller into GSS_Wrap(), in which case the corresponding peer calling 2738 GSS_Unwrap() on the transferred token will receive a zero-length 2739 object as output from GSS_Unwrap(). Similarly, GSS_GetMIC() can be 2740 called on an empty object, yielding a MIC which GSS_VerifyMIC() will 2741 successfully verify against the active security context in 2742 conjunction with a zero-length object. 2744 2.3.1: GSS_GetMIC call 2746 Note: This call is functionally equivalent to the GSS_Sign call as 2747 defined in previous versions of this specification. In the interests 2748 of backward compatibility, it is recommended that implementations 2749 support this function under both names for the present; future 2750 references to this function as GSS_Sign are deprecated. 2752 Inputs: 2754 o context_handle CONTEXT HANDLE, 2756 o qop_req INTEGER, -- 0 specifies default QOP 2758 o message OCTET STRING 2760 Outputs: 2762 o major_status INTEGER, 2764 o minor_status INTEGER, 2766 o per_msg_token OCTET STRING -- caller must release 2767 -- with GSS_Release_buffer() 2769 Return major_status codes: 2771 o GSS_S_COMPLETE indicates that an integrity check, suitable for an 2772 established security context, was successfully applied and 2773 that the message and corresponding per_msg_token are ready 2774 for transmission. 2776 o GSS_S_CONTEXT_EXPIRED indicates that context-related data 2777 items have expired, so that the requested operation cannot be 2778 performed. 2780 o GSS_S_NO_CONTEXT indicates that no valid context was recognized 2781 for the input context_handle provided. 2783 o GSS_S_BAD_QOP indicates that the provided QOP value is not 2784 recognized or supported for the context. 2786 o GSS_S_FAILURE indicates that the context is recognized, but 2787 that the requested operation could not be performed for 2788 reasons unspecified at the GSS-API level. 2790 Using the security context referenced by context_handle, apply an 2791 integrity check to the input message (along with timestamps and/or 2792 other data included in support of mech_type-specific mechanisms) and 2793 return the result in per_msg_token. The qop_req parameter, 2794 interpretation of which is discussed in Section 1.2.4, allows 2795 quality-of-protection control. The caller passes the message and the 2796 per_msg_token to the target. 2798 The GSS_GetMIC() function completes before the message and 2799 per_msg_token is sent to the peer; successful application of 2800 GSS_GetMIC() does not guarantee that a corresponding GSS_VerifyMIC() 2801 has been (or can necessarily be) performed successfully when the 2802 message arrives at the destination. 2804 Mechanisms which do not support per-message protection services 2805 should return GSS_S_FAILURE if this routine is called. 2807 2.3.2: GSS_VerifyMIC call 2809 Note: This call is functionally equivalent to the GSS_Verify call as 2810 defined in previous versions of this specification. In the interests 2811 of backward compatibility, it is recommended that implementations 2812 support this function under both names for the present; future 2813 references to this function as GSS_Verify are deprecated. 2815 Inputs: 2817 o context_handle CONTEXT HANDLE, 2819 o message OCTET STRING, 2821 o per_msg_token OCTET STRING 2823 Outputs: 2825 o qop_state INTEGER, 2827 o major_status INTEGER, 2829 o minor_status INTEGER, 2831 Return major_status codes: 2833 o GSS_S_COMPLETE indicates that the message was successfully 2834 verified. 2836 o GSS_S_DEFECTIVE_TOKEN indicates that consistency checks performed 2837 on the received per_msg_token failed, preventing 2838 further processing from being performed with that token. 2840 o GSS_S_BAD_SIG (GSS_S_BAD_MIC) indicates that the received 2841 per_msg_token contains an incorrect integrity check for the 2842 message. 2844 o GSS_S_DUPLICATE_TOKEN, GSS_S_OLD_TOKEN, GSS_S_UNSEQ_TOKEN, 2845 and GSS_S_GAP_TOKEN values appear in conjunction with the 2846 optional per-message replay detection features described 2847 in Section 1.2.3; their semantics are described in that section. 2849 o GSS_S_CONTEXT_EXPIRED indicates that context-related data 2850 items have expired, so that the requested operation cannot be 2851 performed. 2853 o GSS_S_NO_CONTEXT indicates that no valid context was recognized 2854 for the input context_handle provided. 2856 o GSS_S_FAILURE indicates that the context is recognized, but 2857 that the GSS_VerifyMIC() operation could not be performed for 2858 reasons unspecified at the GSS-API level. 2860 Using the security context referenced by context_handle, verify that 2861 the input per_msg_token contains an appropriate integrity check for 2862 the input message, and apply any active replay detection or 2863 sequencing features. Returns an indication of the quality-of- 2864 protection applied to the processed message in the qop_state result. 2866 Mechanisms which do not support per-message protection services 2867 should return GSS_S_FAILURE if this routine is called. 2869 2.3.3: GSS_Wrap call 2871 Note: This call is functionally equivalent to the GSS_Seal call as 2872 defined in previous versions of this specification. In the interests 2873 of backward compatibility, it is recommended that implementations 2874 support this function under both names for the present; future 2875 references to this function as GSS_Seal are deprecated. 2877 Inputs: 2879 o context_handle CONTEXT HANDLE, 2881 o conf_req_flag BOOLEAN, 2883 o qop_req INTEGER, -- 0 specifies default QOP 2885 o input_message OCTET STRING 2887 Outputs: 2889 o major_status INTEGER, 2891 o minor_status INTEGER, 2893 o conf_state BOOLEAN, 2894 o output_message OCTET STRING -- caller must release with 2895 -- GSS_Release_buffer() 2897 Return major_status codes: 2899 o GSS_S_COMPLETE indicates that the input_message was successfully 2900 processed and that the output_message is ready for 2901 transmission. 2903 o GSS_S_CONTEXT_EXPIRED indicates that context-related data 2904 items have expired, so that the requested operation cannot be 2905 performed. 2907 o GSS_S_NO_CONTEXT indicates that no valid context was recognized 2908 for the input context_handle provided. 2910 o GSS_S_BAD_QOP indicates that the provided QOP value is not 2911 recognized or supported for the context. 2913 o GSS_S_FAILURE indicates that the context is recognized, but 2914 that the GSS_Wrap() operation could not be performed for 2915 reasons unspecified at the GSS-API level. 2917 Performs the data origin authentication and data integrity functions 2918 of GSS_GetMIC(). If the input conf_req_flag is TRUE, requests that 2919 confidentiality be applied to the input_message. Confidentiality may 2920 not be supported in all mech_types or by all implementations; the 2921 returned conf_state flag indicates whether confidentiality was 2922 provided for the input_message. The qop_req parameter, interpretation 2923 of which is discussed in Section 1.2.4, allows quality-of-protection 2924 control. 2926 In all cases, the GSS_Wrap() call yields a single output_message data 2927 element containing (optionally enciphered) user data as well as 2928 control information. 2930 Mechanisms which do not support per-message protection services 2931 should return GSS_S_FAILURE if this routine is called. 2933 2.3.4: GSS_Unwrap call 2935 Note: This call is functionally equivalent to the GSS_Unseal call as 2936 defined in previous versions of this specification. In the interests 2937 of backward compatibility, it is recommended that implementations 2938 support this function under both names for the present; future 2939 references to this function as GSS_Unseal are deprecated. 2941 Inputs: 2943 o context_handle CONTEXT HANDLE, 2945 o input_message OCTET STRING 2947 Outputs: 2949 o conf_state BOOLEAN, 2951 o qop_state INTEGER, 2953 o major_status INTEGER, 2955 o minor_status INTEGER, 2957 o output_message OCTET STRING -- caller must release with 2958 -- GSS_Release_buffer() 2960 Return major_status codes: 2962 o GSS_S_COMPLETE indicates that the input_message was 2963 successfully processed and that the resulting output_message is 2964 available. 2966 o GSS_S_DEFECTIVE_TOKEN indicates that consistency checks performed 2967 on the per_msg_token extracted from the input_message 2968 failed, preventing further processing from being performed. 2970 o GSS_S_BAD_SIG (GSS_S_BAD_MIC) indicates that an incorrect 2971 integrity check was detected for the message. 2973 o GSS_S_DUPLICATE_TOKEN, GSS_S_OLD_TOKEN, GSS_S_UNSEQ_TOKEN, 2974 and GSS_S_GAP_TOKEN values appear in conjunction with the 2975 optional per-message replay detection features described 2976 in Section 1.2.3; their semantics are described in that section. 2978 o GSS_S_CONTEXT_EXPIRED indicates that context-related data 2979 items have expired, so that the requested operation cannot be 2980 performed. 2982 o GSS_S_NO_CONTEXT indicates that no valid context was recognized 2983 for the input context_handle provided. 2985 o GSS_S_FAILURE indicates that the context is recognized, but 2986 that the GSS_Unwrap() operation could not be performed for 2987 reasons unspecified at the GSS-API level. 2989 Processes a data element generated (and optionally enciphered) by 2990 GSS_Wrap(), provided as input_message. The returned conf_state value 2991 indicates whether confidentiality was applied to the input_message. 2992 If conf_state is TRUE, GSS_Unwrap() has deciphered the input_message. 2993 Returns an indication of the quality-of-protection applied to the 2994 processed message in the qop_state result. GSS_Unwrap() performs the 2995 data integrity and data origin authentication checking functions of 2996 GSS_VerifyMIC() on the plaintext data. Plaintext data is returned in 2997 output_message. 2999 Mechanisms which do not support per-message protection services 3000 should return GSS_S_FAILURE if this routine is called. 3002 2.4: Support calls 3004 This group of calls provides support functions useful to GSS-API 3005 callers, independent of the state of established contexts. Their 3006 characterization with regard to blocking or non-blocking status in 3007 terms of network interactions is unspecified. 3009 2.4.1: GSS_Display_status call 3011 Inputs: 3013 o status_value INTEGER, -- GSS-API major_status or minor_status 3014 -- return value 3016 o status_type INTEGER, -- 1 if major_status, 2 if minor_status 3018 o mech_type OBJECT IDENTIFIER -- mech_type to be used for 3019 -- minor_status translation 3021 Outputs: 3023 o major_status INTEGER, 3025 o minor_status INTEGER, 3027 o status_string_set SET OF OCTET STRING -- required calls for 3028 -- release by caller are specific to language bindings 3030 Return major_status codes: 3032 o GSS_S_COMPLETE indicates that a valid printable status 3033 representation (possibly representing more than one status event 3034 encoded within the status_value) is available in the returned 3035 status_string_set. 3037 o GSS_S_BAD_MECH indicates that translation in accordance with an 3038 unsupported mech_type was requested, so translation could not 3039 be performed. 3041 o GSS_S_BAD_STATUS indicates that the input status_value was 3042 invalid, or that the input status_type carried a value other 3043 than 1 or 2, so translation could not be performed. 3045 o GSS_S_FAILURE indicates that the requested operation could not 3046 be performed for reasons unspecified at the GSS-API level. 3048 Provides a means for callers to translate GSS-API-returned major and 3049 minor status codes into printable string representations. Note: some 3050 language bindings may employ an iterative approach in order to emit 3051 successive status components; this approach is acceptable but not 3052 required for conformance with the current specification. 3054 Although not contemplated in [RFC-2078], it has been observed that 3055 some existing GSS-API implementations return GSS_S_CONTINUE_NEEDED 3056 status when iterating through successive messages returned from 3057 GSS_Display_status(). This behavior is deprecated; 3058 GSS_S_CONTINUE_NEEDED should be returned only by 3059 GSS_Init_sec_context() and GSS_Accept_sec_context(). For maximal 3060 portability, however, it is recommended that defensive callers be 3061 able to accept and ignore GSS_S_CONTINUE_NEEDED status if indicated 3062 by GSS_Display_status() or any other call other than 3063 GSS_Init_sec_context() or GSS_Accept_sec_context(). 3065 2.4.2: GSS_Indicate_mechs call 3067 Input: 3069 o (none) 3071 Outputs: 3073 o major_status INTEGER, 3075 o minor_status INTEGER, 3077 o mech_set SET OF OBJECT IDENTIFIER -- caller must release 3078 -- with GSS_Release_oid_set() 3080 Return major_status codes: 3082 o GSS_S_COMPLETE indicates that a set of available mechanisms has 3083 been returned in mech_set. 3085 o GSS_S_FAILURE indicates that the requested operation could not 3086 be performed for reasons unspecified at the GSS-API level. 3088 Allows callers to determine the set of mechanism types available on 3089 the local system. This call is intended for support of specialized 3090 callers who need to request non-default mech_type sets from GSS-API 3091 calls which accept input mechanism type specifiers. 3093 2.4.3: GSS_Compare_name call 3095 Inputs: 3097 o name1 INTERNAL NAME, 3099 o name2 INTERNAL NAME 3101 Outputs: 3103 o major_status INTEGER, 3105 o minor_status INTEGER, 3107 o name_equal BOOLEAN 3109 Return major_status codes: 3111 o GSS_S_COMPLETE indicates that name1 and name2 were comparable, 3112 and that the name_equal result indicates whether name1 and 3113 name2 represent the same entity. 3115 o GSS_S_BAD_NAMETYPE indicates that 3116 the two input names' types are different and incomparable, so that 3117 the comparison operation could not be completed. 3119 o GSS_S_BAD_NAME indicates that one or both of the input names 3120 was ill-formed in terms of its internal type specifier, so 3121 the comparison operation could not be completed. 3123 o GSS_S_FAILURE indicates that the call's operation could not 3124 be performed for reasons unspecified at the GSS-API level. 3126 Allows callers to compare two internal name representations to 3127 determine whether they refer to the same entity. If either name 3128 presented to GSS_Compare_name() denotes an anonymous principal, 3129 GSS_Compare_name() shall indicate FALSE. It is not required that 3130 either or both inputs name1 and name2 be MNs; for some 3131 implementations and cases, GSS_S_BAD_NAMETYPE may be returned, 3132 indicating name incomparability, for the case where neither input 3133 name is an MN. 3135 2.4.4: GSS_Display_name call 3136 Inputs: 3138 o name INTERNAL NAME 3140 Outputs: 3142 o major_status INTEGER, 3144 o minor_status INTEGER, 3146 o name_string OCTET STRING, -- caller must release 3147 -- with GSS_Release_buffer() 3149 o name_type OBJECT IDENTIFIER -- caller should treat 3150 -- as read-only; does not need to be released 3152 Return major_status codes: 3154 o GSS_S_COMPLETE indicates that a valid printable name 3155 representation is available in the returned name_string. 3157 o GSS_S_BAD_NAME indicates that the contents of the provided name 3158 were inconsistent with the internally-indicated name type, so 3159 no printable representation could be generated. 3161 o GSS_S_FAILURE indicates that the requested operation could not 3162 be performed for reasons unspecified at the GSS-API level. 3164 Allows callers to translate an internal name representation into a 3165 printable form with associated namespace type descriptor. The syntax 3166 of the printable form is a local matter. 3168 If the input name represents an anonymous identity, a reserved value 3169 (GSS_C_NT_ANONYMOUS) shall be returned for name_type. 3171 The GSS_C_NO_OID name type is to be returned only when the 3172 corresponding internal name was created through import with 3173 GSS_C_NO_OID. It is acceptable for mechanisms to normalize names 3174 imported with GSS_C_NO_OID into other supported types and, therefore, 3175 to display them with types other than GSS_C_NO_OID. 3177 2.4.5: GSS_Import_name call 3179 Inputs: 3181 o input_name_string OCTET STRING, 3183 o input_name_type OBJECT IDENTIFIER 3184 Outputs: 3186 o major_status INTEGER, 3188 o minor_status INTEGER, 3190 o output_name INTERNAL NAME -- caller must release with 3191 -- GSS_Release_name() 3193 Return major_status codes: 3195 o GSS_S_COMPLETE indicates that a valid name representation is 3196 output in output_name and described by the type value in 3197 output_name_type. 3199 o GSS_S_BAD_NAMETYPE indicates that the input_name_type is 3200 unsupported by the applicable underlying GSS-API mechanism(s), 3201 so the import operation could not be completed. 3203 o GSS_S_BAD_NAME indicates that the provided input_name_string 3204 is ill-formed in terms of the input_name_type, so the import 3205 operation could not be completed. 3207 o GSS_S_BAD_MECH indicates that the input presented for import was 3208 an exported name object and that its enclosed mechanism type was not 3209 recognized or was unsupported by the GSS-API implementation. 3211 o GSS_S_FAILURE indicates that the requested operation could not 3212 be performed for reasons unspecified at the GSS-API level. 3214 Allows callers to provide a name representation as a contiguous octet 3215 string, designate the type of namespace in conjunction with which it 3216 should be parsed, and convert that representation to an internal form 3217 suitable for input to other GSS-API routines. The syntax of the 3218 input_name_string is defined in conjunction with its associated name 3219 type; depending on the input_name_type, the associated 3220 input_name_string may or may not be a printable string. If the 3221 input_name_type's value is GSS_C_NO_OID, a mechanism-specific default 3222 printable syntax (which shall be specified in the corresponding GSS- 3223 V2 mechanism specification) is assumed for the input_name_string; 3224 other input_name_type values as registered by GSS-API implementations 3225 can be used to indicate specific non-default name syntaxes. Note: The 3226 input_name_type argument serves to describe and qualify the 3227 interpretation of the associated input_name_string; it does not 3228 specify the data type of the returned output_name. 3230 If a mechanism claims support for a particular name type, its 3231 GSS_Import_name() operation shall be able to accept all possible 3232 values conformant to the external name syntax as defined for that 3233 name type. These imported values may correspond to: 3235 (1) locally registered entities (for which credentials may be 3236 acquired), 3238 (2) non-local entities (for which local credentials cannot be 3239 acquired, but which may be referenced as targets of initiated 3240 security contexts or initiators of accepted security contexts), 3241 or to 3243 (3) neither of the above. 3245 Determination of whether a particular name belongs to class (1), (2), 3246 or (3) as described above is not guaranteed to be performed by the 3247 GSS_Import_name() function. 3249 The internal name generated by a GSS_Import_name() operation may be a 3250 single-mechanism MN, and is likely to be an MN within a single- 3251 mechanism implementation, but portable callers must not depend on 3252 this property (and must not, therefore, assume that the output from 3253 GSS_Import_name() can be passed directly to GSS_Export_name() without 3254 first being processed through GSS_Canonicalize_name()). 3256 2.4.6: GSS_Release_name call 3258 Inputs: 3260 o name INTERNAL NAME 3262 Outputs: 3264 o major_status INTEGER, 3266 o minor_status INTEGER 3268 Return major_status codes: 3270 o GSS_S_COMPLETE indicates that the storage associated with the 3271 input name was successfully released. 3273 o GSS_S_BAD_NAME indicates that the input name argument did not 3274 contain a valid name. 3276 o GSS_S_FAILURE indicates that the requested operation could not 3277 be performed for reasons unspecified at the GSS-API level. 3279 Allows callers to release the storage associated with an internal 3280 name representation. This call's specific behavior depends on the 3281 language and programming environment within which a GSS-API 3282 implementation operates, and is therefore detailed within applicable 3283 bindings specifications; in particular, implementation and invocation 3284 of this call may be superfluous (and may be omitted) within bindings 3285 where memory management is automatic. 3287 2.4.7: GSS_Release_buffer call 3289 Inputs: 3291 o buffer OCTET STRING 3293 Outputs: 3295 o major_status INTEGER, 3297 o minor_status INTEGER 3299 Return major_status codes: 3301 o GSS_S_COMPLETE indicates that the storage associated with the 3302 input buffer was successfully released. 3304 o GSS_S_FAILURE indicates that the requested operation could not 3305 be performed for reasons unspecified at the GSS-API level. 3307 Allows callers to release the storage associated with an OCTET STRING 3308 buffer allocated by another GSS-API call. This call's specific 3309 behavior depends on the language and programming environment within 3310 which a GSS-API implementation operates, and is therefore detailed 3311 within applicable bindings specifications; in particular, 3312 implementation and invocation of this call may be superfluous (and 3313 may be omitted) within bindings where memory management is automatic. 3315 2.4.8: GSS_Release_OID_set call 3317 Inputs: 3319 o buffer SET OF OBJECT IDENTIFIER 3321 Outputs: 3323 o major_status INTEGER, 3325 o minor_status INTEGER 3327 Return major_status codes: 3329 o GSS_S_COMPLETE indicates that the storage associated with the 3330 input object identifier set was successfully released. 3332 o GSS_S_FAILURE indicates that the requested operation could not 3333 be performed for reasons unspecified at the GSS-API level. 3335 Allows callers to release the storage associated with an object 3336 identifier set object allocated by another GSS-API call. This call's 3337 specific behavior depends on the language and programming environment 3338 within which a GSS-API implementation operates, and is therefore 3339 detailed within applicable bindings specifications; in particular, 3340 implementation and invocation of this call may be superfluous (and 3341 may be omitted) within bindings where memory management is automatic. 3343 2.4.9: GSS_Create_empty_OID_set call 3345 Inputs: 3347 o (none) 3349 Outputs: 3351 o major_status INTEGER, 3353 o minor_status INTEGER, 3355 o oid_set SET OF OBJECT IDENTIFIER -- caller must release 3356 -- with GSS_Release_oid_set() 3358 Return major_status codes: 3360 o GSS_S_COMPLETE indicates successful completion 3362 o GSS_S_FAILURE indicates that the operation failed 3364 Creates an object identifier set containing no object identifiers, to 3365 which members may be subsequently added using the 3366 GSS_Add_OID_set_member() routine. These routines are intended to be 3367 used to construct sets of mechanism object identifiers, for input to 3368 GSS_Acquire_cred(). 3370 2.4.10: GSS_Add_OID_set_member call 3372 Inputs: 3374 o member_oid OBJECT IDENTIFIER, 3375 o oid_set SET OF OBJECT IDENTIFIER 3377 Outputs: 3379 o major_status INTEGER, 3381 o minor_status INTEGER, 3383 Return major_status codes: 3385 o GSS_S_COMPLETE indicates successful completion 3387 o GSS_S_FAILURE indicates that the operation failed 3389 Adds an Object Identifier to an Object Identifier set. This routine 3390 is intended for use in conjunction with GSS_Create_empty_OID_set() 3391 when constructing a set of mechanism OIDs for input to 3392 GSS_Acquire_cred(). 3394 2.4.11: GSS_Test_OID_set_member call 3396 Inputs: 3398 o member OBJECT IDENTIFIER, 3400 o set SET OF OBJECT IDENTIFIER 3402 Outputs: 3404 o major_status INTEGER, 3406 o minor_status INTEGER, 3408 o present BOOLEAN 3410 Return major_status codes: 3412 o GSS_S_COMPLETE indicates successful completion 3414 o GSS_S_FAILURE indicates that the operation failed 3416 Interrogates an Object Identifier set to determine whether a 3417 specified Object Identifier is a member. This routine is intended to 3418 be used with OID sets returned by GSS_Indicate_mechs(), 3419 GSS_Acquire_cred(), and GSS_Inquire_cred(). 3421 2.4.12: GSS_Inquire_names_for_mech call 3423 Input: 3425 o input_mech_type OBJECT IDENTIFIER, -- mechanism type 3427 Outputs: 3429 o major_status INTEGER, 3431 o minor_status INTEGER, 3433 o name_type_set SET OF OBJECT IDENTIFIER -- caller must release 3434 -- with GSS_Release_oid_set() 3436 Return major_status codes: 3438 o GSS_S_COMPLETE indicates that the output name_type_set contains 3439 a list of name types which are supported by the locally available 3440 mechanism identified by input_mech_type. 3442 o GSS_S_BAD_MECH indicates that the mechanism identified by 3443 input_mech_type was unsupported within the local implementation, 3444 causing the query to fail. 3446 o GSS_S_FAILURE indicates that the requested operation could not 3447 be performed for reasons unspecified at the GSS-API level. 3449 Allows callers to determine the set of name types which are 3450 supportable by a specific locally-available mechanism. 3452 2.4.13: GSS_Inquire_mechs_for_name call 3454 Inputs: 3456 o input_name INTERNAL NAME, 3458 Outputs: 3460 o major_status INTEGER, 3462 o minor_status INTEGER, 3464 o mech_types SET OF OBJECT IDENTIFIER -- caller must release 3465 -- with GSS_Release_oid_set() 3467 Return major_status codes: 3469 o GSS_S_COMPLETE indicates that a set of object identifiers, 3470 corresponding to the set of mechanisms suitable for processing 3471 the input_name, is available in mech_types. 3473 o GSS_S_BAD_NAME indicates that the input_name was ill-formed 3474 and could not be processed. 3476 o GSS_S_BAD_NAMETYPE indicates that the input_name parameter 3477 contained an invalid name type or a name type unsupported 3478 by the GSS-API implementation. 3480 o GSS_S_FAILURE indicates that the requested operation could not 3481 be performed for reasons unspecified at the GSS-API level. 3483 This routine returns the mechanism set with which the input_name may 3484 be processed. 3486 Each mechanism returned will recognize at least one element within 3487 the name. It is permissible for this routine to be implemented within 3488 a mechanism-independent GSS-API layer, using the type information 3489 contained within the presented name, and based on registration 3490 information provided by individual mechanism implementations. This 3491 means that the returned mech_types result may indicate that a 3492 particular mechanism will understand a particular name when in fact 3493 it would refuse to accept that name as input to 3494 GSS_Canonicalize_name(), GSS_Init_sec_context(), GSS_Acquire_cred(), 3495 or GSS_Add_cred(), due to some property of the particular name rather 3496 than a property of the name type. Thus, this routine should be used 3497 only as a pre-filter for a call to a subsequent mechanism-specific 3498 routine. 3500 2.4.14: GSS_Canonicalize_name call 3502 Inputs: 3504 o input_name INTERNAL NAME, 3506 o mech_type OBJECT IDENTIFIER -- must be explicit mechanism, 3507 -- not "default" specifier or identifier of negotiating mechanism 3509 Outputs: 3511 o major_status INTEGER, 3513 o minor_status INTEGER, 3515 o output_name INTERNAL NAME -- caller must release with 3516 -- GSS_Release_name() 3518 Return major_status codes: 3520 o GSS_S_COMPLETE indicates that a mechanism-specific reduction of 3521 the input_name, as processed by the mechanism identified by 3522 mech_type, is available in output_name. 3524 o GSS_S_BAD_MECH indicates that the identified mechanism is 3525 unsupported for this operation; this may correspond either to 3526 a mechanism wholly unsupported by the local GSS-API implementation 3527 or to a negotiating mechanism with which the canonicalization 3528 operation cannot be performed. 3530 o GSS_S_BAD_NAMETYPE indicates that the input name does not 3531 contain an element with suitable type for processing by the 3532 identified mechanism. 3534 o GSS_S_BAD_NAME indicates that the input name contains an 3535 element with suitable type for processing by the identified 3536 mechanism, but that this element could not be processed 3537 successfully. 3539 o GSS_S_FAILURE indicates that the requested operation could not 3540 be performed for reasons unspecified at the GSS-API level. 3542 This routine reduces a GSS-API internal name input_name, which may in 3543 general contain elements corresponding to multiple mechanisms, to a 3544 mechanism-specific Mechanism Name (MN) output_name by applying the 3545 translations corresponding to the mechanism identified by mech_type. 3546 The contents of input_name are unaffected by the 3547 GSS_Canonicalize_name() operation. References to output_name will 3548 remain valid until output_name is released, independent of whether or 3549 not input_name is subsequently released. 3551 2.4.15: GSS_Export_name call 3553 Inputs: 3555 o input_name INTERNAL NAME, -- required to be MN 3557 Outputs: 3559 o major_status INTEGER, 3561 o minor_status INTEGER, 3563 o output_name OCTET STRING -- caller must release 3564 -- with GSS_Release_buffer() 3566 Return major_status codes: 3568 o GSS_S_COMPLETE indicates that a flat representation of the 3569 input name is available in output_name. 3571 o GSS_S_NAME_NOT_MN indicates that the input name contained 3572 elements corresponding to multiple mechanisms, so cannot 3573 be exported into a single-mechanism flat form. 3575 o GSS_S_BAD_NAME indicates that the input name was an MN, 3576 but could not be processed. 3578 o GSS_S_BAD_NAMETYPE indicates that the input name was an MN, 3579 but that its type is unsupported by the GSS-API implementation. 3581 o GSS_S_FAILURE indicates that the requested operation could not 3582 be performed for reasons unspecified at the GSS-API level. 3584 This routine creates a flat name representation, suitable for 3585 bytewise comparison or for input to GSS_Import_name() in conjunction 3586 with the reserved GSS-API Exported Name Object OID, from a internal- 3587 form Mechanism Name (MN) as emitted, e.g., by GSS_Canonicalize_name() 3588 or GSS_Accept_sec_context(). 3590 The emitted GSS-API Exported Name Object is self-describing; no 3591 associated parameter-level OID need be emitted by this call. This 3592 flat representation consists of a mechanism-independent wrapper 3593 layer, defined in Section 3.2 of this document, enclosing a 3594 mechanism-defined name representation. 3596 In all cases, the flat name output by GSS_Export_name() to correspond 3597 to a particular input MN must be invariant over time within a 3598 particular installation. 3600 The GSS_S_NAME_NOT_MN status code is provided to enable 3601 implementations to reject input names which are not MNs. It is not, 3602 however, required for purposes of conformance to this specification 3603 that all non-MN input names must necessarily be rejected. 3605 2.4.16: GSS_Duplicate_name call 3607 Inputs: 3609 o src_name INTERNAL NAME 3611 Outputs: 3613 o major_status INTEGER, 3615 o minor_status INTEGER, 3617 o dest_name INTERNAL NAME -- caller must release 3618 -- with GSS_Release_name() 3620 Return major_status codes: 3622 o GSS_S_COMPLETE indicates that dest_name references an internal 3623 name object containing the same name as passed to src_name. 3625 o GSS_S_BAD_NAME indicates that the input name was invalid. 3627 o GSS_S_FAILURE indicates that the requested operation could not 3628 be performed for reasons unspecified at the GSS-API level. 3630 This routine takes input internal name src_name, and returns another 3631 reference (dest_name) to that name which can be used even if src_name 3632 is later freed. (Note: This may be implemented by copying or through 3633 use of reference counts.) 3635 3: Data Structure Definitions for GSS-V2 Usage 3637 Subsections of this section define, for interoperability and 3638 portability purposes, certain data structures for use with GSS-V2. 3640 3.1: Mechanism-Independent Token Format 3642 This section specifies a mechanism-independent level of encapsulating 3643 representation for the initial token of a GSS-API context 3644 establishment sequence, incorporating an identifier of the mechanism 3645 type to be used on that context and enabling tokens to be interpreted 3646 unambiguously at GSS-API peers. Use of this format is required for 3647 initial context establishment tokens of Internet standards-track 3648 GSS-API mechanisms; use in non-initial tokens is optional. 3650 The encoding format for the token tag is derived from ASN.1 and DER 3651 (per illustrative ASN.1 syntax included later within this 3652 subsection), but its concrete representation is defined directly in 3653 terms of octets rather than at the ASN.1 level in order to facilitate 3654 interoperable implementation without use of general ASN.1 processing 3655 code. The token tag consists of the following elements, in order: 3657 1. 0x60 -- Tag for [APPLICATION 0] SEQUENCE; indicates that 3658 -- constructed form, definite length encoding follows. 3660 2. Token length octets, specifying length of subsequent data 3661 (i.e., the summed lengths of elements 3-5 in this list, and of 3662 the mechanism-defined token object following the tag). 3663 This element comprises a variable number of octets: 3665 2a. If the indicated value is less than 128, it shall be 3666 represented in a single octet with bit 8 (high order) 3667 set to "0" and the remaining bits representing the value. 3669 2b. If the indicated value is 128 or more, it shall be 3670 represented in two or more octets, with bit 8 of the first 3671 octet set to "1" and the remaining bits of the first octet 3672 specifying the number of additional octets. The subsequent 3673 octets carry the value, 8 bits per octet, most significant 3674 digit first. The minimum number of octets shall be used to 3675 encode the length (i.e., no octets representing leading zeros 3676 shall be included within the length encoding). 3678 3. 0x06 -- Tag for OBJECT IDENTIFIER 3680 4. Object identifier length -- length (number of octets) of 3681 -- the encoded object identifier contained in element 5, 3682 -- encoded per rules as described in 2a. and 2b. above. 3684 5. Object identifier octets -- variable number of octets, 3685 -- encoded per ASN.1 BER rules: 3687 5a. The first octet contains the sum of two values: (1) the 3688 top-level object identifier component, multiplied by 40 3689 (decimal), and (2) the second-level object identifier 3690 component. This special case is the only point within an 3691 object identifier encoding where a single octet represents 3692 contents of more than one component. 3694 5b. Subsequent octets, if required, encode successively-lower 3695 components in the represented object identifier. A component's 3696 encoding may span multiple octets, encoding 7 bits per octet 3697 (most significant bits first) and with bit 8 set to "1" on 3698 all but the final octet in the component's encoding. The 3699 minimum number of octets shall be used to encode each component 3700 (i.e., no octets representing leading zeros shall be included 3701 within a component's encoding). 3703 (Note: In many implementations, elements 3-5 may be stored and 3704 referenced as a contiguous string constant.) 3706 The token tag is immediately followed by a mechanism-defined token 3707 object. Note that no independent size specifier intervenes following 3708 the object identifier value to indicate the size of the mechanism- 3709 defined token object. While ASN.1 usage within mechanism-defined 3710 tokens is permitted, there is no requirement that the mechanism- 3711 specific innerContextToken, innerMsgToken, and sealedUserData data 3712 elements must employ ASN.1 BER/DER encoding conventions. 3714 The following ASN.1 syntax is included for descriptive purposes only, 3715 to illustrate structural relationships among token and tag objects. 3716 For interoperability purposes, token and tag encoding shall be 3717 performed using the concrete encoding procedures described earlier in 3718 this subsection. 3720 GSS-API DEFINITIONS ::= 3722 BEGIN 3724 MechType ::= OBJECT IDENTIFIER 3725 -- data structure definitions 3727 -- callers must be able to distinguish among 3728 -- InitialContextToken, SubsequentContextToken, 3729 -- PerMsgToken, and SealedMessage data elements 3730 -- based on the usage in which they occur 3732 InitialContextToken ::= 3733 -- option indication (delegation, etc.) indicated within 3734 -- mechanism-specific token 3735 [APPLICATION 0] IMPLICIT SEQUENCE { 3736 thisMech MechType, 3737 innerContextToken ANY DEFINED BY thisMech 3738 -- contents mechanism-specific 3739 -- ASN.1 structure not required 3740 } 3742 SubsequentContextToken ::= innerContextToken ANY 3743 -- interpretation based on predecessor InitialContextToken 3744 -- ASN.1 structure not required 3746 PerMsgToken ::= 3747 -- as emitted by GSS_GetMIC and processed by GSS_VerifyMIC 3748 -- ASN.1 structure not required 3749 innerMsgToken ANY 3751 SealedMessage ::= 3752 -- as emitted by GSS_Wrap and processed by GSS_Unwrap 3753 -- includes internal, mechanism-defined indicator 3754 -- of whether or not encrypted 3755 -- ASN.1 structure not required 3756 sealedUserData ANY 3758 END 3760 3.2: Mechanism-Independent Exported Name Object Format 3762 This section specifies a mechanism-independent level of encapsulating 3763 representation for names exported via the GSS_Export_name() call, 3764 including an object identifier representing the exporting mechanism. 3765 The format of names encapsulated via this representation shall be 3766 defined within individual mechanism drafts. The Object Identifier 3767 value to indicate names of this type is defined in Section 4.7 of 3768 this document. 3770 No name type OID is included in this mechanism-independent level of 3771 format definition, since (depending on individual mechanism 3772 specifications) the enclosed name may be implicitly typed or may be 3773 explicitly typed using a means other than OID encoding. 3775 The bytes within MECH_OID_LEN and NAME_LEN elements are represented 3776 most significant byte first (equivalently, in IP network byte order). 3778 Length Name Description 3780 2 TOK_ID Token Identifier 3781 For exported name objects, this 3782 must be hex 04 01. 3783 2 MECH_OID_LEN Length of the Mechanism OID 3784 MECH_OID_LEN MECH_OID Mechanism OID, in DER 3785 4 NAME_LEN Length of name 3786 NAME_LEN NAME Exported name; format defined in 3787 applicable mechanism draft. 3789 A concrete example of the contents of an exported name object, 3790 derived from the Kerberos Version 5 mechanism, is as follows: 3792 04 01 00 0B 06 09 2A 86 48 86 F7 12 01 02 02 hx xx xx xl pp qq ... zz 3794 04 01 mandatory token identifier 3796 00 0B 2-byte length of the immediately following DER-encoded 3797 ASN.1 value of type OID, most significant octet first 3799 06 09 2A 86 48 86 F7 12 01 02 02 DER-encoded ASN.1 value 3800 of type OID; Kerberos V5 3801 mechanism OID indicates 3802 Kerberos V5 exported name 3804 in Detail: 06 Identifier octet (6=OID) 3805 09 Length octet(s) 3806 2A 86 48 86 F7 12 01 02 02 Content octet(s) 3808 hx xx xx xl 4-byte length of the immediately following exported 3809 name blob, most significant octet first 3811 pp qq ... zz exported name blob of specified length, 3812 bits and bytes specified in the 3813 (Kerberos 5) GSS-API v2 mechanism spec 3815 4: Name Type Definitions 3817 This section includes definitions for name types and associated 3818 syntaxes which are defined in a mechanism-independent fashion at the 3819 GSS-API level rather than being defined in individual mechanism 3820 specifications. 3822 4.1: Host-Based Service Name Form 3824 This name form shall be represented by the Object Identifier: 3826 {iso(1) member-body(2) United States(840) mit(113554) infosys(1) 3827 "gssapi(2) generic(1) service_name(4)}. 3829 The recommended symbolic name for this type is 3830 "GSS_C_NT_HOSTBASED_SERVICE". 3832 For reasons of compatibility with existing implementations, it is 3833 recommended that this OID be used rather than the alternate value as 3834 included in [RFC-2078]: 3836 {1(iso), 3(org), 6(dod), 1(internet), 5(security), 6(nametypes), 3837 2(gss-host-based-services)} 3839 While it is not recommended that this alternate value be emitted on 3840 output by GSS implementations, it is recommended that it be accepted 3841 on input as equivalent to the recommended value. 3843 This name type is used to represent services associated with host 3844 computers. Support for this name form is recommended to mechanism 3845 designers in the interests of portability, but is not mandated by 3846 this specification. This name form is constructed using two elements, 3847 "service" and "hostname", as follows: 3849 service@hostname 3851 When a reference to a name of this type is resolved, the "hostname" 3852 may (as an example implementation strategy) be canonicalized by 3853 attempting a DNS lookup and using the fully-qualified domain name 3854 which is returned, or by using the "hostname" as provided if the DNS 3855 lookup fails. The canonicalization operation also maps the host's 3856 name into lower-case characters. 3858 The "hostname" element may be omitted. If no "@" separator is 3859 included, the entire name is interpreted as the service specifier, 3860 with the "hostname" defaulted to the canonicalized name of the local 3861 host. 3863 Values for the "service" element are registered with the IANA. 3865 4.2: User Name Form 3867 This name form shall be represented by the Object Identifier {iso(1) 3868 member-body(2) United States(840) mit(113554) infosys(1) gssapi(2) 3869 generic(1) user_name(1)}. The recommended mechanism-independent 3870 symbolic name for this type is "GSS_C_NT_USER_NAME". (Note: the same 3871 name form and OID is defined within the Kerberos V5 GSS-API 3872 mechanism, but the symbolic name recommended there begins with a 3873 "GSS_KRB5_NT_" prefix.) 3875 This name type is used to indicate a named user on a local system. 3876 Its syntax and interpretation may be OS-specific. This name form is 3877 constructed as: 3879 username 3881 4.3: Machine UID Form 3883 This name form shall be represented by the Object Identifier {iso(1) 3884 member-body(2) United States(840) mit(113554) infosys(1) gssapi(2) 3885 generic(1) machine_uid_name(2)}. The recommended mechanism- 3886 independent symbolic name for this type is 3887 "GSS_C_NT_MACHINE_UID_NAME". (Note: the same name form and OID is 3888 defined within the Kerberos V5 GSS-API mechanism, but the symbolic 3889 name recommended there begins with a "GSS_KRB5_NT_" prefix.) 3891 This name type is used to indicate a numeric user identifier 3892 corresponding to a user on a local system. Its interpretation is 3893 OS-specific. The gss_buffer_desc representing a name of this type 3894 should contain a locally-significant user ID, represented in host 3895 byte order. The GSS_Import_name() operation resolves this uid into a 3896 username, which is then treated as the User Name Form. 3898 4.4: String UID Form 3899 This name form shall be represented by the Object Identifier {iso(1) 3900 member-body(2) United States(840) mit(113554) infosys(1) gssapi(2) 3901 generic(1) string_uid_name(3)}. The recommended symbolic name for 3902 this type is "GSS_C_NT_STRING_UID_NAME". (Note: the same name form 3903 and OID is defined within the Kerberos V5 GSS-API mechanism, but the 3904 symbolic name recommended there begins with a "GSS_KRB5_NT_" prefix.) 3906 This name type is used to indicate a string of digits representing 3907 the numeric user identifier of a user on a local system. Its 3908 interpretation is OS-specific. This name type is similar to the 3909 Machine UID Form, except that the buffer contains a string 3910 representing the user ID. 3912 4.5: Anonymous Nametype 3914 The following Object Identifier value is provided as a means to 3915 identify anonymous names, and can be compared against in order to 3916 determine, in a mechanism-independent fashion, whether a name refers 3917 to an anonymous principal: 3919 {1(iso), 3(org), 6(dod), 1(internet), 5(security), 6(nametypes), 3920 3(gss-anonymous-name)} 3922 The recommended symbolic name corresponding to this definition is 3923 GSS_C_NT_ANONYMOUS. 3925 4.6: GSS_C_NO_OID 3927 The recommended symbolic name GSS_C_NO_OID corresponds to a null 3928 input value instead of an actual object identifier. Where specified, 3929 it indicates interpretation of an associated name based on a 3930 mechanism-specific default printable syntax. 3932 4.7: Exported Name Object 3934 Name objects of the Mechanism-Independent Exported Name Object type, 3935 as defined in Section 3.2 of this document, will be identified with 3936 the following Object Identifier: 3938 {1(iso), 3(org), 6(dod), 1(internet), 5(security), 6(nametypes), 3939 4(gss-api-exported-name)} 3941 The recommended symbolic name corresponding to this definition is 3942 GSS_C_NT_EXPORT_NAME. 3944 4.8: GSS_C_NO_NAME 3946 The recommended symbolic name GSS_C_NO_NAME indicates that no name is 3947 being passed within a particular value of a parameter used for the 3948 purpose of transferring names. 3950 5: Mechanism-Specific Example Scenarios 3952 This section provides illustrative overviews of the use of various 3953 candidate mechanism types to support the GSS-API. These discussions 3954 are intended primarily for readers familiar with specific security 3955 technologies, demonstrating how GSS-API functions can be used and 3956 implemented by candidate underlying mechanisms. They should not be 3957 regarded as constrictive to implementations or as defining the only 3958 means through which GSS-API functions can be realized with a 3959 particular underlying technology, and do not demonstrate all GSS-API 3960 features with each technology. 3962 5.1: Kerberos V5, single-TGT 3964 OS-specific login functions yield a TGT to the local realm Kerberos 3965 server; TGT is placed in a credentials structure for the client. 3966 Client calls GSS_Acquire_cred() to acquire a cred_handle in order to 3967 reference the credentials for use in establishing security contexts. 3969 Client calls GSS_Init_sec_context(). If the requested service is 3970 located in a different realm, GSS_Init_sec_context() gets the 3971 necessary TGT/key pairs needed to traverse the path from local to 3972 target realm; these data are placed in the owner's TGT cache. After 3973 any needed remote realm resolution, GSS_Init_sec_context() yields a 3974 service ticket to the requested service with a corresponding session 3975 key; these data are stored in conjunction with the context. GSS-API 3976 code sends KRB_TGS_REQ request(s) and receives KRB_TGS_REP 3977 response(s) (in the successful case) or KRB_ERROR. 3979 Assuming success, GSS_Init_sec_context() builds a Kerberos-formatted 3980 KRB_AP_REQ message, and returns it in output_token. The client sends 3981 the output_token to the service. 3983 The service passes the received token as the input_token argument to 3984 GSS_Accept_sec_context(), which verifies the authenticator, provides 3985 the service with the client's authenticated name, and returns an 3986 output_context_handle. 3988 Both parties now hold the session key associated with the service 3989 ticket, and can use this key in subsequent GSS_GetMIC(), 3990 GSS_VerifyMIC(), GSS_Wrap(), and GSS_Unwrap() operations. 3992 5.2: Kerberos V5, double-TGT 3994 TGT acquisition as above. 3996 Note: To avoid unnecessary frequent invocations of error paths when 3997 implementing the GSS-API atop Kerberos V5, it seems appropriate to 3998 represent "single-TGT K-V5" and "double-TGT K-V5" with separate 3999 mech_types, and this discussion makes that assumption. 4001 Based on the (specified or defaulted) mech_type, 4002 GSS_Init_sec_context() determines that the double-TGT protocol 4003 should be employed for the specified target. GSS_Init_sec_context() 4004 returns GSS_S_CONTINUE_NEEDED major_status, and its returned 4005 output_token contains a request to the service for the service's TGT. 4006 (If a service TGT with suitably long remaining lifetime already 4007 exists in a cache, it may be usable, obviating the need for this 4008 step.) The client passes the output_token to the service. Note: this 4009 scenario illustrates a different use for the GSS_S_CONTINUE_NEEDED 4010 status return facility than for support of mutual authentication; 4011 note that both uses can coexist as successive operations within a 4012 single context establishment operation. 4014 The service passes the received token as the input_token argument to 4015 GSS_Accept_sec_context(), which recognizes it as a request for TGT. 4016 (Note that current Kerberos V5 defines no intra-protocol mechanism to 4017 represent such a request.) GSS_Accept_sec_context() returns 4018 GSS_S_CONTINUE_NEEDED major_status and provides the service's TGT in 4019 its output_token. The service sends the output_token to the client. 4021 The client passes the received token as the input_token argument to a 4022 continuation of GSS_Init_sec_context(). GSS_Init_sec_context() caches 4023 the received service TGT and uses it as part of a service ticket 4024 request to the Kerberos authentication server, storing the returned 4025 service ticket and session key in conjunction with the context. 4026 GSS_Init_sec_context() builds a Kerberos-formatted authenticator, and 4027 returns it in output_token along with GSS_S_COMPLETE return 4028 major_status. The client sends the output_token to the service. 4030 Service passes the received token as the input_token argument to a 4031 continuation call to GSS_Accept_sec_context(). 4032 GSS_Accept_sec_context() verifies the authenticator, provides the 4033 service with the client's authenticated name, and returns 4034 major_status GSS_S_COMPLETE. 4036 GSS_GetMIC(), GSS_VerifyMIC(), GSS_Wrap(), and GSS_Unwrap() as 4037 above. 4039 5.3: X.509 Authentication Framework 4041 This example illustrates use of the GSS-API in conjunction with 4042 public-key mechanisms, consistent with the X.509 Directory 4043 Authentication Framework. 4045 The GSS_Acquire_cred() call establishes a credentials structure, 4046 making the client's private key accessible for use on behalf of the 4047 client. 4049 The client calls GSS_Init_sec_context(), which interrogates the 4050 Directory to acquire (and validate) a chain of public-key 4051 certificates, thereby collecting the public key of the service. The 4052 certificate validation operation determines that suitable integrity 4053 checks were applied by trusted authorities and that those 4054 certificates have not expired. GSS_Init_sec_context() generates a 4055 secret key for use in per-message protection operations on the 4056 context, and enciphers that secret key under the service's public 4057 key. 4059 The enciphered secret key, along with an authenticator quantity 4060 signed with the client's private key, is included in the output_token 4061 from GSS_Init_sec_context(). The output_token also carries a 4062 certification path, consisting of a certificate chain leading from 4063 the service to the client; a variant approach would defer this path 4064 resolution to be performed by the service instead of being asserted 4065 by the client. The client application sends the output_token to the 4066 service. 4068 The service passes the received token as the input_token argument to 4069 GSS_Accept_sec_context(). GSS_Accept_sec_context() validates the 4070 certification path, and as a result determines a certified binding 4071 between the client's distinguished name and the client's public key. 4072 Given that public key, GSS_Accept_sec_context() can process the 4073 input_token's authenticator quantity and verify that the client's 4074 private key was used to sign the input_token. At this point, the 4075 client is authenticated to the service. The service uses its private 4076 key to decipher the enciphered secret key provided to it for per- 4077 message protection operations on the context. 4079 The client calls GSS_GetMIC() or GSS_Wrap() on a data message, which 4080 causes per-message authentication, integrity, and (optional) 4081 confidentiality facilities to be applied to that message. The service 4082 uses the context's shared secret key to perform corresponding 4083 GSS_VerifyMIC() and GSS_Unwrap() calls. 4085 6: Security Considerations 4087 Security issues are discussed throughout this memo. 4089 7: Related Activities 4091 In order to implement the GSS-API atop existing, emerging, and future 4092 security mechanisms: 4094 object identifiers must be assigned to candidate GSS-API 4095 mechanisms and the name types which they support 4097 concrete data element formats and processing procedures must be 4098 defined for candidate mechanisms 4100 Calling applications must implement formatting conventions which will 4101 enable them to distinguish GSS-API tokens from other data carried in 4102 their application protocols. 4104 Concrete language bindings are required for the programming 4105 environments in which the GSS-API is to be employed, as [RFC-1509] 4106 defines for the C programming language and GSS-V1. 4108 8: Referenced Documents 4110 [ISO-7498-2] International Standard ISO 7498-2-1988(E), Security 4111 Architecture. 4113 [ISOIEC-8824] ISO/IEC 8824, "Specification of Abstract Syntax 4114 Notation One (ASN.1)". 4116 [ISOIEC-8825] ISO/IEC 8825, "Specification of Basic Encoding Rules 4117 for Abstract Syntax Notation One (ASN.1)".) 4119 [RFC-1507]: C. Kaufman, "DASS: Distributed Authentication Security 4120 Service", RFC 1507. 4122 [RFC-1508]: J. Linn, "Generic Security Service Application Program 4123 Interface", RFC 1508. 4125 [RFC-1509]: J. Wray, "Generic Security Service API: C-bindings", RFC 4126 1509. 4128 [RFC-1964]: J. Linn, "The Kerberos Version 5 GSS-API Mechanism", RFC 4129 1964. 4131 [RFC-2025]: C. Adams, "The Simple Public-Key GSS-API Mechanism 4132 (SPKM)", RFC 2025. 4134 [RFC-2078]: J. Linn, "Generic Security Service Application Program 4135 Interface, Version 2", RFC 2078. 4137 [RFC-2203]: M. Eisler, A. Chiu, L. Ling, "RPCSEC_GSS Protocol 4138 Specification", RFC 2203. 4140 APPENDIX A 4142 MECHANISM DESIGN CONSTRAINTS 4144 The following constraints on GSS-API mechanism designs are adopted in 4145 response to observed caller protocol requirements, and adherence thereto 4146 is anticipated in subsequent descriptions of GSS-API mechanisms to be 4147 documented in standards-track Internet specifications. 4149 It is strongly recommended that mechanisms offering per-message 4150 protection services also offer at least one of the replay detection and 4151 sequencing services, as mechanisms offering neither of the latter will 4152 fail to satisfy recognized requirements of certain candidate caller 4153 protocols. 4155 APPENDIX B 4157 COMPATIBILITY WITH GSS-V1 4159 It is the intent of this document to define an interface and procedures 4160 which preserve compatibility between GSS-V1 [RFC-1508] callers and GSS- 4161 V2 providers. All calls defined in GSS-V1 are preserved, and it has 4162 been a goal that GSS-V1 callers should be able to operate atop GSS-V2 4163 provider implementations. Certain detailed changes, summarized in this 4164 section, have been made in order to resolve omissions identified in 4165 GSS-V1. 4167 The following GSS-V1 constructs, while supported within GSS-V2, are 4168 deprecated: 4170 Names for per-message processing routines: GSS_Seal() deprecated in 4171 favor of GSS_Wrap(); GSS_Sign() deprecated in favor of 4172 GSS_GetMIC(); GSS_Unseal() deprecated in favor of GSS_Unwrap(); 4173 GSS_Verify() deprecated in favor of GSS_VerifyMIC(). 4175 GSS_Delete_sec_context() facility for context_token usage, allowing 4176 mechanisms to signal context deletion, is retained for 4177 compatibility with GSS-V1. For current usage, it is recommended 4178 that both peers to a context invoke GSS_Delete_sec_context() 4179 independently, passing a null output_context_token buffer to 4180 indicate that no context_token is required. Implementations of 4181 GSS_Delete_sec_context() should delete relevant locally-stored 4182 context information. 4184 This GSS-V2 specification adds the following calls which are not present 4185 in GSS-V1: 4187 Credential management calls: GSS_Add_cred(), 4188 GSS_Inquire_cred_by_mech(). 4190 Context-level calls: GSS_Inquire_context(), GSS_Wrap_size_limit(), 4191 GSS_Export_sec_context(), GSS_Import_sec_context(). 4193 Per-message calls: No new calls. Existing calls have been renamed. 4195 Support calls: GSS_Create_empty_OID_set(), 4196 GSS_Add_OID_set_member(), GSS_Test_OID_set_member(), 4197 GSS_Inquire_names_for_mech(), GSS_Inquire_mechs_for_name(), 4198 GSS_Canonicalize_name(), GSS_Export_name(), GSS_Duplicate_name(). 4200 This GSS-V2 specification introduces three new facilities applicable to 4201 security contexts, indicated using the following context state values 4202 which are not present in GSS-V1: 4204 anon_state, set TRUE to indicate that a context's initiator is 4205 anonymous from the viewpoint of the target; Section 1.2.5 of this 4206 specification provides a summary description of the GSS-V2 4207 anonymity support facility, support and use of which is optional. 4209 prot_ready_state, set TRUE to indicate that a context may be used 4210 for per-message protection before final completion of context 4211 establishment; Section 1.2.7 of this specification provides a 4212 summary description of the GSS-V2 facility enabling mechanisms to 4213 selectively permit per-message protection during context 4214 establishment, support and use of which is optional. 4216 trans_state, set TRUE to indicate that a context is transferable to 4217 another process using the GSS-V2 GSS_Export_sec_context() facility. 4219 These state values are represented (at the C bindings level) in 4220 positions within a bit vector which are unused in GSS-V1, and may be 4221 safely ignored by GSS-V1 callers. 4223 Relative to GSS-V1, GSS-V2 provides additional guidance to GSS-API 4224 implementors in the following areas: implementation robustness, 4225 credential management, behavior in multi-mechanism configurations, 4226 naming support, and inclusion of optional sequencing services. The 4227 token tagging facility as defined in GSS-V2, Section 3.1, is now 4228 described directly in terms of octets to facilitate interoperable 4229 implementation without general ASN.1 processing code; the corresponding 4230 ASN.1 syntax, included for descriptive purposes, is unchanged from that 4231 in GSS-V1. For use in conjunction with added naming support facilities, 4232 a new Exported Name Object construct is added. Additional name types 4233 are introduced in Section 4. 4235 This GSS-V2 specification adds the following major_status values which 4236 are not defined in GSS-V1: 4238 GSS_S_BAD_QOP unsupported QOP value 4239 GSS_S_UNAUTHORIZED operation unauthorized 4240 GSS_S_UNAVAILABLE operation unavailable 4241 GSS_S_DUPLICATE_ELEMENT duplicate credential element 4242 requested 4243 GSS_S_NAME_NOT_MN name contains multi-mechanism 4244 elements 4245 GSS_S_GAP_TOKEN skipped predecessor token(s) 4246 detected 4248 Of these added status codes, only two values are defined to be 4249 returnable by calls existing in GSS-V1: GSS_S_BAD_QOP (returnable by 4250 GSS_GetMIC() and GSS_Wrap()), and GSS_S_GAP_TOKEN (returnable by 4251 GSS_VerifyMIC() and GSS_Unwrap()). 4253 Additionally, GSS-V2 descriptions of certain calls present in GSS-V1 4254 have been updated to allow return of additional major_status values from 4255 the set as defined in GSS-V1: GSS_Inquire_cred() has 4256 GSS_S_DEFECTIVE_CREDENTIAL and GSS_S_CREDENTIALS_EXPIRED defined as 4257 returnable, GSS_Init_sec_context() has GSS_S_OLD_TOKEN, 4258 GSS_S_DUPLICATE_TOKEN, and GSS_S_BAD_MECH defined as returnable, and 4259 GSS_Accept_sec_context() has GSS_S_BAD_MECH defined as returnable. 4261 AUTHOR'S ADDRESS 4263 John Linn 4264 RSA Laboratories East 4265 20 Crosby Drive 4266 Bedford, MA 01730 USA 4267 +1 781.687.7817 4269 E-mail: linn@rsa.com 4270 TABLE OF CONTENTS 4272 1: GSS-API Characteristics and Concepts 4273 1.1: GSS-API Constructs 4274 1.1.1: Credentials 4275 1.1.1.1: Credential Constructs and Concepts 4276 1.1.1.2: Credential Management 4277 1.1.1.3: Default Credential Resolution 4278 1.1.2: Tokens 4279 1.1.3: Security Contexts 4280 1.1.4: Mechanism Types 4281 1.1.5: Naming 4282 1.1.6: Channel Bindings 4283 1.2: GSS-API Features and Issues 4284 1.2.1: Status Reporting 4285 1.2.2: Per-Message Security Service Availability 4286 1.2.3: Per-Message Replay Detection and Sequencing 4287 1.2.4: Quality of Protection 4288 1.2.5: Anonymity Support 4289 1.2.6: Initialization 4290 1.2.7: Per-Message Protection During Context Establishment 4291 1.2.8: Implementation Robustness 4292 2: Interface Descriptions 4293 2.1: Credential management calls 4294 2.1.1: GSS_Acquire_cred call 4295 2.1.2: GSS_Release_cred call 4296 2.1.3: GSS_Inquire_cred call 4297 2.1.4: GSS_Add_cred call 4298 2.1.5: GSS_Inquire_cred_by_mech call 4299 2.2: Context-level calls 4300 2.2.1: GSS_Init_sec_context call 4301 2.2.2: GSS_Accept_sec_context call 4302 2.2.3: GSS_Delete_sec_context call 4303 2.2.4: GSS_Process_context_token call 4304 2.2.5: GSS_Context_time call 4305 2.2.6: GSS_Inquire_context call 4306 2.2.7: GSS_Wrap_size_limit call 4307 2.2.8: GSS_Export_sec_context call 4308 2.2.9: GSS_Import_sec_context call 4309 2.3: Per-message calls 4310 2.3.1: GSS_GetMIC call 4311 2.3.2: GSS_VerifyMIC call 4312 2.3.3: GSS_Wrap call 4313 2.3.4: GSS_Unwrap call 4314 2.4: Support calls 4315 2.4.1: GSS_Display_status call 4316 2.4.2: GSS_Indicate_mechs call 4317 2.4.3: GSS_Compare_name call 4318 2.4.4: GSS_Display_name call 4319 2.4.5: GSS_Import_name call 4320 2.4.6: GSS_Release_name call 4321 2.4.7: GSS_Release_buffer call 4322 2.4.8: GSS_Release_OID_set call 4323 2.4.9: GSS_Create_empty_OID_set call 4324 2.4.10: GSS_Add_OID_set_member call 4325 2.4.11: GSS_Test_OID_set_member call 4326 2.4.12: GSS_Inquire_names_for_mech call 4327 2.4.13: GSS_Inquire_mechs_for_name call 4328 2.4.14: GSS_Canonicalize_name call 4329 2.4.15: GSS_Export_name call 4330 2.4.16: GSS_Duplicate_name call 4331 3: Data Structure Definitions for GSS-V2 Usage 4332 3.1: Mechanism-Independent Token Format 4333 3.2: Mechanism-Independent Exported Name Object Format 4334 4: Name Type Definitions 4335 4.1: Host-Based Service Name Form 4336 4.2: User Name Form 4337 4.3: Machine UID Form 4338 4.4: String UID Form 4339 5: Mechanism-Specific Example Scenarios 4340 5.1: Kerberos V5, single-TGT 4341 5.2: Kerberos V5, double-TGT 4342 5.3: X.509 Authentication Framework 4343 6: Security Considerations 4344 7: Related Activities 4345 8: Referenced Documents 4346 Appendix A: Mechanism Design Constraints 4347 Appendix B: Compatibility with GSS-V1 4349 John Linn (linn@rsa.com) 4350 RSA Laboratories East, Bedford, MA, USA