DOCSEARCHbyAlgolia
Submit Docs

liboqs-python

repository·main·Indexed 42 days ago

https://github.com/open-quantum-safe/liboqs-python

Python 3 bindings for the liboqs C library, providing post-quantum public key cryptography algorithms including Key Encapsulation Mechanisms (KEMs) and Signatures. Version 0.16.1-dev provides the KeyEncapsulation, Signature, and StatefulSignature classes to enable quantum-resistant cryptography within Python applications.

Tokens
1.6K
Snippets
9
Records
10
Agent score
4%

What's inside liboqs-python

  1. Let liboqs-python install liboqs automatically

    main

    If liboqs is not detected at runtime, liboqs-python will automatically download, configure, and install it as a shared library. This happens only once upon the first import oqs.

    You can control which version of liboqs is installed by setting the PYOQS_VERSION environment variable.

    export PYOQS_VERSION=0.16.0   # install a specific liboqs release
export PYOQS_VERSION=latest   # install liboqs from main (HEAD)

  2. Use liboqs-python with Docker

    main

    A Dockerfile is provided for containerized usage.

    Build the image:

    docker build -t oqs-python .

    Run examples:

    docker run -it oqs-python sh -c ". venv/bin/activate && python liboqs-python/examples/kem.py"

    Run tests:

    docker run -it oqs-python sh -c ". venv/bin/activate && nose2 --verbose"

    Development environment (mounting current directory):

    docker run --rm -it --workdir=/app -v ${PWD}:/app oqs-python /bin/bash

  5. Manually configure, build, and install liboqs

    main

    If you prefer to manage the underlying liboqs C library manually, follow these steps to build and install it.

    Note: On UNIX-like systems, you may need to prefix the install command with sudo. Adjust --parallel 8 to match your system's CPU cores.

    Windows Requirements: You must add the -DCMAKE_WINDOWS_EXPORT_ALL_SYMBOLS=TRUE flag during the configuration step and ensure oqs.dll is in your system PATH.

    git clone --depth=1 https://github.com/open-quantum-safe/liboqs
cmake -S liboqs -B liboqs/build -DBUILD_SHARED_LIBS=ON
cmake --build liboqs/build --parallel 8
cmake --build liboqs/build --target install

  6. Install liboqs-python via PyPI

    main

    The simplest way to install the wrapper is via pip. Note that the PyPI package contains only the Python wrapper and does not bundle a compiled copy of liboqs.

    On the first import oqs, the library will attempt to use a system-wide liboqs. If not found, it will automatically download, build, and install a matching liboqs release. This automatic process requires git, CMake, and a C compiler to be present on your system.

    pip install liboqs-python

  7. Run liboqs-python examples and tests

    main

    Once installed, you can run the provided examples to verify functionality or run the unit tests using nose2.

    # Run examples
python3 examples/kem.py
python3 examples/sig.py
python3 examples/stfl_sig.py
python3 examples/rand.py

# Run unit tests
nose2 --verbose

  8. Configure liboqs installation path

    main

    You can specify a custom installation directory for liboqs using the -DCMAKE_INSTALL_PREFIX flag during the CMake configuration step, or by setting the OQS_INSTALL_PATH environment variable.

    # Using CMake flag
cmake -S liboqs -B liboqs/build -DCMAKE_INSTALL_PREFIX="C:\liboqs" -DCMAKE_WINDOWS_EXPORT_ALL_SYMBOLS=TRUE -DBUILD_SHARED_LIBS=ON

# Using environment variable (UNIX-like)
export OQS_INSTALL_PATH=/path/to/liboqs

  9. Platform-specific setup: Windows and Debian

    main

    Windows

    If you lack a C++ compiler and CMake, install Build Tools for Visual Studio and select the Desktop development with C++ workload. Always run CMake commands from a Developer Command Prompt for VS.

    Debian-based Linux (including Raspberry Pi)

    Install build prerequisites using:

    sudo apt update
sudo apt install -y build-essential cmake ninja-build libssl-dev git python3-pip python3-venv

    After installing liboqs via CMake, run sudo ldconfig to ensure the shared library is found at runtime.

  10. Use the liboqs-python API

    main

    The library is accessed via import oqs. It provides three primary classes for post-quantum cryptography:

    • KeyEncapsulation: For key encapsulation mechanisms (KEM).
    • Signature: For stateless signature mechanisms.
    • StatefulSignature: For stateful signature mechanisms.

    To use a specific algorithm, instantiate the class with a string identifying the mechanism. You can discover supported mechanisms using:

    • get_enabled_kem_mechanisms()
    • get_enabled_sig_mechanisms()
    • get_enabled_stateful_sig_mechanisms()

    Note on StatefulSignatures: Using StatefulSignature requires liboqs to be built with specific flags: -DOQS_HAZARDOUS_EXPERIMENTAL_ENABLE_SIG_STFL_KEY_SIG_GEN=ON, -DOQS_ENABLE_SIG_STFL_LMS=ON, and/or -DOQS_ENABLE_SIG_STFL_XMSS=ON.

    import oqs

# Example: List enabled KEMs
kem_mechanisms = oqs.get_enabled_kem_mechanisms()
print(kem_mechanisms)

# Example: Using a KEM
with oqs.KeyEncapsulation("ML-KEM-768") as kem:
    public_key = kem.generate_keypair()
    # ...