Skip to content

A WiFi security auditing software

20.6 KB
Raw Blame
//! Native WPA crackable-material detection (4-way handshake and PMKID).
//!
//! Reads capture file(s) and reports which access points have crackable WPA
//! material — a captured 4-way handshake and/or a PMKID. Shared because both sides
//! need it against different files: the agent scans the root-owned live/old captures
//! to flag APs while scanning, and the GUI inspects a user-selected capture before
//! offering it for decryption. Reading a capture and parsing it needs no
//! privilege, so the logic is identical on both sides.
//!
//! Only the classic libpcap format is read, with link type
//! `LINKTYPE_IEEE802_11_RADIOTAP` (127, what airgorah itself writes) or plain
//! `LINKTYPE_IEEE802_11` (105). Frames are decoded with `radiotap` + `libwifi`;
//! a data frame carrying an EAPOL key is classified into one of the four handshake
//! messages, and an AP is reported once a crackable combination has been seen. The
//! same message 1 also carries the AP's PMKID (in the RSN PMKID KDE of the key
//! data) when the AP volunteers it — a clientless capture that is crackable on its
//! own, so it is flagged independently of the 4-way handshake.

use std::collections::{HashMap, HashSet};
use std::path::Path;

use libwifi::Addresses;
use libwifi::Frame;
use libwifi::frame::EapolKey;
use libwifi::frame::components::{DataHeader, ManagementHeader, StationInfo};

const LINKTYPE_IEEE802_11: u32 = 105;
const LINKTYPE_IEEE802_11_RADIOTAP: u32 = 127;

/// Crackable WPA material found for one access point in a capture.
///
/// `handshake` and `pmkid` are independent: either alone makes the AP crackable,
/// and both can be present in the same capture.
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct Crackable {
    pub bssid: String,
    pub essid: String,
    pub handshake: bool,
    pub pmkid: bool,
}

/// Return a [`Crackable`] for every AP that yielded a WPA 4-way handshake and/or a
/// PMKID in the given capture file(s). Unreadable or unparsable files are skipped.
pub fn get_crackables<I, S>(paths: I) -> std::io::Result<Vec<Crackable>>
where
    I: IntoIterator<Item = S>,
    S: AsRef<Path>,
{
    let mut essids: HashMap<String, String> = HashMap::new();
    // Per (bssid, station): a bitmask of which handshake messages M1..M4 were seen.
    let mut messages: HashMap<(String, String), u8> = HashMap::new();
    // BSSIDs whose message 1 carried a valid PMKID.
    let mut pmkids: HashSet<String> = HashSet::new();

    for path in paths {
        if let Ok(data) = std::fs::read(path.as_ref()) {
            scan_capture(&data, &mut essids, &mut messages, &mut pmkids);
        }
    }

    // A crackable 4-way handshake needs M2 — the only carrier of the SNonce, plus a
    // MIC — together with an ANonce source (M1 or M3).
    let mut handshakes: HashSet<String> = HashSet::new();
    for ((bssid, _station), seen) in &messages {
        let m1 = seen & 0b0001 != 0;
        let m2 = seen & 0b0010 != 0;
        let m3 = seen & 0b0100 != 0;
        if m2 && (m1 || m3) {
            handshakes.insert(bssid.clone());
        }
    }

    // Report every AP that produced either kind of material.
    let mut bssids: HashSet<String> = HashSet::new();
    bssids.extend(handshakes.iter().cloned());
    bssids.extend(pmkids.iter().cloned());

    Ok(bssids
        .into_iter()
        .map(|bssid| {
            let essid = essids
                .get(&bssid)
                .cloned()
                .unwrap_or_else(|| "hidden".to_string());
            let handshake = handshakes.contains(&bssid);
            let pmkid = pmkids.contains(&bssid);
            Crackable {
                bssid,
                essid,
                handshake,
                pmkid,
            }
        })
        .collect())
}

/// Return `(bssid, essid)` for every AP that has a captured WPA 4-way handshake in
/// the given capture file(s), ignoring PMKID-only APs. A thin view over
/// [`get_crackables`] for callers that only care about full handshakes.
pub fn get_handshakes<I, S>(paths: I) -> std::io::Result<Vec<(String, String)>>
where
    I: IntoIterator<Item = S>,
    S: AsRef<Path>,
{
    Ok(get_crackables(paths)?
        .into_iter()
        .filter(|crackable| crackable.handshake)
        .map(|crackable| (crackable.bssid, crackable.essid))
        .collect())
}

