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 exampleexamples/rand.py: RNG exampleexamples/sig.py: signature exampleexamples/stfl_sig.py: stateful signature exampletests: unit tests
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 installThe 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/libOn 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\binYou 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=ONAlternatively, 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/liboqsIf 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.
Execute in a Terminal/Console/Administrator Command Prompt
python3 -m venv venv
. venv/bin/activate
python3 -m ensurepip --upgradeOn Windows, replace the line
. venv/bin/activateby
venv\Scripts\activate.batExecute in a Terminal/Console/Administrator Command Prompt
git clone --depth=1 https://github.com/open-quantum-safe/liboqs-python
cd liboqs-python
pip install .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.pyExecute
nose2 --verboseliboqs-python can be imported into Python programs with
import oqsliboqs-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.
The liboqs-python project should be in the PYTHONPATH. To ensure this on
UNIX-like systems, execute
export PYTHONPATH=$PYTHONPATH:/path/to/liboqs-pythonor, 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-pythonA 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/bashA more comprehensive Docker example is provided in the directory
docker.
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.
liboqs-python is licensed under the MIT License; see LICENSE for details.
The Open Quantum Safe project is led by Douglas Stebila and Michele Mosca at the University of Waterloo.
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)
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.