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 ofalc.Pppoe
class
alc.Ppp
: LCP/IPCP/IPv6CP messageclass
alc.Pap
: PAP messageclass
alc.Chap
: CHAP messageNote
For PPPoE message, only the pre-provided
alc.pppoe
object should be used in script, the classalc.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.
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 |
int |
|
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 element 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 specified 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.
- 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.Ppp 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.
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
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.
Attribute |
Access |
Type |
---|---|---|
code |
ro |
int |
id |
ro |
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.
Attribute |
Access |
Type |
---|---|---|
code |
ro |
int |
id |
ro |
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.
Breaking changes
Class objects renamed
Warning
In Python 3, the classes alc.Ppp, alc.Pap, and alc.Chap follow the CapWords convention. In the Python 2 API, these are called alc.ppp, alc.pap, and alc.chap respectively (all lowercase).
New exceptions on alc.Pppoe functions
Warning
For alc.Pppoe, When calling the functions getTagList()
, get()
, set()
, clear()
on a packet that is not in discovery state, an exception is raised. In the Python 2 implementation, None is returned.
The same is true when the functions getPPP()
, getPAP()
, and getCHAP()
are called on packets without a corresponding embedded packet.
New exceptions on alc.Pap functions
Warning
The functions alc.Pap.getCred()
, alc.Pap.setCred()
, alc.Pap.getMsg()
, and alc.Pap.setMsg()
raise an exception when called on a packet with the wrong code.
New exceptions on alc.Chap functions
Warning
The functions alc.Chap.getCred()
, alc.Chap.setCred()
, alc.Chap.getMsg()
, and alc.Chap.setMsg()
raise an exception when called on a packet with the wrong code.