Debugging IEEE 802.11 issues often involves combining several sources of information on the devices and often involves creating wireless traces using a separate device, which may not be at hand in all scenarios. Issues may only appear in very specific scenario, e.g. a specific wireless network, thus it is critical for vendors to receive enough information about an issue to fully understand it and provide a solution.
To generate and package broad debug information Apple created the CoreCapture framework. On demand or in case of driver errors CoreCapture creates a folder with log files and dumps of internal hardware state, such as a RAM dump of the Wi-Fi chip. The most interesting data for us was found in PCAP trace files. These files combine driver communication traces, log messages and network traces into one file.
During the log creation process accompanying information states that “You will be able to review the log files on your computer prior to sending them to Apple.” . Reviewing these files is, unfortunately, not possible because there are no public tools to read these proprietary files. Having tools at hand to read these files gives users the possibility to make an informed decision and protect their privacy. The generated data is tailored for the analysis of driver and firmware issues by Apple but could be useful for security researchers, e.g., for reverse engineering. Reverse engineering the Apple Wireless Direct Link Protocol , a proprietary wireless ad hoc protocol, was our entry point to CoreCapture.
2 Introduction to CoreCapture
Traditionally creating debug logs, e.g., with syslog, starts with increasing the amount of log data (e.g., by starting an application in debug mode) and filling the disk with logs. This is not ideal for mobile devices because issues may only appear very seldom and storage is limited. In CoreCapture, information written to a stream that is stored temporarily in a kernel buffer (pipe) until an error condition is reached or a dump is triggered manually. Only then a CoreCapture output is generated and saved to disk, as shown in Fig. 1. Therefore, creating a log in CoreCapture, involves multiple steps:
increase the debug output generation (CoreCapture stream)
configure CoreCapture to log continuously (CoreCapture pipe)
Reproduce the issue or condition
Save the logs
dump the log to persistent storage
transfer logs to a computer (iOS/watchOS only)
3 Creating CoreCapture traces on iOS
Apple provides instructions on their developer website on the creation of logs for bug reports .
In the case of Wi-Fi logs Apple provides a cryptographically signed configuration profile (MegaWifiProfile.mobileconfig) to enable the Wi-Fi diagnostics mode on iOS (and even watchOS) devices. The profile is set to expire after 31 days, therefore this process works only as long as Apple provides updated configuration profiles. To install the configuration profile, the file must be opened on an iOS device (e.g., by opening the link on the device or sending the file via mail or AirDrop). After the profile is installed, a new menu item with a Save Log button is available in the Settings app (Fig. 2 and 3).
After clicking the Save Log button, capture files are saved to flash storage, but are not visible in the iOS UI. They must be exported to a connected computer. The officially supported way to export the files from iOS is through iTunes . When syncing with iTunes on the Mac, CoreCapture files are copied to the folder /Users/<USER>/Library/Logs/CrashReporter/MobileDevice/<DeviceName>/CoreCapture.
If no Mac or Windows computer is available, we can also copy these files using the idevicecrashreport tool from the libimobiledevice  suite.
3.1 Creating traces on watchOS
The process on watchOS is almost the same as on iOS: When opening the configuration profile on an iPhone a user can choose to install it on a connected Apple Watch. The trigger menu item then appears directly in the Settings App on the Watch (Fig. 2).
While the Watch is charged, traces are transferred to the connected iPhone. Afterwards they can be copied to a computer, just as with iOS. The files can be found in /Users/<USER>/Library/Logs/CrashReporter/MobileDevice/<DeviceName>/ProxiedDevice-<UUID>/CoreCapture.
3.2 More details on the MegaWifi configuration profile.
Configuration profiles are based on Apple’s Property List files an optional signature wrapper. Therefore they can be read with a standard text editor. The profile contains three different payloads:
Sets CoreCapture parameters, as shown exemplarily in Fig. 5. This, e.g., shows that the FirmwareLogs/Chip_UART logstream is set to loglevel 5 and LogFlags is set to 1. The FirmwareLogs pipe’s policy is set to 1 (=continuous). This is replicated very similarly for other Wi-Fi drivers and streams. Unfortunately there is no documentation which loglevel and flag parameters are available.
Increased log output from several Wi-Fi related processes. This output is sent to Apple’s Unified Logging framework and is available in the Console application on a Mac. Unified Logging is not part of this manual.
Enables the diagnostic menu item, increases log output for several processes and adds configuration redundant to the payload of com.apple.corecapture.configure.
As stated above the profile is signed by Apple, which is strictly only required for installing the com.apple.defaults.managed payload, especially enabling the otherwise hidden menu item. Therefore a custom unsigned configuration profile to configure CoreCapture can be created and installed, but it is not possible to enable the hidden menu item. If two profiles are installed, Apple’s profile seems to take precedence over an unsigned profile, making it impossible to override e.g., loglevels.
It may also be possible to trigger CoreCapture by inducing an error in the driver, because in some conditions CoreCapture is triggered automatically, but this is outside the scope of this manual.
4 Creating traces on macOS
Apple’s official instructions  to create Wi-Fi logs on the Mac involve using the Wireless Diagnostics Application111alt-click the Wi-Fi symbol in the menu bar to run Wireless Diagnostics, which amongst other information also triggers a manual capture. Unfortunately, the timing of these captures can’t be influenced so it may not be ideal for all cases. Therefore, a better way is to set up CoreCapture manually.
It is possible to install the iOS configuration profile on a Mac, but this provides only logging for the shared part of the Wi-Fi driver and no manual trigger in the UI. But this is not required anyway, because Apple provides us with the cctool command line tool, deep inside the CoreCapture Framework.222/System/Library/PrivateFrameworks/CoreCaptureControl.framework/Resources/cctool It can be used to change settings, just as the configuration profile, and trigger a manual capture. Unfortunately is not possible to list all available pipes and streams with cctool, but the information is available through another framework: IOKit.
4.1 IOKit’s IORegistry
IOKit includes the I/O Catalog which is responsible for matching a device to a driver and the tree-based I/O Registry where all actual devices and properties are listed. It is also the place to find the available CoreCapture pipes and streams. The IORegistry can be queried with IORegistryExplorer333Part of Apples Additional Tools for Xcode or the ioreg command. When switching to the CoreCapture mode in IORegistryExplorer (Fig. 6), several pipe objects with stream objects underneath are shown. Pipes can be understood as internal buffers and have, amongst others, a LogPolicy, Name, and Owner (Fig. 7). The stream objects underneath belong to the pipe. Therefore, they are addressed with the Name and Owner of the pipe as well as their own Name.
Different types of streams can be found here. A LogStream is a configurable information source, such as the logging facility of a driver. It can be configured as needed with loglevels, steering to the amount of information, and flags, setting which subsystems to be logged (Fig. 8). A DataStream is used for information generated once during a capture. This includes snapshots of the internal state of the driver, such as the RAM of the Wi-Fi chip.
4.2 Using cctool
cctool provides some help with the -h parameter and using the parameters together with the information found in the I/O Registry, CoreCapture properties can be changed:
In this case, the parameter -x 1 sets the policy to continuous, which can also be verified using the I/O Registry.
The process is roughly the same for the LogStream objects (Fig. 8): cctool is used to change log levels and log flags and they can be set differently for console and CoreCapture logs. Unfortunately, there is no list of the available loglevels and flags for macOS, but most default values from the iOS configuration profile can also be adapted for macOS. Values can be set to the maximum value with -1, resulting in, e.g., 0xffffffff.
A full example for the Broadcom driver and IO80211PeerManager (the main class handling AWDL in IO80211Family) is presented in Fig. 9. Capture files are saved to /Library/Logs/CrashReporter/CoreCapture.
4.3 Increasing driver output on macOS further
More debug information is available in macOS by enabling additional flags in the boot arguments. The boot arguments need to be present in the NVRAM when the system boots. Thus, this is not possible with unrooted iOS devices. On macOS, access to the NVRAM is blocked by System Integrity Protection (SIP). This can be circumvented by booting the computer in recovery mode by pressing cmd+R during a reboot. The terminal can be accessed in the menu bar and the commands listed in Fig. 10
can be applied. These enable very verbose information in CoreCapture, although they could probably be set more selectively.
We note that disabling part of SIP which implements key security features of macOS renders the system vulnerable to attacks. Thus, we recommend to only do this on a dedicated and non-production machine.
5 A CoreCapture trace folder in detail
An exemplary capture is shown in Fig. 11. The Metadata folder holds information about the system and the time of the capture. The data folder holds the com.apple.iokit.IO80211Family folder with output from Apple’s higher level IEEE 802.11 stack and a adapter-specific folder such as com.apple.driver.AppleBCMWLANCoreV3. with more device-specific output. This mirrors the structure of the pipes and streams in the I/O Registry. Table 1 shows the content of these folders and their file format.
|DatapathEvents||Traces for all network interfaces IOCTLs between IO80211Family and the Broadcom driver AWDL specific output||PCAP|
|DriverLogs||Broadcom driver logs||TXT|
|FirmwareLogs||Broadcom firmware logs||TXT|
|StateSnapshots||internal state and memory dumps||TXT, BIN|
|AssociationEvent History||unidentified content, often empty||XML|
|ControlPath||IOCTLs and Events between user space and IO80211Family||PCAP|
|IO80211AWDL PeerManager||AWDL Traces, including log messages||PCAP|
|OneStats||I/O Registry output||XML|
|IOReporters.xml||I/O Registry output||XML|
6 Wireshark Dissector
Wireshark is a modular packet analyzer and uses the PCAP format natively. Therefore, we decided to extend Wireshark with a CoreCapture dissector. We provide our CoreCapture dissector as part of our Wireshark fork at .
6.1 Building Wireshark
Wireshark can be compiled as described in the included Readme file. On macOS we recommend using the homebrew package manager :
6.2 Creating DLT_USER Mapping
There is one last step to do before Wireshark can decode CoreCapture files successfully, namely, creating a mapping to the CoreCapture dissector. PCAP files are a container format for different types traces, such as 802.11, Bluetooth, Ethernet IP. A link-layer type value included in the PCAP file at creation time indicates at which layer to start the frame dissection. Apple chose to use their own proprietary format and non-unique link-layer type reserved for private use instead of existing link layer types  or requesting a unique identifier. Fortunately Wireshark allows to associate a custom dissector with these types:
Open the Wireshark Preferences select Protocols DLT_USER and Edit the Encapsulation table. Add User 3 (DLT=150) to the table with corecapture as payload protocol, as shown in Fig. 12.
-  Apple Inc. Bug reporting: Profiles and logs. [Online]. Available: https://developer.apple.com/bug-reporting/profiles-and-logs/
-  M. Stute, D. Kreitschmann, and M. Hollick, “One Billion Apples’ Secret Sauce: Recipe of the Apple Wireless Direct Link Ad hoc Protocol,” in ACM Conference on Mobile Computing and Networking (Mobicom), Oct. 2018, to appear.
-  libimobiledevice. [Online]. Available: http://www.libimobiledevice.org
-  D. Kreitschmann and M. Stute. (2018) AWDL and CoreCapture Wireshark dissector. [Online]. Available: https://seemoo.de/wireshark-awdl
-  Homebrew. [Online]. Available: https://brew.sh
-  Tcpdump. Link-layer header types. [Online]. Available: http://www.tcpdump.org/linktypes.html