ffl-mbedtls

Focused CPython bindings for Mbed TLS 3.6.7, providing only the crypto operations FastFileLink uses:

• Secure random bytes, P-384 ECDSA/SHA-256 signing, and P-384 ECDH
• HKDF-SHA256, AES-CBC with PKCS#7 padding, and AES-GCM with 16-byte tags
• RSA generation, RSA-OAEP/SHA-256, PEM normalization, and PKCS#8 output

The native module is _ffl_mbedtls; its public object-oriented facade is ffl_mbedtls.CryptoEngine.

Scope

This is a direct replacement for the subset of python-mbedtls used by FastFileLink. It deliberately does not offer generic cipher object graphs, Python representations of MPI/ECP internals, or compatibility APIs unrelated to that integration.

Architecture

FastFileLink MbedTLS.py
        |
        v
ffl_mbedtls.CryptoEngine
        |
        v
_ffl_mbedtls (CPython C adapter)
        |
        v
crypto_core.c
        |
        v
Mbed TLS 3.6.7 / libmbedcrypto

native/crypto_core.c owns cryptographic sequencing, Mbed TLS contexts, secret zeroization, and key serialization. native/python_module.c performs only CPython argument conversion, GIL release, exception handling, and native buffer-to-bytes conversion. CryptoEngine owns the Python-facing contract and input validation. Protocol-specific behavior, such as voucher pre-hashing and ECIES payload composition, remains in FastFileLink's MbedTLS.py layer.

Build with bundled Mbed TLS

python scripts/bootstrap.py
python -m pip install build
python -m build --wheel

bootstrap.py clones the exact mbedtls-3.6.7 tag into third_party/mbedtls. The C extension checks the Mbed TLS major, minor, and patch version at compile time and rejects any version other than 3.6.7.

Build with system Mbed TLS

Install Mbed TLS 3.6.7 first, then build against it:

CMAKE_ARGS="-DFFL_MBEDTLS_PROVIDER=system" python -m build --wheel

For an ordinary CMake build, provide its installation prefix:

cmake -S . -B build \
  -DFFL_MBEDTLS_PROVIDER=system \
  -DCMAKE_PREFIX_PATH="$COSMOS"

For Cosmopolitan/APE, compile native/crypto_core.c and native/python_module.c directly into CPython and link them once to the common Mbed TLS 3.6.7 crypto archive. A shared superconfigure installation can serve both ffl_mbedtls and libdatachannel; libdatachannel additionally needs its DTLS-SRTP option enabled, while this package needs only libmbedcrypto.

FastFileLink migration

1. Build and install ffl-mbedtls.
2. Replace FastFileLink's existing MbedTLS.py with integration/MbedTLS.py.
3. Remove python-mbedtls, _mbedtls_hkdf, and their build dependencies.
4. Run crypto compatibility tests before removing the old package from release builds.

The replacement retains the MbedTLSBackend surface, reports its name as ffl-mbedtls, and adds decryptData() and derivePublicKeyFromPrivate().

Test

python -m pip install -e ".[dev]"
pytest -q

The test suite exercises the compiled extension's P-384 signing/ECDH, HKDF, AES-CBC/GCM, RSA-OAEP, and PKCS#8 serialization behavior.