A User Guide

Looking for something specific? The User Guide, Formats, Reversing Topics and FAQ are indexed within the app — open Archaeology, click on the Help menu (Command-?), and type in the Search field. Results listed under Help Topics link directly to the appropriate section here.

Opening a File in Archaeology

There are several ways to open file using Archaeology:

Whichever method you choose, Archaeology examines the file to identify the binary format and — assuming it is a format that Archaeology recognizes — opens a new window with the best representation possible: Archaeology main window

In this example, the binary data is in BER-encoded ASN.1 format, as shown on the right side of the window, under the toolbar.

The representation underneath will vary with the actual format: see Formats for how to navigate each supported format. Or click the Help toolbar button Help toolbar button to directly open the format-specific documentation for the current representation.

Archaeology tells macOS that it can open any kind of file, because binary formats are often used without file extensions, and might have any Kind, or a generic Document one. Archaeology does its best to decode whatever you open, but if it doesn't find a format it recognizes, it will say that the file “contains data in a format that can't be decoded.”

Decoding an Embedded Data Value

Depending on the file and its binary format, you will often find an embedded “chunk” of data that is further encoded in some way. In Archaeology, this will appear as an item whose contents is described as “X bytes of data” or in the ASN.1 format, as an item with a tag like OCTET STRING.

In this case, you can ask Archaeology to further decode this chunk of data. Select the item and click the Decode toolbar button Decode toolbar button or use Go > Decode Item (Cmd-Down Arrow). Assuming that Archaeology recognizes the format of the data, it will decode it and show a new view, replacing the file that it came from.

Each time you find another embedded chunk of data, you can continue recursively decoding in this manner.

Of course, not every chunk of data will be decodable. Some have formats that aren't known or supported by Archaeology. Some are unique identifiers or cryptographic hashes of some sort — it's not uncommon to come across SHA-256 digests or the like. (If you come across data that is exactly 16, 20 or 32 bytes, it's very likely a digest of some sort, for example.) However, you can always ask Archaeology to try. If Archaeology can't decode a specific chunk of data, you might learn more by inspecting the value info.

If, at any point, you want to go back to the previous (containing) view, click the Back toolbar button Back toolbar button or use Go > Back (Cmd-[). To go back multiple steps at once — or just to see where you've come from — hold down the toolbar button briefly: Hold down the Back button

Most of the time, Archaeology will figure out the best way to decode a chunk of data (if it can decode it at all). But there are a few cases where data can be decoded in different ways — such as Cocoa Keyed Archives, which are also macOS Property Lists. To override Archaeology's default choice, hold down the Decode toolbar button briefly, and choose a specific format: Hold down the Decode button

Getting More Info About a Data Value

In addition to asking Archaeology to decode an item containing a chunk of data, you can see some general information about that chunk. This can be especially helpful where Archaeology doesn't know how to decode the chunk in question.

To show this additional information, select the item and click the Info toolbar button Show Info toolbar button or use File > Show Value Info (Cmd-I): Show Value Info inspector

From this data value inspector, you'll find the following information:

The Open in Hex Editor and Export Data Value buttons are simply shortcuts to the integration features described below.

Moving a Data Value to Another App

Archaeology provides a few ways to get a specific data value into another app or Terminal command:

Searching the Decoded View

For some binary formats, Archaeology allows you to search in the decoded data. For example, you can search a Cocoa Keyed Archive for specific keys, class names or string values; you can search a macOS Property List for keys or values.

If searching is possible for the current view, the toolbar search field will be enabled. Click in the search field (or use Cmd-F) and enter text: Search Field in toolbar

Press Return to perform the search. How the search results are shown varies with the binary format: see Formats for details.

To change which aspect of the decoded data is being searched — keys or values, say — click the search button Search button in toolbar search field inside the search field.

The “trowel” Command-Line Tool

Archaeology provides a command-line tool — called trowel — that can be useful when you're working in the Terminal. You can use it to open a file in Archaeology by path, without needing to go through the File > Open dialog. You can also specify the expected format and other options.

The trowel tool is delivered inside the Archaeology application bundle, but consistent with our philosophy that you should decide when and how to install software on your Mac, the app does not try to install the command line tool for you.

The easiest way to use trowel is to make a symbolic link to it, inside some directory that is already in your shell's search path. You can get the path to the tool (regardless of where Archaeology itself is installed) by using Help > About the Command-Line Tool, and clicking Copy Path to “trowel” Tool. Then paste that into a Terminal command something like this:

ln -s ⌘V /usr/local/bin

Run trowel with no arguments to see usage information.

The trowel tool relies upon other resources inside the Archaeology application bundle, so don't try to copy or hard-link the tool somewhere else, or it will simply abort when you try to run it. A symbolic link works because the executable can still find the rest of Archaeology relative to itself. If you don't want to use a symbolic link, though, you can use any other mechanism that expands to the actual tool path retrieved through Copy Path to “trowel” Tool, such as a shell alias.