Skip to content

pqblocks-primitives

Production-ready integrated post-quantum cryptographic primitives (ML-KEM, ML-DSA, SLH-DSA, and hybrid schemes).

Install from GitHub Area Status Python Licence Source

At a glance
Area PQ cryptography
Import import pqblocks_primitives
Command line library only
Version 0.1.0 (Alpha)
Python >=3.11
Native dependency liboqs
Repository PQBlocks/fips-pqc-primitives
Licence Apache-2.0

What is pqblocks-primitives?

Production-ready integrated post-quantum cryptographic primitives (ML-KEM, ML-DSA, SLH-DSA, and hybrid schemes).

Install

pip install git+https://github.com/PQBlocks/fips-pqc-primitives

uv add git+https://github.com/PQBlocks/fips-pqc-primitives

PyPI release staged

pqblocks-primitives installs from its GitHub repository while the PyPI release is staged. The import name and API are identical either way.

Native dependency: liboqs

The post-quantum primitives come from liboqs (Open Quantum Safe). The package README explains how the library is located: install notes.

Quickstart

Executed, not just written

This is the quickstart from the package README. It was run against the package source when this page was generated.

quickstart.py
from pqblocks_primitives import kem_keygen, kem_encaps, kem_decaps

# Generate ML-KEM-768 keypair
pk, sk = kem_keygen("768")

# Encapsulate shared secret
ct, shared_secret_sender = kem_encaps(pk, "768")

# Decapsulate shared secret
shared_secret_receiver = kem_decaps(sk, ct, "768")

assert shared_secret_sender == shared_secret_receiver

Examples

Runnable scripts in the repository:

Documentation and evidence

Every PQBlocks package ships the same evidence set, so each claim can be checked against tests, sources and measurements.

  • Overview

    What it does, install, usage and API.

  • For AI agents

    Correct imports, pitfalls and rules for coding assistants.

  • Security notes

    What it protects, hostile input, constant-time and audit status.

  • Testing

    Test suites, coverage, vectors and what is not covered.

  • Benchmarks

    Measured performance, including where it loses.

  • Evidence

    Primary sources and the method-to-code map.

  • Verification report

    Self-verification results, defects found and limits.

  • Use cases

    Worked scenarios and when to pick something else.

  • Changelog

    Every release and what changed.

  • pqblocks-core: Post-quantum hybrid cryptography core SDK with C shared libraries and policy enforcement.
  • pqblocks-files: Hybrid post-quantum file encryption: ML-KEM-768 plus X25519 key encapsulation with chunked ChaCha20-Poly1305 in the…
  • pqblocks-jose: Post-quantum hybrid JOSE library supporting ML-KEM and ML-DSA JWE and JWS tokens.