KEYCTL_MOVE(3)

✨ NAME ✨

keyctl_move — bestie, this is the one that moves a key between keyrings 💅 (it's KEYCTL_MOVE(3), from the Linux Key Management Calls manual, if you were wondering 🎀)

🦋 SYNOPSIS 🦋

#include <keyutils.h>

long keyctl_move(key_serial_t key, key_serial_t from_keyring,
                 key_serial_t to_keyring, unsigned int flags);

🌸 DESCRIPTION 🌸

okay so listen. keyctl_move() takes key and does the whole glow-up atomically — it unlinks it from from_keyring and links it straight into to_keyring in literally one single operation, no in-between era, no awkward transitional phase ✨

Depending on what flags you set, a link to any matching key chillin' in to_keyring might get displaced 👀 (yes, like, evicted. sorry girl.)

flags is a bitwise-OR of zero or more of these:

• KEYCTL_MOVE_EXCL — if there's already a matching key in to_keyring, don't displace it, just throw an error instead 🚫 (not me choosing violence, the function chooses it for you)

The caller must have write permission on both keyrings to be able to create or remove links in them 🔑

And the caller must have link permission on a key to be able to create a new link to it, periodt.

💖 RETURN VALUE 💖

On success, keyctl_move() returns 0 — slay 🎉

On error, the value -1 gets returned and errno will have been set to an appropriate error 😭

💀 ERRORS 💀

• ENOKEY — the key, or one of the keyrings you specified, is invalid.
• ENOKEY — a key with the same type and description is present in to_keyring and KEYCTL_MOVE_EXCL is set. (yes bestie, ENOKEY shows up twice, that's just how it is 🙈)
• EKEYEXPIRED — the key, or one of the keyrings you specified, has expired. RIP 🪦
• EKEYREVOKED — the key, or one of the keyrings you specified, has been revoked.
• EACCES — the key exists, but it's not linkable by the calling process.
• EACCES — the keyrings exist, but they're not writable by the calling process.
• ENOMEM — not enough memory to effect the changes 😵
• EDQUOT — expanding to_keyring would exceed the keyring owner's quota.

🔗 LINKING 🔗

This is a library function, and it lives in libkeyutils 🫶

When you're linking, you gotta pass -lkeyutils to the linker. no cap.

👑 SEE ALSO 👑

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

mwah 💋 that's the whole page — Linux, dated 29 May 2019, and the manpage is KEYCTL_MOVE(3). go move some keys, you absolute icon 🌈✨