mod fingerprint;
mod parser;
use std::net::SocketAddr;
pub use fingerprint::{
Ja4tFingerprint, LinkEstimate, LinkKind, NetworkEstimate, SatoriFingerprint, TcpFingerprint,
};
pub use parser::{LinkLayer, TcpPacketParseError};
use serde::{Deserialize, Serialize, Serializer};
const TCP_OPTION_END_OF_OPTIONS: u8 = 0;
const TCP_OPTION_NO_OPERATION: u8 = 1;
const TCP_OPTION_MAXIMUM_SEGMENT_SIZE: u8 = 2;
const TCP_OPTION_WINDOW_SCALE: u8 = 3;
const TCP_OPTION_SACK_PERMITTED: u8 = 4;
const TCP_OPTION_SACK: u8 = 5;
const TCP_OPTION_TIMESTAMP: u8 = 8;
const MAX_SACK_BLOCKS: usize = 4;
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct TcpPacket {
pub source: SocketAddr,
pub destination: SocketAddr,
pub wire_length: usize,
pub ip: IpHeader,
pub tcp: TcpHeader,
}
impl TcpPacket {
#[inline]
pub fn is_initial_syn(&self) -> bool {
self.tcp.flags.syn() && !self.tcp.flags.ack()
}
#[inline]
pub fn is_syn_ack(&self) -> bool {
self.tcp.flags.syn() && self.tcp.flags.ack()
}
#[inline]
pub fn is_handshake_ack(&self) -> bool {
self.tcp.flags.ack()
&& !self.tcp.flags.syn()
&& !self.tcp.flags.fin()
&& !self.tcp.flags.rst()
}
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
pub enum IpVersion {
Ipv4,
Ipv6,
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct IpHeader {
pub version: IpVersion,
pub header_length: usize,
pub packet_length: usize,
pub hop_limit: u8,
pub dscp: u8,
pub ecn: u8,
#[serde(skip_serializing_if = "Option::is_none")]
pub flow_label: Option<u32>,
#[serde(skip_serializing_if = "Option::is_none")]
pub identification: Option<u16>,
#[serde(skip_serializing_if = "Option::is_none")]
pub flags: Option<Ipv4Flags>,
pub fragment_offset: u16,
#[serde(skip_serializing_if = "Option::is_none")]
pub checksum: Option<u16>,
#[serde(skip_serializing_if = "Option::is_none")]
pub options: Option<Box<str>>,
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(try_from = "Ipv4FlagsRepr")]
pub struct Ipv4Flags {
raw: u8,
values: Vec<Ipv4Flag>,
}
#[derive(Deserialize)]
struct Ipv4FlagsRepr {
raw: u8,
values: Vec<Ipv4Flag>,
}
impl Ipv4Flags {
const RESERVED_MASK: u8 = 0x04;
const DONT_FRAGMENT_MASK: u8 = 0x02;
const MORE_FRAGMENTS_MASK: u8 = 0x01;
const VALID_MASK: u8 = 0x07;
pub(crate) fn from_raw(raw: u8) -> Self {
let values = [
(Self::RESERVED_MASK, Ipv4Flag::Reserved),
(Self::DONT_FRAGMENT_MASK, Ipv4Flag::DontFragment),
(Self::MORE_FRAGMENTS_MASK, Ipv4Flag::MoreFragments),
]
.into_iter()
.filter_map(|(mask, flag)| (raw & mask != 0).then_some(flag))
.collect();
Self { raw, values }
}
#[inline]
pub const fn raw(&self) -> u8 {
self.raw
}
#[inline]
pub fn values(&self) -> &[Ipv4Flag] {
&self.values
}
#[inline]
pub fn reserved(&self) -> bool {
self.raw & Self::RESERVED_MASK != 0
}
#[inline]
pub fn dont_fragment(&self) -> bool {
self.raw & Self::DONT_FRAGMENT_MASK != 0
}
#[inline]
pub fn more_fragments(&self) -> bool {
self.raw & Self::MORE_FRAGMENTS_MASK != 0
}
}
impl TryFrom<Ipv4FlagsRepr> for Ipv4Flags {
type Error = &'static str;
fn try_from(repr: Ipv4FlagsRepr) -> Result<Self, Self::Error> {
if repr.raw & !Self::VALID_MASK != 0 {
return Err("IPv4 flags contain bits outside the three-bit wire field");
}
let expected = Self::from_raw(repr.raw);
if repr.values != expected.values {
return Err("IPv4 flag values do not match the raw flag field");
}
Ok(expected)
}
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
pub enum Ipv4Flag {
Reserved,
DontFragment,
MoreFragments,
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct TcpHeader {
pub sequence_number: u32,
pub acknowledgment_number: u32,
pub header_length: usize,
pub reserved: u8,
pub flags: TcpFlags,
pub window_size: u16,
pub checksum: u16,
pub urgent_pointer: u16,
pub options: Vec<TcpOption>,
pub options_truncated: bool,
pub payload_length: usize,
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(try_from = "TcpFlagsRepr")]
pub struct TcpFlags {
raw: u16,
values: Vec<TcpFlag>,
}
#[derive(Deserialize)]
struct TcpFlagsRepr {
raw: u16,
values: Vec<TcpFlag>,
}
impl TcpFlags {
const NS_MASK: u16 = 0x100;
const CWR_MASK: u16 = 0x080;
const ECE_MASK: u16 = 0x040;
const URG_MASK: u16 = 0x020;
const ACK_MASK: u16 = 0x010;
const PSH_MASK: u16 = 0x008;
const RST_MASK: u16 = 0x004;
const SYN_MASK: u16 = 0x002;
const FIN_MASK: u16 = 0x001;
const VALID_MASK: u16 = 0x01ff;
pub(crate) fn from_raw(raw: u16) -> Self {
let values = [
(Self::NS_MASK, TcpFlag::Ns),
(Self::CWR_MASK, TcpFlag::Cwr),
(Self::ECE_MASK, TcpFlag::Ece),
(Self::URG_MASK, TcpFlag::Urg),
(Self::ACK_MASK, TcpFlag::Ack),
(Self::PSH_MASK, TcpFlag::Psh),
(Self::RST_MASK, TcpFlag::Rst),
(Self::SYN_MASK, TcpFlag::Syn),
(Self::FIN_MASK, TcpFlag::Fin),
]
.into_iter()
.filter_map(|(mask, flag)| (raw & mask != 0).then_some(flag))
.collect();
Self { raw, values }
}
#[inline]
pub const fn raw(&self) -> u16 {
self.raw
}
#[inline]
pub fn values(&self) -> &[TcpFlag] {
&self.values
}
#[inline]
pub fn ns(&self) -> bool {
self.raw & Self::NS_MASK != 0
}
#[inline]
pub fn fin(&self) -> bool {
self.raw & Self::FIN_MASK != 0
}
#[inline]
pub fn syn(&self) -> bool {
self.raw & Self::SYN_MASK != 0
}
#[inline]
pub fn rst(&self) -> bool {
self.raw & Self::RST_MASK != 0
}
#[inline]
pub fn psh(&self) -> bool {
self.raw & Self::PSH_MASK != 0
}
#[inline]
pub fn ack(&self) -> bool {
self.raw & Self::ACK_MASK != 0
}
#[inline]
pub fn urg(&self) -> bool {
self.raw & Self::URG_MASK != 0
}
#[inline]
pub fn ece(&self) -> bool {
self.raw & Self::ECE_MASK != 0
}
#[inline]
pub fn cwr(&self) -> bool {
self.raw & Self::CWR_MASK != 0
}
}
impl TryFrom<TcpFlagsRepr> for TcpFlags {
type Error = &'static str;
fn try_from(repr: TcpFlagsRepr) -> Result<Self, Self::Error> {
if repr.raw & !Self::VALID_MASK != 0 {
return Err("TCP flags contain bits outside the nine-bit wire field");
}
let expected = Self::from_raw(repr.raw);
if repr.values != expected.values {
return Err("TCP flag values do not match the raw flag field");
}
Ok(expected)
}
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
pub enum TcpFlag {
Ns,
Cwr,
Ece,
Urg,
Ack,
Psh,
Rst,
Syn,
Fin,
}
#[derive(Debug, Clone, PartialEq, Eq, Deserialize)]
#[serde(try_from = "TcpOptionRepr")]
pub enum TcpOption {
EndOfOptions,
NoOperation,
MaximumSegmentSize {
value: u16,
},
WindowScale {
value: u8,
},
SackPermitted,
Sack {
blocks: Vec<SackBlock>,
},
Timestamp {
value: u32,
echo_reply: u32,
},
Other {
id: u8,
value: Box<str>,
},
Malformed {
id: u8,
value: Box<str>,
},
}
#[derive(Deserialize)]
#[serde(tag = "name")]
enum TcpOptionRepr {
EndOfOptions { id: u8 },
NoOperation { id: u8 },
MaximumSegmentSize { id: u8, value: u16 },
WindowScale { id: u8, value: u8 },
SackPermitted { id: u8 },
Sack { id: u8, blocks: Vec<SackBlock> },
Timestamp { id: u8, value: u32, echo_reply: u32 },
Other { id: u8, value: Box<str> },
Malformed { id: u8, value: Box<str> },
}
#[derive(Serialize)]
#[serde(tag = "name")]
enum TcpOptionRef<'a> {
EndOfOptions { id: u8 },
NoOperation { id: u8 },
MaximumSegmentSize { id: u8, value: u16 },
WindowScale { id: u8, value: u8 },
SackPermitted { id: u8 },
Sack { id: u8, blocks: &'a [SackBlock] },
Timestamp { id: u8, value: u32, echo_reply: u32 },
Other { id: u8, value: &'a str },
Malformed { id: u8, value: &'a str },
}
impl TcpOption {
pub fn id(&self) -> u8 {
match self {
Self::EndOfOptions => TCP_OPTION_END_OF_OPTIONS,
Self::NoOperation => TCP_OPTION_NO_OPERATION,
Self::MaximumSegmentSize { .. } => TCP_OPTION_MAXIMUM_SEGMENT_SIZE,
Self::WindowScale { .. } => TCP_OPTION_WINDOW_SCALE,
Self::SackPermitted => TCP_OPTION_SACK_PERMITTED,
Self::Sack { .. } => TCP_OPTION_SACK,
Self::Timestamp { .. } => TCP_OPTION_TIMESTAMP,
Self::Other { id, .. } | Self::Malformed { id, .. } => *id,
}
}
}
impl TryFrom<TcpOptionRepr> for TcpOption {
type Error = &'static str;
fn try_from(repr: TcpOptionRepr) -> Result<Self, Self::Error> {
match repr {
TcpOptionRepr::EndOfOptions { id } => {
require_option_id(id, TCP_OPTION_END_OF_OPTIONS).map(|()| Self::EndOfOptions)
}
TcpOptionRepr::NoOperation { id } => {
require_option_id(id, TCP_OPTION_NO_OPERATION).map(|()| Self::NoOperation)
}
TcpOptionRepr::MaximumSegmentSize { id, value } => {
require_option_id(id, TCP_OPTION_MAXIMUM_SEGMENT_SIZE)
.map(|()| Self::MaximumSegmentSize { value })
}
TcpOptionRepr::WindowScale { id, value } => {
require_option_id(id, TCP_OPTION_WINDOW_SCALE).map(|()| Self::WindowScale { value })
}
TcpOptionRepr::SackPermitted { id } => {
require_option_id(id, TCP_OPTION_SACK_PERMITTED).map(|()| Self::SackPermitted)
}
TcpOptionRepr::Sack { id, blocks } => {
require_option_id(id, TCP_OPTION_SACK)?;
if !(1..=MAX_SACK_BLOCKS).contains(&blocks.len()) {
return Err("SACK requires between one and four blocks");
}
Ok(Self::Sack { blocks })
}
TcpOptionRepr::Timestamp {
id,
value,
echo_reply,
} => require_option_id(id, TCP_OPTION_TIMESTAMP)
.map(|()| Self::Timestamp { value, echo_reply }),
TcpOptionRepr::Other { id, value } => {
if is_decoded_option(id) {
return Err("decoded TCP option kinds cannot be represented as Other");
}
if !is_canonical_hex(value.as_ref()) {
return Err("TCP option payloads must use canonical lowercase hexadecimal");
}
Ok(Self::Other { id, value })
}
TcpOptionRepr::Malformed { id, value } => {
if !is_length_encoded_option(id) {
return Err("Malformed requires a recognized length-encoded TCP option kind");
}
if !is_canonical_hex(value.as_ref()) {
return Err("TCP option payloads must use canonical lowercase hexadecimal");
}
if option_payload_is_valid(id, value.len() / 2) {
return Err("a valid TCP option payload cannot be represented as Malformed");
}
Ok(Self::Malformed { id, value })
}
}
}
}
impl Serialize for TcpOption {
fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
where
S: Serializer,
{
let repr = match self {
Self::EndOfOptions => TcpOptionRef::EndOfOptions {
id: TCP_OPTION_END_OF_OPTIONS,
},
Self::NoOperation => TcpOptionRef::NoOperation {
id: TCP_OPTION_NO_OPERATION,
},
Self::MaximumSegmentSize { value } => TcpOptionRef::MaximumSegmentSize {
id: TCP_OPTION_MAXIMUM_SEGMENT_SIZE,
value: *value,
},
Self::WindowScale { value } => TcpOptionRef::WindowScale {
id: TCP_OPTION_WINDOW_SCALE,
value: *value,
},
Self::SackPermitted => TcpOptionRef::SackPermitted {
id: TCP_OPTION_SACK_PERMITTED,
},
Self::Sack { blocks } => TcpOptionRef::Sack {
id: TCP_OPTION_SACK,
blocks,
},
Self::Timestamp { value, echo_reply } => TcpOptionRef::Timestamp {
id: TCP_OPTION_TIMESTAMP,
value: *value,
echo_reply: *echo_reply,
},
Self::Other { id, value } => TcpOptionRef::Other { id: *id, value },
Self::Malformed { id, value } => TcpOptionRef::Malformed { id: *id, value },
};
repr.serialize(serializer)
}
}
fn require_option_id(id: u8, expected: u8) -> Result<(), &'static str> {
(id == expected)
.then_some(())
.ok_or("TCP option id does not match its name")
}
const fn is_decoded_option(id: u8) -> bool {
matches!(
id,
TCP_OPTION_END_OF_OPTIONS
| TCP_OPTION_NO_OPERATION
| TCP_OPTION_MAXIMUM_SEGMENT_SIZE
| TCP_OPTION_WINDOW_SCALE
| TCP_OPTION_SACK_PERMITTED
| TCP_OPTION_SACK
| TCP_OPTION_TIMESTAMP
)
}
const fn is_length_encoded_option(id: u8) -> bool {
matches!(
id,
TCP_OPTION_MAXIMUM_SEGMENT_SIZE
| TCP_OPTION_WINDOW_SCALE
| TCP_OPTION_SACK_PERMITTED
| TCP_OPTION_SACK
| TCP_OPTION_TIMESTAMP
)
}
fn is_canonical_hex(value: &str) -> bool {
value.len().is_multiple_of(2)
&& value
.bytes()
.all(|byte| byte.is_ascii_digit() || (b'a'..=b'f').contains(&byte))
}
const fn option_payload_is_valid(id: u8, length: usize) -> bool {
match id {
TCP_OPTION_MAXIMUM_SEGMENT_SIZE => length == 2,
TCP_OPTION_WINDOW_SCALE => length == 1,
TCP_OPTION_SACK_PERMITTED => length == 0,
TCP_OPTION_SACK => length > 0 && length.is_multiple_of(8),
TCP_OPTION_TIMESTAMP => length == 8,
_ => false,
}
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
pub struct SackBlock {
pub left_edge: u32,
pub right_edge: u32,
}
#[cfg(test)]
mod tests {
use serde_json::json;
use super::{Ipv4Flag, Ipv4Flags, TcpFlag, TcpFlags, TcpOption};
#[test]
fn tcp_flags_roundtrip_in_canonical_form() {
let flags = TcpFlags::from_raw(0x012);
let json = serde_json::to_value(&flags).unwrap();
let restored = serde_json::from_value(json).unwrap();
assert_eq!(flags, restored);
assert_eq!(flags.raw(), 0x012);
assert_eq!(flags.values(), [TcpFlag::Ack, TcpFlag::Syn]);
}
#[test]
fn tcp_flags_reject_inconsistent_or_out_of_range_values() {
assert!(serde_json::from_value::<TcpFlags>(json!({
"raw": 0,
"values": ["Syn"]
}))
.is_err());
assert!(serde_json::from_value::<TcpFlags>(json!({
"raw": 512,
"values": []
}))
.is_err());
}
#[test]
fn ipv4_flags_reject_inconsistent_values() {
let flags = Ipv4Flags::from_raw(0x02);
assert_eq!(flags.raw(), 0x02);
assert_eq!(flags.values(), [Ipv4Flag::DontFragment]);
assert!(serde_json::from_value::<Ipv4Flags>(json!({
"raw": 2,
"values": ["MoreFragments"]
}))
.is_err());
}
#[test]
fn known_tcp_options_serialize_their_canonical_id() {
let option = TcpOption::MaximumSegmentSize { value: 1_460 };
let json = serde_json::to_value(&option).unwrap();
assert_eq!(
json,
json!({
"name": "MaximumSegmentSize",
"id": 2,
"value": 1460
})
);
assert_eq!(serde_json::from_value::<TcpOption>(json).unwrap(), option);
}
#[test]
fn tcp_options_reject_mismatched_or_disguised_ids() {
assert!(serde_json::from_value::<TcpOption>(json!({
"name": "MaximumSegmentSize",
"id": 3,
"value": 1460
}))
.is_err());
assert!(serde_json::from_value::<TcpOption>(json!({
"name": "Other",
"id": 2,
"value": "05b4"
}))
.is_err());
assert!(serde_json::from_value::<TcpOption>(json!({
"name": "Other",
"id": 30,
"value": "AB"
}))
.is_err());
assert!(serde_json::from_value::<TcpOption>(json!({
"name": "Other",
"id": 30,
"value": "a"
}))
.is_err());
assert!(serde_json::from_value::<TcpOption>(json!({
"name": "Malformed",
"id": 2,
"value": "05b4"
}))
.is_err());
}
#[test]
fn sack_options_require_between_one_and_four_blocks() {
assert!(serde_json::from_value::<TcpOption>(json!({
"name": "Sack",
"id": 5,
"blocks": []
}))
.is_err());
assert!(serde_json::from_value::<TcpOption>(json!({
"name": "Sack",
"id": 5,
"blocks": (0..5)
.map(|value| json!({
"left_edge": value,
"right_edge": value + 1
}))
.collect::<Vec<_>>()
}))
.is_err());
}
#[test]
fn malformed_known_tcp_options_roundtrip_explicitly() {
let option = TcpOption::Malformed {
id: 5,
value: Box::from(""),
};
let json = serde_json::to_vec(&option).unwrap();
assert_eq!(serde_json::from_slice::<TcpOption>(&json).unwrap(), option);
}
}