idnits 2.17.1 draft-ietf-cat-rfc2078bis-08.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-26) 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 100 longer pages, the longest (page 2) being 60 lines == It seems as if not all pages are separated by form feeds - found 0 form feeds but 101 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 1266 has weird spacing: '...t_token pro...' == Line 1305 has weird spacing: '...or_mech indi...' == Line 1307 has weird spacing: '...or_name indi...' == Line 3894 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 (16 December 1998) is 9263 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 4255 looks like a reference -- Missing reference section? 'ISO-7498-2' on line 4231 looks like a reference -- Missing reference section? 'RFC-1964' on line 4249 looks like a reference -- Missing reference section? 'RFC-2025' on line 4252 looks like a reference -- Missing reference section? 'RFC-2203' on line 4258 looks like a reference -- Missing reference section? 'ISOIEC-8825' on line 4237 looks like a reference -- Missing reference section? 'ISOIEC-8824' on line 4234 looks like a reference -- Missing reference section? 'RFC-1507' on line 4240 looks like a reference -- Missing reference section? 'APPLICATION 0' on line 3818 looks like a reference -- Missing reference section? 'RFC-1509' on line 4246 looks like a reference -- Missing reference section? 'RFC-1508' on line 4281 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 16 December 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.'' 20 To view the entire list of current Internet-Drafts, please check the 21 "1id-abstracts.txt" listing contained in the Internet-Drafts Shadow 22 Directories on ftp.is.co.za (Africa), ftp.nordu.net (Northern 23 Europe), ftp.nis.garr.it (Southern Europe), munnari.oz.au (Pacific 24 Rim), ftp.ietf.org (US East Coast), or ftp.isi.edu (US West Coast). 26 Comments on this document should be sent to "cat-ietf@mit.edu", the 27 IETF Common Authentication Technology WG discussion list. 29 ABSTRACT 31 The Generic Security Service Application Program Interface (GSS-API), 32 Version 2, as defined in [RFC-2078], provides security services to 33 callers in a generic fashion, supportable with a range of underlying 34 mechanisms and technologies and hence allowing source-level 35 portability of applications to different environments. This 36 specification defines GSS-API services and primitives at a level 37 independent of underlying mechanism and programming language 38 environment, and is to be complemented by other, related 39 specifications: 41 documents defining specific parameter bindings for particular 42 language environments 44 documents defining token formats, protocols, and procedures to be 45 implemented in order to realize GSS-API services atop particular 46 security mechanisms 48 This Internet-Draft revises [RFC-2078], making specific, incremental 49 changes in response to implementation experience and liaison 50 requests. It is intended, therefore, that this draft or a successor 51 version thereto will become the basis for subsequent progression of 52 the GSS-API specification on the standards track. 54 1: GSS-API Characteristics and Concepts 56 GSS-API operates in the following paradigm. A typical GSS-API caller 57 is itself a communications protocol, calling on GSS-API in order to 58 protect its communications with authentication, integrity, and/or 59 confidentiality security services. A GSS-API caller accepts tokens 60 provided to it by its local GSS-API implementation and transfers the 61 tokens to a peer on a remote system; that peer passes the received 62 tokens to its local GSS-API implementation for processing. The 63 security services available through GSS-API in this fashion are 64 implementable (and have been implemented) over a range of underlying 65 mechanisms based on secret-key and public-key cryptographic 66 technologies. 68 The GSS-API separates the operations of initializing a security 69 context between peers, achieving peer entity authentication 70 (GSS_Init_sec_context() and GSS_Accept_sec_context() calls), from the 71 operations of providing per-message data origin authentication and 72 data integrity protection (GSS_GetMIC() and GSS_VerifyMIC() calls) 73 for messages subsequently transferred in conjunction with that 74 context. (The definition for the peer entity authentication service, 75 and other definitions used in this document, corresponds to that 76 provided in [ISO-7498-2].) When establishing a security context, the 77 GSS-API enables a context initiator to optionally permit its 78 credentials to be delegated, meaning that the context acceptor may 79 initiate further security contexts on behalf of the initiating 80 caller. Per-message GSS_Wrap() and GSS_Unwrap() calls provide the 81 data origin authentication and data integrity services which 82 GSS_GetMIC() and GSS_VerifyMIC() offer, and also support selection of 83 confidentiality services as a caller option. Additional calls provide 84 supportive functions to the GSS-API's users. 86 The following paragraphs provide an example illustrating the 87 dataflows involved in use of the GSS-API by a client and server in a 88 mechanism-independent fashion, establishing a security context and 89 transferring a protected message. The example assumes that credential 90 acquisition has already been completed. The example also assumes 91 that the underlying authentication technology is capable of 92 authenticating a client to a server using elements carried within a 93 single token, and of authenticating the server to the client (mutual 94 authentication) with a single returned token; this assumption holds 95 for some presently-documented CAT mechanisms but is not necessarily 96 true for other cryptographic technologies and associated protocols. 98 The client calls GSS_Init_sec_context() to establish a security 99 context to the server identified by targ_name, and elects to set the 100 mutual_req_flag so that mutual authentication is performed in the 101 course of context establishment. GSS_Init_sec_context() returns an 102 output_token to be passed to the server, and indicates 103 GSS_S_CONTINUE_NEEDED status pending completion of the mutual 104 authentication sequence. Had mutual_req_flag not been set, the 105 initial call to GSS_Init_sec_context() would have returned 106 GSS_S_COMPLETE status. The client sends the output_token to the 107 server. 109 The server passes the received token as the input_token parameter to 110 GSS_Accept_sec_context(). GSS_Accept_sec_context indicates 111 GSS_S_COMPLETE status, provides the client's authenticated identity 112 in the src_name result, and provides an output_token to be passed to 113 the client. The server sends the output_token to the client. 115 The client passes the received token as the input_token parameter to 116 a successor call to GSS_Init_sec_context(), which processes data 117 included in the token in order to achieve mutual authentication from 118 the client's viewpoint. This call to GSS_Init_sec_context() returns 119 GSS_S_COMPLETE status, indicating successful mutual authentication 120 and the completion of context establishment for this example. 122 The client generates a data message and passes it to GSS_Wrap(). 123 GSS_Wrap() performs data origin authentication, data integrity, and 124 (optionally) confidentiality processing on the message and 125 encapsulates the result into output_message, indicating 126 GSS_S_COMPLETE status. The client sends the output_message to the 127 server. 129 The server passes the received message to GSS_Unwrap(). GSS_Unwrap() 130 inverts the encapsulation performed by GSS_Wrap(), deciphers the 131 message if the optional confidentiality feature was applied, and 132 validates the data origin authentication and data integrity checking 133 quantities. GSS_Unwrap() indicates successful validation by returning 134 GSS_S_COMPLETE status along with the resultant output_message. 136 For purposes of this example, we assume that the server knows by 137 out-of-band means that this context will have no further use after 138 one protected message is transferred from client to server. Given 139 this premise, the server now calls GSS_Delete_sec_context() to flush 140 context-level information. Optionally, the server-side application 141 may provide a token buffer to GSS_Delete_sec_context(), to receive a 142 context_token to be transferred to the client in order to request 143 that client-side context-level information be deleted. 145 If a context_token is transferred, the client passes the 146 context_token to GSS_Process_context_token(), which returns 147 GSS_S_COMPLETE status after deleting context-level information at the 148 client system. 150 The GSS-API design assumes and addresses several basic goals, 151 including: 153 Mechanism independence: The GSS-API defines an interface to 154 cryptographically implemented strong authentication and other 155 security services at a generic level which is independent of 156 particular underlying mechanisms. For example, GSS-API-provided 157 services have been implemented using secret-key technologies 158 (e.g., Kerberos, per [RFC-1964]) and with public-key approaches 159 (e.g., SPKM, per [RFC-2025]). 161 Protocol environment independence: The GSS-API is independent of 162 the communications protocol suites with which it is employed, 163 permitting use in a broad range of protocol environments. In 164 appropriate environments, an intermediate implementation "veneer" 165 which is oriented to a particular communication protocol may be 166 interposed between applications which call that protocol and the 167 GSS-API (e.g., as defined in [RFC-2203] for Open Network Computing 168 Remote Procedure Call (RPC)), thereby invoking GSS-API facilities 169 in conjunction with that protocol's communications invocations. 171 Protocol association independence: The GSS-API's security context 172 construct is independent of communications protocol association 173 constructs. This characteristic allows a single GSS-API 174 implementation to be utilized by a variety of invoking protocol 175 modules on behalf of those modules' calling applications. GSS-API 176 services can also be invoked directly by applications, wholly 177 independent of protocol associations. 179 Suitability to a range of implementation placements: GSS-API 180 clients are not constrained to reside within any Trusted Computing 181 Base (TCB) perimeter defined on a system where the GSS-API is 182 implemented; security services are specified in a manner suitable 183 to both intra-TCB and extra-TCB callers. 185 1.1: GSS-API Constructs 187 This section describes the basic elements comprising the GSS-API. 189 1.1.1: Credentials 191 1.1.1.1: Credential Constructs and Concepts 193 Credentials provide the prerequisites which permit GSS-API peers to 194 establish security contexts with each other. A caller may designate 195 that the credential elements which are to be applied for context 196 initiation or acceptance be selected by default. Alternately, those 197 GSS-API callers which need to make explicit selection of particular 198 credentials structures may make references to those credentials 199 through GSS-API-provided credential handles ("cred_handles"). In all 200 cases, callers' credential references are indirect, mediated by GSS- 201 API implementations and not requiring callers to access the selected 202 credential elements. 204 A single credential structure may be used to initiate outbound 205 contexts and to accept inbound contexts. Callers needing to operate 206 in only one of these modes may designate this fact when credentials 207 are acquired for use, allowing underlying mechanisms to optimize 208 their processing and storage requirements. The credential elements 209 defined by a particular mechanism may contain multiple cryptographic 210 keys, e.g., to enable authentication and message encryption to be 211 performed with different algorithms. 213 A GSS-API credential structure may contain multiple credential 214 elements, each containing mechanism-specific information for a 215 particular underlying mechanism (mech_type), but the set of elements 216 within a given credential structure represent a common entity. A 217 credential structure's contents will vary depending on the set of 218 mech_types supported by a particular GSS-API implementation. Each 219 credential element identifies the data needed by its mechanism in 220 order to establish contexts on behalf of a particular principal, and 221 may contain separate credential references for use in context 222 initiation and context acceptance. Multiple credential elements 223 within a given credential having overlapping combinations of 224 mechanism, usage mode, and validity period are not permitted. 226 Commonly, a single mech_type will be used for all security contexts 227 established by a particular initiator to a particular target. A major 228 motivation for supporting credential sets representing multiple 229 mech_types is to allow initiators on systems which are equipped to 230 handle multiple types to initiate contexts to targets on other 231 systems which can accommodate only a subset of the set supported at 232 the initiator's system. 234 1.1.1.2: Credential Management 236 It is the responsibility of underlying system-specific mechanisms and 237 OS functions below the GSS-API to ensure that the ability to acquire 238 and use credentials associated with a given identity is constrained 239 to appropriate processes within a system. This responsibility should 240 be taken seriously by implementors, as the ability for an entity to 241 utilize a principal's credentials is equivalent to the entity's 242 ability to successfully assert that principal's identity. 244 Once a set of GSS-API credentials is established, the transferability 245 of that credentials set to other processes or analogous constructs 246 within a system is a local matter, not defined by the GSS-API. An 247 example local policy would be one in which any credentials received 248 as a result of login to a given user account, or of delegation of 249 rights to that account, are accessible by, or transferable to, 250 processes running under that account. 252 The credential establishment process (particularly when performed on 253 behalf of users rather than server processes) is likely to require 254 access to passwords or other quantities which should be protected 255 locally and exposed for the shortest time possible. As a result, it 256 will often be appropriate for preliminary credential establishment to 257 be performed through local means at user login time, with the 258 result(s) cached for subsequent reference. These preliminary 259 credentials would be set aside (in a system-specific fashion) for 260 subsequent use, either: 262 to be accessed by an invocation of the GSS-API GSS_Acquire_cred() 263 call, returning an explicit handle to reference that credential 265 to comprise default credential elements to be installed, and to be 266 used when default credential behavior is requested on behalf of a 267 process 269 1.1.1.3: Default Credential Resolution 271 The GSS_Init_sec_context() and GSS_Accept_sec_context() routines 272 allow the value GSS_C_NO_CREDENTIAL to be specified as their 273 credential handle parameter. This special credential-handle 274 indicates a desire by the application to act as a default principal. 275 In support of application portability, support for the default 276 resolution behavior described below for initiator credentials 277 (GSS_Init_sec_context() usage) is mandated; support for the default 278 resolution behavior described below for acceptor credentials 279 (GSS_Accept_sec_context() usage) is recommended. If default 280 credential resolution fails, GSS_S_NO_CRED status is to be returned. 282 GSS_Init_sec_context: 284 (i) If there is only a single principal capable of initiating 285 security contexts that the application is authorized to act on 286 behalf of, then that principal shall be used, otherwise 288 (ii) If the platform maintains a concept of a default network- 289 identity, and if the application is authorized to act on behalf 290 of that identity for the purpose of initiating security 291 contexts, then the principal corresponding to that identity 292 shall be used, otherwise 294 (iii) If the platform maintains a concept of a default local 295 identity, and provides a means to map local identities into 296 network-identities, and if the application is authorized to act 297 on behalf of the network-identity image of the default local 298 identity for the purpose of initiating security contexts, then 299 the principal corresponding to that identity shall be used, 300 otherwise 302 (iv) A user-configurable default identity should be used. 304 GSS_Accept_sec_context: 306 (i) If there is only a single authorized principal identity 307 capable of accepting security contexts, then that principal 308 shall be used, otherwise 310 (ii) If the mechanism can determine the identity of the target 311 principal by examining the context-establishment token, and if 312 the accepting application is authorized to act as that 313 principal for the purpose of accepting security contexts, then 314 that principal identity shall be used, otherwise 316 (iii) If the mechanism supports context acceptance by any 317 principal, and mutual authentication was not requested, any 318 principal that the application is authorized to accept security 319 contexts under may be used, otherwise 321 (iv) A user-configurable default identity shall be used. 323 The purpose of the above rules is to allow security contexts to be 324 established by both initiator and acceptor using the default behavior 325 wherever possible. Applications requesting default behavior are 326 likely to be more portable across mechanisms and platforms than those 327 that use GSS_Acquire_cred() to request a specific identity. 329 1.1.2: Tokens 331 Tokens are data elements transferred between GSS-API callers, and are 332 divided into two classes. Context-level tokens are exchanged in order 333 to establish and manage a security context between peers. Per-message 334 tokens relate to an established context and are exchanged to provide 335 protective security services (i.e., data origin authentication, 336 integrity, and optional confidentiality) for corresponding data 337 messages. 339 The first context-level token obtained from GSS_Init_sec_context() is 340 required to indicate at its very beginning a globally-interpretable 341 mechanism identifier, i.e., an Object Identifier (OID) of the 342 security mechanism. The remaining part of this token as well as the 343 whole content of all other tokens are specific to the particular 344 underlying mechanism used to support the GSS-API. Section 3.1 of this 345 document provides, for designers of GSS-API mechanisms, the 346 description of the header of the first context-level token which is 347 then followed by mechanism-specific information. 349 Tokens' contents are opaque from the viewpoint of GSS-API callers. 350 They are generated within the GSS-API implementation at an end 351 system, provided to a GSS-API caller to be transferred to the peer 352 GSS-API caller at a remote end system, and processed by the GSS-API 353 implementation at that remote end system. 355 Context-level tokens may be output by GSS-API calls (and should be 356 transferred to GSS-API peers) whether or not the calls' status 357 indicators indicate successful completion. Per-message tokens, in 358 contrast, are to be returned only upon successful completion of per- 359 message calls. Zero-length tokens are never returned by GSS routines 360 for transfer to a peer. Token transfer may take place in an in-band 361 manner, integrated into the same protocol stream used by the GSS-API 362 callers for other data transfers, or in an out-of-band manner across 363 a logically separate channel. 365 Different GSS-API tokens are used for different purposes (e.g., 366 context initiation, context acceptance, protected message data on an 367 established context), and it is the responsibility of a GSS-API 368 caller receiving tokens to distinguish their types, associate them 369 with corresponding security contexts, and pass them to appropriate 370 GSS-API processing routines. Depending on the caller protocol 371 environment, this distinction may be accomplished in several ways. 373 The following examples illustrate means through which tokens' types 374 may be distinguished: 376 - implicit tagging based on state information (e.g., all tokens on 377 a new association are considered to be context establishment 378 tokens until context establishment is completed, at which point 379 all tokens are considered to be wrapped data objects for that 380 context), 382 - explicit tagging at the caller protocol level, 384 - a hybrid of these approaches. 386 Commonly, the encapsulated data within a token includes internal 387 mechanism-specific tagging information, enabling mechanism-level 388 processing modules to distinguish tokens used within the mechanism 389 for different purposes. Such internal mechanism-level tagging is 390 recommended to mechanism designers, and enables mechanisms to 391 determine whether a caller has passed a particular token for 392 processing by an inappropriate GSS-API routine. 394 Development of GSS-API mechanisms based on a particular underlying 395 cryptographic technique and protocol (i.e., conformant to a specific 396 GSS-API mechanism definition) does not necessarily imply that GSS-API 397 callers using that GSS-API mechanism will be able to interoperate 398 with peers invoking the same technique and protocol outside the GSS- 399 API paradigm, or with peers implementing a different GSS-API 400 mechanism based on the same underlying technology. The format of 401 GSS-API tokens defined in conjunction with a particular mechanism, 402 and the techniques used to integrate those tokens into callers' 403 protocols, may not be interoperable with the tokens used by non-GSS- 404 API callers of the same underlying technique. 406 1.1.3: Security Contexts 408 Security contexts are established between peers, using credentials 409 established locally in conjunction with each peer or received by 410 peers via delegation. Multiple contexts may exist simultaneously 411 between a pair of peers, using the same or different sets of 412 credentials. Coexistence of multiple contexts using different 413 credentials allows graceful rollover when credentials expire. 414 Distinction among multiple contexts based on the same credentials 415 serves applications by distinguishing different message streams in a 416 security sense. 418 The GSS-API is independent of underlying protocols and addressing 419 structure, and depends on its callers to transport GSS-API-provided 420 data elements. As a result of these factors, it is a caller 421 responsibility to parse communicated messages, separating GSS-API- 422 related data elements from caller-provided data. The GSS-API is 423 independent of connection vs. connectionless orientation of the 424 underlying communications service. 426 No correlation between security context and communications protocol 427 association is dictated. (The optional channel binding facility, 428 discussed in Section 1.1.6 of this document, represents an 429 intentional exception to this rule, supporting additional protection 430 features within GSS-API supporting mechanisms.) This separation 431 allows the GSS-API to be used in a wide range of communications 432 environments, and also simplifies the calling sequences of the 433 individual calls. In many cases (depending on underlying security 434 protocol, associated mechanism, and availability of cached 435 information), the state information required for context setup can be 436 sent concurrently with initial signed user data, without interposing 437 additional message exchanges. Messages may be protected and 438 transferred in both directions on an established GSS-API security 439 context concurrently; protection of messages in one direction does 440 not interfere with protection of messages in the reverse direction. 442 GSS-API implementations are expected to retain inquirable context 443 data on a context until the context is released by a caller, even 444 after the context has expired, although underlying cryptographic data 445 elements may be deleted after expiration in order to limit their 446 exposure. 448 1.1.4: Mechanism Types 450 In order to successfully establish a security context with a target 451 peer, it is necessary to identify an appropriate underlying mechanism 452 type (mech_type) which both initiator and target peers support. The 453 definition of a mechanism embodies not only the use of a particular 454 cryptographic technology (or a hybrid or choice among alternative 455 cryptographic technologies), but also definition of the syntax and 456 semantics of data element exchanges which that mechanism will employ 457 in order to support security services. 459 It is recommended that callers initiating contexts specify the 460 "default" mech_type value, allowing system-specific functions within 461 or invoked by the GSS-API implementation to select the appropriate 462 mech_type, but callers may direct that a particular mech_type be 463 employed when necessary. 465 For GSS-API purposes, the phrase "negotiating mechanism" refers to a 466 mechanism which itself performs negotiation in order to select a 467 concrete mechanism which is shared between peers and is then used for 468 context establishment. Only those mechanisms which are defined in 469 their specifications as negotiating mechanisms are to yield selected 470 mechanisms with different identifier values than the value which is 471 input by a GSS-API caller, except for the case of a caller requesting 472 the "default" mech_type. 474 The means for identifying a shared mech_type to establish a security 475 context with a peer will vary in different environments and 476 circumstances; examples include (but are not limited to): 478 use of a fixed mech_type, defined by configuration, within an 479 environment 481 syntactic convention on a target-specific basis, through 482 examination of a target's name 483 lookup of a target's name in a naming service or other database in 484 order to identify mech_types supported by that target 486 explicit negotiation between GSS-API callers in advance of 487 security context setup 489 use of a negotiating mechanism 491 When transferred between GSS-API peers, mech_type specifiers (per 492 Section 3 of this document, represented as Object Identifiers (OIDs)) 493 serve to qualify the interpretation of associated tokens. (The 494 structure and encoding of Object Identifiers is defined in [ISOIEC- 495 8824] and [ISOIEC-8825].) Use of hierarchically structured OIDs 496 serves to preclude ambiguous interpretation of mech_type specifiers. 497 The OID representing the DASS ([RFC-1507]) MechType, for example, is 498 1.3.12.2.1011.7.5, and that of the Kerberos V5 mechanism ([RFC- 499 1964]), having been advanced to the level of Proposed Standard, is 500 1.2.840.113554.1.2.2. 502 1.1.5: Naming 504 The GSS-API avoids prescribing naming structures, treating the names 505 which are transferred across the interface in order to initiate and 506 accept security contexts as opaque objects. This approach supports 507 the GSS-API's goal of implementability atop a range of underlying 508 security mechanisms, recognizing the fact that different mechanisms 509 process and authenticate names which are presented in different 510 forms. Generalized services offering translation functions among 511 arbitrary sets of naming environments are outside the scope of the 512 GSS-API; availability and use of local conversion functions to 513 translate among the naming formats supported within a given end 514 system is anticipated. 516 Different classes of name representations are used in conjunction 517 with different GSS-API parameters: 519 - Internal form (denoted in this document by INTERNAL NAME), 520 opaque to callers and defined by individual GSS-API 521 implementations. GSS-API implementations supporting multiple 522 namespace types must maintain internal tags to disambiguate the 523 interpretation of particular names. A Mechanism Name (MN) is a 524 special case of INTERNAL NAME, guaranteed to contain elements 525 corresponding to one and only one mechanism; calls which are 526 guaranteed to emit MNs or which require MNs as input are so 527 identified within this specification. 529 - Contiguous string ("flat") form (denoted in this document by 530 OCTET STRING); accompanied by OID tags identifying the namespace 531 to which they correspond. Depending on tag value, flat names may 532 or may not be printable strings for direct acceptance from and 533 presentation to users. Tagging of flat names allows GSS-API 534 callers and underlying GSS-API mechanisms to disambiguate name 535 types and to determine whether an associated name's type is one 536 which they are capable of processing, avoiding aliasing problems 537 which could result from misinterpreting a name of one type as a 538 name of another type. 540 - The GSS-API Exported Name Object, a special case of flat name 541 designated by a reserved OID value, carries a canonicalized form 542 of a name suitable for binary comparisons. 544 In addition to providing means for names to be tagged with types, 545 this specification defines primitives to support a level of naming 546 environment independence for certain calling applications. To provide 547 basic services oriented towards the requirements of callers which 548 need not themselves interpret the internal syntax and semantics of 549 names, GSS-API calls for name comparison (GSS_Compare_name()), 550 human-readable display (GSS_Display_name()), input conversion 551 (GSS_Import_name()), internal name deallocation (GSS_Release_name()), 552 and internal name duplication (GSS_Duplicate_name()) functions are 553 defined. (It is anticipated that these proposed GSS-API calls will be 554 implemented in many end systems based on system-specific name 555 manipulation primitives already extant within those end systems; 556 inclusion within the GSS-API is intended to offer GSS-API callers a 557 portable means to perform specific operations, supportive of 558 authorization and audit requirements, on authenticated names.) 560 GSS_Import_name() implementations can, where appropriate, support 561 more than one printable syntax corresponding to a given namespace 562 (e.g., alternative printable representations for X.500 Distinguished 563 Names), allowing flexibility for their callers to select among 564 alternative representations. GSS_Display_name() implementations 565 output a printable syntax selected as appropriate to their 566 operational environments; this selection is a local matter. Callers 567 desiring portability across alternative printable syntaxes should 568 refrain from implementing comparisons based on printable name forms 569 and should instead use the GSS_Compare_name() call to determine 570 whether or not one internal-format name matches another. 572 When used in large access control lists, the overhead of invoking 573 GSS_Import_name() and GSS_Compare_name() on each name from the ACL 574 may be prohibitive. As an alternative way of supporting this case, 575 GSS-API defines a special form of the contiguous string name which 576 may be compared directly (e.g., with memcmp()). Contiguous names 577 suitable for comparison are generated by the GSS_Export_name() 578 routine, which requires an MN as input. Exported names may be re- 579 imported by the GSS_Import_name() routine, and the resulting internal 580 name will also be an MN. The symbolic constant GSS_C_NT_EXPORT_NAME 581 identifies the "export name" type. Structurally, an exported name 582 object consists of a header containing an OID identifying the 583 mechanism that authenticated the name, and a trailer containing the 584 name itself, where the syntax of the trailer is defined by the 585 individual mechanism specification. The precise format of an 586 exported name is defined in Section 3.2 of this specification. 588 Note that the results obtained by using GSS_Compare_name() will in 589 general be different from those obtained by invoking 590 GSS_Canonicalize_name() and GSS_Export_name(), and then comparing the 591 exported names. The first series of operations determines whether 592 two (unauthenticated) names identify the same principal; the second 593 whether a particular mechanism would authenticate them as the same 594 principal. These two operations will in general give the same 595 results only for MNs. 597 The following diagram illustrates the intended dataflow among name- 598 related GSS-API processing routines. 600 GSS-API library defaults 601 | 602 | 603 V text, for 604 text --------------> internal_name (IN) -----------> display only 605 import_name() / display_name() 606 / 607 / 608 / 609 accept_sec_context() / 610 | / 611 | / 612 | / canonicalize_name() 613 | / 614 | / 615 | / 616 | / 617 | / 618 | | 619 V V <--------------------- 620 single mechanism import_name() exported name: flat 621 internal_name (MN) binary "blob" usable 622 ----------------------> for access control 623 export_name() 625 1.1.6: Channel Bindings 627 The GSS-API accommodates the concept of caller-provided channel 628 binding ("chan_binding") information. Channel bindings are used to 629 strengthen the quality with which peer entity authentication is 630 provided during context establishment, by limiting the scope within 631 which an intercepted context establishment token can be reused by an 632 attacker. Specifically, they enable GSS-API callers to bind the 633 establishment of a security context to relevant characteristics 634 (e.g., addresses, transformed representations of encryption keys) of 635 the underlying communications channel, of protection mechanisms 636 applied to that communications channel, and to application-specific 637 data. 639 The caller initiating a security context must determine the 640 appropriate channel binding values to provide as input to the 641 GSS_Init_sec_context() call, and consistent values must be provided 642 to GSS_Accept_sec_context() by the context's target, in order for 643 both peers' GSS-API mechanisms to validate that received tokens 644 possess correct channel-related characteristics. Use or non-use of 645 the GSS-API channel binding facility is a caller option. GSS-API 646 mechanisms can operate in an environment where NULL channel bindings 647 are presented; mechanism implementors are encouraged, but not 648 required, to make use of caller-provided channel binding data within 649 their mechanisms. Callers should not assume that underlying 650 mechanisms provide confidentiality protection for channel binding 651 information. 653 When non-NULL channel bindings are provided by callers, certain 654 mechanisms can offer enhanced security value by interpreting the 655 bindings' content (rather than simply representing those bindings, or 656 integrity check values computed on them, within tokens) and will 657 therefore depend on presentation of specific data in a defined 658 format. To this end, agreements among mechanism implementors are 659 defining conventional interpretations for the contents of channel 660 binding arguments, including address specifiers (with content 661 dependent on communications protocol environment) for context 662 initiators and acceptors. (These conventions are being incorporated 663 in GSS-API mechanism specifications and into the GSS-API C language 664 bindings specification.) In order for GSS-API callers to be portable 665 across multiple mechanisms and achieve the full security 666 functionality which each mechanism can provide, it is strongly 667 recommended that GSS-API callers provide channel bindings consistent 668 with these conventions and those of the networking environment in 669 which they operate. 671 1.2: GSS-API Features and Issues 673 This section describes aspects of GSS-API operations, of the security 674 services which the GSS-API provides, and provides commentary on 675 design issues. 677 1.2.1: Status Reporting and Optional Service Support 679 1.2.1.1: Status Reporting 681 Each GSS-API call provides two status return values. Major_status 682 values provide a mechanism-independent indication of call status 683 (e.g., GSS_S_COMPLETE, GSS_S_FAILURE, GSS_S_CONTINUE_NEEDED), 684 sufficient to drive normal control flow within the caller in a 685 generic fashion. Table 1 summarizes the defined major_status return 686 codes in tabular fashion. 688 Sequencing-related informatory major_status codes 689 (GSS_S_DUPLICATE_TOKEN, GSS_S_OLD_TOKEN, GSS_S_UNSEQ_TOKEN, and 690 GSS_S_GAP_TOKEN) can be indicated in conjunction with either 691 GSS_S_COMPLETE or GSS_S_FAILURE status for GSS-API per-message calls. 692 For context establishment calls, these sequencing-related codes will 693 be indicated only in conjunction with GSS_S_FAILURE status (never in 694 conjunction with GSS_S_COMPLETE or GSS_S_CONTINUE_NEEDED), and, 695 therefore, always correspond to fatal failures if encountered during 696 the context establishment phase. 698 Table 1: GSS-API Major Status Codes 700 FATAL ERROR CODES 702 GSS_S_BAD_BINDINGS channel binding mismatch 703 GSS_S_BAD_MECH unsupported mechanism requested 704 GSS_S_BAD_NAME invalid name provided 705 GSS_S_BAD_NAMETYPE name of unsupported type provided 706 GSS_S_BAD_STATUS invalid input status selector 707 GSS_S_BAD_SIG token had invalid integrity check 708 GSS_S_BAD_MIC preferred alias for GSS_S_BAD_SIG 709 GSS_S_CONTEXT_EXPIRED specified security context expired 710 GSS_S_CREDENTIALS_EXPIRED expired credentials detected 711 GSS_S_DEFECTIVE_CREDENTIAL defective credential detected 712 GSS_S_DEFECTIVE_TOKEN defective token detected 713 GSS_S_FAILURE failure, unspecified at GSS-API 714 level 715 GSS_S_NO_CONTEXT no valid security context specified 716 GSS_S_NO_CRED no valid credentials provided 717 GSS_S_BAD_QOP unsupported QOP value 718 GSS_S_UNAUTHORIZED operation unauthorized 719 GSS_S_UNAVAILABLE operation unavailable 720 GSS_S_DUPLICATE_ELEMENT duplicate credential element requested 721 GSS_S_NAME_NOT_MN name contains multi-mechanism elements 723 INFORMATORY STATUS CODES 725 GSS_S_COMPLETE normal completion 726 GSS_S_CONTINUE_NEEDED continuation call to routine 727 required 728 GSS_S_DUPLICATE_TOKEN duplicate per-message token 729 detected 730 GSS_S_OLD_TOKEN timed-out per-message token 731 detected 732 GSS_S_UNSEQ_TOKEN reordered (early) per-message token 733 detected 734 GSS_S_GAP_TOKEN skipped predecessor token(s) 735 detected 737 Minor_status provides more detailed status information which may 738 include status codes specific to the underlying security mechanism. 739 Minor_status values are not specified in this document. 741 GSS_S_CONTINUE_NEEDED major_status returns, and optional message 742 outputs, are provided in GSS_Init_sec_context() and 743 GSS_Accept_sec_context() calls so that different mechanisms' 744 employment of different numbers of messages within their 745 authentication sequences need not be reflected in separate code paths 746 within calling applications. Instead, such cases are accommodated 747 with sequences of continuation calls to GSS_Init_sec_context() and 748 GSS_Accept_sec_context(). The same facility is used to encapsulate 749 mutual authentication within the GSS-API's context initiation calls. 751 For mech_types which require interactions with third-party servers in 752 order to establish a security context, GSS-API context establishment 753 calls may block pending completion of such third-party interactions. 754 On the other hand, no GSS-API calls pend on serialized interactions 755 with GSS-API peer entities. As a result, local GSS-API status 756 returns cannot reflect unpredictable or asynchronous exceptions 757 occurring at remote peers, and reflection of such status information 758 is a caller responsibility outside the GSS-API. 760 1.2.1.2: Optional Service Support 762 A context initiator may request various optional services at context 763 establishment time. Each of these services is requested by setting a 764 flag in the req_flags input parameter to GSS_Init_sec_context(). 766 The optional services currently defined are: 768 - Delegation - The (usually temporary) transfer of rights from 769 initiator to acceptor, enabling the acceptor to authenticate 770 itself as an agent of the initiator. 772 - Mutual Authentication - In addition to the initiator 773 authenticating its identity to the context acceptor, the context 774 acceptor should also authenticate itself to the initiator. 776 - Replay detection - In addition to providing message integrity 777 services, GSS_GetMIC() and GSS_Wrap() should include message 778 numbering information to enable GSS_VerifyMIC() and GSS_Unwrap() 779 to detect if a message has been duplicated. 781 - Out-of-sequence detection - In addition to providing message 782 integrity services, GSS_GetMIC() and GSS_Wrap() should include 783 message sequencing information to enable GSS_VerifyMIC() and 784 GSS_Unwrap() to detect if a message has been received out of 785 sequence. 787 - Anonymous authentication - The establishment of the security 788 context should not reveal the initiator's identity to the 789 context acceptor. 791 - Available per-message confidentiality - requests that per- 792 message confidentiality services be available on the context. 794 - Available per-message integrity - requests that per-message 795 integrity services be available on the context. 797 Any currently undefined bits within such flag arguments should be 798 ignored by GSS-API implementations when presented by an application, 799 and should be set to zero when returned to the application by the 800 GSS-API implementation. 802 Some mechanisms may not support all optional services, and some 803 mechanisms may only support some services in conjunction with others. 804 Both GSS_Init_sec_context() and GSS_Accept_sec_context() inform the 805 applications which services will be available from the context when 806 the establishment phase is complete, via the ret_flags output 807 parameter. In general, if the security mechanism is capable of 808 providing a requested service, it should do so, even if additional 809 services must be enabled in order to provide the requested service. 810 If the mechanism is incapable of providing a requested service, it 811 should proceed without the service, leaving the application to abort 812 the context establishment process if it considers the requested 813 service to be mandatory. 815 Some mechanisms may specify that support for some services is 816 optional, and that implementors of the mechanism need not provide it. 817 This is most commonly true of the confidentiality service, often 818 because of legal restrictions on the use of data-encryption, but may 819 apply to any of the services. Such mechanisms are required to send 820 at least one token from acceptor to initiator during context 821 establishment when the initiator indicates a desire to use such a 822 service, so that the initiating GSS-API can correctly indicate 823 whether the service is supported by the acceptor's GSS-API. 825 1.2.2: Per-Message Security Service Availability 827 When a context is established, two flags are returned to indicate the 828 set of per-message protection security services which will be 829 available on the context: 831 the integ_avail flag indicates whether per-message integrity and 832 data origin authentication services are available 834 the conf_avail flag indicates whether per-message confidentiality 835 services are available, and will never be returned TRUE unless the 836 integ_avail flag is also returned TRUE 837 GSS-API callers desiring per-message security services should 838 check the values of these flags at context establishment time, and 839 must be aware that a returned FALSE value for integ_avail means 840 that invocation of GSS_GetMIC() or GSS_Wrap() primitives on the 841 associated context will apply no cryptographic protection to user 842 data messages. 844 The GSS-API per-message integrity and data origin authentication 845 services provide assurance to a receiving caller that protection was 846 applied to a message by the caller's peer on the security context, 847 corresponding to the entity named at context initiation. The GSS-API 848 per-message confidentiality service provides assurance to a sending 849 caller that the message's content is protected from access by 850 entities other than the context's named peer. 852 The GSS-API per-message protection service primitives, as the 853 category name implies, are oriented to operation at the granularity 854 of protocol data units. They perform cryptographic operations on the 855 data units, transfer cryptographic control information in tokens, 856 and, in the case of GSS_Wrap(), encapsulate the protected data unit. 857 As such, these primitives are not oriented to efficient data 858 protection for stream-paradigm protocols (e.g., Telnet) if 859 cryptography must be applied on an octet-by-octet basis. 861 1.2.3: Per-Message Replay Detection and Sequencing 863 Certain underlying mech_types offer support for replay detection 864 and/or sequencing of messages transferred on the contexts they 865 support. These optionally-selectable protection features are distinct 866 from replay detection and sequencing features applied to the context 867 establishment operation itself; the presence or absence of context- 868 level replay or sequencing features is wholly a function of the 869 underlying mech_type's capabilities, and is not selected or omitted 870 as a caller option. 872 The caller initiating a context provides flags (replay_det_req_flag 873 and sequence_req_flag) to specify whether the use of per-message 874 replay detection and sequencing features is desired on the context 875 being established. The GSS-API implementation at the initiator system 876 can determine whether these features are supported (and whether they 877 are optionally selectable) as a function of the selected mechanism, 878 without need for bilateral negotiation with the target. When enabled, 879 these features provide recipients with indicators as a result of 880 GSS-API processing of incoming messages, identifying whether those 881 messages were detected as duplicates or out-of-sequence. Detection of 882 such events does not prevent a suspect message from being provided to 883 a recipient; the appropriate course of action on a suspect message is 884 a matter of caller policy. 886 The semantics of the replay detection and sequencing services applied 887 to received messages, as visible across the interface which the GSS- 888 API provides to its clients, are as follows: 890 When replay_det_state is TRUE, the possible major_status returns for 891 well-formed and correctly signed messages are as follows: 893 1. GSS_S_COMPLETE, without concurrent indication of 894 GSS_S_DUPLICATE_TOKEN or GSS_S_OLD_TOKEN, indicates that the 895 message was within the window (of time or sequence space) allowing 896 replay events to be detected, and that the message was not a 897 replay of a previously-processed message within that window. 899 2. GSS_S_DUPLICATE_TOKEN indicates that the cryptographic 900 checkvalue on the received message was correct, but that the 901 message was recognized as a duplicate of a previously-processed 902 message. In addition to identifying duplicated tokens originated 903 by a context's peer, this status may also be used to identify 904 reflected copies of locally-generated tokens; it is recommended 905 that mechanism designers include within their protocols facilities 906 to detect and report such tokens. 908 3. GSS_S_OLD_TOKEN indicates that the cryptographic checkvalue on 909 the received message was correct, but that the message is too old 910 to be checked for duplication. 912 When sequence_state is TRUE, the possible major_status returns for 913 well-formed and correctly signed messages are as follows: 915 1. GSS_S_COMPLETE, without concurrent indication of 916 GSS_S_DUPLICATE_TOKEN, GSS_S_OLD_TOKEN, GSS_S_UNSEQ_TOKEN, or 917 GSS_S_GAP_TOKEN, indicates that the message was within the window 918 (of time or sequence space) allowing replay events to be detected, 919 that the message was not a replay of a previously-processed 920 message within that window, and that no predecessor sequenced 921 messages are missing relative to the last received message (if 922 any) processed on the context with a correct cryptographic 923 checkvalue. 925 2. GSS_S_DUPLICATE_TOKEN indicates that the integrity check value 926 on the received message was correct, but that the message was 927 recognized as a duplicate of a previously-processed message. In 928 addition to identifying duplicated tokens originated by a 929 context's peer, this status may also be used to identify reflected 930 copies of locally-generated tokens; it is recommended that 931 mechanism designers include within their protocols facilities to 932 detect and report such tokens. 934 3. GSS_S_OLD_TOKEN indicates that the integrity check value on the 935 received message was correct, but that the token is too old to be 936 checked for duplication. 938 4. GSS_S_UNSEQ_TOKEN indicates that the cryptographic checkvalue 939 on the received message was correct, but that it is earlier in a 940 sequenced stream than a message already processed on the context. 941 [Note: Mechanisms can be architected to provide a stricter form of 942 sequencing service, delivering particular messages to recipients 943 only after all predecessor messages in an ordered stream have been 944 delivered. This type of support is incompatible with the GSS-API 945 paradigm in which recipients receive all messages, whether in 946 order or not, and provide them (one at a time, without intra-GSS- 947 API message buffering) to GSS-API routines for validation. GSS- 948 API facilities provide supportive functions, aiding clients to 949 achieve strict message stream integrity in an efficient manner in 950 conjunction with sequencing provisions in communications 951 protocols, but the GSS-API does not offer this level of message 952 stream integrity service by itself.] 954 5. GSS_S_GAP_TOKEN indicates that the cryptographic checkvalue on 955 the received message was correct, but that one or more predecessor 956 sequenced messages have not been successfully processed relative 957 to the last received message (if any) processed on the context 958 with a correct cryptographic checkvalue. 960 As the message stream integrity features (especially sequencing) may 961 interfere with certain applications' intended communications 962 paradigms, and since support for such features is likely to be 963 resource intensive, it is highly recommended that mech_types 964 supporting these features allow them to be activated selectively on 965 initiator request when a context is established. A context initiator 966 and target are provided with corresponding indicators 967 (replay_det_state and sequence_state), signifying whether these 968 features are active on a given context. 970 An example mech_type supporting per-message replay detection could 971 (when replay_det_state is TRUE) implement the feature as follows: The 972 underlying mechanism would insert timestamps in data elements output 973 by GSS_GetMIC() and GSS_Wrap(), and would maintain (within a time- 974 limited window) a cache (qualified by originator-recipient pair) 975 identifying received data elements processed by GSS_VerifyMIC() and 976 GSS_Unwrap(). When this feature is active, exception status returns 977 (GSS_S_DUPLICATE_TOKEN, GSS_S_OLD_TOKEN) will be provided when 978 GSS_VerifyMIC() or GSS_Unwrap() is presented with a message which is 979 either a detected duplicate of a prior message or which is too old to 980 validate against a cache of recently received messages. 982 1.2.4: Quality of Protection 984 Some mech_types provide their users with fine granularity control 985 over the means used to provide per-message protection, allowing 986 callers to trade off security processing overhead dynamically against 987 the protection requirements of particular messages. A per-message 988 quality-of-protection parameter (analogous to quality-of-service, or 989 QOS) selects among different QOP options supported by that mechanism. 990 On context establishment for a multi-QOP mech_type, context-level 991 data provides the prerequisite data for a range of protection 992 qualities. 994 It is expected that the majority of callers will not wish to exert 995 explicit mechanism-specific QOP control and will therefore request 996 selection of a default QOP. Definitions of, and choices among, non- 997 default QOP values are mechanism-specific, and no ordered sequences 998 of QOP values can be assumed equivalent across different mechanisms. 999 Meaningful use of non-default QOP values demands that callers be 1000 familiar with the QOP definitions of an underlying mechanism or 1001 mechanisms, and is therefore a non-portable construct. The 1002 GSS_S_BAD_QOP major_status value is defined in order to indicate that 1003 a provided QOP value is unsupported for a security context, most 1004 likely because that value is unrecognized by the underlying 1005 mechanism. 1007 In the interests of interoperability, mechanisms which allow optional 1008 support of particular QOP values shall satisfy one of the following 1009 conditions. Either: 1011 (i) All implementations of the mechanism are required to be 1012 capable of processing messages protected using any QOP value, 1013 regardless of whether they can apply protection corresponding to 1014 that QOP, or 1016 (ii) The set of mutually-supported receiver QOP values must be 1017 determined during context establishment, and messages may be 1018 protected by either peer using only QOP values from this 1019 mutually-supported set. 1021 NOTE: (i) is just a special-case of (ii), where implementations are 1022 required to support all QOP values on receipt. 1024 1.2.5: Anonymity Support 1026 In certain situations or environments, an application may wish to 1027 authenticate a peer and/or protect communications using GSS-API per- 1028 message services without revealing its own identity. For example, 1029 consider an application which provides read access to a research 1030 database, and which permits queries by arbitrary requestors. A 1031 client of such a service might wish to authenticate the service, to 1032 establish trust in the information received from it, but might not 1033 wish to disclose its identity to the service for privacy reasons. 1035 In ordinary GSS-API usage, a context initiator's identity is made 1036 available to the context acceptor as part of the context 1037 establishment process. To provide for anonymity support, a facility 1038 (input anon_req_flag to GSS_Init_sec_context()) is provided through 1039 which context initiators may request that their identity not be 1040 provided to the context acceptor. Mechanisms are not required to 1041 honor this request, but a caller will be informed (via returned 1042 anon_state indicator from GSS_Init_sec_context()) whether or not the 1043 request is honored. Note that authentication as the anonymous 1044 principal does not necessarily imply that credentials are not 1045 required in order to establish a context. 1047 Section 4.5 of this document defines the Object Identifier value used 1048 to identify an anonymous principal. 1050 Four possible combinations of anon_state and mutual_state are 1051 possible, with the following results: 1053 anon_state == FALSE, mutual_state == FALSE: initiator 1054 authenticated to target. 1056 anon_state == FALSE, mutual_state == TRUE: initiator authenticated 1057 to target, target authenticated to initiator. 1059 anon_state == TRUE, mutual_state == FALSE: initiator authenticated 1060 as anonymous principal to target. 1062 anon_state == TRUE, mutual_state == TRUE: initiator authenticated 1063 as anonymous principal to target, target authenticated to 1064 initiator. 1066 1.2.6: Initialization 1068 No initialization calls (i.e., calls which must be invoked prior to 1069 invocation of other facilities in the interface) are defined in GSS- 1070 API. As an implication of this fact, GSS-API implementations must 1071 themselves be self-initializing. 1073 1.2.7: Per-Message Protection During Context Establishment 1075 A facility is defined in GSS-V2 to enable protection and buffering of 1076 data messages for later transfer while a security context's 1077 establishment is in GSS_S_CONTINUE_NEEDED status, to be used in cases 1078 where the caller side already possesses the necessary session key to 1079 enable this processing. Specifically, a new state Boolean, called 1080 prot_ready_state, is added to the set of information returned by 1081 GSS_Init_sec_context(), GSS_Accept_sec_context(), and 1082 GSS_Inquire_context(). 1084 For context establishment calls, this state Boolean is valid and 1085 interpretable when the associated major_status is either 1086 GSS_S_CONTINUE_NEEDED, or GSS_S_COMPLETE. Callers of GSS-API (both 1087 initiators and acceptors) can assume that per-message protection (via 1088 GSS_Wrap(), GSS_Unwrap(), GSS_GetMIC() and GSS_VerifyMIC()) is 1089 available and ready for use if either: prot_ready_state == TRUE, or 1090 major_status == GSS_S_COMPLETE, though mutual authentication (if 1091 requested) cannot be guaranteed until GSS_S_COMPLETE is returned. 1092 Callers making use of per-message protection services in advance of 1093 GSS_S_COMPLETE status should be aware of the possibility that a 1094 subsequent context establishment step may fail, and that certain 1095 context data (e.g., mech_type) as returned for subsequent calls may 1096 change. 1098 This approach achieves full, transparent backward compatibility for 1099 GSS-API V1 callers, who need not even know of the existence of 1100 prot_ready_state, and who will get the expected behavior from 1101 GSS_S_COMPLETE, but who will not be able to use per-message 1102 protection before GSS_S_COMPLETE is returned. 1104 It is not a requirement that GSS-V2 mechanisms ever return TRUE 1105 prot_ready_state before completion of context establishment (indeed, 1106 some mechanisms will not evolve usable message protection keys, 1107 especially at the context acceptor, before context establishment is 1108 complete). It is expected but not required that GSS-V2 mechanisms 1109 will return TRUE prot_ready_state upon completion of context 1110 establishment if they support per-message protection at all (however 1111 GSS-V2 applications should not assume that TRUE prot_ready_state will 1112 always be returned together with the GSS_S_COMPLETE major_status, 1113 since GSS-V2 implementations may continue to support GSS-V1 mechanism 1114 code, which will never return TRUE prot_ready_state). 1116 When prot_ready_state is returned TRUE, mechanisms shall also set 1117 those context service indicator flags (deleg_state, mutual_state, 1118 replay_det_state, sequence_state, anon_state, trans_state, 1119 conf_avail, integ_avail) which represent facilities confirmed, at 1120 that time, to be available on the context being established. In 1121 situations where prot_ready_state is returned before GSS_S_COMPLETE, 1122 it is possible that additional facilities may be confirmed and 1123 subsequently indicated when GSS_S_COMPLETE is returned. 1125 1.2.8: Implementation Robustness 1126 This section recommends aspects of GSS-API implementation behavior in 1127 the interests of overall robustness. 1129 Invocation of GSS-API calls is to incur no undocumented side effects 1130 visible at the GSS-API level. 1132 If a token is presented for processing on a GSS-API security context 1133 and that token generates a fatal error in processing or is otherwise 1134 determined to be invalid for that context, the context's state should 1135 not be disrupted for purposes of processing subsequent valid tokens. 1137 Certain local conditions at a GSS-API implementation (e.g., 1138 unavailability of memory) may preclude, temporarily or permanently, 1139 the successful processing of tokens on a GSS-API security context, 1140 typically generating GSS_S_FAILURE major_status returns along with 1141 locally-significant minor_status. For robust operation under such 1142 conditions, the following recommendations are made: 1144 Failing calls should free any memory they allocate, so that callers 1145 may retry without causing further loss of resources. 1147 Failure of an individual call on an established context should not 1148 preclude subsequent calls from succeeding on the same context. 1150 Whenever possible, it should be possible for 1151 GSS_Delete_sec_context() calls to be successfully processed even if 1152 other calls cannot succeed, thereby enabling context-related 1153 resources to be released. 1155 A failure of GSS_GetMIC() or GSS_Wrap() due to an attempt to use an 1156 unsupported QOP will not interfere with context validity, nor shall 1157 such a failure impact the ability of the application to subsequently 1158 invoke GSS_GetMIC() or GSS_Wrap() using a supported QOP. Any state 1159 information concerning sequencing of outgoing messages shall be 1160 unchanged by an unsuccesful call of GSS_GetMIC() or GSS_Wrap(). 1162 1.2.9: Delegation 1164 The GSS-API allows delegation to be controlled by the initiating 1165 application via a Boolean parameter to GSS_Init_sec_context(), the 1166 routine that establishes a security context. Some mechanisms do not 1167 support delegation, and for such mechanisms attempts by an 1168 application to enable delegation are ignored. 1170 The acceptor of a security context for which the initiator enabled 1171 delegation will receive (via the delegated_cred_handle parameter of 1172 GSS_Accept_sec_context()) a credential handle that contains the 1173 delegated identity, and this credential handle may be used to 1174 initiate subsequent GSS-API security contexts as an agent or delegate 1175 of the initiator. If the original initiator's identity is "A" and 1176 the delegate's identity is "B", then, depending on the underlying 1177 mechanism, the identity embodied by the delegated credential may be 1178 either "A" or "B acting for A". 1180 For many mechanisms that support delegation, a simple Boolean does 1181 not provide enough control. Examples of additional aspects of 1182 delegation control that a mechanism might provide to an application 1183 are duration of delegation, network addresses from which delegation 1184 is valid, and constraints on the tasks that may be performed by a 1185 delegate. Such controls are presently outside the scope of the GSS- 1186 API. GSS-API implementations supporting mechanisms offering 1187 additional controls should provide extension routines that allow 1188 these controls to be exercised (perhaps by modifying the initiator's 1189 GSS-API credential prior to its use in establishing a context). 1190 However, the simple delegation control provided by GSS-API should 1191 always be able to over-ride other mechanism-specific delegation 1192 controls; if the application instructs GSS_Init_sec_context() that 1193 delegation is not desired, then the implementation must not permit 1194 delegation to occur. This is an exception to the general rule that a 1195 mechanism may enable services even if they are not requested; 1196 delegation may only be provided at the explicit request of the 1197 application. 1199 1.2.10: Interprocess Context Transfer 1201 GSS-API V2 provides routines (GSS_Export_sec_context() and 1202 GSS_Import_sec_context()) which allow a security context to be 1203 transferred between processes on a single machine. The most common 1204 use for such a feature is a client-server design where the server is 1205 implemented as a single process that accepts incoming security 1206 contexts, which then launches child processes to deal with the data 1207 on these contexts. In such a design, the child processes must have 1208 access to the security context data structure created within the 1209 parent by its call to GSS_Accept_sec_context() so that they can use 1210 per-message protection services and delete the security context when 1211 the communication session ends. 1213 Since the security context data structure is expected to contain 1214 sequencing information, it is impractical in general to share a 1215 context between processes. Thus GSS-API provides a call 1216 (GSS_Export_sec_context()) that the process which currently owns the 1217 context can call to declare that it has no intention to use the 1218 context subsequently, and to create an inter-process token containing 1219 information needed by the adopting process to successfully import the 1220 context. After successful completion of this call, the original 1221 security context is made inaccessible to the calling process by GSS- 1222 API, and any context handles referring to this context are no longer 1223 valid. The originating process transfers the inter-process token to 1224 the adopting process, which passes it to GSS_Import_sec_context(), 1225 and a fresh context handle is created such that it is functionally 1226 identical to the original context. 1228 The inter-process token may contain sensitive data from the original 1229 security context (including cryptographic keys). Applications using 1230 inter-process tokens to transfer security contexts must take 1231 appropriate steps to protect these tokens in transit. 1232 Implementations are not required to support the inter-process 1233 transfer of security contexts. The ability to transfer a security 1234 context is indicated when the context is created, by 1235 GSS_Init_sec_context() or GSS_Accept_sec_context() indicating a TRUE 1236 trans_state return value. 1238 2: Interface Descriptions 1240 This section describes the GSS-API's service interface, dividing the 1241 set of calls offered into four groups. Credential management calls 1242 are related to the acquisition and release of credentials by 1243 principals. Context-level calls are related to the management of 1244 security contexts between principals. Per-message calls are related 1245 to the protection of individual messages on established security 1246 contexts. Support calls provide ancillary functions useful to GSS-API 1247 callers. Table 2 groups and summarizes the calls in tabular fashion. 1249 Table 2: GSS-API Calls 1251 CREDENTIAL MANAGEMENT 1253 GSS_Acquire_cred acquire credentials for use 1254 GSS_Release_cred release credentials after use 1255 GSS_Inquire_cred display information about 1256 credentials 1257 GSS_Add_cred construct credentials incrementally 1258 GSS_Inquire_cred_by_mech display per-mechanism credential 1259 information 1261 CONTEXT-LEVEL CALLS 1263 GSS_Init_sec_context initiate outbound security context 1264 GSS_Accept_sec_context accept inbound security context 1265 GSS_Delete_sec_context flush context when no longer needed 1266 GSS_Process_context_token process received control token on 1267 context 1268 GSS_Context_time indicate validity time remaining on 1269 context 1271 GSS_Inquire_context display information about context 1272 GSS_Wrap_size_limit determine GSS_Wrap token size limit 1273 GSS_Export_sec_context transfer context to other process 1274 GSS_Import_sec_context import transferred context 1276 PER-MESSAGE CALLS 1278 GSS_GetMIC apply integrity check, receive as 1279 token separate from message 1280 GSS_VerifyMIC validate integrity check token 1281 along with message 1282 GSS_Wrap sign, optionally encrypt, 1283 encapsulate 1284 GSS_Unwrap decapsulate, decrypt if needed, 1285 validate integrity check 1287 SUPPORT CALLS 1289 GSS_Display_status translate status codes to printable 1290 form 1291 GSS_Indicate_mechs indicate mech_types supported on 1292 local system 1293 GSS_Compare_name compare two names for equality 1294 GSS_Display_name translate name to printable form 1295 GSS_Import_name convert printable name to 1296 normalized form 1297 GSS_Release_name free storage of normalized-form 1298 name 1299 GSS_Release_buffer free storage of general GSS-allocated 1300 object 1301 GSS_Release_OID_set free storage of OID set object 1302 GSS_Create_empty_OID_set create empty OID set 1303 GSS_Add_OID_set_member add member to OID set 1304 GSS_Test_OID_set_member test if OID is member of OID set 1305 GSS_Inquire_names_for_mech indicate name types supported by 1306 mechanism 1307 GSS_Inquire_mechs_for_name indicates mechanisms supporting name 1308 type 1309 GSS_Canonicalize_name translate name to per-mechanism form 1310 GSS_Export_name externalize per-mechanism name 1311 GSS_Duplicate_name duplicate name object 1313 2.1: Credential management calls 1315 These GSS-API calls provide functions related to the management of 1316 credentials. Their characterization with regard to whether or not 1317 they may block pending exchanges with other network entities (e.g., 1318 directories or authentication servers) depends in part on OS-specific 1319 (extra-GSS-API) issues, so is not specified in this document. 1321 The GSS_Acquire_cred() call is defined within the GSS-API in support 1322 of application portability, with a particular orientation towards 1323 support of portable server applications. It is recognized that (for 1324 certain systems and mechanisms) credentials for interactive users may 1325 be managed differently from credentials for server processes; in such 1326 environments, it is the GSS-API implementation's responsibility to 1327 distinguish these cases and the procedures for making this 1328 distinction are a local matter. The GSS_Release_cred() call provides 1329 a means for callers to indicate to the GSS-API that use of a 1330 credentials structure is no longer required. The GSS_Inquire_cred() 1331 call allows callers to determine information about a credentials 1332 structure. The GSS_Add_cred() call enables callers to append 1333 elements to an existing credential structure, allowing iterative 1334 construction of a multi-mechanism credential. The 1335 GSS_Inquire_cred_by_mech() call enables callers to extract per- 1336 mechanism information describing a credentials structure. 1338 2.1.1: GSS_Acquire_cred call 1340 Inputs: 1342 o desired_name INTERNAL NAME, -- NULL requests locally-determined 1343 -- default 1345 o lifetime_req INTEGER, -- in seconds; 0 requests default 1347 o desired_mechs SET OF OBJECT IDENTIFIER, -- NULL requests 1348 -- system-selected default 1350 o cred_usage INTEGER -- 0=INITIATE-AND-ACCEPT, 1=INITIATE-ONLY, 1351 -- 2=ACCEPT-ONLY 1353 Outputs: 1355 o major_status INTEGER, 1357 o minor_status INTEGER, 1359 o output_cred_handle CREDENTIAL HANDLE, -- if returned non-NULL, 1360 -- caller must release with GSS_Release_cred() 1362 o actual_mechs SET OF OBJECT IDENTIFIER, -- if returned non-NULL, 1363 -- caller must release with GSS_Release_oid_set() 1365 o lifetime_rec INTEGER -- in seconds, or reserved value for 1366 -- INDEFINITE 1367 Return major_status codes: 1369 o GSS_S_COMPLETE indicates that requested credentials were 1370 successfully established, for the duration indicated in 1371 lifetime_rec, suitable for the usage requested in cred_usage, 1372 for the set of mech_types indicated in actual_mechs, and that 1373 those credentials can be referenced for subsequent use with 1374 the handle returned in output_cred_handle. 1376 o GSS_S_BAD_MECH indicates that a mech_type unsupported by the 1377 GSS-API implementation type was requested, causing the 1378 credential establishment operation to fail. 1380 o GSS_S_BAD_NAMETYPE indicates that the provided desired_name is 1381 uninterpretable or of a type unsupported by the applicable 1382 underlying GSS-API mechanism(s), so no credentials could be 1383 established for the accompanying desired_name. 1385 o GSS_S_BAD_NAME indicates that the provided desired_name is 1386 inconsistent in terms of internally-incorporated type specifier 1387 information, so no credentials could be established for the 1388 accompanying desired_name. 1390 o GSS_S_CREDENTIALS_EXPIRED indicates that underlying credential 1391 elements corresponding to the requested desired_name have 1392 expired, so requested credentials could not be established. 1394 o GSS_S_NO_CRED indicates that no credential elements corresponding 1395 to the requested desired_name and usage could be accessed, so 1396 requested credentials could not be established. In particular, 1397 this status should be returned upon temporary user-fixable 1398 conditions preventing successful credential establishment and 1399 upon lack of authorization to establish and use credentials 1400 associated with the identity named in the input desired_name 1401 argument. 1403 o GSS_S_FAILURE indicates that credential establishment failed 1404 for reasons unspecified at the GSS-API level. 1406 GSS_Acquire_cred() is used to acquire credentials so that a principal 1407 can (as a function of the input cred_usage parameter) initiate and/or 1408 accept security contexts under the identity represented by the 1409 desired_name input argument. On successful completion, the returned 1410 output_cred_handle result provides a handle for subsequent references 1411 to the acquired credentials. Typically, single-user client processes 1412 requesting that default credential behavior be applied for context 1413 establishment purposes will have no need to invoke this call. 1415 A caller may provide the value NULL (GSS_C_NO_NAME) for desired_name, 1416 which will be interpreted as a request for a credential handle that 1417 will invoke default behavior when passed to GSS_Init_sec_context(), 1418 if cred_usage is GSS_C_INITIATE or GSS_C_BOTH, or 1419 GSS_Accept_sec_context(), if cred_usage is GSS_C_ACCEPT or 1420 GSS_C_BOTH. It is possible that multiple pre-established credentials 1421 may exist for the same principal identity (for example, as a result 1422 of multiple user login sessions) when GSS_Acquire_cred() is called; 1423 the means used in such cases to select a specific credential are 1424 local matters. The input lifetime_req argument to GSS_Acquire_cred() 1425 may provide useful information for local GSS-API implementations to 1426 employ in making this disambiguation in a manner which will best 1427 satisfy a caller's intent. 1429 This routine is expected to be used primarily by context acceptors, 1430 since implementations are likely to provide mechanism-specific ways 1431 of obtaining GSS-API initiator credentials from the system login 1432 process. Some implementations may therefore not support the 1433 acquisition of GSS_C_INITIATE or GSS_C_BOTH credentials via 1434 GSS_Acquire_cred() for any name other than GSS_C_NO_NAME, or a name 1435 resulting from applying GSS_Inquire_context() to an active context, 1436 or a name resulting from applying GSS_Inquire_cred() against a 1437 credential handle corresponding to default behavior. It is important 1438 to recognize that the explicit name which is yielded by resolving a 1439 default reference may change over time, e.g., as a result of local 1440 credential element management operations outside GSS-API; once 1441 resolved, however, the value of such an explicit name will remain 1442 constant. 1444 The lifetime_rec result indicates the length of time for which the 1445 acquired credentials will be valid, as an offset from the present. A 1446 mechanism may return a reserved value indicating INDEFINITE if no 1447 constraints on credential lifetime are imposed. A caller of 1448 GSS_Acquire_cred() can request a length of time for which acquired 1449 credentials are to be valid (lifetime_req argument), beginning at the 1450 present, or can request credentials with a default validity interval. 1451 (Requests for postdated credentials are not supported within the 1452 GSS-API.) Certain mechanisms and implementations may bind in 1453 credential validity period specifiers at a point preliminary to 1454 invocation of the GSS_Acquire_cred() call (e.g., in conjunction with 1455 user login procedures). As a result, callers requesting non-default 1456 values for lifetime_req must recognize that such requests cannot 1457 always be honored and must be prepared to accommodate the use of 1458 returned credentials with different lifetimes as indicated in 1459 lifetime_rec. 1461 The caller of GSS_Acquire_cred() can explicitly specify a set of 1462 mech_types which are to be accommodated in the returned credentials 1463 (desired_mechs argument), or can request credentials for a system- 1464 defined default set of mech_types. Selection of the system-specified 1465 default set is recommended in the interests of application 1466 portability. The actual_mechs return value may be interrogated by the 1467 caller to determine the set of mechanisms with which the returned 1468 credentials may be used. 1470 2.1.2: GSS_Release_cred call 1472 Input: 1474 o cred_handle CREDENTIAL HANDLE -- if GSS_C_NO_CREDENTIAL 1475 -- is specified, the call will complete successfully, but 1476 -- will have no effect; no credential elements will be 1477 -- released. 1479 Outputs: 1481 o major_status INTEGER, 1483 o minor_status INTEGER 1485 Return major_status codes: 1487 o GSS_S_COMPLETE indicates that the credentials referenced by the 1488 input cred_handle were released for purposes of subsequent 1489 access by the caller. The effect on other processes which may 1490 be authorized shared access to such credentials is a local 1491 matter. 1493 o GSS_S_NO_CRED indicates that no release operation was 1494 performed, either because the input cred_handle was invalid or 1495 because the caller lacks authorization to access the 1496 referenced credentials. 1498 o GSS_S_FAILURE indicates that the release operation failed for 1499 reasons unspecified at the GSS-API level. 1501 Provides a means for a caller to explicitly request that credentials 1502 be released when their use is no longer required. Note that system- 1503 specific credential management functions are also likely to exist, 1504 for example to assure that credentials shared among processes are 1505 properly deleted when all affected processes terminate, even if no 1506 explicit release requests are issued by those processes. Given the 1507 fact that multiple callers are not precluded from gaining authorized 1508 access to the same credentials, invocation of GSS_Release_cred() 1509 cannot be assumed to delete a particular set of credentials on a 1510 system-wide basis. 1512 2.1.3: GSS_Inquire_cred call 1514 Input: 1516 o cred_handle CREDENTIAL HANDLE -- if GSS_C_NO_CREDENTIAL 1517 -- is specified, default initiator credentials are queried 1519 Outputs: 1521 o major_status INTEGER, 1523 o minor_status INTEGER, 1525 o cred_name INTERNAL NAME, -- caller must release with 1526 -- GSS_Release_name() 1528 o lifetime_rec INTEGER -- in seconds, or reserved value for 1529 -- INDEFINITE 1531 o cred_usage INTEGER, -- 0=INITIATE-AND-ACCEPT, 1=INITIATE-ONLY, 1532 -- 2=ACCEPT-ONLY 1534 o mech_set SET OF OBJECT IDENTIFIER -- caller must release 1535 -- with GSS_Release_oid_set() 1537 Return major_status codes: 1539 o GSS_S_COMPLETE indicates that the credentials referenced by the 1540 input cred_handle argument were valid, and that the output 1541 cred_name, lifetime_rec, and cred_usage values represent, 1542 respectively, the credentials' associated principal name, 1543 remaining lifetime, suitable usage modes, and supported 1544 mechanism types. 1546 o GSS_S_NO_CRED indicates that no information could be returned 1547 about the referenced credentials, either because the input 1548 cred_handle was invalid or because the caller lacks 1549 authorization to access the referenced credentials. 1551 o GSS_S_DEFECTIVE_CREDENTIAL indicates that the referenced 1552 credentials are invalid. 1554 o GSS_S_CREDENTIALS_EXPIRED indicates that the referenced 1555 credentials have expired. 1557 o GSS_S_FAILURE indicates that the operation failed for 1558 reasons unspecified at the GSS-API level. 1560 The GSS_Inquire_cred() call is defined primarily for the use of those 1561 callers which request use of default credential behavior rather than 1562 acquiring credentials explicitly with GSS_Acquire_cred(). It enables 1563 callers to determine a credential structure's associated principal 1564 name, remaining validity period, usability for security context 1565 initiation and/or acceptance, and supported mechanisms. 1567 For a multi-mechanism credential, the returned "lifetime" specifier 1568 indicates the shortest lifetime of any of the mechanisms' elements in 1569 the credential (for either context initiation or acceptance 1570 purposes). 1572 GSS_Inquire_cred() should indicate INITIATE-AND-ACCEPT for 1573 "cred_usage" if both of the following conditions hold: 1575 (1) there exists in the credential an element which allows 1576 context initiation using some mechanism 1578 (2) there exists in the credential an element which allows 1579 context acceptance using some mechanism (allowably, but not 1580 necessarily, one of the same mechanism(s) qualifying for (1)). 1582 If condition (1) holds but not condition (2), GSS_Inquire_cred() 1583 should indicate INITIATE-ONLY for "cred_usage". If condition (2) 1584 holds but not condition (1), GSS_Inquire_cred() should indicate 1585 ACCEPT-ONLY for "cred_usage". 1587 Callers requiring finer disambiguation among available combinations 1588 of lifetimes, usage modes, and mechanisms should call the 1589 GSS_Inquire_cred_by_mech() routine, passing that routine one of the 1590 mech OIDs returned by GSS_Inquire_cred(). 1592 2.1.4: GSS_Add_cred call 1594 Inputs: 1596 o input_cred_handle CREDENTIAL HANDLE -- handle to credential 1597 -- structure created with prior GSS_Acquire_cred() or 1598 -- GSS_Add_cred() call; see text for definition of behavior 1599 -- when GSS_C_NO_CREDENTIAL provided. 1601 o desired_name INTERNAL NAME 1603 o initiator_time_req INTEGER -- in seconds; 0 requests default 1605 o acceptor_time_req INTEGER -- in seconds; 0 requests default 1607 o desired_mech OBJECT IDENTIFIER 1608 o cred_usage INTEGER -- 0=INITIATE-AND-ACCEPT, 1=INITIATE-ONLY, 1609 -- 2=ACCEPT-ONLY 1611 Outputs: 1613 o major_status INTEGER, 1615 o minor_status INTEGER, 1617 o output_cred_handle CREDENTIAL HANDLE, -- NULL to request that 1618 -- credential elements be added "in place" to the credential 1619 -- structure identified by input_cred_handle, 1620 -- non-NULL pointer to request that 1621 -- a new credential structure and handle be created. 1622 -- if credential handle returned, caller must release with 1623 -- GSS_Release_cred() 1625 o actual_mechs SET OF OBJECT IDENTIFIER, -- if returned, caller must 1626 -- release with GSS_Release_oid_set() 1628 o initiator_time_rec INTEGER -- in seconds, or reserved value for 1629 -- INDEFINITE 1631 o acceptor_time_rec INTEGER -- in seconds, or reserved value for 1632 -- INDEFINITE 1634 o cred_usage INTEGER, -- 0=INITIATE-AND-ACCEPT, 1=INITIATE-ONLY, 1635 -- 2=ACCEPT-ONLY 1637 o mech_set SET OF OBJECT IDENTIFIER -- full set of mechanisms 1638 -- supported by resulting credential. 1640 Return major_status codes: 1642 o GSS_S_COMPLETE indicates that the credentials referenced by 1643 the input_cred_handle argument were valid, and that the 1644 resulting credential from GSS_Add_cred() is valid for the 1645 durations indicated in initiator_time_rec and acceptor_time_rec, 1646 suitable for the usage requested in cred_usage, and for the 1647 mechanisms indicated in actual_mechs. 1649 o GSS_S_DUPLICATE_ELEMENT indicates that the input desired_mech 1650 specified a mechanism for which the referenced credential 1651 already contained a credential element with overlapping cred_usage 1652 and validity time specifiers. 1654 o GSS_S_BAD_MECH indicates that the input desired_mech specified 1655 a mechanism unsupported by the GSS-API implementation, causing 1656 the GSS_Add_cred() operation to fail. 1658 o GSS_S_BAD_NAMETYPE indicates that the provided desired_name 1659 is uninterpretable or of a type unsupported by the applicable 1660 underlying GSS-API mechanism(s), so the GSS_Add_cred() operation 1661 could not be performed for that name. 1663 o GSS_S_BAD_NAME indicates that the provided desired_name is 1664 inconsistent in terms of internally-incorporated type specifier 1665 information, so the GSS_Add_cred() operation could not be 1666 performed for that name. 1668 o GSS_S_NO_CRED indicates that the input_cred_handle referenced 1669 invalid or inaccessible credentials. In particular, 1670 this status should be returned upon temporary user-fixable 1671 conditions preventing successful credential establishment or 1672 upon lack of authorization to establish or use credentials 1673 representing the requested identity. 1675 o GSS_S_CREDENTIALS_EXPIRED indicates that referenced credential 1676 elements have expired, so the GSS_Add_cred() operation could 1677 not be performed. 1679 o GSS_S_FAILURE indicates that the operation failed for 1680 reasons unspecified at the GSS-API level. 1682 GSS_Add_cred() enables callers to construct credentials iteratively 1683 by adding credential elements in successive operations, corresponding 1684 to different mechanisms. This offers particular value in multi- 1685 mechanism environments, as the major_status and minor_status values 1686 returned on each iteration are individually visible and can therefore 1687 be interpreted unambiguously on a per-mechanism basis. A credential 1688 element is identified by the name of the principal to which it 1689 refers. GSS-API implementations must impose a local access control 1690 policy on callers of this routine to prevent unauthorized callers 1691 from acquiring credential elements to which they are not entitled. 1692 This routine is not intended to provide a ``login to the network'' 1693 function, as such a function would involve the creation of new 1694 mechanism-specific authentication data, rather than merely acquiring 1695 a GSS-API handle to existing data. Such functions, if required, 1696 should be defined in implementation-specific extension routines. 1698 If credential acquisition is time-consuming for a mechanism, the 1699 mechanism may choose to delay the actual acquisition until the 1700 credential is required (e.g. by GSS_Init_sec_context() or 1701 GSS_Accept_sec_context()). Such mechanism-specific implementation 1702 decisions should be invisible to the calling application; thus a call 1703 of GSS_Inquire_cred() immediately following the call of 1704 GSS_Acquire_cred() must return valid credential data, and may 1705 therefore incur the overhead of a deferred credential acquisition. 1707 If GSS_C_NO_CREDENTIAL is specified as input_cred_handle, a non-NULL 1708 output_cred_handle must be supplied. For the case of 1709 GSS_C_NO_CREDENTIAL as input_cred_handle, GSS_Add_cred() will create 1710 the credential referenced by its output_cred_handle based on default 1711 behavior. That is, the call will have the same effect as if the 1712 caller had previously called GSS_Acquire_cred(), specifying the same 1713 usage and passing GSS_C_NO_NAME as the desired_name parameter 1714 (thereby obtaining an explicit credential handle corresponding to 1715 default behavior), had passed that credential handle to 1716 GSS_Add_cred(), and had finally called GSS_Release_cred() on the 1717 credential handle received from GSS_Acquire_cred(). 1719 This routine is expected to be used primarily by context acceptors, 1720 since implementations are likely to provide mechanism-specific ways 1721 of obtaining GSS-API initiator credentials from the system login 1722 process. Some implementations may therefore not support the 1723 acquisition of GSS_C_INITIATE or GSS_C_BOTH credentials via 1724 GSS_Acquire_cred() for any name other than GSS_C_NO_NAME, or a name 1725 resulting from applying GSS_Inquire_context() to an active context, 1726 or a name resulting from applying GSS_Inquire_cred() against a 1727 credential handle corresponding to default behavior. It is important 1728 to recognize that the explicit name which is yielded by resolving a 1729 default reference may change over time, e.g., as a result of local 1730 credential element management operations outside GSS-API; once 1731 resolved, however, the value of such an explicit name will remain 1732 constant. 1734 A caller may provide the value NULL (GSS_C_NO_NAME) for desired_name, 1735 which will be interpreted as a request for a credential handle that 1736 will invoke default behavior when passed to GSS_Init_sec_context(), 1737 if cred_usage is GSS_C_INITIATE or GSS_C_BOTH, or 1738 GSS_Accept_sec_context(), if cred_usage is GSS_C_ACCEPT or 1739 GSS_C_BOTH. 1741 The same input desired_name, or default reference, should be used on 1742 all GSS_Acquire_cred() and GSS_Add_cred() calls corresponding to a 1743 particular credential. 1745 2.1.5: GSS_Inquire_cred_by_mech call 1747 Inputs: 1749 o cred_handle CREDENTIAL HANDLE -- if GSS_C_NO_CREDENTIAL 1750 -- specified, default initiator credentials are queried 1751 o mech_type OBJECT IDENTIFIER -- specific mechanism for 1752 -- which credentials are being queried 1754 Outputs: 1756 o major_status INTEGER, 1758 o minor_status INTEGER, 1760 o cred_name INTERNAL NAME, -- guaranteed to be MN; caller must 1761 -- release with GSS_Release_name() 1763 o lifetime_rec_initiate INTEGER -- in seconds, or reserved value for 1764 -- INDEFINITE 1766 o lifetime_rec_accept INTEGER -- in seconds, or reserved value for 1767 -- INDEFINITE 1769 o cred_usage INTEGER, -- 0=INITIATE-AND-ACCEPT, 1=INITIATE-ONLY, 1770 -- 2=ACCEPT-ONLY 1772 Return major_status codes: 1774 o GSS_S_COMPLETE indicates that the credentials referenced by the 1775 input cred_handle argument were valid, that the mechanism 1776 indicated by the input mech_type was represented with elements 1777 within those credentials, and that the output cred_name, 1778 lifetime_rec_initiate, lifetime_rec_accept, and cred_usage values 1779 represent, respectively, the credentials' associated principal 1780 name, remaining lifetimes, and suitable usage modes. 1782 o GSS_S_NO_CRED indicates that no information could be returned 1783 about the referenced credentials, either because the input 1784 cred_handle was invalid or because the caller lacks 1785 authorization to access the referenced credentials. 1787 o GSS_S_DEFECTIVE_CREDENTIAL indicates that the referenced 1788 credentials are invalid. 1790 o GSS_S_CREDENTIALS_EXPIRED indicates that the referenced 1791 credentials have expired. 1793 o GSS_S_BAD_MECH indicates that the referenced credentials do not 1794 contain elements for the requested mechanism. 1796 o GSS_S_FAILURE indicates that the operation failed for reasons 1797 unspecified at the GSS-API level. 1799 The GSS_Inquire_cred_by_mech() call enables callers in multi- 1800 mechanism environments to acquire specific data about available 1801 combinations of lifetimes, usage modes, and mechanisms within a 1802 credential structure. The lifetime_rec_initiate result indicates the 1803 available lifetime for context initiation purposes; the 1804 lifetime_rec_accept result indicates the available lifetime for 1805 context acceptance purposes. 1807 2.2: Context-level calls 1809 This group of calls is devoted to the establishment and management of 1810 security contexts between peers. A context's initiator calls 1811 GSS_Init_sec_context(), resulting in generation of a token which the 1812 caller passes to the target. At the target, that token is passed to 1813 GSS_Accept_sec_context(). Depending on the underlying mech_type and 1814 specified options, additional token exchanges may be performed in the 1815 course of context establishment; such exchanges are accommodated by 1816 GSS_S_CONTINUE_NEEDED status returns from GSS_Init_sec_context() and 1817 GSS_Accept_sec_context(). 1819 Either party to an established context may invoke 1820 GSS_Delete_sec_context() to flush context information when a context 1821 is no longer required. GSS_Process_context_token() is used to process 1822 received tokens carrying context-level control information. 1823 GSS_Context_time() allows a caller to determine the length of time 1824 for which an established context will remain valid. 1825 GSS_Inquire_context() returns status information describing context 1826 characteristics. GSS_Wrap_size_limit() allows a caller to determine 1827 the size of a token which will be generated by a GSS_Wrap() 1828 operation. GSS_Export_sec_context() and GSS_Import_sec_context() 1829 enable transfer of active contexts between processes on an end 1830 system. 1832 2.2.1: GSS_Init_sec_context call 1834 Inputs: 1836 o claimant_cred_handle CREDENTIAL HANDLE, -- NULL specifies "use 1837 -- default" 1839 o input_context_handle CONTEXT HANDLE, -- 0 1840 -- (GSS_C_NO_CONTEXT) specifies "none assigned yet" 1842 o targ_name INTERNAL NAME, 1844 o mech_type OBJECT IDENTIFIER, -- NULL parameter specifies "use 1845 -- default" 1846 o deleg_req_flag BOOLEAN, 1848 o mutual_req_flag BOOLEAN, 1850 o replay_det_req_flag BOOLEAN, 1852 o sequence_req_flag BOOLEAN, 1854 o anon_req_flag BOOLEAN, 1856 o conf_req_flag BOOLEAN, 1858 o integ_req_flag BOOLEAN, 1860 o lifetime_req INTEGER, -- 0 specifies default lifetime 1862 o chan_bindings OCTET STRING, 1864 o input_token OCTET STRING -- NULL or token received from target 1866 Outputs: 1868 o major_status INTEGER, 1870 o minor_status INTEGER, 1872 o output_context_handle CONTEXT HANDLE, -- once returned non-NULL, 1873 -- caller must release with GSS_Delete_sec_context() 1875 o mech_type OBJECT IDENTIFIER, -- actual mechanism always 1876 -- indicated, never NULL; caller should treat as read-only 1877 -- and should not attempt to release 1879 o output_token OCTET STRING, -- NULL or token to pass to context 1880 -- target; caller must release with GSS_Release_buffer() 1882 o deleg_state BOOLEAN, 1884 o mutual_state BOOLEAN, 1886 o replay_det_state BOOLEAN, 1888 o sequence_state BOOLEAN, 1890 o anon_state BOOLEAN, 1892 o trans_state BOOLEAN, 1893 o prot_ready_state BOOLEAN, -- see Section 1.2.7 1895 o conf_avail BOOLEAN, 1897 o integ_avail BOOLEAN, 1899 o lifetime_rec INTEGER -- in seconds, or reserved value for 1900 -- INDEFINITE 1902 This call may block pending network interactions for those mech_types 1903 in which an authentication server or other network entity must be 1904 consulted on behalf of a context initiator in order to generate an 1905 output_token suitable for presentation to a specified target. 1907 Return major_status codes: 1909 o GSS_S_COMPLETE indicates that context-level information was 1910 successfully initialized, and that the returned output_token 1911 will provide sufficient information for the target to perform 1912 per-message processing on the newly-established context. 1914 o GSS_S_CONTINUE_NEEDED indicates that control information in the 1915 returned output_token must be sent to the target, and that a 1916 reply must be received and passed as the input_token argument 1917 to a continuation call to GSS_Init_sec_context(), before 1918 per-message processing can be performed in conjunction with 1919 this context (unless the prot_ready_state value is concurrently 1920 returned TRUE). 1922 o GSS_S_DEFECTIVE_TOKEN indicates that consistency checks 1923 performed on the input_token failed, preventing further 1924 processing from being performed based on that token. 1926 o GSS_S_DEFECTIVE_CREDENTIAL indicates that consistency checks 1927 performed on the credential structure referenced by 1928 claimant_cred_handle failed, preventing further processing from 1929 being performed using that credential structure. 1931 o GSS_S_BAD_SIG (GSS_S_BAD_MIC) indicates that the received 1932 input_token contains an incorrect integrity check, so context 1933 setup cannot be accomplished. 1935 o GSS_S_NO_CRED indicates that no context was established, 1936 either because the input cred_handle was invalid, because the 1937 referenced credentials are valid for context acceptor use 1938 only, because the caller lacks authorization to access the 1939 referenced credentials, or because the resolution of default 1940 credentials failed. 1942 o GSS_S_CREDENTIALS_EXPIRED indicates that the credentials 1943 provided through the input claimant_cred_handle argument are no 1944 longer valid, so context establishment cannot be completed. 1946 o GSS_S_BAD_BINDINGS indicates that a mismatch between the 1947 caller-provided chan_bindings and those extracted from the 1948 input_token was detected, signifying a security-relevant 1949 event and preventing context establishment. (This result will 1950 be returned by GSS_Init_sec_context() only for contexts where 1951 mutual_state is TRUE.) 1953 o GSS_S_OLD_TOKEN indicates that the input_token is too old to 1954 be checked for integrity. This is a fatal error during context 1955 establishment. 1957 o GSS_S_DUPLICATE_TOKEN indicates that the input token has a 1958 correct integrity check, but is a duplicate of a token already 1959 processed. This is a fatal error during context establishment. 1961 o GSS_S_NO_CONTEXT indicates that no valid context was recognized 1962 for the input context_handle provided; this major status will 1963 be returned only for successor calls following GSS_S_CONTINUE_ 1964 NEEDED status returns. 1966 o GSS_S_BAD_NAMETYPE indicates that the provided targ_name is 1967 of a type uninterpretable or unsupported by the applicable 1968 underlying GSS-API mechanism(s), so context establishment 1969 cannot be completed. 1971 o GSS_S_BAD_NAME indicates that the provided targ_name is 1972 inconsistent in terms of internally-incorporated type specifier 1973 information, so context establishment cannot be accomplished. 1975 o GSS_S_BAD_MECH indicates receipt of a context establishment token 1976 or of a caller request specifying a mechanism unsupported by 1977 the local system or with the caller's active credentials 1979 o GSS_S_FAILURE indicates that context setup could not be 1980 accomplished for reasons unspecified at the GSS-API level, and 1981 that no interface-defined recovery action is available. 1983 This routine is used by a context initiator, and ordinarily emits an 1984 output_token suitable for use by the target within the selected 1985 mech_type's protocol. For the case of a multi-step exchange, this 1986 output_token will be one in a series, each generated by a successive 1987 call. Using information in the credentials structure referenced by 1988 claimant_cred_handle, GSS_Init_sec_context() initializes the data 1989 structures required to establish a security context with target 1990 targ_name. 1992 The targ_name may be any valid INTERNAL NAME; it need not be an MN. 1993 In addition to support for other name types, it is recommended (newly 1994 as of GSS-V2, Update 1) that mechanisms be able to accept 1995 GSS_C_NO_NAME as an input type for targ_name. While recommended, 1996 such support is not required, and it is recognized that not all 1997 mechanisms can construct tokens without explicitly naming the context 1998 target, even when mutual authentication of the target is not 1999 obtained. Callers wishing to make use of this facility and concerned 2000 with portability should be aware that support for GSS_C_NO_NAME as 2001 input targ_name type is unlikely to be provided within mechanism 2002 definitions specified prior to GSS-V2, Update 1. 2004 The claimant_cred_handle must correspond to the same valid 2005 credentials structure on the initial call to GSS_Init_sec_context() 2006 and on any successor calls resulting from GSS_S_CONTINUE_NEEDED 2007 status returns; different protocol sequences modeled by the 2008 GSS_S_CONTINUE_NEEDED facility will require access to credentials at 2009 different points in the context establishment sequence. 2011 The caller-provided input_context_handle argument is to be 0 2012 (GSS_C_NO_CONTEXT), specifying "not yet assigned", on the first 2013 GSS_Init_sec_context() call relating to a given context. If 2014 successful (i.e., if accompanied by major_status GSS_S_COMPLETE or 2015 GSS_S_CONTINUE_NEEDED), and only if successful, the initial 2016 GSS_Init_sec_context() call returns a non-zero output_context_handle 2017 for use in future references to this context. Once a non-zero 2018 output_context_handle has been returned, GSS-API callers should call 2019 GSS_Delete_sec_context() to release context-related resources if 2020 errors occur in later phases of context establishment, or when an 2021 established context is no longer required. If GSS_Init_sec_context() 2022 is passed the handle of a context which is already fully established, 2023 GSS_S_FAILURE status is returned. 2025 When continuation attempts to GSS_Init_sec_context() are needed to 2026 perform context establishment, the previously-returned non-zero 2027 handle value is entered into the input_context_handle argument and 2028 will be echoed in the returned output_context_handle argument. On 2029 such continuation attempts (and only on continuation attempts) the 2030 input_token value is used, to provide the token returned from the 2031 context's target. 2033 The chan_bindings argument is used by the caller to provide 2034 information binding the security context to security-related 2035 characteristics (e.g., addresses, cryptographic keys) of the 2036 underlying communications channel. See Section 1.1.6 of this document 2037 for more discussion of this argument's usage. 2039 The input_token argument contains a message received from the target, 2040 and is significant only on a call to GSS_Init_sec_context() which 2041 follows a previous return indicating GSS_S_CONTINUE_NEEDED 2042 major_status. 2044 It is the caller's responsibility to establish a communications path 2045 to the target, and to transmit any returned output_token (independent 2046 of the accompanying returned major_status value) to the target over 2047 that path. The output_token can, however, be transmitted along with 2048 the first application-provided input message to be processed by 2049 GSS_GetMIC() or GSS_Wrap() in conjunction with a successfully- 2050 established context. (Note: when the GSS-V2 prot_ready_state 2051 indicator is returned TRUE, it can be possible to transfer a 2052 protected message before context establishment is complete: see also 2053 Section 1.2.7) 2055 The initiator may request various context-level functions through 2056 input flags: the deleg_req_flag requests delegation of access rights, 2057 the mutual_req_flag requests mutual authentication, the 2058 replay_det_req_flag requests that replay detection features be 2059 applied to messages transferred on the established context, and the 2060 sequence_req_flag requests that sequencing be enforced. (See Section 2061 1.2.3 for more information on replay detection and sequencing 2062 features.) The anon_req_flag requests that the initiator's identity 2063 not be transferred within tokens to be sent to the acceptor. 2065 The conf_req_flag and integ_req_flag provide informatory inputs to 2066 the GSS-API implementation as to whether, respectively, per-message 2067 confidentiality and per-message integrity services will be required 2068 on the context. This information is important as an input to 2069 negotiating mechanisms. It is important to recognize, however, that 2070 the inclusion of these flags (which are newly defined for GSS-V2) 2071 introduces a backward incompatibility with callers implemented to 2072 GSS-V1, where the flags were not defined. Since no GSS-V1 callers 2073 would set these flags, even if per-message services are desired, 2074 GSS-V2 mechanism implementations which enable such services 2075 selectively based on the flags' values may fail to provide them to 2076 contexts established for GSS-V1 callers. It may be appropriate under 2077 certain circumstances, therefore, for such mechanism implementations 2078 to infer these service request flags to be set if a caller is known 2079 to be implemented to GSS-V1. 2081 Not all of the optionally-requestable features will be available in 2082 all underlying mech_types. The corresponding return state values 2083 deleg_state, mutual_state, replay_det_state, and sequence_state 2084 indicate, as a function of mech_type processing capabilities and 2085 initiator-provided input flags, the set of features which will be 2086 active on the context. The returned trans_state value indicates 2087 whether the context is transferable to other processes through use of 2088 GSS_Export_sec_context(). These state indicators' values are 2089 undefined unless either the routine's major_status indicates 2090 GSS_S_COMPLETE, or TRUE prot_ready_state is returned along with 2091 GSS_S_CONTINUE_NEEDED major_status; for the latter case, it is 2092 possible that additional features, not confirmed or indicated along 2093 with TRUE prot_ready_state, will be confirmed and indicated when 2094 GSS_S_COMPLETE is subsequently returned. 2096 The returned anon_state and prot_ready_state values are significant 2097 for both GSS_S_COMPLETE and GSS_S_CONTINUE_NEEDED major_status 2098 returns from GSS_Init_sec_context(). When anon_state is returned 2099 TRUE, this indicates that neither the current token nor its 2100 predecessors delivers or has delivered the initiator's identity. 2101 Callers wishing to perform context establishment only if anonymity 2102 support is provided should transfer a returned token from 2103 GSS_Init_sec_context() to the peer only if it is accompanied by a 2104 TRUE anon_state indicator. When prot_ready_state is returned TRUE in 2105 conjunction with GSS_S_CONTINUE_NEEDED major_status, this indicates 2106 that per-message protection operations may be applied on the context: 2107 see Section 1.2.7 for further discussion of this facility. 2109 Failure to provide the precise set of features requested by the 2110 caller does not cause context establishment to fail; it is the 2111 caller's prerogative to delete the context if the feature set 2112 provided is unsuitable for the caller's use. 2114 The returned mech_type value indicates the specific mechanism 2115 employed on the context; it will never indicate the value for 2116 "default". A valid mech_type result must be returned along with a 2117 GSS_S_COMPLETE status return; GSS-API implementations may (but are 2118 not required to) also return mech_type along with predecessor calls 2119 indicating GSS_S_CONTINUE_NEEDED status or (if a mechanism is 2120 determinable) in conjunction with fatal error cases. For the case of 2121 mechanisms which themselves perform negotiation, the returned 2122 mech_type result may indicate selection of a mechanism identified by 2123 an OID different than that passed in the input mech_type argument, 2124 and the returned value may change between successive calls returning 2125 GSS_S_CONTINUE_NEEDED and the final call returning GSS_S_COMPLETE. 2127 The conf_avail return value indicates whether the context supports 2128 per-message confidentiality services, and so informs the caller 2129 whether or not a request for encryption through the conf_req_flag 2130 input to GSS_Wrap() can be honored. In similar fashion, the 2131 integ_avail return value indicates whether per-message integrity 2132 services are available (through either GSS_GetMIC() or GSS_Wrap()) on 2133 the established context. These state indicators' values are undefined 2134 unless either the routine's major_status indicates GSS_S_COMPLETE, or 2135 TRUE prot_ready_state is returned along with GSS_S_CONTINUE_NEEDED 2136 major_status. 2138 The lifetime_req input specifies a desired upper bound for the 2139 lifetime of the context to be established, with a value of 0 used to 2140 request a default lifetime. The lifetime_rec return value indicates 2141 the length of time for which the context will be valid, expressed as 2142 an offset from the present; depending on mechanism capabilities, 2143 credential lifetimes, and local policy, it may not correspond to the 2144 value requested in lifetime_req. If no constraints on context 2145 lifetime are imposed, this may be indicated by returning a reserved 2146 value representing INDEFINITE lifetime_req. The value of lifetime_rec 2147 is undefined unless the routine's major_status indicates 2148 GSS_S_COMPLETE. 2150 If the mutual_state is TRUE, this fact will be reflected within the 2151 output_token. A call to GSS_Accept_sec_context() at the target in 2152 conjunction with such a context will return a token, to be processed 2153 by a continuation call to GSS_Init_sec_context(), in order to achieve 2154 mutual authentication. 2156 2.2.2: GSS_Accept_sec_context call 2158 Inputs: 2160 o acceptor_cred_handle CREDENTIAL HANDLE, -- NULL specifies 2161 -- "use default" 2163 o input_context_handle CONTEXT HANDLE, -- 0 2164 -- (GSS_C_NO_CONTEXT) specifies "not yet assigned" 2166 o chan_bindings OCTET STRING, 2168 o input_token OCTET STRING 2170 Outputs: 2172 o major_status INTEGER, 2174 o minor_status INTEGER, 2176 o src_name INTERNAL NAME, -- guaranteed to be MN 2177 -- once returned, caller must release with GSS_Release_name() 2179 o mech_type OBJECT IDENTIFIER, -- caller should treat as 2180 -- read-only; does not need to be released 2182 o output_context_handle CONTEXT HANDLE, -- once returned 2183 -- non-NULL in context establishment sequence, caller 2184 -- must release with GSS_Delete_sec_context() 2186 o deleg_state BOOLEAN, 2188 o mutual_state BOOLEAN, 2190 o replay_det_state BOOLEAN, 2192 o sequence_state BOOLEAN, 2194 o anon_state BOOLEAN, 2196 o trans_state BOOLEAN, 2198 o prot_ready_state BOOLEAN, -- see Section 1.2.7 for discussion 2200 o conf_avail BOOLEAN, 2202 o integ_avail BOOLEAN, 2204 o lifetime_rec INTEGER, -- in seconds, or reserved value for 2205 -- INDEFINITE 2207 o delegated_cred_handle CREDENTIAL HANDLE, -- if returned non-NULL, 2208 -- caller must release with GSS_Release_cred() 2210 o output_token OCTET STRING -- NULL or token to pass to context 2211 -- initiator; if returned non-NULL, caller must release with 2212 -- GSS_Release_buffer() 2214 This call may block pending network interactions for those mech_types 2215 in which a directory service or other network entity must be 2216 consulted on behalf of a context acceptor in order to validate a 2217 received input_token. 2219 Return major_status codes: 2221 o GSS_S_COMPLETE indicates that context-level data structures 2222 were successfully initialized, and that per-message processing 2223 can now be performed in conjunction with this context. 2225 o GSS_S_CONTINUE_NEEDED indicates that control information in the 2226 returned output_token must be sent to the initiator, and that 2227 a response must be received and passed as the input_token 2228 argument to a continuation call to GSS_Accept_sec_context(), 2229 before per-message processing can be performed in conjunction 2230 with this context. 2232 o GSS_S_DEFECTIVE_TOKEN indicates that consistency checks performed 2233 on the input_token failed, preventing further processing from 2234 being performed based on that token. 2236 o GSS_S_DEFECTIVE_CREDENTIAL indicates that consistency checks 2237 performed on the credential structure referenced by 2238 acceptor_cred_handle failed, preventing further processing from 2239 being performed using that credential structure. 2241 o GSS_S_BAD_SIG (GSS_S_BAD_MIC) indicates that the received 2242 input_token contains an incorrect integrity check, so context 2243 setup cannot be accomplished. 2245 o GSS_S_DUPLICATE_TOKEN indicates that the integrity check on the 2246 received input_token was correct, but that the input_token 2247 was recognized as a duplicate of an input_token already 2248 processed. No new context is established. 2250 o GSS_S_OLD_TOKEN indicates that the integrity check on the received 2251 input_token was correct, but that the input_token is too old 2252 to be checked for duplication against previously-processed 2253 input_tokens. No new context is established. 2255 o GSS_S_NO_CRED indicates that no context was established, either 2256 because the input cred_handle was invalid, because the 2257 referenced credentials are valid for context initiator use 2258 only, because the caller lacks authorization to access the 2259 referenced credentials, or because the procedure for default 2260 credential resolution failed. 2262 o GSS_S_CREDENTIALS_EXPIRED indicates that the credentials provided 2263 through the input acceptor_cred_handle argument are no 2264 longer valid, so context establishment cannot be completed. 2266 o GSS_S_BAD_BINDINGS indicates that a mismatch between the 2267 caller-provided chan_bindings and those extracted from the 2268 input_token was detected, signifying a security-relevant 2269 event and preventing context establishment. 2271 o GSS_S_NO_CONTEXT indicates that no valid context was recognized 2272 for the input context_handle provided; this major status will 2273 be returned only for successor calls following GSS_S_CONTINUE_ 2274 NEEDED status returns. 2276 o GSS_S_BAD_MECH indicates receipt of a context establishment token 2277 specifying a mechanism unsupported by the local system or with 2278 the caller's active credentials. 2280 o GSS_S_FAILURE indicates that context setup could not be 2281 accomplished for reasons unspecified at the GSS-API level, and 2282 that no interface-defined recovery action is available. 2284 The GSS_Accept_sec_context() routine is used by a context target. 2285 Using information in the credentials structure referenced by the 2286 input acceptor_cred_handle, it verifies the incoming input_token and 2287 (following the successful completion of a context establishment 2288 sequence) returns the authenticated src_name and the mech_type used. 2289 The returned src_name is guaranteed to be an MN, processed by the 2290 mechanism under which the context was established. The 2291 acceptor_cred_handle must correspond to the same valid credentials 2292 structure on the initial call to GSS_Accept_sec_context() and on any 2293 successor calls resulting from GSS_S_CONTINUE_NEEDED status returns; 2294 different protocol sequences modeled by the GSS_S_CONTINUE_NEEDED 2295 mechanism will require access to credentials at different points in 2296 the context establishment sequence. 2298 The caller-provided input_context_handle argument is to be 0 2299 (GSS_C_NO_CONTEXT), specifying "not yet assigned", on the first 2300 GSS_Accept_sec_context() call relating to a given context. If 2301 successful (i.e., if accompanied by major_status GSS_S_COMPLETE or 2302 GSS_S_CONTINUE_NEEDED), and only if successful, the initial 2303 GSS_Accept_sec_context() call returns a non-zero 2304 output_context_handle for use in future references to this context. 2305 Once a non-zero output_context_handle has been returned, GSS-API 2306 callers should call GSS_Delete_sec_context() to release context- 2307 related resources if errors occur in later phases of context 2308 establishment, or when an established context is no longer required. 2309 If GSS_Accept_sec_context() is passed the handle of a context which 2310 is already fully established, GSS_S_FAILURE status is returned. 2312 The chan_bindings argument is used by the caller to provide 2313 information binding the security context to security-related 2314 characteristics (e.g., addresses, cryptographic keys) of the 2315 underlying communications channel. See Section 1.1.6 of this document 2316 for more discussion of this argument's usage. 2318 The returned state results (deleg_state, mutual_state, 2319 replay_det_state, sequence_state, anon_state, trans_state, and 2320 prot_ready_state) reflect the same information as described for 2321 GSS_Init_sec_context(), and their values are significant under the 2322 same return state conditions. 2324 The conf_avail return value indicates whether the context supports 2325 per-message confidentiality services, and so informs the caller 2326 whether or not a request for encryption through the conf_req_flag 2327 input to GSS_Wrap() can be honored. In similar fashion, the 2328 integ_avail return value indicates whether per-message integrity 2329 services are available (through either GSS_GetMIC() or GSS_Wrap()) 2330 on the established context. These values are significant under the 2331 same return state conditions as described under 2332 GSS_Init_sec_context(). 2334 The lifetime_rec return value is significant only in conjunction with 2335 GSS_S_COMPLETE major_status, and indicates the length of time for 2336 which the context will be valid, expressed as an offset from the 2337 present. 2339 The returned mech_type value indicates the specific mechanism 2340 employed on the context; it will never indicate the value for 2341 "default". A valid mech_type result must be returned whenever 2342 GSS_S_COMPLETE status is indicated; GSS-API implementations may (but 2343 are not required to) also return mech_type along with predecessor 2344 calls indicating GSS_S_CONTINUE_NEEDED status or (if a mechanism is 2345 determinable) in conjunction with fatal error cases. For the case of 2346 mechanisms which themselves perform negotiation, the returned 2347 mech_type result may indicate selection of a mechanism identified by 2348 an OID different than that passed in the input mech_type argument, 2349 and the returned value may change between successive calls returning 2350 GSS_S_CONTINUE_NEEDED and the final call returning GSS_S_COMPLETE. 2352 The delegated_cred_handle result is significant only when deleg_state 2353 is TRUE, and provides a means for the target to reference the 2354 delegated credentials. The output_token result, when non-NULL, 2355 provides a context-level token to be returned to the context 2356 initiator to continue a multi-step context establishment sequence. As 2357 noted with GSS_Init_sec_context(), any returned token should be 2358 transferred to the context's peer (in this case, the context 2359 initiator), independent of the value of the accompanying returned 2360 major_status. 2362 Note: A target must be able to distinguish a context-level 2363 input_token, which is passed to GSS_Accept_sec_context(), from the 2364 per-message data elements passed to GSS_VerifyMIC() or GSS_Unwrap(). 2365 These data elements may arrive in a single application message, and 2366 GSS_Accept_sec_context() must be performed before per-message 2367 processing can be performed successfully. 2369 2.2.3: GSS_Delete_sec_context call 2371 Input: 2373 o context_handle CONTEXT HANDLE 2375 Outputs: 2377 o major_status INTEGER, 2379 o minor_status INTEGER, 2381 o output_context_token OCTET STRING 2383 Return major_status codes: 2385 o GSS_S_COMPLETE indicates that the context was recognized, and that 2386 relevant context-specific information was flushed. If the caller 2387 provides a non-null buffer to receive an output_context_token, and 2388 the mechanism returns a non-NULL token into that buffer, the 2389 returned output_context_token is ready for transfer to the 2390 context's peer. 2392 o GSS_S_NO_CONTEXT indicates that no valid context was recognized 2393 for the input context_handle provided, so no deletion was 2394 performed. 2396 o GSS_S_FAILURE indicates that the context is recognized, but 2397 that the GSS_Delete_sec_context() operation could not be 2398 performed for reasons unspecified at the GSS-API level. 2400 This call can be made by either peer in a security context, to flush 2401 context-specific information. Once a non-zero output_context_handle 2402 has been returned by context establishment calls, GSS-API callers 2403 should call GSS_Delete_sec_context() to release context-related 2404 resources if errors occur in later phases of context establishment, 2405 or when an established context is no longer required. This call may 2406 block pending network interactions for mech_types in which active 2407 notification must be made to a central server when a security context 2408 is to be deleted. 2410 If a non-null output_context_token parameter is provided by the 2411 caller, an output_context_token may be returned to the caller. If an 2412 output_context_token is provided to the caller, it can be passed to 2413 the context's peer to inform the peer's GSS-API implementation that 2414 the peer's corresponding context information can also be flushed. 2415 (Once a context is established, the peers involved are expected to 2416 retain cached credential and context-related information until the 2417 information's expiration time is reached or until a 2418 GSS_Delete_sec_context() call is made.) 2420 The facility for context_token usage to signal context deletion is 2421 retained for compatibility with GSS-API Version 1. For current 2422 usage, it is recommended that both peers to a context invoke 2423 GSS_Delete_sec_context() independently, passing a null 2424 output_context_token buffer to indicate that no context_token is 2425 required. Implementations of GSS_Delete_sec_context() should delete 2426 relevant locally-stored context information. 2428 Attempts to perform per-message processing on a deleted context will 2429 result in error returns. 2431 2.2.4: GSS_Process_context_token call 2433 Inputs: 2435 o context_handle CONTEXT HANDLE, 2437 o input_context_token OCTET STRING 2439 Outputs: 2441 o major_status INTEGER, 2443 o minor_status INTEGER, 2445 Return major_status codes: 2447 o GSS_S_COMPLETE indicates that the input_context_token was 2448 successfully processed in conjunction with the context 2449 referenced by context_handle. 2451 o GSS_S_DEFECTIVE_TOKEN indicates that consistency checks 2452 performed on the received context_token failed, preventing 2453 further processing from being performed with that token. 2455 o GSS_S_NO_CONTEXT indicates that no valid context was recognized 2456 for the input context_handle provided. 2458 o GSS_S_FAILURE indicates that the context is recognized, but 2459 that the GSS_Process_context_token() operation could not be 2460 performed for reasons unspecified at the GSS-API level. 2462 This call is used to process context_tokens received from a peer once 2463 a context has been established, with corresponding impact on 2464 context-level state information. One use for this facility is 2465 processing of the context_tokens generated by 2466 GSS_Delete_sec_context(); GSS_Process_context_token() will not block 2467 pending network interactions for that purpose. Another use is to 2468 process tokens indicating remote-peer context establishment failures 2469 after the point where the local GSS-API implementation has already 2470 indicated GSS_S_COMPLETE status. 2472 2.2.5: GSS_Context_time call 2473 Input: 2475 o context_handle CONTEXT HANDLE, 2477 Outputs: 2479 o major_status INTEGER, 2481 o minor_status INTEGER, 2483 o lifetime_rec INTEGER -- in seconds, or reserved value for 2484 -- INDEFINITE 2486 Return major_status codes: 2488 o GSS_S_COMPLETE indicates that the referenced context is valid, 2489 and will remain valid for the amount of time indicated in 2490 lifetime_rec. 2492 o GSS_S_CONTEXT_EXPIRED indicates that data items related to the 2493 referenced context have expired. 2495 o GSS_S_NO_CONTEXT indicates that no valid context was recognized 2496 for the input context_handle provided. 2498 o GSS_S_FAILURE indicates that the requested operation failed for 2499 reasons unspecified at the GSS-API level. 2501 This call is used to determine the amount of time for which a 2502 currently established context will remain valid. 2504 2.2.6: GSS_Inquire_context call 2506 Input: 2508 o context_handle CONTEXT HANDLE, 2510 Outputs: 2512 o major_status INTEGER, 2514 o minor_status INTEGER, 2516 o src_name INTERNAL NAME, -- name of context initiator, 2517 -- guaranteed to be MN; 2518 -- caller must release with GSS_Release_name() if returned 2520 o targ_name INTERNAL NAME, -- name of context target, 2521 -- guaranteed to be MN; 2522 -- caller must release with GSS_Release_name() if returned 2524 o lifetime_rec INTEGER -- in seconds, or reserved value for 2525 -- INDEFINITE or EXPIRED 2527 o mech_type OBJECT IDENTIFIER, -- the mechanism supporting this 2528 -- security context; caller should treat as read-only and not 2529 -- attempt to release 2531 o deleg_state BOOLEAN, 2533 o mutual_state BOOLEAN, 2535 o replay_det_state BOOLEAN, 2537 o sequence_state BOOLEAN, 2539 o anon_state BOOLEAN, 2541 o trans_state BOOLEAN, 2543 o prot_ready_state BOOLEAN, 2545 o conf_avail BOOLEAN, 2547 o integ_avail BOOLEAN, 2549 o locally_initiated BOOLEAN, -- TRUE if initiator, FALSE if acceptor 2551 o open BOOLEAN, -- TRUE if context fully established, FALSE 2552 -- if partly established (in CONTINUE_NEEDED state) 2554 Return major_status codes: 2556 o GSS_S_COMPLETE indicates that the referenced context is valid 2557 and that deleg_state, mutual_state, replay_det_state, sequence_state, 2558 anon_state, trans_state, prot_ready_state, conf_avail, 2559 integ_avail, locally_initiated, and open return values describe the 2560 corresponding characteristics of the context. If open is TRUE, 2561 lifetime_rec is also returned: if open is TRUE and the context 2562 peer's name is known, src_name and targ_name are valid in addition 2563 to the values listed above. The mech_type value must be returned 2564 for contexts where open is TRUE and may be returned for contexts 2565 where open is FALSE. 2567 o GSS_S_NO_CONTEXT indicates that no valid context was recognized 2568 for the input context_handle provided. Return values other than 2569 major_status and minor_status are undefined. 2571 o GSS_S_FAILURE indicates that the requested operation failed for 2572 reasons unspecified at the GSS-API level. Return values other than 2573 major_status and minor_status are undefined. 2575 This call is used to extract information describing characteristics 2576 of a security context. Note that GSS-API implementations are 2577 expected to retain inquirable context data on a context until the 2578 context is released by a caller, even after the context has expired, 2579 although underlying cryptographic data elements may be deleted after 2580 expiration in order to limit their exposure. 2582 2.2.7: GSS_Wrap_size_limit call 2584 Inputs: 2586 o context_handle CONTEXT HANDLE, 2588 o conf_req_flag BOOLEAN, 2590 o qop INTEGER, 2592 o output_size INTEGER 2594 Outputs: 2596 o major_status INTEGER, 2598 o minor_status INTEGER, 2600 o max_input_size INTEGER 2602 Return major_status codes: 2604 o GSS_S_COMPLETE indicates a successful token size determination: 2605 an input message with a length in octets equal to the 2606 returned max_input_size value will, when passed to GSS_Wrap() 2607 for processing on the context identified by the context_handle 2608 parameter with the confidentiality request state as provided in 2609 conf_req_flag and with the quality of protection specifier provided 2610 in the qop parameter, yield an output token no larger than the 2611 value of the provided output_size parameter. 2613 o GSS_S_CONTEXT_EXPIRED indicates that the provided input 2614 context_handle is recognized, but that the referenced context has 2615 expired. Return values other than major_status and minor_status 2616 are undefined. 2618 o GSS_S_NO_CONTEXT indicates that no valid context was recognized 2619 for the input context_handle provided. Return values other than 2620 major_status and minor_status are undefined. 2622 o GSS_S_BAD_QOP indicates that the provided QOP value is not 2623 recognized or supported for the context. 2625 o GSS_S_FAILURE indicates that the requested operation failed for 2626 reasons unspecified at the GSS-API level. Return values other than 2627 major_status and minor_status are undefined. 2629 This call is used to determine the largest input datum which may be 2630 passed to GSS_Wrap() without yielding an output token larger than a 2631 caller-specified value. 2633 2.2.8: GSS_Export_sec_context call 2635 Inputs: 2637 o context_handle CONTEXT HANDLE 2639 Outputs: 2641 o major_status INTEGER, 2643 o minor_status INTEGER, 2645 o interprocess_token OCTET STRING -- caller must release 2646 -- with GSS_Release_buffer() 2648 Return major_status codes: 2650 o GSS_S_COMPLETE indicates that the referenced context has been 2651 successfully exported to a representation in the interprocess_token, 2652 and is no longer available for use by the caller. 2654 o GSS_S_UNAVAILABLE indicates that the context export facility 2655 is not available for use on the referenced context. (This status 2656 should occur only for contexts for which the trans_state value is 2657 FALSE.) Return values other than major_status and minor_status are 2658 undefined. 2660 o GSS_S_CONTEXT_EXPIRED indicates that the provided input 2661 context_handle is recognized, but that the referenced context has 2662 expired. Return values other than major_status and minor_status 2663 are undefined. 2665 o GSS_S_NO_CONTEXT indicates that no valid context was recognized 2666 for the input context_handle provided. Return values other than 2667 major_status and minor_status are undefined. 2669 o GSS_S_FAILURE indicates that the requested operation failed for 2670 reasons unspecified at the GSS-API level. Return values other than 2671 major_status and minor_status are undefined. 2673 This call generates an interprocess token for transfer to another 2674 process within an end system, in order to transfer control of a 2675 security context to that process. The recipient of the interprocess 2676 token will call GSS_Import_sec_context() to accept the transfer. The 2677 GSS_Export_sec_context() operation is defined for use only with 2678 security contexts which are fully and successfully established (i.e., 2679 those for which GSS_Init_sec_context() and GSS_Accept_sec_context() 2680 have returned GSS_S_COMPLETE major_status). 2682 A successful GSS_Export_sec_context() operation deactivates the 2683 security context for the calling process; for this case, the GSS-API 2684 implementation shall deallocate all process-wide resources associated 2685 with the security context and shall set the context_handle to 2686 GSS_C_NO_CONTEXT. In the event of an error that makes it impossible 2687 to complete export of the security context, the GSS-API 2688 implementation must not return an interprocess token and should 2689 strive to leave the security context referenced by the context_handle 2690 untouched. If this is impossible, it is permissible for the 2691 implementation to delete the security context, provided that it also 2692 sets te context_handle parameter to GSS_C_NO_CONTEXT. 2694 Portable callers must not assume that a given interprocess token can 2695 be imported by GSS_Import_sec_context() more than once, thereby 2696 creating multiple instantiations of a single context. GSS-API 2697 implementations may detect and reject attempted multiple imports, but 2698 are not required to do so. 2700 The internal representation contained within the interprocess token 2701 is an implementation-defined local matter. Interprocess tokens 2702 cannot be assumed to be transferable across different GSS-API 2703 implementations. 2705 It is recommended that GSS-API implementations adopt policies suited 2706 to their operational environments in order to define the set of 2707 processes eligible to import a context, but specific constraints in 2708 this area are local matters. Candidate examples include transfers 2709 between processes operating on behalf of the same user identity, or 2710 processes comprising a common job. However, it may be impossible to 2711 enforce such policies in some implementations. 2713 In support of the above goals, implementations may protect the 2714 transferred context data by using cryptography to protect data within 2715 the interprocess token, or by using interprocess tokens as a means to 2716 reference local interprocess communication facilities (protected by 2717 other means) rather than storing the context data directly within the 2718 tokens. 2720 Transfer of an open context may, for certain mechanisms and 2721 implementations, reveal data about the credential which was used to 2722 establish the context. Callers should, therefore, be cautious about 2723 the trustworthiness of processes to which they transfer contexts. 2724 Although the GSS-API implementation may provide its own set of 2725 protections over the exported context, the caller is responsible for 2726 protecting the interprocess token from disclosure, and for taking 2727 care that the context is transferred to an appropriate destination 2728 process. 2730 2.2.9: GSS_Import_sec_context call 2732 Inputs: 2734 o interprocess_token OCTET STRING 2736 Outputs: 2738 o major_status INTEGER, 2740 o minor_status INTEGER, 2742 o context_handle CONTEXT HANDLE -- if successfully returned, 2743 -- caller must release with GSS_Delete_sec_context() 2745 Return major_status codes: 2747 o GSS_S_COMPLETE indicates that the context represented by the 2748 input interprocess_token has been successfully transferred to 2749 the caller, and is available for future use via the output 2750 context_handle. 2752 o GSS_S_NO_CONTEXT indicates that the context represented by the 2753 input interprocess_token was invalid. Return values other than 2754 major_status and minor_status are undefined. 2756 o GSS_S_DEFECTIVE_TOKEN indicates that the input interprocess_token 2757 was defective. Return values other than major_status and 2758 minor_status are undefined. 2760 o GSS_S_UNAVAILABLE indicates that the context import facility 2761 is not available for use on the referenced context. Return values 2762 other than major_status and minor_status are undefined. 2764 o GSS_S_UNAUTHORIZED indicates that the context represented by 2765 the input interprocess_token is unauthorized for transfer to the 2766 caller. Return values other than major_status and minor_status 2767 are undefined. 2769 o GSS_S_FAILURE indicates that the requested operation failed for 2770 reasons unspecified at the GSS-API level. Return values other than 2771 major_status and minor_status are undefined. 2773 This call processes an interprocess token generated by 2774 GSS_Export_sec_context(), making the transferred context available 2775 for use by the caller. After a successful GSS_Import_sec_context() 2776 operation, the imported context is available for use by the importing 2777 process. In particular, the imported context is usable for all per- 2778 message operations and may be deleted or exported by its importer. 2779 The inability to receive delegated credentials through 2780 gss_import_sec_context() precludes establishment of new contexts 2781 based on information delegated to the importer's end system within 2782 the context which is being imported, unless those delegated 2783 credentials are obtained through separate routines (e.g., XGSS-API 2784 calls) outside the GSS-V2 definition. 2786 For further discussion of the security and authorization issues 2787 regarding this call, please see the discussion in Section 2.2.8. 2789 2.3: Per-message calls 2791 This group of calls is used to perform per-message protection 2792 processing on an established security context. None of these calls 2793 block pending network interactions. These calls may be invoked by a 2794 context's initiator or by the context's target. The four members of 2795 this group should be considered as two pairs; the output from 2796 GSS_GetMIC() is properly input to GSS_VerifyMIC(), and the output 2797 from GSS_Wrap() is properly input to GSS_Unwrap(). 2799 GSS_GetMIC() and GSS_VerifyMIC() support data origin authentication 2800 and data integrity services. When GSS_GetMIC() is invoked on an input 2801 message, it yields a per-message token containing data items which 2802 allow underlying mechanisms to provide the specified security 2803 services. The original message, along with the generated per-message 2804 token, is passed to the remote peer; these two data elements are 2805 processed by GSS_VerifyMIC(), which validates the message in 2806 conjunction with the separate token. 2808 GSS_Wrap() and GSS_Unwrap() support caller-requested confidentiality 2809 in addition to the data origin authentication and data integrity 2810 services offered by GSS_GetMIC() and GSS_VerifyMIC(). GSS_Wrap() 2811 outputs a single data element, encapsulating optionally enciphered 2812 user data as well as associated token data items. The data element 2813 output from GSS_Wrap() is passed to the remote peer and processed by 2814 GSS_Unwrap() at that system. GSS_Unwrap() combines decipherment (as 2815 required) with validation of data items related to authentication and 2816 integrity. 2818 Although zero-length tokens are never returned by GSS calls for 2819 transfer to a context's peer, a zero-length object may be passed by a 2820 caller into GSS_Wrap(), in which case the corresponding peer calling 2821 GSS_Unwrap() on the transferred token will receive a zero-length 2822 object as output from GSS_Unwrap(). Similarly, GSS_GetMIC() can be 2823 called on an empty object, yielding a MIC which GSS_VerifyMIC() will 2824 successfully verify against the active security context in 2825 conjunction with a zero-length object. 2827 2.3.1: GSS_GetMIC call 2829 Note: This call is functionally equivalent to the GSS_Sign call as 2830 defined in previous versions of this specification. In the interests 2831 of backward compatibility, it is recommended that implementations 2832 support this function under both names for the present; future 2833 references to this function as GSS_Sign are deprecated. 2835 Inputs: 2837 o context_handle CONTEXT HANDLE, 2839 o qop_req INTEGER, -- 0 specifies default QOP 2841 o message OCTET STRING 2843 Outputs: 2845 o major_status INTEGER, 2847 o minor_status INTEGER, 2849 o per_msg_token OCTET STRING -- caller must release 2850 -- with GSS_Release_buffer() 2852 Return major_status codes: 2854 o GSS_S_COMPLETE indicates that an integrity check, suitable for an 2855 established security context, was successfully applied and 2856 that the message and corresponding per_msg_token are ready 2857 for transmission. 2859 o GSS_S_CONTEXT_EXPIRED indicates that context-related data 2860 items have expired, so that the requested operation cannot be 2861 performed. 2863 o GSS_S_NO_CONTEXT indicates that no context was recognized 2864 for the input context_handle provided. 2866 o GSS_S_BAD_QOP indicates that the provided QOP value is not 2867 recognized or supported for the context. 2869 o GSS_S_FAILURE indicates that the context is recognized, but 2870 that the requested operation could not be performed for 2871 reasons unspecified at the GSS-API level. 2873 Using the security context referenced by context_handle, apply an 2874 integrity check to the input message (along with timestamps and/or 2875 other data included in support of mech_type-specific mechanisms) and 2876 (if GSS_S_COMPLETE status is indicated) return the result in 2877 per_msg_token. The qop_req parameter, interpretation of which is 2878 discussed in Section 1.2.4, allows quality-of-protection control. The 2879 caller passes the message and the per_msg_token to the target. 2881 The GSS_GetMIC() function completes before the message and 2882 per_msg_token is sent to the peer; successful application of 2883 GSS_GetMIC() does not guarantee that a corresponding GSS_VerifyMIC() 2884 has been (or can necessarily be) performed successfully when the 2885 message arrives at the destination. 2887 Mechanisms which do not support per-message protection services 2888 should return GSS_S_FAILURE if this routine is called. 2890 2.3.2: GSS_VerifyMIC call 2892 Note: This call is functionally equivalent to the GSS_Verify call as 2893 defined in previous versions of this specification. In the interests 2894 of backward compatibility, it is recommended that implementations 2895 support this function under both names for the present; future 2896 references to this function as GSS_Verify are deprecated. 2898 Inputs: 2900 o context_handle CONTEXT HANDLE, 2902 o message OCTET STRING, 2904 o per_msg_token OCTET STRING 2905 Outputs: 2907 o qop_state INTEGER, 2909 o major_status INTEGER, 2911 o minor_status INTEGER, 2913 Return major_status codes: 2915 o GSS_S_COMPLETE indicates that the message was successfully 2916 verified. 2918 o GSS_S_DEFECTIVE_TOKEN indicates that consistency checks performed 2919 on the received per_msg_token failed, preventing 2920 further processing from being performed with that token. 2922 o GSS_S_BAD_SIG (GSS_S_BAD_MIC) indicates that the received 2923 per_msg_token contains an incorrect integrity check for the 2924 message. 2926 o GSS_S_DUPLICATE_TOKEN, GSS_S_OLD_TOKEN, GSS_S_UNSEQ_TOKEN, 2927 and GSS_S_GAP_TOKEN values appear in conjunction with the 2928 optional per-message replay detection features described 2929 in Section 1.2.3; their semantics are described in that section. 2931 o GSS_S_CONTEXT_EXPIRED indicates that context-related data 2932 items have expired, so that the requested operation cannot be 2933 performed. 2935 o GSS_S_NO_CONTEXT indicates that no context was recognized 2936 for the input context_handle provided. 2938 o GSS_S_FAILURE indicates that the context is recognized, but 2939 that the GSS_VerifyMIC() operation could not be performed for 2940 reasons unspecified at the GSS-API level. 2942 Using the security context referenced by context_handle, verify that 2943 the input per_msg_token contains an appropriate integrity check for 2944 the input message, and apply any active replay detection or 2945 sequencing features. Returns an indication of the quality-of- 2946 protection applied to the processed message in the qop_state result. 2948 Mechanisms which do not support per-message protection services 2949 should return GSS_S_FAILURE if this routine is called. 2951 2.3.3: GSS_Wrap call 2952 Note: This call is functionally equivalent to the GSS_Seal call as 2953 defined in previous versions of this specification. In the interests 2954 of backward compatibility, it is recommended that implementations 2955 support this function under both names for the present; future 2956 references to this function as GSS_Seal are deprecated. 2958 Inputs: 2960 o context_handle CONTEXT HANDLE, 2962 o conf_req_flag BOOLEAN, 2964 o qop_req INTEGER, -- 0 specifies default QOP 2966 o input_message OCTET STRING 2968 Outputs: 2970 o major_status INTEGER, 2972 o minor_status INTEGER, 2974 o conf_state BOOLEAN, 2976 o output_message OCTET STRING -- caller must release with 2977 -- GSS_Release_buffer() 2979 Return major_status codes: 2981 o GSS_S_COMPLETE indicates that the input_message was successfully 2982 processed and that the output_message is ready for 2983 transmission. 2985 o GSS_S_CONTEXT_EXPIRED indicates that context-related data 2986 items have expired, so that the requested operation cannot be 2987 performed. 2989 o GSS_S_NO_CONTEXT indicates that no context was recognized 2990 for the input context_handle provided. 2992 o GSS_S_BAD_QOP indicates that the provided QOP value is not 2993 recognized or supported for the context. 2995 o GSS_S_FAILURE indicates that the context is recognized, but 2996 that the GSS_Wrap() operation could not be performed for 2997 reasons unspecified at the GSS-API level. 2999 Performs the data origin authentication and data integrity functions 3000 of GSS_GetMIC(). If the input conf_req_flag is TRUE, requests that 3001 confidentiality be applied to the input_message. Confidentiality may 3002 not be supported in all mech_types or by all implementations; the 3003 returned conf_state flag indicates whether confidentiality was 3004 provided for the input_message. The qop_req parameter, interpretation 3005 of which is discussed in Section 1.2.4, allows quality-of-protection 3006 control. 3008 When GSS_S_COMPLETE status is returned, the GSS_Wrap() call yields a 3009 single output_message data element containing (optionally enciphered) 3010 user data as well as control information. 3012 Mechanisms which do not support per-message protection services 3013 should return GSS_S_FAILURE if this routine is called. 3015 2.3.4: GSS_Unwrap call 3017 Note: This call is functionally equivalent to the GSS_Unseal call as 3018 defined in previous versions of this specification. In the interests 3019 of backward compatibility, it is recommended that implementations 3020 support this function under both names for the present; future 3021 references to this function as GSS_Unseal are deprecated. 3023 Inputs: 3025 o context_handle CONTEXT HANDLE, 3027 o input_message OCTET STRING 3029 Outputs: 3031 o conf_state BOOLEAN, 3033 o qop_state INTEGER, 3035 o major_status INTEGER, 3037 o minor_status INTEGER, 3039 o output_message OCTET STRING -- caller must release with 3040 -- GSS_Release_buffer() 3042 Return major_status codes: 3044 o GSS_S_COMPLETE indicates that the input_message was 3045 successfully processed and that the resulting output_message is 3046 available. 3048 o GSS_S_DEFECTIVE_TOKEN indicates that consistency checks performed 3049 on the per_msg_token extracted from the input_message 3050 failed, preventing further processing from being performed. 3052 o GSS_S_BAD_SIG (GSS_S_BAD_MIC) indicates that an incorrect 3053 integrity check was detected for the message. 3055 o GSS_S_DUPLICATE_TOKEN, GSS_S_OLD_TOKEN, GSS_S_UNSEQ_TOKEN, 3056 and GSS_S_GAP_TOKEN values appear in conjunction with the 3057 optional per-message replay detection features described 3058 in Section 1.2.3; their semantics are described in that section. 3060 o GSS_S_CONTEXT_EXPIRED indicates that context-related data 3061 items have expired, so that the requested operation cannot be 3062 performed. 3064 o GSS_S_NO_CONTEXT indicates that no context was recognized 3065 for the input context_handle provided. 3067 o GSS_S_FAILURE indicates that the context is recognized, but 3068 that the GSS_Unwrap() operation could not be performed for 3069 reasons unspecified at the GSS-API level. 3071 Processes a data element generated (and optionally enciphered) by 3072 GSS_Wrap(), provided as input_message. The returned conf_state value 3073 indicates whether confidentiality was applied to the input_message. 3074 If conf_state is TRUE, GSS_Unwrap() has deciphered the input_message. 3075 Returns an indication of the quality-of-protection applied to the 3076 processed message in the qop_state result. GSS_Unwrap() performs the 3077 data integrity and data origin authentication checking functions of 3078 GSS_VerifyMIC() on the plaintext data. Plaintext data is returned in 3079 output_message. 3081 Mechanisms which do not support per-message protection services 3082 should return GSS_S_FAILURE if this routine is called. 3084 2.4: Support calls 3086 This group of calls provides support functions useful to GSS-API 3087 callers, independent of the state of established contexts. Their 3088 characterization with regard to blocking or non-blocking status in 3089 terms of network interactions is unspecified. 3091 2.4.1: GSS_Display_status call 3093 Inputs: 3095 o status_value INTEGER, -- GSS-API major_status or minor_status 3096 -- return value 3098 o status_type INTEGER, -- 1 if major_status, 2 if minor_status 3100 o mech_type OBJECT IDENTIFIER -- mech_type to be used for 3101 -- minor_status translation 3103 Outputs: 3105 o major_status INTEGER, 3107 o minor_status INTEGER, 3109 o status_string_set SET OF OCTET STRING -- required calls for 3110 -- release by caller are specific to language bindings 3112 Return major_status codes: 3114 o GSS_S_COMPLETE indicates that a valid printable status 3115 representation (possibly representing more than one status event 3116 encoded within the status_value) is available in the returned 3117 status_string_set. 3119 o GSS_S_BAD_MECH indicates that translation in accordance with an 3120 unsupported mech_type was requested, so translation could not 3121 be performed. 3123 o GSS_S_BAD_STATUS indicates that the input status_value was 3124 invalid, or that the input status_type carried a value other 3125 than 1 or 2, so translation could not be performed. 3127 o GSS_S_FAILURE indicates that the requested operation could not 3128 be performed for reasons unspecified at the GSS-API level. 3130 Provides a means for callers to translate GSS-API-returned major and 3131 minor status codes into printable string representations. Note: some 3132 language bindings may employ an iterative approach in order to emit 3133 successive status components; this approach is acceptable but not 3134 required for conformance with the current specification. 3136 Although not contemplated in [RFC-2078], it has been observed that 3137 some existing GSS-API implementations return GSS_S_CONTINUE_NEEDED 3138 status when iterating through successive messages returned from 3139 GSS_Display_status(). This behavior is deprecated; 3140 GSS_S_CONTINUE_NEEDED should be returned only by 3141 GSS_Init_sec_context() and GSS_Accept_sec_context(). For maximal 3142 portability, however, it is recommended that defensive callers be 3143 able to accept and ignore GSS_S_CONTINUE_NEEDED status if indicated 3144 by GSS_Display_status() or any other call other than 3145 GSS_Init_sec_context() or GSS_Accept_sec_context(). 3147 2.4.2: GSS_Indicate_mechs call 3149 Input: 3151 o (none) 3153 Outputs: 3155 o major_status INTEGER, 3157 o minor_status INTEGER, 3159 o mech_set SET OF OBJECT IDENTIFIER -- caller must release 3160 -- with GSS_Release_oid_set() 3162 Return major_status codes: 3164 o GSS_S_COMPLETE indicates that a set of available mechanisms has 3165 been returned in mech_set. 3167 o GSS_S_FAILURE indicates that the requested operation could not 3168 be performed for reasons unspecified at the GSS-API level. 3170 Allows callers to determine the set of mechanism types available on 3171 the local system. This call is intended for support of specialized 3172 callers who need to request non-default mech_type sets from GSS-API 3173 calls which accept input mechanism type specifiers. 3175 2.4.3: GSS_Compare_name call 3177 Inputs: 3179 o name1 INTERNAL NAME, 3181 o name2 INTERNAL NAME 3183 Outputs: 3185 o major_status INTEGER, 3187 o minor_status INTEGER, 3189 o name_equal BOOLEAN 3191 Return major_status codes: 3193 o GSS_S_COMPLETE indicates that name1 and name2 were comparable, 3194 and that the name_equal result indicates whether name1 and 3195 name2 represent the same entity. 3197 o GSS_S_BAD_NAMETYPE indicates that 3198 the two input names' types are different and incomparable, so that 3199 the comparison operation could not be completed. 3201 o GSS_S_BAD_NAME indicates that one or both of the input names 3202 was ill-formed in terms of its internal type specifier, so 3203 the comparison operation could not be completed. 3205 o GSS_S_FAILURE indicates that the call's operation could not 3206 be performed for reasons unspecified at the GSS-API level. 3208 Allows callers to compare two internal name representations to 3209 determine whether they refer to the same entity. If either name 3210 presented to GSS_Compare_name() denotes an anonymous principal, 3211 GSS_Compare_name() shall indicate FALSE. It is not required that 3212 either or both inputs name1 and name2 be MNs; for some 3213 implementations and cases, GSS_S_BAD_NAMETYPE may be returned, 3214 indicating name incomparability, for the case where neither input 3215 name is an MN. 3217 2.4.4: GSS_Display_name call 3219 Inputs: 3221 o name INTERNAL NAME 3223 Outputs: 3225 o major_status INTEGER, 3227 o minor_status INTEGER, 3229 o name_string OCTET STRING, -- caller must release 3230 -- with GSS_Release_buffer() 3232 o name_type OBJECT IDENTIFIER -- caller should treat 3233 -- as read-only; does not need to be released 3235 Return major_status codes: 3237 o GSS_S_COMPLETE indicates that a valid printable name 3238 representation is available in the returned name_string. 3240 o GSS_S_BAD_NAME indicates that the contents of the provided name 3241 were inconsistent with the internally-indicated name type, so 3242 no printable representation could be generated. 3244 o GSS_S_FAILURE indicates that the requested operation could not 3245 be performed for reasons unspecified at the GSS-API level. 3247 Allows callers to translate an internal name representation into a 3248 printable form with associated namespace type descriptor. The syntax 3249 of the printable form is a local matter. 3251 If the input name represents an anonymous identity, a reserved value 3252 (GSS_C_NT_ANONYMOUS) shall be returned for name_type. 3254 The GSS_C_NO_OID name type is to be returned only when the 3255 corresponding internal name was created through import with 3256 GSS_C_NO_OID. It is acceptable for mechanisms to normalize names 3257 imported with GSS_C_NO_OID into other supported types and, therefore, 3258 to display them with types other than GSS_C_NO_OID. 3260 2.4.5: GSS_Import_name call 3262 Inputs: 3264 o input_name_string OCTET STRING, 3266 o input_name_type OBJECT IDENTIFIER 3268 Outputs: 3270 o major_status INTEGER, 3272 o minor_status INTEGER, 3274 o output_name INTERNAL NAME -- caller must release with 3275 -- GSS_Release_name() 3277 Return major_status codes: 3279 o GSS_S_COMPLETE indicates that a valid name representation is 3280 output in output_name and described by the type value in 3281 output_name_type. 3283 o GSS_S_BAD_NAMETYPE indicates that the input_name_type is 3284 unsupported by the applicable underlying GSS-API mechanism(s), 3285 so the import operation could not be completed. 3287 o GSS_S_BAD_NAME indicates that the provided input_name_string 3288 is ill-formed in terms of the input_name_type, so the import 3289 operation could not be completed. 3291 o GSS_S_BAD_MECH indicates that the input presented for import was 3292 an exported name object and that its enclosed mechanism type was not 3293 recognized or was unsupported by the GSS-API implementation. 3295 o GSS_S_FAILURE indicates that the requested operation could not 3296 be performed for reasons unspecified at the GSS-API level. 3298 Allows callers to provide a name representation as a contiguous octet 3299 string, designate the type of namespace in conjunction with which it 3300 should be parsed, and convert that representation to an internal form 3301 suitable for input to other GSS-API routines. The syntax of the 3302 input_name_string is defined in conjunction with its associated name 3303 type; depending on the input_name_type, the associated 3304 input_name_string may or may not be a printable string. If the 3305 input_name_type's value is GSS_C_NO_OID, a mechanism-specific default 3306 printable syntax (which shall be specified in the corresponding GSS- 3307 V2 mechanism specification) is assumed for the input_name_string; 3308 other input_name_type values as registered by GSS-API implementations 3309 can be used to indicate specific non-default name syntaxes. Note: The 3310 input_name_type argument serves to describe and qualify the 3311 interpretation of the associated input_name_string; it does not 3312 specify the data type of the returned output_name. 3314 If a mechanism claims support for a particular name type, its 3315 GSS_Import_name() operation shall be able to accept all possible 3316 values conformant to the external name syntax as defined for that 3317 name type. These imported values may correspond to: 3319 (1) locally registered entities (for which credentials may be 3320 acquired), 3322 (2) non-local entities (for which local credentials cannot be 3323 acquired, but which may be referenced as targets of initiated 3324 security contexts or initiators of accepted security contexts), 3325 or to 3327 (3) neither of the above. 3329 Determination of whether a particular name belongs to class (1), (2), 3330 or (3) as described above is not guaranteed to be performed by the 3331 GSS_Import_name() function. 3333 The internal name generated by a GSS_Import_name() operation may be a 3334 single-mechanism MN, and is likely to be an MN within a single- 3335 mechanism implementation, but portable callers must not depend on 3336 this property (and must not, therefore, assume that the output from 3337 GSS_Import_name() can be passed directly to GSS_Export_name() without 3338 first being processed through GSS_Canonicalize_name()). 3340 2.4.6: GSS_Release_name call 3342 Inputs: 3344 o name INTERNAL NAME 3346 Outputs: 3348 o major_status INTEGER, 3350 o minor_status INTEGER 3352 Return major_status codes: 3354 o GSS_S_COMPLETE indicates that the storage associated with the 3355 input name was successfully released. 3357 o GSS_S_BAD_NAME indicates that the input name argument did not 3358 contain a valid name. 3360 o GSS_S_FAILURE indicates that the requested operation could not 3361 be performed for reasons unspecified at the GSS-API level. 3363 Allows callers to release the storage associated with an internal 3364 name representation. This call's specific behavior depends on the 3365 language and programming environment within which a GSS-API 3366 implementation operates, and is therefore detailed within applicable 3367 bindings specifications; in particular, implementation and invocation 3368 of this call may be superfluous (and may be omitted) within bindings 3369 where memory management is automatic. 3371 2.4.7: GSS_Release_buffer call 3373 Inputs: 3375 o buffer OCTET STRING 3377 Outputs: 3379 o major_status INTEGER, 3381 o minor_status INTEGER 3383 Return major_status codes: 3385 o GSS_S_COMPLETE indicates that the storage associated with the 3386 input buffer was successfully released. 3388 o GSS_S_FAILURE indicates that the requested operation could not 3389 be performed for reasons unspecified at the GSS-API level. 3391 Allows callers to release the storage associated with an OCTET STRING 3392 buffer allocated by another GSS-API call. This call's specific 3393 behavior depends on the language and programming environment within 3394 which a GSS-API implementation operates, and is therefore detailed 3395 within applicable bindings specifications; in particular, 3396 implementation and invocation of this call may be superfluous (and 3397 may be omitted) within bindings where memory management is automatic. 3399 2.4.8: GSS_Release_OID_set call 3401 Inputs: 3403 o buffer SET OF OBJECT IDENTIFIER 3405 Outputs: 3407 o major_status INTEGER, 3409 o minor_status INTEGER 3411 Return major_status codes: 3413 o GSS_S_COMPLETE indicates that the storage associated with the 3414 input object identifier set was successfully released. 3416 o GSS_S_FAILURE indicates that the requested operation could not 3417 be performed for reasons unspecified at the GSS-API level. 3419 Allows callers to release the storage associated with an object 3420 identifier set object allocated by another GSS-API call. This call's 3421 specific behavior depends on the language and programming environment 3422 within which a GSS-API implementation operates, and is therefore 3423 detailed within applicable bindings specifications; in particular, 3424 implementation and invocation of this call may be superfluous (and 3425 may be omitted) within bindings where memory management is automatic. 3427 2.4.9: GSS_Create_empty_OID_set call 3429 Inputs: 3431 o (none) 3432 Outputs: 3434 o major_status INTEGER, 3436 o minor_status INTEGER, 3438 o oid_set SET OF OBJECT IDENTIFIER -- caller must release 3439 -- with GSS_Release_oid_set() 3441 Return major_status codes: 3443 o GSS_S_COMPLETE indicates successful completion 3445 o GSS_S_FAILURE indicates that the operation failed 3447 Creates an object identifier set containing no object identifiers, to 3448 which members may be subsequently added using the 3449 GSS_Add_OID_set_member() routine. These routines are intended to be 3450 used to construct sets of mechanism object identifiers, for input to 3451 GSS_Acquire_cred(). 3453 2.4.10: GSS_Add_OID_set_member call 3455 Inputs: 3457 o member_oid OBJECT IDENTIFIER, 3459 o oid_set SET OF OBJECT IDENTIFIER 3461 Outputs: 3463 o major_status INTEGER, 3465 o minor_status INTEGER, 3467 Return major_status codes: 3469 o GSS_S_COMPLETE indicates successful completion 3471 o GSS_S_FAILURE indicates that the operation failed 3473 Adds an Object Identifier to an Object Identifier set. This routine 3474 is intended for use in conjunction with GSS_Create_empty_OID_set() 3475 when constructing a set of mechanism OIDs for input to 3476 GSS_Acquire_cred(). 3478 2.4.11: GSS_Test_OID_set_member call 3480 Inputs: 3482 o member OBJECT IDENTIFIER, 3484 o set SET OF OBJECT IDENTIFIER 3486 Outputs: 3488 o major_status INTEGER, 3490 o minor_status INTEGER, 3492 o present BOOLEAN 3494 Return major_status codes: 3496 o GSS_S_COMPLETE indicates successful completion 3498 o GSS_S_FAILURE indicates that the operation failed 3500 Interrogates an Object Identifier set to determine whether a 3501 specified Object Identifier is a member. This routine is intended to 3502 be used with OID sets returned by GSS_Indicate_mechs(), 3503 GSS_Acquire_cred(), and GSS_Inquire_cred(). 3505 2.4.12: GSS_Inquire_names_for_mech call 3507 Input: 3509 o input_mech_type OBJECT IDENTIFIER, -- mechanism type 3511 Outputs: 3513 o major_status INTEGER, 3515 o minor_status INTEGER, 3517 o name_type_set SET OF OBJECT IDENTIFIER -- caller must release 3518 -- with GSS_Release_oid_set() 3520 Return major_status codes: 3522 o GSS_S_COMPLETE indicates that the output name_type_set contains 3523 a list of name types which are supported by the locally available 3524 mechanism identified by input_mech_type. 3526 o GSS_S_BAD_MECH indicates that the mechanism identified by 3527 input_mech_type was unsupported within the local implementation, 3528 causing the query to fail. 3530 o GSS_S_FAILURE indicates that the requested operation could not 3531 be performed for reasons unspecified at the GSS-API level. 3533 Allows callers to determine the set of name types which are 3534 supportable by a specific locally-available mechanism. 3536 2.4.13: GSS_Inquire_mechs_for_name call 3538 Inputs: 3540 o input_name INTERNAL NAME, 3542 Outputs: 3544 o major_status INTEGER, 3546 o minor_status INTEGER, 3548 o mech_types SET OF OBJECT IDENTIFIER -- caller must release 3549 -- with GSS_Release_oid_set() 3551 Return major_status codes: 3553 o GSS_S_COMPLETE indicates that a set of object identifiers, 3554 corresponding to the set of mechanisms suitable for processing 3555 the input_name, is available in mech_types. 3557 o GSS_S_BAD_NAME indicates that the input_name was ill-formed 3558 and could not be processed. 3560 o GSS_S_BAD_NAMETYPE indicates that the input_name parameter 3561 contained an invalid name type or a name type unsupported 3562 by the GSS-API implementation. 3564 o GSS_S_FAILURE indicates that the requested operation could not 3565 be performed for reasons unspecified at the GSS-API level. 3567 This routine returns the mechanism set with which the input_name may 3568 be processed. 3570 Each mechanism returned will recognize at least one element within 3571 the name. It is permissible for this routine to be implemented within 3572 a mechanism-independent GSS-API layer, using the type information 3573 contained within the presented name, and based on registration 3574 information provided by individual mechanism implementations. This 3575 means that the returned mech_types result may indicate that a 3576 particular mechanism will understand a particular name when in fact 3577 it would refuse to accept that name as input to 3578 GSS_Canonicalize_name(), GSS_Init_sec_context(), GSS_Acquire_cred(), 3579 or GSS_Add_cred(), due to some property of the particular name rather 3580 than a property of the name type. Thus, this routine should be used 3581 only as a pre-filter for a call to a subsequent mechanism-specific 3582 routine. 3584 2.4.14: GSS_Canonicalize_name call 3586 Inputs: 3588 o input_name INTERNAL NAME, 3590 o mech_type OBJECT IDENTIFIER -- must be explicit mechanism, 3591 -- not "default" specifier or identifier of negotiating mechanism 3593 Outputs: 3595 o major_status INTEGER, 3597 o minor_status INTEGER, 3599 o output_name INTERNAL NAME -- caller must release with 3600 -- GSS_Release_name() 3602 Return major_status codes: 3604 o GSS_S_COMPLETE indicates that a mechanism-specific reduction of 3605 the input_name, as processed by the mechanism identified by 3606 mech_type, is available in output_name. 3608 o GSS_S_BAD_MECH indicates that the identified mechanism is 3609 unsupported for this operation; this may correspond either to 3610 a mechanism wholly unsupported by the local GSS-API implementation 3611 or to a negotiating mechanism with which the canonicalization 3612 operation cannot be performed. 3614 o GSS_S_BAD_NAMETYPE indicates that the input name does not 3615 contain an element with suitable type for processing by the 3616 identified mechanism. 3618 o GSS_S_BAD_NAME indicates that the input name contains an 3619 element with suitable type for processing by the identified 3620 mechanism, but that this element could not be processed 3621 successfully. 3623 o GSS_S_FAILURE indicates that the requested operation could not 3624 be performed for reasons unspecified at the GSS-API level. 3626 This routine reduces a GSS-API internal name input_name, which may in 3627 general contain elements corresponding to multiple mechanisms, to a 3628 mechanism-specific Mechanism Name (MN) output_name by applying the 3629 translations corresponding to the mechanism identified by mech_type. 3630 The contents of input_name are unaffected by the 3631 GSS_Canonicalize_name() operation. References to output_name will 3632 remain valid until output_name is released, independent of whether or 3633 not input_name is subsequently released. 3635 2.4.15: GSS_Export_name call 3637 Inputs: 3639 o input_name INTERNAL NAME, -- required to be MN 3641 Outputs: 3643 o major_status INTEGER, 3645 o minor_status INTEGER, 3647 o output_name OCTET STRING -- caller must release 3648 -- with GSS_Release_buffer() 3650 Return major_status codes: 3652 o GSS_S_COMPLETE indicates that a flat representation of the 3653 input name is available in output_name. 3655 o GSS_S_NAME_NOT_MN indicates that the input name contained 3656 elements corresponding to multiple mechanisms, so cannot 3657 be exported into a single-mechanism flat form. 3659 o GSS_S_BAD_NAME indicates that the input name was an MN, 3660 but could not be processed. 3662 o GSS_S_BAD_NAMETYPE indicates that the input name was an MN, 3663 but that its type is unsupported by the GSS-API implementation. 3665 o GSS_S_FAILURE indicates that the requested operation could not 3666 be performed for reasons unspecified at the GSS-API level. 3668 This routine creates a flat name representation, suitable for 3669 bytewise comparison or for input to GSS_Import_name() in conjunction 3670 with the reserved GSS-API Exported Name Object OID, from a internal- 3671 form Mechanism Name (MN) as emitted, e.g., by GSS_Canonicalize_name() 3672 or GSS_Accept_sec_context(). 3674 The emitted GSS-API Exported Name Object is self-describing; no 3675 associated parameter-level OID need be emitted by this call. This 3676 flat representation consists of a mechanism-independent wrapper 3677 layer, defined in Section 3.2 of this document, enclosing a 3678 mechanism-defined name representation. 3680 In all cases, the flat name output by GSS_Export_name() to correspond 3681 to a particular input MN must be invariant over time within a 3682 particular installation. 3684 The GSS_S_NAME_NOT_MN status code is provided to enable 3685 implementations to reject input names which are not MNs. It is not, 3686 however, required for purposes of conformance to this specification 3687 that all non-MN input names must necessarily be rejected. 3689 2.4.16: GSS_Duplicate_name call 3691 Inputs: 3693 o src_name INTERNAL NAME 3695 Outputs: 3697 o major_status INTEGER, 3699 o minor_status INTEGER, 3701 o dest_name INTERNAL NAME -- caller must release 3702 -- with GSS_Release_name() 3704 Return major_status codes: 3706 o GSS_S_COMPLETE indicates that dest_name references an internal 3707 name object containing the same name as passed to src_name. 3709 o GSS_S_BAD_NAME indicates that the input name was invalid. 3711 o GSS_S_FAILURE indicates that the requested operation could not 3712 be performed for reasons unspecified at the GSS-API level. 3714 This routine takes input internal name src_name, and returns another 3715 reference (dest_name) to that name which can be used even if src_name 3716 is later freed. (Note: This may be implemented by copying or through 3717 use of reference counts.) 3719 3: Data Structure Definitions for GSS-V2 Usage 3721 Subsections of this section define, for interoperability and 3722 portability purposes, certain data structures for use with GSS-V2. 3724 3.1: Mechanism-Independent Token Format 3726 This section specifies a mechanism-independent level of encapsulating 3727 representation for the initial token of a GSS-API context 3728 establishment sequence, incorporating an identifier of the mechanism 3729 type to be used on that context and enabling tokens to be interpreted 3730 unambiguously at GSS-API peers. Use of this format is required for 3731 initial context establishment tokens of Internet standards-track 3732 GSS-API mechanisms; use in non-initial tokens is optional. 3734 The encoding format for the token tag is derived from ASN.1 and DER 3735 (per illustrative ASN.1 syntax included later within this 3736 subsection), but its concrete representation is defined directly in 3737 terms of octets rather than at the ASN.1 level in order to facilitate 3738 interoperable implementation without use of general ASN.1 processing 3739 code. The token tag consists of the following elements, in order: 3741 1. 0x60 -- Tag for [APPLICATION 0] SEQUENCE; indicates that 3742 -- constructed form, definite length encoding follows. 3744 2. Token length octets, specifying length of subsequent data 3745 (i.e., the summed lengths of elements 3-5 in this list, and of 3746 the mechanism-defined token object following the tag). 3747 This element comprises a variable number of octets: 3749 2a. If the indicated value is less than 128, it shall be 3750 represented in a single octet with bit 8 (high order) 3751 set to "0" and the remaining bits representing the value. 3753 2b. If the indicated value is 128 or more, it shall be 3754 represented in two or more octets, with bit 8 of the first 3755 octet set to "1" and the remaining bits of the first octet 3756 specifying the number of additional octets. The subsequent 3757 octets carry the value, 8 bits per octet, most significant 3758 digit first. The minimum number of octets shall be used to 3759 encode the length (i.e., no octets representing leading zeros 3760 shall be included within the length encoding). 3762 3. 0x06 -- Tag for OBJECT IDENTIFIER 3764 4. Object identifier length -- length (number of octets) of 3765 -- the encoded object identifier contained in element 5, 3766 -- encoded per rules as described in 2a. and 2b. above. 3768 5. Object identifier octets -- variable number of octets, 3769 -- encoded per ASN.1 BER rules: 3771 5a. The first octet contains the sum of two values: (1) the 3772 top-level object identifier component, multiplied by 40 3773 (decimal), and (2) the second-level object identifier 3774 component. This special case is the only point within an 3775 object identifier encoding where a single octet represents 3776 contents of more than one component. 3778 5b. Subsequent octets, if required, encode successively-lower 3779 components in the represented object identifier. A component's 3780 encoding may span multiple octets, encoding 7 bits per octet 3781 (most significant bits first) and with bit 8 set to "1" on 3782 all but the final octet in the component's encoding. The 3783 minimum number of octets shall be used to encode each component 3784 (i.e., no octets representing leading zeros shall be included 3785 within a component's encoding). 3787 (Note: In many implementations, elements 3-5 may be stored and 3788 referenced as a contiguous string constant.) 3790 The token tag is immediately followed by a mechanism-defined token 3791 object. Note that no independent size specifier intervenes following 3792 the object identifier value to indicate the size of the mechanism- 3793 defined token object. While ASN.1 usage within mechanism-defined 3794 tokens is permitted, there is no requirement that the mechanism- 3795 specific innerContextToken, innerMsgToken, and sealedUserData data 3796 elements must employ ASN.1 BER/DER encoding conventions. 3798 The following ASN.1 syntax is included for descriptive purposes only, 3799 to illustrate structural relationships among token and tag objects. 3800 For interoperability purposes, token and tag encoding shall be 3801 performed using the concrete encoding procedures described earlier in 3802 this subsection. 3804 GSS-API DEFINITIONS ::= 3806 BEGIN 3808 MechType ::= OBJECT IDENTIFIER 3809 -- data structure definitions 3810 -- callers must be able to distinguish among 3811 -- InitialContextToken, SubsequentContextToken, 3812 -- PerMsgToken, and SealedMessage data elements 3813 -- based on the usage in which they occur 3815 InitialContextToken ::= 3816 -- option indication (delegation, etc.) indicated within 3817 -- mechanism-specific token 3818 [APPLICATION 0] IMPLICIT SEQUENCE { 3819 thisMech MechType, 3820 innerContextToken ANY DEFINED BY thisMech 3821 -- contents mechanism-specific 3822 -- ASN.1 structure not required 3823 } 3825 SubsequentContextToken ::= innerContextToken ANY 3826 -- interpretation based on predecessor InitialContextToken 3827 -- ASN.1 structure not required 3829 PerMsgToken ::= 3830 -- as emitted by GSS_GetMIC and processed by GSS_VerifyMIC 3831 -- ASN.1 structure not required 3832 innerMsgToken ANY 3834 SealedMessage ::= 3835 -- as emitted by GSS_Wrap and processed by GSS_Unwrap 3836 -- includes internal, mechanism-defined indicator 3837 -- of whether or not encrypted 3838 -- ASN.1 structure not required 3839 sealedUserData ANY 3841 END 3843 3.2: Mechanism-Independent Exported Name Object Format 3845 This section specifies a mechanism-independent level of encapsulating 3846 representation for names exported via the GSS_Export_name() call, 3847 including an object identifier representing the exporting mechanism. 3848 The format of names encapsulated via this representation shall be 3849 defined within individual mechanism drafts. The Object Identifier 3850 value to indicate names of this type is defined in Section 4.7 of 3851 this document. 3853 No name type OID is included in this mechanism-independent level of 3854 format definition, since (depending on individual mechanism 3855 specifications) the enclosed name may be implicitly typed or may be 3856 explicitly typed using a means other than OID encoding. 3858 The bytes within MECH_OID_LEN and NAME_LEN elements are represented 3859 most significant byte first (equivalently, in IP network byte order). 3861 Length Name Description 3863 2 TOK_ID Token Identifier 3864 For exported name objects, this 3865 must be hex 04 01. 3866 2 MECH_OID_LEN Length of the Mechanism OID 3867 MECH_OID_LEN MECH_OID Mechanism OID, in DER 3868 4 NAME_LEN Length of name 3869 NAME_LEN NAME Exported name; format defined in 3870 applicable mechanism draft. 3872 A concrete example of the contents of an exported name object, 3873 derived from the Kerberos Version 5 mechanism, is as follows: 3875 04 01 00 0B 06 09 2A 86 48 86 F7 12 01 02 02 hx xx xx xl pp qq ... zz 3877 04 01 mandatory token identifier 3879 00 0B 2-byte length of the immediately following DER-encoded 3880 ASN.1 value of type OID, most significant octet first 3882 06 09 2A 86 48 86 F7 12 01 02 02 DER-encoded ASN.1 value 3883 of type OID; Kerberos V5 3884 mechanism OID indicates 3885 Kerberos V5 exported name 3887 in Detail: 06 Identifier octet (6=OID) 3888 09 Length octet(s) 3889 2A 86 48 86 F7 12 01 02 02 Content octet(s) 3891 hx xx xx xl 4-byte length of the immediately following exported 3892 name blob, most significant octet first 3894 pp qq ... zz exported name blob of specified length, 3895 bits and bytes specified in the 3896 (Kerberos 5) GSS-API v2 mechanism spec 3898 4: Name Type Definitions 3900 This section includes definitions for name types and associated 3901 syntaxes which are defined in a mechanism-independent fashion at the 3902 GSS-API level rather than being defined in individual mechanism 3903 specifications. 3905 4.1: Host-Based Service Name Form 3906 This name form shall be represented by the Object Identifier: 3908 {iso(1) member-body(2) United States(840) mit(113554) infosys(1) 3909 "gssapi(2) generic(1) service_name(4)}. 3911 The recommended symbolic name for this type is 3912 "GSS_C_NT_HOSTBASED_SERVICE". 3914 For reasons of compatibility with existing implementations, it is 3915 recommended that this OID be used rather than the alternate value as 3916 included in [RFC-2078]: 3918 {1(iso), 3(org), 6(dod), 1(internet), 5(security), 6(nametypes), 3919 2(gss-host-based-services)} 3921 While it is not recommended that this alternate value be emitted on 3922 output by GSS implementations, it is recommended that it be accepted 3923 on input as equivalent to the recommended value. 3925 This name type is used to represent services associated with host 3926 computers. Support for this name form is recommended to mechanism 3927 designers in the interests of portability, but is not mandated by 3928 this specification. This name form is constructed using two elements, 3929 "service" and "hostname", as follows: 3931 service@hostname 3933 When a reference to a name of this type is resolved, the "hostname" 3934 may (as an example implementation strategy) be canonicalized by 3935 attempting a DNS lookup and using the fully-qualified domain name 3936 which is returned, or by using the "hostname" as provided if the DNS 3937 lookup fails. The canonicalization operation also maps the host's 3938 name into lower-case characters. 3940 The "hostname" element may be omitted. If no "@" separator is 3941 included, the entire name is interpreted as the service specifier, 3942 with the "hostname" defaulted to the canonicalized name of the local 3943 host. 3945 Documents specifying means for GSS integration into a particular 3946 protocol should state either: 3948 (a) that a specific IANA-registered name associated with that 3949 protocol shall be used for the "service" element (this admits, if 3950 needed, the possibility that a single name can be registered and 3951 shared among a related set of protocols), or 3953 (b) that the generic name "host" shall be used for the "service" 3954 element, or 3956 (c) that, for that protocol, fallback in specified order (a, then 3957 b) or (b, then a) shall be applied. 3959 IANA registration of specific names per (a) should be handled in 3960 accordance with the "Specification Required" assignment policy, 3961 defined as of draft-iesg-iana-considerations-02 as follows: "Values 3962 and their meaning must be documented in an RFC or other available 3963 reference, in sufficient detail so that interoperability between 3964 independent implementations is possible." 3966 4.2: User Name Form 3968 This name form shall be represented by the Object Identifier {iso(1) 3969 member-body(2) United States(840) mit(113554) infosys(1) gssapi(2) 3970 generic(1) user_name(1)}. The recommended mechanism-independent 3971 symbolic name for this type is "GSS_C_NT_USER_NAME". (Note: the same 3972 name form and OID is defined within the Kerberos V5 GSS-API 3973 mechanism, but the symbolic name recommended there begins with a 3974 "GSS_KRB5_NT_" prefix.) 3976 This name type is used to indicate a named user on a local system. 3977 Its syntax and interpretation may be OS-specific. This name form is 3978 constructed as: 3980 username 3982 4.3: Machine UID Form 3984 This name form shall be represented by the Object Identifier {iso(1) 3985 member-body(2) United States(840) mit(113554) infosys(1) gssapi(2) 3986 generic(1) machine_uid_name(2)}. The recommended mechanism- 3987 independent symbolic name for this type is 3988 "GSS_C_NT_MACHINE_UID_NAME". (Note: the same name form and OID is 3989 defined within the Kerberos V5 GSS-API mechanism, but the symbolic 3990 name recommended there begins with a "GSS_KRB5_NT_" prefix.) 3992 This name type is used to indicate a numeric user identifier 3993 corresponding to a user on a local system. Its interpretation is 3994 OS-specific. The gss_buffer_desc representing a name of this type 3995 should contain a locally-significant user ID, represented in host 3996 byte order. The GSS_Import_name() operation resolves this uid into a 3997 username, which is then treated as the User Name Form. 3999 4.4: String UID Form 4000 This name form shall be represented by the Object Identifier {iso(1) 4001 member-body(2) United States(840) mit(113554) infosys(1) gssapi(2) 4002 generic(1) string_uid_name(3)}. The recommended symbolic name for 4003 this type is "GSS_C_NT_STRING_UID_NAME". (Note: the same name form 4004 and OID is defined within the Kerberos V5 GSS-API mechanism, but the 4005 symbolic name recommended there begins with a "GSS_KRB5_NT_" prefix.) 4007 This name type is used to indicate a string of digits representing 4008 the numeric user identifier of a user on a local system. Its 4009 interpretation is OS-specific. This name type is similar to the 4010 Machine UID Form, except that the buffer contains a string 4011 representing the user ID. 4013 4.5: Anonymous Nametype 4015 The following Object Identifier value is provided as a means to 4016 identify anonymous names, and can be compared against in order to 4017 determine, in a mechanism-independent fashion, whether a name refers 4018 to an anonymous principal: 4020 {1(iso), 3(org), 6(dod), 1(internet), 5(security), 6(nametypes), 4021 3(gss-anonymous-name)} 4023 The recommended symbolic name corresponding to this definition is 4024 GSS_C_NT_ANONYMOUS. 4026 4.6: GSS_C_NO_OID 4028 The recommended symbolic name GSS_C_NO_OID corresponds to a null 4029 input value instead of an actual object identifier. Where specified, 4030 it indicates interpretation of an associated name based on a 4031 mechanism-specific default printable syntax. 4033 4.7: Exported Name Object 4035 Name objects of the Mechanism-Independent Exported Name Object type, 4036 as defined in Section 3.2 of this document, will be identified with 4037 the following Object Identifier: 4039 {1(iso), 3(org), 6(dod), 1(internet), 5(security), 6(nametypes), 4040 4(gss-api-exported-name)} 4042 The recommended symbolic name corresponding to this definition is 4043 GSS_C_NT_EXPORT_NAME. 4045 4.8: GSS_C_NO_NAME 4047 The recommended symbolic name GSS_C_NO_NAME indicates that no name is 4048 being passed within a particular value of a parameter used for the 4049 purpose of transferring names. Note: GSS_C_NO_NAME is not an actual 4050 name type, and is not represented by an OID; its acceptability in 4051 lieu of an actual name is confined to specific calls 4052 (GSS_Acquire_cred(), GSS_Add_cred(), and GSS_Init_sec_context()) with 4053 usages as identified within this specification. 4055 5: Mechanism-Specific Example Scenarios 4057 This section provides illustrative overviews of the use of various 4058 candidate mechanism types to support the GSS-API. These discussions 4059 are intended primarily for readers familiar with specific security 4060 technologies, demonstrating how GSS-API functions can be used and 4061 implemented by candidate underlying mechanisms. They should not be 4062 regarded as constrictive to implementations or as defining the only 4063 means through which GSS-API functions can be realized with a 4064 particular underlying technology, and do not demonstrate all GSS-API 4065 features with each technology. 4067 5.1: Kerberos V5, single-TGT 4069 OS-specific login functions yield a TGT to the local realm Kerberos 4070 server; TGT is placed in a credentials structure for the client. 4071 Client calls GSS_Acquire_cred() to acquire a cred_handle in order to 4072 reference the credentials for use in establishing security contexts. 4074 Client calls GSS_Init_sec_context(). If the requested service is 4075 located in a different realm, GSS_Init_sec_context() gets the 4076 necessary TGT/key pairs needed to traverse the path from local to 4077 target realm; these data are placed in the owner's TGT cache. After 4078 any needed remote realm resolution, GSS_Init_sec_context() yields a 4079 service ticket to the requested service with a corresponding session 4080 key; these data are stored in conjunction with the context. GSS-API 4081 code sends KRB_TGS_REQ request(s) and receives KRB_TGS_REP 4082 response(s) (in the successful case) or KRB_ERROR. 4084 Assuming success, GSS_Init_sec_context() builds a Kerberos-formatted 4085 KRB_AP_REQ message, and returns it in output_token. The client sends 4086 the output_token to the service. 4088 The service passes the received token as the input_token argument to 4089 GSS_Accept_sec_context(), which verifies the authenticator, provides 4090 the service with the client's authenticated name, and returns an 4091 output_context_handle. 4093 Both parties now hold the session key associated with the service 4094 ticket, and can use this key in subsequent GSS_GetMIC(), 4095 GSS_VerifyMIC(), GSS_Wrap(), and GSS_Unwrap() operations. 4097 5.2: Kerberos V5, double-TGT 4099 TGT acquisition as above. 4101 Note: To avoid unnecessary frequent invocations of error paths when 4102 implementing the GSS-API atop Kerberos V5, it seems appropriate to 4103 represent "single-TGT K-V5" and "double-TGT K-V5" with separate 4104 mech_types, and this discussion makes that assumption. 4106 Based on the (specified or defaulted) mech_type, 4107 GSS_Init_sec_context() determines that the double-TGT protocol 4108 should be employed for the specified target. GSS_Init_sec_context() 4109 returns GSS_S_CONTINUE_NEEDED major_status, and its returned 4110 output_token contains a request to the service for the service's TGT. 4111 (If a service TGT with suitably long remaining lifetime already 4112 exists in a cache, it may be usable, obviating the need for this 4113 step.) The client passes the output_token to the service. Note: this 4114 scenario illustrates a different use for the GSS_S_CONTINUE_NEEDED 4115 status return facility than for support of mutual authentication; 4116 note that both uses can coexist as successive operations within a 4117 single context establishment operation. 4119 The service passes the received token as the input_token argument to 4120 GSS_Accept_sec_context(), which recognizes it as a request for TGT. 4121 (Note that current Kerberos V5 defines no intra-protocol mechanism to 4122 represent such a request.) GSS_Accept_sec_context() returns 4123 GSS_S_CONTINUE_NEEDED major_status and provides the service's TGT in 4124 its output_token. The service sends the output_token to the client. 4126 The client passes the received token as the input_token argument to a 4127 continuation of GSS_Init_sec_context(). GSS_Init_sec_context() caches 4128 the received service TGT and uses it as part of a service ticket 4129 request to the Kerberos authentication server, storing the returned 4130 service ticket and session key in conjunction with the context. 4131 GSS_Init_sec_context() builds a Kerberos-formatted authenticator, and 4132 returns it in output_token along with GSS_S_COMPLETE return 4133 major_status. The client sends the output_token to the service. 4135 Service passes the received token as the input_token argument to a 4136 continuation call to GSS_Accept_sec_context(). 4137 GSS_Accept_sec_context() verifies the authenticator, provides the 4138 service with the client's authenticated name, and returns 4139 major_status GSS_S_COMPLETE. 4141 GSS_GetMIC(), GSS_VerifyMIC(), GSS_Wrap(), and GSS_Unwrap() as 4142 above. 4144 5.3: X.509 Authentication Framework 4145 This example illustrates use of the GSS-API in conjunction with 4146 public-key mechanisms, consistent with the X.509 Directory 4147 Authentication Framework. 4149 The GSS_Acquire_cred() call establishes a credentials structure, 4150 making the client's private key accessible for use on behalf of the 4151 client. 4153 The client calls GSS_Init_sec_context(), which interrogates the 4154 Directory to acquire (and validate) a chain of public-key 4155 certificates, thereby collecting the public key of the service. The 4156 certificate validation operation determines that suitable integrity 4157 checks were applied by trusted authorities and that those 4158 certificates have not expired. GSS_Init_sec_context() generates a 4159 secret key for use in per-message protection operations on the 4160 context, and enciphers that secret key under the service's public 4161 key. 4163 The enciphered secret key, along with an authenticator quantity 4164 signed with the client's private key, is included in the output_token 4165 from GSS_Init_sec_context(). The output_token also carries a 4166 certification path, consisting of a certificate chain leading from 4167 the service to the client; a variant approach would defer this path 4168 resolution to be performed by the service instead of being asserted 4169 by the client. The client application sends the output_token to the 4170 service. 4172 The service passes the received token as the input_token argument to 4173 GSS_Accept_sec_context(). GSS_Accept_sec_context() validates the 4174 certification path, and as a result determines a certified binding 4175 between the client's distinguished name and the client's public key. 4176 Given that public key, GSS_Accept_sec_context() can process the 4177 input_token's authenticator quantity and verify that the client's 4178 private key was used to sign the input_token. At this point, the 4179 client is authenticated to the service. The service uses its private 4180 key to decipher the enciphered secret key provided to it for per- 4181 message protection operations on the context. 4183 The client calls GSS_GetMIC() or GSS_Wrap() on a data message, which 4184 causes per-message authentication, integrity, and (optional) 4185 confidentiality facilities to be applied to that message. The service 4186 uses the context's shared secret key to perform corresponding 4187 GSS_VerifyMIC() and GSS_Unwrap() calls. 4189 6: Security Considerations 4191 This document specifies a service interface for security facilities 4192 and services; as such, security considerations are considered 4193 throughout the specification. Nonetheless, it is appropriate to 4194 summarize certain specific points relevant to GSS-API implementors 4195 and calling applications. Usage of the GSS-API interface does not in 4196 itself provide security services or assurance; instead, these 4197 attributes are dependent on the underlying mechanism(s) which support 4198 a GSS-API implementation. Callers must be attentive to the requests 4199 made to GSS-API calls and to the status indicators returned by GSS- 4200 API, as these specify the security service characteristics which 4201 GSS-API will provide. When the interprocess context transfer 4202 facility is used, appropriate local controls should be applied to 4203 constrain access to interprocess tokens and to the sensitive data 4204 which they contain. 4206 7: Related Activities 4208 In order to implement the GSS-API atop existing, emerging, and future 4209 security mechanisms: 4211 object identifiers must be assigned to candidate GSS-API 4212 mechanisms and the name types which they support 4214 concrete data element formats and processing procedures must be 4215 defined for candidate mechanisms 4217 Calling applications must implement formatting conventions which will 4218 enable them to distinguish GSS-API tokens from other data carried in 4219 their application protocols. 4221 Concrete language bindings are required for the programming 4222 environments in which the GSS-API is to be employed, as [RFC-1509] 4223 defines for the C programming language and GSS-V1. Preparation of C 4224 language bindings for GSS-V2 is in process in parallel with the 4225 preparation of the current document, and it is anticipated that this 4226 bindings document will be submitted as a candidate for 4227 standardization along with the current specification. 4229 8: Referenced Documents 4231 [ISO-7498-2] International Standard ISO 7498-2-1988(E), Security 4232 Architecture. 4234 [ISOIEC-8824] ISO/IEC 8824, "Specification of Abstract Syntax 4235 Notation One (ASN.1)". 4237 [ISOIEC-8825] ISO/IEC 8825, "Specification of Basic Encoding Rules 4238 for Abstract Syntax Notation One (ASN.1)".) 4240 [RFC-1507]: C. Kaufman, "DASS: Distributed Authentication Security 4241 Service", RFC 1507. 4243 [RFC-1508]: J. Linn, "Generic Security Service Application Program 4244 Interface", RFC 1508. 4246 [RFC-1509]: J. Wray, "Generic Security Service API: C-bindings", RFC 4247 1509. 4249 [RFC-1964]: J. Linn, "The Kerberos Version 5 GSS-API Mechanism", RFC 4250 1964. 4252 [RFC-2025]: C. Adams, "The Simple Public-Key GSS-API Mechanism 4253 (SPKM)", RFC 2025. 4255 [RFC-2078]: J. Linn, "Generic Security Service Application Program 4256 Interface, Version 2", RFC 2078. 4258 [RFC-2203]: M. Eisler, A. Chiu, L. Ling, "RPCSEC_GSS Protocol 4259 Specification", RFC 2203. 4261 APPENDIX A 4263 MECHANISM DESIGN CONSTRAINTS 4265 The following constraints on GSS-API mechanism designs are adopted in 4266 response to observed caller protocol requirements, and adherence thereto 4267 is anticipated in subsequent descriptions of GSS-API mechanisms to be 4268 documented in standards-track Internet specifications. 4270 It is strongly recommended that mechanisms offering per-message 4271 protection services also offer at least one of the replay detection and 4272 sequencing services, as mechanisms offering neither of the latter will 4273 fail to satisfy recognized requirements of certain candidate caller 4274 protocols. 4276 APPENDIX B 4278 COMPATIBILITY WITH GSS-V1 4280 It is the intent of this document to define an interface and procedures 4281 which preserve compatibility between GSS-V1 [RFC-1508] callers and GSS- 4282 V2 providers. All calls defined in GSS-V1 are preserved, and it has 4283 been a goal that GSS-V1 callers should be able to operate atop GSS-V2 4284 provider implementations. Certain detailed changes, summarized in this 4285 section, have been made in order to resolve omissions identified in 4286 GSS-V1. 4288 The following GSS-V1 constructs, while supported within GSS-V2, are 4289 deprecated: 4291 Names for per-message processing routines: GSS_Seal() deprecated in 4292 favor of GSS_Wrap(); GSS_Sign() deprecated in favor of 4293 GSS_GetMIC(); GSS_Unseal() deprecated in favor of GSS_Unwrap(); 4294 GSS_Verify() deprecated in favor of GSS_VerifyMIC(). 4296 GSS_Delete_sec_context() facility for context_token usage, allowing 4297 mechanisms to signal context deletion, is retained for 4298 compatibility with GSS-V1. For current usage, it is recommended 4299 that both peers to a context invoke GSS_Delete_sec_context() 4300 independently, passing a null output_context_token buffer to 4301 indicate that no context_token is required. Implementations of 4302 GSS_Delete_sec_context() should delete relevant locally-stored 4303 context information. 4305 This GSS-V2 specification adds the following calls which are not present 4306 in GSS-V1: 4308 Credential management calls: GSS_Add_cred(), 4309 GSS_Inquire_cred_by_mech(). 4311 Context-level calls: GSS_Inquire_context(), GSS_Wrap_size_limit(), 4312 GSS_Export_sec_context(), GSS_Import_sec_context(). 4314 Per-message calls: No new calls. Existing calls have been renamed. 4316 Support calls: GSS_Create_empty_OID_set(), 4317 GSS_Add_OID_set_member(), GSS_Test_OID_set_member(), 4318 GSS_Inquire_names_for_mech(), GSS_Inquire_mechs_for_name(), 4319 GSS_Canonicalize_name(), GSS_Export_name(), GSS_Duplicate_name(). 4321 This GSS-V2 specification introduces three new facilities applicable to 4322 security contexts, indicated using the following context state values 4323 which are not present in GSS-V1: 4325 anon_state, set TRUE to indicate that a context's initiator is 4326 anonymous from the viewpoint of the target; Section 1.2.5 of this 4327 specification provides a summary description of the GSS-V2 4328 anonymity support facility, support and use of which is optional. 4330 prot_ready_state, set TRUE to indicate that a context may be used 4331 for per-message protection before final completion of context 4332 establishment; Section 1.2.7 of this specification provides a 4333 summary description of the GSS-V2 facility enabling mechanisms to 4334 selectively permit per-message protection during context 4335 establishment, support and use of which is optional. 4337 trans_state, set TRUE to indicate that a context is transferable to 4338 another process using the GSS-V2 GSS_Export_sec_context() facility. 4340 These state values are represented (at the C bindings level) in 4341 positions within a bit vector which are unused in GSS-V1, and may be 4342 safely ignored by GSS-V1 callers. 4344 New conf_req_flag and integ_req_flag inputs are defined for 4345 GSS_Init_sec_context(), primarily to provide information to negotiating 4346 mechanisms. This introduces a compatibility issue with GSS-V1 callers, 4347 discussed in section 2.2.1 of this specification. 4349 Relative to GSS-V1, GSS-V2 provides additional guidance to GSS-API 4350 implementors in the following areas: implementation robustness, 4351 credential management, behavior in multi-mechanism configurations, 4352 naming support, and inclusion of optional sequencing services. The 4353 token tagging facility as defined in GSS-V2, Section 3.1, is now 4354 described directly in terms of octets to facilitate interoperable 4355 implementation without general ASN.1 processing code; the corresponding 4356 ASN.1 syntax, included for descriptive purposes, is unchanged from that 4357 in GSS-V1. For use in conjunction with added naming support facilities, 4358 a new Exported Name Object construct is added. Additional name types 4359 are introduced in Section 4. 4361 This GSS-V2 specification adds the following major_status values which 4362 are not defined in GSS-V1: 4364 GSS_S_BAD_QOP unsupported QOP value 4365 GSS_S_UNAUTHORIZED operation unauthorized 4366 GSS_S_UNAVAILABLE operation unavailable 4367 GSS_S_DUPLICATE_ELEMENT duplicate credential element 4368 requested 4369 GSS_S_NAME_NOT_MN name contains multi-mechanism 4370 elements 4371 GSS_S_GAP_TOKEN skipped predecessor token(s) 4372 detected 4374 Of these added status codes, only two values are defined to be 4375 returnable by calls existing in GSS-V1: GSS_S_BAD_QOP (returnable by 4376 GSS_GetMIC() and GSS_Wrap()), and GSS_S_GAP_TOKEN (returnable by 4377 GSS_VerifyMIC() and GSS_Unwrap()). 4379 Additionally, GSS-V2 descriptions of certain calls present in GSS-V1 4380 have been updated to allow return of additional major_status values from 4381 the set as defined in GSS-V1: GSS_Inquire_cred() has 4382 GSS_S_DEFECTIVE_CREDENTIAL and GSS_S_CREDENTIALS_EXPIRED defined as 4383 returnable, GSS_Init_sec_context() has GSS_S_OLD_TOKEN, 4384 GSS_S_DUPLICATE_TOKEN, and GSS_S_BAD_MECH defined as returnable, and 4385 GSS_Accept_sec_context() has GSS_S_BAD_MECH defined as returnable. 4387 APPENDIX C 4389 CHANGES RELATIVE TO RFC-2078 4391 This document incorporates a number of changes relative to RFC-2078, 4392 made primarily in response to implementation experience, for purposes of 4393 alignment with the GSS-V2 C language bindings document, and to add 4394 informative clarification. This section summarizes technical changes 4395 incorporated. 4397 General: 4399 Clarified usage of object release routines, and incorporated 4400 statement that some may be omitted within certain operating 4401 environments. 4403 Removed GSS_Release_OID, GSS_OID_to_str(), and GSS_Str_to_OID() 4404 routines. 4406 Clarified circumstances under which zero-length tokens may validly 4407 exist as inputs and outputs to/from GSS-API calls. 4409 Added GSS_S_BAD_MIC status code as alias for GSS_S_BAD_SIG. 4411 For GSS_Display_status(), deferred to language bindings the choice 4412 of whether to return multiple status values in parallel or via 4413 iteration, and added commentary deprecating return of 4414 GSS_S_CONTINUE_NEEDED. 4416 Adapted and incorporated clarifying material on optional service 4417 support, delegation, and interprocess context transfer from C 4418 bindings document. 4420 Added and updated references to related documents, and to current 4421 status of cited Kerberos mechanism OID. 4423 Added general statement about GSS-API calls having no side effects 4424 visible at the GSS-API level. 4426 Context-related (including per-message protection issues): 4428 Clarified GSS_Delete_sec_context() usage for partially-established 4429 contexts. 4431 Added clarification on GSS_Export_sec_context() and 4432 GSS_Import_sec_context() behavior and context usage following an 4433 export-import sequence. 4435 Added informatory conf_req_flag, integ_req_flag inputs to 4436 GSS_Init_sec_context(). (Note: this facility introduces a backward 4437 incompatibility with GSS-V1 callers, discussed in Section 2.2.1; 4438 this implication was recognized and accepted in working group 4439 discussion.) 4441 Stated that GSS_S_FAILURE is to be returned if 4442 GSS_Init_sec_context() or GSS_Accept_sec_context() is passed the 4443 handle of a context which is already fully established. 4445 Re GSS_Inquire_sec_context(), stated that src_name and targ_name 4446 are not returned until GSS_S_COMPLETE status is reached; removed 4447 use of GSS_S_CONTEXT_EXPIRED status code (replacing with EXPIRED 4448 lifetime return value); stated requirement to retain inquirable 4449 data until context released by caller; added result value 4450 indicating whether or not context is fully open. 4452 Added discussion of interoperability conditions for mechanisms 4453 permitting optional support of QOPs. Removed reference to 4454 structured QOP elements in GSS_Verify_MIC(). 4456 Added discussion of use of GSS_S_DUPLICATE_TOKEN status to indicate 4457 reflected per-message tokens. 4459 Clarified use of informational sequencing codes from per-message 4460 protection calls in conjunction with GSS_S_COMPLETE and 4461 GSS_S_FAILURE major_status returns, adjusting status code 4462 descriptions accordingly. 4464 Added specific statements about impact of GSS_GetMIC() and 4465 GSS_Wrap() failures on context state information, and generalized 4466 existing statements about impact of processing failures on received 4467 per-message tokens. 4469 For GSS_Init_sec_context() and GSS_Accept_sec_context(), permitted 4470 returned mech_type to be valid before GSS_S_COMPLETE, recognizing 4471 that the value may change on successive continuation calls in the 4472 negotiated mechanism case. 4474 Deleted GSS_S_CONTEXT_EXPIRED status from GSS_Import_sec_context(). 4476 Added conf_req_flag input to GSS_Wrap_size_limit(). 4478 Stated requirement for mechanisms' support of per-message 4479 protection services to be usable concurrently in both directions on 4480 a context. 4482 Credential-related: 4484 For GSS_Acquire_cred() and GSS_Add_cred(), aligned with C bindings 4485 statement of likely non-support for INITIATE or BOTH credentials if 4486 input name is neither empty nor a name resulting from applying 4487 GSS_Inquire_cred() against the default credential. Further, stated 4488 that an explicit name returned by GSS_Inquire_context() should also 4489 be accepted. Added commentary about potentially time-variant 4490 results of default resolution and attendant implications. Aligned 4491 with C bindings re behavior when GSS_C_NO_NAME provided for 4492 desired_name. In GSS_Acquire_cred(), stated that NULL, rather than 4493 empty OID set, should be used for desired_mechs in order to request 4494 default mechanism set. 4496 Added GSS_S_CREDENTIALS_EXPIRED as returnable major_status for 4497 GSS_Acquire_cred(), GSS_Add_cred(), also specifying GSS_S_NO_CRED 4498 as appropriate return for temporary, user-fixable credential 4499 unavailability. GSS_Acquire_cred() and GSS_Add_cred() are also to 4500 return GSS_S_NO_CRED if an authorization failure is encountered 4501 upon credential acquisition. 4503 Removed GSS_S_CREDENTIALS_EXPIRED status return from per-message 4504 protection, GSS_Context_time(), and GSS_Inquire_context() calls. 4506 For GSS_Add_cred(), aligned with C bindings' description of 4507 behavior when addition of elements to the default credential is 4508 requested. 4510 Upgraded recommended default credential resolution algorithm to 4511 status of requirement for initiator credentials. 4513 For GSS_Release_cred(), GSS_Inquire_cred(), and 4514 GSS_Inquire_cred_by_mech(), clarified behavior for input 4515 GSS_C_NO_CREDENTIAL. 4517 Name-related: 4519 Aligned GSS_Inquire_mechs_for_name() description with C bindings. 4521 Removed GSS_S_BAD_NAMETYPE status return from GSS_Duplicate_name(), 4522 GSS_Display_name(); constrained its applicability for 4523 GSS_Compare_name(). 4525 Aligned with C bindings statement re GSS_Import_name() behavior 4526 with GSS_C_NO_OID input name type, and stated that GSS-V2 mechanism 4527 specifications are to define processing procedures applicable to 4528 their mechanisms. Also clarified GSS_C_NO_OID usage with 4529 GSS_Display_name(). 4531 Downgraded reference to name canonicalization via DNS lookup to an 4532 example. 4534 For GSS_Canonicalize_name(), stated that neither negotiated 4535 mechanisms nor the default mechanism are supported input mech_types 4536 for this operation, and specified GSS_S_BAD_MECH status to be 4537 returned in this case. Clarified that the GSS_Canonicalize_name() 4538 operation is non-destructive to its input name. 4540 Clarified semantics of GSS_C_NT_USER_NAME name type. 4542 Added descriptions of additional name types. Also added discussion 4543 of GSS_C_NO_NAME and its constrained usage with specific GSS calls. 4545 Adapted and incorporated C bindings discussion about name 4546 comparisons with exported name objects. 4548 Added recommendation to mechanism designers for support of host- 4549 based service name type, deferring any requirement statement to 4550 individual mechanism specifications. Added discussion of host- 4551 based service's service name element and proposed approach for IANA 4552 registration policy therefor. 4554 Clarified byte ordering within exported name object. Stated that 4555 GSS_S_BAD_MECH is to be returned if, in the course of attempted 4556 import of an exported name object, the name object's enclosed 4557 mechanism type is unrecognized or unsupported. 4559 Stated that mechanisms may optionally accept GSS_C_NO_NAME as an 4560 input target name to GSS_Init_sec_context(), with comment that such 4561 support is unlikely within mechanisms predating GSS-V2, Update 1. 4563 AUTHOR'S ADDRESS 4565 John Linn 4566 RSA Laboratories East 4567 20 Crosby Drive 4568 Bedford, MA 01730 USA 4569 +1 781.687.7817 4571 E-mail: linn@rsa.com 4572 TABLE OF CONTENTS 4574 1: GSS-API Characteristics and Concepts 4575 1.1: GSS-API Constructs 4576 1.1.1: Credentials 4577 1.1.1.1: Credential Constructs and Concepts 4578 1.1.1.2: Credential Management 4579 1.1.1.3: Default Credential Resolution 4580 1.1.2: Tokens 4581 1.1.3: Security Contexts 4582 1.1.4: Mechanism Types 4583 1.1.5: Naming 4584 1.1.6: Channel Bindings 4585 1.2: GSS-API Features and Issues 4586 1.2.1: Status Reporting 4587 1.2.2: Per-Message Security Service Availability 4588 1.2.3: Per-Message Replay Detection and Sequencing 4589 1.2.4: Quality of Protection 4590 1.2.5: Anonymity Support 4591 1.2.6: Initialization 4592 1.2.7: Per-Message Protection During Context Establishment 4593 1.2.8: Implementation Robustness 4594 2: Interface Descriptions 4595 2.1: Credential management calls 4596 2.1.1: GSS_Acquire_cred call 4597 2.1.2: GSS_Release_cred call 4598 2.1.3: GSS_Inquire_cred call 4599 2.1.4: GSS_Add_cred call 4600 2.1.5: GSS_Inquire_cred_by_mech call 4601 2.2: Context-level calls 4602 2.2.1: GSS_Init_sec_context call 4603 2.2.2: GSS_Accept_sec_context call 4604 2.2.3: GSS_Delete_sec_context call 4605 2.2.4: GSS_Process_context_token call 4606 2.2.5: GSS_Context_time call 4607 2.2.6: GSS_Inquire_context call 4608 2.2.7: GSS_Wrap_size_limit call 4609 2.2.8: GSS_Export_sec_context call 4610 2.2.9: GSS_Import_sec_context call 4611 2.3: Per-message calls 4612 2.3.1: GSS_GetMIC call 4613 2.3.2: GSS_VerifyMIC call 4614 2.3.3: GSS_Wrap call 4615 2.3.4: GSS_Unwrap call 4616 2.4: Support calls 4617 2.4.1: GSS_Display_status call 4618 2.4.2: GSS_Indicate_mechs call 4619 2.4.3: GSS_Compare_name call 4620 2.4.4: GSS_Display_name call 4621 2.4.5: GSS_Import_name call 4622 2.4.6: GSS_Release_name call 4623 2.4.7: GSS_Release_buffer call 4624 2.4.8: GSS_Release_OID_set call 4625 2.4.9: GSS_Create_empty_OID_set call 4626 2.4.10: GSS_Add_OID_set_member call 4627 2.4.11: GSS_Test_OID_set_member call 4628 2.4.12: GSS_Inquire_names_for_mech call 4629 2.4.13: GSS_Inquire_mechs_for_name call 4630 2.4.14: GSS_Canonicalize_name call 4631 2.4.15: GSS_Export_name call 4632 2.4.16: GSS_Duplicate_name call 4633 3: Data Structure Definitions for GSS-V2 Usage 4634 3.1: Mechanism-Independent Token Format 4635 3.2: Mechanism-Independent Exported Name Object Format 4636 4: Name Type Definitions 4637 4.1: Host-Based Service Name Form 4638 4.2: User Name Form 4639 4.3: Machine UID Form 4640 4.4: String UID Form 4641 5: Mechanism-Specific Example Scenarios 4642 5.1: Kerberos V5, single-TGT 4643 5.2: Kerberos V5, double-TGT 4644 5.3: X.509 Authentication Framework 4645 6: Security Considerations 4646 7: Related Activities 4647 8: Referenced Documents 4648 Appendix A: Mechanism Design Constraints 4649 Appendix B: Compatibility with GSS-V1 4650 Appendix C: Changes Relative to RFC-2078