README.MSCHAP80

   1 PPP Support for Microsoft's CHAP-80
   2 ===================================
   3
   4 Eric 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
  10 INTRODUCTION
  11
  12 Microsoft has introduced an extension to the Challenge/Handshake
  13 Authentication Protocol (CHAP) which avoids storing cleartext
  14 passwords on a server.  (Unfortunately, this is not as secure as it
  15 sounds, because the encrypted password stored on a server can be used
  16 by a bogus client to gain access to the server just as easily as if
  17 the password were stored in cleartext.)  The details of the Microsoft
  18 extensions can be found in the document:
  19
  20     <http://www.ietf.org/rfc/rfc2433.txt>
  21
  22 In short, MS-CHAP is identified as <auth chap 80> since the hex value
  23 of 80 is used to designate Microsoft's scheme.  Standard PPP CHAP uses
  24 a value of 5.  If you enable PPP debugging with the "debug" option and
  25 see something like the following in your logs, the remote server is
  26 requesting MS-CHAP:
  27
  28   rcvd [LCP ConfReq id=0x2 <asyncmap 0x0> <auth chap 80> <magic 0x46a3>]
  29                                            ^^^^^^^^^^^^
  30
  31 The standard pppd implementation will indicate its lack of support for
  32 MS-CHAP by NAKing it:
  33
  34   sent [LCP ConfNak id=0x2 <auth chap 05>]
  35
  36 Windows NT Server systems are often configured to "Accept only
  37 Microsoft Authentication" (this is intended to enhance security).  Up
  38 until now, that meant that you couldn't use this version of PPPD to
  39 connect to such a system.
  40
  41
  42 BUILDING THE PPPD
  43
  44 MS-CHAP uses a combination of MD4 hashing and DES encryption for
  45 authentication.  You may need to get Eric Young's libdes library in
  46 order to use my MS-CHAP extensions.  A lot of UNIX systems already
  47 have DES encryption available via the crypt(3), encrypt(3) and
  48 setkey(3) interfaces.  Some may (such as that on Digital UNIX)
  49 provide only the encryption mechanism and will not perform
  50 decryption.  This is okay.  We only need to encrypt to perform
  51 MS-CHAP authentication.
  52
  53 If you have encrypt/setkey available, then hopefully you need only
  54 define these two things in your Makefile: -DUSE_CRYPT and -DCHAPMS.
  55 Skip the paragraphs below about obtaining and building libdes.  Do
  56 the "make clean" and "make" as described below.  Linux users
  57 should not need to modify their Makefiles.  Instead,
  58 just do "make CHAPMS=1 USE_CRYPT=1".
  59
  60 If you don't have encrypt and setkey, you will need Eric Young's
  61 libdes library.  You can find it in:
  62
  63 ftp://ftp.funet.fi/pub/crypt/mirrors/ftp.psy.uq.oz.au/DES/libdes-3.06.tar.gz
  64
  65 Australian residents can get libdes from Eric Young's site:
  66
  67 ftp://ftp.psy.uq.oz.au/pub/Crypto/DES/libdes-3.06.tar.gz
  68
  69 It is also available on many other sites (ask Archie).
  70
  71 I used libdes-3.06, but hopefully anything newer than that will work
  72 also.  Get the library, build and test it on your system, and install
  73 it somewhere (typically /usr/local/lib and /usr/local/include).
  74
  75
  76
  77 You should now be ready to (re)compile the PPPD.  Go to the pppd
  78 subdirectory and make sure the Makefile contains "-DCHAPMS" in the
  79 CFLAGS or COMPILE_FLAGS macro, and that the LIBS macro (or LDADD for
  80 BSD systems) contains "-ldes".  Depending on your system and where the
  81 DES library was installed, you may also need to alter the include and
  82 library paths used by your compiler.
  83
  84 Do a "make clean" and then a "make" to rebuild pppd.  Assuming all
  85 goes well, install the new pppd and move on to the CONFIGURATION
  86 section.
  87
  88
  89 CONFIGURATION
  90
  91 If 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
  93 edit the "chap-secrets" file typically named /etc/ppp/chap-secrets.
  94 This should contain the following two lines for each system with which
  95 you use CHAP (with no leading blanks):
  96
  97     RemoteHost  Account     Secret
  98     Account     RemoteHost  Secret
  99
 100 Note that you need both lines and that item 1 and 2 are swapped in the
 101 second line.  I'm not sure why you need it twice, but it works and I didn't
 102 have time to look into it further.  The "RemoteHost" is a somewhat
 103 arbitrary name for the remote Windows NT system you're dialing.  It doesn't
 104 have to match the NT system's name, but it *does* have to match what you
 105 use with the "remotename" parameter.  The "Account" is the Windows NT
 106 account name you have been told to use when dialing, and the "Secret" is
 107 the password for that account.  For example, if your service provider calls
 108 their 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
 114 The only other thing you need to do for MS-CHAP (compared to normal CHAP)
 115 is to always use the "remotename" option, either on the command line or in
 116 your "options" file (see the pppd man page for details).  In the case of
 117 the above example, you would need to use the following command line:
 118
 119     pppd name customer47 remotename DialupNT <other options>
 120
 121 or add:
 122
 123     name customer47
 124     remotename DialupNT
 125
 126 to your PPPD "options" file.
 127
 128 The "remotename" option is required for MS-CHAP since Microsoft PPP servers
 129 don't send their system name in the CHAP challenge packet.
 130
 131
 132 E=691 (AUTHENTICATION_FAILURE) ERRORS WHEN YOU HAVE THE VALID SECRET (PASSWORD)
 133
 134 If your RAS server is not the domain controller and is not a 'stand-alone'
 135 server then it must make a query to the domain controller for your domain.
 136
 137 You need to specify the domain name with the user name when you attempt to
 138 use this type of a configuration. The domain name is specified with the
 139 local name in the chap-secrets file and with the option for the 'name'
 140 parameter.
 141
 142 For example, the previous example would become:
 143
 144     DialupNT            domain\\customer47   foobar
 145     domain\\customer47  DialupNT             foobar
 146
 147 and
 148
 149     pppd name 'domain\\customer47' remotename DialupNT <other options>
 150
 151 or add:
 152
 153     name domain\\customer47
 154     remotename DialupNT
 155
 156 when the Windows NT domain name is simply called 'domain'.
 157
 158
 159 TROUBLESHOOTING
 160
 161 Assuming that everything else has been configured correctly for PPP and
 162 CHAP, the MS-CHAP-specific problems you're likely to encounter are mostly
 163 related to your Windows NT account and its settings.  A Microsoft server
 164 returns error codes in its CHAP response.  The following are extracted from
 165 RFC 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
 174 You'll see these in your pppd log as a line similar to:
 175
 176    Remote message: E=649 R=0
 177
 178 The "E=" is the error number from the table above, and the "R=" flag
 179 indicates whether the error is transient and the client should retry.  If
 180 you consistently get error 691, then either you're using the wrong account
 181 name/password, or the DES library or MD4 hashing (in md4.c) aren't working
 182 properly.  Verify your account name and password (use a Windows NT or
 183 Windows 95 system to dial-in if you have one available).  If that checks
 184 out, test the DES library with the "destest" program included with the DES
 185 library.  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
 187 only got access to a Linux system, so you're on your own for anything else.
 188
 189 Another thing that might cause problems is that some RAS servers won't
 190 respond at all to LCP config requests without seeing the word "CLIENT"
 191 from the other end.  If you see pppd sending out LCP config requests
 192 without getting any reply, try putting something in your chat script
 193 to send the word CLIENT after the modem has connected.
 194
 195 If everything compiles cleanly, but fails at authentication time, then
 196 it might be a case of the MD4 or DES code screwing up.  The following
 197 small program can be used to test the MS-CHAP code to see if it
 198 produces a known response:
 199
 200 -----------------
 201 #include <stdio.h>
 202
 203 #include "pppd.h"
 204 #include "chap.h"
 205 #include "chap_ms.h"
 206
 207 int main(argc, argv)
 208     int     argc;
 209     char    *argv[];
 210 {
 211     u_char          challenge[8];
 212     int             challengeInt[sizeof(challenge)];
 213     chap_state      cstate;
 214     int             i;
 215
 216     if (argc != 3) {
 217         fprintf(stderr, "Usage: %s <16-hexchar challenge> <password>\n",
 218         argv[0]); exit(1);
 219     }
 220
 221     sscanf(argv[1], "%2x%2x%2x%2x%2x%2x%2x%2x",
 222            challengeInt + 0, challengeInt + 1, challengeInt + 2,
 223            challengeInt + 3, challengeInt + 4, challengeInt + 5,
 224            challengeInt + 6, challengeInt + 7);
 225
 226     for (i = 0; i < sizeof(challenge); i++)
 227         challenge[i] = (u_char)challengeInt[i];
 228
 229     ChapMS(&cstate, challenge, argv[2], strlen(argv[2]),
 230            (MS_ChapResponse *)&cstate.response);
 231     printf("Response length is %d, response is:", cstate.resp_length);
 232
 233     for (i = 0; i < cstate.resp_length; i++) {
 234         if (i % 8 == 0)
 235             putchar('\n');
 236         printf("%02X ", (unsigned int)cstate.response[i]);
 237     }
 238
 239     putchar('\n');
 240
 241     exit(0);
 242 }
 243 -------------
 244
 245 This needs to link against chap_ms.o, md4.o, sha1.o and the DES library.
 246 When you run it with the command line:
 247
 248  $ testchap 00000000000000000000000000000000 hello
 249
 250 it should output the following:
 251
 252  Response length is 49, response is:
 253  00 00 00 00 00 00 00 00
 254  00 00 00 00 00 00 00 00
 255  00 00 00 00 00 00 00 00
 256  F4 D9 9D AF 82 64 DC 3C
 257  53 F9 BC 92 14 B5 5D 9E
 258  78 C4 21 48 9D B7 A8 B4
 259  01
 260
 261 if not, then either the DES library is not working, the MD4 code isn't
 262 working, or there are some problems with the port of the code in
 263 chap_ms.c.
 264
 265
 266 STILL TO DO
 267
 268 A site using only MS-CHAP to authenticate has no need to store cleartext
 269 passwords in the "chap-secrets" file.  A utility that spits out the ASCII
 270 hex MD4 hash of a given password would be nice, and would allow that hash
 271 to be used in chap-secrets in place of the password.  The code to do this
 272 could quite easily be lifted from chap_ms.c (you have to convert the
 273 password to Unicode before hashing it).  The chap_ms.c file would also have
 274 to be changed to recognize a password hash (16 binary bytes == 32 ASCII hex
 275 characters) and skip the hashing stage.  This would have no real security
 276 value as the hash is plaintext-equivalent.