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
VERSIONis the sole build version; installed packages read the embedded distribution metadata. - All 33 public C exports have declared
ctypessignatures and can be accessed aspq_cp_abe.native.<C_symbol>; low-level native buffers requirenative.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 --testorpython -m pq_cp_abe --testfor 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)
| File | Actions Reset | |||
|---|---|---|---|---|
| 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 logRelease 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 logRelease 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 logRelease 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 logRelease 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 logRelease 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 logSecurity 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.
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 logA 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.