KCAPI_AEAD_DECRYPT(3)

🌸 NAME 🌸

kcapi_aead_decrypt — bestie, this is the one that synchronously decrypts your AEAD data in a single shot. one and done, no cap ✨

---

✨ SYNOPSIS ✨

ssize_t kcapi_aead_decrypt(struct kcapi_handle * handle,
                           const uint8_t * in, size_t inlen,
                           const uint8_t * iv, uint8_t * out,
                           size_t outlen, int access);

---

🎀 ARGUMENTS 🎀

• handle — [in] your cipher handle, the main character of this whole operation 💅
• in — [in] the ciphertext data buffer, aka the locked little secret we're about to crack open
• inlen — [in] how long the in buffer is
• iv — [in] the IV that gets used for the cipher operation
• out — [out] the plaintext data buffer, where the truth comes out 🦋
• outlen — [in] how long the out buffer is
• access — [in] the kernel access type, pick your fighter:
  • KCAPI_ACCESS_HEURISTIC — use the internal heuristic to find the fastest kernel access 🔥
  • KCAPI_ACCESS_VMSPLICE — use vmsplice access
  • KCAPI_ACCESS_SENDMSG — use sendmsg access

---

💖 DESCRIPTION 💖

okay so, AEAD is not like the other ciphers — it wants its associated authentication data, like it literally requires you to furnish it. and if you don't need that data at all? no problem, set it to NULL and the length value must be set to zero. that's the rule, periodt.

and here's the gag: it is perfectly legal to use the same buffer for both the plaintext and the ciphertext pointers. so what that means is — after the encryption operation, the ciphertext is overwritten with the plaintext. same buffer, glow-up complete 💫

now, the memory? it should be aligned at the page boundary using posix_memalign(sysconf(_SC_PAGESIZE)). because if it's not aligned at the page boundary, the vmsplice call may not send all of your data to the kernel. and we do NOT want half your data just ghosting the kernel, bestie 😭

also the iv buffer must be exactly kcapi_cipher_ivsize bytes in size. exactly. not a byte more, not a byte less, iykyk.

and to catch authentication errors (aka integrity violations, the sneaky ones) during decryption, you gotta check the return value of this call. if this function returns -EBADMSG, an authentication error was detected. that's your red flag, do not ignore it 🚩

---

👑 IMPORTANT NOTE 👑

the kernel will only process sysconf(_SC_PAGESIZE) * ALG_MAX_PAGES at one time. longer input data cannot be handled by the kernel. like, it literally cannot, so don't try it 💀

and the return? on success you get the number of bytes decrypted back. if something went wrong, you get a negative errno-style error code instead. that's it, that's the tea 🍓

---

🌈 AUTHOR 🌈

• Stephan Mueller <smueller@chronox.de> — Author. we stan 👑

---

💜 COPYRIGHT 💜

that's the whole page bestie, hope it slayed for you 🫶✨ this was the libkcapi Manual, version 1.5.0, dated July 2025 — and that's the vibe check, we're done here 🎀