pppoe

package
v0.1.7 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Feb 19, 2024 License: MIT Imports: 7 Imported by: 0

Documentation

Overview

Package pppoe is a library for PPP over Ethernet applications running on Linux systems.

PPPoE is specified by RFC2516, and is widely used in home broadband links when connecting the client's router into the Internet Service Provider network.

Currently package pppoe implements:

  • Connection and protocol support for the PPPoE Active Discovery protocol. This is a simple sequence of messages which is used to instantiate and tear down a PPPoE connection. Protocol support for both client and server applications is provided.

  • Integration with the Linux kernel's L2TP access concentrator subsystem used to control the switching of PPPoE session data packets into an L2TP session for transmission to the LNS. This is of use when building PPPoE servers.

Actual session data packets are managed using a PPP daemon and are outside the scope of package pppoe.

Usage 

# Note we're ignoring errors for brevity

import (
	"fmt"
	"github.com/katalix/go-l2tp/pppoe"
)

// Create a new PPPoE discovery connection on interface eth0
conn, _ := pppoe.NewDiscoveryConnection("eth0")

// Build a PADI packet to kick off the discovery process.
// Add two service name tags indicating the services we're interested in.
padi, _ := pppoe.NewPADI(conn.HWAddr(), "SuperBroadbandServiceName")
padi.AddServiceNameTag("MegaBroadbandServiceName")

// Encode the packet ready to send on the connection.
b, _ := padi.ToBytes()

// Send the packet.  Hopefully a server responds!
conn.Send(b)

// Receive any replies to our PADI packet.
rcv, _ := conn.Recv()

// Parse the received frames into PPPoE packets.
parsed, _ := pppoe.ParsePacketBuffer(rcv)
fmt.Printf("received: %v\n", parsed[0])

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type PPPoECode 

type PPPoECode uint8

PPPoECode indicates the PPPoE packet type. 

const (
	// PPPoE Active Discovery Initiation packet
	PPPoECodePADI PPPoECode = 0x09
	// PPPoE Active Discovery Offer packet
	PPPoECodePADO PPPoECode = 0x07
	// PPPoE Active Discovery Request packet
	PPPoECodePADR PPPoECode = 0x19
	// PPPoE Active Discovery Session-confirmation packet
	PPPoECodePADS PPPoECode = 0x65
	// PPPoE Active Discovery Terminate packet
	PPPoECodePADT PPPoECode = 0xa7
)

PPPoE packet codes.

func (PPPoECode) String 

func (code PPPoECode) String() string

String provides a human-readable representation of PPPoECode.

type PPPoEConn 

type PPPoEConn struct {
	// contains filtered or unexported fields
}

PPPoEConn represents a PPPoE discovery connection, allowing receipt and transmission of PPPoE discovery packets.

Because raw sockets are used for sending Ethernet frames, it is necessary to have root permissions to create PPPoEConn instances.

func NewDiscoveryConnection 

func NewDiscoveryConnection(ifname string) (conn *PPPoEConn, err error)

NewDiscoveryConnection creates a new PPPoE discovery connection on the specified network interface.

func (*PPPoEConn) Close 

func (c *PPPoEConn) Close() (err error)

Close closes the discovery connection, releasing allocated resources.

func (*PPPoEConn) HWAddr 

func (c *PPPoEConn) HWAddr() (addr [6]byte)

HWAddr returns the hardware address of the interface the discovery connection is using.

func (*PPPoEConn) Recv 

func (c *PPPoEConn) Recv(b []byte) (n int, err error)

Recv receives one or more frames over the discovery connection.

func (*PPPoEConn) Send 

func (c *PPPoEConn) Send(b []byte) (n int, err error)

Send sends a frame over the discovery connection.

type PPPoEPacket 

type PPPoEPacket struct {
	// SrcHWAddr is the Ethernet address of the sender of the packet.
	SrcHWAddr [6]byte
	// DstHWAddr is the Ethernet address of the receiver of the packet.
	DstHWAddr [6]byte
	// Code is the code per RFC2516 which identifes the packet.
	Code PPPoECode
	// SessionID is the allocated session ID, once it has been set.
	// Up until that point in the discovery sequence the ID is zero.
	SessionID PPPoESessionID
	// Tags is the data payload of the packet.
	Tags []*PPPoETag
}

PPPoEPacket represents a PPPoE discovery packet.

func NewPADI 

func NewPADI(sourceHWAddr [6]byte, serviceName string) (packet *PPPoEPacket, err error)

NewPADI returns a PADI packet with the RFC-mandated service name tag included.

PADI packets are used by the client to initiate the PPPoE discovery sequence.

Clients which wish to use any service available should pass an empty string.

PADI packets are sent to the Ethernet broadcast address, so only the source address must be specified.

func NewPADO 

func NewPADO(sourceHWAddr [6]byte, destHWAddr [6]byte, serviceName string, acName string) (packet *PPPoEPacket, err error)

NewPADO returns a PADO packet with the RFC-mandated service name and AC name tags included.

PADO packets are used by the server respond to a client's PADI.

func NewPADR 

func NewPADR(sourceHWAddr [6]byte, destHWAddr [6]byte, serviceName string) (packet *PPPoEPacket, err error)

NewPADR returns a PADR packet with the RFC-mandated service name tag included.

PADR packets are used by the client to request a specific service from a server, based on a server's PADO.

The service name tag should be derived from the PADO packet received from the server.

func NewPADS 

func NewPADS(sourceHWAddr [6]byte, destHWAddr [6]byte, serviceName string, sid PPPoESessionID) (packet *PPPoEPacket, err error)

NewPADS returns a PADS packet including an allocated session ID and the RFC-mandated service name tag.

