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

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

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