head	1.1;
branch	1.1.1;
access;
symbols
	netbsd-9-5-RELEASE:1.1.1.1
	netbsd-11-0-RELEASE:1.1.1.2
	netbsd-11-0-RC7:1.1.1.2
	netbsd-11-0-RC6:1.1.1.2
	netbsd-11-0-RC5:1.1.1.2
	netbsd-11-0-RC4:1.1.1.2
	netbsd-11-0-RC3:1.1.1.2
	netbsd-11-0-RC2:1.1.1.2
	netbsd-11-0-RC1:1.1.1.2
	perseant-exfatfs-base-20250801:1.1.1.2
	netbsd-11:1.1.1.2.0.2
	netbsd-11-base:1.1.1.2
	ppp-2-5-2:1.1.1.2
	netbsd-10-1-RELEASE:1.1.1.1
	perseant-exfatfs-base-20240630:1.1.1.1
	perseant-exfatfs:1.1.1.1.0.42
	perseant-exfatfs-base:1.1.1.1
	netbsd-8-3-RELEASE:1.1.1.1
	netbsd-9-4-RELEASE:1.1.1.1
	netbsd-10-0-RELEASE:1.1.1.1
	netbsd-10-0-RC6:1.1.1.1
	netbsd-10-0-RC5:1.1.1.1
	netbsd-10-0-RC4:1.1.1.1
	netbsd-10-0-RC3:1.1.1.1
	netbsd-10-0-RC2:1.1.1.1
	netbsd-10-0-RC1:1.1.1.1
	netbsd-10:1.1.1.1.0.40
	netbsd-10-base:1.1.1.1
	netbsd-9-3-RELEASE:1.1.1.1
	cjep_sun2x-base1:1.1.1.1
	cjep_sun2x:1.1.1.1.0.38
	cjep_sun2x-base:1.1.1.1
	cjep_staticlib_x-base1:1.1.1.1
	netbsd-9-2-RELEASE:1.1.1.1
	cjep_staticlib_x:1.1.1.1.0.36
	cjep_staticlib_x-base:1.1.1.1
	ppp-2-4-9:1.1.1.1
	netbsd-9-1-RELEASE:1.1.1.1
	phil-wifi-20200421:1.1.1.1
	phil-wifi-20200411:1.1.1.1
	is-mlppp:1.1.1.1.0.34
	is-mlppp-base:1.1.1.1
	phil-wifi-20200406:1.1.1.1
	netbsd-8-2-RELEASE:1.1.1.1
	netbsd-9-0-RELEASE:1.1.1.1
	netbsd-9-0-RC2:1.1.1.1
	netbsd-9-0-RC1:1.1.1.1
	phil-wifi-20191119:1.1.1.1
	netbsd-9:1.1.1.1.0.32
	netbsd-9-base:1.1.1.1
	phil-wifi-20190609:1.1.1.1
	netbsd-8-1-RELEASE:1.1.1.1
	netbsd-8-1-RC1:1.1.1.1
	pgoyette-compat-merge-20190127:1.1.1.1
	pgoyette-compat-20190127:1.1.1.1
	pgoyette-compat-20190118:1.1.1.1
	pgoyette-compat-1226:1.1.1.1
	pgoyette-compat-1126:1.1.1.1
	pgoyette-compat-1020:1.1.1.1
	pgoyette-compat-0930:1.1.1.1
	pgoyette-compat-0906:1.1.1.1
	netbsd-7-2-RELEASE:1.1.1.1
	pgoyette-compat-0728:1.1.1.1
	netbsd-8-0-RELEASE:1.1.1.1
	phil-wifi:1.1.1.1.0.30
	phil-wifi-base:1.1.1.1
	pgoyette-compat-0625:1.1.1.1
	netbsd-8-0-RC2:1.1.1.1
	pgoyette-compat-0521:1.1.1.1
	pgoyette-compat-0502:1.1.1.1
	pgoyette-compat-0422:1.1.1.1
	netbsd-8-0-RC1:1.1.1.1
	pgoyette-compat-0415:1.1.1.1
	pgoyette-compat-0407:1.1.1.1
	pgoyette-compat-0330:1.1.1.1
	pgoyette-compat-0322:1.1.1.1
	pgoyette-compat-0315:1.1.1.1
	netbsd-7-1-2-RELEASE:1.1.1.1
	pgoyette-compat:1.1.1.1.0.28
	pgoyette-compat-base:1.1.1.1
	netbsd-7-1-1-RELEASE:1.1.1.1
	matt-nb8-mediatek:1.1.1.1.0.26
	matt-nb8-mediatek-base:1.1.1.1
	perseant-stdc-iso10646:1.1.1.1.0.24
	perseant-stdc-iso10646-base:1.1.1.1
	netbsd-8:1.1.1.1.0.22
	netbsd-8-base:1.1.1.1
	prg-localcount2-base3:1.1.1.1
	prg-localcount2-base2:1.1.1.1
	prg-localcount2-base1:1.1.1.1
	prg-localcount2:1.1.1.1.0.20
	prg-localcount2-base:1.1.1.1
	pgoyette-localcount-20170426:1.1.1.1
	bouyer-socketcan-base1:1.1.1.1
	pgoyette-localcount-20170320:1.1.1.1
	netbsd-7-1:1.1.1.1.0.18
	netbsd-7-1-RELEASE:1.1.1.1
	netbsd-7-1-RC2:1.1.1.1
	netbsd-7-nhusb-base-20170116:1.1.1.1
	bouyer-socketcan:1.1.1.1.0.16
	bouyer-socketcan-base:1.1.1.1
	pgoyette-localcount-20170107:1.1.1.1
	netbsd-7-1-RC1:1.1.1.1
	pgoyette-localcount-20161104:1.1.1.1
	netbsd-7-0-2-RELEASE:1.1.1.1
	localcount-20160914:1.1.1.1
	netbsd-7-nhusb:1.1.1.1.0.14
	netbsd-7-nhusb-base:1.1.1.1
	pgoyette-localcount-20160806:1.1.1.1
	pgoyette-localcount-20160726:1.1.1.1
	pgoyette-localcount:1.1.1.1.0.12
	pgoyette-localcount-base:1.1.1.1
	netbsd-7-0-1-RELEASE:1.1.1.1
	netbsd-7-0:1.1.1.1.0.10
	netbsd-7-0-RELEASE:1.1.1.1
	netbsd-7-0-RC3:1.1.1.1
	netbsd-7-0-RC2:1.1.1.1
	netbsd-7-0-RC1:1.1.1.1
	PPP2_4_7:1.1.1.1
	tls-maxphys-base:1.1.1.1
	tls-maxphys:1.1.1.1.0.8
	netbsd-7:1.1.1.1.0.6
	netbsd-7-base:1.1.1.1
	yamt-pagecache:1.1.1.1.0.4
	yamt-pagecache-base9:1.1.1.1
	tls-earlyentropy:1.1.1.1.0.2
	tls-earlyentropy-base:1.1.1.1
	riastradh-xf86-video-intel-2-7-1-pre-2-21-15:1.1.1.1
	riastradh-drm2-base3:1.1.1.1
	ppp-2-4-5:1.1.1.1
	MACKERRAS:1.1.1;
