Microwalk is a microarchitectural leakage detection framework, which combines dynamic instrumentation and statistical methods in order to identify and quantify side-channel leakages. For the scientific background, consult the corresponding paper.
For Windows, it is recommended to install Visual Studio, as it brings almost all dependencies and compilers, as well as debugging support. The solution can then be built directly in the IDE.
The following guide is mostly for Linux systems and command line builds on Windows.
The main application is based on .NET 5.0, so the .NET 5.0 SDK is required for compiling.
cd Microwalk dotnet build -c Release
Run (compiles and executes; if you compile manually, you can suppress compiliation with
cd Microwalk dotnet run -c Release <args>
The command line arguments
<args> are documented in Section "Configuration"
Microwalk comes with a Pin tool for instrumenting and tracing x86 binaries. Building the Pin tool requires the full Pin kit, preferably the latest version. It is assumed that Pin's directory path is contained in the variable
When building through Visual Studio: Edit Settings.props to point to the Pin directory.
cd PinTracer make PIN_ROOT="$pinDir" obj-intel64/PinTracer.so
Run (assuming the
pin executable is in the system's
pin -t PinTracer/obj-intel64/PinTracer.so -o /path/to/output/file -- /path/to/wrapper/executable
Note that the above run command is needed for testing/debugging only, since
Microwalk calls the Pin tool itself.
Pin wrapper executable
In order to efficiently generate Pin-based trace data, Microwalk needs a special wrapper executable which interactively loads and executes test cases. The
PinTracerWrapper project contains a skeleton program with further instructions ("
/*** TODO ***/").
The wrapper skeleton is C++-compatible and needs to be linked against the target library. It works on both Windows and Linux (GCC).
Alternatively, it is also possible to use an own wrapper implementation, as long as it exports the Pin notification functions and correctly handles
The general steps for analyzing a library with Microwalk are:
Copy and adjust the
PinTracerWrapperprogram to load the investigated library, and read and execute test case files. It is advised to test the wrapper with a few dummy test cases, and use debug outputs to verify its correctness. Make to sure to remove these debug outputs afterwards, else they may clutter the I/O pipe which Microwalk uses for communication with the dynamic instrumentation framework, and lead to errors.
Create a custom test case generator module, or check whether the built-in ones are able to yield the expected input formats. Guidelines for adding custom framework modules can be found in the section "Creating own framework modules".
Compose a configuration file which describes the steps to be executed by Microwalk.
Microwalk takes the following command line arguments:
-p <plugin directory>(optional)
A directory containing plugin binaries. This needs to be specified when the configuration references a plugin that is not in Microwalk's main build directory.
The path to a YAML-based configuration file.
Creating own framework modules
Follow these steps to create a custom framework plugin with a new module:
Create a new project
MyPluginand add a reference to the
Create a class
PluginMainwhich derives from
Microwalk.FrameworkBase.PluginBase. In this class, you need to override the
Register()function (see step 5).
Create a class
MyModulefor your new module, which inherits from
XXXStageand has a
XXXStagehere corresponds to one of the framework's pipeline stages:
TestcaseStage: Produces a new testcase on each call.
TraceStage: Takes a testcases and generates raw trace data.
PreprocessorStage: Takes raw trace data and preprocesses it.
AnalysisStage: Takes preprocessed trace data and updates its internal state for each trace. Yields an analysis result once the finish function is called.
Implement the module logic.
Register the module by calling
Compile the plugin project.
Run Microwalk and pass the plugin's build folder via the
-pcommand line switch.
Look into the
Microwalk.Plugins.PinTracer project for some examples.
Contributions are appreciated! Feel free to submit issues and pull requests.
The entire system is licensed under the MIT license. For further information refer to the LICENSE file.