KEYCTL_GET_PERSISTENT(3)

💖 KEYCTL_GET_PERSISTENT 💖

okay bestie, gather round, because we're diving into keyctl_get_persistent — a page straight out of the Linux Key Management Calls manual (section 3, library functions, iykyk). it's giving "the keyring that refuses to leave the group chat" energy and honestly? iconic. 💅

✨ NAME ✨

keyctl_get_persistent — grab the persistent keyring for a user, no cap 🔑

✨ SYNOPSIS ✨

#include <keyutils.h>

long keyctl_get_persistent(uid_t uid, key_serial_t keyring);

like, that's it. two args. she's low maintenance, she's efficient, she's main character energy 🎀

✨ DESCRIPTION ✨

so keyctl_get_persistent() gets the persistent keyring for the user ID you point at. and here's the tea ☕ — unlike the session and user keyrings, this one persists once every single login session has been deleted. meaning she sticks around. meaning you can use her to carry authentication tokens for processes that run with zero user interaction, like stuff started by cron. yes, cron. the little background gremlin that never asks for your password 🙈

the kernel will create the persistent keyring for you if it doesn't exist yet — no need to manifest it yourself, she just shows up 🦋

and every single time this function gets called, the persistent keyring's expiration timeout gets reset to whatever value lives in:

/proc/sys/kernel/keys/persistent_keyring_expiry

which, btw, defaults to three days ⏳

and if that timeout ever actually gets reached? the persistent keyring gets removed, and everything it was pinning can then be garbage collected. rip to her fr fr 💀

now, the uid rules, listen closely:

• if uid is -1, then the calling process's real user ID gets used. easy, no thoughts, just vibes.
• if uid is not -1, then error EPERM will be given if the user ID you requested doesn't match either the caller's real or effective user IDs, or if the calling process doesn't have SetUid capability. so like, know your limits bestie 🫶

and if it all goes well? a link to the persistent keyring gets added into keyring. slay. ✨

✨ RETURN VALUE ✨

on success, keyctl_get_persistent() returns the serial number of the persistent keyring. a whole number, a whole identity, a whole queen 👑

on error, the value -1 gets returned and errno will have been set to an appropriate error. classic. 😭

✨ ERRORS ✨

here's the mood board of ways this can go wrong, and every single one matters:

• EPERM — not permitted to access the persistent keyring for the requested uid. the bouncer said no 💅
• ENOMEM — insufficient memory to create the persistent keyring or to extend keyring. she's out of RAM and out of patience.
• ENOKEY — keyring does not exist. never was. never will be. ghosted 💀
• EKEYEXPIRED — keyring has expired. the timer ran out, bestie.
• EKEYREVOKED — keyring has been revoked. cancelled, actually.
• EDQUOT — the user does not have sufficient quota to extend keyring. quota said no more, you're maxed out 🍓
• EACCES — keyring exists, but does not grant write permission to the calling process. she's there, she's just not letting you in 🔒

✨ LINKING ✨

this is a library function, and you'll find her hanging out in libkeyutils. so when you're linking, you gotta pass -lkeyutils to the linker. don't forget it, or the linker will simply not know her and that would be embarrassing 🎀

✨ SEE ALSO ✨

the whole friend group, go say hi:

• keyctl(1)
• add_key(2)
• keyctl(2)
• request_key(2)
• keyctl(3)
• keyrings(7)
• keyutils(7)
• persistent-keyring(7)

and that's the whole page, bestie!! ✨ no thoughts, just keyrings that outlive your login sessions 💖 this page came to you from the Linux manual, dated 20 Feb 2014, and it's a total banger. go forth and persist. periodt. 👑