Containers

container.py

class lascar.container.container.AbstractArray(shape, dtype)

Bases: object

Used when your leakage or data cannot be represented as an array (most of the time in lascar.container.container.AbstractContainer) It simply emulates a few methods needed by other classes (such as lascar.session.Session)

Parameters:

• shape – the shape of your leakages (or values)
• dtype – the dtype of your leakages (or values)

update(array)

zeros()

class lascar.container.container.AbstractContainer(number_of_traces, **kwargs)

Bases: lascar.container.container.Container

AbstractContainer is a Container class used when the side-channel traces are generated from functions. It can be used for instance:

• setting up sitions with oscilloscope and DUT
• when implementing Simulated traces

generate_trace(idx)

Generates a single trace indexed by an integer i (the i^th trace)

Function to be overloaded

Parameters:idx – integer Returns:a Trace

generate_trace_batch(idx_begin, idx_end)

Generates a trace_batch of specified indexes

class lascar.container.container.AcquisitionFromGetters(number_of_traces, value_getter, leakage_getter, **kargs)

Bases: lascar.container.container.AbstractContainer

An AcquisitionFromGetters is built from 2 object whose role are similar:

• value_getter which delivers values (for instance a class communicating with the dut)
• leakage_getter which delivers leakages (for instance an oscilloscope)

value_getter and leakage_getter must either: - be iterable: each iteration returns the leakage or value OR - implement a .get() method which returns leakage or value

generate_trace(idx)

Generates a single trace indexed by an integer i (the i^th trace)

Function to be overloaded

Parameters:idx – integer Returns:a Trace

class lascar.container.container.Container(**kwargs)

Bases: object

Container class is an abstact class used to represent Side-Channel traces.

In lascar a trace is a couple (tuple) of a side-channel leakage associated to the values handled.

trace = (leakage, value)

Where both leakage and value can be represented as a numpy array.

The role of the Container class is to be overloaded so that it can deliver traces, stored as a specified format. Mostly, the __getitem__/__setitem__ have to be overloaded when user want to write its own Container format class.

Parameters:number_of_traces –

apply_both_leakage(leakages)

apply_both_value(values)

apply_leakage_processing(leakages)

apply_leakage_section(leakages)

apply_value_processing(values)

apply_value_section(values)

get_leakage_mean_var()

Compute mean/var of the leakage. :return: mean/var of the container leakages

leakage_processing

Leakage_processing. function applied upon the leakages after reading and leakage_section)

Type:function (or callable) taking leakage[leakage_section] as an argument

leakage_section

Leakage area to be read from the original leakage.

Type:list, range, slice

plot_leakage(key)

value_processing

Current value_processing. function applied upon the values after reading and value_section.

Type:function (or callable) taking value[value_section] as an argument

value_section

Value area to be read from the original value.

Type:list, range, slice

class lascar.container.container.Trace

Bases: lascar.container.container.Trace

Trace is the class to represent a side-channel trace (Trace in lascar), Genuinely, it is a tuple of two items: - The first item is “leakage” and represents the side-channel observable - The second item is “value” and represents the handled values during the observation of “leakage”.

The only restriction here is that “leakage” and “data” must be numpy.arrays of any shape.

trace = (leakage, value) where leakage and value are numpy.arrays

class lascar.container.container.TraceBatchContainer(*args, **kwargs)

Bases: lascar.container.container.Container

static export(container)

get_leakage_mean_var()

Compute mean/var of the leakage. :return: mean/var of the container leakages

static load(filename)

Load a file using np.load and create from it a TraceBatchContainer.

Parameters:filename – Returns:

save(filename)

Save the current TraceBatchContainer to a file using np.save

Parameters:filename – Returns:

filtered_container.py

class lascar.container.filtered_container.FilteredContainer(container, filtering, **kwargs)

Bases: lascar.container.container.AbstractContainer

FilteredContainer is an AbstractContainer, which is built from another container, and will select only traces satisfying a specified condition. (usefull when doing traces synchronisation)

generate_trace(idx)

Return the idx th trace of the container. :param idx: integer :return:

class lascar.container.filtered_container.RandomizedContainer(container, **kwargs)

Bases: lascar.container.filtered_container.FilteredContainer

RandomizedContainer is an AbstractContainer, which is built from another container, and will shuffle the trace order.

lascar.container.filtered_container.split_container(container, random=True, **kwargs)

Parameters:

