BaseFWX 3.7.0 release notes

Release status: loader + wire tag implemented on main (2026-06-26). Tag and publish only after remote test_all.sh passes.

Headline (when shipped): blackbox plugin in production encrypt/decrypt through basefwx fwxaes-enc/dec --plugin … plus audit-driven hardening from the 3.6.5 queue. Callers ship a .so / .dll driver that wraps the AEAD payload — open-source crypto core, closed-source obfuscation layer.

3.6.x → 3.7.0 is backwards-compatible on the wire for blobs without a plugin tag. Plugin-tagged blobs (algo=0x03) require 3.7.0+ and the matching plugin loaded at decrypt time.

Plugin (blackbox) core — what’s in 3.7.0 vs queued

3.7.0 ships the complete ABI surface — the C ABI header (plugin.h), the C++ helper layer (plugin.hpp) with two macro variants for Profile-A (BASEFWX_PLUGIN_DEFINE) and Profile-B (BASEFWX_PLUGIN_DEFINE_KEYED), the static-embed Registry (plugin_static.hpp), and five example plugins covering all three usage profiles:

examples/plugins/THREAT_MODEL.md is the authoritative document for what each profile defends against. The short version: a deterministic plugin is fine for traffic-shaping inside an AEAD layer (Profile A); a keyed plugin with host_secret

• per-call tweak is required for raw-mode use without AEAD wrapping (Profile B); static embedding is a deployment choice that raises the cost of plugin extraction but does not provide cryptographic security on its own (Profile C).

What is in 3.7.0: everything above plus the C++ host loader (cpp/src/plugin/plugin_loader.cpp), fwxAES PRE/POST AEAD integration in C++ / Java / Python, the wire-format plugin tag, CLI --plugin flags, and an fwxAES round-trip step in scripts/plugin-smoke.sh.

Example (C++ CLI, xor-rotate plugin, PRE_AEAD):

# 32-byte plugin config (xor-rotate requires exactly 32 bytes)
python3 -c 'open("xor.cfg","wb").write(bytes([0x42^i for i in range(32)]))'

basefwx fwxaes-enc secret.txt -p 'your-password' \
  --legacy-pbkdf2 --no-master \
  --plugin /path/to/libbasefwx-xor-rotate.so \
  --plugin-pos pre --plugin-config xor.cfg \
  -o secret.fwx

basefwx fwxaes-dec secret.fwx -p 'your-password' --no-master \
  --plugin /path/to/libbasefwx-xor-rotate.so \
  -o secret.plain

What is NOT in 3.7.0 and is scoped for 3.7.x point releases: plugin integration in b512file / pb512file / livecipher, streaming fwxAES with plugins, the JNI bridge for native .so from Java, Profile B parity on the Java/Python SPI, and the basefwx-plugin-verify tool.

fwxAES plugin wire tag (algo 0x03)

Immediately after the 16-byte FWX1 fixed header:

Then the usual salt/key_header, IV, and AES-GCM ciphertext follow. Blobs with algo=0x01 or 0x02 are unchanged from 3.6.4.

Wire format without a plugin tag is unchanged from 3.6.x.

TL;DR (security/hardening track)

Integrator / API changes

The full security-policy stance lives in SECURITY.md; this document focuses on what changed in 3.7.0 and what it costs.

1. Compatibility

• Blob format unchanged. Anything you encrypted with 3.6.4 (PBKDF2 or Argon2id, password or wrap, any algorithm tier) decrypts unchanged in 3.7.0, including with a BASEFWX_USER_KDF override. The bounds tightening only rejects pathological values (iteration counts < 10 000, wrap-header > 64 KiB) that no legitimate writer ever produced.
• Old pre-3.x blobs that relied on the silent PBKDF2-32k fallback during decryption no longer decrypt. Those formats were marked “≤ 2.7: Treat as incompatible” in SECURITY.md since 3.x; this release enforces that line.
• CLI / API behavior changes that may affect existing callers:
  • --password "/some/path" no longer reads the file — pass --password "file:///some/path" instead, or the literal string with --password "password://literal".
  • BASEFWX_MASTER_PQ_ALLOW_BAKED=1 is no longer recognized. Deployments that previously relied on it must either:
    • configure their own runtime key with BASEFWX_MASTER_PQ_PUB=<path>, or
    • rebuild with -DBASEFWX_MASTER_PQ_PUB_B64=<base64-key> (C++) / -Dbasefwx.master.pq.public.b64=<base64-key> (Java sysprop).
  • BASEFWX_MASTER_EC_CREATE_IF_MISSING=1 is no longer recognized. Provision the EC master keypair out-of-band and point BASEFWX_MASTER_EC_PUB / BASEFWX_MASTER_EC_PRIV at it.
  • BASEFWX_TEST_KDF_ITERS is no longer honored in release builds. The test suite builds with -DBASEFWX_TESTING=ON (C++) and runs Java with -Dbasefwx.testing=true to keep its fast-path.

2. Why this is 3.7.0 and not 3.6.5

The security-fix track is byte-compatible with 3.6.4. On its own it would have been 3.6.5 (and was, in working trees, briefly). The blackbox plugin core changes the calculus — it’s a new optional wire-format layer that callers can opt into, with a non-trivial public ABI (basefwx/plugin.h) that other people will compile against. That’s the right thing to gate behind a minor bump.

The ABI lands in 3.7.0 along with Java SPI and Python ctypes (Profile A); the runtime loader inside CLI/fwxAES, wire-format plugin tags, verifier tool, and JNI bridge land in 3.7.x point releases — held back deliberately so the header gets a review window before any code commits to it. Blobs that don’t opt into the plugin layer remain byte-identical to 3.6.4.

3. Provenance

This release was driven by a code-audit pass against the C++ and Java trees. The audit findings, their severity ratings, and the rationale for each fix are recorded in the git history; the audit document itself lives outside the repository.

Upgrade

Standard roll-forward — install 3.7.0 over 3.6.4, no migration step.

If you depended on:

• The --password <path> auto-load: replace with --password file://<path>.
• The baked master public key: configure your own via env or build-time option (see TL;DR).
• The BASEFWX_MASTER_EC_CREATE_IF_MISSING auto-generation: provision the EC keypair manually.
• The PBKDF2-32k decryption fallback: re-encrypt affected blobs with the current defaults; 32k-iter blobs are pre-3.x and out of the supported window.