idnits 2.17.1 draft-ietf-cat-gssv2-02.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** Cannot find the required boilerplate sections (Copyright, IPR, etc.) in this document. Expected boilerplate is as follows today (2024-03-29) 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 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.) ** There are 19 instances of too long lines in the document, the longest one being 4 characters in excess of 72. Miscellaneous warnings: ---------------------------------------------------------------------------- == Line 783 has weird spacing: '...t_token pro...' -- 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 (2 June 1995) is 10528 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? 'APPLICATION 0' on line 2956 looks like a reference Summary: 11 errors (**), 0 flaws (~~), 2 warnings (==), 3 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Internet-Draft J. Linn (OpenVision) 3 IETF Common Authentication Technology WG OpenVision Technologies 4 2 June 1995 6 Generic Security Service Application Program Interface, Version 2 8 STATUS OF THIS MEMO 10 This document is an Internet-Draft. Internet-Drafts are working 11 documents of the Internet Engineering Task Force (IETF), its areas, 12 and its working groups. Note that other groups may also distribute 13 working documents as Internet-Drafts. 15 Internet-Drafts are draft documents valid for a maximum of six months 16 and may be updated, replaced, or obsoleted by other documents at any 17 time. It is inappropriate to use Internet- Drafts as reference 18 material or to cite them other than as ``work in progress.'' 20 To learn the current status of any Internet-Draft, please check the 21 ``1id-abstracts.txt'' listing contained in the Internet- Drafts 22 Shadow Directories on ds.internic.net (US East Coast), nic.nordu.net 23 (Europe), ftp.isi.edu (US West Coast), or munnari.oz.au (Pacific 24 Rim). 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 as defined in RFC-1508, provides security services to callers in a 33 generic fashion, supportable with a range of underlying mechanisms 34 and technologies and hence allowing source-level portability of 35 applications to different environments. This specification defines 36 GSS-API services and primitives at a level independent of underlying 37 mechanism and programming language environment, and is to be 38 complemented by other, related specifications: 40 documents defining specific parameter bindings for particular 41 language environments 43 documents defining token formats, protocols, and procedures to be 44 implemented in order to realize GSS-API services atop particular 45 security mechanisms 47 This Internet-Draft revises RFC-1508, making specific, incremental 48 changes in response to implementation experience and liaison 49 requests. It is intended, therefore, that this draft or a successor 50 version thereto will become the basis for subsequent progression of 51 the GSS-API specification on the standards track. 53 1: GSS-API Characteristics and Concepts 55 GSS-API operates in the following paradigm. A typical GSS-API caller 56 is itself a communications protocol, calling on GSS-API in order to 57 protect its communications with authentication, integrity, and/or 58 confidentiality security services. A GSS-API caller accepts tokens 59 provided to it by its local GSS-API implementation and transfers the 60 tokens to a peer on a remote system; that peer passes the received 61 tokens to its local GSS-API implementation for processing. The 62 security services available through GSS-API in this fashion are 63 implementable (and have been implemented) over a range of underlying 64 mechanisms based on secret-key and public-key cryptographic 65 technologies. 67 The GSS-API separates the operations of initializing a security 68 context between peers, achieving peer entity authentication (This 69 security service definition, and other definitions used in this 70 document, corresponds to that provided in International Standard ISO 71 7498-2-1988(E), Security Architecture.) (GSS_Init_sec_context() and 72 GSS_Accept_sec_context() calls), from the operations of providing 73 per-message data origin authentication and data integrity protection 74 (GSS_GetMIC() and GSS_VerifyMIC() calls) for messages subsequently 75 transferred in conjunction with that context. When establishing a 76 security context, the GSS-API enables a context initiator to 77 optionally permit its credentials to be delegated, meaning that the 78 context acceptor may initiate further security contexts on behalf of 79 the initiating caller. Per-message GSS_Wrap() and GSS_Unwrap() 80 calls provide the data origin authentication and data integrity 81 services which GSS_GetMIC() and GSS_VerifyMIC() offer, and also 82 support selection of confidentiality services as a caller option. 83 Additional calls provide supportive functions to the GSS-API's users. 85 The following paragraphs provide an example illustrating the 86 dataflows involved in use of the GSS-API by a client and server in a 87 mechanism-independent fashion, establishing a security context and 88 transferring a protected message. The example assumes that credential 89 acquisition has already been completed. The example assumes that the 90 underlying authentication technology is capable of authenticating a 91 client to a server using elements carried within a single token, and 92 of authenticating the server to the client (mutual authentication) 93 with a single returned token; this assumption holds for presently- 94 documented CAT mechanisms but is not necessarily true for other 95 cryptographic technologies and associated protocols. 97 The client calls GSS_Init_sec_context() to establish a security 98 context to the server identified by targ_name, and elects to set the 99 mutual_req_flag so that mutual authentication is performed in the 100 course of context establishment. GSS_Init_sec_context() returns an 101 output_token to be passed to the server, and indicates 102 GSS_S_CONTINUE_NEEDED status pending completion of the mutual 103 authentication sequence. Had mutual_req_flag not been set, the 104 initial call to GSS_Init_sec_context() would have returned 105 GSS_S_COMPLETE status. The client sends the output_token to the 106 server. 108 The server passes the received token as the input_token parameter to 109 GSS_Accept_sec_context(). GSS_Accept_sec_context indicates 110 GSS_S_COMPLETE status, provides the client's authenticated identity 111 in the src_name result, and provides an output_token to be passed to 112 the client. The server sends the output_token to the client. 114 The client passes the received token as the input_token parameter to 115 a successor call to GSS_Init_sec_context(), which processes data 116 included in the token in order to achieve mutual authentication from 117 the client's viewpoint. This call to GSS_Init_sec_context() returns 118 GSS_S_COMPLETE status, indicating successful mutual authentication 119 and the completion of context establishment for this example. 121 The client generates a data message and passes it to GSS_Wrap(). 122 GSS_Wrap() performs data origin authentication, data integrity, and 123 (optionally) confidentiality processing on the message and 124 encapsulates the result into output_message, indicating 125 GSS_S_COMPLETE status. The client sends the output_message to the 126 server. 128 The server passes the received message to GSS_Unwrap(). GSS_Unwrap() 129 inverts the encapsulation performed by GSS_Wrap(), deciphers the 130 message if the optional confidentiality feature was applied, and 131 validates the data origin authentication and data integrity checking 132 quantities. GSS_Unwrap() indicates successful validation by 133 returning GSS_S_COMPLETE status along with the resultant 134 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 can be implemented by secret-key technologies (e.g., 158 Kerberos) or public-key approaches (e.g., X.509). 160 Protocol environment independence: The GSS-API is independent of 161 the communications protocol suites with which it is employed, 162 permitting use in a broad range of protocol environments. In 163 appropriate environments, an intermediate implementation "veneer" 164 which is oriented to a particular communication protocol (e.g., 165 Remote Procedure Call (RPC)) may be interposed between 166 applications which call that protocol and the GSS-API, thereby 167 invoking GSS-API facilities in conjunction with that protocol's 168 communications invocations. 170 Protocol association independence: The GSS-API's security context 171 construct is independent of communications protocol association 172 constructs. This characteristic allows a single GSS-API 173 implementation to be utilized by a variety of invoking protocol 174 modules on behalf of those modules' calling applications. GSS-API 175 services can also be invoked directly by applications, wholly 176 independent of protocol associations. 178 Suitability to a range of implementation placements: GSS-API 179 clients are not constrained to reside within any Trusted Computing 180 Base (TCB) perimeter defined on a system where the GSS-API is 181 implemented; security services are specified in a manner suitable 182 to both intra-TCB and extra-TCB callers. 184 1.1: GSS-API Constructs 186 This section describes the basic elements comprising the GSS-API. 188 1.1.1: Credentials 190 Credentials structures provide the prerequisites enabling peers to 191 establish security contexts with each other. A caller may designate 192 that the credential elements to be applied for context initiation or 193 acceptance be selected by default. Alternately, those GSS-API 194 callers which need to make explicit selection of particular 195 credentials structures may make references to those credentials 196 through GSS-API-provided credential handles ("cred_handles"). 198 A single credential structure may be used for initiation of outbound 199 contexts and acceptance of inbound contexts. Callers needing to 200 operate in only one of these modes may designate this fact when 201 credentials are acquired for use, allowing underlying mechanisms to 202 optimize their processing and storage requirements. The credential 203 elements defined by a particular mechanism may contain multiple 204 cryptographic keys, e.g., to enable authentication and message 205 encryption to be performed with different algorithms. 207 A single credential structure may accommodate credential information 208 associated with multiple underlying mechanisms (mech_types), but the 209 elements within a given credential structure represent a common 210 entity. A credential structure's contents will vary depending on the 211 set of mech_types supported by a particular GSS-API implementation. 212 Commonly, a single mech_type will be used for all security contexts 213 established by a particular initiator to a particular target; the 214 primary motivation for supporting credential sets representing 215 multiple mech_types is to allow initiators on systems which are 216 equipped to handle multiple types to initiate contexts to targets on 217 other systems which can accommodate only a subset of the set 218 supported at the initiator's system. 220 It is the responsibility of underlying system-specific mechanisms and 221 OS functions below the GSS-API to ensure that the ability to acquire 222 and use credentials associated with a given identity is constrained 223 to appropriate processes within a system. This responsibility should 224 be taken seriously by implementors, as the ability for an entity to 225 utilize a principal's credentials is equivalent to the entity's 226 ability to successfully assert that principal's identity. 228 Once a set of GSS-API credentials is established, the transferability 229 of that credentials set to other processes or analogous constructs 230 within a system is a local matter, not defined by the GSS-API. An 231 example local policy would be one in which any credentials received 232 as a result of login to a given user account, or of delegation of 233 rights to that account, are accessible by, or transferable to, 234 processes running under that account. 236 The credential establishment process (particularly when performed on 237 behalf of users rather than server processes) is likely to require 238 access to passwords or other quantities which should be protected 239 locally and exposed for the shortest time possible. As a result, it 240 will often be appropriate for preliminary credential establishment to 241 be performed through local means at user login time, with the 242 result(s) cached for subsequent reference. These preliminary 243 credentials would be set aside (in a system-specific fashion) for 244 subsequent use, either: 246 to be accessed by an invocation of the GSS-API GSS_Acquire_cred() 247 call, returning an explicit handle to reference that credential 249 to comprise default credential elements to be installed, and to be 250 used when default credential behavior is requested on behalf of a 251 process 253 1.1.2: Tokens 255 Tokens are data elements transferred between GSS-API callers, and are 256 divided into two classes. Context-level tokens are exchanged in order 257 to establish and manage a security context between peers. Per-message 258 tokens are exchanged in conjunction with an established context to 259 provide protective security services for corresponding data messages. 260 The internal contents of both classes of tokens are specific to the 261 particular underlying mechanism used to support the GSS-API; Appendix 262 B of this document provides a uniform recommendation for designers of 263 GSS-API support mechanisms, encapsulating mechanism-specific 264 information along with a globally-interpretable mechanism identifier. 266 Tokens are opaque from the viewpoint of GSS-API callers. They are 267 generated within the GSS-API implementation at an end system, 268 provided to a GSS-API caller to be transferred to the peer GSS-API 269 caller at a remote end system, and processed by the GSS-API 270 implementation at that remote end system. Tokens may be output by 271 GSS-API primitives (and are to be transferred to GSS-API peers) 272 independent of the status indications which those primitives 273 indicate. Token transfer may take place in an in-band manner, 274 integrated into the same protocol stream used by the GSS-API callers 275 for other data transfers, or in an out-of-band manner across a 276 logically separate channel. 278 Development of GSS-API support primitives based on a particular 279 underlying cryptographic technique and protocol does not necessarily 280 imply that GSS-API callers invoking that GSS-API mechanism type will 281 be able to interoperate with peers invoking the same technique and 282 protocol outside the GSS-API paradigm. For example, the format of 283 GSS-API tokens defined in conjunction with a particular mechanism, 284 and the techniques used to integrate those tokens into callers' 285 protocols, may not be the same as those used by non-GSS-API callers 286 of the same underlying technique. 288 1.1.3: Security Contexts 289 Security contexts are established between peers, using credentials 290 established locally in conjunction with each peer or received by 291 peers via delegation. Multiple contexts may exist simultaneously 292 between a pair of peers, using the same or different sets of 293 credentials. Coexistence of multiple contexts using different 294 credentials allows graceful rollover when credentials expire. 295 Distinction among multiple contexts based on the same credentials 296 serves applications by distinguishing different message streams in a 297 security sense. 299 The GSS-API is independent of underlying protocols and addressing 300 structure, and depends on its callers to transport GSS-API-provided 301 data elements. As a result of these factors, it is a caller 302 responsibility to parse communicated messages, separating GSS-API- 303 related data elements from caller-provided data. The GSS-API is 304 independent of connection vs. connectionless orientation of the 305 underlying communications service. 307 No correlation between security context and communications protocol 308 association is dictated. (The optional channel binding facility, 309 discussed in Section 1.1.6 of this document, represents an 310 intentional exception to this rule, supporting additional protection 311 features within GSS-API supporting mechanisms.) This separation 312 allows the GSS-API to be used in a wide range of communications 313 environments, and also simplifies the calling sequences of the 314 individual calls. In many cases (depending on underlying security 315 protocol, associated mechanism, and availability of cached 316 information), the state information required for context setup can be 317 sent concurrently with initial signed user data, without interposing 318 additional message exchanges. 320 1.1.4: Mechanism Types 322 In order to successfully establish a security context with a target 323 peer, it is necessary to identify an appropriate underlying mechanism 324 type (mech_type) which both initiator and target peers support. The 325 definition of a mechanism embodies not only the use of a particular 326 cryptographic technology (or a hybrid or choice among alternative 327 cryptographic technologies), but also definition of the syntax and 328 semantics of data element exchanges which that mechanism will employ 329 in order to support security services. 331 It is recommended that callers initiating contexts specify the 332 "default" mech_type value, allowing system-specific functions within 333 or invoked by the GSS-API implementation to select the appropriate 334 mech_type, but callers may direct that a particular mech_type be 335 employed when necessary. 337 The means for identifying a shared mech_type to establish a security 338 context with a peer will vary in different environments and 339 circumstances; examples include (but are not limited to): 341 use of a fixed mech_type, defined by configuration, within an 342 environment 344 syntactic convention on a target-specific basis, through 345 examination of a target's name 347 lookup of a target's name in a naming service or other database in 348 order to identify mech_types supported by that target 350 explicit negotiation between GSS-API callers in advance of 351 security context setup 353 When transferred between GSS-API peers, mech_type specifiers (per 354 Appendix B, represented as Object Identifiers (OIDs)) serve to 355 qualify the interpretation of associated tokens. (The structure and 356 encoding of Object Identifiers is defined in ISO/IEC 8824, 357 "Specification of Abstract Syntax Notation One (ASN.1)" and in 358 ISO/IEC 8825, "Specification of Basic Encoding Rules for Abstract 359 Syntax Notation One (ASN.1)".) Use of hierarchically structured OIDs 360 serves to preclude ambiguous interpretation of mech_type specifiers. 361 The OID representing the DASS MechType, for example, is 362 1.3.12.2.1011.7.5, and that of the Kerberos V5 mechanism, once 363 advanced to the level of Proposed Standard, will be 364 1.2.840.113554.1.2.2. 366 1.1.5: Naming 368 The GSS-API avoids prescription of naming structures, treating the 369 names transferred across the interface in order to initiate and 370 accept security contexts as opaque octet string quantities. This 371 approach supports the GSS-API's goal of implementability atop a range 372 of underlying security mechanisms, recognizing the fact that 373 different mechanisms process and authenticate names which are 374 presented in different forms. Generalized services offering 375 translation functions among arbitrary sets of naming environments are 376 outside the scope of the GSS-API; availability and use of local 377 conversion functions to translate among the naming formats supported 378 within a given end system is anticipated. 380 Three distinct classes of name representations are used in 381 conjunction with different GSS-API parameters: 383 an internal form (denoted by INTERNAL NAME), opaque to callers and 384 defined by individual GSS-API implementations; GSS-API 385 implementations supporting multiple namespace types are 386 responsible for maintaining internal tags to disambiguate the 387 interpretation of particular names 389 a printable form (denoted by OCTET STRING), for acceptance from 390 and presentation to users; printable name forms are accompanied by 391 OID tags identifying the namespace to which they correspond 393 tagged, typed naming objects (denoted by ANY) 395 Tagging of printable names allows GSS-API callers and underlying 396 GSS-API mechanisms to disambiguate name types and to determine 397 whether an associated name's type is one which they are capable of 398 processing, avoiding aliasing problems which could result from 399 misinterpreting a name of one type as a name of another type. 401 In addition to providing means for names to be tagged with types, 402 this specification defines primitives to support a level of naming 403 environment independence for certain calling applications. To provide 404 basic services oriented towards the requirements of callers which 405 need not themselves interpret the internal syntax and semantics of 406 names, GSS-API calls for name comparison (GSS_Compare_name()), 407 human-readable display (GSS_Display_name()), input conversion 408 (GSS_Import_name()), and internal name deallocation 409 (GSS_Release_name()) functions are defined. (It is anticipated that 410 these proposed GSS-API calls will be implemented in many end systems 411 based on system-specific name manipulation primitives already extant 412 within those end systems; inclusion within the GSS-API is intended to 413 offer GSS-API callers a portable means to perform specific 414 operations, supportive of authorization and audit requirements, on 415 authenticated names.) 417 GSS_Import_name() implementations can, where appropriate, support 418 more than one printable syntax corresponding to a given namespace 419 (e.g., alternative printable representations for X.500 Distinguished 420 Names), allowing flexibility for their callers to select among 421 alternative representations. GSS_Display_name() implementations 422 output a printable syntax selected as appropriate to their 423 operational environments; this selection is a local matter. Callers 424 desiring portability across alternative printable syntaxes should 425 refrain from implementing comparisons based on printable name forms 426 and should instead use the GSS_Compare_name() call to determine 427 whether or not one internal-format name matches another. 429 GSS_Import_name_object() and GSS_Export_name_object() routines are 430 incorporated to enable callers to translate between GSS-API internal 431 names and typed naming objects (not necessarily printable) used 432 within their end systems but outside GSS-API. This facility 433 simplifies integration with certain mechanisms and their naming 434 objects; it must be noted, however, that wired-in application 435 dependence on particular mechanism-specific naming representations 436 conflicts with portability goals. 438 1.1.6: Channel Bindings 440 The GSS-API accommodates the concept of caller-provided channel 441 binding ("chan_binding") information. Channel bindings are used to 442 strengthen the quality with which peer entity authentication is 443 provided during context establishment, by limiting the scope within 444 which an intercepted context establishment token can be reused by an 445 attacker. Specifically, they enable GSS-API callers to bind the 446 establishment of a security context to relevant characteristics 447 (e.g., addresses, transformed representations of encryption keys) of 448 the underlying communications channel, of protection mechanisms 449 applied to that communications channel, and to application-specific 450 data. 452 The caller initiating a security context must determine the 453 appropriate channel binding values to provide as input to the 454 GSS_Init_sec_context() call, and consistent values must be provided 455 to GSS_Accept_sec_context() by the context's target, in order for 456 both peers' GSS-API mechanisms to validate that received tokens 457 possess correct channel-related characteristics. Use or non-use of 458 the GSS-API channel binding facility is a caller option. GSS-API 459 mechanisms can operate in an environment where NULL channel bindings 460 are presented; mechanism implementors are encouraged, but not 461 required, to make use of caller-provided channel binding data within 462 their mechanisms. Callers should not assume that underlying 463 mechanisms provide confidentiality protection for channel binding 464 information. 466 When non-NULL channel bindings are provided by callers, certain 467 mechanisms can offer enhanced security value by interpreting the 468 bindings' content (rather than simply representing those bindings, or 469 signatures computed on them, within tokens) and will therefore depend 470 on presentation of specific data in a defined format. To this end, 471 agreements among mechanism implementors are defining conventional 472 interpretations for the contents of channel binding arguments, 473 including address specifiers (with content dependent on 474 communications protocol environment) for context initiators and 475 acceptors. (These conventions are being incorporated in GSS-API 476 mechanism specifications and into the GSS-API C language bindings 477 specification.) In order for GSS-API callers to be portable across 478 multiple mechanisms and achieve the full security functionality which 479 each mechanism can provide, it is strongly recommended that GSS-API 480 callers provide channel bindings consistent with these conventions 481 and those of the networking environment in which they operate. 483 1.2: GSS-API Features and Issues 485 This section describes aspects of GSS-API operations, of the security 486 services which the GSS-API provides, and provides commentary on 487 design issues. 489 1.2.1: Status Reporting 491 Each GSS-API call provides two status return values. Major_status 492 values provide a mechanism-independent indication of call status 493 (e.g., GSS_S_COMPLETE, GSS_S_FAILURE, GSS_S_CONTINUE_NEEDED), 494 sufficient to drive normal control flow within the caller in a 495 generic fashion. Table 1 summarizes the defined major_status return 496 codes in tabular fashion. 498 Table 1: GSS-API Major Status Codes 500 FATAL ERROR CODES 502 GSS_S_BAD_BINDINGS channel binding mismatch 503 GSS_S_BAD_MECH unsupported mechanism requested 504 GSS_S_BAD_NAME invalid name provided 505 GSS_S_BAD_NAMETYPE name of unsupported type provided 506 GSS_S_BAD_STATUS invalid input status selector 507 GSS_S_BAD_SIG token had invalid signature 508 GSS_S_CONTEXT_EXPIRED specified security context expired 509 GSS_S_CREDENTIALS_EXPIRED expired credentials detected 510 GSS_S_DEFECTIVE_CREDENTIAL defective credential detected 511 GSS_S_DEFECTIVE_TOKEN defective token detected 512 GSS_S_FAILURE failure, unspecified at GSS-API 513 level 514 GSS_S_NO_CONTEXT no valid security context specified 515 GSS_S_NO_CRED no valid credentials provided 516 GSS_S_BAD_QOP unsupported QOP value 517 GSS_S_UNAUTHORIZED operation unauthorized 518 GSS_S_UNAVAILABLE operation unavailable 520 INFORMATORY STATUS CODES 522 GSS_S_COMPLETE normal completion 523 GSS_S_CONTINUE_NEEDED continuation call to routine 524 required 525 GSS_S_DUPLICATE_TOKEN duplicate per-message token 526 detected 527 GSS_S_OLD_TOKEN timed-out per-message token 528 detected 530 GSS_S_UNSEQ_TOKEN reordered (early) per-message token 531 detected 532 GSS_S_GAP_TOKEN skipped predecessor token(s) 533 detected 535 Minor_status provides more detailed status information which may 536 include status codes specific to the underlying security mechanism. 537 Minor_status values are not specified in this document. 539 GSS_S_CONTINUE_NEEDED major_status returns, and optional message 540 outputs, are provided in GSS_Init_sec_context() and 541 GSS_Accept_sec_context() calls so that different mechanisms' 542 employment of different numbers of messages within their 543 authentication sequences need not be reflected in separate code paths 544 within calling applications. Instead, such cases are accomodated with 545 sequences of continuation calls to GSS_Init_sec_context() and 546 GSS_Accept_sec_context(). The same mechanism is used to encapsulate 547 mutual authentication within the GSS-API's context initiation calls. 549 For mech_types which require interactions with third-party servers in 550 order to establish a security context, GSS-API context establishment 551 calls may block pending completion of such third-party interactions. 552 On the other hand, no GSS-API calls pend on serialized interactions 553 with GSS-API peer entities. As a result, local GSS-API status 554 returns cannot reflect unpredictable or asynchronous exceptions 555 occurring at remote peers, and reflection of such status information 556 is a caller responsibility outside the GSS-API. 558 1.2.2: Per-Message Security Service Availability 560 When a context is established, two flags are returned to indicate the 561 set of per-message protection security services which will be 562 available on the context: 564 the integ_avail flag indicates whether per-message integrity and 565 data origin authentication services are available 567 the conf_avail flag indicates whether per-message confidentiality 568 services are available, and will never be returned TRUE unless the 569 integ_avail flag is also returned TRUE 571 GSS-API callers desiring per-message security services should 572 check the values of these flags at context establishment time, and 573 must be aware that a returned FALSE value for integ_avail means 574 that invocation of GSS_GetMIC() or GSS_Wrap() primitives on the 575 associated context will apply no cryptographic protection to user 576 data messages. 578 The GSS-API per-message protection service primitives, as the 579 category name implies, are oriented to operation at the granularity 580 of protocol data units. They perform cryptographic operations on the 581 data units, transfer cryptographic control information in tokens, 582 and, in the case of GSS_Wrap(), encapsulate the protected data unit. 583 As such, these primitives are not oriented to efficient data 584 protection for stream-paradigm protocols (e.g., Telnet) if 585 cryptography must be applied on an octet-by-octet basis. 587 1.2.3: Per-Message Replay Detection and Sequencing 589 Certain underlying mech_types are expected to offer support for 590 replay detection and/or sequencing of messages transferred on the 591 contexts they support. These optionally-selectable protection 592 features are distinct from replay detection and sequencing features 593 applied to the context establishment operation itself; the presence 594 or absence of context-level replay or sequencing features is wholly a 595 function of the underlying mech_type's capabilities, and is not 596 selected or omitted as a caller option. 598 The caller initiating a context provides flags (replay_det_req_flag 599 and sequence_req_flag) to specify whether the use of per-message 600 replay detection and sequencing features is desired on the context 601 being established. The GSS-API implementation at the initiator system 602 can determine whether these features are supported (and whether they 603 are optionally selectable) as a function of mech_type, without need 604 for bilateral negotiation with the target. When enabled, these 605 features provide recipients with indicators as a result of GSS-API 606 processing of incoming messages, identifying whether those messages 607 were detected as duplicates or out-of-sequence. Detection of such 608 events does not prevent a suspect message from being provided to a 609 recipient; the appropriate course of action on a suspect message is a 610 matter of caller policy. 612 The semantics of the replay detection and sequencing services applied 613 to received messages, as visible across the interface which the GSS- 614 API provides to its clients, are as follows: 616 When replay_det_state is TRUE, the possible major_status returns for 617 well-formed and correctly signed messages are as follows: 619 1. GSS_S_COMPLETE indicates that the message was within the window 620 (of time or sequence space) allowing replay events to be detected, 621 and that the message was not a replay of a previously-processed 622 message within that window. 624 2. GSS_S_DUPLICATE_TOKEN indicates that the cryptographic 625 checkvalue on the received message was correct, but that the 626 message was recognized as a duplicate of a previously-processed 627 message. 629 3. GSS_S_OLD_TOKEN indicates that the cryptographic checkvalue on 630 the received message was correct, but that the message is too old 631 to be checked for duplication. 633 When sequence_state is TRUE, the possible major_status returns for 634 well-formed and correctly signed messages are as follows: 636 1. GSS_S_COMPLETE indicates that the message was within the window 637 (of time or sequence space) allowing replay events to be detected, 638 that the message was not a replay of a previously-processed 639 message within that window, and that no predecessor sequenced 640 messages are missing relative to the last received message (if 641 any) processed on the context with a correct cryptographic 642 checkvalue. 644 2. GSS_S_DUPLICATE_TOKEN indicates that the signature on the 645 received message was correct, but that the message was recognized 646 as a duplicate of a previously-processed message. 648 3. GSS_S_OLD_TOKEN indicates that the signature on the received 649 message was correct, but that the token is too old to be checked 650 for duplication. 652 4. GSS_S_UNSEQ_TOKEN indicates that the cryptographic checkvalue 653 on the received message was correct, but that it is earlier in a 654 sequenced stream than a message already processed on the context. 655 [Note: Mechanisms can be architected to provide a stricter form of 656 sequencing service, delivering particular messages to recipients 657 only after all predecessor messages in an ordered stream have been 658 delivered. This type of support is incompatible with the GSS-API 659 paradigm in which recipients receive all messages, whether in 660 order or not, and provide them (one at a time, without intra-GSS- 661 API message buffering) to GSS-API routines for validation. GSS- 662 API facilities provide supportive functions, aiding clients to 663 achieve strict message stream integrity in an efficient manner in 664 conjunction with sequencing provisions in communications 665 protocols, but the GSS-API does not offer this level of message 666 stream integrity service by itself.] 668 5. GSS_S_GAP_TOKEN indicates that the cryptographic checkvalue on 669 the received message was correct, but that one or more predecessor 670 sequenced messages have not been successfully processed relative 671 to the last received message (if any) processed on the context 672 with a correct cryptographic checkvalue. 674 As the message stream integrity features (especially sequencing) may 675 interfere with certain applications' intended communications 676 paradigms, and since support for such features is likely to be 677 resource intensive, it is highly recommended that mech_types 678 supporting these features allow them to be activated selectively on 679 initiator request when a context is established. A context initiator 680 and target are provided with corresponding indicators 681 (replay_det_state and sequence_state), signifying whether these 682 features are active on a given context. 684 An example mech_type supporting per-message replay detection could 685 (when replay_det_state is TRUE) implement the feature as follows: The 686 underlying mechanism would insert timestamps in data elements output 687 by GSS_GetMIC() and GSS_Wrap(), and would maintain (within a time- 688 limited window) a cache (qualified by originator-recipient pair) 689 identifying received data elements processed by GSS_VerifyMIC() and 690 GSS_Unwrap(). When this feature is active, exception status returns 691 (GSS_S_DUPLICATE_TOKEN, GSS_S_OLD_TOKEN) will be provided when 692 GSS_VerifyMIC() or GSS_Unwrap() is presented with a message which is 693 either a detected duplicate of a prior message or which is too old to 694 validate against a cache of recently received messages. 696 1.2.4: Quality of Protection 698 Some mech_types will provide their users with fine granularity 699 control over the means used to provide per-message protection, 700 allowing callers to trade off security processing overhead 701 dynamically against the protection requirements of particular 702 messages. A per-message quality-of-protection parameter (analogous to 703 quality-of-service, or QOS) selects among different QOP options 704 supported by that mechanism. On context establishment for a multi-QOP 705 mech_type, context-level data provides the prerequisite data for a 706 range of protection qualities. 708 It is expected that the majority of callers will not wish to exert 709 explicit mechanism-specific QOP control and will therefore request 710 selection of a default QOP. Definitions of, and choices among, non- 711 default QOP values are mechanism-specific, and no ordered sequences 712 of QOP values can be assumed equivalent across different mechanisms. 713 Meaningful use of non-default QOP values demands that callers be 714 familiar with the QOP definitions of an underlying mechanism or 715 mechanisms, and is therefore a non-portable construct. The 716 GSS_S_BAD_QOP major_status value is defined in order to indicate that 717 a provided QOP value is unsupported for a security context, most 718 likely because that value is unrecognized by the underlying 719 mechanism. 721 1.2.5: Anonymity Support 722 In certain situations or environments, an application may wish to 723 authenticate a peer and/or protect communications using GSS-API per- 724 message services without revealing its own identity. For example, 725 consider an application which provides read access to a research 726 database, and which permits queries by arbitrary requestors. A 727 client of such a service might wish to authenticate the service, to 728 establish trust in the information received from it, but might not 729 wish to disclose its identity to the service for privacy reasons. 731 In ordinary GSS-API usage, a context initiator's identity is made 732 available to the context acceptor as part of the context 733 establishment process. To provide for anonymity support, a facility 734 (input anon_req_flag to GSS_Init_sec_context()) is provided through 735 which context initiators may request that their identity not be 736 provided to the context acceptor. Mechanisms are not required to 737 honor this request, but a caller will be informed (via returned 738 anon_state indicator from GSS_Init_sec_context()) whether or not the 739 request is honored. 741 The following Object Identifier value is provided as a means to 742 identify anonymous names: 744 {2(joint-iso-ccitt), 16(country), 840(US(ANSI)), 1(organizations), 745 113687(OpenVision), 1(security), 2(nametypes), 1(anonymous-name)} 747 The recommended symbolic name corresponding to this definition is 748 GSS_C_NAMETYPE_ANONYMOUS. 750 1.2.6: Initialization 752 No initialization calls (i.e., calls which must be invoked prior to 753 invocation of other facilities in the interface) are defined in GSS- 754 API. As an implication of this fact, GSS-API implementations must 755 themselves be self-initializing. 757 2: Interface Descriptions 759 This section describes the GSS-API's service interface, dividing the 760 set of calls offered into four groups. Credential management calls 761 are related to the acquisition and release of credentials by 762 principals. Context-level calls are related to the management of 763 security contexts between principals. Per-message calls are related 764 to the protection of individual messages on established security 765 contexts. Support calls provide ancillary functions useful to GSS-API 766 callers. Table 2 groups and summarizes the calls in tabular fashion. 768 Table 2: GSS-API Calls 770 CREDENTIAL MANAGEMENT 772 GSS_Acquire_cred acquire credentials for use 773 GSS_Release_cred release credentials after use 774 GSS_Inquire_cred display information about 775 credentials 776 GSS_Add_cred construct credentials incrementally 778 CONTEXT-LEVEL CALLS 780 GSS_Init_sec_context initiate outbound security context 781 GSS_Accept_sec_context accept inbound security context 782 GSS_Delete_sec_context flush context when no longer needed 783 GSS_Process_context_token process received control token on 784 context 785 GSS_Context_time indicate validity time remaining on 786 context 787 GSS_Inquire_context display information about context 788 GSS_Wrap_size_limit determine GSS_Wrap token size limit 789 GSS_Export_sec_context transfer context to other process 790 GSS_Import_sec_context import transferred context 792 PER-MESSAGE CALLS 794 GSS_GetMIC apply signature, receive as token 795 separate from message 796 GSS_VerifyMIC validate signature token along with 797 message 798 GSS_Wrap sign, optionally encrypt, 799 encapsulate 800 GSS_Unwrap decapsulate, decrypt if needed, 801 validate signature 803 SUPPORT CALLS 805 GSS_Display_status translate status codes to printable 806 form 807 GSS_Indicate_mechs indicate mech_types supported on 808 local system 809 GSS_Compare_name compare two names for equality 810 GSS_Display_name translate name to printable form 811 GSS_Import_name convert printable name to 812 normalized form 813 GSS_Release_name free storage of normalized-form 814 name 815 GSS_Release_buffer free storage of printable name 816 GSS_Release_oid free storage of OID object 817 GSS_Release_oid_set free storage of OID set object 818 GSS_Import_name_object import name from object 819 GSS_Export_name_object export name to object 820 GSS_Create_empty_oid_set create empty OID set 821 GSS_Add_oid_set_member add member to OID set 822 GSS_Test_oid_set_member test if OID is member of OID set 823 GSS_OID_to_str display OID as string 824 GSS_Str_to_OID construct OID from string 825 GSS_Get_mechs_for_name identify mechanisms supporting name 827 2.1: Credential management calls 829 These GSS-API calls provide functions related to the management of 830 credentials. Their characterization with regard to whether or not 831 they may block pending exchanges with other network entities (e.g., 832 directories or authentication servers) depends in part on OS-specific 833 (extra-GSS-API) issues, so is not specified in this document. 835 The GSS_Acquire_cred() call is defined within the GSS-API in support 836 of application portability, with a particular orientation towards 837 support of portable server applications. It is recognized that (for 838 certain systems and mechanisms) credentials for interactive users may 839 be managed differently from credentials for server processes; in such 840 environments, it is the GSS-API implementation's responsibility to 841 distinguish these cases and the procedures for making this 842 distinction are a local matter. The GSS_Release_cred() call provides 843 a means for callers to indicate to the GSS-API that use of a 844 credentials structure is no longer required. The GSS_Inquire_cred() 845 call allows callers to determine information about a credentials 846 structure. The GSS_Add_cred() call enables callers to append 847 elements to an existing credential structure, as to iteratively 848 construct a multi-mechanism credential. 850 2.1.1 GSS_Acquire_cred call 852 Inputs: 854 o desired_name INTERNAL NAME, -NULL requests locally-determined 855 default 857 o lifetime_req INTEGER,-in seconds; 0 requests default 859 o desired_mechs SET OF OBJECT IDENTIFIER,-empty set requests 860 system-selected default 862 o cred_usage INTEGER-0=INITIATE-AND-ACCEPT, 1=INITIATE-ONLY, 863 2=ACCEPT-ONLY 865 Outputs: 867 o major_status INTEGER, 869 o minor_status INTEGER, 871 o output_cred_handle CREDENTIAL HANDLE, 873 o actual_mechs SET OF OBJECT IDENTIFIER, 875 o lifetime_rec INTEGER -in seconds, or reserved value for 876 INDEFINITE 878 Return major_status codes: 880 o GSS_S_COMPLETE indicates that requested credentials were 881 successfully established, for the duration indicated in 882 lifetime_rec, suitable for the usage requested in cred_usage, 883 for the set of mech_types indicated in actual_mechs, and that 884 those credentials can be referenced for subsequent use with 885 the handle returned in output_cred_handle. 887 o GSS_S_BAD_MECH indicates that a mech_type unsupported by the 888 GSS-API implementation type was requested, causing the 889 credential establishment operation to fail. 891 o GSS_S_BAD_NAMETYPE indicates that the provided desired_name is 892 uninterpretable or of a type unsupported by the supporting 893 GSS-API implementation, so no credentials could be 894 established for the accompanying desired_name. 896 o GSS_S_BAD_NAME indicates that the provided desired_name is 897 inconsistent in terms of internally-incorporated type specifier 898 information, so no credentials could be established for the 899 accompanying desired_name. 901 o GSS_S_FAILURE indicates that credential establishment failed 902 for reasons unspecified at the GSS-API level, including lack 903 of authorization to establish and use credentials associated 904 with the identity named in the input desired_name argument. 906 GSS_Acquire_cred() is used to acquire credentials so that a 907 principal can (as a function of the input cred_usage parameter) 908 initiate and/or accept security contexts under the identity 909 represented by the desired_name input argument. On successful 910 completion, the returned output_cred_handle result provides a handle 911 for subsequent references to the acquired credentials. Typically, 912 single-user client processes requesting that default credential 913 behavior be applied for context establishment purposes will have no 914 need to invoke this call. 916 A caller may provide the value NULL for desired_name, signifying a 917 request for credentials corresponding to a principal identity 918 selected by default for the caller. The procedures used by GSS-API 919 implementations to select the appropriate principal identity in 920 response to such a request are local matters. It is possible that 921 multiple pre-established credentials may exist for the same principal 922 identity (for example, as a result of multiple user login sessions) 923 when GSS_Acquire_cred() is called; the means used in such cases to 924 select a specific credential are local matters. The input 925 lifetime_req argument to GSS_Acquire_cred() may provide useful 926 information for local GSS-API implementations to employ in making 927 this disambiguation in a manner which will best satisfy a caller's 928 intent. 930 The lifetime_rec result indicates the length of time for which the 931 acquired credentials will be valid, as an offset from the present. A 932 mechanism may return a reserved value indicating INDEFINITE if no 933 constraints on credential lifetime are imposed. A caller of 934 GSS_Acquire_cred() can request a length of time for which acquired 935 credentials are to be valid (lifetime_req argument), beginning at the 936 present, or can request credentials with a default validity interval. 937 (Requests for postdated credentials are not supported within the 938 GSS-API.) Certain mechanisms and implementations may bind in 939 credential validity period specifiers at a point preliminary to 940 invocation of the GSS_Acquire_cred() call (e.g., in conjunction with 941 user login procedures). As a result, callers requesting non-default 942 values for lifetime_req must recognize that such requests cannot 943 always be honored and must be prepared to accommodate the use of 944 returned credentials with different lifetimes as indicated in 945 lifetime_rec. 947 The caller of GSS_Acquire_cred() can explicitly specify a set of 948 mech_types which are to be accommodated in the returned credentials 949 (desired_mechs argument), or can request credentials for a system- 950 defined default set of mech_types. Selection of the system-specified 951 default set is recommended in the interests of application 952 portability. The actual_mechs return value may be interrogated by the 953 caller to determine the set of mechanisms with which the returned 954 credentials may be used. 956 2.1.2: GSS_Release_cred call 957 Input: 959 o cred_handle CREDENTIAL HANDLE - NULL specifies that 960 the credential elements used when default credential behavior 961 is requested be released. 963 Outputs: 965 o major_status INTEGER, 967 o minor_status INTEGER 969 Return major_status codes: 971 o GSS_S_COMPLETE indicates that the credentials referenced by the 972 input cred_handle were released for purposes of subsequent 973 access by the caller. The effect on other processes which may 974 be authorized shared access to such credentials is a local 975 matter. 977 o GSS_S_NO_CRED indicates that no release operation was 978 performed, either because the input cred_handle was invalid or 979 because the caller lacks authorization to access the 980 referenced credentials. 982 o GSS_S_FAILURE indicates that the release operation failed for 983 reasons unspecified at the GSS-API level. 985 Provides a means for a caller to explicitly request that credentials 986 be released when their use is no longer required. Note that system- 987 specific credential management functions are also likely to exist, 988 for example to assure that credentials shared among processes are 989 properly deleted when all affected processes terminate, even if no 990 explicit release requests are issued by those processes. Given the 991 fact that multiple callers are not precluded from gaining authorized 992 access to the same credentials, invocation of GSS_Release_cred() 993 cannot be assumed to delete a particular set of credentials on a 994 system-wide basis. 996 2.1.3: GSS_Inquire_cred call 998 Input: 1000 o cred_handle CREDENTIAL HANDLE -NULL specifies that the 1001 credential elements used when default credential behavior is 1002 requested are to be queried 1004 Outputs: 1006 o major_status INTEGER, 1008 o minor_status INTEGER, 1010 o cred_name INTERNAL NAME, 1012 o lifetime_rec INTEGER -in seconds, or reserved value for 1013 INDEFINITE 1015 o cred_usage INTEGER, -0=INITIATE-AND-ACCEPT, 1=INITIATE-ONLY, 1016 2=ACCEPT-ONLY 1018 o mech_set SET OF OBJECT IDENTIFIER 1020 Return major_status codes: 1022 o GSS_S_COMPLETE indicates that the credentials referenced by the 1023 input cred_handle argument were valid, and that the output 1024 cred_name, lifetime_rec, and cred_usage values represent, 1025 respectively, the credentials' associated principal name, 1026 remaining lifetime, suitable usage modes, and supported 1027 mechanism types. 1029 o GSS_S_NO_CRED indicates that no information could be returned 1030 about the referenced credentials, either because the input 1031 cred_handle was invalid or because the caller lacks 1032 authorization to access the referenced credentials. 1034 o GSS_S_FAILURE indicates that the release operation failed for 1035 reasons unspecified at the GSS-API level. 1037 The GSS_Inquire_cred() call is defined primarily for the use of 1038 those callers which request use of default credential behavior rather 1039 than acquiring credentials explicitly with GSS_Acquire_cred(). It 1040 enables callers to determine a credential structure's associated 1041 principal name, remaining validity period, usability for security 1042 context initiation and/or acceptance, and supported mechanisms. 1044 2.1.4: GSS_Add_cred call 1046 Inputs: 1048 o cred_handle CREDENTIAL HANDLE - handle to credential structure 1049 created with prior GSS_Acquire_cred() or GSS_Add_cred() call, 1050 or NULL to append elements to the set applied for the caller 1051 when default credential behavior is specified. 1053 o desired_name INTERNAL NAME - NULL requests locally-determined 1054 default 1056 o lifetime_req INTEGER - in seconds; 0 requests default 1058 o desired_mech OBJECT IDENTIFIER 1060 o cred_usage INTEGER - 0=INITIATE-AND-ACCEPT, 1=INITIATE-ONLY, 1061 2=ACCEPT-ONLY 1063 Outputs: 1065 o major_status INTEGER, 1067 o minor_status INTEGER, 1069 o output_cred_handle CREDENTIAL HANDLE, 1071 o actual_mechs SET OF OBJECT IDENTIFIER, 1073 o lifetime_rec INTEGER -in seconds, or reserved value for 1074 INDEFINITE 1076 o cred_usage INTEGER, -0=INITIATE-AND-ACCEPT, 1=INITIATE-ONLY, 1077 2=ACCEPT-ONLY 1079 o mech_set SET OF OBJECT IDENTIFIER 1081 Return major_status codes: 1083 o GSS_S_COMPLETE indicates that the credentials referenced by 1084 the input cred_handle argument were valid, and that the 1085 output_cred_handle references a credential valid for the 1086 duration indicated in lifetime_rec, suitable for the usage 1087 requested in cred_usage, and for the mechanisms indicated in 1088 actual_mechs. 1090 o GSS_S_BAD_MECH indicates that the input desired_mech specified 1091 a mechanism unsupported by the GSS-API implementation, causing 1092 the GSS_Add_cred() operation to fail. 1094 o GSS_S_BAD_NAMETYPE indicates that the provided desired_name is 1095 is uninterpretable or of a type unsupported by the GSS-API 1096 implementation, so the GSS_Add_cred() operation could not be 1097 performed for that name. 1099 o GSS_S_BAD_NAME indicates that the provided desired_name is 1100 inconsistent in terms of internally-incorporated type specifier 1101 information, so the GSS_Add_cred() operation could not be 1102 performed for that name. 1104 o GSS_S_NO_CRED indicates that the input cred_handle referenced 1105 invalid or inaccessible credentials. 1107 o GSS_S_FAILURE indicates that the release operation failed for 1108 reasons unspecified at the GSS-API level, including lack of 1109 authorization to establish or use credentials representing 1110 the requested identity. 1112 GSS_Add_cred() enables callers to construct credentials iteratively 1113 through successive operations. This offers particular value in 1114 multi-mechanism environments, as the major_status and minor_status 1115 values returned on each iteration are individually visible and can 1116 therefore be interpreted unambiguously on a per-mechanism basis. 1118 The same input desired_name, or default reference, should be used on 1119 all GSS_Acquire_cred() and GSS_Add_cred() calls corresponding to a 1120 particular credential. 1122 2.2: Context-level calls 1124 This group of calls is devoted to the establishment and management of 1125 security contexts between peers. A context's initiator calls 1126 GSS_Init_sec_context(), resulting in generation of a token which the 1127 caller passes to the target. At the target, that token is passed to 1128 GSS_Accept_sec_context(). Depending on the underlying mech_type and 1129 specified options, additional token exchanges may be performed in the 1130 course of context establishment; such exchanges are accommodated by 1131 GSS_S_CONTINUE_NEEDED status returns from GSS_Init_sec_context() and 1132 GSS_Accept_sec_context(). 1134 Either party to an established context may invoke 1135 GSS_Delete_sec_context() to flush context information when a context 1136 is no longer required. GSS_Process_context_token() is used to 1137 process received tokens carrying context-level control information. 1138 GSS_Context_time() allows a caller to determine the length of time 1139 for which an established context will remain valid. 1140 GSS_Inquire_context() returns status information describing context 1141 characteristics. GSS_Wrap_size_limit() allows a caller to determine 1142 the size of a token which will be generated by a GSS_Wrap() 1143 operation. GSS_Export_sec_context() and GSS_Import_sec_context() 1144 enable transfer of active contexts between processes on an end 1145 system. 1147 2.2.1: GSS_Init_sec_context call 1149 Inputs: 1151 o claimant_cred_handle CREDENTIAL HANDLE, -NULL specifies "use 1152 default" 1154 o input_context_handle CONTEXT HANDLE, -0 specifies "none assigned 1155 yet" 1157 o targ_name INTERNAL NAME, 1159 o mech_type OBJECT IDENTIFIER, -NULL parameter specifies "use 1160 default" 1162 o deleg_req_flag BOOLEAN, 1164 o mutual_req_flag BOOLEAN, 1166 o replay_det_req_flag BOOLEAN, 1168 o sequence_req_flag BOOLEAN, 1170 o anon_req_flag BOOLEAN, 1172 o lifetime_req INTEGER,-0 specifies default lifetime 1174 o chan_bindings OCTET STRING, 1176 o input_token OCTET STRING-NULL or token received from target 1178 Outputs: 1180 o major_status INTEGER, 1182 o minor_status INTEGER, 1184 o output_context_handle CONTEXT HANDLE, 1186 o mech_type OBJECT IDENTIFIER, -actual mechanism always 1187 indicated, never NULL 1189 o output_token OCTET STRING, -NULL or token to pass to context 1190 target 1192 o deleg_state BOOLEAN, 1194 o mutual_state BOOLEAN, 1196 o replay_det_state BOOLEAN, 1198 o sequence_state BOOLEAN, 1199 o anon_state BOOLEAN, 1201 o trans_state BOOLEAN, 1203 o conf_avail BOOLEAN, 1205 o integ_avail BOOLEAN, 1207 o lifetime_rec INTEGER - in seconds, or reserved value for 1208 INDEFINITE 1210 This call may block pending network interactions for those mech_types 1211 in which an authentication server or other network entity must be 1212 consulted on behalf of a context initiator in order to generate an 1213 output_token suitable for presentation to a specified target. 1215 Return major_status codes: 1217 o GSS_S_COMPLETE indicates that context-level information was 1218 successfully initialized, and that the returned output_token 1219 will provide sufficient information for the target to perform 1220 per-message processing on the newly-established context. 1222 o GSS_S_CONTINUE_NEEDED indicates that control information in the 1223 returned output_token must be sent to the target, and that a 1224 reply must be received and passed as the input_token argument 1225 to a continuation call to GSS_Init_sec_context(), before 1226 per-message processing can be performed in conjunction with 1227 this context. 1229 o GSS_S_DEFECTIVE_TOKEN indicates that consistency checks 1230 performed on the input_token failed, preventing further 1231 processing from being performed based on that token. 1233 o GSS_S_DEFECTIVE_CREDENTIAL indicates that consistency checks 1234 performed on the credential structure referenced by 1235 claimant_cred_handle failed, preventing further processing from 1236 being performed using that credential structure. 1238 o GSS_S_BAD_SIG indicates that the received input_token 1239 contains an incorrect signature, so context setup cannot be 1240 accomplished. 1242 o GSS_S_NO_CRED indicates that no context was established, 1243 either because the input cred_handle was invalid, because the 1244 referenced credentials are valid for context acceptor use 1245 only, or because the caller lacks authorization to access the 1246 referenced credentials. 1248 o GSS_S_CREDENTIALS_EXPIRED indicates that the credentials 1249 provided through the input claimant_cred_handle argument are no 1250 longer valid, so context establishment cannot be completed. 1252 o GSS_S_BAD_BINDINGS indicates that a mismatch between the 1253 caller-provided chan_bindings and those extracted from the 1254 input_token was detected, signifying a security-relevant 1255 event and preventing context establishment. (This result will 1256 be returned by GSS_Init_sec_context only for contexts where 1257 mutual_state is TRUE.) 1259 o GSS_S_NO_CONTEXT indicates that no valid context was recognized 1260 for the input context_handle provided; this major status will 1261 be returned only for successor calls following GSS_S_CONTINUE_ 1262 NEEDED status returns. 1264 o GSS_S_BAD_NAMETYPE indicates that the provided targ_name is 1265 of a type uninterpretable or unsupported by the supporting 1266 GSS-API implementation, so context establishment cannot be 1267 completed. 1269 o GSS_S_BAD_NAME indicates that the provided targ_name is 1270 inconsistent in terms of internally-incorporated type specifier 1271 information, so context establishment cannot be accomplished. 1273 o GSS_S_BAD_MECH indicates receipt of a context establishment token 1274 or of a caller request specifying a mechanism unsupported by 1275 the local system or with the caller's active credentials 1277 o GSS_S_FAILURE indicates that context setup could not be 1278 accomplished for reasons unspecified at the GSS-API level, and 1279 that no interface-defined recovery action is available. 1281 This routine is used by a context initiator, and ordinarily emits one 1282 (or, for the case of a multi-step exchange, more than one) 1283 output_token suitable for use by the target within the selected 1284 mech_type's protocol. Using information in the credentials structure 1285 referenced by claimant_cred_handle, GSS_Init_sec_context() 1286 initializes the data structures required to establish a security 1287 context with target targ_name. The claimant_cred_handle must 1288 correspond to the same valid credentials structure on the initial 1289 call to GSS_Init_sec_context() and on any successor calls resulting 1290 from GSS_S_CONTINUE_NEEDED status returns; different protocol 1291 sequences modeled by the GSS_S_CONTINUE_NEEDED facility will require 1292 access to credentials at different points in the context 1293 establishment sequence. 1295 The input_context_handle argument is 0, specifying "not yet 1296 assigned", on the first GSS_Init_sec_context() call relating to a 1297 given context. If successful (i.e., if accompanied by major_status 1298 GSS_S_COMPLETE or GSS_S_CONTINUE_NEEDED), and only if successful, the 1299 initial GSS_Init_sec_context() call returns a non-zero 1300 output_context_handle for use in future references to this context. 1301 Once a non-zero output_context_handle has been returned, GSS-API 1302 callers should call GSS_Delete_sec_context() to release context- 1303 related resources if errors occur in later phases of context 1304 establishment, or when an established context is no longer required. 1306 When continuation attempts to GSS_Init_sec_context() are needed to 1307 perform context establishment, the previously-returned non-zero 1308 handle value is entered into the input_context_handle argument and 1309 will be echoed in the returned output_context_handle argument. On 1310 such continuation attempts (and only on continuation attempts) the 1311 input_token value is used, to provide the token returned from the 1312 context's target. 1314 The chan_bindings argument is used by the caller to provide 1315 information binding the security context to security-related 1316 characteristics (e.g., addresses, cryptographic keys) of the 1317 underlying communications channel. See Section 1.1.6 of this document 1318 for more discussion of this argument's usage. 1320 The input_token argument contains a message received from the target, 1321 and is significant only on a call to GSS_Init_sec_context() which 1322 follows a previous return indicating GSS_S_CONTINUE_NEEDED 1323 major_status. 1325 It is the caller's responsibility to establish a communications path 1326 to the target, and to transmit any returned output_token (independent 1327 of the accompanying returned major_status value) to the target over 1328 that path. The output_token can, however, be transmitted along with 1329 the first application-provided input message to be processed by 1330 GSS_GetMIC() or GSS_Wrap() in conjunction with a successfully- 1331 established context. 1333 The initiator may request various context-level functions through 1334 input flags: the deleg_req_flag requests delegation of access rights, 1335 the mutual_req_flag requests mutual authentication, the 1336 replay_det_req_flag requests that replay detection features be 1337 applied to messages transferred on the established context, and the 1338 sequence_req_flag requests that sequencing be enforced. (See Section 1339 1.2.3 for more information on replay detection and sequencing 1340 features.) The anon_req_flag requests that the initiator's identity 1341 not be transferred within tokens to be sent to the acceptor. 1343 Not all of the optionally-requestable features will be available in 1344 all underlying mech_types. The corresponding return state values 1345 deleg_state, mutual_state, replay_det_state, and sequence_state 1346 indicate, as a function of mech_type processing capabilities and 1347 initiator-provided input flags, the set of features which will be 1348 active on the context. The returned trans_state value indicates 1349 whether the context is transferable to other processes through use of 1350 GSS_Export_sec_context(). These state indicators' values are 1351 undefined unless the routine's major_status indicates GSS_S_COMPLETE. 1353 The returned anon_state value, unlike the other feature indicators, 1354 has a defined value not only when GSS_Init_sec_context() returns 1355 GSS_S_COMPLETE but also when GSS_S_CONTINUE_NEEDED is returned. When 1356 anon_state is returned TRUE, this indicates that neither the current 1357 token nor its predecessors delivers or has delivered the initiator's 1358 identity. Callers wishing to perform context establishment only if 1359 anonymity support is provided should transfer a returned token from 1360 GSS_Init_sec_context() to the peer only if it is accompanied by a 1361 TRUE anon_state indicator. 1363 Failure to provide the precise set of features requested by the 1364 caller does not cause context establishment to fail; it is the 1365 caller's prerogative to delete the context if the feature set 1366 provided is unsuitable for the caller's use. 1368 The returned mech_type value indicates the specific mechanism 1369 employed on the context, is valid only along with major_status 1370 GSS_S_COMPLETE, and will never indicate the value for "default". 1371 Note that, for the case of certain mechanisms which themselves 1372 perform negotiation, the returned mech_type result may indicate 1373 selection of a mechanism identified by an OID different than that 1374 passed in the input mech_type argument. 1376 The conf_avail return value indicates whether the context supports 1377 per-message confidentiality services, and so informs the caller 1378 whether or not a request for encryption through the conf_req_flag 1379 input to GSS_Wrap() can be honored. In similar fashion, the 1380 integ_avail return value indicates whether per-message integrity 1381 services are available (through either GSS_GetMIC() or GSS_Wrap()) 1382 on the established context. 1384 The lifetime_req input specifies a desired upper bound for the 1385 lifetime of the context to be established, with a value of 0 used to 1386 request a default lifetime. The lifetime_rec return value indicates 1387 the length of time for which the context will be valid, expressed as 1388 an offset from the present; depending on mechanism capabilities, 1389 credential lifetimes, and local policy, it may not correspond to the 1390 value requested in lifetime_req. If no constraints on context 1391 lifetime are imposed, this may be indicated by returning a reserved 1392 value representing INDEFINITE lifetime_req. The values of conf_avail, 1393 integ_avail, and lifetime_rec are undefined unless the routine's 1394 major_status indicates GSS_S_COMPLETE. 1396 If the mutual_state is TRUE, this fact will be reflected within the 1397 output_token. A call to GSS_Accept_sec_context() at the target in 1398 conjunction with such a context will return a token, to be processed 1399 by a continuation call to GSS_Init_sec_context(), in order to 1400 achieve mutual authentication. 1402 2.2.2: GSS_Accept_sec_context call 1404 Inputs: 1406 o acceptor_cred_handle CREDENTIAL HANDLE,-NULL specifies "use 1407 default" 1409 o input_context_handle CONTEXT HANDLE, -0 specifies "not yet assigned" 1411 o chan_bindings OCTET STRING, 1413 o input_token OCTET STRING 1415 Outputs: 1417 o major_status INTEGER, 1419 o minor_status INTEGER, 1421 o src_name INTERNAL NAME, 1423 o mech_type OBJECT IDENTIFIER, 1425 o output_context_handle CONTEXT HANDLE, 1427 o deleg_state BOOLEAN, 1429 o mutual_state BOOLEAN, 1431 o replay_det_state BOOLEAN, 1433 o sequence_state BOOLEAN, 1435 o anon_state BOOLEAN, 1437 o trans_state BOOLEAN, 1439 o conf_avail BOOLEAN, 1440 o integ_avail BOOLEAN, 1442 o lifetime_rec INTEGER, - in seconds, or reserved value for 1443 INDEFINITE 1445 o delegated_cred_handle CREDENTIAL HANDLE, 1447 o output_token OCTET STRING -NULL or token to pass to context 1448 initiator 1450 This call may block pending network interactions for those mech_types 1451 in which a directory service or other network entity must be 1452 consulted on behalf of a context acceptor in order to validate a 1453 received input_token. 1455 Return major_status codes: 1457 o GSS_S_COMPLETE indicates that context-level data structures 1458 were successfully initialized, and that per-message processing 1459 can now be performed in conjunction with this context. 1461 o GSS_S_CONTINUE_NEEDED indicates that control information in the 1462 returned output_token must be sent to the initiator, and that 1463 a response must be received and passed as the input_token 1464 argument to a continuation call to GSS_Accept_sec_context(), 1465 before per-message processing can be performed in conjunction 1466 with this context. 1468 o GSS_S_DEFECTIVE_TOKEN indicates that consistency checks performed 1469 on the input_token failed, preventing further processing from 1470 being performed based on that token. 1472 o GSS_S_DEFECTIVE_CREDENTIAL indicates that consistency checks 1473 performed on the credential structure referenced by 1474 acceptor_cred_handle failed, preventing further processing from being 1475 performed using that credential structure. 1477 o GSS_S_BAD_SIG indicates that the received input_token contains 1478 an incorrect signature, so context setup cannot be accomplished. 1480 o GSS_S_DUPLICATE_TOKEN indicates that the signature on the 1481 received input_token was correct, but that the input_token 1482 was recognized as a duplicate of an input_token already 1483 processed. No new context is established. 1485 o GSS_S_OLD_TOKEN indicates that the signature on the received 1486 input_token was correct, but that the input_token is too old 1487 to be checked for duplication against previously-processed 1488 input_tokens. No new context is established. 1490 o GSS_S_NO_CRED indicates that no context was established, either 1491 because the input cred_handle was invalid, because the 1492 referenced credentials are valid for context initiator use 1493 only, or because the caller lacks authorization to access the 1494 referenced credentials. 1496 o GSS_S_CREDENTIALS_EXPIRED indicates that the credentials provided 1497 through the input acceptor_cred_handle argument are no 1498 longer valid, so context establishment cannot be completed. 1500 o GSS_S_BAD_BINDINGS indicates that a mismatch between the 1501 caller-provided chan_bindings and those extracted from the 1502 input_token was detected, signifying a security-relevant 1503 event and preventing context establishment. 1505 o GSS_S_NO_CONTEXT indicates that no valid context was recognized 1506 for the input context_handle provided; this major status will 1507 be returned only for successor calls following GSS_S_CONTINUE_ 1508 NEEDED status returns. 1510 o GSS_S_BAD_MECH indicates receipt of a context establishment token 1511 specifying a mechanism unsupported by the local system or with 1512 the caller's active credentials. 1514 o GSS_S_FAILURE indicates that context setup could not be accomplished 1515 for reasons unspecified at the GSS-API level, and 1516 that no interface-defined recovery action is available. 1518 The GSS_Accept_sec_context() routine is used by a context target. 1519 Using information in the credentials structure referenced by the 1520 input acceptor_cred_handle, it verifies the incoming input_token and 1521 (following the successful completion of a context establishment 1522 sequence) returns the authenticated src_name and the mech_type used. 1523 The acceptor_cred_handle must correspond to the same valid 1524 credentials structure on the initial call to GSS_Accept_sec_context() 1525 and on any successor calls resulting from GSS_S_CONTINUE_NEEDED 1526 status returns; different protocol sequences modeled by the 1527 GSS_S_CONTINUE_NEEDED mechanism will require access to credentials at 1528 different points in the context establishment sequence. 1530 The input_context_handle argument is 0, specifying "not yet 1531 assigned", on the first GSS_Accept_sec_context() call relating to a 1532 given context. If successful (i.e., if accompanied by major_status 1533 GSS_S_COMPLETE or GSS_S_CONTINUE_NEEDED), and only if successful, the 1534 initial GSS_Accept_sec_context() call returns a non-zero 1535 output_context_handle for use in future references to this context. 1537 Once a non-zero output_context_handle has been returned, GSS-API 1538 callers should call GSS_Delete_sec_context() to release context- 1539 related resources if errors occur in later phases of context 1540 establishment, or when an established context is no longer required. 1542 The chan_bindings argument is used by the caller to provide 1543 information binding the security context to security-related 1544 characteristics (e.g., addresses, cryptographic keys) of the 1545 underlying communications channel. See Section 1.1.6 of this document 1546 for more discussion of this argument's usage. 1548 The returned state results (deleg_state, mutual_state, 1549 replay_det_state, sequence_state, anon_state, and trans_state) 1550 reflect the same context state values as returned to 1551 GSS_Init_sec_context()'s caller at the initiator system. 1553 The conf_avail return value indicates whether the context supports 1554 per-message confidentiality services, and so informs the caller 1555 whether or not a request for encryption through the conf_req_flag 1556 input to GSS_Wrap() can be honored. In similar fashion, the 1557 integ_avail return value indicates whether per-message integrity 1558 services are available (through either GSS_GetMIC() or GSS_Wrap()) 1559 on the established context. 1561 The lifetime_rec return value indicates the length of time for which 1562 the context will be valid, expressed as an offset from the present. 1563 The values of deleg_state, mutual_state, replay_det_state, 1564 sequence_state, anon_state, trans_state, conf_avail, integ_avail, and 1565 lifetime_rec are undefined unless the accompanying major_status 1566 indicates GSS_S_COMPLETE. 1568 The mech_type return value indicates the specific mechanism employed 1569 on the context, is valid only along with major_status GSS_S_COMPLETE, 1570 and will never indicate the value for "default". 1572 The delegated_cred_handle result is significant only when deleg_state 1573 is TRUE, and provides a means for the target to reference the 1574 delegated credentials. The output_token result, when non-NULL, 1575 provides a context-level token to be returned to the context 1576 initiator to continue a multi-step context establishment sequence. As 1577 noted with GSS_Init_sec_context(), any returned token should be 1578 transferred to the context's peer (in this case, the context 1579 initiator), independent of the value of the accompanying returned 1580 major_status. 1582 Note: A target must be able to distinguish a context-level 1583 input_token, which is passed to GSS_Accept_sec_context(), from the 1584 per-message data elements passed to GSS_VerifyMIC() or GSS_Unwrap(). 1586 These data elements may arrive in a single application message, and 1587 GSS_Accept_sec_context() must be performed before per-message 1588 processing can be performed successfully. 1590 2.2.3: GSS_Delete_sec_context call 1592 Input: 1594 o context_handle CONTEXT HANDLE 1596 Outputs: 1598 o major_status INTEGER, 1600 o minor_status INTEGER, 1602 o output_context_token OCTET STRING 1604 Return major_status codes: 1606 o GSS_S_COMPLETE indicates that the context was recognized, that 1607 relevant context-specific information was flushed, and that 1608 the returned output_context_token, if requested via caller 1609 provision of a non-null buffer for receipt of said token, 1610 is ready for transfer to the context's peer. 1612 o GSS_S_NO_CONTEXT indicates that no valid context was recognized 1613 for the input context_handle provide, so no deletion was 1614 performed. 1616 o GSS_S_FAILURE indicates that the context is recognized, but 1617 that the GSS_Delete_sec_context() operation could not be 1618 performed for reasons unspecified at the GSS-API level. 1620 This call may block pending network interactions for mech_types in 1621 which active notification must be made to a central server when a 1622 security context is to be deleted. 1624 This call can be made by either peer in a security context, to flush 1625 context-specific information. If a non-null output_context_token 1626 parameter is provided, an output_context_token will be returned, and 1627 can be passed to the context's peer to inform the peer's GSS-API 1628 implementation that the peer's corresponding context information can 1629 also be flushed. (Once a context is established, the peers involved 1630 are expected to retain cached credential and context-related 1631 information until the information's expiration time is reached or 1632 until a GSS_Delete_sec_context() call is made.) 1633 The facility for context_token usage to signal context deletion is 1634 retained for compatibility with GSS-API Version 1. For current 1635 usage, it is recommended that both peers to a context invoke 1636 GSS_Delete_sec_context() independently, passing a null 1637 output_context_token buffer to indicate that no context_token is 1638 required. Implementations of GSS_Delete_sec_context() should delete 1639 relevant locally-stored context information. 1641 Attempts to perform per-message processing on a deleted context will 1642 result in error returns. 1644 2.2.4: GSS_Process_context_token call 1646 Inputs: 1648 o context_handle CONTEXT HANDLE, 1650 o input_context_token OCTET STRING 1652 Outputs: 1654 o major_status INTEGER, 1656 o minor_status INTEGER, 1658 Return major_status codes: 1660 o GSS_S_COMPLETE indicates that the input_context_token was 1661 successfully processed in conjunction with the context 1662 referenced by context_handle. 1664 o GSS_S_DEFECTIVE_TOKEN indicates that consistency checks 1665 performed on the received context_token failed, preventing 1666 further processing from being performed with that token. 1668 o GSS_S_NO_CONTEXT indicates that no valid context was recognized 1669 for the input context_handle provided. 1671 o GSS_S_FAILURE indicates that the context is recognized, but 1672 that the GSS_Process_context_token() operation could not be 1673 performed for reasons unspecified at the GSS-API level. 1675 This call is used to process context_tokens received from a peer once 1676 a context has been established, with corresponding impact on 1677 context-level state information. One use for this facility is 1678 processing of the context_tokens generated by 1679 GSS_Delete_sec_context(); GSS_Process_context_token() will not block 1680 pending network interactions for that purpose. Another use is to 1681 process tokens indicating remote-peer context establishment failures 1682 after the point where the local GSS-API implementation has already 1683 indicated GSS_S_COMPLETE status. 1685 2.2.5: GSS_Context_time call 1687 Input: 1689 o context_handle CONTEXT HANDLE, 1691 Outputs: 1693 o major_status INTEGER, 1695 o minor_status INTEGER, 1697 o lifetime_rec INTEGER - in seconds, or reserved value for 1698 INDEFINITE 1700 Return major_status codes: 1702 o GSS_S_COMPLETE indicates that the referenced context is valid, 1703 and will remain valid for the amount of time indicated in 1704 lifetime_rec. 1706 o GSS_S_CONTEXT_EXPIRED indicates that data items related to the 1707 referenced context have expired. 1709 o GSS_S_CREDENTIALS_EXPIRED indicates that the context is recognized, 1710 but that its associated credentials have expired. 1712 o GSS_S_NO_CONTEXT indicates that no valid context was recognized 1713 for the input context_handle provided. 1715 o GSS_S_FAILURE indicates that the requested operation failed for 1716 reasons unspecified at the GSS-API level. 1718 This call is used to determine the amount of time for which a 1719 currently established context will remain valid. 1721 2.2.6: GSS_Inquire_context call 1723 Input: 1725 o context_handle INTEGER, 1727 Outputs: 1729 o major_status INTEGER, 1731 o minor_status INTEGER, 1733 o src_name INTERNAL NAME, -- name of context initiator 1735 o targ_name INTERNAL NAME, -- name of context target 1737 o lifetime_rec INTEGER -- in seconds, or reserved value for 1738 INDEFINITE, 1740 o mech_type OBJECT IDENTIFIER, -- the mechanism supporting this 1741 security context 1743 o deleg_state BOOLEAN, 1745 o mutual_state BOOLEAN, 1747 o replay_det_state BOOLEAN, 1749 o sequence_state BOOLEAN, 1751 o anon_state BOOLEAN, 1753 o trans_state BOOLEAN, 1755 o conf_avail BOOLEAN, 1757 o integ_avail BOOLEAN, 1759 o locally_initiated BOOLEAN, -- TRUE if initiator, FALSE if acceptor 1761 Return major_status codes: 1763 o GSS_S_COMPLETE indicates that the referenced context is valid 1764 and that src_name, targ_name, lifetime_rec, mech_type, deleg_state, 1765 mutual_state, replay_det_state, sequence_state, anon_state, 1766 trans_state, conf_avail, integ_avail, and locally_initiated 1767 return values describe the corresponding characteristics of 1768 the context. 1770 o GSS_S_CONTEXT_EXPIRED indicates that the provided input context_handle 1771 is recognized, but that the referenced context has expired. Return 1772 values other than major_status and minor_status are undefined. 1774 o GSS_S_NO_CONTEXT indicates that no valid context was recognized 1775 for the input context_handle provided. Return values other than 1776 major_status and minor_status are undefined. 1778 o GSS_S_FAILURE indicates that the requested operation failed for 1779 reasons unspecified at the GSS-API level. Return values other than 1780 major_status and minor_status are undefined. 1782 This call is used to extract information describing characteristics 1783 of a security context. 1785 2.2.7: GSS_Wrap_size_limit call 1787 Inputs: 1789 o context_handle INTEGER, 1791 o qop INTEGER, 1793 o output_size INTEGER 1795 Outputs: 1797 o major_status INTEGER, 1799 o minor_status INTEGER, 1801 o max_input_size INTEGER 1803 Return major_status codes: 1805 o GSS_S_COMPLETE indicates a successful token size determination: 1806 an input message with a length in octets equal to the 1807 returned max_input_size value will, when passed to GSS_Wrap() 1808 for processing on the context identified by the context_handle 1809 parameter and with the quality of protection specifier provided 1810 in the qop parameter, yield an output token no larger than the 1811 value of the provided output_size parameter. 1813 o GSS_S_CONTEXT_EXPIRED indicates that the provided input context_handle 1814 is recognized, but that the referenced context has expired. Return 1815 values other than major_status and minor_status are undefined. 1817 o GSS_S_NO_CONTEXT indicates that no valid context was recognized 1818 for the input context_handle provided. Return values other than 1819 major_status and minor_status are undefined. 1821 o GSS_S_BAD_QOP indicates that the provided QOP value is not 1822 recognized or supported for the context. 1824 o GSS_S_FAILURE indicates that the requested operation failed for 1825 reasons unspecified at the GSS-API level. Return values other than 1826 major_status and minor_status are undefined. 1828 This call is used to determine the largest input datum which may be 1829 passed to GSS_Wrap() without yielding an output token larger than a 1830 caller-specified value. 1832 2.2.8: GSS_Export_sec_context call 1834 Inputs: 1836 o context_handle INTEGER 1838 Outputs: 1840 o major_status INTEGER, 1842 o minor_status INTEGER, 1844 o interprocess_token OCTET STRING 1846 Return major_status codes: 1848 o GSS_S_COMPLETE indicates that the referenced context has been 1849 successfully exported to a representation in the interprocess_token, 1850 and is no longer available for use by the caller. 1852 o GSS_S_UNAVAILABLE indicates that the context export facility 1853 is not available for use on the referenced context. (This status 1854 should occur only for contexts for which the trans_state value is 1855 FALSE.) Return values other than major_status and minor_status are 1856 undefined. 1858 o GSS_S_CONTEXT_EXPIRED indicates that the provided input context_handle 1859 is recognized, but that the referenced context has expired. Return 1860 values other than major_status and minor_status are undefined. 1862 o GSS_S_NO_CONTEXT indicates that no valid context was recognized 1863 for the input context_handle provided. Return values other than 1864 major_status and minor_status are undefined. 1866 o GSS_S_FAILURE indicates that the requested operation failed for 1867 reasons unspecified at the GSS-API level. Return values other than 1868 major_status and minor_status are undefined. 1870 This call generates an interprocess token for transfer to another 1871 process within an end system, in order to transfer control of a 1872 security context to that process. The recipient of the interprocess 1873 token will call GSS_Import_sec_context() to accept the transfer. 1875 The internal representation contained within the interprocess token 1876 is an implementation-defined local matter. Interprocess tokens 1877 cannot be assumed to be transferable across different GSS-API 1878 implementations. It is recommended that implementations supporting 1879 context transfer protect the transferred context data, either by 1880 using cryptography to protect data within the tokens or by using 1881 interprocess tokens as a means to reference local interprocess 1882 communication facilities (protected by other means) rather than 1883 storing the context data directly within the tokens. 1885 Transfer of an open context may, for certain mechanisms and 1886 implementations, reveal data about the credential which was used to 1887 establish the context. Callers should, therefore, be cautious about 1888 the trustworthiness of processes to which they transfer contexts. 1890 2.2.9: GSS_Import_sec_context call 1892 Inputs: 1894 o interprocess_token OCTET STRING 1896 Outputs: 1898 o major_status INTEGER, 1900 o minor_status INTEGER, 1902 o context_handle CONTEXT HANDLE 1904 Return major_status codes: 1906 o GSS_S_COMPLETE indicates that the context represented by the 1907 input interprocess_token has been successfully transferred to 1908 the caller, and is available for future use via the output 1909 context_handle. 1911 o GSS_S_CONTEXT_EXPIRED indicates that the context represented by 1912 the input interprocess_token has expired. Return values other 1913 than major_status and minor_status are undefined. 1915 o GSS_S_NO_CONTEXT indicates that the context represented by the 1916 input interprocess_token was invalid. Return values other than 1917 major_status and minor_status are undefined. 1919 o GSS_S_DEFECTIVE_TOKEN indicates that the input interprocess_token 1920 was defective. Return values other than major_status and minor_status 1921 are undefined. 1923 o GSS_S_UNAVAILABLE indicates that the context import facility 1924 is not available for use on the referenced context. Return values 1925 other than major_status and minor_status are undefined. 1927 o GSS_S_UNAUTHORIZED indicates that the context represented by 1928 the input interprocess_token is unauthorized for transfer to the 1929 caller. Return values other than major_status and minor_status 1930 are undefined. 1932 o GSS_S_FAILURE indicates that the requested operation failed for 1933 reasons unspecified at the GSS-API level. Return values other than 1934 major_status and minor_status are undefined. 1936 This call processes an interprocess token generated by 1937 GSS_Export_sec_context(), making the transferred context available 1938 for use by the caller. After a successful GSS_Import_sec_context() 1939 operation, the imported context is fully and exclusively owned by the 1940 importing process. 1942 It is recommended that GSS-API implementations adopt policies suited 1943 to their operational environments in order to define the set of 1944 processes eligible to import a context, but specific constraints in 1945 this area are local matters. Candidate examples include transfers 1946 between processes operating on behalf of the same user identity, or 1947 processes comprising a common job. 1949 2.3: Per-message calls 1951 This group of calls is used to perform per-message protection 1952 processing on an established security context. None of these calls 1953 block pending network interactions. These calls may be invoked by a 1954 context's initiator or by the context's target. The four members of 1955 this group should be considered as two pairs; the output from 1956 GSS_GetMIC() is properly input to GSS_VerifyMIC(), and the output 1957 from GSS_Wrap() is properly input to GSS_Unwrap(). 1959 GSS_GetMIC() and GSS_VerifyMIC() support data origin authentication 1960 and data integrity services. When GSS_GetMIC() is invoked on an 1961 input message, it yields a per-message token containing data items 1962 which allow underlying mechanisms to provide the specified security 1963 services. The original message, along with the generated per-message 1964 token, is passed to the remote peer; these two data elements are 1965 processed by GSS_VerifyMIC(), which validates the message in 1966 conjunction with the separate token. 1968 GSS_Wrap() and GSS_Unwrap() support caller-requested confidentiality 1969 in addition to the data origin authentication and data integrity 1970 services offered by GSS_GetMIC() and GSS_VerifyMIC(). GSS_Wrap() 1971 outputs a single data element, encapsulating optionally enciphered 1972 user data as well as associated token data items. The data element 1973 output from GSS_Wrap() is passed to the remote peer and processed by 1974 GSS_Unwrap() at that system. GSS_Unwrap() combines decipherment (as 1975 required) with validation of data items related to authentication and 1976 integrity. 1978 2.3.1: GSS_GetMIC call 1980 Note: This call is functionally equivalent to the GSS_Sign call as 1981 defined in previous versions of this specification. In the interests 1982 of backward compatibility, it is recommended that implementations 1983 support this function under both names for the present; future 1984 references to this function as GSS_Sign are deprecated. 1986 Inputs: 1988 o context_handle CONTEXT HANDLE, 1990 o qop_req INTEGER,-0 specifies default QOP 1992 o message OCTET STRING 1994 Outputs: 1996 o major_status INTEGER, 1998 o minor_status INTEGER, 2000 o per_msg_token OCTET STRING 2002 Return major_status codes: 2004 o GSS_S_COMPLETE indicates that a signature, suitable for an 2005 established security context, was successfully applied and 2006 that the message and corresponding per_msg_token are ready 2007 for transmission. 2009 o GSS_S_CONTEXT_EXPIRED indicates that context-related data 2010 items have expired, so that the requested operation cannot be 2011 performed. 2013 o GSS_S_CREDENTIALS_EXPIRED indicates that the context is recognized, 2014 but that its associated credentials have expired, so 2015 that the requested operation cannot be performed. 2017 o GSS_S_NO_CONTEXT indicates that no valid context was recognized 2018 for the input context_handle provided. 2020 o GSS_S_BAD_QOP indicates that the provided QOP value is not 2021 recognized or supported for the context. 2023 o GSS_S_FAILURE indicates that the context is recognized, but 2024 that the requested operation could not be performed for 2025 reasons unspecified at the GSS-API level. 2027 Using the security context referenced by context_handle, apply a 2028 signature to the input message (along with timestamps and/or other 2029 data included in support of mech_type-specific mechanisms) and return 2030 the result in per_msg_token. The qop_req parameter, interpretation of 2031 which is discussed in Section 1.2.4, allows quality-of-protection 2032 control. The caller passes the message and the per_msg_token to the 2033 target. 2035 The GSS_GetMIC() function completes before the message and 2036 per_msg_token is sent to the peer; successful application of 2037 GSS_GetMIC() does not guarantee that a corresponding GSS_VerifyMIC() 2038 has been (or can necessarily be) performed successfully when the 2039 message arrives at the destination. 2041 2.3.2: GSS_VerifyMIC call 2043 Note: This call is functionally equivalent to the GSS_Verify call as 2044 defined in previous versions of this specification. In the interests 2045 of backward compatibility, it is recommended that implementations 2046 support this function under both names for the present; future 2047 references to this function as GSS_Verify are deprecated. 2049 Inputs: 2051 o context_handle CONTEXT HANDLE, 2053 o message OCTET STRING, 2055 o per_msg_token OCTET STRING 2057 Outputs: 2059 o qop_state INTEGER, 2060 o major_status INTEGER, 2062 o minor_status INTEGER, 2064 Return major_status codes: 2066 o GSS_S_COMPLETE indicates that the message was successfully 2067 verified. 2069 o GSS_S_DEFECTIVE_TOKEN indicates that consistency checks performed 2070 on the received per_msg_token failed, preventing 2071 further processing from being performed with that token. 2073 o GSS_S_BAD_SIG indicates that the received per_msg_token contains 2074 an incorrect signature for the message. 2076 o GSS_S_DUPLICATE_TOKEN, GSS_S_OLD_TOKEN, GSS_S_UNSEQ_TOKEN, 2077 and GSS_S_GAP_TOKEN values appear in conjunction with the 2078 optional per-message replay detection features described 2079 in Section 1.2.3; their semantics are described in that section. 2081 o GSS_S_CONTEXT_EXPIRED indicates that context-related data 2082 items have expired, so that the requested operation cannot be 2083 performed. 2085 o GSS_S_CREDENTIALS_EXPIRED indicates that the context is recognized, 2086 but that its associated credentials have expired, so 2087 that the requested operation cannot be performed. 2089 o GSS_S_NO_CONTEXT indicates that no valid context was recognized 2090 for the input context_handle provided. 2092 o GSS_S_FAILURE indicates that the context is recognized, but 2093 that the GSS_VerifyMIC() operation could not be performed for 2094 reasons unspecified at the GSS-API level. 2096 Using the security context referenced by context_handle, verify that 2097 the input per_msg_token contains an appropriate signature for the 2098 input message, and apply any active replay detection or sequencing 2099 features. Return an indication of the quality-of-protection applied 2100 to the processed message in the qop_state result. 2102 2.3.3: GSS_Wrap call 2104 Note: This call is functionally equivalent to the GSS_Seal call as 2105 defined in previous versions of this specification. In the interests 2106 of backward compatibility, it is recommended that implementations 2107 support this function under both names for the present; future 2108 references to this function as GSS_Seal are deprecated. 2110 Inputs: 2112 o context_handle CONTEXT HANDLE, 2114 o conf_req_flag BOOLEAN, 2116 o qop_req INTEGER,-0 specifies default QOP 2118 o input_message OCTET STRING 2120 Outputs: 2122 o major_status INTEGER, 2124 o minor_status INTEGER, 2126 o conf_state BOOLEAN, 2128 o output_message OCTET STRING 2130 Return major_status codes: 2132 o GSS_S_COMPLETE indicates that the input_message was successfully 2133 processed and that the output_message is ready for 2134 transmission. 2136 o GSS_S_CONTEXT_EXPIRED indicates that context-related data 2137 items have expired, so that the requested operation cannot be 2138 performed. 2140 o GSS_S_CREDENTIALS_EXPIRED indicates that the context is recognized, 2141 but that its associated credentials have expired, so 2142 that the requested operation cannot be performed. 2144 o GSS_S_NO_CONTEXT indicates that no valid context was recognized 2145 for the input context_handle provided. 2147 o GSS_S_BAD_QOP indicates that the provided QOP value is not 2148 recognized or supported for the context. 2150 o GSS_S_FAILURE indicates that the context is recognized, but 2151 that the GSS_Wrap() operation could not be performed for 2152 reasons unspecified at the GSS-API level. 2154 Performs the data origin authentication and data integrity functions 2155 of GSS_GetMIC(). If the input conf_req_flag is TRUE, requests that 2156 confidentiality be applied to the input_message. Confidentiality may 2157 not be supported in all mech_types or by all implementations; the 2158 returned conf_state flag indicates whether confidentiality was 2159 provided for the input_message. The qop_req parameter, interpretation 2160 of which is discussed in Section 1.2.4, allows quality-of-protection 2161 control. 2163 In all cases, the GSS_Wrap() call yields a single output_message 2164 data element containing (optionally enciphered) user data as well as 2165 control information. 2167 2.3.4: GSS_Unwrap call 2169 Note: This call is functionally equivalent to the GSS_Unseal call as 2170 defined in previous versions of this specification. In the interests 2171 of backward compatibility, it is recommended that implementations 2172 support this function under both names for the present; future 2173 references to this function as GSS_Unseal are deprecated. 2175 Inputs: 2177 o context_handle CONTEXT HANDLE, 2179 o input_message OCTET STRING 2181 Outputs: 2183 o conf_state BOOLEAN, 2185 o qop_state INTEGER, 2187 o major_status INTEGER, 2189 o minor_status INTEGER, 2191 o output_message OCTET STRING 2193 Return major_status codes: 2195 o GSS_S_COMPLETE indicates that the input_message was 2196 successfully processed and that the resulting output_message is 2197 available. 2199 o GSS_S_DEFECTIVE_TOKEN indicates that consistency checks performed 2200 on the per_msg_token extracted from the input_message 2201 failed, preventing further processing from being performed. 2203 o GSS_S_BAD_SIG indicates that an incorrect signature was detected 2204 for the message. 2206 o GSS_S_DUPLICATE_TOKEN, GSS_S_OLD_TOKEN, GSS_S_UNSEQ_TOKEN, 2207 and GSS_S_GAP_TOKEN values appear in conjunction with the 2208 optional per-message replay detection features described 2209 in Section 1.2.3; their semantics are described in that section. 2211 o GSS_S_CONTEXT_EXPIRED indicates that context-related data 2212 items have expired, so that the requested operation cannot be 2213 performed. 2215 o GSS_S_CREDENTIALS_EXPIRED indicates that the context is recognized, 2216 but that its associated credentials have expired, so 2217 that the requested operation cannot be performed. 2219 o GSS_S_NO_CONTEXT indicates that no valid context was recognized 2220 for the input context_handle provided. 2222 o GSS_S_FAILURE indicates that the context is recognized, but 2223 that the GSS_Unwrap() operation could not be performed for 2224 reasons unspecified at the GSS-API level. 2226 Processes a data element generated (and optionally enciphered) by 2227 GSS_Wrap(), provided as input_message. The returned conf_state value 2228 indicates whether confidentiality was applied to the input_message. 2229 If conf_state is TRUE, GSS_Unwrap() deciphers the input_message. 2230 Returns an indication of the quality-of-protection applied to the 2231 processed message in the qop_state result. GSS_Wrap() performs the 2232 data integrity and data origin authentication checking functions of 2233 GSS_VerifyMIC() on the plaintext data. Plaintext data is returned in 2234 output_message. 2236 2.4: Support calls 2238 This group of calls provides support functions useful to GSS-API 2239 callers, independent of the state of established contexts. Their 2240 characterization with regard to blocking or non-blocking status in 2241 terms of network interactions is unspecified. 2243 2.4.1: GSS_Display_status call 2245 Inputs: 2247 o status_value INTEGER,-GSS-API major_status or minor_status 2248 return value 2250 o status_type INTEGER,-1 if major_status, 2 if minor_status 2251 o mech_type OBJECT IDENTIFIER-mech_type to be used for minor_ 2252 status translation 2254 Outputs: 2256 o major_status INTEGER, 2258 o minor_status INTEGER, 2260 o status_string_set SET OF OCTET STRING 2262 Return major_status codes: 2264 o GSS_S_COMPLETE indicates that a valid printable status representation 2265 (possibly representing more than one status event 2266 encoded within the status_value) is available in the returned 2267 status_string_set. 2269 o GSS_S_BAD_MECH indicates that translation in accordance with an 2270 unsupported mech_type was requested, so translation could not 2271 be performed. 2273 o GSS_S_BAD_STATUS indicates that the input status_value was 2274 invalid, or that the input status_type carried a value other 2275 than 1 or 2, so translation could not be performed. 2277 o GSS_S_FAILURE indicates that the requested operation could not 2278 be performed for reasons unspecified at the GSS-API level. 2280 Provides a means for callers to translate GSS-API-returned major and 2281 minor status codes into printable string representations. 2283 2.4.2: GSS_Indicate_mechs call 2285 Input: 2287 o (none) 2289 Outputs: 2291 o major_status INTEGER, 2293 o minor_status INTEGER, 2295 o mech_set SET OF OBJECT IDENTIFIER 2297 Return major_status codes: 2299 o GSS_S_COMPLETE indicates that a set of available mechanisms has 2300 been returned in mech_set. 2302 o GSS_S_FAILURE indicates that the requested operation could not 2303 be performed for reasons unspecified at the GSS-API level. 2305 Allows callers to determine the set of mechanism types available on 2306 the local system. This call is intended for support of specialized 2307 callers who need to request non-default mech_type sets from 2308 GSS_Acquire_cred(), and should not be needed by other callers. 2310 2.4.3: GSS_Compare_name call 2312 Inputs: 2314 o name1 INTERNAL NAME, 2316 o name2 INTERNAL NAME 2318 Outputs: 2320 o major_status INTEGER, 2322 o minor_status INTEGER, 2324 o name_equal BOOLEAN 2326 Return major_status codes: 2328 o GSS_S_COMPLETE indicates that name1 and name2 were comparable, 2329 and that the name_equal result indicates whether name1 and 2330 name2 represent the same entity. 2332 o GSS_S_BAD_NAMETYPE indicates that one or both of name1 and 2333 name2 contained internal type specifiers uninterpretable 2334 by the supporting GSS-API implementation, or that the two 2335 names' types are different and incomparable, so that the 2336 comparison operation could not be completed. 2338 o GSS_S_BAD_NAME indicates that one or both of the input names 2339 was ill-formed in terms of its internal type specifier, so 2340 the comparison operation could not be completed. 2342 o GSS_S_FAILURE indicates that the call's operation could not 2343 be performed for reasons unspecified at the GSS-API level. 2345 Allows callers to compare two internal name representations to 2346 determine whether they refer to the same entity. If either name 2347 presented to GSS_Compare_name() denotes an anonymous principal, 2348 GSS_Compare_name() shall indicate FALSE. 2350 2.4.4: GSS_Display_name call 2352 Inputs: 2354 o name INTERNAL NAME 2356 Outputs: 2358 o major_status INTEGER, 2360 o minor_status INTEGER, 2362 o name_string OCTET STRING, 2364 o name_type OBJECT IDENTIFIER 2366 Return major_status codes: 2368 o GSS_S_COMPLETE indicates that a valid printable name 2369 representation is available in the returned name_string. 2371 o GSS_S_BAD_NAMETYPE indicates that the provided name was of a 2372 type uninterpretable by the supporting GSS-API implementation, 2373 so no printable representation could be generated. 2375 o GSS_S_BAD_NAME indicates that the contents of the provided name 2376 were inconsistent with the internally-indicated name type, so 2377 no printable representation could be generated. 2379 o GSS_S_FAILURE indicates that the requested operation could not 2380 be performed for reasons unspecified at the GSS-API level. 2382 Allows callers to translate an internal name representation into a 2383 printable form with associated namespace type descriptor. The syntax 2384 of the printable form is a local matter. 2386 If the input name represents an anonymous identity, a reserved value 2387 (GSS_C_NAMETYPE_ANONYMOUS) shall be returned for name_type. 2389 2.4.5: GSS_Import_name call 2391 Inputs: 2393 o input_name_string OCTET STRING, 2394 o input_name_type OBJECT IDENTIFIER 2396 Outputs: 2398 o major_status INTEGER, 2400 o minor_status INTEGER, 2402 o output_name INTERNAL NAME 2404 Return major_status codes: 2406 o GSS_S_COMPLETE indicates that a valid name representation is 2407 output in output_name and described by the type value in 2408 output_name_type. 2410 o GSS_S_BAD_NAMETYPE indicates that the input_name_type is unsupported 2411 by the GSS-API implementation, so the import operation 2412 could not be completed. 2414 o GSS_S_BAD_NAME indicates that the provided input_name_string 2415 is ill-formed in terms of the input_name_type, so the import 2416 operation could not be completed. 2418 o GSS_S_FAILURE indicates that the requested operation could not 2419 be performed for reasons unspecified at the GSS-API level. 2421 Allows callers to provide a printable name representation, designate 2422 the type of namespace in conjunction with which it should be parsed, 2423 and convert that printable representation to an internal form 2424 suitable for input to other GSS-API routines. The syntax of the 2425 input_name_string is a local matter. Note: The input_name_type 2426 argument serves to describe and qualify the interpretation of the 2427 associated input_name_string; it does not specify the data type of 2428 the returned output_name. 2430 2.4.6: GSS_Release_name call 2432 Inputs: 2434 o name INTERNAL NAME 2436 Outputs: 2438 o major_status INTEGER, 2440 o minor_status INTEGER 2441 Return major_status codes: 2443 o GSS_S_COMPLETE indicates that the storage associated with the 2444 input name was successfully released. 2446 o GSS_S_BAD_NAME indicates that the input name argument did not 2447 contain a valid name. 2449 o GSS_S_FAILURE indicates that the requested operation could not 2450 be performed for reasons unspecified at the GSS-API level. 2452 Allows callers to release the storage associated with an internal 2453 name representation. 2455 2.4.7: GSS_Release_buffer call 2457 Inputs: 2459 o buffer OCTET STRING 2461 Outputs: 2463 o major_status INTEGER, 2465 o minor_status INTEGER 2467 Return major_status codes: 2469 o GSS_S_COMPLETE indicates that the storage associated with the 2470 input buffer was successfully released. 2472 o GSS_S_FAILURE indicates that the requested operation could not 2473 be performed for reasons unspecified at the GSS-API level. 2475 Allows callers to release the storage associated with an OCTET STRING 2476 buffer allocated by another GSS-API call. 2478 2.4.8: GSS_Release_oid_set call 2480 Inputs: 2482 o buffer SET OF OBJECT IDENTIFIER 2484 Outputs: 2486 o major_status INTEGER, 2488 o minor_status INTEGER 2489 Return major_status codes: 2491 o GSS_S_COMPLETE indicates that the storage associated with the 2492 input object identifier set was successfully released. 2494 o GSS_S_FAILURE indicates that the requested operation could not 2495 be performed for reasons unspecified at the GSS-API level. 2497 Allows callers to release the storage associated with an object 2498 identifier set object allocated by another GSS-API call. 2500 2.4.9: GSS_Import_name_object call 2502 Inputs: 2504 o input_name ANY, 2506 o name_type OBJECT IDENTIFIER 2508 Outputs: 2510 o major_status INTEGER, 2512 o minor_status INTEGER, 2514 o output_name INTERNAL NAME 2516 Return major_status codes: 2518 o GSS_S_COMPLETE indicates that a valid GSS-API internal 2519 name representation, corresponding to the contents of 2520 input_name, is output in output_name. 2522 o GSS_S_BAD_NAMETYPE indicates that the input name_type is 2523 unsupported by the GSS-API implementation, so the import 2524 operation could not be completed. 2526 o GSS_S_BAD_NAME indicates that the contents of the input_name 2527 object are ill-formed in terms of the input name_type, so the 2528 import operation could not be completed. 2530 o GSS_S_FAILURE indicates that the requested operation could not 2531 be performed for reasons unspecified at the GSS-API level. 2533 Converts an input_name object, with type identified by name_type, 2534 into a GSS-API internal name represented by output_name. 2536 Implementors should note that use of this routine, and associated 2537 mechanism-specific name objects, by an application is a construct 2538 unlikely to be portable to other mechanisms. 2540 2.4.10: GSS_Export_name_object call 2542 Inputs: 2544 o input_name INTERNAL NAME, 2546 o desired_name_type OBJECT IDENTIFIER 2548 Outputs: 2550 o major_status INTEGER, 2552 o minor_status INTEGER, 2554 o output_name ANY 2556 Return major_status codes: 2558 o GSS_S_COMPLETE indicates that a valid name object, with type 2559 corresponding to desired_name_type and contents corresponding 2560 to input_name, is output in output_name. 2562 o GSS_S_BAD_NAMETYPE indicates that the requested desired_name_type 2563 was uninterpretable or unsupported by the GSS-API implementation, 2564 so no output_name object could be generated. 2566 o GSS_S_BAD_NAME indicates that the contents of the provided 2567 input_name could not be converted into an output_name object 2568 of the requested desired_name_type. 2570 o GSS_S_FAILURE indicates that the requested operation could not 2571 be performed for reasons unspecified at the GSS-API level. 2573 Converts a GSS_API internal name, specified by input_name, into a 2574 name object representation specified by output_name and with the type 2575 specified by desired_name_type. Note that it may not be possible to 2576 convert all input_name values or types into all supported 2577 desired_name_types. Implementors should note that use of this 2578 routine, and associated mechanism-specific name objects, by an 2579 application is a construct unlikely to be portable to other 2580 mechanisms. 2582 2.4.11: GSS_Create_empty_OID_set call 2584 Inputs: 2586 o (none) 2588 Outputs: 2590 o major_status INTEGER, 2592 o minor_status INTEGER, 2594 o oid_set SET OF OBJECT IDENTIFIER 2596 Return major_status codes: 2598 o GSS_S_COMPLETE indicates successful completion 2600 o GSS_S_FAILURE indicates that the operation failed 2602 Creates an object identifier set containing no object identifiers, to 2603 which members may be subsequently added using the 2604 GSS_Add_OID_set_member() routine. These routines are intended to be 2605 used to construct sets of mechanism object identifiers, for input to 2606 GSS_Acquire_cred(). 2608 2.4.12: GSS_Add_OID_set_member call 2610 Inputs: 2612 o member_OID OBJECT IDENTIFIER, 2614 o oid_set SET OF OBJECT IDENTIFIER 2616 Outputs: 2618 o major_status INTEGER, 2620 o minor_status INTEGER, 2622 Return major_status codes: 2624 o GSS_S_COMPLETE indicates successful completion 2626 o GSS_S_FAILURE indicates that the operation failed 2627 Adds an Object Identifier to an Object Identifier set. This routine 2628 is intended for use in conjunction with GSS_Create_empty_OID_set() 2629 when constructing a set of mechanism OIDs for input to 2630 GSS_Acquire_cred(). 2632 2.4.13: GSS_Test_oid_set_member call 2634 Inputs: 2636 o member OBJECT IDENTIFIER, 2638 o set SET OF OBJECT IDENTIFIER 2640 Outputs: 2642 o major_status INTEGER, 2644 o minor_status INTEGER, 2646 o present BOOLEAN 2648 Return major_status codes: 2650 o GSS_S_COMPLETE indicates successful completion 2652 o GSS_S_FAILURE indicates that the operation failed 2654 Interrogates an Object Identifier set to determine whether a 2655 specified Object Identifier is a member. This routine is intended to 2656 be used with OID sets returned by GSS_Indicate_mechs(), 2657 GSS_Acquire_cred(), and GSS_Inquire_cred(). 2659 2.4.14: GSS_Release_OID call 2661 Inputs: 2663 o oid OBJECT IDENTIFIER 2665 Outputs: 2667 o major_status INTEGER, 2669 o minor_status INTEGER 2671 Return major_status codes: 2673 o GSS_S_COMPLETE indicates successful completion 2675 o GSS_S_FAILURE indicates that the operation failed 2677 Discards an OID. This routine is provided for completeness only. 2678 While some of the GSS-API routines return OIDs, these routines are 2679 currently documented as returning pointers to structures maintained 2680 in static storage. GSS_Release_OID() will recognise any of the GSS- 2681 API's own OID values, and will silently ignore attempts to free these 2682 OIDs; for other OIDs it will call the local language environment's 2683 equivalent of C's "free()" routine for both the OID data and the 2684 descriptor. This allows applications to freely mix their own heap- 2685 allocated OID values with OIDs returned by GSS-API. 2687 2.4.15: GSS_OID_to_str call 2689 Inputs: 2691 o oid OBJECT IDENTIFIER 2693 Outputs: 2695 o major_status INTEGER, 2697 o minor_status INTEGER, 2699 o oid_str PRINTABLE STRING 2701 Return major_status codes: 2703 o GSS_S_COMPLETE indicates successful completion 2705 o GSS_S_FAILURE indicates that the operation failed 2707 The function GSS_OID_to_str() returns a string allocated from the 2708 free store representing the OID in printable form (e.g., "1.2.3.3"). 2709 The string is suitable for release using the function "free()" for C, 2710 or by its functional equivalent in other language environments. An 2711 empty string (i.e., "") is returned if NULL is passed. 2713 2.4.16: GSS_Str_to_OID call 2715 Inputs: 2717 o oid_str PRINTABLE STRING 2719 Outputs: 2721 o major_status INTEGER, 2723 o minor_status INTEGER, 2725 o oid OBJECT IDENTIFIER 2727 Return major_status codes: 2729 o GSS_S_COMPLETE indicates successful completion 2731 o GSS_S_FAILURE indicates that the operation failed 2733 The function GSS_Str_to_OID() constructs and returns an OID from its 2734 printable form (i.e., "1.2.3.3"). The OID is allocated from the free 2735 store suitable for release using the function GSS_OID_free(). An 2736 empty OID is returned if an empty string or NULL is passed. 2738 2.4.17: GSS_Get_mechs_for_name call 2740 Inputs: 2742 o input_is_external BOOLEAN, -- TRUE if input is external name 2743 -- FALSE if input is internal name 2745 o input_name_string OCTET STRING, -- for external name 2747 o input_name_type OBJECT IDENTIFIER, -- type for external name 2749 o input_int_name INTERNAL NAME -- if providing internal name 2751 Outputs: 2753 o major_status INTEGER, 2755 o minor_status INTEGER, 2757 o oid_set SET OF OBJECT IDENTIFIER 2759 Return major_status codes: 2761 o GSS_S_COMPLETE indicates that the output oid_set contains 2762 a list of locally supported mechanisms capable of supporting 2763 the input name. 2765 o GSS_S_BAD_NAMETYPE indicates (when an external name is 2766 provided) that the input_name_type is unsupported 2767 by the GSS-API implementation, so the operation could not be 2768 completed. Return values other than major_status and 2769 minor_status are undefined. 2771 o GSS_S_BAD_NAME indicates (when an external name is provided) 2772 that the provided input_name_string is ill-formed in terms 2773 of the input_name_type, so the operation could not be completed. 2774 Return values other than major_status and minor_status are 2775 undefined. 2777 o GSS_S_FAILURE indicates that the requested operation could not 2778 be performed for reasons unspecified at the GSS-API level. 2780 Allows callers to determine the set of locally supported mechanisms 2781 capable of supporting a name. Callers may use the input_is_external 2782 flag as a means to indicate that they are providing either an 2783 external name and type specifier, as would be provided to 2784 GSS_Import_name(), or an internal name as would be provided to 2785 GSS_Init_sec_context(). 2787 3: Mechanism-Specific Example Scenarios 2789 This section provides illustrative overviews of the use of various 2790 candidate mechanism types to support the GSS-API. These discussions 2791 are intended primarily for readers familiar with specific security 2792 technologies, demonstrating how GSS-API functions can be used and 2793 implemented by candidate underlying mechanisms. They should not be 2794 regarded as constrictive to implementations or as defining the only 2795 means through which GSS-API functions can be realized with a 2796 particular underlying technology, and do not demonstrate all GSS-API 2797 features with each technology. 2799 3.1: Kerberos V5, single-TGT 2801 OS-specific login functions yield a TGT to the local realm Kerberos 2802 server; TGT is placed in a credentials structure for the client. 2803 Client calls GSS_Acquire_cred() to acquire a cred_handle in order to 2804 reference the credentials for use in establishing security contexts. 2806 Client calls GSS_Init_sec_context(). If the requested service is 2807 located in a different realm, GSS_Init_sec_context() gets the 2808 necessary TGT/key pairs needed to traverse the path from local to 2809 target realm; these data are placed in the owner's TGT cache. After 2810 any needed remote realm resolution, GSS_Init_sec_context() yields a 2811 service ticket to the requested service with a corresponding session 2812 key; these data are stored in conjunction with the context. GSS-API 2813 code sends KRB_TGS_REQ request(s) and receives KRB_TGS_REP 2814 response(s) (in the successful case) or KRB_ERROR. 2816 Assuming success, GSS_Init_sec_context() builds a Kerberos-formatted 2817 KRB_AP_REQ message, and returns it in output_token. The client sends 2818 the output_token to the service. 2820 The service passes the received token as the input_token argument to 2821 GSS_Accept_sec_context(), which verifies the authenticator, provides 2822 the service with the client's authenticated name, and returns an 2823 output_context_handle. 2825 Both parties now hold the session key associated with the service 2826 ticket, and can use this key in subsequent GSS_GetMIC(), 2827 GSS_VerifyMIC(), GSS_Wrap(), and GSS_Unwrap() operations. 2829 3.2: Kerberos V5, double-TGT 2831 TGT acquisition as above. 2833 Note: To avoid unnecessary frequent invocations of error paths when 2834 implementing the GSS-API atop Kerberos V5, it seems appropriate to 2835 represent "single-TGT K-V5" and "double-TGT K-V5" with separate 2836 mech_types, and this discussion makes that assumption. 2838 Based on the (specified or defaulted) mech_type, 2839 GSS_Init_sec_context() determines that the double-TGT protocol 2840 should be employed for the specified target. GSS_Init_sec_context() 2841 returns GSS_S_CONTINUE_NEEDED major_status, and its returned 2842 output_token contains a request to the service for the service's TGT. 2843 (If a service TGT with suitably long remaining lifetime already 2844 exists in a cache, it may be usable, obviating the need for this 2845 step.) The client passes the output_token to the service. Note: this 2846 scenario illustrates a different use for the GSS_S_CONTINUE_NEEDED 2847 status return facility than for support of mutual authentication; 2848 note that both uses can coexist as successive operations within a 2849 single context establishment operation. 2851 The service passes the received token as the input_token argument to 2852 GSS_Accept_sec_context(), which recognizes it as a request for TGT. 2853 (Note that current Kerberos V5 defines no intra-protocol mechanism to 2854 represent such a request.) GSS_Accept_sec_context() returns 2855 GSS_S_CONTINUE_NEEDED major_status and provides the service's TGT in 2856 its output_token. The service sends the output_token to the client. 2858 The client passes the received token as the input_token argument to a 2859 continuation of GSS_Init_sec_context(). GSS_Init_sec_context() 2860 caches the received service TGT and uses it as part of a service 2861 ticket request to the Kerberos authentication server, storing the 2862 returned service ticket and session key in conjunction with the 2863 context. GSS_Init_sec_context() builds a Kerberos-formatted 2864 authenticator, and returns it in output_token along with 2865 GSS_S_COMPLETE return major_status. The client sends the output_token 2866 to the service. 2868 Service passes the received token as the input_token argument to a 2869 continuation call to GSS_Accept_sec_context(). 2870 GSS_Accept_sec_context() verifies the authenticator, provides the 2871 service with the client's authenticated name, and returns 2872 major_status GSS_S_COMPLETE. 2874 GSS_GetMIC(), GSS_VerifyMIC(), GSS_Wrap(), and GSS_Unwrap() as 2875 above. 2877 3.3: X.509 Authentication Framework 2879 This example illustrates use of the GSS-API in conjunction with 2880 public-key mechanisms, consistent with the X.509 Directory 2881 Authentication Framework. 2883 The GSS_Acquire_cred() call establishes a credentials structure, 2884 making the client's private key accessible for use on behalf of the 2885 client. 2887 The client calls GSS_Init_sec_context(), which interrogates the 2888 Directory to acquire (and validate) a chain of public-key 2889 certificates, thereby collecting the public key of the service. The 2890 certificate validation operation determines that suitable signatures 2891 were applied by trusted authorities and that those certificates have 2892 not expired. GSS_Init_sec_context() generates a secret key for use 2893 in per-message protection operations on the context, and enciphers 2894 that secret key under the service's public key. 2896 The enciphered secret key, along with an authenticator quantity 2897 signed with the client's private key, is included in the output_token 2898 from GSS_Init_sec_context(). The output_token also carries a 2899 certification path, consisting of a certificate chain leading from 2900 the service to the client; a variant approach would defer this path 2901 resolution to be performed by the service instead of being asserted 2902 by the client. The client application sends the output_token to the 2903 service. 2905 The service passes the received token as the input_token argument to 2906 GSS_Accept_sec_context(). GSS_Accept_sec_context() validates the 2907 certification path, and as a result determines a certified binding 2908 between the client's distinguished name and the client's public key. 2909 Given that public key, GSS_Accept_sec_context() can process the 2910 input_token's authenticator quantity and verify that the client's 2911 private key was used to sign the input_token. At this point, the 2912 client is authenticated to the service. The service uses its private 2913 key to decipher the enciphered secret key provided to it for per- 2914 message protection operations on the context. 2916 The client calls GSS_GetMIC() or GSS_Wrap() on a data message, which 2917 causes per-message authentication, integrity, and (optional) 2918 confidentiality facilities to be applied to that message. The service 2919 uses the context's shared secret key to perform corresponding 2920 GSS_VerifyMIC() and GSS_Unwrap() calls. 2922 4: Mechanism-Independent Token Format 2924 This section specifies a mechanism-independent level of encapsulating 2925 representation for the initial token of a GSS-API context 2926 establishment sequence, incorporating an identifier of the mechanism 2927 type to be used on that context and enabling tokens to be interpreted 2928 unambiguously at GSS-API peers. Use of this format (with ASN.1- 2929 encoded data elements represented in BER, constrained in the 2930 interests of parsing simplicity to the Distinguished Encoding Rule 2931 (DER) BER subset defined in X.509, clause 8.7) is required for 2932 initial context establishment tokens of Internet standards-track 2933 GSS-API mechanisms; use in non-initial tokens is optional. There is 2934 no requirement that the mechanism-specific innerContextToken, 2935 innerMsgToken, and sealedUserData data elements be encoded in ASN.1 2936 BER. 2938 -- optional top-level token definitions to 2939 -- frame different mechanisms 2941 GSS-API DEFINITIONS ::= 2943 BEGIN 2945 MechType ::= OBJECT IDENTIFIER 2946 -- data structure definitions 2948 -- callers must be able to distinguish among 2949 -- InitialContextToken, SubsequentContextToken, 2950 -- PerMsgToken, and SealedMessage data elements 2951 -- based on the usage in which they occur 2953 InitialContextToken ::= 2954 -- option indication (delegation, etc.) indicated within 2955 -- mechanism-specific token 2956 [APPLICATION 0] IMPLICIT SEQUENCE { 2957 thisMech MechType, 2958 innerContextToken ANY DEFINED BY thisMech 2959 -- contents mechanism-specific 2960 -- ASN.1 structure not required 2961 } 2963 SubsequentContextToken ::= innerContextToken ANY 2964 -- interpretation based on predecessor InitialContextToken 2965 -- ASN.1 structure not required 2967 PerMsgToken ::= 2968 -- as emitted by GSS_GetMIC and processed by GSS_VerifyMIC 2969 -- ASN.1 structure not required 2970 innerMsgToken ANY 2972 SealedMessage ::= 2973 -- as emitted by GSS_Wrap and processed by GSS_Unwrap 2974 -- includes internal, mechanism-defined indicator 2975 -- of whether or not encrypted 2976 -- ASN.1 structure not required 2977 sealedUserData ANY 2979 END 2981 5: Related Activities 2983 In order to implement the GSS-API atop existing, emerging, and future 2984 security mechanisms: 2986 object identifiers must be assigned to candidate GSS-API 2987 mechanisms and the name types which they support 2989 concrete data element formats must be defined for candidate 2990 mechanisms 2992 Calling applications must implement formatting conventions which will 2993 enable them to distinguish GSS-API tokens from other data carried in 2994 their application protocols. 2996 Concrete language bindings are required for the programming 2997 environments in which the GSS-API is to be employed; such bindings 2998 for the C language are currently specified in RFC-1509. 3000 APPENDIX A 3002 PACS AND AUTHORIZATION SERVICES 3004 Consideration has been given to modifying the GSS-API service 3005 interface to recognize and manipulate Privilege Attribute 3006 Certificates (PACs) as in ECMA 138, carrying authorization data as a 3007 side effect of establishing a security context, but no such 3008 modifications have been incorporated at this time. This appendix 3009 provides rationale for this decision and discusses compatibility 3010 alternatives between PACs and the GSS-API which do not require that 3011 PACs be made visible to GSS-API callers. 3013 Existing candidate mechanism types such as Kerberos and X.509 do not 3014 incorporate PAC manipulation features, and exclusion of such 3015 mechanisms from the set of candidates equipped to fully support the 3016 GSS-API seems inappropriate. Inclusion (and GSS-API visibility) of a 3017 feature supported by only a limited number of mechanisms could 3018 encourage the development of ostensibly portable applications which 3019 would in fact have only limited portability. 3021 The status quo, in which PACs are not visible across the GSS-API 3022 interface, does not preclude implementations in which PACs are 3023 carried transparently, within the tokens defined and used for certain 3024 mech_types, and stored within peers' credentials and context-level 3025 data structures. While invisible to API callers, such PACs could be 3026 used by operating system or other local functions as inputs in the 3027 course of mediating access requests made by callers. This course of 3028 action allows dynamic selection of PAC contents, if such selection is 3029 administratively-directed rather than caller-directed. 3031 In a distributed computing environment, authentication must span 3032 different systems; the need for such authentication provides 3033 motivation for GSS-API definition and usage. Heterogeneous systems in 3034 a network can intercommunicate, with globally authenticated names 3035 comprising the common bond between locally defined access control 3036 policies. Access control policies to which authentication provides 3037 inputs are often local, or specific to particular operating systems 3038 or environments. If the GSS-API made particular authorization models 3039 visible across its service interface, its scope of application would 3040 become less general. The current GSS-API paradigm is consistent with 3041 the precedent set by Kerberos, neither defining the interpretation of 3042 authorization-related data nor enforcing access controls based on 3043 such data. 3045 The GSS-API is a general interface, whose callers may reside inside 3046 or outside any defined TCB or NTCB boundaries. Given this 3047 characteristic, it appears more realistic to provide facilities which 3048 provide "value-added" security services to its callers than to offer 3049 facilities which enforce restrictions on those callers. Authorization 3050 decisions must often be mediated below the GSS-API level in a local 3051 manner against (or in spite of) applications, and cannot be 3052 selectively invoked or omitted at those applications' discretion. 3053 Given that the GSS-API's placement prevents it from providing a 3054 comprehensive solution to the authorization issue, the value of a 3055 partial contribution specific to particular authorization models is 3056 debatable. 3058 APPENDIX B 3060 MECHANISM DESIGN CONSTRAINTS 3062 The following constraints on GSS-API mechanism designs are adopted in 3063 response to observed caller protocol requirements, and adherence 3064 thereto is anticipated in subsequent descriptions of GSS-API 3065 mechanisms to be documented in standards-track Internet 3066 specifications. 3068 It is strongly recommended that mechanisms offering per-message 3069 protection services also offer at least one of the replay detection 3070 and sequencing services, as mechanisms offering neither of the latter 3071 will fail to satisfy recognized requirements of certain candidate 3072 caller protocols. 3074 AUTHOR'S ADDRESS 3076 John Linn 3077 OpenVision Technologies 3078 One Main St. 3079 Cambridge, MA 02142 USA 3081 Phone: +1 617.374.2245 3083 E-mail: John.Linn@ov.com