PPPoE/PPP/PAP/CHAP

The system provides the following Python object/classes to inspect and in certain cases, modify the corresponding protocol packet or message:

  • object alc.pppoe: PPPoE packet, class of alc.Pppoe

  • class alc.Ppp: LCP/IPCP/IPv6CP message

  • class alc.Pap: PAP message

  • class alc.Chap: CHAP message

    Note

    For PPPoE message, only the pre-provided alc.pppoe object should be used in script, the class alc.Pppoe should not be used directly.

The alc.Pppoe class

Note

In addition to PPPoE packets, alc.pppoe is also available when the Python script is triggered by packets encapsulated in PPPoE, such as LCP, PAP, or CHAP.

Instance Attributes

The PPPoE header fields are exposed as instance attributes on the object.

Attributes defined on alc.pppoe object

Attribute

Access

Type

Format

dest_mac

ro

str

“xx:xx:xx:xx:xx:xx”

src_mac

ro

str

“xx:xx:xx:xx:xx:xx”

port_id

ro

str

“1/2/3”

vlan_tag

ro

str

ver

ro

int

type

ro

int

code

ro

int

session_id

ro

int

len

ro

int

Methods

drop()

Drops the packet.

getTagList()

Retrieves a tuple that includes tag-type of existing PPPoE tags in the packet.

  • The order of the elements in the tuple is the same as the order of the tags in the packet.

  • If there are multiple instances of the same tag, the tag appears multiple times in the resulting tuple.

Returns:

tuple of tag-types

Raises:

RuntimeError – when called on a PPPoE packet that does not accept tags.

get(type, /)

Retrieves all instances of a specific tag-type.

Parameters:

type (int) – tag type

Returns:

tuple of bytes where each element is the value (as a bytestring) of a single instance. An empty tuple is returned when the tag is not present.

Raises:

RuntimeError – when called on a PPPoE packet that does not accept tags.

set(type, values, /)

Deletes existing tags of the specified type and inserts new tags with the spcified type and values.

Parameters:
  • type (int) – tag type

  • values – tuple of bytes, each element is the value of a separate tag (the length is deduced from this value)

Raises:

RuntimeError – when called on a PPPoE packet that does not accept tags.

clear(type, /)

Removes all tags of specified type.

Parameters:

type (int) – tag type

Raises:

RuntimeError – when called on a PPPoE packet that does not accept tags.

getPPP()

Retrieves an object of type alc.Ppp which represents the LCP, IPCP or IP6CP packet encapsulated inside the PPPoE packet.

Returns:

alc.Ppp object

Raises:

RuntimeError – when called on a PPPoE packet without embedded PPP packet.

Note

Modifying the object returned by this function does not alter the PPPoE packet. For the changes to take effect, setPPP() must be called with the modified PPP packet as its argument.

setPPP(ppp, /)

Replaces the existing PPP packet.

Parameters:

ppp (alc.Ppp) – new PPP packet

Raises:

RuntimeError – when called on a PPPoE packet without embedded PPP packet.

getPAP()

Retrieves an object of type alc.Pap which represents the embedded PAP packet.

Returns:

alc.Pap object

Raises:

RuntimeError – when called on a PPPoE packet without embedded PAP packet.

Note

Modifying the object returned by this function does not alter the PPPoE packet. For the changes to take effect, setPAP() must be called with the modified PAP packet as its argument.

setPAP(pap, /)

Replaces the existing PAP packet.

Parameters:

pap (alc.Pap) – new PAP packet

Raises:

RuntimeError – when called on a PPPoE packet without embedded PAP packet.

getCHAP()

Retrieves an object of type alc.Chap which represents the embedded CHAP packet.

Returns:

alc.Chap object

Raises:

RuntimeError – when called on a PPPoE packet without embedded CHAP packet.

Note

Modifying the object returned by this function does not alter the PPPoE packet. For the changes to take effect, setCHAP() must be called with the modified CHAP packet as its argument.

setCHAP(chap, /)

Replaces the existing CHAP packet.

Parameters:

chap (alc.Chap) – new CHAP packet

Raises:

RuntimeError – when called on a PPPoE packet without embedded CHAP packet.

The alc.Ppp class

