1 2 3 4 5 6 7Network Working Group J. Linn 8Request for Comments: 2078 OpenVision Technologies 9Category: Standards Track January 1997 10Obsoletes: 1508 11 12 13 Generic Security Service Application Program Interface, Version 2 14 15Status of this Memo 16 17 This document specifies an Internet standards track protocol for the 18 Internet community, and requests discussion and suggestions for 19 improvements. Please refer to the current edition of the "Internet 20 Official Protocol Standards" (STD 1) for the standardization state 21 and status of this protocol. Distribution of this memo is unlimited. 22 23Abstract 24 25 The Generic Security Service Application Program Interface (GSS-API), 26 as defined in RFC-1508, provides security services to callers in a 27 generic fashion, supportable with a range of underlying mechanisms 28 and technologies and hence allowing source-level portability of 29 applications to different environments. This specification defines 30 GSS-API services and primitives at a level independent of underlying 31 mechanism and programming language environment, and is to be 32 complemented by other, related specifications: 33 34 documents defining specific parameter bindings for particular 35 language environments 36 37 documents defining token formats, protocols, and procedures to be 38 implemented in order to realize GSS-API services atop particular 39 security mechanisms 40 41 This memo revises RFC-1508, making specific, incremental changes in 42 response to implementation experience and liaison requests. It is 43 intended, therefore, that this memo or a successor version thereto 44 will become the basis for subsequent progression of the GSS-API 45 specification on the standards track. 46 47Table of Contents 48 49 1: GSS-API Characteristics and Concepts.......................... 3 50 1.1: GSS-API Constructs.......................................... 6 51 1.1.1: Credentials.............................................. 6 52 1.1.1.1: Credential Constructs and Concepts...................... 6 53 1.1.1.2: Credential Management................................... 7 54 1.1.1.3: Default Credential Resolution........................... 8 55 56 57 58Linn Standards Track [Page 1] 59 60RFC 2078 GSS-API January 1997 61 62 63 1.1.2: Tokens.................................................... 9 64 1.1.3: Security Contexts........................................ 10 65 1.1.4: Mechanism Types.......................................... 11 66 1.1.5: Naming................................................... 12 67 1.1.6: Channel Bindings......................................... 14 68 1.2: GSS-API Features and Issues................................ 15 69 1.2.1: Status Reporting......................................... 15 70 1.2.2: Per-Message Security Service Availability................. 17 71 1.2.3: Per-Message Replay Detection and Sequencing............... 18 72 1.2.4: Quality of Protection.................................... 20 73 1.2.5: Anonymity Support......................................... 21 74 1.2.6: Initialization............................................ 22 75 1.2.7: Per-Message Protection During Context Establishment....... 22 76 1.2.8: Implementation Robustness................................. 23 77 2: Interface Descriptions....................................... 23 78 2.1: Credential management calls................................ 25 79 2.1.1: GSS_Acquire_cred call.................................... 26 80 2.1.2: GSS_Release_cred call.................................... 28 81 2.1.3: GSS_Inquire_cred call.................................... 29 82 2.1.4: GSS_Add_cred call........................................ 31 83 2.1.5: GSS_Inquire_cred_by_mech call............................ 33 84 2.2: Context-level calls........................................ 34 85 2.2.1: GSS_Init_sec_context call................................ 34 86 2.2.2: GSS_Accept_sec_context call.............................. 40 87 2.2.3: GSS_Delete_sec_context call.............................. 44 88 2.2.4: GSS_Process_context_token call........................... 46 89 2.2.5: GSS_Context_time call.................................... 47 90 2.2.6: GSS_Inquire_context call................................. 47 91 2.2.7: GSS_Wrap_size_limit call................................. 49 92 2.2.8: GSS_Export_sec_context call.............................. 50 93 2.2.9: GSS_Import_sec_context call.............................. 52 94 2.3: Per-message calls.......................................... 53 95 2.3.1: GSS_GetMIC call.......................................... 54 96 2.3.2: GSS_VerifyMIC call....................................... 55 97 2.3.3: GSS_Wrap call............................................ 56 98 2.3.4: GSS_Unwrap call.......................................... 58 99 2.4: Support calls.............................................. 59 100 2.4.1: GSS_Display_status call.................................. 60 101 2.4.2: GSS_Indicate_mechs call.................................. 60 102 2.4.3: GSS_Compare_name call.................................... 61 103 2.4.4: GSS_Display_name call.................................... 62 104 2.4.5: GSS_Import_name call..................................... 63 105 2.4.6: GSS_Release_name call.................................... 64 106 2.4.7: GSS_Release_buffer call.................................. 65 107 2.4.8: GSS_Release_OID_set call................................. 65 108 2.4.9: GSS_Create_empty_OID_set call............................ 66 109 2.4.10: GSS_Add_OID_set_member call.............................. 67 110 2.4.11: GSS_Test_OID_set_member call............................. 67 111 112 113 114Linn Standards Track [Page 2] 115 116RFC 2078 GSS-API January 1997 117 118 119 2.4.12: GSS_Release_OID call..................................... 68 120 2.4.13: GSS_OID_to_str call...................................... 68 121 2.4.14: GSS_Str_to_OID call...................................... 69 122 2.4.15: GSS_Inquire_names_for_mech call.......................... 69 123 2.4.16: GSS_Inquire_mechs_for_name call.......................... 70 124 2.4.17: GSS_Canonicalize_name call............................... 71 125 2.4.18: GSS_Export_name call..................................... 72 126 2.4.19: GSS_Duplicate_name call.................................. 73 127 3: Data Structure Definitions for GSS-V2 Usage................... 73 128 3.1: Mechanism-Independent Token Format.......................... 74 129 3.2: Mechanism-Independent Exported Name Object Format........... 77 130 4: Name Type Definitions......................................... 77 131 4.1: Host-Based Service Name Form................................ 77 132 4.2: User Name Form.............................................. 78 133 4.3: Machine UID Form............................................ 78 134 4.4: String UID Form............................................. 79 135 5: Mechanism-Specific Example Scenarios......................... 79 136 5.1: Kerberos V5, single-TGT..................................... 79 137 5.2: Kerberos V5, double-TGT..................................... 80 138 5.3: X.509 Authentication Framework............................. 81 139 6: Security Considerations...................................... 82 140 7: Related Activities........................................... 82 141 Appendix A: Mechanism Design Constraints......................... 83 142 Appendix B: Compatibility with GSS-V1............................ 83 143 1441: GSS-API Characteristics and Concepts 145 146 GSS-API operates in the following paradigm. A typical GSS-API caller 147 is itself a communications protocol, calling on GSS-API in order to 148 protect its communications with authentication, integrity, and/or 149 confidentiality security services. A GSS-API caller accepts tokens 150 provided to it by its local GSS-API implementation and transfers the 151 tokens to a peer on a remote system; that peer passes the received 152 tokens to its local GSS-API implementation for processing. The 153 security services available through GSS-API in this fashion are 154 implementable (and have been implemented) over a range of underlying 155 mechanisms based on secret-key and public-key cryptographic 156 technologies. 157 158 The GSS-API separates the operations of initializing a security 159 context between peers, achieving peer entity authentication (This 160 security service definition, and other definitions used in this 161 document, corresponds to that provided in International Standard ISO 162 7498-2-1988(E), Security Architecture.) (GSS_Init_sec_context() and 163 GSS_Accept_sec_context() calls), from the operations of providing 164 per-message data origin authentication and data integrity protection 165 (GSS_GetMIC() and GSS_VerifyMIC() calls) for messages subsequently 166 transferred in conjunction with that context. When establishing a 167 168 169 170Linn Standards Track [Page 3] 171 172RFC 2078 GSS-API January 1997 173 174 175 security context, the GSS-API enables a context initiator to 176 optionally permit its credentials to be delegated, meaning that the 177 context acceptor may initiate further security contexts on behalf of 178 the initiating caller. Per-message GSS_Wrap() and GSS_Unwrap() calls 179 provide the data origin authentication and data integrity services 180 which GSS_GetMIC() and GSS_VerifyMIC() offer, and also support 181 selection of confidentiality services as a caller option. Additional 182 calls provide supportive functions to the GSS-API's users. 183 184 The following paragraphs provide an example illustrating the 185 dataflows involved in use of the GSS-API by a client and server in a 186 mechanism-independent fashion, establishing a security context and 187 transferring a protected message. The example assumes that credential 188 acquisition has already been completed. The example assumes that the 189 underlying authentication technology is capable of authenticating a 190 client to a server using elements carried within a single token, and 191 of authenticating the server to the client (mutual authentication) 192 with a single returned token; this assumption holds for presently- 193 documented CAT mechanisms but is not necessarily true for other 194 cryptographic technologies and associated protocols. 195 196 The client calls GSS_Init_sec_context() to establish a security 197 context to the server identified by targ_name, and elects to set the 198 mutual_req_flag so that mutual authentication is performed in the 199 course of context establishment. GSS_Init_sec_context() returns an 200 output_token to be passed to the server, and indicates 201 GSS_S_CONTINUE_NEEDED status pending completion of the mutual 202 authentication sequence. Had mutual_req_flag not been set, the 203 initial call to GSS_Init_sec_context() would have returned 204 GSS_S_COMPLETE status. The client sends the output_token to the 205 server. 206 207 The server passes the received token as the input_token parameter to 208 GSS_Accept_sec_context(). GSS_Accept_sec_context indicates 209 GSS_S_COMPLETE status, provides the client's authenticated identity 210 in the src_name result, and provides an output_token to be passed to 211 the client. The server sends the output_token to the client. 212 213 The client passes the received token as the input_token parameter to 214 a successor call to GSS_Init_sec_context(), which processes data 215 included in the token in order to achieve mutual authentication from 216 the client's viewpoint. This call to GSS_Init_sec_context() returns 217 GSS_S_COMPLETE status, indicating successful mutual authentication 218 and the completion of context establishment for this example. 219 220 The client generates a data message and passes it to GSS_Wrap(). 221 GSS_Wrap() performs data origin authentication, data integrity, and 222 (optionally) confidentiality processing on the message and 223 224 225 226Linn Standards Track [Page 4] 227 228RFC 2078 GSS-API January 1997 229 230 231 encapsulates the result into output_message, indicating 232 GSS_S_COMPLETE status. The client sends the output_message to the 233 server. 234 235 The server passes the received message to GSS_Unwrap(). GSS_Unwrap() 236 inverts the encapsulation performed by GSS_Wrap(), deciphers the 237 message if the optional confidentiality feature was applied, and 238 validates the data origin authentication and data integrity checking 239 quantities. GSS_Unwrap() indicates successful validation by 240 returning GSS_S_COMPLETE status along with the resultant 241 output_message. 242 243 For purposes of this example, we assume that the server knows by 244 out-of-band means that this context will have no further use after 245 one protected message is transferred from client to server. Given 246 this premise, the server now calls GSS_Delete_sec_context() to flush 247 context-level information. Optionally, the server-side application 248 may provide a token buffer to GSS_Delete_sec_context(), to receive a 249 context_token to be transferred to the client in order to request 250 that client-side context-level information be deleted. 251 252 If a context_token is transferred, the client passes the 253 context_token to GSS_Process_context_token(), which returns 254 GSS_S_COMPLETE status after deleting context-level information at the 255 client system. 256 257 The GSS-API design assumes and addresses several basic goals, 258 including: 259 260 Mechanism independence: The GSS-API defines an interface to 261 cryptographically implemented strong authentication and other 262 security services at a generic level which is independent of 263 particular underlying mechanisms. For example, GSS-API-provided 264 services can be implemented by secret-key technologies (e.g., 265 Kerberos) or public-key approaches (e.g., X.509). 266 267 Protocol environment independence: The GSS-API is independent of 268 the communications protocol suites with which it is employed, 269 permitting use in a broad range of protocol environments. In 270 appropriate environments, an intermediate implementation "veneer" 271 which is oriented to a particular communication protocol (e.g., 272 Remote Procedure Call (RPC)) may be interposed between 273 applications which call that protocol and the GSS-API, thereby 274 invoking GSS-API facilities in conjunction with that protocol's 275 communications invocations. 276 277 Protocol association independence: The GSS-API's security context 278 construct is independent of communications protocol association 279 280 281 282Linn Standards Track [Page 5] 283 284RFC 2078 GSS-API January 1997 285 286 287 constructs. This characteristic allows a single GSS-API 288 implementation to be utilized by a variety of invoking protocol 289 modules on behalf of those modules' calling applications. GSS-API 290 services can also be invoked directly by applications, wholly 291 independent of protocol associations. 292 293 Suitability to a range of implementation placements: GSS-API 294 clients are not constrained to reside within any Trusted Computing 295 Base (TCB) perimeter defined on a system where the GSS-API is 296 implemented; security services are specified in a manner suitable 297 to both intra-TCB and extra-TCB callers. 298 2991.1: GSS-API Constructs 300 301 This section describes the basic elements comprising the GSS-API. 302 3031.1.1: Credentials 304 3051.1.1.1: Credential Constructs and Concepts 306 307 Credentials provide the prerequisites which permit GSS-API peers to 308 establish security contexts with each other. A caller may designate 309 that the credential elements which are to be applied for context 310 initiation or acceptance be selected by default. Alternately, those 311 GSS-API callers which need to make explicit selection of particular 312 credentials structures may make references to those credentials 313 through GSS-API-provided credential handles ("cred_handles"). In all 314 cases, callers' credential references are indirect, mediated by GSS- 315 API implementations and not requiring callers to access the selected 316 credential elements. 317 318 A single credential structure may be used to initiate outbound 319 contexts and to accept inbound contexts. Callers needing to operate 320 in only one of these modes may designate this fact when credentials 321 are acquired for use, allowing underlying mechanisms to optimize 322 their processing and storage requirements. The credential elements 323 defined by a particular mechanism may contain multiple cryptographic 324 keys, e.g., to enable authentication and message encryption to be 325 performed with different algorithms. 326 327 A GSS-API credential structure may contain multiple credential 328 elements, each containing mechanism-specific information for a 329 particular underlying mechanism (mech_type), but the set of elements 330 within a given credential structure represent a common entity. A 331 credential structure's contents will vary depending on the set of 332 mech_types supported by a particular GSS-API implementation. Each 333 credential element identifies the data needed by its mechanism in 334 order to establish contexts on behalf of a particular principal, and 335 336 337 338Linn Standards Track [Page 6] 339 340RFC 2078 GSS-API January 1997 341 342 343 may contain separate credential references for use in context 344 initiation and context acceptance. Multiple credential elements 345 within a given credential having overlapping combinations of 346 mechanism, usage mode, and validity period are not permitted. 347 348 Commonly, a single mech_type will be used for all security contexts 349 established by a particular initiator to a particular target. A major 350 motivation for supporting credential sets representing multiple 351 mech_types is to allow initiators on systems which are equipped to 352 handle multiple types to initiate contexts to targets on other 353 systems which can accommodate only a subset of the set supported at 354 the initiator's system. 355 3561.1.1.2: Credential Management 357 358 It is the responsibility of underlying system-specific mechanisms and 359 OS functions below the GSS-API to ensure that the ability to acquire 360 and use credentials associated with a given identity is constrained 361 to appropriate processes within a system. This responsibility should 362 be taken seriously by implementors, as the ability for an entity to 363 utilize a principal's credentials is equivalent to the entity's 364 ability to successfully assert that principal's identity. 365 366 Once a set of GSS-API credentials is established, the transferability 367 of that credentials set to other processes or analogous constructs 368 within a system is a local matter, not defined by the GSS-API. An 369 example local policy would be one in which any credentials received 370 as a result of login to a given user account, or of delegation of 371 rights to that account, are accessible by, or transferable to, 372 processes running under that account. 373 374 The credential establishment process (particularly when performed on 375 behalf of users rather than server processes) is likely to require 376 access to passwords or other quantities which should be protected 377 locally and exposed for the shortest time possible. As a result, it 378 will often be appropriate for preliminary credential establishment to 379 be performed through local means at user login time, with the 380 result(s) cached for subsequent reference. These preliminary 381 credentials would be set aside (in a system-specific fashion) for 382 subsequent use, either: 383 384 to be accessed by an invocation of the GSS-API GSS_Acquire_cred() 385 call, returning an explicit handle to reference that credential 386 387 to comprise default credential elements to be installed, and to be 388 used when default credential behavior is requested on behalf of a 389 process 390 391 392 393 394Linn Standards Track [Page 7] 395 396RFC 2078 GSS-API January 1997 397 398 3991.1.1.3: Default Credential Resolution 400 401 The gss_init_sec_context and gss_accept_sec_context routines allow 402 the value GSS_C_NO_CREDENTIAL to be specified as their credential 403 handle parameter. This special credential-handle indicates a desire 404 by the application to act as a default principal. While individual 405 GSS-API implementations are free to determine such default behavior 406 as appropriate to the mechanism, the following default behavior by 407 these routines is recommended for portability: 408 409 GSS_Init_sec_context: 410 411 (i) If there is only a single principal capable of initiating 412 security contexts that the application is authorized to act on 413 behalf of, then that principal shall be used, otherwise 414 415 (ii) If the platform maintains a concept of a default network- 416 identity, and if the application is authorized to act on behalf of 417 that identity for the purpose of initiating security contexts, 418 then the principal corresponding to that identity shall be used, 419 otherwise 420 421 (iii) If the platform maintains a concept of a default local 422 identity, and provides a means to map local identities into 423 network-identities, and if the application is authorized to act on 424 behalf of the network-identity image of the default local identity 425 for the purpose of initiating security contexts, then the 426 principal corresponding to that identity shall be used, otherwise 427 428 (iv) A user-configurable default identity should be used. 429 430 GSS_Accept_sec_context: 431 432 (i) If there is only a single authorized principal identity 433 capable of accepting security contexts, then that principal shall 434 be used, otherwise 435 436 (ii) If the mechanism can determine the identity of the target 437 principal by examining the context-establishment token, and if the 438 accepting application is authorized to act as that principal for 439 the purpose of accepting security contexts, then that principal 440 identity shall be used, otherwise 441 442 (iii) If the mechanism supports context acceptance by any 443 principal, and mutual authentication was not requested, any 444 principal that the application is authorized to accept security 445 contexts under may be used, otherwise 446 447 448 449 450Linn Standards Track [Page 8] 451 452RFC 2078 GSS-API January 1997 453 454 455 (iv) A user-configurable default identity shall be used. 456 457 The purpose of the above rules is to allow security contexts to be 458 established by both initiator and acceptor using the default behavior 459 wherever possible. Applications requesting default behavior are 460 likely to be more portable across mechanisms and platforms than ones 461 that use GSS_Acquire_cred to request a specific identity. 462 4631.1.2: Tokens 464 465 Tokens are data elements transferred between GSS-API callers, and are 466 divided into two classes. Context-level tokens are exchanged in order 467 to establish and manage a security context between peers. Per-message 468 tokens relate to an established context and are exchanged to provide 469 protective security services (i.e., data origin authentication, 470 integrity, and optional confidentiality) for corresponding data 471 messages. 472 473 The first context-level token obtained from GSS_Init_sec_context() is 474 required to indicate at its very beginning a globally-interpretable 475 mechanism identifier, i.e., an Object Identifier (OID) of the 476 security mechanism. The remaining part of this token as well as the 477 whole content of all other tokens are specific to the particular 478 underlying mechanism used to support the GSS-API. Section 3 of this 479 document provides, for designers of GSS-API support mechanisms, the 480 description of the header of the first context-level token which is 481 then followed by mechanism-specific information. 482 483 Tokens' contents are opaque from the viewpoint of GSS-API callers. 484 They are generated within the GSS-API implementation at an end 485 system, provided to a GSS-API caller to be transferred to the peer 486 GSS-API caller at a remote end system, and processed by the GSS-API 487 implementation at that remote end system. Tokens may be output by 488 GSS-API calls (and should be transferred to GSS-API peers) whether or 489 not the calls' status indicators indicate successful completion. 490 Token transfer may take place in an in-band manner, integrated into 491 the same protocol stream used by the GSS-API callers for other data 492 transfers, or in an out-of-band manner across a logically separate 493 channel. 494 495 Different GSS-API tokens are used for different purposes (e.g., 496 context initiation, context acceptance, protected message data on an 497 established context), and it is the responsibility of a GSS-API 498 caller receiving tokens to distinguish their types, associate them 499 with corresponding security contexts, and pass them to appropriate 500 GSS-API processing routines. Depending on the caller protocol 501 environment, this distinction may be accomplished in several ways. 502 503 504 505 506Linn Standards Track [Page 9] 507 508RFC 2078 GSS-API January 1997 509 510 511 The following examples illustrate means through which tokens' types 512 may be distinguished: 513 514 - implicit tagging based on state information (e.g., all tokens on 515 a new association are considered to be context establishment 516 tokens until context establishment is completed, at which point 517 all tokens are considered to be wrapped data objects for that 518 context), 519 520 - explicit tagging at the caller protocol level, 521 522 - a hybrid of these approaches. 523 524 Commonly, the encapsulated data within a token includes internal 525 mechanism-specific tagging information, enabling mechanism-level 526 processing modules to distinguish tokens used within the mechanism 527 for different purposes. Such internal mechanism-level tagging is 528 recommended to mechanism designers, and enables mechanisms to 529 determine whether a caller has passed a particular token for 530 processing by an inappropriate GSS-API routine. 531 532 Development of GSS-API support primitives based on a particular 533 underlying cryptographic technique and protocol (i.e., conformant to 534 a specific GSS-API mechanism definition) does not necessarily imply 535 that GSS-API callers using that GSS-API mechanism will be able to 536 interoperate with peers invoking the same technique and protocol 537 outside the GSS-API paradigm, or with peers implementing a different 538 GSS-API mechanism based on the same underlying technology. The 539 format of GSS-API tokens defined in conjunction with a particular 540 mechanism, and the techniques used to integrate those tokens into 541 callers' protocols, may not be interoperable with the tokens used by 542 non-GSS-API callers of the same underlying technique. 543 5441.1.3: Security Contexts 545 546 Security contexts are established between peers, using credentials 547 established locally in conjunction with each peer or received by 548 peers via delegation. Multiple contexts may exist simultaneously 549 between a pair of peers, using the same or different sets of 550 credentials. Coexistence of multiple contexts using different 551 credentials allows graceful rollover when credentials expire. 552 Distinction among multiple contexts based on the same credentials 553 serves applications by distinguishing different message streams in a 554 security sense. 555 556 The GSS-API is independent of underlying protocols and addressing 557 structure, and depends on its callers to transport GSS-API-provided 558 data elements. As a result of these factors, it is a caller 559 560 561 562Linn Standards Track [Page 10] 563 564RFC 2078 GSS-API January 1997 565 566 567 responsibility to parse communicated messages, separating GSS-API- 568 related data elements from caller-provided data. The GSS-API is 569 independent of connection vs. connectionless orientation of the 570 underlying communications service. 571 572 No correlation between security context and communications protocol 573 association is dictated. (The optional channel binding facility, 574 discussed in Section 1.1.6 of this document, represents an 575 intentional exception to this rule, supporting additional protection 576 features within GSS-API supporting mechanisms.) This separation 577 allows the GSS-API to be used in a wide range of communications 578 environments, and also simplifies the calling sequences of the 579 individual calls. In many cases (depending on underlying security 580 protocol, associated mechanism, and availability of cached 581 information), the state information required for context setup can be 582 sent concurrently with initial signed user data, without interposing 583 additional message exchanges. 584 5851.1.4: Mechanism Types 586 587 In order to successfully establish a security context with a target 588 peer, it is necessary to identify an appropriate underlying mechanism 589 type (mech_type) which both initiator and target peers support. The 590 definition of a mechanism embodies not only the use of a particular 591 cryptographic technology (or a hybrid or choice among alternative 592 cryptographic technologies), but also definition of the syntax and 593 semantics of data element exchanges which that mechanism will employ 594 in order to support security services. 595 596 It is recommended that callers initiating contexts specify the 597 "default" mech_type value, allowing system-specific functions within 598 or invoked by the GSS-API implementation to select the appropriate 599 mech_type, but callers may direct that a particular mech_type be 600 employed when necessary. 601 602 The means for identifying a shared mech_type to establish a security 603 context with a peer will vary in different environments and 604 circumstances; examples include (but are not limited to): 605 606 use of a fixed mech_type, defined by configuration, within an 607 environment 608 609 syntactic convention on a target-specific basis, through 610 examination of a target's name 611 612 lookup of a target's name in a naming service or other database in 613 order to identify mech_types supported by that target 614 615 616 617 618Linn Standards Track [Page 11] 619 620RFC 2078 GSS-API January 1997 621 622 623 explicit negotiation between GSS-API callers in advance of 624 security context setup 625 626 When transferred between GSS-API peers, mech_type specifiers (per 627 Section 3, represented as Object Identifiers (OIDs)) serve to qualify 628 the interpretation of associated tokens. (The structure and encoding 629 of Object Identifiers is defined in ISO/IEC 8824, "Specification of 630 Abstract Syntax Notation One (ASN.1)" and in ISO/IEC 8825, 631 "Specification of Basic Encoding Rules for Abstract Syntax Notation 632 One (ASN.1)".) Use of hierarchically structured OIDs serves to 633 preclude ambiguous interpretation of mech_type specifiers. The OID 634 representing the DASS MechType, for example, is 1.3.12.2.1011.7.5, 635 and that of the Kerberos V5 mechanism, once advanced to the level of 636 Proposed Standard, will be 1.2.840.113554.1.2.2. 637 6381.1.5: Naming 639 640 The GSS-API avoids prescribing naming structures, treating the names 641 which are transferred across the interface in order to initiate and 642 accept security contexts as opaque objects. This approach supports 643 the GSS-API's goal of implementability atop a range of underlying 644 security mechanisms, recognizing the fact that different mechanisms 645 process and authenticate names which are presented in different 646 forms. Generalized services offering translation functions among 647 arbitrary sets of naming environments are outside the scope of the 648 GSS-API; availability and use of local conversion functions to 649 translate among the naming formats supported within a given end 650 system is anticipated. 651 652 Different classes of name representations are used in conjunction 653 with different GSS-API parameters: 654 655 - Internal form (denoted in this document by INTERNAL NAME), 656 opaque to callers and defined by individual GSS-API 657 implementations. GSS-API implementations supporting multiple 658 namespace types must maintain internal tags to disambiguate the 659 interpretation of particular names. A Mechanism Name (MN) is a 660 special case of INTERNAL NAME, guaranteed to contain elements 661 corresponding to one and only one mechanism; calls which are 662 guaranteed to emit MNs or which require MNs as input are so 663 identified within this specification. 664 665 - Contiguous string ("flat") form (denoted in this document by 666 OCTET STRING); accompanied by OID tags identifying the namespace 667 to which they correspond. Depending on tag value, flat names may 668 or may not be printable strings for direct acceptance from and 669 presentation to users. Tagging of flat names allows GSS-API 670 callers and underlying GSS-API mechanisms to disambiguate name 671 672 673 674Linn Standards Track [Page 12] 675 676RFC 2078 GSS-API January 1997 677 678 679 types and to determine whether an associated name's type is one 680 which they are capable of processing, avoiding aliasing problems 681 which could result from misinterpreting a name of one type as a 682 name of another type. 683 684 - The GSS-API Exported Name Object, a special case of flat name 685 designated by a reserved OID value, carries a canonicalized form 686 of a name suitable for binary comparisons. 687 688 In addition to providing means for names to be tagged with types, 689 this specification defines primitives to support a level of naming 690 environment independence for certain calling applications. To provide 691 basic services oriented towards the requirements of callers which 692 need not themselves interpret the internal syntax and semantics of 693 names, GSS-API calls for name comparison (GSS_Compare_name()), 694 human-readable display (GSS_Display_name()), input conversion 695 (GSS_Import_name()), internal name deallocation (GSS_Release_name()), 696 and internal name duplication (GSS_Duplicate_name()) functions are 697 defined. (It is anticipated that these proposed GSS-API calls will be 698 implemented in many end systems based on system-specific name 699 manipulation primitives already extant within those end systems; 700 inclusion within the GSS-API is intended to offer GSS-API callers a 701 portable means to perform specific operations, supportive of 702 authorization and audit requirements, on authenticated names.) 703 704 GSS_Import_name() implementations can, where appropriate, support 705 more than one printable syntax corresponding to a given namespace 706 (e.g., alternative printable representations for X.500 Distinguished 707 Names), allowing flexibility for their callers to select among 708 alternative representations. GSS_Display_name() implementations 709 output a printable syntax selected as appropriate to their 710 operational environments; this selection is a local matter. Callers 711 desiring portability across alternative printable syntaxes should 712 refrain from implementing comparisons based on printable name forms 713 and should instead use the GSS_Compare_name() call to determine 714 whether or not one internal-format name matches another. 715 716 The GSS_Canonicalize_name() and GSS_Export_name() calls enable 717 callers to acquire and process Exported Name Objects, canonicalized 718 and translated in accordance with the procedures of a particular 719 GSS-API mechanism. Exported Name Objects can, in turn, be input to 720 GSS_Import_name(), yielding equivalent MNs. These facilities are 721 designed specifically to enable efficient storage and comparison of 722 names (e.g., for use in access control lists). 723 724 725 726 727 728 729 730Linn Standards Track [Page 13] 731 732RFC 2078 GSS-API January 1997 733 734 735 The following diagram illustrates the intended dataflow among name- 736 related GSS-API processing routines. 737 738 GSS-API library defaults 739 | 740 | 741 V text, for 742 text --------------> internal_name (IN) -----------> display only 743 import_name() / display_name() 744 / 745 / 746 / 747 accept_sec_context() / 748 | / 749 | / 750 | / canonicalize_name() 751 | / 752 | / 753 | / 754 | / 755 | / 756 | | 757 V V <--------------------- 758 single mechanism import_name() exported name: flat 759 internal_name (MN) binary "blob" usable 760 ----------------------> for access control 761 export_name() 762 7631.1.6: Channel Bindings 764 765 The GSS-API accommodates the concept of caller-provided channel 766 binding ("chan_binding") information. Channel bindings are used to 767 strengthen the quality with which peer entity authentication is 768 provided during context establishment, by limiting the scope within 769 which an intercepted context establishment token can be reused by an 770 attacker. Specifically, they enable GSS-API callers to bind the 771 establishment of a security context to relevant characteristics 772 (e.g., addresses, transformed representations of encryption keys) of 773 the underlying communications channel, of protection mechanisms 774 applied to that communications channel, and to application-specific 775 data. 776 777 The caller initiating a security context must determine the 778 appropriate channel binding values to provide as input to the 779 GSS_Init_sec_context() call, and consistent values must be provided 780 to GSS_Accept_sec_context() by the context's target, in order for 781 both peers' GSS-API mechanisms to validate that received tokens 782 possess correct channel-related characteristics. Use or non-use of 783 784 785 786Linn Standards Track [Page 14] 787 788RFC 2078 GSS-API January 1997 789 790 791 the GSS-API channel binding facility is a caller option. GSS-API 792 mechanisms can operate in an environment where NULL channel bindings 793 are presented; mechanism implementors are encouraged, but not 794 required, to make use of caller-provided channel binding data within 795 their mechanisms. Callers should not assume that underlying 796 mechanisms provide confidentiality protection for channel binding 797 information. 798 799 When non-NULL channel bindings are provided by callers, certain 800 mechanisms can offer enhanced security value by interpreting the 801 bindings' content (rather than simply representing those bindings, or 802 integrity check values computed on them, within tokens) and will 803 therefore depend on presentation of specific data in a defined 804 format. To this end, agreements among mechanism implementors are 805 defining conventional interpretations for the contents of channel 806 binding arguments, including address specifiers (with content 807 dependent on communications protocol environment) for context 808 initiators and acceptors. (These conventions are being incorporated 809 in GSS-API mechanism specifications and into the GSS-API C language 810 bindings specification.) In order for GSS-API callers to be portable 811 across multiple mechanisms and achieve the full security 812 functionality which each mechanism can provide, it is strongly 813 recommended that GSS-API callers provide channel bindings consistent 814 with these conventions and those of the networking environment in 815 which they operate. 816 8171.2: GSS-API Features and Issues 818 819 This section describes aspects of GSS-API operations, of the security 820 services which the GSS-API provides, and provides commentary on 821 design issues. 822 8231.2.1: Status Reporting 824 825 Each GSS-API call provides two status return values. Major_status 826 values provide a mechanism-independent indication of call status 827 (e.g., GSS_S_COMPLETE, GSS_S_FAILURE, GSS_S_CONTINUE_NEEDED), 828 sufficient to drive normal control flow within the caller in a 829 generic fashion. Table 1 summarizes the defined major_status return 830 codes in tabular fashion. 831 832 833 834 835 836 837 838 839 840 841 842Linn Standards Track [Page 15] 843 844RFC 2078 GSS-API January 1997 845 846 847Table 1: GSS-API Major Status Codes 848 849 FATAL ERROR CODES 850 851 GSS_S_BAD_BINDINGS channel binding mismatch 852 GSS_S_BAD_MECH unsupported mechanism requested 853 GSS_S_BAD_NAME invalid name provided 854 GSS_S_BAD_NAMETYPE name of unsupported type provided 855 GSS_S_BAD_STATUS invalid input status selector 856 GSS_S_BAD_SIG token had invalid integrity check 857 GSS_S_CONTEXT_EXPIRED specified security context expired 858 GSS_S_CREDENTIALS_EXPIRED expired credentials detected 859 GSS_S_DEFECTIVE_CREDENTIAL defective credential detected 860 GSS_S_DEFECTIVE_TOKEN defective token detected 861 GSS_S_FAILURE failure, unspecified at GSS-API 862 level 863 GSS_S_NO_CONTEXT no valid security context specified 864 GSS_S_NO_CRED no valid credentials provided 865 GSS_S_BAD_QOP unsupported QOP value 866 GSS_S_UNAUTHORIZED operation unauthorized 867 GSS_S_UNAVAILABLE operation unavailable 868 GSS_S_DUPLICATE_ELEMENT duplicate credential element requested 869 GSS_S_NAME_NOT_MN name contains multi-mechanism elements 870 871 INFORMATORY STATUS CODES 872 873 GSS_S_COMPLETE normal completion 874 GSS_S_CONTINUE_NEEDED continuation call to routine 875 required 876 GSS_S_DUPLICATE_TOKEN duplicate per-message token 877 detected 878 GSS_S_OLD_TOKEN timed-out per-message token 879 detected 880 GSS_S_UNSEQ_TOKEN reordered (early) per-message token 881 detected 882 GSS_S_GAP_TOKEN skipped predecessor token(s) 883 detected 884 885 Minor_status provides more detailed status information which may 886 include status codes specific to the underlying security mechanism. 887 Minor_status values are not specified in this document. 888 889 GSS_S_CONTINUE_NEEDED major_status returns, and optional message 890 outputs, are provided in GSS_Init_sec_context() and 891 GSS_Accept_sec_context() calls so that different mechanisms' 892 employment of different numbers of messages within their 893 authentication sequences need not be reflected in separate code paths 894 within calling applications. Instead, such cases are accommodated 895 896 897 898Linn Standards Track [Page 16] 899 900RFC 2078 GSS-API January 1997 901 902 903 with sequences of continuation calls to GSS_Init_sec_context() and 904 GSS_Accept_sec_context(). The same mechanism is used to encapsulate 905 mutual authentication within the GSS-API's context initiation calls. 906 907 For mech_types which require interactions with third-party servers in 908 order to establish a security context, GSS-API context establishment 909 calls may block pending completion of such third-party interactions. 910 911 On the other hand, no GSS-API calls pend on serialized interactions 912 with GSS-API peer entities. As a result, local GSS-API status 913 returns cannot reflect unpredictable or asynchronous exceptions 914 occurring at remote peers, and reflection of such status information 915 is a caller responsibility outside the GSS-API. 916 9171.2.2: Per-Message Security Service Availability 918 919 When a context is established, two flags are returned to indicate the 920 set of per-message protection security services which will be 921 available on the context: 922 923 the integ_avail flag indicates whether per-message integrity and 924 data origin authentication services are available 925 926 the conf_avail flag indicates whether per-message confidentiality 927 services are available, and will never be returned TRUE unless the 928 integ_avail flag is also returned TRUE 929 930 GSS-API callers desiring per-message security services should 931 check the values of these flags at context establishment time, and 932 must be aware that a returned FALSE value for integ_avail means 933 that invocation of GSS_GetMIC() or GSS_Wrap() primitives on the 934 associated context will apply no cryptographic protection to user 935 data messages. 936 937 The GSS-API per-message integrity and data origin authentication 938 services provide assurance to a receiving caller that protection was 939 applied to a message by the caller's peer on the security context, 940 corresponding to the entity named at context initiation. The GSS-API 941 per-message confidentiality service provides assurance to a sending 942 caller that the message's content is protected from access by 943 entities other than the context's named peer. 944 945 946 947 948 949 950 951 952 953 954Linn Standards Track [Page 17] 955 956RFC 2078 GSS-API January 1997 957 958 959 The GSS-API per-message protection service primitives, as the 960 category name implies, are oriented to operation at the granularity 961 of protocol data units. They perform cryptographic operations on the 962 data units, transfer cryptographic control information in tokens, 963 and, in the case of GSS_Wrap(), encapsulate the protected data unit. 964 As such, these primitives are not oriented to efficient data 965 protection for stream-paradigm protocols (e.g., Telnet) if 966 cryptography must be applied on an octet-by-octet basis. 967 9681.2.3: Per-Message Replay Detection and Sequencing 969 970 Certain underlying mech_types offer support for replay detection 971 and/or sequencing of messages transferred on the contexts they 972 support. These optionally-selectable protection features are distinct 973 from replay detection and sequencing features applied to the context 974 establishment operation itself; the presence or absence of context- 975 level replay or sequencing features is wholly a function of the 976 underlying mech_type's capabilities, and is not selected or omitted 977 as a caller option. 978 979 The caller initiating a context provides flags (replay_det_req_flag 980 and sequence_req_flag) to specify whether the use of per-message 981 replay detection and sequencing features is desired on the context 982 being established. The GSS-API implementation at the initiator system 983 can determine whether these features are supported (and whether they 984 are optionally selectable) as a function of mech_type, without need 985 for bilateral negotiation with the target. When enabled, these 986 features provide recipients with indicators as a result of GSS-API 987 processing of incoming messages, identifying whether those messages 988 were detected as duplicates or out-of-sequence. Detection of such 989 events does not prevent a suspect message from being provided to a 990 recipient; the appropriate course of action on a suspect message is a 991 matter of caller policy. 992 993 The semantics of the replay detection and sequencing services applied 994 to received messages, as visible across the interface which the GSS- 995 API provides to its clients, are as follows: 996 997 When replay_det_state is TRUE, the possible major_status returns for 998 well-formed and correctly signed messages are as follows: 999 1000 1. GSS_S_COMPLETE indicates that the message was within the window 1001 (of time or sequence space) allowing replay events to be detected, 1002 and that the message was not a replay of a previously-processed 1003 message within that window. 1004 1005 1006 1007 1008 1009 1010Linn Standards Track [Page 18] 1011 1012RFC 2078 GSS-API January 1997 1013 1014 1015 2. GSS_S_DUPLICATE_TOKEN indicates that the cryptographic 1016 checkvalue on the received message was correct, but that the 1017 message was recognized as a duplicate of a previously-processed 1018 message. 1019 1020 3. GSS_S_OLD_TOKEN indicates that the cryptographic checkvalue on 1021 the received message was correct, but that the message is too old 1022 to be checked for duplication. 1023 1024 When sequence_state is TRUE, the possible major_status returns for 1025 well-formed and correctly signed messages are as follows: 1026 1027 1. GSS_S_COMPLETE indicates that the message was within the window 1028 (of time or sequence space) allowing replay events to be detected, 1029 that the message was not a replay of a previously-processed 1030 message within that window, and that no predecessor sequenced 1031 messages are missing relative to the last received message (if 1032 any) processed on the context with a correct cryptographic 1033 checkvalue. 1034 1035 2. GSS_S_DUPLICATE_TOKEN indicates that the integrity check value 1036 on the received message was correct, but that the message was 1037 recognized as a duplicate of a previously-processed message. 1038 1039 3. GSS_S_OLD_TOKEN indicates that the integrity check value on the 1040 received message was correct, but that the token is too old to be 1041 checked for duplication. 1042 1043 4. GSS_S_UNSEQ_TOKEN indicates that the cryptographic checkvalue 1044 on the received message was correct, but that it is earlier in a 1045 sequenced stream than a message already processed on the context. 1046 [Note: Mechanisms can be architected to provide a stricter form of 1047 sequencing service, delivering particular messages to recipients 1048 only after all predecessor messages in an ordered stream have been 1049 delivered. This type of support is incompatible with the GSS-API 1050 paradigm in which recipients receive all messages, whether in 1051 order or not, and provide them (one at a time, without intra-GSS- 1052 API message buffering) to GSS-API routines for validation. GSS- 1053 API facilities provide supportive functions, aiding clients to 1054 achieve strict message stream integrity in an efficient manner in 1055 conjunction with sequencing provisions in communications 1056 protocols, but the GSS-API does not offer this level of message 1057 stream integrity service by itself.] 1058 1059 1060 1061 1062 1063 1064 1065 1066Linn Standards Track [Page 19] 1067 1068RFC 2078 GSS-API January 1997 1069 1070 1071 5. GSS_S_GAP_TOKEN indicates that the cryptographic checkvalue on 1072 the received message was correct, but that one or more predecessor 1073 sequenced messages have not been successfully processed relative 1074 to the last received message (if any) processed on the context 1075 with a correct cryptographic checkvalue. 1076 1077 As the message stream integrity features (especially sequencing) may 1078 interfere with certain applications' intended communications 1079 paradigms, and since support for such features is likely to be 1080 resource intensive, it is highly recommended that mech_types 1081 supporting these features allow them to be activated selectively on 1082 initiator request when a context is established. A context initiator 1083 and target are provided with corresponding indicators 1084 (replay_det_state and sequence_state), signifying whether these 1085 features are active on a given context. 1086 1087 An example mech_type supporting per-message replay detection could 1088 (when replay_det_state is TRUE) implement the feature as follows: The 1089 underlying mechanism would insert timestamps in data elements output 1090 by GSS_GetMIC() and GSS_Wrap(), and would maintain (within a time- 1091 limited window) a cache (qualified by originator-recipient pair) 1092 identifying received data elements processed by GSS_VerifyMIC() and 1093 GSS_Unwrap(). When this feature is active, exception status returns 1094 (GSS_S_DUPLICATE_TOKEN, GSS_S_OLD_TOKEN) will be provided when 1095 GSS_VerifyMIC() or GSS_Unwrap() is presented with a message which is 1096 either a detected duplicate of a prior message or which is too old to 1097 validate against a cache of recently received messages. 1098 10991.2.4: Quality of Protection 1100 1101 Some mech_types provide their users with fine granularity control 1102 over the means used to provide per-message protection, allowing 1103 callers to trade off security processing overhead dynamically against 1104 the protection requirements of particular messages. A per-message 1105 quality-of-protection parameter (analogous to quality-of-service, or 1106 QOS) selects among different QOP options supported by that mechanism. 1107 On context establishment for a multi-QOP mech_type, context-level 1108 data provides the prerequisite data for a range of protection 1109 qualities. 1110 1111 It is expected that the majority of callers will not wish to exert 1112 explicit mechanism-specific QOP control and will therefore request 1113 selection of a default QOP. Definitions of, and choices among, non- 1114 default QOP values are mechanism-specific, and no ordered sequences 1115 of QOP values can be assumed equivalent across different mechanisms. 1116 Meaningful use of non-default QOP values demands that callers be 1117 familiar with the QOP definitions of an underlying mechanism or 1118 mechanisms, and is therefore a non-portable construct. The 1119 1120 1121 1122Linn Standards Track [Page 20] 1123 1124RFC 2078 GSS-API January 1997 1125 1126 1127 GSS_S_BAD_QOP major_status value is defined in order to indicate that 1128 a provided QOP value is unsupported for a security context, most 1129 likely because that value is unrecognized by the underlying 1130 mechanism. 1131 11321.2.5: Anonymity Support 1133 1134 In certain situations or environments, an application may wish to 1135 authenticate a peer and/or protect communications using GSS-API per- 1136 message services without revealing its own identity. For example, 1137 consider an application which provides read access to a research 1138 database, and which permits queries by arbitrary requestors. A 1139 client of such a service might wish to authenticate the service, to 1140 establish trust in the information received from it, but might not 1141 wish to disclose its identity to the service for privacy reasons. 1142 1143 In ordinary GSS-API usage, a context initiator's identity is made 1144 available to the context acceptor as part of the context 1145 establishment process. To provide for anonymity support, a facility 1146 (input anon_req_flag to GSS_Init_sec_context()) is provided through 1147 which context initiators may request that their identity not be 1148 provided to the context acceptor. Mechanisms are not required to 1149 honor this request, but a caller will be informed (via returned 1150 anon_state indicator from GSS_Init_sec_context()) whether or not the 1151 request is honored. Note that authentication as the anonymous 1152 principal does not necessarily imply that credentials are not 1153 required in order to establish a context. 1154 1155 The following Object Identifier value is provided as a means to 1156 identify anonymous names, and can be compared against in order to 1157 determine, in a mechanism-independent fashion, whether a name refers 1158 to an anonymous principal: 1159 1160 {1(iso), 3(org), 6(dod), 1(internet), 5(security), 6(nametypes), 1161 3(gss-anonymous-name)} 1162 1163 The recommended symbolic name corresponding to this definition is 1164 GSS_C_NT_ANONYMOUS. 1165 1166 Four possible combinations of anon_state and mutual_state are 1167 possible, with the following results: 1168 1169 anon_state == FALSE, mutual_state == FALSE: initiator 1170 authenticated to target. 1171 1172 anon_state == FALSE, mutual_state == TRUE: initiator authenticated 1173 to target, target authenticated to initiator. 1174 1175 1176 1177 1178Linn Standards Track [Page 21] 1179 1180RFC 2078 GSS-API January 1997 1181 1182 1183 anon_state == TRUE, mutual_state == FALSE: initiator authenticated 1184 as anonymous principal to target. 1185 1186 anon_state == TRUE, mutual_state == TRUE: initiator authenticated 1187 as anonymous principal to target, target authenticated to 1188 initiator. 1189 11901.2.6: Initialization 1191 1192 No initialization calls (i.e., calls which must be invoked prior to 1193 invocation of other facilities in the interface) are defined in GSS- 1194 API. As an implication of this fact, GSS-API implementations must 1195 themselves be self-initializing. 1196 11971.2.7: Per-Message Protection During Context Establishment 1198 1199 A facility is defined in GSS-V2 to enable protection and buffering of 1200 data messages for later transfer while a security context's 1201 establishment is in GSS_S_CONTINUE_NEEDED status, to be used in cases 1202 where the caller side already possesses the necessary session key to 1203 enable this processing. Specifically, a new state Boolean, called 1204 prot_ready_state, is added to the set of information returned by 1205 GSS_Init_sec_context(), GSS_Accept_sec_context(), and 1206 GSS_Inquire_context(). 1207 1208 For context establishment calls, this state Boolean is valid and 1209 interpretable when the associated major_status is either 1210 GSS_S_CONTINUE_NEEDED, or GSS_S_COMPLETE. Callers of GSS-API (both 1211 initiators and acceptors) can assume that per-message protection (via 1212 GSS_Wrap(), GSS_Unwrap(), GSS_GetMIC() and GSS_VerifyMIC()) is 1213 available and ready for use if either: prot_ready_state == TRUE, or 1214 major_status == GSS_S_COMPLETE, though mutual authentication (if 1215 requested) cannot be guaranteed until GSS_S_COMPLETE is returned. 1216 1217 This achieves full, transparent backward compatibility for GSS-API V1 1218 callers, who need not even know of the existence of prot_ready_state, 1219 and who will get the expected behavior from GSS_S_COMPLETE, but who 1220 will not be able to use per-message protection before GSS_S_COMPLETE 1221 is returned. 1222 1223 It is not a requirement that GSS-V2 mechanisms ever return TRUE 1224 prot_ready_state before completion of context establishment (indeed, 1225 some mechanisms will not evolve usable message protection keys, 1226 especially at the context acceptor, before context establishment is 1227 complete). It is expected but not required that GSS-V2 mechanisms 1228 will return TRUE prot_ready_state upon completion of context 1229 establishment if they support per-message protection at all (however 1230 GSS-V2 applications should not assume that TRUE prot_ready_state will 1231 1232 1233 1234Linn Standards Track [Page 22] 1235 1236RFC 2078 GSS-API January 1997 1237 1238 1239 always be returned together with the GSS_S_COMPLETE major_status, 1240 since GSS-V2 implementations may continue to support GSS-V1 mechanism 1241 code, which will never return TRUE prot_ready_state). 1242 1243 When prot_ready_state is returned TRUE, mechanisms shall also set 1244 those context service indicator flags (deleg_state, mutual_state, 1245 replay_det_state, sequence_state, anon_state, trans_state, 1246 conf_avail, integ_avail) which represent facilities confirmed, at 1247 that time, to be available on the context being established. In 1248 situations where prot_ready_state is returned before GSS_S_COMPLETE, 1249 it is possible that additional facilities may be confirmed and 1250 subsequently indicated when GSS_S_COMPLETE is returned. 1251 12521.2.8: Implementation Robustness 1253 1254 This section recommends aspects of GSS-API implementation behavior in 1255 the interests of overall robustness. 1256 1257 If a token is presented for processing on a GSS-API security context 1258 and that token is determined to be invalid for that context, the 1259 context's state should not be disrupted for purposes of processing 1260 subsequent valid tokens. 1261 1262 Certain local conditions at a GSS-API implementation (e.g., 1263 unavailability of memory) may preclude, temporarily or permanently, 1264 the successful processing of tokens on a GSS-API security context, 1265 typically generating GSS_S_FAILURE major_status returns along with 1266 locally-significant minor_status. For robust operation under such 1267 conditions, the following recommendations are made: 1268 1269 Failing calls should free any memory they allocate, so that 1270 callers may retry without causing further loss of resources. 1271 1272 Failure of an individual call on an established context should not 1273 preclude subsequent calls from succeeding on the same context. 1274 1275 Whenever possible, it should be possible for 1276 GSS_Delete_sec_context() calls to be successfully processed even 1277 if other calls cannot succeed, thereby enabling context-related 1278 resources to be released. 1279 12802: Interface Descriptions 1281 1282 This section describes the GSS-API's service interface, dividing the 1283 set of calls offered into four groups. Credential management calls 1284 are related to the acquisition and release of credentials by 1285 principals. Context-level calls are related to the management of 1286 security contexts between principals. Per-message calls are related 1287 1288 1289 1290Linn Standards Track [Page 23] 1291 1292RFC 2078 GSS-API January 1997 1293 1294 1295 to the protection of individual messages on established security 1296 contexts. Support calls provide ancillary functions useful to GSS-API 1297 callers. Table 2 groups and summarizes the calls in tabular fashion. 1298 1299Table 2: GSS-API Calls 1300 1301 CREDENTIAL MANAGEMENT 1302 1303 GSS_Acquire_cred acquire credentials for use 1304 GSS_Release_cred release credentials after use 1305 GSS_Inquire_cred display information about 1306 credentials 1307 GSS_Add_cred construct credentials incrementally 1308 GSS_Inquire_cred_by_mech display per-mechanism credential 1309 information 1310 1311 CONTEXT-LEVEL CALLS 1312 1313 GSS_Init_sec_context initiate outbound security context 1314 GSS_Accept_sec_context accept inbound security context 1315 GSS_Delete_sec_context flush context when no longer needed 1316 GSS_Process_context_token process received control token on 1317 context 1318 GSS_Context_time indicate validity time remaining on 1319 context 1320 GSS_Inquire_context display information about context 1321 GSS_Wrap_size_limit determine GSS_Wrap token size limit 1322 GSS_Export_sec_context transfer context to other process 1323 GSS_Import_sec_context import transferred context 1324 1325 PER-MESSAGE CALLS 1326 1327 GSS_GetMIC apply integrity check, receive as 1328 token separate from message 1329 GSS_VerifyMIC validate integrity check token 1330 along with message 1331 GSS_Wrap sign, optionally encrypt, 1332 encapsulate 1333 GSS_Unwrap decapsulate, decrypt if needed, 1334 validate integrity check 1335 1336 1337 1338 1339 1340 1341 1342 1343 1344 1345 1346Linn Standards Track [Page 24] 1347 1348RFC 2078 GSS-API January 1997 1349 1350 1351 SUPPORT CALLS 1352 1353 GSS_Display_status translate status codes to printable 1354 form 1355 GSS_Indicate_mechs indicate mech_types supported on 1356 local system 1357 GSS_Compare_name compare two names for equality 1358 GSS_Display_name translate name to printable form 1359 GSS_Import_name convert printable name to 1360 normalized form 1361 GSS_Release_name free storage of normalized-form 1362 name 1363 GSS_Release_buffer free storage of printable name 1364 GSS_Release_OID free storage of OID object 1365 GSS_Release_OID_set free storage of OID set object 1366 GSS_Create_empty_OID_set create empty OID set 1367 GSS_Add_OID_set_member add member to OID set 1368 GSS_Test_OID_set_member test if OID is member of OID set 1369 GSS_OID_to_str display OID as string 1370 GSS_Str_to_OID construct OID from string 1371 GSS_Inquire_names_for_mech indicate name types supported by 1372 mechanism 1373 GSS_Inquire_mechs_for_name indicates mechanisms supporting name 1374 type 1375 GSS_Canonicalize_name translate name to per-mechanism form 1376 GSS_Export_name externalize per-mechanism name 1377 GSS_Duplicate_name duplicate name object 1378 13792.1: Credential management calls 1380 1381 These GSS-API calls provide functions related to the management of 1382 credentials. Their characterization with regard to whether or not 1383 they may block pending exchanges with other network entities (e.g., 1384 directories or authentication servers) depends in part on OS-specific 1385 (extra-GSS-API) issues, so is not specified in this document. 1386 1387 The GSS_Acquire_cred() call is defined within the GSS-API in support 1388 of application portability, with a particular orientation towards 1389 support of portable server applications. It is recognized that (for 1390 certain systems and mechanisms) credentials for interactive users may 1391 be managed differently from credentials for server processes; in such 1392 environments, it is the GSS-API implementation's responsibility to 1393 distinguish these cases and the procedures for making this 1394 distinction are a local matter. The GSS_Release_cred() call provides 1395 a means for callers to indicate to the GSS-API that use of a 1396 credentials structure is no longer required. The GSS_Inquire_cred() 1397 call allows callers to determine information about a credentials 1398 structure. The GSS_Add_cred() call enables callers to append 1399 1400 1401 1402Linn Standards Track [Page 25] 1403 1404RFC 2078 GSS-API January 1997 1405 1406 1407 elements to an existing credential structure, allowing iterative 1408 construction of a multi-mechanism credential. The 1409 GSS_Inquire_cred_by_mech() call enables callers to extract per- 1410 mechanism information describing a credentials structure. 1411 14122.1.1: GSS_Acquire_cred call 1413 1414 Inputs: 1415 1416 o desired_name INTERNAL NAME, -NULL requests locally-determined 1417 default 1418 1419 o lifetime_req INTEGER,-in seconds; 0 requests default 1420 1421 o desired_mechs SET OF OBJECT IDENTIFIER,-empty set requests 1422 system-selected default 1423 1424 o cred_usage INTEGER -0=INITIATE-AND-ACCEPT, 1=INITIATE-ONLY, 1425 2=ACCEPT-ONLY 1426 1427 Outputs: 1428 1429 o major_status INTEGER, 1430 1431 o minor_status INTEGER, 1432 1433 o output_cred_handle CREDENTIAL HANDLE, 1434 1435 o actual_mechs SET OF OBJECT IDENTIFIER, 1436 1437 o lifetime_rec INTEGER -in seconds, or reserved value for 1438 INDEFINITE 1439 1440 Return major_status codes: 1441 1442 o GSS_S_COMPLETE indicates that requested credentials were 1443 successfully established, for the duration indicated in 1444 lifetime_rec, suitable for the usage requested in cred_usage, 1445 for the set of mech_types indicated in actual_mechs, and that 1446 those credentials can be referenced for subsequent use with 1447 the handle returned in output_cred_handle. 1448 1449 o GSS_S_BAD_MECH indicates that a mech_type unsupported by the 1450 GSS-API implementation type was requested, causing the 1451 credential establishment operation to fail. 1452 1453 1454 1455 1456 1457 1458Linn Standards Track [Page 26] 1459 1460RFC 2078 GSS-API January 1997 1461 1462 1463 o GSS_S_BAD_NAMETYPE indicates that the provided desired_name is 1464 uninterpretable or of a type unsupported by the applicable 1465 underlying GSS-API mechanism(s), so no credentials could be 1466 established for the accompanying desired_name. 1467 1468 o GSS_S_BAD_NAME indicates that the provided desired_name is 1469 inconsistent in terms of internally-incorporated type specifier 1470 information, so no credentials could be established for the 1471 accompanying desired_name. 1472 1473 o GSS_S_FAILURE indicates that credential establishment failed 1474 for reasons unspecified at the GSS-API level, including lack 1475 of authorization to establish and use credentials associated 1476 with the identity named in the input desired_name argument. 1477 1478 GSS_Acquire_cred() is used to acquire credentials so that a 1479 principal can (as a function of the input cred_usage parameter) 1480 initiate and/or accept security contexts under the identity 1481 represented by the desired_name input argument. On successful 1482 completion, the returned output_cred_handle result provides a handle 1483 for subsequent references to the acquired credentials. Typically, 1484 single-user client processes requesting that default credential 1485 behavior be applied for context establishment purposes will have no 1486 need to invoke this call. 1487 1488 A caller may provide the value NULL for desired_name, signifying a 1489 request for credentials corresponding to a principal identity 1490 selected by default for the caller. The procedures used by GSS-API 1491 implementations to select the appropriate principal identity in 1492 response to such a request are local matters. It is possible that 1493 multiple pre-established credentials may exist for the same principal 1494 identity (for example, as a result of multiple user login sessions) 1495 when GSS_Acquire_cred() is called; the means used in such cases to 1496 select a specific credential are local matters. The input 1497 lifetime_req argument to GSS_Acquire_cred() may provide useful 1498 information for local GSS-API implementations to employ in making 1499 this disambiguation in a manner which will best satisfy a caller's 1500 intent. 1501 1502 The lifetime_rec result indicates the length of time for which the 1503 acquired credentials will be valid, as an offset from the present. A 1504 mechanism may return a reserved value indicating INDEFINITE if no 1505 constraints on credential lifetime are imposed. A caller of 1506 GSS_Acquire_cred() can request a length of time for which acquired 1507 credentials are to be valid (lifetime_req argument), beginning at the 1508 present, or can request credentials with a default validity interval. 1509 (Requests for postdated credentials are not supported within the 1510 GSS-API.) Certain mechanisms and implementations may bind in 1511 1512 1513 1514Linn Standards Track [Page 27] 1515 1516RFC 2078 GSS-API January 1997 1517 1518 1519 credential validity period specifiers at a point preliminary to 1520 invocation of the GSS_Acquire_cred() call (e.g., in conjunction with 1521 user login procedures). As a result, callers requesting non-default 1522 values for lifetime_req must recognize that such requests cannot 1523 always be honored and must be prepared to accommodate the use of 1524 returned credentials with different lifetimes as indicated in 1525 lifetime_rec. 1526 1527 The caller of GSS_Acquire_cred() can explicitly specify a set of 1528 mech_types which are to be accommodated in the returned credentials 1529 (desired_mechs argument), or can request credentials for a system- 1530 defined default set of mech_types. Selection of the system-specified 1531 default set is recommended in the interests of application 1532 portability. The actual_mechs return value may be interrogated by the 1533 caller to determine the set of mechanisms with which the returned 1534 credentials may be used. 1535 15362.1.2: GSS_Release_cred call 1537 1538 Input: 1539 1540 o cred_handle CREDENTIAL HANDLE - NULL specifies that 1541 the credential elements used when default credential behavior 1542 is requested be released. 1543 1544 Outputs: 1545 1546 o major_status INTEGER, 1547 1548 o minor_status INTEGER 1549 1550 Return major_status codes: 1551 1552 o GSS_S_COMPLETE indicates that the credentials referenced by the 1553 input cred_handle were released for purposes of subsequent 1554 access by the caller. The effect on other processes which may 1555 be authorized shared access to such credentials is a local 1556 matter. 1557 1558 o GSS_S_NO_CRED indicates that no release operation was 1559 performed, either because the input cred_handle was invalid or 1560 because the caller lacks authorization to access the 1561 referenced credentials. 1562 1563 o GSS_S_FAILURE indicates that the release operation failed for 1564 reasons unspecified at the GSS-API level. 1565 1566 1567 1568 1569 1570Linn Standards Track [Page 28] 1571 1572RFC 2078 GSS-API January 1997 1573 1574 1575 Provides a means for a caller to explicitly request that credentials 1576 be released when their use is no longer required. Note that system- 1577 specific credential management functions are also likely to exist, 1578 for example to assure that credentials shared among processes are 1579 properly deleted when all affected processes terminate, even if no 1580 explicit release requests are issued by those processes. Given the 1581 fact that multiple callers are not precluded from gaining authorized 1582 access to the same credentials, invocation of GSS_Release_cred() 1583 cannot be assumed to delete a particular set of credentials on a 1584 system-wide basis. 1585 15862.1.3: GSS_Inquire_cred call 1587 1588 Input: 1589 1590 o cred_handle CREDENTIAL HANDLE -NULL specifies that the 1591 credential elements used when default credential behavior is 1592 requested are to be queried 1593 1594 Outputs: 1595 1596 o major_status INTEGER, 1597 1598 o minor_status INTEGER, 1599 1600 o cred_name INTERNAL NAME, 1601 1602 o lifetime_rec INTEGER -in seconds, or reserved value for 1603 INDEFINITE 1604 1605 o cred_usage INTEGER, -0=INITIATE-AND-ACCEPT, 1=INITIATE-ONLY, 1606 2=ACCEPT-ONLY 1607 1608 o mech_set SET OF OBJECT IDENTIFIER 1609 1610 Return major_status codes: 1611 1612 o GSS_S_COMPLETE indicates that the credentials referenced by the 1613 input cred_handle argument were valid, and that the output 1614 cred_name, lifetime_rec, and cred_usage values represent, 1615 respectively, the credentials' associated principal name, 1616 remaining lifetime, suitable usage modes, and supported 1617 mechanism types. 1618 1619 o GSS_S_NO_CRED indicates that no information could be returned 1620 about the referenced credentials, either because the input 1621 cred_handle was invalid or because the caller lacks 1622 authorization to access the referenced credentials. 1623 1624 1625 1626Linn Standards Track [Page 29] 1627 1628RFC 2078 GSS-API January 1997 1629 1630 1631 o GSS_S_DEFECTIVE_CREDENTIAL indicates that the referenced 1632 credentials are invalid. 1633 1634 o GSS_S_CREDENTIALS_EXPIRED indicates that the referenced 1635 credentials have expired. 1636 1637 o GSS_S_FAILURE indicates that the operation failed for 1638 reasons unspecified at the GSS-API level. 1639 1640 The GSS_Inquire_cred() call is defined primarily for the use of those 1641 callers which request use of default credential behavior rather than 1642 acquiring credentials explicitly with GSS_Acquire_cred(). It enables 1643 callers to determine a credential structure's associated principal 1644 name, remaining validity period, usability for security context 1645 initiation and/or acceptance, and supported mechanisms. 1646 1647 For a multi-mechanism credential, the returned "lifetime" specifier 1648 indicates the shortest lifetime of any of the mechanisms' elements in 1649 the credential (for either context initiation or acceptance 1650 purposes). 1651 1652 GSS_Inquire_cred() should indicate INITIATE-AND-ACCEPT for 1653 "cred_usage" if both of the following conditions hold: 1654 1655 (1) there exists in the credential an element which allows context 1656 initiation using some mechanism 1657 1658 (2) there exists in the credential an element which allows context 1659 acceptance using some mechanism (allowably, but not necessarily, 1660 one of the same mechanism(s) qualifying for (1)). 1661 1662 If condition (1) holds but not condition (2), GSS_Inquire_cred() 1663 should indicate INITIATE-ONLY for "cred_usage". If condition (2) 1664 holds but not condition (1), GSS_Inquire_cred() should indicate 1665 ACCEPT-ONLY for "cred_usage". 1666 1667 Callers requiring finer disambiguation among available combinations 1668 of lifetimes, usage modes, and mechanisms should call the 1669 GSS_Inquire_cred_by_mech() routine, passing that routine one of the 1670 mech OIDs returned by GSS_Inquire_cred(). 1671 1672 1673 1674 1675 1676 1677 1678 1679 1680 1681 1682Linn Standards Track [Page 30] 1683 1684RFC 2078 GSS-API January 1997 1685 1686 16872.1.4: GSS_Add_cred call 1688 1689 Inputs: 1690 1691 o input_cred_handle CREDENTIAL HANDLE - handle to credential 1692 structure created with prior GSS_Acquire_cred() or 1693 GSS_Add_cred() call, or NULL to append elements to the set 1694 which are applied for the caller when default credential 1695 behavior is specified. 1696 1697 o desired_name INTERNAL NAME - NULL requests locally-determined 1698 default 1699 1700 o initiator_time_req INTEGER - in seconds; 0 requests default 1701 1702 o acceptor_time_req INTEGER - in seconds; 0 requests default 1703 1704 o desired_mech OBJECT IDENTIFIER 1705 1706 o cred_usage INTEGER - 0=INITIATE-AND-ACCEPT, 1=INITIATE-ONLY, 1707 2=ACCEPT-ONLY 1708 1709 Outputs: 1710 1711 o major_status INTEGER, 1712 1713 o minor_status INTEGER, 1714 1715 o output_cred_handle CREDENTIAL HANDLE, - NULL to request that 1716 credential elements be added "in place" to the credential 1717 structure identified by input_cred_handle, non-NULL pointer 1718 to request that a new credential structure and handle be created. 1719 1720 o actual_mechs SET OF OBJECT IDENTIFIER, 1721 1722 o initiator_time_rec INTEGER - in seconds, or reserved value for 1723 INDEFINITE 1724 1725 o acceptor_time_rec INTEGER - in seconds, or reserved value for 1726 INDEFINITE 1727 1728 o cred_usage INTEGER, -0=INITIATE-AND-ACCEPT, 1=INITIATE-ONLY, 1729 2=ACCEPT-ONLY 1730 1731 o mech_set SET OF OBJECT IDENTIFIER -- full set of mechanisms 1732 supported by resulting credential. 1733 1734 1735 1736 1737 1738Linn Standards Track [Page 31] 1739 1740RFC 2078 GSS-API January 1997 1741 1742 1743 Return major_status codes: 1744 1745 o GSS_S_COMPLETE indicates that the credentials referenced by 1746 the input_cred_handle argument were valid, and that the 1747 resulting credential from GSS_Add_cred() is valid for the 1748 durations indicated in initiator_time_rec and acceptor_time_rec, 1749 suitable for the usage requested in cred_usage, and for the 1750 mechanisms indicated in actual_mechs. 1751 1752 o GSS_S_DUPLICATE_ELEMENT indicates that the input desired_mech 1753 specified a mechanism for which the referenced credential 1754 already contained a credential element with overlapping 1755 cred_usage and validity time specifiers. 1756 1757 o GSS_S_BAD_MECH indicates that the input desired_mech specified 1758 a mechanism unsupported by the GSS-API implementation, causing 1759 the GSS_Add_cred() operation to fail. 1760 1761 o GSS_S_BAD_NAMETYPE indicates that the provided desired_name 1762 is uninterpretable or of a type unsupported by the applicable 1763 underlying GSS-API mechanism(s), so the GSS_Add_cred() operation 1764 could not be performed for that name. 1765 1766 o GSS_S_BAD_NAME indicates that the provided desired_name is 1767 inconsistent in terms of internally-incorporated type specifier 1768 information, so the GSS_Add_cred() operation could not be 1769 performed for that name. 1770 1771 o GSS_S_NO_CRED indicates that the input_cred_handle referenced 1772 invalid or inaccessible credentials. 1773 1774 o GSS_S_FAILURE indicates that the operation failed for 1775 reasons unspecified at the GSS-API level, including lack of 1776 authorization to establish or use credentials representing 1777 the requested identity. 1778 1779 GSS_Add_cred() enables callers to construct credentials iteratively 1780 by adding credential elements in successive operations, corresponding 1781 to different mechanisms. This offers particular value in multi- 1782 mechanism environments, as the major_status and minor_status values 1783 returned on each iteration are individually visible and can therefore 1784 be interpreted unambiguously on a per-mechanism basis. 1785 1786 The same input desired_name, or default reference, should be used on 1787 all GSS_Acquire_cred() and GSS_Add_cred() calls corresponding to a 1788 particular credential. 1789 1790 1791 1792 1793 1794Linn Standards Track [Page 32] 1795 1796RFC 2078 GSS-API January 1997 1797 1798 17992.1.5: GSS_Inquire_cred_by_mech call 1800 1801 Inputs: 1802 1803 o cred_handle CREDENTIAL HANDLE -- NULL specifies that the 1804 credential elements used when default credential behavior is 1805 requested are to be queried 1806 1807 o mech_type OBJECT IDENTIFIER -- specific mechanism for 1808 which credentials are being queried 1809 1810 Outputs: 1811 1812 o major_status INTEGER, 1813 1814 o minor_status INTEGER, 1815 1816 o cred_name INTERNAL NAME, -- guaranteed to be MN 1817 1818 o lifetime_rec_initiate INTEGER -- in seconds, or reserved value for 1819 INDEFINITE 1820 1821 o lifetime_rec_accept INTEGER -- in seconds, or reserved value for 1822 INDEFINITE 1823 1824 o cred_usage INTEGER, -0=INITIATE-AND-ACCEPT, 1=INITIATE-ONLY, 1825 2=ACCEPT-ONLY 1826 1827 Return major_status codes: 1828 1829 o GSS_S_COMPLETE indicates that the credentials referenced by the 1830 input cred_handle argument were valid, that the mechanism 1831 indicated by the input mech_type was represented with elements 1832 within those credentials, and that the output cred_name, 1833 lifetime_rec_initiate, lifetime_rec_accept, and cred_usage values 1834 represent, respectively, the credentials' associated principal 1835 name, remaining lifetimes, and suitable usage modes. 1836 1837 o GSS_S_NO_CRED indicates that no information could be returned 1838 about the referenced credentials, either because the input 1839 cred_handle was invalid or because the caller lacks 1840 authorization to access the referenced credentials. 1841 1842 o GSS_S_DEFECTIVE_CREDENTIAL indicates that the referenced 1843 credentials are invalid. 1844 1845 o GSS_S_CREDENTIALS_EXPIRED indicates that the referenced 1846 credentials have expired. 1847 1848 1849 1850Linn Standards Track [Page 33] 1851 1852RFC 2078 GSS-API January 1997 1853 1854 1855 o GSS_S_BAD_MECH indicates that the referenced credentials do not 1856 contain elements for the requested mechanism. 1857 1858 o GSS_S_FAILURE indicates that the operation failed for reasons 1859 unspecified at the GSS-API level. 1860 1861 The GSS_Inquire_cred_by_mech() call enables callers in multi- 1862 mechanism environments to acquire specific data about available 1863 combinations of lifetimes, usage modes, and mechanisms within a 1864 credential structure. The lifetime_rec_initiate result indicates the 1865 available lifetime for context initiation purposes; the 1866 lifetime_rec_accept result indicates the available lifetime for 1867 context acceptance purposes. 1868 18692.2: Context-level calls 1870 1871 This group of calls is devoted to the establishment and management of 1872 security contexts between peers. A context's initiator calls 1873 GSS_Init_sec_context(), resulting in generation of a token which the 1874 caller passes to the target. At the target, that token is passed to 1875 GSS_Accept_sec_context(). Depending on the underlying mech_type and 1876 specified options, additional token exchanges may be performed in the 1877 course of context establishment; such exchanges are accommodated by 1878 GSS_S_CONTINUE_NEEDED status returns from GSS_Init_sec_context() and 1879 GSS_Accept_sec_context(). 1880 1881 Either party to an established context may invoke 1882 GSS_Delete_sec_context() to flush context information when a context 1883 is no longer required. GSS_Process_context_token() is used to 1884 process received tokens carrying context-level control information. 1885 GSS_Context_time() allows a caller to determine the length of time 1886 for which an established context will remain valid. 1887 GSS_Inquire_context() returns status information describing context 1888 characteristics. GSS_Wrap_size_limit() allows a caller to determine 1889 the size of a token which will be generated by a GSS_Wrap() 1890 operation. GSS_Export_sec_context() and GSS_Import_sec_context() 1891 enable transfer of active contexts between processes on an end 1892 system. 1893 18942.2.1: GSS_Init_sec_context call 1895 1896 Inputs: 1897 1898 o claimant_cred_handle CREDENTIAL HANDLE, -NULL specifies "use 1899 default" 1900 1901 o input_context_handle CONTEXT HANDLE, -0 specifies "none assigned 1902 yet" 1903 1904 1905 1906Linn Standards Track [Page 34] 1907 1908RFC 2078 GSS-API January 1997 1909 1910 1911 o targ_name INTERNAL NAME, 1912 1913 o mech_type OBJECT IDENTIFIER, -NULL parameter specifies "use 1914 default" 1915 1916 o deleg_req_flag BOOLEAN, 1917 1918 o mutual_req_flag BOOLEAN, 1919 1920 o replay_det_req_flag BOOLEAN, 1921 1922 o sequence_req_flag BOOLEAN, 1923 1924 o anon_req_flag BOOLEAN, 1925 1926 o lifetime_req INTEGER,-0 specifies default lifetime 1927 1928 o chan_bindings OCTET STRING, 1929 1930 o input_token OCTET STRING-NULL or token received from target 1931 1932 Outputs: 1933 1934 o major_status INTEGER, 1935 1936 o minor_status INTEGER, 1937 1938 o output_context_handle CONTEXT HANDLE, 1939 1940 o mech_type OBJECT IDENTIFIER, -actual mechanism always 1941 indicated, never NULL 1942 1943 o output_token OCTET STRING, -NULL or token to pass to context 1944 target 1945 1946 o deleg_state BOOLEAN, 1947 1948 o mutual_state BOOLEAN, 1949 1950 o replay_det_state BOOLEAN, 1951 1952 o sequence_state BOOLEAN, 1953 1954 o anon_state BOOLEAN, 1955 1956 o trans_state BOOLEAN, 1957 1958 o prot_ready_state BOOLEAN, -- see Section 1.2.7 1959 1960 1961 1962Linn Standards Track [Page 35] 1963 1964RFC 2078 GSS-API January 1997 1965 1966 1967 o conf_avail BOOLEAN, 1968 1969 o integ_avail BOOLEAN, 1970 1971 o lifetime_rec INTEGER - in seconds, or reserved value for 1972 INDEFINITE 1973 1974 This call may block pending network interactions for those mech_types 1975 in which an authentication server or other network entity must be 1976 consulted on behalf of a context initiator in order to generate an 1977 output_token suitable for presentation to a specified target. 1978 1979 Return major_status codes: 1980 1981 o GSS_S_COMPLETE indicates that context-level information was 1982 successfully initialized, and that the returned output_token 1983 will provide sufficient information for the target to perform 1984 per-message processing on the newly-established context. 1985 1986 o GSS_S_CONTINUE_NEEDED indicates that control information in the 1987 returned output_token must be sent to the target, and that a 1988 reply must be received and passed as the input_token argument 1989 to a continuation call to GSS_Init_sec_context(), before 1990 per-message processing can be performed in conjunction with 1991 this context. 1992 1993 o GSS_S_DEFECTIVE_TOKEN indicates that consistency checks 1994 performed on the input_token failed, preventing further 1995 processing from being performed based on that token. 1996 1997 o GSS_S_DEFECTIVE_CREDENTIAL indicates that consistency checks 1998 performed on the credential structure referenced by 1999 claimant_cred_handle failed, preventing further processing from 2000 being performed using that credential structure. 2001 2002 o GSS_S_BAD_SIG indicates that the received input_token 2003 contains an incorrect integrity check, so context setup cannot 2004 be accomplished. 2005 2006 o GSS_S_NO_CRED indicates that no context was established, 2007 either because the input cred_handle was invalid, because the 2008 referenced credentials are valid for context acceptor use 2009 only, or because the caller lacks authorization to access the 2010 referenced credentials. 2011 2012 o GSS_S_CREDENTIALS_EXPIRED indicates that the credentials 2013 provided through the input claimant_cred_handle argument are no 2014 longer valid, so context establishment cannot be completed. 2015 2016 2017 2018Linn Standards Track [Page 36] 2019 2020RFC 2078 GSS-API January 1997 2021 2022 2023 o GSS_S_BAD_BINDINGS indicates that a mismatch between the 2024 caller-provided chan_bindings and those extracted from the 2025 input_token was detected, signifying a security-relevant 2026 event and preventing context establishment. (This result will 2027 be returned by GSS_Init_sec_context only for contexts where 2028 mutual_state is TRUE.) 2029 2030 o GSS_S_OLD_TOKEN indicates that the input_token is too old to 2031 be checked for integrity. This is a fatal error during context 2032 establishment. 2033 2034 o GSS_S_DUPLICATE_TOKEN indicates that the input token has a 2035 correct integrity check, but is a duplicate of a token already 2036 processed. This is a fatal error during context establishment. 2037 2038 o GSS_S_NO_CONTEXT indicates that no valid context was recognized 2039 for the input context_handle provided; this major status will 2040 be returned only for successor calls following GSS_S_CONTINUE_ 2041 NEEDED status returns. 2042 2043 o GSS_S_BAD_NAMETYPE indicates that the provided targ_name is 2044 of a type uninterpretable or unsupported by the applicable 2045 underlying GSS-API mechanism(s), so context establishment 2046 cannot be completed. 2047 2048 o GSS_S_BAD_NAME indicates that the provided targ_name is 2049 inconsistent in terms of internally-incorporated type specifier 2050 information, so context establishment cannot be accomplished. 2051 2052 o GSS_S_BAD_MECH indicates receipt of a context establishment token 2053 or of a caller request specifying a mechanism unsupported by 2054 the local system or with the caller's active credentials 2055 2056 o GSS_S_FAILURE indicates that context setup could not be 2057 accomplished for reasons unspecified at the GSS-API level, and 2058 that no interface-defined recovery action is available. 2059 2060 This routine is used by a context initiator, and ordinarily emits one 2061 (or, for the case of a multi-step exchange, more than one) 2062 output_token suitable for use by the target within the selected 2063 mech_type's protocol. Using information in the credentials structure 2064 referenced by claimant_cred_handle, GSS_Init_sec_context() 2065 initializes the data structures required to establish a security 2066 context with target targ_name. The targ_name may be any valid 2067 INTERNAL NAME; it need not be an MN. The claimant_cred_handle must 2068 correspond to the same valid credentials structure on the initial 2069 call to GSS_Init_sec_context() and on any successor calls resulting 2070 from GSS_S_CONTINUE_NEEDED status returns; different protocol 2071 2072 2073 2074Linn Standards Track [Page 37] 2075 2076RFC 2078 GSS-API January 1997 2077 2078 2079 sequences modeled by the GSS_S_CONTINUE_NEEDED facility will require 2080 access to credentials at different points in the context 2081 establishment sequence. 2082 2083 The input_context_handle argument is 0, specifying "not yet 2084 assigned", on the first GSS_Init_sec_context() call relating to a 2085 given context. If successful (i.e., if accompanied by major_status 2086 GSS_S_COMPLETE or GSS_S_CONTINUE_NEEDED), and only if successful, the 2087 initial GSS_Init_sec_context() call returns a non-zero 2088 output_context_handle for use in future references to this context. 2089 Once a non-zero output_context_handle has been returned, GSS-API 2090 callers should call GSS_Delete_sec_context() to release context- 2091 related resources if errors occur in later phases of context 2092 establishment, or when an established context is no longer required. 2093 2094 When continuation attempts to GSS_Init_sec_context() are needed to 2095 perform context establishment, the previously-returned non-zero 2096 handle value is entered into the input_context_handle argument and 2097 will be echoed in the returned output_context_handle argument. On 2098 such continuation attempts (and only on continuation attempts) the 2099 input_token value is used, to provide the token returned from the 2100 context's target. 2101 2102 The chan_bindings argument is used by the caller to provide 2103 information binding the security context to security-related 2104 characteristics (e.g., addresses, cryptographic keys) of the 2105 underlying communications channel. See Section 1.1.6 of this document 2106 for more discussion of this argument's usage. 2107 2108 The input_token argument contains a message received from the target, 2109 and is significant only on a call to GSS_Init_sec_context() which 2110 follows a previous return indicating GSS_S_CONTINUE_NEEDED 2111 major_status. 2112 2113 It is the caller's responsibility to establish a communications path 2114 to the target, and to transmit any returned output_token (independent 2115 of the accompanying returned major_status value) to the target over 2116 that path. The output_token can, however, be transmitted along with 2117 the first application-provided input message to be processed by 2118 GSS_GetMIC() or GSS_Wrap() in conjunction with a successfully- 2119 established context. 2120 2121 The initiator may request various context-level functions through 2122 input flags: the deleg_req_flag requests delegation of access rights, 2123 the mutual_req_flag requests mutual authentication, the 2124 replay_det_req_flag requests that replay detection features be 2125 applied to messages transferred on the established context, and the 2126 sequence_req_flag requests that sequencing be enforced. (See Section 2127 2128 2129 2130Linn Standards Track [Page 38] 2131 2132RFC 2078 GSS-API January 1997 2133 2134 2135 1.2.3 for more information on replay detection and sequencing 2136 features.) The anon_req_flag requests that the initiator's identity 2137 not be transferred within tokens to be sent to the acceptor. 2138 2139 Not all of the optionally-requestable features will be available in 2140 all underlying mech_types. The corresponding return state values 2141 deleg_state, mutual_state, replay_det_state, and sequence_state 2142 indicate, as a function of mech_type processing capabilities and 2143 initiator-provided input flags, the set of features which will be 2144 active on the context. The returned trans_state value indicates 2145 whether the context is transferable to other processes through use of 2146 GSS_Export_sec_context(). These state indicators' values are 2147 undefined unless either the routine's major_status indicates 2148 GSS_S_COMPLETE, or TRUE prot_ready_state is returned along with 2149 GSS_S_CONTINUE_NEEDED major_status; for the latter case, it is 2150 possible that additional features, not confirmed or indicated along 2151 with TRUE prot_ready_state, will be confirmed and indicated when 2152 GSS_S_COMPLETE is subsequently returned. 2153 2154 The returned anon_state and prot_ready_state values are significant 2155 for both GSS_S_COMPLETE and GSS_S_CONTINUE_NEEDED major_status 2156 returns from GSS_Init_sec_context(). When anon_state is returned 2157 TRUE, this indicates that neither the current token nor its 2158 predecessors delivers or has delivered the initiator's identity. 2159 Callers wishing to perform context establishment only if anonymity 2160 support is provided should transfer a returned token from 2161 GSS_Init_sec_context() to the peer only if it is accompanied by a 2162 TRUE anon_state indicator. When prot_ready_state is returned TRUE in 2163 conjunction with GSS_S_CONTINUE_NEEDED major_status, this indicates 2164 that per-message protection operations may be applied on the context: 2165 see Section 1.2.7 for further discussion of this facility. 2166 2167 Failure to provide the precise set of features requested by the 2168 caller does not cause context establishment to fail; it is the 2169 caller's prerogative to delete the context if the feature set 2170 provided is unsuitable for the caller's use. 2171 2172 The returned mech_type value indicates the specific mechanism 2173 employed on the context, is valid only along with major_status 2174 GSS_S_COMPLETE, and will never indicate the value for "default". 2175 Note that, for the case of certain mechanisms which themselves 2176 perform negotiation, the returned mech_type result may indicate 2177 selection of a mechanism identified by an OID different than that 2178 passed in the input mech_type argument. 2179 2180 The conf_avail return value indicates whether the context supports 2181 per-message confidentiality services, and so informs the caller 2182 whether or not a request for encryption through the conf_req_flag 2183 2184 2185 2186Linn Standards Track [Page 39] 2187 2188RFC 2078 GSS-API January 1997 2189 2190 2191 input to GSS_Wrap() can be honored. In similar fashion, the 2192 integ_avail return value indicates whether per-message integrity 2193 services are available (through either GSS_GetMIC() or GSS_Wrap()) on 2194 the established context. These state indicators' values are undefined 2195 unless either the routine's major_status indicates GSS_S_COMPLETE, or 2196 TRUE prot_ready_state is returned along with GSS_S_CONTINUE_NEEDED 2197 major_status. 2198 2199 The lifetime_req input specifies a desired upper bound for the 2200 lifetime of the context to be established, with a value of 0 used to 2201 request a default lifetime. The lifetime_rec return value indicates 2202 the length of time for which the context will be valid, expressed as 2203 an offset from the present; depending on mechanism capabilities, 2204 credential lifetimes, and local policy, it may not correspond to the 2205 value requested in lifetime_req. If no constraints on context 2206 lifetime are imposed, this may be indicated by returning a reserved 2207 value representing INDEFINITE lifetime_req. The value of lifetime_rec 2208 is undefined unless the routine's major_status indicates 2209 GSS_S_COMPLETE. 2210 2211 If the mutual_state is TRUE, this fact will be reflected within the 2212 output_token. A call to GSS_Accept_sec_context() at the target in 2213 conjunction with such a context will return a token, to be processed 2214 by a continuation call to GSS_Init_sec_context(), in order to 2215 achieve mutual authentication. 2216 22172.2.2: GSS_Accept_sec_context call 2218 2219 Inputs: 2220 2221 o acceptor_cred_handle CREDENTIAL HANDLE, -- NULL specifies 2222 "use default" 2223 2224 o input_context_handle CONTEXT HANDLE, -- 0 specifies 2225 "not yet assigned" 2226 2227 o chan_bindings OCTET STRING, 2228 2229 o input_token OCTET STRING 2230 2231 Outputs: 2232 2233 o major_status INTEGER, 2234 2235 o minor_status INTEGER, 2236 2237 o src_name INTERNAL NAME, -- guaranteed to be MN 2238 2239 2240 2241 2242Linn Standards Track [Page 40] 2243 2244RFC 2078 GSS-API January 1997 2245 2246 2247 o mech_type OBJECT IDENTIFIER, 2248 2249 o output_context_handle CONTEXT HANDLE, 2250 2251 o deleg_state BOOLEAN, 2252 2253 o mutual_state BOOLEAN, 2254 2255 o replay_det_state BOOLEAN, 2256 2257 o sequence_state BOOLEAN, 2258 2259 o anon_state BOOLEAN, 2260 2261 o trans_state BOOLEAN, 2262 2263 o prot_ready_state BOOLEAN, -- see Section 1.2.7 for discussion 2264 2265 o conf_avail BOOLEAN, 2266 2267 o integ_avail BOOLEAN, 2268 2269 o lifetime_rec INTEGER, - in seconds, or reserved value for 2270 INDEFINITE 2271 2272 o delegated_cred_handle CREDENTIAL HANDLE, 2273 2274 o output_token OCTET STRING -NULL or token to pass to context 2275 initiator 2276 2277 This call may block pending network interactions for those mech_types 2278 in which a directory service or other network entity must be 2279 consulted on behalf of a context acceptor in order to validate a 2280 received input_token. 2281 2282 Return major_status codes: 2283 2284 o GSS_S_COMPLETE indicates that context-level data structures 2285 were successfully initialized, and that per-message processing 2286 can now be performed in conjunction with this context. 2287 2288 o GSS_S_CONTINUE_NEEDED indicates that control information in the 2289 returned output_token must be sent to the initiator, and that 2290 a response must be received and passed as the input_token 2291 argument to a continuation call to GSS_Accept_sec_context(), 2292 before per-message processing can be performed in conjunction 2293 with this context. 2294 2295 2296 2297 2298Linn Standards Track [Page 41] 2299 2300RFC 2078 GSS-API January 1997 2301 2302 2303 o GSS_S_DEFECTIVE_TOKEN indicates that consistency checks performed 2304 on the input_token failed, preventing further processing from 2305 being performed based on that token. 2306 2307 o GSS_S_DEFECTIVE_CREDENTIAL indicates that consistency checks 2308 performed on the credential structure referenced by 2309 acceptor_cred_handle failed, preventing further processing from 2310 being performed using that credential structure. 2311 2312 o GSS_S_BAD_SIG indicates that the received input_token contains 2313 an incorrect integrity check, so context setup cannot be 2314 accomplished. 2315 2316 o GSS_S_DUPLICATE_TOKEN indicates that the integrity check on the 2317 received input_token was correct, but that the input_token 2318 was recognized as a duplicate of an input_token already 2319 processed. No new context is established. 2320 2321 o GSS_S_OLD_TOKEN indicates that the integrity check on the received 2322 input_token was correct, but that the input_token is too old 2323 to be checked for duplication against previously-processed 2324 input_tokens. No new context is established. 2325 2326 o GSS_S_NO_CRED indicates that no context was established, either 2327 because the input cred_handle was invalid, because the 2328 referenced credentials are valid for context initiator use 2329 only, or because the caller lacks authorization to access the 2330 referenced credentials. 2331 2332 o GSS_S_CREDENTIALS_EXPIRED indicates that the credentials provided 2333 through the input acceptor_cred_handle argument are no 2334 longer valid, so context establishment cannot be completed. 2335 2336 o GSS_S_BAD_BINDINGS indicates that a mismatch between the 2337 caller-provided chan_bindings and those extracted from the 2338 input_token was detected, signifying a security-relevant 2339 event and preventing context establishment. 2340 2341 o GSS_S_NO_CONTEXT indicates that no valid context was recognized 2342 for the input context_handle provided; this major status will 2343 be returned only for successor calls following GSS_S_CONTINUE_ 2344 NEEDED status returns. 2345 2346 o GSS_S_BAD_MECH indicates receipt of a context establishment token 2347 specifying a mechanism unsupported by the local system or with 2348 the caller's active credentials. 2349 2350 2351 2352 2353 2354Linn Standards Track [Page 42] 2355 2356RFC 2078 GSS-API January 1997 2357 2358 2359 o GSS_S_FAILURE indicates that context setup could not be 2360 accomplished for reasons unspecified at the GSS-API level, and 2361 that no interface-defined recovery action is available. 2362 2363 The GSS_Accept_sec_context() routine is used by a context target. 2364 Using information in the credentials structure referenced by the 2365 input acceptor_cred_handle, it verifies the incoming input_token and 2366 (following the successful completion of a context establishment 2367 sequence) returns the authenticated src_name and the mech_type used. 2368 The returned src_name is guaranteed to be an MN, processed by the 2369 mechanism under which the context was established. The 2370 acceptor_cred_handle must correspond to the same valid credentials 2371 structure on the initial call to GSS_Accept_sec_context() and on any 2372 successor calls resulting from GSS_S_CONTINUE_NEEDED status returns; 2373 different protocol sequences modeled by the GSS_S_CONTINUE_NEEDED 2374 mechanism will require access to credentials at different points in 2375 the context establishment sequence. 2376 2377 The input_context_handle argument is 0, specifying "not yet 2378 assigned", on the first GSS_Accept_sec_context() call relating to a 2379 given context. If successful (i.e., if accompanied by major_status 2380 GSS_S_COMPLETE or GSS_S_CONTINUE_NEEDED), and only if successful, the 2381 initial GSS_Accept_sec_context() call returns a non-zero 2382 output_context_handle for use in future references to this context. 2383 Once a non-zero output_context_handle has been returned, GSS-API 2384 callers should call GSS_Delete_sec_context() to release context- 2385 related resources if errors occur in later phases of context 2386 establishment, or when an established context is no longer required. 2387 2388 The chan_bindings argument is used by the caller to provide 2389 information binding the security context to security-related 2390 characteristics (e.g., addresses, cryptographic keys) of the 2391 underlying communications channel. See Section 1.1.6 of this document 2392 for more discussion of this argument's usage. 2393 2394 The returned state results (deleg_state, mutual_state, 2395 replay_det_state, sequence_state, anon_state, trans_state, and 2396 prot_ready_state) reflect the same information as described for 2397 GSS_Init_sec_context(), and their values are significant under the 2398 same return state conditions. 2399 2400 2401 2402 2403 2404 2405 2406 2407 2408 2409 2410Linn Standards Track [Page 43] 2411 2412RFC 2078 GSS-API January 1997 2413 2414 2415 The conf_avail return value indicates whether the context supports 2416 per-message confidentiality services, and so informs the caller 2417 whether or not a request for encryption through the conf_req_flag 2418 input to GSS_Wrap() can be honored. In similar fashion, the 2419 integ_avail return value indicates whether per-message integrity 2420 services are available (through either GSS_GetMIC() or GSS_Wrap()) 2421 on the established context. These values are significant under the 2422 same return state conditions as described under 2423 GSS_Init_sec_context(). 2424 2425 The lifetime_rec return value is significant only in conjunction with 2426 GSS_S_COMPLETE major_status, and indicates the length of time for 2427 which the context will be valid, expressed as an offset from the 2428 present. 2429 2430 The mech_type return value indicates the specific mechanism employed 2431 on the context, is valid only along with major_status GSS_S_COMPLETE, 2432 and will never indicate the value for "default". 2433 2434 The delegated_cred_handle result is significant only when deleg_state 2435 is TRUE, and provides a means for the target to reference the 2436 delegated credentials. The output_token result, when non-NULL, 2437 provides a context-level token to be returned to the context 2438 initiator to continue a multi-step context establishment sequence. As 2439 noted with GSS_Init_sec_context(), any returned token should be 2440 transferred to the context's peer (in this case, the context 2441 initiator), independent of the value of the accompanying returned 2442 major_status. 2443 2444 Note: A target must be able to distinguish a context-level 2445 input_token, which is passed to GSS_Accept_sec_context(), from the 2446 per-message data elements passed to GSS_VerifyMIC() or GSS_Unwrap(). 2447 These data elements may arrive in a single application message, and 2448 GSS_Accept_sec_context() must be performed before per-message 2449 processing can be performed successfully. 2450 24512.2.3: GSS_Delete_sec_context call 2452 2453 Input: 2454 2455 o context_handle CONTEXT HANDLE 2456 2457 Outputs: 2458 2459 o major_status INTEGER, 2460 2461 o minor_status INTEGER, 2462 2463 2464 2465 2466Linn Standards Track [Page 44] 2467 2468RFC 2078 GSS-API January 1997 2469 2470 2471 o output_context_token OCTET STRING 2472 2473 Return major_status codes: 2474 2475 o GSS_S_COMPLETE indicates that the context was recognized, and that 2476 relevant context-specific information was flushed. If the caller 2477 provides a non-null buffer to receive an output_context_token, and 2478 the mechanism returns a non-NULL token into that buffer, the 2479 returned output_context_token is ready for transfer to the 2480 context's peer. 2481 2482 o GSS_S_NO_CONTEXT indicates that no valid context was recognized 2483 for the input context_handle provided, so no deletion was 2484 performed. 2485 2486 o GSS_S_FAILURE indicates that the context is recognized, but 2487 that the GSS_Delete_sec_context() operation could not be 2488 performed for reasons unspecified at the GSS-API level. 2489 2490 This call may block pending network interactions for mech_types in 2491 which active notification must be made to a central server when a 2492 security context is to be deleted. 2493 2494 This call can be made by either peer in a security context, to flush 2495 context-specific information. If a non-null output_context_token 2496 parameter is provided by the caller, an output_context_token may be 2497 returned to the caller. If an output_context_token is provided to 2498 the caller, it can be passed to the context's peer to inform the 2499 peer's GSS-API implementation that the peer's corresponding context 2500 information can also be flushed. (Once a context is established, the 2501 peers involved are expected to retain cached credential and context- 2502 related information until the information's expiration time is 2503 reached or until a GSS_Delete_sec_context() call is made.) 2504 2505 The facility for context_token usage to signal context deletion is 2506 retained for compatibility with GSS-API Version 1. For current 2507 usage, it is recommended that both peers to a context invoke 2508 GSS_Delete_sec_context() independently, passing a null 2509 output_context_token buffer to indicate that no context_token is 2510 required. Implementations of GSS_Delete_sec_context() should delete 2511 relevant locally-stored context information. 2512 2513 Attempts to perform per-message processing on a deleted context will 2514 result in error returns. 2515 2516 2517 2518 2519 2520 2521 2522Linn Standards Track [Page 45] 2523 2524RFC 2078 GSS-API January 1997 2525 2526 25272.2.4: GSS_Process_context_token call 2528 2529 Inputs: 2530 2531 o context_handle CONTEXT HANDLE, 2532 2533 o input_context_token OCTET STRING 2534 2535 Outputs: 2536 2537 o major_status INTEGER, 2538 2539 o minor_status INTEGER, 2540 2541 Return major_status codes: 2542 2543 o GSS_S_COMPLETE indicates that the input_context_token was 2544 successfully processed in conjunction with the context 2545 referenced by context_handle. 2546 2547 o GSS_S_DEFECTIVE_TOKEN indicates that consistency checks 2548 performed on the received context_token failed, preventing 2549 further processing from being performed with that token. 2550 2551 o GSS_S_NO_CONTEXT indicates that no valid context was recognized 2552 for the input context_handle provided. 2553 2554 o GSS_S_FAILURE indicates that the context is recognized, but 2555 that the GSS_Process_context_token() operation could not be 2556 performed for reasons unspecified at the GSS-API level. 2557 2558 This call is used to process context_tokens received from a peer once 2559 a context has been established, with corresponding impact on 2560 context-level state information. One use for this facility is 2561 processing of the context_tokens generated by 2562 GSS_Delete_sec_context(); GSS_Process_context_token() will not block 2563 pending network interactions for that purpose. Another use is to 2564 process tokens indicating remote-peer context establishment failures 2565 after the point where the local GSS-API implementation has already 2566 indicated GSS_S_COMPLETE status. 2567 2568 2569 2570 2571 2572 2573 2574 2575 2576 2577 2578Linn Standards Track [Page 46] 2579 2580RFC 2078 GSS-API January 1997 2581 2582 25832.2.5: GSS_Context_time call 2584 2585 Input: 2586 2587 o context_handle CONTEXT HANDLE, 2588 2589 Outputs: 2590 2591 o major_status INTEGER, 2592 2593 o minor_status INTEGER, 2594 2595 o lifetime_rec INTEGER - in seconds, or reserved value for 2596 INDEFINITE 2597 2598 Return major_status codes: 2599 2600 o GSS_S_COMPLETE indicates that the referenced context is valid, 2601 and will remain valid for the amount of time indicated in 2602 lifetime_rec. 2603 2604 o GSS_S_CONTEXT_EXPIRED indicates that data items related to the 2605 referenced context have expired. 2606 2607 o GSS_S_CREDENTIALS_EXPIRED indicates that the context is 2608 recognized, but that its associated credentials have expired. 2609 2610 o GSS_S_NO_CONTEXT indicates that no valid context was recognized 2611 for the input context_handle provided. 2612 2613 o GSS_S_FAILURE indicates that the requested operation failed for 2614 reasons unspecified at the GSS-API level. 2615 2616 This call is used to determine the amount of time for which a 2617 currently established context will remain valid. 2618 26192.2.6: GSS_Inquire_context call 2620 2621 Input: 2622 2623 o context_handle CONTEXT HANDLE, 2624 2625 Outputs: 2626 2627 o major_status INTEGER, 2628 2629 o minor_status INTEGER, 2630 2631 2632 2633 2634Linn Standards Track [Page 47] 2635 2636RFC 2078 GSS-API January 1997 2637 2638 2639 o src_name INTERNAL NAME, -- name of context initiator, 2640 -- guaranteed to be MN 2641 2642 o targ_name INTERNAL NAME, -- name of context target, 2643 -- guaranteed to be MN 2644 2645 2646 o lifetime_rec INTEGER -- in seconds, or reserved value for 2647 INDEFINITE, 2648 2649 o mech_type OBJECT IDENTIFIER, -- the mechanism supporting this 2650 security context 2651 2652 o deleg_state BOOLEAN, 2653 2654 o mutual_state BOOLEAN, 2655 2656 o replay_det_state BOOLEAN, 2657 2658 o sequence_state BOOLEAN, 2659 2660 o anon_state BOOLEAN, 2661 2662 o trans_state BOOLEAN, 2663 2664 o prot_ready_state BOOLEAN, 2665 2666 o conf_avail BOOLEAN, 2667 2668 o integ_avail BOOLEAN, 2669 2670 o locally_initiated BOOLEAN, -- TRUE if initiator, FALSE if acceptor 2671 2672 Return major_status codes: 2673 2674 o GSS_S_COMPLETE indicates that the referenced context is valid 2675 and that src_name, targ_name, lifetime_rec, mech_type, deleg_state, 2676 mutual_state, replay_det_state, sequence_state, anon_state, 2677 trans_state, prot_ready_state, conf_avail, integ_avail, and 2678 locally_initiated return values describe the corresponding 2679 characteristics of the context. 2680 2681 o GSS_S_CONTEXT_EXPIRED indicates that the provided input 2682 context_handle is recognized, but that the referenced context 2683 has expired. Return values other than major_status and 2684 minor_status are undefined. 2685 2686 2687 2688 2689 2690Linn Standards Track [Page 48] 2691 2692RFC 2078 GSS-API January 1997 2693 2694 2695 o GSS_S_NO_CONTEXT indicates that no valid context was recognized 2696 for the input context_handle provided. Return values other than 2697 major_status and minor_status are undefined. 2698 2699 o GSS_S_FAILURE indicates that the requested operation failed for 2700 reasons unspecified at the GSS-API level. Return values other than 2701 major_status and minor_status are undefined. 2702 2703 This call is used to extract information describing characteristics 2704 of a security context. 2705 27062.2.7: GSS_Wrap_size_limit call 2707 2708 Inputs: 2709 2710 o context_handle CONTEXT HANDLE, 2711 2712 o qop INTEGER, 2713 2714 o output_size INTEGER 2715 2716 Outputs: 2717 2718 o major_status INTEGER, 2719 2720 o minor_status INTEGER, 2721 2722 o max_input_size INTEGER 2723 2724 Return major_status codes: 2725 2726 o GSS_S_COMPLETE indicates a successful token size determination: 2727 an input message with a length in octets equal to the 2728 returned max_input_size value will, when passed to GSS_Wrap() 2729 for processing on the context identified by the context_handle 2730 parameter and with the quality of protection specifier provided 2731 in the qop parameter, yield an output token no larger than the 2732 value of the provided output_size parameter. 2733 2734 o GSS_S_CONTEXT_EXPIRED indicates that the provided input 2735 context_handle is recognized, but that the referenced context 2736 has expired. Return values other than major_status and 2737 minor_status are undefined. 2738 2739 o GSS_S_NO_CONTEXT indicates that no valid context was recognized 2740 for the input context_handle provided. Return values other than 2741 major_status and minor_status are undefined. 2742 2743 2744 2745 2746Linn Standards Track [Page 49] 2747 2748RFC 2078 GSS-API January 1997 2749 2750 2751 o GSS_S_BAD_QOP indicates that the provided QOP value is not 2752 recognized or supported for the context. 2753 2754 o GSS_S_FAILURE indicates that the requested operation failed for 2755 reasons unspecified at the GSS-API level. Return values other than 2756 major_status and minor_status are undefined. 2757 2758 This call is used to determine the largest input datum which may be 2759 passed to GSS_Wrap() without yielding an output token larger than a 2760 caller-specified value. 2761 27622.2.8: GSS_Export_sec_context call 2763 2764 Inputs: 2765 2766 o context_handle CONTEXT HANDLE 2767 2768 Outputs: 2769 2770 o major_status INTEGER, 2771 2772 o minor_status INTEGER, 2773 2774 o interprocess_token OCTET STRING 2775 2776 Return major_status codes: 2777 2778 o GSS_S_COMPLETE indicates that the referenced context has been 2779 successfully exported to a representation in the interprocess_token, 2780 and is no longer available for use by the caller. 2781 2782 o GSS_S_UNAVAILABLE indicates that the context export facility 2783 is not available for use on the referenced context. (This status 2784 should occur only for contexts for which the trans_state value is 2785 FALSE.) Return values other than major_status and minor_status are 2786 undefined. 2787 2788 o GSS_S_CONTEXT_EXPIRED indicates that the provided input 2789 context_handle is recognized, but that the referenced context has 2790 expired. Return values other than major_status and minor_status are 2791 undefined. 2792 2793 o GSS_S_NO_CONTEXT indicates that no valid context was recognized 2794 for the input context_handle provided. Return values other than 2795 major_status and minor_status are undefined. 2796 2797 2798 2799 2800 2801 2802Linn Standards Track [Page 50] 2803 2804RFC 2078 GSS-API January 1997 2805 2806 2807 o GSS_S_FAILURE indicates that the requested operation failed for 2808 reasons unspecified at the GSS-API level. Return values other than 2809 major_status and minor_status are undefined. 2810 2811 This call generates an interprocess token for transfer to another 2812 process within an end system, in order to transfer control of a 2813 security context to that process. The recipient of the interprocess 2814 token will call GSS_Import_sec_context() to accept the transfer. The 2815 GSS_Export_sec_context() operation is defined for use only with 2816 security contexts which are fully and successfully established (i.e., 2817 those for which GSS_Init_sec_context() and GSS_Accept_sec_context() 2818 have returned GSS_S_COMPLETE major_status). 2819 2820 To ensure portability, a caller of GSS_Export_sec_context() must not 2821 assume that a context may continue to be used once it has been 2822 exported; following export, the context referenced by the 2823 context_handle cannot be assumed to remain valid. Further, portable 2824 callers must not assume that a given interprocess token can be 2825 imported by GSS_Import_sec_context() more than once, thereby creating 2826 multiple instantiations of a single context. GSS-API implementations 2827 may detect and reject attempted multiple imports, but are not 2828 required to do so. 2829 2830 The internal representation contained within the interprocess token 2831 is an implementation-defined local matter. Interprocess tokens 2832 cannot be assumed to be transferable across different GSS-API 2833 implementations. 2834 2835 It is recommended that GSS-API implementations adopt policies suited 2836 to their operational environments in order to define the set of 2837 processes eligible to import a context, but specific constraints in 2838 this area are local matters. Candidate examples include transfers 2839 between processes operating on behalf of the same user identity, or 2840 processes comprising a common job. However, it may be impossible to 2841 enforce such policies in some implementations. 2842 2843 In support of the above goals, implementations may protect the 2844 transferred context data by using cryptography to protect data within 2845 the interprocess token, or by using interprocess tokens as a means to 2846 reference local interprocess communication facilities (protected by 2847 other means) rather than storing the context data directly within the 2848 tokens. 2849 2850 Transfer of an open context may, for certain mechanisms and 2851 implementations, reveal data about the credential which was used to 2852 establish the context. Callers should, therefore, be cautious about 2853 the trustworthiness of processes to which they transfer contexts. 2854 Although the GSS-API implementation may provide its own set of 2855 2856 2857 2858Linn Standards Track [Page 51] 2859 2860RFC 2078 GSS-API January 1997 2861 2862 2863 protections over the exported context, the caller is responsible for 2864 protecting the interprocess token from disclosure, and for taking 2865 care that the context is transferred to an appropriate destination 2866 process. 2867 28682.2.9: GSS_Import_sec_context call 2869 2870 Inputs: 2871 2872 o interprocess_token OCTET STRING 2873 2874 Outputs: 2875 2876 o major_status INTEGER, 2877 2878 o minor_status INTEGER, 2879 2880 o context_handle CONTEXT HANDLE 2881 2882 Return major_status codes: 2883 2884 o GSS_S_COMPLETE indicates that the context represented by the 2885 input interprocess_token has been successfully transferred to 2886 the caller, and is available for future use via the output 2887 context_handle. 2888 2889 o GSS_S_CONTEXT_EXPIRED indicates that the context represented by 2890 the input interprocess_token has expired. Return values other 2891 than major_status and minor_status are undefined. 2892 2893 o GSS_S_NO_CONTEXT indicates that the context represented by the 2894 input interprocess_token was invalid. Return values other than 2895 major_status and minor_status are undefined. 2896 2897 o GSS_S_DEFECTIVE_TOKEN indicates that the input interprocess_token 2898 was defective. Return values other than major_status and 2899 minor_status are undefined. 2900 2901 o GSS_S_UNAVAILABLE indicates that the context import facility 2902 is not available for use on the referenced context. Return values 2903 other than major_status and minor_status are undefined. 2904 2905 o GSS_S_UNAUTHORIZED indicates that the context represented by 2906 the input interprocess_token is unauthorized for transfer to the 2907 caller. Return values other than major_status and minor_status 2908 are undefined. 2909 2910 2911 2912 2913 2914Linn Standards Track [Page 52] 2915 2916RFC 2078 GSS-API January 1997 2917 2918 2919 o GSS_S_FAILURE indicates that the requested operation failed for 2920 reasons unspecified at the GSS-API level. Return values other than 2921 major_status and minor_status are undefined. 2922 2923 This call processes an interprocess token generated by 2924 GSS_Export_sec_context(), making the transferred context available 2925 for use by the caller. After a successful GSS_Import_sec_context() 2926 operation, the imported context is available for use by the importing 2927 process. 2928 2929 For further discussion of the security and authorization issues 2930 regarding this call, please see the discussion in Section 2.2.8. 2931 29322.3: Per-message calls 2933 2934 This group of calls is used to perform per-message protection 2935 processing on an established security context. None of these calls 2936 block pending network interactions. These calls may be invoked by a 2937 context's initiator or by the context's target. The four members of 2938 this group should be considered as two pairs; the output from 2939 GSS_GetMIC() is properly input to GSS_VerifyMIC(), and the output 2940 from GSS_Wrap() is properly input to GSS_Unwrap(). 2941 2942 GSS_GetMIC() and GSS_VerifyMIC() support data origin authentication 2943 and data integrity services. When GSS_GetMIC() is invoked on an 2944 input message, it yields a per-message token containing data items 2945 which allow underlying mechanisms to provide the specified security 2946 services. The original message, along with the generated per-message 2947 token, is passed to the remote peer; these two data elements are 2948 processed by GSS_VerifyMIC(), which validates the message in 2949 conjunction with the separate token. 2950 2951 GSS_Wrap() and GSS_Unwrap() support caller-requested confidentiality 2952 in addition to the data origin authentication and data integrity 2953 services offered by GSS_GetMIC() and GSS_VerifyMIC(). GSS_Wrap() 2954 outputs a single data element, encapsulating optionally enciphered 2955 user data as well as associated token data items. The data element 2956 output from GSS_Wrap() is passed to the remote peer and processed by 2957 GSS_Unwrap() at that system. GSS_Unwrap() combines decipherment (as 2958 required) with validation of data items related to authentication and 2959 integrity. 2960 2961 2962 2963 2964 2965 2966 2967 2968 2969 2970Linn Standards Track [Page 53] 2971 2972RFC 2078 GSS-API January 1997 2973 2974 29752.3.1: GSS_GetMIC call 2976 2977 Note: This call is functionally equivalent to the GSS_Sign call as 2978 defined in previous versions of this specification. In the interests 2979 of backward compatibility, it is recommended that implementations 2980 support this function under both names for the present; future 2981 references to this function as GSS_Sign are deprecated. 2982 2983 Inputs: 2984 2985 o context_handle CONTEXT HANDLE, 2986 2987 o qop_req INTEGER,-0 specifies default QOP 2988 2989 o message OCTET STRING 2990 2991 Outputs: 2992 2993 o major_status INTEGER, 2994 2995 o minor_status INTEGER, 2996 2997 o per_msg_token OCTET STRING 2998 2999 Return major_status codes: 3000 3001 o GSS_S_COMPLETE indicates that an integrity check, suitable for an 3002 established security context, was successfully applied and 3003 that the message and corresponding per_msg_token are ready 3004 for transmission. 3005 3006 o GSS_S_CONTEXT_EXPIRED indicates that context-related data 3007 items have expired, so that the requested operation cannot be 3008 performed. 3009 3010 o GSS_S_CREDENTIALS_EXPIRED indicates that the context is recognized, 3011 but that its associated credentials have expired, so 3012 that the requested operation cannot be performed. 3013 3014 o GSS_S_NO_CONTEXT indicates that no valid context was recognized 3015 for the input context_handle provided. 3016 3017 o GSS_S_BAD_QOP indicates that the provided QOP value is not 3018 recognized or supported for the context. 3019 3020 o GSS_S_FAILURE indicates that the context is recognized, but 3021 that the requested operation could not be performed for 3022 reasons unspecified at the GSS-API level. 3023 3024 3025 3026Linn Standards Track [Page 54] 3027 3028RFC 2078 GSS-API January 1997 3029 3030 3031 Using the security context referenced by context_handle, apply an 3032 integrity check to the input message (along with timestamps and/or 3033 other data included in support of mech_type-specific mechanisms) and 3034 return the result in per_msg_token. The qop_req parameter, 3035 interpretation of which is discussed in Section 1.2.4, allows 3036 quality-of-protection control. The caller passes the message and the 3037 per_msg_token to the target. 3038 3039 The GSS_GetMIC() function completes before the message and 3040 per_msg_token is sent to the peer; successful application of 3041 GSS_GetMIC() does not guarantee that a corresponding GSS_VerifyMIC() 3042 has been (or can necessarily be) performed successfully when the 3043 message arrives at the destination. 3044 3045 Mechanisms which do not support per-message protection services 3046 should return GSS_S_FAILURE if this routine is called. 3047 30482.3.2: GSS_VerifyMIC call 3049 3050 Note: This call is functionally equivalent to the GSS_Verify call as 3051 defined in previous versions of this specification. In the interests 3052 of backward compatibility, it is recommended that implementations 3053 support this function under both names for the present; future 3054 references to this function as GSS_Verify are deprecated. 3055 3056 Inputs: 3057 3058 o context_handle CONTEXT HANDLE, 3059 3060 o message OCTET STRING, 3061 3062 o per_msg_token OCTET STRING 3063 3064 Outputs: 3065 3066 o qop_state INTEGER, 3067 3068 o major_status INTEGER, 3069 3070 o minor_status INTEGER, 3071 3072 Return major_status codes: 3073 3074 o GSS_S_COMPLETE indicates that the message was successfully 3075 verified. 3076 3077 3078 3079 3080 3081 3082Linn Standards Track [Page 55] 3083 3084RFC 2078 GSS-API January 1997 3085 3086 3087 o GSS_S_DEFECTIVE_TOKEN indicates that consistency checks performed 3088 on the received per_msg_token failed, preventing 3089 further processing from being performed with that token. 3090 3091 o GSS_S_BAD_SIG indicates that the received per_msg_token contains 3092 an incorrect integrity check for the message. 3093 3094 o GSS_S_DUPLICATE_TOKEN, GSS_S_OLD_TOKEN, GSS_S_UNSEQ_TOKEN, 3095 and GSS_S_GAP_TOKEN values appear in conjunction with the 3096 optional per-message replay detection features described 3097 in Section 1.2.3; their semantics are described in that section. 3098 3099 o GSS_S_CONTEXT_EXPIRED indicates that context-related data 3100 items have expired, so that the requested operation cannot be 3101 performed. 3102 3103 o GSS_S_CREDENTIALS_EXPIRED indicates that the context is 3104 recognized, 3105 but that its associated credentials have expired, so 3106 that the requested operation cannot be performed. 3107 3108 o GSS_S_NO_CONTEXT indicates that no valid context was recognized 3109 for the input context_handle provided. 3110 3111 o GSS_S_FAILURE indicates that the context is recognized, but 3112 that the GSS_VerifyMIC() operation could not be performed for 3113 reasons unspecified at the GSS-API level. 3114 3115 Using the security context referenced by context_handle, verify that 3116 the input per_msg_token contains an appropriate integrity check for 3117 the input message, and apply any active replay detection or 3118 sequencing features. Return an indication of the quality-of- 3119 protection applied to the processed message in the qop_state result. 3120 Since the GSS_VerifyMIC() routine never provides a confidentiality 3121 service, its implementations should not return non-zero values in the 3122 confidentiality fields of the output qop_state. 3123 3124 Mechanisms which do not support per-message protection services 3125 should return GSS_S_FAILURE if this routine is called. 3126 31272.3.3: GSS_Wrap call 3128 3129 Note: This call is functionally equivalent to the GSS_Seal call as 3130 defined in previous versions of this specification. In the interests 3131 of backward compatibility, it is recommended that implementations 3132 support this function under both names for the present; future 3133 references to this function as GSS_Seal are deprecated. 3134 3135 3136 3137 3138Linn Standards Track [Page 56] 3139 3140RFC 2078 GSS-API January 1997 3141 3142 3143 Inputs: 3144 3145 o context_handle CONTEXT HANDLE, 3146 3147 o conf_req_flag BOOLEAN, 3148 3149 o qop_req INTEGER,-0 specifies default QOP 3150 3151 o input_message OCTET STRING 3152 3153 Outputs: 3154 3155 o major_status INTEGER, 3156 3157 o minor_status INTEGER, 3158 3159 o conf_state BOOLEAN, 3160 3161 o output_message OCTET STRING 3162 3163 Return major_status codes: 3164 3165 o GSS_S_COMPLETE indicates that the input_message was successfully 3166 processed and that the output_message is ready for 3167 transmission. 3168 3169 o GSS_S_CONTEXT_EXPIRED indicates that context-related data 3170 items have expired, so that the requested operation cannot be 3171 performed. 3172 3173 o GSS_S_CREDENTIALS_EXPIRED indicates that the context is 3174 recognized, 3175 but that its associated credentials have expired, so 3176 that the requested operation cannot be performed. 3177 3178 o GSS_S_NO_CONTEXT indicates that no valid context was recognized 3179 for the input context_handle provided. 3180 3181 o GSS_S_BAD_QOP indicates that the provided QOP value is not 3182 recognized or supported for the context. 3183 3184 o GSS_S_FAILURE indicates that the context is recognized, but 3185 that the GSS_Wrap() operation could not be performed for 3186 reasons unspecified at the GSS-API level. 3187 3188 Performs the data origin authentication and data integrity functions 3189 of GSS_GetMIC(). If the input conf_req_flag is TRUE, requests that 3190 confidentiality be applied to the input_message. Confidentiality may 3191 3192 3193 3194Linn Standards Track [Page 57] 3195 3196RFC 2078 GSS-API January 1997 3197 3198 3199 not be supported in all mech_types or by all implementations; the 3200 returned conf_state flag indicates whether confidentiality was 3201 provided for the input_message. The qop_req parameter, interpretation 3202 of which is discussed in Section 1.2.4, allows quality-of-protection 3203 control. 3204 3205 In all cases, the GSS_Wrap() call yields a single output_message 3206 data element containing (optionally enciphered) user data as well as 3207 control information. 3208 3209 Mechanisms which do not support per-message protection services 3210 should return GSS_S_FAILURE if this routine is called. 3211 32122.3.4: GSS_Unwrap call 3213 3214 Note: This call is functionally equivalent to the GSS_Unseal call as 3215 defined in previous versions of this specification. In the interests 3216 of backward compatibility, it is recommended that implementations 3217 support this function under both names for the present; future 3218 references to this function as GSS_Unseal are deprecated. 3219 3220 Inputs: 3221 3222 o context_handle CONTEXT HANDLE, 3223 3224 o input_message OCTET STRING 3225 3226 Outputs: 3227 3228 o conf_state BOOLEAN, 3229 3230 o qop_state INTEGER, 3231 3232 o major_status INTEGER, 3233 3234 o minor_status INTEGER, 3235 3236 o output_message OCTET STRING 3237 3238 Return major_status codes: 3239 3240 o GSS_S_COMPLETE indicates that the input_message was 3241 successfully processed and that the resulting output_message is 3242 available. 3243 3244 o GSS_S_DEFECTIVE_TOKEN indicates that consistency checks performed 3245 on the per_msg_token extracted from the input_message 3246 failed, preventing further processing from being performed. 3247 3248 3249 3250Linn Standards Track [Page 58] 3251 3252RFC 2078 GSS-API January 1997 3253 3254 3255 o GSS_S_BAD_SIG indicates that an incorrect integrity check was 3256 detected 3257 for the message. 3258 3259 o GSS_S_DUPLICATE_TOKEN, GSS_S_OLD_TOKEN, GSS_S_UNSEQ_TOKEN, 3260 and GSS_S_GAP_TOKEN values appear in conjunction with the 3261 optional per-message replay detection features described 3262 in Section 1.2.3; their semantics are described in that section. 3263 3264 o GSS_S_CONTEXT_EXPIRED indicates that context-related data 3265 items have expired, so that the requested operation cannot be 3266 performed. 3267 3268 o GSS_S_CREDENTIALS_EXPIRED indicates that the context is 3269 recognized, 3270 but that its associated credentials have expired, so 3271 that the requested operation cannot be performed. 3272 3273 o GSS_S_NO_CONTEXT indicates that no valid context was recognized 3274 for the input context_handle provided. 3275 3276 o GSS_S_FAILURE indicates that the context is recognized, but 3277 that the GSS_Unwrap() operation could not be performed for 3278 reasons unspecified at the GSS-API level. 3279 3280 Processes a data element generated (and optionally enciphered) by 3281 GSS_Wrap(), provided as input_message. The returned conf_state value 3282 indicates whether confidentiality was applied to the input_message. 3283 If conf_state is TRUE, GSS_Unwrap() deciphers the input_message. 3284 Returns an indication of the quality-of-protection applied to the 3285 processed message in the qop_state result. GSS_Wrap() performs the 3286 data integrity and data origin authentication checking functions of 3287 GSS_VerifyMIC() on the plaintext data. Plaintext data is returned in 3288 output_message. 3289 3290 Mechanisms which do not support per-message protection services 3291 should return GSS_S_FAILURE if this routine is called. 3292 32932.4: Support calls 3294 3295 This group of calls provides support functions useful to GSS-API 3296 callers, independent of the state of established contexts. Their 3297 characterization with regard to blocking or non-blocking status in 3298 terms of network interactions is unspecified. 3299 3300 3301 3302 3303 3304 3305 3306Linn Standards Track [Page 59] 3307 3308RFC 2078 GSS-API January 1997 3309 3310 33112.4.1: GSS_Display_status call 3312 3313 Inputs: 3314 3315 o status_value INTEGER,-GSS-API major_status or minor_status 3316 return value 3317 3318 o status_type INTEGER,-1 if major_status, 2 if minor_status 3319 3320 o mech_type OBJECT IDENTIFIER-mech_type to be used for minor_ 3321 status translation 3322 3323 Outputs: 3324 3325 o major_status INTEGER, 3326 3327 o minor_status INTEGER, 3328 3329 o status_string_set SET OF OCTET STRING 3330 3331 Return major_status codes: 3332 3333 o GSS_S_COMPLETE indicates that a valid printable status 3334 representation (possibly representing more than one status event 3335 encoded within the status_value) is available in the returned 3336 status_string_set. 3337 3338 o GSS_S_BAD_MECH indicates that translation in accordance with an 3339 unsupported mech_type was requested, so translation could not 3340 be performed. 3341 3342 o GSS_S_BAD_STATUS indicates that the input status_value was 3343 invalid, or that the input status_type carried a value other 3344 than 1 or 2, so translation could not be performed. 3345 3346 o GSS_S_FAILURE indicates that the requested operation could not 3347 be performed for reasons unspecified at the GSS-API level. 3348 3349 Provides a means for callers to translate GSS-API-returned major and 3350 minor status codes into printable string representations. 3351 33522.4.2: GSS_Indicate_mechs call 3353 3354 Input: 3355 3356 o (none) 3357 3358 3359 3360 3361 3362Linn Standards Track [Page 60] 3363 3364RFC 2078 GSS-API January 1997 3365 3366 3367 Outputs: 3368 3369 o major_status INTEGER, 3370 3371 o minor_status INTEGER, 3372 3373 o mech_set SET OF OBJECT IDENTIFIER 3374 3375 Return major_status codes: 3376 3377 o GSS_S_COMPLETE indicates that a set of available mechanisms has 3378 been returned in mech_set. 3379 3380 o GSS_S_FAILURE indicates that the requested operation could not 3381 be performed for reasons unspecified at the GSS-API level. 3382 3383 Allows callers to determine the set of mechanism types available on 3384 the local system. This call is intended for support of specialized 3385 callers who need to request non-default mech_type sets from 3386 GSS_Acquire_cred(), and should not be needed by other callers. 3387 33882.4.3: GSS_Compare_name call 3389 3390 Inputs: 3391 3392 o name1 INTERNAL NAME, 3393 3394 o name2 INTERNAL NAME 3395 3396 Outputs: 3397 3398 o major_status INTEGER, 3399 3400 o minor_status INTEGER, 3401 3402 o name_equal BOOLEAN 3403 3404 Return major_status codes: 3405 3406 o GSS_S_COMPLETE indicates that name1 and name2 were comparable, 3407 and that the name_equal result indicates whether name1 and 3408 name2 represent the same entity. 3409 3410 o GSS_S_BAD_NAMETYPE indicates that one or both of name1 and 3411 name2 contained internal type specifiers uninterpretable 3412 by the applicable underlying GSS-API mechanism(s), or that 3413 the two names' types are different and incomparable, so that 3414 the comparison operation could not be completed. 3415 3416 3417 3418Linn Standards Track [Page 61] 3419 3420RFC 2078 GSS-API January 1997 3421 3422 3423 o GSS_S_BAD_NAME indicates that one or both of the input names 3424 was ill-formed in terms of its internal type specifier, so 3425 the comparison operation could not be completed. 3426 3427 o GSS_S_FAILURE indicates that the call's operation could not 3428 be performed for reasons unspecified at the GSS-API level. 3429 3430 Allows callers to compare two internal name representations to 3431 determine whether they refer to the same entity. If either name 3432 presented to GSS_Compare_name() denotes an anonymous principal, 3433 GSS_Compare_name() shall indicate FALSE. It is not required that 3434 either or both inputs name1 and name2 be MNs; for some 3435 implementations and cases, GSS_S_BAD_NAMETYPE may be returned, 3436 indicating name incomparability, for the case where neither input 3437 name is an MN. 3438 34392.4.4: GSS_Display_name call 3440 3441 Inputs: 3442 3443 o name INTERNAL NAME 3444 3445 Outputs: 3446 3447 o major_status INTEGER, 3448 3449 o minor_status INTEGER, 3450 3451 o name_string OCTET STRING, 3452 3453 o name_type OBJECT IDENTIFIER 3454 3455 Return major_status codes: 3456 3457 o GSS_S_COMPLETE indicates that a valid printable name 3458 representation is available in the returned name_string. 3459 3460 o GSS_S_BAD_NAMETYPE indicates that the provided name was of a 3461 type uninterpretable by the applicable underlying GSS-API 3462 mechanism(s), so no printable representation could be generated. 3463 3464 o GSS_S_BAD_NAME indicates that the contents of the provided name 3465 were inconsistent with the internally-indicated name type, so 3466 no printable representation could be generated. 3467 3468 o GSS_S_FAILURE indicates that the requested operation could not 3469 be performed for reasons unspecified at the GSS-API level. 3470 3471 3472 3473 3474Linn Standards Track [Page 62] 3475 3476RFC 2078 GSS-API January 1997 3477 3478 3479 Allows callers to translate an internal name representation into a 3480 printable form with associated namespace type descriptor. The syntax 3481 of the printable form is a local matter. 3482 3483 If the input name represents an anonymous identity, a reserved value 3484 (GSS_C_NT_ANONYMOUS) shall be returned for name_type. 3485 34862.4.5: GSS_Import_name call 3487 3488 Inputs: 3489 3490 o input_name_string OCTET STRING, 3491 3492 o input_name_type OBJECT IDENTIFIER 3493 3494 Outputs: 3495 3496 o major_status INTEGER, 3497 3498 o minor_status INTEGER, 3499 3500 o output_name INTERNAL NAME 3501 3502 Return major_status codes: 3503 3504 o GSS_S_COMPLETE indicates that a valid name representation is 3505 output in output_name and described by the type value in 3506 output_name_type. 3507 3508 o GSS_S_BAD_NAMETYPE indicates that the input_name_type is unsupported 3509 by the applicable underlying GSS-API mechanism(s), so the import 3510 operation could not be completed. 3511 3512 o GSS_S_BAD_NAME indicates that the provided input_name_string 3513 is ill-formed in terms of the input_name_type, so the import 3514 operation could not be completed. 3515 3516 o GSS_S_FAILURE indicates that the requested operation could not 3517 be performed for reasons unspecified at the GSS-API level. 3518 3519 Allows callers to provide a name representation as a contiguous octet 3520 string, designate the type of namespace in conjunction with which it 3521 should be parsed, and convert that representation to an internal form 3522 suitable for input to other GSS-API routines. The syntax of the 3523 input_name_string is defined in conjunction with its associated name 3524 type; depending on the input_name_type, the associated 3525 input_name_string may or may not be a printable string. Note: The 3526 input_name_type argument serves to describe and qualify the 3527 3528 3529 3530Linn Standards Track [Page 63] 3531 3532RFC 2078 GSS-API January 1997 3533 3534 3535 interpretation of the associated input_name_string; it does not 3536 specify the data type of the returned output_name. 3537 3538 If a mechanism claims support for a particular name type, its 3539 GSS_Import_name() operation shall be able to accept all possible 3540 values conformant to the external name syntax as defined for that 3541 name type. These imported values may correspond to: 3542 3543 (1) locally registered entities (for which credentials may be 3544 acquired), 3545 3546 (2) non-local entities (for which local credentials cannot be 3547 acquired, but which may be referenced as targets of initiated 3548 security contexts or initiators of accepted security contexts), or 3549 to 3550 3551 (3) neither of the above. 3552 3553 Determination of whether a particular name belongs to class (1), (2), 3554 or (3) as described above is not guaranteed to be performed by the 3555 GSS_Import_name() function. 3556 3557 The internal name generated by a GSS_Import_name() operation may be a 3558 single-mechanism MN, and is likely to be an MN within a single- 3559 mechanism implementation, but portable callers must not depend on 3560 this property (and must not, therefore, assume that the output from 3561 GSS_Import_name() can be passed directly to GSS_Export_name() without 3562 first being processed through GSS_Canonicalize_name()). 3563 35642.4.6: GSS_Release_name call 3565 3566 Inputs: 3567 3568 o name INTERNAL NAME 3569 3570 Outputs: 3571 3572 o major_status INTEGER, 3573 3574 o minor_status INTEGER 3575 3576 Return major_status codes: 3577 3578 o GSS_S_COMPLETE indicates that the storage associated with the 3579 input name was successfully released. 3580 3581 o GSS_S_BAD_NAME indicates that the input name argument did not 3582 contain a valid name. 3583 3584 3585 3586Linn Standards Track [Page 64] 3587 3588RFC 2078 GSS-API January 1997 3589 3590 3591 o GSS_S_FAILURE indicates that the requested operation could not 3592 be performed for reasons unspecified at the GSS-API level. 3593 3594 Allows callers to release the storage associated with an internal 3595 name representation. This call's specific behavior depends on the 3596 language and programming environment within which a GSS-API 3597 implementation operates, and is therefore detailed within applicable 3598 bindings specifications; in particular, this call may be superfluous 3599 within bindings where memory management is automatic. 3600 36012.4.7: GSS_Release_buffer call 3602 3603 Inputs: 3604 3605 o buffer OCTET STRING 3606 3607 Outputs: 3608 3609 o major_status INTEGER, 3610 3611 o minor_status INTEGER 3612 3613 Return major_status codes: 3614 3615 o GSS_S_COMPLETE indicates that the storage associated with the 3616 input buffer was successfully released. 3617 3618 o GSS_S_FAILURE indicates that the requested operation could not 3619 be performed for reasons unspecified at the GSS-API level. 3620 3621 Allows callers to release the storage associated with an OCTET STRING 3622 buffer allocated by another GSS-API call. This call's specific 3623 behavior depends on the language and programming environment within 3624 which a GSS-API implementation operates, and is therefore detailed 3625 within applicable bindings specifications; in particular, this call 3626 may be superfluous within bindings where memory management is 3627 automatic. 3628 36292.4.8: GSS_Release_OID_set call 3630 3631 Inputs: 3632 3633 o buffer SET OF OBJECT IDENTIFIER 3634 3635 Outputs: 3636 3637 o major_status INTEGER, 3638 3639 3640 3641 3642Linn Standards Track [Page 65] 3643 3644RFC 2078 GSS-API January 1997 3645 3646 3647 o minor_status INTEGER 3648 3649 Return major_status codes: 3650 3651 o GSS_S_COMPLETE indicates that the storage associated with the 3652 input object identifier set was successfully released. 3653 3654 o GSS_S_FAILURE indicates that the requested operation could not 3655 be performed for reasons unspecified at the GSS-API level. 3656 3657 Allows callers to release the storage associated with an object 3658 identifier set object allocated by another GSS-API call. This call's 3659 specific behavior depends on the language and programming environment 3660 within which a GSS-API implementation operates, and is therefore 3661 detailed within applicable bindings specifications; in particular, 3662 this call may be superfluous within bindings where memory management 3663 is automatic. 3664 36652.4.9: GSS_Create_empty_OID_set call 3666 3667 Inputs: 3668 3669 o (none) 3670 3671 Outputs: 3672 3673 o major_status INTEGER, 3674 3675 o minor_status INTEGER, 3676 3677 o oid_set SET OF OBJECT IDENTIFIER 3678 3679 Return major_status codes: 3680 3681 o GSS_S_COMPLETE indicates successful completion 3682 3683 o GSS_S_FAILURE indicates that the operation failed 3684 3685 Creates an object identifier set containing no object identifiers, to 3686 which members may be subsequently added using the 3687 GSS_Add_OID_set_member() routine. These routines are intended to be 3688 used to construct sets of mechanism object identifiers, for input to 3689 GSS_Acquire_cred(). 3690 3691 3692 3693 3694 3695 3696 3697 3698Linn Standards Track [Page 66] 3699 3700RFC 2078 GSS-API January 1997 3701 3702 37032.4.10: GSS_Add_OID_set_member call 3704 3705 Inputs: 3706 3707 o member_oid OBJECT IDENTIFIER, 3708 3709 o oid_set SET OF OBJECT IDENTIFIER 3710 3711 Outputs: 3712 3713 o major_status INTEGER, 3714 3715 o minor_status INTEGER, 3716 3717 Return major_status codes: 3718 3719 o GSS_S_COMPLETE indicates successful completion 3720 3721 o GSS_S_FAILURE indicates that the operation failed 3722 3723 Adds an Object Identifier to an Object Identifier set. This routine 3724 is intended for use in conjunction with GSS_Create_empty_OID_set() 3725 when constructing a set of mechanism OIDs for input to 3726 GSS_Acquire_cred(). 3727 37282.4.11: GSS_Test_OID_set_member call 3729 3730 Inputs: 3731 3732 o member OBJECT IDENTIFIER, 3733 3734 o set SET OF OBJECT IDENTIFIER 3735 3736 Outputs: 3737 3738 o major_status INTEGER, 3739 3740 o minor_status INTEGER, 3741 3742 o present BOOLEAN 3743 3744 Return major_status codes: 3745 3746 o GSS_S_COMPLETE indicates successful completion 3747 3748 o GSS_S_FAILURE indicates that the operation failed 3749 3750 3751 3752 3753 3754Linn Standards Track [Page 67] 3755 3756RFC 2078 GSS-API January 1997 3757 3758 3759 Interrogates an Object Identifier set to determine whether a 3760 specified Object Identifier is a member. This routine is intended to 3761 be used with OID sets returned by GSS_Indicate_mechs(), 3762 GSS_Acquire_cred(), and GSS_Inquire_cred(). 3763 37642.4.12: GSS_Release_OID call 3765 3766 Inputs: 3767 3768 o oid OBJECT IDENTIFIER 3769 3770 Outputs: 3771 3772 o major_status INTEGER, 3773 3774 o minor_status INTEGER 3775 3776 Return major_status codes: 3777 3778 o GSS_S_COMPLETE indicates successful completion 3779 3780 o GSS_S_FAILURE indicates that the operation failed 3781 3782 Allows the caller to release the storage associated with an OBJECT 3783 IDENTIFIER buffer allocated by another GSS-API call. This call's 3784 specific behavior depends on the language and programming environment 3785 within which a GSS-API implementation operates, and is therefore 3786 detailed within applicable bindings specifications; in particular, 3787 this call may be superfluous within bindings where memory management 3788 is automatic. 3789 37902.4.13: GSS_OID_to_str call 3791 3792 Inputs: 3793 3794 o oid OBJECT IDENTIFIER 3795 3796 Outputs: 3797 3798 o major_status INTEGER, 3799 3800 o minor_status INTEGER, 3801 3802 o oid_str OCTET STRING 3803 3804 Return major_status codes: 3805 3806 o GSS_S_COMPLETE indicates successful completion 3807 3808 3809 3810Linn Standards Track [Page 68] 3811 3812RFC 2078 GSS-API January 1997 3813 3814 3815 o GSS_S_FAILURE indicates that the operation failed 3816 3817 The function GSS_OID_to_str() returns a string representing the input 3818 OID in numeric ASN.1 syntax format (curly-brace enclosed, space- 3819 delimited, e.g., "{2 16 840 1 113687 1 2 1}"). The string is 3820 releasable using GSS_Release_buffer(). If the input "oid" does not 3821 represent a syntactically valid object identifier, GSS_S_FAILURE 3822 status is returned and the returned oid_str result is NULL. 3823 38242.4.14: GSS_Str_to_OID call 3825 3826 Inputs: 3827 3828 o oid_str OCTET STRING 3829 3830 Outputs: 3831 3832 o major_status INTEGER, 3833 3834 o minor_status INTEGER, 3835 3836 o oid OBJECT IDENTIFIER 3837 3838 Return major_status codes: 3839 3840 o GSS_S_COMPLETE indicates successful completion 3841 3842 o GSS_S_FAILURE indicates that the operation failed 3843 3844 The function GSS_Str_to_OID() constructs and returns an OID from its 3845 printable form; implementations should be able to accept the numeric 3846 ASN.1 syntax form as described for GSS_OID_to_str(), and this form 3847 should be used for portability, but implementations of this routine 3848 may also accept other formats (e.g., "1.2.3.3"). The OID is suitable 3849 for release using the function GSS_Release_OID(). If the input 3850 oid_str cannot be translated into an OID, GSS_S_FAILURE status is 3851 returned and the "oid" result is NULL. 3852 38532.4.15: GSS_Inquire_names_for_mech call 3854 3855 Input: 3856 3857 o input_mech_type OBJECT IDENTIFIER, -- mechanism type 3858 3859 Outputs: 3860 3861 o major_status INTEGER, 3862 3863 3864 3865 3866Linn Standards Track [Page 69] 3867 3868RFC 2078 GSS-API January 1997 3869 3870 3871 o minor_status INTEGER, 3872 3873 o name_type_set SET OF OBJECT IDENTIFIER 3874 3875 Return major_status codes: 3876 3877 o GSS_S_COMPLETE indicates that the output name_type_set contains 3878 a list of name types which are supported by the locally available 3879 mechanism identified by input_mech_type. 3880 3881 o GSS_S_BAD_MECH indicates that the mechanism identified by 3882 input_mech_type was unsupported within the local implementation, 3883 causing the query to fail. 3884 3885 o GSS_S_FAILURE indicates that the requested operation could not 3886 be performed for reasons unspecified at the GSS-API level. 3887 3888 Allows callers to determine the set of name types which are 3889 supportable by a specific locally-available mechanism. 3890 38912.4.16: GSS_Inquire_mechs_for_name call 3892 3893 Inputs: 3894 3895 o input_name INTERNAL NAME, 3896 3897 Outputs: 3898 3899 o major_status INTEGER, 3900 3901 o minor_status INTEGER, 3902 3903 o mech_types SET OF OBJECT IDENTIFIER 3904 3905 Return major_status codes: 3906 3907 o GSS_S_COMPLETE indicates that a set of object identifiers, 3908 corresponding to the set of mechanisms suitable for processing 3909 the input_name, is available in mech_types. 3910 3911 o GSS_S_BAD_NAME indicates that the input_name could not be 3912 processed. 3913 3914 o GSS_S_BAD_NAMETYPE indicates that the type of the input_name 3915 is unsupported by the GSS-API implementation. 3916 3917 o GSS_S_FAILURE indicates that the requested operation could not 3918 be performed for reasons unspecified at the GSS-API level. 3919 3920 3921 3922Linn Standards Track [Page 70] 3923 3924RFC 2078 GSS-API January 1997 3925 3926 3927 This routine returns the mechanism set with which the input_name may 3928 be processed. After use, the mech_types object should be freed by 3929 the caller via the GSS_Release_OID_set() call. Note: it is 3930 anticipated that implementations of GSS_Inquire_mechs_for_name() will 3931 commonly operate based on type information describing the 3932 capabilities of available mechanisms; it is not guaranteed that all 3933 identified mechanisms will necessarily be able to canonicalize (via 3934 GSS_Canonicalize_name()) a particular name. 3935 39362.4.17: GSS_Canonicalize_name call 3937 3938 Inputs: 3939 3940 o input_name INTERNAL NAME, 3941 3942 o mech_type OBJECT IDENTIFIER -- must be explicit mechanism, 3943 not "default" specifier 3944 3945 Outputs: 3946 3947 o major_status INTEGER, 3948 3949 o minor_status INTEGER, 3950 3951 o output_name INTERNAL NAME 3952 3953 Return major_status codes: 3954 3955 o GSS_S_COMPLETE indicates that a mechanism-specific reduction of 3956 the input_name, as processed by the mechanism identified by 3957 mech_type, is available in output_name. 3958 3959 o GSS_S_BAD_MECH indicates that the identified mechanism is 3960 unsupported. 3961 3962 o GSS_S_BAD_NAMETYPE indicates that the input name does not 3963 contain an element with suitable type for processing by the 3964 identified mechanism. 3965 3966 o GSS_S_BAD_NAME indicates that the input name contains an 3967 element with suitable type for processing by the identified 3968 mechanism, but that this element could not be processed 3969 successfully. 3970 3971 o GSS_S_FAILURE indicates that the requested operation could not 3972 be performed for reasons unspecified at the GSS-API level. 3973 3974 3975 3976 3977 3978Linn Standards Track [Page 71] 3979 3980RFC 2078 GSS-API January 1997 3981 3982 3983 This routine reduces a GSS-API internal name, which may in general 3984 contain elements corresponding to multiple mechanisms, to a 3985 mechanism-specific Mechanism Name (MN) by applying the translations 3986 corresponding to the mechanism identified by mech_type. 3987 39882.4.18: GSS_Export_name call 3989 3990 Inputs: 3991 3992 o input_name INTERNAL NAME, -- required to be MN 3993 3994 Outputs: 3995 3996 o major_status INTEGER, 3997 3998 o minor_status INTEGER, 3999 4000 o output_name OCTET STRING 4001 4002 Return major_status codes: 4003 4004 o GSS_S_COMPLETE indicates that a flat representation of the 4005 input name is available in output_name. 4006 4007 o GSS_S_NAME_NOT_MN indicates that the input name contained 4008 elements corresponding to multiple mechanisms, so cannot 4009 be exported into a single-mechanism flat form. 4010 4011 o GSS_S_BAD_NAME indicates that the input name was an MN, 4012 but could not be processed. 4013 4014 o GSS_S_BAD_NAMETYPE indicates that the input name was an MN, 4015 but that its type is unsupported by the GSS-API implementation. 4016 4017 o GSS_S_FAILURE indicates that the requested operation could not 4018 be performed for reasons unspecified at the GSS-API level. 4019 4020 This routine creates a flat name representation, suitable for 4021 bytewise comparison or for input to GSS_Import_name() in conjunction 4022 with the reserved GSS-API Exported Name Object OID, from a internal- 4023 form Mechanism Name (MN) as emitted, e.g., by GSS_Canonicalize_name() 4024 or GSS_Accept_sec_context(). 4025 4026 The emitted GSS-API Exported Name Object is self-describing; no 4027 associated parameter-level OID need be emitted by this call. This 4028 flat representation consists of a mechanism-independent wrapper 4029 layer, defined in Section 3.2 of this document, enclosing a 4030 mechanism-defined name representation. 4031 4032 4033 4034Linn Standards Track [Page 72] 4035 4036RFC 2078 GSS-API January 1997 4037 4038 4039 In all cases, the flat name output by GSS_Export_name() to correspond 4040 to a particular input MN must be invariant over time within a 4041 particular installation. 4042 4043 The GSS_S_NAME_NOT_MN status code is provided to enable 4044 implementations to reject input names which are not MNs. It is not, 4045 however, required for purposes of conformance to this specification 4046 that all non-MN input names must necessarily be rejected. 4047 40482.4.19: GSS_Duplicate_name call 4049 4050 Inputs: 4051 4052 o src_name INTERNAL NAME 4053 4054 Outputs: 4055 4056 o major_status INTEGER, 4057 4058 o minor_status INTEGER, 4059 4060 o dest_name INTERNAL NAME 4061 4062 Return major_status codes: 4063 4064 o GSS_S_COMPLETE indicates that dest_name references an internal 4065 name object containing the same name as passed to src_name. 4066 4067 o GSS_S_BAD_NAME indicates that the input name was invalid. 4068 4069 o GSS_S_BAD_NAMETYPE indicates that the input name's type 4070 is unsupported by the GSS-API implementation. 4071 4072 o GSS_S_FAILURE indicates that the requested operation could not 4073 be performed for reasons unspecified at the GSS-API level. 4074 4075 This routine takes input internal name src_name, and returns another 4076 reference (dest_name) to that name which can be used even if src_name 4077 is later freed. (Note: This may be implemented by copying or through 4078 use of reference counts.) 4079 40803: Data Structure Definitions for GSS-V2 Usage 4081 4082 Subsections of this section define, for interoperability and 4083 portability purposes, certain data structures for use with GSS-V2. 4084 4085 4086 4087 4088 4089 4090Linn Standards Track [Page 73] 4091 4092RFC 2078 GSS-API January 1997 4093 4094 40953.1: Mechanism-Independent Token Format 4096 4097 This section specifies a mechanism-independent level of encapsulating 4098 representation for the initial token of a GSS-API context 4099 establishment sequence, incorporating an identifier of the mechanism 4100 type to be used on that context and enabling tokens to be interpreted 4101 unambiguously at GSS-API peers. Use of this format is required for 4102 initial context establishment tokens of Internet standards-track 4103 GSS-API mechanisms; use in non-initial tokens is optional. 4104 4105 The encoding format for the token tag is derived from ASN.1 and DER 4106 (per illustrative ASN.1 syntax included later within this 4107 subsection), but its concrete representation is defined directly in 4108 terms of octets rather than at the ASN.1 level in order to facilitate 4109 interoperable implementation without use of general ASN.1 processing 4110 code. The token tag consists of the following elements, in order: 4111 4112 1. 0x60 -- Tag for [APPLICATION 0] SEQUENCE; indicates that 4113 constructed form, definite length encoding follows. 4114 4115 2. Token length octets, specifying length of subsequent data 4116 (i.e., the summed lengths of elements 3-5 in this list, and of the 4117 mechanism-defined token object following the tag). This element 4118 comprises a variable number of octets: 4119 4120 2a. If the indicated value is less than 128, it shall be 4121 represented in a single octet with bit 8 (high order) set to "0" 4122 and the remaining bits representing the value. 4123 4124 2b. If the indicated value is 128 or more, it shall be represented 4125 in two or more octets, with bit 8 of the first octet set to "1" 4126 and the remaining bits of the first octet specifying the number of 4127 additional octets. The subsequent octets carry the value, 8 bits 4128 per octet, most significant digit first. The minimum number of 4129 octets shall be used to encode the length (i.e., no octets 4130 representing leading zeros shall be included within the length 4131 encoding). 4132 4133 3. 0x06 -- Tag for OBJECT IDENTIFIER 4134 4135 4. Object identifier length -- length (number of octets) of the 4136 encoded object identifier contained in element 5, encoded per 4137 rules as described in 2a. and 2b. above. 4138 4139 5. Object identifier octets -- variable number of octets, encoded 4140 per ASN.1 BER rules: 4141 4142 4143 4144 4145 4146Linn Standards Track [Page 74] 4147 4148RFC 2078 GSS-API January 1997 4149 4150 4151 5a. The first octet contains the sum of two values: (1) the top- 4152 level object identifier component, multiplied by 40 (decimal), and 4153 (2) the second-level object identifier component. This special 4154 case is the only point within an object identifier encoding where 4155 a single octet represents contents of more than one component. 4156 4157 5b. Subsequent octets, if required, encode successively-lower 4158 components in the represented object identifier. A component's 4159 encoding may span multiple octets, encoding 7 bits per octet (most 4160 significant bits first) and with bit 8 set to "1" on all but the 4161 final octet in the component's encoding. The minimum number of 4162 octets shall be used to encode each component (i.e., no octets 4163 representing leading zeros shall be included within a component's 4164 encoding). 4165 4166 (Note: In many implementations, elements 3-5 may be stored and 4167 referenced as a contiguous string constant.) 4168 4169 The token tag is immediately followed by a mechanism-defined token 4170 object. Note that no independent size specifier intervenes following 4171 the object identifier value to indicate the size of the mechanism- 4172 defined token object. While ASN.1 usage within mechanism-defined 4173 tokens is permitted, there is no requirement that the mechanism- 4174 specific innerContextToken, innerMsgToken, and sealedUserData data 4175 elements must employ ASN.1 BER/DER encoding conventions. 4176 4177 4178 4179 4180 4181 4182 4183 4184 4185 4186 4187 4188 4189 4190 4191 4192 4193 4194 4195 4196 4197 4198 4199 4200 4201 4202Linn Standards Track [Page 75] 4203 4204RFC 2078 GSS-API January 1997 4205 4206 4207 The following ASN.1 syntax is included for descriptive purposes only, 4208 to illustrate structural relationships among token and tag objects. 4209 For interoperability purposes, token and tag encoding shall be 4210 performed using the concrete encoding procedures described earlier in 4211 this subsection. 4212 4213 GSS-API DEFINITIONS ::= 4214 4215 BEGIN 4216 4217 MechType ::= OBJECT IDENTIFIER 4218 -- data structure definitions 4219 4220 -- callers must be able to distinguish among 4221 -- InitialContextToken, SubsequentContextToken, 4222 -- PerMsgToken, and SealedMessage data elements 4223 -- based on the usage in which they occur 4224 4225 InitialContextToken ::= 4226 -- option indication (delegation, etc.) indicated within 4227 -- mechanism-specific token 4228 [APPLICATION 0] IMPLICIT SEQUENCE { 4229 thisMech MechType, 4230 innerContextToken ANY DEFINED BY thisMech 4231 -- contents mechanism-specific 4232 -- ASN.1 structure not required 4233 } 4234 4235 SubsequentContextToken ::= innerContextToken ANY 4236 -- interpretation based on predecessor InitialContextToken 4237 -- ASN.1 structure not required 4238 4239 PerMsgToken ::= 4240 -- as emitted by GSS_GetMIC and processed by GSS_VerifyMIC 4241 -- ASN.1 structure not required 4242 innerMsgToken ANY 4243 4244 SealedMessage ::= 4245 -- as emitted by GSS_Wrap and processed by GSS_Unwrap 4246 -- includes internal, mechanism-defined indicator 4247 -- of whether or not encrypted 4248 -- ASN.1 structure not required 4249 sealedUserData ANY 4250 4251 END 4252 4253 4254 4255 4256 4257 4258Linn Standards Track [Page 76] 4259 4260RFC 2078 GSS-API January 1997 4261 4262 42633.2: Mechanism-Independent Exported Name Object Format 4264 4265 This section specifies a mechanism-independent level of encapsulating 4266 representation for names exported via the GSS_Export_name() call, 4267 including an object identifier representing the exporting mechanism. 4268 The format of names encapsulated via this representation shall be 4269 defined within individual mechanism drafts. Name objects of this 4270 type will be identified with the following Object Identifier: 4271 4272 {1(iso), 3(org), 6(dod), 1(internet), 5(security), 6(nametypes), 4273 4(gss-api-exported-name)} 4274 4275 No name type OID is included in this mechanism-independent level of 4276 format definition, since (depending on individual mechanism 4277 specifications) the enclosed name may be implicitly typed or may be 4278 explicitly typed using a means other than OID encoding. 4279 4280 Length Name Description 4281 4282 2 TOK_ID Token Identifier 4283 For exported name objects, this 4284 must be hex 04 01. 4285 2 MECH_OID_LEN Length of the Mechanism OID 4286 MECH_OID_LEN MECH_OID Mechanism OID, in DER 4287 4 NAME_LEN Length of name 4288 NAME_LEN NAME Exported name; format defined in 4289 applicable mechanism draft. 4290 42914: Name Type Definitions 4292 4293 This section includes definitions for name types and associated 4294 syntaxes which are defined in a mechanism-independent fashion at the 4295 GSS-API level rather than being defined in individual mechanism 4296 specifications. 4297 42984.1: Host-Based Service Name Form 4299 4300 The following Object Identifier value is provided as a means to 4301 identify this name form: 4302 4303 {1(iso), 3(org), 6(dod), 1(internet), 5(security), 6(nametypes), 4304 2(gss-host-based-services)} 4305 4306 The recommended symbolic name for this type is 4307 "GSS_C_NT_HOSTBASED_SERVICE". 4308 4309 4310 4311 4312 4313 4314Linn Standards Track [Page 77] 4315 4316RFC 2078 GSS-API January 1997 4317 4318 4319 This name type is used to represent services associated with host 4320 computers. This name form is constructed using two elements, 4321 "service" and "hostname", as follows: 4322 4323 service@hostname 4324 4325 When a reference to a name of this type is resolved, the "hostname" 4326 is canonicalized by attempting a DNS lookup and using the fully- 4327 qualified domain name which is returned, or by using the "hostname" 4328 as provided if the DNS lookup fails. The canonicalization operation 4329 also maps the host's name into lower-case characters. 4330 4331 The "hostname" element may be omitted. If no "@" separator is 4332 included, the entire name is interpreted as the service specifier, 4333 with the "hostname" defaulted to the canonicalized name of the local 4334 host. 4335 4336 Values for the "service" element are registered with the IANA. 4337 43384.2: User Name Form 4339 4340 This name form shall be represented by the Object Identifier {iso(1) 4341 member-body(2) United States(840) mit(113554) infosys(1) gssapi(2) 4342 generic(1) user_name(1)}. The recommended mechanism-independent 4343 symbolic name for this type is "GSS_C_NT_USER_NAME". (Note: the same 4344 name form and OID is defined within the Kerberos V5 GSS-API 4345 mechanism, but the symbolic name recommended there begins with a 4346 "GSS_KRB5_NT_" prefix.) 4347 4348 This name type is used to indicate a named user on a local system. 4349 Its interpretation is OS-specific. This name form is constructed as: 4350 4351 username 4352 43534.3: Machine UID Form 4354 4355 This name form shall be represented by the Object Identifier {iso(1) 4356 member-body(2) United States(840) mit(113554) infosys(1) gssapi(2) 4357 generic(1) machine_uid_name(2)}. The recommended mechanism- 4358 independent symbolic name for this type is 4359 "GSS_C_NT_MACHINE_UID_NAME". (Note: the same name form and OID is 4360 defined within the Kerberos V5 GSS-API mechanism, but the symbolic 4361 name recommended there begins with a "GSS_KRB5_NT_" prefix.) 4362 4363 This name type is used to indicate a numeric user identifier 4364 corresponding to a user on a local system. Its interpretation is 4365 OS-specific. The gss_buffer_desc representing a name of this type 4366 should contain a locally-significant uid_t, represented in host byte 4367 4368 4369 4370Linn Standards Track [Page 78] 4371 4372RFC 2078 GSS-API January 1997 4373 4374 4375 order. The GSS_Import_name() operation resolves this uid into a 4376 username, which is then treated as the User Name Form. 4377 43784.4: String UID Form 4379 4380 This name form shall be represented by the Object Identifier {iso(1) 4381 member-body(2) United States(840) mit(113554) infosys(1) gssapi(2) 4382 generic(1) string_uid_name(3)}. The recommended symbolic name for 4383 this type is "GSS_C_NT_STRING_UID_NAME". (Note: the same name form 4384 and OID is defined within the Kerberos V5 GSS-API mechanism, but the 4385 symbolic name recommended there begins with a "GSS_KRB5_NT_" prefix.) 4386 4387 This name type is used to indicate a string of digits representing 4388 the numeric user identifier of a user on a local system. Its 4389 interpretation is OS-specific. This name type is similar to the 4390 Machine UID Form, except that the buffer contains a string 4391 representing the uid_t. 4392 43935: Mechanism-Specific Example Scenarios 4394 4395 This section provides illustrative overviews of the use of various 4396 candidate mechanism types to support the GSS-API. These discussions 4397 are intended primarily for readers familiar with specific security 4398 technologies, demonstrating how GSS-API functions can be used and 4399 implemented by candidate underlying mechanisms. They should not be 4400 regarded as constrictive to implementations or as defining the only 4401 means through which GSS-API functions can be realized with a 4402 particular underlying technology, and do not demonstrate all GSS-API 4403 features with each technology. 4404 44055.1: Kerberos V5, single-TGT 4406 4407 OS-specific login functions yield a TGT to the local realm Kerberos 4408 server; TGT is placed in a credentials structure for the client. 4409 Client calls GSS_Acquire_cred() to acquire a cred_handle in order to 4410 reference the credentials for use in establishing security contexts. 4411 4412 Client calls GSS_Init_sec_context(). If the requested service is 4413 located in a different realm, GSS_Init_sec_context() gets the 4414 necessary TGT/key pairs needed to traverse the path from local to 4415 target realm; these data are placed in the owner's TGT cache. After 4416 any needed remote realm resolution, GSS_Init_sec_context() yields a 4417 service ticket to the requested service with a corresponding session 4418 key; these data are stored in conjunction with the context. GSS-API 4419 code sends KRB_TGS_REQ request(s) and receives KRB_TGS_REP 4420 response(s) (in the successful case) or KRB_ERROR. 4421 4422 4423 4424 4425 4426Linn Standards Track [Page 79] 4427 4428RFC 2078 GSS-API January 1997 4429 4430 4431 Assuming success, GSS_Init_sec_context() builds a Kerberos-formatted 4432 KRB_AP_REQ message, and returns it in output_token. The client sends 4433 the output_token to the service. 4434 4435 The service passes the received token as the input_token argument to 4436 GSS_Accept_sec_context(), which verifies the authenticator, provides 4437 the service with the client's authenticated name, and returns an 4438 output_context_handle. 4439 4440 Both parties now hold the session key associated with the service 4441 ticket, and can use this key in subsequent GSS_GetMIC(), 4442 GSS_VerifyMIC(), GSS_Wrap(), and GSS_Unwrap() operations. 4443 44445.2: Kerberos V5, double-TGT 4445 4446 TGT acquisition as above. 4447 4448 Note: To avoid unnecessary frequent invocations of error paths when 4449 implementing the GSS-API atop Kerberos V5, it seems appropriate to 4450 represent "single-TGT K-V5" and "double-TGT K-V5" with separate 4451 mech_types, and this discussion makes that assumption. 4452 4453 Based on the (specified or defaulted) mech_type, 4454 GSS_Init_sec_context() determines that the double-TGT protocol 4455 should be employed for the specified target. GSS_Init_sec_context() 4456 returns GSS_S_CONTINUE_NEEDED major_status, and its returned 4457 output_token contains a request to the service for the service's TGT. 4458 (If a service TGT with suitably long remaining lifetime already 4459 exists in a cache, it may be usable, obviating the need for this 4460 step.) The client passes the output_token to the service. Note: this 4461 scenario illustrates a different use for the GSS_S_CONTINUE_NEEDED 4462 status return facility than for support of mutual authentication; 4463 note that both uses can coexist as successive operations within a 4464 single context establishment operation. 4465 4466 The service passes the received token as the input_token argument to 4467 GSS_Accept_sec_context(), which recognizes it as a request for TGT. 4468 (Note that current Kerberos V5 defines no intra-protocol mechanism to 4469 represent such a request.) GSS_Accept_sec_context() returns 4470 GSS_S_CONTINUE_NEEDED major_status and provides the service's TGT in 4471 its output_token. The service sends the output_token to the client. 4472 4473 The client passes the received token as the input_token argument to a 4474 continuation of GSS_Init_sec_context(). GSS_Init_sec_context() caches 4475 the received service TGT and uses it as part of a service ticket 4476 request to the Kerberos authentication server, storing the returned 4477 service ticket and session key in conjunction with the context. 4478 GSS_Init_sec_context() builds a Kerberos-formatted authenticator, 4479 4480 4481 4482Linn Standards Track [Page 80] 4483 4484RFC 2078 GSS-API January 1997 4485 4486 4487 and returns it in output_token along with GSS_S_COMPLETE return 4488 major_status. The client sends the output_token to the service. 4489 4490 Service passes the received token as the input_token argument to a 4491 continuation call to GSS_Accept_sec_context(). 4492 GSS_Accept_sec_context() verifies the authenticator, provides the 4493 service with the client's authenticated name, and returns 4494 major_status GSS_S_COMPLETE. 4495 4496 GSS_GetMIC(), GSS_VerifyMIC(), GSS_Wrap(), and GSS_Unwrap() as 4497 above. 4498 44995.3: X.509 Authentication Framework 4500 4501 This example illustrates use of the GSS-API in conjunction with 4502 public-key mechanisms, consistent with the X.509 Directory 4503 Authentication Framework. 4504 4505 The GSS_Acquire_cred() call establishes a credentials structure, 4506 making the client's private key accessible for use on behalf of the 4507 client. 4508 4509 The client calls GSS_Init_sec_context(), which interrogates the 4510 Directory to acquire (and validate) a chain of public-key 4511 certificates, thereby collecting the public key of the service. The 4512 certificate validation operation determines that suitable integrity 4513 checks were applied by trusted authorities and that those 4514 certificates have not expired. GSS_Init_sec_context() generates a 4515 secret key for use in per-message protection operations on the 4516 context, and enciphers that secret key under the service's public 4517 key. 4518 4519 The enciphered secret key, along with an authenticator quantity 4520 signed with the client's private key, is included in the output_token 4521 from GSS_Init_sec_context(). The output_token also carries a 4522 certification path, consisting of a certificate chain leading from 4523 the service to the client; a variant approach would defer this path 4524 resolution to be performed by the service instead of being asserted 4525 by the client. The client application sends the output_token to the 4526 service. 4527 4528 The service passes the received token as the input_token argument to 4529 GSS_Accept_sec_context(). GSS_Accept_sec_context() validates the 4530 certification path, and as a result determines a certified binding 4531 between the client's distinguished name and the client's public key. 4532 Given that public key, GSS_Accept_sec_context() can process the 4533 input_token's authenticator quantity and verify that the client's 4534 private key was used to sign the input_token. At this point, the 4535 4536 4537 4538Linn Standards Track [Page 81] 4539 4540RFC 2078 GSS-API January 1997 4541 4542 4543 client is authenticated to the service. The service uses its private 4544 key to decipher the enciphered secret key provided to it for per- 4545 message protection operations on the context. 4546 4547 The client calls GSS_GetMIC() or GSS_Wrap() on a data message, which 4548 causes per-message authentication, integrity, and (optional) 4549 confidentiality facilities to be applied to that message. The service 4550 uses the context's shared secret key to perform corresponding 4551 GSS_VerifyMIC() and GSS_Unwrap() calls. 4552 45536: Security Considerations 4554 4555 Security issues are discussed throughout this memo. 4556 45577: Related Activities 4558 4559 In order to implement the GSS-API atop existing, emerging, and future 4560 security mechanisms: 4561 4562 object identifiers must be assigned to candidate GSS-API 4563 mechanisms and the name types which they support 4564 4565 concrete data element formats and processing procedures must be 4566 defined for candidate mechanisms 4567 4568 Calling applications must implement formatting conventions which will 4569 enable them to distinguish GSS-API tokens from other data carried in 4570 their application protocols. 4571 4572 Concrete language bindings are required for the programming 4573 environments in which the GSS-API is to be employed, as RFC-1509 4574 defines for the C programming language and GSS-V1. 4575 4576 4577 4578 4579 4580 4581 4582 4583 4584 4585 4586 4587 4588 4589 4590 4591 4592 4593 4594Linn Standards Track [Page 82] 4595 4596RFC 2078 GSS-API January 1997 4597 4598 4599APPENDIX A 4600 4601MECHANISM DESIGN CONSTRAINTS 4602 4603 The following constraints on GSS-API mechanism designs are adopted in 4604 response to observed caller protocol requirements, and adherence 4605 thereto is anticipated in subsequent descriptions of GSS-API 4606 mechanisms to be documented in standards-track Internet 4607 specifications. 4608 4609 It is strongly recommended that mechanisms offering per-message 4610 protection services also offer at least one of the replay detection 4611 and sequencing services, as mechanisms offering neither of the latter 4612 will fail to satisfy recognized requirements of certain candidate 4613 caller protocols. 4614 4615APPENDIX B 4616 4617 COMPATIBILITY WITH GSS-V1 4618 4619 It is the intent of this document to define an interface and 4620 procedures which preserve compatibility between GSS-V1 (RFC-1508) 4621 callers and GSS- V2 providers. All calls defined in GSS-V1 are 4622 preserved, and it has been a goal that GSS-V1 callers should be able 4623 to operate atop GSS-V2 provider implementations. Certain detailed 4624 changes, summarized in this section, have been made in order to 4625 resolve omissions identified in GSS-V1. 4626 4627 The following GSS-V1 constructs, while supported within GSS-V2, are 4628 deprecated: 4629 4630 Names for per-message processing routines: GSS_Seal() deprecated 4631 in favor of GSS_Wrap(); GSS_Sign() deprecated in favor of 4632 GSS_GetMIC(); GSS_Unseal() deprecated in favor of GSS_Unwrap(); 4633 GSS_Verify() deprecated in favor of GSS_VerifyMIC(). 4634 4635 GSS_Delete_sec_context() facility for context_token usage, 4636 allowing mechanisms to signal context deletion, is retained for 4637 compatibility with GSS-V1. For current usage, it is recommended 4638 that both peers to a context invoke GSS_Delete_sec_context() 4639 independently, passing a null output_context_token buffer to 4640 indicate that no context_token is required. Implementations of 4641 GSS_Delete_sec_context() should delete relevant locally-stored 4642 context information. 4643 4644 4645 4646 4647 4648 4649 4650Linn Standards Track [Page 83] 4651 4652RFC 2078 GSS-API January 1997 4653 4654 4655 This GSS-V2 specification adds the following calls which are not 4656 present in GSS-V1: 4657 4658 Credential management calls: GSS_Add_cred(), 4659 GSS_Inquire_cred_by_mech(). 4660 4661 Context-level calls: GSS_Inquire_context(), GSS_Wrap_size_limit(), 4662 GSS_Export_sec_context(), GSS_Import_sec_context(). 4663 4664 Per-message calls: No new calls. Existing calls have been renamed. 4665 4666 Support calls: GSS_Create_empty_OID_set(), 4667 GSS_Add_OID_set_member(), GSS_Test_OID_set_member(), 4668 GSS_Release_OID(), GSS_OID_to_str(), GSS_Str_to_OID(), 4669 GSS_Inquire_names_for_mech(), GSS_Inquire_mechs_for_name(), 4670 GSS_Canonicalize_name(), GSS_Export_name(), GSS_Duplicate_name(). 4671 4672 This GSS-V2 specification introduces three new facilities applicable 4673 to security contexts, indicated using the following context state 4674 values which are not present in GSS-V1: 4675 4676 anon_state, set TRUE to indicate that a context's initiator is 4677 anonymous from the viewpoint of the target; Section 1.2.5 of this 4678 specification provides a summary description of the GSS-V2 4679 anonymity support facility, support and use of which is optional. 4680 4681 prot_ready_state, set TRUE to indicate that a context may be used 4682 for per-message protection before final completion of context 4683 establishment; Section 1.2.7 of this specification provides a 4684 summary description of the GSS-V2 facility enabling mechanisms to 4685 selectively permit per-message protection during context 4686 establishment, support and use of which is optional. 4687 4688 trans_state, set TRUE to indicate that a context is transferable to 4689 another process using the GSS-V2 GSS_Export_sec_context() facility. 4690 4691 These state values are represented (at the C bindings level) in 4692 positions within a bit vector which are unused in GSS-V1, and may be 4693 safely ignored by GSS-V1 callers. 4694 4695 Relative to GSS-V1, GSS-V2 provides additional guidance to GSS-API 4696 implementors in the following areas: implementation robustness, 4697 credential management, behavior in multi-mechanism configurations, 4698 naming support, and inclusion of optional sequencing services. The 4699 token tagging facility as defined in GSS-V2, Section 3.1, is now 4700 described directly in terms of octets to facilitate interoperable 4701 implementation without general ASN.1 processing code; the 4702 corresponding ASN.1 syntax, included for descriptive purposes, is 4703 4704 4705 4706Linn Standards Track [Page 84] 4707 4708RFC 2078 GSS-API January 1997 4709 4710 4711 unchanged from that in GSS-V1. For use in conjunction with added 4712 naming support facilities, a new Exported Name Object construct is 4713 added. Additional name types are introduced in Section 4. 4714 4715 This GSS-V2 specification adds the following major_status values 4716 which are not defined in GSS-V1: 4717 4718 GSS_S_BAD_QOP unsupported QOP value 4719 GSS_S_UNAUTHORIZED operation unauthorized 4720 GSS_S_UNAVAILABLE operation unavailable 4721 GSS_S_DUPLICATE_ELEMENT duplicate credential element requested 4722 GSS_S_NAME_NOT_MN name contains multi-mechanism elements 4723 GSS_S_GAP_TOKEN skipped predecessor token(s) 4724 detected 4725 4726 Of these added status codes, only two values are defined to be 4727 returnable by calls existing in GSS-V1: GSS_S_BAD_QOP (returnable by 4728 GSS_GetMIC() and GSS_Wrap()), and GSS_S_GAP_TOKEN (returnable by 4729 GSS_VerifyMIC() and GSS_Unwrap()). 4730 4731 Additionally, GSS-V2 descriptions of certain calls present in GSS-V1 4732 have been updated to allow return of additional major_status values 4733 from the set as defined in GSS-V1: GSS_Inquire_cred() has 4734 GSS_S_DEFECTIVE_CREDENTIAL and GSS_S_CREDENTIALS_EXPIRED defined as 4735 returnable, GSS_Init_sec_context() has GSS_S_OLD_TOKEN, 4736 GSS_S_DUPLICATE_TOKEN, and GSS_S_BAD_MECH defined as returnable, and 4737 GSS_Accept_sec_context() has GSS_S_BAD_MECH defined as returnable. 4738 4739Author's Address 4740 4741 John Linn 4742 OpenVision Technologies 4743 One Main St. 4744 Cambridge, MA 02142 USA 4745 4746 Phone: +1 617.374.2245 4747 EMail: John.Linn@ov.com 4748 4749 4750 4751 4752 4753 4754 4755 4756 4757 4758 4759 4760 4761 4762Linn Standards Track [Page 85] 4763 4764