use std::net::IpAddr;
use crate::model::technique::{TcpReply, TcpScanTechnique};
use crate::protocols::craft;
use crate::protocols::error::{PacketError, Result};
use crate::protocols::sizes::TCP_HDR_LEN;
pub mod flags {
pub const FIN: u8 = 1;
pub const SYN: u8 = 1 << 1;
pub const RST: u8 = 1 << 2;
pub const PSH: u8 = 1 << 3;
pub const ACK: u8 = 1 << 4;
pub const URG: u8 = 1 << 5;
}
#[cfg(test)]
const TCP_HDR_LEN_WITH_OPTIONS: usize = TCP_HDR_LEN + SYN_OPTIONS_LEN;
#[cfg(test)]
const WORD_IN_BYTES: usize = 4;
pub(crate) const PROBE_WINDOW: u16 = 1024;
const PROBE_MSS: u16 = 1412;
const SYN_OPTIONS_LEN: usize = 20;
pub const fn probe_flags(technique: TcpScanTechnique) -> u8 {
match technique {
TcpScanTechnique::Syn => flags::SYN,
TcpScanTechnique::Fin => flags::FIN,
TcpScanTechnique::Null => 0,
TcpScanTechnique::Xmas => flags::FIN | flags::PSH | flags::URG,
TcpScanTechnique::Maimon => flags::FIN | flags::ACK,
TcpScanTechnique::Ack | TcpScanTechnique::Window => flags::ACK,
}
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
enum NonceField {
Sequence { span: u32 },
Acknowledgement,
}
const fn nonce_field(flags: u8) -> NonceField {
if flags & flags::ACK != 0 {
return NonceField::Acknowledgement;
}
let mut span = 0;
if flags & flags::SYN != 0 {
span += 1;
}
if flags & flags::FIN != 0 {
span += 1;
}
NonceField::Sequence { span }
}
pub fn build_probe(
technique: TcpScanTechnique,
src_addr: IpAddr,
dst_addr: IpAddr,
src_port: u16,
dst_port: u16,
nonce: u32,
) -> Result<Vec<u8>> {
build_probe_shaped(
technique, src_addr, dst_addr, src_port, dst_port, nonce, None, false,
)
}
#[allow(clippy::too_many_arguments)]
pub fn build_probe_shaped(
technique: TcpScanTechnique,
src_addr: IpAddr,
dst_addr: IpAddr,
src_port: u16,
dst_port: u16,
nonce: u32,
padding: Option<u16>,
bad_checksum: bool,
) -> Result<Vec<u8>> {
build_probe_with_flags(
probe_flags(technique),
src_addr,
dst_addr,
src_port,
dst_port,
nonce,
padding,
bad_checksum,
)
}
#[allow(clippy::too_many_arguments)]
pub(crate) fn build_probe_with_flags(
flags: u8,
src_addr: IpAddr,
dst_addr: IpAddr,
src_port: u16,
dst_port: u16,
nonce: u32,
padding: Option<u16>,
bad_checksum: bool,
) -> Result<Vec<u8>> {
let mut segment = craft::Tcp::new(src_port, dst_port).with_flags(flags);
match nonce_field(flags) {
NonceField::Sequence { .. } => {
segment.sequence = nonce;
segment.acknowledgement = 0;
}
NonceField::Acknowledgement => {
segment.sequence = rand::random();
segment.acknowledgement = nonce;
}
}
if flags & flags::SYN != 0 {
segment.options = syn_options(PROBE_MSS);
}
if let Some(len) = padding {
segment.payload = craft::random_padding(len);
}
let addresses = (src_addr, dst_addr);
if bad_checksum {
segment.checksum = craft::Field::Exact(segment.corrupt_checksum(Some(addresses))?);
}
segment.to_bytes(Some(addresses))
}
fn syn_options(mss: u16) -> Vec<u8> {
let [high, low] = mss.to_be_bytes();
let timestamp: u32 = rand::random();
let mut options = Vec::with_capacity(SYN_OPTIONS_LEN);
options.extend_from_slice(&[2, 4, high, low]); options.extend_from_slice(&[4, 2]); options.extend_from_slice(&[8, 10]); options.extend_from_slice(×tamp.to_be_bytes()); options.extend_from_slice(&0u32.to_be_bytes()); options.push(1); options.extend_from_slice(&[3, 3, 7]);
debug_assert_eq!(options.len(), SYN_OPTIONS_LEN);
options
}
pub fn echoed_nonce(technique: TcpScanTechnique, reply: &Segment<'_>, padding: u16) -> u32 {
echoed_nonce_with_flags(probe_flags(technique), reply, padding)
}
pub(crate) fn sent_nonce_with_flags(flags: u8, probe: &Segment<'_>) -> u32 {
match nonce_field(flags) {
NonceField::Sequence { .. } => probe.sequence(),
NonceField::Acknowledgement => probe.acknowledgement(),
}
}
pub(crate) fn echoed_nonce_with_flags(flags: u8, reply: &Segment<'_>, padding: u16) -> u32 {
match nonce_field(flags) {
NonceField::Sequence { span } => {
let acked_padding = if reply.flags() & flags::RST != 0 {
u32::from(padding)
} else {
0
};
reply
.acknowledgement()
.wrapping_sub(span)
.wrapping_sub(acked_padding)
}
NonceField::Acknowledgement => reply.sequence(),
}
}
#[non_exhaustive]
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct QuotedProbe {
pub source: u16,
pub destination: u16,
pub sequence: u32,
pub acknowledgement: Option<u32>,
}
pub fn quoted_probe(quoted: &[u8]) -> Option<QuotedProbe> {
let head: &[u8; 8] = quoted.first_chunk()?;
Some(QuotedProbe {
source: u16::from_be_bytes([head[0], head[1]]),
destination: u16::from_be_bytes([head[2], head[3]]),
sequence: u32::from_be_bytes([head[4], head[5], head[6], head[7]]),
acknowledgement: quoted
.first_chunk::<12>()
.map(|full| u32::from_be_bytes([full[8], full[9], full[10], full[11]])),
})
}
pub fn quoted_nonce(technique: TcpScanTechnique, quoted: &QuotedProbe) -> Option<u32> {
quoted_nonce_with_flags(probe_flags(technique), quoted)
}
pub(crate) fn quoted_nonce_with_flags(flags: u8, quoted: &QuotedProbe) -> Option<u32> {
match nonce_field(flags) {
NonceField::Sequence { .. } => Some(quoted.sequence),
NonceField::Acknowledgement => quoted.acknowledgement,
}
}
#[derive(Debug, Clone, Copy)]
pub struct Segment<'a> {
bytes: &'a [u8],
}
impl<'a> Segment<'a> {
pub fn source_port(&self) -> u16 {
u16::from_be_bytes([self.bytes[0], self.bytes[1]])
}
pub fn destination_port(&self) -> u16 {
u16::from_be_bytes([self.bytes[2], self.bytes[3]])
}
pub fn sequence(&self) -> u32 {
u32::from_be_bytes([self.bytes[4], self.bytes[5], self.bytes[6], self.bytes[7]])
}
pub fn acknowledgement(&self) -> u32 {
u32::from_be_bytes([self.bytes[8], self.bytes[9], self.bytes[10], self.bytes[11]])
}
pub fn flags(&self) -> u8 {
self.bytes[13]
}
pub fn window(&self) -> u16 {
u16::from_be_bytes([self.bytes[14], self.bytes[15]])
}
pub fn payload(&self) -> &'a [u8] {
let offset = usize::from(self.bytes[12] >> 4) * 4;
if offset < TCP_HDR_LEN || offset > self.bytes.len() {
return &[];
}
&self.bytes[offset..]
}
}
pub fn parse(bytes: &'_ [u8]) -> Result<Segment<'_>> {
if bytes.len() < TCP_HDR_LEN {
return Err(PacketError::truncated(
"a TCP segment",
TCP_HDR_LEN,
bytes.len(),
));
}
Ok(Segment { bytes })
}
pub fn classify_probe_response(segment: &Segment<'_>) -> Option<TcpReply> {
let flags = segment.flags();
if flags & flags::RST != 0 {
Some(TcpReply::Rst {
window: segment.window(),
})
} else if flags & flags::SYN != 0 && flags & flags::ACK != 0 {
Some(TcpReply::SynAck)
} else if flags & flags::ACK != 0 && flags & (flags::SYN | flags::FIN) == 0 {
Some(TcpReply::ChallengeAck)
} else {
None
}
}
#[cfg(test)]
mod tests {
use super::*;
use pnet_packet::Packet;
use pnet_packet::tcp::MutableTcpPacket;
use std::net::Ipv4Addr;
const SRC: IpAddr = IpAddr::V4(Ipv4Addr::new(192, 0, 2, 10));
const DST: IpAddr = IpAddr::V4(Ipv4Addr::new(192, 0, 2, 20));
const NONCE: u32 = 0xDEAD_BEEF;
fn packet_with_flags(flags: u8) -> Vec<u8> {
let mut buffer = vec![0u8; TCP_HDR_LEN];
let mut tcp = MutableTcpPacket::new(&mut buffer).unwrap();
tcp.set_data_offset((TCP_HDR_LEN / WORD_IN_BYTES) as u8);
tcp.set_flags(flags);
buffer
}
fn probe(technique: TcpScanTechnique) -> Vec<u8> {
build_probe(technique, SRC, DST, 50_000, 80, NONCE).expect("probe builds")
}
fn conformant_rst(probe: &[u8]) -> Vec<u8> {
let sent = parse(probe).expect("the probe parses");
let sent_flags = sent.flags();
let mut buffer = vec![0u8; TCP_HDR_LEN];
let mut rst = MutableTcpPacket::new(&mut buffer).unwrap();
rst.set_source(sent.destination_port());
rst.set_destination(sent.source_port());
rst.set_data_offset((TCP_HDR_LEN / WORD_IN_BYTES) as u8);
if sent_flags & flags::ACK != 0 {
rst.set_flags(flags::RST);
rst.set_sequence(sent.acknowledgement());
} else {
let control_octets = u32::from(sent_flags & flags::SYN != 0)
+ u32::from(sent_flags & flags::FIN != 0)
+ sent.payload().len() as u32;
rst.set_flags(flags::RST | flags::ACK);
rst.set_sequence(0);
rst.set_acknowledgement(sent.sequence().wrapping_add(control_octets));
}
buffer
}
#[test]
fn each_technique_carries_its_own_flags() {
use TcpScanTechnique::*;
let sent = |technique| parse(&probe(technique)).unwrap().flags();
assert_eq!(sent(Syn), flags::SYN);
assert_eq!(sent(Fin), flags::FIN);
assert_eq!(sent(Null), 0);
assert_eq!(sent(Xmas), flags::FIN | flags::PSH | flags::URG);
assert_eq!(sent(Maimon), flags::FIN | flags::ACK);
assert_eq!(sent(Ack), flags::ACK);
assert_eq!(
sent(Window),
flags::ACK,
"a window scan sends the ack probe"
);
}
#[test]
fn the_nonce_goes_in_the_field_the_reply_will_echo() {
use TcpScanTechnique::*;
for technique in [Syn, Fin, Null, Xmas] {
let bytes = probe(technique);
let sent = parse(&bytes).unwrap();
assert_eq!(sent.sequence(), NONCE, "{technique} nonce");
assert_eq!(
sent.acknowledgement(),
0,
"{technique} must not claim to acknowledge anything"
);
}
for technique in [Maimon, Ack, Window] {
let bytes = probe(technique);
let sent = parse(&bytes).unwrap();
assert_eq!(sent.acknowledgement(), NONCE, "{technique} nonce");
}
}
#[test]
fn only_a_syn_probe_carries_options() {
assert_eq!(probe(TcpScanTechnique::Syn).len(), TCP_HDR_LEN_WITH_OPTIONS);
for technique in [
TcpScanTechnique::Fin,
TcpScanTechnique::Null,
TcpScanTechnique::Xmas,
TcpScanTechnique::Maimon,
TcpScanTechnique::Ack,
TcpScanTechnique::Window,
] {
assert_eq!(probe(technique).len(), TCP_HDR_LEN, "{technique}");
}
}
#[test]
fn a_syn_offers_every_option_it_wants_answered() {
let probe = probe(TcpScanTechnique::Syn);
let options = &probe[TCP_HDR_LEN..];
assert_eq!(options[0..2], [2, 4], "maximum segment size");
assert_eq!(options[4..6], [4, 2], "SACK permitted");
assert_eq!(options[6..8], [8, 10], "timestamp");
assert_eq!(options[16], 1, "no-op, aligning what follows");
assert_eq!(options[17..20], [3, 3, 7], "window scale");
assert_eq!(options[12..16], [0, 0, 0, 0], "TSecr");
assert_eq!(
options.len() % 4,
0,
"the header is measured in four-byte words, so an option list that is \
not a multiple of four needs padding it does not have"
);
}
#[test]
fn a_probe_across_address_families_is_refused_rather_than_mis_checksummed() {
let v6: IpAddr = "2001:db8::1".parse().unwrap();
assert!(build_probe(TcpScanTechnique::Syn, SRC, v6, 50_000, 80, NONCE).is_err());
}
#[test]
fn every_technique_reads_its_nonce_back_out_of_a_conformant_reset() {
for technique in TcpScanTechnique::ALL {
let sent = probe(technique);
let rst = conformant_rst(&sent);
let reply = parse(&rst).unwrap();
assert_eq!(
echoed_nonce(technique, &reply, 0),
NONCE,
"{technique} could not recognize its own answer"
);
}
}
#[test]
fn an_arbitrary_flag_combination_is_sent_and_read_back() {
const MASK: u8 = flags::SYN | flags::FIN;
let sent = build_probe_with_flags(MASK, SRC, DST, 50_000, 80, NONCE, None, false)
.expect("probe builds");
let parsed = parse(&sent).unwrap();
assert_eq!(parsed.flags(), MASK, "the segment carries the chosen flags");
let rst = conformant_rst(&sent);
let reply = parse(&rst).unwrap();
assert_eq!(echoed_nonce_with_flags(MASK, &reply, 0), NONCE);
}
#[test]
fn a_reset_answering_a_different_probe_yields_a_different_nonce() {
let ours = probe(TcpScanTechnique::Fin);
let theirs = build_probe(TcpScanTechnique::Fin, SRC, DST, 50_000, 80, NONCE ^ 0x1234)
.expect("probe builds");
assert_ne!(ours, theirs);
let reply_bytes = conformant_rst(&theirs);
let reply = parse(&reply_bytes).unwrap();
assert_ne!(echoed_nonce(TcpScanTechnique::Fin, &reply, 0), NONCE);
}
#[test]
fn a_padded_probe_reads_its_nonce_back_from_either_answer() {
const PADDING: u16 = 24;
let padded = build_probe_shaped(
TcpScanTechnique::Syn,
SRC,
DST,
50_000,
80,
NONCE,
Some(PADDING),
false,
)
.expect("a padded probe builds");
let rst = conformant_rst(&padded);
let reply = parse(&rst).unwrap();
assert_eq!(
echoed_nonce(TcpScanTechnique::Syn, &reply, PADDING),
NONCE,
"a closed port's reset acks the padding, which has to be subtracted back"
);
let sent = parse(&padded).unwrap();
let mut buffer = vec![0u8; TCP_HDR_LEN];
let mut syn_ack = MutableTcpPacket::new(&mut buffer).unwrap();
syn_ack.set_source(sent.destination_port());
syn_ack.set_destination(sent.source_port());
syn_ack.set_data_offset((TCP_HDR_LEN / WORD_IN_BYTES) as u8);
syn_ack.set_flags(flags::SYN | flags::ACK);
syn_ack.set_sequence(0x5555_5555);
syn_ack.set_acknowledgement(sent.sequence().wrapping_add(1));
let reply = parse(syn_ack.packet()).expect("the reply parses");
assert_eq!(
echoed_nonce(TcpScanTechnique::Syn, &reply, PADDING),
NONCE,
"an open port's SYN+ACK acks only the SYN, so padding must be left in place"
);
}
#[test]
fn an_unshaped_probe_is_the_ordinary_probe() {
for technique in [
TcpScanTechnique::Fin,
TcpScanTechnique::Null,
TcpScanTechnique::Xmas,
] {
let plain = build_probe(technique, SRC, DST, 50_000, 80, NONCE).unwrap();
let shaped =
build_probe_shaped(technique, SRC, DST, 50_000, 80, NONCE, None, false).unwrap();
assert_eq!(
plain, shaped,
"{technique} shaped with nothing must not differ"
);
}
}
#[test]
fn padding_lengthens_the_probe_and_the_checksum_covers_it() {
const LEN: u16 = 20;
let bare = build_probe(TcpScanTechnique::Fin, SRC, DST, 50_000, 80, NONCE).unwrap();
let padded = build_probe_shaped(
TcpScanTechnique::Fin,
SRC,
DST,
50_000,
80,
NONCE,
Some(LEN),
false,
)
.unwrap();
assert_eq!(padded.len(), bare.len() + usize::from(LEN));
assert_eq!(parse(&padded).unwrap().payload().len(), usize::from(LEN));
let (IpAddr::V4(src), IpAddr::V4(dst)) = (SRC, DST) else {
unreachable!("the fixtures are IPv4")
};
let segment = pnet_packet::tcp::TcpPacket::new(&padded).expect("the probe parses");
assert_eq!(
pnet_packet::tcp::ipv4_checksum(&segment, &src, &dst),
segment.get_checksum(),
"a well-formed padded probe carries a checksum that covers its padding"
);
}
#[test]
fn a_bad_checksum_probe_carries_a_checksum_the_host_rejects() {
let bad = build_probe_shaped(
TcpScanTechnique::Syn,
SRC,
DST,
50_000,
80,
NONCE,
None,
true,
)
.unwrap();
let (IpAddr::V4(src), IpAddr::V4(dst)) = (SRC, DST) else {
unreachable!("the fixtures are IPv4")
};
let segment = pnet_packet::tcp::TcpPacket::new(&bad).expect("the probe parses");
let correct = pnet_packet::tcp::ipv4_checksum(&segment, &src, &dst);
assert_ne!(
segment.get_checksum(),
correct,
"the checksum must be wrong"
);
assert_ne!(
segment.get_checksum(),
0,
"zero is a checksum a host accepts"
);
}
#[test]
fn a_null_probe_and_a_fin_probe_are_acknowledged_one_apart() {
let null = conformant_rst(&probe(TcpScanTechnique::Null));
let fin = conformant_rst(&probe(TcpScanTechnique::Fin));
let null_ack = parse(&null).unwrap().acknowledgement();
let fin_ack = parse(&fin).unwrap().acknowledgement();
assert_eq!(null_ack, NONCE);
assert_eq!(fin_ack, NONCE.wrapping_add(1));
}
#[test]
fn eight_quoted_bytes_name_the_probe_and_a_sequence_nonce() {
let sent = probe(TcpScanTechnique::Fin);
let quoted = quoted_probe(&sent[..8]).expect("eight bytes are enough");
assert_eq!(quoted.source, 50_000);
assert_eq!(quoted.destination, 80);
assert_eq!(quoted.acknowledgement, None);
assert_eq!(quoted_nonce(TcpScanTechnique::Fin, "ed), Some(NONCE));
}
#[test]
fn an_ack_carrying_probe_needs_a_generous_quotation_to_name_its_attempt() {
let sent = probe(TcpScanTechnique::Ack);
let short = quoted_probe(&sent[..8]).expect("eight bytes are enough");
assert_eq!(short.destination, 80, "the probe is still identified");
assert_eq!(quoted_nonce(TcpScanTechnique::Ack, &short), None);
let full = quoted_probe(&sent).expect("a full header parses");
assert_eq!(quoted_nonce(TcpScanTechnique::Ack, &full), Some(NONCE));
}
#[test]
fn a_quotation_too_short_to_name_a_probe_is_rejected() {
assert_eq!(quoted_probe(&probe(TcpScanTechnique::Syn)[..7]), None);
}
#[test]
fn classifies_syn_ack_and_rst() {
let syn_ack = packet_with_flags(flags::SYN | flags::ACK);
let rst = packet_with_flags(flags::RST);
assert_eq!(
classify_probe_response(&parse(&syn_ack).unwrap()),
Some(TcpReply::SynAck)
);
assert_eq!(
classify_probe_response(&parse(&rst).unwrap()),
Some(TcpReply::Rst { window: 0 })
);
}
#[test]
fn classifies_rst_ack_as_a_reset() {
let bytes = packet_with_flags(flags::RST | flags::ACK);
assert_eq!(
classify_probe_response(&parse(&bytes).unwrap()),
Some(TcpReply::Rst { window: 0 })
);
}
#[test]
fn a_reset_carries_the_window_it_announced() {
let mut buffer = vec![0u8; TCP_HDR_LEN];
let mut tcp = MutableTcpPacket::new(&mut buffer).unwrap();
tcp.set_data_offset((TCP_HDR_LEN / WORD_IN_BYTES) as u8);
tcp.set_flags(flags::RST | flags::ACK);
tcp.set_window(4096);
assert_eq!(
classify_probe_response(&parse(&buffer).unwrap()),
Some(TcpReply::Rst { window: 4096 })
);
}
#[test]
fn classifies_a_bare_ack_as_a_challenge() {
let bytes = packet_with_flags(flags::ACK);
assert_eq!(
classify_probe_response(&parse(&bytes).unwrap()),
Some(TcpReply::ChallengeAck)
);
}
#[test]
fn ignores_unrelated_flag_combinations() {
for flags in [
flags::ACK | flags::FIN,
flags::SYN,
flags::PSH,
flags::URG,
0,
] {
let bytes = packet_with_flags(flags);
assert_eq!(
classify_probe_response(&parse(&bytes).unwrap()),
None,
"flags {flags:#04b} answer no probe"
);
}
}
}