keyring_search_rcu(9)

💅 keyring_search_rcu(9) — Kernel API Manual 🫶

✨ NAME ✨

keyring_search_rcu — Search a keyring tree for a matching key under RCU. No cap, that's the whole vibe 💫

🌸 SYNOPSIS 🌸

key_ref_t keyring_search_rcu (key_ref_t keyring_ref , struct
keyring_search_context *ctx );

🎀 ARGUMENTS 🎀

• keyring_ref — A pointer to the keyring with possession indicator. Bestie, that possession indicator is coming along for the ride 🎟️
• ctx — The keyring search context. The search context itself, literally carrying the context of the search ✨

🦋 DESCRIPTION 🦋

Okay so bestie, this function searches the supplied keyring tree for a key that matches the criteria given. The root keyring and any linked keyrings must grant Search permission to the caller to be searchable, and keys can only be found if they too grant Search to the caller. The possession flag on the root keyring pointer controls use of the possessor bits in permissions checking of the entire tree. In addition, the LSM gets to forbid keyring searches and key matches. The LSM really said “not on my watch” there 👀

The search is performed as a breadth-then-depth search up to the prescribed limit (KEYRING_SEARCH_MAX_DEPTH). Like, it goes broad, then deep — it's giving main character traversal energy 🌈

⚠️ Real talk: the caller must hold the RCU read lock to prevent keyrings from being destroyed or rearranged whilst they are being searched. This is not optional, bestie — hold that lock 💀

Keys are matched to the type provided and are then filtered by the match function, which is given the description to use in any way it sees fit. The match function may use any attributes of a key that it wishes to determine the match. Normally the match function from the key type would be used. It's basically the matchmaker of key attributes 💅

RCU can be used to prevent the keyring key lists from disappearing without the need to take lots of locks. Less lock drama, more RCU protection — we love an efficient icon ✨

Returns a pointer to the found key and increments the key usage count if successful; -EAGAIN if no matching keys were found, or if expired or revoked keys were found; -ENOKEY if only negative keys were found; -ENOTDIR if the specified keyring wasn't a keyring. Those return codes are the whole plot twist 🫶

In the case of a successful return, the possession attribute from keyring_ref is propagated to the returned key reference. Yes, the possession attribute understood the assignment and traveled with it 🎀

👑 SEE ALSO 👑

Kernel file ./security/keys/keyring.c, plus these absolute legends:

• key_put_tag(9)
• key_remove_domain(9)
• restrict_link_reject(9)
• keyring_search(9)
• keyring_restrict(9)
• key_link(9)
• key_unlink(9)
• key_move(9)
• keyring_clear(9)

okay bye bestie — this was keyring_search_rcu(9) from the Kernel API Manual, footer source/version ./security/keys, dated October 2026. Obsessed, honestly 💖✨💅