/// Walk a single capture's frames, accumulating ESSIDs, handshake messages, and
/// the BSSIDs that leaked a PMKID.
fn scan_capture(
    data: &[u8],
    essids: &mut HashMap<String, String>,
    messages: &mut HashMap<(String, String), u8>,
    pmkids: &mut HashSet<String>,
) {
    let Some(mut reader) = PcapReader::new(data) else {
        return;
    };
    let link_type = reader.link_type;
    if link_type != LINKTYPE_IEEE802_11 && link_type != LINKTYPE_IEEE802_11_RADIOTAP {
        return;
    }

    while let Some(record) = reader.next_frame() {
        let (body, fcs) = if link_type == LINKTYPE_IEEE802_11_RADIOTAP {
            let Ok((radiotap, rest)) = radiotap::Radiotap::parse(record) else {
                continue;
            };
            if radiotap.flags.as_ref().is_some_and(|f| f.bad_fcs) {
                continue;
            }
            (rest, radiotap.flags.as_ref().is_some_and(|f| f.fcs))
        } else {
            (record, false)
        };

        // The FCS flag is best-effort; fall back to parsing without it so a
        // mislabelled trailer never hides a handshake.
        let frame = match libwifi::parse_frame(body, fcs) {
            Ok(frame) => frame,
            Err(_) if fcs => match libwifi::parse_frame(body, false) {
                Ok(frame) => frame,
                Err(_) => continue,
            },
            Err(_) => continue,
        };

        match frame {
            Frame::Beacon(beacon) => record_essid(&beacon.header, &beacon.station_info, essids),
            Frame::ProbeResponse(resp) => record_essid(&resp.header, &resp.station_info, essids),
            Frame::Data(data) => record_eapol(&data.header, &data.eapol_key, messages, pmkids),
            Frame::QosData(data) => record_eapol(&data.header, &data.eapol_key, messages, pmkids),
            _ => {}
        }
    }
}

/// Remember an AP's ESSID from a beacon / probe response (ignoring hidden ones).
fn record_essid(
    header: &ManagementHeader,
    info: &StationInfo,
    essids: &mut HashMap<String, String>,
) {
    let Some(bssid) = header.bssid() else {
        return;
    };
    if let Some(essid) = info.essid()
        && !essid.is_empty()
        && !essid.starts_with("<hidden")
    {
        essids.entry(bssid.to_long_string()).or_insert(essid);
    }
}

/// Whether an EAPOL key frame carries a PMKID that a passphrase dictionary can
/// actually recover.
pub fn has_crackable_pmkid(key: &EapolKey) -> bool {
    let descriptor_version = key.key_information & 0x0007;
    matches!(descriptor_version, 1..=3) && key.pmkid().is_some()
}

/// Classify an EAPOL data frame, record which handshake message it is, and note
/// the AP's PMKID when message 1 carries one.
fn record_eapol(
    header: &DataHeader,
    eapol: &Option<EapolKey>,
    messages: &mut HashMap<(String, String), u8>,
    pmkids: &mut HashSet<String>,
) {
    let Some(key) = eapol else {
        return;
    };
    let Some(message) = classify_message(key.key_information) else {
        return;
    };

    // M1/M3 flow AP->station (from_ds); M2/M4 flow station->AP (to_ds).
    let fc = &header.frame_control;
    let (bssid, station) = if fc.to_ds() && !fc.from_ds() {
        (header.ra(), header.ta())
    } else if fc.from_ds() && !fc.to_ds() {
        (header.ta(), header.ra())
    } else {
        return;
    };

    let bssid = bssid.to_long_string();

    // A message 1 may advertise the AP's PMKID, flagging the AP as crackable with
    // no client and no full handshake — but only when that PMKID is actually
    // recoverable by a passphrase attack.
    if has_crackable_pmkid(key) {
        pmkids.insert(bssid.clone());
    }

    let pair = (bssid, station.to_long_string());
    *messages.entry(pair).or_insert(0) |= 1 << (message - 1);
}

/// Which 4-way handshake message (1..4) an EAPOL key frame is, from its Key
/// Information field, or `None` if it is not a pairwise handshake message.
fn classify_message(key_information: u16) -> Option<u8> {
    // Key Type bit (0x0008) distinguishes the pairwise 4-way from group rekeying.
    if key_information & 0x0008 == 0 {
        return None;
    }
    let ack = key_information & 0x0080 != 0;
    let mic = key_information & 0x0100 != 0;
    let secure = key_information & 0x0200 != 0;

    match (ack, mic, secure) {
        (true, false, _) => Some(1),     // ANonce, no MIC
        (false, true, false) => Some(2), // SNonce + MIC
        (true, true, _) => Some(3),      // ANonce + MIC, install/secure
        (false, true, true) => Some(4),  // MIC, secure
        _ => None,
    }
}

