smoltcp

Module wire

Source
Expand description

Low-level packet access and construction.

The wire module deals with the packet representation. It provides two levels of functionality.

  • First, it provides functions to extract fields from sequences of octets, and to insert fields into sequences of octets. This happens Packet family of structures, e.g. EthernetFrame or Ipv4Packet.
  • Second, in cases where the space of valid field values is much smaller than the space of possible field values, it provides a compact, high-level representation of packet data that can be parsed from and emitted into a sequence of octets. This happens through the Repr family of structs and enums, e.g. ArpRepr or Ipv4Repr.

The functions in the wire module are designed for use together with -Cpanic=abort.

The Packet family of data structures guarantees that, if the Packet::check_len() method returned Ok(()), then no accessor or setter method will panic; however, the guarantee provided by Packet::check_len() may no longer hold after changing certain fields, which are listed in the documentation for the specific packet.

The Packet::new_checked method is a shorthand for a combination of Packet::new_unchecked and Packet::check_len. When parsing untrusted input, it is necessary to use Packet::new_checked(); so long as the buffer is not modified, no accessor will fail. When emitting output, though, it is incorrect to use Packet::new_checked(); the length check is likely to succeed on a zeroed buffer, but fail on a buffer filled with data from a previous packet, such as when reusing buffers, resulting in nondeterministic panics with some network devices but not others. The buffer length for emission is not calculated by the Packet layer.

In the Repr family of data structures, the Repr::parse() method never panics as long as Packet::new_checked() (or Packet::check_len()) has succeeded, and the Repr::emit() method never panics as long as the underlying buffer is exactly Repr::buffer_len() octets long.

§Examples

To emit an IP packet header into an octet buffer, and then parse it back:

use smoltcp::phy::ChecksumCapabilities;
use smoltcp::wire::*;
let repr = Ipv4Repr {
    src_addr:    Ipv4Address::new(10, 0, 0, 1),
    dst_addr:    Ipv4Address::new(10, 0, 0, 2),
    next_header: IpProtocol::Tcp,
    payload_len: 10,
    hop_limit:   64,
};
let mut buffer = vec![0; repr.buffer_len() + repr.payload_len];
{ // emission
    let mut packet = Ipv4Packet::new_unchecked(&mut buffer);
    repr.emit(&mut packet, &ChecksumCapabilities::default());
}
{ // parsing
    let packet = Ipv4Packet::new_checked(&buffer)
                            .expect("truncated packet");
    let parsed = Ipv4Repr::parse(&packet, &ChecksumCapabilities::default())
                          .expect("malformed packet");
    assert_eq!(repr, parsed);
}

Re-exports§

Modules§

Structs§

Enums§

  • ArpHardware
    ARP hardware type.
  • ArpOperation
    ARP operation type.
  • ArpRepr
    A high-level representation of an Address Resolution Protocol packet.
  • DhcpMessageType
    The possible message types of a DHCP packet.
  • EthernetProtocol
    Ethernet protocol type.
  • HardwareAddress
    Representation of an hardware address, such as an Ethernet address or an IEEE802.15.4 address.
  • IcmpRepr
  • Icmpv4DstUnreachable
    Internet protocol control message subtype for type “Destination Unreachable”.
  • Icmpv4Message
    Internet protocol control message type.
  • Icmpv4ParamProblem
    Internet protocol control message subtype for type “Parameter Problem”.
  • Icmpv4Redirect
    Internet protocol control message subtype for type “Redirect Message”.
  • Icmpv4Repr
    A high-level representation of an Internet Control Message Protocol version 4 packet header.
  • Icmpv4TimeExceeded
    Internet protocol control message subtype for type “Time Exceeded”.
  • Icmpv6DstUnreachable
    Internet protocol control message subtype for type “Destination Unreachable”.
  • Icmpv6Message
    Internet protocol control message type.
  • Icmpv6ParamProblem
    Internet protocol control message subtype for the type “Parameter Problem”.
  • Icmpv6Repr
    A high-level representation of an Internet Control Message Protocol version 6 packet header.
  • Icmpv6TimeExceeded
    Internet protocol control message subtype for the type “Time Exceeded”.
  • IpAddress
    An internetworking address.
  • IpCidr
    A specification of a CIDR block, containing an address and a variable-length subnet masking prefix length.
  • IpProtocol
    IP datagram encapsulated protocol.
  • IpRepr
    An IP packet representation.
  • IpVersion
    Internet protocol version.
  • Ipv6OptionFailureType
    Action required when parsing the given IPv6 Extension Header Option Type fails
  • Ipv6OptionRepr
    A high-level representation of an IPv6 Extension Header Option.
  • Ipv6OptionType
    IPv6 Extension Header Option Type
  • Ipv6RoutingRepr
    A high-level representation of an IPv6 Routing Header.
  • Ipv6RoutingType
    IPv6 Extension Routing Header Routing Type
  • MldRepr
    A high-level representation of an MLDv2 packet header.
  • NdiscOptionRepr
    A high-level representation of an NDISC Option.
  • NdiscOptionType
    NDISC Option Type
  • NdiscRepr
    A high-level representation of an Neighbor Discovery packet header.
  • TcpControl
    The possible control flags of a Transmission Control Protocol packet.
  • TcpOption
    A representation of a single TCP option.

Constants§

Type Aliases§