The object returned from calling alc.pppoe.getPPP() is of type alc.Ppp. This object can be inspected.

class Ppp(bytes, /)

Creates a new object representing a PPP packet.

Parameters:

bytes (bytes) – the bytes representation of the complete PPP packet, including the header.

Instance Attributes

The PPP header fields are exposed as instance attributes on the object.

Attributes defined on alc.Ppp objects

Attribute

Access

Type

protocol

ro

int

code

ro

int

id

ro

int

len

ro

int

Methods

getOptionList()

Retrieves a tuple of all PPP options that are present in the packet.

  • The order of the options is the same as they appear in the packet.

  • Each instance of the option is reflected in the tuple.

Returns:

tuple of option-types

get()

Retrieves the values of a specific PPP option.

Parameters:

type (int) – option-type

Returns:

tuple of bytes, each element is the value of an instance of the specified option-type

set(type, value, /)

Deletes existing options of the specified type and inserts new options with the specified type and value. Multiple values can be specified in a tuple, in which case an option is added for each item in the tuple.

Parameters:
  • type (int) – option-type

  • value (bytes|tuple(bytes)) – value of the option; the length is computed from this value

clear(type, /)

Removes all options of the specified type.

Parameters:

type (int) – option-type

The alc.Pap class

The object returned from calling alc.pppoe.getPAP() is of type alc.Pap. This object can be inspected and modified and can be passed to alc.pppoe.setPAP() to modify the active PPPoE packet.

Alternatively, new objects of this class can be created and used to set the embedded PAP packet.

class Pap(bytes, /)

Creates a new object representing a PAP packet.

Parameters:

bytes (bytes) – the bytes representation of the complete PAP packet, including the header.

Instance Attributes

The PAP header fields are exposed as instance attributes on the object.

Attributes defined on alc.Pap objects

Attribute

Access

Type

code

rw

int

id

rw

int

len

ro

int

Methods

getCred()

Retrieves the peer-id and password of an Authentication-Request packet.

Returns:

(peer_id, password) tuple, both elements are bytes, possibly b’’ if the length is 0.

Raises:

RuntimeError – when the packet is not an Authentication-Request

setCred(value, /)

Set the peer-id and password on an Authentication-Request packet.

Parameters:

value – (peer_id, password) tuple, both elements are bytes, b’’ is allowed for either element.

Raises:

RuntimeError – when the packet is not an Authentication-Request

getMsg()

Retrieves the contents of the packet.

Returns:

contents as a bytestring

Raises:

RuntimeError – when the packet is not an Authentication-Ack/Nak

setMsg(value, /)

Sets the contents of the packet.

Parameters:

value (bytes) – contents as a bytestring

Raises:

RuntimeError – when the packet is not an Authentication-Ack/Nak

The alc.Chap class

The object returned from calling alc.pppoe.getCHAP() is of type alc.Chap. This object can be inspected and modified and can be passed to alc.pppoe.setCHAP() to modify the active PPPoE packet.

Alternatively, new objects of this class can be created and used to set the embedded CHAP packet.

class Chap(bytes, /)

Creates a new object representing a CHAP packet.

Parameters:

bytes (bytes) – the bytes representation of the complete CHAP packet, including the header.

Instance Attributes

The CHAP header fields are exposed as instance attributes on the object.

Attributes defined on alc.Chap objects

Attribute

Access

Type

code

rw

int

id

rw

int

len

ro

int

Methods

getCred()

Retrieves the name and challenge/response from a challenge or response packet.

Returns:

(name, value) tuple, both elements are bytes, where value is either the challenge or response depending on the code of the packet

Raises:

RuntimeError – when the packet is not a challenge or response packet

setCred(value, /)

Sets the name and challenge/response on a challenge/response packet.

Parameters:

value – (name, value) tuple, both elements are bytes, where value is either the challenge or response depending on the code of the packet. b’’ is valid for either element.

Raises:

RuntimeError – when the packet is not a challenge or response packet

getMsg()

Retrieves the contents of the packet.

Returns:

contents as a bytestring

Raises:

RuntimeError – when the packet is not a success or failure packet.

setMsg(value, /)

Sets the contents of the packet.

Parameters:

value (bytes) – contents as a bytestring

Raises:

RuntimeError – when the packet is not a success or failure packet.