This is the README file for ppp-2.5, a package which implements the
Point-to-Point Protocol (PPP) to provide Internet connections over
serial lines and other types of links which can be considered to be
point-to-point links.


Introduction.
*************

The Point-to-Point Protocol (PPP) provides a standard way to establish
a network connection over a serial link.  At present, this package
supports IP and IPV6 and the protocols layered above them, such as TCP
and UDP.

This PPP implementation consists of two parts:

- Kernel code, which establishes a network interface and passes
packets between the serial port, the kernel networking code and the
PPP daemon (pppd).  This code is implemented using STREAMS modules on
Solaris, and as a line discipline under Linux.

- The PPP daemon (pppd), which negotiates with the peer to establish
the link and sets up the ppp network interface.  Pppd includes support
for authentication, so you can control which other systems may make a
PPP connection and what IP addresses they may use.

The platforms supported by this package are Linux and Solaris.
(There is also code to support various old flavours of Unix in the git
repository, but it is quite old and unmaintained.)

The kernel code for Linux is no longer distributed with this package,
since the relevant kernel code is in the official Linux kernel source
(and has been for many years) and is included in all reasonably modern
Linux distributions.  The Linux kernel code supports using PPP over
things other than serial ports, such as PPP over Ethernet and PPP over
ATM.

Similarly, the kernel code for Solaris is no longer distributed with
this package.  See the Illumos web site for pointers to the kernel
module source code and build environment.

  https://www.illumos.org/


Installation.
*************

The file SETUP contains general information about setting up your
system for using PPP.  There is also a README file for each supported
system, which contains more specific details for installing PPP on
that system.  The supported systems, and the corresponding README
files, are:

          Linux                                   README.linux
          Solaris                                 README.sol2

In each case you start by running the ./configure script.  This works
out which operating system you are using and creates the appropriate
makefiles.  You then run `make' to compile the user-level code, and
(as root) `make install' to install the user-level programs pppd, chat
and pppstats.

N.B. Since 2.3.0, leaving the permitted IP addresses column of the
pap-secrets or chap-secrets file empty means that no addresses are
permitted.  You need to put a "*" in that column to allow the peer to
use any IP address.  (This only applies where the peer is
authenticating itself to you, of course.)


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.


Compression methods.
********************

This package supports two packet compression methods: Deflate and
BSD-Compress.  Other compression methods which are in common use
include Predictor, LZS, and MPPC.  These methods are not supported for
two reasons - they are patent-encumbered, and they cause some packets
to expand slightly, which pppd doesn't currently allow for.
BSD-Compress and Deflate (which uses the same algorithm as gzip) don't
ever expand packets.


Contacts.
*********

Most communication relating to this package happens on github at
https://github.com/ppp-project/ppp/.  The linux-ppp@vger.kernel.org
mailing list also exists and can be used.

If you find bugs in this package, the best thing to do is to create an
issue on github.  If you can't or don't want to do that, you can post
to linux-ppp@vger.kernel.org, or report them to the maintainer for the
port for the operating system you are using:

Linux                         Paul Mackerras <paulus@ozlabs.org>
Solaris                       James Carlson <carlsonj@workingcode.com>


Copyrights:
***********

All of the code can be freely used and redistributed.  The individual
source files each have their own copyright and permission notice.
Pppd, pppstats and pppdump are under BSD-style notices.  Some of the
pppd plugins are GPL'd.  Chat has an MIT licence notice.


Distribution:
*************

The primary site for releases of this software is:

          ftp://ftp.samba.org/pub/ppp/

PPP Support for MPPE (Microsoft Point to Point Encryption)
==========================================================

Frank Cusack                  frank@google.com
Mar 19, 2002

Updated by Paul Mackerras, Sep 2008


DISCUSSION

MPPE is Microsoft's encryption scheme for PPP links.  It is pretty much
solely intended for use with PPP over Internet links -- if you have a true
point to point link you have little need for encryption.  It is generally
used with PPTP.

