1PPP Support for Microsoft's CHAP-80
2===================================
3
4Eric Rosenquist          rosenqui@strataware.com
5(updated by Paul Mackerras)
6(updated by Al Longyear)
7(updated by Farrell Woods)
8(updated by Frank Cusack)
9
10INTRODUCTION
11
12Microsoft has introduced an extension to the Challenge/Handshake
13Authentication Protocol (CHAP) which avoids storing cleartext
14passwords on a server.  (Unfortunately, this is not as secure as it
15sounds, because the encrypted password stored on a server can be used
16by a bogus client to gain access to the server just as easily as if
17the password were stored in cleartext.)  The details of the Microsoft
18extensions can be found in the document:
19
20    <http://www.ietf.org/rfc/rfc2433.txt>
21
22In short, MS-CHAP is identified as <auth chap 80> since the hex value
23of 80 is used to designate Microsoft's scheme.  Standard PPP CHAP uses
24a value of 5.  If you enable PPP debugging with the "debug" option and
25see something like the following in your logs, the remote server is
26requesting MS-CHAP:
27
28  rcvd [LCP ConfReq id=0x2 <asyncmap 0x0> <auth MS> <magic 0x46a3>]
29                                           ^^^^^^^
30
31MS-CHAP support in pppd (along with MPPE support) can be enabled or
32disabled at configure time using the --enable-microsoft-extensions and
33--disable-microsoft-extensions arguments.  The default is enabled.
34
35
36CONFIGURATION
37
38If you've never used PPPD with CHAP before, read the man page (type
39"man pppd") and read the description in there.  Basically, you need to
40edit the "chap-secrets" file typically named /etc/ppp/chap-secrets.
41This should contain the following two lines for each system with which
42you use CHAP (with no leading blanks):
43
44    RemoteHost  Account     Secret
45    Account     RemoteHost  Secret
46
47Note that you need both lines and that item 1 and 2 are swapped in the
48second line.  I'm not sure why you need it twice, but it works and I didn't
49have time to look into it further.  The "RemoteHost" is a somewhat
50arbitrary name for the remote Windows NT system you're dialing.  It doesn't
51have to match the NT system's name, but it *does* have to match what you
52use with the "remotename" parameter.  The "Account" is the Windows NT
53account name you have been told to use when dialing, and the "Secret" is
54the password for that account.  For example, if your service provider calls
55their machine "DialupNT" and tells you your account and password are
56"customer47" and "foobar", add the following to your chap-secrets file:
57
58    DialupNT    customer47  foobar
59    customer47  DialupNT    foobar
60
61The only other thing you need to do for MS-CHAP (compared to normal CHAP)
62is to always use the "remotename" option, either on the command line or in
63your "options" file (see the pppd man page for details).  In the case of
64the above example, you would need to use the following command line:
65
66    pppd name customer47 remotename DialupNT <other options>
67
68or add:
69
70    name customer47
71    remotename DialupNT
72
73to your PPPD "options" file.
74
75The "remotename" option is required for MS-CHAP since Microsoft PPP servers
76don't send their system name in the CHAP challenge packet.
77
78
79E=691 (AUTHENTICATION_FAILURE) ERRORS WHEN YOU HAVE THE VALID SECRET (PASSWORD)
80
81If your RAS server is not the domain controller and is not a 'stand-alone'
82server then it must make a query to the domain controller for your domain.
83
84You need to specify the domain name with the user name when you attempt to
85use this type of a configuration. The domain name is specified with the
86local name in the chap-secrets file and with the option for the 'name'
87parameter.
88
89For example, the previous example would become:
90
91    DialupNT            domain\\customer47   foobar
92    domain\\customer47  DialupNT             foobar
93
94and
95
96    pppd name 'domain\\customer47' remotename DialupNT <other options>
97
98or add:
99
100    name domain\\customer47
101    remotename DialupNT
102
103when the Windows NT domain name is simply called 'domain'.
104
105
106TROUBLESHOOTING
107
108Assuming that everything else has been configured correctly for PPP and
109CHAP, the MS-CHAP-specific problems you're likely to encounter are mostly
110related to your Windows NT account and its settings.  A Microsoft server
111returns error codes in its CHAP response.  The following are extracted from
112RFC 2433:
113
114 646 ERROR_RESTRICTED_LOGON_HOURS
115 647 ERROR_ACCT_DISABLED
116 648 ERROR_PASSWD_EXPIRED
117 649 ERROR_NO_DIALIN_PERMISSION
118 691 ERROR_AUTHENTICATION_FAILURE
119 709 ERROR_CHANGING_PASSWORD
120
121You'll see these in your pppd log as a line similar to:
122
123   Remote message: E=649 R=0
124
125The "E=" is the error number from the table above, and the "R=" flag
126indicates whether the error is transient and the client should retry.  If
127you consistently get error 691, then either you're using the wrong account
128name/password, or the DES library or MD4 hashing (in md4.c) aren't working
129properly.  Verify your account name and password (use a Windows NT or
130Windows 95 system to dial-in if you have one available).  If that checks
131out, test the DES library with the "destest" program included with the DES
132library.  If DES checks out, the md4.c routines are probably failing
133(system byte ordering may be a problem) or my code is screwing up.  I've
134only got access to a Linux system, so you're on your own for anything else.
135
136Another thing that might cause problems is that some RAS servers won't
137respond at all to LCP config requests without seeing the word "CLIENT"
138from the other end.  If you see pppd sending out LCP config requests
139without getting any reply, try putting something in your chat script
140to send the word CLIENT after the modem has connected.
141
142STILL TO DO
143
144A site using only MS-CHAP to authenticate has no need to store cleartext
145passwords in the "chap-secrets" file.  A utility that spits out the ASCII
146hex MD4 hash of a given password would be nice, and would allow that hash
147to be used in chap-secrets in place of the password.  The code to do this
148could quite easily be lifted from chap_ms.c (you have to convert the
149password to Unicode before hashing it).  The chap_ms.c file would also have
150to be changed to recognize a password hash (16 binary bytes == 32 ASCII hex
151characters) and skip the hashing stage.  This would have no real security
152value as the hash is plaintext-equivalent.
153