liboqs & Open Quantum Safe

liboqs is the C library at the heart of the Open Quantum Safe (OQS) project — a single, uniform API over post-quantum KEMs and signatures, with language wrappers for Python, Go, Rust, C++, and Java. OQS is now a project of the Linux Foundation's Post-Quantum Cryptography Alliance (PQCA), and liboqs is the fastest way to experiment with every NIST candidate (current release: 0.15.0, Nov 2025).

What OQS gives you

• liboqs — the core C library exposing KEMs (ML-KEM, Classic McEliece, HQC, BIKE, FrodoKEM, NTRU, NTRU-Prime) and signatures (ML-DSA, SLH-DSA, Falcon, plus the NIST additional-signature on-ramp candidates CROSS, MAYO, SNOVA, UOV) behind two simple object types. Stateful hash signatures (LMS, XMSS) are also provided.
• Language wrappers — liboqs-python, liboqs-go, liboqs-rust, liboqs-cpp, and liboqs-java.
• oqs-provider — an OpenSSL 3 provider that plugs liboqs algorithms into the OpenSSL TLS/X.509 machinery (see OpenSSL).
• OQS forks — patched builds of OpenSSL and other tools for end-to-end demos.

Build liboqs from source

liboqs uses CMake. On a Debian/Ubuntu box:

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

git clone --depth 1 https://github.com/open-quantum-safe/liboqs.git
cd liboqs
mkdir build && cd build
cmake -GNinja -DCMAKE_INSTALL_PREFIX=/usr/local ..
ninja
sudo ninja install
sudo ldconfig

Install the Python wrapper

The Python binding builds against (or downloads) liboqs automatically:

pip install liboqs-python

Then verify the install and list what your build enabled:

import oqs

print("liboqs version:", oqs.oqs_version())
print("enabled KEMs:", oqs.get_enabled_kem_mechanisms())
print("enabled sigs:", oqs.get_enabled_sig_mechanisms())

KEM example: ML-KEM-768

A full encapsulate/decapsulate round trip with the oqs.KeyEncapsulation object:

import oqs

kem_name = "ML-KEM-768"

with oqs.KeyEncapsulation(kem_name) as server:
    public_key = server.generate_keypair()

    # The client encapsulates against the server's public key.
    with oqs.KeyEncapsulation(kem_name) as client:
        ciphertext, shared_secret_client = client.encap_secret(public_key)

    # The server recovers the identical shared secret.
    shared_secret_server = server.decap_secret(ciphertext)

assert shared_secret_client == shared_secret_server
print("agreed on", len(shared_secret_client), "bytes")  # 32

Teaching demo only — production code needs exception handling and secure handling of the secret key material. See Production hardening below.

Signature example: ML-DSA-65

Signing and verification use the oqs.Signature object:

import oqs

sig_name = "ML-DSA-65"
message = b"post-quantum signatures in production"

with oqs.Signature(sig_name) as signer:
    public_key = signer.generate_keypair()
    signature = signer.sign(message)

# Verification needs only the public key, so use a fresh object.
with oqs.Signature(sig_name) as verifier:
    is_valid = verifier.verify(message, signature, public_key)

print("signature valid:", is_valid)

Enumerating and probing mechanisms

Because a given build may not enable every algorithm, gate your code on what is actually available:

import oqs

wanted = "Classic-McEliece-348864"
if wanted in oqs.get_enabled_kem_mechanisms():
    with oqs.KeyEncapsulation(wanted) as kem:
        details = kem.details
        print(details["name"], "ek/ct bytes:",
              details["length_public_key"],
              details["length_ciphertext"])
else:
    print(wanted, "is not enabled in this liboqs build")

The details dictionary exposes claimed NIST security level and the byte lengths of keys, ciphertexts, and signatures — handy for budgeting bandwidth before you commit to a scheme.

Production hardening

The round-trip examples above are deliberately minimal — they show the API, not a deployable pattern. Before shipping liboqs-backed code, add explicit error handling, treat the shared secret as live key material, and compare secrets in constant time:

import hmac
import oqs

kem_name = "ML-KEM-768"

try:
    # Each `with` block frees the underlying C key material — including the
    # secret key — deterministically when the object goes out of scope.
    with oqs.KeyEncapsulation(kem_name) as server:
        public_key = server.generate_keypair()
        with oqs.KeyEncapsulation(kem_name) as client:
            ciphertext, ss_client = client.encap_secret(public_key)
        ss_server = server.decap_secret(ciphertext)
except oqs.MechanismNotSupportedError:
    raise SystemExit(f"{kem_name} is not enabled in this liboqs build")

# Compare shared secrets in constant time — never with `==`.
if not hmac.compare_digest(ss_client, ss_server):
    raise ValueError("KEM shared-secret mismatch")

# Use the shared secret only through a KDF bound to the protocol transcript,
# e.g. HKDF-SHA256 over ss_client together with the public key and ciphertext.

• Handle errors explicitly. An unavailable mechanism raises oqs.MechanismNotSupportedError; catch it rather than failing deep inside a handshake. Derive your session key from the KEM output through a KDF over the full transcript, so a tampered ciphertext yields a different key instead of a silent success.
• Treat the shared secret as key material. Feed it straight into an HKDF; never log, print, or persist it. Python bytes are immutable and cannot be reliably zeroized, so keep them short-lived — and rely on the with block to free the C-side secret key promptly.
• Compare in constant time. Use hmac.compare_digest for any secret or MAC comparison; a plain == can leak information through timing.
• Mind side channels. Prefer constant-time implementations and validate the ones your build ships. Falcon / FN-DSA floating-point Gaussian sampling and naive Classic McEliece decoders are classic leak sources — avoid secret-dependent branches and memory access, and never roll your own sampler. See Side-channel resistance.
• Use a validated module in production. liboqs is not FIPS-validated. For the standardized algorithms prefer a CMVP/CAVP-validated module or OpenSSL 3.5 native support, and pin the standardized parameter sets and object identifiers so encodings stay interoperable.
• Seed the RNG properly. liboqs uses the operating-system CSPRNG by default; make sure that entropy source is present and well-seeded in your deployment — containers, early boot, and minimal images are common failure points.

Related

Standards & references

• Open Quantum Safe — the OQS project that develops liboqs and its wrappers.
• liboqs (GitHub) — source, build instructions, and issue tracker.
• PQClean — reference implementations that liboqs draws from.
• Resources — full standards register