Quick Build - PPPoE Client on JunOS

In this quick-build guide I'll show you how to set up a very basic JunOS-based PPPoE client. This example is from a Firefly virtual SRX firewall appliance, however the config should be identical on any JunOS platform. As usual, the build will cover the most simple common use case (no VLAN tags, dynamic AC selection, negotiated IP).

Note, if you want a PPPoE access concentrator to go with your client, you may find the Quick Build: Cisco IOS PPPoE Server with RADIUS Authentication post useful.

The Setup

The PPPoE client is set up in two config stanzas - the first being the physical interface which will connect towards the access concentrator, the second being a virtual point to point interface that will become live when the PPPoE session comes up. We'll build the physical interface first, as follows:

set interfaces ge-0/0/2 unit 0 encapsulation ppp-over-ether

In true JunOS fashion, very little config required there. Turn the interface encapsulation dial to PPPoE :)

Next, we need to set up the point to point interface. We'll create it as unit 0 and bind it to the physical interface we just configured:


set interfaces pp0 unit 0 pppoe-options underlying-interface ge-0/0/2.0
set interfaces pp0 unit 0 pppoe-options client

Now the PPP settings:

set interfaces pp0 unit 0 ppp-options chap default-chap-secret b0dges
set interfaces pp0 unit 0 ppp-options chap local-name "user@domain"
set interfaces pp0 unit 0 ppp-options chap passive

The lines above essentially just set the CHAP local name (think username), the CHAP secret (think password) and set CHAP to passive mode (i.e. tell it not to try to get the AC to authenticate to us). All that then remains is to configure up the IP:

set interfaces pp0 unit 0 family inet negotiate-address
set routing-options static route 0.0.0.0/0 next-hop pp0.0

That really is all that you need! In real life you will probably need to add NAT and so on, but the PPPoE configuration is done and the interface should just pop up on its own.

Debugging

Debugging PPPoE setup is best done by enabling trace logging for the PPP and PPPoE protocols as follows:

set protocols ppp traceoptions file ppp
set protocols ppp traceoptions level all
set protocols ppp traceoptions flag all
set protocols pppoe traceoptions file pppoe
set protocols pppoe traceoptions level all
set protocols pppoe traceoptions flag all

The output of these traces can then be seen using "show log ppp" and "show log pppoe" respectively. They are quite verbose and should give a strong steer on what is not working.

Quick Build - Cisco IOS PPPoE Server with RADIUS Authentication

In this guide I'll show you how to quickly set up an IOS-based PPPoE access concentrator and a RADIUS server for it to authenticate against. As part of the setup I'll include both dynamic (pool based) IP subscribers and a fixed IP subscriber, which should cover most basic use cases.

The setup I describe will look like this (we will only build the RADIUS and the AC):

If you need a client to go with it, please check out my post titled Quick build - PPPoE Client on Cisco IOS

Stage 1 - The RADIUS Server

Firstly we'll configure the RADIUS server - the starting point for this is a completely clean install of Kali Linux. It makes no difference if this is running as a VM or on a physical box but you will probably run out of "disk space" if you try to do this from a live CD boot. This assumes that you either have configured an Internet connection or have a full Kali disc / image from which to install packages.

Task 1 - Configure the Network Interface

Edit /etc/networks/interfaces and add the following (adjust interface names as necessary):

auto eth1
iface eth1 inet static
    address 10.0.0.10
    netmask 255.255.255.0

Save the file, then run:

ifdown eth1
ifup eth1

Task 2 - Install FreeRADIUS

Assuming your Internet connection / Kali disc is accessible, just run:

apt-get update
apt-get install freeradius

Task 3 - Configure FreeRADIUS

The FreeRADIUS config files are pretty big and are mostly full of examples that aren't relevant to this setup, so we'll just set them aside and create new ones from scratch. Firstly we will replace the clients.conf file which tells FreeRADIUS which devices are allowed to authenticate against it.

Firstly, ditch the old one:
mv /etc/freeradius/clients.conf /etc/freeradius/ORIG-clients.conf

Next, edit /etc/freeradius/clients.conf and add:

client 10.0.0.100/32 {
    secret        = b0dges
    shortname    = PE1
    nastype        = cisco
}

Save the file and exit. Now do a similar thing with the users file (which is used to define how the users will be authenticated):

mv /etc/freeradius/users /etc/freeradius/ORIG-users

Edit /etc/freeradius/users and add:

DEFAULT         Auth-Type := CHAP, Cleartext-Password := "password1"
                    Framed-Protocol = PPP,
                    Framed-IP-Address = 255.255.255.254
foeh@fixed      Auth-Type := CHAP, Cleartext-Password := "password2"
                    Framed-Protocol = PPP,
                    Framed-IP-Address = 192.168.100.1

Save the file and exit. Note that the special "255.255.255.254" address above instructs the access concentrator to assign an IP locally from its pool.

Task 4 - Restart FreeRADIUS with the New Config

Simply run:

service freeradius restart

The service should restart without error. That's the difficult RADIUS config done, now onto the access concentrator!

Stage 2 - Configure the Access Concentrator

I'll go into a little more detail on this part as it's not quite as intuitive. The base device here is an IOS 12.3 router, Cisco's licensing model is complex and seems to vary wildly between platforms so I'll let you poke around in feature navigator to work out which feature set and release will work on your device... It seems to work fine on a 3845 running security services if that helps.

Task 1 - Configure Interfaces

We need a couple of interfaces configured here:

• An interface towards RADIUS (obviously)
• A loopback interface (used to address the "unnumbered" PPPoE tunnel interfaces)
• A client interface (where the PPPoE users will attach)

interface FastEthernet1/0
 description To RADIUS
 ip address 10.0.0.100 255.255.255.0
 no shutdown
!
interface Loopback0
 description IP for Unnumbered Tunnel Interfaces
 ip address 1.1.1.1 255.255.255.255
!
interface FastEthernet0/1
 description To Clients
 no shutdown
!

We won't configure anything on the client interface for the moment but we will return to it momentarily...

Task 2 - Configure PPPoE

Firstly we need to configure a BBA group, which is just a way to associate a bunch of settings with a particular interface. We'll use the default "global" group and configure it to use virtual-template 1:

bba-group pppoe global
 virtual-template 1

Next, we need to define what Virtual-Template1 is. Virtual template interfaces are used to define a prototype on which to base the Virtual-Access (tunnel) interfaces which are automatically created when a PPPoE user connects. In this most simple of examples we just define where the interface's local IP address should be cloned from, where the PPPoE user's IP address should be allocated from and the authentication protocol we want to use:

interface Virtual-Template1
 ip unnumbered Loopback0
 peer default ip address pool localpool
 ppp authentication chap

The "peer default ip address" command above refers to a pool called "localpool", so we'd better create that:

ip local pool localpool 172.16.0.1 172.16.0.100

Now that we've defined all that good stuff, we need to apply the BBA group to the client interface:

interface FastEthernet0/1
 pppoe enable group global

Pretty simple so far and, in fact, that's most of the config done. All we need to do now is to...

Task 3 - Point the Router at the RADIUS

There are three relatively straightforward steps here, firstly we have to enable AAA new model on the device and then define the RADIUS server details (note, FreeRADIUS' ports differ from Cisco's defaults so we need to specify them):

aaa new-model
radius server kali
 address ipv4 10.0.0.10 auth-port 1812 acct-port 1813
 key b0dges

Then we have to tell the router to go to RADIUS when authenticating PPPoE users:

aaa authentication ppp default group radius
aaa authorization network default group radius

The second line is not necessary for dynamic IP users but instructs the router that it should allow RADIUS to tell it what the user's IP (and some other things) should be. If you leave out the last line then users with a RADIUS defined static IP will get one out of the pool like everyone else, so if RADIUS Framed-IP attributes are being ignored this is probably the cause.

Note: You may want to configure some local usernames for access to the CLI and add "aaa authentication login default local" or similar.

At this point, your PPPoE Access Concentrator with RADIUS authentication is ready for use!

If you're unsure how to set up a client, I've also written quick build posts for that:

• On IOS
• On JunOS

Debugging

