KEYCTL_RESTRICT_KEYRING(2const)

💖 KEYCTL_RESTRICT_KEYRING — bestie edition 💖

okay so this is a page from the Linux man-pages, section 2const (that's "constants and stuff for syscalls", iykyk), and it's all about KEYCTL_RESTRICT_KEYRING, which is one of the keyctl(2) subcommands. Basically: it locks a keyring down so only certain keys are allowed in. iconic behaviour, honestly. 🔒✨

---

✨ NAME ✨

KEYCTL_RESTRICT_KEYRING — restrict which keys are allowed to get linked to a keyring 🎀

📚 LIBRARY 📚

Standard C library (libc, -lc) 💅

🌸 SYNOPSIS 🌸

#include <linux/keyctl.h>  /* Definition of KEY* constants */
#include <sys/syscall.h>   /* Definition of SYS_* constants */
#include <unistd.h>

long syscall(SYS_keyctl, KEYCTL_RESTRICT_KEYRING, key_serial_t keyring,
             const char *_Nullable type, const char *restriction);

🦋 DESCRIPTION 🦋

So you take the keyring whose ID you passed as keyring, and you slap a key-linking restriction on it. That's the whole vibe. The way that you must have setattr permission on the key though — no permission, no slay. 🫶

If type is NULL, then literally any attempt to add a key to that keyring gets blocked. Full lockdown. Door closed, no notes. 🚪💀

Otherwise, type is a pointer to a string holding a key type name, and restriction is a pointer to a string describing the type-specific restriction. And as of Linux 4.12, only one type actually has restrictions defined, and that type is "asymmetric":

• builtin_trusted — only allows keys that are signed by a key linked to the built-in keyring (".builtin_trusted_keys"). nothing else gets in bestie, periodt ✨
• builtin_and_secondary_trusted — only allows keys that are signed by a key linked to the secondary keyring (".secondary_trusted_keys") or, by extension, a key in a built-in keyring, because the built-in one is linked to the secondary one. it's giving nepotism but make it cryptographically valid 💅
• key_or_keyring:key
• key_or_keyring:key:chain

and here's the tea for those two:

• If key specifies the ID of a key of type "asymmetric", then only keys that are signed by this key are allowed. 🗝️
• If key specifies the ID of a keyring, then only keys that are signed by a key linked to this keyring are allowed. 🔗
• If ":chain" is specified, then keys that are signed by a keys linked to the destination keyring are also allowed. and yes — "destination keyring" means the keyring with the ID you passed in the keyring argument. 😌

🚨 VERY IMPORTANT, NO CAP: a restriction can only be configured once for a given keyring. Once it's set, it can't be overridden. Ever. Choose wisely bestie, that's a permanent decision. 😭

🎀 RETURN VALUE 🎀

• On success, 0 is returned. slay! ✅
• On error, -1 is returned, and errno is set to indicate the error. 🙈

💀 ERRORS 💀

• EDEADLK — the requested keyring restriction would result in a cycle. loops are NOT the move here. 🔄🚫
• EEXIST — keyring already has a restriction set. told you it was permanent. 💅
• ENOENT — the type provided in the type argument doesn't support setting key linking restrictions. wrong type, wrong vibe. 🙅
• EOPNOTSUPP — type was "asymmetric", and the key specified in the restriction specification provided in restriction has type other than "asymmetric" or "keyring". mismatch detected, not it. 😤

🌈 VERSIONS 🌈

There's a wrapper for all of this in the libkeyutils library: keyctl_restrict_keyring(3). use that one if you don't wanna hand-roll the syscall, bestie, it's the low-effort high-reward route 🧚

⭐ STANDARDS ⭐

Linux. 🐧 (it's giving very Linux-core, because it is)

👑 HISTORY 👑

Linux 4.12. a classic, honestly. 🔥

🫶 SEE ALSO 🫶

• keyctl(2)
• keyctl_restrict_keyring(3)

---

okay that's the whole page, go forth and restrict responsibly 💜✨

<xoxo> this was Linux man-pages 6.20, dated 2026-02-08 — KEYCTL_RESTRICT_KEYRING(2const), signing off 🎀🦋💖

---