Skip to content

pqblocks-fips-check

FIPS 203/204 boundary validator and hybrid key exchange (X25519 + ML-KEM-768) with ML-DSA-65 signatures and CBOM reporting.

Install from GitHub Area Status Python Licence Source

At a glance
Area Conformance
Import import pqblocks_fips_check
Command line library only
Version 0.1.0 (Alpha)
Python >=3.11
Native dependency liboqs
Repository PQBlocks/fips-boundary-validator
Licence Apache-2.0

What is pqblocks-fips-check?

FIPS 203/204 boundary validator and hybrid post-quantum key exchange (X25519 + ML-KEM-768) with ML-DSA-65 signatures and CBOM reporting.

Install

pip install git+https://github.com/PQBlocks/fips-boundary-validator

uv add git+https://github.com/PQBlocks/fips-boundary-validator

PyPI release staged

pqblocks-fips-check 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_fips_check import (
    hybrid_encap,
    hybrid_decap,
    sign,
    verify_sig,
    generate_cbom,
    PQCUnavailableError,
)
from pqblocks_fips_check.hybrid import hybrid_keygen

# 1. Hybrid key exchange (X25519 + ML-KEM-768)
alice_pk, alice_sk = hybrid_keygen()
bob_pk, bob_sk = hybrid_keygen()

# Alice encapsulates shared secret for Bob
ct, ss_alice = hybrid_encap(bob_pk, b"session-context")

# Bob decapsulates the ciphertext
_, ss_bob = hybrid_decap(bob_sk, ct)
assert ss_alice == ss_bob

# 2. ML-DSA-65 signature with context binding
sig = sign(b"Critical message payload", context=b"audit-auth")
assert verify_sig(b"Critical message payload", sig, context=b"audit-auth")

# 3. Export SPDX CBOM
cbom_json = generate_cbom()
assert "ML-KEM-768" in cbom_json and "ML-DSA-65" in cbom_json

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-acvp: Cross-implementation NIST ACVP conformance harness for FIPS 203 (ML-KEM) and FIPS 204 (ML-DSA).