KEYCTL_LINK(3)

💖 KEYCTL_LINK(3) — it's giving Linux Key Management Calls ✨

okay bestie, sit down, hydrate, and let me tell you about keyctl_link and keyctl_unlink — the duo that links and unlinks a key to/from a keyring. this is from the Linux Key Management Calls manual, section 3, and it's lowkey iconic. 🎀

---

🌸 NAME 🌸

keyctl_link, keyctl_unlink — link/unlink a key to/from a keyring

---

✨ SYNOPSIS ✨

#include <keyutils.h>

long keyctl_link(key_serial_t key, key_serial_t keyring);

long keyctl_unlink(key_serial_t key, key_serial_t keyring);

---

🦋 DESCRIPTION 🦋

so, two functions, two vibes. 💅

keyctl_link() creates a link from keyring to key. and the way that it will displace any link to another key of the same type and description in that keyring if one already exists? yeah. it said "move over, there's a new main character." periodt.

keyctl_unlink() removes the link from keyring to key — but only if it exists. no drama, just a clean break. 🫶

now for the permissions tea, and this is important, no cap:

• the caller must have write permission on a keyring to be able to create or remove links in it.
• the caller must have link permission on a key to be able to create a link to it.

so like, you can't just barge into somebody else's keyring and start redecorating. vibe check first. 🔥

---

⭐ RETURN VALUE ⭐

on success, both keyctl_link() and keyctl_unlink() return 0. slay. 💖

on error, the value -1 will be returned and errno will have been set to an appropriate error. it's not a vibe, but at least it tells you why.

---

💀 ERRORS 💀

here's the whole list, bestie, don't skip it:

• ENOKEY — The key or the keyring specified are invalid. 🙈
• EKEYEXPIRED — The key or the keyring specified have expired.
• EKEYREVOKED — The key or the keyring specified have been revoked.
• EACCES — The keyring exists, but is not writable by the calling process.

and these ones are for keyctl_link() only:

• ENOMEM — Insufficient memory to expand the keyring
• EDQUOT — Expanding the keyring would exceed the keyring owner's quota.
• EACCES — The key exists, but is not linkable by the calling process.

yes, EACCES shows up twice. once for the keyring being unwritable, once for the key being unlinkable. two different reasons, same name, it's giving twins but make it errors. 😭

---

🌈 LINKING 🌈

This is a library function that can be found in libkeyutils. When linking, -lkeyutils should be specified to the linker.

that's the one. that's the flag. don't forget it or nothing links and you'll be sitting there like 👑→💀. iykyk.

---

🧚 SEE ALSO 🧚

keyctl(1), add_key(2), keyctl(2), request_key(2), keyctl(3), keyrings(7), keyutils(7)

go read those too, they're all part of the same little friend group. 🍓

---

and that's the whole page, bestie!! this one came from the Linux crew, dated 4 May 2006, and it lives under the name KEYCTL_LINK(3) in the Linux Key Management Calls manual. mwah. 💅✨