liboqs-python: Python 3 bindings for liboqs

About

The Open Quantum Safe (OQS) project has the goal of developing and prototyping quantum-resistant cryptography.

liboqs-python offers a Python 3 wrapper for the Open Quantum Safe liboqs C library, which is a C library for quantum-resistant cryptographic algorithms.

The wrapper is written in Python 3, hence in the following it is assumed that you have access to a Python 3 interpreter. liboqs-python has been extensively tested on Linux, macOS and Windows platforms. Continuous integration is provided via GitHub actions.

The project contains the following files and directories

• oqs/oqs.py: a Python 3 module wrapper for the liboqs C library.
• oqs/rand.py: a Python 3 module supporting RNGs from <oqs/rand.h>
• examples/kem.py: key encapsulation example
• examples/rand.py: RNG example
• examples/sig.py: signature example
• examples/stfl_sig.py: stateful signature example
• tests: unit tests

Pre-requisites

• liboqs
• git
• CMake
• C compiler, e.g., gcc, clang, MSVC etc.
• Python 3

Installation

Configure, build and install liboqs

Execute in a Terminal/Console/Administrator Command Prompt

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

The last line may require prefixing it by sudo on UNIX-like systems. Change --parallel 8 to match the number of available cores on your system.

On UNIX-like platforms, you may need to set the LD_LIBRARY_PATH (DYLD_LIBRARY_PATH on macOS) environment variable to point to the path to liboqs' library directory, e.g.,

export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/local/lib

On Windows platforms, you must ensure that you add the -DCMAKE_WINDOWS_EXPORT_ALL_SYMBOLS=TRUE flag to CMake, and that the liboqs shared library oqs.dll is visible system-wide, i.e., set the PATH environment variable accordingly by using the "Edit the system environment variables" Control Panel tool or executing in a Command Prompt

set PATH=%PATH%;C:\Program Files (x86)\liboqs\bin

You can change liboqs' installation directory by configuring the build to use an alternative path, e.g., C:\liboqs, by passing the -DCMAKE_INSTALL_PREFIX=/path/to/liboqs flag to CMake, e.g.,

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

Alternatively, you can set the OQS_INSTALL_PATH environment variable to point to the installation directory, e.g., on a UNIX-like system, execute

export OQS_INSTALL_PATH=/path/to/liboqs

Let liboqs-python install liboqs automatically

If liboqs is not detected at runtime by liboqs-python, it will be downloaded, configured and installed automatically (as a shared library). This process will be performed only once, at runtime, i.e., when loading the liboqs-python wrapper. The liboqs source directory will be automatically removed at the end of the process.

This is convenient in case you want to avoid installing liboqs manually, as described in the subsection above.

By default, liboqs-python installs the liboqs release that matches its own version; a maintenance release such as liboqs-python 0.16.0.1 installs liboqs 0.16.0. Set the PYOQS_VERSION environment variable to override this:

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

Other values must be a liboqs release version, e.g., 0.16.0 or 0.16.0-rc1.

Install and activate a Python virtual environment

Execute in a Terminal/Console/Administrator Command Prompt

python3 -m venv venv
. venv/bin/activate
python3 -m ensurepip --upgrade

On Windows, replace the line

. venv/bin/activate

by

venv\Scripts\activate.bat

Install the wrapper from PyPI

The simplest way to install liboqs-python is from PyPI

pip install liboqs-python

The PyPI package contains only the Python wrapper; it does not bundle a compiled copy of liboqs. The first time you import oqs, liboqs-python uses a system-wide liboqs if one is available, or otherwise downloads, builds and installs the matching liboqs release automatically, as described in Let liboqs-python install liboqs automatically above. Building liboqs from source requires git, CMake and a C compiler; see Pre-requisites.

Install the wrapper from source

Alternatively, install the wrapper directly from the source repository by executing in a Terminal/Console/Administrator Command Prompt

git clone --depth=1 https://github.com/open-quantum-safe/liboqs-python
cd liboqs-python
pip install .

Run the examples

Execute

python3 liboqs-python/examples/kem.py
python3 liboqs-python/examples/sig.py
python3 liboqs-python/examples/stfl_sig.py
python3 liboqs-python/examples/rand.py

Run the unit test

Execute

nose2 --verbose

Platform-specific notes

The instructions above apply to all platforms; the notes below cover prerequisites that are easy to miss on Windows and on Debian-based Linux (including Raspberry Pi).

