KEYCTL_SEARCH(3)

💖 KEYCTL_SEARCH — ok so you wanna find a key in a keyring bestie

welcome to the Linux Key Management Calls chapter of the manual, specifically the keyctl_search(3) entry 🎀 this is a <keyutils.h> situation and honestly? it's giving treasure hunt but make it kernel. let's go ✨

🌸 NAME 🌸

keyctl_search — search a keyring for a key 🔍 no cap

✨ SYNOPSIS ✨

#include <keyutils.h>

long keyctl_search(key_serial_t keyring, const char *type,
const char *description, key_serial_t destination);

look at that signature. four args. gorgeous. iconic. we love to see it 💅

🦋 DESCRIPTION 🦋

okay so keyctl_search() recursively searches the keyring for a key of the specified type and description. like it goes digging. it does not stop at the top level. it's thorough. it's committed. main character energy fr fr.

If found, the key will be attached to the destination keyring (if given), and its serial number will be returned. 🫶

now here's the permission tea ☕ The source keyring must grant search permission to the caller, and for a key to be found, it must also grant search permission to the caller. Child keyrings will be only be recursively searched if they grant search permission to the caller as well. so basically everyone in the chain has to say yes or the whole thing falls apart 😭

If the destination keyring is zero, no attempt will be made to forge a link to the key, and just the serial number will be returned. (zero = no linking, just vibes and a number)

If the destination keyring is given, then the link may only be formed if the found key grants the caller link permission and the destination keyring grants the caller write permission. two yeses minimum, bestie 🤝

If the search is successful, and if the destination keyring already contains a link to a key that matches the specified type and description, then that link will be replaced by a link to the found key. out with the old, in with the new, periodt ✨

The source keyring and destination keyring serial numbers may be those of valid keyrings to which the caller has appropriate permission, or they may be special keyring IDs:

• KEY_SPEC_THREAD_KEYRING — This specifies the caller's thread-specific keyring. 🧵
• KEY_SPEC_PROCESS_KEYRING — This specifies the caller's process-specific keyring. 🏃
• KEY_SPEC_SESSION_KEYRING — This specifies the caller's session-specific keyring. 🌈
• KEY_SPEC_USER_KEYRING — This specifies the caller's UID-specific keyring. 👑
• KEY_SPEC_USER_SESSION_KEYRING — This specifies the caller's UID-session keyring. 🎀

iykyk these special IDs are how you point at the keyrings the kernel already made for you without knowing their serial numbers 💖

⭐ RETURN VALUE ⭐

On success keyctl_search() returns the serial number of the key it found. 🎉 you got your number, bestie!

On error, the value -1 will be returned and errno will have been set to an appropriate error. 💀 not the -1…

🔥 ERRORS 🔥

• ENOKEY — One of the keyrings doesn't exist, no key was found by the search, or the only key found by the search was a negative key. (a negative key is a "no" stored as a key, so like… you found a no. sad.)
• ENOTDIR — One of the keyrings is a valid key that isn't a keyring. 🫠 not a directory, not a keyring, it's just some guy
• EKEYEXPIRED — One of the keyrings has expired, or the only key found was expired. ⌛
• EKEYREVOKED — One of the keyrings has been revoked, or the only key found was revoked. 🚫
• ENOMEM — Insufficient memory to expand the destination keyring. 😭 the kernel ran out of room, it happens to the best of us
• EDQUOT — The key quota for this user would be exceeded by creating a link to the found key in the destination keyring. 📊
• EACCES — The source keyring didn't grant search permission, the destination keyring didn't grant write permission or the found key didn't grant link permission to the caller. 🔒 permission denied bestie, go ask nicely

🔗 LINKING 🔗

Although this is a Linux system call, it is not present in libc but can be found rather in libkeyutils. When linking, -lkeyutils should be specified to the linker.

so when you're compiling, don't forget the flag or you'll be staring at undefined reference errors like 👁️👄👁️

-lkeyutils

👀 SEE ALSO 👀

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

the whole friend group fr fr 🫶

and that's the page babes 💖 this entry lives in the Linux manual, dated 4 May 2006 — yeah she's a classic, an OG, and she still slays. go search some keyrings, you got this 👑✨💅