KEYCTL_SETPERM(3)

💅 keyctl_setperm — like, the key permission glow-up page

okay bestie, pull up a chair 🫶 this is keyctl_setperm(3), one of the Linux Key Management Calls, and it's genuinely so useful. no cap.

---

✨ NAME ✨

keyctl_setperm — change the permissions mask on a key 🔐

---

🌸 SYNOPSIS 🌸

#include <keyutils.h>

long keyctl_setperm(key_serial_t key, key_perm_t perm);

---

🎀 DESCRIPTION 🎀

keyctl_setperm() changes the permissions mask on a key. that's the whole vibe. it's giving "who gets to do what with this key" ✨

now. plot twist. a process that does not have the SysAdmin capability may not change the permissions mask on a key that doesn't have the same UID as the caller. so if it's not your key and you're not sysadmin-coded, hands off bestie 🙈

also, the caller must have setattr permission on a key to be able to change its permissions mask. like, you need the pass to change the pass. iykyk 💅

the permissions mask is a bitwise-OR of the following flags:

• KEY_xxx_VIEW — grant permission to view the attributes of a key. peek at the metadata, not the payload 👀
• KEY_xxx_READ — grant permission to read the payload of a key or to list a keyring 📖
• KEY_xxx_WRITE — grant permission to modify the payload of a key or to add or remove links to/from a keyring ✍️
• KEY_xxx_SEARCH — grant permission to find a key or to search a keyring 🔎
• KEY_xxx_LINK — grant permission to make links to a key 🔗
• KEY_xxx_SETATTR — grant permission to change the ownership and permissions attributes of a key 🛠️
• KEY_xxx_ALL — grant all the above. the whole menu, no substitutions 👑

the xxx in the above should be replaced by one of:

• POS — grant the permission to a process that possesses the key (has it attached searchably to one of the process's keyrings). the main character category 💖
• USR — grant the permission to a process with the same UID as the key.
• GRP — grant the permission to a process with the same GID as the key, or with a match for the key's GID amongst that process's Groups list.
• OTH — grant the permission to any other process. everyone else, come on in 🌈

examples include: KEY_POS_VIEW, KEY_USR_READ, KEY_GRP_SEARCH and KEY_OTH_ALL. see how the pattern goes? KEY_ + category + _ + action. slay ✨

okay this next part is the part people get wrong, so listen up fr fr:

user, group and other grants are exclusive: if a process qualifies in the user category, it will not qualify in the groups category; and if a process qualifies in either user or groups then it will not qualify in the other category. it's giving strict clique rules — you're in one lane, not all of them 💀

possessor grants are cumulative with the grants from the user, groups and other categories. so POS stacks on top of whatever else you got 🫶

---

⭐ RETURN VALUE ⭐

on success keyctl_setperm() returns 0. on error, the value -1 will be returned and errno will have been set to an appropriate error. classic. 😌

---

🔥 ERRORS 🔥

• ENOKEY — the specified key does not exist. it's not there bestie, it never was 😭
• EKEYEXPIRED — the specified key has expired. it had its moment, and its moment is over ⏳
• EKEYREVOKED — the specified key has been revoked. cancelled, literally 🚫
• EACCES — the named key exists, but does not grant setattr permission to the calling process. the key is right there and it's still not letting you in 💀

---

🧚 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 simply not know her 🎀

---

🦋 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. go forth and set some perms responsibly 💜

this one came out of the Linux corner of the world, dated 4 May 2006, and it lives at KEYCTL_SETPERM(3) in the manual. periodt. 💅✨