Windows: If you do not already have a C++ compiler and CMake, install the Build Tools for Visual Studio (scroll to "All Downloads" → "Tools for Visual Studio"). In the installer, select the Desktop development with C++ workload, which provides the MSVC compiler, the Windows SDK, and CMake. Then run the CMake commands from a Developer Command Prompt for VS so the compiler is on your PATH. Remember the -DCMAKE_WINDOWS_EXPORT_ALL_SYMBOLS=TRUE flag and the PATH setting for oqs.dll described above.

Debian-based Linux (including Raspberry Pi): Install the build prerequisites with

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

After cmake --build ... --target install, run sudo ldconfig so the newly installed shared library is found at runtime (an alternative to setting LD_LIBRARY_PATH as described above).

Usage in standalone applications

liboqs-python can be imported into Python programs with

import oqs

liboqs-python defines three main classes: KeyEncapsulation, Signature, and StatefulSignature, providing post-quantum key encapsulation as well as stateless and stateful signature mechanisms. Each must be instantiated with a string identifying one of the mechanisms supported by liboqs; these can be enumerated using the get_enabled_kem_mechanisms(), get_enabled_sig_mechanisms() and get_enabled_stateful_sig_mechanisms() functions. ML-KEM key pairs can also be deterministically generated from a seed using KeyEncapsulation.generate_keypair_seed(). The files in examples/ demonstrate the wrapper's API. Support for alternative RNGs is provided via the randombytes_*() functions.

Note: StatefulSignature requires liboqs to be built with -DOQS_HAZARDOUS_EXPERIMENTAL_ENABLE_SIG_STFL_KEY_SIG_GEN=ON in addition to -DOQS_ENABLE_SIG_STFL_LMS=ON and/or -DOQS_ENABLE_SIG_STFL_XMSS=ON. Without that flag, instantiating StatefulSignature raises RuntimeError (the public C ABI for stateful signatures is only available when the flag is set).

The liboqs-python project should be in the PYTHONPATH. To ensure this on UNIX-like systems, execute

export PYTHONPATH=$PYTHONPATH:/path/to/liboqs-python

or, on Windows platforms, use the "Edit the system environment variables" Control Panel tool or execute in a Command Prompt

set PYTHONPATH=%PYTHONPATH%;C:\path\to\liboqs-python

Docker

A self-explanatory minimalistic Docker file is provided in Dockerfile.

Build the image by executing

docker build -t oqs-python .

Run, e.g., the key encapsulation example by executing

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

Or, run the unit tests with

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

In case you want to use the Docker container as a development environment, mount your current project in the Docker container with

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

Limitations and security

liboqs is designed for prototyping and evaluating quantum-resistant cryptography. Security of proposed quantum-resistant algorithms may rapidly change as research advances, and may ultimately be completely insecure against either classical or quantum computers.

We believe that the NIST Post-Quantum Cryptography standardization project is currently the best avenue to identifying potentially quantum-resistant algorithms. liboqs does not intend to "pick winners", and we strongly recommend that applications and protocols rely on the outcomes of the NIST standardization project when deploying post-quantum cryptography.

We acknowledge that some parties may want to begin deploying post-quantum cryptography prior to the conclusion of the NIST standardization project. We strongly recommend that any attempts to do make use of so-called hybrid cryptography, in which post-quantum public-key algorithms are used alongside traditional public key algorithms (like RSA or elliptic curves) so that the solution is at least no less secure than existing traditional cryptography.

Just like liboqs, liboqs-python is provided "as is", without warranty of any kind. See LICENSE for the full disclaimer.

License

liboqs-python is licensed under the MIT License; see LICENSE for details.

Team

The Open Quantum Safe project is led by Douglas Stebila and Michele Mosca at the University of Waterloo.

Contributors

Contributors to the liboqs-python wrapper include

• Ben Davies (University of Waterloo)
• Vlad Gheorghiu (softwareQ Inc. and the University of Waterloo)
• Christian Paquin (Microsoft Research)
• Douglas Stebila (University of Waterloo)

Support

Financial support for the development of Open Quantum Safe has been provided by Amazon Web Services and the Canadian Centre for Cyber Security.

We'd like to make a special acknowledgement to the companies who have dedicated programmer time to contribute source code to OQS, including Amazon Web Services, evolutionQ, softwareQ, and Microsoft Research.

Research projects which developed specific components of OQS have been supported by various research grants, including funding from the Natural Sciences and Engineering Research Council of Canada (NSERC); see the source papers for funding acknowledgments.