KEYCTL_PKEY_SIGN(3)

💅 KEYCTL_PKEY_SIGN — the Linux public-key signatures moment (man page 3, bestie)

okay so real talk, we're in section 3 of the Linux manual, and this page is literally about making signatures and checking them. it's giving cryptography but make it a group chat. let's GO 🫶

---

✨ NAME ✨

keyctl_pkey_sign, keyctl_pkey_verify — generate and verify signatures. that's it, that's the whole vibe. one signs, one verifies, iconic duo energy 👑

---

🌸 SYNOPSIS 🌸

#include <keyutils.h>

long keyctl_pkey_sign(key_serial_t key, const char *info,
                      const void *data, size_t data_len,
                      void *sig, size_t sig_len);

long keyctl_pkey_verify(key_serial_t key, const char *info,
                        const void *data, size_t data_len,
                        const void *sig, size_t sig_len);

look at those signatures (pun fully intended 💀). same args, different jobs.

---

🦋 DESCRIPTION 🦋

keyctl_pkey_sign() is the one that asks the kernel to use the crypto data attached to a key and generate a detached signature for a blob of data. lowkey important note: this may involve calling out to actual cryptographic hardware. yes, real hardware, not just vibes ✨

keyctl_pkey_verify() asks the kernel to use the key to generate a verify the signature against that same blob of data. (yes that sentence is exactly how the original words it, we don't fix, we report 💅). this one may also involve calling out to cryptographic hardware.

🚨 the caller must have search permission on a key to be able to perform either operation. no search perms, no service. periodt.

so when you invoke the function:

• key — indicates the key that will provide the cryptographic material.
• info — points to a space- or tab-separated string of "key[=value]" parameters. these indicate things like encoding forms and passwords to unlock the key. for more info, go read asymmetric-key(7), bestie, it's all there 📖

and then the buffers:

• data and datalen — the address and size of the buffer of data to be signed.
• sig and siglen — the address and size of the signature buffer.

the sign function draws data from the data buffer, generates a signature from it, and places the output into the signature buffer. the verify function also draws data from the data buffer, then decrypts the signature and compares the result. chef's kiss comparison 🧚

⚠️ heads up: the data buffer is strictly limited in capacity, typically unable to hold more bits than the size of the key. so no, you cannot just dump your whole novel in there. the caller is expected to have pre-digested the actual data and will thus pass the digest output to this function. the name of the digest used should be passed as part of the info string as hash=<name> for use in constructing the signature metadata.

keyctl_pkey_query(2) can be called to find out how large the buffers need to be and what the maximum size of the data can be for a specific signature encoding. use it. it's your little calculator friend 🎀

and ngl, not all asymmetric-type keys will support these operations. further, the operations available may depend on which components of the key material are 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_sign() returns the amount of data written into the signature buffer. 🎉

keyctl_pkey_verify() will return 0 in this case, as it doesn't write to userspace. it's the strong silent type fr fr 🤐

on error, the value -1 will be returned and errno will have been set to an appropriate error. sad girl hours 😭

---

💀 ERRORS 💀

• ENOKEY — The key specified is invalid. like, who even is she 💅
• EKEYEXPIRED — The key specified has expired. time's up, babe ⌛
• EKEYREVOKED — The key specified has been revoked. cancelled 🚫
• EACCES — The key exists, but is not searchable by the calling process. she's there but she's not answering the door 🙈
• EINVAL, EBADMSG, EOVERFLOW — Some part of the key material or signature data is bad. something is rotten in the state of your buffers 🍓
• EKEYREJECTED — Signature verification failed. 🚨 the whole point and it did NOT pass, we're devastated
• 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. wrong place, bestie 📍

---

🌈 LINKING 🌈

this is a library function that can be found in libkeyutils. when 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), keyrings(7), keyutils(7)

go read all of them, i know you will, you're a scholar ⭐

---

and that's the page, bestie!! this one came from Linux, dated 8 Nov 2018, and it lives at the top of the page as KEYCTL_PKEY_SIGN(3) — so if you ever forget where you found me, it's the Linux keyutils manual, section 3. mwah, stay signed, stay verified 💖💅✨