1 2 3 4 5 6 7Network Working Group J. Linn 8Request for Comments: 1508 Geer Zolot Associates 9 September 1993 10 11 12 Generic Security Service Application Program Interface 13 14Status of this Memo 15 16 This RFC specifies an Internet standards track protocol for the 17 Internet community, and requests discussion and suggestions for 18 improvements. Please refer to the current edition of the "Internet 19 Official Protocol Standards" for the standardization state and status 20 of this protocol. Distribution of this memo is unlimited. 21 22Abstract 23 24 This Generic Security Service Application Program Interface (GSS-API) 25 definition provides security services to callers in a generic 26 fashion, supportable with a range of underlying mechanisms and 27 technologies and hence allowing source-level portability of 28 applications to different environments. This specification defines 29 GSS-API services and primitives at a level independent of underlying 30 mechanism and programming language environment, and is to be 31 complemented by other, related specifications: 32 33 documents defining specific parameter bindings for particular 34 language environments 35 36 documents defining token formats, protocols, and procedures to 37 be implemented in order to realize GSS-API services atop 38 particular security mechanisms 39 40Table of Contents 41 42 1. GSS-API Characteristics and Concepts ....................... 2 43 1.1. GSS-API Constructs ....................................... 5 44 1.1.1. Credentials ........................................... 5 45 1.1.2. Tokens ................................................ 6 46 1.1.3. Security Contexts ..................................... 7 47 1.1.4. Mechanism Types ....................................... 8 48 1.1.5. Naming ................................................ 9 49 1.1.6. Channel Bindings ...................................... 10 50 1.2. GSS-API Features and Issues ............................. 11 51 1.2.1. Status Reporting ...................................... 11 52 1.2.2. Per-Message Security Service Availability ............. 12 53 1.2.3. Per-Message Replay Detection and Sequencing ........... 13 54 1.2.4. Quality of Protection ................................. 15 55 56 57 58Linn [Page 1] 59 60RFC 1508 Generic Security Interface September 1993 61 62 63 2. Interface Descriptions ..................................... 15 64 2.1. Credential management calls ............................. 17 65 2.1.1. GSS_Acquire_cred call ................................. 17 66 2.1.2. GSS_Release_cred call ................................. 19 67 2.1.3. GSS_Inquire_cred call ................................. 20 68 2.2. Context-level calls ..................................... 21 69 2.2.1. GSS_Init_sec_context call ............................. 21 70 2.2.2. GSS_Accept_sec_context call ........................... 26 71 2.2.3. GSS_Delete_sec_context call ........................... 29 72 2.2.4. GSS_Process_context_token call ........................ 30 73 2.2.5. GSS_Context_time call ................................. 31 74 2.3. Per-message calls ....................................... 32 75 2.3.1. GSS_Sign call ......................................... 32 76 2.3.2. GSS_Verify call ....................................... 33 77 2.3.3. GSS_Seal call ......................................... 35 78 2.3.4. GSS_Unseal call ....................................... 36 79 2.4. Support calls ........................................... 37 80 2.4.1. GSS_Display_status call ............................... 37 81 2.4.2. GSS_Indicate_mechs call ............................... 38 82 2.4.3. GSS_Compare_name call ................................. 38 83 2.4.4. GSS_Display_name call ................................. 39 84 2.4.5. GSS_Import_name call .................................. 40 85 2.4.6. GSS_Release_name call ................................. 41 86 2.4.7. GSS_Release_buffer call ............................... 41 87 2.4.8. GSS_Release_oid_set call .............................. 42 88 3. Mechanism-Specific Example Scenarios ....................... 42 89 3.1. Kerberos V5, single-TGT ................................. 43 90 3.2. Kerberos V5, double-TGT ................................. 43 91 3.3. X.509 Authentication Framework .......................... 44 92 4. Related Activities ......................................... 45 93 5. Acknowledgments ............................................ 46 94 6. Security Considerations .................................... 46 95 7. Author's Address ........................................... 46 96 Appendix A .................................................... 47 97 Appendix B .................................................... 48 98 Appendix C .................................................... 49 99 1001. GSS-API Characteristics and Concepts 101 102 The operational paradigm in which GSS-API operates is as follows. A 103 typical GSS-API caller is itself a communications protocol, calling 104 on GSS-API in order to protect its communications with 105 authentication, integrity, and/or confidentiality security services. 106 A GSS-API caller accepts tokens provided to it by its local GSS-API 107 implementation and transfers the tokens to a peer on a remote system; 108 that peer passes the received tokens to its local GSS-API 109 implementation for processing. The security services available 110 through GSS-API in this fashion are implementable (and have been 111 112 113 114Linn [Page 2] 115 116RFC 1508 Generic Security Interface September 1993 117 118 119 implemented) over a range of underlying mechanisms based on secret- 120 key and public-key cryptographic technologies. 121 122 The GSS-API separates the operations of initializing a security 123 context between peers, achieving peer entity authentication (This 124 security service definition, and other definitions used in this 125 document, corresponds to that provided in International Standard ISO 126 7498-2-1988(E), Security Architecture.) (GSS_Init_sec_context() and 127 GSS_Accept_sec_context() calls), from the operations of providing 128 per-message data origin authentication and data integrity protection 129 (GSS_Sign() and GSS_Verify() calls) for messages subsequently 130 transferred in conjunction with that context. Per-message GSS_Seal() 131 and GSS_Unseal() calls provide the data origin authentication and 132 data integrity services which GSS_Sign() and GSS_Verify() offer, and 133 also support selection of confidentiality services as a caller 134 option. Additional calls provide supportive functions to the GSS- 135 API's users. 136 137 The following paragraphs provide an example illustrating the 138 dataflows involved in use of the GSS-API by a client and server in a 139 mechanism-independent fashion, establishing a security context and 140 transferring a protected message. The example assumes that credential 141 acquisition has already been completed. The example assumes that the 142 underlying authentication technology is capable of authenticating a 143 client to a server using elements carried within a single token, and 144 of authenticating the server to the client (mutual authentication) 145 with a single returned token; this assumption holds for presently- 146 documented CAT mechanisms but is not necessarily true for other 147 cryptographic technologies and associated protocols. 148 149 The client calls GSS_Init_sec_context() to establish a security 150 context to the server identified by targ_name, and elects to set the 151 mutual_req_flag so that mutual authentication is performed in the 152 course of context establishment. GSS_Init_sec_context() returns an 153 output_token to be passed to the server, and indicates 154 GSS_CONTINUE_NEEDED status pending completion of the mutual 155 authentication sequence. Had mutual_req_flag not been set, the 156 initial call to GSS_Init_sec_context() would have returned 157 GSS_COMPLETE status. The client sends the output_token to the server. 158 159 The server passes the received token as the input_token parameter to 160 GSS_Accept_sec_context(). GSS_Accept_sec_context indicates 161 GSS_COMPLETE status, provides the client's authenticated identity in 162 the src_name result, and provides an output_token to be passed to the 163 client. The server sends the output_token to the client. 164 165 The client passes the received token as the input_token parameter to 166 a successor call to GSS_Init_sec_context(), which processes data 167 168 169 170Linn [Page 3] 171 172RFC 1508 Generic Security Interface September 1993 173 174 175 included in the token in order to achieve mutual authentication from 176 the client's viewpoint. This call to GSS_Init_sec_context() returns 177 GSS_COMPLETE status, indicating successful mutual authentication and 178 the completion of context establishment for this example. 179 180 The client generates a data message and passes it to GSS_Seal(). 181 GSS_Seal() performs data origin authentication, data integrity, and 182 (optionally) confidentiality processing on the message and 183 encapsulates the result into output_message, indicating GSS_COMPLETE 184 status. The client sends the output_message to the server. 185 186 The server passes the received message to GSS_Unseal(). GSS_Unseal 187 inverts the encapsulation performed by GSS_Seal(), deciphers the 188 message if the optional confidentiality feature was applied, and 189 validates the data origin authentication and data integrity checking 190 quantities. GSS_Unseal() indicates successful validation by 191 returning GSS_COMPLETE status along with the resultant 192 output_message. 193 194 For purposes of this example, we assume that the server knows by 195 out-of-band means that this context will have no further use after 196 one protected message is transferred from client to server. Given 197 this premise, the server now calls GSS_Delete_sec_context() to flush 198 context-level information. GSS_Delete_sec_context() returns a 199 context_token for the server to pass to the client. 200 201 The client passes the returned context_token to 202 GSS_Process_context_token(), which returns GSS_COMPLETE status after 203 deleting context-level information at the client system. 204 205 The GSS-API design assumes and addresses several basic goals, 206 including: 207 208 Mechanism independence: The GSS-API defines an interface to 209 cryptographically implemented strong authentication and other 210 security services at a generic level which is independent of 211 particular underlying mechanisms. For example, GSS-API-provided 212 services can be implemented by secret-key technologies (e.g., 213 Kerberos) or public-key approaches (e.g., X.509). 214 215 Protocol environment independence: The GSS-API is independent of 216 the communications protocol suites with which it is employed, 217 permitting use in a broad range of protocol environments. In 218 appropriate environments, an intermediate implementation "veneer" 219 which is oriented to a particular communication protocol (e.g., 220 Remote Procedure Call (RPC)) may be interposed between 221 applications which call that protocol and the GSS-API, thereby 222 invoking GSS-API facilities in conjunction with that protocol's 223 224 225 226Linn [Page 4] 227 228RFC 1508 Generic Security Interface September 1993 229 230 231 communications invocations. 232 233 Protocol association independence: The GSS-API's security context 234 construct is independent of communications protocol association 235 constructs. This characteristic allows a single GSS-API 236 implementation to be utilized by a variety of invoking protocol 237 modules on behalf of those modules' calling applications. GSS-API 238 services can also be invoked directly by applications, wholly 239 independent of protocol associations. 240 241 Suitability to a range of implementation placements: GSS-API 242 clients are not constrained to reside within any Trusted Computing 243 Base (TCB) perimeter defined on a system where the GSS-API is 244 implemented; security services are specified in a manner suitable 245 to both intra-TCB and extra-TCB callers. 246 2471.1. GSS-API Constructs 248 249 This section describes the basic elements comprising the GSS-API. 250 2511.1.1. Credentials 252 253 Credentials structures provide the prerequisites enabling peers to 254 establish security contexts with each other. A caller may designate 255 that its default credential be used for context establishment calls 256 without presenting an explicit handle to that credential. 257 Alternately, those GSS-API callers which need to make explicit 258 selection of particular credentials structures may make references to 259 those credentials through GSS-API-provided credential handles 260 ("cred_handles"). 261 262 A single credential structure may be used for initiation of outbound 263 contexts and acceptance of inbound contexts. Callers needing to 264 operate in only one of these modes may designate this fact when 265 credentials are acquired for use, allowing underlying mechanisms to 266 optimize their processing and storage requirements. The credential 267 elements defined by a particular mechanism may contain multiple 268 cryptographic keys, e.g., to enable authentication and message 269 encryption to be performed with different algorithms. 270 271 A single credential structure may accommodate credential information 272 associated with multiple underlying mechanisms (mech_types); a 273 credential structure's contents will vary depending on the set of 274 mech_types supported by a particular GSS-API implementation. 275 Commonly, a single mech_type will be used for all security contexts 276 established by a particular initiator to a particular target; the 277 primary motivation for supporting credential sets representing 278 multiple mech_types is to allow initiators on systems which are 279 280 281 282Linn [Page 5] 283 284RFC 1508 Generic Security Interface September 1993 285 286 287 equipped to handle multiple types to initiate contexts to targets on 288 other systems which can accommodate only a subset of the set 289 supported at the initiator's system. 290 291 It is the responsibility of underlying system-specific mechanisms and 292 OS functions below the GSS-API to ensure that the ability to acquire 293 and use credentials associated with a given identity is constrained 294 to appropriate processes within a system. This responsibility should 295 be taken seriously by implementors, as the ability for an entity to 296 utilize a principal's credentials is equivalent to the entity's 297 ability to successfully assert that principal's identity. 298 299 Once a set of GSS-API credentials is established, the transferability 300 of that credentials set to other processes or analogous constructs 301 within a system is a local matter, not defined by the GSS-API. An 302 example local policy would be one in which any credentials received 303 as a result of login to a given user account, or of delegation of 304 rights to that account, are accessible by, or transferable to, 305 processes running under that account. 306 307 The credential establishment process (particularly when performed on 308 behalf of users rather than server processes) is likely to require 309 access to passwords or other quantities which should be protected 310 locally and exposed for the shortest time possible. As a result, it 311 will often be appropriate for preliminary credential establishment to 312 be performed through local means at user login time, with the 313 result(s) cached for subsequent reference. These preliminary 314 credentials would be set aside (in a system-specific fashion) for 315 subsequent use, either: 316 317 to be accessed by an invocation of the GSS-API GSS_Acquire_cred() 318 call, returning an explicit handle to reference that credential 319 320 as the default credentials installed on behalf of a process 321 3221.1.2. Tokens 323 324 Tokens are data elements transferred between GSS-API callers, and are 325 divided into two classes. Context-level tokens are exchanged in order 326 to establish and manage a security context between peers. Per-message 327 tokens are exchanged in conjunction with an established context to 328 provide protective security services for corresponding data messages. 329 The internal contents of both classes of tokens are specific to the 330 particular underlying mechanism used to support the GSS-API; Appendix 331 B of this document provides a uniform recommendation for designers of 332 GSS-API support mechanisms, encapsulating mechanism-specific 333 information along with a globally-interpretable mechanism identifier. 334 335 336 337 338Linn [Page 6] 339 340RFC 1508 Generic Security Interface September 1993 341 342 343 Tokens are opaque from the viewpoint of GSS-API callers. They are 344 generated within the GSS-API implementation at an end system, 345 provided to a GSS-API caller to be transferred to the peer GSS-API 346 caller at a remote end system, and processed by the GSS-API 347 implementation at that remote end system. Tokens may be output by 348 GSS-API primitives (and are to be transferred to GSS-API peers) 349 independent of the status indications which those primitives 350 indicate. Token transfer may take place in an in-band manner, 351 integrated into the same protocol stream used by the GSS-API callers 352 for other data transfers, or in an out-of-band manner across a 353 logically separate channel. 354 355 Development of GSS-API support primitives based on a particular 356 underlying cryptographic technique and protocol does not necessarily 357 imply that GSS-API callers invoking that GSS-API mechanism type will 358 be able to interoperate with peers invoking the same technique and 359 protocol outside the GSS-API paradigm. For example, the format of 360 GSS-API tokens defined in conjunction with a particular mechanism, 361 and the techniques used to integrate those tokens into callers' 362 protocols, may not be the same as those used by non-GSS-API callers 363 of the same underlying technique. 364 3651.1.3. Security Contexts 366 367 Security contexts are established between peers, using credentials 368 established locally in conjunction with each peer or received by 369 peers via delegation. Multiple contexts may exist simultaneously 370 between a pair of peers, using the same or different sets of 371 credentials. Coexistence of multiple contexts using different 372 credentials allows graceful rollover when credentials expire. 373 Distinction among multiple contexts based on the same credentials 374 serves applications by distinguishing different message streams in a 375 security sense. 376 377 The GSS-API is independent of underlying protocols and addressing 378 structure, and depends on its callers to transport GSS-API-provided 379 data elements. As a result of these factors, it is a caller 380 responsibility to parse communicated messages, separating GSS-API- 381 related data elements from caller-provided data. The GSS-API is 382 independent of connection vs. connectionless orientation of the 383 underlying communications service. 384 385 No correlation between security context and communications protocol 386 association is dictated. (The optional channel binding facility, 387 discussed in Section 1.1.6 of this document, represents an 388 intentional exception to this rule, supporting additional protection 389 features within GSS-API supporting mechanisms.) This separation 390 allows the GSS-API to be used in a wide range of communications 391 392 393 394Linn [Page 7] 395 396RFC 1508 Generic Security Interface September 1993 397 398 399 environments, and also simplifies the calling sequences of the 400 individual calls. In many cases (depending on underlying security 401 protocol, associated mechanism, and availability of cached 402 information), the state information required for context setup can be 403 sent concurrently with initial signed user data, without interposing 404 additional message exchanges. 405 4061.1.4. Mechanism Types 407 408 In order to successfully establish a security context with a target 409 peer, it is necessary to identify an appropriate underlying mechanism 410 type (mech_type) which both initiator and target peers support. The 411 definition of a mechanism embodies not only the use of a particular 412 cryptographic technology (or a hybrid or choice among alternative 413 cryptographic technologies), but also definition of the syntax and 414 semantics of data element exchanges which that mechanism will employ 415 in order to support security services. 416 417 It is recommended that callers initiating contexts specify the 418 "default" mech_type value, allowing system-specific functions within 419 or invoked by the GSS-API implementation to select the appropriate 420 mech_type, but callers may direct that a particular mech_type be 421 employed when necessary. 422 423 The means for identifying a shared mech_type to establish a security 424 context with a peer will vary in different environments and 425 circumstances; examples include (but are not limited to): 426 427 use of a fixed mech_type, defined by configuration, within an 428 environment 429 430 syntactic convention on a target-specific basis, through 431 examination of a target's name 432 433 lookup of a target's name in a naming service or other database in 434 order to identify mech_types supported by that target 435 436 explicit negotiation between GSS-API callers in advance of 437 security context setup 438 439 When transferred between GSS-API peers, mech_type specifiers (per 440 Appendix B, represented as Object Identifiers (OIDs)) serve to 441 qualify the interpretation of associated tokens. (The structure and 442 encoding of Object Identifiers is defined in ISO/IEC 8824, 443 "Specification of Abstract Syntax Notation One (ASN.1)" and in 444 ISO/IEC 8825, "Specification of Basic Encoding Rules for Abstract 445 Syntax Notation One (ASN.1)".) Use of hierarchically structured OIDs 446 serves to preclude ambiguous interpretation of mech_type specifiers. 447 448 449 450Linn [Page 8] 451 452RFC 1508 Generic Security Interface September 1993 453 454 455 The OID representing the DASS MechType, for example, is 456 1.3.12.2.1011.7.5. 457 4581.1.5. Naming 459 460 The GSS-API avoids prescription of naming structures, treating the 461 names transferred across the interface in order to initiate and 462 accept security contexts as opaque octet string quantities. This 463 approach supports the GSS-API's goal of implementability atop a range 464 of underlying security mechanisms, recognizing the fact that 465 different mechanisms process and authenticate names which are 466 presented in different forms. Generalized services offering 467 translation functions among arbitrary sets of naming environments are 468 outside the scope of the GSS-API; availability and use of local 469 conversion functions to translate among the naming formats supported 470 within a given end system is anticipated. 471 472 Two distinct classes of name representations are used in conjunction 473 with different GSS-API parameters: 474 475 a printable form (denoted by OCTET STRING), for acceptance from 476 and presentation to users; printable name forms are accompanied by 477 OID tags identifying the namespace to which they correspond 478 479 an internal form (denoted by INTERNAL NAME), opaque to callers and 480 defined by individual GSS-API implementations; GSS-API 481 implementations supporting multiple namespace types are 482 responsible for maintaining internal tags to disambiguate the 483 interpretation of particular names 484 485 Tagging of printable names allows GSS-API callers and underlying 486 GSS-API mechanisms to disambiguate name types and to determine 487 whether an associated name's type is one which they are capable of 488 processing, avoiding aliasing problems which could result from 489 misinterpreting a name of one type as a name of another type. 490 491 In addition to providing means for names to be tagged with types, 492 this specification defines primitives to support a level of naming 493 environment independence for certain calling applications. To provide 494 basic services oriented towards the requirements of callers which 495 need not themselves interpret the internal syntax and semantics of 496 names, GSS-API calls for name comparison (GSS_Compare_name()), 497 human-readable display (GSS_Display_name()), input conversion 498 (GSS_Import_name()), and internal name deallocation 499 (GSS_Release_name()) functions are defined. (It is anticipated that 500 these proposed GSS-API calls will be implemented in many end systems 501 based on system-specific name manipulation primitives already extant 502 within those end systems; inclusion within the GSS-API is intended to 503 504 505 506Linn [Page 9] 507 508RFC 1508 Generic Security Interface September 1993 509 510 511 offer GSS-API callers a portable means to perform specific 512 operations, supportive of authorization and audit requirements, on 513 authenticated names.) 514 515 GSS_Import_name() implementations can, where appropriate, support 516 more than one printable syntax corresponding to a given namespace 517 (e.g., alternative printable representations for X.500 Distinguished 518 Names), allowing flexibility for their callers to select among 519 alternative representations. GSS_Display_name() implementations 520 output a printable syntax selected as appropriate to their 521 operational environments; this selection is a local matter. Callers 522 desiring portability across alternative printable syntaxes should 523 refrain from implementing comparisons based on printable name forms 524 and should instead use the GSS_Compare_name() call to determine 525 whether or not one internal-format name matches another. 526 5271.1.6. Channel Bindings 528 529 The GSS-API accommodates the concept of caller-provided channel 530 binding ("chan_binding") information, used by GSS-API callers to bind 531 the establishment of a security context to relevant characteristics 532 (e.g., addresses, transformed representations of encryption keys) of 533 the underlying communications channel and of protection mechanisms 534 applied to that communications channel. Verification by one peer of 535 chan_binding information provided by the other peer to a context 536 serves to protect against various active attacks. The caller 537 initiating a security context must determine the chan_binding values 538 before making the GSS_Init_sec_context() call, and consistent values 539 must be provided by both peers to a context. Callers should not 540 assume that underlying mechanisms provide confidentiality protection 541 for channel binding information. 542 543 Use or non-use of the GSS-API channel binding facility is a caller 544 option, and GSS-API supporting mechanisms can support operation in an 545 environment where NULL channel bindings are presented. When non-NULL 546 channel bindings are used, certain mechanisms will offer enhanced 547 security value by interpreting the bindings' content (rather than 548 simply representing those bindings, or signatures computed on them, 549 within tokens) and will therefore depend on presentation of specific 550 data in a defined format. To this end, agreements among mechanism 551 implementors are defining conventional interpretations for the 552 contents of channel binding arguments, including address specifiers 553 (with content dependent on communications protocol environment) for 554 context initiators and acceptors. (These conventions are being 555 incorporated into related documents.) In order for GSS-API callers to 556 be portable across multiple mechanisms and achieve the full security 557 functionality available from each mechanism, it is strongly 558 recommended that GSS-API callers provide channel bindings consistent 559 560 561 562Linn [Page 10] 563 564RFC 1508 Generic Security Interface September 1993 565 566 567 with these conventions and those of the networking environment in 568 which they operate. 569 5701.2. GSS-API Features and Issues 571 572 This section describes aspects of GSS-API operations, of the security 573 services which the GSS-API provides, and provides commentary on 574 design issues. 575 5761.2.1. Status Reporting 577 578 Each GSS-API call provides two status return values. Major_status 579 values provide a mechanism-independent indication of call status 580 (e.g., GSS_COMPLETE, GSS_FAILURE, GSS_CONTINUE_NEEDED), sufficient to 581 drive normal control flow within the caller in a generic fashion. 582 Table 1 summarizes the defined major_status return codes in tabular 583 fashion. 584 585 Table 1: GSS-API Major Status Codes 586 587 FATAL ERROR CODES 588 589 GSS_BAD_BINDINGS channel binding mismatch 590 GSS_BAD_MECH unsupported mechanism requested 591 GSS_BAD_NAME invalid name provided 592 GSS_BAD_NAMETYPE name of unsupported type provided 593 GSS_BAD_STATUS invalid input status selector 594 GSS_BAD_SIG token had invalid signature 595 GSS_CONTEXT_EXPIRED specified security context expired 596 GSS_CREDENTIALS_EXPIRED expired credentials detected 597 GSS_DEFECTIVE_CREDENTIAL defective credential detected 598 GSS_DEFECTIVE_TOKEN defective token detected 599 GSS_FAILURE failure, unspecified at GSS-API 600 level 601 GSS_NO_CONTEXT no valid security context specified 602 GSS_NO_CRED no valid credentials provided 603 604 INFORMATORY STATUS CODES 605 606 GSS_COMPLETE normal completion 607 GSS_CONTINUE_NEEDED continuation call to routine 608 required 609 GSS_DUPLICATE_TOKEN duplicate per-message token 610 detected 611 GSS_OLD_TOKEN timed-out per-message token 612 detected 613 GSS_UNSEQ_TOKEN out-of-order per-message token 614 detected 615 616 617 618Linn [Page 11] 619 620RFC 1508 Generic Security Interface September 1993 621 622 623 Minor_status provides more detailed status information which may 624 include status codes specific to the underlying security mechanism. 625 Minor_status values are not specified in this document. 626 627 GSS_CONTINUE_NEEDED major_status returns, and optional message 628 outputs, are provided in GSS_Init_sec_context() and 629 GSS_Accept_sec_context() calls so that different mechanisms' 630 employment of different numbers of messages within their 631 authentication sequences need not be reflected in separate code paths 632 within calling applications. Instead, such cases are accomodated with 633 sequences of continuation calls to GSS_Init_sec_context() and 634 GSS_Accept_sec_context(). The same mechanism is used to encapsulate 635 mutual authentication within the GSS-API's context initiation calls. 636 637 For mech_types which require interactions with third-party servers in 638 order to establish a security context, GSS-API context establishment 639 calls may block pending completion of such third-party interactions. 640 On the other hand, no GSS-API calls pend on serialized interactions 641 with GSS-API peer entities. As a result, local GSS-API status 642 returns cannot reflect unpredictable or asynchronous exceptions 643 occurring at remote peers, and reflection of such status information 644 is a caller responsibility outside the GSS-API. 645 6461.2.2. Per-Message Security Service Availability 647 648 When a context is established, two flags are returned to indicate the 649 set of per-message protection security services which will be 650 available on the context: 651 652 the integ_avail flag indicates whether per-message integrity and 653 data origin authentication services are available 654 655 the conf_avail flag indicates whether per-message confidentiality 656 services are available, and will never be returned TRUE unless the 657 integ_avail flag is also returned TRUE 658 659 GSS-API callers desiring per-message security services should 660 check the values of these flags at context establishment time, and 661 must be aware that a returned FALSE value for integ_avail means 662 that invocation of GSS_Sign() or GSS_Seal() primitives on the 663 associated context will apply no cryptographic protection to user 664 data messages. 665 666 The GSS-API per-message protection service primitives, as the 667 category name implies, are oriented to operation at the granularity 668 of protocol data units. They perform cryptographic operations on the 669 data units, transfer cryptographic control information in tokens, 670 and, in the case of GSS_Seal(), encapsulate the protected data unit. 671 672 673 674Linn [Page 12] 675 676RFC 1508 Generic Security Interface September 1993 677 678 679 As such, these primitives are not oriented to efficient data 680 protection for stream-paradigm protocols (e.g., Telnet) if 681 cryptography must be applied on an octet-by-octet basis. 682 6831.2.3. Per-Message Replay Detection and Sequencing 684 685 Certain underlying mech_types are expected to offer support for 686 replay detection and/or sequencing of messages transferred on the 687 contexts they support. These optionally-selectable protection 688 features are distinct from replay detection and sequencing features 689 applied to the context establishment operation itself; the presence 690 or absence of context-level replay or sequencing features is wholly a 691 function of the underlying mech_type's capabilities, and is not 692 selected or omitted as a caller option. 693 694 The caller initiating a context provides flags (replay_det_req_flag 695 and sequence_req_flag) to specify whether the use of per-message 696 replay detection and sequencing features is desired on the context 697 being established. The GSS-API implementation at the initiator system 698 can determine whether these features are supported (and whether they 699 are optionally selectable) as a function of mech_type, without need 700 for bilateral negotiation with the target. When enabled, these 701 features provide recipients with indicators as a result of GSS-API 702 processing of incoming messages, identifying whether those messages 703 were detected as duplicates or out-of-sequence. Detection of such 704 events does not prevent a suspect message from being provided to a 705 recipient; the appropriate course of action on a suspect message is a 706 matter of caller policy. 707 708 The semantics of the replay detection and sequencing services applied 709 to received messages, as visible across the interface which the GSS- 710 API provides to its clients, are as follows: 711 712 When replay_det_state is TRUE, the possible major_status returns for 713 well-formed and correctly signed messages are as follows: 714 715 1. GSS_COMPLETE indicates that the message was within the window 716 (of time or sequence space) allowing replay events to be detected, 717 and that the message was not a replay of a previously-processed 718 message within that window. 719 720 2. GSS_DUPLICATE_TOKEN indicates that the signature on the 721 received message was correct, but that the message was recognized 722 as a duplicate of a previously-processed message. 723 724 3. GSS_OLD_TOKEN indicates that the signature on the received 725 message was correct, but that the message is too old to be checked 726 for duplication. 727 728 729 730Linn [Page 13] 731 732RFC 1508 Generic Security Interface September 1993 733 734 735 When sequence_state is TRUE, the possible major_status returns for 736 well-formed and correctly signed messages are as follows: 737 738 1. GSS_COMPLETE indicates that the message was within the window 739 (of time or sequence space) allowing replay events to be detected, 740 and that the message was not a replay of a previously-processed 741 message within that window. 742 743 2. GSS_DUPLICATE_TOKEN indicates that the signature on the 744 received message was correct, but that the message was recognized 745 as a duplicate of a previously-processed message. 746 747 3. GSS_OLD_TOKEN indicates that the signature on the received 748 message was correct, but that the token is too old to be checked 749 for duplication. 750 751 4. GSS_UNSEQ_TOKEN indicates that the signature on the received 752 message was correct, but that it is earlier in a sequenced stream 753 than a message already processed on the context. [Note: 754 Mechanisms can be architected to provide a stricter form of 755 sequencing service, delivering particular messages to recipients 756 only after all predecessor messages in an ordered stream have been 757 delivered. This type of support is incompatible with the GSS-API 758 paradigm in which recipients receive all messages, whether in 759 order or not, and provide them (one at a time, without intra-GSS- 760 API message buffering) to GSS-API routines for validation. GSS- 761 API facilities provide supportive functions, aiding clients to 762 achieve strict message stream integrity in an efficient manner in 763 conjunction with sequencing provisions in communications 764 protocols, but the GSS-API does not offer this level of message 765 stream integrity service by itself.] 766 767 As the message stream integrity features (especially sequencing) may 768 interfere with certain applications' intended communications 769 paradigms, and since support for such features is likely to be 770 resource intensive, it is highly recommended that mech_types 771 supporting these features allow them to be activated selectively on 772 initiator request when a context is established. A context initiator 773 and target are provided with corresponding indicators 774 (replay_det_state and sequence_state), signifying whether these 775 features are active on a given context. 776 777 An example mech_type supporting per-message replay detection could 778 (when replay_det_state is TRUE) implement the feature as follows: The 779 underlying mechanism would insert timestamps in data elements output 780 by GSS_Sign() and GSS_Seal(), and would maintain (within a time- 781 limited window) a cache (qualified by originator-recipient pair) 782 identifying received data elements processed by GSS_Verify() and 783 784 785 786Linn [Page 14] 787 788RFC 1508 Generic Security Interface September 1993 789 790 791 GSS_Unseal(). When this feature is active, exception status returns 792 (GSS_DUPLICATE_TOKEN, GSS_ OLD_TOKEN) will be provided when 793 GSS_Verify() or GSS_Unseal() is presented with a message which is 794 either a detected duplicate of a prior message or which is too old to 795 validate against a cache of recently received messages. 796 7971.2.4. Quality of Protection 798 799 Some mech_types will provide their users with fine granularity 800 control over the means used to provide per-message protection, 801 allowing callers to trade off security processing overhead 802 dynamically against the protection requirements of particular 803 messages. A per-message quality-of-protection parameter (analogous to 804 quality-of-service, or QOS) selects among different QOP options 805 supported by that mechanism. On context establishment for a multi-QOP 806 mech_type, context-level data provides the prerequisite data for a 807 range of protection qualities. 808 809 It is expected that the majority of callers will not wish to exert 810 explicit mechanism-specific QOP control and will therefore request 811 selection of a default QOP. Definitions of, and choices among, non- 812 default QOP values are mechanism-specific, and no ordered sequences 813 of QOP values can be assumed equivalent across different mechanisms. 814 Meaningful use of non-default QOP values demands that callers be 815 familiar with the QOP definitions of an underlying mechanism or 816 mechanisms, and is therefore a non-portable construct. 817 8182. Interface Descriptions 819 820 This section describes the GSS-API's service interface, dividing the 821 set of calls offered into four groups. Credential management calls 822 are related to the acquisition and release of credentials by 823 principals. Context-level calls are related to the management of 824 security contexts between principals. Per-message calls are related 825 to the protection of individual messages on established security 826 contexts. Support calls provide ancillary functions useful to GSS-API 827 callers. Table 2 groups and summarizes the calls in tabular fashion. 828 829 830 831 832 833 834 835 836 837 838 839 840 841 842Linn [Page 15] 843 844RFC 1508 Generic Security Interface September 1993 845 846 847 Table 2: GSS-API Calls 848 849 CREDENTIAL MANAGEMENT 850 851 GSS_Acquire_cred acquire credentials for use 852 GSS_Release_cred release credentials after use 853 GSS_Inquire_cred display information about 854 credentials 855 856 CONTEXT-LEVEL CALLS 857 858 GSS_Init_sec_context initiate outbound security context 859 GSS_Accept_sec_context accept inbound security context 860 GSS_Delete_sec_context flush context when no longer needed 861 GSS_Process_context_token process received control token on 862 context 863 GSS_Context_time indicate validity time remaining on 864 context 865 866 PER-MESSAGE CALLS 867 868 GSS_Sign apply signature, receive as token 869 separate from message 870 GSS_Verify validate signature token along with 871 message 872 GSS_Seal sign, optionally encrypt, 873 encapsulate 874 GSS_Unseal decapsulate, decrypt if needed, 875 validate signature 876 877 SUPPORT CALLS 878 879 GSS_Display_status translate status codes to printable 880 form 881 GSS_Indicate_mechs indicate mech_types supported on 882 local system 883 GSS_Compare_name compare two names for equality 884 GSS_Display_name translate name to printable form 885 GSS_Import_name convert printable name to 886 normalized form 887 GSS_Release_name free storage of normalized-form 888 name 889 GSS_Release_buffer free storage of printable name 890 GSS_Release_oid_set free storage of OID set object 891 892 893 894 895 896 897 898Linn [Page 16] 899 900RFC 1508 Generic Security Interface September 1993 901 902 9032.1. Credential management calls 904 905 These GSS-API calls provide functions related to the management of 906 credentials. Their characterization with regard to whether or not 907 they may block pending exchanges with other network entities (e.g., 908 directories or authentication servers) depends in part on OS-specific 909 (extra-GSS-API) issues, so is not specified in this document. 910 911 The GSS_Acquire_cred() call is defined within the GSS-API in support 912 of application portability, with a particular orientation towards 913 support of portable server applications. It is recognized that (for 914 certain systems and mechanisms) credentials for interactive users may 915 be managed differently from credentials for server processes; in such 916 environments, it is the GSS-API implementation's responsibility to 917 distinguish these cases and the procedures for making this 918 distinction are a local matter. The GSS_Release_cred() call provides 919 a means for callers to indicate to the GSS-API that use of a 920 credentials structure is no longer required. The GSS_Inquire_cred() 921 call allows callers to determine information about a credentials 922 structure. 923 9242.1.1. GSS_Acquire_cred call 925 926 Inputs: 927 928 o desired_name INTERNAL NAME, -NULL requests locally-determined 929 default 930 931 o lifetime_req INTEGER,-in seconds; 0 requests default 932 933 o desired_mechs SET OF OBJECT IDENTIFIER,-empty set requests 934 system-selected default 935 936 o cred_usage INTEGER-0=INITIATE-AND-ACCEPT, 1=INITIATE-ONLY, 937 2=ACCEPT-ONLY 938 939 Outputs: 940 941 o major_status INTEGER, 942 943 o minor_status INTEGER, 944 945 o output_cred_handle OCTET STRING, 946 947 o actual_mechs SET OF OBJECT IDENTIFIER, 948 949 o lifetime_rec INTEGER -in seconds, or reserved value for 950 INDEFINITE 951 952 953 954Linn [Page 17] 955 956RFC 1508 Generic Security Interface September 1993 957 958 959 Return major_status codes: 960 961 o GSS_COMPLETE indicates that requested credentials were 962 successfully established, for the duration indicated in 963 lifetime_rec, suitable for the usage requested in cred_usage, for 964 the set of mech_types indicated in actual_mechs, and that those 965 credentials can be referenced for subsequent use with the handle 966 returned in output_cred_handle. 967 968 o GSS_BAD_MECH indicates that a mech_type unsupported by the GSS-API 969 implementation type was requested, causing the credential 970 establishment operation to fail. 971 972 o GSS_BAD_NAMETYPE indicates that the provided desired_name is 973 uninterpretable or of a type unsupported by the supporting GSS-API 974 implementation, so no credentials could be established for the 975 accompanying desired_name. 976 977 o GSS_BAD_NAME indicates that the provided desired_name is 978 inconsistent in terms of internally-incorporated type specifier 979 information, so no credentials could be established for the 980 accompanying desired_name. 981 982 o GSS_FAILURE indicates that credential establishment failed for 983 reasons unspecified at the GSS-API level, including lack of 984 authorization to establish and use credentials associated with the 985 identity named in the input desired_name argument. 986 987 GSS_Acquire_cred() is used to acquire credentials so that a 988 principal can (as a function of the input cred_usage parameter) 989 initiate and/or accept security contexts under the identity 990 represented by the desired_name input argument. On successful 991 completion, the returned output_cred_handle result provides a handle 992 for subsequent references to the acquired credentials. Typically, 993 single-user client processes using only default credentials for 994 context establishment purposes will have no need to invoke this call. 995 996 A caller may provide the value NULL for desired_name, signifying a 997 request for credentials corresponding to a default principal 998 identity. The procedures used by GSS-API implementations to select 999 the appropriate principal identity in response to this form of 1000 request are local matters. It is possible that multiple pre- 1001 established credentials may exist for the same principal identity 1002 (for example, as a result of multiple user login sessions) when 1003 GSS_Acquire_cred() is called; the means used in such cases to select 1004 a specific credential are local matters. The input lifetime_req 1005 argument to GSS_Acquire_cred() may provide useful information for 1006 local GSS-API implementations to employ in making this disambiguation 1007 1008 1009 1010Linn [Page 18] 1011 1012RFC 1508 Generic Security Interface September 1993 1013 1014 1015 in a manner which will best satisfy a caller's intent. 1016 1017 The lifetime_rec result indicates the length of time for which the 1018 acquired credentials will be valid, as an offset from the present. A 1019 mechanism may return a reserved value indicating INDEFINITE if no 1020 constraints on credential lifetime are imposed. A caller of 1021 GSS_Acquire_cred() can request a length of time for which acquired 1022 credentials are to be valid (lifetime_req argument), beginning at the 1023 present, or can request credentials with a default validity interval. 1024 (Requests for postdated credentials are not supported within the 1025 GSS-API.) Certain mechanisms and implementations may bind in 1026 credential validity period specifiers at a point preliminary to 1027 invocation of the GSS_Acquire_cred() call (e.g., in conjunction with 1028 user login procedures). As a result, callers requesting non-default 1029 values for lifetime_req must recognize that such requests cannot 1030 always be honored and must be prepared to accommodate the use of 1031 returned credentials with different lifetimes as indicated in 1032 lifetime_rec. 1033 1034 The caller of GSS_Acquire_cred() can explicitly specify a set of 1035 mech_types which are to be accommodated in the returned credentials 1036 (desired_mechs argument), or can request credentials for a system- 1037 defined default set of mech_types. Selection of the system-specified 1038 default set is recommended in the interests of application 1039 portability. The actual_mechs return value may be interrogated by the 1040 caller to determine the set of mechanisms with which the returned 1041 credentials may be used. 1042 10432.1.2. GSS_Release_cred call 1044 1045 Input: 1046 1047 o cred_handle OCTET STRING-NULL specifies default credentials 1048 1049 Outputs: 1050 1051 o major_status INTEGER, 1052 1053 o minor_status INTEGER 1054 1055 Return major_status codes: 1056 1057 o GSS_COMPLETE indicates that the credentials referenced by the 1058 input cred_handle were released for purposes of subsequent access 1059 by the caller. The effect on other processes which may be 1060 authorized shared access to such credentials is a local matter. 1061 1062 1063 1064 1065 1066Linn [Page 19] 1067 1068RFC 1508 Generic Security Interface September 1993 1069 1070 1071 o GSS_NO_CRED indicates that no release operation was performed, 1072 either because the input cred_handle was invalid or because the 1073 caller lacks authorization to access the referenced credentials. 1074 1075 o GSS_FAILURE indicates that the release operation failed for 1076 reasons unspecified at the GSS-API level. 1077 1078 Provides a means for a caller to explicitly request that credentials 1079 be released when their use is no longer required. Note that system- 1080 specific credential management functions are also likely to exist, 1081 for example to assure that credentials shared among processes are 1082 properly deleted when all affected processes terminate, even if no 1083 explicit release requests are issued by those processes. Given the 1084 fact that multiple callers are not precluded from gaining authorized 1085 access to the same credentials, invocation of GSS_Release_cred() 1086 cannot be assumed to delete a particular set of credentials on a 1087 system-wide basis. 1088 10892.1.3. GSS_Inquire_cred call 1090 1091 Input: 1092 1093 o cred_handle OCTET STRING -NULL specifies default credentials 1094 1095 Outputs: 1096 1097 o major_status INTEGER, 1098 1099 o minor_status INTEGER, 1100 1101 o cred_name INTERNAL NAME, 1102 1103 o lifetime_rec INTEGER -in seconds, or reserved value for 1104 INDEFINITE 1105 1106 o cred_usage INTEGER, -0=INITIATE-AND-ACCEPT, 1=INITIATE-ONLY, 1107 2=ACCEPT-ONLY 1108 1109 o mech_set SET OF OBJECT IDENTIFIER 1110 1111 Return major_status codes: 1112 1113 o GSS_COMPLETE indicates that the credentials referenced by the 1114 input cred_handle argument were valid, and that the output 1115 cred_name, lifetime_rec, and cred_usage values represent, 1116 respectively, the credentials' associated principal name, 1117 remaining lifetime, suitable usage modes, and supported 1118 mechanism types. 1119 1120 1121 1122Linn [Page 20] 1123 1124RFC 1508 Generic Security Interface September 1993 1125 1126 1127 o GSS_NO_CRED indicates that no information could be returned 1128 about the referenced credentials, either because the input 1129 cred_handle was invalid or because the caller lacks 1130 authorization to access the referenced credentials. 1131 1132 o GSS_FAILURE indicates that the release operation failed for 1133 reasons unspecified at the GSS-API level. 1134 1135 The GSS_Inquire_cred() call is defined primarily for the use of 1136 those callers which make use of default credentials rather than 1137 acquiring credentials explicitly with GSS_Acquire_cred(). It enables 1138 callers to determine a credential structure's associated principal 1139 name, remaining validity period, usability for security context 1140 initiation and/or acceptance, and supported mechanisms. 1141 11422.2. Context-level calls 1143 1144 This group of calls is devoted to the establishment and management of 1145 security contexts between peers. A context's initiator calls 1146 GSS_Init_sec_context(), resulting in generation of a token which the 1147 caller passes to the target. At the target, that token is passed to 1148 GSS_Accept_sec_context(). Depending on the underlying mech_type and 1149 specified options, additional token exchanges may be performed in the 1150 course of context establishment; such exchanges are accommodated by 1151 GSS_CONTINUE_NEEDED status returns from GSS_Init_sec_context() and 1152 GSS_Accept_sec_context(). Either party to an established context may 1153 invoke GSS_Delete_sec_context() to flush context information when a 1154 context is no longer required. GSS_Process_context_token() is used 1155 to process received tokens carrying context-level control 1156 information. GSS_Context_time() allows a caller to determine the 1157 length of time for which an established context will remain valid. 1158 11592.2.1. GSS_Init_sec_context call 1160 1161 Inputs: 1162 1163 o claimant_cred_handle OCTET STRING, -NULL specifies "use 1164 default" 1165 1166 o input_context_handle INTEGER, -0 specifies "none assigned 1167 yet" 1168 1169 o targ_name INTERNAL NAME, 1170 1171 o mech_type OBJECT IDENTIFIER, -NULL parameter specifies "use 1172 default" 1173 1174 o deleg_req_flag BOOLEAN, 1175 1176 1177 1178Linn [Page 21] 1179 1180RFC 1508 Generic Security Interface September 1993 1181 1182 1183 o mutual_req_flag BOOLEAN, 1184 1185 o replay_det_req_flag BOOLEAN, 1186 1187 o sequence_req_flag BOOLEAN, 1188 1189 o lifetime_req INTEGER,-0 specifies default lifetime 1190 1191 o chan_bindings OCTET STRING, 1192 1193 o input_token OCTET STRING-NULL or token received from target 1194 1195 Outputs: 1196 1197 o major_status INTEGER, 1198 1199 o minor_status INTEGER, 1200 1201 o output_context_handle INTEGER, 1202 1203 o mech_type OBJECT IDENTIFIER, -actual mechanism always 1204 indicated, never NULL 1205 1206 o output_token OCTET STRING, -NULL or token to pass to context 1207 target 1208 1209 o deleg_state BOOLEAN, 1210 1211 o mutual_state BOOLEAN, 1212 1213 o replay_det_state BOOLEAN, 1214 1215 o sequence_state BOOLEAN, 1216 1217 o conf_avail BOOLEAN, 1218 1219 o integ_avail BOOLEAN, 1220 1221 o lifetime_rec INTEGER - in seconds, or reserved value for 1222 INDEFINITE 1223 1224 This call may block pending network interactions for those mech_types 1225 in which an authentication server or other network entity must be 1226 consulted on behalf of a context initiator in order to generate an 1227 output_token suitable for presentation to a specified target. 1228 1229 Return major_status codes: 1230 1231 1232 1233 1234Linn [Page 22] 1235 1236RFC 1508 Generic Security Interface September 1993 1237 1238 1239 o GSS_COMPLETE indicates that context-level information was 1240 successfully initialized, and that the returned output_token will 1241 provide sufficient information for the target to perform per- 1242 message processing on the newly-established context. 1243 1244 o GSS_CONTINUE_NEEDED indicates that control information in the 1245 returned output_token must be sent to the target, and that a reply 1246 must be received and passed as the input_token argument to a 1247 continuation call to GSS_Init_sec_context(), before per-message 1248 processing can be performed in conjunction with this context. 1249 1250 o GSS_DEFECTIVE_TOKEN indicates that consistency checks performed on 1251 the input_token failed, preventing further processing from being 1252 performed based on that token. 1253 1254 o GSS_DEFECTIVE_CREDENTIAL indicates that consistency checks 1255 performed on the credential structure referenced by 1256 claimant_cred_handle failed, preventing further processing from 1257 being performed using that credential structure. 1258 1259 o GSS_BAD_SIG indicates that the received input_token contains an 1260 incorrect signature, so context setup cannot be accomplished. 1261 1262 o GSS_NO_CRED indicates that no context was established, either 1263 because the input cred_handle was invalid, because the referenced 1264 credentials are valid for context acceptor use only, or because 1265 the caller lacks authorization to access the referenced 1266 credentials. 1267 1268 o GSS_CREDENTIALS_EXPIRED indicates that the credentials provided 1269 through the input claimant_cred_handle argument are no longer 1270 valid, so context establishment cannot be completed. 1271 1272 o GSS_BAD_BINDINGS indicates that a mismatch between the caller- 1273 provided chan_bindings and those extracted from the input_token 1274 was detected, signifying a security-relevant event and preventing 1275 context establishment. (This result will be returned by 1276 GSS_Init_sec_context only for contexts where mutual_state is 1277 TRUE.) 1278 1279 o GSS_NO_CONTEXT indicates that no valid context was recognized for 1280 the input context_handle provided; this major status will be 1281 returned only for successor calls following GSS_CONTINUE_NEEDED 1282 status returns. 1283 1284 o GSS_BAD_NAMETYPE indicates that the provided targ_name is of a 1285 type uninterpretable or unsupported by the supporting GSS-API 1286 implementation, so context establishment cannot be completed. 1287 1288 1289 1290Linn [Page 23] 1291 1292RFC 1508 Generic Security Interface September 1993 1293 1294 1295 o GSS_BAD_NAME indicates that the provided targ_name is inconsistent 1296 in terms of internally-incorporated type specifier information, so 1297 context establishment cannot be accomplished. 1298 1299 o GSS_FAILURE indicates that context setup could not be accomplished 1300 for reasons unspecified at the GSS-API level, and that no 1301 interface-defined recovery action is available. 1302 1303 This routine is used by a context initiator, and ordinarily emits one 1304 (or, for the case of a multi-step exchange, more than one) 1305 output_token suitable for use by the target within the selected 1306 mech_type's protocol. Using information in the credentials structure 1307 referenced by claimant_cred_handle, GSS_Init_sec_context() 1308 initializes the data structures required to establish a security 1309 context with target targ_name. The claimant_cred_handle must 1310 correspond to the same valid credentials structure on the initial 1311 call to GSS_Init_sec_context() and on any successor calls resulting 1312 from GSS_CONTINUE_NEEDED status returns; different protocol sequences 1313 modeled by the GSS_CONTINUE_NEEDED mechanism will require access to 1314 credentials at different points in the context establishment 1315 sequence. 1316 1317 The input_context_handle argument is 0, specifying "not yet 1318 assigned", on the first GSS_Init_sec_context() call relating to a 1319 given context. That call returns an output_context_handle for future 1320 references to this context. When continuation attempts to 1321 GSS_Init_sec_context() are needed to perform context establishment, 1322 the previously-returned non-zero handle value is entered into the 1323 input_context_handle argument and will be echoed in the returned 1324 output_context_handle argument. On such continuation attempts (and 1325 only on continuation attempts) the input_token value is used, to 1326 provide the token returned from the context's target. 1327 1328 The chan_bindings argument is used by the caller to provide 1329 information binding the security context to security-related 1330 characteristics (e.g., addresses, cryptographic keys) of the 1331 underlying communications channel. See Section 1.1.6 of this document 1332 for more discussion of this argument's usage. 1333 1334 The input_token argument contains a message received from the target, 1335 and is significant only on a call to GSS_Init_sec_context() which 1336 follows a previous return indicating GSS_CONTINUE_NEEDED 1337 major_status. 1338 1339 It is the caller's responsibility to establish a communications path 1340 to the target, and to transmit any returned output_token (independent 1341 of the accompanying returned major_status value) to the target over 1342 that path. The output_token can, however, be transmitted along with 1343 1344 1345 1346Linn [Page 24] 1347 1348RFC 1508 Generic Security Interface September 1993 1349 1350 1351 the first application-provided input message to be processed by 1352 GSS_Sign() or GSS_Seal() in conjunction with a successfully- 1353 established context. 1354 1355 The initiator may request various context-level functions through 1356 input flags: the deleg_req_flag requests delegation of access rights, 1357 the mutual_req_flag requests mutual authentication, the 1358 replay_det_req_flag requests that replay detection features be 1359 applied to messages transferred on the established context, and the 1360 sequence_req_flag requests that sequencing be enforced. (See Section 1361 1.2.3 for more information on replay detection and sequencing 1362 features.) 1363 1364 Not all of the optionally-requestable features will be available in 1365 all underlying mech_types; the corresponding return state values 1366 (deleg_state, mutual_state, replay_det_state, sequence_state) 1367 indicate, as a function of mech_type processing capabilities and 1368 initiator-provided input flags, the set of features which will be 1369 active on the context. These state indicators' values are undefined 1370 unless the routine's major_status indicates COMPLETE. Failure to 1371 provide the precise set of features requested by the caller does not 1372 cause context establishment to fail; it is the caller's prerogative 1373 to delete the context if the feature set provided is unsuitable for 1374 the caller's use. The returned mech_type value indicates the 1375 specific mechanism employed on the context, and will never indicate 1376 the value for "default". 1377 1378 The conf_avail return value indicates whether the context supports 1379 per-message confidentiality services, and so informs the caller 1380 whether or not a request for encryption through the conf_req_flag 1381 input to GSS_Seal() can be honored. In similar fashion, the 1382 integ_avail return value indicates whether per-message integrity 1383 services are available (through either GSS_Sign() or GSS_Seal()) on 1384 the established context. 1385 1386 The lifetime_req input specifies a desired upper bound for the 1387 lifetime of the context to be established, with a value of 0 used to 1388 request a default lifetime. The lifetime_rec return value indicates 1389 the length of time for which the context will be valid, expressed as 1390 an offset from the present; depending on mechanism capabilities, 1391 credential lifetimes, and local policy, it may not correspond to the 1392 value requested in lifetime_req. If no constraints on context 1393 lifetime are imposed, this may be indicated by returning a reserved 1394 value representing INDEFINITE lifetime_req. The values of conf_avail, 1395 integ_avail, and lifetime_rec are undefined unless the routine's 1396 major_status indicates COMPLETE. 1397 1398 If the mutual_state is TRUE, this fact will be reflected within the 1399 1400 1401 1402Linn [Page 25] 1403 1404RFC 1508 Generic Security Interface September 1993 1405 1406 1407 output_token. A call to GSS_Accept_sec_context() at the target in 1408 conjunction with such a context will return a token, to be processed 1409 by a continuation call to GSS_Init_sec_context(), in order to achieve 1410 mutual authentication. 1411 14122.2.2. GSS_Accept_sec_context call 1413 1414 Inputs: 1415 1416 o acceptor_cred_handle OCTET STRING,-NULL specifies "use 1417 default" 1418 1419 o input_context_handle INTEGER, -0 specifies "not yet assigned" 1420 1421 o chan_bindings OCTET STRING, 1422 1423 o input_token OCTET STRING 1424 1425 Outputs: 1426 1427 o major_status INTEGER, 1428 1429 o minor_status INTEGER, 1430 1431 o src_name INTERNAL NAME, 1432 1433 o mech_type OBJECT IDENTIFIER, 1434 1435 o output_context_handle INTEGER, 1436 1437 o deleg_state BOOLEAN, 1438 1439 o mutual_state BOOLEAN, 1440 1441 o replay_det_state BOOLEAN, 1442 1443 o sequence_state BOOLEAN, 1444 1445 o conf_avail BOOLEAN, 1446 1447 o integ_avail BOOLEAN, 1448 1449 o lifetime_rec INTEGER, - in seconds, or reserved value for 1450 INDEFINITE 1451 1452 o delegated_cred_handle OCTET STRING, 1453 1454 o output_token OCTET STRING -NULL or token to pass to context 1455 1456 1457 1458Linn [Page 26] 1459 1460RFC 1508 Generic Security Interface September 1993 1461 1462 1463 initiator 1464 1465 This call may block pending network interactions for those mech_types 1466 in which a directory service or other network entity must be 1467 consulted on behalf of a context acceptor in order to validate a 1468 received input_token. 1469 1470 Return major_status codes: 1471 1472 o GSS_COMPLETE indicates that context-level data structures were 1473 successfully initialized, and that per-message processing can now 1474 be performed in conjunction with this context. 1475 1476 o GSS_CONTINUE_NEEDED indicates that control information in the 1477 returned output_token must be sent to the initiator, and that a 1478 response must be received and passed as the input_token argument 1479 to a continuation call to GSS_Accept_sec_context(), before per- 1480 message processing can be performed in conjunction with this 1481 context. 1482 1483 o GSS_DEFECTIVE_TOKEN indicates that consistency checks performed on 1484 the input_token failed, preventing further processing from being 1485 performed based on that token. 1486 1487 o GSS_DEFECTIVE_CREDENTIAL indicates that consistency checks 1488 performed on the credential structure referenced by 1489 acceptor_cred_handle failed, preventing further processing from 1490 being performed using that credential structure. 1491 1492 o GSS_BAD_SIG indicates that the received input_token contains an 1493 incorrect signature, so context setup cannot be accomplished. 1494 1495 o GSS_DUPLICATE_TOKEN indicates that the signature on the received 1496 input_token was correct, but that the input_token was recognized 1497 as a duplicate of an input_token already processed. No new context 1498 is established. 1499 1500 o GSS_OLD_TOKEN indicates that the signature on the received 1501 input_token was correct, but that the input_token is too old to be 1502 checked for duplication against previously-processed input_tokens. 1503 No new context is established. 1504 1505 o GSS_NO_CRED indicates that no context was established, either 1506 because the input cred_handle was invalid, because the referenced 1507 credentials are valid for context initiator use only, or because 1508 the caller lacks authorization to access the referenced 1509 credentials. 1510 1511 1512 1513 1514Linn [Page 27] 1515 1516RFC 1508 Generic Security Interface September 1993 1517 1518 1519 o GSS_CREDENTIALS_EXPIRED indicates that the credentials provided 1520 through the input acceptor_cred_handle argument are no longer 1521 valid, so context establishment cannot be completed. 1522 1523 o GSS_BAD_BINDINGS indicates that a mismatch between the caller- 1524 provided chan_bindings and those extracted from the input_token 1525 was detected, signifying a security-relevant event and preventing 1526 context establishment. 1527 1528 o GSS_NO_CONTEXT indicates that no valid context was recognized for 1529 the input context_handle provided; this major status will be 1530 returned only for successor calls following GSS_CONTINUE_NEEDED 1531 status returns. 1532 1533 o GSS_FAILURE indicates that context setup could not be accomplished 1534 for reasons unspecified at the GSS-API level, and that no 1535 interface-defined recovery action is available. 1536 1537 The GSS_Accept_sec_context() routine is used by a context target. 1538 Using information in the credentials structure referenced by the 1539 input acceptor_cred_handle, it verifies the incoming input_token and 1540 (following the successful completion of a context establishment 1541 sequence) returns the authenticated src_name and the mech_type used. 1542 The acceptor_cred_handle must correspond to the same valid 1543 credentials structure on the initial call to GSS_Accept_sec_context() 1544 and on any successor calls resulting from GSS_CONTINUE_NEEDED status 1545 returns; different protocol sequences modeled by the 1546 GSS_CONTINUE_NEEDED mechanism will require access to credentials at 1547 different points in the context establishment sequence. 1548 1549 The input_context_handle argument is 0, specifying "not yet 1550 assigned", on the first GSS_Accept_sec_context() call relating to a 1551 given context. That call returns an output_context_handle for future 1552 references to this context; when continuation attempts to 1553 GSS_Accept_sec_context() are needed to perform context 1554 establishment, that handle value will be entered into the 1555 input_context_handle argument. 1556 1557 The chan_bindings argument is used by the caller to provide 1558 information binding the security context to security-related 1559 characteristics (e.g., addresses, cryptographic keys) of the 1560 underlying communications channel. See Section 1.1.6 of this document 1561 for more discussion of this argument's usage. 1562 1563 The returned state results (deleg_state, mutual_state, 1564 replay_det_state, and sequence_state) reflect the same context state 1565 values as returned to GSS_Init_sec_context()'s caller at the 1566 initiator system. 1567 1568 1569 1570Linn [Page 28] 1571 1572RFC 1508 Generic Security Interface September 1993 1573 1574 1575 The conf_avail return value indicates whether the context supports 1576 per-message confidentiality services, and so informs the caller 1577 whether or not a request for encryption through the conf_req_flag 1578 input to GSS_Seal() can be honored. In similar fashion, the 1579 integ_avail return value indicates whether per-message integrity 1580 services are available (through either GSS_Sign() or GSS_Seal()) on 1581 the established context. 1582 1583 The lifetime_rec return value indicates the length of time for which 1584 the context will be valid, expressed as an offset from the present. 1585 The values of deleg_state, mutual_state, replay_det_state, 1586 sequence_state, conf_avail, integ_avail, and lifetime_rec are 1587 undefined unless the accompanying major_status indicates COMPLETE. 1588 1589 The delegated_cred_handle result is significant only when deleg_state 1590 is TRUE, and provides a means for the target to reference the 1591 delegated credentials. The output_token result, when non-NULL, 1592 provides a context-level token to be returned to the context 1593 initiator to continue a multi-step context establishment sequence. As 1594 noted with GSS_Init_sec_context(), any returned token should be 1595 transferred to the context's peer (in this case, the context 1596 initiator), independent of the value of the accompanying returned 1597 major_status. 1598 1599 Note: A target must be able to distinguish a context-level 1600 input_token, which is passed to GSS_Accept_sec_context(), from the 1601 per-message data elements passed to GSS_Verify() or GSS_Unseal(). 1602 These data elements may arrive in a single application message, and 1603 GSS_Accept_sec_context() must be performed before per-message 1604 processing can be performed successfully. 1605 16062.2.3. GSS_Delete_sec_context call 1607 1608 Input: 1609 1610 o context_handle INTEGER 1611 1612 Outputs: 1613 1614 o major_status INTEGER, 1615 1616 o minor_status INTEGER, 1617 1618 o output_context_token OCTET STRING 1619 1620 Return major_status codes: 1621 1622 1623 1624 1625 1626Linn [Page 29] 1627 1628RFC 1508 Generic Security Interface September 1993 1629 1630 1631 o GSS_COMPLETE indicates that the context was recognized, that 1632 relevant context-specific information was flushed, and that the 1633 returned output_context_token is ready for transfer to the 1634 context's peer. 1635 1636 o GSS_NO_CONTEXT indicates that no valid context was recognized for 1637 the input context_handle provide, so no deletion was performed. 1638 1639 o GSS_FAILURE indicates that the context is recognized, but that the 1640 GSS_Delete_sec_context() operation could not be performed for 1641 reasons unspecified at the GSS-API level. 1642 1643 This call may block pending network interactions for mech_types in 1644 which active notification must be made to a central server when a 1645 security context is to be deleted. 1646 1647 This call can be made by either peer in a security context, to flush 1648 context-specific information and to return an output_context_token 1649 which can be passed to the context's peer informing it that the 1650 peer's corresponding context information can also be flushed. (Once a 1651 context is established, the peers involved are expected to retain 1652 cached credential and context-related information until the 1653 information's expiration time is reached or until a 1654 GSS_Delete_sec_context() call is made.) Attempts to perform per- 1655 message processing on a deleted context will result in error returns. 1656 16572.2.4. GSS_Process_context_token call 1658 1659 Inputs: 1660 1661 o context_handle INTEGER, 1662 1663 o input_context_token OCTET STRING 1664 1665 Outputs: 1666 1667 o major_status INTEGER, 1668 1669 o minor_status INTEGER, 1670 1671 Return major_status codes: 1672 1673 o GSS_COMPLETE indicates that the input_context_token was 1674 successfully processed in conjunction with the context referenced 1675 by context_handle. 1676 1677 o GSS_DEFECTIVE_TOKEN indicates that consistency checks performed on 1678 the received context_token failed, preventing further processing 1679 1680 1681 1682Linn [Page 30] 1683 1684RFC 1508 Generic Security Interface September 1993 1685 1686 1687 from being performed with that token. 1688 1689 o GSS_NO_CONTEXT indicates that no valid context was recognized for 1690 the input context_handle provided. 1691 1692 o GSS_FAILURE indicates that the context is recognized, but that the 1693 GSS_Process_context_token() operation could not be performed for 1694 reasons unspecified at the GSS-API level. 1695 1696 This call is used to process context_tokens received from a peer once 1697 a context has been established, with corresponding impact on 1698 context-level state information. One use for this facility is 1699 processing of the context_tokens generated by 1700 GSS_Delete_sec_context(); GSS_Process_context_token() will not block 1701 pending network interactions for that purpose. Another use is to 1702 process tokens indicating remote-peer context establishment failures 1703 after the point where the local GSS-API implementation has already 1704 indicated GSS_COMPLETE status. 1705 17062.2.5. GSS_Context_time call 1707 1708 Input: 1709 1710 o context_handle INTEGER, 1711 1712 Outputs: 1713 1714 o major_status INTEGER, 1715 1716 o minor_status INTEGER, 1717 1718 o lifetime_rec INTEGER - in seconds, or reserved value for 1719 INDEFINITE 1720 1721 Return major_status codes: 1722 1723 o GSS_COMPLETE indicates that the referenced context is valid, and 1724 will remain valid for the amount of time indicated in 1725 lifetime_rec. 1726 1727 o GSS_CONTEXT_EXPIRED indicates that data items related to the 1728 referenced context have expired. 1729 1730 o GSS_CREDENTIALS_EXPIRED indicates that the context is recognized, 1731 but that its associated credentials have expired. 1732 1733 o GSS_NO_CONTEXT indicates that no valid context was recognized for 1734 the input context_handle provided. 1735 1736 1737 1738Linn [Page 31] 1739 1740RFC 1508 Generic Security Interface September 1993 1741 1742 1743 o GSS_FAILURE indicates that the requested operation failed for 1744 reasons unspecified at the GSS-API level. 1745 1746 This call is used to determine the amount of time for which a 1747 currently established context will remain valid. 1748 17492.3. Per-message calls 1750 1751 This group of calls is used to perform per-message protection 1752 processing on an established security context. None of these calls 1753 block pending network interactions. These calls may be invoked by a 1754 context's initiator or by the context's target. The four members of 1755 this group should be considered as two pairs; the output from 1756 GSS_Sign() is properly input to GSS_Verify(), and the output from 1757 GSS_Seal() is properly input to GSS_Unseal(). 1758 1759 GSS_Sign() and GSS_Verify() support data origin authentication and 1760 data integrity services. When GSS_Sign() is invoked on an input 1761 message, it yields a per-message token containing data items which 1762 allow underlying mechanisms to provide the specified security 1763 services. The original message, along with the generated per-message 1764 token, is passed to the remote peer; these two data elements are 1765 processed by GSS_Verify(), which validates the message in 1766 conjunction with the separate token. 1767 1768 GSS_Seal() and GSS_Unseal() support caller-requested confidentiality 1769 in addition to the data origin authentication and data integrity 1770 services offered by GSS_Sign() and GSS_Verify(). GSS_Seal() outputs 1771 a single data element, encapsulating optionally enciphered user data 1772 as well as associated token data items. The data element output from 1773 GSS_Seal() is passed to the remote peer and processed by 1774 GSS_Unseal() at that system. GSS_Unseal() combines decipherment (as 1775 required) with validation of data items related to authentication and 1776 integrity. 1777 17782.3.1. GSS_Sign call 1779 1780 Inputs: 1781 1782 o context_handle INTEGER, 1783 1784 o qop_req INTEGER,-0 specifies default QOP 1785 1786 o message OCTET STRING 1787 1788 Outputs: 1789 1790 o major_status INTEGER, 1791 1792 1793 1794Linn [Page 32] 1795 1796RFC 1508 Generic Security Interface September 1993 1797 1798 1799 o minor_status INTEGER, 1800 1801 o per_msg_token OCTET STRING 1802 1803 Return major_status codes: 1804 1805 o GSS_COMPLETE indicates that a signature, suitable for an 1806 established security context, was successfully applied and that 1807 the message and corresponding per_msg_token are ready for 1808 transmission. 1809 1810 o GSS_CONTEXT_EXPIRED indicates that context-related data items have 1811 expired, so that the requested operation cannot be performed. 1812 1813 o GSS_CREDENTIALS_EXPIRED indicates that the context is recognized, 1814 but that its associated credentials have expired, so that the 1815 requested operation cannot be performed. 1816 1817 o GSS_NO_CONTEXT indicates that no valid context was recognized for 1818 the input context_handle provided. 1819 1820 o GSS_FAILURE indicates that the context is recognized, but that the 1821 requested operation could not be performed for reasons unspecified 1822 at the GSS-API level. 1823 1824 Using the security context referenced by context_handle, apply a 1825 signature to the input message (along with timestamps and/or other 1826 data included in support of mech_type-specific mechanisms) and return 1827 the result in per_msg_token. The qop_req parameter allows quality- 1828 of-protection control. The caller passes the message and the 1829 per_msg_token to the target. 1830 1831 The GSS_Sign() function completes before the message and 1832 per_msg_token is sent to the peer; successful application of 1833 GSS_Sign() does not guarantee that a corresponding GSS_Verify() has 1834 been (or can necessarily be) performed successfully when the message 1835 arrives at the destination. 1836 18372.3.2. GSS_Verify call 1838 1839 Inputs: 1840 1841 o context_handle INTEGER, 1842 1843 o message OCTET STRING, 1844 1845 o per_msg_token OCTET STRING 1846 1847 1848 1849 1850Linn [Page 33] 1851 1852RFC 1508 Generic Security Interface September 1993 1853 1854 1855 Outputs: 1856 1857 o qop_state INTEGER, 1858 1859 o major_status INTEGER, 1860 1861 o minor_status INTEGER, 1862 1863 Return major_status codes: 1864 1865 o GSS_COMPLETE indicates that the message was successfully verified. 1866 1867 o GSS_DEFECTIVE_TOKEN indicates that consistency checks performed on 1868 the received per_msg_token failed, preventing further processing 1869 from being performed with that token. 1870 1871 o GSS_BAD_SIG indicates that the received per_msg_token contains an 1872 incorrect signature for the message. 1873 1874 o GSS_DUPLICATE_TOKEN, GSS_OLD_TOKEN, and GSS_UNSEQ_TOKEN values 1875 appear in conjunction with the optional per-message replay 1876 detection features described in Section 1.2.3; their semantics are 1877 described in that section. 1878 1879 o GSS_CONTEXT_EXPIRED indicates that context-related data items have 1880 expired, so that the requested operation cannot be performed. 1881 1882 o GSS_CREDENTIALS_EXPIRED indicates that the context is recognized, 1883 but that its associated credentials have expired, so that the 1884 requested operation cannot be performed. 1885 1886 o GSS_NO_CONTEXT indicates that no valid context was recognized for 1887 the input context_handle provided. 1888 1889 o GSS_FAILURE indicates that the context is recognized, but that the 1890 GSS_Verify() operation could not be performed for reasons 1891 unspecified at the GSS-API level. 1892 1893 Using the security context referenced by context_handle, verify that 1894 the input per_msg_token contains an appropriate signature for the 1895 input message, and apply any active replay detection or sequencing 1896 features. Return an indication of the quality-of-protection applied 1897 to the processed message in the qop_state result. 1898 1899 1900 1901 1902 1903 1904 1905 1906Linn [Page 34] 1907 1908RFC 1508 Generic Security Interface September 1993 1909 1910 19112.3.3. GSS_Seal call 1912 1913 Inputs: 1914 1915 o context_handle INTEGER, 1916 1917 o conf_req_flag BOOLEAN, 1918 1919 o qop_req INTEGER,-0 specifies default QOP 1920 1921 o input_message OCTET STRING 1922 1923 Outputs: 1924 1925 o major_status INTEGER, 1926 1927 o minor_status INTEGER, 1928 1929 o conf_state BOOLEAN, 1930 1931 o output_message OCTET STRING 1932 1933 Return major_status codes: 1934 1935 o GSS_COMPLETE indicates that the input_message was successfully 1936 processed and that the output_message is ready for transmission. 1937 1938 o GSS_CONTEXT_EXPIRED indicates that context-related data items have 1939 expired, so that the requested operation cannot be performed. 1940 1941 o GSS_CREDENTIALS_EXPIRED indicates that the context is recognized, 1942 but that its associated credentials have expired, so that the 1943 requested operation cannot be performed. 1944 1945 o GSS_NO_CONTEXT indicates that no valid context was recognized for 1946 the input context_handle provided. 1947 1948 o GSS_FAILURE indicates that the context is recognized, but that the 1949 GSS_Seal() operation could not be performed for reasons 1950 unspecified at the GSS-API level. 1951 1952 Performs the data origin authentication and data integrity functions 1953 of GSS_Sign(). If the input conf_req_flag is TRUE, requests that 1954 confidentiality be applied to the input_message. Confidentiality may 1955 not be supported in all mech_types or by all implementations; the 1956 returned conf_state flag indicates whether confidentiality was 1957 provided for the input_message. The qop_req parameter allows 1958 quality-of-protection control. 1959 1960 1961 1962Linn [Page 35] 1963 1964RFC 1508 Generic Security Interface September 1993 1965 1966 1967 In all cases, the GSS_Seal() call yields a single output_message 1968 data element containing (optionally enciphered) user data as well as 1969 control information. 1970 19712.3.4. GSS_Unseal call 1972 1973 Inputs: 1974 1975 o context_handle INTEGER, 1976 1977 o input_message OCTET STRING 1978 1979 Outputs: 1980 1981 o conf_state BOOLEAN, 1982 1983 o qop_state INTEGER, 1984 1985 o major_status INTEGER, 1986 1987 o minor_status INTEGER, 1988 1989 o output_message OCTET STRING 1990 1991 Return major_status codes: 1992 1993 o GSS_COMPLETE indicates that the input_message was successfully 1994 processed and that the resulting output_message is available. 1995 1996 o GSS_DEFECTIVE_TOKEN indicates that consistency checks performed on 1997 the per_msg_token extracted from the input_message failed, 1998 preventing further processing from being performed. 1999 2000 o GSS_BAD_SIG indicates that an incorrect signature was detected for 2001 the message. 2002 2003 o GSS_DUPLICATE_TOKEN, GSS_OLD_TOKEN, and GSS_UNSEQ_TOKEN values 2004 appear in conjunction with the optional per-message replay 2005 detection features described in Section 1.2.3; their semantics are 2006 described in that section. 2007 2008 o GSS_CONTEXT_EXPIRED indicates that context-related data items have 2009 expired, so that the requested operation cannot be performed. 2010 2011 o GSS_CREDENTIALS_EXPIRED indicates that the context is recognized, 2012 but that its associated credentials have expired, so that the 2013 requested operation cannot be performed. 2014 2015 2016 2017 2018Linn [Page 36] 2019 2020RFC 1508 Generic Security Interface September 1993 2021 2022 2023 o GSS_NO_CONTEXT indicates that no valid context was recognized for 2024 the input context_handle provided. 2025 2026 o GSS_FAILURE indicates that the context is recognized, but that the 2027 GSS_Unseal() operation could not be performed for reasons 2028 unspecified at the GSS-API level. 2029 2030 Processes a data element generated (and optionally enciphered) by 2031 GSS_Seal(), provided as input_message. The returned conf_state value 2032 indicates whether confidentiality was applied to the input_message. 2033 If conf_state is TRUE, GSS_Unseal() deciphers the input_message. 2034 Returns an indication of the quality-of-protection applied to the 2035 processed message in the qop_state result. GSS_Seal() performs the 2036 data integrity and data origin authentication checking functions of 2037 GSS_Verify() on the plaintext data. Plaintext data is returned in 2038 output_message. 2039 20402.4. Support calls 2041 2042 This group of calls provides support functions useful to GSS-API 2043 callers, independent of the state of established contexts. Their 2044 characterization with regard to blocking or non-blocking status in 2045 terms of network interactions is unspecified. 2046 20472.4.1. GSS_Display_status call 2048 2049 Inputs: 2050 2051 o status_value INTEGER,-GSS-API major_status or minor_status 2052 return value 2053 2054 o status_type INTEGER,-1 if major_status, 2 if minor_status 2055 2056 o mech_type OBJECT IDENTIFIER-mech_type to be used for minor_ 2057 status translation 2058 2059 Outputs: 2060 2061 o major_status INTEGER, 2062 2063 o minor_status INTEGER, 2064 2065 o status_string_set SET OF OCTET STRING 2066 2067 Return major_status codes: 2068 2069 o GSS_COMPLETE indicates that a valid printable status 2070 representation (possibly representing more than one status event 2071 2072 2073 2074Linn [Page 37] 2075 2076RFC 1508 Generic Security Interface September 1993 2077 2078 2079 encoded within the status_value) is available in the returned 2080 status_string_set. 2081 2082 o GSS_BAD_MECH indicates that translation in accordance with an 2083 unsupported mech_type was requested, so translation could not be 2084 performed. 2085 2086 o GSS_BAD_STATUS indicates that the input status_value was invalid, 2087 or that the input status_type carried a value other than 1 or 2, 2088 so translation could not be performed. 2089 2090 o GSS_FAILURE indicates that the requested operation could not be 2091 performed for reasons unspecified at the GSS-API level. 2092 2093 Provides a means for callers to translate GSS-API-returned major and 2094 minor status codes into printable string representations. 2095 20962.4.2. GSS_Indicate_mechs call 2097 2098 Input: 2099 2100 o (none) 2101 2102 Outputs: 2103 2104 o major_status INTEGER, 2105 2106 o minor_status INTEGER, 2107 2108 o mech_set SET OF OBJECT IDENTIFIER 2109 2110 Return major_status codes: 2111 2112 o GSS_COMPLETE indicates that a set of available mechanisms has 2113 been returned in mech_set. 2114 2115 o GSS_FAILURE indicates that the requested operation could not 2116 be performed for reasons unspecified at the GSS-API level. 2117 2118 Allows callers to determine the set of mechanism types available on 2119 the local system. This call is intended for support of specialized 2120 callers who need to request non-default mech_type sets from 2121 GSS_Acquire_cred(), and should not be needed by other callers. 2122 21232.4.3. GSS_Compare_name call 2124 2125 Inputs: 2126 2127 2128 2129 2130Linn [Page 38] 2131 2132RFC 1508 Generic Security Interface September 1993 2133 2134 2135 o name1 INTERNAL NAME, 2136 2137 o name2 INTERNAL NAME 2138 2139 Outputs: 2140 2141 o major_status INTEGER, 2142 2143 o minor_status INTEGER, 2144 2145 o name_equal BOOLEAN 2146 2147 Return major_status codes: 2148 2149 o GSS_COMPLETE indicates that name1 and name2 were comparable, and 2150 that the name_equal result indicates whether name1 and name2 were 2151 equal or unequal. 2152 2153 o GSS_BAD_NAMETYPE indicates that one or both of name1 and name2 2154 contained internal type specifiers uninterpretable by the 2155 supporting GSS-API implementation, or that the two names' types 2156 are different and incomparable, so the equality comparison could 2157 not be completed. 2158 2159 o GSS_BAD_NAME indicates that one or both of the input names was 2160 ill-formed in terms of its internal type specifier, so the 2161 equality comparison could not be completed. 2162 2163 o GSS_FAILURE indicates that the requested operation could not be 2164 performed for reasons unspecified at the GSS-API level. 2165 2166 Allows callers to compare two internal name representations for 2167 equality. 2168 21692.4.4. GSS_Display_name call 2170 2171 Inputs: 2172 2173 o name INTERNAL NAME 2174 2175 Outputs: 2176 2177 o major_status INTEGER, 2178 2179 o minor_status INTEGER, 2180 2181 o name_string OCTET STRING, 2182 2183 2184 2185 2186Linn [Page 39] 2187 2188RFC 1508 Generic Security Interface September 1993 2189 2190 2191 o name_type OBJECT IDENTIFIER 2192 2193 Return major_status codes: 2194 2195 o GSS_COMPLETE indicates that a valid printable name representation 2196 is available in the returned name_string. 2197 2198 o GSS_BAD_NAMETYPE indicates that the provided name was of a type 2199 uninterpretable by the supporting GSS-API implementation, so no 2200 printable representation could be generated. 2201 2202 o GSS_BAD_NAME indicates that the contents of the provided name were 2203 inconsistent with the internally-indicated name type, so no 2204 printable representation could be generated. 2205 2206 o GSS_FAILURE indicates that the requested operation could not be 2207 performed for reasons unspecified at the GSS-API level. 2208 2209 Allows callers to translate an internal name representation into a 2210 printable form with associated namespace type descriptor. The syntax 2211 of the printable form is a local matter. 2212 22132.4.5. GSS_Import_name call 2214 2215 Inputs: 2216 2217 o input_name_string OCTET STRING, 2218 2219 o input_name_type OBJECT IDENTIFIER 2220 2221 Outputs: 2222 2223 o major_status INTEGER, 2224 2225 o minor_status INTEGER, 2226 2227 o output_name INTERNAL NAME 2228 2229 Return major_status codes: 2230 2231 o GSS_COMPLETE indicates that a valid name representation is output 2232 in output_name and described by the type value in 2233 output_name_type. 2234 2235 o GSS_BAD_NAMETYPE indicates that the input_name_type is unsupported 2236 by the GSS-API implementation, so the import operation could not 2237 be completed. 2238 2239 2240 2241 2242Linn [Page 40] 2243 2244RFC 1508 Generic Security Interface September 1993 2245 2246 2247 o GSS_BAD_NAME indicates that the provided input_name_string is 2248 ill-formed in terms of the input_name_type, so the import 2249 operation could not be completed. 2250 2251 o GSS_FAILURE indicates that the requested operation could not be 2252 performed for reasons unspecified at the GSS-API level. 2253 2254 Allows callers to provide a printable name representation, designate 2255 the type of namespace in conjunction with which it should be parsed, 2256 and convert that printable representation to an internal form 2257 suitable for input to other GSS-API routines. The syntax of the 2258 input_name is a local matter. 2259 22602.4.6. GSS_Release_name call 2261 2262 Inputs: 2263 2264 o name INTERNAL NAME 2265 2266 Outputs: 2267 2268 o major_status INTEGER, 2269 2270 o minor_status INTEGER 2271 2272 Return major_status codes: 2273 2274 o GSS_COMPLETE indicates that the storage associated with the input 2275 name was successfully released. 2276 2277 o GSS_BAD_NAME indicates that the input name argument did not 2278 contain a valid name. 2279 2280 o GSS_FAILURE indicates that the requested operation could not be 2281 performed for reasons unspecified at the GSS-API level. 2282 2283 Allows callers to release the storage associated with an internal 2284 name representation. 2285 22862.4.7. GSS_Release_buffer call 2287 2288 Inputs: 2289 2290 o buffer OCTET STRING 2291 2292 Outputs: 2293 2294 o major_status INTEGER, 2295 2296 2297 2298Linn [Page 41] 2299 2300RFC 1508 Generic Security Interface September 1993 2301 2302 2303 o minor_status INTEGER 2304 2305 Return major_status codes: 2306 2307 o GSS_COMPLETE indicates that the storage associated with the input 2308 buffer was successfully released. 2309 2310 o GSS_FAILURE indicates that the requested operation could not be 2311 performed for reasons unspecified at the GSS-API level. 2312 2313 Allows callers to release the storage associated with an OCTET STRING 2314 buffer allocated by another GSS-API call. 2315 23162.4.8. GSS_Release_oid_set call 2317 2318 Inputs: 2319 2320 o buffer SET OF OBJECT IDENTIFIER 2321 2322 Outputs: 2323 2324 o major_status INTEGER, 2325 2326 o minor_status INTEGER 2327 2328 Return major_status codes: 2329 2330 o GSS_COMPLETE indicates that the storage associated with the input 2331 object identifier set was successfully released. 2332 2333 o GSS_FAILURE indicates that the requested operation could not be 2334 performed for reasons unspecified at the GSS-API level. 2335 2336 Allows callers to release the storage associated with an object 2337 identifier set object allocated by another GSS-API call. 2338 23393. Mechanism-Specific Example Scenarios 2340 2341 This section provides illustrative overviews of the use of various 2342 candidate mechanism types to support the GSS-API. These discussions 2343 are intended primarily for readers familiar with specific security 2344 technologies, demonstrating how GSS-API functions can be used and 2345 implemented by candidate underlying mechanisms. They should not be 2346 regarded as constrictive to implementations or as defining the only 2347 means through which GSS-API functions can be realized with a 2348 particular underlying technology, and do not demonstrate all GSS-API 2349 features with each technology. 2350 2351 2352 2353 2354Linn [Page 42] 2355 2356RFC 1508 Generic Security Interface September 1993 2357 2358 23593.1. Kerberos V5, single-TGT 2360 2361 OS-specific login functions yield a TGT to the local realm Kerberos 2362 server; TGT is placed in a credentials structure for the client. 2363 Client calls GSS_Acquire_cred() to acquire a cred_handle in order to 2364 reference the credentials for use in establishing security contexts. 2365 2366 Client calls GSS_Init_sec_context(). If the requested service is 2367 located in a different realm, GSS_Init_sec_context() gets the 2368 necessary TGT/key pairs needed to traverse the path from local to 2369 target realm; these data are placed in the owner's TGT cache. After 2370 any needed remote realm resolution, GSS_Init_sec_context() yields a 2371 service ticket to the requested service with a corresponding session 2372 key; these data are stored in conjunction with the context. GSS-API 2373 code sends KRB_TGS_REQ request(s) and receives KRB_TGS_REP 2374 response(s) (in the successful case) or KRB_ERROR. 2375 2376 Assuming success, GSS_Init_sec_context() builds a Kerberos-formatted 2377 KRB_AP_REQ message, and returns it in output_token. The client sends 2378 the output_token to the service. 2379 2380 The service passes the received token as the input_token argument to 2381 GSS_Accept_sec_context(), which verifies the authenticator, provides 2382 the service with the client's authenticated name, and returns an 2383 output_context_handle. 2384 2385 Both parties now hold the session key associated with the service 2386 ticket, and can use this key in subsequent GSS_Sign(), GSS_Verify(), 2387 GSS_Seal(), and GSS_Unseal() operations. 2388 23893.2. Kerberos V5, double-TGT 2390 2391 TGT acquisition as above. 2392 2393 Note: To avoid unnecessary frequent invocations of error paths when 2394 implementing the GSS-API atop Kerberos V5, it seems appropriate to 2395 represent "single-TGT K-V5" and "double-TGT K-V5" with separate 2396 mech_types, and this discussion makes that assumption. 2397 2398 Based on the (specified or defaulted) mech_type, 2399 GSS_Init_sec_context() determines that the double-TGT protocol 2400 should be employed for the specified target. GSS_Init_sec_context() 2401 returns GSS_CONTINUE_NEEDED major_status, and its returned 2402 output_token contains a request to the service for the service's TGT. 2403 (If a service TGT with suitably long remaining lifetime already 2404 exists in a cache, it may be usable, obviating the need for this 2405 step.) The client passes the output_token to the service. Note: this 2406 scenario illustrates a different use for the GSS_CONTINUE_NEEDED 2407 2408 2409 2410Linn [Page 43] 2411 2412RFC 1508 Generic Security Interface September 1993 2413 2414 2415 status return facility than for support of mutual authentication; 2416 note that both uses can coexist as successive operations within a 2417 single context establishment operation. 2418 2419 The service passes the received token as the input_token argument to 2420 GSS_Accept_sec_context(), which recognizes it as a request for TGT. 2421 (Note that current Kerberos V5 defines no intra-protocol mechanism to 2422 represent such a request.) GSS_Accept_sec_context() returns 2423 GSS_CONTINUE_NEEDED major_status and provides the service's TGT in 2424 its output_token. The service sends the output_token to the client. 2425 2426 The client passes the received token as the input_token argument to a 2427 continuation of GSS_Init_sec_context(). GSS_Init_sec_context() caches 2428 the received service TGT and uses it as part of a service ticket 2429 request to the Kerberos authentication server, storing the returned 2430 service ticket and session key in conjunction with the context. 2431 GSS_Init_sec_context() builds a Kerberos-formatted authenticator, 2432 and returns it in output_token along with GSS_COMPLETE return 2433 major_status. The client sends the output_token to the service. 2434 2435 Service passes the received token as the input_token argument to a 2436 continuation call to GSS_Accept_sec_context(). 2437 GSS_Accept_sec_context() verifies the authenticator, provides the 2438 service with the client's authenticated name, and returns 2439 major_status GSS_COMPLETE. 2440 2441 GSS_Sign(), GSS_Verify(), GSS_Seal(), and GSS_Unseal() as above. 2442 24433.3. X.509 Authentication Framework 2444 2445 This example illustrates use of the GSS-API in conjunction with 2446 public-key mechanisms, consistent with the X.509 Directory 2447 Authentication Framework. 2448 2449 The GSS_Acquire_cred() call establishes a credentials structure, 2450 making the client's private key accessible for use on behalf of the 2451 client. 2452 2453 The client calls GSS_Init_sec_context(), which interrogates the 2454 Directory to acquire (and validate) a chain of public-key 2455 certificates, thereby collecting the public key of the service. The 2456 certificate validation operation determines that suitable signatures 2457 were applied by trusted authorities and that those certificates have 2458 not expired. GSS_Init_sec_context() generates a secret key for use 2459 in per-message protection operations on the context, and enciphers 2460 that secret key under the service's public key. 2461 2462 The enciphered secret key, along with an authenticator quantity 2463 2464 2465 2466Linn [Page 44] 2467 2468RFC 1508 Generic Security Interface September 1993 2469 2470 2471 signed with the client's private key, is included in the output_token 2472 from GSS_Init_sec_context(). The output_token also carries a 2473 certification path, consisting of a certificate chain leading from 2474 the service to the client; a variant approach would defer this path 2475 resolution to be performed by the service instead of being asserted 2476 by the client. The client application sends the output_token to the 2477 service. 2478 2479 The service passes the received token as the input_token argument to 2480 GSS_Accept_sec_context(). GSS_Accept_sec_context() validates the 2481 certification path, and as a result determines a certified binding 2482 between the client's distinguished name and the client's public key. 2483 Given that public key, GSS_Accept_sec_context() can process the 2484 input_token's authenticator quantity and verify that the client's 2485 private key was used to sign the input_token. At this point, the 2486 client is authenticated to the service. The service uses its private 2487 key to decipher the enciphered secret key provided to it for per- 2488 message protection operations on the context. 2489 2490 The client calls GSS_Sign() or GSS_Seal() on a data message, which 2491 causes per-message authentication, integrity, and (optional) 2492 confidentiality facilities to be applied to that message. The service 2493 uses the context's shared secret key to perform corresponding 2494 GSS_Verify() and GSS_Unseal() calls. 2495 24964. Related Activities 2497 2498 In order to implement the GSS-API atop existing, emerging, and future 2499 security mechanisms: 2500 2501 object identifiers must be assigned to candidate GSS-API 2502 mechanisms and the name types which they support 2503 2504 concrete data element formats must be defined for candidate 2505 mechanisms 2506 2507 Calling applications must implement formatting conventions which will 2508 enable them to distinguish GSS-API tokens from other data carried in 2509 their application protocols. 2510 2511 Concrete language bindings are required for the programming 2512 environments in which the GSS-API is to be employed; such bindings 2513 for the C language are available in an associated RFC. 2514 2515 2516 2517 2518 2519 2520 2521 2522Linn [Page 45] 2523 2524RFC 1508 Generic Security Interface September 1993 2525 2526 25275. Acknowledgments 2528 2529 This proposal is the result of a collaborative effort. 2530 Acknowledgments are due to the many members of the IETF Security Area 2531 Advisory Group (SAAG) and the Common Authentication Technology (CAT) 2532 Working Group for their contributions at meetings and by electronic 2533 mail. Acknowledgments are also due to Kannan Alagappan, Doug Barlow, 2534 Bill Brown, Cliff Kahn, Charlie Kaufman, Butler Lampson, Richard 2535 Pitkin, Joe Tardo, and John Wray of Digital Equipment Corporation, 2536 and John Carr, John Kohl, Jon Rochlis, Jeff Schiller, and Ted T'so of 2537 MIT and Project Athena. Joe Pato and Bill Sommerfeld of HP/Apollo, 2538 Walt Tuvell of OSF, and Bill Griffith and Mike Merritt of AT&T, 2539 provided inputs which helped to focus and clarify directions. 2540 Precursor work by Richard Pitkin, presented to meetings of the 2541 Trusted Systems Interoperability Group (TSIG), helped to demonstrate 2542 the value of a generic, mechanism-independent security service API. 2543 25446. Security Considerations 2545 2546 Security issues are discussed throughout this memo. 2547 25487. Author's Address 2549 2550 John Linn 2551 Geer Zolot Associates 2552 One Main St. 2553 Cambridge, MA 02142 USA 2554 2555 Phone: +1 617.374.3700 2556 Email: Linn@gza.com 2557 2558 2559 2560 2561 2562 2563 2564 2565 2566 2567 2568 2569 2570 2571 2572 2573 2574 2575 2576 2577 2578Linn [Page 46] 2579 2580RFC 1508 Generic Security Interface September 1993 2581 2582 2583APPENDIX A 2584 2585PACS AND AUTHORIZATION SERVICES 2586 2587 Consideration has been given to modifying the GSS-API service 2588 interface to recognize and manipulate Privilege Attribute 2589 Certificates (PACs) as in ECMA 138, carrying authorization data as a 2590 side effect of establishing a security context, but no such 2591 modifications have been incorporated at this time. This appendix 2592 provides rationale for this decision and discusses compatibility 2593 alternatives between PACs and the GSS-API which do not require that 2594 PACs be made visible to GSS-API callers. 2595 2596 Existing candidate mechanism types such as Kerberos and X.509 do not 2597 incorporate PAC manipulation features, and exclusion of such 2598 mechanisms from the set of candidates equipped to fully support the 2599 GSS-API seems inappropriate. Inclusion (and GSS-API visibility) of a 2600 feature supported by only a limited number of mechanisms could 2601 encourage the development of ostensibly portable applications which 2602 would in fact have only limited portability. 2603 2604 The status quo, in which PACs are not visible across the GSS-API 2605 interface, does not preclude implementations in which PACs are 2606 carried transparently, within the tokens defined and used for certain 2607 mech_types, and stored within peers' credentials and context-level 2608 data structures. While invisible to API callers, such PACs could be 2609 used by operating system or other local functions as inputs in the 2610 course of mediating access requests made by callers. This course of 2611 action allows dynamic selection of PAC contents, if such selection is 2612 administratively-directed rather than caller-directed. 2613 2614 In a distributed computing environment, authentication must span 2615 different systems; the need for such authentication provides 2616 motivation for GSS-API definition and usage. Heterogeneous systems in 2617 a network can intercommunicate, with globally authenticated names 2618 comprising the common bond between locally defined access control 2619 policies. Access control policies to which authentication provides 2620 inputs are often local, or specific to particular operating systems 2621 or environments. If the GSS-API made particular authorization models 2622 visible across its service interface, its scope of application would 2623 become less general. The current GSS-API paradigm is consistent with 2624 the precedent set by Kerberos, neither defining the interpretation of 2625 authorization-related data nor enforcing access controls based on 2626 such data. 2627 2628 The GSS-API is a general interface, whose callers may reside inside 2629 or outside any defined TCB or NTCB boundaries. Given this 2630 characteristic, it appears more realistic to provide facilities which 2631 2632 2633 2634Linn [Page 47] 2635 2636RFC 1508 Generic Security Interface September 1993 2637 2638 2639 provide "value-added" security services to its callers than to offer 2640 facilities which enforce restrictions on those callers. Authorization 2641 decisions must often be mediated below the GSS-API level in a local 2642 manner against (or in spite of) applications, and cannot be 2643 selectively invoked or omitted at those applications' discretion. 2644 Given that the GSS-API's placement prevents it from providing a 2645 comprehensive solution to the authorization issue, the value of a 2646 partial contribution specific to particular authorization models is 2647 debatable. 2648 2649APPENDIX B 2650 2651MECHANISM-INDEPENDENT TOKEN FORMAT 2652 2653 This appendix specifies a mechanism-independent level of 2654 encapsulating representation for the initial token of a GSS-API 2655 context establishment sequence, incorporating an identifier of the 2656 mechanism type to be used on that context. Use of this format (with 2657 ASN.1-encoded data elements represented in BER, constrained in the 2658 interests of parsing simplicity to the Distinguished Encoding Rule 2659 (DER) BER subset defined in X.509, clause 8.7) is recommended to the 2660 designers of GSS-API implementations based on various mechanisms, so 2661 that tokens can be interpreted unambiguously at GSS-API peers. There 2662 is no requirement that the mechanism-specific innerContextToken, 2663 innerMsgToken, and sealedUserData data elements be encoded in ASN.1 2664 BER. 2665 2666 -- optional top-level token definitions to 2667 -- frame different mechanisms 2668 2669 GSS-API DEFINITIONS ::= 2670 2671 BEGIN 2672 2673 MechType ::= OBJECT IDENTIFIER 2674 -- data structure definitions 2675 2676 -- callers must be able to distinguish among 2677 -- InitialContextToken, SubsequentContextToken, 2678 -- PerMsgToken, and SealedMessage data elements 2679 -- based on the usage in which they occur 2680 2681 InitialContextToken ::= 2682 -- option indication (delegation, etc.) indicated within 2683 -- mechanism-specific token 2684 [APPLICATION 0] IMPLICIT SEQUENCE { 2685 thisMech MechType, 2686 innerContextToken ANY DEFINED BY thisMech 2687 2688 2689 2690Linn [Page 48] 2691 2692RFC 1508 Generic Security Interface September 1993 2693 2694 2695 -- contents mechanism-specific 2696 } 2697 2698 SubsequentContextToken ::= innerContextToken ANY 2699 -- interpretation based on predecessor InitialContextToken 2700 2701 PerMsgToken ::= 2702 -- as emitted by GSS_Sign and processed by GSS_Verify 2703 innerMsgToken ANY 2704 2705 SealedMessage ::= 2706 -- as emitted by GSS_Seal and processed by GSS_Unseal 2707 -- includes internal, mechanism-defined indicator 2708 -- of whether or not encrypted 2709 sealedUserData ANY 2710 2711 END 2712 2713APPENDIX C 2714 2715MECHANISM DESIGN CONSTRAINTS 2716 2717 The following constraints on GSS-API mechanism designs are adopted in 2718 response to observed caller protocol requirements, and adherence 2719 thereto is anticipated in subsequent descriptions of GSS-API 2720 mechanisms to be documented in standards-track Internet 2721 specifications. 2722 2723 Use of the approach defined in Appendix B of this specification, 2724 applying a mechanism type tag to the InitialContextToken, is 2725 required. 2726 2727 It is strongly recommended that mechanisms offering per-message 2728 protection services also offer at least one of the replay detection 2729 and sequencing services, as mechanisms offering neither of the latter 2730 will fail to satisfy recognized requirements of certain candidate 2731 caller protocols. 2732 2733 2734 2735 2736 2737 2738 2739 2740 2741 2742 2743 2744 2745 2746Linn [Page 49] 2747