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 MS> <magic 0x46a3>]
  29                                            ^^^^^^^
  30
  31 MS-CHAP support in pppd (along with MPPE support) can be enabled or
  32 disabled at configure time using the --enable-microsoft-extensions and
  33 --disable-microsoft-extensions arguments.  The default is enabled.
  34
  35
  36 CONFIGURATION
  37
  38 If 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
  40 edit the "chap-secrets" file typically named /etc/ppp/chap-secrets.
  41 This should contain the following two lines for each system with which
  42 you use CHAP (with no leading blanks):
  43
  44     RemoteHost  Account     Secret
  45     Account     RemoteHost  Secret
  46
  47 Note that you need both lines and that item 1 and 2 are swapped in the
  48 second line.  I'm not sure why you need it twice, but it works and I didn't
  49 have time to look into it further.  The "RemoteHost" is a somewhat
  50 arbitrary name for the remote Windows NT system you're dialing.  It doesn't
  51 have to match the NT system's name, but it *does* have to match what you
  52 use with the "remotename" parameter.  The "Account" is the Windows NT
  53 account name you have been told to use when dialing, and the "Secret" is
  54 the password for that account.  For example, if your service provider calls
  55 their 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
  61 The only other thing you need to do for MS-CHAP (compared to normal CHAP)
  62 is to always use the "remotename" option, either on the command line or in
  63 your "options" file (see the pppd man page for details).  In the case of
  64 the above example, you would need to use the following command line:
  65
  66     pppd name customer47 remotename DialupNT <other options>
  67
  68 or add:
  69
  70     name customer47
  71     remotename DialupNT
  72
  73 to your PPPD "options" file.
  74
  75 The "remotename" option is required for MS-CHAP since Microsoft PPP servers
  76 don't send their system name in the CHAP challenge packet.
  77
  78
  79 E=691 (AUTHENTICATION_FAILURE) ERRORS WHEN YOU HAVE THE VALID SECRET (PASSWORD)
  80
  81 If your RAS server is not the domain controller and is not a 'stand-alone'
  82 server then it must make a query to the domain controller for your domain.
  83
  84 You need to specify the domain name with the user name when you attempt to
  85 use this type of a configuration. The domain name is specified with the
  86 local name in the chap-secrets file and with the option for the 'name'
  87 parameter.
  88
  89 For example, the previous example would become:
  90
  91     DialupNT            domain\\customer47   foobar
  92     domain\\customer47  DialupNT             foobar
  93
  94 and
  95
  96     pppd name 'domain\\customer47' remotename DialupNT <other options>
  97
  98 or add:
  99
 100     name domain\\customer47
 101     remotename DialupNT
 102
 103 when the Windows NT domain name is simply called 'domain'.
 104
 105
 106 TROUBLESHOOTING
 107
 108 Assuming that everything else has been configured correctly for PPP and
 109 CHAP, the MS-CHAP-specific problems you're likely to encounter are mostly
 110 related to your Windows NT account and its settings.  A Microsoft server
 111 returns error codes in its CHAP response.  The following are extracted from
 112 RFC 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
 121 You'll see these in your pppd log as a line similar to:
 122
 123    Remote message: E=649 R=0
 124
 125 The "E=" is the error number from the table above, and the "R=" flag
 126 indicates whether the error is transient and the client should retry.  If
 127 you consistently get error 691, then either you're using the wrong account
 128 name/password, or the DES library or MD4 hashing (in md4.c) aren't working
 129 properly.  Verify your account name and password (use a Windows NT or
 130 Windows 95 system to dial-in if you have one available).  If that checks
 131 out, test the DES library with the "destest" program included with the DES
 132 library.  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
 134 only got access to a Linux system, so you're on your own for anything else.
 135
 136 Another thing that might cause problems is that some RAS servers won't
 137 respond at all to LCP config requests without seeing the word "CLIENT"
 138 from the other end.  If you see pppd sending out LCP config requests
 139 without getting any reply, try putting something in your chat script
 140 to send the word CLIENT after the modem has connected.
 141
 142 STILL TO DO
 143
 144 A site using only MS-CHAP to authenticate has no need to store cleartext
 145 passwords in the "chap-secrets" file.  A utility that spits out the ASCII
 146 hex MD4 hash of a given password would be nice, and would allow that hash
 147 to be used in chap-secrets in place of the password.  The code to do this
 148 could quite easily be lifted from chap_ms.c (you have to convert the
 149 password to Unicode before hashing it).  The chap_ms.c file would also have
 150 to be changed to recognize a password hash (16 binary bytes == 32 ASCII hex
 151 characters) and skip the hashing stage.  This would have no real security
 152 value as the hash is plaintext-equivalent.