KCAPI_CIPHER_STREAM_(3)

💖 kcapi_cipher_stream_update — send more data for processing (stream) 💖

okay bestie, so this is the tea on kcapi_cipher_stream_update from the libkcapi manual page (KCAPI_CIPHER_STREAM_(3)), and honestly? she's a whole mood. let's get into it ✨

---

🌈 SYNOPSIS 🌈

ssize_t kcapi_cipher_stream_update(struct kcapi_handle * handle,
                                   struct iovec * iov, size_t iovlen);

that's the whole flex. three args, one ssize_t coming back at you. slay 💅

---

🎀 ARGUMENTS 🎀

• handle — [in] the cipher handle, aka your girl. she's the one holding the cipher state.
• iov — [in] a scatter/gather list stuffed with the data that the cipher operation is gonna chew through. yes, a scatter/gather list. very ✨sophisticated✨ of you.
• iovlen — [in] how many elements are in that scatter/gather list. count them. no, literally.

---

🦋 DESCRIPTION 🦋

so with this function call you can hand MORE plaintext over for encryption, or MORE ciphertext over for decryption, and the kernel will take it from there. that's it. that's the whole job. lowkey iconic 🫶

heads up though: this function may cause the caller to sleep if the kernel buffer holding the data is getting full. not a nap-nap, a sleep-sleep. 😭 your process gets woken back up once more buffer space becomes available — and that happens when somebody calls kcapi_cipher_stream_op.

so like, the wake-up call comes from kcapi_cipher_stream_op, not from this function. noted. ✍️

---

⭐ NOTE ⭐

the way this is designed? with the separate API calls of kcapi_cipher_stream_update and kcapi_cipher_stream_op, a multi-threaded application can be implemented where:

1. one thread sends data to be processed, and
2. one thread picks up data processed by the cipher operation.

two threads, one pipeline, main character energy fr fr 👑

---

💀 IMPORTANT NOTE 💀

okay this part is NOT a drill, bestie. pay attention:

the kernel will only process sysconf(_SC_PAGESIZE) * ALG_MAX_PAGES at one time.

if your input data is larger than this threshold, you MUST segment it into chunks of at most sysconf(_SC_PAGESIZE) * ALG_MAX_PAGES, and then invoke kcapi_cipher_stream_update on that segment followed by kcapi_cipher_stream_op — before the next chunk gets processed.

and if you don't obey this rule? the thread invoking kcapi_cipher_stream_update gets put to sleep until another thread invokes kcapi_cipher_stream_op. not me warning you and you still ignoring it 🙈 just chunk your data. please. for me. 🥺

---

🔥 WARNING 🔥

the memory referenced by iov is NOT accessed by the kernel during this call. like, at all. the memory is first accessed when kcapi_cipher_stream_op is called. so you MUST make sure that the referenced memory is still present at the time kcapi_cipher_stream_op is called.

translation: don't free it, don't let it go out of scope, don't let it wander off into the void. keep that memory alive or it's giving undefined chaos. 💀

return number of bytes sent to the kernel upon success; a negative errno-style error code if an error occurred.

---

🌸 AUTHOR 🌸

Stephan Mueller <smueller@chronox.de> — Author. yes, THE Stephan Mueller. we stan. 💜

---

👑 COPYRIGHT 👑

that's all the legal girlies needed to say on the matter ✨

---

and that's the whole page, bestie! this came straight out of the libkcapi Manual, version 1.5.0, dated July 2025 — so if you're quoting her, quote her with love. bye pookie, go chunk your data 💖🌈🦋🎀🫶💅