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>;
|
|
|
|
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;
|
|
|
|
|
2019-10-04 17:10:20 +08:00
|
|
|
#[cfg(feature = "ethernet")]
|
2016-12-10 21:13:13 +08:00
|
|
|
mod ethernet;
|
2019-10-04 17:10:20 +08:00
|
|
|
#[cfg(all(feature = "proto-ipv4", feature = "ethernet"))]
|
2016-12-10 21:13:13 +08:00
|
|
|
mod arp;
|
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")]
|
|
|
|
mod ipv6option;
|
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")]
|
|
|
|
mod ipv6fragment;
|
2018-02-01 10:26:13 +08:00
|
|
|
#[cfg(feature = "proto-ipv6")]
|
|
|
|
mod ipv6routing;
|
2017-12-24 21:28:59 +08:00
|
|
|
#[cfg(feature = "proto-ipv4")]
|
2016-12-13 06:11:52 +08:00
|
|
|
mod icmpv4;
|
2018-01-18 09:27:14 +08:00
|
|
|
#[cfg(feature = "proto-ipv6")]
|
|
|
|
mod icmpv6;
|
2018-05-09 21:27:51 +08:00
|
|
|
#[cfg(any(feature = "proto-ipv4", feature = "proto-ipv6"))]
|
|
|
|
mod icmp;
|
2018-03-06 00:10:22 +08:00
|
|
|
#[cfg(feature = "proto-igmp")]
|
2018-03-12 02:08:08 +08:00
|
|
|
mod igmp;
|
2019-10-04 17:10:20 +08:00
|
|
|
#[cfg(all(feature = "proto-ipv6", feature = "ethernet"))]
|
2018-02-10 01:43:42 +08:00
|
|
|
mod ndisc;
|
2019-10-04 17:10:20 +08:00
|
|
|
#[cfg(all(feature = "proto-ipv6", feature = "ethernet"))]
|
2018-03-12 05:35:30 +08:00
|
|
|
mod ndiscoption;
|
2018-05-21 10:58:34 +08:00
|
|
|
#[cfg(feature = "proto-ipv6")]
|
|
|
|
mod mld;
|
2016-12-14 08:11:45 +08:00
|
|
|
mod udp;
|
2016-12-19 05:42:44 +08:00
|
|
|
mod tcp;
|
2018-07-25 03:56:01 +08:00
|
|
|
#[cfg(feature = "proto-dhcpv4")]
|
|
|
|
pub(crate) mod dhcpv4;
|
2016-12-10 21:13:13 +08:00
|
|
|
|
2016-12-11 07:15:56 +08:00
|
|
|
pub use self::pretty_print::PrettyPrinter;
|
|
|
|
|
2019-10-04 17:10:20 +08:00
|
|
|
#[cfg(feature = "ethernet")]
|
2017-12-17 05:45:24 +08:00
|
|
|
pub use self::ethernet::{EtherType as EthernetProtocol,
|
|
|
|
Address as EthernetAddress,
|
2018-02-15 17:03:04 +08:00
|
|
|
Frame as EthernetFrame,
|
|
|
|
Repr as EthernetRepr};
|
2016-12-10 21:13:13 +08:00
|
|
|
|
2019-10-04 17:10:20 +08:00
|
|
|
#[cfg(all(feature = "proto-ipv4", feature = "ethernet"))]
|
2017-12-17 05:45:24 +08:00
|
|
|
pub use self::arp::{Hardware as ArpHardware,
|
|
|
|
Operation as ArpOperation,
|
|
|
|
Packet as ArpPacket,
|
|
|
|
Repr as ArpRepr};
|
2016-12-10 21:13:13 +08:00
|
|
|
|
2017-12-17 05:45:24 +08:00
|
|
|
pub use self::ip::{Version as IpVersion,
|
|
|
|
Protocol as IpProtocol,
|
|
|
|
Address as IpAddress,
|
|
|
|
Endpoint as IpEndpoint,
|
|
|
|
Repr as IpRepr,
|
|
|
|
Cidr as IpCidr};
|
2016-12-13 01:26:06 +08:00
|
|
|
|
2017-12-24 21:28:59 +08:00
|
|
|
#[cfg(feature = "proto-ipv4")]
|
2017-12-17 05:45:24 +08:00
|
|
|
pub use self::ipv4::{Address as Ipv4Address,
|
|
|
|
Packet as Ipv4Packet,
|
|
|
|
Repr as Ipv4Repr,
|
2018-01-06 03:21:45 +08:00
|
|
|
Cidr as Ipv4Cidr,
|
|
|
|
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")]
|
|
|
|
pub use self::ipv6::{Address as Ipv6Address,
|
2017-12-01 13:05:05 +08:00
|
|
|
Packet as Ipv6Packet,
|
|
|
|
Repr as Ipv6Repr,
|
2018-01-06 03:21:45 +08:00
|
|
|
Cidr as Ipv6Cidr,
|
|
|
|
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")]
|
|
|
|
pub use self::ipv6option::{Ipv6Option,
|
|
|
|
Repr as Ipv6OptionRepr,
|
2018-05-10 03:05:19 +08:00
|
|
|
Type as Ipv6OptionType,
|
|
|
|
FailureType as Ipv6OptionFailureType};
|
2018-01-31 03:45:25 +08:00
|
|
|
|
2018-01-20 14:27:49 +08:00
|
|
|
#[cfg(feature = "proto-ipv6")]
|
|
|
|
pub use self::ipv6hopbyhop::{Header as Ipv6HopByHopHeader,
|
|
|
|
Repr as Ipv6HopByHopRepr};
|
|
|
|
|
2018-02-21 23:10:22 +08:00
|
|
|
#[cfg(feature = "proto-ipv6")]
|
|
|
|
pub use self::ipv6fragment::{Header as Ipv6FragmentHeader,
|
|
|
|
Repr as Ipv6FragmentRepr};
|
|
|
|
|
2018-02-01 10:26:13 +08:00
|
|
|
#[cfg(feature = "proto-ipv6")]
|
|
|
|
pub use self::ipv6routing::{Header as Ipv6RoutingHeader,
|
|
|
|
Repr as Ipv6RoutingRepr};
|
|
|
|
|
2017-12-24 21:28:59 +08:00
|
|
|
#[cfg(feature = "proto-ipv4")]
|
2017-12-17 05:45:24 +08:00
|
|
|
pub use self::icmpv4::{Message as Icmpv4Message,
|
|
|
|
DstUnreachable as Icmpv4DstUnreachable,
|
|
|
|
Redirect as Icmpv4Redirect,
|
|
|
|
TimeExceeded as Icmpv4TimeExceeded,
|
|
|
|
ParamProblem as Icmpv4ParamProblem,
|
|
|
|
Packet as Icmpv4Packet,
|
|
|
|
Repr as Icmpv4Repr};
|
2016-12-14 08:11:45 +08:00
|
|
|
|
2018-03-06 00:10:22 +08:00
|
|
|
#[cfg(feature = "proto-igmp")]
|
2018-03-12 02:08:08 +08:00
|
|
|
pub use self::igmp::{Packet as IgmpPacket,
|
|
|
|
Repr as IgmpRepr,
|
|
|
|
IgmpVersion};
|
|
|
|
|
2018-01-18 09:27:14 +08:00
|
|
|
#[cfg(feature = "proto-ipv6")]
|
|
|
|
pub use self::icmpv6::{Message as Icmpv6Message,
|
|
|
|
DstUnreachable as Icmpv6DstUnreachable,
|
2018-02-06 00:24:25 +08:00
|
|
|
TimeExceeded as Icmpv6TimeExceeded,
|
|
|
|
ParamProblem as Icmpv6ParamProblem,
|
2018-01-18 09:27:14 +08:00
|
|
|
Packet as Icmpv6Packet,
|
|
|
|
Repr as Icmpv6Repr};
|
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
|
|
|
|
2018-02-10 01:43:42 +08:00
|
|
|
|
2019-10-04 17:10:20 +08:00
|
|
|
#[cfg(all(feature = "proto-ipv6", feature = "ethernet"))]
|
2018-05-27 02:10:27 +08:00
|
|
|
pub use self::ndisc::{Repr as NdiscRepr,
|
|
|
|
RouterFlags as NdiscRouterFlags,
|
|
|
|
NeighborFlags as NdiscNeighborFlags};
|
2018-04-13 00:42:09 +08:00
|
|
|
|
2019-10-04 17:10:20 +08:00
|
|
|
#[cfg(all(feature = "proto-ipv6", feature = "ethernet"))]
|
2018-03-12 05:35:30 +08:00
|
|
|
pub use self::ndiscoption::{NdiscOption,
|
|
|
|
Repr as NdiscOptionRepr,
|
|
|
|
Type as NdiscOptionType,
|
2018-04-21 00:03:56 +08:00
|
|
|
PrefixInformation as NdiscPrefixInformation,
|
|
|
|
RedirectedHeader as NdiscRedirectedHeader,
|
2018-03-12 05:35:30 +08:00
|
|
|
PrefixInfoFlags as NdiscPrefixInfoFlags};
|
|
|
|
|
2018-05-21 10:58:34 +08:00
|
|
|
#[cfg(feature = "proto-ipv6")]
|
2018-06-26 20:24:24 +08:00
|
|
|
pub use self::mld::{AddressRecord as MldAddressRecord,
|
|
|
|
Repr as MldRepr};
|
2018-05-21 10:58:34 +08:00
|
|
|
|
2017-12-17 05:45:24 +08:00
|
|
|
pub use self::udp::{Packet as UdpPacket,
|
|
|
|
Repr as UdpRepr};
|
2016-12-19 05:42:44 +08:00
|
|
|
|
2017-12-17 05:45:24 +08:00
|
|
|
pub use self::tcp::{SeqNumber as TcpSeqNumber,
|
|
|
|
Packet as TcpPacket,
|
|
|
|
TcpOption,
|
|
|
|
Repr as TcpRepr,
|
|
|
|
Control as TcpControl};
|
2017-11-08 23:04:42 +08:00
|
|
|
|
2018-07-25 03:56:01 +08:00
|
|
|
#[cfg(feature = "proto-dhcpv4")]
|
2017-11-08 23:04:42 +08:00
|
|
|
pub use self::dhcpv4::{Packet as DhcpPacket,
|
2018-07-25 03:56:01 +08:00
|
|
|
Repr as DhcpRepr,
|
|
|
|
MessageType as DhcpMessageType};
|