Skip to content

pqblocks-files

Hybrid post-quantum file encryption: ML-KEM-768 plus X25519 key encapsulation with chunked ChaCha20-Poly1305 in the pfsh v1 format.

Install from GitHub Area Status Python Licence Source

At a glance
Area PQ cryptography
Import import pqblocks_files
Command line pqblocks-files
Version 0.1.0 (Alpha)
Python >=3.11
Native dependency liboqs
Repository PQBlocks/hybrid-file-encryption
Licence Apache-2.0

What is pqblocks-files?

Hybrid post-quantum file encryption for Python and the command line: ML-KEM-768 plus X25519 key encapsulation, with the payload sealed in 64 KiB ChaCha20-Poly1305 chunks (the pfsh v1 file format).

Use it to encrypt files or byte strings to one or more recipients' public keys so that a future quantum computer, or a break of either primitive alone, does not expose them.

Implements NIST FIPS 203 (ML-KEM-768, via liboqs), RFC 7748 (X25519), RFC 8439 (ChaCha20-Poly1305) and RFC 5869 (HKDF). Not FIPS or CMVP validated. Pre-1.0: not independently audited.

Install

pip install git+https://github.com/PQBlocks/hybrid-file-encryption

uv add git+https://github.com/PQBlocks/hybrid-file-encryption

PyPI release staged

pqblocks-files 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_files.encrypt import encrypt, decrypt
from pqblocks_files.keys import keygen

keypair = keygen()                                    # ML-KEM-768 + X25519
blob = encrypt(b"quarterly numbers", [keypair.public])  # fresh random file key every call
assert decrypt(blob, keypair) == b"quarterly numbers"   # refuses classical-only files by default

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-jose: Post-quantum hybrid JOSE library supporting ML-KEM and ML-DSA JWE and JWS tokens.
  • pqblocks-primitives: Production-ready integrated post-quantum cryptographic primitives (ML-KEM, ML-DSA, SLH-DSA, and hybrid schemes).