locks; strict;
comment	@# @;


1.1
date	2013.11.28.21.53.41;	author christos;	state Exp;
branches
	1.1.1.1;
next	;
commitid	Esxn9c33hEocM5fx;

1.1.1.1
date	2013.11.28.21.53.41;	author christos;	state Exp;
branches
	1.1.1.1.4.1
	1.1.1.1.8.1
	1.1.1.1.42.1;
next	1.1.1.2;
commitid	Esxn9c33hEocM5fx;

1.1.1.2
date	2025.01.08.19.54.36;	author christos;	state Exp;
branches;
next	;
commitid	akeeBvxAosn3EIEF;

1.1.1.1.4.1
date	2013.11.28.21.53.41;	author yamt;	state dead;
branches;
next	1.1.1.1.4.2;
commitid	K94L62dsYauo9yBx;

1.1.1.1.4.2
date	2014.05.22.15.51.08;	author yamt;	state Exp;
branches;
next	;
commitid	K94L62dsYauo9yBx;

1.1.1.1.8.1
date	2013.11.28.21.53.41;	author tls;	state dead;
branches;
next	1.1.1.1.8.2;
commitid	jTnpym9Qu0o4R1Nx;

1.1.1.1.8.2
date	2014.08.19.23.52.11;	author tls;	state Exp;
branches;
next	;
commitid	jTnpym9Qu0o4R1Nx;

1.1.1.1.42.1
date	2025.08.02.05.23.14;	author perseant;	state Exp;
branches;
next	;
commitid	23j6GFaDws3O875G;


