KEYCTL_DESCRIBE(3)

💖 KEYCTL_DESCRIBE 💖

okay bestie, welcome to keyctl_describe from the Linux Key Management Calls lineup ✨ this is the one that spills the tea on a key — like, tells you everything about it. no cap.

🌸 NAME 🌸

keyctl_describe — describe a key 🫶

✨ SYNOPSIS ✨

#include <keyutils.h>

long keyctl_describe(key_serial_t key, char *buffer, size_tbuflen);

long keyctl_describe_alloc(key_serial_t key, char **_buffer);

🎀 DESCRIPTION 🎀

keyctl_describe() hands you the attributes of a key, all wrapped up as a NUL-terminated string. it's giving "here's everything you wanted to know" 💅

lowkey important tho: the caller must have view permission on a key before it'll let you get a description of it. no view permission, no tea. periodt.

buffer and buflen are the two of you pointing at the buffer where the key description is gonna land, and how big it is. and if that buffer is too small? 😭 the full size of the description gets returned anyway, and no copy will take place — so nothing gets written, you just get told how much room you'd need.

keyctl_describe_alloc() is the same vibe as keyctl_describe() except it's the main character who handles the logistics: it allocates a buffer big enough to hold the description and drops the description in there for you. if it works out, a pointer to that buffer gets placed in *_buffer. and bestie, the caller must free the buffer — it's yours now, take care of it 🫶

the description comes out as a string of format:

"%s;%d;%d;%08x;%s"

and the arguments are, in order: key type name, key UID, key GID, key permissions mask, and key description. iconic little five-part combo meal 🍓

NOTE! 🚨 the key description itself will not contain any semicolons. so you should separate it out by working backwards from the end of the string. why? because that's what lets later versions of the kernel sneak extra information in before it, just by inserting more semicolon-terminated substrings. foresight? we love to see it 👑

🌈 RETURN VALUE 🌈

on success, keyctl_describe() returns the amount of data placed into the buffer. 💖

if the buffer was too small, then the size of buffer required gets returned instead — but no data will be transferred. sad but informative.

on error, the value -1 comes back and errno will have been set to an appropriate error. 💀

on success, keyctl_describe_alloc() returns the amount of data in the buffer, less the NUL terminator. on error, the value -1 comes back and errno will have been set to an appropriate error.

💀 ERRORS 💀

• ENOKEY — the key specified is invalid. doesn't exist, bestie, can't help you 🙈
• EKEYEXPIRED — the key specified has expired. it's giving expired milk energy 🥛
• EKEYREVOKED — the key specified had been revoked. it got cancelled fr fr
• EACCES — the key exists, but is not viewable by the calling process. the key is right there and still won't talk to you 😭

🔗 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 skip this step, it's the whole plot 🎀

👑 SEE ALSO 👑

keyctl(1), add_key(2), keyctl(2), request_key(2), keyctl(3), keyrings(7), keyutils(7)

and that's the whole page, bestie!! this one's from Linux, dated 4 May 2006 — yeah she's an elder but she still slays 💅✨ mwah, go describe some keys responsibly 🦋💖