• container –
• random – boolean to indicate if spliting is done randomly
• kwargs – specify either the number of splits (number_of_splits), or the size of each split (size_of_splits)

Returns:

a list of number_of_splits containers OR a list of containers of size_of_splits each.

multiple_container.py

MultipleContainer concatenate containers already instanciated.

class lascar.container.multiple_container.MultipleContainer(*args, **kwargs)

Bases: lascar.container.container.Container

get_leakage_mean_var()

Compute mean/var of the leakage. :return: mean/var of the container leakages

leakage_processing

Leakage_processing. function applied upon the leakages after reading and leakage_section)

Type:function (or callable) taking leakage[leakage_section] as an argument

leakage_section

Leakage area to be read from the original leakage.

Type:list, range, slice

value_processing

Current value_processing. function applied upon the values after reading and value_section.

Type:function (or callable) taking value[value_section] as an argument

value_section

Value area to be read from the original value.

Type:list, range, slice

hdf5_container.py

class lascar.container.hdf5_container.Hdf5Container(filename, leakages_dataset_name='leakages', values_dataset_name='values', mode='r', **kwargs)

Bases: lascar.container.container.Container

Hdf5Container is a Container based upon hdf5 files (with h5py).

A hdf5 file emulates a file system and can contains two types of objects: - Group = folder - Dataset = multidimensional array of data (which are loaded into np.array thanks to h5py)

A Hdf5Container consists in a hdf5 file which containes at least two datasets; - 1 dataset containing the leakages - 1 dataset containing the values

static export(container, filename, name=None, leakages_dataset_name='leakages', values_dataset_name='values', batch_size=100)

export method is used to export an existing container into an Hdf5Container.

It creates a session and use a ContainerDumpEngine to recopy the traces delivered by the original container.

Parameters:

• container – container to be exported
• filename – name of the Hdf5Container to build
• leakages_dataset_name –
• values_dataset_name –
• batch_size –

Returns:

get_leakage_mean_var()

Compute mean/var of the leakage. :return: mean/var of the container leakages

static void_container(filename, number_of_traces, leakage_shape, leakage_dtype, value_shape, value_dtype, leakages_dataset_name='leakages', values_dataset_name='values', **kwargs)

void_container is a static method for building an empty Hdf5Container with the specified parameters.

Parameters:

• filename – container filename
• number_of_traces –
• leakage_shape – shape of 1 leakage
• leakage_dtype – dtype of leakage
• value_shape – shape of 1 value
• value_dtype – dtype of value
• leakages_dataset_name –
• values_dataset_name –

Returns:

an empty Hdf5Container

class lascar.container.npy_container.NpyContainer(leakages_filename, values_filename, **kwargs)

Bases: lascar.container.container.Container

NpyContainer is a Container based upon .npy file format.

Two .npy files (one for the leakages, one for the values) are used by lascar using memmap (all data are not loaded in memory, contrary to np.load)

static export(container, leakages_filename, values_filename, name=None, batch_size=100)

export method is used to export an existing container into an NpyContainer.

It creates a session and use a ContainerDumpEngine to recopy the traces delivered by the original container into a NpyContainer.

Parameters:

• container – container to be exported
• leakages_filename – name of the npy file to create corresponding to the leakages
• values_filename – name of the npy file to create corresponding to the values
• name – name for the session
• batch_size – batch_size for the session

Returns:

get_leakage_mean_var()

Compute mean/var of the leakage. :return: mean/var of the container leakages

simulation_container.py

class lascar.container.simulation_container.AesSimulationContainer(number_of_traces, noise=1, key=[0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15], seed=1337, leakage_model='default', additional_time_samples=10, **kwargs)

Bases: lascar.container.container.AbstractContainer

AesSimulationContainer is an AbstractContainer used to simulate traces during all the round function of an AES.

generate_trace(idx)

Generates a single trace indexed by an integer i (the i^th trace)

Function to be overloaded

Parameters:idx – integer Returns:a Trace

class lascar.container.simulation_container.BasicAesSimulationContainer(number_of_traces, noise=1, key=[0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15], seed=1337, leakage_model='default', additional_time_samples=10, **kwargs)

Bases: lascar.container.container.AbstractContainer

BascAesSimulationContainer is an AbstractContainer used to naively simulate traces during the first Subbyte of the first round of an AES.

generate_trace(idx)

Generates a single trace indexed by an integer i (the i^th trace)

Function to be overloaded

Parameters:idx – integer Returns:a Trace