Engines

engine.py

class lascar.engine.engine.ContainerDumpEngine(container_void)

Bases: lascar.engine.engine.Engine

ContainerDumpEngine is an engine whose role is to simply dump the traces handled by the Session into a specified container. The container has to be created before.

class lascar.engine.engine.Engine(name)

Bases: object

Engine is an abstract class whose role is to handle TraceBatches from a Session.

Any class inheriting from Engine must implemement at least 3 methods:

• _initialize(): called by the Session once before processing batchs
• _update(batch): called each time the Session has a TraceBatch to process
• _finalize(): used to deliver the result of the Engine
• _clean(): used to clean Engine, ie: erase

clean()

finalize()

get_results()

initialize(session)

intitialize method is called by the Session the engine is registered.

Parameters:session – the Session that will drive it Returns:

update(batch)

Parameters:batch – a TraceBatch Returns:

class lascar.engine.engine.GroupedEngines(name, *engines)

Bases: lascar.engine.engine.Engine

GroupedEngines is an abstact engine whose role regroup engines within one. Useful when performing multiple charac/attacks at the same time.

class lascar.engine.engine.MeanEngine

Bases: lascar.engine.engine.Engine

MeanEngine is an Engine whose role is to compute the mean of the leakage delivered by the Session.

(MeanEngine is by default added to any Session under the name ‘mean’)

class lascar.engine.engine.PearsonCorrelationEngine(name, model)

Bases: lascar.engine.engine.Engine

PearsonCorrelationEngine is an engine whose role is compute the Pearson Correlation coefficient between the observed trace leakages and a model function applied to the trace values

The model function is a function who takes “value” as input and output a scalar. (eg it can compute the hamming weight at the output of a sbox)

class lascar.engine.engine.VarEngine

Bases: lascar.engine.engine.Engine

VarEngine is an Engine whose role is to compute the mean of the leakage delivered by the Session.

(VarEngine is by default added to any Session under the name ‘mean’)

class lascar.engine.chi2test_engine.Chi2TestEngine(name, partition_function, n_bins, bin_range)

Bases: lascar.engine.partitioner_engine.PartitionerEngine

TtestEngine is a PartitionerEngine used to compute Pearson’s chi square test on Side-Channel Traces