desc
@@


1.1
log
@Initial revision
@
text
@PPP Support for Microsoft's CHAP-80
===================================

Eric Rosenquist          rosenqui@@strataware.com
(updated by Paul Mackerras)
(updated by Al Longyear)
(updated by Farrell Woods)
(updated by Frank Cusack)

INTRODUCTION

Microsoft has introduced an extension to the Challenge/Handshake
Authentication Protocol (CHAP) which avoids storing cleartext
passwords on a server.  (Unfortunately, this is not as secure as it
sounds, because the encrypted password stored on a server can be used
by a bogus client to gain access to the server just as easily as if
the password were stored in cleartext.)  The details of the Microsoft
extensions can be found in the document:

    <http://www.ietf.org/rfc/rfc2433.txt>

In short, MS-CHAP is identified as <auth chap 80> since the hex value
of 80 is used to designate Microsoft's scheme.  Standard PPP CHAP uses
a value of 5.  If you enable PPP debugging with the "debug" option and
see something like the following in your logs, the remote server is
requesting MS-CHAP:

  rcvd [LCP ConfReq id=0x2 <asyncmap 0x0> <auth MS> <magic 0x46a3>]
                                           ^^^^^^^

MS-CHAP is enabled by default under Linux in pppd/Makefile.linux by
the line "CHAPMS=y".


CONFIGURATION

If you've never used PPPD with CHAP before, read the man page (type
"man pppd") and read the description in there.  Basically, you need to
edit the "chap-secrets" file typically named /etc/ppp/chap-secrets.
This should contain the following two lines for each system with which
you use CHAP (with no leading blanks):

    RemoteHost  Account     Secret
    Account     RemoteHost  Secret

Note that you need both lines and that item 1 and 2 are swapped in the
second line.  I'm not sure why you need it twice, but it works and I didn't
have time to look into it further.  The "RemoteHost" is a somewhat
arbitrary name for the remote Windows NT system you're dialing.  It doesn't
have to match the NT system's name, but it *does* have to match what you
use with the "remotename" parameter.  The "Account" is the Windows NT
account name you have been told to use when dialing, and the "Secret" is
the password for that account.  For example, if your service provider calls
their machine "DialupNT" and tells you your account and password are
"customer47" and "foobar", add the following to your chap-secrets file:

    DialupNT    customer47  foobar
    customer47  DialupNT    foobar

The only other thing you need to do for MS-CHAP (compared to normal CHAP)
is to always use the "remotename" option, either on the command line or in
your "options" file (see the pppd man page for details).  In the case of
the above example, you would need to use the following command line:

    pppd name customer47 remotename DialupNT <other options>

or add:

    name customer47
    remotename DialupNT

to your PPPD "options" file.

The "remotename" option is required for MS-CHAP since Microsoft PPP servers
don't send their system name in the CHAP challenge packet.


E=691 (AUTHENTICATION_FAILURE) ERRORS WHEN YOU HAVE THE VALID SECRET (PASSWORD)

If your RAS server is not the domain controller and is not a 'stand-alone'
server then it must make a query to the domain controller for your domain.

You need to specify the domain name with the user name when you attempt to
use this type of a configuration. The domain name is specified with the
local name in the chap-secrets file and with the option for the 'name'
parameter.

For example, the previous example would become:

    DialupNT            domain\\customer47   foobar
    domain\\customer47  DialupNT             foobar

and

    pppd name 'domain\\customer47' remotename DialupNT <other options>

or add:

    name domain\\customer47
    remotename DialupNT

when the Windows NT domain name is simply called 'domain'.


TROUBLESHOOTING

Assuming that everything else has been configured correctly for PPP and
CHAP, the MS-CHAP-specific problems you're likely to encounter are mostly
related to your Windows NT account and its settings.  A Microsoft server
returns error codes in its CHAP response.  The following are extracted from
RFC 2433:

 646 ERROR_RESTRICTED_LOGON_HOURS
 647 ERROR_ACCT_DISABLED
 648 ERROR_PASSWD_EXPIRED
 649 ERROR_NO_DIALIN_PERMISSION
 691 ERROR_AUTHENTICATION_FAILURE
 709 ERROR_CHANGING_PASSWORD

You'll see these in your pppd log as a line similar to:

   Remote message: E=649 R=0