MPPE is negotiated within CCP (Compression Control Protocol) as option
18.  In order for MPPE to work, both peers must agree to do it.  This
complicates things enough that I chose to implement it as strictly a binary
option, off by default.  If you turn it on, all other compression options
are disabled and MPPE *must* be negotiated successfully in both directions
(CCP is unidirectional) or the link will be disconnected.  I think this is
reasonable since, if you want encryption, you want encryption.  That is,
I am not convinced that optional encryption is useful.

While PPP regards MPPE as a "compressor", it actually expands every frame
by 4 bytes, the MPPE overhead (encapsulation).

Because of the data expansion, you'll see that ppp interfaces get their
mtu reduced by 4 bytes whenever MPPE is negotiated.  This is because
when MPPE is active, it is *required* that *every* packet be encrypted.
PPPD sets the mtu = MIN(peer mru, configured mtu).  To ensure that
MPPE frames are not larger than the peer's mru, we reduce the mtu by 4
bytes so that the network layer never sends ppp a packet that's too large.

There is an option to compress the data before encrypting (MPPC), however
the algorithm is patented and requires execution of a license with Hifn.
MPPC as an RFC is a complete farce.  I have no further details on MPPC.

Some recommendations:

- Use stateless mode.  Stateful mode is disabled by default.  Unfortunately,
  stateless mode is very expensive as the peers must rekey for every packet.
- Use 128-bit encryption.
- Use MS-CHAPv2 only.

Reference documents:

    <http://www.ietf.org/rfc/rfc3078.txt> MPPE
    <http://www.ietf.org/rfc/rfc3079.txt> MPPE Key Derivation
    <http://www.ietf.org/rfc/rfc2118.txt> MPPC
    <http://www.ietf.org/rfc/rfc2637.txt> PPTP
    <http://www.ietf.org/rfc/rfc2548.txt> MS RADIUS Attributes

You might be interested in PoPToP, a Linux PPTP server.  You can find it at
<http://www.poptop.org/>

RADIUS support for MPPE is from Ralf Hofmann, <ralf.hofmann@elvido.net>.


BUILDING THE PPPD

The userland component of PPPD has no additional requirements above
those for MS-CHAP and MS-CHAPv2.

MPPE support is now included in the mainline Linux kernel releases.


CONFIGURATION

See pppd(8) for the MPPE options.  Under Linux, if your modutils is earlier
than 2.4.15, you will need to add

    alias ppp-compress-18 ppp_mppe

to /etc/modules.conf.

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 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.


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.

PPP Support for Microsoft's CHAP-81
===================================

Frank Cusack                  frank@google.com

Some text verbatim from README.MSCHAP80,
by Eric Rosenquist, rosenqui@strataware.com

INTRODUCTION

First, please read README.MSCHAP80; almost everything there applies here.
MS-CHAP was basically devised by Microsoft because rather than store
plaintext passwords, they (Microsoft) store the md4 hash of passwords.
It provides no advantage over standard CHAP, since the hash is used
as plaintext-equivalent.  (Well, the Change-Password packet is arguably
an advantage.)  It does introduce a significant weakness if the LM hash
is used.  Additionally, the format of the failure packet potentially
gives information to an attacker.  The weakness of the LM hash is partly
addressed in RFC 2433, which deprecates its use.

MS-CHAPv2 adds 2 benefits to MS-CHAP.  (1) The LM hash is no longer
used.  (2) Mutual authentication is required.  Note that the mutual
authentication in MS-CHAPv2 is different than the case where both PPP
peers require authentication from the other; the former proves that
the server has access to the client's password, the latter proves that
the server has access to a secret which the client also has -- which
may or may not be the same as the client's password (but should not be
the same, per RFC 1994).  Whether this provides any actual benefit is
outside the scope of this document.  The details of MS-CHAPv2 can be
found in the document:

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


BUILDING THE PPPD

