use std::net::{IpAddr, Ipv4Addr, Ipv6Addr};
use pnet_base::MacAddr;
use pnet_packet::ethernet::EtherType;
use crate::protocols::ethernet::Frame;
use crate::protocols::text::field as text;
pub const ETHERTYPE: EtherType = EtherType(0x88CC);
const GROUP_ADDRESSES: [MacAddr; 3] = [
MacAddr(0x01, 0x80, 0xC2, 0x00, 0x00, 0x0E),
MacAddr(0x01, 0x80, 0xC2, 0x00, 0x00, 0x03),
MacAddr(0x01, 0x80, 0xC2, 0x00, 0x00, 0x00),
];
const MAX_TLVS: usize = 128;
const OUI_802_1: [u8; 3] = [0x00, 0x80, 0xC2];
const SUBTYPE_PORT_VLAN: u8 = 1;
const TLV_END: u8 = 0;
const TLV_CHASSIS_ID: u8 = 1;
const TLV_PORT_ID: u8 = 2;
const TLV_TTL: u8 = 3;
const TLV_PORT_DESCRIPTION: u8 = 4;
const TLV_SYSTEM_NAME: u8 = 5;
const TLV_SYSTEM_DESCRIPTION: u8 = 6;
const TLV_CAPABILITIES: u8 = 7;
const TLV_MANAGEMENT_ADDRESS: u8 = 8;
const TLV_ORGANIZATIONALLY_SPECIFIC: u8 = 127;
const CHASSIS_SUBTYPE_MAC: u8 = 4;
const CHASSIS_SUBTYPE_NETWORK: u8 = 5;
const PORT_SUBTYPE_MAC: u8 = 3;
const PORT_SUBTYPE_NETWORK: u8 = 4;
const AFN_IPV4: u8 = 1;
const AFN_IPV6: u8 = 2;
#[non_exhaustive]
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum Identifier<'a> {
Mac(MacAddr),
Network(IpAddr),
Text(&'a str),
Other {
subtype: u8,
bytes: &'a [u8],
},
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct Capabilities {
supported: u16,
enabled: u16,
}
impl Capabilities {
const REPEATER: u16 = 1 << 1;
const BRIDGE: u16 = 1 << 2;
const WLAN_ACCESS_POINT: u16 = 1 << 3;
const ROUTER: u16 = 1 << 4;
const TELEPHONE: u16 = 1 << 5;
const STATION_ONLY: u16 = 1 << 7;
pub fn is_bridge(self) -> bool {
self.enabled & Self::BRIDGE != 0
}
pub fn is_router(self) -> bool {
self.enabled & Self::ROUTER != 0
}
pub fn is_wlan_access_point(self) -> bool {
self.enabled & Self::WLAN_ACCESS_POINT != 0
}
pub fn is_telephone(self) -> bool {
self.enabled & Self::TELEPHONE != 0
}
pub fn is_repeater(self) -> bool {
self.enabled & Self::REPEATER != 0
}
pub fn is_station_only(self) -> bool {
self.enabled & Self::STATION_ONLY != 0
}
pub fn bits(self) -> (u16, u16) {
(self.supported, self.enabled)
}
}
#[non_exhaustive]
#[derive(Debug, Clone, Default, PartialEq, Eq)]
pub struct Advertisement<'a> {
pub chassis_id: Option<Identifier<'a>>,
pub port_id: Option<Identifier<'a>>,
pub ttl: Option<u16>,
pub system_name: Option<&'a str>,
pub system_description: Option<&'a str>,
pub port_description: Option<&'a str>,
pub capabilities: Option<Capabilities>,
pub management_address: Option<IpAddr>,
pub port_vlan: Option<u16>,
}
pub fn parse<'a>(frame: &Frame<'a>) -> Option<Advertisement<'a>> {
if frame.ethertype() != ETHERTYPE {
return None;
}
let mut advertisement = Advertisement::default();
let mut rest = frame.payload();
let mut seen = 0usize;
while seen < MAX_TLVS {
let Some((kind, value, remainder)) = next_tlv(rest) else {
break;
};
if kind == TLV_END {
break;
}
rest = remainder;
seen += 1;
match kind {
TLV_CHASSIS_ID => keep_first(
&mut advertisement.chassis_id,
identifier(value, CHASSIS_SUBTYPE_MAC, CHASSIS_SUBTYPE_NETWORK),
),
TLV_PORT_ID => keep_first(
&mut advertisement.port_id,
identifier(value, PORT_SUBTYPE_MAC, PORT_SUBTYPE_NETWORK),
),
TLV_TTL => keep_first(
&mut advertisement.ttl,
value
.first_chunk::<2>()
.map(|bytes| u16::from_be_bytes(*bytes)),
),
TLV_PORT_DESCRIPTION => keep_first(&mut advertisement.port_description, text(value)),
TLV_SYSTEM_NAME => keep_first(&mut advertisement.system_name, text(value)),
TLV_SYSTEM_DESCRIPTION => {
keep_first(&mut advertisement.system_description, text(value));
}
TLV_CAPABILITIES => keep_first(&mut advertisement.capabilities, capabilities(value)),
TLV_MANAGEMENT_ADDRESS => {
keep_first(&mut advertisement.management_address, management(value));
}
TLV_ORGANIZATIONALLY_SPECIFIC => {
keep_first(&mut advertisement.port_vlan, port_vlan(value));
}
_ => {}
}
}
let read_something = advertisement.chassis_id.is_some()
|| advertisement.port_id.is_some()
|| advertisement.ttl.is_some();
read_something.then_some(advertisement)
}
fn keep_first<T>(field: &mut Option<T>, value: Option<T>) {
if field.is_none() {
*field = value;
}
}
pub fn addressed_to_a_bridge_group(destination: MacAddr) -> bool {
GROUP_ADDRESSES.contains(&destination)
}
fn next_tlv(bytes: &[u8]) -> Option<(u8, &[u8], &[u8])> {
let header = bytes.first_chunk::<2>()?;
let kind = header[0] >> 1;
let length = usize::from(u16::from_be_bytes([header[0] & 1, header[1]]));
let value = bytes.get(2..2 + length)?;
let remainder = bytes.get(2 + length..)?;
Some((kind, value, remainder))
}
fn identifier(value: &[u8], mac: u8, network: u8) -> Option<Identifier<'_>> {
let (subtype, id) = value.split_first()?;
if id.is_empty() {
return None;
}
match *subtype {
found if found == mac => id.first_chunk::<6>().map(|bytes| {
Identifier::Mac(MacAddr::new(
bytes[0], bytes[1], bytes[2], bytes[3], bytes[4], bytes[5],
))
}),
found if found == network => {
let (family, address) = id.split_first()?;
address_of(*family, address).map(Identifier::Network)
}
other => match text(id) {
Some(name) => Some(Identifier::Text(name)),
None => Some(Identifier::Other {
subtype: other,
bytes: id,
}),
},
}
}
fn capabilities(value: &[u8]) -> Option<Capabilities> {
let bytes = value.first_chunk::<4>()?;
Some(Capabilities {
supported: u16::from_be_bytes([bytes[0], bytes[1]]),
enabled: u16::from_be_bytes([bytes[2], bytes[3]]),
})
}
fn management(value: &[u8]) -> Option<IpAddr> {
let (length, rest) = value.split_first()?;
let length = usize::from(*length);
let string = rest.get(..length)?;
let (family, address) = string.split_first()?;
address_of(*family, address)
}
fn port_vlan(value: &[u8]) -> Option<u16> {
let (oui, rest) = value.split_at_checked(OUI_802_1.len())?;
if oui != OUI_802_1 {
return None;
}
let (subtype, vlan) = rest.split_first()?;
if *subtype != SUBTYPE_PORT_VLAN {
return None;
}
vlan.first_chunk::<2>()
.map(|bytes| u16::from_be_bytes(*bytes))
}
fn address_of(family: u8, address: &[u8]) -> Option<IpAddr> {
match family {
AFN_IPV4 => address
.first_chunk::<4>()
.map(|bytes| IpAddr::V4(Ipv4Addr::from(*bytes))),
AFN_IPV6 => address
.first_chunk::<16>()
.map(|bytes| IpAddr::V6(Ipv6Addr::from(*bytes))),
_ => None,
}
}
#[cfg(test)]
pub(crate) mod tests {
use super::*;
use crate::protocols::ethernet;
use crate::protocols::sizes::ETH_HDR_LEN;
pub(crate) const SWITCH_MAC: MacAddr = MacAddr(0x00, 0x1B, 0x2C, 0x3D, 0x4E, 0x5F);
const NEAREST_BRIDGE: MacAddr = MacAddr(0x01, 0x80, 0xC2, 0x00, 0x00, 0x0E);
fn tlv(kind: u8, value: &[u8]) -> Vec<u8> {
let length = value.len();
assert!(length < 512, "a TLV value is nine bits of length");
let mut bytes = vec![
(kind << 1) | u8::try_from(length >> 8).expect("one bit"),
u8::try_from(length & 0xFF).expect("eight bits"),
];
bytes.extend_from_slice(value);
bytes
}
fn frame_of(tlvs: &[Vec<u8>]) -> Vec<u8> {
let mut bytes = unterminated_frame_of(tlvs);
bytes.extend_from_slice(&tlv(TLV_END, &[]));
bytes
}
fn unterminated_frame_of(tlvs: &[Vec<u8>]) -> Vec<u8> {
let mut bytes = ethernet::build_header(SWITCH_MAC, NEAREST_BRIDGE, ETHERTYPE);
for tlv in tlvs {
bytes.extend_from_slice(tlv);
}
bytes
}
fn chassis_mac(mac: MacAddr) -> Vec<u8> {
tlv(
TLV_CHASSIS_ID,
&[
CHASSIS_SUBTYPE_MAC,
mac.0,
mac.1,
mac.2,
mac.3,
mac.4,
mac.5,
],
)
}
fn port_named(name: &str) -> Vec<u8> {
let mut value = vec![5u8];
value.extend_from_slice(name.as_bytes());
tlv(TLV_PORT_ID, &value)
}
fn port_mac(mac: MacAddr) -> Vec<u8> {
tlv(
TLV_PORT_ID,
&[PORT_SUBTYPE_MAC, mac.0, mac.1, mac.2, mac.3, mac.4, mac.5],
)
}
fn capability_tlv(supported: u16, enabled: u16) -> Vec<u8> {
let mut value = supported.to_be_bytes().to_vec();
value.extend_from_slice(&enabled.to_be_bytes());
tlv(TLV_CAPABILITIES, &value)
}
pub(crate) fn switch_announcement() -> Vec<u8> {
frame_of(&[
chassis_mac(SWITCH_MAC),
port_named("GigabitEthernet1/0/14"),
tlv(TLV_TTL, &120u16.to_be_bytes()),
tlv(TLV_SYSTEM_NAME, b"core-sw-02"),
capability_tlv(
Capabilities::BRIDGE | Capabilities::ROUTER,
Capabilities::BRIDGE | Capabilities::ROUTER,
),
tlv(
TLV_ORGANIZATIONALLY_SPECIFIC,
&[0x00, 0x80, 0xC2, SUBTYPE_PORT_VLAN, 0x00, 0x28],
),
tlv(
TLV_MANAGEMENT_ADDRESS,
&[5, AFN_IPV4, 198, 51, 100, 2, 0x03, 0, 0, 0, 1, 0],
),
])
}
#[test]
fn a_switch_advertisement_is_read_field_by_field() {
let bytes = frame_of(&[
chassis_mac(SWITCH_MAC),
port_named("GigabitEthernet1/0/14"),
tlv(TLV_TTL, &120u16.to_be_bytes()),
tlv(TLV_SYSTEM_NAME, b"core-sw-02"),
tlv(TLV_SYSTEM_DESCRIPTION, b"Cisco IOS Software, C2960X"),
tlv(TLV_PORT_DESCRIPTION, b"uplink to rack 4"),
capability_tlv(
Capabilities::BRIDGE | Capabilities::ROUTER,
Capabilities::BRIDGE,
),
tlv(
TLV_ORGANIZATIONALLY_SPECIFIC,
&[0x00, 0x80, 0xC2, SUBTYPE_PORT_VLAN, 0x00, 0x28],
),
tlv(
TLV_MANAGEMENT_ADDRESS,
&[5, AFN_IPV4, 198, 51, 100, 2, 0x03, 0, 0, 0, 1, 0],
),
]);
let frame = ethernet::parse(&bytes).expect("an Ethernet frame");
let advertisement = parse(&frame).expect("an LLDP advertisement");
assert_eq!(advertisement.chassis_id, Some(Identifier::Mac(SWITCH_MAC)));
assert_eq!(
advertisement.port_id,
Some(Identifier::Text("GigabitEthernet1/0/14"))
);
assert_eq!(advertisement.ttl, Some(120));
assert_eq!(advertisement.system_name, Some("core-sw-02"));
assert_eq!(
advertisement.system_description,
Some("Cisco IOS Software, C2960X")
);
assert_eq!(advertisement.port_description, Some("uplink to rack 4"));
assert_eq!(advertisement.port_vlan, Some(40));
assert_eq!(
advertisement.management_address,
Some(IpAddr::V4(Ipv4Addr::new(198, 51, 100, 2)))
);
assert!(addressed_to_a_bridge_group(frame.destination()));
}
#[test]
fn a_subtype_is_read_against_the_table_its_identifier_is_numbered_by() {
let bytes = frame_of(&[chassis_mac(SWITCH_MAC), port_named("Gi1/0/14")]);
let frame = ethernet::parse(&bytes).expect("an Ethernet frame");
let advertisement = parse(&frame).expect("an advertisement");
assert_eq!(
advertisement.chassis_id,
Some(Identifier::Mac(SWITCH_MAC)),
"chassis subtype 4 is a hardware address"
);
assert_eq!(
advertisement.port_id,
Some(Identifier::Text("Gi1/0/14")),
"port subtype 5 is an interface name, not the network address it is \
for a chassis"
);
let port_mac_address = MacAddr(0x00, 0x1B, 0x2C, 0x3D, 0x4E, 0x60);
let bytes = frame_of(&[chassis_mac(SWITCH_MAC), port_mac(port_mac_address)]);
let frame = ethernet::parse(&bytes).expect("an Ethernet frame");
assert_eq!(
parse(&frame).expect("an advertisement").port_id,
Some(Identifier::Mac(port_mac_address)),
"port subtype 3 is a hardware address, where 3 is a port component \
for a chassis"
);
}
#[test]
fn a_capability_that_is_supported_but_not_enabled_is_not_a_claim() {
let bytes = frame_of(&[
chassis_mac(SWITCH_MAC),
capability_tlv(
Capabilities::BRIDGE | Capabilities::ROUTER | Capabilities::WLAN_ACCESS_POINT,
Capabilities::BRIDGE,
),
]);
let frame = ethernet::parse(&bytes).expect("an Ethernet frame");
let capabilities = parse(&frame)
.expect("an advertisement")
.capabilities
.expect("capabilities");
assert!(capabilities.is_bridge(), "it said it is bridging");
assert!(
!capabilities.is_router(),
"it said it could route, which is not the same as doing it"
);
assert!(!capabilities.is_wlan_access_point());
}
#[test]
fn a_value_longer_than_a_byte_can_count_is_read_whole() {
let long = "x".repeat(400);
let bytes = frame_of(&[
chassis_mac(SWITCH_MAC),
tlv(TLV_SYSTEM_DESCRIPTION, long.as_bytes()),
tlv(TLV_SYSTEM_NAME, b"after-the-long-one"),
]);
let frame = ethernet::parse(&bytes).expect("an Ethernet frame");
let advertisement = parse(&frame).expect("an LLDP advertisement");
assert_eq!(advertisement.system_description, Some(long.as_str()));
assert_eq!(
advertisement.system_name,
Some("after-the-long-one"),
"and the walk resumed at the right place afterwards"
);
}
#[test]
fn a_length_running_past_the_frame_is_refused() {
let mut bytes = frame_of(&[chassis_mac(SWITCH_MAC)]);
bytes.extend_from_slice(&[(TLV_SYSTEM_NAME << 1) | 1, 0xF4]);
let frame = ethernet::parse(&bytes).expect("an Ethernet frame");
let advertisement = parse(&frame).expect("what was read before the end");
assert_eq!(advertisement.chassis_id, Some(Identifier::Mac(SWITCH_MAC)));
assert_eq!(advertisement.system_name, None);
}
#[test]
fn a_truncated_advertisement_keeps_the_fields_that_arrived_whole() {
let bytes = unterminated_frame_of(&[
chassis_mac(SWITCH_MAC),
port_named("Gi1/0/14"),
tlv(TLV_TTL, &120u16.to_be_bytes()),
tlv(
TLV_SYSTEM_DESCRIPTION,
b"a description long enough to cut inside",
),
]);
let chassis = chassis_mac(SWITCH_MAC).len();
let port = port_named("Gi1/0/14").len();
let both_read = ETH_HDR_LEN + chassis + port;
let mut kept = 0usize;
for cut in both_read..bytes.len() {
let frame = ethernet::parse(&bytes[..cut]).expect("a frame");
let Some(advertisement) = parse(&frame) else {
panic!("a frame cut to {cut} bytes lost an advertisement it had already read");
};
assert_eq!(
advertisement.chassis_id,
Some(Identifier::Mac(SWITCH_MAC)),
"the chassis identifier was read whole and then discarded, at {cut} bytes"
);
assert_eq!(
advertisement.port_id,
Some(Identifier::Text("Gi1/0/14")),
"the port identifier was read whole and then discarded, at {cut} bytes"
);
assert!(
advertisement.ttl.is_none() || cut >= both_read + 4,
"a TTL was reported from a frame cut to {cut} bytes"
);
kept += 1;
}
assert!(
kept >= 30,
"only {kept} truncations reached the assertions; the test is not measuring what it names"
);
}
#[test]
fn a_unit_with_no_end_record_reads_as_one_that_has_it() {
let tlvs = [chassis_mac(SWITCH_MAC), tlv(TLV_SYSTEM_NAME, b"core-01")];
let without_end = unterminated_frame_of(&tlvs);
let with_end = frame_of(&tlvs);
fn read(bytes: &[u8]) -> Advertisement<'_> {
let frame = ethernet::parse(bytes).expect("a frame");
parse(&frame).expect("an advertisement")
}
assert_eq!(read(&without_end), read(&with_end));
assert_eq!(read(&without_end).system_name, Some("core-01"));
}
#[test]
fn reading_further_never_takes_away_a_field_already_read() {
proptest::proptest!(|(
tlvs in proptest::collection::vec(
(0u8..=8u8, proptest::collection::vec(proptest::prelude::any::<u8>(), 0..24)),
1..12,
),
)| {
let bytes = unterminated_frame_of(
&tlvs
.iter()
.map(|(kind, value)| tlv(*kind, value))
.collect::<Vec<_>>(),
);
let frame = ethernet::parse(&bytes).expect("a frame");
if let Some(whole) = parse(&frame) {
for cut in ETH_HDR_LEN..bytes.len() {
let shorter = ethernet::parse(&bytes[..cut]).expect("a frame");
let Some(before) = parse(&shorter) else {
continue;
};
if before.chassis_id.is_some() {
proptest::prop_assert_eq!(before.chassis_id, whole.chassis_id);
}
if before.port_id.is_some() {
proptest::prop_assert_eq!(before.port_id, whole.port_id);
}
if before.ttl.is_some() {
proptest::prop_assert_eq!(before.ttl, whole.ttl);
}
if before.system_name.is_some() {
proptest::prop_assert_eq!(before.system_name, whole.system_name);
}
if before.capabilities.is_some() {
proptest::prop_assert_eq!(before.capabilities, whole.capabilities);
}
}
}
});
}
#[test]
fn a_second_unreadable_record_does_not_erase_the_first() {
let good = chassis_mac(SWITCH_MAC);
let bad = tlv(TLV_CHASSIS_ID, &[CHASSIS_SUBTYPE_MAC, 1, 2, 3, 4]);
let bytes = frame_of(&[good, bad, tlv(TLV_SYSTEM_NAME, b"core-01")]);
let frame = ethernet::parse(&bytes).expect("a frame");
let advertisement = parse(&frame).expect("an advertisement");
assert_eq!(advertisement.chassis_id, Some(Identifier::Mac(SWITCH_MAC)));
assert_eq!(advertisement.system_name, Some("core-01"));
}
#[test]
fn a_unit_of_endless_tlvs_terminates() {
let filler: Vec<Vec<u8>> =
std::iter::repeat_n(tlv(TLV_SYSTEM_NAME, b"a"), MAX_TLVS * 4).collect();
let mut tlvs = vec![chassis_mac(SWITCH_MAC)];
tlvs.extend(filler);
let bytes = frame_of(&tlvs);
let frame = ethernet::parse(&bytes).expect("an Ethernet frame");
let advertisement = parse(&frame).expect("it returns rather than hanging");
assert_eq!(advertisement.chassis_id, Some(Identifier::Mac(SWITCH_MAC)));
}
#[test]
fn a_unit_carrying_no_mandatory_field_is_not_an_advertisement() {
let bytes = frame_of(&[tlv(TLV_PORT_DESCRIPTION, b"only a description")]);
let frame = ethernet::parse(&bytes).expect("an Ethernet frame");
assert_eq!(parse(&frame), None);
}
#[test]
fn a_frame_of_another_protocol_is_declined() {
let bytes = ethernet::build_header(
SWITCH_MAC,
NEAREST_BRIDGE,
pnet_packet::ethernet::EtherTypes::Ipv4,
);
let frame = ethernet::parse(&bytes).expect("an Ethernet frame");
assert_eq!(parse(&frame), None);
}
}