third_party/heimdal/doc/standardisation/rfc4178.txt

   1
   2
   3
   4
   5
   6
   7 Network Working Group                                             L. Zhu
   8 Request for Comments: 4178                                      P. Leach
   9 Obsoletes: 2478                                            K. Jaganathan
  10 Category: 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
  20 Status 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
  28 Copyright Notice
  29
  30    Copyright (C) The Internet Society (2005).
  31
  32
  33 Abstract
  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
  58 Zhu, et al.                 Standards Track                     [Page 1]
  59 \f
  60 RFC 4178           The GSS-API Negotiation Mechanism        October 2005
  61
  62
  63 Table 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
  89 1.  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
 114 Zhu, et al.                 Standards Track                     [Page 2]
 115 \f
 116 RFC 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
 150 2.  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
 156 3.  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
 170 Zhu, et al.                 Standards Track                     [Page 3]
 171 \f
 172 RFC 4178           The GSS-API Negotiation Mechanism        October 2005
 173
 174
 175    This section describes the negotiation process of this protocol.
 176
 177 3.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
 226 Zhu, et al.                 Standards Track                     [Page 4]
 227 \f
 228 RFC 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
 249 3.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
 282 Zhu, et al.                 Standards Track                     [Page 5]
 283 \f
 284 RFC 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
 338 Zhu, et al.                 Standards Track                     [Page 6]
 339 \f
 340 RFC 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
 348 4.  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
 368 4.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
 379 4.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
 394 Zhu, et al.                 Standards Track                     [Page 7]
 395 \f
 396 RFC 4178           The GSS-API Negotiation Mechanism        October 2005
 397
 398
 399       NegotiationToken ::= CHOICE {
 400           negTokenInit    [0] NegTokenInit,
 401           negTokenResp    [1] NegTokenResp
 402       }
 403
 404 4.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
 450 Zhu, et al.                 Standards Track                     [Page 8]
 451 \f
 452 RFC 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
 468 4.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
 506 Zhu, et al.                 Standards Track                     [Page 9]
 507 \f
 508 RFC 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
 545 5.  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
 562 Zhu, et al.                 Standards Track                    [Page 10]
 563 \f
 564 RFC 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
 618 Zhu, et al.                 Standards Track                    [Page 11]
 619 \f
 620 RFC 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
 674 Zhu, et al.                 Standards Track                    [Page 12]
 675 \f
 676 RFC 4178           The GSS-API Negotiation Mechanism        October 2005
 677
 678
 679 6.  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
 704 7.  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
 730 Zhu, et al.                 Standards Track                    [Page 13]
 731 \f
 732 RFC 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
 755 8.  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
 769 9.  References
 770
 771 9.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
 786 Zhu, et al.                 Standards Track                    [Page 14]
 787 \f
 788 RFC 4178           The GSS-API Negotiation Mechanism        October 2005
 789
 790
 791 9.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
 842 Zhu, et al.                 Standards Track                    [Page 15]
 843 \f
 844 RFC 4178           The GSS-API Negotiation Mechanism        October 2005
 845
 846
 847 Appendix 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
 898 Zhu, et al.                 Standards Track                    [Page 16]
 899 \f
 900 RFC 4178           The GSS-API Negotiation Mechanism        October 2005
 901
 902
 903        confFlag        (5),
 904        integFlag       (6)
 905    } (SIZE (32))
 906
 907    END
 908
 909 Appendix 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
 924 B.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
 954 Zhu, et al.                 Standards Track                    [Page 17]
 955 \f
 956 RFC 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
 963 B.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
 996 Appendix 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
1010 Zhu, et al.                 Standards Track                    [Page 18]
1011 \f
1012 RFC 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
1066 Zhu, et al.                 Standards Track                    [Page 19]
1067 \f
1068 RFC 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
1082 Appendix 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
1122 Zhu, et al.                 Standards Track                    [Page 20]
1123 \f
1124 RFC 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
1130 Authors' 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
1178 Zhu, et al.                 Standards Track                    [Page 21]
1179 \f
1180 RFC 4178           The GSS-API Negotiation Mechanism        October 2005
1181
1182
1183 Full 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
1199 Intellectual 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
1223 Acknowledgement
1224
1225    Funding for the RFC Editor function is currently provided by the
1226    Internet Society.
1227
1228
1229
1230
1231
1232
1233
1234 Zhu, et al.                 Standards Track                    [Page 22]
1235 \f