The "E=" is the error number from the table above, and the "R=" flag
indicates whether the error is transient and the client should retry.  If
you consistently get error 691, then either you're using the wrong account
name/password, or the DES library or MD4 hashing (in md4.c) aren't working
properly.  Verify your account name and password (use a Windows NT or
Windows 95 system to dial-in if you have one available).  If that checks
out, test the DES library with the "destest" program included with the DES
library.  If DES checks out, the md4.c routines are probably failing
(system byte ordering may be a problem) or my code is screwing up.  I've
only got access to a Linux system, so you're on your own for anything else.

Another thing that might cause problems is that some RAS servers won't
respond at all to LCP config requests without seeing the word "CLIENT"
from the other end.  If you see pppd sending out LCP config requests
without getting any reply, try putting something in your chat script
to send the word CLIENT after the modem has connected.

STILL TO DO

A site using only MS-CHAP to authenticate has no need to store cleartext
passwords in the "chap-secrets" file.  A utility that spits out the ASCII
hex MD4 hash of a given password would be nice, and would allow that hash
to be used in chap-secrets in place of the password.  The code to do this
could quite easily be lifted from chap_ms.c (you have to convert the
password to Unicode before hashing it).  The chap_ms.c file would also have
to be changed to recognize a password hash (16 binary bytes == 32 ASCII hex
characters) and skip the hashing stage.  This would have no real security
value as the hash is plaintext-equivalent.
@


1.1.1.1
log
@Import ppp-2.4.5 from git://ozlabs.org/~paulus/ppp.git
@
text
@@


1.1.1.1.42.1
log
@Sync with HEAD
@
text
@d31 2
a32 3
MS-CHAP support in pppd (along with MPPE support) can be enabled or
disabled at configure time using the --enable-microsoft-extensions and
--disable-microsoft-extensions arguments.  The default is enabled.
@


1.1.1.2
log
@Import ppp-2.5.2, previous was 2.4.9

What's new in ppp-2.5.2
***********************

* Some old and probably unused code has been removed, notably the
  pppgetpass program and the passprompt plugin, and some of the files
  in the sample and scripts directories.

* If a remote number has been set, it is available to scripts in the
  REMOTENUMBER environment variable.

* The Solaris port has been updated, including updated installation
  instructions in README.sol2.

* Various other bug fixes and minor enhancements.


What was new in ppp-2.5.1
*************************

* The files copied to /etc/ppp (or <sysconfdir>/ppp) now have
  ".example" appended to their filenames, so as to indicate that they
  are just examples, and to avoid overwriting existing configuration
  files.

* Pppd can now measure and log the round-trip time (RTT) of LCP
  echo-requests and record them in a binary file structured as a
  circular buffer.  Other programs or scripts can examine the file and
  provide real-time statistics on link latency.  This is enabled by a
  new "lcp-rtt-file" option.

* New scripts net-init, net-pre-up and net-down are executed in the
  process of bringing the network interface up and down.  They provide
  additional, more deterministic ways for pppd to interact with the
  rest of the networking configuration.

* New options have been added to allow the system administrator to
  set the location of various scripts and secrets files.

* A new "noresolvconf" option tells pppd not to write the
  /etc/ppp/resolv.conf file; DNS server addresses, if obtained from
  the peer, are still passed to scripts in the environment.

* Pppd will now create the directory for the TDB connection database
  if it doesn't already exist.

* Kernel module code for Solaris is no longer included.

* Support for decompressing compressed packets has been removed from
  pppdump, because the zlib code used was old and potentially
  vulnerable.

* Some old code has been removed.

* Various other bug fixes and minor enhancements.


What was new in ppp-2.5.0.
**************************

The 2.5.0 release is a major release of pppd which contains breaking
changes for third-party plugins, a complete revamp of the build-system
and that allows for flexibility of configuring features as needed.

In Summary:
* Support for PEAP authentication by Eivind Næss and Rustam Kovhaev
* Support for loading PKCS12 certificate envelopes
* Adoption of GNU Autoconf / Automake build environment, by Eivind Næss
  and others.
* Support for pkgconfig tool has been added by Eivind Næss.
* Bunch of fixes and cleanup to PPPoE and IPv6 support by Pali Rohár.
* Major revision to PPPD's Plugin API by Eivind Næss.
  - Defines in which describes what features was included in pppd
  - Functions now prefixed with explicit ppp_* to indicate that
    pppd functions being called.
  - Header files were renamed to better align with their features,
    and now use proper include guards
  - A pppdconf.h file is supplied to allow third-party modules to use
    the same feature defines pppd was compiled with.
  - No extern declarations of internal variable names of pppd,
    continued use of these extern variables are considered
    unstable.