(Amir Moradi, Bastian Richter, Tobias Schneider, and François-Xavier Standaert. Leakage detection with the x2-test. IACR Trans. Cryptogr. Hardw. Embed. Syst., 2018(1):209–237, 2018. https://tches.iacr.org/index.php/TCHES/article/view/838/790)

It needs as en input a partition_function that will take trace values as an input and returns 0 or 1 (2 partitions_values).

update(batch)

Parameters:batch – a TraceBatch Returns:

class lascar.engine.classifier_engine.MatchEngine(classifier, selection_function, guess_range, name=None, solution=None)

Bases: lascar.engine.guess_engine.GuessEngine

MatchEngine is a GuessEngine allowing to perform the matching phase of a Profiled Side-Channel Attack.

Compute for each guess, the log_proba accumulated by the classifier along traces.

see examples/attacks/classifier.py for an example.

class lascar.engine.classifier_engine.ProfileEngine(classifier, partition_function, partition_range, epochs=10, test_size=0.1, verbose=1, batch_size=128, name=None)

Bases: lascar.engine.partitioner_engine.PartitionerEngine

ProfileEngine is a PartitionerEngine used to mount Profiled Side-Channel Attacks.

A classifier has to be instanciated first, and will be updated by traces batches, and a partition function to separate them. The classifier can be either a sklearn classifier or a keras model (neural network).

After the partition is done, the finalize() method output the classifier updated. It can hence be used by MatchEngine.

see examples/attacks/classifier.py for an example.

lascar.engine.classifier_engine.load_classifier(filename)

lascar.engine.classifier_engine.save_classifier(classifier, filename)

cpa_engine.py

class lascar.engine.cpa_engine.CpaEngine(selection_function, guess_range, name=None, solution=None, jit=True)

Bases: lascar.engine.guess_engine.GuessEngine

CpaEngine is a GuessEngine used to perform Correlation Power Analysis.

(E. Brier, C. Clavier, and F. Olivier. Correlation Power Analysis with a Leakage Model. In M. Joye and J.-J. Quisquater, editors, Cryptographic Hardware and Embedded Systems – CHES 2004, volume 3156 of Lecture Notes in Computer Science, pages 16–29. Springer, 2004.)

Given a selection_function on the values under a guess guess (emulating a leakage model), Cpa engines computes, for each guess guess, the Pearson’s correlation between the output of the selection_function and the corresponding leakages.

class lascar.engine.cpa_engine.CpaPartitionedEngine(partition_function, partition_range, selection_function, guess_range, name=None, solution=None)

Bases: lascar.engine.partitioner_engine.PartitionerEngine, lascar.engine.guess_engine.GuessEngine

CpaPartitionedEngine is an optimization of CpaEngine, that can be used when the cardinal of the domain of the selection_function is low.

In such a case, this engine first partitions the leakages according to a partitioning_function

on this ‘small’ domain. Then one (or several) leakage_model can be applied on this partitioning.

When dealing with appropriate data (enought number of traces, partition appropriated), the complexity of this engine is much lower than a classical CpaEngine, since the model is computed once one each partition_range values, instead of on all the traces values.

Victor Lomn´e, Emmanuel Prouff, and Thomas Roche. Behind the Scene of Side Channel Attacks. In Kazue Sako and Palash Sarkar, editors, ASIACRYPT (1), volume 8269 of Lecture Notes in Computer Science, pages 506–525. Springer, 2013.

class lascar.engine.dom_engine.DomEngine(partition_function, name=None)

Bases: lascar.engine.partitioner_engine.PartitionerEngine

TtestEngine is a PartitionerEngine used to compute Welch’s T-test on Side-Channel Traces

(Gilbert Goodwill, Benjamin Jun, Josh Jaffe, and Pankaj Rohatgi. A testing methodology for side channel resistance validation. NIST noninvasive attack testing workshop, 2011. http://csrc.nist.gov/news_events/ non-invasive-attack-testing-workshop/papers/08_Goodwill.pdf.)

It needs as en input a partition_function that will take trace values as an input and returns 0 or 1 (2 partitions_values).

dpa_lsb_engine.py

class lascar.engine.dpa_engine.DpaEngine(selection_function, guess_range, name=None, solution=None)

Bases: lascar.engine.guess_engine.GuessEngine

DpaEngine is a GuessEngine used to perform Differential Power Analysis.

(P. Kocher, J. Jaffe, and B. Jun. Differential Power Analysis. In M. Wiener, editor, Advances in Cryptology – CRYPTO ’99, volume 1666 of Lecture Notes in Computer Science, pages 388–397. Springer, 1999.)

Given a selection_function under a guess guess, DpaEngine separates leakages into two sets, and output, for each guess guess, the difference betwenn the means of those two sets.

guess_engine.py

class lascar.engine.guess_engine.GuessEngine(selection_function, guess_range, name=None, solution=None, jit=True)

Bases: lascar.engine.engine.Engine

GuessEngine is a specialized Engine which is used when dealing with Side-Channel Analysis

involving a guess guess (such as Dpa, Cpa, Mia, Template matching, …).

It requires a selection_function taking as an input the trace value and a guess guess which lives in guess_range.

In the case where the solution is known, it can be passed as an argument.

lra_engine.py

class lascar.engine.lra_engine.LraEngine(name, partition_function, partition_range, selection_function, guess_range, solution=None, regression_order=1, size_target_value=8)

Bases: lascar.engine.partitioner_engine.PartitionerEngine, lascar.engine.guess_engine.GuessEngine

LraEngine is a GuessEngine used to perform Linear Regression Analysis. It is implemented as a PartitionerEngine to allow for improvements as described in (M. Ouladj, S. Guilley, E. Prouff, On the Implementation Efficiency of Linear Regression-Based Side-Channel Attacks)

Given a selection_function on the values under a guess guess (emulating a leakage model), LraEngine computes, for each guess guess, the goodness of fit, based on the coefficient of determination, between the output of the selection_function and the corresponding leakages.

lascar.engine.lra_engine.get_bit_coefficients(value, order)

nicv_engine.py

class lascar.engine.nicv_engine.NicvEngine(partition_function, partition_range, name=None, jit=True)

Bases: lascar.engine.partitioner_engine.PartitionerEngine

NicvEngine is a PartitionerEngine used to compute the Normalized-Inter-Class-Variance on Side-Channel Traces.

(S. Bhasin, J.-L. Danger, S. Guilley, Z. Najm, ” NICV: Normalized Inter-Class Variance for Detection of Side-Channel Leakage”, Cryptology ePrint Archive Report 2013/717, 2013.)

It needs a partition_function that will take trace values as an input and returns output within partition_range.

partitioner_engine.py

class lascar.engine.partitioner_engine.PartitionerEngine(partition_function, partition_range, order, name=None, jit=True)

Bases: lascar.engine.engine.Engine

PartitionEngine is an abstract splecialized Engine which role is to partition the ‘leakages’, according to a ‘partition_value’ computed from the ‘values’.

The partition_value is computed by a fonction called ‘partition’, which ouputs are in partition_range.

partition_value = partition(value) 0 <= partition_value < partition_size

get_mean_by_partition()

Compute a np.array containing the means by partiion

E[ leakage | partition(value) = i) for i in partiton_values

Returns:np.array containing the means by partition.

snr_engine.py

class lascar.engine.snr_engine.SnrEngine(partition_function, partition_range, name=None, jit=True)

Bases: lascar.engine.partitioner_engine.PartitionerEngine

SnrEngine is a PartitionerEngine used to compute the Signal-to-Noise-Ratio on Side-Channel Traces.

(Stefan Mangard, Elisabeth Oswald, and Thomas Popp. Power analysis attacks - revealing the guesses of smart cards. Springer, 2007.)

It needs a partition_function that will take trace values as an input and returns output within partition_range.

class lascar.engine.ttest_engine.TTestEngine(partition_function, analysis_order=1, name=None)

Bases: lascar.engine.partitioner_engine.PartitionerEngine

TtestEngine is a PartitionerEngine used to compute Welch’s T-test on Side-Channel Traces

(Gilbert Goodwill, Benjamin Jun, Josh Jaffe, and Pankaj Rohatgi. A testing methodology for side channel resistance validation. NIST noninvasive attack testing workshop, 2011. http://csrc.nist.gov/news_events/ non-invasive-attack-testing-workshop/papers/08_Goodwill.pdf.)

It needs as input a partition_function that will take trace values as an input and returns 0 or 1 (2 partitions_values).

update(batch)

One-pass update formulas from:

Formulas for Robust, One-Pass Parallel Computation of Covariances and Arbitrary-Order Statistical Moments, P. Pébay, 2008 (https://www.osti.gov/servlets/purl/1028931)

lascar.engine.ttest_engine.compute_ttest(*containers, batch_size=100)

Compute Welch’s TTest from distinct containers: no need of partitioning function, since each container contain only one of each criterion

Parameters:*containers – Returns: