Building a Python CLI for the Linux Kernel Crypto API
Building a Python-based command-line interface to the Linux kernel's Crypto API starts with an important boundary: most crypto functions live inside the kernel and are not a general user-space ABI. A practical tool should target AF_ALG, the kernel's user-space socket interface, instead of calling internal symbols or guessing private ioctl structures. Python can then act as a thin, testable front end to available hashing, cipher, and compression algorithms.
The finished program should feel like a normal Unix utility rather than a kernel demo. It should discover available algorithms, stream data without loading whole files, separate machine-readable results from diagnostics, and fail clearly when privileges, keys, or kernel features are missing. That approach also makes the project attractive to Australian teams that prefer self-hosted tools and keep sensitive material in their own environments.
Why the kernel crypto layer is worth wrapping
The Crypto API centralises algorithm implementations behind common kernel interfaces. It offers hashes, symmetric ciphers, compression primitives, and random data through modules that administrators can inspect, configure, and replace without rewriting every caller.
Its catalogue is dynamic. A distribution may ship different modules, enable options under different kernel configuration names, and expose driver-specific implementations. Even two machines running the same distribution can therefore report different algorithms and limits.
The wrapper's job is to turn that variability into a predictable command contract. It should disclose what is available, avoid assuming hardware acceleration, and return a precise error when a requested algorithm cannot run.
Choosing a safe user-space boundary
AF_ALG gives user space a socket-based route to hash and symmetric-key operations. A hash socket accepts a stream and returns a digest; a cipher socket can receive a key, an initialisation vector, and data blocks through documented kernel interfaces.
In Python, the client can use socket.AF_ALG where the runtime exposes it, with a capability check at startup. /proc/crypto remains useful for discovery, but it is not a substitute for performing operations. This avoids fragile ctypes structures tied to private kernel code.
Compatibility deserves deliberate testing. A developer in Sydney, Melbourne, or Canberra may encounter several Ubuntu LTS images and current upstream kernels, so feature detection and a documented support matrix matter more than optimistic assumptions about every host.
Two layers of command design
Command design works best when inspection is separated from data transformation. Discovery commands should be safe to run anywhere, while operational commands should make key sources, output formats, and overwrite behaviour explicit.
Discovery commands
inforeports the kernel version, AF_ALG availability, and loaded crypto modules.algorithmsfilters the crypto catalogue by type, name, or driver.selftestruns a small known-answer check before operational use.
Data commands
hashstreams a file or standard input into a digest.encryptcreates a versioned, authenticated container using a named symmetric algorithm.decryptvalidates a container's authentication tag before releasing plaintext.verifycompares a computed digest with an expected value.
All commands should use consistent exit statuses: success, a general runtime failure, invalid usage, and a distinct code for an unavailable algorithm or unsupported kernel feature. Requested data belongs on standard output, while diagnostics belong on standard error, allowing the CLI to compose safely with pipes and scripts.
Implementing commands in Python
Use argparse with nested subparsers, then move validated values into dataclasses rather than passing loose dictionaries through the code. A --json option can provide stable fields for automation, while the default format remains readable in a terminal. This is particularly useful in Ansible tasks and CI jobs.
Keep AF_ALG behind a small transport module with methods such as available_algorithms(), hash_stream(), and transform(). Higher-level commands can then validate inputs and choose output formats without depending on socket details. Mocking that boundary makes most command tests fast and independent of kernel configuration.
Process files in bounded chunks rather than reading an entire video, archive, or disk image into memory. Hashing can update incrementally, while symmetric operations require careful handling of block boundaries and the final partial block. Binary output should remain binary, with text added only when the selected output format calls for it.
Handling failures, secrets, and permissions
Failures should be classified close to their source. An unsupported algorithm, malformed container, incorrect key length, unavailable AEAD mode, and permission error require different messages and exit codes. Full exception traces can be offered through a diagnostic flag, but ordinary failures should remain concise and actionable.
Key handling needs more care than encryption itself. Keys must never be accepted as command-line arguments because process listings and shell history can expose them. Read them from a protected file, a file descriptor, or standard input, reject unexpectedly permissive files, and release references promptly. Python cannot guarantee complete memory zeroisation, so the documentation should not imply otherwise.
Authenticated encryption must verify its tag before any plaintext is returned, and nonce generation must prevent reuse with the same key. Keys and plaintext should also be excluded from logs. The Australian Cyber Security Centre's emphasis on protecting sensitive information makes these controls particularly important for Australian organisations deploying the tool locally.
Testing across real Linux environments
Start with fast unit tests around argument parsing, container serialisation, error mapping, and output formatting. Known-answer vectors then check the crypto layer, including SHA-256 inputs and an AEAD mode supported by the target kernel. Tests should cover empty input, large files, unusual filenames, broken pipes, and interrupted standard input.
Integration tests should run against real AF_ALG sockets across several Ubuntu LTS releases and current upstream kernels. They can inspect /proc/crypto to skip algorithms that are genuinely unavailable while still verifying the rest of the command contract. A CI matrix should also cover the supported Python versions and both little-endian and big-endian builds where practical.
Australian environments add useful edge cases. Daylight-saving changes between AEST and AEDT can expose poor timestamp handling, so diagnostics should store UTC and label any local conversion. Locale tests can catch accidental assumptions about number formatting or case conversion. Documentation should also use Australian English, including terms such as “licence” for a permission document and “analyser” for a reporting tool.
Releasing and maintaining the project
Package the CLI with pipx for individual use and provide a Debian package for managed Linux installations. Include clear versioning, a changelog, SPDX licence identifiers, example command output, and a stated kernel and Python support policy. A machine-readable JSON schema can make integrations more stable than informal parsing of human-readable output.
For Australian small businesses and public-sector buyers, a self-hosted package with transparent licensing and reproducible releases can be easier to adopt than a hosted service with recurring data-transfer or subscription requirements. Clear documentation around keys, backups, upgrades, and audit logs helps internal teams assess the software without relying on marketing claims.
The reporting approach used by the Scratchy log analyser offers a useful open-source model: terse summaries, practical filters, and deeper detail available when needed. A crypto CLI benefits from the same discipline, presenting only the requested result while preserving dependable diagnostics. That combination of a narrow interface, explicit failure modes, and reproducible releases gives the tool a realistic place in day-to-day Linux administration.