* Lots of internal fixes and cleanups for Radius and PPPoE by Jaco Kroon
* Dropped IPX support, as Linux has dropped support in version 5.15
  for this protocol.
* Many more fixes and cleanups.
* Pppd is no longer installed setuid-root.
* New pppd options:
  - ipv6cp-noremote, ipv6cp-nosend, ipv6cp-use-remotenumber,
    ipv6-up-script, ipv6-down-script
  - -v, show-options
  - usepeerwins, ipcp-no-address, ipcp-no-addresses, nosendip
* On Linux, any baud rate can be set on a serial port provided the
  kernel serial driver supports that.

Note that if you have built and installed previous versions of this
package and you want to continue having configuration and TDB files in
/etc/ppp, you will need to use the --sysconfdir option to ./configure.

For a list of the changes made during the 2.4 series releases of this
package, see the Changes-2.4 file.
@
text
@d31 2
a32 3
MS-CHAP support in pppd (along with MPPE support) can be enabled or
disabled at configure time using the --enable-microsoft-extensions and
--disable-microsoft-extensions arguments.  The default is enabled.
@


1.1.1.1.8.1
log
@file README.MSCHAP80 was added on branch tls-maxphys on 2014-08-19 23:52:11 +0000
@
text
@d1 151
@


1.1.1.1.8.2
log
@Rebase to HEAD as of a few days ago.
@
text
@a0 151
PPP Support for Microsoft's CHAP-80
===================================

Eric Rosenquist          rosenqui@@strataware.com
(updated by Paul Mackerras)
(updated by Al Longyear)
(updated by Farrell Woods)
(updated by Frank Cusack)

INTRODUCTION

Microsoft has introduced an extension to the Challenge/Handshake
Authentication Protocol (CHAP) which avoids storing cleartext
passwords on a server.  (Unfortunately, this is not as secure as it
sounds, because the encrypted password stored on a server can be used
by a bogus client to gain access to the server just as easily as if
the password were stored in cleartext.)  The details of the Microsoft
extensions can be found in the document:

    <http://www.ietf.org/rfc/rfc2433.txt>

In short, MS-CHAP is identified as <auth chap 80> since the hex value
of 80 is used to designate Microsoft's scheme.  Standard PPP CHAP uses
a value of 5.  If you enable PPP debugging with the "debug" option and
see something like the following in your logs, the remote server is
requesting MS-CHAP:

  rcvd [LCP ConfReq id=0x2 <asyncmap 0x0> <auth MS> <magic 0x46a3>]
                                           ^^^^^^^

MS-CHAP is enabled by default under Linux in pppd/Makefile.linux by
the line "CHAPMS=y".


CONFIGURATION

If you've never used PPPD with CHAP before, read the man page (type
"man pppd") and read the description in there.  Basically, you need to
edit the "chap-secrets" file typically named /etc/ppp/chap-secrets.
This should contain the following two lines for each system with which
you use CHAP (with no leading blanks):

    RemoteHost  Account     Secret
    Account     RemoteHost  Secret

Note that you need both lines and that item 1 and 2 are swapped in the
second line.  I'm not sure why you need it twice, but it works and I didn't
have time to look into it further.  The "RemoteHost" is a somewhat
arbitrary name for the remote Windows NT system you're dialing.  It doesn't
have to match the NT system's name, but it *does* have to match what you
use with the "remotename" parameter.  The "Account" is the Windows NT
account name you have been told to use when dialing, and the "Secret" is
the password for that account.  For example, if your service provider calls
their machine "DialupNT" and tells you your account and password are
"customer47" and "foobar", add the following to your chap-secrets file:

    DialupNT    customer47  foobar
    customer47  DialupNT    foobar

The only other thing you need to do for MS-CHAP (compared to normal CHAP)
is to always use the "remotename" option, either on the command line or in
your "options" file (see the pppd man page for details).  In the case of
the above example, you would need to use the following command line:

    pppd name customer47 remotename DialupNT <other options>

or add:

    name customer47
    remotename DialupNT

to your PPPD "options" file.

The "remotename" option is required for MS-CHAP since Microsoft PPP servers
don't send their system name in the CHAP challenge packet.


E=691 (AUTHENTICATION_FAILURE) ERRORS WHEN YOU HAVE THE VALID SECRET (PASSWORD)

