Installation

This guide provides detailed instructions for installing the Open Cryptanalysis Platform (OCP), ensuring that you can get up and running with all necessary dependencies and libraries.

Prerequisites

Before installing OCP, ensure that you have the following dependencies installed:

• Python 3.8
• pip (Python package manager, used to install Python libraries)
• Git (to clone the repository)

Step 1: Clone the Repository

Clone the OCP repository to get the latest version:

git clone https://github.com/Open-CP/OCP.git
cd OCP

Step 2: Install Required Libraries

OCP depends on several Python libraries for its operations. Ensure you have the following dependencies installed:

1. NumPy

NumPy is crucial for scientific computing, providing support for large, multi-dimensional arrays and matrices.

Installation Command:

# Test version: numpy=1.21.0
pip install numpy # install numpy using pip

conda install -c conda-forge numpy # install numpy using conda

Test to Verify Installation: After installing NumPy, open your Python interpreter and run the following Python code to test:

import numpy as np
print(np.array([1, 2, 3, 4]))

For more details, see NumPy website.

2. PyEDA

PyEDA is a library dedicated to electronic design automation (EDA) built for Python. It is used to model S-box with espresso_tts in our tool.

Installation Command:

# Test version: pyeda=0.20.8
pip3 install pyeda # install pyeda using pip

conda install -c conda-forge pyeda # install pyeda using conda

Test to Verify Installation: After installing pyeda, open your Python interpreter and run the following Python code to test:

from pyeda.inter import *
expr1 = expr('a & b')
print(expr1.simplify()) # And(a, b)

For more details, see PyEDA documentation.

3. MILP Solvers for solving MILP models

(1) Gurobi

Installation Command:

# Test version: gurobi=11.0.3
conda install -c gurobi gurobi # install gurobi using conda for python only
grbgetkey xxx (your license) # activate Gurobi license

Test to Verify Installation: After installing Gurobi, open your Python interpreter and run the following Python code to test:

from gurobipy import Model
m = Model()
x = m.addVar(name="x")
m.update()
print("Variable x created.")

For Gurobi license and more details, see Gurobi installation page.

(2) SCIP

Installation Commands:

# Test version: scip=8.0.3, pyscipopt=4.3.0
conda install -c conda-forge scip=8.0.3 pyscipopt # install scip and Python interface using conda

Test to Verify Installation: After installing SCIP, open your Python interpreter and run the following Python code to test:

from pyscipopt import Model
model = Model()
x = model.addVar("x")
model.setObjective(x, "maximize")
model.optimize()
print("Model status:", model.getStatus())

For more details, see SCIP installation page.

(3) Or-tools

OR-Tools is an open-source optimization toolkit developed by Google.

Installation Commands:

# Test vector: 9.12.4544
pip install ortools # install ortools using pip

Test to Verify Installation: After installing OR-Tools, open your Python interpreter and run the following Python code to test:

from ortools.linear_solver import pywraplp
solver = pywraplp.Solver.CreateSolver("SCIP")
x = solver.NumVar(0, 10, "x")
y = solver.NumVar(0, 10, "y")
solver.Add(x + y <= 12)
solver.Maximize(3 * x + 4 * y)
status = solver.Solve()
print("Model status:", status)
print("x =", x.solution_value())
print("y =", y.solution_value())

For more details, see OR-Tools installation page.

4. SAT Solvers for solving SAT models

(1) Python-SAT

Python-SAT provides a unified interface to a number of state-of-art Boolean Satisfiability (SAT) solvers, including Cadical103, Cadical153, Cadical195, CryptoMinisat, Gluecard3, Gluecard4, Glucose3, Glucose4, Lingeling, MapleChrono, MapleCM, Maplesat, Mergesat3, Minicard, Minisat22, and MinisatGH.

Installation Command:

# Test version:  python-sat=1.8.dev16, pycryptosat==5.11.21
pip install python-sat # install python-sat using pip
pip install pycryptosat==5.11.21 # install pycryptosat for using CryptoMiniSat solver

Test to Verify Installation: After installing Python-SAT, open your Python interpreter and run the following Python code to test:

from pysat.solvers import Solver
from pysat.formula import CNF
cnf = CNF()
cnf.append([1, -2])
solver = Solver()
solver.append_formula(cnf.clauses)
result = solver.solve()
print("SAT Solver result:", result)

For more details, see Python-SAT GitHub page.

5. Matplotlib

Matplotlib is a comprehensive library for creating static, animated, and interactive visualizations in Python, used to generate figures in OCP.

Installation Command:

# Test version: 3.7.1
pip install matplotlib # install matplotlib using pip

conda install -c conda-forge matplotlib # install matplotlib using conda

Test to Verify Installation: After installing Matplotlib, open your Python interpreter and run the following Python code to test:

import matplotlib.pyplot as plt

plt.plot([1, 2, 3, 4], [1, 4, 9, 16])  # Plot some data on the axes.
plt.ylabel('Example Numbers')
plt.xlabel('Index')
plt.title('Simple Line Plot')
plt.show()  # Display the figure.

Notes

• Ensure your Python environment is set up and activated before running these commands.
• Using a virtual environment (recommended) helps in isolating and managing dependencies effectively.