argon2-cffi-bindings

argon2-cffi-bindings provides low-level CFFI bindings to the official C implementation of the Argon2 password-hashing algorithm. It vendors the P-H-C/phc-winner-argon2 reference implementation as a git submodule, compiles it with CMake and scikit-build-core into a private _argon2_cffi_bindings extension module, and exposes the compiled ffi and lib objects for direct calls into argon2_hash, argon2_verify, and the raw argon2_ctx API.

The package is explicitly not meant for application developers hashing passwords directly — its README redirects that use case to argon2-cffi, which consumes these bindings as its compiled backend. Instead, it targets integrators who need raw access to Argon2’s C API: other libraries building their own password-hashing abstractions, packagers linking against a system-installed libargon2 via ARGON2_CFFI_USE_SYSTEM, or cross-compilation and WASM (Pyodide) pipelines that need fine control over build flags like SSE2 detection.

What You Get

• A vendored copy of the official P-H-C/phc-winner-argon2 C implementation, built via a git submodule so there’s no separate system install required by default
• Prebuilt wheels across CPython (stable ABI, cp310+), PyPy, and Pyodide/WASM targets, published via cibuildwheel
• Direct low-level access to argon2_hash, argon2_verify, and argon2_ctx through CFFI’s generated ffi and lib objects
• Build-time environment toggles (ARGON2_CFFI_USE_SYSTEM, ARGON2_CFFI_USE_SSE2) for linking a system Argon2 or overriding SIMD codegen when cross-compiling

Common Use Cases

• Serving as the compiled backend that argon2-cffi imports for its high-level PasswordHasher API
• Building custom password-hashing or key-derivation tooling that needs raw Argon2 primitives without writing a bespoke CFFI layer
• Linux distro or enterprise packaging pipelines that set ARGON2_CFFI_USE_SYSTEM=1 to link an already-packaged libargon2 instead of vendoring another copy
• Cross-compilation and Pyodide/WASM builds that rely on the SSE2 override and Pyodide-specific cibuildwheel targets to produce compatible wheels

Under The Hood

Architecture This package is almost entirely a build pipeline rather than a Python codebase: CMakeLists.txt drives python_add_library to compile a single _ffi extension from a checked-in _ffi.c, which is itself generated ahead of time from _ffi.cdef.txt and _ffi.csrc.c via CFFI’s out-of-line API-mode generator (regenerated with tox -e gen, not at install time, so PyPy builds don’t need cffi-gen-src). By default the build links against a vendored git submodule of the official Argon2 C source under extras/libargon2; setting ARGON2_CFFI_USE_SYSTEM=1 instead links a system-installed libargon2, and ARGON2_CFFI_USE_SSE2 overrides the automatic SIMD-architecture detection used for cross-compiling. At runtime, src/_argon2_cffi_bindings/__init__.py is a two-line facade that re-exports ffi and lib from the compiled extension — there is no application logic in Python, so the real “architecture” decisions (what gets compiled, how, and against which Argon2 copy) live entirely in the CMake/CFFI build graph, and changing the CFFI declarations changes every downstream consumer’s compiled ABI.

Tech Stack The build backend is scikit-build-core, which wraps CMake (3.20+) behind PEP 517 hooks; the resulting extension targets CPython’s stable ABI (cp310) where possible to minimize the wheel matrix. The only runtime Python dependency is cffi (>=1.0.1, or >=2 on Python 3.14+). cibuildwheel (using uv as its build frontend) publishes wheels for CPython, PyPy, and Pyodide/WASM targets, including prerelease and EOL PyPy builds. Development tooling includes tox for orchestrating generation/testing/doc-cogging environments, ruff with select = ["ALL"] for linting, pre-commit hooks, and interrogate for docstring-coverage enforcement on test files.

Code Quality The only test is tests/test_smoke.py, a single smoke test asserting that the compiled ffi/lib objects import correctly and that a known Argon2 constant and a deterministic argon2_encodedlen call return expected values — appropriate given that the actual hashing logic lives in the upstream, separately-tested Argon2 C library rather than in this package’s own code. pytest is configured with --strict-markers, --strict-config, and xfail_strict, and ruff’s full rule set (ALL, with a short documented ignore list) is applied across src and tests. There is no Python-level type checking beyond CFFI’s own type-annotated C declarations, which is consistent with the package containing almost no Python logic to type-check.

API Design The public surface is deliberately tiny and explicitly discouraged from casual use: it’s exposed under a leading-underscore private module name (_argon2_cffi_bindings) specifically to signal “implementation detail, not a stable public API,” and the README redirects application developers to argon2-cffi’s higher-level interface instead. The two names it does export, ffi and lib, follow standard CFFI conventions, so anyone familiar with CFFI already understands the shape of the API, and the actual function surface (argon2_hash, argon2_verify, argon2_ctx) mirrors the upstream C header rather than inventing new naming. Getting started requires only one import line, but using it correctly still requires understanding CFFI’s ffi/lib object model, which this package’s own docs don’t teach — they point to CFFI’s documentation instead.