KCAPI_AEAD_STREAM_IN(3)

💖 KCAPI_AEAD_STREAM_IN 💖

okay bestie, welcome to the <pink>libkcapi</pink> corner of the manual — this one's kcapi_aead_stream_init_enc(3) and it's literally the moment your encryption era begins. ✨

---

🌸 NAME 🌸

kcapi_aead_stream_init_enc — start an encryption operation (stream) 🫶

---

🎀 SYNOPSIS 🎀

ssize_t kcapi_aead_stream_init_enc(struct kcapi_handle * handle,
                                   const uint8_t * iv,
                                   struct iovec * iov, size_t iovlen);

---

✨ ARGUMENTS ✨

• handle — [in] the cipher handle. your main character, your plus-one, your whole vibe. 💅
• iv — [in] the IV to be used for the cipher operation. 🔑
• iov — [in] the scatter/gather list holding the data you wanna encrypt. if you're passing an array of iov entries, this here is the pointer to the first one. peek at sendmsg(2) for the whole tea on how iov is meant to be used. and lowkey? this pointer can be NULL if you've got no data to encrypt at the moment of the call — no data, no problem, it's giving "showing up empty-handed but cute". 🙈
• iovlen — [in] how many scatter/gather list elements there are. and heads up: if iov is NULL, this value must be zero. not one, not "ehh close enough", zero. 🫠

---

🦋 DESCRIPTION 🦋

A stream encryption operation gets started right here with this call. no cap. Then you can hit up kcapi_aead_stream_update multiple times in a row to send more plaintext over to be encrypted. 🌈

The kernel holds onto that input and buffers it until kcapi_aead_stream_op comes through and picks up the encrypted data. And the moment plaintext gets encrypted during kcapi_aead_stream_op? bestie, it's gone — removed from the kernel buffer. poof. 💀

⚠️ NOT me mixing things up — unlike the corresponding symmetric cipher API, the function calls of kcapi_aead_stream_update and kcapi_aead_stream_op cannot be mixed! periodt. this is just the nature of AEAD being AEAD: the cipher operation is out here ensuring the integrity of the entire data (that's decryption) or calculating a message digest over the entire data (that's encryption). it's an all-or-nothing situation and honestly? iconic. 👑

When you're using the stream API, the caller has to make sure data goes in the correct order — doesn't matter whether you're sending data in multiple chunks via kcapi_aead_stream_init_enc or kcapi_cipher_stream_update:

1. the complete associated data must be provided first,
2. and then the plaintext.

in that order. no skipping ahead, no shuffling. ✋

The IV buffer must be exactly kcapi_cipher_ivsize bytes in size. exactly exactly. 📏

And what do you get back? the number of bytes sent to the kernel upon success; or a negative errno-style error code if something went wrong. 😭

---

💜 AUTHOR 💜

Stephan Mueller <smueller@chronox.de> — Author. 🫡

---

🌟 COPYRIGHT 🌟

libkcapi Manual 1.5.0 — July 2025 — KCAPI_AEAD_STREAM_IN(3)

---

and that's the whole page, bestie! 🎀 go forth, init that stream, and may all your errno values be non-negative. mwah. 💖✨🦋🌸💅