Capturing Wi-Fi packets lets you see details and interactions that are otherwise masked before they reach software running on a device, making these captures an important tool for some types of bugs. The main steps involved are: 1. Find the right channel to sniff on. 2. Capture the traffic. 3. Share the capture and a hash of your WLAN password. ## 1. Determine the right channel and width WLAN networks operate on: - a channel, typically referred to with a number. 1-13 is for [2.4GHz channels](https://en.wikipedia.org/wiki/List_of_WLAN_channels#2.4_GHz_(802.11b/g/n/ax)), 36-200 for [5GHz channels](https://en.wikipedia.org/wiki/List_of_WLAN_channels#5_GHz_(802.11a/h/j/n/ac/ax)) - with a specific width (either 20Mhz, 40Mhz, 80Mhz, 160MHz) Each access point (for example router, mesh node) in your network typically has a unique 2.4GHz channel and a 5GHz channel and you need to find which one the device is connected to. There are several options: ### Use your router's control panel If you use Nest WiFi, skip this option -- the info isn't exposed. Most routers have a list of connected devices and which channel and width they are using. 1. Find your router's IP address using this [guide](https://router-network.com/help/find-router-ip-address). 2. Go to your router's address in your web browser, for example . 3. Sign in. Don't know your password? Look for a tag on your router, or use [Router Passwords](https://www.routerpasswords.com/). 4. Look for a page named something like "clients" or "attached devices". For example a Netgear router page might look like the following, or for [Eero devices](https://support.eero.com/hc/en-us/articles/207895143-Where-do-I-view-the-devices-on-my-network-). ![Netgear Client view](https://developers.home.google.com/static/matter/build/images/netgear-clients.png) 5. You may have to look elsewhere in the settings to map the info from step 4 to a particular channel and bandwidth. For example, a Netgear router: ![Netgear Channels view](https://developers.home.google.com/static/matter/build/images/netgear-channels.png) ### Use your Mac, if it is already connected to the same channel > [!NOTE] > **Note:** A lot of modern Wi-Fi networks have multiple bands and multiple Wi-Fi access points (AP) so the band and AP your laptop is connected to might actually be different, making this option unreliable. Hold **Option** on your keyboard then click the WLAN icon at the top right corner in your Mac's status bar. You should see the regular WLAN menu with a few more options and information. Take a look at the unavailable menu items and look for the one that mentions Channel: `Channel 60 (DFS, 5GHz, 40MHz)` ![Mac WLAN](https://developers.home.google.com/static/matter/build/images/mac-wlan.png) ### Can't find channel and width If the other methods don't work, you can try: 1. List all the channels your APs are using (typically 2 for each AP or mesh point). a. **Recommended** With an Android phone, you can use an app like [Wifiman](https://play.google.com/store/apps/details?id=com.ubnt.usurvey&gl=US) or [Aruba Utilities](https://play.google.com/store/apps/details?id=com.arubanetworks.arubautilities&gl=US). a. On a Mac, you can use `/System/Library/PrivateFrameworks/Apple80211.framework/Resources/airport-s` to list options. 2. Perform a short (even 15 seconds is enough) capture on each of those channels, using the instructions below 3. Install Wireshark (for assistance, see [Install Wireshark](https://developers.home.google.com/matter/wifi-capture.md.txt#install_wireshark)). 4. Open each of the captures using Wireshark, apply a display filter of `wlan.addr == YOUR_DEVICE'S_MAC`, and see if any packets show up. ## 2. Start the capture **Important: Capturing the 4-way handshake** If security is turned on for Wi-Fi, you need to know the encryption keys to decrypt the captured packets. Encryption keys are derived from a 4-way handshake that occurs when the device connects to the network, and are unique to each connection between a device and the AP. Because of this, you **MUST** capture the 4-way handshake to decrypt Wi-Fi payloads. If the device is already connected to the network when you start the capture, **disconnect and reconnect the device (or reboot it) once the sniffing starts.** ### Capture on Mac While holding the Option key on your keyboard, click the WLAN icon then select "Open Wireless Diagnostics...": ![Mac WLAN Capture](https://developers.home.google.com/static/matter/build/images/mac-wlan-capture.png) From the Wireless Diagnostics menu bar, select **Window \> Sniffer**: ![Mac WLAN Sniffer](https://developers.home.google.com/static/matter/build/images/mac-wlan-sniffer.png) Set the channel and width to the values you retrieved earlier (Screenshot example is for Channel 60 and Width 40 MHz): ![Mac WLAN Channel and Width](https://developers.home.google.com/static/matter/build/images/mac-wlan-channel-width.png) Press `Start` and enter your password. Now, try to reproduce the problem. **Ensure you capture the 4-way handshake from a connection as noted in [Capturing the 4-way handshake](https://developers.home.google.com/matter/wifi-capture.md.txt#2_start_the_capture).** Once done, press `Stop`. A new `*.pcap` file can be found in `/var/tmp` which contains all the traffic. An example filename is: `(null)_ch100_2018-11-06_10.52.01.pcap`. > [!NOTE] > **Note:** Wireless Diagnostics can refuse to sniff. As of yet, it's not clear why this occurs, but if you click the **Start** button in the sniffer dialog for Wireless Diagnostics and it doesn't do anything, it may be due to this issue. In this case you might have to repeat these steps and record traffic multiple times. ### Capture on Linux 1. Turn off Wi-Fi. This can either be done by: - Using the GUI (recommended) - Using Network Manager CLI to tell it to stop managing the WLAN interface: `sudo nmcli dev set managed on` - If using an alternate network manager, adjust accordingly. 2. Save this script. Replace `` with the name of your Wi-Fi interface. This doc assumes the script name to be `setup-wifi-capture`. ```bash #!/usr/bin/env bash sudo ifconfig down sudo rfkill unblock wifi sudo iwconfig mode monitor sudo ifconfig up sudo iw dev set channel $@ ``` 3. Execute the preceding script and pass in the channel and highest bandwidth to sniff, for example channel 153 with 80MHz bandwidth: ```bash ./setup-wifi-capture chan 153 80 MHz ``` 4. Open Wireshark, and you should now be able to capture packets on the wlan interface. ## 3. Share the capture 1. Use [WPA PSK (Raw Key) Generator](https://www.wireshark.org/tools/wpa-psk.html) to generate a hash of your password. This lets you decrypt the capture without knowing your plain-text password. 2. You need to share the generated PSK as well so others can decrypt the capture. ## Appendix ### Install Wireshark You can install Wireshark using apt install wireshark on Linux or download it online from the [Wireshark website](https://www.wireshark.org/#download). ### Set up Wireshark to decrypt traffic This isn't necessary for sharing your capture files, only do this if you want to examine decrypted traffic yourself in Wireshark. With WPA2 security on Wi-Fi, the WPA2-PSK isn't used directly for encryption and decryption of traffic. It's used in a [4-way handshake](https://en.wikipedia.org/wiki/IEEE_802.11i-2004#Four-way_handshake), which you need to capture to decrypt packets. However, if all you're trying to capture are issues with connecting to Wi-Fi or drops in connectivity, which can be gleaned from Wi-Fi management frames, you don't need to capture the 4-way handshake. In either case, it doesn't hurt to capture it anyway. Open Wireshark and open the Preferences page (**Wireshark menu \> Preferences** or \*\*Cmd + , \*\*). 1. Find "IEEE 802.11" section in "Protocols" category and ensure "Enable decryption" is checked: ![Mac Wireshark Prefs](https://developers.home.google.com/static/matter/build/images/mac-wireshark-prefs.png) 2. Click the **Edit** button next to the **Decryption Keys** label. 3. Click the '+' button in the bottom-left corner and select the "wpa-pwd" option. ![Mac Wireshark WPA and Password](https://developers.home.google.com/static/matter/build/images/mac-wireshark-wpa-pwd.png) 4. Click the key column of newly created row (right next to the wpa-pwd string), type in your WPA2 PSK and SSID in the format of `:`. For example, if your network name was `MyHomeNetwork` and your WPA2 PSK was `myp4ssword`, type in `myp4ssword:MyHomeNetwork`. ![Mac Wireshark SSID](https://developers.home.google.com/static/matter/build/images/mac-wireshark-ssid.png) 5. Click OK to confirm For further information, see Wireshark's official guide (with screenshots) at [How to Decrypt 802.11](https://wiki.wireshark.org/HowToDecrypt802.11). If using `tshark`, pass the following arguments: tshark -o wlan.enable_decryption:TRUE -o 'uat:80211_keys:"wpa-pwd",":"' ### Colorize Wireshark 802.11 Data There is a handy 802.11 color profile located on metageek.com: [Wireshark Configuration Profile](https://support.metageek.com/hc/en-us/articles/115013527388-Wireshark-Configuration-Profile).