No build would be complete without a little bit of debugging. This is such a straightforward setup that, barring layer 3 issues, there's not a lot that can go wrong. Troubleshooting would pretty much be as follows:

• Verify that you are getting PPPoE control traffic in from your client (debug pppoe packet, debug pppoe event). The sequence should be PADI, PADO, PADR, PADS. PADT indicates someone is pulling down the session, the debugs should show you who!
• Check IP reachability to the RADIUS box using ping
• Verify that FreeRADIUS is running (ps -aux | grep freeradius), start it if necessary (/etc/init.d/freeradius start)
• If your client can't authenticate, check the password matches what's in FreeRADIUS (/etc/freeradius/users), not forgetting to restart FreeRADIUS if you make changes (/etc/init.d/freeradius restart)
• If the passwords match but you are still getting authentication errors, verify that your secrets match between the router ("key" under "radius-server") and FreeRADIUS (/etc/freeradius/clients.conf), the NAS IP matches your router and that FreeRADIUS has been restarted since the last change (/etc/init.d/freeradius restart)
•  Check your PPP is negotiating OK (debug ppp negotiation)

Some more tips that may be helpful can be found on my post about debugging Cisco PPPoE clients.

Quick build - PPPoE Client on Cisco IOS

In this quick-build guide I'll show you how to set up a very basic IOS-based PPPoE client. This example is from a Cisco 819 router, however the config is pretty much the same on most ISR type devices. As usual, the build will cover the most simple common use case (no VLAN tags, dynamic AC selection, negotiated IP).

Note, if you want a PPPoE access concentrator to go with your client, you may find the Quick Build: Cisco IOS PPPoE Server with RADIUS Authentication post useful.

The Setup

The PPPoE client is basically set up in two parts - the first being the physical interface which will connect towards the access concentrator, the second being a dialer interface that will become instantiated when the PPPoE session comes up. We'll build the physical interface first, as follows:

interface GigabitEthernet0
 description To AC
 pppoe enable pppoe-client dial-pool-number 1
 no shutdown
!

Pretty minimal... turn PPPoE on, and tell it which dialer pool to use. Note, in older versions of IOS the command was simply "pppoe-client dial-pool-number 1". Next, we have to configure the dialer interface, as follows:

interface Dialer1
 ip address negotiated
 encapsulation ppp
 dialer pool 1
 dialer-group 1
 ppp authentication chap callin
 ppp chap hostname user@domain
 ppp chap password 0 b0dges
!
dialer-list 1 protocol ip permit
ip route 0.0.0.0 0.0.0.0 Dialer1

This creates the dialer interface that we will use, tells it to use PPP and to pick up its IP address dynamically.

The "dialer pool" command places this dialer into the pool where the physical interface was set to look, while the "dialer-group" command specifies which dialer-list will be used to decide what traffic is interesting (i.e. will bring or keep the PPPoE session up).

The PPP commands force the authentication type to CHAP, specify that we will not make the AC authenticate to us (generally not supported) and set the CHAP hostname (think username) and password.

Finally, the dialer-list referred to in the earlier "dialer-group" command is defined to match any IP traffic at all, before a static route is used to force traffic out of the dialer interface.

That really is all that you need! In real life you will probably need to add NAT statements and you will definitely need at least one other interface, but that's the PPPoE part done.

Debugging

There's an entire post dedicated to this subject, but the short version is as follows:

• Verify that you are getting PPPoE control traffic between your client and the server (debug pppoe packet, debug pppoe event). The sequence should be PADI, PADO, PADR, PADS. PADT indicates someone is pulling down the session, the debugs should show you who!
• Check the static route has installed in your routing table as traffic will only trigger the PPP up if it hits the interface (show ip route)
• Verify that there is at least one "up" IP interface on the box other than the dialer. If there's no source address usable then any test traffic will fail to encapsulate and you won't be able to bring PPP up. (show ip interfaces brief)
• If your client can't authenticate, check the credentials (both hostname and password under the Dialer interface) and ensure that the authentication type is CHAP in "callin" mode.
•  Check your PPP is negotiating OK (debug ppp negotiation)

Removing VLAN/MPLS/PPPoE/GRE/GTP/VXLAN Encapsulation Headers from pcap Files

Many years ago, when I worked in a school, I used to port mirror our proxy server to an old PC running driftnet and leave the screen where the kids could see it as a warning that staff could "see what you're doing on the Internet". I haven't played with driftnet since but certainly at the time it could only handle native frames (no VLAN tags, certainly no MPLS or PPPoE). I vaguely remember some other tools being similar, unfortunately I can't remember which ones.

Looking at the analytics for this blog, I can see I'm not the only one who's had the problem. It's certainly not the number one issue that people are searching for when they get here but there have been a few and the thought occurred that the packet processing engine I wrote for dechap would be really good for this task - it already stripped back VLANs and MPLS, plus it knows how to detect PPPoE and L2TP.

After a couple of hours it was working to the point of being able to strip VLANs and MPLS off, with a little more effort PPPoE also gave way. GRE came quite easily, too, as it has simple headers and uses the same etypes as Ethernet.

Anyway, here is "stripe" (from STRIP Encapsulation), a command line tool which takes a pcap file as input, re-assembles IP fragments and strips off all the encap it can (currently VLAN tags, MPLS shim headers, PPPoE, L2TP, GRE GTP and VXLAN) then outputs another pcap containing just payload over Ethernet.

**UPDATE** - Version 0.3b now adds support for VXLAN.

Download

Stripe is available from my github: https://github.com/theclam/stripe

Usage

The command line is pretty straightforward, as shown in the online help:

Harrys-MacBook-Air:stripe foeh$ ./stripe
stripe: a utility to remove VLAN tags, MPLS shims, PPPoE, L2TP headers,
etc. from the frames in a PCAP file and return untagged IP over Ethernet.
Version v0.1 alpha, November 2014

Usage:
./stripe -r inputcapfile -w outputcapfile

Where inputcapfile is a tcpdump-style .cap file containing encapsulated IP 
outputcapfile is the file where the decapsulated IP will be saved

Harrys-MacBook-Air:stripe foeh$ 

Simply specify the files you want to read encapsulated packets from (-r) and write the cleaned up packets to (-w). Stripe will remove as many layers of encap as it can until you are left with straight payload over Ethernet.

How it Works

The majority of stripe's work is done by the "decap" function. This function takes in a block of memory, a length parameter, a data type hint and a frame template. The process runs as follows:

1. If the type is Ethernet, populate the source / destination MACs of the frame template
2. If the type has an Ethertype or protocol type field, use this to populate the ethertype of the frame template
3. If the next protocol is possibly or definitely payload, set the payload pointer of the frame template to the address of the next protocol and return
4. If the next protocol is possibly or definitely encapsulation, call decap against the remainder of the packet

So essentially it eats up encap, recording MACs and protocol types as it goes, until there is no more encap left. By the end there is a fully populated frame template with source and destination MAC (the innermost copy if there are multiple as in the case of MPLS pseudowires), the etherype of the payload and the payload itself. Piecing these together gives a minimally encapsulated frame, i.e. one with just an Ethernet header and payload.

Here is a worked example for a frame with VLAN, MPLS, GRE over IP and an IP payload:

Step 1 - The "decap" function is called on the entire frame. Since the first header is Ethernet, the frame template gets populated with the source / destination MACs and the etype from the Ethernet header. The frame template's length field gets populated with the size of the frame minus the Ethernet header and the payload pointer is adjusted to point at the next header. The decap function then calls itself on the remainder of the frame, hinting that the type is VLAN tag based on the current header's etype.

Step 2 - The decap function now considers the partial frame starting at the VLAN tag. Since the VLAN tag has an etype associated, the frame template's etype is overwritten with the one from the VLAN header. The length is overwritten with the length of the payload after the VLAN header and the pointer adjusted to point at the next header. The decap function then calls itself again with a hint of MPLS, based on the etype in the VLAN header.

