README.MSCHAP80

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