-
Notifications
You must be signed in to change notification settings - Fork 95
Introduction to HAL
HAL [/hel/] is a comprehensive netlist reverse engineering and manipulation framework. It takes a gate-level netlist — from an ASIC, an FPGA, or a third-party IP core — turns it into a graph-based representation, and gives you the tools to navigate, understand, transform, and simulate it.
Our vision is that HAL becomes the hardware reverse engineering equivalent of tools like IDA Pro or Ghidra. With HAL, we want to establish a common ground for researchers and analysts alike to improve reproducibility of results and take care of general tasks such as project management, netlist parsing, or netlist traversal. HAL offers
- high performance thanks to the optimized C++ core,
- flexibility through built-in Python bindings,
- modularity via a C++ plugin system, and
- stability ensured via a rich test suite.
HAL is actively developed by the Embedded Security group of the Max Planck Institute for Security and Privacy. Apart from multiple research projects, it is also used in our university lecture on hardware reverse engineering.
A gate-level netlist is what is left of a chip design after synthesis — and it is often all an analyst ever gets to see. You may obtain one by delayering and imaging an ASIC, by reverse engineering an FPGA bitstream, or simply because a vendor shipped you an encrypted or pre-synthesized IP core instead of readable source code.
Whatever the source, the result looks the same: tens of thousands of primitive gates wired together by nets, with no hierarchy, no meaningful signal names, and no comments. Every abstraction a human designer relied on — registers, arithmetic units, state machines, datapaths — has been dissolved into an undifferentiated sea of gates. Answering even simple questions ("where is the key stored?", "what does this circuit compute?") means recovering that structure by hand.
HAL gives you a foundation for doing this systematically. At its heart are three things:
- a netlist data model (netlist, gates, nets, modules, groupings) that mirrors how hardware is actually built, and in which you record what you figure out,
- a gate library abstraction (gate library, gate types) that models the behavior of the technology-specific cells your netlist is built from, and
- a symbolic reasoning engine for Boolean functions, including SMT solving, so you can reason about what a circuit computes rather than only about how it is wired.
HAL is a toolbox rather than a push-button solution, but it is a toolbox with a lot of prior art in it. The following are applications that HAL has been built for and used in — most of them are backed by published research and shipped as plugins.
Teach and learn hardware reverse engineering. Netlist reverse engineering is difficult to teach without a tool students can actually work in, which is why HAL underpins the practical part of our university lecture. The example projects shipped with HAL are built as a guided introduction and overlap with some of that material, though the lecture itself goes considerably further.
Detect and analyze hardware Trojans. Malicious modifications can be inserted anywhere between design and fabrication, and they are tiny compared to the surrounding design. HAL lets you recover the design's register structure, isolate suspicious logic, and reason about its trigger condition. The Crypto Trojan example project walks through locating a key-leaking Trojan inside a 10,000-gate AES core.
Recover high-level structure from a flattened netlist. Rebuilding the abstractions synthesis destroyed takes several complementary steps. Dataflow analysis (DANA) groups individual flip-flops back into the multi-bit registers they originally formed, module identification classifies the combinational blocks between those registers into word-level operations such as additions, counters, or comparisons, and bitorder propagation recovers the bit order within the registers.
Find cryptographic implementations. HAWKEYE automatically locates symmetric cryptographic primitives in a gate-level netlist without knowing the algorithm in advance — useful when you need to find the crypto core in a design before you can attack or audit it.
Reverse engineer finite state machines. Controllers are where a design's behavior is decided. HAL can extract the state transition graph of an FSM from its state register and transition logic, see the FSM example project.
Simulate and formally reason about a design. The netlist simulator and waveform viewer simulates arbitrary parts of a loaded netlist, the logic evaluator evaluates purely combinational subcircuits interactively, and the Boolean function engine lets you prove equivalence between a recovered subcircuit and a model of what you think it does (see the Simple ALU example).
Evaluate hardware obfuscation and logic locking. If you design a protection scheme, HAL is how you check whether it survives an attacker who has your netlist. Several published attacks on camouflaging, logic locking, and FSM obfuscation were implemented on top of HAL.
Audit third-party or legacy IP. When you only have a netlist and need to know what it really does — undocumented functionality, hidden debug paths, a supposedly removed feature — HAL gives you the traversal, simulation, and formal tooling to check.
Modify netlists, not just read them. HAL's data model is fully writable, and netlists can be exported again as Verilog. This makes it a platform for netlist instrumentation, design patching, obfuscation research, and — on the offensive side — Trojan insertion studies.
Publish reproducible research. Implementing your analysis as a HAL plugin means others can rerun it on their own netlists. We also maintain a set of modern benchmark circuits for evaluating netlist reverse engineering techniques in a separate repository.
HAL consists of a core library, two API layers on top of it, and a plugin system that everything else is built with.
Core. The HAL core is a C++ library that holds the netlist representation and all functionality operating on it: parsing, traversal, manipulation, Boolean function handling, and project management. It is optimized for netlists with hundreds of thousands of gates.
Python bindings. Nearly all core functionality is exposed to Python. This is the interface most users work with day to day: it is fast enough for real analyses, and it fits the exploratory nature of reverse engineering much better than a compile-run cycle. You can use it from the Python console and Python editor inside the GUI, or standalone via the python_shell plugin.
GUI. The GUI is where you actually look at the circuit. It renders the netlist as an interactive graph view, lets you navigate the module hierarchy, isolate parts of the design into views, group elements for later reference, and inspect every detail of a selected gate, net, or module. The embedded Python console operates on the very same netlist, so scripted and manual analysis go hand in hand.
Plugin system. Every non-core capability of HAL — including the GUI itself — is a plugin. Plugins are written in C++, have full access to the core API, and can expose their own Python bindings and GUI menu entries. See Create your own Plugins if you want to build one.
Around thirty plugins come with HAL, covering five broad areas:
- Input and output — parsers and writers for netlist formats such as Verilog and VHDL, for gate library formats such as liberty and HAL's own HGL, and a set of ready-to-use gate library definitions for common FPGA and ASIC technologies.
- Analysis — the reverse engineering tools behind most of the applications listed above.
- Execution and verification — simulation, waveform inspection, and SMT-based reasoning.
- Netlist transformation — cleaning up and normalizing a netlist so that the analyses above see the structure rather than the synthesizer's artifacts.
- User interface — the GUI itself, a command-line Python shell for headless and batch use, and a viewer for graphs produced by other plugins.
Note that not all plugins are built by default, which is worth knowing before you build: several of the tools used throughout this wiki are opt-in, see Building HAL.
For the complete list — what each plugin does, its CMake flag, whether it is built by default, and a link to its documentation — see Provided Plugins.
If this is your first contact with HAL, start here and work through it in order:
- Building HAL — get HAL onto your machine.
- Starting HAL — launch it with or without the GUI.
- Using HAL — import your first netlist and find your way around.
- Example Projects — work through the pre-built projects that ship with HAL; this is by far the fastest way to get a feel for the tool.
Once things click, where you go next depends on what you want to do:
- Analyze a netlist visually — the GUI documentation covers the graph view and every widget in detail.
- Script your analyses — Core explains the netlist data model (netlist, gate, net, module) that the Python API is built on.
- Use the existing tooling — Provided Plugins lists everything that ships with HAL, from dataflow analysis to simulation.
- Extend HAL — Create your own Plugins walks through writing a plugin, and there are dedicated guides for adding netlist and gate library parsers or a gate library of your own.
- Publish with HAL — HAL in Academia covers how to cite it and what has been built on it so far.
This wiki provides an overview of HAL and its most important applications, using small Python snippets to teach the underlying concepts. For a complete reference of every available function, see the API documentation:
For background on the project, watch our talk at 36C3, and see HAL in Academia for publications built on HAL and for how to cite it.
Stuck, or missing something? Please open an issue — see Reporting Bugs.