Package: escapydl
eSCAPyDL: SCA PyTorch Deep Learning frameworkThis framework is a framework for deep learning in the context of side-channel analysis. It is based on PyTorch and provides a set of tools to train and evaluate deep learning models for side-channel analysis.The framework is made with customization in mind. You can easily add your own dataset, model, loss function, metrics, etc. and use them with the framework.InstallationPre-requisites:sudo apt install gir1.2-gtksource-5Install the package from PyPI:pip install escapydlBuild from sourceInstall the packages necessary for GTK and the compilation of python packages.
Ubuntu:sudo apt install gir1.2-gtksource-5 libgtk-4-1 libgtk-4-dev libgirepository1.0-dev libcairo2-devgit clone
(python -m venv escapydl)
python -m build
pip install dist/escapydl-*.tar.gzBuild FlatpakDownload Python package to convert a requirement file to a list of sources to build the Flatpak.pip install req2flatpak
req2flatpak--requirement-file requirements.txt --target-platforms 310-x86_64If you get SSL: CERTIFICATE_VERIFY_FAILED error, try the following (ugly and dirty) modifications to the package and re-run the previous command:REQ2FLATPAK=$(python -c "import site; print(site.getsitepackages()[0])")/req2flatpak.py
sed 's/import urllib.request/import requests/' $REQ2FLAPTAK > tmp.py
sed 's/urllib.request.urlopen(url)/requests.get(url,verify=False)' tmp.py > $REQ2FLATPAK
sed 's/json_string\ =\ response.read().decode("utf-8")/json_string\ =\ response.text/' $REQ2FLATPAK > tmp.py
mv tmp.py $REQ2FLATPAKCopy the output to the .yml file and adapt as in the example.Build docsThe documentation is built using Sphinx. To build the documentation, you need to install the dependencies:pip install -r docs/requirements.txtThen, you can build the documentation:cd docs
make htmlStructureescapydl/               # Main package
├── datasets/           # Datasets, each dataset is defined in a separate file
├── helpers/            # Helper functions, useful to define cipher specific functions
├── ressources/         # Ressources for the GUI
├── Callback.py         # Callbacks for the training (e.g., guessing entropy, model checkpoint, etc.)
├── Dataset.py          # Dataset class, used to load the data
├── Models.py           # Models, all models available are defined in this file
├── Optuna_models.py    # Models for Optuna optimization
├── Utils.py            # Utility functions
├── train.py            # Script to train a model, is independent of model and dataset
├── optimize.py         # Script to optimize a model with Optuna, used to find the best hyperparameters for a given model and dataset
├── main.py             # Main script, forks to train.py, optimize.py or gui.py
├── gui.py              # Script to run the GUI
└── README.md           # This fileDataset exampleimporthelpers.aes_helperasaes# Dataset specific parametersparameters={"training_size":1000,# Number of traces used for training"val_size":100,# Number of traces used for validation...}# Hyperparameters of the best known model (if it exists)model={"n_layers":2,# Number of layers...# Other hyperparameters}# Define the three functions used to compute the intermediate values associated to the traces# The first function returns the trace parameters (here, plaintext, key and subkey) for a given trace indexdefget_attack_parameters(traceset,subkey,index):return{"plaintext":traceset.plaintext[index],"key":traceset.key[index],"subkey":subkey}# The second function returns the real key stored in the traceset for a given trace indexdefget_known_key(traceset,subkey,index):returntraceset['key'][index][subkey]# The third function returns the intermediate value for a given key guess and trace parametersdefintermediate_value(keyguess,trace_parameters):returnaes.sbox[keyguess^trace_parameters['plaintext'][trace_parameters['subkey']]]Model exampleclassMLP(nn.Module):default_Hparams={"activation_function":'tanh',"lr":1e-3,"n_layers":2,"n_units_l0":20,"n_units_l1":10}# Default hyperparametersdef__init__(self,trace_length,num_classes,Hparams={}):super(MLP,self).__init__()self.name="MLP"self.Hparams={**MLP.default_Hparams,**Hparams}# Merge default and given Hparamsself.n_layers=int(self.Hparams['n_layers'])# Define the number of layersself.act={"relu":nn.ReLU(),"tanh":nn.Tanh(),"selu":nn.SELU()}[self.Hparams['activation_function'].lower()]if'activation_function'inself.Hparams.keys()elsenn.ReLU()# Define the activation function# Create the PyTorch layers of the modelself.hidden=nn.ModuleList()self.hidden.append(nn.Linear(trace_length,int(self.Hparams['n_units_l0'])))foriinrange(self.n_layers-1):self.hidden.append(nn.Linear(int(self.Hparams['n_units_l{}'.format(i)]),int(self.Hparams['n_units_l{}'.format(i+1)])))self.fc1=nn.Linear(int(self.Hparams['n_units_l{}'.format(self.n_layers-1)]),num_classes)self.dropout=nn.Dropout(0.1)self.bnorm=nn.BatchNorm1d(trace_length)self.flatten=nn.Flatten()defforward(self,x):# Define the forward passx=self.flatten(x)x=self.bnorm(x)foriinrange(self.n_layers):x=self.act(self.hidden[i](x))x=self.dropout(x)x=self.fc1(x)returnxdeffit(self,*args,**kwargs):# Update the default hyperparameters and the ones passed to the model.fit function and redirect to the global fit functionif"Hparams"inkwargs.keys():kwargs["Hparams"]={**kwargs["Hparams"],**self.Hparams}else:kwargs["Hparams"]=self.Hparamsreturnfit(self,*args,**kwargs)Runescapydl -d <dataset> -m <model> -t<dataset>: dpav42, ascad_fixed, ascad_random or aesrd<model>: cnn or mlporescapydl -gTo run the GUI