In addition to the requirements for MS-CHAP, MS-CHAPv2 uses the SHA-1
hash algorithm.  A public domain implementation is provided with pppd.


TROUBLESHOOTING

Assuming that everything else has been configured correctly for PPP and
CHAP, the MS-CHAPv2-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 2759:

 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 No dialin permission

Previously, pppd would log this as:

   Remote message: E=649 R=0

Now, the text message is logged (both for MS-CHAP and MS-CHAPv2).

               Microsoft Call Back Configuration Protocol.
                              by Pedro Roque Marques
                              (updated by Paul Mackerras)

The CBCP is a method by which the Microsoft Windows NT Server may
implement additional security. It is possible to configure the server
in such a manner so as to require that the client systems which
connect with it are required that following a valid authentication to
leave a method by which the number may be returned call.

It is a requirement of servers to be so configured that the protocol be
exchanged.

So, this set of patches may be applied to the pppd process to enable
the cbcp client *only* portion of the specification. It is primarily
meant to permit connection with Windows NT Servers.

The ietf-working specification may be obtained from ftp.microsoft.com
in the developr/rfc directory.

The ietf task group has decided to recommend that the LCP sequence be
extended to permit the callback operation. For this reason, these
patches are not 'part' of pppd but are an adjunct to the code.

CBCP support is enabled or disabled in pppd at configure time using the
--enable-cbcp and --disable-cbcp arguments to ./configure.  The default
is disabled.

I use such script to make a callback:

pppd debug nodetach /dev/modem 115200 crtscts modem         \
callback 222222 name NAME remotename SERVER       \
connect 'chat -v "" atz OK atdt111111 CONNECT ""'
sleep 1
pppd debug /dev/modem 115200 crtscts modem        \
name NAME remotename SERVER defaultroute          \
connect 'chat -v RING ATA CONNECT "\c"'

First we invoke pppd with 'nodetach' option in order to not detach from
the controlling terminal and 'callback NUMBER' option, then wait for
1 second and invoke pppd again which waits for a callback (RING) and
then answers (ATA). Number 222222 is a callback number, i.e. server will
call us back at this number, while number 111111 is the number we are
calling to.

You have to put in /etc/ppp/chap-secrets the following two lines:

NAME SERVER PASSWORD
SERVER NAME PASSWORD

You have to use your real login name, remote server name and password.

EAP with MD5-Challenge and SRP-SHA1 support
by James Carlson, Sun Microsystems
Version 2, September 22nd, 2002


1.  What it does

    The Extensible Authentication Protocol (EAP; RFC 2284) is a
    security protocol that can be used with PPP.  It provides a means
    to plug in multiple optional authentication methods.

    This implementation includes the required default MD5-Challenge
    method, which is similar to CHAP (RFC 1994), as well as the new
    SRP-SHA1 method.  This latter method relies on an exchange that is
    not vulnerable to dictionary attacks (as is CHAP), does not
    require the server to keep a cleartext copy of the secret (as in
    CHAP), supports identity privacy, and produces a temporary shared
    key that could be used for data encryption.

    The SRP-SHA1 method is based on draft-ietf-pppext-eap-srp-03.txt,
    a work in progress.

2.  Required libraries

    Two other packages are required first.  Download and install
    OpenSSL and Thomas Wu's SRP implementation.

          http://www.openssl.org/ (or ftp://ftp.openssl.org/source/)
          http://srp.stanford.edu/

    Follow the directions in each package to install the SSL and SRP
    libraries.  Once SRP is installed, you may run tconf as root to
    create known fields, if desired.  (This step is not required.)

