Skip to main content

PQ-CP-ABE Python SDK

Encrypt data under a policy such as role::admin && department::finance. Only a user whose key grants the admin role in the finance department can decrypt it. This is ciphertext-policy attribute-based encryption (CP-ABE).

The default scheme, CoverCrypt, brings post-quantum protection to ABE key encapsulation. Its default hybridized mode combines Curve25519 and ML-KEM-768 to protect the secret used for AES-256-GCM payload encryption. Optional ML-DSA-87 signatures authenticate the sender and signed data. AC17 and TKN20 use classical ABE key protection, including when signing is enabled.

  • PyPI distribution: pq-cp-abe
  • Import: import pq_cp_abe
  • The repository root VERSION is the sole build version; installed packages read the embedded distribution metadata.
  • All 33 public C exports have declared ctypes signatures and can be accessed as pq_cp_abe.native.<C_symbol>; low-level native buffers require native.freeBuffer. Python-friendly wrappers are provided for the additional AES-GCM, ML-DSA-87, setup/genkey buffer and CoverCrypt authority operations.
  • Run python bindings/python/hybrid_pq_cp_abe.py --test or python -m pq_cp_abe --test for an end-to-end, disposable Python-only self-test. It invokes all 33 native symbols, verifies roundtrips across AC17/TKN20/CoverCrypt, AES-GCM, ML-DSA and CoverCrypt authority updates. It does not build C++ or modify application keys; the temporary test files are removed automatically. Exit code 0 means PASS; a nonzero code means FAIL.

Quick start

Install the package on Python 3.10 or later once the wheel is published to PyPI. You can also install the wheel for your platform directly from GitHub Releases with python -m pip install <downloaded-wheel.whl>.

python -m pip install pq-cp-abe

Post-quantum ABE from the CLI

Run python -m pq_cp_abe to list commands and python -m pq_cp_abe --test to run the full self-test. The demo uses CoverCrypt in its default hybridized mode. Here, hybrid means Curve25519 and ML-KEM-768 each contribute a shared secret to the same key encapsulation. CoverCrypt uses both components to recover the protected secret, while AES-256-GCM encrypts the file itself. For ML-KEM-768-only encapsulation, see how to choose post_quantum.

In a new working directory, create a file named attributes-dimensions.json:

{
  "dimensions": [
    {"name": "role", "attributes": ["admin", "analyst"]},
    {"name": "department", "attributes": ["finance", "engineering"]}
  ]
}

Set HCPABE_COVERCRYPT_CONFIG in the terminal where you will run the demo. Set HCPABE_COVERCRYPT_MODE to hybridized if the terminal already uses another mode.

  • Bash: export HCPABE_COVERCRYPT_CONFIG=./attributes-dimensions.json
  • PowerShell: $env:HCPABE_COVERCRYPT_CONFIG = (Resolve-Path ./attributes-dimensions.json).Path
  • CMD: set "HCPABE_COVERCRYPT_CONFIG=%CD%\attributes-dimensions.json"
mkdir keys
python -c "from pathlib import Path; Path('message.txt').write_text('Hello from PQ-CP-ABE', encoding='utf-8')"
python -m pq_cp_abe setup keys
python -m pq_cp_abe genkey keys/cpabe_msk.key "role::admin department::finance" keys/user.key
python -m pq_cp_abe encrypt keys/cpabe_pk.key message.txt "role::admin && department::finance" message.enc
python -m pq_cp_abe decrypt keys/user.key message.enc recovered.txt
python -c "from pathlib import Path; print(Path('recovered.txt').read_text(encoding='utf-8'))"

CoverCrypt writes each attribute as dimension::value. Pass a space-separated list to genkey and join required attributes with && in the encryption policy. Setup creates the authority's master secret key (cpabe_msk.key) and public key (cpabe_pk.key). Use the master secret key to issue user keys, and share the public key with encryptors.

To add ML-DSA-87 signing and verification to the same post-quantum ABE flow, use a separate key directory and the same message.txt.

mkdir signed-keys
python -m pq_cp_abe setup-pqc signed-keys
python -m pq_cp_abe genkey signed-keys/cpabe_msk.key "role::admin department::finance" signed-keys/user.key
python -m pq_cp_abe encrypt-pqc signed-keys/cpabe_pk.key signed-keys/pqc_sk.key message.txt "role::admin && department::finance" signed.enc
python -m pq_cp_abe decrypt-pqc signed-keys/user.key signed-keys/pqc_pk.key signed.enc verified.txt

