Metadata-Version: 2.5
Name: qace
Version: 1.0.1
Summary: Quantum-Assisted Cryptanalytic Exploration SDK
Author: Fraunhofer AISEC
License-Expression: Apache-2.0
License-File: LICENSE
License-File: NOTICE
License-File: third_party_licenses/EditorConfig-0.17.1.LICENSE.txt
License-File: third_party_licenses/INDEX.md
License-File: third_party_licenses/Jinja2-3.1.6.LICENSE.txt
License-File: third_party_licenses/Markdown-3.10.2.LICENSE.txt
License-File: third_party_licenses/MarkupSafe-3.0.3.LICENSE.txt
License-File: third_party_licenses/PyJWT-2.13.0.LICENSE.txt
License-File: third_party_licenses/PyYAML-6.0.3.LICENSE.txt
License-File: third_party_licenses/Pygments-2.20.0.LICENSE.txt
License-File: third_party_licenses/annotated-types-0.7.0.LICENSE.txt
License-File: third_party_licenses/annotated-types-0.8.0.LICENSE.txt
License-File: third_party_licenses/antlr4-python3-runtime-4.13.2.LICENSE.txt
License-File: third_party_licenses/beartype-0.22.9.LICENSE.txt
License-File: third_party_licenses/beautifulsoup4-4.15.0.LICENSE.txt
License-File: third_party_licenses/bitarray-3.9.1.LICENSE.txt
License-File: third_party_licenses/black-26.5.1.LICENSE.txt
License-File: third_party_licenses/bracex-3.0.1.LICENSE.txt
License-File: third_party_licenses/certifi-2026.6.17.LICENSE.txt
License-File: third_party_licenses/certifi-2026.7.22.LICENSE.txt
License-File: third_party_licenses/cffi-2.1.0.LICENSE.txt
License-File: third_party_licenses/cfgv-3.5.0.LICENSE.txt
License-File: third_party_licenses/charset-normalizer-3.4.9.LICENSE.txt
License-File: third_party_licenses/click-8.4.2.LICENSE.txt
License-File: third_party_licenses/cryptography-49.0.0.LICENSE.txt
License-File: third_party_licenses/dill-0.4.1.LICENSE.txt
License-File: third_party_licenses/distlib-0.4.3.LICENSE.txt
License-File: third_party_licenses/filelock-3.32.0.LICENSE.txt
License-File: third_party_licenses/ghp-import-2.1.0.LICENSE.txt
License-File: third_party_licenses/griffelib-2.1.0.LICENSE.txt
License-File: third_party_licenses/ibm-cloud-sdk-core-3.26.0.LICENSE.txt
License-File: third_party_licenses/ibm-platform-services-0.76.0.LICENSE.txt
License-File: third_party_licenses/ibm-platform-services-0.77.0.LICENSE.txt
License-File: third_party_licenses/ibm-quantum-schemas-0.10.20260723.LICENSE.txt
License-File: third_party_licenses/ibm-quantum-schemas-0.9.20260612.LICENSE.txt
License-File: third_party_licenses/identify-2.6.19.LICENSE.txt
License-File: third_party_licenses/idna-3.18.LICENSE.txt
License-File: third_party_licenses/iniconfig-2.3.0.LICENSE.txt
License-File: third_party_licenses/jsbeautifier-2.0.3.LICENSE.txt
License-File: third_party_licenses/llvmlite-0.44.0.LICENSE.txt
License-File: third_party_licenses/mergedeep-1.3.4.LICENSE.txt
License-File: third_party_licenses/mkdocs-1.6.1.LICENSE.txt
License-File: third_party_licenses/mkdocs-autorefs-1.4.4.LICENSE.txt
License-File: third_party_licenses/mkdocs-get-deps-0.2.2.LICENSE.txt
License-File: third_party_licenses/mkdocs-glightbox-0.5.2.LICENSE.txt
License-File: third_party_licenses/mkdocs-include-markdown-plugin-7.3.0.LICENSE.txt
License-File: third_party_licenses/mkdocs-mermaid2-plugin-1.2.3.LICENSE.txt
License-File: third_party_licenses/mkdocstrings-1.0.6.LICENSE.txt
License-File: third_party_licenses/mkdocstrings-python-2.0.5.LICENSE.txt
License-File: third_party_licenses/mypy_extensions-1.1.0.LICENSE.txt
License-File: third_party_licenses/nodeenv-1.10.0.LICENSE.txt
License-File: third_party_licenses/numba-0.61.2.LICENSE.txt
License-File: third_party_licenses/numpy-2.2.6.LICENSE.txt
License-File: third_party_licenses/openqasm3-1.0.1.LICENSE.txt
License-File: third_party_licenses/orjson-3.11.9.LICENSE.txt
License-File: third_party_licenses/packaging-26.2.LICENSE.txt
License-File: third_party_licenses/pathspec-1.1.1.LICENSE.txt
License-File: third_party_licenses/platformdirs-4.10.1.LICENSE.txt
License-File: third_party_licenses/platformdirs-4.11.0.LICENSE.txt
License-File: third_party_licenses/pluggy-1.6.0.LICENSE.txt
License-File: third_party_licenses/pre_commit-4.6.1.LICENSE.txt
License-File: third_party_licenses/psutil-7.2.2.LICENSE.txt
License-File: third_party_licenses/pybase64-1.4.3.LICENSE.txt
License-File: third_party_licenses/pycparser-3.0.LICENSE.txt
License-File: third_party_licenses/pydantic-2.13.4.LICENSE.txt
License-File: third_party_licenses/pydantic_core-2.46.4.LICENSE.txt
License-File: third_party_licenses/pymdown-extensions-11.0.1.LICENSE.txt
License-File: third_party_licenses/pyspnego-0.12.1.LICENSE.txt
License-File: third_party_licenses/pytest-9.1.1.LICENSE.txt
License-File: third_party_licenses/python-dateutil-2.9.0.post0.LICENSE.txt
License-File: third_party_licenses/python-discovery-1.5.0.LICENSE.txt
License-File: third_party_licenses/pytokens-0.4.1.LICENSE.txt
License-File: third_party_licenses/pyyaml_env_tag-1.1.LICENSE.txt
License-File: third_party_licenses/qiskit-2.5.0.LICENSE.txt
License-File: third_party_licenses/qiskit-2.5.1.LICENSE.txt
License-File: third_party_licenses/qiskit-aer-0.17.2.LICENSE.txt
License-File: third_party_licenses/qiskit-ibm-runtime-0.47.0.LICENSE.txt
License-File: third_party_licenses/qiskit-qasm3-import-0.6.0.LICENSE.txt
License-File: third_party_licenses/requests-2.34.2.LICENSE.txt
License-File: third_party_licenses/requests-2.34.2.NOTICE.txt
License-File: third_party_licenses/requests_ntlm-1.3.0.LICENSE.txt
License-File: third_party_licenses/rustworkx-0.18.0.LICENSE.txt
License-File: third_party_licenses/samplomatic-0.20.0.LICENSE.txt
License-File: third_party_licenses/scipy-1.18.0.LICENSE.txt
License-File: third_party_licenses/selectolax-0.4.11.LICENSE.txt
License-File: third_party_licenses/six-1.17.0.LICENSE.txt
License-File: third_party_licenses/soupsieve-2.9.1.LICENSE.txt
License-File: third_party_licenses/soupsieve-2.9.LICENSE.txt
License-File: third_party_licenses/stevedore-5.9.0.LICENSE.txt
License-File: third_party_licenses/typing-inspection-0.4.2.LICENSE.txt
License-File: third_party_licenses/typing_extensions-4.16.0.LICENSE.txt
License-File: third_party_licenses/urllib3-2.7.0.LICENSE.txt
License-File: third_party_licenses/virtualenv-21.7.0.LICENSE.txt
License-File: third_party_licenses/watchdog-6.0.0.LICENSE.txt
License-File: third_party_licenses/wcmatch-11.0.LICENSE.txt
Requires-Python: >=3.12
Requires-Dist: beartype<0.23,>=0.22
Requires-Dist: bitarray<4,>=3.6
Requires-Dist: numba<0.62,>=0.61
Requires-Dist: qiskit-aer<0.18,>=0.17
Requires-Dist: qiskit-ibm-runtime<0.48,>=0.47
Requires-Dist: qiskit<3,>=2.5
Requires-Dist: scipy<2,>=1.16
Provides-Extra: docs
Requires-Dist: mkdocs-autorefs<2,>=1.4; extra == 'docs'
Requires-Dist: mkdocs-glightbox<0.6,>=0.5; extra == 'docs'
Requires-Dist: mkdocs-include-markdown-plugin<8,>=7.3; extra == 'docs'
Requires-Dist: mkdocs-mermaid2-plugin<2,>=1.2; extra == 'docs'
Requires-Dist: mkdocs<2,>=1.6; extra == 'docs'
Requires-Dist: mkdocstrings-python<3,>=2; extra == 'docs'
Requires-Dist: mkdocstrings<2,>=1; extra == 'docs'
Provides-Extra: test
Requires-Dist: black>=26.0.0; extra == 'test'
Requires-Dist: pre-commit>=4.0.0; extra == 'test'
Requires-Dist: pytest<10,>=9; extra == 'test'
Description-Content-Type: text/markdown

