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