This repository contains the implementation of the Osiris framework discussed in the research paper "Osiris: Automated Discovery of Microarchitectural Side Channels" (USENIX Security'21). You can find the paper at the USENIX website.
The framework is developed to find microarchitectural side channels in an automated manner. Currently the implementation supports only x86 processors.
Osiris is developed and tested on Arch Linux and Ubuntu. Hence, we expect Osiris to work on other Linux distributions as well but we did not test it.
- Arch-Linux-package:
gcc
- Ubuntu-package:
g++
- Arch-Linux-package:
make
- Ubuntu-package:
make
- Arch-Linux-package:
cmake
- Ubuntu-package:
cmake
- Arch-Linux-package:
capstone
- Ubuntu-packages:
libcapstone-dev, libcapstone3
- Arch-Linux-package:
openssl
- Ubuntu-package:
libssl-dev
On Ubuntu:
apt-get update
apt-get install python3 python3-pip python3-dev git libssl-dev libffi-dev build-essential
python3 -m pip install --upgrade pip
python3 -m pip install --upgrade pwntools
(taken from: https://github.com/Gallopsled/pwntools)
On Arch-Linux:
pip install pwntools --user
Just install all listed dependencies and execute ./build.sh INTEL
or ./build.sh AMD
for Intel and AMD processors, respectively.
To get precise results Osiris relies on the operating system to reduce the noise of its
measurements. This is done via fixing the processor frequency and by isolating a CPU core.
The script ./run.sh
(described later in this README) will ask for the isolated CPU core.
Osiris will also run without going through these steps but the results will be less reliable,
hence we strongly recommend following these steps.
One can isolate single CPU cores using the Linux kernel parameter isolcpus
, e.g.,
adding the parameter isolcpus=5,11
variable GRUB_CMDLINE_LINUX_DEFAULT
in /etc/default/grub
will isolate
the CPU cores 5 and 11. Note that one has to update GRUB after applying these changes, i.e, run grub-mkconfig -o /boot/grub/grub.cfg
.
It is beneficial to isolate both hardware threads belonging to one CPU core.
You can get a list of your hardware threads and their CPU cores via the following command:
cat /proc/cpuinfo |grep -E "(core id)|(processor)|(^$)"
Two hardware threads (called processors in the above output) belong to the same CPU core if they have the same core id.
One can fix the CPU frequency of a specific hardware thread using the following command by replacing
1337
with the number referring to the hardware thread:
echo "performance" | sudo tee /sys/devices/system/cpu/cpu1337/cpufreq/scaling_governor
Note that you should fix the frequency for the same hardware thread which was isolated in the previous
step.
Further note that it can be helpful to note down the content of the scaing_governor
file to revert
these changes.
If you missed this opportunity, a simple restart of your operating system should also do the trick.
This step is optional as we already provide the output of it inside ./x86-instructions
.
The instruction set provided by us does not include the sleep pseudo-instruction.
For fuzzing with the sleep pseudo-instruction you have to rerun this step with the corresponding
parameter.
You can find instructions for this step in the README of ./x86-instructions
You can start the main part of the framework using ./run.sh $CPUCORE
where $CPUCORE
is
a decimal number representing the CPU core Osiris will be executed on.
We highly recommend using an isolated CPU core with a fixed frequency (see "Noise Reduction").
Executing ./run.sh $CPUCORE
will fuzz with the assumption that the trigger sequence is equal
to the measurement sequence and will execute the trigger sequence architecturally (refer to the research paper for details).
The behavior can be changed with the following parameters:
Parameter | Description |
---|---|
--all |
Removes the assumption that the trigger sequence is equal to the measurement sequence. |
--speculation |
Executes the trigger sequence only in transient execution. |
--filter-cache |
Removes cache-based side channels from the final report. |
(Please note that the positional parameter for the CPU core always has to be the first argument, e.g., ./run.sh 11 --speculation --all
)
The previous script then will leave you with the following (or similar, depending on your parameters) contents in the folder ./build
:
# can be ignored (created and needed by the build system)
CMakeCache.txt
CMakeFiles
cmake_install.cmake
Makefile
# compiled binary
osiris
# can be ignored [1]
triggerpairs
triggerpairs-formatted
# results before confirmation stage (see Output Format)
triggerpairs.csv
# results of the first confirmation stage (see Output Format)
triggerpairs_confirmed_iter1.csv
# results that passed the first confirmation stage (see Output Format)
triggerpairs_confirmed_iter1_cleaned.csv
# results of the second confirmation stage (see Output Format)
triggerpairs_confirmed_iter2.csv
# results that passed the second confirmation stage (see Output Format)
triggerpairs_confirmed_iter2_cleaned.csv
# results after confirmation without cache-related side channels
triggerpairs_confirmed_iter2_cleaned_nocache.csv
# results after confirmation without cache-related side channels and only 1
# instance per unique triple of instruction categories is kept
triggerpairs_confirmed_iter2_cleaned_nocache_filtered_by_all.csv
# results after confirmation without cache-related side channels and only 1
# instance per unique triple of instruction categories is kept.
# Additionally, we only keep 1 instance per unique pair of measurement and trigger extensions
triggerpairs_confirmed_iter2_cleaned_nocache_filtered_by_all_mt_extensionpair.csv
1: These files are additional outputs from Osiris which exist in 2 forms (machine-readable in triggerpairs
; human-readable in triggerpairs-formatted
).
As these files are only used for development we will not describe them further.
The file (./x86-instructions/instructions.b64
) contains descriptions of instruction variants. One per line (excluding the first line).
The Format is as follows:
BR;AC;CATEGORY;EXTENSION;ISA-SET
With:
BR
: A base64-encoded representation of the bytes for the instructionAC
: The human-readable assembly code for the instructionCATEGORY
: The category of the instruction (e.g., arithmetic)EXTENSION
: The extension of the instruction (e.g., 3DNow)ISA-SET
: The ISA-set of the instruction. This is most of the time the same as the extension.
timing;M;T;R
With:
timing
: The observed timing difference in cycles between executions with and without the trigger sequenceM
: the measurement sequence consisting of an internal UID and the properties already mentioned previously (see "Instruction File")T
: the trigger sequence consisting of an internal UID and the properties already mentioned previously (see "Instruction File")R
: the reset sequence consisting of an internal UID and the properties already mentioned previously (see "Instruction File")
Many programs exist which can parse these CSV files. We like to use Microsoft Excel or LibreOffice Calc.
The following is an example of a reported sequence triple. The output is formatted as a table for better readability.
timing | measurement-uid | measurement-sequence | measurement-category | measurement-extension | measurement-isa-set | trigger-uid | trigger-sequence | trigger-category | trigger-extension | trigger-isa-set | reset-uid | reset-sequence | reset-category | reset-extension | reset-isa-set |
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
182 | 551c05b2 | INC byte ptr [R8] |
BINARY | BASE | I86 | 551c05b2 | INC byte ptr [R8] |
BINARY | BASE | I86 | 551c08ca | CLFLUSHOPT zmmword ptr [R8] |
CLFLUSHOPT | CLFLUSHOPT | CLFLUSHOPT |
We can see that Osiris observed a timing difference of 182 CPU cycles and that the
measurement sequence, i.e., the sequence whose timing was observed,
and the trigger sequence, i.e. the instruction sequence that lead to a timing delta,
were INC byte ptr [R8]
.
The reset sequence, i.e. the sequence that reset the microarchitectural state, was CLFLUSH zmmword ptr [R8]
.
Flushing a memory address from the CPU cache and triggering a side channel by loading it again is a well-known side channel known as Flush+Reload.
If there are questions regarding this tool, please send an email to daniel.weber (AT) cispa.saarland
or message @weber_daniel
on Twitter.
The paper is available at the USENIX website. You can cite our work with the following BibTeX entry:
@inproceedings{Weber2021,
author = {Weber, Daniel and Ibrahim, Ahmad and Nemati, Hamed and Schwarz, Michael and Rossow, Christian},
booktitle = {USENIX Security Symposium},
title = {{Osiris: Automatic Discovery of Microarchitectural Side Channels}},
year = {2021}
}
We are providing this code as-is. You are responsible for protecting yourself, your property and data, and others from any risks caused by this code. This code may cause unexpected and undesirable behavior to occur on your machine.