KCAPI_HANDLE_REINIT(3)

✨ kcapi_handle_reinit(3) ✨

okay bestie, gather round 💖 this one lives in the Programming Interface section of the manual (yes that's the manual name, it's giving very official), and it's literally the "make me a twin handle" function. no cap. 🦋

---

🌸 NAME 🌸

kcapi_handle_reinit — re-initialize a new kernel interface 👑

---

🌈 SYNOPSIS 🌈

int kcapi_handle_reinit(struct kcapi_handle ** newhandle,
                        struct kcapi_handle * existing, uint32_t flags);

---

🎀 ARGUMENTS 🎀

• newhandle — [out] the cipher handle that gets filled in during the call, i.e. where your shiny new baby handle lands 🍼
• existing — [in] the existing cipher handle you're re-initializing a new handle from. it's the source, the blueprint, the moment 💅
• flags — [in] flags that specify the type of cipher handle 🚩

---

💜 DESCRIPTION 💜

so. the kernel crypto API interface runs on two types of file descriptors, and you gotta know both or you're lost:

• the TFM file descriptor — this is the one holding the cipher-operation static info: the key, and the AEAD tag size 🔑
• the OP file descriptor — this is the one holding the volatile data, like the plaintext / ciphertext, the IV, or the AEAD AD size 🌊

the kernel crypto API AF_ALG interface supports this whole concept where one TFM file descriptor can operate with multiple OP file descriptors. and like, not just "multiple", the different OP file descriptors can perform completely separate cipher operations using the same key, and those can execute in parallel 🔥. that parallel execution can happen in the same process threads or in different process threads — dealer's choice, bestie.

so what does kcapi_handle_reinit do? it allows the allocation of a new cipher handle with a new OP file descriptor but using the same TFM file descriptor. to get a reference to that TFM file descriptor, an existing cipher handle is used as the source. ✨

and the way that you can invoke kcapi_handle_reinit multiple times?? iconic. each resulting cipher handle must be deallocated with kcapi_cipher_destroy. and the deallocation is smart — it ensures that the TFM resource is only released if the last handle using this TFM resource is released. reference counting, but make it cute 🫶

🚨 not me reminding you: every single handle you spawn from this needs its own kcapi_cipher_destroy. no leaving them orphaned, that's not the vibe.

and the return situation:

• 0 upon success 🎉
• -EINVAL — accept syscall failed 💀
• -ENOMEM — cipher handle cannot be allocated 😭

---

👑 AUTHOR 👑

Stephan Mueller <smueller@chronox.de> — Author. 🫡 absolute legend, we thank them for their service.

---

📜 COPYRIGHT 📜

that's the whole page, bestie! this was brought to you by the libkcapi Manual 1.5.0, dated July 2025, and you can find it filed under KCAPI_HANDLE_REINIT(3) 💖✨ go forth and reinit responsibly, mwah 🎀