/// A minimal reader over the records of a classic libpcap file.
struct PcapReader<'a> {
    data: &'a [u8],
    offset: usize,
    big_endian: bool,
    link_type: u32,
}

impl<'a> PcapReader<'a> {
    /// Parse the 24-byte global header, detecting endianness from the magic.
    /// Returns `None` if the header is missing or not a libpcap magic.
    fn new(data: &'a [u8]) -> Option<Self> {
        if data.len() < 24 {
            return None;
        }
        let magic = u32::from_le_bytes(data[0..4].try_into().ok()?);
        let big_endian = match magic {
            // microsecond / nanosecond magics, same-endian as this reader
            0xa1b2_c3d4 | 0xa1b2_3c4d => false,
            // byte-swapped
            0xd4c3_b2a1 | 0x4d3c_b2a1 => true,
            _ => return None,
        };
        let link_type = read_u32(&data[20..24], big_endian);
        Some(Self {
            data,
            offset: 24,
            big_endian,
            link_type,
        })
    }

    /// Yield the next record's captured bytes, or `None` at the end (or on a
    /// truncated trailing record, which a live capture being read mid-write can
    /// present).
    fn next_frame(&mut self) -> Option<&'a [u8]> {
        if self.offset + 16 > self.data.len() {
            return None;
        }
        let incl_len = read_u32(
            &self.data[self.offset + 8..self.offset + 12],
            self.big_endian,
        ) as usize;
        let start = self.offset + 16;
        let end = start.checked_add(incl_len)?;
        if end > self.data.len() {
            return None;
        }
        self.offset = end;
        Some(&self.data[start..end])
    }
}

