User Manual for the Apple CoreCapture Framework

07/17/2018 ∙ by David Kreitschmann, et al. ∙ 0

CoreCapture is Apple's primary logging and tracing framework for IEEE 802.11 on iOS and macOS. It allows users and developers to create comprehensive debug output for analysis by Apple. In this manual, we provide an overview into the concepts, show in detail how CoreCapture logs can be created on iOS and macOS, and introduce the first CoreCapture dissector for Wireshark.



There are no comments yet.


This week in AI

Get the week's most popular data science and artificial intelligence research sent straight to your inbox every Saturday.

1 Motivation

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.” [1]. 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 [2], 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:

  1. Preparation:

    1. increase the debug output generation (CoreCapture stream)

    2. configure CoreCapture to log continuously (CoreCapture pipe)

  2. Reproduce the issue or condition

  3. Save the logs

    1. dump the log to persistent storage

    2. transfer logs to a computer (iOS/watchOS only)

uniform color list=gray!60!black for 4 items, back arrow disabled=true, additions= additional item offset=0.85cm, additional item border color=red, additional connections disabled=false, additional arrow color=red, additional arrow tip=stealth, additional arrow line width=1pt, additional arrow style=]-latex’, [flow diagram:horizontal]Driver, CC Stream, CC Pipe, File

Figure 1: CoreCapture flow of log entries

3 Creating CoreCapture traces on iOS

Apple provides instructions on their developer website on the creation of logs for bug reports [1].

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).

Figure 2: iOS Wi-Fi Diagnostic Mode in Wi-Fi Settings
Figure 3: iOS Wi-Fi Diagnostic Mode
Figure 4: watchOS “Dump Wi-Fi Logs” button

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 [1]. 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 [3] 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

Figure 5: iOS MegaWifiProfile excerpt

As stated above the profile is signed by Apple, which is strictly only required for installing the 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 [1] 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:

sudo ./cctool -o -p DriverLogs -x 1

In this case, the parameter -x 1 sets the policy to continuous, which can also be verified using the I/O Registry.

Figure 6: CoreCapture Pipes and LogStreams
Figure 7: CoreCapture Pipe properties

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.

Figure 8: CoreCapture LogStream properties
export CCTOOL=/System/Library/PrivateFrameworks/CoreCaptureControl.framework/Resources/cctool
sudo $CCTOOL -o -p DriverLogs -x 1
sudo $CCTOOL -o -p DriverLogs -s DriverLogs -l 5 -f 8388608
sudo $CCTOOL -o -p IO80211AWDLPeerManager -x 1
sudo $CCTOOL -o -p IO80211AWDLPeerManager -s bpfIO80211Awdl -l 5 -f 27358198660246032 -g 1 -m 0
sudo $CCTOOL -o "*" -p "*" -c manual_dump
Figure 9: cctool commands using log settings from Apples iOS profile

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.

csrutil enable --without nvram
nvram boot-args=debug=0x10000 awdl_log_flags=0xffffffffffffffff awdl_log_flags_verbose=0xffffffffffffffff awdl_log_flags_config=1 wlan.debug.enable=0xff
Figure 10: Disabling part of theSystem Integrity Protection and setting the boot-args NVRAM variable

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 folder with output from Apple’s higher level IEEE 802.11 stack and a adapter-specific folder such as 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.

Figure 11: iOS CoreCapture folder
Name Content Format iOS macOS
DatapathEvents Traces for all network interfaces IOCTLs between IO80211Family and the Broadcom driver AWDL specific output PCAP
DriverLogs Broadcom driver logs TXT
FirmwareBusLogs unidentified traces PCAP
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
Table 1: Overview of the files inside a CoreCapture folder

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 [4].

6.1 Building Wireshark

Wireshark can be compiled as described in the included Readme file. On macOS we recommend using the homebrew package manager [5]:

brew install --only-dependencies --with-qt wireshark
git clone <git url> wireshark-awdl # or download an archive
mkdir wireshark-build
cd wireshark-build
export PATH="/usr/local/opt/qt/bin:$PATH"
cmake ../wireshark-awdl
open run/

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 [6] 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.

Figure 12: Wireshark User DLTs Table