If your RAS server is not the domain controller and is not a 'stand-alone'
server then it must make a query to the domain controller for your domain.

You need to specify the domain name with the user name when you attempt to
use this type of a configuration. The domain name is specified with the
local name in the chap-secrets file and with the option for the 'name'
parameter.

For example, the previous example would become:

    DialupNT            domain\\customer47   foobar
    domain\\customer47  DialupNT             foobar

and

    pppd name 'domain\\customer47' remotename DialupNT <other options>

or add:

    name domain\\customer47
    remotename DialupNT

when the Windows NT domain name is simply called 'domain'.


TROUBLESHOOTING

Assuming that everything else has been configured correctly for PPP and
CHAP, the MS-CHAP-specific problems you're likely to encounter are mostly
related to your Windows NT account and its settings.  A Microsoft server
returns error codes in its CHAP response.  The following are extracted from
RFC 2433:

 646 ERROR_RESTRICTED_LOGON_HOURS
 647 ERROR_ACCT_DISABLED
 648 ERROR_PASSWD_EXPIRED
 649 ERROR_NO_DIALIN_PERMISSION
 691 ERROR_AUTHENTICATION_FAILURE
 709 ERROR_CHANGING_PASSWORD

You'll see these in your pppd log as a line similar to:

   Remote message: E=649 R=0

The "E=" is the error number from the table above, and the "R=" flag
indicates whether the error is transient and the client should retry.  If
you consistently get error 691, then either you're using the wrong account
name/password, or the DES library or MD4 hashing (in md4.c) aren't working
properly.  Verify your account name and password (use a Windows NT or
Windows 95 system to dial-in if you have one available).  If that checks
out, test the DES library with the "destest" program included with the DES
library.  If DES checks out, the md4.c routines are probably failing
(system byte ordering may be a problem) or my code is screwing up.  I've
only got access to a Linux system, so you're on your own for anything else.

Another thing that might cause problems is that some RAS servers won't
respond at all to LCP config requests without seeing the word "CLIENT"
from the other end.  If you see pppd sending out LCP config requests
without getting any reply, try putting something in your chat script
to send the word CLIENT after the modem has connected.

STILL TO DO

A site using only MS-CHAP to authenticate has no need to store cleartext
passwords in the "chap-secrets" file.  A utility that spits out the ASCII
hex MD4 hash of a given password would be nice, and would allow that hash
to be used in chap-secrets in place of the password.  The code to do this
could quite easily be lifted from chap_ms.c (you have to convert the
password to Unicode before hashing it).  The chap_ms.c file would also have
to be changed to recognize a password hash (16 binary bytes == 32 ASCII hex
characters) and skip the hashing stage.  This would have no real security
value as the hash is plaintext-equivalent.
@


1.1.1.1.4.1
log
@file README.MSCHAP80 was added on branch yamt-pagecache on 2014-05-22 15:51:08 +0000
@
text
@d1 151
@


1.1.1.1.4.2
log
@sync with head.

for a reference, the tree before this commit was tagged
as yamt-pagecache-tag8.

this commit was splitted into small chunks to avoid
a limitation of cvs.  ("Protocol error: too many arguments")
@
text
@a0 151
PPP Support for Microsoft's CHAP-80
===================================

Eric Rosenquist          rosenqui@@strataware.com
(updated by Paul Mackerras)
(updated by Al Longyear)
(updated by Farrell Woods)
(updated by Frank Cusack)

INTRODUCTION

Microsoft has introduced an extension to the Challenge/Handshake
Authentication Protocol (CHAP) which avoids storing cleartext
passwords on a server.  (Unfortunately, this is not as secure as it
sounds, because the encrypted password stored on a server can be used
by a bogus client to gain access to the server just as easily as if
the password were stored in cleartext.)  The details of the Microsoft
extensions can be found in the document:

    <http://www.ietf.org/rfc/rfc2433.txt>

In short, MS-CHAP is identified as <auth chap 80> since the hex value
of 80 is used to designate Microsoft's scheme.  Standard PPP CHAP uses
a value of 5.  If you enable PPP debugging with the "debug" option and
see something like the following in your logs, the remote server is
requesting MS-CHAP:

  rcvd [LCP ConfReq id=0x2 <asyncmap 0x0> <auth MS> <magic 0x46a3>]
                                           ^^^^^^^

MS-CHAP is enabled by default under Linux in pppd/Makefile.linux by
the line "CHAPMS=y".