fn read_u32(bytes: &[u8], big_endian: bool) -> u32 {
    let arr = [bytes[0], bytes[1], bytes[2], bytes[3]];
    if big_endian {
        u32::from_be_bytes(arr)
    } else {
        u32::from_le_bytes(arr)
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn classifies_the_four_handshake_messages() {
        // Canonical Key Information values for a WPA2 4-way handshake.
        assert_eq!(classify_message(0x008a), Some(1)); // pairwise + ACK
        assert_eq!(classify_message(0x010a), Some(2)); // pairwise + MIC
        assert_eq!(classify_message(0x13ca), Some(3)); // pairwise + ACK + MIC + install/secure
        assert_eq!(classify_message(0x030a), Some(4)); // pairwise + MIC + secure
        // Group rekey (Key Type bit clear) and empty are not handshake messages.
        assert_eq!(classify_message(0x0382), None);
        assert_eq!(classify_message(0x0000), None);
    }

    /// The rule get_handshakes applies: M2 (SNonce+MIC) plus an ANonce source.
    fn is_complete(bits: u8) -> bool {
        let m1 = bits & 0b0001 != 0;
        let m2 = bits & 0b0010 != 0;
        let m3 = bits & 0b0100 != 0;
        m2 && (m1 || m3)
    }

    #[test]
    fn a_crackable_handshake_needs_m2_plus_anonce() {
        assert!(is_complete(0b0011)); // M1 + M2
        assert!(is_complete(0b0110)); // M2 + M3
        assert!(!is_complete(0b0010)); // M2 alone (no ANonce)
        assert!(!is_complete(0b0101)); // M1 + M3 (no SNonce)
        assert!(!is_complete(0b1000)); // M4 alone
    }

    fn push_record(data: &mut Vec<u8>, payload: &[u8]) {
        data.extend_from_slice(&0u32.to_le_bytes()); // ts_sec
        data.extend_from_slice(&0u32.to_le_bytes()); // ts_usec
        data.extend_from_slice(&(payload.len() as u32).to_le_bytes()); // incl_len
        data.extend_from_slice(&(payload.len() as u32).to_le_bytes()); // orig_len
        data.extend_from_slice(payload);
    }

    /// Build an 802.11 Data frame (from-DS) carrying an EAPOL-Key message 1, with
    /// an optional RSN PMKID KDE in its key data. `bssid`/`station` are the AP and
    /// client MACs; the AP is the transmitter (address 2) on this downlink frame.
    fn eapol_m1_frame(bssid: [u8; 6], station: [u8; 6], pmkid: Option<[u8; 16]>) -> Vec<u8> {
        // Default to key descriptor version 2 (WPA2-PSK): a crackable PMKID.
        eapol_m1_frame_ki(bssid, station, pmkid, 0x008a)
    }

    /// As [`eapol_m1_frame`], with an explicit EAPOL Key Information field so a test
    /// can select the key descriptor version (bits 0-2).
    fn eapol_m1_frame_ki(
        bssid: [u8; 6],
        station: [u8; 6],
        pmkid: Option<[u8; 16]>,
        key_information: u16,
    ) -> Vec<u8> {
        let mut frame = Vec::new();

        // 802.11 MAC header (24 bytes): a from-DS data frame, so address 1 is the
        // destination station and address 2 is the transmitting AP (the BSSID).
        frame.extend_from_slice(&[0x08, 0x02]); // frame control: Data, subtype 0, from_ds
        frame.extend_from_slice(&[0x00, 0x00]); // duration
        frame.extend_from_slice(&station); // address 1 (RA): destination station
        frame.extend_from_slice(&bssid); // address 2 (TA): transmitting AP
        frame.extend_from_slice(&bssid); // address 3: BSSID
        frame.extend_from_slice(&[0x00, 0x00]); // sequence control

        // LLC/SNAP header announcing EAPOL (ethertype 0x888e).
        frame.extend_from_slice(&[0xaa, 0xaa, 0x03, 0x00, 0x00, 0x00, 0x88, 0x8e]);

        // Key data: an RSN PMKID KDE when a PMKID is provided, otherwise empty.
        let key_data = match pmkid {
            Some(pmkid) => {
                let mut kde = vec![0xdd, 0x14, 0x00, 0x0f, 0xac, 0x04]; // id, len, OUI, type 4
                kde.extend_from_slice(&pmkid);
                kde
            }
            None => Vec::new(),
        };

        // EAPOL-Key body (message 1: pairwise Key Type + Key ACK, no MIC).
        let mut eapol = Vec::new();
        eapol.push(0x02); // protocol version
        eapol.push(0x03); // packet type: EAPOL-Key
        eapol.extend_from_slice(&(95 + key_data.len() as u16).to_be_bytes()); // packet length
        eapol.push(0x02); // descriptor type: RSN
        eapol.extend_from_slice(&key_information.to_be_bytes()); // key information: message 1
        eapol.extend_from_slice(&0x0010u16.to_be_bytes()); // key length
        eapol.extend_from_slice(&1u64.to_be_bytes()); // replay counter
        eapol.extend_from_slice(&[0x11; 32]); // key nonce (ANonce)
        eapol.extend_from_slice(&[0x00; 16]); // key iv
        eapol.extend_from_slice(&0u64.to_be_bytes()); // key rsc
        eapol.extend_from_slice(&0u64.to_be_bytes()); // key id
        eapol.extend_from_slice(&[0x00; 16]); // key mic (absent in message 1)
        eapol.extend_from_slice(&(key_data.len() as u16).to_be_bytes()); // key data length
        eapol.extend_from_slice(&key_data);

        frame.extend_from_slice(&eapol);
        frame
    }

    #[test]
    fn detects_pmkid_in_message_one() {
        let bssid = [0x18, 0x86, 0x37, 0x1f, 0x30, 0x40];
        let station = [0xaa, 0xbb, 0xcc, 0xdd, 0xee, 0xff];

        let mut essids = HashMap::new();
        let mut messages = HashMap::new();
        let mut pmkids = HashSet::new();

        let frame = eapol_m1_frame(bssid, station, Some([0x42; 16]));
        let mut data = global_header(LINKTYPE_IEEE802_11);
        push_record(&mut data, &frame);

        scan_capture(&data, &mut essids, &mut messages, &mut pmkids);

        // The AP's PMKID is recorded, and no full handshake is claimed from M1 alone.
        assert_eq!(pmkids.len(), 1);
        assert_eq!(messages.values().copied().collect::<Vec<_>>(), vec![0b0001]);
    }

    #[test]
    fn ignores_a_wpa3_sae_pmkid() {
        // A well-formed, non-zero PMKID KDE, but the message 1 uses key descriptor
        // version 0 (WPA3-SAE): its PMK is not PBKDF2(passphrase), so the PMKID is
        // not crackable and must not be flagged, even though libwifi returns it.
        let bssid = [0x6a, 0xeb, 0xef, 0x11, 0x3b, 0x92];
        let station = [0x7a, 0x98, 0xc7, 0x54, 0x93, 0xee];

        let mut essids = HashMap::new();
        let mut messages = HashMap::new();
        let mut pmkids = HashSet::new();

        // 0x0088: pairwise + ACK (message 1) with key descriptor version 0.
        let frame = eapol_m1_frame_ki(bssid, station, Some([0x42; 16]), 0x0088);
        let mut data = global_header(LINKTYPE_IEEE802_11);
        push_record(&mut data, &frame);

        scan_capture(&data, &mut essids, &mut messages, &mut pmkids);

        assert!(pmkids.is_empty());
    }

    #[test]
    fn message_one_without_pmkid_is_not_flagged() {
        let bssid = [0x18, 0x86, 0x37, 0x1f, 0x30, 0x40];
        let station = [0xaa, 0xbb, 0xcc, 0xdd, 0xee, 0xff];

        let mut essids = HashMap::new();
        let mut messages = HashMap::new();
        let mut pmkids = HashSet::new();

        // A message 1 whose key data has no PMKID KDE (empty key data).
        let frame = eapol_m1_frame(bssid, station, None);
        let mut data = global_header(LINKTYPE_IEEE802_11);
        push_record(&mut data, &frame);

        scan_capture(&data, &mut essids, &mut messages, &mut pmkids);

        assert!(pmkids.is_empty());
    }

    #[test]
    fn get_crackables_reports_a_pmkid_only_ap() {
        let bssid = [0x18, 0x86, 0x37, 0x1f, 0x30, 0x40];
        let station = [0xaa, 0xbb, 0xcc, 0xdd, 0xee, 0xff];

        let mut data = global_header(LINKTYPE_IEEE802_11);
        push_record(&mut data, &eapol_m1_frame(bssid, station, Some([0x42; 16])));

        let mut path = std::env::temp_dir();
        path.push(format!("airgorah-pmkid-test-{}.cap", std::process::id()));
        std::fs::write(&path, &data).unwrap();

        let crackables = get_crackables([&path]).unwrap();
        std::fs::remove_file(&path).ok();

        // A lone PMKID makes the AP crackable even though there is no 4-way handshake.
        assert_eq!(crackables.len(), 1);
        assert!(crackables[0].pmkid);
        assert!(!crackables[0].handshake);
        // get_handshakes, which reports only 4-way handshakes, ignores it.
        let handshakes = get_handshakes([&path]).unwrap_or_default();
        assert!(handshakes.is_empty());
    }

    fn global_header(link_type: u32) -> Vec<u8> {
        let mut header = Vec::new();
        header.extend_from_slice(&0xa1b2_c3d4u32.to_le_bytes()); // magic (little-endian)
        header.extend_from_slice(&2u16.to_le_bytes()); // version major
        header.extend_from_slice(&4u16.to_le_bytes()); // version minor
        header.extend_from_slice(&0i32.to_le_bytes()); // thiszone
        header.extend_from_slice(&0u32.to_le_bytes()); // sigfigs
        header.extend_from_slice(&65535u32.to_le_bytes()); // snaplen
        header.extend_from_slice(&link_type.to_le_bytes()); // network
        header
    }

    #[test]
    fn pcap_reader_reads_records() {
        let mut data = global_header(LINKTYPE_IEEE802_11);
        push_record(&mut data, &[1, 2, 3]);
        push_record(&mut data, &[4, 5]);

        let mut reader = PcapReader::new(&data).expect("valid header");
        assert_eq!(reader.link_type, LINKTYPE_IEEE802_11);
        assert_eq!(reader.next_frame(), Some(&[1u8, 2, 3][..]));
        assert_eq!(reader.next_frame(), Some(&[4u8, 5][..]));
        assert_eq!(reader.next_frame(), None);
    }

    #[test]
    fn pcap_reader_drops_a_truncated_trailing_record() {
        // A live capture read mid-write can end with a partially-written record.
        let mut data = global_header(LINKTYPE_IEEE802_11_RADIOTAP);
        push_record(&mut data, &[1, 2, 3]);
        data.extend_from_slice(&0u32.to_le_bytes()); // ts_sec
        data.extend_from_slice(&0u32.to_le_bytes()); // ts_usec
        data.extend_from_slice(&10u32.to_le_bytes()); // incl_len claims 10 bytes
        data.extend_from_slice(&10u32.to_le_bytes());
        data.extend_from_slice(&[9, 9]); // ...but only 2 are present

        let mut reader = PcapReader::new(&data).expect("valid header");
        assert_eq!(reader.next_frame(), Some(&[1u8, 2, 3][..]));
        assert_eq!(reader.next_frame(), None); // truncated record ignored, no panic
    }

    #[test]
    fn rejects_non_pcap_data() {
        assert!(PcapReader::new(&[0u8; 4]).is_none()); // too short
        assert!(PcapReader::new(&[0u8; 24]).is_none()); // right size, bad magic
    }
}