<!--
Copyright 2026 Fraunhofer AISEC

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
# QACE

**Quantum-Assisted Cryptanalytic Exploration** is a toolkit for investigating cryptanalytic problems using quantum
computing capabilities.

The SDK provides a framework for analyzing classical ciphers, S-boxes, and Boolean functions using quantum algorithms.
It integrates three components into a coherent workflow: a model of the analysis target, a corresponding quantum
algorithm, and the execution of the resulting circuit on a backend. Because these three layers are clearly separated,
each component can be exchanged independently, ranging from a local simulator to physical IBM Quantum hardware, without
modifying the algorithm itself.

For more information, see the [documentation](https://fraunhofer-aisec.github.io/qace-sdk/).

## The Three Layers

The SDK is designed as a framework. Each layer defines an abstract interface and a set of base classes; the components
listed below are reference implementations illustrating how the respective abstractions can be realized. Users are
expected to extend these layers with their own implementations.

- **VBF Layer.** Defines an abstract representation of vectorial Boolean functions, which serve as the cryptanalytic
  targets under investigation. Any function that conforms to this interface can be analyzed. The provided
  implementations, including S-boxes, XOR ciphers, lookup tables, and both random and deliberately biased functions, are
  examples of such targets.
- **Algorithm Layer.** Defines an abstract quantum algorithm that operates on a target and produces a structured result.
  It establishes the common contract shared by all algorithms. The provided implementations, such as Correlation
  Extraction, Amplitude Amplification, Preimage search, and SITH, are examples that build on this abstraction.
- **Execution Layer.** Defines an abstract interface for executing quantum circuits, decoupling algorithms from any
  particular backend. The provided implementations, including the Aer simulator, the IBM Quantum Runtime, and an
  iterative executor, are examples of concrete backends.

Each algorithm constructs its circuit and delegates execution to an injected `CircuitExecutor`. This design keeps the
algorithm logic fully decoupled from the backend and allows every layer to be exchanged or extended independently.

## Architecture
```mermaid
graph TB
    subgraph "Problem"
        PF["Vectorial Boolean Function"]
    end

    subgraph "Algorithm"
        A["Quantum Algorithm"]
    end

    subgraph "Execution"
        E["Executor"]
    end

    PF -.->|"Oracle"| A
    E -.->|"injected"| A
    A -->|"Result"| R["AlgorithmResult"]
    E -->|"Result"| ER["ExecResult"]
```

## Installation

```bash
git clone https://github.com/Fraunhofer-AISEC/qace-sdk.git
cd qace-sdk
python -m venv .venv
source .venv/bin/activate
make install
```

Requires Python ≥ 3.12.

## Usage Example

```python
from qace.vbf import rijndael_s_box
from qace.algorithm import CorrelationExtraction
from qace.execution import AerExecutor

executor = AerExecutor.default()
cea = CorrelationExtraction(executor=executor, vbf=rijndael_s_box)
result = cea.run()

print(result.mask_pairs)
```

## Running Tests

Tests use [pytest](https://docs.pytest.org/):

```bash
make test              # install (with test extras) and run all tests
```

or

```bash
make install
pytest tests/execution/  # run a specific module
```

## Documentation

The docs are built with [MkDocs](https://www.mkdocs.org/):

```bash
make docs-serve   # live-reload server at http://127.0.0.1:8000
make docs-build   # static HTML in site/
```

Documentation dependencies are declared under the `docs` extra in `pyproject.toml`
(`pip install -e ".[docs]"`).

## Status

| Layer | State |
|---|---|
| Execution | implemented & tested |
| Algorithm | implemented & tested |
| VBF | implemented & tested |

The API is still evolving and may change before the first stable release.

## License

Apache-2.0 — see the [LICENSE](https://github.com/Fraunhofer-AISEC/qace-sdk/blob/main/LICENSE) file, or contact the authors for details.

## Contact
For questions or feedback:
- qace-sdk@aisec.fraunhofer.de

For bugs and feature requests:
- Please create an issue in the repository

## Acknowledgements

 We thank the Bavarian Ministry of Economic Affairs, Regional Development and Energy,
 with funds from the Hightech Agenda Bayern, for funding the theoretical work (SITH-Algorithm) as part of the
 BayQS project. Furthermore, we thank the Munich Quantum Valley,  which is supported by the
 Bavarian state government, with funds from the Hightech Agenda
 Bayern Plus, for funding the implementation of the QACE-SDK as part of the QACI project.