Generalizations of ChiChi

This repository contains SageMath notebooks to regenerate and verify the results for the computational searches in [1], as well as the code used for the tool-assisted proof of the degree of the components of the inverse of the family ${\chi\chi}_{(m,m')}^{(b,\hat{b})}$.

Additionally, we provide a MAGMA script to classify a list of vectorial Boolean functions up to Affine Equivalence.

Finally, the directory results contains all datasets generated in the search for variations of chichi.

File Structure

chichi_generalizations/
├── README.md
├── LICENSE
├── chichi_lib/                       # Source code for families and their cryptographic proeprties
├── results/                          # Datasets of raw and classified chichi generalizations
├── bruteforce.ipynb                  # Bruteforce to identify generalised chi that are permutations
├── families_crypto_properties.ipynb  # Analysis of the crypto properties for the swap and 4-cycle families
├── invariant_classification.ipynb    # Partial classification of functions using invariants
├── tool_assisted_degrees.ipynb       # Tool assisted proof of the degres of the components for the 4-cycle family

├── AffineEquivalence.m               # Affine equivalence testing using code equivalence

The example notebooks use parameters that allow for the computations to terminate in a reasonable time even with limited resources. In particular, all notebooks should terminate whithin seconds or minutes, except for the families cryptographic proterties, that can take up to a few hours. If you wish to modify the parameters, we recommend to use total dimensions for bruteforce and invariant classifications up to 8, and total dimensions for the families up to 12.

Dependencies

The following are the dependencies for the chichi_lib and the python notebooks

Python 3.9.9 or newer
SageMath 9.4 or newer
sboxU 1.2 or newer

Moreover, Magma 2.27 or newer is necessary to run the affine equivalence tests.

SageMath Notebooks

All the notebooks in this repository need a Notebook graphical interface for SageMath to run.

You can install SageMath using the installation manual provided on their page.

Once you have installed SageMath, you can follow the instructions to run a Notebook graphical interface on the SageMath documentation.

Most notebooks in this repository also depend on the sboxU library. The only exception being the tool_assisted_degrees.ipynb notebook.

You can install it directly using sage with the following command

sage --pip install git+https://github.com/lpp-crypto/sboxU

For alternative ways of installation we refer to the installation manual on the sboxU Github repository.

Troubleshooting

For Apple devices using the ARM chipset the pip installer can fail for a number of reasons depending on your setup.
We recommend following the alternative instructions in sboxU. In particular, we recommend to clone the repository and build sboxU locally. Then it is sufficient to copy the build directory in the main directory of this project.

Affine Equivalence Classification

The code for classification up to Affine Equivalence needs the MAGMA Computational Algebra System. This is a proprietary software, and we refer to its Download and Installation manuals if you wish to obtain a copy.

For the sake of verifying the correct working of the code provided in this repository, the MAGMA Calculator is sufficient. You can copy-paste the content of the file AffineEquivalence.m in the online calculator to verify it runs correctly.

References

[1] S. Andreoli, G. Leander, E. Piccione, L. Stennes, "Generalizations of ChiChi: Families of Low-Latency Permutations in Any Even Dimension"