Step 3 - The decap function now considers the partial frame starting at the MPLS label. Since the MPLS label is bottom of stack, we know there are no more MPLS labels left . Unfortunately there is no protocol type in an MPLS header (these are signaled on the control plane) so we have to take a peek at the byte immediately following the label. If we find a "4" or a "6" in the high order nibble then we have to guess that the next protocol is IPv4 or IPv6, respectively. If the following four bytes are all zeroes then we assume Ethernet over MPLS with control word, otherwise we assume Ethernet over MPLS without control word. In this case we find a 4 in the low nibble, so call decap with an "IP" hint.

Step 4 - The IP header tells us that GRE is the next protocol so for now nothing changes in the frame template (the remainder could be decodable or not). We just call decap again on the GRE part...

Step 5 - The GRE header is decoded and the etype is copied into the frame header. The length of the remaining payload is updated in the frame template and the pointer is adjusted. Decap is called on the next header, which is IP. When the decap function inspects the IP payload it can go no further and just returns the frame template.

In essence, the process has started with a deeply encapsulated frame and ended with IP over Ethernet. The source and destination MACs are taken from the innermost ones found (which in this case is the outermost Ethernet header) but with the etype changed to match the payload, which is the first non-encapsulating payload found in the frame, in this case the second IP.

References

https://tools.ietf.org/html/rfc2784
https://tools.ietf.org/html/rfc1701
http://www.ieee802.org/1/pages/802.1Q.html
http://www.3gpp.org/DynaReport/29060.htm

Troubleshooting PPPoE Client on Cisco Routers

There are are essentially a handful of stages involved in bringing up a PPPoE client session on a Cisco router, each of which could fail for a distinct set of reasons. This guide takes a walk through the entire process, step by step, highlighting the most common causes of problems at each stage.

Routing

Even though PPP itself is peer to peer, PPPoE is inherently client-server. That means that the connection has to be originated by the client and, in most cases, the client will only do that when it has some traffic to send over PPPoE. Therefore, the router must know the dialer as its next hop interface for some destination, i.e. it must have a route. It sounds trivial but it's surprising how often people go to all the trouble of putting in a perfectly good PPPoE config, then forget to put a default route in for the traffic!

More broadly, though, there are other things that could stop a route from being installed. For example, if you configure a dialer as a backup interface to another interface then there are some gotchas. Shutting down the primary will usually not enable its backup, also you still need a (static) route pointing traffic towards the dialer in order to make it dial - a step which is often forgotten. It's usually best to remove the backup interface configuration while testing the dialer, then re-apply it when that has been proven to work.

Dialer

Once traffic hits the dialer interface, the router will only attempt to bring up a PPPoE session if its dialer becomes activated. If a route exists but the dialer is not trying to connect then enable dialer debugging as follows:

Client#debug dialer packet
Dial on demand packets debugging is on
Client#debug dialer event
Dial on demand events debugging is on

Now generate some traffic that should bring up the link, for example by sending a ping:

Client#ping 8.8.8.8
Type escape sequence to abort.
Sending 5, 100-byte ICMP Echos to 8.8.8.8, timeout is 2 seconds:
*Nov  5 21:44:34.147: Di0 DDR: ip (s=10.10.10.10, d=8.8.8.8), 100 bytes, outgoing interesting (ip PERMIT)
*Nov  5 21:44:34.151: Di0 DDR: Cannot place call, no dialer string set.
*Nov  5 21:44:41.491: %DIALER-6-BIND: Interface Vi2 bound to profile Di0
*Nov  5 21:44:41.503: %LINK-3-UPDOWN: Interface Virtual-Access2, changed state to up
*Nov  5 21:44:41.503: Vi2 DDR: Dialer statechange to up
Client#
*Nov  5 21:44:42.195: %LINEPROTO-5-UPDOWN: Line protocol on Interface Virtual-Access2, changed state to up
Client#

*Nov  5 21:44:42.371: Vi2 DDR: dialer protocol up

When the "dialer protocol up" message is received, the dialer has been activated correctly and troubleshooting should move on to the PPPoE stage.

Common problems:

• If no debug messages are generated at all:
• Verify that traffic is being routed towards the dialer interface
• Verify that the dialer-list is configured correctly and referenced by the dialer
• Verify that the dialer's encapsulation is configured to ppp
• Di0 DDR: Cannot place call, no dialer string set. 
• Appears to be spurious, no dialer string is required for PPPoE and it dials anyway
• Di0 DDR: ip (s=10.10.10.10, d=8.8.8.8), 100 bytes, outgoing uninteresting (no dialer-group defined).
• Exactly what it says - dialer is not associated with a dialer list. Ensure a dialer-list is configured and is referred to by the dialer with the "dialer-group x" command.
• Di0 DDR: ip (s=10.10.10.10, d=8.8.8.8), 100 bytes, outgoing uninteresting (dialer-list 2 not defined).
• Again, exactly what it says. The dialer is associated with a non-existent dialer-list. Either re-point the dialer using the "dialer-group x" command or create a new dialer-list with the appropriate number.
• Di0 DDR: ip (s=10.10.10.10, d=8.8.8.8), 100 bytes, outgoing interesting (ip PERMIT)
• Repeated interesting traffic lines but no dialling can occur if the dialer references an empty dialer pool - ensure your PPPoE interface is configured with both "pppoe enable" and "pppoe-client dial-pool-number x". Also ensure that the interface is admin up.
• Could also be due to PPPoE discovery phase failing, see below.

PPPoE Discovery

In order to bring up a PPP session over Ethernet, a PPPoE session must be set up to create a point-to-point connection over a broadcast Ethernet network. This is established using PPPoE Auto-Discovery, where the PPPoE client (our router) searches for a PPPoE access concentrator which is willing to terminate its connection. This phase should operate as follows:

PPPoE Discovery Phase

The client sends a PPPoE Auto Discovery Initiate (PADI) frame, asking any available access concentrators to make themselves known. The access concentrator(s) then respond(s) with a PADO (offer) frame to indicate its availability. The client then sends a PADR (request) frame to its chosen access concentrator which, all being well, will respond with a PADS (session) message to indicate that the PPPoE session is now up. At any time either device may issue a PADT to close the PPPoE session.

To see what is happening at this stage, run the following command:

Client#debug pppoe packet

*Nov  5 20:38:52.107: pppoe_send_padi: 
contiguous pak, size 60
FF FF FF FF FF FF 00 01 02 03 04 05 88 63 11 09
00 00 00 10 01 01 00 00 01 03 00 08 2A 00 00 01
00 00 06 CD 00 00 00 00 00 00 00 00 00 00 00 00
00 00 00 00 00 00 00 00 00 00 00 00
*Nov  5 20:38:52.143: PPPoE 0: I PADO  R:0011.2233.4455 L:0001.0203.0405 Fa0/0
contiguous pak, size 66
00 01 02 03 04 05 00 11 22 33 44 55 88 63 11 07
00 00 00 2E 01 01 00 00 01 03 00 08 2A 00 00 01
00 00 06 CD 01 02 00 06 4C 61 62 2D 41 43 01 04
00 10 D5 60 38 B8 05 81 B6 69 29 1B 5E 82 77 A0
5E 91
*Nov  5 20:38:54.155: OUT PADR from PPPoE Session
contiguous pak, size 66
00 11 22 33 44 55 00 01 02 03 04 05 88 63 11 19
00 00 00 2E 01 03 00 08 2A 00 00 01 00 00 06 CD
01 02 00 06 4C 61 62 2D 41 43 01 04 00 10 D5 60
38 B8 05 81 B6 69 29 1B 5E 82 77 A0 5E 91 01 01
00 00
*Nov  5 20:38:54.355: PPPoE 14: I PADS  R:0011.2233.4455 L:0001.0203.0405 Fa0/0
contiguous pak, size 66
00 01 02 03 04 05 00 11 22 33 44 55 88 63 11 65
00 0E 00 2E 01 03 00 08 2A 00 00 01 00 00 06 CD
01 02 00 06 4C 61 62 2D 41 43 01 04 00 10 D5 60
38 B8 05 81 B6 69 29 1B 5E 82 77 A0 5E 91 01 01
00 00
*Nov  5 20:38:54.363: [0]PPPoE 0: O PADT  R:0000.0000.0000 L:0000.0000.0000 Fa0/0
contiguous pak, size 60
00 00 00 00 00 00 00 01 02 03 04 05 88 63 11 A7
00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
00 00 00 00 00 00 00 00 00 00 00 00