3.  Installing the patch

    The EAP-SRP patch described here is integrated into this version
    of pppd.  The following patch may be used with older pppd sources:

          ftp://playground.sun.com/carlsonj/eap/ppp-2.4.1-eap-1.tar.gz

    Configure, compile, and install as root.  You may want to edit
    pppd/Makefile after configuring to enable or disable optional
    features.

          % ./configure
          % make
          % su
          # make install

    If you use csh or tcsh, run "rehash" to pick up the new commands.

    If you're using Solaris, and you run into trouble with the
    pseudonym feature on the server side ("no DES here" shows in the
    log file), make sure that you have the "domestic" versions of the
    DES libraries linked.  You should see "crypt_d" in "ldd
    /usr/local/bin/pppd".  If you see "crypt_i" instead, then make
    sure that /usr/lib/libcrypt.* links to /usr/lib/libcrypt_d.*.  (If
    you have the international version of Solaris, then you won't have
    crypt_d.  You might want to find an alternative DES library.)

4.  Adding the secrets

    On the EAP SRP-SHA1 client side, access to the cleartext secret is
    required.  This can be done in two ways:

          - Enter the client name, server name, and password in the
          /etc/ppp/srp-secrets file.  This file has the same format as
          the existing chap-secrets and pap-secrets files.

            clientname servername "secret here"

          - Use the "password" option in any of the standard
          configuration files (or the command line) to specify the
          secret.

            password "secret here"

    On the EAP SRP-SHA1 server side, a secret verifier is required.
    This is a one-way hash of the client's name and password.  To
    generate this value, run the srp-entry program (see srp-entry(8)).
    This program prompts for the client name and the passphrase (the
    secret).  The output will be an entry, such as the following,
    suitable for use in the server's srp-secrets file.  Note that if
    this is transferred by cut-and-paste, the entry must be a single
    line of text in the file.

pppuser srpserver 0:LFDpwg4HBLi4/kWByzbZpW6pE95/iIWBSt7L.DAkHsvwQphtiq0f6reoUy/1LC1qYqjcrV97lCDmQHQd4KIACGgtkhttLdP3KMowvS0wLXLo25FPJeG2sMAUEWu/HlJPn2/gHyh9aT.ZxUs5MsoQ1E61sJkVBc.2qze1CdZiQGTK3qtWRP6DOpM1bfhKtPoVm.g.MiCcTMWzc54xJUIA0mgKtpthE3JrqCc81cXUt4DYi5yBzeeGTqrI0z2/Gj8Jp7pS4Fkq3GmnYjMxnKfQorFXNwl3m7JSaPa8Gj9/BqnorJOsnSMlIhBe6dy4CYytuTbNb4Wv/nFkmSThK782V:2cIyMp1yKslQgE *

    The "secret" field consists of three entries separated by colons.
    The first entry is the index of the modulus and generator from
    SRP's /etc/tpasswd.conf.  If the special value 0 is used, then the
    well-known modulus/generator value is used (this is recommended,
    because it is much faster).  The second value is the verifier
    value.  The third is the password "salt."  These latter two values
    are encoded in base64 notation.

    For EAP MD5-Challenge, both client and server use the existing
    /etc/ppp/chap-secrets file.

5.  Configuration options

    There are two main options relating to EAP available for the
    client.  These are:

          refuse-eap                    - refuse to authenticate with EAP
          srp-use-pseudonym   - use the identity privacy if
                                          offered by server

    The second option stores a pseudonym, if offered by the EAP
    SRP-SHA1 server, in the $HOME/.ppp_pseudonym file.  The pseudonym
    is typically an encrypted version of the client identity.  During
    EAP start-up, the pseudonym stored in this file is offered to the
    peer as the identity.  If this is accepted by the peer, then
    eavesdroppers will be unable to determine the identity of the
    client.  Each time the client is authenticated, the server will
    offer a new pseudoname to the client using an obscured (reversibly
    encrypted) message.  Thus, access across successive sessions
    cannot be tracked.

    There are two main options for EAP on the server:

          require-eap                   - require client to use EAP
          srp-pn-secret "string"        - set server's pseudoname secret

    The second option sets the long-term secret used on the server to
    encrypt the user's identity to produce pseudonames.  The
    pseudoname is constructed by hashing this string with the current
    date (to the nearest day) with SHA1, then using this hash as the
    key for a DES encryption of the client's name.  The date is added
    to the hash for two reasons.  First, this allows the pseudonym to
    change daily.  Second, it allows the server to decode any previous
    pseudonym by trying previous dates.

    See the pppd(8) man page for additional options.

