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