# Codelab: Using wifi Autotests to learn 802.11 basics The Autotest infrastructure provides packet capture functionality which we can use to intercept and view WiFi packets that are sent between the Device-Under-Test (DUT) and router during a test. In this codelab we will analyze the packet sequence during the connection process to learn the basics of 802.11 connection protocols. ## Setup ### Prerequisites * Access to a wifi test setup (local or in test lab). Read the [wificell documentation] for some background. * Understanding of Autotest and the [test_that] command. ### Configuration Considerations This codelab can be completed from either a personal testing setup or a dedicated setup in our testing lab, but there are a few special considerations in each case. For instance, some of the commands in this lab will use the variable `${DUT_HOSTNAME}`, and the value of this variable is dependent on the testing setup that you use. Further considerations are included below in the instructions for each option. #### Using the wifi testing labs Our testing lab setups are operated through the skylab infrastructure. If you don't have the skylab tool installed on your machine, follow the instructions in the [skylab tools guide]. Once you have the skylab tool, you'll need to run the login command and follow its instructions to get started. ```bash skylab login ``` For this codelab, you will need to use a `wificell` test setup. Available DUTs can be found on the [skylab portal]. To find a wificell test setup, visit the portal and filter for *label-wificell = true* (the filter should already be set when you click the link). You'll need to find a setup who's current task is *idle* with dut_state *ready*, and then lock it while in use. To lock a DUT in the skylab use this command to lease it for the specified number of minutes (60 minutes should suffice for this codelab, but if your lease expires you can simply lease your DUT again): ```bash skylab lease-dut -minutes ${NUM_MINUTES} ${DUT_NAME} ``` *** note **Note:** There are several similar fields on the bot page that can potentially be confused. Bots are listed by their *id* field in the skylab search portal, which usually takes a form similar to `crossk-chromeos15-row2-rack4-host6`. *dut_name* is referred to in this document by the variable `${DUT_NAME}`, and is typically the *id* without `crossk`, e.g. `chromeos15-row2-rack4-host6`. The hostname for a DUT (`${DUT_HOSTNAME}` in this doc) is not shown on the skylab bot page, but it is the *dut_name* with '.cros' appended e.g. `chromeos15-row2-rack4-host6.cros`. *** Autotest requires a working build of the board type being tested on, so it is best to pick a board for which you have already built an image on your machine. Autotest will automatically determine the hostnames of the router and packet capture device but if you want to access them directly, say through ssh, you can use the hostnames **${DUT\_NAME}-router.cros** and **${DUT\_NAME}-pcap.cros** respectively. You can access each with ssh through the root user with password `test0000`. Lastly, Autotest may have issues with hosts that have the `chameleon` label. If you are having [chameleon issues], the current workaround is to set *enable_ssh_tunnel_for_chameleon: True* in `src/third_party/autotest/files/global_config.ini`. #### Using a local testing setup For a local test setup, you'll need a flashed DUT and two flashed Google-made wifi routers that run Chrome OS, all running special test images. The Google-made routers can be either of the boards `whirlwind` or `gale`, and see [network_WiFi_UpdateRouter] for what images they should be running. In order for Autotest to determine the hostnames of your router and packet capture device, you'll have to designate their IP addresses within your chroot. Assign the IP address of your DUT to 'dut', and the IPs of your routers to 'dut-router' and 'dut-pcap' by adding lines like these to `/etc/hosts`: ```bash xxx.xxx.xxx.xxx dut-router xxx.xxx.xxx.xxx dut-pcap xxx.xxx.xxx.xxx dut ``` Now, you can use **${DUT\_HOSTNAME}** = '*dut*' and Autotest will use your hosts file to find the other devices. The final consideration when using a local testing setup is that the designated testbeds are contained in shielding boxes which isolate them from other signals, while your local setup is probably held in open air. This means that your packet capture device will also pick up packets from any other devices broadcasting in your area. This will make the packet feed noisier, but you can still find all the packets involved in the connection process so its not a dealbreaker for this codelab. ### Let's get started [network_WiFi_SimpleConnect] is a very simple test that connects and disconnects a DUT from a router, so it's ideal for our purposes in this codelab. The test itself is held at `server/site_tests/network_WiFi_SimpleConnect/` in the Autotest repository. Briefly look through this file to get a sense for what it is doing. Before you make any changes to code, be sure to start a new branch within the Autotest repository. #### 1. Gather pcap data Our first goal is to initiate packet capture and record all of the frames that our pcap device sees throughout the test. Conveniently, [network_WiFi_SimpleConnect] already utilizes a pcap device, which is accessed at `self.context.capture_host`. Before the testing starts, the test begins capturing packets by calling `start_capture()` on the capture device, and after the test completes, `stop_capture()` completes the capturing process. `stop_capture()` returns a list of filepaths that hold the captured packets, so let's store the results of this function in a variable: ```python3 capture_results = self.context.capture_host.stop_capture() ``` The pcap file is accessible at `capture_results[0].local_pcap_path`, so let's print out a dump of our captured packets. Add these lines after the call to `stop_capture()`: ```python3 packets = open(capture_results[0].local_pcap_path, 'r') logging.info(packets.read()) packets.close() ``` Now, lets run the test and see what we can learn: ```bash test_that --fast -b ${BOARD} ${DUT_HOSTNAME} network_WiFi_SimpleConnect.wifi_check5HT20 ``` That's a lot of garbage. The packets aren't going to be much use to us in their current state. In the next section, we'll use Wireshark to translate the packets into a readable form that we can study. #### 2. Use Wireshark to analyze the packets Pyshark is a wrapper for Wireshark within Python, and we'll be using it in this codelab to interperet our captured packets. Learn more at the [Pyshark documentation] page. Delete the lines you just added and replace them with calls to Pyshark that will parse and translate the packets, then write the packets to a file: ```python3 import pyshark capture = pyshark.FileCapture( input_file=capture_results[0].local_pcap_path) capture.load_packets(timeout=2) packet_file = open('/tmp/pcap', 'w') for packet in capture: packet_file.write(str(packet)) packet_file.close() ``` Run the Autotest again and open `/tmp/pcap`. Look at that, tons of human-readable data! Maybe even a little too much? Right now we're getting the entirety of every packet, but we only need a few fields. As a final step, we're going to parse out the needed fields from each packet so we can digest some relevant information about the connection process. Add the following methods to the global scope of [network_WiFi_SimpleConnect]: ```python3 def _fetch_frame_field_value(frame, field): layer_object = frame for layer in field.split('.'): try: layer_object = getattr(layer_object, layer) except AttributeError: return None return layer_object """ Parses input frames and stores frames of type listed in filter_types. If filter_types is empty, stores all parsed frames. """ def parse_frames(capture_frames, filter_types): frames = [] for frame in capture_frames: frame_type = _fetch_frame_field_value( frame, 'wlan.fc_type_subtype') if filter_types and frame_type not in filter_types: continue frametime = frame.sniff_time source_addr = _fetch_frame_field_value( frame, 'wlan.sa') dest_addr = _fetch_frame_field_value( frame, 'wlan.da') frames.append([frametime, source_addr, dest_addr, frame_type]) return frames ``` Using these functions, you can retrieve a timestamp, the source address, the destination address, and the frame subtype for every packet that your pcap device captured over the course of the test. The keywords within `parse_frames()` ('wlan.sa', 'wlan.da', 'wlan.fc_type_subtype'), are special Wireshark filters that correspond to the relevant data we are looking for. There are over 242000 such filters which you can find in the [wireshark docs]. Now we just need to call `parse_frames()` and upgrade our packet logging logic. Replace the file logging logic from above with the following code which parses the frames into a much more readable format: ```python3 frameTypesToFilter = {} frames = parse_frames(capture, frameTypesToFilter) packet_file = open('/tmp/pcap', 'w') packet_file.write('{:^28s}|{:^19s}|{:^19s}|{:^6s}\n'.format( 'Timestamp', 'Source Address', 'Receiver Address', 'Type')) packet_file.write('---------------------------------------------------------------------------\n') for packet in frames: packet_file.write('{:^28s}|{:^19s}|{:^19s}|{:^6s}\n'.format( str(packet[0]), packet[1], packet[2], packet[3])) packet_file.close() ``` This time when we run the test we can very concisely see every single packet that our pcap device captured, and we get only the data which is relevant to our purposes. Later on we'll populate `frameTypesToFilter` to single out the frames that are relevant to the connection/disconnection process, but first let's look deeper into the frames themselves. #### 3. Learn some 802.11 background Before we start analyzing the packets, we need some background on 802.11 frames. The state machine below represents the 802.11 connection/disconnection protocol. As you can see, a connection's state is determined by the authentication and association status between its devices. The types of packets that a device is able to send and receive are dependent on the state of its connections.  ##### Authentication and Association In order to ensure security, users must be authenticated to a network before they are allowed to use the network. The authentication process itself is not strictly defined by the 802.11 protocol, but it usually consists of a robust cryptographic exchange that allows the network to trust the user. Once a user has been authenticated to the network, it is *trusted*, but it is still not actually a member of the network until it has been *associated*. Association can be thought of as the proccess of actually joining the network, and also acts as a sort of *registration* that allows the network to determine which access point to use for a given user. ##### Class 1 frames Class 1 frames can be sent in any state, and they are used to support the basic operations of 802.11 connections. Class 1 frames are called *Management Frames* and they allow devices to find a network and negotiate their connection status. **Some class 1 frames:** * *Beacons* are frames that access points send out on a regular interval to broadcast their existence to the world. Devices are only aware of access points because they can see the beacon frames they send. * Devices respond to beacons with *Probe Requests* which in turn let the network know of their existence. The probe request also includes a list of all data rates the device supports, which the network can use to check for compatibility with those supported by the access point. * Access points respond with *Probe Responses* which either confirm or deny compatibility. * If the two are compatible, they can engage in the authentication/association process as explained above with various *Association* and *Authentication* frames. ##### Class 2 frames Class 2 frames can only be sent from a successfully authenticated device, which means they can be sent in states 2 and 3. Class 2 frames are called *Control Frames*, and their purpose is to allow authenticated devices to negotiate the sending of data between them. Request to send (RTS), clear to send (CTS), and acknowledge (ACK) are all examples of class 2 frames. ##### Class 3 frames Class 3 frames can only be sent from an authenticated and associated device, meaning they can only be sent while in state 3. Class 3 frames are *Data Frames* and they make up all of the actual bulk of wireless communication. All frames which are used to send non-meta data between devices are data frames. #### 4. Let's analyze some packets Now that we have a basic understanding of 802.11 frame classes, we can use our captured packets to study the 802.11 connection/disconnection protocol in action. Near the bottom of this page is a set of [lookup tables] that outline every type of frame in the 802.11 protocol, which you can use to determine what kind of packets we picked up. [Solutions and hints] to the questions below can be found after the lookup tables at the bottom of this page, but please do your best to answer them yourself before referring to the solutions. Lets see if we can answer some basic questions about your configuration based on the context of the captured packets: 1. What is the MAC address of your router? (you may already know this, but try to infer from the context of the packets) 1. What is the MAC address of your DUT? 1. What is the beacon interval (time between beacons) of your router? 1. What could a receiver address of *ff:ff:ff:ff:ff:ff* indicate? Now, try to find the frames where the DUT and router negotiate their connection. Depending on how noisy your setup is this could be somewhat difficult, but you should be able to see the authentication/association process in action by looking for some key frame types. (Hint: look for a class 3 frame being sent from your DUT to your router, and work back to see the frames that got them there). Study the process and compare the flow to the frame class descriptions above. #### 5. Filter the frames and check your results We can populate `framesToFilter` with frame type codes (i.e. '0x04') to show only the frames that are a part of the connection process. Based on what you know about the 802.11 state machine, begin filtering for frames that you know are relevant. Do not include beacon frames (type 0x08) because while they are a part of the connection process, there are so many of them that they will clog up the output. After improving the filter, add the following code to the bottom of [network_WiFi_SimpleConnect] to produce another output file which only shows the frametypes so the testing script can parse them. ```python3 output_file = open('/tmp/filtered_pcap', 'w') for packet in frames: output_file.write(str(packet[3]) + '\n') output_file.close() ``` Now, test your ouput file by running the testing python script: ```bash python wifi-basics-codelab-pcap-test.py ``` This script will check your output to see if you've isolated the correct frames and that the entire connection sequence can be seen. If the script fails, keep adjusting your filter until it succeeds. After you have passed the test, review `/tmp/pcap` again to see the entire process in action. Finally, refer back to the questions in [section 4] one last time to see if you've gained any new insight into the 802.11 protocol. ## Lookup Tables ### Management Frames (Class 1) | Subtype Value | Hex Encoding | Subtype Name | |---------------|--------------|------------------------| | 0000 | 0x00 | Association Request | | 0001 | 0x01 | Association Response | | 0010 | 0x02 | Reassociation Request | | 0011 | 0x03 | Reassociation Response | | 0100 | 0x04 | Probe Request | | 0101 | 0x05 | Probe Response | | 1000 | 0x08 | Beacon | | 1001 | 0x09 | ATIM | | 1010 | 0x0a | Disassociation | | 1011 | 0x0b | Authentication | | 1100 | 0x0c | Deauthentication | | 1101 | 0x0d | Action | ### Control Frames (Class 2) | Subtype Value | Hex Encoding | Subtype Name | |---------------|--------------|------------------------------| | 1000 | 0x18 | Block Acknowedgement Request | | 1001 | 0x19 | Block Acknowledgement | | 1010 | 0x1a | Power Save (PS)-Poll | | 1011 | 0x1b | RTS | | 1100 | 0x1c | CTS | | 1101 | 0x1d | Acknowledgement (ACK) | | 1110 | 0x1e | Contention-Free (CF)-End | | 1111 | 0x1f | CF-End+CF-ACK | ### Data Frames (Class 3) | Subtype Value | Hex Encoding | Subtype Name | |---------------|--------------|--------------------------------------------| | 0000 | 0x20 | Data | | 0001 | 0x21 | Data + CF-Ack | | 0010 | 0x22 | Data + CF-Poll | | 0011 | 0x23 | Data + CF-Ack+CF-Poll | | 0100 | 0x24 | Null Data (no data transmitted) | | 0101 | 0x25 | CF-Ack (no data transmitted) | | 0110 | 0x26 | CF-Poll (no data transmitted) | | 0111 | 0x27 | CF-Ack + CF-Poll (no data transmitted) | | 1000 | 0x28 | QoS Data | | 1001 | 0x29 | Qos Data + CF-Ack | | 1010 | 0x2a | QoS Data + CF-Poll | | 1011 | 0x2b | QoS Data + CF-Ack + CF-Poll | | 1100 | 0x2c | QoS Null (no data transmitted) | | 1101 | 0x2d | Qos CF-Ack (no data transmitted) | | 1110 | 0x2e | QoS CF-Poll (no data transmitted) | | 1111 | 0x2f | QoS CF-Ack + CF-Poll (no data transmitted) | ## Solutions and hints ### Configuration questions 1. Your router should be sending many beacon packets (type 0x08 frames), so look for the source address of the frames of type 0x08. 1. Your DUT can be recognized as the device which has a "conversation" with your router. I.e. you should be able to see one IP which is the sender/receiver of several different management frames (0x00, 0x01, etc.) with your router. 1. The beacon interval is the time a device waits between sending beacon frames. You can determine this interval for a device by finding the time that passes between two beacons being transmitted by the device. The beacon interval for your router is most likely 100ms. 1. A receiver address of *ff:ff:ff:ff:ff:ff* indicates that the frame is being broadcasted to any receiver that can hear it. This is pattern is used for beacon frames because these frames are intended as a sort of 'ping' to all nearby devices. ### Packet filter solution The testing script is looking for a particular packet sequence that shows the DUT and router connecting to each other. The golden connection sequence is as follows: 1. Probe Request: 0x04 1. Probe Response: 0x05 1. Authentication: 0x0b 1. Assoc Request: 0x00 1. Assoc Response: 0x01 1. Deauthentication: 0x0c In practice, we have noticed that many of the recorded connection sequences do not include an Assoc Request packet, so the script is tolerant of that case. Finally, the script also verifies that no non-relevant frames were included, so any non class 1 frames in the output file will cause failure. (Although, only the frames in the sequence above are strictly required.) [chameleon issues]: https://crbug.com/964549 [lookup tables]: #lookup-tables [network_WiFi_UpdateRouter]: ../server/site_tests/network_WiFi_UpdateRouter/network_WiFi_UpdateRouter.py [network_WiFi_SimpleConnect]: ../server/site_tests/network_WiFi_SimpleConnect/network_WiFi_SimpleConnect.py [Pyshark documentation]: https://kiminewt.github.io/pyshark/ [section 4]: #4_let_s-analyze-some-packets [skylab portal]: https://chromeos-swarming.appspot.com/botlist?c=id&c=task&c=dut_state&c=label-board&c=label-model&c=label-pool&c=os&c=provisionable-cros-version&c=status&d=asc&f=label-wificell%3ATrue&k=label-wificell&s=id [skylab tools guide]: http://go/skylab-cli [solutions and hints]: #solutions-and-hints [test_that]: ./test-that.md [wificell documentation]: ./wificell.md [wireshark docs]: https://www.wireshark.org/docs/dfref/