6.  Comments welcome!

    This is still an experimental implementation.  It has been tested
    and reviewed carefully for correctness, but may still be
    incomplete or have other flaws.  All comments are welcome.  Please
    address them to the author:

                    james.d.carlson@sun.com

    or, for EAP itself or the SRP extensions to EAP, to the IETF PPP
    Extensions working group:

                    ietf-ppp@merit.edu

EAP-TLS authentication support for PPP
======================================

1. Intro

    The Extensible Authentication Protocol (EAP; RFC 3748) is a
    security protocol that can be used with PPP.  It provides a means
    to plug in multiple optional authentication methods.

    Transport Level Security (TLS; RFC 5216) provides for mutual
    authentication, integrity-protected ciphersuite negotiation and
    key exchange between two endpoints.  It also provides for optional
    MPPE encryption.

    EAP-TLS (RFC 2716) incapsulates the TLS messages in EAP packets,
    allowing TLS mutual authentication to be used as a generic EAP
    mechanism. It also provides optional encryption using the MPPE
    protocol.

    EAP-TLS support is included in pppd, and is enabled or disabled
    at configure time by using the --enable-eaptls and --disable-eaptls
    arguments to ./configure.

    This authentication method can be used in both client and server mode.

2. Building

    To build pppd with EAP-TLS support, OpenSSL (http://www.openssl.org)
    is required. Any version from 0.9.7 should work.

    Configure, compile, and install as usual.

3. Configuration

    On the client side there are two ways to configure EAP-TLS:

    1. supply the appropriate 'ca', 'cert' and 'key' command-line parameters

    2. edit the /etc/ppp/eaptls-client file.
    Insert a line for each system with which you use EAP-TLS.
    The line is composed of this fields separated by tab:

      - Client name
        The name used by the client for authentication, can be *
      - Server name
        The name of the server, can be *
      - Client certificate file
        The file containing the certificate chain for the
        client in PEM format
      - Server certificate file
        If you want to specify the certificate that the
        server is allowed to use, put the certificate file name.
        Else put a dash '-'.
      - CA certificate file
        The file containing the trusted CA certificates in PEM
        format.
      - Client private key file
        The file containing the client private key in PEM format.


    On the server side edit the /etc/ppp/eaptls-server file.
    Insert a line for each system with which you use EAP-TLS.
    The line is composed of this fields separated by tab:

      - Client name
        The name used by the client for authentication, can be *
      - Server name
        The name of the server, can be *
      - Client certificate file
        If you want to specify the certificate that the
        client is allowed to use, put the certificate file name.
        Else put a dash '-'.
      - Server certificate file
        The file containing the certificate chain for the
        server in PEM format
      - CA certificate file
        The file containing the trusted CA certificates in PEM format.
      - Client private key file
        The file containing the server private key in PEM format.
      - addresses
        A list of IP addresses the client is allowed to use.


    OpenSSL engine support is included starting with v0.95 of this patch.
    Currently the only engine tested is the 'pkcs11' engine (hardware token
    support). To use the 'pksc11' engine:
      - Use a special private key fileiname in the /etc/ppp/eaptls-client file:
          <engine>:<identifier>
        e.g.
          pkcs11:123456

      - The certificate can also be loaded from the 'pkcs11' engine using
        a special client certificate filename in the /etc/ppp/eaptls-client file:
          <engine>:<identifier>
        e.g.
          pkcs11:123456

      - Create an /etc/ppp/openssl.cnf file to load the right OpenSSL engine prior
        to starting 'pppd'. A sample openssl.cnf file is

        openssl_conf = openssl_def

        [ openssl_def ]
        engines = engine_section

        [ engine_section ]
        pkcs11 = pkcs11_section

        [ pkcs11_section ]
        engine_id = pkcs11
        dynamic_path = /usr/lib64/openssl/engines/engine_pkcs11.so
        MODULE_PATH = /usr/lib64/libeTPkcs11.so
        init = 0

      - There are two ways to specify a password/PIN for the PKCS11 engine:
          - inside the openssl.cnf file using
              PIN = your-secret-pin
            Note The keyword 'PIN' is case sensitive!
          - Using the 'password' in the ppp options file.
        From v0.97 of the eap-tls patch the password can also be supplied
        using the appropriate 'eaptls_passwd_hook' (see plugins/passprompt.c
        for an example).


4. Options

    These pppd options are available:

      ca <ca-file>
        Use the CA public certificate found in <ca-file> in PEM format
      capath <directory>
        Use the directory <directory> as the CA public certificate directory
      cert <cert-file>
        Use the client public certificate found in <cert-file> in PEM format
        or in engine:engine_id format
      key <key-file>
        Use the client private key found in <key-file> in PEM format
        or in engine:engine_id format
      pkcs12 <pkcs12-file>
        Use a pkcs12 envelope as a substitute for cert and key. A password may be
        required to use this file.
      crl <crl-file>
        Use the Certificate Revocation List (CRL) file <crl-file> in PEM format.
      crl-dir <dir>
        Use CRL files from directory <dir>. It contains CRL files in PEM
        format and each file contains a CRL. The files are looked up
        by the issuer name hash value. Use the c_rehash utility
        to create necessary links.
      need-peer-eap
        If the peer doesn't ask us to authenticate or doesn't use eap
        to authenticate us, disconnect.
      max-tls-version <1.0|1.1|1.2 (default)|1.3>
        Specify the maximum TLS protocol version to negotiate with peers. Defaults
        to TLSv1.2 as the TLSv1.3 code is experimental.
      tls-verify-key-usage
        Validate certificate purpose and extended key usage
      tls-verify-method <none|subject|name|suffix>
        Compare the remotename against the subject, certificate name, or
        match by suffix. Default is 'name'.

    Note:
      password-encrypted certificates can be used as of v0.94 of this
      patch. The password for the eap-tls.key file is specified using
      the regular
          password ....
      statement in the ppp options file, or by using the appropriate
      plugin which supplies a 'eaptls_passwd_hook' routine.

5. Connecting

    If you're setting up a pppd server, edit the EAP-TLS configuration file
    as written above and then run pppd with the 'auth' option to authenticate
    the client. The EAP-TLS method will be used if the other eap methods can't
    be used (no secrets).

    If you're setting up a client, edit the configuration file and then run
    pppd with 'remotename' option to specify the server name. Add the
    'need-peer-eap' option if you want to be sure the peer ask you to
    authenticate (and to use eap) and to disconnect if it doesn't.

6. Example

    The following example can be used to connect a Linux client with the 'pptp'
    package to a Linux server running the 'pptpd' (PoPToP) package. The server
    was configured with a certificate with name (CN) 'pptp-server', the client
    was configured with a certificate with name (CN) 'pptp-client', both
    signed by the same Certificate Authority (CA).

    Server side:
      - /etc/pptpd.conf file:
          option /etc/ppp/options-pptpd-eaptls
          localip 172.16.1.1
          remoteip 172.16.1.10-20
      - /etc/ppp/options-pptpd-eaptls file:
          name pptp-server
          lock
          mtu 1500
          mru 1450
          auth
          lcp-echo-failure 3
          lcp-echo-interval 5
          nodeflate
          nobsdcomp
          nopredictor1
          nopcomp
          noaccomp

          require-eap
          require-mppe-128

          crl /home/janjust/ppp/keys/crl.pem

          debug
          logfile /tmp/pppd.log

      - /etc/ppp/eaptls-server file:
           * pptp-server - /etc/ppp/pptp-server.crt /etc/ppp/ca.crt /etc/ppp/pptp-server.key *

      - On the server, run
          pptdp --conf /etc/pptpd.conf

    Client side:
      - Run
          pppd noauth require-eap require-mppe-128 \
            ipcp-accept-local ipcp-accept-remote noipdefault \
            cert  /etc/ppp/keys/pptp-client.crt \
            key   /etc/ppp/keys/pptp-client.key \
            ca    /etc/ppp/keys/ca.crt \
            name pptp-client remotename pptp-server \
            debug logfile /tmp/pppd.log
            pty "pptp pptp-server.example.com --nolaunchpppd"

    Check /var/log/messages and the files /tmp/pppd.log on both sides for debugging info.

7. Notes

    This is experimental code.
    Send suggestions and comments to Jan Just Keijser <janjust@nikhef.nl>

PPPoL2TP plugin
===============

The pppol2tp plugin lets pppd use the Linux kernel driver pppol2tp.ko
to pass PPP frames in L2TP tunnels. The driver was integrated into the
kernel in the 2.6.23 release. For kernels before 2.6.23, an
out-of-tree kernel module is available from the pppol2tp-kmod package
in the OpenL2TP project.

Note that pppd receives only PPP control frames over the PPPoL2TP
socket; data frames are handled entirely by the kernel.

The pppol2tp plugin adds extra arguments to pppd and uses the Linux kernel
PPP-over-L2TP driver to set up each session's data path.

Arguments are:-

pppol2tp <fd>                   - FD for PPPoL2TP socket
pppol2tp_lns_mode               - PPPoL2TP LNS behavior. Default off.
pppol2tp_send_seq               - PPPoL2TP enable sequence numbers in
                                  transmitted data packets. Default off.
pppol2tp_recv_seq               - PPPoL2TP enforce sequence numbers in
                                  received data packets. Default off.
pppol2tp_reorderto <millisecs>  - PPPoL2TP data packet reorder timeout.
                                  Default 0 (no reordering).
pppol2tp_debug_mask <mask>      - PPPoL2TP debug mask. Bitwise OR of
                                          1 - verbose debug
                                          2 - control
                                          4 - kernel transport
                                          8 - ppp packet data
                                          Default: 0 (no debug).
pppol2tp_ifname <ifname>      - Name of PPP network interface visible
                                          to "ifconfig" and "ip link".
                                          Default: "pppN"
pppol2tp_tunnel_id <id>                 - L2TP tunnel_id tunneling this PPP
                                          session.
pppol2tp_session_id <id>      - L2TP session_id of this PPP session.
                                          The tunnel_id/session_id pair is used
                                          when sending event messages to openl2tpd.

pppd will typically be started by an L2TP daemon for each L2TP sesion,
supplying one or more of the above arguments as required. The pppd
user will usually have no visibility of these arguments.

Two hooks are exported by this plugin.

void (*pppol2tp_send_accm_hook)(int tunnel_id, int session_id,
     uint32_t send_accm, uint32_t recv_accm);
void (*pppol2tp_ip_updown_hook)(int tunnel_id, int session_id, int up);

Credits
=======

This plugin was developed by Katalix Systems as part of the OpenL2TP
project, http://openl2tp.sourceforge.net. OpenL2TP is a full-featured
L2TP client-server, suitable for use as an enterprise L2TP VPN server
or a VPN client.

Please copy problems to the OpenL2TP mailing list:
openl2tp-users@lists.sourceforge.net.

Maintained by:
          James Chapman
          jchapman@katalix.com
          Katalix Systems Ltd
          http://www.katalix.com

          Support to pass the password via a pipe to the pppd
          ---------------------------------------------------

          Arvin Schnell <arvin@suse.de>
          2002-02-08


1. Introduction
---------------

Normally programs like wvdial or kppp read the online password from their
config file and store them in the pap- and chap-secrets before they start the
pppd and remove them afterwards. Sure they need special privileges to do so.

The passwordfd feature offers a simpler and more secure solution. The program
that starts the pppd opens a pipe and writes the password into it. The pppd
simply reads the password from that pipe.

This methods is used for quite a while on SuSE Linux by the programs wvdial,
kppp and smpppd.


2. Example
----------

Here is a short C program that uses the passwordfd feature. It starts the pppd
to buildup a pppoe connection.


--snip--

#include <stdio.h>
#include <stdlib.h>
#include <unistd.h>
#include <signal.h>
#include <string.h>
#include <paths.h>

#ifndef _PATH_PPPD
#define _PATH_PPPD "/usr/sbin/pppd"
#endif


// Of course these values can be read from a configuration file or
// entered in a graphical dialog.
char *device = "eth0";
char *username = "1122334455661122334455660001@t-online.de";
char *password = "hello";

pid_t pid = 0;


void
sigproc (int src)
{
    fprintf (stderr, "Sending signal %d to pid %d\n", src, pid);
    kill (pid, src);
    exit (EXIT_SUCCESS);
}


void
sigchild (int src)
{
    fprintf (stderr, "Daemon died\n");
    exit (EXIT_SUCCESS);
}


int
start_pppd ()
{
    signal (SIGINT, &sigproc);
    signal (SIGTERM, &sigproc);
    signal (SIGCHLD, &sigchild);

    pid = fork ();
    if (pid < 0) {
          fprintf (stderr, "unable to fork() for pppd: %m\n");
          return 0;
    }

    if (pid == 0) {

          int i, pppd_argc = 0;
          char *pppd_argv[20];
          char buffer[32] = "";
          int pppd_passwdfd[2];

          for (i = 0; i < 20; i++)
              pppd_argv[i] = NULL;

          pppd_argv[pppd_argc++] = "pppd";

          pppd_argv[pppd_argc++] = "call";
          pppd_argv[pppd_argc++] = "pwfd-test";

          // The device must be after the call, since the call loads the plugin.
          pppd_argv[pppd_argc++] = device;

          pppd_argv[pppd_argc++] = "user";
          pppd_argv[pppd_argc++] = username;

          // Open a pipe to pass the password to pppd.
          if (pipe (pppd_passwdfd) == -1) {
              fprintf (stderr, "pipe failed: %m\n");
              exit (EXIT_FAILURE);
          }

          // Of course this only works it the password is shorter
          // than the pipe buffer. Otherwise you have to fork to
          // prevent that your main program blocks.
          write (pppd_passwdfd[1], password, strlen (password));
          close (pppd_passwdfd[1]);

          // Tell the pppd to read the password from the fd.
          pppd_argv[pppd_argc++] = "passwordfd";
          snprintf (buffer, 32, "%d", pppd_passwdfd[0]);
          pppd_argv[pppd_argc++] = buffer;

          if (execv (_PATH_PPPD, (char **) pppd_argv) < 0) {
              fprintf (stderr, "cannot execl %s: %m\n", _PATH_PPPD);
              exit (EXIT_FAILURE);
          }
    }

    pause ();

    return 1;
}


int
main (int argc, char **argv)
{
    if (start_pppd ())
          exit (EXIT_SUCCESS);

    exit (EXIT_FAILURE);
}

---snip---


Copy this file to /etc/ppp/peers/pwfd-test. The plugins can't be loaded on the
command line (unless you are root) since the plugin option is privileged.


---snip---

#
# PPPoE plugin for kernel 2.4
#
plugin pppoe.so

#
# This plugin enables us to pipe the password to pppd, thus we don't have
# to fiddle with pap-secrets and chap-secrets. The user is also passed
# on the command line.
#
plugin passwordfd.so

noauth
usepeerdns
defaultroute
hide-password
nodetach
nopcomp
novjccomp
noccp

---snip---