2018-01-06 03:38:23 +08:00
|
|
|
/*! 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].
|
|
|
|
|
|
|
|
[EthernetFrame]: struct.EthernetFrame.html
|
|
|
|
[Ipv4Packet]: struct.Ipv4Packet.html
|
|
|
|
[ArpRepr]: enum.ArpRepr.html
|
|
|
|
[Ipv4Repr]: struct.Ipv4Repr.html
|
|
|
|
|
|
|
|
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.
|
|
|
|
|
2018-07-11 08:22:43 +08:00
|
|
|
The `Packet::new_checked` method is a shorthand for a combination of `Packet::new_unchecked`
|
|
|
|
and `Packet::check_len`.
|
2018-01-06 03:38:23 +08:00
|
|
|
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:
|
|
|
|
|
2016-12-31 19:44:51 +08:00
|
|
|
```rust
|
2017-12-24 21:28:59 +08:00
|
|
|
# #[cfg(feature = "proto-ipv4")]
|
|
|
|
# {
|
2017-10-02 18:47:51 +08:00
|
|
|
use smoltcp::phy::ChecksumCapabilities;
|
2016-12-31 19:44:51 +08:00
|
|
|
use smoltcp::wire::*;
|
|
|
|
let repr = Ipv4Repr {
|
2017-01-14 19:07:06 +08:00
|
|
|
src_addr: Ipv4Address::new(10, 0, 0, 1),
|
|
|
|
dst_addr: Ipv4Address::new(10, 0, 0, 2),
|
|
|
|
protocol: IpProtocol::Tcp,
|
2017-10-15 08:05:55 +08:00
|
|
|
payload_len: 10,
|
2017-12-10 11:09:50 +08:00
|
|
|
hop_limit: 64
|
2016-12-31 19:44:51 +08:00
|
|
|
};
|
Do not attempt to validate length of packets being emitted.
This is a form of an uninitialized read bug; although safe it caused
panics. In short, transmit buffers received from the network stack
should be considered uninitialized (in practice they will often
contain previously transmitted packets or parts thereof). Wrapping
them with the only method we had (e.g. Ipv4Packet) treated the buffer
as if it contained a valid incoming packet, which can easily fail
with Error::Truncated.
This commit splits every `fn new(buffer: T) -> Result<Self, Error>`
method on a `Packet` into three smaller ones:
* `fn check_len(&self) -> Result<(), Error>`, purely a validator;
* `fn new(T) -> Self`, purely a wrapper;
* `fn new_checked(T) -> Result<Self, Error>`, a validating wrapper.
This makes it easy to process ingress packets (using `new_checked`),
egress packets (using `new`), and, if needed, maintain the invariants
at any point during packet construction (using `check_len`).
Fixes #17.
2017-06-24 17:15:22 +08:00
|
|
|
let mut buffer = vec![0; repr.buffer_len() + repr.payload_len];
|
2016-12-31 19:44:51 +08:00
|
|
|
{ // emission
|
2018-07-11 08:22:43 +08:00
|
|
|
let mut packet = Ipv4Packet::new_unchecked(&mut buffer);
|
2017-10-02 18:47:51 +08:00
|
|
|
repr.emit(&mut packet, &ChecksumCapabilities::default());
|
2016-12-31 19:44:51 +08:00
|
|
|
}
|
|
|
|
{ // parsing
|
Do not attempt to validate length of packets being emitted.
This is a form of an uninitialized read bug; although safe it caused
panics. In short, transmit buffers received from the network stack
should be considered uninitialized (in practice they will often
contain previously transmitted packets or parts thereof). Wrapping
them with the only method we had (e.g. Ipv4Packet) treated the buffer
as if it contained a valid incoming packet, which can easily fail
with Error::Truncated.
This commit splits every `fn new(buffer: T) -> Result<Self, Error>`
method on a `Packet` into three smaller ones:
* `fn check_len(&self) -> Result<(), Error>`, purely a validator;
* `fn new(T) -> Self`, purely a wrapper;
* `fn new_checked(T) -> Result<Self, Error>`, a validating wrapper.
This makes it easy to process ingress packets (using `new_checked`),
egress packets (using `new`), and, if needed, maintain the invariants
at any point during packet construction (using `check_len`).
Fixes #17.
2017-06-24 17:15:22 +08:00
|
|
|
let packet = Ipv4Packet::new_checked(&buffer)
|
|
|
|
.expect("truncated packet");
|
2017-10-02 18:47:51 +08:00
|
|
|
let parsed = Ipv4Repr::parse(&packet, &ChecksumCapabilities::default())
|
Do not attempt to validate length of packets being emitted.
This is a form of an uninitialized read bug; although safe it caused
panics. In short, transmit buffers received from the network stack
should be considered uninitialized (in practice they will often
contain previously transmitted packets or parts thereof). Wrapping
them with the only method we had (e.g. Ipv4Packet) treated the buffer
as if it contained a valid incoming packet, which can easily fail
with Error::Truncated.
This commit splits every `fn new(buffer: T) -> Result<Self, Error>`
method on a `Packet` into three smaller ones:
* `fn check_len(&self) -> Result<(), Error>`, purely a validator;
* `fn new(T) -> Self`, purely a wrapper;
* `fn new_checked(T) -> Result<Self, Error>`, a validating wrapper.
This makes it easy to process ingress packets (using `new_checked`),
egress packets (using `new`), and, if needed, maintain the invariants
at any point during packet construction (using `check_len`).
Fixes #17.
2017-06-24 17:15:22 +08:00
|
|
|
.expect("malformed packet");
|
2016-12-31 19:44:51 +08:00
|
|
|
assert_eq!(repr, parsed);
|
|
|
|
}
|
2017-12-24 21:28:59 +08:00
|
|
|
# }
|
2016-12-31 19:44:51 +08:00
|
|
|
```
|
|
|
|
*/
|
2016-12-10 21:13:13 +08:00
|
|
|
|
|
|
|
mod field {
|
2016-12-14 08:11:45 +08:00
|
|
|
pub type Field = ::core::ops::Range<usize>;
|
2021-06-27 15:31:59 +08:00
|
|
|
pub type Rest = ::core::ops::RangeFrom<usize>;
|
2016-12-10 21:13:13 +08:00
|
|
|
}
|
|
|
|
|
2016-12-11 07:15:56 +08:00
|
|
|
pub mod pretty_print;
|
|
|
|
|
2020-12-28 06:52:37 +08:00
|
|
|
#[cfg(all(feature = "proto-ipv4", feature = "medium-ethernet"))]
|
2016-12-10 21:13:13 +08:00
|
|
|
mod arp;
|
2021-06-27 15:31:59 +08:00
|
|
|
#[cfg(feature = "proto-dhcpv4")]
|
|
|
|
pub(crate) mod dhcpv4;
|
|
|
|
#[cfg(feature = "medium-ethernet")]
|
|
|
|
mod ethernet;
|
|
|
|
#[cfg(any(feature = "proto-ipv4", feature = "proto-ipv6"))]
|
|
|
|
mod icmp;
|
|
|
|
#[cfg(feature = "proto-ipv4")]
|
|
|
|
mod icmpv4;
|
|
|
|
#[cfg(feature = "proto-ipv6")]
|
|
|
|
mod icmpv6;
|
|
|
|
#[cfg(feature = "proto-igmp")]
|
|
|
|
mod igmp;
|
2017-12-24 21:28:59 +08:00
|
|
|
pub(crate) mod ip;
|
|
|
|
#[cfg(feature = "proto-ipv4")]
|
2016-12-10 21:13:13 +08:00
|
|
|
mod ipv4;
|
2017-11-02 11:55:10 +08:00
|
|
|
#[cfg(feature = "proto-ipv6")]
|
|
|
|
mod ipv6;
|
2018-01-31 03:45:25 +08:00
|
|
|
#[cfg(feature = "proto-ipv6")]
|
2021-06-27 15:31:59 +08:00
|
|
|
mod ipv6fragment;
|
2018-01-20 14:27:49 +08:00
|
|
|
#[cfg(feature = "proto-ipv6")]
|
|
|
|
mod ipv6hopbyhop;
|
2018-02-21 23:10:22 +08:00
|
|
|
#[cfg(feature = "proto-ipv6")]
|
2021-06-27 15:31:59 +08:00
|
|
|
mod ipv6option;
|
2018-02-01 10:26:13 +08:00
|
|
|
#[cfg(feature = "proto-ipv6")]
|
|
|
|
mod ipv6routing;
|
2018-01-18 09:27:14 +08:00
|
|
|
#[cfg(feature = "proto-ipv6")]
|
2021-06-27 15:31:59 +08:00
|
|
|
mod mld;
|
2020-12-28 06:52:37 +08:00
|
|
|
#[cfg(all(feature = "proto-ipv6", feature = "medium-ethernet"))]
|
2018-02-10 01:43:42 +08:00
|
|
|
mod ndisc;
|
2020-12-28 06:52:37 +08:00
|
|
|
#[cfg(all(feature = "proto-ipv6", feature = "medium-ethernet"))]
|
2018-03-12 05:35:30 +08:00
|
|
|
mod ndiscoption;
|
2016-12-19 05:42:44 +08:00
|
|
|
mod tcp;
|
2021-06-27 15:31:59 +08:00
|
|
|
mod udp;
|
2016-12-10 21:13:13 +08:00
|
|
|
|
2016-12-11 07:15:56 +08:00
|
|
|
pub use self::pretty_print::PrettyPrinter;
|
|
|
|
|
2020-12-28 06:52:37 +08:00
|
|
|
#[cfg(feature = "medium-ethernet")]
|
2021-06-27 15:31:59 +08:00
|
|
|
pub use self::ethernet::{
|
|
|
|
Address as EthernetAddress, EtherType as EthernetProtocol, Frame as EthernetFrame,
|
|
|
|
Repr as EthernetRepr, HEADER_LEN as ETHERNET_HEADER_LEN,
|
|
|
|
};
|
2016-12-10 21:13:13 +08:00
|
|
|
|
2020-12-28 06:52:37 +08:00
|
|
|
#[cfg(all(feature = "proto-ipv4", feature = "medium-ethernet"))]
|
2021-06-27 15:31:59 +08:00
|
|
|
pub use self::arp::{
|
|
|
|
Hardware as ArpHardware, Operation as ArpOperation, Packet as ArpPacket, Repr as ArpRepr,
|
|
|
|
};
|
|
|
|
|
|
|
|
pub use self::ip::{
|
|
|
|
Address as IpAddress, Cidr as IpCidr, Endpoint as IpEndpoint, Protocol as IpProtocol,
|
|
|
|
Repr as IpRepr, Version as IpVersion,
|
|
|
|
};
|
2016-12-13 01:26:06 +08:00
|
|
|
|
2017-12-24 21:28:59 +08:00
|
|
|
#[cfg(feature = "proto-ipv4")]
|
2021-06-27 15:31:59 +08:00
|
|
|
pub use self::ipv4::{
|
|
|
|
Address as Ipv4Address, Cidr as Ipv4Cidr, Packet as Ipv4Packet, Repr as Ipv4Repr,
|
|
|
|
HEADER_LEN as IPV4_HEADER_LEN, MIN_MTU as IPV4_MIN_MTU,
|
|
|
|
};
|
2016-12-13 06:11:52 +08:00
|
|
|
|
2017-11-02 11:55:10 +08:00
|
|
|
#[cfg(feature = "proto-ipv6")]
|
2021-06-27 15:31:59 +08:00
|
|
|
pub use self::ipv6::{
|
|
|
|
Address as Ipv6Address, Cidr as Ipv6Cidr, Packet as Ipv6Packet, Repr as Ipv6Repr,
|
|
|
|
HEADER_LEN as IPV6_HEADER_LEN, MIN_MTU as IPV6_MIN_MTU,
|
|
|
|
};
|
2017-11-02 11:55:10 +08:00
|
|
|
|
2018-01-31 03:45:25 +08:00
|
|
|
#[cfg(feature = "proto-ipv6")]
|
2021-06-27 15:31:59 +08:00
|
|
|
pub use self::ipv6option::{
|
|
|
|
FailureType as Ipv6OptionFailureType, Ipv6Option, Repr as Ipv6OptionRepr,
|
|
|
|
Type as Ipv6OptionType,
|
|
|
|
};
|
2018-01-31 03:45:25 +08:00
|
|
|
|
2018-01-20 14:27:49 +08:00
|
|
|
#[cfg(feature = "proto-ipv6")]
|
2021-06-27 15:31:59 +08:00
|
|
|
pub use self::ipv6hopbyhop::{Header as Ipv6HopByHopHeader, Repr as Ipv6HopByHopRepr};
|
2018-01-20 14:27:49 +08:00
|
|
|
|
2018-02-21 23:10:22 +08:00
|
|
|
#[cfg(feature = "proto-ipv6")]
|
2021-06-27 15:31:59 +08:00
|
|
|
pub use self::ipv6fragment::{Header as Ipv6FragmentHeader, Repr as Ipv6FragmentRepr};
|
2018-02-21 23:10:22 +08:00
|
|
|
|
2018-02-01 10:26:13 +08:00
|
|
|
#[cfg(feature = "proto-ipv6")]
|
2021-06-27 15:31:59 +08:00
|
|
|
pub use self::ipv6routing::{Header as Ipv6RoutingHeader, Repr as Ipv6RoutingRepr};
|
2018-02-01 10:26:13 +08:00
|
|
|
|
2017-12-24 21:28:59 +08:00
|
|
|
#[cfg(feature = "proto-ipv4")]
|
2021-06-27 15:31:59 +08:00
|
|
|
pub use self::icmpv4::{
|
|
|
|
DstUnreachable as Icmpv4DstUnreachable, Message as Icmpv4Message, Packet as Icmpv4Packet,
|
|
|
|
ParamProblem as Icmpv4ParamProblem, Redirect as Icmpv4Redirect, Repr as Icmpv4Repr,
|
|
|
|
TimeExceeded as Icmpv4TimeExceeded,
|
|
|
|
};
|
2016-12-14 08:11:45 +08:00
|
|
|
|
2018-03-06 00:10:22 +08:00
|
|
|
#[cfg(feature = "proto-igmp")]
|
2021-06-27 15:31:59 +08:00
|
|
|
pub use self::igmp::{IgmpVersion, Packet as IgmpPacket, Repr as IgmpRepr};
|
2018-03-12 02:08:08 +08:00
|
|
|
|
2018-01-18 09:27:14 +08:00
|
|
|
#[cfg(feature = "proto-ipv6")]
|
2021-06-27 15:31:59 +08:00
|
|
|
pub use self::icmpv6::{
|
|
|
|
DstUnreachable as Icmpv6DstUnreachable, Message as Icmpv6Message, Packet as Icmpv6Packet,
|
|
|
|
ParamProblem as Icmpv6ParamProblem, Repr as Icmpv6Repr, TimeExceeded as Icmpv6TimeExceeded,
|
|
|
|
};
|
2018-05-21 10:58:34 +08:00
|
|
|
|
2018-05-09 21:27:51 +08:00
|
|
|
#[cfg(any(feature = "proto-ipv4", feature = "proto-ipv6"))]
|
|
|
|
pub use self::icmp::Repr as IcmpRepr;
|
2018-01-18 09:27:14 +08:00
|
|
|
|
2020-12-28 06:52:37 +08:00
|
|
|
#[cfg(all(feature = "proto-ipv6", feature = "medium-ethernet"))]
|
2021-06-27 15:31:59 +08:00
|
|
|
pub use self::ndisc::{
|
|
|
|
NeighborFlags as NdiscNeighborFlags, Repr as NdiscRepr, RouterFlags as NdiscRouterFlags,
|
|
|
|
};
|
2018-04-13 00:42:09 +08:00
|
|
|
|
2020-12-28 06:52:37 +08:00
|
|
|
#[cfg(all(feature = "proto-ipv6", feature = "medium-ethernet"))]
|
2021-06-27 15:31:59 +08:00
|
|
|
pub use self::ndiscoption::{
|
|
|
|
NdiscOption, PrefixInfoFlags as NdiscPrefixInfoFlags,
|
|
|
|
PrefixInformation as NdiscPrefixInformation, RedirectedHeader as NdiscRedirectedHeader,
|
|
|
|
Repr as NdiscOptionRepr, Type as NdiscOptionType,
|
|
|
|
};
|
2018-03-12 05:35:30 +08:00
|
|
|
|
2018-05-21 10:58:34 +08:00
|
|
|
#[cfg(feature = "proto-ipv6")]
|
2021-06-27 15:31:59 +08:00
|
|
|
pub use self::mld::{AddressRecord as MldAddressRecord, Repr as MldRepr};
|
2018-05-21 10:58:34 +08:00
|
|
|
|
2021-06-27 15:31:59 +08:00
|
|
|
pub use self::udp::{Packet as UdpPacket, Repr as UdpRepr, HEADER_LEN as UDP_HEADER_LEN};
|
2016-12-19 05:42:44 +08:00
|
|
|
|
2021-06-27 15:31:59 +08:00
|
|
|
pub use self::tcp::{
|
|
|
|
Control as TcpControl, Packet as TcpPacket, Repr as TcpRepr, SeqNumber as TcpSeqNumber,
|
|
|
|
TcpOption, HEADER_LEN as TCP_HEADER_LEN,
|
|
|
|
};
|
2017-11-08 23:04:42 +08:00
|
|
|
|
2018-07-25 03:56:01 +08:00
|
|
|
#[cfg(feature = "proto-dhcpv4")]
|
2021-06-27 15:31:59 +08:00
|
|
|
pub use self::dhcpv4::{
|
|
|
|
MessageType as DhcpMessageType, Packet as DhcpPacket, Repr as DhcpRepr,
|
|
|
|
CLIENT_PORT as DHCP_CLIENT_PORT, MAX_DNS_SERVER_COUNT as DHCP_MAX_DNS_SERVER_COUNT,
|
|
|
|
SERVER_PORT as DHCP_SERVER_PORT,
|
|
|
|
};
|