1 2 3 4 5 6 7Network Working Group L. Zhu 8Request for Comments: 4178 P. Leach 9Obsoletes: 2478 K. Jaganathan 10Category: Standards Track Microsoft Corporation 11 W. Ingersoll 12 Sun Microsystems 13 October 2005 14 15 16 The Simple and Protected 17 Generic Security Service Application Program Interface (GSS-API) 18 Negotiation Mechanism 19 20Status of This Memo 21 22 This document specifies an Internet standards track protocol for the 23 Internet community, and requests discussion and suggestions for 24 improvements. Please refer to the current edition of the "Internet 25 Official Protocol Standards" (STD 1) for the standardization state 26 and status of this protocol. Distribution of this memo is unlimited. 27 28Copyright Notice 29 30 Copyright (C) The Internet Society (2005). 31 32 33Abstract 34 35 This document specifies a negotiation mechanism for the Generic 36 Security Service Application Program Interface (GSS-API), which is 37 described in RFC 2743. GSS-API peers can use this negotiation 38 mechanism to choose from a common set of security mechanisms. If 39 per-message integrity services are available on the established 40 mechanism context, then the negotiation is protected against an 41 attacker that forces the selection of a mechanism not desired by the 42 peers. 43 44 This mechanism replaces RFC 2478 in order to fix defects in that 45 specification and to describe how to inter-operate with 46 implementations of that specification that are commonly deployed on 47 the Internet. 48 49 50 51 52 53 54 55 56 57 58Zhu, et al. Standards Track [Page 1] 59 60RFC 4178 The GSS-API Negotiation Mechanism October 2005 61 62 63Table of Contents 64 65 1. Introduction ....................................................2 66 2. Conventions Used in This Document ...............................3 67 3. Negotiation Protocol ............................................3 68 3.1. Negotiation Description ....................................4 69 3.2. Negotiation Procedure ......................................5 70 4. Token Definitions ...............................................7 71 4.1. Mechanism Types ............................................7 72 4.2. Negotiation Tokens .........................................7 73 4.2.1. negTokenInit ........................................8 74 4.2.2. negTokenResp ........................................9 75 5. Processing of mechListMIC ......................................10 76 6. Extensibility ..................................................13 77 7. Security Considerations ........................................13 78 8. Acknowledgments ................................................14 79 9. References .....................................................14 80 9.1. Normative References ......................................14 81 9.2. Informative References ....................................15 82 Appendix A. SPNEGO ASN.1 Module ..................................16 83 Appendix B. GSS-API Negotiation Support API ......................17 84 B.1. GSS_Set_neg_mechs Call ...................................17 85 B.2. GSS_Get_neg_mechs Call ...................................18 86 Appendix C. Changes since RFC 2478 ...............................18 87 Appendix D. mechListMIC Computation Example ......................20 88 891. Introduction 90 91 The GSS-API [RFC2743] provides a generic interface that can be 92 layered atop different security mechanisms such that, if 93 communicating peers acquire GSS-API credentials for the same security 94 mechanism, then a security context may be established between them 95 (subject to policy). However, GSS-API does not prescribe the method 96 by which GSS-API peers can establish whether they have a common 97 security mechanism. 98 99 The Simple and Protected GSS-API Negotiation (SPNEGO) mechanism 100 defined here is a pseudo security mechanism that enables GSS-API 101 peers to determine in-band whether their credentials support a common 102 set of one or more GSS-API security mechanisms; if so, it invokes the 103 normal security context establishment for a selected common security 104 mechanism. This is most useful for applications that depend on GSS- 105 API implementations and share multiple mechanisms between the peers. 106 107 The SPNEGO mechanism negotiation is based on the following model: the 108 initiator proposes a list of security mechanism(s), in decreasing 109 preference order (favorite choice first), the acceptor (also known as 110 the target) either accepts the initiator's preferred security 111 112 113 114Zhu, et al. Standards Track [Page 2] 115 116RFC 4178 The GSS-API Negotiation Mechanism October 2005 117 118 119 mechanism (the first in the list) or chooses one of the available 120 mechanisms from the offered list; if neither is acceptable, the 121 acceptor rejects the proposed value(s). The target then informs the 122 initiator of its choice. 123 124 Once a common security mechanism is chosen, mechanism-specific 125 options MAY be negotiated as part of the selected mechanism's context 126 establishment. These negotiations (if any) are internal to the 127 mechanism and opaque to the SPNEGO protocol. As such, they are 128 outside the scope of this document. 129 130 If per-message integrity services [RFC2743] are available on the 131 established mechanism security context, then the negotiation is 132 protected to ensure that the mechanism list has not been modified. 133 In cases where an attacker could have materially influenced the 134 negotiation, peers exchange message integrity code (MIC) tokens to 135 confirm that the mechanism list has not been modified. If no action 136 of an attacker could have materially modified the outcome of the 137 negotiation, the exchange of MIC tokens is optional (see Section 5). 138 Allowing MIC tokens to be optional in this case provides 139 interoperability with existing implementations while still protecting 140 the negotiation. This interoperability comes at the cost of 141 increased complexity. 142 143 SPNEGO relies on the concepts developed in the GSS-API specification 144 [RFC2743]. The negotiation data is encapsulated in context-level 145 tokens. Therefore, callers of the GSS-API do not need to be aware of 146 the existence of the negotiation tokens, but only of the new pseudo- 147 security mechanism. A failure in the negotiation phase causes a 148 major status code to be returned: GSS_S_BAD_MECH. 149 1502. Conventions Used in This Document 151 152 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 153 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 154 document are to be interpreted as described in [RFC2119]. 155 1563. Negotiation Protocol 157 158 When the established mechanism context provides integrity protection, 159 the mechanism negotiation can be protected. When acquiring 160 negotiated security mechanism tokens, per-message integrity services 161 are always requested by the SPNEGO mechanism. 162 163 When the established mechanism context supports per-message integrity 164 services, SPNEGO guarantees that the selected mechanism is mutually 165 preferred. 166 167 168 169 170Zhu, et al. Standards Track [Page 3] 171 172RFC 4178 The GSS-API Negotiation Mechanism October 2005 173 174 175 This section describes the negotiation process of this protocol. 176 1773.1. Negotiation Description 178 179 The first negotiation token sent by the initiator contains an ordered 180 list of mechanisms in decreasing preference order (favorite mechanism 181 first), and optionally the initial mechanism token for the preferred 182 mechanism of the initiator (i.e., the first in the list). (Note that 183 the list MUST NOT contain this SPNEGO mechanism itself or any 184 mechanism for which the client does not have appropriate 185 credentials.) 186 187 The target then processes the token from the initiator. This will 188 result in one of four possible states (as defined in Section 4.2.2) 189 being returned in the reply message: accept-completed, accept- 190 incomplete, reject, or request-mic. A reject state will terminate 191 the negotiation; an accept-completed state indicates that the 192 initiator-selected mechanism was acceptable to the target, and that 193 the security mechanism token embedded in the first negotiation 194 message was sufficient to complete the authentication; an accept- 195 incomplete state indicates that further message exchange is needed 196 but the MIC token exchange (as described in Section 5) is OPTIONAL; a 197 request-mic state (this state can only be present in the first reply 198 message from the target) indicates that the MIC token exchange is 199 REQUIRED if per-message integrity services are available. 200 201 Unless the preference order is specified by the application, the 202 policy by which the target chooses a mechanism is an implementation- 203 specific, local matter. In the absence of an application-specified 204 preference order or other policy, the target SHALL choose the first 205 mechanism in the initiator proposed list for which it has valid 206 credentials. 207 208 In case of a successful negotiation, the security mechanism in the 209 first reply message represents the value suitable for the target that 210 was chosen from the list offered by the initiator. 211 212 In case of an unsuccessful negotiation, the reject state is returned, 213 and the generation of a context-level negotiation token is OPTIONAL. 214 215 Once a mechanism has been selected, context establishment tokens 216 specific to the selected mechanism are carried within the negotiation 217 tokens. 218 219 Lastly, MIC tokens may be exchanged to ensure the authenticity of the 220 mechanism list received by the target. 221 222 223 224 225 226Zhu, et al. Standards Track [Page 4] 227 228RFC 4178 The GSS-API Negotiation Mechanism October 2005 229 230 231 To avoid conflicts with the use of MIC tokens by SPNEGO, partially- 232 established contexts MUST NOT be used for per-message calls. To 233 guarantee this, the prot_ready_state [RFC2743] MUST be set to false 234 on return from GSS_Init_sec_context() and GSS_Accept_sec_context(), 235 even if the underlying mechanism returned true. 236 237 Note that in order to avoid an extra round trip, the first context 238 establishment token of the initiator's preferred mechanism SHOULD be 239 embedded in the initial negotiation message (as defined in Section 240 4.2). (This mechanism token is referred to as the optimistic 241 mechanism token in this document.) In addition, using the optimistic 242 mechanism token allows the initiator to recover from non-fatal errors 243 encountered when trying to produce the first mechanism token before a 244 mechanism can be selected. In cases where the initiator's preferred 245 mechanism is not likely to be selected by the acceptor because of the 246 significant cost of its generation, implementations MAY omit the 247 optimistic mechanism token. 248 2493.2. Negotiation Procedure 250 251 The basic form of the procedure assumes that per-message integrity 252 services are available on the established mechanism context, and it 253 is summarized as follows: 254 255 a) The GSS-API initiator invokes GSS_Init_sec_context() as normal, 256 but requests that SPNEGO be used. SPNEGO can either be explicitly 257 requested or accepted as the default mechanism. 258 259 b) The initiator GSS-API implementation generates a negotiation token 260 containing a list of one or more security mechanisms that are 261 available based on the credentials used for this context 262 establishment, and optionally on the initial mechanism token for 263 the first mechanism in the list. 264 265 c) The GSS-API initiator application sends the token to the target 266 application. The GSS-API target application passes the token by 267 invoking GSS_Accept_sec_context(). The acceptor will do one of 268 the following: 269 270 I) If none of the proposed mechanisms are acceptable, the 271 negotiation SHALL be terminated. GSS_Accept_sec_context 272 indicates GSS_S_BAD_MECH. The acceptor MAY output a 273 negotiation token containing a reject state. 274 275 II) If either the initiator's preferred mechanism is not accepted 276 by the target or this mechanism is accepted but is not the 277 acceptor's most preferred mechanism (i.e., the MIC token 278 exchange as described in Section 5 is required), 279 280 281 282Zhu, et al. Standards Track [Page 5] 283 284RFC 4178 The GSS-API Negotiation Mechanism October 2005 285 286 287 GSS_Accept_sec_context() indicates GSS_S_CONTINUE_NEEDED. 288 The acceptor MUST output a negotiation token containing a 289 request-mic state. 290 291 III) Otherwise, if at least one additional negotiation token from 292 the initiator is needed to establish this context, 293 GSS_Accept_sec_context() indicates GSS_S_CONTINUE_NEEDED and 294 outputs a negotiation token containing an accept-incomplete 295 state. 296 297 IV) Otherwise, no additional negotiation token from the initiator 298 is needed to establish this context, GSS_Accept_sec_context() 299 indicates GSS_S_COMPLETE and outputs a negotiation token 300 containing an accept_complete state. 301 302 If the initiator's preferred mechanism is accepted, and an 303 optimistic mechanism token was included, this mechanism token MUST 304 be passed to the selected mechanism by invoking 305 GSS_Accept_sec_context(). If a response mechanism token is 306 returned, it MUST be included in the response negotiation token. 307 Otherwise, the target will not generate a response mechanism token 308 in the first reply. 309 310 d) The GSS-API target application returns the negotiation token to 311 the initiator application. The GSS-API initiator application 312 passes the token by invoking GSS_Init_sec_context(). The security 313 context initialization is then continued according to the standard 314 GSS-API conventions for the selected mechanism, where the tokens 315 of the selected mechanism are encapsulated in negotiation messages 316 (see Section 4) until GSS_S_COMPLETE is returned for both the 317 initiator and the target by the selected security mechanism. 318 319 e) MIC tokens are then either skipped or exchanged according to 320 Section 5. 321 322 Note that the *_req_flag input parameters for context establishment 323 are relative to the selected mechanism, as are the *_state output 324 parameters. That is, these parameters are not applicable to the 325 negotiation process per se. 326 327 On receipt of a negotiation token on the target side, a GSS-API 328 implementation that does not support negotiation would indicate the 329 GSS_S_BAD_MECH status as though a particular basic security mechanism 330 had been requested and was not supported. 331 332 When a GSS-API credential is acquired for the SPNEGO mechanism, the 333 implementation SHOULD produce a credential element for the SPNEGO 334 mechanism that internally contains GSS-API credential elements for 335 336 337 338Zhu, et al. Standards Track [Page 6] 339 340RFC 4178 The GSS-API Negotiation Mechanism October 2005 341 342 343 all mechanisms for which the principal has credentials available, 344 except for any mechanisms that are not to be negotiated, per 345 implementation-, site-, or application-specific policy. See Appendix 346 B for interfaces for expressing application policy. 347 3484. Token Definitions 349 350 The type definitions in this section assume an ASN.1 module 351 definition of the following form: 352 353 SPNEGOASNOneSpec { 354 iso(1) identified-organization(3) dod(6) internet(1) 355 security(5) mechanism(5) snego (2) modules(4) spec2(2) 356 } DEFINITIONS EXPLICIT TAGS ::= BEGIN 357 358 -- rest of definitions here 359 360 END 361 362 This specifies that the tagging context for the module will be 363 explicit and non-automatic. 364 365 The encoding of the SPNEGO protocol messages shall obey the 366 Distinguished Encoding Rules (DER) of ASN.1, as described in [X690]. 367 3684.1. Mechanism Types 369 370 In this negotiation model, each OID represents one GSS-API mechanism 371 or one variant (see Section 6) of it, according to [RFC2743]. 372 373 MechType ::= OBJECT IDENTIFIER 374 -- OID represents each security mechanism as suggested by 375 -- [RFC2743] 376 377 MechTypeList ::= SEQUENCE OF MechType 378 3794.2. Negotiation Tokens 380 381 The syntax of the initial negotiation tokens follows the 382 initialContextToken syntax defined in Section 3.1 of [RFC2743]. The 383 SPNEGO pseudo mechanism is identified by the Object Identifier 384 iso.org.dod.internet.security.mechanism.snego (1.3.6.1.5.5.2). 385 Subsequent tokens MUST NOT be encapsulated in this GSS-API generic 386 token framing. 387 388 This section specifies the syntax of the inner token for the initial 389 message and the syntax of subsequent context establishment tokens. 390 391 392 393 394Zhu, et al. Standards Track [Page 7] 395 396RFC 4178 The GSS-API Negotiation Mechanism October 2005 397 398 399 NegotiationToken ::= CHOICE { 400 negTokenInit [0] NegTokenInit, 401 negTokenResp [1] NegTokenResp 402 } 403 4044.2.1. negTokenInit 405 406 NegTokenInit ::= SEQUENCE { 407 mechTypes [0] MechTypeList, 408 reqFlags [1] ContextFlags OPTIONAL, 409 -- inherited from RFC 2478 for backward compatibility, 410 -- RECOMMENDED to be left out 411 mechToken [2] OCTET STRING OPTIONAL, 412 mechListMIC [3] OCTET STRING OPTIONAL, 413 ... 414 } 415 ContextFlags ::= BIT STRING { 416 delegFlag (0), 417 mutualFlag (1), 418 replayFlag (2), 419 sequenceFlag (3), 420 anonFlag (4), 421 confFlag (5), 422 integFlag (6) 423 } (SIZE (32)) 424 425 This is the syntax for the inner token of the initial negotiation 426 message. 427 428 mechTypes 429 430 This field contains one or more security mechanisms available for 431 the initiator, in decreasing preference order (favorite choice 432 first). 433 434 reqFlags 435 436 This field, if present, contains the service options that are 437 requested to establish the context (the req_flags parameter of 438 GSS_Init_sec_context()). This field is inherited from RFC 2478 439 and is not integrity protected. For implementations of this 440 specification, the initiator SHOULD omit this reqFlags field and 441 the acceptor MUST ignore this reqFlags field. 442 443 The size constraint on the ContextFlags ASN.1 type only applies to 444 the abstract type. The ASN.1 DER requires that all trailing zero 445 bits be truncated from the encoding of a bit string type whose 446 abstract definition includes named bits. Implementations should 447 448 449 450Zhu, et al. Standards Track [Page 8] 451 452RFC 4178 The GSS-API Negotiation Mechanism October 2005 453 454 455 not expect to receive exactly 32 bits in an encoding of 456 ContextFlags. 457 458 mechToken 459 460 This field, if present, contains the optimistic mechanism token. 461 462 mechlistMIC 463 464 This field, if present, contains an MIC token for the mechanism 465 list in the initial negotiation message. This MIC token is 466 computed according to Section 5. 467 4684.2.2. negTokenResp 469 470 NegTokenResp ::= SEQUENCE { 471 negState [0] ENUMERATED { 472 accept-completed (0), 473 accept-incomplete (1), 474 reject (2), 475 request-mic (3) 476 } OPTIONAL, 477 -- REQUIRED in the first reply from the target 478 supportedMech [1] MechType OPTIONAL, 479 -- present only in the first reply from the target 480 responseToken [2] OCTET STRING OPTIONAL, 481 mechListMIC [3] OCTET STRING OPTIONAL, 482 ... 483 } 484 485 This is the syntax for all subsequent negotiation messages. 486 487 negState 488 489 This field, if present, contains the state of the negotiation. 490 This can be: 491 492 accept-completed 493 494 No further negotiation message from the peer is expected, and 495 the security context is established for the sender. 496 497 accept-incomplete 498 499 At least one additional negotiation message from the peer is 500 needed to establish the security context. 501 502 503 504 505 506Zhu, et al. Standards Track [Page 9] 507 508RFC 4178 The GSS-API Negotiation Mechanism October 2005 509 510 511 reject 512 513 The sender terminates the negotiation. 514 515 request-mic 516 517 The sender indicates that the exchange of MIC tokens, as 518 described in Section 5, will be REQUIRED if per-message 519 integrity services are available on the mechanism context to be 520 established. This value SHALL only be present in the first 521 reply from the target. 522 523 This field is REQUIRED in the first reply from the target, and is 524 OPTIONAL thereafter. When negState is absent, the actual state 525 should be inferred from the state of the negotiated mechanism 526 context. 527 528 supportedMech 529 530 This field SHALL only be present in the first reply from the 531 target. It MUST be one of the mechanism(s) offered by the 532 initiator. 533 534 ResponseToken 535 536 This field, if present, contains tokens specific to the mechanism 537 selected. 538 539 mechlistMIC 540 541 This field, if present, contains an MIC token for the mechanism 542 list in the initial negotiation message. This MIC token is 543 computed according to Section 5. 544 5455. Processing of mechListMIC 546 547 If the mechanism selected by the negotiation does not support 548 integrity protection, then no mechlistMIC token is used. 549 550 Otherwise, if the accepted mechanism is the most preferred mechanism 551 of both the initiator and the acceptor, then the MIC token exchange, 552 as described later in this section, is OPTIONAL. A mechanism is the 553 acceptor's most preferred mechanism if there is no other mechanism 554 that the acceptor would have preferred over the accepted mechanism 555 had it been present in the mechanism list. 556 557 In all other cases, MIC tokens MUST be exchanged after the mechanism 558 context is fully established. 559 560 561 562Zhu, et al. Standards Track [Page 10] 563 564RFC 4178 The GSS-API Negotiation Mechanism October 2005 565 566 567 a) The mechlistMIC token (or simply the MIC token) is computed over 568 the mechanism list in the initial negotiation message by invoking 569 GSS_GetMIC() as follows: the input context_handle is the 570 established mechanism context, the input qop_req is 0, and the 571 input message is the DER encoding of the value of type 572 MechTypeList, which is contained in the "mechTypes" field of the 573 NegTokenInit. The input message is NOT the DER encoding of the 574 type "[0] MechTypeList". 575 576 b) If the selected mechanism exchanges an even number of mechanism 577 tokens (i.e., the acceptor sends the last mechanism token), the 578 acceptor does the following when generating the negotiation 579 message containing the last mechanism token: if the MIC token 580 exchange is optional, GSS_Accept_sec_context() either indicates 581 GSS_S_COMPLETE and does not include a mechlistMIC token, or 582 indicates GSS_S_CONTINUE_NEEDED and includes a mechlistMIC token 583 and an accept-incomplete state; if the MIC token exchange is 584 required, GSS_Accept_sec_context() indicates GSS_S_CONTINUE_NEEDED 585 and includes a mechlistMIC token. Acceptors that wish to be 586 compatible with legacy Windows SPNEGO implementations, as 587 described in Appendix C, should not generate a mechlistMIC token 588 when the MIC token exchange is not required. The initiator then 589 processes the last mechanism token, and does one of the following: 590 591 I) If a mechlistMIC token was included and is correctly 592 verified, GSS_Init_sec_context() indicates GSS_S_COMPLETE. 593 The output negotiation message contains a mechlistMIC token 594 and an accept_complete state. The acceptor MUST then verify 595 this mechlistMIC token. 596 597 II) If a mechlistMIC token was included but is incorrect, the 598 negotiation SHALL be terminated. GSS_Init_sec_context() 599 indicates GSS_S_DEFECTIVE_TOKEN. 600 601 III) If no mechlistMIC token was included and the MIC token 602 exchange is not required, GSS_Init_sec_context() indicates 603 GSS_S_COMPLETE with no output token. 604 605 IV) If no mechlistMIC token was included but the MIC token 606 exchange is required, the negotiation SHALL be terminated. 607 GSS_Accept_sec_context() indicates GSS_S_DEFECTIVE_TOKEN. 608 609 c) In the case that the chosen mechanism exchanges an odd number of 610 mechanism tokens (i.e., the initiator sends the last mechanism 611 token), the initiator does the following when generating the 612 negotiation message containing the last mechanism token: if the 613 negState was request-mic in the first reply from the target, a 614 mechlistMIC token MUST be included; otherwise, the mechlistMIC 615 616 617 618Zhu, et al. Standards Track [Page 11] 619 620RFC 4178 The GSS-API Negotiation Mechanism October 2005 621 622 623 token is OPTIONAL. (Note that the MIC token exchange is required 624 if a mechanism other than the initiator's first choice is chosen.) 625 In the case that the optimistic mechanism token is the only 626 mechanism token for the initiator's preferred mechanism, the 627 mechlistMIC token is OPTIONAL. Whether the mechlistMIC token is 628 included, GSS_Init_sec_context() indicates GSS_S_CONTINUE_NEEDED. 629 Initiators that wish to be compatible with legacy Windows SPNEGO 630 implementations, as described in Appendix C, should not generate a 631 mechlistMIC token when the MIC token exchange is not required. 632 The acceptor then processes the last mechanism token and does one 633 of the following: 634 635 I) If a mechlistMIC token was included and is correctly 636 verified, GSS_Accept_sec_context() indicates GSS_S_COMPLETE. 637 The output negotiation message contains a mechlistMIC token 638 and an accept_complete state. The initiator MUST then verify 639 this mechlistMIC token. 640 641 II) If a mechlistMIC token was included but is incorrect, the 642 negotiation SHALL be terminated. GSS_Accept_sec_context() 643 indicates GSS_S_DEFECTIVE_TOKEN. 644 645 III) If no mechlistMIC token was included and the mechlistMIC 646 token exchange is not required, GSS_Accept_sec_context() 647 indicates GSS_S_COMPLETE. The output negotiation message 648 contains an accept_complete state. 649 650 IV) In the case that the optimistic mechanism token is also the 651 last mechanism token (when the initiator's preferred 652 mechanism is accepted by the target) and the target sends a 653 request-mic state but the initiator did not send a 654 mechlistMIC token, the target then MUST include a mechlistMIC 655 token in that first reply. GSS_Accept_sec_context() 656 indicates GSS_S_CONTINUE_NEEDED. The initiator MUST verify 657 the received mechlistMIC token and generate a mechlistMIC 658 token to send back to the target. The target SHALL, in turn, 659 verify the returned mechlistMIC token and complete the 660 negotiation. 661 662 V) If no mechlistMIC token was included and the acceptor sent a 663 request-mic state in the first reply message (the exchange of 664 MIC tokens is required), the negotiation SHALL be terminated. 665 GSS_Accept_sec_context() indicates GSS_S_DEFECTIVE_TOKEN. 666 667 668 669 670 671 672 673 674Zhu, et al. Standards Track [Page 12] 675 676RFC 4178 The GSS-API Negotiation Mechanism October 2005 677 678 6796. Extensibility 680 681 Two mechanisms are provided for extensibility. First, the ASN.1 682 structures in this specification MAY be expanded by IETF standards 683 action. Implementations receiving unknown fields MUST ignore these 684 fields. 685 686 Secondly, OIDs corresponding to a desired mechanism attribute (i.e., 687 mechanism variants) may be included in the set of preferred 688 mechanisms by an initiator. The acceptor can choose to honor this 689 request by preferring mechanisms that have the included attributes. 690 Future work within the Kitten working group is expected to 691 standardize common attributes that SPNEGO mechanisms may wish to 692 support. At this time, it is sufficient to say that initiators MAY 693 include OIDs that do not correspond to mechanisms. Such OIDs MAY 694 influence the acceptor's choice of mechanism. As discussed in 695 Section 5, if there are mechanisms that, if present in the 696 initiator's list of mechanisms, might be preferred by the acceptor 697 instead of the initiator's preferred mechanism, the acceptor MUST 698 demand the MIC token exchange. As the consequence, acceptors MUST 699 demand the MIC token exchange if they support negotiation of 700 attributes not available in the initiator's preferred mechanism, 701 regardless of whether the initiator actually requested these 702 attributes. 703 7047. Security Considerations 705 706 In order to produce the MIC token for the mechanism list, the 707 mechanism must provide integrity protection. When the selected 708 mechanism does not support integrity protection, the negotiation is 709 vulnerable: an active attacker can force it to use a security 710 mechanism that is not mutually preferred but is acceptable to the 711 target. 712 713 This protocol provides the following guarantees when per-message 714 integrity services are available on the established mechanism 715 context, and the mechanism list was altered by an adversary such that 716 a mechanism that is not mutually preferred could be selected: 717 718 a) If the last mechanism token is sent by the initiator, both peers 719 shall fail; 720 721 b) If the last mechanism token is sent by the acceptor, the acceptor 722 shall not complete and the initiator, at worst, shall complete 723 with its preferred mechanism being selected. 724 725 The negotiation may not be terminated if an alteration was made but 726 had no material impact. 727 728 729 730Zhu, et al. Standards Track [Page 13] 731 732RFC 4178 The GSS-API Negotiation Mechanism October 2005 733 734 735 The protection of the negotiation depends on the strength of the 736 integrity protection. In particular, the strength of SPNEGO is no 737 stronger than the integrity protection of the weakest mechanism 738 acceptable to GSS-API peers. 739 740 Note that where there exist multiple mechanisms with similar context 741 tokens, but different semantics, such that some or all of the 742 mechanisms' context tokens can be easily altered so that one 743 mechanism's context tokens may pass for another of the similar 744 mechanism's context tokens, then there may exist a downgrade or 745 similar attacks. For example, if a given family of mechanisms uses 746 the same context token syntax for two or more variants and depends on 747 the OID in the initial token's pseudo-ASN.1/DER wrapper, but does not 748 provide integrity protection for that OID, then there may exist an 749 attack against those mechanisms. SPNEGO does not generally defeat 750 such attacks. 751 752 In all cases, the communicating peers are exposed to the denial of 753 service threat. 754 7558. Acknowledgments 756 757 The authors wish to thank Sam Hartman, Nicolas Williams, Ken Raeburn, 758 Martin Rex, Jeff Altman, Tom Yu, Cristian Ilac, Simon Spero, and Bill 759 Sommerfeld for their comments and suggestions during the development 760 of this document. 761 762 Luke Howard provided a prototype of this protocol in Heimdal and 763 resolved several issues in the initial version of this document. 764 765 Eric Baize and Denis Pinkas wrote the original SPNEGO specification 766 [RFC2478] of which some of the text has been retained in this 767 document. 768 7699. References 770 7719.1. Normative References 772 773 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 774 Requirement Levels", BCP 14, RFC 2119, March 1997. 775 776 [RFC2743] Linn, J., "Generic Security Service Application Program 777 Interface Version 2, Update 1", RFC 2743, January 2000. 778 779 [X690] ASN.1 encoding rules: Specification of Basic Encoding Rules 780 (BER), Canonical Encoding Rules (CER) and Distinguished 781 Encoding Rules (DER), ITU-T Recommendation X.690 (1997) | 782 ISO/IEC International Standard 8825-1:1998. 783 784 785 786Zhu, et al. Standards Track [Page 14] 787 788RFC 4178 The GSS-API Negotiation Mechanism October 2005 789 790 7919.2. Informative References 792 793 [RFC2478] Baize, E. and D. Pinkas, "The Simple and Protected GSS-API 794 Negotiation Mechanism", RFC 2478, December 1998. 795 796 797 798 799 800 801 802 803 804 805 806 807 808 809 810 811 812 813 814 815 816 817 818 819 820 821 822 823 824 825 826 827 828 829 830 831 832 833 834 835 836 837 838 839 840 841 842Zhu, et al. Standards Track [Page 15] 843 844RFC 4178 The GSS-API Negotiation Mechanism October 2005 845 846 847Appendix A. SPNEGO ASN.1 Module 848 849 SPNEGOASNOneSpec { 850 iso(1) identified-organization(3) dod(6) internet(1) 851 security(5) mechanism(5) snego (2) modules(4) spec2(2) 852 } DEFINITIONS EXPLICIT TAGS ::= BEGIN 853 854 MechType ::= OBJECT IDENTIFIER 855 -- OID represents each security mechanism as suggested by 856 -- [RFC2743] 857 858 MechTypeList ::= SEQUENCE OF MechType 859 860 NegotiationToken ::= CHOICE { 861 negTokenInit [0] NegTokenInit, 862 negTokenResp [1] NegTokenResp 863 } 864 865 NegTokenInit ::= SEQUENCE { 866 mechTypes [0] MechTypeList, 867 reqFlags [1] ContextFlags OPTIONAL, 868 -- inherited from RFC 2478 for backward compatibility, 869 -- RECOMMENDED to be left out 870 mechToken [2] OCTET STRING OPTIONAL, 871 mechListMIC [3] OCTET STRING OPTIONAL, 872 ... 873 } 874 NegTokenResp ::= SEQUENCE { 875 negState [0] ENUMERATED { 876 accept-completed (0), 877 accept-incomplete (1), 878 reject (2), 879 request-mic (3) 880 } OPTIONAL, 881 -- REQUIRED in the first reply from the target 882 supportedMech [1] MechType OPTIONAL, 883 -- present only in the first reply from the target 884 responseToken [2] OCTET STRING OPTIONAL, 885 mechListMIC [3] OCTET STRING OPTIONAL, 886 ... 887 } 888 889 ContextFlags ::= BIT STRING { 890 delegFlag (0), 891 mutualFlag (1), 892 replayFlag (2), 893 sequenceFlag (3), 894 anonFlag (4), 895 896 897 898Zhu, et al. Standards Track [Page 16] 899 900RFC 4178 The GSS-API Negotiation Mechanism October 2005 901 902 903 confFlag (5), 904 integFlag (6) 905 } (SIZE (32)) 906 907 END 908 909Appendix B. GSS-API Negotiation Support API 910 911 In order to provide to a GSS-API caller (the initiator or the target 912 or both) with the ability to choose among the set of supported 913 mechanisms, a reduced set of mechanisms for negotiation and two 914 additional APIs are defined: 915 916 o GSS_Get_neg_mechs() indicates the set of security mechanisms 917 available on the local system to the caller for negotiation, for 918 which appropriate credentials are available. 919 920 o GSS_Set_neg_mechs() specifies the set of security mechanisms to be 921 used on the local system by the caller for negotiation, for the 922 given credentials. 923 924B.1. GSS_Set_neg_mechs Call 925 926 Inputs: 927 928 o cred_handle CREDENTIAL HANDLE, -- NULL specifies default 929 -- credentials 930 o mech_set SET OF OBJECT IDENTIFIER 931 932 Outputs: 933 934 o major_status INTEGER, 935 o minor_status INTEGER 936 937 Return major_status codes: 938 939 o GSS_S_COMPLETE indicates that the set of security mechanisms 940 available for negotiation has been set to mech_set. 941 o GSS_S_FAILURE indicates that the requested operation could not be 942 performed for reasons unspecified at the GSS-API level. 943 944 This allows callers to specify the set of security mechanisms that 945 may be negotiated with the credential identified by cred_handle. 946 This call is intended to support specialized callers who need to 947 restrict the set of negotiable security mechanisms from the set of 948 all security mechanisms available to the caller (based on available 949 950 951 952 953 954Zhu, et al. Standards Track [Page 17] 955 956RFC 4178 The GSS-API Negotiation Mechanism October 2005 957 958 959 credentials). Note that if more than one mechanism is specified in 960 mech_set, the order in which those mechanisms are specified implies a 961 relative preference. 962 963B.2. GSS_Get_neg_mechs Call 964 965 Input: 966 967 o cred_handle CREDENTIAL HANDLE -- NULL specifies default -- 968 credentials 969 970 Outputs: 971 972 o major_status INTEGER, 973 o minor_status INTEGER, 974 o mech_set SET OF OBJECT IDENTIFIER 975 976 Return major_status codes: 977 978 o GSS_S_COMPLETE indicates that the set of security mechanisms 979 available for negotiation has been returned in mech_set. 980 981 o GSS_S_FAILURE indicates that the requested operation could not be 982 performed for reasons unspecified at the GSS-API level. 983 984 This allows callers to determine the set of security mechanisms 985 available for negotiation with the credential identified by 986 cred_handle. This call is intended to support specialized callers 987 who need to reduce the set of negotiable security mechanisms from the 988 set of supported security mechanisms available to the caller (based 989 on available credentials). 990 991 Note: The GSS_Indicate_mechs() function indicates the full set of 992 mechanism types available on the local system. Since this call has 993 no input parameter, the returned set is not necessarily available for 994 all credentials. 995 996Appendix C. Changes since RFC 2478 997 998 SPNEGO implementations in Microsoft Windows 2000/Windows XP/Windows 999 Server 2003 have the following behavior: no mechlistMIC is produced 1000 and mechlistMIC is not processed if one is provided; if the initiator 1001 sends the last mechanism token, the acceptor will send back a 1002 negotiation token with an accept_complete state and no mechlistMIC 1003 token. In addition, an incorrect OID (1.2.840.48018.1.2.2) can be 1004 used to identify the GSS-API Kerberos Version 5 mechanism. 1005 1006 1007 1008 1009 1010Zhu, et al. Standards Track [Page 18] 1011 1012RFC 4178 The GSS-API Negotiation Mechanism October 2005 1013 1014 1015 The following changes have been made to be compatible with these 1016 legacy implementations. 1017 1018 * NegTokenTarg is changed to negTokenResp and is the message format 1019 for all subsequent negotiation tokens. 1020 1021 * NegTokenInit is the message for the initial negotiation message, 1022 and only that message. 1023 1024 * mechTypes in negTokenInit is not optional. 1025 1026 * If the selected mechanism is also the most preferred mechanism for 1027 both peers, it is safe to omit the MIC tokens. 1028 1029 If at least one of the two peers implements the updated pseudo 1030 mechanism in this document, the negotiation is protected. 1031 1032 The following changes are to address problems in RFC 2478. 1033 1034 * reqFlags is not protected, therefore it should not impact the 1035 negotiation. 1036 1037 * DER encoding is required. 1038 1039 * GSS_GetMIC() input is clarified. 1040 1041 * Per-message integrity services are requested for the negotiated 1042 mechanism. 1043 1044 * Two MIC tokens are exchanged, one in each direction. 1045 1046 An implementation that conforms to this specification will not 1047 inter-operate with a strict RFC 2748 implementation. Even if the new 1048 implementation always sends a mechlistMIC token, it will still fail 1049 to inter-operate. If it is a server, it will fail because it 1050 requests a mechlistMIC token using an option that older 1051 implementations do not support. Clients will tend to fail as well. 1052 1053 As an alternative to the approach chosen in this specification, we 1054 could have documented a correct behavior that is fully backward 1055 compatible with RFC 2478 and included an appendix on how to inter- 1056 operate with existing incorrect implementations of RFC 2478. 1057 1058 As a practical matter, the SPNEGO implementers within the IETF have 1059 valued interoperability with the Microsoft implementations. We were 1060 unable to choose to maintain reasonable security guarantees, to 1061 maintain interoperability with the Microsoft implementations, and to 1062 maintain interoperability with correct implementations of RFC 2478. 1063 1064 1065 1066Zhu, et al. Standards Track [Page 19] 1067 1068RFC 4178 The GSS-API Negotiation Mechanism October 2005 1069 1070 1071 The working group was not aware of any RFC 2478 implementations 1072 deployed on the Internet. Even if there are such implementations, it 1073 is unlikely that they will inter-operate because of a critical flaw 1074 in the description of the encoding of the mechanism list in RFC 2478. 1075 1076 With the approach taken in this specification, security is ensured 1077 between new implementations all the time while maintaining 1078 interoperability with the implementations deployed within the IETF 1079 community. The working group believes that this justifies breaking 1080 compatibility with a correct implementation of RFC 2478. 1081 1082Appendix D. mechListMIC Computation Example 1083 1084 The following is an example to illustrate how the mechListMIC field 1085 would be computed. 1086 1087 The initial part of the DER encoding of NegTokenInit is constructed 1088 as follows (the "nn" are length encodings, possibly longer than one 1089 octet): 1090 1091 30 -- identifier octet for constructed SEQUENCE (NegTokenInit) 1092 nn -- length 1093 1094 -- contents octets of the SEQUENCE begin with 1095 -- DER encoding of "[0] MechTypeList": 1096 A0 -- identifier octet for constructed [0] 1097 nn -- length 1098 1099 -- contents of the constructed [0] are DER encoding 1100 -- of MechTypeList (which is a SEQUENCE): 1101 30 -- identifier octet for constructed SEQUENCE 1102 nn -- length 1103 1104 -- contents octets of the SEQUENCE begin with 1105 -- DER encoding of OBJECT IDENTIFIER: 1106 06 -- identifier octet for primitive OBJECT IDENTIFIER 1107 09 -- length 1108 2A 86 48 86 F7 12 01 02 02 -- Kerberos V5 1109 -- {1 2 840 113554 1 2 2} 1110 1111 If a mechlistMIC needs to be generated (according to the rules in 1112 Section 5), it is computed by using the DER encoding of the type 1113 MechTypeList data from the initiator's NegTokenInit token as input to 1114 the GSS_GetMIC() function. In this case, the MIC would be computed 1115 over the following octets: 1116 1117 DER encoding of MechTypeList: 1118 30 nn 06 09 2A 86 48 86 F7 12 01 02 02 ... 1119 1120 1121 1122Zhu, et al. Standards Track [Page 20] 1123 1124RFC 4178 The GSS-API Negotiation Mechanism October 2005 1125 1126 1127 Note that the identifier octet and length octet(s) for constructed 1128 [0] (A0 nn) are not included in the MIC computation. 1129 1130Authors' Addresses 1131 1132 Larry Zhu 1133 Microsoft Corporation 1134 One Microsoft Way 1135 Redmond, WA 98052 1136 US 1137 1138 EMail: lzhu@microsoft.com 1139 1140 1141 Paul Leach 1142 Microsoft Corporation 1143 One Microsoft Way 1144 Redmond, WA 98052 1145 US 1146 1147 EMail: paulle@microsoft.com 1148 1149 1150 Karthik Jaganathan 1151 Microsoft Corporation 1152 One Microsoft Way 1153 Redmond, WA 98052 1154 US 1155 1156 EMail: karthikj@microsoft.com 1157 1158 1159 Wyllys Ingersoll 1160 Sun Microsystems 1161 1775 Wiehle Avenue, 2nd Floor 1162 Reston, VA 20190 1163 US 1164 1165 EMail: wyllys.ingersoll@sun.com 1166 1167 1168 1169 1170 1171 1172 1173 1174 1175 1176 1177 1178Zhu, et al. Standards Track [Page 21] 1179 1180RFC 4178 The GSS-API Negotiation Mechanism October 2005 1181 1182 1183Full Copyright Statement 1184 1185 Copyright (C) The Internet Society (2005). 1186 1187 This document is subject to the rights, licenses and restrictions 1188 contained in BCP 78, and except as set forth therein, the authors 1189 retain all their rights. 1190 1191 This document and the information contained herein are provided on an 1192 "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS 1193 OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET 1194 ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, 1195 INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE 1196 INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED 1197 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 1198 1199Intellectual Property 1200 1201 The IETF takes no position regarding the validity or scope of any 1202 Intellectual Property Rights or other rights that might be claimed to 1203 pertain to the implementation or use of the technology described in 1204 this document or the extent to which any license under such rights 1205 might or might not be available; nor does it represent that it has 1206 made any independent effort to identify any such rights. Information 1207 on the procedures with respect to rights in RFC documents can be 1208 found in BCP 78 and BCP 79. 1209 1210 Copies of IPR disclosures made to the IETF Secretariat and any 1211 assurances of licenses to be made available, or the result of an 1212 attempt made to obtain a general license or permission for the use of 1213 such proprietary rights by implementers or users of this 1214 specification can be obtained from the IETF on-line IPR repository at 1215 http://www.ietf.org/ipr. 1216 1217 The IETF invites any interested party to bring to its attention any 1218 copyrights, patents or patent applications, or other proprietary 1219 rights that may cover technology that may be required to implement 1220 this standard. Please address the information to the IETF at ietf- 1221 ipr@ietf.org. 1222 1223Acknowledgement 1224 1225 Funding for the RFC Editor function is currently provided by the 1226 Internet Society. 1227 1228 1229 1230 1231 1232 1233 1234Zhu, et al. Standards Track [Page 22] 1235 1236