Python ELMO

Python ELMO is a Python library which proposes an encapsulation of the project ELMO.

[MOW17] Towards Practical Tools for Side Channel Aware Software Engineering : ’Grey Box’ Modelling for Instruction Leakages by David McCann, Elisabeth Oswald et Carolyn Whitnall. https://www.usenix.org/conference/usenixsecurity17/technical-sessions/presentation/mccann

ELMO GitHub: https://github.com/sca-research/ELMO

Requirements

To use Python ELMO, you need at least Python3.5 and numpy.

The library will install and compile ELMO. So, you need the GCC compiler collection and the command/utility ‘make’ (for more details, see the documentation of ELMO). On Ubuntu/Debian,

sudo apt install build-essential

To use ELMO on a leaking binary program, you need to compile the C implementations to binary programs (a “.bin” file). “ELMO is not linked to any ARM specific tools, so users should be fine to utilise whatever they want for this purpose. A minimal working platform for compiling your code into an ARM Thumb binary would be to use the GNU ARM Embedded Toolchain (tested version: arm-none-eabi-gcc version 7.3.1 20180622, it can be downloaded from https://developer.arm.com/open-source/gnu-toolchain/gnu-rm).”, see the documentation of ELMO for more details.

Installation

First, download Python ELMO.

git clone https://git.aprilas.fr/tfeneuil/python-elmo

And then, install ELMO thanks to the script of installation.

python setup.py install

Usage

Create a new simulation project

What is a simulation project ? It is a project to simulate the traces of one binary program. It includes

• A Python class which enable to generate traces in Python;
• The C program which will be compile to have the binary program for the analysis;
• A linker script where the configuration of the simulated device are defined.

To start a new project, you can use the following function.

from elmo.manage import create_simulation
create_simulation(
   'dilithium', # The (relative) path of the project
   'DilithiumSimulation' # The classname of the simulation
)

This function will create a repository dilithium with all the complete squeleton of the project. In this repository, you can find:

• The file project.c where you must put the leaking code;
• The file projectclass.py where there is the class of the simulation which will enable you to generate traces of the project in Python scripts;
• A Makefile ready to be used with a compiler arm-none-eabi-gcc.

List all the available simulation

from elmo.manage import search_simulations
search_simulations('.')

{'DilithiumSimulation': <class 'DilithiumSimulation'>,
 'KyberNTTSimulation': <class 'KyberNTTSimulation'>}

Python ELMO offers a example project to you in the repository projects/Examples of the module. This example is a project to generate traces of the execution of the NTT implemented in the cryptosystem Kyber.

Use a simulation project

Warning! Before using it, you have to compile your project thanks to the provided Makefile.

from elmo.manage import get_simulation
KyberNTTSimulation = get_simulation_via_classname('KyberNTTSimulation')

import numpy as np
Kyber512 = {'k': 2, 'n': 256}
challenges = [
    np.ones((Kyber512['k'], Kyber512['n']), dtype=int),
]

simulation = KyberNTTSimulation(challenges)
simulation.run() # Launch the simulation
traces = simulation.get_traces()
# And now, I can draw and analyse the traces

Use a simulation project thanks to a server

Sometimes, it is impossible to run the simulation thanks the simple method run of the project class. Indeed, sometimes the Python script is executed in the environment where Python ELMO cannot launch the ELMO tool. For example, it is the case where Python ELMO is used in SageMath on Windows. On Windows, SageMath installation relies on the Cygwin POSIX emulation system and it can be a problem.

To offer a solution, Online ELMO can be used thanks to a link client-server. The idea is you must launch the script run_server.py which will listen (by default) at port 5000 in localhost.

python -m elmo run-server

And after, you can manipulate the projects as described in the previous section by replacing run to run_online.

from elmo.manage import get_simulation
KyberNTTSimulation = get_simulation('KyberNTTSimulation')

import numpy as np
Kyber512 = {'k': 2, 'n': 256}
challenges = [
    np.ones((Kyber512['k'], Kyber512['n']), dtype=int),
]

simulation = KyberNTTSimulation(challenges)
simulation.run_online() # Launch the simulation THANKS TO A SERVER
traces = simulation.get_traces()
# And now, I can draw and analyse the traces

Warning! Using the run_online method doesn’t exempt you from compiling the project with the provided Makefile.

Use the ELMO Engine

The engine exploits the model of ELMO to directly give the power consumption of an assembler instruction. In the model, to have the power consumption of an assembler instruction, it needs

• the type and the operands of the previous assembler instruction
• the type and the operands of the current assembler instruction
• the type of the next assembler instruction

The type of the instructions are:

• “EOR” for ADD(1-4), AND, CMP, CPY, EOR, MOV, ORR, ROR, SUB;
• “LSL” for LSL(2), LSR(2);
• “STR” for STR, STRB, STRH;
• “LDR” for LDR, LDRB, LDRH;
• “MUL” for MUL;
• “OTHER” for the other instructions.

from elmo.engine import ELMOEngine, Instr
engine = ELMOEngine()
for i in range(0, 256):
    engine.add_point(
        (Instr.LDR, Instr.MUL, Instr.OTHER), # Types of the previous, current and next instructions
        (0x0000, i), # Operands of the previous instructions
        (0x2BAC, i)  # Operands of the current instructions
    )
engine.run() # Compute the power consumption of all these points
power = engine.power # Numpy 1D array with an entry for each previous point
engine.reset_points() # Reset the engine to study other points

Licences

MIT