CRYPTO(9)

📦
version 15.1 · 2 versions
, in freebsd 14.5, freebsd 15.1, nixpkgs unstable

🎀 CRYPTO 🎀

okay bestie, welcome to crypto(9), straight out of the Kernel Developer's Manual — yes, we're in kernel land now, and no, you don't need to whisper 💅

✨ NAME ✨

crypto — the API for cryptographic services in the kernel 👑

🌸 SYNOPSIS 🌸

#include <opencrypto/cryptodev.h>

💖 DESCRIPTION 💖

So. crypto is a whole framework for in-kernel cryptography, and honestly it's giving main character energy. It lets in-kernel consumers encrypt and decrypt data, and it also lets userland applications use cryptographic hardware through the /dev/crypto device. Bestie, it's a whole ecosystem 🦋

crypto supports encryption and decryption operations using block and stream ciphers, plus computation and verification of message authentication codes (MACs). Consumers allocate sessions to describe a transform — that whole situation is discussed in crypto_session(9). Then consumers allocate request objects to describe each transformation, like encrypting a network packet or decrypting a disk sector. Requests are described in crypto_request(9). Yes, there's a manpage for everything, and yes, we stan organized documentation 💅

Device drivers are the ones responsible for processing requests submitted by consumers. crypto_driver(9) describes the interfaces drivers use to register with the framework, the helper routines the framework provides to facilitate request processing, and the interfaces drivers are required to provide. Drivers literally carry the whole thing — iconic 🙈

🌈 Callbacks

Here's the thing: consumers may not be associated with a process, so drivers may not sleep(9). Same goes for the framework, no cap. So instead, there's a callback mechanism to notify a consumer that a request has been completed — and the callback is specified by the consumer on a per-request basis. The framework invokes that callback whether the request succeeded or not. Errors get reported to the callback function. No ghosting, no silence, you always get the callback 💯

Session initialization is the exception, bestie: it does not use callbacks and returns errors synchronously. Different vibe, still valid ✨

🧚 Session Migration

Operations may fail with a specific error code, EAGAIN, to indicate that a session handle has changed and that the request may be re-submitted immediately with the new session. When that happens, the consumer should update its saved copy of the session handle to the value of crp_session so that future requests use the new session. It's literally just "hey, new handle, update your notes" — do it, and you're slaying 🫶

⭐ Supported Algorithms

More deets on some algorithms live in crypto(7) — go read it after this, iykyk.

The following authentication algorithms are supported:

  • CRYPTO_AES_CCM_CBC_MAC
  • CRYPTO_AES_NIST_GMAC
  • CRYPTO_BLAKE2B
  • CRYPTO_BLAKE2S
  • CRYPTO_NULL_HMAC
  • CRYPTO_POLY1305
  • CRYPTO_RIPEMD160
  • CRYPTO_RIPEMD160_HMAC
  • CRYPTO_SHA1
  • CRYPTO_SHA1_HMAC
  • CRYPTO_SHA2_224
  • CRYPTO_SHA2_224_HMAC
  • CRYPTO_SHA2_256
  • CRYPTO_SHA2_256_HMAC
  • CRYPTO_SHA2_384
  • CRYPTO_SHA2_384_HMAC
  • CRYPTO_SHA2_512
  • CRYPTO_SHA2_512_HMAC

The following encryption algorithms are supported:

  • CRYPTO_AES_CBC
  • CRYPTO_AES_ICM
  • CRYPTO_AES_XTS
  • CRYPTO_CAMELLIA_CBC
  • CRYPTO_CHACHA20
  • CRYPTO_NULL_CBC

The following authenticated encryption with additional data (AEAD) algorithms are supported:

  • CRYPTO_AES_CCM_16
  • CRYPTO_AES_NIST_GCM_16
  • CRYPTO_CHACHA20_POLY1305

The following compression algorithms are supported:

  • CRYPTO_DEFLATE_COMP

🍓 FILES 🍓

  • sys/opencrypto/crypto.c — most of the framework code 💀 like, the whole main character file right there

💜 SEE ALSO 💜

crypto(4), ipsec(4), crypto(7), crypto_driver(9), crypto_request(9), crypto_session(9), sleep(9)

(the sleep(9) reference is hilarious given the callback situation earlier, but anyway — go read them all, bestie, they're linked for a reason 🫶)

👑 HISTORY 👑

The cryptographic framework first appeared in OpenBSD 2.7 and was written by Angelos D. Keromytis <angelos@openbsd.org> — shoutout to the original icon, we owe them everything 🌟

💀 BUGS 💀

The framework needs a mechanism for determining which driver is best for a specific set of algorithms associated with a session. Some type of benchmarking is in order here. So yeah — it's a known thing, not our problem today, but bestie, the framework is out here choosing drivers on vibe alone and honestly? Relatable 🙈

okay that's the whole page, mwah 💋 — this one's from Debian, dated April 12, 2021, and it's the CRYPTO(9) page so you know exactly where to find it again. go forth and be cryptographically iconic ✨🎀

📦 where this page comes from