Updating dictionary.erx based on Juniper documentation
[freeradius.git] / doc / rfc / draft-kamath-pppext-eap-mschapv2-00.txt
1
2
3
4
5
6
7 PPPEXT Working Group                                        Vivek Kamath
8 INTERNET-DRAFT                                            Ashwin Palekar
9 Category: Informational                                        Microsoft
10 <draft-kamath-pppext-eap-mschapv2-00.txt>
11 2 September 2002
12
13
14                      Microsoft EAP CHAP Extensions
15
16 This document is an Internet-Draft and is in full conformance with all
17 provisions of Section 10 of RFC 2026.
18
19 Internet-Drafts are working documents of the Internet Engineering Task
20 Force (IETF), its areas, and its working groups.  Note that other groups
21 may also distribute working documents as Internet- Drafts.
22
23 Internet-Drafts are draft documents valid for a maximum of six months
24 and may be updated, replaced, or obsoleted by other documents at any
25 time.  It is inappropriate to use Internet-Drafts as reference material
26 or to cite them other than as "work in progress."
27
28 The list of current Internet-Drafts can be accessed at
29 http://www.ietf.org/ietf/1id-abstracts.txt
30
31 The list of Internet-Draft Shadow Directories can be accessed at
32 http://www.ietf.org/shadow.html.
33
34 Copyright Notice
35
36 Copyright (C) The Internet Society (2002).  All Rights Reserved.
37
38 Abstract
39
40 This document defines the Microsoft EAP CHAP Extensions Protocol,
41 Version 2, which encapsulates the MS-CHAP-v2 protocol, defined in
42 [RFC2759], within EAP.
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58 Kamath & Palekar              Informational                     [Page 1]
59
60
61
62
63
64 INTERNET-DRAFT                EAP MS-CHAPv2             2 September 2002
65
66
67 Table of Contents
68
69 1.     Introduction ..........................................    3
70    1.1       Requirements language ...........................    3
71    1.2       Terminology .....................................    3
72 2.     EAP MS-CHAP-v2 Packet Format ..........................    4
73    2.1.      Challenge packet ................................    5
74    2.2.      Response packet .................................    7
75    2.3.      Success Request packet ..........................    9
76    2.4.      Success Response packet .........................   11
77    2.5.      Failure Request packet ..........................   12
78    2.6.      Failure Response packet .........................   14
79    2.7.      Change-Password packet ..........................   15
80    2.8.      Alternative failure behavior ....................   17
81    2.9.      Known bugs ......................................   17
82 3.  Normative references .....................................   18
83 4.  Informative references ...................................   19
84 Appendix A - Examples ........................................   20
85 Acknowledgments ..............................................   23
86 Author Addresses .............................................   23
87 Full copyright statement .....................................   23
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118 Kamath & Palekar              Informational                     [Page 2]
119
120
121
122
123
124 INTERNET-DRAFT                EAP MS-CHAPv2             2 September 2002
125
126
127 1.  Introduction
128
129 The Extensible Authentication Protocol (EAP), described in [RFC2284],
130 provides a standard mechanism for support of multiple authentication
131 methods.  Through the use of EAP, support for a number of authentication
132 schemes may be added, including smart cards, Kerberos, Public Key, One
133 Time Passwords, and others.
134
135 This document defines the Microsoft EAP CHAP Extensions Protocol,
136 Version 2, which encapsulates the MS-CHAP-v2 protocol, defined in
137 [RFC2759], within EAP.  As with MS-CHAP-v2,  EAP-MSCHAPv2 supports
138 mutual authentication and key derivation.  The way EAP-MSCHAPv2 derived
139 keys are used with the Microsoft Point to Point Encryption (MPPE) cipher
140 is described in [RFC3079].
141
142 EAP MS-CHAP-V2 provides mutual authentication between peers by
143 piggybacking a peer challenge on the Response packet and an
144 authenticator response on the Success packet.
145
146 1.1.  Requirements language
147
148 In this document, several words are used to signify the requirements of
149 the specification.  These words are often capitalized.  The key words
150 "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD
151 NOT", "RECOMMENDED",  "MAY", and "OPTIONAL" in this document are to be
152 interpreted as described in [RFC2119].
153
154 1.2.  Terminology
155
156 This document frequently uses the following terms:
157
158 Authenticator
159      The end of the link requiring the authentication.
160
161 Peer The other end of the point-to-point link; the end which is being
162      authenticated by the authenticator.
163
164 silently discard
165      This means the implementation discards the packet without further
166      processing.  The implementation SHOULD provide the capability of
167      logging the error, including the contents of the silently discarded
168      packet, and SHOULD record the event in a statistics counter.
169
170
171
172
173
174
175
176
177
178 Kamath & Palekar              Informational                     [Page 3]
179
180
181
182
183
184 INTERNET-DRAFT                EAP MS-CHAPv2             2 September 2002
185
186
187 2.  EAP MS-CHAP-v2 Packet Format
188
189 A summary of the EAP MS-CHAP-V2 packet format is shown below.  The
190 fields are transmitted from left to right.
191
192  0                   1                   2                   3
193  0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
194 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
195 |     Code      |   Identifier  |            Length             |
196 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
197 |     Type      |   OpCode      |  MS-CHAPv2-ID |  MS-Length...
198 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
199 |   MS-Length   |     Data...
200 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
201
202 Code
203
204    1 - Request
205    2 - Response
206
207 Identifier
208
209    The Identifier field is one octet and aids in matching responses with
210    requests.
211
212 Length
213
214    The Length field is two octets and indicates the length of the EAP
215    packet including the Code, Identifier, Length, Type, OpCode, MS-
216    CHAPv2-ID, MS-Length and Data fields.  Octets outside the range of
217    the Length field should be treated as Data Link Layer padding and
218    should be ignored on reception.
219
220 Type
221
222    26 - EAP MS-CHAP-V2
223
224 OpCode
225
226    The OpCode field is one octet and identifies the type of EAP MS-CHAP-
227    v2 packet.  OpCodes are assigned as follows:
228
229    1       Challenge
230    2       Response
231    3       Success
232    4       Failure
233    7       Change-Password
234
235
236
237
238 Kamath & Palekar              Informational                     [Page 4]
239
240
241
242
243
244 INTERNET-DRAFT                EAP MS-CHAPv2             2 September 2002
245
246
247 MS-CHAPv2-ID
248
249    The MS-CHAPv2-ID field is one octet and aids in matching MSCHAP-v2
250    responses with requests. Typically, the MS-CHAPv2-ID field is the
251    same as the Identifier field.
252
253 MS-Length
254
255    The MS-Length field is two octets and MUST be set to the value of the
256    Length field minus 5.
257
258 Data
259
260    The format of the Data field is determined by the OpCode field.
261
262 2.1.  Challenge packet
263
264 The Challenge packet is used to begin the EAP MS-CHAP-V2 protocol.  The
265 authenticator MUST transmit an EAP Request packet with Type=26, and the
266 OpCode field set to 1 (Challenge).  The format of the EAP MS-CHAP-v2
267 Challenge packet is shown below.  The fields are transmitted from left
268 to right.
269
270  0                   1                   2                   3
271  0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
272 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
273 |     Code      |   Identifier  |            Length             |
274 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
275 |     Type      |   OpCode      |  MS-CHAPv2-ID |  MS-Length...
276 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
277 |   MS-Length   |  Value-Size   |  Challenge...
278 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
279 |                             Challenge...
280 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
281 |                             Name...
282 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
283
284 Code
285
286    1 - Request
287
288 Identifier
289
290    The Identifier field is one octet.  The Identifier field MUST be the
291    same if a Request packet is retransmitted due to a timeout while
292    waiting for a Response.  Any new (non-retransmission) Requests MUST
293    modify the Identifier field.  If a peer receives a duplicate Request
294    for which it has already sent a Response, it MUST resend it's
295
296
297
298 Kamath & Palekar              Informational                     [Page 5]
299
300
301
302
303
304 INTERNET-DRAFT                EAP MS-CHAPv2             2 September 2002
305
306
307    Response.  If a peer receives a duplicate Request before it has sent
308    a Response to the initial Request (i.e. it's waiting for user input),
309    it MUST silently discard the duplicate Request.
310
311 Length
312
313    The Length field is two octets and indicates the length of the EAP
314    packet including the Code, Identifier, Length, Type, OpCode, MS-
315    CHAPv2-ID, MS-Length, Value-Size, Challenge, and Name fields.  Octets
316    outside the range of the Length field should be treated as Data Link
317    Layer padding and should be ignored on reception.
318
319 Type
320
321    26 - EAP MS-CHAP-V2
322
323 OpCode
324
325    1 - Challenge
326
327 MS-CHAPv2-ID
328
329    The MS-CHAPv2-ID field is one octet and aids in matching MSCHAP-v2
330    responses with requests. Typically, the MS-CHAPv2-ID field is the
331    same as the Identifier field.
332
333 MS-Length
334
335    The MS-Length field is two octets and MUST be set to the value of the
336    Length field minus 5.
337
338 Value-Size
339
340    This field is one octet and indicates the length of the Challenge
341    field.  Since EAP MS-CHAPv2 utilizes a 16 octet Challenge field, it
342    is set to 0x10 (16 decimal).
343
344 Challenge
345
346    The Challenge field is 16 octets.  The most significant octet is
347    transmitted first.  The Challenge MUST be changed each time a
348    Challenge is sent.
349
350 Name
351
352    The Name field is one or more octets representing the identification
353    of the system transmitting the packet.  There are no limitations on
354    the content of this field.  The Name should not be NUL or CR/LF
355
356
357
358 Kamath & Palekar              Informational                     [Page 6]
359
360
361
362
363
364 INTERNET-DRAFT                EAP MS-CHAPv2             2 September 2002
365
366
367    terminated.  The size of the Name field is equal to Length - Value-
368    Size - 10.
369
370 2.2.  Response packet
371
372 The format of the EAP MS-CHAP-v2 Response packet is shown below.  The
373 fields are transmitted from left to right.
374
375  0                   1                   2                   3
376  0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
377 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
378 |     Code      |   Identifier  |            Length             |
379 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
380 |     Type      |   OpCode      |  MS-CHAPv2-ID |  MS-Length...
381 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
382 |   MS-Length   |  Value-Size   |    Response...
383 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
384 |                             Response...
385 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
386 |                             Name...
387 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
388
389 Code
390
391    2 - Response
392
393 Identifier
394
395    The Identifier field is one octet and contains the value included in
396    the EAP Request to which it responds.
397
398 Length
399
400    The Length field is two octets and indicates the length of the EAP
401    packet including the Code, Identifier, Length, Type, OpCode, MS-
402    CHAPv2-ID, MS-Length, Value-Size, Response, and Name fields.  Octets
403    outside the range of the Length field should be treated as Data Link
404    Layer padding and should be ignored on reception.
405
406 Type
407
408    26 - EAP MS-CHAP-V2
409
410 OpCode
411
412    2 - Response
413
414
415
416
417
418 Kamath & Palekar              Informational                     [Page 7]
419
420
421
422
423
424 INTERNET-DRAFT                EAP MS-CHAPv2             2 September 2002
425
426
427 MS-CHAPv2-ID
428
429    The MS-CHAPv2-ID field is one octet and aids in matching MSCHAP-v2
430    responses with requests. Typically, the MS-CHAPv2-ID field is the
431    same as the Identifier field.
432
433 MS-Length
434
435    The MS-Length field is two octets and MUST be set to the value of the
436    Length field minus 5.
437
438 Value-Size
439
440    This field is one octet and indicates the length of the Response
441    field.  It is set to 0x31 (Decimal 49).
442
443 Response
444
445    The Response field is 49 octets.  The most significant octet is
446    transmitted first.  It is sub-formatted as follows:
447
448                   16 octets: Peer-Challenge
449                   8 octets: Reserved, must be zero
450                   24 octets: NT-Response
451                   1 octet : Flags
452
453    The Peer-Challenge field is a 16-octet random number.  As the name
454    implies, it is generated by the peer and is used in the calculation
455    of the NT-Response field, below.  Peers need not duplicate
456    Microsoft's algorithm for selecting the 16-octet value, but the
457    standard guidelines on randomness [RFC1750] SHOULD be observed.
458
459    The NT-Response field is an encoded function of the password, the
460    Name field of the Response packet, the contents of the Peer-Challenge
461    field and the received Challenge as output by the routine
462    GenerateNTResponse() defined in  [RFC2759], Section 8.1.
463
464    The Windows NT password is a string of 0 to (theoretically) 256 case-
465    sensitive Unicode [UNICODE] characters.  Current versions of Windows
466    NT limit passwords to 14 characters, mainly for compatibility
467    reasons; this may change in the future.  When computing the NT-
468    Response field contents, only the user name is used, without any
469    associated Windows NT domain name.  This is true regardless of
470    whether a Windows NT domain name is present in the Name field (see
471    below).
472
473    The Flag field is reserved for future use and MUST be zero.
474
475
476
477
478 Kamath & Palekar              Informational                     [Page 8]
479
480
481
482
483
484 INTERNET-DRAFT                EAP MS-CHAPv2             2 September 2002
485
486
487    Whenever a Response packet is received, the authenticator compares
488    the Response Value with its own calculation of the expected value. If
489    the values match, then the authenticator MUST send a Success-Request
490    packet, as described in Section 2.3.  If the values do not match, and
491    if the error is retryable, then a Failure-Request packet MUST be sent
492    as described in Section 2.5. If the values do not match, and the
493    error is not retryable, then  a Failure-Request packet (described in
494    Section 2.5) SHOULD be sent, or alternatively, the authentication MAY
495    be  terminated (as described in Section 2.8) such as by sending an
496    EAP Failure.
497
498 Name
499
500    The Name field is a string of 0 to (theoretically) 256 case-sensitive
501    ASCII characters which identifies the peer's user account name.  The
502    Windows NT domain name may prefix the user's account name (e.g.
503    BIGCO\johndoe where BIGCO is a Windows NT domain containing the user
504    account johndoe).  If a domain is not provided, the backslash should
505    also be omitted, (e.g. johndoe).  The Name SHOULD NOT be NUL or CR/LF
506    terminated.  The size of the Name field is determined from the Length
507    - Value-Size - 10.
508
509 2.3.  Success Request packet
510
511 If the value received in the Response field of the EAP MS-CHAP-V2
512 Response packet is equal to the expected value, then the implementation
513 MUST transmit an EAP MS-CHAP-V2 Request packet with the OpCode field set
514 to 3 (Success).
515
516 The format of the EAP MS-CHAP-v2 Success Request packet is shown below.
517 The fields are transmitted from left to right.
518
519  0                   1                   2                   3
520  0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
521 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
522 |     Code      |   Identifier  |            Length             |
523 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
524 |     Type      |   OpCode      |  MS-CHAPv2-ID |  MS-Length...
525 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
526 |   MS-Length   |                    Message...
527 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
528
529 Code
530
531    1 - Request
532
533
534
535
536
537
538 Kamath & Palekar              Informational                     [Page 9]
539
540
541
542
543
544 INTERNET-DRAFT                EAP MS-CHAPv2             2 September 2002
545
546
547 Identifier
548
549    The Identifier field is one octet.  The Identifier field MUST be the
550    same if a Request packet is retransmitted due to a timeout while
551    waiting for a Response.  Any new (non-retransmission) Requests MUST
552    modify the Identifier field.  If a peer receives a duplicate Request
553    for which it has already sent a Response, it MUST resend it's
554    Response.  If a peer receives a duplicate Request before it has sent
555    a Response to the initial Request (i.e. it's waiting for user input),
556    it MUST silently discard the duplicate Request.
557
558 Length
559
560    The Length field is two octets and indicates the length of the EAP
561    packet including the Code, Identifier, Length, Type, OpCode, MS-
562    CHAPv2-ID, MS-Length, and Message fields.  Octets outside the range
563    of the Length field should be treated as Data Link Layer padding and
564    should be ignored on reception.
565
566 Type
567
568    26 - EAP MS-CHAP-V2
569
570 OpCode
571
572    3 - Success
573
574 MS-CHAPv2-ID
575
576    The MS-CHAPv2-ID field is one octet and aids in matching MSCHAP-v2
577    responses with requests.  Typically, the MS-CHAPv2-ID field is the
578    same as the Identifier field.
579
580 MS-Length
581
582    The MS-Length field is two octets and MUST be set to the value of the
583    Length field minus 5.
584
585 Message
586
587    The Message field contains a 42-octet authenticator response string
588    and a printable message.  The format of the message field is
589    illustrated below.
590
591       "S=<auth_string> M=<message>"
592
593    The <auth_string> quantity is a 20 octet number encoded in ASCII as
594    40 hexadecimal digits.  The hexadecimal digits A-F (if present) MUST
595
596
597
598 Kamath & Palekar              Informational                    [Page 10]
599
600
601
602
603
604 INTERNET-DRAFT                EAP MS-CHAPv2             2 September 2002
605
606
607    be uppercase.  This number is derived from the challenge from the
608    Challenge packet, the Peer-Challenge and NT-Response fields from the
609    Response packet, and the peer password as output by the routine
610    GenerateAuthenticatorResponse() defined in [RFC2759], Section 8.7.
611    The authenticating peer MUST verify the authenticator response when a
612    Success packet is received.  The method for verifying the
613    authenticator is described in [RFC2759], section 8.8.  If the
614    authenticator response is either missing or incorrect, the peer MUST
615    end the session without sending a response.
616
617    The <message> quantity is human-readable text in the appropriate
618    charset and language [RFC2484].
619
620 2.4.  Success Response packet
621
622 In the peer successfully validates the EAP MS-CHAP-V2 Success Request
623 packet sent by the authenticator, then it MUST respond with an EAP MS-
624 CHAP-V2 Success Response packet with the OpCode field set to 3
625 (Success).
626
627 The format of the EAP MS-CHAP-v2 Success Response packet is shown below.
628 The fields are transmitted from left to right.
629
630  0                   1                   2                   3
631  0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
632 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
633 |     Code      |   Identifier  |            Length             |
634 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
635 |     Type      |   OpCode      |
636 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
637
638 Code
639
640    2 - Response
641
642 Identifier
643
644    The Identifier field is one octet and contains the value included in
645    the EAP Request to which it responds.
646
647 Length
648
649    6
650
651
652
653
654
655
656
657
658 Kamath & Palekar              Informational                    [Page 11]
659
660
661
662
663
664 INTERNET-DRAFT                EAP MS-CHAPv2             2 September 2002
665
666
667 Type
668
669    26 - EAP MS-CHAP-V2
670
671 OpCode
672
673    3 - Success
674
675 2.5.  Failure Request packet
676
677 If the Value received in a Response is not equal to the expected value,
678 and the error is retryable, then  the implementation MUST transmit an
679 EAP MS-CHAP-v2 Request packet with the OpCode field set to 4 (Failure).
680 If the error is not retryable, then the implementation SHOULD transmit
681 an EAP MS-CHAP-v2 Failure Request packet, or it MAY terminate the
682 authentication (e.g. send an EAP Failure packet). The former approach is
683 preferable, since this enables the cause of the error to be
684 communicated.
685
686 The format of the EAP MS-CHAP-v2 Failure Request packet is shown below.
687 The fields are transmitted from left to right.
688
689  0                   1                   2                   3
690  0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
691 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
692 |     Code      |   Identifier  |            Length             |
693 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
694 |     Type      |   OpCode      |  MS-CHAPv2-ID |  MS-Length...
695 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
696 |   MS-Length   |                    Message...
697 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
698
699 Code
700
701    1 - Request
702
703 Identifier
704
705    The Identifier field is one octet.  The Identifier field MUST be the
706    same if a Request packet is retransmitted due to a timeout while
707    waiting for a Response.  Any new (non-retransmission) Requests MUST
708    modify the Identifier field.  If a peer receives a duplicate Request
709    for which it has already sent a Response, it MUST resend it's
710    Response.  If a peer receives a duplicate Request before it has sent
711    a Response to the initial Request (i.e. it's waiting for user input),
712    it MUST silently discard the duplicate Request.
713
714
715
716
717
718 Kamath & Palekar              Informational                    [Page 12]
719
720
721
722
723
724 INTERNET-DRAFT                EAP MS-CHAPv2             2 September 2002
725
726
727 Length
728
729    The Length field is two octets and indicates the length of the EAP
730    packet including the Code, Identifier, Length, Type, OpCode, MS-
731    CHAPv2-ID, MS-Length, and Message fields.  Octets outside the range
732    of the Length field should be treated as Data Link Layer padding and
733    should be ignored on reception.
734
735 Type
736
737    26 - EAP MS-CHAP-V2
738
739 OpCode
740
741    4 - Failure
742
743 MS-CHAPv2-ID
744
745    The MS-CHAPv2-ID field is one octet and aids in matching MSCHAP-v2
746    responses with requests. Typically, the MS-CHAPv2-ID field is the
747    same as the Identifier field.
748
749 MS-Length
750
751    The MS-Length field is two octets and MUST be set to the value of the
752    Length field minus 5.
753
754 Message
755
756    The Message field format is:
757
758      "E=eeeeeeeeee R=r C=cccccccccccccccccccccccccccccccc V=vvvvvvvvvv M=<msg>"
759
760    where
761
762    The "eeeeeeeeee" is the ASCII representation of a decimal error code
763    corresponding to one of those listed below, though implementations
764    should deal with codes not on this list gracefully. The error code
765    need not be 10 digits long.
766
767         646 ERROR_RESTRICTED_LOGON_HOURS
768         647 ERROR_ACCT_DISABLED
769         648 ERROR_PASSWD_EXPIRED
770         649 ERROR_NO_DIALIN_PERMISSION
771         691 ERROR_AUTHENTICATION_FAILURE
772         709 ERROR_CHANGING_PASSWORD
773
774    The "r" is a single character ASCII flag set to '1' if a retry is
775
776
777
778 Kamath & Palekar              Informational                    [Page 13]
779
780
781
782
783
784 INTERNET-DRAFT                EAP MS-CHAPv2             2 September 2002
785
786
787    allowed, and '0' if not.  Typically, errors 646, 647, and 649 are
788    non-retryable (R=0). When the authenticator sets this flag to '1' it
789    disables short timeouts, expecting the peer to prompt the user for
790    new credentials and resubmit the response. The
791    "cccccccccccccccccccccccccccccccc" is the ASCII representation of a
792    hexadecimal challenge value.  This field MUST be exactly 32 octets
793    long and MUST be present.
794
795    The "vvvvvvvvvv" is the ASCII representation of a decimal version
796    code (need not be 10 digits) indicating the password changing
797    protocol version supported on the server.  For EAP MS-CHAP-V2, this
798    value MUSTalways be 3.
799
800    <msg> is human-readable text in the appropriate charset and language
801    [RFC2484].
802
803 2.6.  Failure Response packet
804
805 When the peer receives a Failure Request packet that is retryable (R=1),
806 the authentication MAY be retried. For example, a new Response packet,
807 or Change Password packet MAY be sent. In these cases a Failure Response
808 packet is not sent.
809
810 However, if the EAP MS-CHAPv2 Failure Request is non-retryable (R=0),
811 then the peer SHOULD transmit an EAP MS-CHAP-v2 Response packet with the
812 OpCode field set to 4 (Failure). The format of the EAP MS-CHAP-v2
813 Failure Response packet is shown below. The fields are transmitted from
814 left to right.
815
816  0                   1                   2                   3
817  0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
818 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
819 |     Code      |   Identifier  |            Length             |
820 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
821 |     Type      |   OpCode      |
822 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
823
824 Code
825
826    2 - Response
827
828 Identifier
829
830    The Identifier field is one octet and contains the value included in
831    the EAP Request to which it responds.
832
833
834
835
836
837
838 Kamath & Palekar              Informational                    [Page 14]
839
840
841
842
843
844 INTERNET-DRAFT                EAP MS-CHAPv2             2 September 2002
845
846
847 Length
848
849    6
850
851 Type
852
853    26 - EAP MS-CHAP-V2
854
855 OpCode
856
857    4 - Failure
858
859 2.7.  Change-Password packet
860
861 The Change-Password packet does not appear in either standard CHAP or
862 MS-CHAP-V1.  It allows the peer to change the password on the account
863 specified in the preceding Response packet.  The Change-Password packet
864 should be sent only if the authenticator reports ERROR_PASSWD_EXPIRED
865 (E=648) in the Message field of the Failure packet.
866
867 The format of the EAP MS-CHAP-v2 Change Password packet is shown below.
868 The fields are transmitted from left to right.
869
870  0                   1                   2                   3
871  0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
872 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
873 |     Code      |   Identifier  |            Length             |
874 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
875 |     Type      |   OpCode      |  MS-CHAPv2-ID |  MS-Length...
876 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
877 |   MS-Length   |                    Data...
878 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
879
880 Code
881
882    2 - Response
883
884 Identifier
885
886    The Identifier field is one octet and aids in matching responses with
887    requests.  The value is the Identifier of the received Failure packet
888    to which this packet responds.
889
890 Length
891
892    The Length field is two octets and indicates the length of the EAP
893    packet including the Code, Identifier, Length, Type, OpCode, MS-
894    CHAPv2-ID, MS-Length and Data  fields.  Octets outside the range of
895
896
897
898 Kamath & Palekar              Informational                    [Page 15]
899
900
901
902
903
904 INTERNET-DRAFT                EAP MS-CHAPv2             2 September 2002
905
906
907    the Length field should be treated as Data Link Layer padding and
908    should be ignored on reception. For the Change Password packet, the
909    length = 591.
910
911 Type
912
913    26 - EAP MS-CHAP-V2
914
915 OpCode
916
917    7 - Change Password
918
919 MS-CHAPv2-ID
920
921    The MS-CHAPv2-ID field is one octet and aids in matching MSCHAP-v2
922    responses with requests.  Typically, the MS-CHAPv2-ID field is the
923    same as the Identifier field.
924
925 MS-Length
926
927    The MS-Length field is two octets and MUST be set to the value of the
928    Length field minus 5.
929
930 Data
931
932    The Data field is 582 octets in length, and is subdivided as follows:
933
934         516 octets : Encrypted-Password
935          16 octets : Encrypted-Hash
936          16 octets : Peer-Challenge
937           8 octets : Reserved
938          24 octets : NT-Response
939           2-octet  : Flags
940
941 Encrypted-Password
942
943    The Encrypted-Password field is 516 octets in length, and contains
944    the PWBLOCK form of the new Windows NT password encrypted with the
945    old Windows NT password hash, as output by the
946    NewPasswordEncryptedWithOldNtPasswordHash() routine defined in
947    [RFC2759], Section 8.9.
948
949 Encrypted-Hash
950
951    The Encrypted-Hash field is 16 octets in length and contains the old
952    Windows NT password hash encrypted with the new Windows NT password
953    hash, as output by the
954    OldNtPasswordHashEncryptedWithNewNtPasswordHash() routine, defined in
955
956
957
958 Kamath & Palekar              Informational                    [Page 16]
959
960
961
962
963
964 INTERNET-DRAFT                EAP MS-CHAPv2             2 September 2002
965
966
967    [RFC2759], Section 8.12.
968
969 Peer-Challenge
970
971    The Peer-Challenge field is 16 octets in length, and contains a
972    16-octet random quantity, as described in the Response packet
973    description.
974
975 Reserved
976
977    8 octets, must be zero.
978
979 NT-Response
980
981    The NT-Response field is 24 octets in length and is as described in
982    the Response packet description. However it is calculated on the new
983    password and the challenge received in the Failure packet.
984
985 Flags
986
987    The Flags field is two octets in length.  It is a bit field of option
988    flags where 0 is the least significant bit of the 16-bit quantity.
989    The format of this field is illustrated in the following diagram:
990
991                   1
992         5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0
993        +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
994        |                               |
995        +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
996
997        Bits 0-15
998        Reserved, always clear (0).
999
1000 2.8.  Alternative failure behavior
1001
1002 Rather than sending a Failure Request as described in Section 2.5, if
1003 the error is non-retryable (e.g. R=0), or if the maximum number of
1004 retries has been exhausted, then the Authenticator MAY terminate the
1005 authentication conversation. Where EAP MS-CHAP-V2 is running standalone
1006 (e.g. without PEAP), this will result in transmission of an EAP Failure
1007 message to the authenticator. Since EAP Failure packets do not carry
1008 additional data, no error message may be transmitted to the peer.
1009
1010 2.9.  Known bugs
1011
1012 In Windows XP SP1, Failure Request packets are only sent where the error
1013 is retryable (R=1). Rather than sending a Failure Request with a non-
1014 retryable error (R=0), a Windows XP SP1 authenticator will terminate
1015
1016
1017
1018 Kamath & Palekar              Informational                    [Page 17]
1019
1020
1021
1022
1023
1024 INTERNET-DRAFT                EAP MS-CHAPv2             2 September 2002
1025
1026
1027 authentication.  This is undesirable, because it prevents non-retryable
1028 error messages from being received by the peer. A Windows XP SP1 host,
1029 on receiving a Failure Request packet with a non-retryable error (R=0),
1030 will silently discard the packet.
1031
1032 Since a Windows XP SP1 peer will respond to a retryable (R=1) Failure
1033 Request by retrying authentication (such as by sending a Response or
1034 Change-Password packet), and non-retryable (R=0) Failure Requests are
1035 silently discarded, Windows XP SP1 peers do not send Failure Response
1036 packets. If a Windows XP SP1 authenticator receives a Failure Response
1037 packet, it will be silently discarded.
1038
1039 3.  Normative references
1040
1041 [RFC1320] Rivest, R., "MD4 Message Digest Algorithm", RFC 1320, April
1042           1992.
1043
1044 [RFC1994] Simpson, W., "PPP Challenge Handshake Authentication Protocol
1045           (CHAP)", RFC 1994, August 1996.
1046
1047 [RFC1750] Eastlake, D., Crocker, S. and J. Schiller, "Randomness
1048           Recommendations for Security", RFC 1750, December 1994.
1049
1050 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
1051           Requirement Levels", BCP 14, RFC 2119, March 1997.
1052
1053 [RFC2284] Blunk, L., Vollbrecht, J., "PPP Extensible Authentication
1054           Protocol (EAP)", RFC 2284, March 1998.
1055
1056 [RFC2433] Zorn, G. and Cobb, S., "Microsoft PPP CHAP Extensions", RFC
1057           2433, October 1998.
1058
1059 [RFC2484] Zorn, G., "PPP LCP Internationalization Configuration Option",
1060           RFC 2484, January 1999.
1061
1062 [RFC2759] Zorn, G., "Microsoft PPP CHAP Extensions, Version 2", RFC
1063           2759, January 2000.
1064
1065 [RC4]     RC4 is a proprietary encryption algorithm available under
1066           license from RSA Data Security Inc.  For licensing
1067           information, contact:
1068                             RSA Data Security, Inc.
1069                             100 Marine Parkway
1070                             Redwood City, CA 94065-1031
1071
1072 [IEEE8021X]
1073           IEEE Standards for Local and Metropolitan Area Networks: Port
1074           Based Network Access Control, IEEE Std 802.1X-2001, June 2001.
1075
1076
1077
1078 Kamath & Palekar              Informational                    [Page 18]
1079
1080
1081
1082
1083
1084 INTERNET-DRAFT                EAP MS-CHAPv2             2 September 2002
1085
1086
1087 [SHA1]    "Secure Hash Standard", Federal Information Processing
1088           Standards Publication 180-1, National Institute of Standards
1089           and Technology, April 1995.
1090
1091 [UNICODE] "The Unicode Standard, Version 2.0", The Unicode Consortium,
1092           Addison-Wesley, 1996. ISBN 0-201-48345-9.
1093
1094 4.  Informative references
1095
1096 [RFC1570] Simpson, W., Editor, "PPP LCP Extensions", RFC 1570, January
1097           1994.
1098
1099 [RFC1661] Simpson, W., "The Point-to-Point Protocol (PPP)", STD 51, RFC
1100           1661, July 1994.
1101
1102 [DES]     "Data Encryption Standard (DES)", Federal Information
1103           Processing Standard Publication 46-2, National Institute of
1104           Standards and Technology, December 1993.
1105
1106 [DESMODES]
1107           "DES Modes of Operation", Federal Information Processing
1108           Standards Publication 81, National Institute of Standards and
1109           Technology, December 1980.
1110
1111 [RFC3079] Zorn, G., "Deriving Keys for use with Microsoft Point-to-Point
1112           Encryption (MPPE)", RFC 3079, March 2001.
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138 Kamath & Palekar              Informational                    [Page 19]
1139
1140
1141
1142
1143
1144 INTERNET-DRAFT                EAP MS-CHAPv2             2 September 2002
1145
1146
1147 Appendix A - Examples
1148
1149 In the case where the EAP-MS-CHAP-V2 authentication is successful, the
1150 conversation will appear as follows:
1151
1152 Peer                   Authenticator
1153 ----                   -------------
1154                        <- EAP-Request/Identity
1155 EAP-Response/
1156 Identity (MyID) ->
1157                        <- EAP-Request/
1158                           EAP-Type=EAP MS-CHAP-V2
1159                           (Challenge)
1160 EAP-Response/
1161 EAP-Type=EAP-MS-CHAP-V2
1162 (Response)->
1163                        <- EAP-Request/
1164                           EAP-Type=EAP-MS-CHAP-V2
1165                           (Success)
1166 EAP-Response/
1167 EAP-Type=EAP-MS-CHAP-V2
1168 (Success) ->
1169                        <- EAP-Success
1170
1171 In the case where the EAP MS-CHAP-V2 authentication is unsuccessful, due
1172 to a retryable error, the conversation will appear as follows (assuming
1173 a maximum of two retries):
1174
1175 Peer                   Authenticator
1176 ----                   -------------
1177                        <- EAP-Request/Identity
1178 EAP-Response/
1179 Identity (MyID) ->
1180                        <- EAP-Request/
1181                           EAP-Type=EAP MS-CHAP-V2
1182                           (Challenge)
1183 EAP-Response/
1184 EAP-Type=EAP-MS-CHAP-V2
1185 (Response)->
1186                        <- EAP-Request/
1187                           EAP-Type=EAP-MS-CHAP-V2
1188                          (Failure, R=1)
1189 EAP-Response/
1190 EAP-Type=EAP-MS-CHAP-V2
1191 (Response) ->
1192                        <- EAP-Request/
1193                           EAP-Type=EAP-MS-CHAP-V2
1194                          (Failure, R=1)
1195
1196
1197
1198 Kamath & Palekar              Informational                    [Page 20]
1199
1200
1201
1202
1203
1204 INTERNET-DRAFT                EAP MS-CHAPv2             2 September 2002
1205
1206
1207 EAP-Response/
1208 EAP-Type=EAP-MS-CHAP-V2
1209 (Response) ->
1210
1211                        <- EAP-Failure
1212
1213 In the case where the EAP MS-CHAP-V2 authentication is unsuccessful, due
1214 to a non-retryable error, the conversation will appear as follows
1215 (Windows XP SP1):
1216
1217 Peer                   Authenticator
1218 ----                   -------------
1219                        <- EAP-Request/Identity
1220 EAP-Response/
1221 Identity (MyID) ->
1222                        <- EAP-Request/
1223                           EAP-Type=EAP MS-CHAP-V2
1224                           (Challenge)
1225 EAP-Response/
1226 EAP-Type=EAP-MS-CHAP-V2
1227 (Response)->
1228                        <- EAP-Failure
1229
1230 In the case where the EAP MS-CHAP-V2 authentication is unsuccessful, due
1231 to a non-retryable error, and a Failure Request packet is sent, the
1232 conversation will appear as follows (behavior not exhibited by Windows
1233 XP SP1):
1234
1235 Peer                   Authenticator
1236 ----                   -------------
1237                        <- EAP-Request/Identity
1238 EAP-Response/
1239 Identity (MyID) ->
1240                        <- EAP-Request/
1241                           EAP-Type=EAP MS-CHAP-V2
1242                           (Challenge)
1243 EAP-Response/
1244 EAP-Type=EAP-MS-CHAP-V2
1245 (Response)->
1246                        <- EAP-Request/
1247                           EAP-Type=EAP MS-CHAP-V2
1248                           (Failure, R=0)
1249 EAP-Response/
1250 EAP-Type=EAP-MS-CHAP-V2
1251 (Failure)->
1252                        <- EAP-Failure
1253
1254 In the case where the EAP MS-CHAP-V2 authentication is initially
1255
1256
1257
1258 Kamath & Palekar              Informational                    [Page 21]
1259
1260
1261
1262
1263
1264 INTERNET-DRAFT                EAP MS-CHAPv2             2 September 2002
1265
1266
1267 unsuccessful due to password expiration, but the subsequent Change
1268 Password operation succeeds, the conversation will appear as follows:
1269
1270 Peer                   Authenticator
1271 ----                   -------------
1272                        <- EAP-Request/Identity
1273 EAP-Response/
1274 Identity (MyID) ->
1275                        <- EAP-Request/
1276                           EAP-Type=EAP MS-CHAP-V2
1277                           (Challenge)
1278 EAP-Response/
1279 EAP-Type=EAP-MS-CHAP-V2
1280 (Response)->
1281                        <- EAP-Request/
1282                           EAP-Type=MS-CHAP-V2
1283                           (Failure, R=1,
1284                            Message=ERROR_PASSWD_EXPIRED (E=648))
1285 EAP-Response/
1286 EAP-Type=EAP-MS-CHAP-V2
1287 (Change-Password) ->
1288                        <- EAP-Request/
1289                           EAP-Type=MS-CHAP-V2
1290                           (Success)
1291 EAP-Response/
1292 EAP-Type=EAP-MS-CHAP-V2
1293 (Success) ->
1294                         <- EAP-Success
1295
1296 In the case where the EAP MS-CHAP-V2 authentication is unnsuccessful due
1297 to password failure and a successful retry occurs, the conversation
1298 appears as follows:
1299
1300 Peer                   Authenticator
1301 ----                   -------------
1302                        <- EAP-Request/Identity
1303 EAP-Response/
1304 Identity (MyID) ->
1305                        <- EAP-Request/
1306                           EAP-Type=EAP MS-CHAP-V2
1307                           (Challenge)
1308 EAP-Response/
1309 EAP-Type=EAP-MS-CHAP-V2
1310 (Response)->
1311                        <- EAP-Request/
1312                           EAP-Type=MS-CHAP-V2
1313                          (Failure, R=1,
1314                           Message=ERROR_AUTHENTICATION_FAILURE (E=691)
1315
1316
1317
1318 Kamath & Palekar              Informational                    [Page 22]
1319
1320
1321
1322
1323
1324 INTERNET-DRAFT                EAP MS-CHAPv2             2 September 2002
1325
1326
1327 EAP-Response/
1328 EAP-Type=EAP-MS-CHAP-V2
1329 (Response)->
1330                        <- EAP-Request/
1331                           EAP-Type=MS-CHAP-V2
1332                           (Success)
1333 EAP-Response/
1334 EAP-Type=EAP-MS-CHAP-V2
1335 (Success) ->
1336                        <- EAP-Success
1337
1338 Acknowledgments
1339
1340 Thanks to Mark Wodrich and Narendra Gidwani of Microsoft for discussions
1341 relating to this document.
1342
1343 Authors' Addresses
1344
1345 Vivek Kamath
1346 Ashwin Palekar
1347 Microsoft Corporation
1348 One Microsoft Way
1349 Redmond, WA 98052
1350
1351 EMail: {vivek, ashwinp}@microsoft.com
1352 Phone: +1 425 882 8080
1353 Fax:   +1 425 936 7329
1354
1355 Full Copyright Statement
1356
1357 Copyright (C) The Internet Society (2002).  All Rights Reserved.
1358 This document and translations of it may be copied and furnished to
1359 others, and derivative works that comment on or otherwise explain it or
1360 assist in its implementation may be prepared, copied, published and
1361 distributed, in whole or in part, without restriction of any kind,
1362 provided that the above copyright notice and this paragraph are included
1363 on all such copies and derivative works.  However, this document itself
1364 may not be modified in any way, such as by removing the copyright notice
1365 or references to the Internet Society or other Internet organizations,
1366 except as needed for the purpose of developing Internet standards in
1367 which case the procedures for copyrights defined in the Internet
1368 Standards process must be followed, or as required to translate it into
1369 languages other than English.  The limited permissions granted above are
1370 perpetual and will not be revoked by the Internet Society or its
1371 successors or assigns.  This document and the information contained
1372 herein is provided on an "AS IS" basis and THE INTERNET SOCIETY AND THE
1373 INTERNET ENGINEERING TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR
1374 IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE
1375
1376
1377
1378 Kamath & Palekar              Informational                    [Page 23]
1379
1380
1381
1382
1383
1384 INTERNET-DRAFT                EAP MS-CHAPv2             2 September 2002
1385
1386
1387 INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED
1388 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE."
1389
1390 Expiration Date
1391
1392 This memo is filed as <draft-kamath-pppext-eap-mschapv2-00.txt>,  and
1393 expires March 19, 2003.
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438 Kamath & Palekar              Informational                    [Page 24]
1439
1440