Skip to content

v0.18.0 MACsec Support & ECN+DSCP Support for IPv6

Choose a tag to compare

View all tags
@JulianSchmid JulianSchmid released this 24 Apr 10:57
· 25 commits to master since this release
v0.18.0
c74726f
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Verified
Learn about vigilant mode.

What are the major changes?

  • Support for MACsec (IEEE 802.1AE)
  • The vlan field in SlicedPacket, LaxSlicedPacket, PacketHeaders, LaxPacketHeaders has been replaced with link_exts.
  • Ipv4Ecn & Ipv4Dscp have been replaced by IpEcn & IpDscp.
  • Ipv6Header & Ipv6HeaderSlice now supports the reading & setting of IpEcn & IpDscp (thanks to @baxterjo)
  • LaxEtherPayloadSlice has been introduced & len_source added to EtherPayloadSlice.
  • source_addr() & destination_addr() methods of IpSlice, Ipv4HeaderSlice, Ipv6Header, Ipv6HeaderSlice, LaxIpSlice are now available in non-std mode (thanks to @Dominaezzz)
  • Minimum supported Rust version as been configured to 1.83.0 (thanks to @baxterjo)

What is MACsec (IEEE 802.1AE)?

MACsec is a protocol that allows the signing and/or encryption of packet contents from the link layer downwards. The main difference between MACsec and IPSec is that IPSec is located after the IP header while MACsec is located above the IP header and can also encrypt the contents of the IP header itself while IPSSec does not encrypt the IP header. As such MACsec is usually used to secure local networks, while IPSec is more commonly used for VPNs and alike that leave the local network.

Changes needed for MACsec Support

Adding MACsec support required some breaking changes, specifically on how VLAN headers are handled. The MACsec SECTAG is a header that can be present in the same locations as "VLAN" headers. It has no fixed position and can be located before or after VLAN headers or after the Ethernet 2 header without a VLAN header being present at all. This invalidates the assumption etherparse had in previous versions that VLAN headers are always directly located after the Ethernet2 header and that if there are multiple VLAN headers that they are directly located after each other. Now there could be a MACsec header present in between VLAN headers.

To support the different combinations of MACSec & VLAN headers the vlan field in SlicedPacket, PacketHeaders, LaxSlicedPacket & LaxPacketHeaders has been replaced with a link_exts field that can contain up to three "link extensions":

pub struct SlicedPacket<'a> {
    /// Ethernet II header if present.
    pub link: Option<LinkSlice<'a>>,

-    /// Single or double vlan headers if present.
-    pub vlan: Option<VlanSlice<'a>>,
+    /// Link extensions (VLAN & MAC Sec headers).
+    pub link_exts: ArrayVec<LinkExtSlice<'a>, { SlicedPacket::LINK_EXTS_CAP }>,

    /// IPv4 or IPv6 header, IP extension headers & payload if present.
    pub net: Option<NetSlice<'a>>,

    /// TCP or UDP header & payload if present.
    pub transport: Option<TransportSlice<'a>>,
}

impl<'a> SlicedPacket<'a> {
+    /// Maximum supported number of link extensions.
+    pub const LINK_EXTS_CAP: usize = 3;

LinkExtSlice, LinkExtHeader & LaxLinkExtSlice are enums that can either contain a MACsec or VLAN header:

/// A slice containing the link layer extension header (currently only Ethernet II and
/// SLL are supported).
#[derive(Clone, Debug, Eq, PartialEq)]
pub enum LinkExtSlice<'a> {
    /// Slice containing a VLAN header & payload.
    Vlan(SingleVlanSlice<'a>),

    /// Slice containing MACsec header & payload.
    Macsec(MacsecSlice<'a>),
}

LINK_EXTS_CAP is currently set to 3. This means that up to three MACsec & VLAN headers can be parsed by etherparse.

New Methods to access VLAN related data:

In case you don't care about MACsec and only care about VLAN a new vlan() method has been added to SlicedPacket, PacketHeaders, LaxSlicedPacket & LaxPacketHeaders that behave the same as the old vlan field:

    /// Returns the first two VLAN headers.
    pub fn vlan(&self) -> Option<VlanHeader> {

If you only care about the VLAN ids you can also use the new vlan_ids() method in SlicedPacket, PacketHeaders, LaxSlicedPacket & LaxPacketHeaders:

    /// Returns the VLAN ids present in this packet.
    pub fn vlan_ids(&self) -> ArrayVec<VlanId, { SlicedPacket::LINK_EXTS_CAP }> {

New LaxEtherPayloadSlice & EtherPayloadSlice

As MACsec has an optional length field new LaxEtherPayloadSlice & EtherPayloadSlice structs have been introduced that can be used to keep track where the original length of the payload came from.

MacsecPayloadSlice

As MACsec can be "encrypted", "unencrypted without payload modification" and "unencrypted with payload modifications" a new payload enum has been introduced:

pub enum MacsecPayloadSlice<'a> {
    /// Unencrypted unmodified ether payload.
    Unmodified(EtherPayloadSlice<'a>),

    /// Modified payload (either by encryption or other algorithm).
    Modified(&'a [u8]),
}

In the unmodified case the next ether_type value can be read from the EtherPayloadSlice. In the encrypted or modified case this is not possible as there are no informations available on how to decrypt the packet or how the payload was modified.

What does the MACSec implementation not support?

Currently the ICV present at the end of an MACsec packet is not separated. The current implementation relies on the length fields of the lower layers (IP header, UDP or other transport length fields) to make sure it is not interpreted as data from a lower layer. The implementation is also missing any support for encrypting/decrypting payload data or verifying signatures. It is purely a "parse the parsable header fields" implementation.

Pull Requests

New Contributors

Thanks for your contributions.

Full Changelog: v0.17.0...v0.18.0

Contributors

JulianSchmid, hawkinsw, and 2 other contributors
Assets 2
Loading