Run a post-quantum ABE example in Python

Copy this into demo.py and run python demo.py. It creates an authority, issues a user key with role::admin and department::finance, and encrypts and decrypts a message in memory using CoverCrypt in hybridized mode. It also checks that a user key from the engineering department cannot decrypt the same ciphertext. Each step reports OK or FAILED. A failure prints the error and exits with status 1.

import json
import os
import sys
from contextlib import contextmanager
from pathlib import Path
from tempfile import TemporaryDirectory

import pq_cp_abe as abe


@contextmanager
def step(number, label):
    prefix = f"[{number}/7] {label}"
    print(f"{prefix} ...", flush=True)
    try:
        yield
    except Exception as error:
        print(f"{prefix}: FAILED ({error})", file=sys.stderr, flush=True)
        raise SystemExit(1) from None
    print(f"{prefix}: OK", flush=True)


def main():
    mode = "hybridized"
    attributes = "role::admin department::finance"
    policy = "role::admin && department::finance"
    message = b"Hello from PQ-CP-ABE"

    print(f"Native library version: {abe.get_version()}")
    print(f"Scheme: CoverCrypt ({mode})")

    with TemporaryDirectory() as directory:
        with step(1, "Write the CoverCrypt configuration"):
            config = Path(directory) / "attributes-dimensions.json"
            config.write_text(json.dumps({"dimensions": [
                {"name": "role", "attributes": ["admin", "analyst"]},
                {"name": "department", "attributes": ["finance", "engineering"]},
            ]}), encoding="utf-8")
            os.environ["HCPABE_COVERCRYPT_CONFIG"] = str(config)
            os.environ["HCPABE_COVERCRYPT_MODE"] = mode

        with step(2, "Create authority keys"):
            public_key, master_key = abe.setup_buffer()

        with step(3, f"Issue a user key for {attributes}"):
            user_key = abe.genkey_buffer(master_key, attributes)

        with step(4, f"Encrypt under policy {policy}"):
            ciphertext = abe.call_hybrid_cpabe_encryptBuffer(public_key, message, policy)
            print(f"    Ciphertext size: {len(ciphertext)} bytes")

        with step(5, "Decrypt with the user key"):
            recovered = abe.call_hybrid_cpabe_decryptBuffer(user_key, ciphertext)

        with step(6, "Compare the recovered message with the original"):
            if recovered != message:
                raise ValueError("The decrypted message does not match the original")
            print(f"    Recovered message: {recovered.decode('utf-8')}")

        with step(7, "Check that a user from engineering is denied"):
            other_attributes = "role::admin department::engineering"
            other_key = abe.genkey_buffer(master_key, other_attributes)
            try:
                abe.call_hybrid_cpabe_decryptBuffer(other_key, ciphertext)
            except RuntimeError as error:
                if "Attributes do not satisfy policy" not in str(error):
                    raise
                print(f"    Access denied as expected for {other_attributes}")
            else:
                raise RuntimeError("The engineering user unexpectedly decrypted the message")


if __name__ == "__main__":
    main()

For existing AC17 or TKN20 keys, pass scheme=abe.CPABE_SCHEME_AC17 or scheme=abe.CPABE_SCHEME_TKN20 to setup, key generation and encryption. Decryption detects the scheme from the ciphertext. See the scheme guide.

Choose hybrid or PQC-only key encapsulation

CoverCrypt supports three modes for protecting the secret behind the access policy. Choose one with HCPABE_COVERCRYPT_MODE before setup.

Mode CoverCrypt key encapsulation
hybridized (default) Combines a classical Curve25519-based shared secret and an ML-KEM-768 shared secret in the same encapsulation. Decapsulation uses both components.
post_quantum Uses ML-KEM-768 alone for key encapsulation.
classic Uses the classical Curve25519-based component alone.

For a PQC-only ABE/KEM demo, select post_quantum and run setup in a fresh key directory. Keep HCPABE_COVERCRYPT_CONFIG set to the dimensions file from the CLI example above.

  • Bash: export HCPABE_COVERCRYPT_MODE=post_quantum
  • PowerShell: $env:HCPABE_COVERCRYPT_MODE = 'post_quantum'
  • CMD: set "HCPABE_COVERCRYPT_MODE=post_quantum"

