KEYCTL_SETPERM(2const)

🗝️✨ KEYCTL_SETPERM — the "who's allowed to touch my key" syscall 💅

okay so bestie, picture this: you've got a key (the kernel kind, not your house key, not your car key, the cryptographic-superpower kind) and you wanna decide exactly who gets to do what with it. That's this. This is the KEYCTL_SETPERM operation of the keyctl(2) family, from the 2const corner of the manual pages. It rewrites the permissions mask on a key. Lowkey one of the most important calls in the whole keyring universe fr fr. 👑

---

📚 LIBRARY

Standard C library (libc, -lc). The classic. 🫶

---

✨ 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_SETPERM, key_serial_t key,
             key_perm_t perms);

---

💖 DESCRIPTION

So here's the vibe: you take the key whose ID you dropped into the key argument, and you change its permissions to whatever you put in the perms argument. That's it. That's the whole thing. Glow up achieved. ✨

⚠️ now the fine print, and bestie you need this part:

• If the caller doesn't have the CAP_SYS_ADMIN capability, it can change permissions only for the keys it owns. 💀 (More precisely: the caller's filesystem UID must match the UID of the key.)
• The key must grant setattr permission to the caller regardless of the caller's capabilities. No exceptions, no main character loopholes.

The permissions in perms are masks of available operations, one mask per user category. Here are the categories, bestie, take notes 📝:

• possessor (since Linux 2.6.14) — the permission granted to a process that possesses the key, meaning it has the key attached searchably to one of the process's keyrings. See keyrings(7) for the lore. 💫
• user — the permission granted to a process whose filesystem UID matches the UID of the key.
• group — the permission granted to a process whose filesystem GID, or any of its supplementary GIDs, matches the GID of the key.
• other — the permission granted to other processes that don't match the user and group categories. The randoms. 🫥

Important structural tea: the user, group, and other categories are exclusive. If a process matches the user category, it will not receive permissions granted in the group category. And if a process matches the user or group category, it will not receive permissions granted in the other category. Pick a lane, babes. 🚫

Meanwhile the possessor category is cumulative — those grants stack on top of whatever the user, group, or other category already handed over. Stacked. Slay. 💅

Each permission mask is eight bits in size, and only six bits are currently used. The available permissions are:

🌸 view

This permission allows reading attributes of a key.

It's required for the KEYCTL_DESCRIBE(2const) operation.

The permission bits for each category are:

KEY_POS_VIEW
KEY_USR_VIEW
KEY_GRP_VIEW
KEY_OTH_VIEW

🌸 read

This permission allows reading a key's payload.

It's required for the KEYCTL_READ(2const) operation.

The permission bits for each category are

KEY_POS_READ
KEY_USR_READ
KEY_GRP_READ
KEY_OTH_READ

🌸 write

This permission allows update or instantiation of a key's payload. For a keyring, it allows keys to be linked and unlinked from the keyring,

It's required for the KEYCTL_UPDATE(2const), KEYCTL_REVOKE(2const), KEYCTL_CLEAR(2const), KEYCTL_LINK(2const), and KEYCTL_UNLINK(2const) operations.

The permission bits for each category are:

KEY_POS_WRITE
KEY_USR_WRITE
KEY_GRP_WRITE
KEY_OTH_WRITE

🌸 search

This permission allows keyrings to be searched and keys to be found. Searches can recurse only into nested keyrings that have search permission set.

It's required for the KEYCTL_GET_KEYRING_ID(2const), KEYCTL_JOIN_SESSION_KEYRING(2const), KEYCTL_SEARCH(2const), and KEYCTL_INVALIDATE (2const) operations.

The permission bits for each category are:

KEY_POS_SEARCH
KEY_USR_SEARCH
KEY_GRP_SEARCH
KEY_OTH_SEARCH

🌸 link

This permission allows a key or keyring to be linked to.

It's required for the KEYCTL_LINK(2const) and KEYCTL_SESSION_TO_PARENT(2const) operations.

The permission bits for each category are:

KEY_POS_LINK
KEY_USR_LINK
KEY_GRP_LINK
KEY_OTH_LINK

🌸 setattr (since Linux 2.6.15)

This permission allows a key's UID, GID, and permissions mask to be changed. Yes, it's the permission that controls the permission-changer. Recursive queen behavior. 👑

It's required for the KEYCTL_REVOKE(2const), KEYCTL_CHOWN(2const), and KEYCTL_SETPERM (2const) operations.

The permission bits for each category are:

KEY_POS_SETATTR
KEY_USR_SETATTR
KEY_GRP_SETATTR
KEY_OTH_SETATTR

---

🎀 the convenience macros (a gift, honestly)

As a convenience, the following macros are defined as masks for all of the permission bits in each of the user categories:

KEY_POS_ALL
KEY_USR_ALL
KEY_GRP_ALL
KEY_OTH_ALL

---

🫶 RETURN VALUE

• On success, 0 is returned. 🎉
• On error, -1 is returned, and errno is set to indicate the error. 😭

---

💀 ERRORS

• EINVAL — operation was KEYCTL_SETPERM and an invalid permission bit was specified in perms. You gave it a bit that does not exist, bestie. It said no. 🙈

---

🌈 VERSIONS

A wrapper is provided in the libkeyutils library: keyctl_setperm(3). Use it, it's comfier than raw syscalls. 🛋️

---

⭐ STANDARDS

Linux. That's the standard. That's it. 🐧

---

🦋 HISTORY

Linux 2.6.10. Vintage. Iconic. Still eating. ✨

---

👀 SEE ALSO

• keyctl(2)
• keyctl_setperm(3)

---

and that's the whole page, babe!! This was pulled straight from the Linux man-pages, version 6.20, dated 2026-02-08 — so if anyone asks where you got your info, that's the receipt. 🧾💖 Now go set some permissions. Responsibly. Or at least setattr-responsibly. 💅