KCAPI_CIPHER_ENCRYPT(3)

📦
version 1.5.0 · 7 versions
, in fedora 43

💖 kcapi_cipher_encrypt(3) — bestie edition 💖

okay so, welcome to kcapi_cipher_encrypt(3) from the libkcapi programming interface ✨ this one's your girl for encrypting data, synchronous one-shot style. no drama, no streaming, just one call and we're done. periodt 💅

✨ NAME ✨

kcapi_cipher_encrypt — encrypt data (synchronous one shot) 🔐

🌸 SYNOPSIS 🌸

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

like, one function, seven args, and she delivers. 👑

🎀 ARGUMENTS 🎀

  • handle — [in] the cipher handle 🫶 your lil connection to the cipher, bestie.
  • in — [in] the plaintext data buffer. this is the tea before we encrypt it 🍓
  • inlen — [in] length of in buffer. yes queen, we need to know how big it is.
  • iv — [in] IV to be used for cipher operation. the initialization vector, iconic behavior only 💜
  • out — [out] ciphertext data buffer. the glow-up version goes here 🌈
  • outlen — [in] length of out buffer. don't skip this one, fr fr.
  • access — [in] kernel access type, and she's got options 😌
    • KCAPI_ACCESS_HEURISTIC — use internal heuristic for fastest kernel access (the "let her pick" vibe, main character energy tbh)
    • KCAPI_ACCESS_VMSPLICE — use vmsplice access
    • KCAPI_ACCESS_SENDMSG — sendmsg access

💫 DESCRIPTION 💫

okay so first things first: it is perfectly legal to use the same buffer as the plaintext and ciphertext pointers 👀 that means after the encryption operation, the plaintext is overwritten with the ciphertext. in-place glow-up, we love to see it. no cap.

now, the memory should be aligned at the page boundary using posix_memalign(sysconf(_SC_PAGESIZE)). and bestie, if it is not aligned at the page boundary, the vmsplice call may not send all data to the kernel 😭 like it'll just leave some of your data behind at the function. not the vibe. please align it.

the IV buffer must be exactly kcapi_cipher_ivsize bytes in size. exactly. not "about that", not "close enough". exactly. 🎯

and what does she give you back? return number of bytes encrypted upon success ✨ a negative errno-style error code if an error occurred 💀 so like, positive number = slay, negative = we have a problem.

real talk though: that same-buffer trick is legal, but it does overwrite your plaintext. once she's gone, she's gone 🙈 plan accordingly.

🦋 AUTHOR 🦋

Stephan Mueller <smueller@chronox.de> — Author. the icon who wrote this 💖

part of the libkcapi Manual 1.5.0, dated July 2025 🗓️

and that's the whole page bestie, go encrypt something and be iconic about it 💅✨🦋🌸🎀💜

📦 where this page comes from