In demo.py, change the mode to "post_quantum" before calling abe.setup_buffer(). Setup applies the selected mode to the configured attributes. Encryption uses the mode encoded in the public key for the selected rights. To switch modes for an existing demo, generate a new authority and issue new user keys. Changing the environment variable alone leaves existing keys and ciphertext unchanged.

All three modes use AES-256-GCM for payload encryption. ML-DSA-87 is a separate, optional signature layer. See the C++ mode selector and the CoverCrypt encapsulation implementation.

Layout

pq_cp_abe/_native.py handles ctypes loading and the C ABI, api.py exposes the existing Python API, __main__.py implements the CLI, and _libs/ holds the bundled native runtimes.

Native GitHub Release as the binary source

.github/workflows/publish-pypi.yml uses already published native ZIPs from the exact v<VERSION> GitHub Release. It does not build C++, Rust or Go and does not use local lib/ or build/artifacts/ output. stage_native.py verifies the archive against the release's SHA256SUMS.txt and stages the runtime binaries and license files.

OS Architecture Required runtime
Windows x86_64 libhybrid-pq-cp-abe.dll and libcpabe_tkn20.dll
Linux x86_64 libhybrid-pq-cp-abe.so
macOS Intel x86_64 libhybrid-pq-cp-abe.dylib
macOS Apple Silicon arm64 libhybrid-pq-cp-abe.dylib

The wheel is platform-specific and uses Python-independent py3-none-<platform> tags. Linux wheels are repaired/audited with auditwheel for manylinux; macOS wheels use delocate. Different macOS architectures are separate wheels, not incorrectly marked universal2. Windows wheels require both DLLs.

Build/check on CI

From the repository on the matching GitHub Actions runner:

python bindings/python/stage_native.py --platform windows --arch x86_64
python -m pip install build
python -m build --wheel bindings/python
python bindings/python/verify_wheel.py --wheel-dir bindings/python/dist

Substitute windows/x86_64 with the actual runner target. On Linux/macOS, repair the wheel before calling verify_wheel.py, as in the workflow.

Staging also copies the project license, notice, and third-party licenses from the verified native release. The wheel ships those files in its .dist-info/licenses/ directory.

The verifier installs the wheel outside the source checkout, checks its internal native files and version, and runs AC17/TKN20/CoverCrypt setup, user key generation and encrypt/decrypt roundtrips. Do not use a local cached binary to judge a GitHub Release.

Publishing

From GitHub Actions, run Build Python Wheels with the publish input set to false to build/test/download the wheel artifacts only.

Once all four jobs pass, configure a PyPI Trusted Publisher for this GitHub repository, workflow publish-pypi.yml, and environment pypi. Then manually dispatch the workflow with publish=true. This is opt-in: no deployment occurs on ordinary pushes or releases.

The existing native release.yml is unchanged and Python publishing is independent. Source distribution (sdist) is intentionally not published because it cannot install a functioning native runtime by itself.

For local source development, the SDK can still fall back to the repository's lib/ binaries when available. This is separate from GitHub Release staging for wheels.

Compatibility entrypoints bindings/python/hybrid_pq_cp_abe.py and bindings/python/test_api.py remain, while new callers should use pq_cp_abe.

Metadata

Release files for pq-cp-abe 6.0.2

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Built distributions (wheels)

Table of built distributions (wheels) for pq-cp-abe 6.0.2
File Actions
pq_cp_abe-6.0.2-py3-none-win_amd64.whl Python 3 none Windows x86-64 Details for pq_cp_abe-6.0.2-py3-none-win_amd64.whl
pq_cp_abe-6.0.2-py3-none-manylinux_2_34_x86_64.whl Python 3 none Linux glibc 2.34+ x86-64 Details for pq_cp_abe-6.0.2-py3-none-manylinux_2_34_x86_64.whl
pq_cp_abe-6.0.2-py3-none-macosx_15_0_x86_64.whl Python 3 none macOS 15.0+ x86-64 Details for pq_cp_abe-6.0.2-py3-none-macosx_15_0_x86_64.whl
pq_cp_abe-6.0.2-py3-none-macosx_15_0_arm64.whl Python 3 none macOS 15.0+ ARM64 Details for pq_cp_abe-6.0.2-py3-none-macosx_15_0_arm64.whl
pq_cp_abe-6.0.2-py3-none-macosx_12_0_x86_64.whl Python 3 none macOS 12.0+ x86-64 Details for pq_cp_abe-6.0.2-py3-none-macosx_12_0_x86_64.whl
pq_cp_abe-6.0.2-py3-none-macosx_12_0_arm64.whl Python 3 none macOS 12.0+ ARM64 Details for pq_cp_abe-6.0.2-py3-none-macosx_12_0_arm64.whl

