Repository navigation
Releases
v6.0.2
Hybrid PQ-CP-ABE Library - Version 6.0.2
Overview
Version 6.0.2 adds a WebAssembly (Wasm) SDK for browsers and Node.js, and a Python SDK distributed as platform-specific wheels. GitHub Actions builds the Wasm release artifacts on Linux. Node.js users can install the SDK from npm, and the GitHub Release provides a ZIP for browser deployment, manual Node.js setup, and Emscripten C/C++ linking.
The SDKs support AC17, TKN20, and CoverCrypt. CoverCrypt provides post-quantum protection for key encapsulation through ML-KEM-768, with a hybrid mode that also uses Curve25519. The library encrypts payloads with AES-256-GCM and supports optional ML-DSA-87 signatures.
WebAssembly SDK
The Emscripten module exposes the public C API. Setup, key generation, encryption, and decryption are available through file and buffer APIs for all three ABE schemes. File operations use an in-memory filesystem, and the CLI entry point is available through callMain.
Node.js via npm
Use Node.js 18 or newer. Install version 6.0.2 and run the bundled self-test.
npm install @wanthinnn/pq-cp-abe@6.0.2
npx @wanthinnn/pq-cp-abe@6.0.2 --testSave this example as demo.mjs and run node demo.mjs to print the library version.
import createHybridCPABE from '@wanthinnn/pq-cp-abe';
const abe = await createHybridCPABE();
console.log(abe.ccall('getVersion', 'string', [], []));The npm package bundles the Wasm runtime files and initializes them when you call createHybridCPABE(). See the Node.js SDK guide for CLI commands and a CoverCrypt example.
Browser and manual ZIP setup
Download the WebAssembly SDK ZIP and extract it. Keep the five runtime files together in lib/wasm/ so the loader can initialize both the Emscripten module and the Go runtime used by TKN20.
| File | Purpose |
|---|---|
loader.mjs |
Initializes both runtimes |
hybrid-pq-cp-abe.mjs |
Emscripten module factory |
hybrid-pq-cp-abe.wasm |
Core library |
tkn20.wasm |
Go module for TKN20 |
wasm_exec.js |
Go runtime support |
From the extracted package directory, import the loader in a JavaScript module.
import createHybridCPABE from './lib/wasm/loader.mjs';
const abe = await createHybridCPABE();
console.log(abe.ccall('getVersion', 'string', [], []));For browser use, serve the page and runtime files from a secure context such as HTTPS or http://localhost. Use abe.FS.writeFile() to pass input to the in-memory filesystem and abe.FS.readFile() to retrieve output.
Build from source and release artifacts
On Linux, activate Emscripten SDK 7.0.0 or newer and install Rust nightly with rust-src, Go, and the prerequisites in the Wasm build guide. From the repository root, run the following commands.
make wasm -j8
make wasm-test -j8The GitHub Release includes the Wasm ZIP alongside native SDK archives and the Linux Vault plugin archive. The Wasm ZIP includes the runtime files, public headers, libhybrid-pq-cp-abe.a for Emscripten C/C++ linking, documentation, and dependency notices. Verify the ZIP using SHA256SUMS.txt.
Release CI runs a Node.js smoke test against the extracted Wasm ZIP. It covers file and buffer round trips for all three schemes, policy denial, ML-DSA-87 signing and verification, and rejection of modified ciphertext.
Python SDK and PyPI wheels
The Python distribution is pq-cp-abe and the import name is pq_cp_abe. The SDK requires Python 3.10 or newer and uses ctypes to expose all 33 native C exports along with higher-level Python helpers.
Install and verify
Install version 6.0.2 from PyPI. Pip selects a compatible wheel for your platform.
python -m pip install pq-cp-abe==6.0.2
python -m pq_cp_abe --test| Platform | Architecture | Bundled native runtime |
|---|---|---|
| Windows | x86_64 (AMD64) | libhybrid-pq-cp-abe.dll and libcpabe_tkn20.dll |
| Linux with glibc 2.34 or newer | x86_64 | libhybrid-pq-cp-abe.so |
| macOS 12 or newer | x86_64 (Intel) | libhybrid-pq-cp-abe.dylib |
| macOS 12 or newer | arm64 (Apple Silicon) | libhybrid-pq-cp-abe.dylib |
Version 6.0.2 also has the original macOS 15 wheels for both architectures. The macOS 12 backfill adds two wheels tagged macosx_12_0 and two native ZIPs for Intel and Apple Silicon. The native ZIPs have a separate checksum file, SHA256SUMS-macos12.txt. GitHub Release assets
For an offline installation, download a compatible .whl file from the GitHub Release and pass it to pip. The following example uses the Windows x64 wheel.
python -m pip install ./pq_cp_abe-6.0.2-py3-none-win_amd64.whlThe self-test runs in a temporary directory and checks all three schemes, AES-GCM, signed ciphertext, and CoverCrypt authority updates. A successful run reports 33/33 C symbols actually invoked and exits with code 0. From a repository checkout with the native library available, the equivalent command is python bindings/python/hybrid_pq_cp_abe.py --test.
Python API example
Save as demo.py and run python demo.py. The example creates a CoverCrypt authority, encrypts under a finance-admin policy, and checks both an authorized user and a user from another department.
import json
import os
from pathlib import Path
from tempfile import TemporaryDirectory
import pq_cp_abe as abe
print(f"Python package {abe.__version__}, native library {abe.get_version()}")
with TemporaryDirectory() as directory:
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"] = "hybridized"
public_key, master_key = abe.setup_buffer()
print("OK - Created CoverCrypt authority keys")
finance_key = abe.genkey_buffer(master_key, "role::admin department::finance")
engineering_key = abe.genkey_buffer(master_key, "role::admin department::engineering")
print("OK - Issued keys for finance and engineering admins")
message = b"Hello from Python"
policy = "role::admin && department::finance"
ciphertext = abe.call_hybrid_cpabe_encryptBuffer(public_key, message, policy)
print(f"OK - Encrypted {len(ciphertext)} bytes under {policy}")
recovered = abe.call_hybrid_cpabe_decryptBuffer(finance_key, ciphertext)
if recovered != message:
raise RuntimeError("The recovered message differs from the original")
print(f"OK - Finance admin decrypted: {recovered.decode('utf-8')}")
try:
abe.call_hybrid_cpabe_decryptBuffer(engineering_key, ciphertext)
except RuntimeError as error:
if "Attributes do not satisfy policy" not in str(error):
raise
print("OK - Engineering admin was denied as expected")
else:
raise RuntimeError("The engineering admin unexpectedly decrypted the message")The default CoverCrypt mode, hybridized, combines Curve25519 and ML-KEM-768 in the same key encapsulation. To use ML-KEM-768 alone for encapsulation, select post_quantum before generating fresh authority keys. Select classic to use the Curve25519 component alone. AC17 and TKN20 use classical ABE.
The SDK also exposes AES-GCM and ML-DSA-87 helpers and APIs for adding CoverCrypt attributes or dimensions. Advanced callers can access the typed C API through abe.native and release C-allocated buffers with freeBuffer. Python SDK guide
Wheel build and publishing
The manually dispatched Build Python Wheels workflow reads the repository-root VERSION, downloads the corresponding native GitHub Release ZIPs, and verifies them against SHA256SUMS.txt. It uses auditwheel for Linux wheels and delocate for macOS wheels. Each wheel is installed and tested in isolation.
publish=falsebuilds and tests the wheels and saves them as GitHub Actions artifacts.publish=trueattaches the verified wheels to the GitHub Release and publishes them to PyPI through Trusted Publishing (GitHub OIDC).
Maintainers can review the Build Python Wheels workflow and the release process.
v6.0.1
Hybrid PQ-CP-ABE Library — Version 6.0.1
Overview
Version 6.0.1 adds a WebAssembly SDK built on Linux for browser and Node.js applications. It exposes the public C API through an Emscripten module and supports AC17, TKN20, and CoverCrypt, including CoverCrypt with ML-KEM-768, AES-GCM encryption, and optional ML-DSA-87 signing and verification. It also introduces installable Python bindings with platform-specific wheels, a full 33-export native self-test, and an opt-in PyPI publishing workflow.
New Feature: WebAssembly SDK
- File and buffer APIs support setup, key generation, encryption, and decryption for all three ABE schemes. File APIs use an in-memory filesystem.
- Import
lib/wasm/loader.mjsto initialize the library and the Go runtime for TKN20. Keep the five JavaScript and WebAssembly runtime files together. - The SDK includes public headers and
libhybrid-pq-cp-abe.afor Emscripten C and C++ applications. The CLI entry point is available throughcallMain.
Build System & Release Artifacts
Build and test from source on Linux with Emscripten 7.0+, Rust nightly with rust-src, and Go. See the WASM build guide for toolchain setup and integration examples.
make wasm -j8
make wasm-test -j8- The release includes
libhybrid-pq-cp-abe_wasm_v6.0.1.zipalongside the four native SDK archives and the Linux Vault plugin archive. - The WASM ZIP contains the runtime files, static archive, public headers, documentation, and dependency notices. Its checksum is listed in
SHA256SUMS.txt. - Release CI runs the Node.js smoke suite against the extracted ZIP. It covers all three schemes, file and buffer round trips, policy denial, ML-DSA-87 signing and verification, and rejection of modified ciphertext.
Usage
Extract the ZIP and import the loader from the package directory:
import createHybridCPABE from './lib/wasm/loader.mjs';
const abe = await createHybridCPABE();
console.log(abe.ccall('getVersion', 'string', [], []));In a browser, serve the runtime files over HTTP(S) from a secure context such as HTTPS or localhost. Use abe.FS.writeFile and abe.FS.readFile to transfer data through the file API.
New Feature: Python SDK and PyPI Wheels
Version 6.0.1 also adds the distributable Python bindings under bindings/python/. The PyPI distribution is pq-cp-abe and the import name is pq_cp_abe (Python 3.10+). It wraps the public native C ABI with ctypes and exposes all 33 exported symbols from the v6.0.1 native library, along with higher-level Python helpers.
Install and Download
After the Python wheels are published to PyPI, install the appropriate platform wheel automatically with:
python -m pip install pq-cp-abe==6.0.1The package page is pq-cp-abe on PyPI. PyPI installation is available only after the separate Python publishing workflow succeeds. The native v6.0.1 GitHub Release ZIPs are not themselves Python wheels.
Before PyPI publishing, run the GitHub Actions Build Python Wheels workflow with publish=false. Download the python-wheel-<platform>-<arch> artifact for your operating system after that job succeeds, extract its .whl file, and install it with:
python -m pip install ./pq_cp_abe-6.0.1-py3-none-win_amd64.whlThe filename above is the Windows x64 example; substitute the actual downloaded wheel filename for Linux or macOS. Select a wheel compatible with your operating system and CPU architecture. The Python CI matrix builds four separate wheels:
| Operating system | Architecture | Bundled native runtime |
|---|---|---|
| Windows | x86_64 (AMD64) | libhybrid-pq-cp-abe.dll + 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 |
These wheels carry the native libraries; users do not need to compile C++, Rust, or Go to install a compatible wheel. Linux wheels undergo auditwheel repair, and macOS wheels undergo delocate dependency processing. Each platform's wheel must pass isolated installation/runtime checks before it can be published.
Python API Examples
Import the package and confirm the installed library version:
import pq_cp_abe as abe
print(abe.__version__)
print(abe.get_version())Use the native ABE schemes through the existing Python wrappers:
import pq_cp_abe as abe
# Choose AC17, TKN20, or CoverCrypt.
scheme = abe.CPABE_SCHEME_AC17
public_key, master_key = abe.setup_buffer(scheme)
user_key = abe.genkey_buffer(master_key, "admin it", scheme)
ciphertext = abe.call_hybrid_cpabe_encryptBuffer_with_scheme(
public_key, b"Hello from Python", "admin and it", scheme
)
plaintext = abe.call_hybrid_cpabe_decryptBuffer(user_key, ciphertext)
assert plaintext == b"Hello from Python"For CoverCrypt, select abe.CPABE_SCHEME_COVERCRYPT and provide a dimensions configuration through HCPABE_COVERCRYPT_CONFIG where required. HCPABE_COVERCRYPT_MODE accepts classic, post_quantum, or hybridized (the default). The CoverCrypt hybridized configuration uses Curve25519 with ML-KEM-768 for the ABE/KEM confidentiality path; AC17/TKN20 remain classical schemes.
The SDK also exposes aes_gcm_encrypt / aes_gcm_decrypt, ml_dsa_87_generate_keypair / ml_dsa_87_sign / ml_dsa_87_verify, and CoverCrypt authority-growth APIs to add attributes or dimensions using either files or memory buffers. Advanced consumers can access the fully typed, low-level C functions through abe.native; buffers allocated by the C library must be released using freeBuffer.
Python Self-Test
Test the installed wheel without a separate native build:
python -m pq_cp_abe --testWhen working directly from a repository checkout, the compatible entrypoint is also available:
python bindings/python/hybrid_pq_cp_abe.py --testThe self-test runs in a temporary directory, exercises all 33 native exports and checks AC17/TKN20/CoverCrypt file and buffer operations, AES-GCM, ML-DSA-87, signed ciphertext and CoverCrypt authority updates. A successful run reports 33/33 C symbols actually invoked and exits with code 0; failures return a non-zero exit code.
Wheel Build and Publishing
The separate publish-pypi.yml workflow uses the repository-root VERSION file to select the exact GitHub Release tag. It downloads the native archives, verifies each release ZIP against SHA256SUMS.txt, stages the platform libraries, builds a Python wheel and tests it independently of the source tree. Version metadata is derived from VERSION, not hard-coded in the Python package.
publish=falsebuilds and tests wheel artifacts only.publish=truepublishes the verified wheels to PyPI after all four platform jobs succeed, using PyPI Trusted Publishing (GitHub OIDC). ThepypiGitHub environment and PyPI Trusted Publisher must be configured beforehand; no PyPI API token is stored in the workflow.
This Python distribution workflow is independent from the existing native library release process. See the Python SDK README for further details.
v6.0.0
Hybrid PQ-CP-ABE Library — Version 6.0.0
Note
IMPORTANT NOTICE:
- From Version 4.0, this library natively supports and includes Post-Quantum Cryptography (PQC).
- If your project DOES NOT need PQC (to save space, avoid
liboqsdependencies, or minimize performance overhead), please download and use Version 3.1 from the Releases page.
Overview
Version 6.0.0 introduces CoverCrypt as a third native ABE scheme alongside
AC17 and TKN20. This is the main architectural reason for the major-version
bump: the previous AC17 and TKN20 schemes remain based on classical
pairing/discrete-log assumptions and are not designed to remain secure
against a sufficiently large cryptographically relevant quantum computer.
Since Version 4.0, this project has already provided post-quantum
authentication through ML-DSA-87 Sign-then-Encrypt. However, adding a
post-quantum signature does not make the underlying AC17/TKN20 ABE
encryption quantum-resistant. A future quantum adversary capable of breaking
the classical ABE layer could still recover the protected symmetric key even
if the ML-DSA signature itself remains secure.
CoverCrypt is added in Version 6.0.0 to address that missing confidentiality
layer. In its default Hybridized mode, CoverCrypt combines a classical
Curve25519 component with ML-KEM-768, bringing post-quantum protection into
the ABE/KEM path itself rather than only protecting authenticity.
This gives the library two distinct PQC layers when CoverCrypt Hybridized mode
is used together with --pqc / the PQC APIs:
- ML-KEM-768 protects the key-establishment / ABE encapsulation path against
quantum attacks. - ML-DSA-87 protects ciphertext authenticity and sender authentication
against quantum attacks.
AC17 and TKN20 are intentionally retained for compatibility, interoperability,
and deployments that still require the established classical schemes.
CoverCrypt is integrated through a project-owned Rust/C bridge and the existing
C++ scheme abstraction, so applications can opt into the new scheme through the
same public *_with_scheme interfaces instead of adopting a separate runtime
plugin or a second API surface.
Why CoverCrypt Was Added
The previous architecture had an important boundary:
- AC17/TKN20 + AES-256-GCM provided fine-grained access control and efficient
payload encryption. - ML-DSA-87 added post-quantum signatures.
- But the ABE key-protection layer itself remained classical.
That distinction matters for long-lived encrypted data and
harvest-now-decrypt-later threat models. An attacker can store ciphertext
today and attempt to decrypt it in the future once a sufficiently capable
quantum computer becomes available. Post-quantum signatures alone do not stop
that attack because signatures protect authenticity, not confidentiality.
CoverCrypt fills this gap by allowing the ABE encapsulation layer itself to use
ML-KEM-768. The default Hybridized mode keeps a classical component alongside
the post-quantum KEM component, providing a transition path that does not rely
exclusively on either family of assumptions.
Important
PQC in this project now has two separate roles. ML-DSA-87 provides
post-quantum authentication/signatures. CoverCrypt Hybridized/PostQuantum
modes provide post-quantum protection for key encapsulation and therefore the
confidentiality path. AC17/TKN20 remain classical even when used with
ML-DSA-87.
New Feature: Native CoverCrypt Integration
Third ABE Scheme
- Added
CPABE_SCHEME_COVERCRYPTas the third native scheme alongside
CPABE_SCHEME_AC17andCPABE_SCHEME_TKN20. - Existing public function names and parameters are preserved. Applications
select CoverCrypt through the current*_with_schemeAPIs. - Decryption continues to recover the scheme from the ciphertext header.
- Existing default functions continue to select AC17 for backward
compatibility. - Keys remain scheme-specific; selecting another scheme does not convert
existing keys or ciphertexts.
CoverCrypt Cryptographic Modes
The standalone CLI and existing setup APIs accept configuration through:
HCPABE_COVERCRYPT_CONFIG— path to the JSON dimensions configuration.HCPABE_COVERCRYPT_MODE—hybridized(default),post_quantum, or
classic.
The native bridge is built with the Curve25519 provider + ML-KEM-768 and
supports Classic, PostQuantum, and Hybridized rights.
Example configuration:
{"dimensions":[{"name":"Department","attributes":["FIN","HR"]},{"name":"Security","attributes":["LOW","TOP"],"hierarchical":true}]}Native CoverCrypt policies use upstream syntax such as:
Department::FIN && Security::TOP
For compatibility with the existing library interface, bare attributes such as
admin AND it are mapped to the corresponding
<attribute>::present values when the configured dimensions provide them.
CoverCrypt does not translate the TKN20 NOT operator. Unsupported policy
syntax fails explicitly rather than being silently rewritten.
Server integrations can instead pass JSON and mode directly to the public
core API. The Vault plugin uses this explicit API and requires no CoverCrypt
configuration file or environment variables on the server.
CoverCrypt KEM/DEM Integration
The CoverCrypt adapter follows the same byte-oriented hybrid architecture used
by the rest of the library:
- CoverCrypt encapsulates a shared KEM secret under the access policy.
- The adapter uses that secret with AES-GCM to protect the supplied random key
buffer. - The shared C++ core derives the payload key and performs AES-256-GCM payload
encryption. - When PQC signing is enabled, ML-DSA-87 remains the optional authentication
layer around the existing Sign-then-Encrypt path.
The Rust bridge does not reimplement CoverCrypt cryptographic primitives.
Serialized keys and encapsulations remain opaque CoverCrypt v16 formats.
Rust panics are caught at the C boundary, and Rust-owned output buffers are
zeroized and released through cc_buffer_free.
CoverCrypt Authority Updates
Correct User-Key Permissions
- Fixed omitted dimensions granting unintended rights in the CoverCrypt
adapter. A key containing onlyDepartment::ITcannot decrypt a ciphertext
requiringDepartment::IT && Level::ADMIN. - AND requires all requested attributes across independent dimensions; OR
accepts a satisfying alternative. Nested expressions are evaluated by the
cryptographic scheme, without a separate plaintext permission filter. - Hierarchical inheritance is retained. Conflicting values of one dimension
in the same AND clause are rejected; use OR for alternatives. - The bridge uses restricted user-key generation; the upstream native Rust
policy API remains available with its original omitted-dimension semantics.
Previously issued keys retain the rights encoded in their key material.
Rebuilding does not revoke excessive permissions already issued. Revoking
those permissions requires a replacement authority and authorized user keys,
with affected data re-encrypted under the replacement public key.
Add Attributes and Dimensions Without Replacing the Authority
- Added File and Buffer APIs for
add_attributeandadd_dimension, plus
corresponding CLI commands. - Growth modifies the existing access structure and calls upstream
Covercrypt::update_msk, retaining existing secrets instead of running setup
again or rotating all keys. - Both updated MSK and PK must be retained. Old user keys keep their existing
rights on old ciphertexts and new ciphertexts using those rights; they gain
no new attributes automatically. - New rights require an authorized user key issued from the updated MSK.
Existing signing keys can be reused, and existing data need not be
re-encrypted merely to add a dimension. - Hierarchical attribute insertion supports the optional
afterargument. - CLI/File growth writes a separate updated pair and refuses to overwrite
existing output files or the input authority.
build/artifacts/linux/main add_dimension --scheme covercrypt keys/demo_msk.key path/to/dimension.json keys/demo-v2
build/artifacts/linux/main add_attribute --scheme covercrypt keys/demo-v2_msk.key Department SALES keys/demo-v3add_dimension takes one JSON dimension object, whereas setup takes a
dimensions array:
{"name":"E","attributes":["present","absent"],"hierarchical":false}Explicit JSON APIs and Buffer Performance
- Added
hybrid_cpabe_covercrypt_setupBuffer_from_jsonand
hybrid_cpabe_covercrypt_add_dimensionBuffer_with_mode. These accept JSON
text and mode directly and never read or modify process environment. - The native bridge exports
cc_add_attributeandcc_add_dimension. - Reduced intermediate cloning during access-structure expansion.
- Added
cc_genkey_ephemeralso the stateless Buffer path avoids serializing
an updated MSK that its caller would discard. File key generation continues
to persist upstream authority/user state. - CoverCrypt's multi-dimensional rights expansion still determines scaling;
the optimizations do not change the cryptographic policy model.
The existing Buffer API remains stateless and does not retain the user
registry for tracing. This library does not expose tracing operations.
Python Binding
- Added
CPABE_SCHEME_COVERCRYPT = 2to the Python binding. - Python tests now exercise AC17, TKN20, and CoverCrypt through the same binding
surface. - CoverCrypt test setup automatically creates the required dimensions
configuration and selectshybridizedmode. - Python native-library loading uses the canonical project
lib/directory.
Windows builds publishlibcpabe_tkn20.dllthere alongside the public native
DLL, avoiding a hidden dependency on the build directory.
Build System & Dependency Layout
- CoverCrypt is now part of the nativ...
v5.2.1
Hybrid PQ-CP-ABE Library — Version 5.2.1
Note
IMPORTANT NOTICE:
- From Version 4.0, this library natively supports and includes Post-Quantum Cryptography (PQC).
- If your project DOES NOT need PQC (to save space, avoid
liboqsdependencies, or minimize performance overhead), please download and use Version 3.1 from the Releases page.
Version 5.2.1 focuses on Windows build reliability, native release automation,
complete dependency packaging, and explicit project licensing. The stable core
remains AC17/TKN20 with ML-DSA-87 signatures; this release does not introduce a
new encryption scheme or change the ciphertext format.
Windows build fixes
- Fixed false dependency-build failures caused by Windows PowerShell losing a
child process's exit code. Actual failures now identify the dependency and
exit code. - Replaced
Get-FileHashwith streaming .NET SHA-256 for dependency fingerprints
and the ready marker. Windows PowerShell workers also prioritize their own
module directory when inheriting a PowerShell 7 CI environment. - Fixed MSYS GNU Make invoking
cmd.exewith rewritten flags and escaped
quotes. C/C++ builds continue to use MSVC x64; MinGW is used only for the Go
TKN20 bridge behind its C ABI DLL. - Made object-directory creation a shared Make prerequisite to avoid parallel
builds failing when several compiler jobs create the same directory. - Matched Crypto++ and liboqs to the native library's
/MDruntime, resolving
theLNK4098runtime conflict. - Removed byte-identical duplicate archive members from the Rust static
library while relocating its COFF indexes and preserving its symbols,
resolvingLNK4006warnings when building the combined static library. - Enabled UTF-8 source decoding for MSVC dependency builds to resolve
C4819. - Stopped detecting
cl.exeas a generic assembler in liboqs CMake builds. - Consolidated liboqs's MSVC optimization-barrier warning at configuration
time instead of repeating it for each object file. The upstream fallback
remains unchanged; this limitation has not been eliminated.
Crypto++ static and DLL outputs
On Windows, make deps now produces all three Crypto++ artifacts together in
build/deps/windows/lib/cryptopp/:
libcryptopp.lib: static library used by the native core.cryptopp.dll: ordinary, non-FIPS DLL exposing the upstream DLL API.cryptopp.lib: import library for DLL consumers.
The ordinary DLL uses the shared CRT allocation functions instead of legacy
MSVCRT allocator discovery. Its power-up algorithm self-tests run without the
legacy Win32 MAC-generation tool. The compliance-enabled upstream path retains
its integrity check. The x64 DLL also uses a suitable image base with ASLR.
Build commands and integration
make testandmake testsnow run the same test suite.make cleanandmake deps-cleanprint the affected directories and a
completion message.- Windows builds retain and publish
libhybrid-pq-cp-abe_dll.lib, the import
library needed to consume the native DLL through MSVC. - macOS shared-library builds use an
@rpathinstall name.
Windows consumers still need the compatible Microsoft Visual C++ runtime.
The TKN20 runtime dependency, libcpabe_tkn20.dll, must remain available beside
the consuming executable or through its configured DLL search path.
GitHub release workflow
The release workflow now builds from source on native runners, instead of
packaging historical binaries from obsolete paths. It targets:
| Platform | Architecture | Toolchain |
|---|---|---|
| Windows | x86_64 | MSVC x64 |
| Linux | x86_64 | GCC |
| macOS Intel | x86_64 | Apple Clang |
| macOS Apple Silicon | arm64 | Apple Clang |
- Pushing a
v*tag or publishing a GitHub Release triggers the build. - A manual workflow run builds Actions artifacts without publishing a release.
- Native tests must pass before packaging. Missing binaries, empty files, and
Git LFS pointers cause packaging to fail. - Packages include the CLI, public/dependency headers, static/shared libraries,
individual dependency libraries, and available third-party license notices. - The packager checks that the extracted CLI runs and that the extracted shared
library loads and exposes its version. - Linux dependency packages retain SONAME aliases; macOS packaged dylibs receive
relocatable install names and ad-hoc signatures. - All four ZIP packages must be present before publication. Release assets also
includeSHA256SUMS.txt.
License
- Added the official Apache License 2.0 text for original project code, with
Copyright 2026 Thien Lai. - Added
NOTICEand clarified the license scope in the README. - Third-party code retains its own terms, including CoverCrypt's bundled
BUSL-1.1 license. The root license does not relicense dependencies.
Validation status before release
- Windows native suite: 35 tests passed during the build-fix validation.
- Crypto++ DLL: AES and SHA-256 known-answer checks, RNG use, and power-up
self-tests passed through a real MSVC-linked DLL consumer. - Workflow syntax and expressions: checked with actionlint 1.7.12.
- Release packaging: 6 automated tests passed, covering platform layouts,
missing DLL import libraries, LFS pointers, unsafe versions, epoch timestamps,
and the requirement for all four release archives. - A Windows ZIP was built, extracted, and checked by running its CLI and loading
its shared library. - Linux and both macOS targets still require validation on GitHub-hosted
runners. These notes do not claim that their native builds have already
passed. Commit the workflow and supporting files before testing the workflow
or creating thev5.2.1tag.
Full Changelog: v5.2.0...v5.2.1
v5.2.0
Hybrid PQ-CP-ABE Library for Windows/Linux - Version 5.2.0
Note
IMPORTANT NOTICE:
- From Version 4.0, this library natively supports and includes Post-Quantum Cryptography (PQC).
- If your project DOES NOT need PQC (to save space, avoid
liboqsdependencies, or minimize performance overhead), please download and use Version 3.1 from the Releases page.
Overview
Version 5.2.0 focuses on a massive overhaul of the underlying cryptographic backend (rabe-ffi). We have successfully upgraded the core rabe Rust dependency from the outdated v0.2.6 to the latest v0.4.2. This update brings critical improvements to cryptographic soundness (AEAD support), modernizes the API layer, and provides strict memory safety guarantees by completely eliminating legacy Undefined Behavior (UB) patterns.
Enhancements & Security Upgrades
1. Core Dependency Upgrade: rabe 0.4.2
- The
rabecryptographic dependency used by therabe-ffimodule has been bumped from0.2.6to0.4.2. - Authenticated Encryption (AEAD): By migrating to
rabe 0.4.2, the internal symmetric encryption layer now securely utilizesaes-gcm(which includes an authentication tag). This replaces the older unauthenticated AES implementation, preventing ciphertext malleability attacks and ensuring cryptographically sound data integrity. - API Modernization: The C-FFI wrappers for AC17, BSW, AW11, BDABE, MKE08, LSW, and YCT14 schemes have been fully rewritten to support the new
rabe 0.4.xstrict reference-based APIs (e.g., converting C-string arrays into Rust&[&str]) and robust error-handling mechanisms (Resultmapping instead ofOption).
2. CI/CD Pipeline & GitHub Release Automation
- Automated GitHub Releases: CI/CD workflows on the
rabe-ffisubmodule have been enhanced to automatically package release artifacts (.zipfor Windows,.tar.gzfor macOS/Linux) and publish a new GitHub Release whenever a version tag (e.g.,v0.4.3) is pushed. - Node.js 16 Deprecation Fix: Upgraded GitHub Actions
actions/checkoutandactions/upload-artifacttov4to resolve workflow failures caused by GitHub's deprecation ofv3actions.
Bug Fixes
Memory Safety & Undefined Behavior (UB) Elimination
- Fixed Allocator Mismatch in
rabe_free_json: Prevented potential heap corruption and allocator layout mismatches by correctly usingCString::from_rawinstead ofBox::from_rawto deallocate memory originally allocated byCString::into_raw. - Eliminated
String::from_raw_partsUB: Completely removed dangerous memory-borrowing patterns that converted C pointers directly into RustStringobjects (which requires specific allocator alignment and layout). Safely replaced this withCStr::from_ptrand idiomatic Rust borrowing (&str), ensuring strict memory safety during FFI interop. - Macro Hardening: Fortified the
set_last_error!macro to safely filter and handle null-bytes within error messages to preventCStringinstantiation panics.
macOS Stack Overflow (SIGTRAP) Resolution
- Fixed a persistent issue where macOS unit tests would crash with
signal: 5, SIGTRAPduring heavy cryptographic operations. - Root Cause: macOS allocates a tiny 512KB default stack for secondary threads (like Rust test threads), which was being overflowed by large elliptic-curve pairing allocations on the stack.
- Resolution: Explicitly configured
RUST_MIN_STACK: 8388608(8MB) in the macOS testing environment, ensuring rock-solid stability for all unit tests across all operating systems.
Full Changelog: v5.1.0...v5.2.0
v5.1.0
Hybrid PQ-CP-ABE Library for Windows/Linux - Version 5.1.0
Note
IMPORTANT NOTICE:
- From Version 4.0, this library natively supports and includes Post-Quantum Cryptography (PQC).
- If your project DOES NOT need PQC (to save space, avoid
liboqsdependencies, or minimize performance overhead), please download and use Version 3.1 from the Releases page.
Overview
This major release introduces the HashiCorp Vault Secrets Engine Plugin, effectively transforming the library into a true Cryptography-as-a-Service platform. It also rolls up all the critical TKN20 scheme bug fixes and the NOT (negation) operator documentation from the 5.0.1 patch.
New Feature: HashiCorp Vault Plugin (Zero-Trust Architecture)
- A completely new Go-based Vault Plugin (
src/go/vault-plugin-abe) has been developed using Cgo to natively wrap the C++ core. - Master Key Isolation: The Master Secret Key (MSK) is now generated and stored entirely within the Vault's secure backend (
msk/abe) during thesetupphase. The MSK never leaves the Vault enclave. - RESTful Endpoints: The plugin exposes four secure endpoints:
/v1/abe/setup,/v1/abe/genkey,/v1/abe/encrypt, and/v1/abe/decrypt. - By delegating all cryptographic operations to Vault, the client applications no longer need to hold or manage the root keys, achieving a true Zero-Trust architecture.
- Comprehensive Python Test Suite: Introduced
src/vault/test_vault.pyto rigorously test the Vault plugin endpoints for bothAC17andTKN20schemes.
New Feature: TKN20 NOT (Negation) Operator
The TKN20 scheme supports the not operator in access policies, enabling negated attribute matching. This is not available in AC17.
How NOT Works in TKN20
Important
not in TKN20 means "attribute must be present with a different value", not "attribute is absent".
Users must always be assigned all relevant attributes with explicit values (e.g., department:hr, department:it).
| Policy | User Attributes | Result |
|---|---|---|
not department:hr |
department:it |
✅ Decrypt OK (it ≠ hr) |
not department:hr |
department:hr |
❌ Decrypt FAIL (hr = hr) |
not department:hr |
(no department attr) |
❌ Decrypt FAIL (attribute absent) |
Usage Examples
Setup & Key Generation:
# Setup TKN20 keys
main.exe setup --scheme tkn20 ./keys
# Admin user (not HR)
main.exe genkey --scheme tkn20 ./keys/cpabe_msk.key "role:admin department:it" ./keys/admin.key
# HR user
main.exe genkey --scheme tkn20 ./keys/cpabe_msk.key "role:hr department:medicine" ./keys/hr.keyEncrypt with NOT policy:
# Only non-HR users can decrypt
main.exe encrypt --scheme tkn20 ./keys/cpabe_pk.key data.txt "not department:hr" data.enc
# Admin can decrypt (department 'it' ≠ 'hr')
main.exe decrypt ./keys/admin.key data.enc recovered.txt # ✅ Success
# HR cannot decrypt (department 'hr' = 'hr')
main.exe decrypt ./keys/hr.key data.enc recovered.txt # ❌ Policy mismatchEnhancements & Optimizations
1. Massive Docker Build Optimization (.dockerignore)
- Identified and fixed a major performance bottleneck where the
docker buildcommand was unnecessarily transferring the entire localsrc/cpp/build/and.git/directories into the Docker daemon context. - Added a precise
.dockerignorefile at the root of the repository. - Impact: The Docker context transfer time dropped from ~30 seconds to <0.1 seconds, and the layer cache is now correctly preserved. Re-running the
test_pluginscripts without C++ source changes is now nearly instantaneous.
2. Port Conflict Resolution in Testing Scripts
- Fixed
test_plugin.ps1andtest_plugin.sh: Removed the-p 8200:8200host port binding from the ephemeralvault-devcontainer launch command. - Testing scripts now map to port
8201(-p 8201:8200), allowing them to run independently without interfering with production or development clusters.
Bug Fixes
Fixed TKN20 CGo Export Directives
- The Go source file
cpabe_tkn20.gohad incorrect export comments (// exportwith a space instead of//export), causingTKN20_Setup,TKN20_KeyGen,TKN20_Encrypt, andTKN20_Decryptto not be exported to C. OnlyTKN20_FreeByteArraywas properly exported. - Impact: On Windows, linking with the TKN20 static archive produced
LNK2019: unresolved external symbolerrors for all TKN20 functions.
Fixed TKN20 NOT Operator Policy Conversion
- The CIRCL TKN20 parser requires
notto be followed by a parenthesized expression (e.g.,not (hr:hr)), butconvertPolicyToTKN20was producingnot hr:hr(without parentheses), resulting in a malformed policy that no attribute set could satisfy. - Added automatic wrapping:
not attr→not (attr)in the policy conversion post-processing step.
Fixed Windows DLL (ELF Mismatch)
- The pre-built
libcpabe_tkn20.dllshipped inlib/dynamic/was actually a Linux ELF binary (.so) renamed to.dll, causing0xc000012f Bad Imageerrors on Windows. - The DLL is now properly built using
go build -buildmode=c-sharedon Windows, producing a valid PE/MZ binary.
Fixed Build Tasks (tasks.json)
- Removed Go static archive (
libcpabe_tkn20.lib) from the MSVC combinedlib.exearchive, which causedLNK1223: invalid .pdataerrors due to Go/MinGW ABI incompatibility with MSVC. - TKN20 is now linked via a MSVC-native import library (generated from
.deffile) + runtime DLL. - Removed broken
copy libcpabe_tkn20.dllstep that referenced a non-existent path.
Quick Start (Vault Integration)
To test the new Vault capabilities, navigate to the Go directory and run the automated script:
Windows:
cd src/go
.\test_plugin.ps1Linux / macOS:
cd src/go
./test_plugin.shTo run the Python validation suite:
cd src/vault
pip install requests
python test_vault.pyFull Changelog: v5.0.1...v5.1.0
v5.0.1
Hybrid PQ-CP-ABE Library for Windows/Linux - Version 5.0.1
Note
IMPORTANT NOTICE:
- From Version 4.0, this library natively supports and includes Post-Quantum Cryptography (PQC).
- If your project DOES NOT need PQC (to save space, avoid
liboqsdependencies, or minimize performance overhead), please download and use Version 3.1 from the Releases page.
Overview
- This patch release fixes critical bugs in the TKN20 scheme, documents its NOT (negation) operator, and improves the Windows build process.
Bug Fixes
Fixed TKN20 CGo Export Directives
- The Go source file
cpabe_tkn20.gohad incorrect export comments (// exportwith a space instead of//export), causingTKN20_Setup,TKN20_KeyGen,TKN20_Encrypt, andTKN20_Decryptto not be exported to C. OnlyTKN20_FreeByteArraywas properly exported. - Impact: On Windows, linking with the TKN20 static archive produced
LNK2019: unresolved external symbolerrors for all TKN20 functions.
Fixed TKN20 NOT Operator Policy Conversion
- The CIRCL TKN20 parser requires
notto be followed by a parenthesized expression (e.g.,not (hr:hr)), butconvertPolicyToTKN20was producingnot hr:hr(without parentheses), resulting in a malformed policy that no attribute set could satisfy. - Added automatic wrapping:
not attr→not (attr)in the policy conversion post-processing step.
Fixed Windows DLL (ELF Mismatch)
- The pre-built
libcpabe_tkn20.dllshipped inlib/dynamic/was actually a Linux ELF binary (.so) renamed to.dll, causing0xc000012f Bad Imageerrors on Windows. - The DLL is now properly built using
go build -buildmode=c-sharedon Windows, producing a valid PE/MZ binary.
Fixed Build Tasks (tasks.json)
- Removed Go static archive (
libcpabe_tkn20.lib) from the MSVC combinedlib.exearchive, which causedLNK1223: invalid .pdataerrors due to Go/MinGW ABI incompatibility with MSVC. - TKN20 is now linked via a MSVC-native import library (generated from
.deffile) + runtime DLL. - Removed broken
copy libcpabe_tkn20.dllstep that referenced a non-existent path.
New Feature: TKN20 NOT (Negation) Operator
The TKN20 scheme supports the not operator in access policies, enabling negated attribute matching. This is not available in AC17.
How NOT Works in TKN20
Important
not in TKN20 means "attribute must be present with a different value", not "attribute is absent".
Users must always be assigned all relevant attributes with explicit values (e.g., department:hr, department:it).
| Policy | User Attributes | Result |
|---|---|---|
not department:hr |
department:it |
✅ Decrypt OK (it ≠ hr) |
not department:hr |
department:hr |
❌ Decrypt FAIL (hr = hr) |
not department:hr |
(no department attr) |
❌ Decrypt FAIL (attribute absent) |
Usage Examples
Setup & Key Generation:
# Setup TKN20 keys
main.exe setup --scheme tkn20 ./keys
# Admin user (not HR)
main.exe genkey --scheme tkn20 ./keys/cpabe_msk.key "role:admin department:it" ./keys/admin.key
# HR user
main.exe genkey --scheme tkn20 ./keys/cpabe_msk.key "role:hr department:medicine" ./keys/hr.keyEncrypt with NOT policy:
# Only non-HR users can decrypt
main.exe encrypt --scheme tkn20 ./keys/cpabe_pk.key data.txt "not department:hr" data.enc
# Admin can decrypt (department 'it' ≠ 'hr')
main.exe decrypt ./keys/admin.key data.enc recovered.txt # ✅ Success
# HR cannot decrypt (department 'hr' = 'hr')
main.exe decrypt ./keys/hr.key data.enc recovered.txt # ❌ Policy mismatchCompound NOT policies:
# Must be admin AND not HR
main.exe encrypt --scheme tkn20 ./keys/cpabe_pk.key data.txt "(role:admin) and not (department:hr)" data.enc
# Either not master, OR (master AND in IT department)
main.exe encrypt --scheme tkn20 ./keys/cpabe_pk.key data.txt "not (role:master) or (role:master and department:it)" data.encChanges Summary
- Fixed
//exportdirectives incpabe_tkn20.go(4 functions were not exported). - Fixed
convertPolicyToTKN20to auto-wrapnot <attr>intonot (<attr>). - Rebuilt
libcpabe_tkn20.dllas a proper Windows PE binary. - Updated
tasks.jsonto use.def-based import lib instead of merging Go objects into MSVC archive. - Updated
lib/README.mdwith corrected TKN20 build instructions.
Full Changelog: v5.0.0...v5.0.1
v5.0.0
Hybrid PQ-CP-ABE Library for Windows/Linux - Version 5.0.0
Note
IMPORTANT NOTICE:
- From Version 4.0, this library natively supports and includes Post-Quantum Cryptography (PQC).
- If your project DOES NOT need PQC (to save space, avoid
liboqsdependencies, or minimize performance overhead), please download and use Version 3.1 from the Releases page.
Overview
- This release introduces an updated implementation of the CP-ABE AC17 (Ciphertext Policy Attribute-Based Encryption) scheme, now integrated with the AES-GCM-256 symmetric encryption algorithm AND ML-DSA-87 Post-Quantum Signatures.
- The main objective of this update is to combine the flexible access control of CP-ABE with the high-performance encryption of AES-GCM-256, and protect data integrity/authentication against quantum adversaries using
liboqs.
Key Features
Post-Quantum Hybrid Encryption:
- Seamlessly append
--pqcto the CLI to encrypt data with AES-GCM, manage access with CP-ABE, and sign the ciphertext using quantum-safe ML-DSA-87 signatures. - Prevents tampering and ensures sender authenticity even against future quantum computers.
Optimized Performance:
- The AES-GCM-256 encryption ensures fast and secure encryption of large data files.
- The AC17 and TKN20 schemes allow for more flexible encryption policies and fine-grained control over who can access the encrypted content.
Ultimate Multi-OS Build:
- A unified
tasks.jsonautomatically detects the OS and builds seamlessly on Windows (MSVC) or Linux (g++).
Changes in This Release
- Added support for TKN20 scheme alongside AC17.
- Added Post-Quantum Signatures (ML-DSA-87 via
liboqs). - Unified executable
mainsupporting both standard mode and--pqcmode with--schemeselector. - Renamed library to
libhybrid-pq-cp-abeto reflect the new architecture. - Removed legacy CLI arguments and improved parsing.
Full Changelog: v4.0.0...v5.0.0
v4.0.0
Hybrid PQ-CP-ABE Library for Windows/Linux - Version 4.0.0
Note
IMPORTANT NOTICE:
- From Version 4.0, this library natively supports and includes Post-Quantum Cryptography (PQC).
- If your project DOES NOT need PQC (to save space, avoid
liboqsdependencies, or minimize performance overhead), please download and use Version 3.1 from the Releases page.
Overview
- This release introduces an updated implementation of the CP-ABE AC17 (Ciphertext Policy Attribute-Based Encryption) scheme, now integrated with the AES-GCM-256 symmetric encryption algorithm AND ML-DSA-87 Post-Quantum Signatures.
- The main objective of this update is to combine the flexible access control of CP-ABE with the high-performance encryption of AES-GCM-256, and protect data integrity/authentication against quantum adversaries using
liboqs.
Key Features
Post-Quantum Hybrid Encryption:
- Seamlessly append
--pqcto the CLI to encrypt data with AES-GCM, manage access with CP-ABE, and sign the ciphertext using quantum-safe ML-DSA-87 signatures. - Prevents tampering and ensures sender authenticity even against future quantum computers.
Optimized Performance:
- The AES-GCM-256 encryption ensures fast and secure encryption of large data files.
- The AC17 scheme allows for more flexible encryption policies and fine-grained control over who can access the encrypted content.
Ultimate Multi-OS Build:
- A unified
tasks.jsonautomatically detects the OS and builds seamlessly on Windows (MSVC) or Linux (g++).
Changes in This Release
- Added Post-Quantum Signatures (ML-DSA-87 via
liboqs). - Unified executable
mainsupporting both standard mode and--pqcmode. - Renamed library to
libhybrid-pq-cp-abeto reflect the new architecture. - Removed legacy CLI arguments and improved parsing.
Download
- Linux:
libhybrid-pq-cp-abe_linux_x86_64_v4.0.0.zip - Windows:
libhybrid-pq-cp-abe_win_x86_64_v4.0.0.zip
What's Changed
- Feature/hybrid pqc abe by @WanThinnn in #1
New Contributors
- @WanThinnn made their first contribution in #1
Full Changelog: v3.1.0...v4.0.0
v3.1.0
Hybrid CP-ABE Library for Windows/Linux - Version 3.1.0
Overview
- This release introduces an updated implementation of the CP-ABE AC17 (Ciphertext Policy Attribute-Based Encryption) scheme, now integrated with the AES-GCM-256 symmetric encryption algorithm.
- The main objective of this update is to combine the flexible access control of CP-ABE with the high-performance encryption of AES-GCM-256, providing a more secure and efficient solution for data encryption.
Key Features
Hybrid Encryption:
- We use the CP-ABE AC17 scheme to encrypt a very big random symmetric key, which is then used SHA3-256 to hash it for 256-bits AES key.
- This approach leverages the access control mechanism of CP-ABE for key management and the high-speed, secure data encryption provided by AES-GCM-256.
Optimized Performance:
- The AES-GCM-256 encryption ensures fast and secure encryption of large data files.
- The AC17 scheme allows for more flexible encryption policies and fine-grained control over who can access the encrypted content.
Secure Encryption & Decryption:
- Encrypted data is protected by both the strength of AES-GCM-256 and the attribute-based access control of CP-ABE.
- The decryption process ensures that only users with the correct attribute-based keys can retrieve the AES encryption key and decrypt the data.
Changes in This Release
- Support buffer encryption/decryption.
- Now supports Linux!
- New name: Hybrid CP-ABE.
- Support large input files.
- The source code is now more secure.
- Added full support for hybrid encryption: combining CP-ABE AC17 and AES-GCM-256 for enhanced security and efficiency.
- Improved error handling and debug information to help identify issues during encryption and decryption processes.
- Code refactoring to separate CP-ABE encrypted keys and AES-GCM encrypted data, ensuring proper decryption in various environments.
Download
- Linux:
libhybrid-cp-abe_linux_x86_64_v3.1.0.zip - Windows:
libhybrid-cp-abe_win_x86_64_v3.1.0.zip
Full Changelog: v3.0.0...v3.1.0