CONFIGURATION

If you've never used PPPD with CHAP before, read the man page (type
"man pppd") and read the description in there.  Basically, you need to
edit the "chap-secrets" file typically named /etc/ppp/chap-secrets.
This should contain the following two lines for each system with which
you use CHAP (with no leading blanks):

    RemoteHost  Account     Secret
    Account     RemoteHost  Secret

Note that you need both lines and that item 1 and 2 are swapped in the
second line.  I'm not sure why you need it twice, but it works and I didn't
have time to look into it further.  The "RemoteHost" is a somewhat
arbitrary name for the remote Windows NT system you're dialing.  It doesn't
have to match the NT system's name, but it *does* have to match what you
use with the "remotename" parameter.  The "Account" is the Windows NT
account name you have been told to use when dialing, and the "Secret" is
the password for that account.  For example, if your service provider calls
their machine "DialupNT" and tells you your account and password are
"customer47" and "foobar", add the following to your chap-secrets file:

    DialupNT    customer47  foobar
    customer47  DialupNT    foobar

The only other thing you need to do for MS-CHAP (compared to normal CHAP)
is to always use the "remotename" option, either on the command line or in
your "options" file (see the pppd man page for details).  In the case of
the above example, you would need to use the following command line:

    pppd name customer47 remotename DialupNT <other options>

or add:

    name customer47
    remotename DialupNT

to your PPPD "options" file.

The "remotename" option is required for MS-CHAP since Microsoft PPP servers
don't send their system name in the CHAP challenge packet.


E=691 (AUTHENTICATION_FAILURE) ERRORS WHEN YOU HAVE THE VALID SECRET (PASSWORD)

If your RAS server is not the domain controller and is not a 'stand-alone'
server then it must make a query to the domain controller for your domain.

You need to specify the domain name with the user name when you attempt to
use this type of a configuration. The domain name is specified with the
local name in the chap-secrets file and with the option for the 'name'
parameter.

For example, the previous example would become:

    DialupNT            domain\\customer47   foobar
    domain\\customer47  DialupNT             foobar

and

    pppd name 'domain\\customer47' remotename DialupNT <other options>

or add:

    name domain\\customer47
    remotename DialupNT

when the Windows NT domain name is simply called 'domain'.


TROUBLESHOOTING

Assuming that everything else has been configured correctly for PPP and
CHAP, the MS-CHAP-specific problems you're likely to encounter are mostly
related to your Windows NT account and its settings.  A Microsoft server
returns error codes in its CHAP response.  The following are extracted from
RFC 2433:

 646 ERROR_RESTRICTED_LOGON_HOURS
 647 ERROR_ACCT_DISABLED
 648 ERROR_PASSWD_EXPIRED
 649 ERROR_NO_DIALIN_PERMISSION
 691 ERROR_AUTHENTICATION_FAILURE
 709 ERROR_CHANGING_PASSWORD

You'll see these in your pppd log as a line similar to:

   Remote message: E=649 R=0

The "E=" is the error number from the table above, and the "R=" flag
indicates whether the error is transient and the client should retry.  If
you consistently get error 691, then either you're using the wrong account
name/password, or the DES library or MD4 hashing (in md4.c) aren't working
properly.  Verify your account name and password (use a Windows NT or
Windows 95 system to dial-in if you have one available).  If that checks
out, test the DES library with the "destest" program included with the DES
library.  If DES checks out, the md4.c routines are probably failing
(system byte ordering may be a problem) or my code is screwing up.  I've
only got access to a Linux system, so you're on your own for anything else.

Another thing that might cause problems is that some RAS servers won't
respond at all to LCP config requests without seeing the word "CLIENT"
from the other end.  If you see pppd sending out LCP config requests
without getting any reply, try putting something in your chat script
to send the word CLIENT after the modem has connected.

STILL TO DO

A site using only MS-CHAP to authenticate has no need to store cleartext
passwords in the "chap-secrets" file.  A utility that spits out the ASCII
hex MD4 hash of a given password would be nice, and would allow that hash
to be used in chap-secrets in place of the password.  The code to do this
could quite easily be lifted from chap_ms.c (you have to convert the
password to Unicode before hashing it).  The chap_ms.c file would also have
to be changed to recognize a password hash (16 binary bytes == 32 ASCII hex
characters) and skip the hashing stage.  This would have no real security
value as the hash is plaintext-equivalent.
@