Total release size: 29.6 MB

Release files / pq_cp_abe-6.0.2-py3-none-win_amd64.whl

Download URL pq_cp_abe-6.0.2-py3-none-win_amd64.whl
Size 3.6 MB
Tags Python 3 Windows x86-64
SHA-256 checksum
How to use checksums
98ef3f816692f366ef669ee1fe8c211b78c5e964e50f9b7e8ad19f6a51b6e046
BLAKE2b-256 checksum
How to use checksums
67965e0fc5002ff65628f5a644f72b7810e289a95e0fb6f0fcafe39c340c8f94
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.

Transparency log

Release files / pq_cp_abe-6.0.2-py3-none-manylinux_2_34_x86_64.whl

Download URL pq_cp_abe-6.0.2-py3-none-manylinux_2_34_x86_64.whl
Size 8.1 MB
Tags Linux glibc 2.34+ x86-64 Python 3
SHA-256 checksum
How to use checksums
f3b76941b48ab6a422883a441a2222dcddd5d28d82b2d5d9b3143b7a44a6789b
BLAKE2b-256 checksum
How to use checksums
aed0771771ebb3b85a278b9674741c1dbf5699f3237344fd378e3dcb0855700b
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.

Transparency log

Release files / pq_cp_abe-6.0.2-py3-none-macosx_15_0_x86_64.whl

Download URL pq_cp_abe-6.0.2-py3-none-macosx_15_0_x86_64.whl
Size 4.6 MB
Tags Python 3 macOS 15.0+ x86-64
SHA-256 checksum
How to use checksums
6d2810a01e5d866503439758fd9cbe3081dfcdccc20c15278c37958fcbaf765c
BLAKE2b-256 checksum
How to use checksums
bed75ef50ef37e8be80b83b9ad4e1fcb3bfbf4f9b2b544eeb8c382451f89e695
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.

Transparency log

Release files / pq_cp_abe-6.0.2-py3-none-macosx_15_0_arm64.whl

Download URL pq_cp_abe-6.0.2-py3-none-macosx_15_0_arm64.whl
Size 4.3 MB
Tags Python 3 macOS 15.0+ ARM64
SHA-256 checksum
How to use checksums
f577c074623b0ecf50e6db5c0dea7ff886ddfb24001693df1012d1580861aa8d
BLAKE2b-256 checksum
How to use checksums
484271f16318d14babb00b1690f70a8c90a2965f54c4c20043cd5c94fd10e964
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.

Transparency log

Release files / pq_cp_abe-6.0.2-py3-none-macosx_12_0_x86_64.whl

Download URL pq_cp_abe-6.0.2-py3-none-macosx_12_0_x86_64.whl
Size 4.7 MB
Tags Python 3 macOS 12.0+ x86-64
SHA-256 checksum
How to use checksums
31b5393c3d7bfb573cdf601d6e333780c25e1a6c1c3708208f5e24063a65b6e1
BLAKE2b-256 checksum
How to use checksums
135565778a7bf6b3035af909d1815166519c22e9867430dda2317b3caf8f7e54
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.

Transparency log

Release files / pq_cp_abe-6.0.2-py3-none-macosx_12_0_arm64.whl

Download URL pq_cp_abe-6.0.2-py3-none-macosx_12_0_arm64.whl
Size 4.3 MB
Tags Python 3 macOS 12.0+ ARM64
SHA-256 checksum
How to use checksums
b20bb443ecd5fb2f5908e1b3051477ace1ef49209fcb9f29bd44526d44700b3d
BLAKE2b-256 checksum
How to use checksums
78592ae6eb360269eae34f4466c71f683cbfca35de3e37de0576f24a8762d528
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.

Transparency log

Security for pq-cp-abe 6.0.2

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

All 6 files in this release have been uploaded with provenance metadata.

Select from 6 files

Attestation for pq_cp_abe-6.0.2-py3-none-win_amd64.whl

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

6.0.2 This release

6 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page