PADS packets are used by the server to respond to a client's PADR. They represent the completion of the PPPoE discovery sequence, and may indicate either success or failure to establish the connection.

If the PADS packet indicates success, the session ID should be a non-zero value which is unique for the PPPoE peers.

If the PADS packet indicates failure, the session ID should be zero, and the packet should have the PPPoETagTypeServiceNameError tag appended.

func NewPADT 

func NewPADT(sourceHWAddr [6]byte, destHWAddr [6]byte, sid PPPoESessionID) (packet *PPPoEPacket, err error)

NewPADT returns a PADT packet for the specified session ID.

PADT packets are used by either client or server to terminate the PPPoE connection once established.

func ParsePacketBuffer 

func ParsePacketBuffer(b []byte) (packets []*PPPoEPacket, err error)

ParsePacketBuffer parses a raw received frame into one or more PPPoE packets.

func (*PPPoEPacket) AddACCookieTag 

func (packet *PPPoEPacket) AddACCookieTag(cookie []byte) (err error)

AddACCookieTag adds an access concentrator cookie tag to the packet. The AC cookie value is an arbitrary byte slice which is used by the access concentrator to aid in protecting against DoS attacks. Refer to RFC2516 for details.

func (*PPPoEPacket) AddACNameTag 

func (packet *PPPoEPacket) AddACNameTag(name string) (err error)

AddACNameTag adds an access concentrator name tag to the packet. The AC name is an arbitrary string.

func (*PPPoEPacket) AddACSystemErrorTag 

func (packet *PPPoEPacket) AddACSystemErrorTag(reason string) (err error)

AddACSystemErrorTag adds an access concentrator system error tag to the packet. The value may be an empty string, but should preferably be a human-readable string explaining the nature of the error.

func (*PPPoEPacket) AddGenericErrorTag 

func (packet *PPPoEPacket) AddGenericErrorTag(reason string) (err error)

AddGenericErrorTag adds an generic error tag to the packet. The value may be an empty string, but should preferably be a human-readable string explaining the nature of the error.

func (*PPPoEPacket) AddHostUniqTag 

func (packet *PPPoEPacket) AddHostUniqTag(hostUniq []byte) (err error)

AddHostUniqTag adds a host unique tag to the packet. The host unique value is an arbitrary byte slice which is used by the client to associate a given response (PADO or PADS) to a particular request (PADI or PADR).

func (*PPPoEPacket) AddServiceNameErrorTag 

func (packet *PPPoEPacket) AddServiceNameErrorTag(reason string) (err error)

AddServiceNameErrorTag adds a service name error tag to the packet. The value may be an empty string, but should preferably be a human-readable string explaining why the request was denied.

func (*PPPoEPacket) AddServiceNameTag 

func (packet *PPPoEPacket) AddServiceNameTag(name string) (err error)

AddServiceNameTag adds a service name tag to the packet. The service name is an arbitrary string.

func (*PPPoEPacket) AddTag 

func (packet *PPPoEPacket) AddTag(typ PPPoETagType, data []byte) (err error)

AddTag adds a generic tag to the packet. The caller is responsible for ensuring that the data type matches the tag type.

func (*PPPoEPacket) GetTag 

func (packet *PPPoEPacket) GetTag(typ PPPoETagType) (tag *PPPoETag, err error)

GetTag searches a packet's tags to find one of the specified type.

The first tag matching the specified type is returned on success.

func (*PPPoEPacket) String 

func (packet *PPPoEPacket) String() string

String provides a human-readable representation of PPPoEPacket.

func (*PPPoEPacket) ToBytes 

func (packet *PPPoEPacket) ToBytes() (encoded []byte, err error)

ToBytes renders the PPPoE packet to a byte slice ready for transmission over a PPPoEConn connection.

Prior to calling ToBytes a packet should ideally be validated using Validate to ensure it adheres to the RFC requirements.

func (*PPPoEPacket) Validate 

func (packet *PPPoEPacket) Validate() (err error)

Validate validates a packet meets the requirements of RFC2516, checking the mandatory tags are included and the session ID is set correctly.

type PPPoESessionID 

type PPPoESessionID uint16

PPPoESessionID, in combination with the peer's Ethernet addresses, uniquely identifies a given PPPoE session.

type PPPoETag 

type PPPoETag struct {
	Type PPPoETagType
	Data []byte
}

PPPoETag represents the TLV data structures which make up the data payload of PPPoE discovery packets.

func (*PPPoETag) String 

func (tag *PPPoETag) String() string

String provides a human-readable representation of PPPoETag.

For tags specified by the RFC to contain strings, a string representation of the tag data is rendered. For all other tags a dump of the raw hex bytes is provided.

type PPPoETagType 

type PPPoETagType uint16

PPPoETagType identifies the tags contained in the data payload of PPPoE discovery packets. 

const (
	PPPoETagTypeEOL              PPPoETagType = 0x0000
	PPPoETagTypeServiceName      PPPoETagType = 0x0101
	PPPoETagTypeACName           PPPoETagType = 0x0102
	PPPoETagTypeHostUniq         PPPoETagType = 0x0103
	PPPoETagTypeACCookie         PPPoETagType = 0x0104
	PPPoETagTypeVendorSpecific   PPPoETagType = 0x0105
	PPPoETagTypeRelaySessionID   PPPoETagType = 0x0110
	PPPoETagTypeServiceNameError PPPoETagType = 0x0201
	PPPoETagTypeACSystemError    PPPoETagType = 0x0202
	PPPoETagTypeGenericError     PPPoETagType = 0x0203
)

PPPoE Tag types.

PPPoE packets may contain zero or more tags, which are TLV constructs.

func (PPPoETagType) String 

func (typ PPPoETagType) String() string

String provides a human-readable representation of PPPoETagType.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.