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 chap 80> <magic 0x46a3>] 29 ^^^^^^^^^^^^ 30 31The standard pppd implementation will indicate its lack of support for 32MS-CHAP by NAKing it: 33 34 sent [LCP ConfNak id=0x2 <auth chap 05>] 35 36Windows NT Server systems are often configured to "Accept only 37Microsoft Authentication" (this is intended to enhance security). Up 38until now, that meant that you couldn't use this version of PPPD to 39connect to such a system. 40 41 42BUILDING THE PPPD 43 44MS-CHAP uses a combination of MD4 hashing and DES encryption for 45authentication. You may need to get Eric Young's libdes library in 46order to use my MS-CHAP extensions. A lot of UNIX systems already 47have DES encryption available via the crypt(3), encrypt(3) and 48setkey(3) interfaces. Some may (such as that on Digital UNIX) 49provide only the encryption mechanism and will not perform 50decryption. This is okay. We only need to encrypt to perform 51MS-CHAP authentication. 52 53If you have encrypt/setkey available, then hopefully you need only 54define these two things in your Makefile: -DUSE_CRYPT and -DCHAPMS. 55Skip the paragraphs below about obtaining and building libdes. Do 56the "make clean" and "make" as described below. Linux users 57should not need to modify their Makefiles. Instead, 58just do "make CHAPMS=1 USE_CRYPT=1". 59 60If you don't have encrypt and setkey, you will need Eric Young's 61libdes library. You can find it in: 62 63ftp://ftp.funet.fi/pub/crypt/mirrors/ftp.psy.uq.oz.au/DES/libdes-3.06.tar.gz 64 65Australian residents can get libdes from Eric Young's site: 66 67ftp://ftp.psy.uq.oz.au/pub/Crypto/DES/libdes-3.06.tar.gz 68 69It is also available on many other sites (ask Archie). 70 71I used libdes-3.06, but hopefully anything newer than that will work 72also. Get the library, build and test it on your system, and install 73it somewhere (typically /usr/local/lib and /usr/local/include). 74 75 76 77You should now be ready to (re)compile the PPPD. Go to the pppd 78subdirectory and make sure the Makefile contains "-DCHAPMS" in the 79CFLAGS or COMPILE_FLAGS macro, and that the LIBS macro (or LDADD for 80BSD systems) contains "-ldes". Depending on your system and where the 81DES library was installed, you may also need to alter the include and 82library paths used by your compiler. 83 84Do a "make clean" and then a "make" to rebuild pppd. Assuming all 85goes well, install the new pppd and move on to the CONFIGURATION 86section. 87 88 89CONFIGURATION 90 91If you've never used PPPD with CHAP before, read the man page (type 92"man pppd") and read the description in there. Basically, you need to 93edit the "chap-secrets" file typically named /etc/ppp/chap-secrets. 94This should contain the following two lines for each system with which 95you use CHAP (with no leading blanks): 96 97 RemoteHost Account Secret 98 Account RemoteHost Secret 99 100Note that you need both lines and that item 1 and 2 are swapped in the 101second line. I'm not sure why you need it twice, but it works and I didn't 102have time to look into it further. The "RemoteHost" is a somewhat 103arbitrary name for the remote Windows NT system you're dialing. It doesn't 104have to match the NT system's name, but it *does* have to match what you 105use with the "remotename" parameter. The "Account" is the Windows NT 106account name you have been told to use when dialing, and the "Secret" is 107the password for that account. For example, if your service provider calls 108their machine "DialupNT" and tells you your account and password are 109"customer47" and "foobar", add the following to your chap-secrets file: 110 111 DialupNT customer47 foobar 112 customer47 DialupNT foobar 113 114The only other thing you need to do for MS-CHAP (compared to normal CHAP) 115is to always use the "remotename" option, either on the command line or in 116your "options" file (see the pppd man page for details). In the case of 117the above example, you would need to use the following command line: 118 119 pppd name customer47 remotename DialupNT <other options> 120 121or add: 122 123 name customer47 124 remotename DialupNT 125 126to your PPPD "options" file. 127 128The "remotename" option is required for MS-CHAP since Microsoft PPP servers 129don't send their system name in the CHAP challenge packet. 130 131 132E=691 (AUTHENTICATION_FAILURE) ERRORS WHEN YOU HAVE THE VALID SECRET (PASSWORD) 133 134If your RAS server is not the domain controller and is not a 'stand-alone' 135server then it must make a query to the domain controller for your domain. 136 137You need to specify the domain name with the user name when you attempt to 138use this type of a configuration. The domain name is specified with the 139local name in the chap-secrets file and with the option for the 'name' 140parameter. 141 142For example, the previous example would become: 143 144 DialupNT domain\\customer47 foobar 145 domain\\customer47 DialupNT foobar 146 147and 148 149 pppd name 'domain\\customer47' remotename DialupNT <other options> 150 151or add: 152 153 name domain\\customer47 154 remotename DialupNT 155 156when the Windows NT domain name is simply called 'domain'. 157 158 159TROUBLESHOOTING 160 161Assuming that everything else has been configured correctly for PPP and 162CHAP, the MS-CHAP-specific problems you're likely to encounter are mostly 163related to your Windows NT account and its settings. A Microsoft server 164returns error codes in its CHAP response. The following are extracted from 165RFC 2433: 166 167 646 ERROR_RESTRICTED_LOGON_HOURS 168 647 ERROR_ACCT_DISABLED 169 648 ERROR_PASSWD_EXPIRED 170 649 ERROR_NO_DIALIN_PERMISSION 171 691 ERROR_AUTHENTICATION_FAILURE 172 709 ERROR_CHANGING_PASSWORD 173 174You'll see these in your pppd log as a line similar to: 175 176 Remote message: E=649 R=0 177 178The "E=" is the error number from the table above, and the "R=" flag 179indicates whether the error is transient and the client should retry. If 180you consistently get error 691, then either you're using the wrong account 181name/password, or the DES library or MD4 hashing (in md4.c) aren't working 182properly. Verify your account name and password (use a Windows NT or 183Windows 95 system to dial-in if you have one available). If that checks 184out, test the DES library with the "destest" program included with the DES 185library. If DES checks out, the md4.c routines are probably failing 186(system byte ordering may be a problem) or my code is screwing up. I've 187only got access to a Linux system, so you're on your own for anything else. 188 189Another thing that might cause problems is that some RAS servers won't 190respond at all to LCP config requests without seeing the word "CLIENT" 191from the other end. If you see pppd sending out LCP config requests 192without getting any reply, try putting something in your chat script 193to send the word CLIENT after the modem has connected. 194 195STILL TO DO 196 197A site using only MS-CHAP to authenticate has no need to store cleartext 198passwords in the "chap-secrets" file. A utility that spits out the ASCII 199hex MD4 hash of a given password would be nice, and would allow that hash 200to be used in chap-secrets in place of the password. The code to do this 201could quite easily be lifted from chap_ms.c (you have to convert the 202password to Unicode before hashing it). The chap_ms.c file would also have 203to be changed to recognize a password hash (16 binary bytes == 32 ASCII hex 204characters) and skip the hashing stage. This would have no real security 205value as the hash is plaintext-equivalent. 206