RPC_GSS_SET_CALLBACK(3)

💅 RPC_GSS_SET_CALLBACK(3) — like, the Library Functions Manual one, bestie

okay so this is rpc_gss_set_callback from the Library Functions Manual, and it lives in the RPC GSS-API Authentication Library (librpcsec_gss, and you link it with -lrpcsec_gss). yes that's a whole mouthful, we're getting through it together 🫶

✨ NAME ✨

rpc_gss_set_callback — the function that registers your security-context-creation callback. that's it, that's the vibe 💅

📚 LIBRARY 📚

RPC GSS-API Authentication Library (librpcsec_gss, -lrpcsec_gss)

🌸 SYNOPSIS 🌸

#include <rpc/rpcsec_gss.h>

bool_t
(*callback)(struct svc_req *req, gss_cred_id_t deleg,
    gss_ctx_id_t gss_context, rpc_gss_lock_t *lock, void **cookie);

bool_t
rpc_gss_set_callback(rpc_gss_callback_t *cb);

🎀 DESCRIPTION 🎀

okay so you're registering a function, right, and that function gets called whenever new security contexts are created on a server. that's the whole thing. she's a hook ✨

she gets called on the first RPC request that uses that context, and she has the full opportunity to just... reject it 😭 like, for instance, after she's matched the request credentials up against an access control list. main character energy honestly.

so: to accept the new security context, the callback should return TRUE. otherwise FALSE. simple as that, no cap. and heads up — if the callback accepts a context, it becomes responsible for the lifetime of the delegated client credentials (if there are any). like, that's on you now, bestie 👑

there's also a little bonus feature: it's possible to 'lock' the values of service and quality of protection used by the context. if a context is locked, then any subsequent requests that use different values for service and quality of protection get rejected. periodt. 🔥

🦋 PARAMETERS 🦋

• cb — a structure holding the RPC program and version for this callback, plus the function that'll get called when new contexts are created for that given RPC program and version
• req — the RPC request using the new context
• deleg — GSS-API delegated credentials (if any)
• gss_context — the GSS-API context
• lock — a structure used to enforce a particular QOP and service. set lock->locked to TRUE to lock the service and QOP values 🔒
• cookie — the callback function may set *cookie to any pointer-sized value. you can get at that value during the lifetime of the context via rpc_gss_getcred(). it's giving little secret stash 🙈

⭐ RETURN VALUES ⭐

returns TRUE if the callback was registered successfully, or FALSE otherwise. that's the vibe check, bestie 🌈

👀 SEE ALSO 👀

gssapi(3), rpc(3), rpc_gss_getcred(3), rpcsec_gss(3) — go read these, iykyk 💜

🕰️ HISTORY 🕰️

the rpc_gss_set_callback function first appeared in FreeBSD 8.0. a little iconique origin story ngl 🎀

✍️ AUTHORS ✍️

this manual page was written by Doug Rabson <dfr@FreeBSD.org>. thank you Doug, we appreciate you 🫶

💀 BUGS 💀

okay so this is the sad part 😭 there is no mechanism for informing a server when a security context has been deleted. which makes it genuinely difficult to allocate resources (e.g. to return via the callback's cookie argument). so like... your cookie's out there living its life and nobody tells you when it's gone. tragic, honestly. lowkey a real limitation 💀

---

and that's the page, bestie! this one's from the Debian build, dated January 26, 2010, filed under RPC_GSS_SET_CALLBACK(3). go forth and register those callbacks responsibly 💖✨