Client#

The mark of a successful PPPoE Discovery phase is that a PADS packet is received - at this point the PPPoE session is up and troubleshooting focus should shift to the PPP stage.

Common problems:

• Only PADI seen:
• Layer 1 or 2 issue between client and server
• PPPoE traffic being filtered between client and server, max sessions per MAC exceeded
• Sometimes possible even if interface is admin down!
• PADT messages received after PADI or PADR:
• Restrictions on Access Concentrator (e.g. max sessions per MAC exceeded)
• PADT message received after PADS:
• Generally a problem further up the stack, continue troubleshooting

Note - PPPoE discovery may occur without the dialer even being activated.

PPP Negotiation (LCP)

With the PPPoE session up, Link Control Protocol (LCP) will attempt to negotiate the parameters for the actual PPP session. These include useful parameters such as the MRU and authentication type, plus potentially many less applicable parameters such as callback, compression or PPP multilink.

The process is that each side will send proposals (CONFiguration REQuests or CONFREQs) to the other indicating its preferred settings. The opposite device can then respond in one of the following ways:

• Send a CONFiguration ACKnowledgement (CONFACK) to indicate agreement to the proposal
• Send a CONFiguration Negative AcKnowledgement (CONFNAK) to indicate a particular setting should be changed and providing a suggested alternative value. If multiple values need to change, there will be multiple CONFNAKs.
• Send a CONFiguration REJect (CONFREJ) to indicate that either the type or the value of the parameter proposed is completely unacceptable.

Only once all the parameters are agreed between the two peers can the connection be established and higher layer protocols be negotiated. Bear in mind that PPP is inherently peer to peer, so both sides will play the roles of both requester and approver / rejecter.

To see what is happening at this stage, run the following command:

Client#debug ppp negotiation
PPP protocol negotiation debugging is on
*Nov  5 22:11:39.191: %DIALER-6-BIND: Interface Vi2 bound to profile Di0
*Nov  5 22:11:39.207: %LINK-3-UPDOWN: Interface Virtual-Access2, changed state to up
*Nov  5 22:11:39.211: Vi2 PPP: Sending cstate UP notification
*Nov  5 22:11:39.219: Vi2 PPP: Processing CstateUp message
*Nov  5 22:11:39.251: PPP: Alloc Context [670153F8]
*Nov  5 22:11:39.255: ppp22 PPP: Phase is ESTABLISHING
*Nov  5 22:11:39.259: Vi2 PPP: Using dialer call direction
*Nov  5 22:11:39.259: Vi2 PPP: Treating connection as a callout
*Nov  5 22:11:39.263: Vi2 PPP: Session handle[F4000016] Session id[22]
*Nov  5 22:11:39.263: Vi2 LCP: Event[OPEN] State[Initial to Starting]
*Nov  5 22:11:39.267: Vi2 PPP: No remote authentication for call-out
*Nov  5 22:11:39.267: Vi2 LCP: O CONFREQ [Starting] id 1 len 10
*Nov  5 22:11:39.271: Vi2 LCP:    MagicNumber 0x03BD43E3 (0x050603BD43E3)
*Nov  5 22:11:39.271: Vi2 LCP: Event[UP] State[Starting to REQsent]
*Nov  5 22:11:39.323: Vi2 LCP: I CONFREQ [REQsent] id 1 len 19
*Nov  5 22:11:39.323: Vi2 LCP:    MRU 1492 (0x010405D4)
*Nov  5 22:11:39.327: Vi2 LCP:    AuthProto CHAP (0x0305C22305)
*Nov  5 22:11:39.327: Vi2 LCP:    MagicNumber 0x02C2DFB3 (0x050602C2DFB3)
*Nov  5 22:11:39.331: Vi2 LCP: O CONFNAK [REQsent] id 1 len 8
*Nov  5 22:11:39.331: Vi2 LCP:    MRU 1500 (0x010405DC)
*Nov  5 22:11:39.335: Vi2 LCP: Event[Receive ConfReq-] State[REQsent to REQsent]
*Nov  5 22:11:39.395: Vi2 LCP: I CONFACK [REQsent] id 1 len 10
*Nov  5 22:11:39.395: Vi2 LCP:    MagicNumber 0x03BD43E3 (0x050603BD43E3)
*Nov  5 22:11:39.399: Vi2 LCP: Event[Receive ConfAck] State[REQsent to ACKrcvd]
*Nov  5 22:11:39.439: Vi2 LCP: I CONFREQ [ACKrcvd] id 2 len 19
*Nov  5 22:11:39.439: Vi2 LCP:    MRU 1500 (0x010405DC)
*Nov  5 22:11:39.443: Vi2 LCP:    AuthProto CHAP (0x0305C22305)
*Nov  5 22:11:39.443: Vi2 LCP:    MagicNumber 0x02C2DFB3 (0x050602C2DFB3)
*Nov  5 22:11:39.447: Vi2 LCP: O CONFACK [ACKrcvd] id 2 len 19
*Nov  5 22:11:39.447: Vi2 LCP:    MRU 1500 (0x010405DC)
*Nov  5 22:11:39.451: Vi2 LCP:    AuthProto CHAP (0x0305C22305)
*Nov  5 22:11:39.451: Vi2 LCP:    MagicNumber 0x02C2DFB3 (0x050602C2DFB3)
*Nov  5 22:11:39.455: Vi2 LCP: Event[Receive ConfReq+] State[ACKrcvd to Open]
*Nov  5 22:11:39.467: Vi2 PPP: Phase is AUTHENTICATING, by the peer
*Nov  5 22:11:39.467: Vi2 LCP: State is Open
Client#

To explain the above transaction, I have highlighted the two conversations in different colours. "O" indicates an outbound frame, "I" an inbound frame.

The blue conversation is what we (the client) are proposing to the access concentrator. The client sends an essentially empty proposal with only a magic number (used for loop detection). The access concentrator responds with an acknowledgement, after all there's nothing to argue about!

The red conversation (where the access concentrator is proposing settings) is slightly more interesting. The first proposal contains a proposed maximum receive unit (MRU) size of 1492 and a proposal to use CHAP authentication. In the next frame our client sends a NAK message to indicate it would prefer the access concentrator used an MRU of 1500. Following that, the access concentrator sends a new proposal with an MRU of 1500 and CHAP authentication, which our client then acknowledges.

Now that both sides are in agreement, the state changes to "Open", which is PPP talk for "up".

Common Problems:

• MRU mismatch - many access concentrators are strictly RFC 2516 compliant and allow a maximum MRU of 1492. This is because 1492 bytes IP + 6 bytes PPPoE + 2 bytes PPP is the largest that can fit inside a standard 1500 byte Ethernet payload. It may be necessary to tweak the MTU on the Ethernet interface using the "pppoe-client ppp-max-payload xxxx" command.
• Authentication type mismatch - if one peer is set for CHAP only while the other is set to PAP only or no authentication, they are not going to talk. A common mistake is forgetting the authentication callin option, which means that the client asks the server to authenticate itself - this is almost invariably not.

General Note:

