KEYCTL_PKEY_ENCRYPT(3)

💖 KEYCTL_PKEY_ENCRYPT(3) 💖

okay bestie, welcome to keyctl_pkey_encrypt(3) and keyctl_pkey_decrypt(3) — the Linux public-key encryption girlies. this is a section 3 manual page, and it's all about locking a lil blob of data up with a key, and then unlocking it again. 🔐✨

🌸 NAME 🌸

keyctl_pkey_encrypt, keyctl_pkey_decrypt — Encrypt and decrypt data

like. the name is literally the whole plot. encrypt. decrypt. that's it, that's the function. 💅

✨ SYNOPSIS ✨

#include <keyutils.h>

long keyctl_pkey_encrypt(key_serial_t key, const char *info,
                         const void *data, size_t data_len,
                         void *enc, size_t enc_len);

long keyctl_pkey_decrypt(key_serial_t key, const char *info,
                         const void *enc, size_t enc_len,
                         void *data, size_t data_len);

look at those signatures. so clean. so symmetrical. the way they mirror each other?? iconic. 🪞

🦋 DESCRIPTION 🦋

so keyctl_pkey_encrypt() is you asking the kernel, very politely, to take the crypto material attached to a key and use it to encrypt a blob of data. and keyctl_pkey_decrypt() is you asking the kernel to run that whole thing backwards and get the original data back out. 🎀

heads up bestie: these operations may involve the kernel calling out to actual cryptographic hardware. so it's not always just vibes and software, sometimes there's a whole chip involved. also — the caller must have search permission on a key to be able to use them in this manner. no search permission, no service. 😭

when you call the function, key is the key that provides the cryptographic material, and info points to a space- or tab-separated string of "key[=value]" parameters. those params say stuff like which encoding forms to use and passwords to unlock the key. for the full tea on that, go read asymmetric-key(7). 📖

data and datalen are the address and size of the decrypted data buffer, and enc and enclen are the address and size of the encrypted data buffer. the encrypt function pulls data out of the decrypted data buffer and drops the output into the encryption buffer. the decrypt function does the reverse — pulls from the encryption buffer and writes into the data buffer. it's giving ✨two-way street✨.

keyctl_pkey_query(2) can be called to find out how large the buffers need to be. so like, do that first, bestie. don't guess your buffer sizes, that's not the move. 📏

⚠️ also real talk: not all asymmetric-type keys will support these operations. and on top of that, the operations available may depend on which components of the key material are actually available. typically, encryption only requires the public key, but decryption requires the private key as well. which operations are supported on a particular key can also be determined using the query function. so like. vibe check your key first. 🕵️♀️

🔥 RETURN VALUE 🔥

on success, keyctl_pkey_encrypt() and keyctl_pkey_decrypt() return the amount of data written into the output buffer. 💯

on error, the value -1 will be returned and errno will have been set to an appropriate error. not the slay we wanted, but okay. 😔

💀 ERRORS 💀

• ENOKEY — The key specified is invalid. (bestie. that key does not exist. respectfully.)
• EKEYEXPIRED — The key specified has expired. (it's past its moment, it had its era, it's over now 🥀)
• EKEYREVOKED — The key specified has been revoked. (cancelled, fr fr)
• EACCES — The key exists, but is not searchable by the calling process. (it's right there and it's still not for you 💔)
• ENOPKG — Some facility needed to complete the requested operation is not available. This is most probably a requested or required digest or encryption algorithm. (the algorithm ghosted you 👻)
• EFAULT — Bad address. (you handed it a pointer to nowhere, bestie 🙈)

🎀 LINKING 🎀

this is a library function that can be found in libkeyutils. when you're linking, -lkeyutils should be specified to the linker. don't forget it or the linker will simply not know her. 💅

🌈 SEE ALSO 🌈

keyctl(1), add_key(2), keyctl(2), keyctl(3), keyctl_pkey_query(3), keyctl_pkey_sign(3), keyrings(7), keyutils(7)

the whole friend group, go say hi 🫶

and that's the page, bestie!! this one is from the Linux manual, dated 8 Nov 2018, and it lives at KEYCTL_PKEY_ENCRYPT(3). mwah, go encrypt something responsibly. 💖✨🎀