KEYCTL_RESTRICT_KEYRING(3)

💖 KEYCTL_RESTRICT_KEYRING — the Linux key management calls, bestie edition 🎀

okay so real talk, this one is a <keyutils.h> situation, it lives in the Linux key management family, and it's lowkey one of the most gatekeeping functions ever because it literally lets you lock a keyring down. iconic behavior fr fr 💅

✨ NAME ✨

keyctl_restrict_keyring — restrict which keys are allowed to get linked onto a keyring 🔒

🦋 SYNOPSIS 🦋

#include <keyutils.h>

long keyctl_restrict_keyring(key_serial_t keyring,
const char *type, const char *restriction);

🌸 DESCRIPTION 🌸

so keyctl_restrict_keyring() does the thing where it limits the linkage of keys to the given keyring, using a key type and a restriction scheme you hand it. the way that it works is very much "you don't get in unless you pass the vibe check" energy 👑

the available options vary depending on the key type, and they typically contain a restriction name, possibly followed by key ids or other data relevant to the restriction. iykyk 🌈

and here's the plot twist: if the type and the restriction are both NULL, the keyring will reject all links. not some. all. it's giving locked door, no key, no note, no nothing 💀

🔥 RETURN VALUE 🔥

on success, keyctl_restrict_keyring() returns 0. slay ✨

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

💜 ERRORS 💜

• EDEADLK — a restriction cycle was avoided. two keyrings cannot restrict each other, periodt. no mutual-lockdown situationships allowed 🙅
• EEXIST — the keyring is already restricted. bestie it's taken, the lock is already on 🔐
• EINVAL — the restriction string is invalid or too large. too much, too messy, we can't work with that 🙈
• ENOKEY — the key type in the restriction is invalid or not available. never heard of her 💀
• ENOTDIR — the provided key id references an item that is not a keyring. wrong main character, wrong role 🎭
• ENOENT — the key type exists but does not support restrictions. she's here, she just doesn't do that ✋

🫶 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 be so confused ngl 🧚

⭐ SEE ALSO ⭐

• keyctl(1)
• keyctl(2)
• keyctl(3)
• keyutils(7)

⚠️ gentle reminder bestie: if you restrict a keyring, you cannot un-restrict it. EEXIST said what it said. commit wisely 💖

that's the whole page!! from the Linux fam, dated 28 Feb 2017, and you're reading the KEYCTL_RESTRICT_KEYRING(3) girlies' cut 💅 mwah, go restrict responsibly 🎀✨