If you examine the debug output, it will be clear what the local device is saying (marked with "O" for output) and what the other end is saying (marked with "I" for input). Whichever options are being rejected (CONFREJ'd) will be at the root of the problem - just work out which end is rejecting what and the rest should fall into place.

PPP Authentication

PPP has the ability to authenticate either, both or neither of the peers. In a typical deployment, the access concentrator will require the client to authenticate, but will refuse to authenticate itself to the client. This is typically done using CHAP as in the example below (output from "debug ppp negotiation"):

*Nov  5 22:11:39.259: Vi2 PPP: Treating connection as a callout
*Nov  5 22:11:39.263: Vi2 PPP: Session handle[F4000016] Session id[22]
*Nov  5 22:11:39.263: Vi2 LCP: Event[OPEN] State[Initial to Starting]
*Nov  5 22:11:39.267: Vi2 PPP: No remote authentication for call-out
-- SNIP --
*Nov  5 22:11:39.467: Vi2 PPP: Phase is AUTHENTICATING, by the peer
*Nov  5 22:11:39.527: Vi2 CHAP: I CHALLENGE id 1 len 27 from "Lab-AC"
*Nov  5 22:11:39.543: Vi2 CHAP: Using hostname from interface CHAP
*Nov  5 22:11:39.543: Vi2 CHAP: Using password from interface CHAP
*Nov  5 22:11:39.543: Vi2 CHAP: O RESPONSE id 1 len 30 from "pppoeuser"
*Nov  5 22:11:39.835: Vi2 CHAP: I SUCCESS id 1 len 4
*Nov  5 22:11:39.839: Vi2 PPP: Phase is FORWARDING, Attempting Forward

The output clearly shows that this connection is considered to be a "callout", i.e. we are the initiating party. Next, the debug informs us that we do not require the remote party to authenticate.

Following that, the peer (the access concentrator) asks us to authenticate. It sends us a "CHALLENGE", we send a "RESPONSE", then it sends us a "SUCCESS" message, indicating that our credentials were accepted.

Common problems:

• It is worth noting the lines which state we are using the hostname and password from interface CHAP. This means that the hostname (in practice essentially a username) and password are configured under the dialer interface with the "ppp chap hostname xxx" and "ppp chap password xxxx". If these are not specified, the router will use its actual hostname and the password will be taken from the local user database, under a user named after the the peer's hostname. Usually that's not what you want.
• A response of "CHAP: I FAILURE id 1 len 25 msg is "Authentication failed"" means exactly what it looks like it means. Check both the username and password are configured correctly.
• A response of "CHAP: Unable to authenticate for peer" indicates that the device does not  know what password to use to authenticate with the peer. This can be because a "ppp chap hostname" is configured but a "ppp chap password" is not, there is not even a "ppp chap hostname" configured or in the case where local usernames are being used it means there's no local username which matches the AC's hostname.

IPCP

Once the PPP session has been brought up (negotiated through LCP), the next stage is to negotiate each of the protocols that will run through the PPP tunnel. Normally this is just IPv4, which is negotiated using IPCP, but there are also IPv6CP, CDPCP and so on, collectively known as Network Control Protocols or NCPs. Below is some example debug (output from "debug ppp negotiation"), with the AC's IP negotiation in blue and the client's IP negotiation in red:

*Nov  5 22:11:39.867: Vi2 PPP: Queue IPCP code[1] id[1]
*Nov  5 22:11:39.883: Vi2 PPP: Phase is ESTABLISHING, Finish LCP
*Nov  5 22:11:39.887: %LINEPROTO-5-UPDOWN: Line protocol on Interface Virtual-Access2, changed state to up
*Nov  5 22:11:39.899: Vi2 PPP: Phase is UP
*Nov  5 22:11:39.903: Vi2 IPCP: Protocol configured, start CP. state[Initial]
*Nov  5 22:11:39.903: Vi2 IPCP: Event[OPEN] State[Initial to Starting]
*Nov  5 22:11:39.907: Vi2 IPCP: O CONFREQ [Starting] id 1 len 10
*Nov  5 22:11:39.907: Vi2 IPCP:    Address 0.0.0.0 (0x030600000000)
*Nov  5 22:11:39.911: Vi2 IPCP: Event[UP] State[Starting to REQsent]
*Nov  5 22:11:39.915: Vi2 PPP: Process pending ncp packets
*Nov  5 22:11:39.915: Vi2 IPCP: Redirect packet to Vi2
*Nov  5 22:11:39.915: Vi2 IPCP: I CONFREQ [REQsent] id 1 len 10
*Nov  5 22:11:39.919: Vi2 IPCP:    Address 1.1.1.1 (0x030601010101)
*Nov  5 22:11:39.923: Vi2 IPCP: O CONFACK [REQsent] id 1 len 10
*Nov  5 22:11:39.923: Vi2 IPCP:    Address 1.1.1.1 (0x030601010101)
*Nov  5 22:11:39.927: Vi2 IPCP: Event[Receive ConfReq+] State[REQsent to ACKsent]
*Nov  5 22:11:39.987: Vi2 IPCP: I CONFNAK [ACKsent] id 1 len 10
*Nov  5 22:11:39.987: Vi2 IPCP:    Address 172.16.0.6 (0x0306AC100006)
*Nov  5 22:11:39.991: Vi2 IPCP: O CONFREQ [ACKsent] id 2 len 10
*Nov  5 22:11:39.991: Vi2 IPCP:    Address 172.16.0.6 (0x0306AC100006)
*Nov  5 22:11:39.995: Vi2 IPCP: Event[Receive ConfNak/Rej] State[ACKsent to ACKsent]
*Nov  5 22:11:40.055: Vi2 IPCP: I CONFACK [ACKsent] id 2 len 10
*Nov  5 22:11:40.059: Vi2 IPCP:    Address 172.16.0.6 (0x0306AC100006)
*Nov  5 22:11:40.059: Vi2 IPCP: Event[Receive ConfAck] State[ACKsent to Open]
*Nov  5 22:11:40.071: Vi2 IPCP: State is Open
*Nov  5 22:11:40.075: Di0 IPCP: Install negotiated IP interface address 172.16.0.6
*Nov  5 22:11:40.131: Di0 Added to neighbor route AVL tree: topoid 0, address 1.1.1.1
*Nov  5 22:11:40.135: Di0 IPCP: Install route to 1.1.1.1

Common Problems:

• If no IPCP appears at all, it could be that both ends have "ppp ncp passive" set.

• If you see a message similar to "O PROTREJ [Open] id 2 len 16 protocol IPCP (0x0101000C030601010101)" this is because IP is not configured on the local dialer interface. Usually you just want to add "ip address negotiated" under the dialer to fix this.

At this point your session is up and you should be able to pass traffic OK. If you're still looking, it may help to read my blog post on the theory behind bringing up a PPPoE session.

References

http://tools.ietf.org/html/rfc2516 (PPPoE)
http://tools.ietf.org/html/rfc4638 (PPPoE large MRU)
http://tools.ietf.org/html/rfc1661 (PPP)

BGP support added to dechap

Hot on the heels of adding the ability to attack OSPF MD5 authentication, I've added BGP support to dechap. It is now possible to feed a pcap file with PPPoE, L2TP, RADIUS, OSPF and BGP packets to the same tool and perform offline dictionary attacks on the authentications within.

As usual, if you're not interested in the theory just skip right to the end for the download link.

TCP MD5 Signatures

BGP authentication uses the MD5 Signature TCP option field, which is defined in RFC 2385. Personally, I found this RFC very vague and it took a lot of iterations to get the technique right. It's particularly fuzzy about what is included in the hash, what isn't and how to present values correctly. I'm hoping to document the process a little more clearly for the next poor guy who tries to implement it as I couldn't find a sufficiently detailed reference anywhere.

RFC 2385 states that the hash must be calculated over the following:

1. the TCP pseudo-header (in the order: source IP address,
   destination IP address, zero-padded protocol number, and
   segment length)
2. the TCP header, excluding options, and assuming a checksum of
   zero
3. the TCP segment data (if any)
4. an independently-specified key or password, known to both TCPs
   and presumably connection-specific

Now, maybe it's just me, but this raised a lot of questions in my mind. Zero padding usually means to fill the trailing space with zeros, but padding the second byte would effectively multiply the protocol number by 256 so should it be a leading zero? Which headers and options are included in the "segment length"? Should the pad bytes be copied with the TCP header?

Through a lot of trial and error I found that:

• The zero padding goes before the protocol number
• The "segment length" includes the TCP header, the TCP options (including room for the MD5 signature option being calculated) and the actual payload data
• The copied TCP header should be 20 bytes long, i.e. includes two padding bytes after the (zeroed out) checksum. The header length remains as-is, including the length of the options.
• The TCP segment data starts immediately after the TCP options and runs to the last byte indicated by the IP length field
• The null byte terminating the password is not passed to the hash algorithm

 The resulting hash value is then stored inside the MD5 signature option (kind 19, length 18).

Checking / Attacking BGP Packets

Using the above method it is straightforward to run a dictionary attack as follows:

• Start with a sniffed BGP packet (see the original dechap blog post for info on how this is extracted).
• Extract and store the authentication hash (look for option kind 19) for later comparison
• Put together the "pseudoheader" as described above
• Append the TCP header without options
• Append the TCP payload
• Append the candidate password
• Calculate the MD5 hash over the complete data set and compare to the value seen in the sniffed packet. A matching hash indicates a matching password.

As of v0.4a, dechap can now be used to automate this process.

Obtaining the Tool

The C source code may be downloaded from: https://github.com/theclam/dechap

Provided the OpenSSL dev libraries are installed it should be possible to simply extract the source code, cd into the directory then run "make". I've only tested this under Ubuntu Linux but there are very few dependancies so I would imagine it will work on most distributions.

Using the Tool

As usual - this is for legitimate audit and recovery purposes and must not be used for any kind of malicious activity.

The usage is pretty straightforward - there are only two parameters and both are mandatory. Specify your capture file (original pcap format) with the -c flag and your word list with the -w flag. Here's an example:

lab@lab:~/dechap$ ./dechap -w mywords.txt -c bgp.cap
Found password "password1" for TCP from 10.0.0.2 to 10.0.0.1.
Found password "password1" for TCP from 10.0.0.1 to 10.0.0.2.
Found password "password1" for TCP from 10.0.0.2 to 10.0.0.1.lab@lab:~/dechap$
I'm not sure how quickly it runs but it doesn't seem quite as quick as the OSPF version. I suppose BGP packets tend to be a little bigger than OSPF so there's more to hash. You can improve the speed by only including one packet for each source / destination pair in each capture as, at present, it doesn't check for multiple packets between pairs and attacks each instance individually.

If you try this out, please leave a comment on this post with your experiences - good or bad. Any suggestions would also be welcome, particularly for other protocols to attack.

References

RFC2385 - Protection of BGP Sessions via the TCP MD5 Signature Option
RFC1321 - The MD5 Message-Digest Algorithm

Recovering CHAP Passwords from Sniffed PPPoE Sessions

In a previous blog post I outlined the theory behind setting up a PPPoE session including PPPoE discovery, LCP, NCPs and, more relevant to this post, the basics of CHAP authentication. At the time I was writing the post I wondered how easy it would be to work back from the CHAP messages on the wire to the original credentials, so I decided to find out.

Recap of CHAP Theory

As a reminder (or a very quick introduction), the CHAP process works something like this:

CHAP Authentication

1. The party requiring the opposite peer to authenticate (i.e. "server") sends a CHAP challenge message containing a challenge ID and some unpredictable "random" data.
2. The party being authenticated (i.e. "client") concatenates the authentication ID, the password and the challenge data into a single unit, then generates an MD5 hash of that. The resulting hash, plus the client name (user ID or hostname) is passed to the server as a CHAP response.
3. The server compares the incoming hash to the value it obtains by performing the same calculation locally and returns a CHAP success or CHAP failure message.

Now, clearly, if the CHAP challenge and response messages can be captured then an offline brute force attack can be mounted against the password. This can be achieved by simply extracting the authentication ID, challenge data and response from the relevant messages and then trying candidate passwords until one (hopefully) generates a hash identical to that seen in the response message.

The Attack in Practice

While the process is intuitively simple, as usual there are a few corner cases to cover. Recovering CHAP authentications from a capture file full of other junk requires a certain amount of processing logic, then responses must be re-united with their corresponding challenges before they can be attacked.

Gathering CHAP Packets

I wanted the tool to be flexible with regards to encap. Since I work primarily on carrier networks, I get really frustrated by tools that do a job perfectly but only accept untagged, unencapsulated frames. Once you have a packet capture in your hand, realising that it can't be used because it has two VLAN tags and a pair of MPLS labels is a nuisance.

The approach that seemed most sensible was to build a recursive decap function which would take in a (partial) frame plus a "hint" as to what type of header to expect. The function would then check for and record any matching criteria present (i.e. MACs for Ethernet, VLAN ID for 802.1Q - more on this in the next section) before either returning or calling itself on the remainder of the packet with a "hint" derived from the current header.

Worked Example

Let's process the following frame as an example. Data in black are used by the algorithm while data in grey are not.

The initial call to the function passes the entire frame with an "Ethernet" hint. In the Ethernet header, the source and destination MAC addresses are read and stored. The EtherType field contains 0x8100, indicating an 802.1Q VLAN header is next. The function calls itself against the contents of the frame from byte 15 and on with a hint of "VLAN".

Now the function reads and stores the VLAN ID. Since this is the first VLAN we have seen it is stored as the C-VLAN for now. The EtherType is, again, 0x8100 so the function calls itself against bytes 5 and onward using a hint of "VLAN".

Again,  the function reads and stores the VLAN ID. Since this is not the first VLAN tag found, the previously known VLAN ID is moved into the S-VLAN field and the value from the frame is stored in the C-VLAN field. This time the EtherType is 0x8864, indicating a PPPoE session header follows. The function calls itself against bytes 5 and onwards using a hint of "PPPoE".

The function now reads and stores the PPPoE session ID (SID). The only valid thing to follow a PPPoE session header is a PPP header, so the function calls itself on bytes 7 and onward, using a hint of "PPP".

The function now simply checks that the protocol ID in the PPP header is 0xC223 for CHAP. If so, it calls itself one last time against bytes 3 and onward using a hint of CHAP.

Finally we are down to the payload. The CHAP message type is checked and:

• For challenges, the authentication ID, challenge length and challenge data are stored.
• For responses, the authentication ID, response and client name are stored.

Each instance of the function can then return to its parent, eventually resulting in a fully populated record of all the data relevant to authentication. The completed records can then be stored in a doubly linked list for later consumption.

Pairing Up

A CHAP response must be paired up with its respective CHAP challenge, otherwise the maths don't work. In real life there may be several authentications in progress at one time across multiple PPPoE sessions, possibly over multiple different VLANs. Often the CHAP authentication ID is only unique within a PPPoE session. Similarly, the PPPoE session ID only needs to be unique within a broadcast domain so these are often re-used across VLANs. Care must be taken to ensure that the challenge and response really do belong together.

In order to be considered a challenge / response pair, I decided the following criteria must match:

• Server and Client MACs
• S & C VLAN IDs (if present)
• PPPoE SID
• CHAP authentication ID

I considered including MPLS labels in this but I struggled to think of a realistic scenario in which two authentications would match the above criteria but use a different label.

Additionally, the thought occurred that even with the above details matching, there may be more than one challenge / response pair for the same PPPoE session so a response would have to be paired with the most recent challenge for which the criteria matched. In the program this is achieved by working backwards through the linked list, starting at the response, until a match is found. Data from matching challenge / response pairs are stored in another list for later consumption. If the search reaches the beginning without a matching challenge being found then the response cannot be used and is ignored.

Brute Force Password Guessing

For each challenge / response pair in the list, the next step is to cycle through a list of password guesses. Each candidate password is combined with the authentication ID and challenge data from the captured authentication and hashed. The resulting hash is compared to the one from the captured response and, for those that match, a correct guess is reported. If no password generated a matching hash then the word list does not contain the correct password and this is also reported back.

Downloading the Tool

The C source code may be downloaded from: https://github.com/theclam/dechap

Provided the OpenSSL dev libraries are installed it should be possible to simply extract the source code, cd into the directory then run "make".

In the future I may add the capability to pull the auths from L2TP or RADIUS interactions but for now only PPPoE is supported. It also assumes that Ethernet control words are not present in MPLS encapsulated traffic.

Using the Tool

The usage is pretty straightforward - there are only two parameters and both are mandatory. Specify your capture file (original pcap format) with the -c flag and your word list with the -w flag. Here's an example:

lab@lab:~/dechap$ ./dechap -w mywords.txt -c someauths.cap
Found password "tangerine" for user user1@testisp.com.
Unable to find a password for user user2@testisp.com.
Found password "password1" for user user3@testisp.com.
Found password "Africa" for user user4@testisp.com.
Found password "Frankenstein" for user user5@testisp.com.
lab@lab:~/dechap$

Considering that I've made no effort at all to make the code efficient, I've found the speed pretty good. On my '90s PC, a worst-case run (i.e. where no passwords are found) against 800 auths with 100k candidate passwords, a run still completes inside a minute. I don't think that's bad for parsing 15,000 packets and running 80 million concatenate - hash - compare sequences.

If you try this out, please leave a comment on this post with your experiences - good or bad.

A Script to Bring Up a PPPoE Sessions using Python & Scapy

As I mentioned in my previous post, I have put together a script which can bring up a PPPoE session, authenticate using CHAP, negotiate an IP address and send / receive traffic. The script is written in Python and requires a relatively up to date version of scapy (I use v2.2.0-dev, just grab the latest from http://www.secdev.org/projects/scapy/).

I warn you now that I am not a professional coder (or even a particularly keen amateur) and I don't really get on with Python... so don't be surprised if it looks a bit C-like!

To run the script, simply download PPPoESession.py from https://github.com/theclam/PPPoESession-Python and call it from within Python:

root@labpc:~# python
Python 2.6.5 (r265:79063, Apr 16 2010, 13:09:56)
[GCC 4.4.3] on linux2
Type "help", "copyright", "credits" or "license" for more information.
>>> execfile("PPPoESession.py")
__main__:2: DeprecationWarning: the md5 module is deprecated; use hashlib instead
WARNING: No route found for IPv6 destination :: (no default route?)
/usr/local/lib/python2.6/dist-packages/scapy/crypto/cert.py:10: DeprecationWarning: the sha module is deprecated; use the hashlib module instead
  import os, sys, math, socket, struct, sha, hmac, string, time
/usr/local/lib/python2.6/dist-packages/scapy/crypto/cert.py:11: DeprecationWarning: The popen2 module is deprecated.  Use the subprocess module.
  import random, popen2, tempfile
>>>


You can expect to see a few deprecation warnings, depending on which version of Python is in use.

The script defines the PPPoESession class, plus a few other miscellaneous functions for encapsulating and extracting parameters. The PPPoESession class inherits from the scapy Automata class, so all the useful features of that class such as graph() and easy debugging are available. See the scapy Automata wiki entry (http://trac.secdev.org/scapy/wiki/Automata) for more details.

In order to bring up a PPPoE session, a PPPoESession object needs to be instantiated and a few parameters need to be set. At minimum the Ethernet interface, username and password need to be configured:

>>> p = PPPoESession()
>>> p.iface="eth1"
>>> p.username="spongebob@bodges"
>>> p.password="password"


Once that is done, the automaton can be started using the runbg() method. The state machine then runs in the background, returning control to the user. Messages will appear as it goes through the motions of bringing up the PPPoE session, then the PPP session, then authenticating before finally completing IPCP:

>>> p = PPPoESession()
>>> p.username="spongebob@bodges"
>>> p.password="password"
>>> p.iface="eth1"
>>> p.runbg()
>>> Starting PPPoED
Starting LCP
Got CHAP Challenge, Authenticating
Authenticated OK
Starting IPCP
Peer provided our IP as 123.4.5.6
IPCP is OPEN

>>>

Once IP is negotiated, the automaton will stay in the IPCP_OPEN state, able to send and receive IP packets and automatically responding to any LCP echoes that arrive.

From that state, the following methods may be called:

recv_queuelen() - returns the number of packets waiting in the receive buffer
recv_packet() - returns and de-queues the first packet in the receive buffer
send_packet(IPPacket) - transmits the given IP packet over the PPPoE session
ip() - returns the IP address given to the client
gw() - returns the peer's IP address

Here's an example of passing some traffic on an open session by pinging the gateway:

>>> p.recv_queuelen()
0
>>> p.send_packet(IP(src=p.ip(), dst=p.gw())/ICMP())
>>> p.recv_queuelen()
1
>>> p.recv_packet()
<IP  version=4L ihl=5L tos=0x0 len=28 id=1 flags= frag=0L ttl=64 proto=icmp chksum=0xbd0f src=1.1.1.1 dst=123.4.5.6 options=[] |<ICMP  type=echo-reply code=0 chksum=0xffff id=0x0 seq=0x0 |<Padding  load='\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00' |>>>
>>>

The script is still very much a work in progress. There is, for example, no clean way to gracefully shut down the PPP session at the moment and it doesn't handle incoming Terminate-Requests, either. I am hoping to add that, and more, soon.

Have a play with it and let me know what you think, good or bad :)

Bringing Up a PPPoE Session - The Theory

In a previous post, I shared a Scapy script that implements the PPPoE discovery stage and stops once the session stage is reached. As handy as that script is for testing AC Cookie validation, it is not particularly useful for anything else. It would be much better if the script could bring the PPP session all the way up.

Luckily, the PPPoE discovery script is a cut-down version of another script that I wrote a long time back which goes all the way from PPPoED, through LCP and CHAP authentication and stops at IPCP. At the time, the script was far too messy to share but I've tidied it up and it is now in a state that it could be useable by others. I've also added IPCP negotiation and a couple of methods for sending and receiving IP traffic over the resulting session.

Before I present the script, I'll cover the theory involved, step by step. The impatient may want to just go to the next post (when it is available) for the script itself and instructions on how to run it.

PPPoE Discovery

PPP is (a) point-to-point protocol, designed to run over a dedicated link between two devices. Ethernet is a multi-access network, so if we want to run PPP over Ethernet then we need a mechanism to discover peers and establish a point-to-point relationship between two devices over the shared medium.

PPPoE provides this service and operates in two distinct stages:

1. Discovery: The discovery stage is responsible for locating PPPoE peers and negotiating session parameters so that, ultimately, a PPPoE session can be created.
2. Session: Once the discovery stage is complete the protocol enters the session stage, at which time the two peers have a tunneled connection between them over which to start passing PPP.

Once the session stage is reached, the peers bring up and operate their PPP session exactly as they would over a dedicated link.

The diagram below summarises the PPPoE "Discovery" stage:

PPPoE State Transitions

The first step in the journey is to find a PPPoE access concentrator which is willing to terminate our session. To do this, we must broadcast a PPPoE Active Discovery Initiation (PADI) message. It is possible to specify a service name in the PADI - this is just a string that identifies a particular type of service in which the client is interested. The access concentrator may use this to decide whether or not to offer to terminate the session, though in most cases it is just ignored. For this reason clients generally use an empty service name.

Any access concentrators listening on the segment will receive the PADI message, inspect its contents and then make a decision whether or not to make an offer to terminate the client's session. If the access concentrator is willing to terminate the session, it signals this to the client by sending a unicast offer (PADO) message. Typically, the PADO has an AC-Cookie attached to it - essentially the AC-Cookie is an "unpredictable" string, derived from the client's MAC address, which the access concentrator uses to mitigate against certain kinds of resource exhaustion attacks. When AC-Cookies are used, a PADO is generated 'mechanically' from the incoming PADI and no state is created on the access concentrator at this point.

When the client has received at least one PADO, it must select a favourite. It is common to just use the first offer received, but other selection criteria may be used. The client then sends a unicast request (PADR) to the chosen access concentrator, indicating that it would like to access its offer. If an AC-Cookie was contained in the PADO message then is echoed back in the PADR. The requirement to echo the cookie back to the access concentrator is designed to validate that the client really exists and is available on the MAC address where the PADO was sent.

Finally, it is up to the access concentrator to confirm that it the session has been created. If AC-Cookies are in use then the incoming PADR is examined to check whether the AC would have generated the provided cookie given the source MAC - in the case of a mismatch the PADR is silently dropped, otherwise the session state is created in the AC and a session (PADS) message is unicast to the client to confirm that the session has been created and the "Session" stage has begun. The PADS always contains a PPPoE session ID number, which is used to discriminate between multiple PPPoE sessions on the same LAN. The session ID is used to differentiate between multiple PPPoE sessions on the same LAN and must be present in the header of every PPPoE frame exchanged with the AC during the "Session" stage.

The fifth type of PPPoE discovery message is the terminate (PADT) which, as its name suggests, is used to terminate (i.e. end) a session which has been established. Either end may send a PADT message to close the session and once a PADT has been received, no further traffic may be sent for that session.

PPP

PPP itself consists of a number of sub-protocols. There are:

• Link Control Protocol (LCP) which is responsible for negotiating overall link parameters
• PAP and CHAP which are used for authentication
• A family of Network Control Protocols (NCPs) used to negotiate the transport of each upper layer protocol

PPP also defines that once a higher layer protocol has been negotiated by its corresponding NCP, that protocol's traffic will be encapsulated with header indicating that particular protocol's protocol number.

Link Control Protocol (LCP)

RFC 1661 defines LCP as the protocol that is responsible for "establishing, configuring,
and testing the data-link connection." Essentially this means that LCP is used to bring up and take down PPP links, negotiate the configuration parameters and check that the link is still alive. There are a range of LCP codes which are used to fulfil these aims, discussed below.

Configuration Type Codes

In order to bring up a PPP session both peers must agree on certain parameters, for example the maximum size of frame that may be passed, whether to use compression and so on. Both peers propose the settings they would like to use - the opposite peer will then either acknowledge (accept), nak (i.e. suggest alternative) or reject (outright refuse) the proposed options. The aim is to reach a state where the opposite peer has acknowledged the locally proposed parameters.

The following LCP codes are standard and must be implemented:

Configure-Request - Used to propose a set of parameters that we would like to use for the session. The peer will then respond to the proposed parameters with one of the next three responses.

Configure-Ack - Used to advise the peer that their proposed parameters are acceptable. The accepted parameters are echoed back in the ack message.

Configure-Nak - Used to advise the peer that their proposed parameters are not acceptable and that the alternative values should be used. The proposed changes are attached to the nak message.

Configure-Reject - Used to advise the peer that their proposed parameters are not supported and cannot be used. The unacceptable parameters are echoed back in the reject message.

Termination Type Codes

Either peer may request to terminate the session at any point and the opposite peer must honour that request. There are two termination related codes in LCP:

Terminate-Request - Generated by a peer to initiate the tear-down of the link. A Terminate-Request should be re-sent if no Terminate-Ack is received in response.

Terminate-Ack - Generated to confirm receipt of a Terminate-Request. A Terminate-Ack must be generated in response to a Terminate-Request.

Liveness Check Codes

LCP includes a ping-like echo mechanism to verify that the opposite peer is still available, with LCP in an open state and is responding. The same mechanism is used to detect a looped interface - due to the symmetric nature of PPP it's quite possible to negotiate a connection to yourself without necessarily realising or for a connection to be looped mid-session. The following codes are used for liveness checks:

Echo-Request - Sent to the remote peer to solicit an Echo-Reply message. There is no requirement to negotiate the use of LCP echoes and an Echo-Request may be generated at any time while LCP is open. If the Magic-Number option was negotiated during LCP, the Echo-Request must contain the "random" 4 octet magic number decided at that time.

Echo-Reply - Sent in response to an Echo-Request message. When LCP is open, an Echo-Reply message must be sent whenever an Echo-Request is received. The magic number contained within the incoming Echo-Request must be copied into the outgoing Echo-Reply. If the incoming packet has our magic number then the connection has become looped.

Other Codes

There are other codes such as Code-Reject, Protocol-Reject and Discard-Request which do pretty much what you would expect. You don't get to see them very often so I will not discuss them here. I suggest referring to RFC 1661 for more detail on these.

LCP State Diagram

Below is a simplified state diagram showing how LCP makes its way from the "Starting" state into an "Opened" state. Most parts of PPP are referred to as "open" when they are up and running. I have omitted a number of transitions that deal with strange corner cases (like if the peer acks something we never sent, etc) and also transitions related to closing the connection (the Term commands discussed above). RFC 1661 contains a complete state transition table which is far more complex. If you bear in mind that at any stage either peer may terminate the session then this minimal version will cover 95% of "normal" cases.

LCP State Transitions

Authentication

Once LCP is open, the next stage is typically to start authentication. Authentication may be done by either, neither or both the peers as negotiated by LCP and can be done using plaintext PAP or MD5 hashed CHAP. If no authentication was negotiated by LCP, an implicit pass is assumed.

PAP is hardly ever used these days, is strongly discouraged and in any case is pretty simple, so I will not discuss it here. Please refer to RFC 1334 if you require details on PAP.

CHAP, though not immune to attack, offers reasonable security. The password itself is never sent "over the wire" and there is good protection against replay attacks via the use of random challenges. Here is how CHAP operates:

CHAP Authentication

Essentially, security is provided in two ways:

1. The password is never exchanged in the clear but instead is passed through a one-way cryptographic hash function. It is computationally infeasible to recover the password from the hash function's output, so it is quite safe to pass this output over the wire.
2. If the client just hashed the password, then it would be possible for an attacker to capture the hashed value and authenticate with the server at a later time by simply replaying the same response. CHAP requires the server to generate a random challenge string, which is also fed into the hash function and affects its output. Provided the server never re-uses a challenge value, an attacker cannot simply replay a previous authentication response to gain access.

When the CHAP response comes in, the server compares the received hash value with the output of a local calculation using the same method to determine whether the authentication attempt was successful. While this is precisely true when the server has a local copy of the password, typically this is not desirable and in practice the authentication check is deferred to an external RADIUS server. In order for the RADIUS to validate the attempt, the server must pass it a copy of the ID and challenge sent, plus the response received. The RADIUS can then use the ID, its own copy of the plaintext password and the challenge value to compute the expected response. If the expected and actual responses match then the RADIUS will return an "Accept" response, otherwise it will return a "Reject" response.

Network Control Protocols (NCPs)

Before any higher layer protocol can be passed through a PPP tunnel, it must be negotiated by a corresponding NCP. For example before you can pass IP through a PPP tunnel, IPCP must be open, indicating that all the required IP parameters have been successfully negotiated. To pass OSI traffic, OSICP must be open. For IPv6, IPV6CP is used.

The operation of each NCP is different but they all essentially follow the same model as LCP - parameters are proposed by each peer and ack'd, nak'd or rejected by the opposite peer. - and the state transition diagram pretty much looks the same.

IPCP

I'll go into a little more detail on IPCP since that is the most commonly used (for now) with a worked example of a DSL subscriber connecting to his ISP, starting immediately after authentication succeeds.

Client Side

The client generally does not know anything when it first connects and relies on the server to provide it with everything it needs. The client sends a Configure-Request proposing an IP address, primary and secondary DNS of 0.0.0.0. Proposing 0.0.0.0 for these is actually an  explicit request for the server to provide legitimate values for the client to use.

The server will then respond with a Configure-Nak message containing the IP address and DNS servers that the client should use.

The client will then send another Configure-Request with the newly acquired details, to which the server responds with a Configure-Ack.

Server Side

The server will typically send out a Configure-Request containing only its own IP address. There is no reason to argue over this so the client should just respond with a Configure-Ack. If the client tries to push a different address to the server using a Configure-Nak, it is typically ignored and after a few retries the session gets pulled down.

Passing Traffic

Once the two peers are agreed and IPCP is open, IP packets may be passed through the PPP tunnel by attaching a header - in most cases, for PPPoE connectivity, the PPP header consists of only a two byte protocol number (0x0021 for IP). The protocol number is analogous to the EtherType field of an Ethernet frame and indicates to the receiver how to interpret the payload. Alternative encapsulations exist - refer to RFC 1662 for more details on HDLC style framing which is often seen in L2TP.

Further Reading

That about covers the protocols involved in bringing up a PPPoE session at a high level. If you require more information I would suggest turning to the following RFCs:

RFC 2516 - PPPoE - http://tools.ietf.org/html/rfc2516
RFC 1661 - PPP - http://tools.ietf.org/html/rfc1661
RFC 1994 - CHAP - http://tools.ietf.org/html/rfc1994
RFC 1332 - IPCP - http://tools.ietf.org/html/rfc1332
RFC 1877 - IPCP extensions for DNS - http://tools.ietf.org/html/rfc1877